update from github stable code (#3)

- Clean initial commit for HuggingFace (f108b29491d90326f90f71fa07edef74d570194b)
- stable v (dbe2d5a13184387b222e127d2a35ab2e1dc948d4)
- Revert "Clean initial commit for HuggingFace" (b2b94e06694eceb7028a307909def1eb5638d81b)
- Update intro.md (5b7957111cd66bf284f360179a122c6b44409cca)


Co-authored-by: Dmitri Moscoglo <dimim@users.noreply.huggingface.co>

.gitignore

@@ -67,4 +67,7 @@ src/database/cvs/tests/*.txt
 .lgcache/
 .langgraph_api/
 
-.idea/
+.idea/
+
+# any .wav files
+*.wav

README.md

@@ -1,14 +1,3 @@
----
-license: mit
-title: HR Assistant
-sdk: docker
-emoji: 🏢
-colorFrom: green
-colorTo: green
-tags:
-  - mcp-in-action-track-enterprise
----
-
 # ***`Recruitment Agent`***
 <p align="left">
   <img src="https://img.shields.io/badge/MCP%20Hackathon-Track%202%20%E2%80%94%20Enterprise-blue" />
@@ -22,16 +11,14 @@ tags:
   <img src="https://img.shields.io/badge/Google%20Cloud-APIs%20%26%20MCP%20Tools-blue?logo=googlecloud" />
 </p>
 
+
+
+
+
+
 > This project was developed as part of the **[MCP 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday)** — submitted under  
 > **Track 2: MCP in Action (Enterprise)**, showcasing a real-world multi-agent application built on top of the Model Context Protocol.
 
-## 👥 ***`Team`***
-| Member   |
-| -------- |
-| [Sebastian Wefers](https://huggingface.co/Basti-1995) |
-| [Dmitri Moscoglo](https://huggingface.co/dimim) |
-| [Owen Kaplinsky](https://huggingface.co/owenkaplinsky) |
-| [SrikarMK](https://huggingface.co/Srikarmk) |
 
 <details>
 <summary><strong>📚 Table of Contents</strong> (click to expand)</summary>
@@ -61,14 +48,19 @@ tags:
 
 ## **Problem Statement**
 
-Modern recruitment is buckling under high volumes and inefficiency, creating a critical bottleneck for organizational growth.
+Modern recruitment processes remain **slow**, **resource-intensive**, and increasingly **unsustainable** for HR teams amid persistent talent shortages and evolving skill demands. Recent industry reports underscore structural bottlenecks that hinder efficient hiring.
+
+High **applicant volumes overwhelm recruiters**, with a *typical job posting attracting hundreds of applications*, many *unqualified*, leading to administrative burdens and rushed evaluations. This results in *only about **5%** of viewers completing applications*, while teams waste time sifting through low-quality submissions. [`1`]
+
+Screening and early-stage evaluation consume excessive recruiter time, with **35%** of their efforts dedicated to tasks like interview scheduling alone, exacerbating workload pressures. Talent acquisition leaders report unmanageable demands, with **27%** citing overload as a key issue, up from prior years. [`2`]
+
+**Hiring timelines average 44 days across industries**, driven by skills mismatches and manual processes that delay filling critical roles. Globally, **76%** of employers struggle to fill positions due to talent gaps, particularly in tech and healthcare sectors. [`1`, `3`]
 
-*   **Overwhelmed Teams**: **35%** of recruiter time is lost to admin tasks like scheduling [`2`], with **27%** of leaders citing workload overload [`2`].
-*   **Slow & Expensive**: Average time-to-hire is **44 days** [`1`], with costs reaching **$4,700 per hire** [`1`].
-*   **Inefficient Funnel**: While job posts attract hundreds of applicants, only **5%** complete the process [`1`], and **76%** of employers still struggle to find the right talent [`3`].
-*   **Burnout Risk**: **51%** of HR teams face high turnover risks [`2`], driven by the inability to scale manual screening against rising application volumes.
+The financial toll is significant, with **average cost-per-hire reaching $4,700**, fueled by prolonged cycles, high turnover in recruitment teams (projected at **51%** as a top 2025 challenge), and inefficiencies in sourcing. [`1`, `2`]
 
-This agentic system automates high-volume screening tasks, allowing HR professionals to focus on strategic decision-making.
+HR professionals **face rising burnout** from these pressures, compounded by competition for diverse talent and the **need for more touchpoints in hiring**, which **45%** of leaders say adds complexity. Skills shortages, cited by **63%** of employers as the primary barrier to growth, further strain teams. [`2`, `4`]
+
+These challenges reveal that **traditional manual recruitment fails to scale** in a competitive 2025 landscape. An AI-driven recruitment agent can alleviate bottlenecks by automating screening, accelerating timelines, enhancing consistency, and allowing HR to prioritize strategic decisions over repetitive tasks.
 
 
 
@@ -82,17 +74,37 @@ This agentic system automates high-volume screening tasks, allowing HR professio
 
 4. [World Economic Forum — The Future of Jobs Report 2025](https://www.weforum.org/publications/the-future-of-jobs-report-2025/digest/)
 
-
 ## **Ethical & Regulatory Considerations**
 
-This project is an **experimental prototype** designed to demonstrate technical orchestration of LLM agents, **not a production-ready HR system**.
+This project was developed as an **experimental prototype for a hackathon**, designed to showcase how language-model agents can automate structured workflows. It is **not intended for production deployment** as an autonomous hiring system. Because it touches on the automated assessment of humans, it must be approached with caution and interpreted within the correct ethical and regulatory context.
+
+The risks of algorithmic profiling have been widely documented, most notably during the **Cambridge Analytica scandal**, where data from millions of users was harvested and used for psychographic targeting without consent. This episode demonstrated how data-driven models can be leveraged to manipulate individuals when used irresponsibly, and it significantly shaped today’s regulatory landscape. [`5`]
+
+Given this history, any system that evaluates or ranks people—particularly in employment—must uphold **strict transparency, human oversight, and narrow scope**. In this prototype, all AI outputs are intended purely as **assistive signals**. The system must **never** be used to autonomously approve, reject, or shortlist candidates.
+
+The **EU AI Act** classifies AI systems used for recruitment, CV screening, candidate ranking, promotion decisions, or termination as **High-Risk AI Systems** (Annex III). Such systems are permitted in the EU but must meet stringent requirements, including:
+
+- **Human oversight** with the ability to override AI suggestions  
+- **Transparency** about the model’s role and limitations  
+- **Detailed logging and traceability** of system behavior  
+- **Bias monitoring and risk management**  
+- **High-quality and relevant training data**  
+- **Clear separation** between AI scoring and final human judgment
+
+The Act also **prohibits** certain practices in hiring, such as emotion recognition in workplace settings, biometric inference of personality traits, and social-scoring-style ranking systems. [`6`, `7`, `8`]
 
-*   **Human-in-the-Loop (HITL)**: The system is purely assistive. All final decisions (approvals/rejections) must be made by human recruiters.
-*   **EU AI Act Compliance**: Recruitment AI is classified as **High-Risk**. This prototype addresses key requirements via:
-    *   **Transparency**: Clear logs of agent reasoning.
-    *   **Oversight**: No autonomous final judgments.
-    *   **Prohibited Practices**: No emotion recognition, biometric inference, or psychographic profiling.
-*   **Scope**: Limited to workflow automation and initial screening support. It does not replace human judgment.
+This prototype **does not** conduct emotion recognition, sensitive-trait inference, biometric profiling, or psychographic prediction. It is a technical experiment focused on agent orchestration, workflow automation, and context management—not an end-to-end HR decision engine.
+
+### **Human-in-the-Loop by Design**
+To remain aligned with ethical expectations and regulatory requirements, this system must always operate with:
+
+- **Human-in-the-Loop (HITL):** Recruiters make all decisions.  
+- **Explainability:** Agents produce structured rationales, not black-box judgments.  
+- **Data minimization:** Only job-relevant information is processed.  
+- **No profiling of protected traits:** No biometric, psychographic, or emotional inference.
+
+### **Project Status**
+This project remains a **research and demonstration artifact**, created to explore the technical viability of LLM-powered coordination between agents. It highlights what is technologically possible, but is **not a deployable HR solution** under the EU AI Act. Any real-world implementation would require extensive risk assessment, compliance measures, and human oversight to avoid replicating the harms demonstrated in past profiling scandals.
 
 ---
 
@@ -106,47 +118,110 @@ This project is an **experimental prototype** designed to demonstrate technical
 
 8. [Clifford Chance — What Does the EU AI Act Mean for Employers?](https://www.cliffordchance.com/content/dam/cliffordchance/briefings/2024/08/what-does-the-eu-ai-act-mean-for-employers.pdf)
 
-## **System Architecture**
 
-1. **User Interfaces (Gradio)**: Serves both **HR Managers** (Supervisor Chat & Management) and **Candidates** (CV Upload & Voice Interface).
-2. **Supervisor Agent**: The main planner that orchestrates the process by delegating to:
-   - **DB Executor**: Handles data queries/updates via code execution.
-   - **CV & Voice Screeners**: Specialized agents for assessment.
-   - **Gmail & Calendar Agents**: Manage communication and scheduling.
-3. **MCP Servers**: Connect the Gmail and Calendar agents to external Google APIs.
-4. **Database**: Central storage for candidate profiles and recruitment state.
 
-![System Architecture](./architecture.png)
+## ***`Quick Start: Run Application`***
+To spin up the entire platform including the database, agents, and UI dashboards, we use **Docker Compose**.
 
-## ***`Application Flow & Entry Points`***
+### ***Services & Ports***
+| Service | Description | Host Port | Container Port |
+|---------|-------------|-----------|----------------|
+| `db` | PostgreSQL 15 database with persistent storage | **5433** | 5432 |
+| `cv_upload_streamlit` | UI for uploading CVs | **8501** | 8501 |
+| `voice_screening_streamlit` | UI for voice screening candidates | **8502** | 8501 |
+| `supervisor_ui` | Main Chat UI for the Supervisor Agent | **8503** | 8501 |
+| `websocket_proxy` | Proxy for OpenAI Realtime API | **8000** | 8000 |
 
-The platform orchestrates a complete recruitment pipeline, interacting with both Candidates and the HR Supervisor.
+### ***Infrastructure & Secrets***
+This project requires Google Cloud credentials for the Gmail and Calendar agents.
+
+- **Secrets:** Google tokens and credentials must be present in the `secrets/` directory.
+- **Infrastructure:** You can provision the necessary GCP infrastructure using the code in `terraform/` or the scripts in `scripts/infra/`.
+- **Documentation:** For detailed setup instructions, refer to the [MCP Docs](docs/mcp/).
 
+### ***Run Command***
+1. **Configure Environment:**
+   Copy the example environment file and fill in your API keys:
+   ```bash
+   cp .env.example .env
+   ```
 
+2. **Start Services:**
+   ```bash
+   docker compose --env-file .env -f docker/docker-compose.yml up --build
+   ```
+
+### 🧹 Resetting the Environment
+If you need a clean slate (e.g., after modifying DB models):
+```bash
+# 1. Stop containers
+docker compose -f docker/docker-compose.yml down
+
+# 2. Remove persistent DB volume
+docker volume rm docker_postgres_data
+
+# 3. Rebuild & Start
+docker compose --env-file .env -f docker/docker-compose.yml up --build
+```
+
+---
+
+## ***`Application Flow & Entry Points`***
+
+The platform orchestrates a complete recruitment pipeline, interacting with both Candidates and the HR Supervisor.
 
 ### 1. The Recruitment Lifecycle
+The system tracks candidates through a defined state machine (see `src/backend/state/candidate.py` for the `CandidateStatus` enum).
 
-The candidate application flow follows these key stages:
+```mermaid
+graph TD
+    %% Actors
+    Candidate((Candidate))
+    HR((HR Supervisor))
+
+    %% System Components (Nodes)
+    CV_UI[CV Portal UI]
+    CV_Screen{CV Screening AI}
+    Voice_UI[Voice Portal UI]
+    Voice_Judge{Voice Judge AI}
+    Interview[Person-to-Person Interview]
+    Decision{Final Decision}
+
+    %% Flow & Actions (Edges)
+    Candidate -->|1. Uploads CV| CV_UI
+    CV_UI -->|2. Triggers Analysis| CV_Screen
+    
+    CV_Screen -->|Pass: Sends Invite| Voice_UI
+    CV_Screen -->|Fail: Notify| Rejected((Rejected))
 
-1. **Application Submission**: Candidate applies; status set to `applied`.
-2. **CV Screening**: AI analyzes CV (`cv_screened`) and evaluates it (`cv_passed` or `cv_rejected`).
-3. **Voice Invitation**: Qualified candidates receive an email with an auth code for the AI voice interview (`voice_invitation_sent`).
-4. **Voice Screening**: Candidate completes the AI interview (`voice_done`); AI judge evaluates performance (`voice_passed` or `voice_rejected`).
-5. **Human Interview Scheduling**: Successful candidates are offered available time slots for a person-to-person interview based on HR calendar availability.
-6. **Confirmation**: Interview is scheduled (`interview_scheduled`) upon candidate's response.
-7. **Final Decision**: HR makes a decision (`hired` or `rejected`), and the outcome is communicated to the candidate. 
+    Voice_UI -->|3. Conducts Interview| Candidate
+    Candidate -->|4. Completes Session| Voice_Judge
+    
+    Voice_Judge -->|Pass: Schedule| Interview
+    Voice_Judge -->|Fail: Notify| Rejected
 
-### 2. User Entry Points
+    Interview -->|5. Feedback| HR
+    HR -->|6. Updates Status| Decision
+    
+    Decision -->|Hire| Hired((Hired))
+    Decision -->|Reject| Rejected
 
-| User | Interface | Description |
-| :--- | :--- | :--- |
-| **HR Manager** | **Supervisor UI** | **The Command Center.** Chat with the Supervisor Agent to manage the pipeline, review candidates, query the DB, and schedule interviews. |
-| **Candidate** | **CV Portal** | Public-facing portal for candidates to register and upload their resumes to the system. |
-| **Candidate** | **Voice Portal** | AI-conducted voice interview interface. Candidates access this only after passing CV screening and receiving an invite. |
+    %% Styling
+    style CV_UI fill:#e3f2fd,stroke:#1565c0
+    style Voice_UI fill:#e3f2fd,stroke:#1565c0
+    style CV_Screen fill:#fff3e0,stroke:#ef6c00
+    style Voice_Judge fill:#fff3e0,stroke:#ef6c00
+    style Interview fill:#e8f5e9,stroke:#2e7d32
+    style Decision fill:#f3e5f5,stroke:#7b1fa2
+```
 
-The interaction between these entry points and the agentic workflow is visualized in the state machine below:
+### 2. User Entry Points
 
-![](/architecture.png)
+| User | Interface | Port | Description |
+| :--- | :--- | :--- | :--- |
+| **HR Manager** | **Supervisor UI** | `8503` | **The Command Center.** Chat with the Supervisor Agent to manage the pipeline, review candidates, query the DB, and schedule interviews. |
+| **Candidate** | **CV Portal** | `8501` | Public-facing portal for candidates to register and upload their resumes to the system. |
+| **Candidate** | **Voice Portal** | `8502` | AI-conducted voice interview interface. Candidates access this only after passing CV screening and receiving an invite. |
 
 ---
 
@@ -156,7 +231,7 @@ The interaction between these entry points and the agentic workflow is visualize
 
 To improve the reliability of complex evaluations (such as CV scoring and Voice Interview judging), we enforce **Chain-of-Thought (CoT)** reasoning within our structured outputs, inspired by [Wei et al. (2022)](https://arxiv.org/abs/2201.11903).
 
-By requiring the model to generate a textual explanation *before* assigning numerical scores, we ensure the model "thinks" through the evidence before committing to a decision. This is implemented directly in our Pydantic schemas (e.g., `src/agents/cv_screening/schemas/output_schema.py`), where field order matters:
+By requiring the model to generate a textual explanation *before* assigning numerical scores, we ensure the model "thinks" through the evidence before committing to a decision. This is implemented directly in our Pydantic schemas (e.g., `src/backend/agents/cv_screening/schemas/output_schema.py`), where field order matters:
 
 ```mermaid
 flowchart LR
@@ -287,14 +362,14 @@ A breakdown of the various LLMs, Agents, and Workflows powering the system.
 
 | Component | Type | Model | Description | Location |
 | :--- | :--- | :--- | :--- | :--- |
-| **Supervisor Agent** | 🤖 **Agent** | `gpt-4o` | Orchestrates delegation, planning, and context management. | `src/agents/supervisor/supervisor_v2.py` |
-| **Gmail Agent** | 🤖 **Agent** | `gpt-4o` | Autonomous email management via MCP (read/send/label). | `src/agents/gmail/gmail_agent.py` |
-| **GCalendar Agent** | 🤖 **Agent** | `gpt-4o` | Autonomous calendar scheduling via MCP. | `src/agents/gcalendar/gcalendar_agent.py` |
-| **DB Executor** | 🤖 **Agent** | `gpt-4o` | Writes SQL/Python to query the database (CodeAct). | `src/agents/db_executor/db_executor.py` |
-| **CV Screening** | ⚙️ **Workflow** | `gpt-4o` | Deterministic pipeline: Fetch → Read → Evaluate → Save. | `src/agents/cv_screening/cv_screening_workflow.py` |
-| **Voice Judge** | 🧠 **Simple LLM** | `gpt-4o-audio` | Evaluates audio/transcripts for sentiment & confidence. | `src/agents/voice_screening/judge.py` |
-| **Doc Parser** | 🧠 **Simple LLM** | `gpt-4o-mini` | Vision-based PDF-to-Markdown conversion. | `src/doc_parser/pdf_to_markdown.py` |
-| **History Manager** | 🧠 **Simple LLM** | `gpt-4o-mini` | Summarizes conversation history for context compaction. | `src/context_eng/history_manager.py` |
+| **Supervisor Agent** | 🤖 **Agent** | `gpt-4o` | Orchestrates delegation, planning, and context management. | `src/backend/agents/supervisor/supervisor_v2.py` |
+| **Gmail Agent** | 🤖 **Agent** | `gpt-4o` | Autonomous email management via MCP (read/send/label). | `src/backend/agents/gmail/gmail_agent.py` |
+| **GCalendar Agent** | 🤖 **Agent** | `gpt-4o` | Autonomous calendar scheduling via MCP. | `src/backend/agents/gcalendar/gcalendar_agent.py` |
+| **DB Executor** | 🤖 **Agent** | `gpt-4o` | Writes SQL/Python to query the database (CodeAct). | `src/backend/agents/db_executor/db_executor.py` |
+| **CV Screening** | ⚙️ **Workflow** | `gpt-4o` | Deterministic pipeline: Fetch → Read → Evaluate → Save. | `src/backend/agents/cv_screening/cv_screening_workflow.py` |
+| **Voice Judge** | 🧠 **Simple LLM** | `gpt-4o-audio` | Evaluates audio/transcripts for sentiment & confidence. | `src/backend/agents/voice_screening/judge.py` |
+| **Doc Parser** | 🧠 **Simple LLM** | `gpt-4o-mini` | Vision-based PDF-to-Markdown conversion. | `src/backend/doc_parser/pdf_to_markdown.py` |
+| **History Manager** | 🧠 **Simple LLM** | `gpt-4o-mini` | Summarizes conversation history for context compaction. | `src/backend/context_eng/history_manager.py` |
 
 ### 🔌 ***`Integrated MCP Servers`***
 The system integrates **Model Context Protocol (MCP)** servers to securely and standardizedly connect agents to external tools.
@@ -316,3 +391,13 @@ This project utilizes code from:
   *Integrated at:* `src/mcp_servers/calendar-mcp/`
 
 We deeply acknowledge these original works and the great AI and Data Science community that makes such collaboration possible. We distribute our modifications under the compatible license terms.
+
+---
+
+## 👥 ***`Team`***
+| Member   |
+| -------- |
+| [Sebastian Wefers](https://github.com/Ocean-code-1995) |
+| [Dmitri Moscoglo](https://github.com/DimiM99) |
+| [Owen Kaplinsky](https://github.com/owenkaplinsky) |
+| [SrikarMK](https://github.com/Srikarmk) |

docker/Dockerfile.candidates_db_init

@@ -15,8 +15,10 @@ COPY ../requirements/base.txt ./requirements/base.txt
 COPY ../requirements/db.txt  ./requirements/db.txt
 RUN pip install --no-cache-dir -r requirements/db.txt
 
-# Copy *only* the candidate database module
-COPY src/database/candidates ./src/database/candidates
+# Copy required source modules
+COPY src/backend/database/candidates ./src/backend/database/candidates
+COPY src/backend/state ./src/backend/state
+COPY src/backend/configs ./src/backend/configs
 
 # Default command - use dedicated init script to avoid circular import
-CMD ["python", "-m", "src.database.candidates.init_db"]
+CMD ["python", "-m", "src.backend.database.candidates.init_db"]

docker/Dockerfile.supervisor_api

@@ -39,5 +39,5 @@ COPY .env /app/.env
 EXPOSE 8080
 
 # Run FastAPI with uvicorn
-CMD ["uvicorn", "src.api.app:app", "--host", "0.0.0.0", "--port", "8080"]
+CMD ["uvicorn", "src.backend.api.app:app", "--host", "0.0.0.0", "--port", "8080"]
 

docker/docker-compose.yml

@@ -19,6 +19,10 @@ services:
       interval: 3s
       timeout: 3s
       retries: 5
+    # Hey compose here is env file,
+    # pass it to container, but not the .env itself
+    env_file:
+      - ../.env
     environment:
       POSTGRES_HOST: ${POSTGRES_HOST}
       POSTGRES_PORT: ${POSTGRES_PORT}
@@ -34,18 +38,23 @@ services:
     # Initializes the database or starts the API (depending on command).
     container_name: candidates_db_init
     build:
-      context: .. # build from the project root
+      context: ..  # build from the project root
       dockerfile: docker/Dockerfile.candidates_db_init
     depends_on:
       db:
         condition: service_healthy
+    # Hey compose here is env file, 
+    # pass it to container, but not the .env itself
+    env_file:
+      - ../.env
     environment:
-      POSTGRES_HOST: ${POSTGRES_HOST}
-      POSTGRES_PORT: ${POSTGRES_PORT}
+      # Explicitly set POSTGRES_HOST to the service name 'db' for Docker networking
+      POSTGRES_HOST: db
+      POSTGRES_PORT: 5432
       POSTGRES_USER: ${POSTGRES_USER}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
       POSTGRES_DB: ${POSTGRES_DB}
-    # command: ["python", "-m", "src.database.candidates.init_db"]
+    command: ["python", "-m", "src.backend.database.candidates.init_db"]
 
     volumes:
       # --- Local code mount (for development only) ---
@@ -53,7 +62,7 @@ services:
       # into the container at /app.
       # ✅ Enables live code changes without rebuilding the image.
       # ⚠️ Do NOT use in production – overrides the built image code.
-      - ../:/app # optional: live reload for local dev
+      - ../:/app  # optional: live reload for local dev
 
     networks:
       - hrnet
@@ -69,15 +78,17 @@ services:
     depends_on:
       - db
       - supervisor_api
+    env_file:
+      - ../.env
     environment:
       # Database connection
-      POSTGRES_HOST: ${POSTGRES_HOST}
-      POSTGRES_PORT: ${POSTGRES_PORT}
+      POSTGRES_HOST: db
+      POSTGRES_PORT: 5432
       POSTGRES_USER: ${POSTGRES_USER}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
       POSTGRES_DB: ${POSTGRES_DB}
-      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
-      CV_UPLOAD_PATH: /app/src/database/cvs/uploads
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
+      CV_UPLOAD_PATH: /app/src/backend/database/cvs/uploads
       # App specific
       CV_UPLOAD_API_URL: http://supervisor_api:8080/api/v1/cv
       PYTHONPATH: /app
@@ -85,15 +96,8 @@ services:
       # Mount local code for live updates
       - ../:/app
       # Shared volume for CV uploads (persistent)
-      - ../src/database/cvs:/app/src/database/cvs
-    command:
-      [
-        "streamlit",
-        "run",
-        "src/frontend/streamlit/cv_ui/app.py",
-        "--server.port=8501",
-        "--server.address=0.0.0.0",
-      ]
+      - ../src/backend/database/cvs:/app/src/backend/database/cvs
+    command: ["streamlit", "run", "src/frontend/streamlit/cv_ui/app.py", "--server.port=8501", "--server.address=0.0.0.0"]
     networks:
       - hrnet
 
@@ -105,6 +109,8 @@ services:
       dockerfile: docker/Dockerfile.voice_proxy
     ports:
       - "8000:8000"
+    env_file:
+      - ../.env
     depends_on:
       - db
       - candidates_db_init
@@ -112,20 +118,16 @@ services:
       PYTHONPATH: /app
       OPENAI_API_KEY: ${OPENAI_API_KEY}
       BACKEND_API_URL: http://supervisor_api:8080
+      # Database connection
+      POSTGRES_HOST: db
+      POSTGRES_PORT: 5432
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
     volumes:
       # Mount local code for live updates
       - ../:/app
-    command:
-      [
-        "python",
-        "-m",
-        "uvicorn",
-        "src.frontend.streamlit.voice_screening_ui.proxy:app",
-        "--host",
-        "0.0.0.0",
-        "--port",
-        "8000",
-      ]
+    command: ["python", "-m", "uvicorn", "src.frontend.streamlit.voice_screening_ui.proxy:app", "--host", "0.0.0.0", "--port", "8000"]
     networks:
       - hrnet
 
@@ -136,10 +138,12 @@ services:
       context: ..
       dockerfile: docker/Dockerfile.voice_screening
     ports:
-      - "8502:8501" # Map host port 8502 to container port 8501
+      - "8502:8501"  # Map host port 8502 to container port 8501
     depends_on:
       - db
       - websocket_proxy
+    env_file:
+      - ../.env
     environment:
       DATABASE_URL: postgresql://agentic_user:password123@db:5432/agentic_hr
       PYTHONPATH: /app
@@ -148,14 +152,7 @@ services:
     volumes:
       # Mount local code for live updates
       - ../:/app
-    command:
-      [
-        "streamlit",
-        "run",
-        "src/frontend/streamlit/voice_screening_ui/app.py",
-        "--server.port=8501",
-        "--server.address=0.0.0.0",
-      ]
+    command: ["streamlit", "run", "src/frontend/streamlit/voice_screening_ui/app.py", "--server.port=8501", "--server.address=0.0.0.0"]
     networks:
       - hrnet
 
@@ -166,13 +163,15 @@ services:
       context: ..
       dockerfile: docker/Dockerfile.supervisor_api
     ports:
-      - "8080:8080" # Map host port 8080 to container port 8080
+      - "8080:8080"  # Map host port 8080 to container port 8080
     depends_on:
       - db
+    env_file:
+      - ../.env
     environment:
       # We set POSTGRES_HOST to 'db' so the agent connects to the container internal network
-      POSTGRES_HOST: ${POSTGRES_HOST}
-      POSTGRES_PORT: ${POSTGRES_PORT}
+      POSTGRES_HOST: db
+      POSTGRES_PORT: 5432
       POSTGRES_USER: ${POSTGRES_USER}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
       POSTGRES_DB: ${POSTGRES_DB}
@@ -180,19 +179,12 @@ services:
       PROMPTLAYER_API_KEY: ${PROMPTLAYER_API_KEY}
       OPENAI_API_KEY: ${OPENAI_API_KEY}
       WEBSOCKET_PROXY_URL: ws://websocket_proxy:8000/ws/realtime
+      CV_UPLOAD_PATH: /app/src/backend/database/cvs/uploads
+      CV_PARSED_PATH: /app/src/backend/database/cvs/parsed
     volumes:
       # Mount local code for live updates
       - ../:/app
-    command:
-      [
-        "uvicorn",
-        "src.api.app:app",
-        "--host",
-        "0.0.0.0",
-        "--port",
-        "8080",
-        "--reload",
-      ]
+    command: ["uvicorn", "src.backend.api.app:app", "--host", "0.0.0.0", "--port", "8080", "--reload"]
     networks:
       - hrnet
 
@@ -203,10 +195,12 @@ services:
       context: ..
       dockerfile: docker/Dockerfile.supervisor
     ports:
-      - "8503:8501" # Map host port 8503 to container port 8501
+      - "8503:8501"  # Map host port 8503 to container port 8501
     depends_on:
       - db
       - supervisor_api
+    env_file:
+      - ../.env
     environment:
       # We set POSTGRES_HOST to 'db' so the agent connects to the container internal network
       PYTHONPATH: /app

docker/info.md

@@ -20,6 +20,7 @@
 docker compose --env-file .env -f docker/docker-compose.yml up --build
 ```
 
+
 ---
 
 ### Resetting the Environment
@@ -30,11 +31,14 @@ To completely reset the environment and database:
 
 ```bash
 # 1. Stop running containers
-docker compose -f docker/docker-compose.yml down
+docker compose -f docker/docker-compose.yml down --remove-orphans
 
 # 2. Remove the persistent database volume
 docker volume rm docker_postgres_data
 
-# 3. Rebuild and start fresh
+# 3. Prune unused Docker resources (optional but recommended)
+docker system prune -f
+
+# 4. Rebuild and start fresh
 docker compose --env-file .env -f docker/docker-compose.yml up --build
 ```

docs/intro.md

@@ -0,0 +1,457 @@
+# ***`Gradio Agents & MCP Hackathon Winter Edition 2025`***
+
+## 🏁 Overview
+This repository hosts our team's submission for **Track 2: MCP in Action** in the [MCP's 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday).
+
+Our goal is to build an **autonomous agentic system** that demonstrates:
+- **Planning, reasoning, and execution**
+- Integration of **custom tools, MCP tools, or external APIs**
+- Effective **context engineering**
+- Clear, practical **user value**
+
+We'll use **LangGraph** as our orchestration backbone for building multi-turn, tool-using, and context-aware agents.
+
+> ***`Check hackathon README for detilaed requirements.`***
+
+## 🧠 ***`Tools & Frameworks`***
+
+- 🧩 [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview): for multi-agent orchestration and planning
+  - Why & how they built [LangGraph for production agents](https://blog.langchain.com/building-langgraph/)
+- 🧠 **LLM Engines:** [OpenAI](https://openai.com) / [Anthropic](https://www.anthropic.com) — reasoning and planning models
+  - gpt-oss inference providers
+    - [Open Router](https://openrouter.ai/openai/gpt-oss-20b):
+      - LangChain Wrapper: https://github.com/langchain-ai/langchain/discussions/27964
+    - [TogetherAI](https://www.together.ai/openai)
+- 💬 [Gradio](https://www.gradio.app/): for the UI and context-engineering demos
+- ⚙️ [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) Tools: standardized interfaces for Gmail, Google Calendar, Voice technologies and other APIs
+- ☁️ [Google Cloud Platform](https://cloud.google.com): optional backend for hosting MCP servers and integrated services
+- 📞 [Twilio](https://www.twilio.com/en-us): enables automated voice calls and candidate interactions
+- 🔊 [ElevenLabs](https://elevenlabs.io): (optional) natural text-to-speech for realistic voice screenings
+- 🎙️ [Whisper-based Transcription API](https://whisperapi.com) (or [OpenAI Whisper API](https://platform.openai.com/docs/guides/speech-to-text) ) — for speech-to-text functionality in voice interviews
+- 🧭 [Langfuse](https://langfuse.com) or [LangSmith](https://docs.langchain.com/langsmith/quick-start-studio): debugging, observability, and trace visualization
+- 📄 [Docling](https://www.docling.ai): for parsing and analyzing uploaded CV documents
+- 🧱 [Pydantic](https://docs.pydantic.dev/latest/): for structured outputs and data validation
+- 🔀 [Parlant](https://github.com/emcie-co/parlant): enables agents to handle multi-intent, free-form conversations by dynamically activating relevant guidelines instead of rigidly routing to a single sub-agent — solving the context fragmentation problem inherent in traditional LangGraph supervisor patterns.
+
+## 📚 ***`References for Context Engineering`***
+
+- [**Context Engineering for AI Agents — Manus Blog**](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
+- [**YouTube Talk Manus**](https://www.youtube.com/watch?v=6_BcCthVvb8&start=2525)
+- [**LangGraph Overview**](https://docs.langchain.com/oss/python/langgraph/overview)
+- https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+- https://medium.com/fundamentals-of-artificial-intelligence/mitigate-context-poisoning-in-ai-agents-using-context-engineering-96cf40dbb38d
+- https://blog.langchain.com/context-engineering-for-agents/
+- **langgraph implementations**
+  - [video]((https://www.youtube.com/watch?v=nyKvyRrpbyY))
+  - [good notebooks](https://github.com/langchain-ai/how_to_fix_your_context/blob/main/notebooks/utils.py)
+- [Langgraph summary of what frontier labs and firms apply](https://www.youtube.com/watch?v=XFCkrYHHfpQ)
+
+These resources guide our approach to **memory management, planning transparency, and tool orchestration** in autonomous agents.
+
+## 🧾  ***`HR Candidate Screening Multi-Agent System`***
+An autonomous HR assistant that streamlines early recruitment through five steps:
+1. **CV Upload (Application)** — candidate applications uploaded and parsed
+2. **CV Screening** — rank and shortlist candidates using LLM reasoning
+3. **Voice Screening** — invite and coordinate interviews using a voice agent.
+4. **Person-to-Person Screening** — schedule HR interviews via Google Calendar integration
+5. **Decision** — generate a concise summary and notify HR
+
+> **`NOTE`**
+> - Final decision of whether candidate will be hired is made by human.
+> - Just automate the boring, tedious stuff while keeping human final decision in the loop.
+
+**Architecture:**
+1. **Main Planner Agent**: orchestrates the workflow
+2. **Subagents**:
+  - CV Screening Agent
+  - Voice Screening Agent
+  - Meeting Scheduler Agent
+3. **Tools (via MCP)** connect to Gmail, Calendar, and Voice APIs.
+4. **Database** stores both candidate info and persistent agent memory.
+5. **Gradio UI** visualizes workflow, reasoning, and results.
+```mermaid
+flowchart TD
+    subgraph MainAgent["🧠 Main Planner Agent"]
+        A1["Plans • Reasons • Executes"]
+    end
+
+    subgraph Subagents["🤖 Subagents"]
+        S1["📄 CV Screening"]
+        S2["🎙️ Voice Screening"]
+        S3["📅 Scheduling"]
+        S4["🧾 Decision Summary"]
+    end
+
+    subgraph Tools["⚙️ MCP & External Tools"]
+        T1["📧 Gmail"]
+        T2["🗓️ Google Calendar"]
+        T3["🗣️ Voice API"]
+    end
+
+    subgraph Data["🗄️ Database"]
+        D1["Candidate Data"]
+        D2["Context Memory (Cognitive Offloading)"]
+    end
+
+    subgraph UI["💬 Gradio Dashboard"]
+        U1["HR View & Interaction"]
+    end
+
+    %% Connections
+    MainAgent --> Subagents
+    Subagents --> Tools
+    Subagents --> Data
+    MainAgent --> Data
+    MainAgent --> UI
+```
+
+**GCP Setup for Judges:**
+A single demo Gmail/Calendar account (`scionhire.demo@gmail.com`) is pre-authorized via OAuth, with stored credentials in `.env`.
+Judges can run or view the live demo without any credential setup, experiencing real Gmail + Calendar automation safely.
+
+We use **hierarchical planning**:
+- **Main Agent:** decides next step in the workflow (plan, adapt, replan)
+- **Subagents:** specialized executors (screening, scheduling, summarization)
+- **Memory State:** tracks plan progress and tool results  
+- **Dashboard Visualization:** shows active plan steps and reasoning traces for transparency
+
+🧠 Why This Is an Agent (Not Just a Workflow)
+
+| Criterion | Workflow | Our System |
+|------------|-----------|-------------|
+| **Autonomy** | Executes fixed sequence of steps | Main agent decides next actions without manual triggers |
+| **Planning** | Predefined order (A → B → C) | Main agent generates and adapts a plan (e.g., skip, retry, re-order) |
+| **Reasoning** | No decision logic | Uses LLM reasoning to evaluate outputs and choose next subagent |
+| **Context Awareness** | Stateless | Maintains shared memory of candidates, progress, and outcomes |
+| **Adaptation** | Fails or stops on error | Re-plans (e.g., if calendar slots full or candidate unresponsive) |
+
+✅ **Therefore:** it qualifies as an *agentic system* because it **plans, reasons, and executes** autonomously rather than following a static workflow.
+
+## ***`Project Structure`***
+```
+agentic-hr/
+│
+├── 📁 src/
+│ │
+│ ├── 📁 core/
+│ │ │ ├── base_agent.py           # Abstract BaseAgent (LangGraph-compatible)
+│ │ │ ├── supervisor.py           # Supervisor agent (LangGraph graph assembly)
+│ │ │ ├── state.py                # Shared AgentState + context window
+│ │ │ ├── planner.py              # High-level planning logic
+│ │ │ └── executor.py             # Graph executor / runner
+│ │
+│ ├── 📁 agents/
+│ │ │
+│ │ ├── 📁 cv_screening/
+│ │ │ │ ├── agent.py              # CVScreeningAgent implementation
+│ │ │ │ ├── 📁 tools/
+│ │ │ │ │ ├── doc_parser.py
+│ │ │ │ │ ├── normalize_skills.py
+│ │ │ │ │ ├── rank_candidates.py
+│ │ │ │ │ └── match_to_jd.py
+│ │ │ │ └── 📁 schemas/
+│ │ │ │     ├── cv_schema.py      # Parsed CV Pydantic schema
+│ │ │ │     └── jd_schema.py      # Job description schema
+│ │ │
+│ │ ├── 📁 voice_screening/
+│ │ │ │ ├── agent.py              # VoiceScreeningAgent
+│ │ │ │ ├── 📁 tools/
+│ │ │ │ │ ├── twilio_client.py
+│ │ │ │ │ ├── whisper_transcribe.py
+│ │ │ │ │ └── tts_service.py
+│ │ │ │ └── 📁 schemas/
+│ │ │ │     ├── call_result.py
+│ │ │ │     └── transcript.py
+│ │ │
+│ │ ├── 📁 scheduler/
+│ │ │ │ ├── agent.py              # SchedulerAgent
+│ │ │ │ ├── 📁 tools/
+│ │ │ │ │ ├── calendar_tool.py
+│ │ │ │ │ ├── gmail_tool.py
+│ │ │ │ │ └── slot_optimizer.py
+│ │ │ │ └── 📁 schemas/
+│ │ │ │     └── meeting_schema.py
+│ │ │
+│ │ └── 📁 decision/
+│ │     ├── agent.py              # DecisionAgent (final summarizer/Reporter)
+│ │     └── 📁 schemas/
+│ │         └── decision_report.py
+│ │
+│ ├── 📁 mcp_server/
+│ │   ├── main.py
+│ │   ├── 📁 endpoints/
+│ │   ├── auth.py
+│ │   └── schemas.py
+│ │
+│ ├── 📁 gradio/
+│ │   ├── app.py                  # Main Gradio app (Hugging Face Space entry)
+│ │   ├── dashboard.py            # Live agent graph & logs view
+│ │   ├── candidate_portal.py     # Candidate upload / screening status
+│ │   ├── hr_portal.py            # HR review + interview approval
+│ │   ├── components.py           # Shared Gradio components
+│ │   └── 📁 assets/              # Logos, CSS, etc.
+│ │
+│ ├── 📁 cv_ui/
+│ │   ├── app.py 
+│ │
+��� ├── 📁 voice_screening_ui/
+│ │   ├── app.py 
+│ │
+│ │
+│ ├── 📁 prompts/
+│ │   ├── prompt_manager.py       # Centralized prompt versioning
+│ │   ├── cv_prompts.py
+│ │   ├── voice_prompts.py
+│ │   └── scheduler_prompts.py
+│ │
+│ ├── 📁 database/
+│ │   ├── models.py               # SQLAlchemy models
+│ │   ├── db_client.py            # Connection & CRUD
+│ │   └── context_sync.py         # Cognitive offloading (context ⇄ DB)
+│ │
+│ ├── main.py                     # CLI runner / local orchestrator entry
+│ └── config.py                   # Environment configuration
+│
+├── 📁 tests/
+│ │ ├── test_cv_agent.py
+│ │ ├── test_voice_agent.py
+│ │ ├── test_scheduler_agent.py
+│ │ ├── test_mcp_server.py
+│ │ └── test_integration.py
+│
+├── .env.example
+├── requirements.txt
+├── Dockerfile
+├── app.py                         # Shortcut to src/ui/app.py
+├── README.md
+└── LICENSE
+```
+
+## ***`Multi Agent System Architecture`***
+Below you will find an overview of the subagent components that mnake upo the entire system. More detailed information and brainstorming is decicated to the `docs/agents/..` directory.
+
+### 1) ***`Orchestrator`***
+#### Overview
+
+The orchestrator agent is reponsible for **supervising** and **triggering** the ***tasks of the subagents***.
+
+> For more planning and info, go to `docs/agents/agent_orchestrator.md`
+
+### 2) ***`CV Screener`***
+#### Overview
+The cv screening agent deals with scanning the applicant's CV's, and deciding who are fruitful versus unpromising candidates as a first filtering step.
+
+> For more planning and info, go to `docs/agents/cv_screening.md`
+
+### 3) 🎙️ ***`Voice Screening Agent`***
+
+#### Overview
+The **Voice Screening Agent** conducts automated phone interviews and integrates with the **LangGraph HR Orchestrator**.  
+It uses **Twilio** for phone calls, **Whisper/ASR** for speech-to-text, **ElevenLabs** for natural voice output, and **LangGraph** for dialogue logic.
+
+> For more planning and info, go to `docs/agents/voice_screening.md`
+
+### 4) ***`Google MCP Agents`***
+#### Overview
+The google mcp agents will be resposnible to:
+a) writing emails
+b) scheduling and menaging google calendar events
+
+It adviseable to break this up into two subagents, to get rid of `context poisoning`.
+
+> For more planning and info, go to `docs/agents/google_mcp_agent.md`
+
+### 4) ***`LLM as a Judge`***
+#### Overview
+LLM-as-a-judge will be leveraged to judge call screening results.
+
+> For more planning and info, go to `docs/agents/judging_agent.md`
+
+## 🗄️ ***`Data Layer`***
+
+The system uses a unified **SQLAlchemy-based database** for both **candidate data management** and **context engineering**.
+
+### 📦 Purpose
+| Data Type | Description |
+|------------|--------------|
+| 🧾 **Candidates** | Stores CVs, parsed data, and screening results |
+| 🎙️ **Voice Results** | Saves transcripts, evaluations, and tone analysis |
+| 🗓️ **Scheduling** | Tracks HR availability and confirmed interviews |
+| 🧠 **Agent Context Memory** | Enables **cognitive offloading** — storing reasoning traces and summaries so the active context stays uncluttered and information can be recalled when needed |
+| 📚 **Logs / Tool History** | Archives tool interactions and results for transparency and reuse |
+
+We use [**SQLAlchemy**](https://www.sqlalchemy.org) as the ORM layer to manage both structured candidate data and **persistent agent memory**, allowing the system to offload, summarize, and retrieve context efficiently across sessions.
+
+## 🗃️ ***`Prompt Archive`***
+
+To ensure consistent behavior and easy experimentation across subagents, the system includes a **centralized prompt management layer**.
+
+### 📦 Purpose
+| Component | Description |
+|------------|--------------|
+| 🧠 **Prompt Templates** | Stores standardized prompts for each subagent (CV screening, voice screening, scheduling) |
+| 🔄 **Prompt Versioning** | Allows tracking and updating of prompt iterations without changing agent code |
+| 🧩 **Dynamic Injection** | Enables context-dependent prompt construction using retrieved memory or database summaries |
+| 📚 **Archive** | Keeps older prompt variants for reproducibility and ablation testing |
+
+## 📺 ***`Gradio Interface`***
+
+We use **Gradio** to demonstrate our agent's reasoning, planning, and tool use interactively — fully aligned with the **Agents & MCP Hackathon** focus on **context engineering** and **user value**.
+
+### 🧩 Key Features
+| Section | Purpose |
+|----------|----------|
+| 🧍 **Candidate Portal** | Upload CVs, submit applications, and view screening results |
+| 🧑‍💼 **HR Portal** | Review shortlisted candidates, trigger voice screenings, and schedule interviews |
+| 🧠 **Agent Dashboard** | Visualizes the current plan, tool calls, and reasoning traces in real time |
+| ⚙️ **Tool Integration** | Shows live MCP actions (Gmail send, Calendar scheduling) with status updates |
+| 📊 **Context View** | Displays agent memory, current workflow stage, and adaptive plan updates |
+
+#### Context Engineering Visualization?
+This is what judges really care about — it must show that the system is agentic (reasoning, memory, planning).
+🧠 Agent Plan Viewer
+gr.JSON() or custom visual showing the current plan state, e.g.:
+```json
+{
+  "plan": [
+    "1. Screen CVs ✅",
+    "2. Invite for voice screening 🔄",
+    "3. Schedule HR interview ⬜",
+    "4. Await HR decision ⬜"
+  ]
+}
+```
+🗺️ Live Plan Progress
+- Use a progress bar or color-coded status list of steps.
+- Judges must see autonomous transitions (from one step to another).
+
+💬 Reasoning Log / Memory
+- Stream or text box showing LLM thought traces or context summary:
+  - “Detected strong match for Data Scientist role.”
+  - “Candidate completed voice interview; confidence: 8.4/10.”
+  - “Next step: scheduling HR interview.”
+
+⚙️ Tool Call Trace
+- Small table showing:
+
+| Time  | Tool     | Action           | Result    |
+| ----- | -------- | ---------------- | --------- |
+| 12:05 | Gmail    | `send_invite()`  | Sent      |
+| 12:06 | Calendar | `create_event()` | Confirmed |
+
+## 🔗 ***`MCP Integration (Best Practice Setup)`***
+
+To align fully with the **Agents & MCP Hackathon** standards, our system will use or extend a **standardized MCP server** for integrations such as **Gmail** and **Google Calendar** — and potentially **Scion Voice** in later stages.
+
+**`Inspired by`** [Huggingface MCP Course](https://huggingface.co/learn/mcp-course/en/unit2/introduction): shows how to build an MCP app.
+
+### 🧩 Why MCP?
+| Benefit | Description |
+|----------|--------------|
+| ✅ **Standardized** | Exposes Gmail & Calendar as reusable MCP tools with a consistent schema |
+| 🔐 **Secure** | OAuth handled once server-side — no tokens or secrets stored in the agent |
+| 🧱 **Modular** | Clean separation between the agent's reasoning logic and the integration layer |
+| 🔄 **Reusable** | Same MCP server can serve multiple projects or agents |
+| 🚀 **Hackathon-Ready** | Directly fulfills the “use MCP tools or external APIs” requirement |
+
+---
+
+### ⚙️ Why Use MCP Instead of Just Defining Tools
+| Approach | Limitation / Risk | MCP Advantage |
+|-----------|-------------------|----------------|
+| **Custom-defined tools** (e.g., direct Gmail API calls in code) | Each project must re-implement auth, rate limits, and API logic | MCP provides a *shared, pre-authorized* interface any agent can use |
+| **Embedded credentials** in `.env` | Security risk, harder for judges to test | Credentials handled server-side — no secrets in the repo |
+| **Tight coupling** between agent and tool | Hard to swap or extend integrations | MCP creates a plug-and-play API boundary between reasoning and execution |
+| **Limited reuse** | Tools only exist in one codebase | MCP servers can expose many tools to multiple agents dynamically |
+
+MCP turns these one-off integrations into **standardized, composable building blocks** that work across agents, organizations, or platforms — the same philosophy used by **Anthropic**, **LangChain**, and **Hugging Face** in 2025 agent ecosystems.
+
+
+We will build or extend the open-source [**mcp-gsuite**](https://github.com/MarkusPfundstein/mcp-gsuite) server and host it securely on **Google Cloud Run**.  
+This server manages authentication, token refresh, and rate limiting — while exposing standardized MCP actions like:
+```json
+{
+  "action": "gmail.send",
+  "parameters": { "to": "candidate@example.com", "subject": "Interview Invite", "body": "..." }
+}
+```
+
+and
+
+```json
+{
+  "action": "calendar.create_event",
+  "parameters": { "summary": "HR Interview", "start": "...", "end": "..." }
+}
+```
+This architecture lets our HR agent (and future projects) perform real email and scheduling actions via secure MCP endpoints — giving judges a safe, live demo of true agentic behavior with no local credential setup required.
+
+## 🧠 ***`Agent Supervisor — Why Parlant + LangGraph`***
+
+LangGraph provides a powerful orchestration backbone for planning, reasoning, and executing multi-agent workflows.  
+However, its common **supervisor pattern** has a key limitation: the supervisor routes each user query to **only one sub-agent** at a time.
+
+### ⚠️ Example Problem
+> “I uploaded my CV yesterday. Can I also reschedule my interview — and how long is the voice call?”
+
+A standard LangGraph supervisor would forward this entire message to, say, the **CV Screening Agent**,  
+missing the **scheduling** and **voice screening** parts — causing incomplete or fragmented responses.
+
+### 💡 Parlant as the Fix
+**[Parlant](https://github.com/emcie-co/parlant)** solves this by replacing single-route logic with **dynamic guideline activation**.  
+Instead of rigid routing, it loads multiple relevant *guidelines* into context simultaneously, allowing coherent handling of mixed intents.
+
+```python
+agent.create_guideline(
+  condition="User asks about rescheduling",
+  action="Call SchedulerAgent via LangGraph tool"
+)
+
+agent.create_guideline(
+  condition="User asks about voice screening duration",
+  action="Query VoiceScreeningAgent"
+)
+```
+
+If a user blends both topics, ***both guidelines trigger***, producing a unified, context-aware response.
+
+### ⚙️ Why Combine Them
+| Layer                         | Framework     | Role                                                                    |
+| ----------------------------- | ------------- | ----------------------------------------------------------------------- |
+| 🧠 **Workflow Orchestration** | **LangGraph** | Executes structured agent workflows (CV → Voice → Schedule → Decision). |
+| 💬 **Conversational Layer**   | **Parlant**   | Dynamically manages mixed intents using guideline-based reasoning.      |
+| 🔧 **Integration Layer**      | **MCP Tools** | Provides standardized access to Gmail, Calendar, and Voice APIs.        |
+
+
+Together, ***Parlant + LangGraph*** merge structured planning with conversational adaptability —
+enabling our HR agent to reason, plan, and respond naturally to complex, multi-topic interactions.
+
+## ✨ ***`Agentic Enhancements [BONUS]`***
+
+To make the system more **autonomous, interpretable, and resilient**, we integrated a few lightweight yet powerful improvements:
+
+- 🧠 **Self-Reflection** – before executing a step, the agent briefly states *why* it's taking that action, improving reasoning transparency.  
+- 🔄 **Adaptive Re-Planning** – if a subagent or tool call fails (e.g., no calendar slot, missing response, or API timeout), the main planner automatically updates its plan — skipping, retrying, or re-ordering steps instead of stopping.  
+- 🧮 **LLM Self-Evaluation** – after each stage (CV, voice, scheduling), a lightweight judge model rates the result and adds feedback for the next step.  
+- 🗂️ **Context Summary** – the dashboard displays a live summary of all candidates, their current stage, and key outcomes.  
+- 🤝 **Human-in-the-Loop Checkpoint** – HR receives a short confirmation prompt before final scheduling to ensure responsible autonomy.
+
+These enhancements demonstrate **true agentic behavior** — autonomous planning, adaptive execution, and transparent reasoning — in a simple, explainable way.
+
+## 👥 ***`Team`***
+| Member   |
+| -------- |
+| [Sebastian Wefers](https://github.com/Ocean-code-1995) |
+| [Owen Kaplinsky](https://github.com/owenkaplinsky) |
+| [SrikarMK](https://github.com/Srikarmk) |
+| [Dmitri Moscoglo](https://github.com/DimiM99) |
+
+# ***`License`***
+
+This project includes and builds upon [gmail-mcp](https://github.com/theposch/gmail-mcp),  
+which is licensed under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).
+
+This repository extends gmail-mcp for experimental integration and automation with Claude Desktop.  
+All modifications are distributed under the same GPLv3 license.
+
+> **Note:** The original gmail-mcp code has not been modified at this stage.

docs/video/script.md

@@ -0,0 +1,69 @@
+# Video Demo Script
+
+This script outlines the flow and queries for the demo video.
+
+## Prerequisites / Setup
+
+
+Manually create:
+1. **Existing Candidate**: "Jane Doe"
+   - Status: `voice_passed` (Ready for final interview)
+   - Includes fake CV and Voice Screening results for the agent to analyze.
+
+
+## Demo Flow
+
+### 1. The New Applicant & Morning Check-in
+*Action 1: Switch to the **CV Portal UI** and upload a new CV for "Alex Smith" (applying him to the system).*
+
+*Goal: Show the agent's awareness of the current database state (both old and new candidates).*
+
+**Query 1:**
+```text
+Hi! Can you give me a summary of the current recruitment status? Who are the active candidates and what stages are they in?
+```
+
+
+---
+
+### 2. CV Screening
+*Goal: Demonstrate the CV screening workflow.*
+
+**Query 2:**
+```text
+I see PERSON X is a new applicant. Can you please screen his CV and summarize the feedback and his score?
+```
+
+**Query 3:**
+```text
+Send him an email invitation for the voice screening!
+```
+
+-> Then do voice screening!
+
+---
+
+### 3. Reviewing the Candidate
+*Goal: Show the "Voice Judge" results and Calendar/Email integration.*
+
+**Query 4:**
+```text
+I see she/he completed the voice screening. Can you analyze her interview transcript and tell me how she performed?
+```
+
+*(Expected Response: Agent reads the voice analysis/judge score and summarizes the candidate's strengths/weaknesses.)*
+
+**Query 5:**
+```text
+That sounds promising. Let's move her to the final stage. Please schedule a person-to-person interview with her for next Tuesday at 10 AM. Add it to the HR calendar and send her a calendar invitation.
+```
+
+---
+
+### 4. Final Status Check
+*Goal: Confirm all actions were executed.*
+
+**Query 6:**
+```text
+Thanks! Can you show me the updated pipeline status?
+```

intro.md

@@ -455,3 +455,4 @@ This repository extends gmail-mcp for experimental integration and automation wi
 All modifications are distributed under the same GPLv3 license.
 
 > **Note:** The original gmail-mcp code has not been modified at this stage.
+> 

requirements/agent.txt

@@ -1,4 +1,3 @@
 langchain
 langchain-openai
 langgraph
-uv

scripts/db/list_candidates.py

@@ -10,8 +10,8 @@ from sqlalchemy.exc import ProgrammingError
 # Ensure project root is in path
 import scripts.db  # noqa: F401
 
-from src.database.candidates.client import SessionLocal
-from src.database.candidates.models import Candidate
+from src.backend.database.candidates.client import SessionLocal
+from src.backend.database.candidates.models import Candidate
 
 
 def list_candidates(limit: int = 10) -> bool:
@@ -41,7 +41,17 @@ def list_candidates(limit: int = 10) -> bool:
                 .all()
             )
             for c in candidates:
-                print(f" - {c.full_name} | {c.email} | Status: {c.status}")
+                print(f" - ID: {c.id}")
+                print(f"   Full Name: {c.full_name}")
+                print(f"   Email: {c.email}")
+                print(f"   Phone: {c.phone_number}")
+                print(f"   CV Path: {c.cv_file_path}")
+                print(f"   Parsed CV Path: {c.parsed_cv_file_path}")
+                print(f"   Status: {c.status}")
+                print(f"   Auth Code: {c.auth_code}")
+                print(f"   Created At: {c.created_at}")
+                print(f"   Updated At: {c.updated_at}")
+                print("-" * 40)
         
         return True
 

scripts/db/setup_demo_state.py

@@ -0,0 +1,65 @@
+import uuid
+from datetime import datetime, timedelta
+from src.backend.database.candidates.client import SessionLocal
+from src.backend.database.candidates.models import Candidate, CVScreeningResult, VoiceScreeningResult
+from src.backend.state.candidate import CandidateStatus
+
+def setup_demo_state():
+    print("🚀 Setting up demo state...")
+    session = SessionLocal()
+    
+    # 1. Cleanup existing Jane Doe
+    existing = session.query(Candidate).filter(Candidate.email == "jane.doe@example.com").first()
+    if existing:
+        print(f"Creating clean slate: Deleting existing candidate {existing.full_name}...")
+        session.delete(existing)
+        session.commit()
+
+    # 2. Create Candidate: Jane Doe (Advanced Stage)
+    candidate_id = uuid.uuid4()
+    jane = Candidate(
+        id=candidate_id,
+        full_name="Jane Doe",
+        email="jane.doe@example.com",
+        phone_number="+15550101",
+        status=CandidateStatus.voice_passed,  # Ready for final interview
+        created_at=datetime.utcnow() - timedelta(days=2)
+    )
+    session.add(jane)
+
+    # 3. Add CV Screening Result (She passed this previously)
+    cv_result = CVScreeningResult(
+        candidate_id=candidate_id,
+        job_title="Senior Product Manager",
+        skills_match_score=92.0,
+        experience_match_score=88.0,
+        education_match_score=95.0,
+        overall_fit_score=91.0,
+        llm_feedback="Candidate demonstrates exceptional strategic thinking and relevant experience in SaaS product management. Strong leadership background.",
+        timestamp=datetime.utcnow() - timedelta(days=2)
+    )
+    session.add(cv_result)
+
+    # 4. Add Voice Screening Result (She just completed this)
+    voice_result = VoiceScreeningResult(
+        candidate_id=candidate_id,
+        transcript_text="I have over 5 years of experience leading agile teams... I believe communication is key to product success... In my last role, I increased user retention by 20%...",
+        sentiment_score=0.8,
+        confidence_score=0.9,
+        communication_score=9.5,
+        llm_summary="Candidate spoke clearly and confidently. Provided concrete examples of past success (20% retention increase). demonstrated strong understanding of agile methodologies.",
+        llm_judgment_json={"decision": "pass", "reasoning": "High confidence and clear articulation of value."},
+        timestamp=datetime.utcnow() - timedelta(hours=1)
+    )
+    session.add(voice_result)
+
+    session.commit()
+    print(f"✅ Successfully created candidate: Jane Doe (ID: {candidate_id})")
+    print("   - Status: voice_passed")
+    print("   - Has CV Result: Yes")
+    print("   - Has Voice Result: Yes")
+    print("\nReady for demo video recording! 🎥")
+
+if __name__ == "__main__":
+    setup_demo_state()
+

scripts/db/test_connection.py

@@ -11,7 +11,7 @@ from sqlalchemy import text
 # Ensure project root is in path
 import scripts.db  # noqa: F401
 
-from src.database.candidates.client import get_engine
+from src.backend.database.candidates.client import get_engine
 
 
 def test_connection() -> bool:

scripts/db/test_cv_upload.py

@@ -0,0 +1,45 @@
+"""
+Test the CV upload functionality.
+Run with:
+>>> export PYTHONPATH=$PYTHONPATH:. && python3 scripts/db/test_cv_upload.py
+"""
+
+
+import os
+from src.sdk.cv_upload import CVUploadClient
+
+def test_upload():
+    client = CVUploadClient(base_url="http://localhost:8080/api/v1/cv")
+    
+    cv_path = "src/backend/database/cvs/uploads/Sebastian_Wefers_CV.pdf"
+    
+    if not os.path.exists(cv_path):
+        print(f"❌ CV file not found at {cv_path}")
+        return
+
+    print(f"📤 Uploading {cv_path}...")
+    
+    try:
+        with open(cv_path, "rb") as f:
+            response = client.submit(
+                full_name="Test Candidate",
+                email="test_candidate@example.com",
+                phone="+1234567890",
+                cv_file=f,
+                filename="test_candidate.pdf"
+            )
+        
+        if response.success:
+            print(f"✅ Upload successful: {response.message}")
+            print(f"Details: {response}")
+        elif response.already_exists:
+            print(f"⚠️ Candidate already exists: {response.message}")
+        else:
+            print(f"❌ Upload failed: {response.message}")
+
+    except Exception as e:
+        print(f"❌ Error during upload: {e}")
+
+if __name__ == "__main__":
+    test_upload()
+

scripts/db/test_session.py

@@ -10,7 +10,7 @@ from sqlalchemy import text
 # Ensure project root is in path
 import scripts.db  # noqa: F401
 
-from src.database.candidates.client import SessionLocal
+from src.backend.database.candidates.client import SessionLocal
 
 
 def test_session_query() -> bool:

scripts/db/wipe.py

@@ -11,7 +11,7 @@ from sqlalchemy import text
 project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../'))
 sys.path.append(project_root)
 
-from src.database.candidates.client import get_engine
+from src.backend.database.candidates.client import get_engine
 
 def wipe_database():
     print("⚠️  WARNING: This will PERMANENTLY DELETE ALL RECORDS from the 'candidates' table and all related tables (CASCADE).")

scripts/infra/reset_db.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Reset the database environment
+
+echo "🛑 Stopping containers..."
+docker compose -f docker/docker-compose.yml down
+
+echo "🗑️ Removing database volume..."
+docker volume rm docker_postgres_data
+
+echo "🚀 Rebuilding and starting..."
+docker compose --env-file .env -f docker/docker-compose.yml up --build
+

src/backend/agents/__init__.py

@@ -0,0 +1,14 @@
+from .db_executor import db_executor
+from .cv_screening import screen_cv, cv_screening_workflow
+from .gcalendar import gcalendar_agent
+from .gmail import gmail_agent
+from .voice_screening import voice_judge
+
+__all__ = [
+    "db_executor",
+    "screen_cv",
+    "cv_screening_workflow",
+    "gcalendar_agent",
+    "gmail_agent",
+    "voice_judge",
+]

src/backend/agents/cv_screening/__init__.py

@@ -0,0 +1,4 @@
+from .cv_screener import screen_cv
+from .cv_screening_workflow import cv_screening_workflow
+
+__all__ = ["screen_cv", "cv_screening_workflow"]

src/backend/agents/cv_screening/cv_screener.py

@@ -0,0 +1,88 @@
+"""CV Screening Agent Module
+
+Run as follows:
+>>> docker compose up --build
+>>> docker compose run --rm candidates_db_init python -m src.agents.cv_screening.screener
+"""
+import json
+from langchain_openai import ChatOpenAI
+from langchain.messages import SystemMessage, HumanMessage
+
+from dotenv import load_dotenv
+from src.backend.agents.cv_screening.schemas.output_schema import CVScreeningOutput
+from src.backend.agents.cv_screening.utils import read_file
+from src.backend.database.candidates import write_cv_results_to_db
+from src.backend.prompts import get_prompt
+
+load_dotenv()
+
+SYSTEM_PROMPT = get_prompt(
+    template_name="CV_Screener",
+    latest_version=True
+)
+
+# --- The evaluator function ---
+def screen_cv(cv_text: str, jd_text: str) -> CVScreeningOutput:
+    """
+    Evaluate a candidate's CV against a job description using an LLM.
+
+    Args:
+        cv_text (str): The text content of the candidate's CV.
+        jd_text (str): The text content of the Job Description.
+
+    Returns:
+        CVScreeningOutput: The structured screening result.
+        Makes model write feedback before scoring, leading to better calibration
+        and genuine reasoning that leads to more balanced scores.
+
+    **NOTE**: 
+    >>> The model generates feedback first (Chain-of-Thought) 
+    >>> to ensure calibrated scores.
+
+    """
+    llm = (
+        ChatOpenAI(
+            model="gpt-4o-mini",
+            temperature=0,
+            max_tokens=1500,
+        )
+        .with_structured_output(CVScreeningOutput)
+    )
+    # payload
+    messages = [
+        # Instruction
+        SystemMessage(
+            content=SYSTEM_PROMPT
+        ),
+        # Payload
+        HumanMessage(
+            content=(
+                f"Job Description:\n{jd_text}\n\n"
+                f"Candidate CV:\n{cv_text}\n"
+            )
+        ),
+    ]
+
+    return llm.invoke(messages)
+
+
+
+# --- Main execution for testing ---
+if __name__ == "__main__":
+    from pathlib import Path
+    #BASE_PATH = Path("/Users/sebastianwefers/Desktop/projects/recruitment-agent/src/database")
+    BASE_PATH = Path(__file__).resolve().parents[2] / "database"
+
+    cv_text = read_file(BASE_PATH / "cvs/parsed/c762271c-af8f-49db-acbb-e37e5f0f0f98_SWefers_CV-sections.txt")
+    jd_text = read_file(BASE_PATH / "cvs/job_postings/ai_engineer.txt")
+
+    # trigger evaluation
+    result = screen_cv(cv_text, jd_text)
+    print(json.dumps(result.model_dump(), indent=2))
+
+    # optionally write to DB
+    write_cv_results_to_db(
+        candidate_email="sebastianwefersnz@gmail.com",
+        result=result,
+        job_title="AI Engineer"
+    )

src/backend/agents/cv_screening/cv_screening_workflow.py

@@ -0,0 +1,108 @@
+from pathlib import Path
+from langchain_core.tools import tool
+
+
+from src.backend.agents.cv_screening.cv_screener import screen_cv
+from src.backend.agents.cv_screening.utils import read_file
+from src.backend.database.candidates import (
+    write_cv_results_to_db,
+    get_candidate_by_name,
+)
+
+@tool
+def cv_screening_workflow(candidate_full_name: str = "") -> str:
+    """
+    Runs the deterministic CV screening workflow for a candidate.
+    This is a fixed sequential process, not a reasoning agent.
+
+    Steps:
+    1. Retrieve candidate info from DB
+    2. Read files (CV & Job Description)
+    3. Evaluate CV
+    4. Store results in DB & update status
+
+    Args:
+        candidate_full_name (str): The full name of the candidate to screen.
+
+    Returns:
+        str: A message indicating the outcome of the workflow. (✅ or ❌)
+    """
+    if not candidate_full_name:
+        return "❌ Candidate name is required."
+
+    # 1️⃣ Retrieve candidate info from DB
+    print(f"🔍 Looking up candidate: {candidate_full_name}")
+    candidate = get_candidate_by_name(candidate_full_name)
+    
+    if not candidate:
+        return f"❌ Candidate '{candidate_full_name}' not found in database."
+
+    candidate_email = candidate["email"]
+    cv_path_str = candidate["parsed_cv_file_path"]
+    
+    if not cv_path_str:
+        return f"❌ No parsed CV path recorded for '{candidate_full_name}'."
+
+    # Resolve paths
+    # Assuming the parsed path in DB is relative to project root (e.g., src/backend/database/cvs/parsed/...)
+    # We need to ensure we can find it.
+    
+    # Calculate project root from this file location
+    # src/backend/agents/cv_screening/cv_screening_workflow.py -> 4 levels up to src -> 5 to root
+    root_dir = Path(__file__).resolve().parents[4]
+    
+    cv_path = root_dir / cv_path_str
+    if not cv_path.exists():
+        # Try treating it as absolute or check if the path in DB was absolute
+        cv_path = Path(cv_path_str)
+        if not cv_path.exists():
+            # Fallback: check legacy path just in case
+            legacy_path = root_dir / "src/database/cvs/parsed" / Path(cv_path_str).name
+            if legacy_path.exists():
+                cv_path = legacy_path
+            else:
+                return f"❌ CV file not found at: {cv_path_str} or {legacy_path}"
+
+    # JD path is constant for this MVP
+    jd_path = root_dir / "src/backend/database/job_postings/ai_engineer.txt"
+    
+    if not jd_path.exists():
+        return f"❌ Job description not found at: {jd_path}"
+
+    # 2️⃣ Read files
+    print(f"📄 Reading Job Description from: {jd_path}")
+    jd_text = read_file(jd_path)
+    
+    print(f"📄 Reading CV from: {cv_path}")
+    cv_text = read_file(cv_path)
+    
+
+    # 3️⃣ Evaluate CV
+    print("🧠 Running LLM screening...")
+    try:
+        result = screen_cv(cv_text, jd_text)
+    except Exception as e:
+        return f"❌ Error during LLM screening: {str(e)}"
+
+    # 4️⃣ Store results in DB & update status
+    print("💾 Saving results to database...")
+    try:
+        write_cv_results_to_db(
+            candidate_email=candidate_email,
+            result=result,
+            job_title="AI Engineer"
+        )
+    except Exception as e:
+        return f"❌ Error saving results to DB: {str(e)}"
+    
+    return f"✅ CV Screening Workflow completed successfully for {candidate_full_name}. Scores and feedback have been saved to the database."
+
+
+
+
+if __name__ == "__main__":
+    # Example usage for testing
+    # You can run this directly if you have a candidate in the DB
+    import sys
+    name = sys.argv[1] if len(sys.argv) > 1 else "Ada Lovelace"
+    cv_screening_workflow(name)

src/backend/agents/cv_screening/schemas/output_schema.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel, Field
+from typing import Optional, Dict, Any
+
+class CVScreeningOutput(BaseModel):
+    # CRITICAL: Keep llm_feedback as the first field. 
+    # This enforces Chain-of-Thought reasoning: the model must explain its assessment
+    # BEFORE assigning scores, leading to better calibration. DO NOT REORDER.
+    llm_feedback: str
+    skills_match_score: float = Field(..., ge=0, le=1)
+    experience_match_score: float = Field(..., ge=0, le=1)
+    education_match_score: float = Field(..., ge=0, le=1)
+    overall_fit_score: float = Field(..., ge=0, le=1)

src/backend/agents/cv_screening/utils/__init__.py

@@ -0,0 +1,5 @@
+from .read_file import read_file
+
+__all__ = [
+    "read_file",
+]

src/backend/agents/cv_screening/utils/read_file.py

@@ -0,0 +1,7 @@
+from pathlib import Path
+
+def read_file(path: Path) -> str:
+    """Read the contents of a file and return as a string.
+    """
+    with open(path, "r", encoding="utf-8") as f:
+        return f.read()

src/backend/agents/db_executor/__init__.py

@@ -0,0 +1,5 @@
+from .db_executor import db_executor
+
+__all__ = [
+    "db_executor",
+]

src/backend/agents/db_executor/codeact/__init__.py

@@ -0,0 +1,6 @@
+"""
+This agent coding agent based `CodeAct`agent pattern, see:
+- https://arxiv.org/abs/2408.02193
+- https://www.google.com/url?sa=t&source=web&rct=j&opi=89978449&url=https://huggingface.co/collections/DataImaginations/codeact-interaction-framework-for-llm-agents&ved=2ahUKEwjpkvKpwIWRAxWJ1wIHHY3KEzAQFnoECCEQAQ&usg=AOvVaw2IxMEyHwZPI7MfLSlFMyqN
+- https://github.com/langchain-ai/langgraph-codeact
+"""

src/backend/agents/db_executor/codeact/core/codeact.py

@@ -0,0 +1,545 @@
+import re
+import io
+import builtins
+import contextlib
+from collections.abc import Generator
+import inspect
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Optional, Sequence, Type, TypeVar, Union, Literal
+import types
+import json
+
+from langchain.chat_models import init_chat_model
+from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import StructuredTool
+from langchain_core.tools import tool as create_tool
+from langchain_core.messages import AIMessageChunk, AIMessage
+from langgraph.graph import END, START, StateGraph, MessagesState
+from langgraph.types import Command
+from langgraph.checkpoint.memory import MemorySaver
+
+from ..schemas import TokenStream
+from ..schemas.openai_key import OpenAIApiKey
+from ..utils import pretty_print_state
+
+
+
+
+class CodeActState(MessagesState):
+    """State for CodeAct agent."""
+
+    script: Optional[str]
+    """The Python code script to be executed."""
+    context: dict[str, Any]
+    """Dictionary containing the execution context with available tools and variables."""
+
+EvalFunction = Callable[[str, dict[str, Any]], tuple[str, dict[str, Any]]]
+EvalCoroutine = Callable[[str, dict[str, Any]], Awaitable[tuple[str, dict[str, Any]]]]
+
+StateSchema = TypeVar("StateSchema", bound=CodeActState)
+StateSchemaType = Type[StateSchema]
+
+
+import inspect
+from pathlib import Path
+import tiktoken
+from typing import Any, Optional, Union, Sequence
+from langchain_core.tools import StructuredTool
+
+
+class CodeActAgent:
+    def __init__(
+        self,
+        model_name: str,
+        model_provider: str,
+        tools: Optional[Sequence] = None,
+        eval_fn=None,
+        system_prompt: Union[str, Path] = None,
+        bind_tools: bool = False,
+        memory: bool = True,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        - model_name : str
+            The name of the chat model to use (e.g., "gpt-4o").
+        - model_provider : str
+            The model provider (e.g., "openai").
+        - tools : Optional[Sequence], optional
+            A list of tools (functions or StructuredTool) available to the agent.
+        - eval_fn : Optional[EvalFunction or EvalCoroutine], optional
+            The function or coroutine to evaluate generated code. If None, uses default_eval.
+        - system_prompt : Union[str, Path], optional
+            The system prompt as a file path or raw string.
+        - bind_tools : bool, optional
+            Whether to bind tool signatures and docstrings into the system prompt.
+        - memory : bool, optional
+            Whether to enable memory checkpointing.
+        """
+        self.model_name = model_name
+        self.model_provider = model_provider
+        self.tools = tools or []
+        self.eval_fn = eval_fn or self.default_eval
+        self.system_prompt = system_prompt
+        self.bind_tools = bind_tools
+        self.memory = memory
+
+        # Initialize components
+        self.model = init_chat_model(model_name, model_provider=model_provider)
+        self.prompt = self._create_system_prompt()
+        self.agent = self._create_codeact(self.model, self.tools, self.eval_fn)
+
+        checkpointer = MemorySaver() if memory else None
+        self.compiled_agent = self.agent.compile(checkpointer=checkpointer)
+
+
+    def _create_system_prompt(self) -> tuple[str, dict[str, int]]:
+        """Build the final system prompt and compute token counts.
+        """
+        system_text = self._load_prompt(self.system_prompt)
+        if not system_text:
+            raise ValueError("`system_prompt` must be provided as a file path or string.")
+
+        system_text = system_text.strip()
+        
+        # Base version (without tools)
+        prompt_text = system_text
+
+        # If bind_tools enabled, build and append
+        if self.bind_tools:
+            if not self.tools:
+                print("[⚠️] bind_tools=True but no tools provided. Skipping tool injection.")
+            else:
+                tools_text = self._build_tool_context()
+                prompt_text = f"{system_text.strip()}\n\n{tools_text.strip()}"
+
+        # Compute token counts
+        tokens_without_tools = self._count_tokens(system_text)
+        tokens_with_tools = self._count_tokens(prompt_text)
+
+        # Print summary neatly
+        print(
+            f"🧮 System prompt token count:\n"
+            f"       - Without tools: {tokens_without_tools}\n"
+            f"       - With tools:    {tokens_with_tools}"
+        )
+
+        return prompt_text
+
+
+    def _build_tool_context(self) -> str:
+        """Constructs the tool context block with docstrings and signatures.
+        """
+        tool_strings = []
+        for t in self.tools:
+            func = t.func if isinstance(t, StructuredTool) else t
+            sig = inspect.signature(func)
+            doc = (func.__doc__ or "").strip()
+            tool_strings.append(
+                f"def {func.__name__}{sig}:\n    \"\"\"{doc}\"\"\"\n    ..."
+            )
+
+        joined_tools = "\n\n".join(tool_strings)
+        return (
+            "\n\nNote that you have access to the following predefined tools:\n\n"
+            f"{joined_tools}"
+        )
+
+    @staticmethod
+    def _load_prompt(p: Optional[Union[str, Path]]) -> Optional[str]:
+        """Load a prompt from file path or treat as raw string."""
+        if p is None:
+            return None
+
+        # If it's already multiline or contains newlines, it's almost certainly a literal string
+        if isinstance(p, str) and ("\n" in p or len(p) > 200):
+            return p
+
+        # Otherwise, check if it's an actual file path
+        path = Path(p)
+        if path.exists() and path.is_file():
+            return path.read_text(encoding="utf-8")
+
+        # Fallback: just return as string
+        return str(p)
+
+
+    def _count_tokens(self, text: str) -> int:
+        """Count tokens for a given text.
+        """
+        try:
+            enc = tiktoken.encoding_for_model(self.model_name)
+        except Exception:
+            enc = tiktoken.get_encoding("cl100k_base")
+        return len(enc.encode(text))
+
+
+
+    def _extract_and_combine_codeblocks(self, text: str) -> str:
+        """ 
+        Extract and combine code blocks from the model completion.
+        Helper function to execute extracted code in sandbox environment.
+        """
+        pattern = r"(?:^|\n)```(.*?)(?:```(?:\n|$))"   #r"(?:^|\n)```(.*?)(?:```(?:\n|$))"
+        code_blocks = re.findall(pattern, text, re.DOTALL)
+        if not code_blocks:
+            return ""
+        processed = []
+        for block in code_blocks:
+            lines = block.strip().split("\n")
+            if lines and (not lines[0].strip() or " " not in lines[0].strip()):
+                block = "\n".join(lines[1:])
+            processed.append(block)
+        return "\n\n".join(processed)
+
+
+    @staticmethod
+    def default_eval(code: str, _locals: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+        """Evaluate the code in the sandbox.
+        """
+        original_keys = set(_locals.keys())
+        try:
+            with contextlib.redirect_stdout(io.StringIO()) as f:
+                exec(code, builtins.__dict__, _locals)
+            result = f.getvalue() or "<code ran, no output printed to stdout>"
+        except Exception as e:
+            result = f"Error during execution: {repr(e)}"
+        new_keys = set(_locals.keys()) - original_keys
+        new_vars = {key: _locals[key] for key in new_keys}
+        return result, new_vars
+
+    @staticmethod
+    def _filter_serializable(d: dict[str, Any]) -> dict[str, Any]:
+        """Keep only JSON/msgpack-serializable values (basic Python types).
+        """
+        serializable_types = (
+            str, int, float, bool, list, dict, type(None)
+        )
+        return {
+            k: v for k, v in d.items() if isinstance(v, serializable_types)
+        }
+
+
+    def _create_codeact(
+        self,
+        model: BaseChatModel,
+        tools: Sequence[Union[StructuredTool, Callable]],
+        eval_fn: Union[EvalFunction, EvalCoroutine],
+        *,
+        state_schema: StateSchemaType = CodeActState,
+    ) -> StateGraph:
+        """Create a LangGraph state graph for the CodeAct agent.
+        """
+        tools = [
+            t if isinstance(t, StructuredTool) else create_tool(t)
+            for t in tools
+        ]
+        self.tools_context = {tool.name: tool.func for tool in tools}
+
+        def call_model_stream(state: StateSchema):
+            messages = [{"role": "system", "content": self.prompt}] + state["messages"]
+
+            # Accumulate into one combined chunk
+            accumulated: AIMessageChunk | None = None
+
+            # stream partial tokens as AIMessagesChunks wioth .content = "Hel",
+            for delta in self.model.stream(messages):
+                if accumulated is None:
+                    accumulated = delta
+                else:
+                    accumulated = accumulated + delta   # merge chunks
+
+                # yield partial update immediately (for streaming UI)
+                yield Command(update={"messages": [delta], "script": None})
+
+            # after streaming completes
+            if accumulated is None:
+                yield Command(update={"messages": [], "script": None})
+                return  # nothing came back
+
+            # Convert merged chunks into a final message
+            full_text = accumulated.content or ""
+
+            # Check for code blocks
+            code = self._extract_and_combine_codeblocks(full_text)
+
+            if code:
+                # Create a fake tool call entry
+                tool_call_id = "sandbox"
+                fake_tool_call = {
+                    "id": tool_call_id,
+                    "type": "function",
+                    "function": {
+                        "name": "sandbox",
+                        "arguments": code
+                    }
+                }
+                # Patch the assistant message with tool_calls
+                accumulated.additional_kwargs = {"tool_calls": [fake_tool_call]}
+
+                #  Pass both the patched assistant message and code to sandbox
+                yield Command(
+                    goto="sandbox",
+                    update={
+                        "messages": [accumulated],
+                        "script": code
+                    }
+                )
+            else:
+                yield Command(
+                    update={
+                        "messages": [accumulated],
+                        "script": None
+                    }
+                )
+
+
+        if inspect.iscoroutinefunction(eval_fn):
+
+            async def sandbox(state: StateSchema):
+                """Run the code in the sandbox and return a proper OpenAI tool message.
+                """
+                existing_context = state.get("context", {})
+
+                # Combine persistent context with runtime-only tools
+                exec_context = {**existing_context, **self.tools_context}
+
+                # Get tool_call_id for traceability
+                prev_msgs = state.get("messages", [])
+                tool_call_id = "sandbox"
+                for msg in reversed(prev_msgs):
+                    if hasattr(msg, "additional_kwargs") and msg.additional_kwargs.get("tool_calls"):
+                        tool_call_id = msg.additional_kwargs["tool_calls"][0]["id"]
+                        break
+
+                # Execute user code
+                output, new_vars = await eval_fn(state["script"], exec_context)
+
+                # Only persist serializable data
+                serializable_new_vars = self._filter_serializable(new_vars)
+                new_context = {**existing_context, **serializable_new_vars}
+
+                # Format output properly
+                content_str = (
+                    f"Sandbox result of your executed code:\n{json.dumps(output, default=str)}"
+                    if not isinstance(output, str)
+                    else f"Sandbox result of your executed code:\n{output}"
+                )
+
+                # Return OpenAI-compliant tool result
+                return {
+                    "messages": [
+                        {
+                            "role": "tool",
+                            "tool_call_id": tool_call_id,
+                            "name": "sandbox",
+                            "content": content_str
+                        }
+                    ],
+                    "context": new_context,
+                }
+
+
+        else:
+            def sandbox(state: StateSchema):
+                """Run the code in the sandbox and return a proper OpenAI tool message.
+                """
+                existing_context = state.get("context", {})
+
+                # Combine persistent context with runtime-only tools
+                exec_context = {**existing_context, **self.tools_context}
+
+                # Get tool_call_id for traceability
+                prev_msgs = state.get("messages", [])
+                tool_call_id = "sandbox"
+                for msg in reversed(prev_msgs):
+                    if hasattr(msg, "additional_kwargs") and msg.additional_kwargs.get("tool_calls"):
+                        tool_call_id = msg.additional_kwargs["tool_calls"][0]["id"]
+                        break
+
+                # Execute user code
+                output, new_vars = eval_fn(state["script"], exec_context)
+
+                # Only persist serializable data
+                serializable_new_vars = self._filter_serializable(new_vars)
+                new_context = {**existing_context, **serializable_new_vars}
+
+                # Format output properly
+                content_str = (                    # NOTE: before "json.dumps(output)"
+                    f"Sandbox result of your executed code:\n{json.dumps(output, default=str)}"
+                    if not isinstance(output, str)
+                    else f"Sandbox result of your executed code:\n{output}"
+                )
+
+                # Return OpenAI-compliant tool result
+                return {
+                    "messages": [
+                        {
+                            "role": "tool",
+                            "tool_call_id": tool_call_id,
+                            "name": "sandbox",
+                            "content": content_str,
+                            # Keep as string if already string else JSON serialize      
+                        }
+                    ],
+                    "context": new_context,
+                }
+
+        # --- Build the state graph ---
+        agent = StateGraph(state_schema)
+        agent.add_node(call_model_stream, destinations=(END, "sandbox"))
+        agent.add_node(sandbox)
+        agent.add_edge(START, "call_model_stream")
+        agent.add_edge("sandbox", "call_model_stream")
+        return agent
+        
+
+    def stream(
+        self,
+        messages: list[dict],
+        thread_id: int = 1
+    ) -> Generator[
+            TokenStream,
+            None,
+            None
+        ]:
+        """
+        Generator yielding agent outputs during execution.
+
+        Yields
+        ------
+        tuple[str, Any]
+            - "messages": list of chat message objects (e.g. AIMessage)
+            - "values":   dict of current agent state (messages, script, context)
+
+        Example
+        -------
+        messages [AIMessage(content="```python\nresult = 3*7+5\nprint(result)\n```")]
+        values   {"messages": [...], "script": "result = 3*7+5\nprint(result)", "context": {}}
+        messages [AIMessage(content="26")]
+        values   {"messages": [...], "script": None, "context": {"result": 26}}
+        """
+
+        config = {
+            "configurable": {
+                "thread_id": thread_id
+                }
+        }
+        for typ, chunk in self.compiled_agent.stream(
+            {"messages": messages},
+            stream_mode=["values", "messages"],
+            config=config,
+        ):
+            yield TokenStream(type=typ, data=chunk)
+
+    #------- BEFORE DB AGENT EXECUTOR -------#
+    #def generate(
+    #    self,
+    #    messages: list[dict],
+    #    thread_id: int = 1
+    #) -> dict[str, Any]:
+    #    """
+    #    Run the agent to completion and return final state.#
+
+    #    Returns
+    #    -------
+    #    dict
+    #        Final agent state containing messages, script, context.
+    #    """
+    #    config = {
+    #        "configurable": {
+    #            "thread_id": thread_id
+    #            }
+    #    }
+    #    final_state = self.compiled_agent.generate(
+    #        {"messages": messages},
+    #        config=config,
+    #    )
+    #    return final_state
+    #------- BEFORE DB AGENT EXECUTOR -------#
+    def generate(
+        self,
+        messages: list[dict],
+        thread_id: int = 1,
+        context: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """
+        *** Test method for db executor ***
+        """
+        config = {
+            "configurable": {"thread_id": thread_id}
+        }
+        state = {
+            "messages": messages, "context": context or {}
+        }
+        return self.compiled_agent.invoke( #TODO: note changed from generate to invoke, hope it works
+            state, config=config
+        )
+
+
+
+
+if __name__ == "__main__":
+    """
+    Run the CodeActAgent in different modes:
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    - python -m agent.core.codeact --mode chat
+    - python -m agent.core.codeact --mode debug
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    """
+    import argparse
+    import json
+    from rich.console import Console
+
+    # Validate environment (api key) before doing *anything* else
+    OpenAIApiKey.validate_environment()
+
+    # --- Parse args ---
+    parser = argparse.ArgumentParser(description="Run CodeActAgent in different modes")
+    parser.add_argument(
+        "--mode",
+        choices=["chat", "debug"],
+        default="chat",
+        help="Mode: 'chat' for normal conversation, 'debug' to also show state values."
+    )
+    args = parser.parse_args()
+
+    # --- Instantiate agent ---
+    agent = CodeActAgent(
+        model_name="gpt-4o",
+        model_provider="openai",
+        tools=[],
+        eval_fn=CodeActAgent.default_eval,   # built-in evaluator
+        system_prompt="agent/prompts/local_archive/original.txt",
+        bind_tools=False,
+        memory=True
+    )
+    #~~~~~~~~~~~~~~~~~~~~~~~~~~#
+    # --- Conversation loop ---#
+    #~~~~~~~~~~~~~~~~~~~~~~~~~~#
+    # --- Rich console setup ---
+    console = Console(width=100, soft_wrap=False)
+
+    while True:
+        user_query = input("\n😎 USER:\n››› ")
+        if user_query.lower() == "exit":
+            break
+
+        messages = [{"role": "user", "content": user_query}]
+
+        # --- Dynamic assistant header (chat only) ---
+        if args.mode == "chat":
+            console.print("\n🧠 [bold magenta]Assistant[/]:\n››› ", end="")
+
+        # --- Stream agent responses ---
+        for typ, chunk in agent.stream(messages):
+            if args.mode == "chat" and typ == "messages":
+                print(chunk[0].content, end="", flush=True)
+
+            elif args.mode == "debug":
+                if typ == "values":
+                    # Print only the nicely formatted message + optional context
+                    pretty_print_state(chunk, show_context=False)
+
+        print("\n")
+

src/backend/agents/db_executor/codeact/prompts/local_archive/original.txt

@@ -0,0 +1,18 @@
+
+You are a helpful assistant. You are encouraged to generate Python code for calculations.
+
+You will be given a task to perform. You should output either
+- a Python code snippet that provides the solution to the task, or a step towards the solution. Any output you want
+to extract from the code should be printed to the console. Code should be output in a fenced code block.
+- text to be shown directly to the user, if you want to ask for more information or provide the final answer.
+
+In addition to the Python Standard Library, you can use the following functions:
+
+{tools}
+
+Variables defined at the top level of previous code snippets can be referenced in your code.
+
+When you include a code block, put a blank line after the closing triple backticks
+before any further text.
+
+Reminder: use Python code snippets to call tools.

src/backend/agents/db_executor/codeact/prompts/local_archive/test.txt

@@ -0,0 +1,25 @@
+You are a helpful assistant that can solve tasks using Python code and a set of predefined tools.
+
+=== RULES ===
+1. CODE BLOCKS:
+   - Always use triple backticks: ```python ... ```
+   - Never include natural language inside code blocks.
+   - Comments (#) are allowed but should be minimal.
+before any further text.
+
+2. OUTPUT EXPLANATION:
+   - After each code block, provide a brief natural language explanation.
+   - Use code outputs in your response.
+   - Keep explanations separate from code.
+
+Note:
+When you include a code block, put a blank line after the closing triple backticks
+before any further text.
+
+=== VALID EXAMPLE ===
+```python
+# Calculate the product
+result = multiply(15, 23)
+print(result)
+```
+The calculation shows that 15 multiplied by 23 equals 345.

src/backend/agents/db_executor/codeact/prompts/prompt_layer.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+PromptLayer Integration for Prompt Management
+==============================================
+
+This module provides a centralized way to manage prompts using PromptLayer platform.
+Allows for versioned, labeled prompts that can be easily updated without code changes.
+"""
+
+import promptlayer
+from promptlayer import PromptLayer
+from dotenv import load_dotenv
+import os
+from typing import Dict, Any, Optional
+from functools import lru_cache
+
+load_dotenv()
+
+
+class PromptManager:
+    """
+    Centralized prompt management using PromptLayer platform.
+    link:
+        - https://www.promptlayer.com
+
+    Features:
+    - Version control for prompts
+    - Environment-based prompt labels (dev, staging, production)
+    - Caching for performance
+    - Fallback to local files if PromptLayer unavailable
+    """
+
+    def __init__(self, api_key: Optional[str] = None, environment: str = "production"):
+        """
+        Initialize PromptManager.
+
+        Args:
+            api_key: PromptLayer API key (defaults to PROMPTLAYER_API_KEY env var)
+            environment: Environment label for prompts (dev, staging, production)
+        """
+        self.api_key = api_key or os.getenv("PROMPTLAYER_API_KEY")
+        self.environment = environment
+        self.client = None
+
+        # Initialize client if API key is available
+        if self.api_key:
+            try:
+                self.client = PromptLayer(api_key=self.api_key)
+                print(f"✅ PromptLayer connected (environment: {environment})")
+
+            except Exception as e:
+                print(f"⚠️  PromptLayer connection failed: {e}")
+                self.client = None
+        else:
+            print("⚠️ No PROMPTLAYER_API_KEY found, using local fallback")
+
+    @lru_cache(maxsize=128)
+    def get_prompt(
+        self,
+        template_name: str,
+        version: Optional[int] = None,
+        label: Optional[str] = None,
+        fallback_path: Optional[str] = None
+    ) -> str:
+        """
+        Get a prompt from PromptLayer with fallback to local file.
+
+        Args:
+            template_name: Name of the prompt template
+            version: Specific version number (defaults to latest)
+            label: Environment label (defaults to instance environment)
+            fallback_path: Local file path if PromptLayer unavailable
+
+        Returns:
+            Prompt content as string
+
+        Raises:
+            ValueError: If prompt cannot be found and no fallback provided
+        """
+        # Use provided label or instance default
+        label = label or self.environment
+
+        # Try PromptLayer first
+        if self.client:
+            try:
+                template_config = {
+                    "label": label
+                }
+                if version:
+                    template_config["version"] = version
+
+                prompttemplate = self.client.templates.get(
+                    template_name,
+                    template_config
+                )
+                # Extract prompt content from response
+                prompt_content = prompttemplate["llm_kwargs"]["messages"][0]["content"]
+                print(f"📋 Loaded prompt '{template_name}' from PromptLayer (v{prompttemplate.get('version', 'latest')}, {label})")
+                return prompt_content
+
+            except Exception as e:
+                print(f"⚠️ PromptLayer failed: {e}, trying fallback...")
+                # Fall through to fallback instead of raising
+
+        # Fallback to local file
+        if fallback_path:
+            try:
+                with open(fallback_path, 'r') as f:
+                    content = f.read()
+                print(f"📂 Loaded prompt '{template_name}' from local file: {fallback_path}")
+                return content
+            except Exception as e:
+                raise ValueError(
+                    f"❌ Failed to load fallback file '{fallback_path}': {e}"
+                )
+
+        # Only raise if both PromptLayer AND fallback fail
+        raise ValueError(
+            f"Could not load prompt '{template_name}' from any source"
+        )
+
+
+    def list_available_prompts(self) -> Dict[str, Any]:
+        """
+        List all available prompts from PromptLayer.
+
+        Returns:
+            Dictionary of available prompts with metadata
+        """
+        if not self.client:
+            return {"error": "PromptLayer client not available"}
+
+        try:
+            # This would depend on PromptLayer's API for listing templates
+            # Placeholder implementation
+            return {
+                "message": "PromptLayer template listing not implemented in this version",
+                "available_methods": [
+                    "get_judge_prompt(simple=True/False)",
+                    "get_agent_prompt(version=int)",
+                    "get_prompt(template_name, version, label, fallback_path)"
+                ]
+            }
+        except Exception as e:
+            return {"error": f"Failed to list prompts: {e}"}
+
+    def clear_cache(self):
+        """Clear the prompt cache."""
+        self.get_prompt.cache_clear()
+        print("🗑️  Prompt cache cleared")
+
+    def set_environment(self, environment: str):
+        """
+        Change the environment label for subsequent prompt requests.
+
+        Args:
+            environment: New environment (dev, staging, production)
+        """
+        self.environment = environment
+        self.clear_cache()  # Clear cache since environment changed
+        print(f"🔄 Environment changed to: {environment}")
+

src/backend/agents/db_executor/codeact/schemas/__init__.py

@@ -0,0 +1,10 @@
+"""Init file for pydantic schemas.
+"""
+
+from .openai_key import OpenAIApiKey
+from .stream import TokenStream
+
+__all__ = [
+    "OpenAIApiKey",
+    "TokenStream",
+]

src/backend/agents/db_executor/codeact/schemas/openai_key.py

@@ -0,0 +1,56 @@
+import os
+from pydantic import Field, ConfigDict, field_validator
+from pydantic_settings import BaseSettings
+from pathlib import Path
+from dotenv import load_dotenv
+from pydantic import ValidationError
+import sys
+
+# Load environment variables
+load_dotenv()
+
+
+class OpenAIApiKey(BaseSettings):
+    """Schema for validating and loading the OpenAI API key configuration.
+    """
+    model_config = ConfigDict(
+        title="OpenAI API Key Schema",
+        description="Validates and loads the OpenAI API key from environment variables.",
+    )
+    api_key: str = Field(
+        ...,                         # >>> required field
+        title="OpenAI API Key",
+        description="API key for OpenAI authentication.",
+        examples=["sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
+        alias="OPENAI_API_KEY",
+    )
+
+    @field_validator("api_key")
+    @classmethod
+    def validate_openai_api_key(cls, v: str) -> str:
+        """Validate that the API key is present and has the correct format.
+        """
+        if not v:
+            raise ValueError(
+                "💥 Missing `OPENAI_API_KEY` environment variable."
+            )
+        if not v.startswith("sk-"):
+            raise ValueError(
+                "💥 Invalid `OPENAI_API_KEY` — must start with 'sk-'."
+            )
+        return v
+    
+    @classmethod
+    def validate_environment(cls) -> "OpenAIApiKey":
+        """
+        Load .env from the root directory 
+        and validate that the API key is present and valid.
+        """
+        try:
+            # Pydantic auto-loads .env and validates
+            config = cls()                                
+            os.environ["OPENAI_API_KEY"] = config.api_key # Set for runtime access
+            return config 
+        except ValidationError as e:
+            print(f"💥 OpenAI API key misconfiguration:\n{e}")
+            sys.exit(1)

src/backend/agents/db_executor/codeact/schemas/stream.py

@@ -0,0 +1,8 @@
+from typing import NamedTuple, Literal, Union, Any
+from langchain_core.messages import AIMessage
+
+class TokenStream(NamedTuple):
+    """Represents a single streamed update emitted by the agent.
+    """
+    type: Literal["messages", "values"]
+    data: Union[list[AIMessage], dict[str, Any]]

src/backend/agents/db_executor/codeact/states/state.py

@@ -0,0 +1,10 @@
+from langgraph.graph import END, START, MessagesState
+from typing import Optional, Any
+
+class CodeActState(MessagesState):
+    """State for CodeAct agent."""
+
+    script: Optional[str]
+    """The Python code script to be executed."""
+    context: dict[str, Any]
+    """Dictionary containing the execution context with available tools and variables."""

src/backend/agents/db_executor/codeact/tools/tools.py

@@ -0,0 +1,53 @@
+import inspect
+from langchain_core.tools import StructuredTool
+from typing import Optional
+from pathlib import Path
+
+# Example tools
+def add(a: float, b: float) -> float:
+    """Add two numbers together."""
+    return a + b
+
+def multiply(a: float, b: float) -> float:
+    """Multiply two numbers together."""
+    return a * b
+
+def divide(a: float, b: float) -> float:
+    """Divide two numbers."""
+    return a / b
+
+def subtract(a: float, b: float) -> float:
+    """Subtract two numbers."""
+    return a - b
+
+# Prompt creation
+def create_default_prompt(
+    tools: list,
+    system_prompt: Optional[str] = None,
+    base_prompt: str = "original.txt",
+) -> str:
+    template_path = Path(__file__).parent.parent / "prompts" / base_prompt
+    template = template_path.read_text()
+
+    tool_strings = []
+    for t in tools:
+        func = t.func if isinstance(t, StructuredTool) else t
+        sig = inspect.signature(func)
+        doc = (func.__doc__ or "").strip()
+        tool_strings.append(
+            f"def {func.__name__}{sig}:\n    \"\"\"{doc}\"\"\"\n    ..."
+        )
+    tools_str = "\n\n".join(tool_strings)
+
+    prompt = template.replace("{tools}", tools_str)
+
+    if system_prompt:
+        prompt = f"{system_prompt}\n\n{prompt}"
+
+    return prompt
+
+
+
+if __name__ == "__main__":
+    tools = [multiply, divide, subtract]
+    print(create_default_prompt(tools, system_prompt="You are a coding agent."))

src/backend/agents/db_executor/codeact/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility functions for the agent."""
+
+from .pretty_state import pretty_print_state
+
+__all__ = ["pretty_print_state"]

src/backend/agents/db_executor/codeact/utils/pretty_state.py

@@ -0,0 +1,73 @@
+import json
+from rich.console import Console
+from rich.syntax import Syntax
+from rich.panel import Panel
+from langchain_core.messages import HumanMessage, AIMessage, ToolMessage
+
+console = Console(width=100, soft_wrap=False)
+
+_last_context_snapshot = None  # used to suppress repeated context
+_last_message_ids = set()  # track printed messages
+
+
+
+def serialize_message(msg) -> dict:
+    """Convert LangChain message objects into serializable dicts."""
+    if hasattr(msg, "dict"):
+        return msg.dict()
+    elif hasattr(msg, "__dict__"):
+        return {k: serialize_message(v) for k, v in msg.__dict__.items()}
+    elif isinstance(msg, list):
+        return [serialize_message(v) for v in msg]
+    elif isinstance(msg, dict):
+        return {k: serialize_message(v) for k, v in msg.items()}
+    else:
+        return msg
+
+
+def pretty_print_state(state: dict, show_context: bool = True) -> None:
+    """
+    Pretty-print the agent's state in a clean, color-coded way.
+
+    Parameters
+    ----------
+    state : dict
+        The LangGraph agent state chunk (from the stream).
+    show_context : bool, optional
+        Whether to display the context (default True).
+        If True, only shows context when it has changed since last call.
+    """
+    global _last_context_snapshot
+
+    # --- Display message chunks ---
+    for msg in state.get("messages", []):
+
+        msg_id = getattr(msg, "id", id(msg))
+        if msg_id in _last_message_ids:
+            continue  # skip duplicates
+        _last_message_ids.add(msg_id)
+
+        msg_dict = serialize_message(msg)
+        msg_json = json.dumps(msg_dict, indent=2)
+
+        if isinstance(msg, HumanMessage):
+            color, title = "cyan", "🧑 HumanMessage"
+        elif isinstance(msg, ToolMessage):
+            color, title = "yellow", f"🧰 ToolMessage ({msg_dict.get('name','?')})"
+        elif isinstance(msg, AIMessage):
+            color, title = "magenta", "🤖 AIMessage"
+        else:
+            color, title = "white", "Other"
+
+        syntax = Syntax(msg_json, "json", theme="monokai", line_numbers=False)
+        console.print(Panel(syntax, title=title, border_style=color))
+
+    # --- Optional context view ---
+    #if show_context:
+    #    context = state.get("context", {})
+    #    if context and context != _last_context_snapshot:
+    #        _last_context_snapshot = context.copy()  # cache for next comparison
+
+    #        context_json = json.dumps(context, indent=2, default=str)
+    #        syntax = Syntax(context_json, "json", theme="monokai", line_numbers=False)
+     #       console.print(Panel(syntax, title="🧠 Context (updated)", border_style="green"))

src/backend/agents/db_executor/db_executor.py

@@ -0,0 +1,99 @@
+from .codeact.core.codeact import CodeActAgent
+from src.backend.database.candidates.client import SessionLocal
+from src.backend.database.candidates.models import (
+    Candidate,
+    CVScreeningResult,
+    VoiceScreeningResult,
+    InterviewScheduling,
+    FinalDecision,
+)
+from src.backend.state.candidate import CandidateStatus, InterviewStatus, DecisionStatus
+from langchain_core.tools import tool
+from typing import Dict, Any
+from src.backend.database.candidates import evaluate_cv_screening_decision
+from src.backend.prompts import get_prompt
+
+
+SYSTEM_PROMPT = get_prompt(
+    template_name="DB_Executor",
+    local_prompt_path="db_executor/v2.txt",
+)
+
+
+@tool
+def db_executor(query: str) -> str:
+    """
+    Consumes a natural-language query as input which is being translated into 
+    SQLAlchemy ORM code by the coding agent. Finally, the code is executed against 
+    the database and the result is returned.
+
+    Args:
+        query (str): Natural-language database query.
+    Returns:
+        str: The natural language summary of the result or error.
+    """
+    # 1. Initialize DB session and ORM context
+    session = SessionLocal()
+    context = {
+        "session": session,
+        "Candidate": Candidate,
+        "CVScreeningResult": CVScreeningResult,
+        "VoiceScreeningResult": VoiceScreeningResult,
+        "InterviewScheduling": InterviewScheduling,
+        "FinalDecision": FinalDecision,
+        "CandidateStatus": CandidateStatus,
+        "InterviewStatus": InterviewStatus,
+        "DecisionStatus": DecisionStatus,
+    }
+
+    try:
+        # 2. Initialize CodeAct agent with system prompt
+        agent = CodeActAgent(
+            model_name="gpt-4o",
+            model_provider="openai",
+            tools=[evaluate_cv_screening_decision],  # Passed as a tool
+            eval_fn=CodeActAgent.default_eval,
+            system_prompt=SYSTEM_PROMPT,
+            bind_tools=True, # Enable tool binding so agent sees signature
+            memory=False,   # optional — can enable if you want persistent thread context
+        )
+
+        # 3. Run natural-language query
+        messages = [{"role": "user", "content": query}]
+        final_state = agent.generate(messages, context=context)
+
+        # 4. Extract model output
+        # Return the final natural language response from the assistant
+        output_msg = final_state["messages"][-1].content if final_state.get("messages") else ""
+        
+        return output_msg
+
+    except Exception as e:
+        import traceback
+        error_trace = traceback.format_exc()
+        print(f"\n❌ Error in db_executor: {e}\n{error_trace}")
+        
+        # Return a clear text error message
+        return f"The DB Executor encountered an internal error: {str(e)}"
+
+    finally:
+        session.close()
+
+
+
+if __name__ == "__main__":
+    from rich.console import Console
+    from rich.panel import Panel
+
+    console = Console()
+    query = "Fetch all candidates and their status."
+    
+    console.rule("[bold magenta]DB Executor Test Run[/bold magenta]")
+    console.print(f"[cyan]Query:[/] {query}\n")
+
+    result = db_executor(query)
+
+    # 🧠 Show model result nicely
+    console.print(Panel.fit(result, title="🧠 Model Output", border_style="blue"))
+
+    console.rule("[bold green]End of Execution[/bold green]")

src/backend/agents/db_executor/info.md

@@ -0,0 +1,22 @@
+This agent coding agent based `CodeAct`agent pattern, see:
+https://github.com/langchain-ai/langgraph-codeact
+
+
+Test as follows:
+
+>>> cd /Users/sebastianwefers/Desktop/projects/recruitment-agent
+
+>>> docker compose -f docker/docker-compose.yml up --build candidates_db_init
+
+
+# Make sure your OpenAI key is available to the process
+>>> export OPENAI_API_KEY=sk-...   # or however you normally set it
+
+# Override host so the Python code connects to localhost, not 'db' and run "db_executor"
+>>> POSTGRES_HOST=localhost POSTGRES_PORT=5433 python -m src.agents.db_executor.db_executor
+
+
+# DEBUG attempt
+------------------------------------------------------------------------------------
+- works:
+POSTGRES_HOST=localhost POSTGRES_PORT=5433 python src/agents/db_executor/debug_db_connection.py

src/backend/agents/example/info.md

@@ -0,0 +1,66 @@
+### How to Run the LangGraph Reasoning Monitoring Demo Agent
+
+1. Make sure to have the follwijg installed
+```bash
+pip install -r requriements/dev.txt
+```
+
+2. Set TAVILY_API_KEY:
+- link: https://www.tavily.com
+
+3. Run the following from repo root:
+```bash
+export PYTHONPATH=./src
+langgraph dev
+```
+This loads the root-level `langgraph.json` and makes all agents available in LangGraph Studio.
+
+4 Open the Studio UI
+After the server starts, open:
+```bash
+https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
+```
+**NOTE:** Open it in anything, but safari!
+
+Select the agent named react_agent (or whichever your config specifies).
+
+---
+
+### Demo Prompt to Use
+Paste the following into the Studio console:
+```txt
+First search for the current temperature in Fahrenheit in Cape Town, South Africa.
+Then convert that temperature to Celsius using the conversion tool.
+```
+
+***This triggers:***
+1. A Tavily search for the current Fahrenheit temperature
+2. A tool call to convert Fahrenheit → Celsius
+3. Full ReAct reasoning + tool trace in the UI
+
+---
+
+### ⚙️ Multiple Agents in langgraph.json
+You can expose multiple agents to LangGraph Studio by listing them under the graphs section of your root `langgraph.json`.
+
+Example:
+```json
+{
+  "dependencies": ["src"],
+  "graphs": {
+    "react_agent": "agents.example.react_agent:agent",
+    "cv_screener": "agents.cv_screening.screener:agent",
+    "supervisor": "agents.supervisor.supervisor:agent"
+  }
+}
+```
+Each entry maps:
+```bash
+"graph_name": "module.path:object_name"
+```
+
+Where:
+- `graph_name` → appears in LangGraph Studio
+- `module.path` → Python import path under `src/`
+- `object_name` → the variable that contains the graph/agent
+This allows one project to host many agents simultaneously (e.g., supervisor, tools agent, CV-screening agent, etc.).

src/backend/agents/example/react_agent.py

@@ -0,0 +1,59 @@
+"""
+Simple React Agent implementation with monitoring capabilities.
+
+- React agent:
+    - https://docs.langchain.com/oss/python/langchain/agents
+
+
+install:
+    - langgraph-cli
+
+Run as follows:
+>>> cd src/agents/example/
+>>> langgraph dev
+
+"""
+from langchain.agents import create_agent
+from langchain_tavily import TavilySearch
+from langchain_core.tools import tool
+from dotenv import load_dotenv
+ 
+ 
+
+load_dotenv()
+
+
+
+# --- Tools ---
+@tool
+def convert_fahrenheit_celsius(fahrenheit: float) -> float:
+    """
+    Convert fahrenheit to celsius.
+    Args:
+        fahrenheit (float): Temperature in fahrenheit.
+    Returns:
+        float: Temperature in celsius.
+    """
+    return (fahrenheit - 32) * 5.0/9.0
+    
+
+
+web_search = TavilySearch(
+    max_results = 5,
+    topic = "general",
+    # include_answer = False,
+    # include_raw_content = False,
+    # ...
+)
+
+
+tools = [
+    web_search,
+    convert_fahrenheit_celsius
+]
+
+
+agent = create_agent(
+    "gpt-5",
+    tools=tools
+)

src/backend/agents/gcalendar/__init__.py

@@ -0,0 +1,2 @@
+from .gcalendar_agent import gcalendar_agent
+

src/backend/agents/gcalendar/gcalendar_agent.py

@@ -0,0 +1,94 @@
+import asyncio
+import sys
+from langchain_core.tools import tool
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain.agents import create_agent
+from langchain_openai import ChatOpenAI
+from src.mcp_servers.examples.gcalendar.settings import GoogleCalendarSettings
+from src.backend.prompts import get_prompt
+
+
+SYSTEM_PROMPT = get_prompt(
+    template_name="GCalendar",
+    latest_version=True     
+)
+
+@tool
+def gcalendar_agent(query: str) -> str:
+    """
+    A tool that acts as a Google Calendar agent.
+    It can list, create, and analyze calendar events using the Google Calendar MCP server.
+    
+    Args:
+        query (str): The natural language request for the calendar (e.g., "Schedule a meeting with X on Friday at 3pm").
+        
+    Returns:
+        str: The natural language response from the agent confirming the action or providing the requested information.
+
+    Example output:
+        "I have successfully scheduled the meeting with X for Friday at 3pm. The event ID is 1234567890."
+    """
+    try:
+        import asyncio
+        async def _run_async():
+            # Load settings
+            settings = GoogleCalendarSettings()
+            CALENDAR_MCP_DIR = settings.calendar_mcp_dir
+            CREDS = settings.creds
+            TOKEN = settings.token
+
+            # Initialize model
+            model = ChatOpenAI(model="gpt-4o", temperature=0)
+
+            # Connect to MCP server
+            # Note: This spawns a new process for each call. 
+            # In a production environment, you might want to manage a persistent connection.
+            client = MultiServerMCPClient({
+                "calendar": {
+                    "command": sys.executable,
+                    "args": [
+                        f"{CALENDAR_MCP_DIR}/run_server.py",
+                        "--creds-file-path", str(CREDS),
+                        "--token-path", str(TOKEN),
+                    ],
+                    "transport": "stdio",
+                }
+            })
+
+            # Fetch tools
+            try:
+                tools = await client.get_tools()
+            except Exception as e:
+                return f"❌ Failed to connect to Calendar MCP server: {str(e)}"
+
+            if not tools:
+                return "❌ No tools available from Calendar MCP server."
+
+            # Create agent
+            agent = create_agent(model, tools)
+
+            # Run agent
+            # We wrap the user query in a system/user message structure
+            result = await agent.ainvoke({
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": SYSTEM_PROMPT,
+                    },
+                    {
+                        "role": "user",
+                        "content": query,
+                    },
+                ]
+            })
+
+            # Extract result
+            output = result["messages"][-1].content
+            return output
+
+        return asyncio.run(_run_async())
+
+    except Exception as e:
+        import traceback
+        return f"❌ Error in gcalendar_agent: {str(e)}\n{traceback.format_exc()}"
+

src/backend/agents/gmail/__init__.py

@@ -0,0 +1,2 @@
+from .gmail_agent import gmail_agent
+