# krish-om/agents-in-ai architecture

> Architecture diagram of the GitHub repository krish-om/agents-in-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krish-om/agents-in-ai
- Repository: https://github.com/krish-om/agents-in-ai

## Overview

##### Project type and purpose
- This is a standalone Python‐based game application (the classic Snake) augmented with multiple AI agent implementations, ranging from simple reflex to reinforcement learning.
- Its primary goal is educational: to demonstrate the evolution of intelligent agent architectures in a game environment and compare their performance.

##### File structure
- Top‐level
- run_agents.py – main entry point, orchestrates menu and agent selection
- core_game/ – the game engine (game loop, rendering, collision detection, audio)
- agents/ – five subpackages, each implementing a distinct AI agent architecture
- resources/ – game audio assets
- reports/ – generated performance reports
- ss/ – screenshots
- requirements.txt, README.md, AI LAB1.1.pdf – documentation and dependencies
- agents/
- simple_reflex/
- goal_based/
- model_based/
- utility_based/
- q_learning/ (contains both training scripts and trained data JSON files)
- Notice the separation: a core game engine module and a plug-in style agent interface.

##### README for additional insights
- Confirms five AI paradigms: reflex, goal‐based (A*), model‐based, utility‐based, Q‐learning (with training pipeline).
- Core engine interface is in core_game/source.py—each agent module imports this to receive perceptions and execute actions.
- Training artifacts (trained_q_table.json, training_stats.json) and reports are generated in dedicated folders.

a. Main components
- Run_Agents Orchestrator
- Core Game Engine
- Agent Interface Layer
- Q-Learning Training Pipeline
- Data Storage (Q-table JSON, stats JSON)
- Resources (Audio)
- Reports Generator
b. Relationships & interactions
- Run_Agents → CoreGame: initializes engine and passes control
- CoreGame ↔ Agent Interface: every game tick, engine sends game state (perceptions) to the selected agent; agent returns an action
- Agent Implementations plug into the interface (polymorphic module loading)
- Q-Learning Trainer → Q-Learning Agent: trainer runs many game sessions via CoreGame, collects experience, updates Q-table → writes JSON
- Trained Player loads JSON → plays via CoreGame
- CoreGame triggers audio via Resources
- Reports scripts parse training_stats.json and gameplay logs → Reports
c. Architectural patterns & design principles
- Plug-in architecture for agents (each in its own package, shares a common API)
- Separation of concerns: game mechanics vs. AI logic vs. training vs. reporting
- Data persistence layer for learning (JSON store)
d. Key technologies/frameworks
- Python 3.8+
- Pygame (rendering, input, audio)
- json (Q-table and statistics persistence)
- Standard libs: os, sys, random, time, math

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration"
        RA["RunAgents Orchestrator"]:::orchestration
        QTP["Q-Learning Training Pipeline"]:::orchestration
    end

    %% Core Engine and Interface
    subgraph "Core Engine"
        CG["Core Game Engine"]:::core
    end
    AI["Agent Interface"]:::interface

    %% Agents Module
    subgraph "Agent Implementations"
        SR["Simple Reflex Agent"]:::agent
        GB["Goal-Based Agent"]:::agent
        MB["Model-Based Agent"]:::agent
        UB["Utility-Based Agent"]:::agent
        QL["Q-Learning Agent"]:::agent
    end

    %% Training Pipeline Components
    subgraph "Training Components"
        AT["Auto Trainer"]:::orchestration
        ST["Screenshot Trainer"]:::orchestration
        SP["Screenshot Player"]:::orchestration
    end

    %% Data Persistence
    subgraph "Data Storage"
        QT["Q-Table JSON"]:::data
        TS["Training Stats JSON"]:::data
    end

    %% Resources and Reports
    subgraph "Supporting Assets"
        RES["Audio Resources"]:::resource
        SS["Screenshots Directory"]:::resource
    end

    subgraph "Reporting"
        RPT1["snake_agents_report.tex"]:::report
        RPT2["training_report.txt"]:::report
    end

    %% Relationships
    RA -->|"initialize"| CG
    CG -->|"send perceptions"| AI
    AI -->|"action"| CG

    AI --> SR
    AI --> GB
    AI --> MB
    AI --> UB
    AI --> QL

    QTP -->|"runs sessions via"| CG
    AT --> QTP
    ST --> QTP
    SP --> QTP

    QTP -->|"update"| QT
    QTP -->|"record stats"| TS

    QT -->|"load JSON"| QL
    QL -->|"play via"| CG

    CG -->|"playback audio"| RES
    CG -->|"generate logs"| RPT2
    TS -->|"input stats"| RPT1

    %% Click Events
    click RA "https://github.com/krish-om/agents-in-ai/blob/master/run_agents.py"
    click CG "https://github.com/krish-om/agents-in-ai/blob/master/core_game/source.py"
    click AI "https://github.com/krish-om/agents-in-ai/blob/master/core_game/source.py"
    click SR "https://github.com/krish-om/agents-in-ai/blob/master/agents/simple_reflex/simple_reflex_agent.py"
    click SR "https://github.com/krish-om/agents-in-ai/blob/master/agents/simple_reflex/simple_reflex_player.py"
    click GB "https://github.com/krish-om/agents-in-ai/blob/master/agents/goal_based/goal_based_agent.py"
    click GB "https://github.com/krish-om/agents-in-ai/blob/master/agents/goal_based/goal_based_player.py"
    click MB "https://github.com/krish-om/agents-in-ai/blob/master/agents/model_based/model_based_agent.py"
    click MB "https://github.com/krish-om/agents-in-ai/blob/master/agents/model_based/model_based_player.py"
    click UB "https://github.com/krish-om/agents-in-ai/blob/master/agents/utility_based/utility_based.py"
    click UB "https://github.com/krish-om/agents-in-ai/blob/master/agents/utility_based/utility_based_player.py"
    click QL "https://github.com/krish-om/agents-in-ai/blob/master/agents/q_learning/trained_player.py"
    click AT "https://github.com/krish-om/agents-in-ai/blob/master/agents/q_learning/auto_trainer.py"
    click ST "https://github.com/krish-om/agents-in-ai/blob/master/agents/q_learning/screenshot_trainer.py"
    click SP "https://github.com/krish-om/agents-in-ai/blob/master/agents/q_learning/screenshot_player.py"
    click QT "https://github.com/krish-om/agents-in-ai/blob/master/agents/q_learning/trained_q_table.json"
    click TS "https://github.com/krish-om/agents-in-ai/blob/master/agents/q_learning/training_stats.json"
    click RES "https://github.com/krish-om/agents-in-ai/blob/master/resources/bg_music_1.mp3"
    click RES "https://github.com/krish-om/agents-in-ai/blob/master/resources/crash.mp3"
    click RES "https://github.com/krish-om/agents-in-ai/blob/master/resources/ding.mp3"
    click SS "https://github.com/krish-om/agents-in-ai/tree/master/ss/"
    click RPT1 "https://github.com/krish-om/agents-in-ai/blob/master/reports/snake_agents_report.tex"
    click RPT2 "https://github.com/krish-om/agents-in-ai/blob/master/reports/training_report.txt"

    %% Styles
    classDef orchestration fill:#FDEBD0,stroke:#C0392B,stroke-width:1px
    classDef core fill:#D6EAF8,stroke:#2471A3,stroke-width:1px
    classDef interface fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef agent fill:#F9EBEA,stroke:#C0392B,stroke-width:1px
    classDef data fill:#FCF3CF,stroke:#B7950B,stroke-width:1px
    classDef resource fill:#EBDEF0,stroke:#8E44AD,stroke-width:1px
    classDef report fill:#FDEDEC,stroke:#A93226,stroke-width:1px
```
