How while-basic/agi-digital-city works
Project Type and Purpose
• This is a Python‐based simulation framework (full-stack) that spawns 10–100 LLM-powered agents (“citizens”) in a closed digital city.
• It provides both a REST API and a web dashboard for monitoring, and uses FAISS+Obsidian for memory and logging.
File Structure
• Top-level scripts:
• run_simulation.py (entrypoint)
• src/ subpackages:
• agents/ (agent classes, emotion system, God agent)
• memory/ (FAISS index wrapper)
• simulation/ (town manager, asyncio loop)
• api/ (Flask REST endpoints)
• ui/ (Flask + JS dashboard, HTML templates)
• utils/ (database connector, LLM interface, Obsidian logger)
• config/ (configuration parameters)
• requirements.txt (.venv for Python env)
• project-docs/ (build & update guides)
README for Insights
• Core technologies: Python, asyncio, Flask, SQLite, FAISS, Obsidian API, Ollama LLM
• Runtime: one process may spawn multiple subprocesses or threads for I/O (LLM calls, memory writes)
• Ports: 5000 for API, 8080 for dashboard
Main Components
a. run_simulation.py (Orchestrator)
b. Simulation Engine (town_manager + asyncio scheduler)
c. Agent Pool (base_agent, emotion_system, god_agent)
d. Memory Backend
– FAISS Index (vector store for embeddings)
– Obsidian Vault (filesystem logs via obsidian_logger)
e. LLM Service (Ollama server with llama3.2:1b)
f. API Service (Flask)
g. UI Dashboard (Flask + JS, templates)
h. Database (SQLite via utils/database.py)
i. Configuration (config/config.py)
Relationships and Data Flows
• The Orchestrator invokes the Simulation Engine.
• The Simulation Engine schedules Agent behaviors each tick.
• Each Agent:
• Sends prompts to the LLM Service (via llm_interface).
• Retrieves/stores memories in FAISS (memory_system).
• Logs events to Obsidian vault.
• Persists state to SQLite.
• API Service exposes endpoints to query/update simulation state (talks to Simulation Engine and/or SQLite).
• UI Dashboard fetches data from the API Service and renders it in the browser.
• Configuration parameters flow into all components at startup.
Architectural Patterns & Principles
• Modular layering: Simulation core, Agents, Memory, API, UI
• Event-driven & asynchronous (asyncio) for high concurrency
• MVC for UI (Flask routes → templates → static assets)
• Adapter pattern in utils (wrapping FAISS, Obsidian, database, LLM calls)
Relevant Technologies
• Ollama LLM (external service)
• FAISS vector store
• Obsidian API (filesystem vault)
• Flask (API & Dashboard)
• SQLite (local file)
• Python asyncio
Final Checklist
• [ ] All major components are represented and labeled.
• [ ] Data flows and dependencies are arrowed and annotated.
• [ ] Architectural patterns (async, modular layering) are evident.
• [ ] Technologies and frameworks are noted.