How ruc-gsai/yulan-rec works
Project Type & Purpose
• Full-stack, Python-backed multi-agent user behavior simulation platform with a React/TypeScript front end.
Key Architectural Layers & Components
A. Frontend (UI folder)
– React single-page application (TypeScript, Vite)
– Components: AgentCard, ChatCard, Graph, SettingsForm, etc.
– State management via React Context (DisplayedAgentContext, UiSettingsContext)
– API hooks under src/hooks/api (agent, relationship, state) for communicating with the backend.
B. API Server / Backend Entry Point
– backend.py (likely FastAPI or Flask) exposes HTTP endpoints consumed by the UI.
– test.js (root) demonstrates raw API calls.
– shell scripts (backend.sh, nohup.sh) to start the server.
C. Simulation Engine
– simulator.py / run_demo.py / demo.py orchestrate simulation rounds.
– Uses config/config.yaml for parameters (LLM choice, data paths, agent count, scheduling).
– Agents directory: recagent.py, recagent_memory.py, roleagent.py implement agent behavior and memory.
– llm directory: custom_llm.py, local_llm.py wrap OpenAI or local LLM API calls.
– recommender directory:
• data/data.py reads item/user/relationship CSVs
• model/* implements MF, random, base interfaces
• recommender.py trains/invokes the recommendation model each round.
– utils: helper modules for event scheduling, messaging, persisting checkpoints.
D. Data Layer
– CSV files under data/ (user.csv, item.csv, relationship.csv)
– FAISS index under data/faiss_index for fast item lookup
– JSON output (messages.json) and logs for simulation records
– config/config.yaml for runtime settings
E. External Services
– OpenAI API (or other LLM endpoints)
– (Optionally) local LLM service
F. Deployment & Orchestration
– Shell scripts: simulator.sh to run simulation headless
– Nohup.sh for background execution
– Docker (not provided, but could be added)
Relationships & Data Flows
– Frontend ←→ Backend/API: all user interactions (start/pause/reset, settings) go via REST calls.
– Backend Simulation Engine invokes:
• Agent modules → consult Memory module → request next action
• Recommender module → returns item recommendations
• LLM module → calls out to OpenAI or local LLM, returns generated text
– Simulation Engine writes events to Data Layer (CSV / FAISS / JSON logs).
– Frontend polls or opens a WebSocket (if implemented) to receive real-time updates on agent state, logs, graphs.
Architectural Patterns & Design Principles
– Layered Architecture:
• Presentation (React UI)
• API / Controller (backend.py)
• Simulation Services (Simulator, Agents, Recommender, LLM, Utils)
• Data Access (CSV readers, FAISS index)
• External Integration (OpenAI)
– Separation of Concerns: each folder/package has clear responsibility.
– Plugin-style Recommender & LLM: easy to extend with new algorithms or LLM providers.
– Config-driven: almost every behavior (agent count, memory type, model choice) comes from YAML.