sync from testing

.github/workflows/deploy-testing.yml

@@ -53,7 +53,36 @@
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
+  build-agent:
+    name: Build & Push Agent Service
+    runs-on: ubuntu-latest
+    needs: [generate-tag]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to DigitalOcean Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ secrets.DO_REGISTRY_TOKEN }}
+          password: ${{ secrets.DO_REGISTRY_TOKEN }}
+
+      - name: Build and Push Agent Service
+        uses: docker/build-push-action@v5
+        with:
+          context: ./echo/agent
+          file: ./echo/agent/Dockerfile
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/dbr-echo-agent:${{ needs.generate-tag.outputs.image-tag }}
+            ${{ env.REGISTRY }}/dbr-echo-agent:testing
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
   build-directus:
     name: Build & Push Directus
     runs-on: ubuntu-latest
     needs: [generate-tag]
@@ -217,7 +246,7 @@
   update-gitops:
     name: Update GitOps Repo
     runs-on: ubuntu-latest
-    needs: [generate-tag, build-api, build-directus]
+    needs: [generate-tag, build-api, build-agent, build-directus]
     steps:
       - name: Checkout GitOps repo
         uses: actions/checkout@v4

.gitignore

@@ -10,6 +10,16 @@ echo/server/dembrane/audio_lightrag/data/progress_tracker.csv
 echo/server/test.py
 echo/server/wandb*
 
+# Python virtual environments
+.venv/
+.venv-*/
+**/venv/
+**/.venv/
+**/.venv-*/
+
+# Local documentation (not committed)
+CLAUDE.md
+IMPLEMENTATION_PLANS/
 
 *.env
 notes_*.md

contributors.yml

@@ -5,3 +5,5 @@
 - RubenNair
 - vanpauli
 - MsVivienne
+- dtrn2048
+- Charugundlavipul

echo/.devcontainer/docker-compose.yml

@@ -80,6 +80,21 @@ services:
       - postgres
       - redis
 
+  agent:
+    build:
+      context: ../agent
+      dockerfile: Dockerfile
+    ports:
+      - 8001:8001
+    environment:
+      - GEMINI_API_KEY=${GEMINI_API_KEY:-}
+      - ECHO_API_URL=http://devcontainer:8000/api
+      - AGENT_CORS_ORIGINS=http://localhost:5173,http://localhost:5174
+    networks:
+      - dembrane-network
+    depends_on:
+      - devcontainer
+
   devcontainer:
     build:
       context: ../server
@@ -123,4 +138,4 @@ services:
 
 networks:
   dembrane-network:
-    driver: bridge
+    driver: bridge

echo/.gitignore

@@ -14,6 +14,7 @@ directus/.env
 *.sql
 node_modules
 .next
+cypress/test-suites/.cypress-cache/
 
 celerybeat-schedule.db
 
@@ -28,3 +29,5 @@ __queuestorage__echo/server/dembrane/workspace_script.py
 
 tools/translator
 echo-gitops/
+
+cypress/reports/

echo/AGENTS.md

@@ -110,8 +110,43 @@ Convention: Use `ENABLE_*` naming pattern for feature flags.
 # Frontend
 cd frontend && pnpm i && pnpm dev
 
-# Backend
-cd server && uv sync && uv run uvicorn dembrane.main:app --reload
+# Backend API
+cd server && uv sync && uv run uvicorn dembrane.main:app --port 8000 --reload --loop asyncio
+
+# Agent service (required for agentic chat)
+cd ../agent && uv sync && uv run uvicorn main:app --host 0.0.0.0 --port 8001 --reload
+```
+
+For full background processing (transcription/audio and non-agentic jobs), also run:
+
+```bash
+cd server
+uv run dramatiq-gevent --watch ./dembrane --queues network --processes 2 --threads 1 dembrane.tasks
+uv run dramatiq --watch ./dembrane --queues cpu --processes 1 --threads 1 dembrane.tasks
+```
+
+Agentic chat execution is stream-first through `POST /api/agentic/runs/{run_id}/stream` and no longer enqueues an agentic Dramatiq actor.
+
+### Future Agent Tool Development
+
+- Add tool definitions in `agent/agent.py` (`@tool` functions in `create_agent_graph`).
+- Add shared API client calls for tools in `agent/echo_client.py`.
+- If a tool needs new data, expose it via `server/dembrane/api/agentic.py` and/or `server/dembrane/service/`.
+- Add tests in `agent/tests/test_agent_tools.py` and `server/tests/test_agentic_api.py`.
+
+### Inspect Local Agentic Conversations
+
+Use the local script from repo root:
+
+```bash
+bash echo/server/scripts/agentic/latest_runs.sh --chat-id <chat_uuid> --limit 3 --events 80
+```
+
+Common variants:
+
+```bash
+bash echo/server/scripts/agentic/latest_runs.sh --run-id <run_uuid> --events 120
+bash echo/server/scripts/agentic/latest_runs.sh --chat-id <chat_uuid> --limit 1 --events 200 --json
 ```
 
 ## Important Files

echo/agent/.env.sample

@@ -0,0 +1,5 @@
+GEMINI_API_KEY=
+ECHO_API_URL=http://host.docker.internal:8000/api
+LLM_MODEL=gemini-3-pro-preview
+AGENT_GRAPH_RECURSION_LIMIT=80
+AGENT_CORS_ORIGINS=http://localhost:5173,http://localhost:5174

echo/agent/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/

echo/agent/Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+COPY pyproject.toml ./
+RUN uv sync --frozen || uv sync
+
+COPY . .
+
+EXPOSE 8001
+
+CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8001"]

echo/agent/README.md

@@ -0,0 +1,37 @@
+# Echo Agent Service
+
+Isolated CopilotKit/LangGraph runtime for Agentic Chat.
+
+## Why This Service Exists
+
+- Keeps agent execution out of the frontend runtime.
+- Avoids dependency conflicts with `echo/server`.
+- Supports long-running execution and backend-owned run lifecycle.
+
+## Local Run
+
+```bash
+cd echo/agent
+cp .env.sample .env
+# set GEMINI_API_KEY in .env
+uv sync
+uv run uvicorn main:app --host 0.0.0.0 --port 8001 --reload
+```
+
+## Docker Run
+
+```bash
+cd echo/agent
+docker build -t echo-agent:local .
+docker run --rm -p 8001:8001 --env-file .env echo-agent:local
+```
+
+## Endpoints
+
+- `GET /health`
+- `POST /copilotkit/{project_id}`
+
+## Notes
+
+- This service is intentionally scoped to one purpose: agentic chat execution.
+- Auth, persistence, and notifications should be owned by `echo/server` gateway routes.