Feat/initial setup

.gitignore

@@ -0,0 +1,27 @@
+# Python artifacts
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Virtual environment
+venv/
+env/
+ENV/
+.venv/
+
+# OS files
+.DS_Store
+
+# SQLite database
+*.db
+
+# Environment variables
+.env
+
+# Gemini API key backup
+gemini_api_key.txt
+
+# VS Code settings
+.vscode/
+node_modules/

.vscode/launch.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug Backend",
+      "program": "${workspaceFolder}/srv/server.js",
+      "envFile": "${workspaceFolder}/srv/.env"
+    }
+  ]
+}

ARCHITECTURE.md

@@ -1,24 +1,70 @@
-## 2. `ARCHITECTURE.md`
-
-```markdown
 # Architecture Overview
 
-Below, sketch (ASCII, hand-drawn JPEG/PNG pasted in, or ASCII art) the high-level components of your agent.
+This system is a cognitive companion app with a modular agent architecture, supporting multi-agent planning and execution via FastAPI and a React dashboard.
+
+---
 
 ## Components
 
-1. **User Interface**  
-   - E.g., Streamlit, CLI, Slack bot  
+1. **User Interface**
+   - **Frontend:** React (Vite) dashboard for user interaction
+   - **Backend API:** FastAPI endpoints for chat and agent orchestration
+
+2. **Agent Core**
+   - **Planner:** Uses Gemini LLM to classify intent and generate step-by-step plans; selects relevant agents for each query
+   - **Executor:** Executes the plan by invoking selected agents in parallel; manages agent responses and workflow
+   - **Memory:** `MemoryManager` stores user context, previous interactions, and session data for personalized responses
+
+3. **Agents**
+   - Modular agent classes (e.g., `psychologist_agent`, `mindcoach_agent`, `facts_agent`, etc.)
+   - Each agent specializes in a cognitive domain (therapy, motivation, facts, games, etc.)
+   - Agents are registered in a central `AGENT_REGISTRY` for dynamic selection
+
+4. **Tools / APIs**
+   - **Google Gemini API:** LLM for planning, classification, and agent reasoning
+   - **Session Service:** Manages session lifecycle and context per user/query
+
+5. **Observability**
+   - **Logging:** Each reasoning step, agent selection, and execution is logged for traceability
+   - **Error Handling:** Fallbacks to default agents (e.g., `facts_agent`) and retries on failure
+   - **Session Isolation:** Each query creates a fresh session for stateless, reproducible workflows
+
+---
+
+## Data Flow
+
+```
+User → React Dashboard → FastAPI → Planner (Gemini) → Agent Selection → Executor → Agents (Parallel) → Response → User
+```
+
+---
+
+## Extensibility
+
+- Add new agents by implementing and registering them in `AGENT_REGISTRY`
+- Swap UI (CLI, Slack, etc.) by changing frontend
+- Integrate new tools/APIs via agent or executor modules
+
+---
 
-2. **Agent Core**  
-   - **Planner**: how you break down tasks  
-   - **Executor**: LLM prompt + tool-calling logic  
-   - **Memory**: vector store, cache, or on-disk logs  
+## Diagram (ASCII)
 
-3. **Tools / APIs**  
-   - E.g., Google Gemini API, Tools, etc
+```
++-------------+      +-----------+      +-----------+      +-----------+
+|   User UI   | ---> |  FastAPI  | ---> |  Planner  | ---> |  Executor |
++-------------+      +-----------+      +-----------+      +-----------+
+                                                              |
+                                                              v
+                                                      +------------------+
+                                                      |   Agents (N)     |
+                                                      +------------------+
+                                                              |
+                                                              v
+                                                      +------------------+
+                                                      |   MemoryManager  |
+                                                      +------------------+
+```
 
-4. **Observability**  
-   - Logging of each reasoning step  
-   - Error handling / retries  
+---
 
+Let me know if you want a more detailed diagram or component breakdown!

EXPLANATION.md

@@ -2,34 +2,44 @@
 
 ## 1. Agent Workflow
 
-Describe step-by-step how your agent processes an input:
-1. Receive user input  
-2. (Optional) Retrieve relevant memory  
-3. Plan sub-tasks (e.g., using ReAct / BabyAGI pattern)  
-4. Call tools or APIs as needed  
-5. Summarize and return final output  
+Step-by-step process for each user query:
+1. **Receive user input** via the React dashboard and FastAPI backend.
+2. **Retrieve relevant memory** (optional): `MemoryManager` fetches past interactions for context.
+3. **Plan sub-tasks**: The `Planner` uses Gemini LLM to classify intent and generate a step-by-step plan, selecting the most relevant agents.
+4. **Agent selection and execution**: The `Executor` invokes selected agents in parallel, passing the plan and context.
+5. **Aggregate and summarize output**: Agent responses are combined and returned to the user.
 
 ## 2. Key Modules
 
-- **Planner** (`planner.py`): …  
-- **Executor** (`executor.py`): …  
-- **Memory Store** (`memory.py`): …  
+- **Planner** (`Planner.py`):  
+  Uses Gemini LLM to classify user intent and generate a plan. Returns agent keys and steps.
+- **Executor** (`executor.py`):  
+  Runs the selected agents in parallel, manages workflow, and aggregates responses.
+- **Memory Store** (`memory.py`):  
+  Stores and retrieves user context, session data, and previous interactions for personalization.
 
 ## 3. Tool Integration
 
-List each external tool or API and how you call it:
-- **Search API**: function `search(query)`  
-- **Calculator**: LLM function calling  
+External tools and APIs:
+- **Google Gemini API**:  
+  Used in `Planner.py` for LLM-based planning and classification.
+- **Session Service**:  
+  Manages session lifecycle and context for each query.
+- **Other APIs/Tools**:  
+  Agents can call additional APIs (e.g., search, games) as needed.
 
 ## 4. Observability & Testing
 
-Explain your logging and how judges can trace decisions:
-- Logs saved in `logs/` directory  
-- `TEST.sh` exercises main path  
+- **Logging**:  
+  All agent decisions, selected agents, and reasoning steps are logged (see `logs/` directory).
+- **Testing**:  
+  `TEST.sh` script exercises main workflow and endpoints.
+- **Error Handling**:  
+  Fallbacks to `facts_agent` and default steps if planning or agent selection fails.
 
 ## 5. Known Limitations
 
-Be honest about edge cases or performance bottlenecks:
-- Long-running API calls  
-- Handling of ambiguous user inputs  
-
+- **Long-running API calls** may delay responses.
+- **Ambiguous user inputs** may result in fallback to default agents.
+- **Session isolation**: Each query creates a new session; persistent context is limited to what is stored in `MemoryManager`.
+- **Agent extensibility**: Adding new agents requires updating `AGENT_REGISTRY` and implementing agent logic.