How neural-maze/philoagents-course works
Project Type and Purpose
• This is a full-stack AI-powered game simulation engine (“PhiloAgents”) that impersonates historical philosophers via dynamic conversation agents.
• Two distinct applications:
• philoagents-api (Python/FastAPI backend with agent orchestration, RAG, memory, evaluation)
• philoagents-ui (Node.js/Phaser-powered frontend with HTTP + WebSocket client)
High-Level Architecture Overview
• Frontend UI container
• Backend API container
• Data stores (MongoDB for long-term memory, vector DB for RAG)
• External AI services (GroqCloud + optionally OpenAI)
• Data ingestion pipelines (Wikipedia + Stanford Encyclopedia)
• Evaluation & monitoring components
Main Components
a. Frontend Layer (“philoagents-ui”)
– Browser Game (Phaser)
– ApiService (HTTP/REST)
– WebSocketApiService (real-time chat)
b. Backend Layer (“philoagents-api”)
1. API Gateway (FastAPI + Uvicorn)
• REST endpoints (/generate_response, /reset_conversation)
• WebSocket endpoint for live dialogue
2. Application Services
• ConversationService (orchestrates workflow graph of nodes/edges/chains)
• DataService (document extraction, deduplication)
• RAGService (embeddings, retriever, splitter)
• MemoryService
– Short-term (in-memory per session)
– Long-term (MongoDB collections, philoagents.infrastructure.mongo.client)
• EvaluationService (dataset generation, agent evaluation)
3. Domain Layer
• Philosopher entities, prompts, evaluation rules, exception models
4. Infrastructure Layer
• MongoDB adapter
• Opik utilities (vector store integration)
• LangGraph/LangChain connectors to LLMs
c. Data Stores
– MongoDB (long-term memory, prompt history, evaluation metadata)
– Vector database (via Opik or external vector store)
d. External Services
– LLM inference (GroqCloud API, optional OpenAI)
– Data sources (Wikipedia + Stanford Encyclopedia; ingested at runtime)
e. DevOps & Tooling
– Docker Compose orchestrates API, UI, MongoDB
– Makefiles & pyproject.toml & package.json for builds
– CI/Monitoring hooks for LLMOps (prompt versioning, evaluation jobs)
Relationships & Data Flows
• User clicks in UI → ApiService → FastAPI controller
• Controller invokes ConversationService →
• Retrieves context from Short-term memory
• Calls RAGService to fetch relevant docs via vector DB
• Calls LLM via LangGraph connector (Groq/OpenAI)
• Updates memory stores (in-memory & MongoDB)
• ConversationService returns response → WebSocket/HTTP → UI
• EvaluationService runs asynchronously (calls LLM judge, stores results)
• Data ingestion jobs (create_long_term_memory.py) fetch external data → vector DB & MongoDB
Architectural Patterns & Principles
• Hexagonal (ports & adapters): separates Domain, Application, Infrastructure
• Layered modular monolith (clear boundaries between services)
• RAG pipeline as a sub-system (splitter → embeddings → retriever → LLM chain)
• Event/workflow graph for conversation orchestration (nodes & edges model)
• LLMOps best practices: versioned prompts, automated evaluation