Production deployment with AMD priority and stability fixes

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.gemini
+.vercel
+
+backend/.env
+backend/venv
+backend/__pycache__
+backend/**/__pycache__
+backend/**/*.pyc
+
+frontend/.env
+frontend/node_modules
+frontend/dist
+
+*.log

.gemini/antigravity/brain/8453b74f-68a6-47ae-887d-1123cb011afb/scratch/verify_supabase.py

@@ -0,0 +1,10 @@
+import sys
+import os
+sys.path.append(os.path.join(os.getcwd(), 'backend'))
+
+try:
+    from backend.services.supabase_service import supabase
+    res = supabase.table("agents").select("count").execute()
+    print(f"Connection successful! Agents count: {res.data}")
+except Exception as e:
+    print(f"Error connecting to Supabase: {e}")

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,13 @@
+backend/.env
+/backend/venv
+/backend/__pycache__
+frontend/.env
+node_modules/
+dist/
+__pycache__/
+*.pyc
+
+.vercel
+frontend/ios
+frontend/android
+.DS_Store

Dockerfile

@@ -0,0 +1,40 @@
+FROM node:22-slim AS frontend-build
+
+WORKDIR /app/frontend
+
+COPY frontend/package*.json ./
+RUN npm ci
+
+COPY frontend ./
+
+ARG VITE_API_URL=""
+ARG VITE_SUPABASE_URL=""
+ARG VITE_SUPABASE_ANON_KEY=""
+ARG VITE_SENTRY_DSN=""
+
+ENV VITE_API_URL=$VITE_API_URL
+ENV VITE_SUPABASE_URL=$VITE_SUPABASE_URL
+ENV VITE_SUPABASE_ANON_KEY=$VITE_SUPABASE_ANON_KEY
+ENV VITE_SENTRY_DSN=$VITE_SENTRY_DSN
+
+RUN npm run build
+
+FROM python:3.11-slim
+
+ENV PORT=7860
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY VERSION VERSION
+COPY backend/requirements.txt backend/requirements.txt
+RUN pip install --no-cache-dir -r backend/requirements.txt
+
+COPY backend backend
+COPY --from=frontend-build /app/frontend/dist frontend/dist
+
+WORKDIR /app/backend
+
+EXPOSE 7860
+
+CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT:-7860}"]

README.md

@@ -0,0 +1,199 @@
+---
+title: Aubm
+sdk: docker
+app_port: 7860
+license: mit
+short_description: Automated Business Machines
+---
+
+# Aubm
+
+Enterprise-grade AI agent orchestration and collaboration platform.
+
+Aubm turns complex goals into supervised multi-agent workflows: projects, context, agents, tasks, dependencies, human approvals, reports, and operational monitoring in one workspace.
+
+## Key Features
+
+- Multi-provider LLM support through backend provider adapters.
+- Project wizard for Guided and Expert creation flows.
+- Agent marketplace for deploying reusable specialist agents.
+- Task orchestration with priorities, dependencies, retries, and human approval.
+- Multi-agent debate for cross-reviewing task outputs.
+- Final reports: full report, short brief, pessimistic analysis, and PDF export.
+- Project roadmap view inferred from task status, priority, and dependencies.
+- Completed project locking: completed projects become read-only in the UI and backend mutation endpoints.
+- Monitoring dashboard with backend health and Supabase fallback metrics.
+- Voice control and spatial task visualization for expert workflows.
+- Sentry-compatible error tracking hooks for backend and frontend.
+
+See [ROADMAP.md](./ROADMAP.md) for the current implementation status. The roadmap is intentionally conservative and separates completed, partial, in-progress, and next work.
+
+## Tech Stack
+
+- Frontend: React + Vite + TypeScript + vanilla CSS.
+- Backend: FastAPI on Python 3.10+.
+- Database/Auth: Supabase Postgres + Supabase Auth.
+- Deployment: Docker, Hugging Face Spaces, and Vercel configuration.
+
+## Project Structure
+
+```text
+aubm/
+  backend/            FastAPI app, agents, routers, services, worker
+  database/           Supabase schema and migrations
+  docs/               Operating guide, audit notes, task plan, sales one-pager
+  frontend/           React/Vite app
+  ROADMAP.md          Current product roadmap and status
+  SPEC.md             Technical specification
+```
+
+## Database Setup
+
+For a fresh Supabase project, apply:
+
+```text
+database/schema.sql
+database/seed.sql
+database/phase3_updates.sql
+database/marketplace.sql
+database/enterprise_security.sql
+database/add_team_permissions.sql
+database/agent_ownership.sql
+database/task_owner_policies.sql
+database/default_agents.sql
+```
+
+For existing projects, also apply any migration that matches your current error or missing capability:
+
+```text
+database/add_task_run_duration.sql
+database/add_task_queued_status.sql
+database/add_task_queue_leasing.sql
+database/add_task_queue_retry_backoff.sql
+database/add_worker_heartbeats.sql
+database/add_audit_mutation_triggers.sql
+database/add_task_claims.sql
+database/add_profile_manager_role.sql
+database/fix_profiles_rls_final.sql
+database/fix_profiles_recursion.sql
+database/add_team_permissions.sql
+```
+
+After schema changes, reload PostgREST when the migration includes:
+
+```sql
+NOTIFY pgrst, 'reload schema';
+```
+
+## Backend Setup
+
+```powershell
+cd backend
+python -m venv venv
+.\venv\Scripts\activate
+pip install -r requirements.txt
+uvicorn main:app --reload --port 8000
+```
+
+Create `backend/.env`:
+
+```env
+SUPABASE_URL=your_project_url
+SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
+OPENAI_API_KEY=optional_key
+GROQ_API_KEY=optional_key
+GEMINI_API_KEY=optional_key
+AMD_API_KEY=optional_key
+TAVILY_API_KEY=optional_key
+SENTRY_DSN=optional_dsn
+```
+
+## Frontend Setup
+
+```powershell
+cd frontend
+npm install
+npm run dev
+```
+
+Create `frontend/.env`:
+
+```env
+VITE_API_URL=http://127.0.0.1:8000
+VITE_SUPABASE_URL=your_project_url
+VITE_SUPABASE_ANON_KEY=your_anon_key
+VITE_SENTRY_DSN=optional_dsn
+```
+
+Validation:
+
+```powershell
+cd frontend
+npm run lint
+npm run build
+```
+
+## Worker
+
+A lightweight worker scaffold exists:
+
+```powershell
+cd backend
+python worker.py
+```
+
+The worker uses `tasks.status = 'queued'` and atomically claims jobs with `claim_next_queued_task`. Existing databases must apply:
+
+```text
+database/add_task_queued_status.sql
+database/add_task_queue_leasing.sql
+database/add_task_queue_retry_backoff.sql
+database/add_worker_heartbeats.sql
+database/add_audit_mutation_triggers.sql
+```
+
+Worker retry behavior can be tuned with:
+
+```env
+AUBM_WORKER_MAX_ATTEMPTS=3
+AUBM_WORKER_RETRY_DELAY_SECONDS=30
+```
+
+To route task/project execution through the worker, set:
+
+```env
+TASK_EXECUTION_MODE=queue
+```
+
+With `TASK_QUEUE_EMBEDDED_WORKER=true` (the default), the FastAPI process starts an embedded worker when queue mode is enabled. Set `TASK_QUEUE_EMBEDDED_WORKER=false` when running separate worker processes with `python worker.py`.
+
+Without queue mode, execution remains direct/background for local development. Individual calls can opt into queue mode with `?use_queue=true`.
+
+## Hugging Face Spaces
+
+This repo can run as a Docker Space. Create a Hugging Face Space with SDK `Docker`, push this repo, and configure secrets:
+
+```env
+SUPABASE_URL=your_project_url
+SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
+SUPABASE_ANON_KEY=your_anon_key
+GROQ_API_KEY=optional_key
+OPENAI_API_KEY=optional_key
+GEMINI_API_KEY=optional_key
+AMD_API_KEY=optional_key
+TAVILY_API_KEY=optional_key
+SENTRY_DSN=optional_dsn
+```
+
+`VITE_API_URL` can stay empty on Spaces when the frontend and FastAPI backend share the same origin.
+
+## Documentation
+
+- [SPEC.md](./SPEC.md): Technical architecture and contracts.
+- [ROADMAP.md](./ROADMAP.md): Current implementation status and next work.
+- [docs/OPERATING_GUIDE.md](./docs/OPERATING_GUIDE.md): Operational usage and setup.
+- [docs/AUTH_MODEL.md](./docs/AUTH_MODEL.md): Enterprise authentication and OAuth policy.
+- [docs/TASK_SCHEMAS.md](./docs/TASK_SCHEMAS.md): Structured task output schema rules.
+- [docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md): Existing Supabase project migrations.
+- [docs/TASKS.md](./docs/TASKS.md): Implementation task tracker.
+- [docs/AUDIT.md](./docs/AUDIT.md): Stability and risk audit.

ROADMAP.md

@@ -0,0 +1,72 @@
+# Aubm Roadmap
+
+This document tracks the practical evolution of Aubm from a working multi-agent orchestrator into an enterprise-ready operating layer. Status is intentionally conservative:
+
+- Completed: implemented and visible in the product or backend.
+- Partial: scaffolded or implemented in a limited form, but not production-complete.
+- Next: planned work with no complete implementation yet.
+
+## Phase 1: Core Foundation (Completed)
+- [x] Autonomous Agent Execution: Multi-provider support for configured LLM providers.
+- [x] Project Orchestration: Project-level task execution with dependency-aware planning support.
+- [x] Human-in-the-Loop: Approval and rejection workflows for agent outputs.
+- [x] Project Context Injection: Project descriptions, context, notes, files, and links are passed into planning/execution.
+- [x] Final Reporting: Full, brief, pessimistic, and PDF report flows.
+
+## Phase 2: Collaboration and Operator Workflow (Completed)
+- [x] Multi-Agent Debates: Agents can cross-review and refine task output before human review.
+- [x] Agent Marketplace: Deploy reusable agent templates into a user's workspace.
+- [x] Voice Interaction: Browser voice APIs can control navigation and read project/task status.
+- [x] Spatial Dashboard: Layered project/task visualization for DAG-style inspection.
+- [x] Guided and Expert Creation Wizard: Step-by-step project creation with explanations.
+- [x] Project Roadmap View: Read-only roadmap modal inferred from task status, priority, and dependencies.
+
+## Phase 3: Production Operations (Completed)
+- [x] Operations Monitoring: Backend health endpoint and frontend monitoring dashboard with Supabase fallback.
+- [x] Deployment Hardening: Dockerized backend/runtime profile and production CORS configuration.
+- [x] Error Tracking Hooks: Sentry-compatible backend and frontend initialization.
+- [x] Performance Budgeting: Frontend code splitting and bundle-size-aware build output.
+- [x] Completed Project Locking: Completed projects are read-only in the UI and guarded by backend mutation checks.
+
+## Phase 4: Security, Governance, and Data Quality (Partial)
+- [x] Row-Level Security: Core Supabase RLS policies for projects, tasks, agents, profiles, marketplace templates, and admin access.
+- [x] Admin and Manager Roles: Profile role support includes user, manager, and admin.
+- [x] Profile Role Protection: Final profile RLS migration uses non-recursive admin checks and a trigger to block non-admin role escalation.
+- [x] Audit Log Schema: Audit table and service exist.
+- [/] Audit Log Coverage: Backend task runs, queue retries, approvals, debates, decomposition, and report generation write audit events; a trigger migration covers direct project, task, agent, and profile mutations.
+- [/] Team Permissions: `teams`, `team_members`, project `team_id`, owner-or-team RLS policies, and team-aware evidence reads are available through migration; frontend/backend workflows still need full team-aware UX/API coverage.
+- [x] SSO State: Google/GitHub buttons remain hidden by default, and the enterprise auth model is documented in `docs/AUTH_MODEL.md`.
+
+## Phase 5: Async Execution and Scale (Complete)
+- [x] Worker Scaffold: `backend/worker.py` and `TaskQueueService` exist.
+- [x] Queued Task Status: `tasks.status` now supports `queued` for background workers.
+- [x] Queue Safety: Workers claim queued tasks through an atomic Postgres lease function.
+- [x] Worker Observability: Worker heartbeats, queue depth, stale leases, and active worker counts are visible in Monitoring.
+- [x] Retry Policy: Queue attempts, exponential backoff, delayed retries, and terminal failure reasons are stored.
+- [x] Worker Integration: Task and project run endpoints can route work to the queue with `TASK_EXECUTION_MODE=queue` or `use_queue=true`.
+- [x] Queue Default: Sync execution is now fallback; queue mode is default in development and production.
+
+## Phase 6: Evidence and Entity Integrity (Complete)
+- [x] Strict JSON Task Schemas: Backend classifies structured task types, prompts for JSON, and blocks approval when required fields are missing.
+- [x] Semantic Deduplication: Extracted claims use normalized text hashes and embedding-based semantic merging to avoid duplicates per project.
+- [x] Mandatory `source_url` per Claim: Structured factual/comparison outputs require source URLs and extracted claims are stored in `task_claims`; approval is blocked if sources are missing for sensitive schemas.
+- [x] Entity Normalization Layer: `task_claims` stores normalized `entity_key` values; new `EvidenceView` component provides a unified UI for semantic findings and entity intelligence.
+- [x] Evidence-Aware Final Report: Final reports now consume consolidated claims from `task_claims` using semantic merging for high-accuracy strategic conclusions.
+
+## Phase 7: Intelligence and Memory (Next)
+- [x] Vectorized Long-Term Memory: Cross-project semantic retrieval over approved outputs and source material; implemented via `project_memory` and `match_project_memory` RPC.
+- [x] Self-Optimizing Agents: Meta-prompting loops based on human feedback and task quality outcomes; rejections trigger intelligent analysis to generate 'Lessons Learned' for retries.
+- [x] Cost Control: Project budgets, estimated usage events, and pre-run execution blocking are implemented; provider-native token usage tracking ensures billing-grade pricing reconciliation.
+- [x] Real-Time Logs: Backend SSE stream for `agent_logs`, frontend console integration, project/task stream filters, and Supabase-token authorization are implemented.
+- [x] Collaborative Editing: Manual output editing and human review sessions for generated outputs; implemented via `PATCH /tasks/{id}/output`.
+
+## Phase 8: Enterprise Multi-Tenancy & Governance (Complete)
+- [x] Team Management UI: Full interface for creating teams, inviting members, and assigning roles (admin, editor, viewer).
+- [x] Team-Aware Project Creation: Select team workspaces during project setup to enable shared context and RLS-enforced collaboration.
+- [x] Audit Explorer: Searchable and filterable UI for system-wide audit logs, including metadata inspection and deep links.
+- [x] Bulk Audit Export: Download audit logs as CSV for compliance and external reporting.
+- [x] Role-Based Marketplace: Teams can publish and share internal agent templates within their own workspace; implemented via `team_id` on templates and AgentsView sharing.
+
+---
+
+*Last updated: May 7, 2026*

SPEC.md

@@ -0,0 +1,200 @@
+# Aubm Technical Specification
+
+Target stack: FastAPI + React/TypeScript + Supabase.
+
+This document describes the current product architecture and the contracts that matter for development. For status and sequencing, see [ROADMAP.md](./ROADMAP.md).
+
+## 1. Architecture
+
+Aubm uses Supabase as the source of truth for users, projects, agents, tasks, templates, and execution records.
+
+```text
+backend/
+  main.py                    FastAPI entrypoint
+  worker.py                  Polling worker scaffold for queued tasks
+  agents/                    LLM provider adapters
+  routers/
+    agent_runner.py          Task run, approve, reject, approve-all
+    orchestrator.py          Debate, project run, report, PDF export
+  services/
+    orchestrator_service.py  Project orchestration and report building
+    agent_runner_service.py  Task execution and task_runs persistence
+    task_queue.py            Lightweight queued-task helper
+    output_quality.py        Heuristic output quality checks
+    semantic_backprop.py     Prior completed-output context builder
+  tools/                     Tool registry and tool implementations
+
+frontend/
+  src/components/            Dashboard, project detail, marketplace, settings, monitoring
+  src/services/              Supabase, runtime config, LLM defaults, UI mode
+  src/context/               Auth context
+
+database/
+  schema.sql                 Baseline schema
+  *.sql                      Idempotent migrations and seed files
+```
+
+## 2. Database
+
+### Core Tables
+
+| Table | Purpose |
+| --- | --- |
+| `profiles` | User metadata and role: `user`, `manager`, `admin`. |
+| `projects` | Project containers with owner, context, status, visibility. |
+| `agents` | Deployed agents owned by users or global templates. |
+| `agent_templates` | Marketplace agent templates. |
+| `tasks` | Units of work with status, priority, assigned agent, output data. |
+| `task_runs` | Execution history, status, errors, duration. |
+| `agent_logs` | Execution traces. |
+| `task_dependencies` | Task dependency edges. |
+| `audit_logs` | Governance trail. Coverage is partial and should be expanded. |
+| `task_feedback` | Like/dislike feedback for future optimization. |
+| `worker_heartbeats` | Background worker status and processing counters. |
+
+### Status Values
+
+Projects:
+
+```text
+active, archived, completed
+```
+
+Tasks:
+
+```text
+todo, queued, in_progress, awaiting_approval, done, failed, cancelled
+```
+
+Task runs:
+
+```text
+queued, running, completed, failed, cancelled
+```
+
+Completed projects are locked by frontend controls and backend mutation checks. Reports remain available.
+
+## 3. Backend Contracts
+
+### Task Execution
+
+`POST /tasks/{task_id}/run`
+
+Optional query:
+
+```text
+use_queue=true
+```
+
+1. Load task and assigned agent.
+2. Reject execution if the parent project is completed.
+3. If `use_queue=true` or `TASK_EXECUTION_MODE=queue`, set task to `queued` for worker execution.
+4. Otherwise set task to `in_progress` and execute through `AgentRunnerService`.
+5. Write `task_runs`, `agent_logs`, and task output.
+6. Set task to `awaiting_approval` or `failed`.
+
+### Task Review
+
+```text
+POST /tasks/{task_id}/approve
+POST /tasks/{task_id}/reject
+POST /tasks/project/{project_id}/approve-all
+```
+
+Approval runs output quality checks before moving a task to `done`. Rejection moves the task back to `todo`. These mutations are blocked when the project is completed.
+
+### Project Orchestration
+
+`POST /orchestrator/projects/{project_id}/run`
+
+Runs `todo` and `failed` tasks in priority order and assigns available agents when needed. If the project has no tasks, it can decompose the project into tasks. Completed projects are not mutable and cannot be orchestrated again.
+
+Queue mode:
+
+- `TASK_EXECUTION_MODE=queue`, or
+- `POST /orchestrator/projects/{project_id}/run?use_queue=true`
+
+In queue mode, runnable tasks are assigned and moved to `queued` for `backend/worker.py`.
+
+### Reports
+
+```text
+GET /orchestrator/projects/{project_id}/final-report?variant=full|brief|pessimistic
+GET /orchestrator/projects/{project_id}/final-report.pdf?variant=full|brief|pessimistic
+```
+
+Reports are built from approved task output. Full report generation marks the project completed.
+
+### Queue Worker
+
+`backend/worker.py` polls `tasks.status = 'queued'` through `TaskQueueService`.
+
+Current state:
+
+- Worker scaffold exists.
+- `queued` task status is supported by schema/migration.
+- Task and project run endpoints can opt into queue mode.
+- Workers claim tasks through `claim_next_queued_task`, an atomic Postgres function using `FOR UPDATE SKIP LOCKED`.
+- Queue attempts, delayed retry time, and terminal failure text are stored on `tasks`.
+- Worker heartbeat, active worker count, queue depth, delayed retry count, and stale lease metrics are exposed in Monitoring.
+
+## 4. Frontend
+
+### Primary Views
+
+- Dashboard: project cards, search, filters, status/progress sorting.
+- New Project: wizard available in Guided and Expert modes.
+- Project Detail: task management, guided workflow, reports, roadmap modal.
+- Marketplace: agent template search and deploy.
+- Agents: custom agent management.
+- Debate: two-agent review flow.
+- Monitoring: backend-first health summary with Supabase fallback.
+- Voice Control: browser speech navigation/status.
+- Spatial View: DAG-style task visualization.
+- Settings: provider defaults, UI mode, user role management.
+
+### UI Modes
+
+Guided:
+
+- Simplified navigation and workflows.
+- Project wizard steps: Basics, Context, Sources, Review.
+
+Expert:
+
+- Advanced tools and settings.
+- Project wizard steps: Basics, Context, Sources, Access, Review.
+
+## 5. Security
+
+- Supabase Auth is used for authentication.
+- Email/password is the visible login method in the current UI.
+- Google/GitHub OAuth buttons are hidden. If OAuth is enabled in Supabase, follow `docs/AUTH_MODEL.md` before exposing OAuth buttons again.
+- RLS policies protect project ownership, tasks, agents, templates, and profiles.
+- Admin profile checks use a SECURITY DEFINER helper to avoid recursive RLS policies.
+- Manager role is supported in profile constraints and admin tooling.
+
+## 6. Current Gaps
+
+- Audit log coverage is incomplete.
+- Real-time logs are persisted, but true SSE/WebSocket streaming is not complete.
+- Cost control exists only as provider token configuration, not persisted budget enforcement.
+- Structured task schemas and `task_claims` evidence extraction exist for common task types. Extracted claims include normalized entity keys and claim hashes. Final reports include normalized evidence summaries, but they are not yet built exclusively from normalized evidence.
+- Worker queue has atomic leasing, retry backoff, and heartbeat monitoring. Queue mode remains opt-in until it is made the default execution path.
+
+## 7. Validation
+
+Frontend:
+
+```powershell
+cd frontend
+npm run lint
+npm run build
+```
+
+Backend syntax spot checks:
+
+```powershell
+python -m py_compile backend\worker.py backend\services\task_queue.py
+python -m py_compile backend\routers\agent_runner.py backend\routers\orchestrator.py
+```

VERSION

@@ -0,0 +1 @@
+0.7.0

backend/.env.example

@@ -0,0 +1,19 @@
+# Supabase Configuration
+SUPABASE_URL=https://your-project-id.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
+
+# AI Provider Keys
+OPENAI_API_KEY=your-openai-key
+GROQ_API_KEY=your-groq-key
+GEMINI_API_KEY=your-gemini-key
+ANTHROPIC_API_KEY=your-anthropic-key
+TAVILY_API_KEY=your-tavily-key
+
+# App Settings
+PORT=8000
+ALLOWED_ORIGINS=http://localhost:5173,https://your-app.vercel.app
+TASK_QUEUE_EMBEDDED_WORKER=true
+OUTPUT_LANGUAGE=en
+
+# Error Tracking
+SENTRY_DSN=your-sentry-dsn

backend/Dockerfile

@@ -0,0 +1,32 @@
+# Build stage for backend
+FROM python:3.11-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# Set work directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Install Playwright browsers and their dependencies
+RUN playwright install --with-deps chromium
+
+# Copy project
+COPY . .
+
+# Expose port
+EXPOSE 8000
+
+# Run the application
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/agents/agent_factory.py

@@ -0,0 +1,45 @@
+from typing import Dict, Type
+from .base import BaseAgent
+from .openai_agent import OpenAIAgent
+from .amd_agent import AMDAgent
+from .groq_agent import GroqAgent
+from .gemini_agent import GeminiAgent
+from .local_agent import LocalAgent
+from .digitalocean_agent import DigitalOceanAgent
+from services.config import settings
+
+# Map of providers to their respective classes
+PROVIDER_MAP: Dict[str, Type[BaseAgent]] = {
+    "openai": OpenAIAgent,
+    "amd": AMDAgent,
+    "groq": GroqAgent,
+    "gemini": GeminiAgent,
+    "local": LocalAgent,
+    "ollama": LocalAgent,
+    "digitalocean": DigitalOceanAgent
+}
+
+class AgentFactory:
+    @staticmethod
+    def get_agent(provider: str, name: str, role: str, model: str, system_prompt: str = None) -> BaseAgent:
+        """
+        Instantiates the appropriate agent based on the provider string.
+        Includes a fallback to Groq if OpenAI is requested but no key is provided.
+        """
+        provider = provider.lower()
+        
+        # Fallback Logic: OpenAI -> AMD -> Groq
+        if provider == "openai" and not settings.OPENAI_API_KEY:
+            if settings.AMD_API_KEY:
+                provider = "amd"
+                model = "llama-3.3-70b-instruct"
+            elif settings.GROQ_API_KEY:
+                provider = "groq"
+                model = "llama-3.3-70b-versatile"
+
+        agent_class = PROVIDER_MAP.get(provider)
+        
+        if not agent_class:
+            raise ValueError(f"Unsupported agent provider: {provider}")
+            
+        return agent_class(name=name, role=role, model=model, system_prompt=system_prompt)

backend/agents/amd_agent.py

@@ -0,0 +1,42 @@
+from .base import BaseAgent
+from typing import Dict, Any, List
+import openai
+from services.config import settings, config_service
+
+class AMDAgent(BaseAgent):
+    """
+    Agent implementation for AMD Inference (inference.do-ai.run).
+    Compatible with OpenAI's API format.
+    """
+    def __init__(self, name: str, role: str, model: str = "gpt-4o", system_prompt: str = None):
+        super().__init__(name, role, model, system_prompt)
+        
+        self.provider_config = config_service.get_provider_config("amd")
+        api_key = self.provider_config.get("api_key") or settings.AMD_API_KEY
+        
+        self.client = None
+        if api_key:
+            self.client = openai.AsyncOpenAI(
+                api_key=api_key,
+                base_url=self.provider_config.get("base_url", "https://inference.do-ai.run/v1")
+            )
+        self.temperature = self.provider_config.get("temperature", 0.7)
+        self.max_tokens = self.provider_config.get("max_tokens", 4096)
+
+    async def run(self, task_description: str, context: List[Dict[str, Any]], use_tools: bool = False, extra_context: str = "") -> Dict[str, Any]:
+        if not self.client:
+            return {
+                "agent_name": self.name,
+                "provider": "amd",
+                "raw_output": "Error: AMD API Key not configured.",
+                "data": {"error": "Missing credentials"}
+            }
+        return await self._run_openai_compatible(
+            provider="amd",
+            create_fn=self.client.chat.completions.create,
+            task_description=task_description,
+            context=context,
+            use_tools=use_tools,
+            extra_context=extra_context,
+            response_format={"type": "json_object"}
+        )

backend/agents/base.py

@@ -0,0 +1,179 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Optional
+import json
+
+class BaseAgent(ABC):
+    def __init__(self, name: str, role: str, model: str, system_prompt: Optional[str] = None):
+        self.name = name
+        self.role = role
+        self.model = model
+        self.system_prompt = system_prompt or f"You are {name}, acting as a {role}."
+
+    @abstractmethod
+    async def run(self, task_description: str, context: List[Dict[str, Any]], use_tools: bool = False, extra_context: str = "") -> Dict[str, Any]:
+        """
+        Executes a task given its description and previous context.
+        Returns a dictionary containing the output data.
+        """
+        pass
+
+    def _format_context(self, context: List[Dict[str, Any]]) -> str:
+        """Helper to format previous task outputs for the current agent."""
+        if not context:
+            return "No previous context available."
+        
+        formatted = "Previous tasks context:\n"
+        for item in context:
+            formatted += f"- Task: {item.get('title')}\n  Output: {json.dumps(item.get('output_data', {}))}\n"
+        return formatted
+
+    def _build_json_prompt(self, task_description: str, context: List[Dict[str, Any]], extra_context: str = "") -> str:
+        return f"""
+Task: {task_description}
+
+{self._format_context(context)}
+
+{extra_context}
+
+Please provide your output as a JSON object.
+"""
+
+    def _build_chat_messages(self, task_description: str, context: List[Dict[str, Any]], extra_context: str = "") -> List[Dict[str, Any]]:
+        return [
+            {"role": "system", "content": self.system_prompt},
+            {"role": "user", "content": self._build_json_prompt(task_description, context, extra_context)}
+        ]
+
+    def _parse_json_output(self, content: str) -> Any:
+        """Parse strict JSON first, then tolerate fenced or prefixed JSON."""
+        if not content:
+            return {}
+
+        try:
+            return json.loads(content)
+        except json.JSONDecodeError:
+            pass
+
+        try:
+            if "```json" in content:
+                clean = content.split("```json", 1)[1].split("```", 1)[0].strip()
+            elif "```" in content:
+                clean = content.split("```", 1)[1].split("```", 1)[0].strip()
+            else:
+                object_start, array_start = content.find("{"), content.find("[")
+                starts = [index for index in (object_start, array_start) if index != -1]
+                start = min(starts) if starts else -1
+                if start == array_start:
+                    end = content.rfind("]")
+                else:
+                    end = content.rfind("}")
+                clean = content[start:end + 1] if start != -1 and end != -1 else content
+            return json.loads(clean)
+        except Exception:
+            return {"raw_text": content}
+
+    def _parse_tool_arguments(self, arguments: str | None) -> Dict[str, Any]:
+        parsed = self._parse_json_output(arguments or "{}")
+        return parsed if isinstance(parsed, dict) else {}
+
+    async def _append_tool_results(self, messages: List[Dict[str, Any]], tool_calls: Any, tool_registry: Any) -> None:
+        for tool_call in tool_calls or []:
+            tool_name = tool_call.function.name
+            tool_args = self._parse_tool_arguments(tool_call.function.arguments)
+            tool_result = await tool_registry.call_tool(tool_name, tool_args)
+
+            messages.append({
+                "tool_call_id": tool_call.id,
+                "role": "tool",
+                "name": tool_name,
+                "content": str(tool_result),
+            })
+
+    async def _run_openai_compatible(
+        self, 
+        provider: str, 
+        create_fn, 
+        task_description: str, 
+        context: List[Dict[str, Any]], 
+        use_tools: bool = False, 
+        extra_context: str = "",
+        **extra_kwargs
+    ) -> Dict[str, Any]:
+        """
+        Unified runner for OpenAI-compatible APIs (OpenAI, Groq, etc.)
+        """
+        from tools.registry import tool_registry
+        
+        messages = self._build_chat_messages(task_description, context, extra_context)
+        
+        is_reasoning_model = "gpt-oss-" in self.model or self.model.startswith("o1-") or self.model.startswith("o3-")
+        
+        kwargs = {
+            "model": self.model,
+            "messages": messages,
+            **extra_kwargs
+        }
+
+        # Handle temperature/max_tokens based on model type
+        if is_reasoning_model:
+            # Reasoning models prefer temperature 1.0 or none
+            kwargs["temperature"] = extra_kwargs.get("temperature", 1.0)
+            # Use max_completion_tokens if provided, otherwise default to max_tokens logic but renamed
+            if "max_completion_tokens" not in kwargs:
+                kwargs["max_completion_tokens"] = getattr(self, "max_tokens", 4096)
+            # Standard max_tokens is often forbidden in reasoning models
+            kwargs.pop("max_tokens", None)
+        else:
+            kwargs["temperature"] = getattr(self, "temperature", 0.7)
+            kwargs["max_tokens"] = getattr(self, "max_tokens", 4096)
+        
+        if use_tools:
+            # Note: Many reasoning models don't support tools yet, but we'll include if requested
+            kwargs["tools"] = tool_registry.get_tool_definitions()
+            kwargs["tool_choice"] = "auto"
+
+        response = await create_fn(**kwargs)
+        message = response.choices[0].message
+        usage = getattr(response, "usage", None)
+
+        if message.tool_calls:
+            messages.append(message)
+            await self._append_tool_results(messages, message.tool_calls, tool_registry)
+            
+            # Second call after tool execution
+            # Remove tools from second call to force a final answer
+            kwargs.pop("tools", None)
+            kwargs.pop("tool_choice", None)
+            
+            final_response = await create_fn(**kwargs)
+            final_usage = getattr(final_response, "usage", None)
+            if usage and final_usage:
+                usage.prompt_tokens += final_usage.prompt_tokens
+                usage.completion_tokens += final_usage.completion_tokens
+                usage.total_tokens += final_usage.total_tokens
+            elif final_usage:
+                usage = final_usage
+
+            content = final_response.choices[0].message.content
+        else:
+            content = message.content
+
+        usage_dict = None
+        if usage:
+            usage_dict = {
+                "prompt_tokens": getattr(usage, "prompt_tokens", 0),
+                "completion_tokens": getattr(usage, "completion_tokens", 0),
+                "total_tokens": getattr(usage, "total_tokens", 0)
+            }
+
+        return self._result(provider, content or "", usage=usage_dict)
+
+    def _result(self, provider: str, content: str, usage: Optional[Dict[str, int]] = None) -> Dict[str, Any]:
+        return {
+            "agent_name": self.name,
+            "provider": provider,
+            "model": self.model,
+            "raw_output": content,
+            "usage": usage,
+            "data": self._parse_json_output(content)
+        }

backend/agents/digitalocean_agent.py

@@ -0,0 +1,62 @@
+from .base import BaseAgent
+from typing import Dict, Any, List
+import openai
+from services.config import settings, config_service
+
+class DigitalOceanAgent(BaseAgent):
+    """
+    Agent provider using DigitalOcean's Gradient Inference API.
+    Supports both Serverless Inference and dedicated Agent Inference endpoints.
+    """
+    def __init__(self, name: str, role: str, model: str = "llama-3.3-70b-instruct", system_prompt: str = None):
+        super().__init__(name, role, model, system_prompt)
+        
+        # Load dynamic config
+        self.provider_config = config_service.get_provider_config("digitalocean")
+        
+        # Priority: Agent Access Key -> Inference Key -> AMD Key -> DO Token
+        api_key = (
+            self.provider_config.get("agent_access_key") or 
+            settings.DO_AGENT_ACCESS_KEY or 
+            self.provider_config.get("api_key") or 
+            settings.DO_INFERENCE_KEY or 
+            settings.AMD_API_KEY or
+            settings.DO_API_TOKEN
+        )
+        
+        # Priority: Agent Endpoint -> Default Serverless Endpoint
+        base_url = (
+            self.provider_config.get("base_url") or 
+            settings.DO_AGENT_ENDPOINT or 
+            "https://inference.do-ai.run/v1"
+        )
+        
+        # Ensure base_url has the correct suffix if it's a raw agent URL
+        if ".agents.do-ai.run" in base_url and not base_url.endswith("/v1"):
+            base_url = f"{base_url.rstrip('/')}/v1"
+        elif "api.digitalocean.com" not in base_url and "do-ai.run" not in base_url:
+             # Fallback logic for potentially missing /v1 in custom domains
+             if not base_url.endswith("/v1"):
+                 base_url = f"{base_url.rstrip('/')}/v1"
+
+        self.client = openai.AsyncOpenAI(
+            api_key=api_key,
+            base_url=base_url
+        )
+        self.is_agent_endpoint = "agents.do-ai.run" in base_url or settings.DO_AGENT_ENDPOINT is not None
+        self.temperature = self.provider_config.get("temperature", 0.7)
+        self.max_tokens = self.provider_config.get("max_tokens", 4096)
+
+    async def run(self, task_description: str, context: List[Dict[str, Any]], use_tools: bool = False, extra_context: str = "") -> Dict[str, Any]:
+        # DigitalOcean Agent Inference requires ?agent=true
+        extra_query = {"agent": "true"} if self.is_agent_endpoint else {}
+        
+        return await self._run_openai_compatible(
+            provider="digitalocean",
+            create_fn=self.client.chat.completions.create,
+            task_description=task_description,
+            context=context,
+            use_tools=use_tools,
+            extra_context=extra_context,
+            extra_query=extra_query
+        )

backend/agents/gemini_agent.py

@@ -0,0 +1,37 @@
+from .base import BaseAgent
+from typing import Dict, Any, List
+from google import genai
+from services.config import settings, config_service
+
+class GeminiAgent(BaseAgent):
+    """
+    Agent implementation for Google Gemini using the new google-genai SDK.
+    """
+    def __init__(self, name: str, role: str, model: str = "gemini-2.0-flash", system_prompt: str = None):
+        super().__init__(name, role, model, system_prompt)
+        
+        # Load dynamic config
+        self.provider_config = config_service.get_provider_config("gemini")
+        api_key = self.provider_config.get("api_key") or settings.GEMINI_API_KEY
+        
+        self.client = genai.Client(api_key=api_key)
+        self.temperature = self.provider_config.get("temperature", 0.7)
+
+    async def run(self, task_description: str, context: List[Dict[str, Any]], use_tools: bool = False, extra_context: str = "") -> Dict[str, Any]:
+        full_prompt = f"""
+System Instruction: {self.system_prompt}
+
+{self._build_json_prompt(task_description, context, extra_context)}
+"""
+
+        # Gemini 2.0 Flash is very fast.
+        response = await self.client.aio.models.generate(
+            model=self.model,
+            contents=full_prompt,
+            config={
+                "temperature": self.temperature,
+                "response_mime_type": "application/json",
+            }
+        )
+
+        return self._result("gemini", response.text or "")

backend/agents/groq_agent.py

@@ -0,0 +1,107 @@
+import logging
+from .base import BaseAgent
+from typing import Dict, Any, List
+import groq
+import json
+from services.config import settings, config_service
+from tools.registry import tool_registry
+
+logger = logging.getLogger("uvicorn")
+
+GROQ_ROTATION_POOL = [
+    "llama-3.3-70b-versatile",
+    "openai/gpt-oss-120b",
+    "meta-llama/llama-4-scout-17b-16e-instruct",
+    "qwen/qwen3-32b",
+    "openai/gpt-oss-20b",
+    "groq/compound",
+    "llama-3.1-8b-instant"
+]
+
+class GroqAgent(BaseAgent):
+    """
+    Agent implementation for Groq with automatic model rotation for rate limits.
+    """
+    def __init__(self, name: str, role: str, model: str = "llama-3.3-70b-versatile", system_prompt: str = None):
+        # Auto-migrate decommissioned models
+        if "llama-3.1-70b" in model or "llama3-70b-8192" in model:
+            model = "llama-3.3-70b-versatile"
+            
+        super().__init__(name, role, model, system_prompt)
+        
+        # Load dynamic config
+        self.provider_config = config_service.get_provider_config("groq")
+        api_key = self.provider_config.get("api_key") or settings.GROQ_API_KEY
+        
+        self.client = None
+        if api_key:
+            self.client = groq.AsyncGroq(api_key=api_key)
+        self.temperature = self.provider_config.get("temperature", 0.7)
+        self.max_tokens = self.provider_config.get("max_tokens", 4096)
+        self.reasoning_effort = self.provider_config.get("reasoning_effort", "medium")
+
+    def _format_context(self, context: List[Dict[str, Any]]) -> str:
+        """Extremely aggressive truncation for Groq TPM limits."""
+        if not context:
+            return "No previous context available."
+        
+        # Only take the last 3 tasks to save tokens
+        recent_context = context[-3:]
+        
+        formatted = "Previous tasks context (EXTREMELY TRUNCATED for Groq):\n"
+        for item in recent_context:
+            output_raw = json.dumps(item.get('output_data', {}))
+            # 800 chars is roughly 200 tokens.
+            if len(output_raw) > 800:
+                output_raw = output_raw[:800] + "... [TRUNCATED]"
+            
+            formatted += f"- Task: {item.get('title')}\n  Output: {output_raw}\n"
+        return formatted
+
+    async def run(self, task_description: str, context: List[Dict[str, Any]], use_tools: bool = False, extra_context: str = "") -> Dict[str, Any]:
+        # Very limited semantic context
+        if len(extra_context) > 1000:
+            extra_context = extra_context[:1000] + "... [TRUNCATED]"
+            
+        try:
+            return await self._execute_run(task_description, context, use_tools, extra_context)
+        except groq.RateLimitError as e:
+            logger.warning(f"Rate limit reached for {self.model} (429). Attempting model rotation...")
+            
+            # Find current model index in pool
+            try:
+                current_idx = GROQ_ROTATION_POOL.index(self.model)
+            except ValueError:
+                current_idx = -1
+            
+            # Try the next model in the pool
+            next_idx = (current_idx + 1) % len(GROQ_ROTATION_POOL)
+            fallback_model = GROQ_ROTATION_POOL[next_idx]
+            
+            logger.info(f"Rotating from {self.model} to {fallback_model}")
+            self.model = fallback_model
+            
+            # Retry once with fallback model
+            return await self._execute_run(task_description, context, use_tools, extra_context)
+
+    async def _execute_run(self, task_description: str, context: List[Dict[str, Any]], use_tools: bool = False, extra_context: str = "") -> Dict[str, Any]:
+        if not self.client:
+            return {
+                "agent_name": self.name,
+                "provider": "groq",
+                "raw_output": "Error: Groq API Key not configured.",
+                "data": {"error": "Missing credentials"}
+            }
+        extra_kwargs = {}
+        if "gpt-oss-" in self.model:
+            extra_kwargs["reasoning_effort"] = self.reasoning_effort
+            
+        return await self._run_openai_compatible(
+            provider="groq",
+            create_fn=self.client.chat.completions.create,
+            task_description=task_description,
+            context=context,
+            use_tools=use_tools,
+            extra_context=extra_context,
+            **extra_kwargs
+        )

backend/agents/local_agent.py

@@ -0,0 +1,48 @@
+from .base import BaseAgent
+from typing import Dict, Any, List
+import httpx
+from services.config import config_service
+
+class LocalAgent(BaseAgent):
+    """
+    Agent implementation for Local LLMs (Ollama).
+    """
+    def __init__(self, name: str, role: str, model: str = "llama3.1:8b", system_prompt: str = None):
+        super().__init__(name, role, model, system_prompt)
+        
+        # Load dynamic config
+        self.provider_config = config_service.get_provider_config("ollama")
+        self.base_url = self.provider_config.get("base_url", "http://localhost:11434")
+        self.temperature = self.provider_config.get("temperature", 0.7)
+
+    async def run(self, task_description: str, context: List[Dict[str, Any]], use_tools: bool = False, extra_context: str = "") -> Dict[str, Any]:
+        full_prompt = f"""
+System Instructions: {self.system_prompt}
+
+{self._build_json_prompt(task_description, context, extra_context)}
+"""
+
+        async with httpx.AsyncClient(timeout=60.0) as client:
+            try:
+                response = await client.post(
+                    f"{self.base_url}/api/generate",
+                    json={
+                        "model": self.model,
+                        "prompt": full_prompt,
+                        "stream": False,
+                        "format": "json",
+                        "options": {
+                            "temperature": self.temperature
+                        }
+                    }
+                )
+                response.raise_for_status()
+                result = response.json()
+                return self._result("local", result.get("response", "{}"))
+            except Exception as e:
+                return {
+                    "agent_name": self.name,
+                    "provider": "local",
+                    "status": "error",
+                    "error": f"Ollama connection failed: {str(e)}"
+                }

backend/agents/openai_agent.py

@@ -0,0 +1,37 @@
+from .base import BaseAgent
+from typing import Dict, Any, List
+import openai
+from services.config import settings, config_service
+from tools.registry import tool_registry
+
+class OpenAIAgent(BaseAgent):
+    def __init__(self, name: str, role: str, model: str = "gpt-4o", system_prompt: str = None):
+        super().__init__(name, role, model, system_prompt)
+        
+        # Load dynamic config
+        self.provider_config = config_service.get_provider_config("openai")
+        api_key = self.provider_config.get("api_key") or settings.OPENAI_API_KEY
+        
+        self.client = None
+        if api_key:
+            self.client = openai.AsyncOpenAI(api_key=api_key)
+        self.temperature = self.provider_config.get("temperature", 0.7)
+        self.max_tokens = self.provider_config.get("max_tokens", 4096)
+
+    async def run(self, task_description: str, context: List[Dict[str, Any]], use_tools: bool = False, extra_context: str = "") -> Dict[str, Any]:
+        if not self.client:
+            return {
+                "agent_name": self.name,
+                "provider": "openai",
+                "raw_output": "Error: OpenAI API Key not configured.",
+                "data": {"error": "Missing credentials"}
+            }
+        return await self._run_openai_compatible(
+            provider="openai",
+            create_fn=self.client.chat.completions.create,
+            task_description=task_description,
+            context=context,
+            use_tools=use_tools,
+            extra_context=extra_context,
+            response_format={"type": "json_object"}
+        )

backend/agents_debug.json

@@ -0,0 +1 @@
+[{"id": "297ef087-89af-4e3b-8d80-c5c5c7499e3b", "name": "GPT-4o", "role": "General Intelligence", "api_provider": "openai", "model": "gpt-4o", "system_prompt": "You are a highly capable AI assistant.", "created_at": "2026-05-04T14:32:03.072888+00:00", "updated_at": "2026-05-04T14:32:03.072888+00:00", "user_id": null}, {"id": "64aebf0c-625a-4c6f-895d-a36274c4f9fd", "name": "AMD-4o", "role": "Performance Specialist", "api_provider": "amd", "model": "gpt-4o", "system_prompt": "You are a high-performance agent running on AMD infrastructure.", "created_at": "2026-05-04T14:32:03.072888+00:00", "updated_at": "2026-05-04T14:32:03.072888+00:00", "user_id": null}, {"id": "f7cc5a82-1e7d-4f21-9855-922fb82cd6f9", "name": "Llama-3-70B", "role": "Fast Logic", "api_provider": "groq", "model": "llama3-70b-8192", "system_prompt": "You are a fast and efficient reasoning agent.", "created_at": "2026-05-04T14:32:03.072888+00:00", "updated_at": "2026-05-04T14:32:03.072888+00:00", "user_id": null}, {"id": "1d988b3c-38c1-4132-85e1-82e7a4bc4f8a", "name": "Growth Hacker", "role": "Marketing Expert", "api_provider": "openai", "model": "gpt-4o", "system_prompt": "You are a Growth Hacker focused on low-cost, high-impact strategies.", "created_at": "2026-05-04T15:50:52.628388+00:00", "updated_at": "2026-05-04T15:50:52.628388+00:00", "user_id": "483025be-ca4b-4de3-aa80-9eb39dbd3578"}, {"id": "7b056c90-f4a6-4629-81b1-f4316b76d091", "name": "Growth Hacker", "role": "Marketing Expert", "api_provider": "openai", "model": "gpt-4o", "system_prompt": "You are a Growth Hacker focused on low-cost, high-impact strategies.", "created_at": "2026-05-04T16:22:10.993123+00:00", "updated_at": "2026-05-04T16:22:10.993123+00:00", "user_id": "483025be-ca4b-4de3-aa80-9eb39dbd3578"}, {"id": "138d7d29-b2c0-4ffb-b89f-1a0965dca6b6", "name": "Planner", "role": "Project Planner", "api_provider": "openai", "model": "gpt-4o", "system_prompt": "You decompose goals into clear, ordered implementation tasks.", "created_at": "2026-05-04T18:06:05.280562+00:00", "updated_at": "2026-05-04T18:06:05.280562+00:00", "user_id": "483025be-ca4b-4de3-aa80-9eb39dbd3578"}, {"id": "edfc99cf-a70c-42e0-a2f6-4508bb6aac33", "name": "Builder", "role": "Implementation Agent", "api_provider": "openai", "model": "gpt-4o", "system_prompt": "You implement practical, production-oriented solutions with concise output.", "created_at": "2026-05-04T18:06:05.280562+00:00", "updated_at": "2026-05-04T18:06:05.280562+00:00", "user_id": "483025be-ca4b-4de3-aa80-9eb39dbd3578"}, {"id": "5ef6c6f3-fc4a-40ba-abe8-7630fefcece2", "name": "Reviewer", "role": "Quality Reviewer", "api_provider": "openai", "model": "gpt-4o", "system_prompt": "You review outputs for correctness, security, completeness, and missing tests.", "created_at": "2026-05-04T18:06:05.280562+00:00", "updated_at": "2026-05-04T18:06:05.280562+00:00", "user_id": "483025be-ca4b-4de3-aa80-9eb39dbd3578"}]

backend/api/index.py

@@ -0,0 +1 @@
+from main import app

backend/main.py

@@ -0,0 +1,199 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, Response, JSONResponse
+import asyncio
+import logging
+import os
+import json
+from pathlib import Path
+from dotenv import load_dotenv
+import sentry_sdk
+from services.orchestrator_service import orchestrator_service
+from services.infrastructure_service import infrastructure_service
+from services.config import settings
+from worker import AubmWorker
+
+
+def _load_app_version() -> str:
+    version_file = Path(__file__).resolve().parent.parent / "VERSION"
+    if version_file.exists():
+        value = version_file.read_text(encoding="utf-8").strip()
+        if value:
+            return value
+    return os.getenv("APP_VERSION", "0.7.0")
+
+
+# Load environment variables
+load_dotenv()
+
+# Silence noisy libraries
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpcore").setLevel(logging.WARNING)
+logging.getLogger("supabase").setLevel(logging.WARNING)
+logging.getLogger("postgrest").setLevel(logging.WARNING)
+
+FRONTEND_DIST = Path(__file__).resolve().parent.parent / "frontend" / "dist"
+APP_VERSION = _load_app_version()
+logger = logging.getLogger("aubm.api")
+embedded_worker: AubmWorker | None = None
+embedded_worker_task: asyncio.Task | None = None
+
+# Sentry Initialization
+SENTRY_DSN = os.getenv("SENTRY_DSN")
+if SENTRY_DSN:
+    sentry_sdk.init(
+        dsn=SENTRY_DSN,
+        traces_sample_rate=1.0,
+        profiles_sample_rate=1.0,
+    )
+
+app = FastAPI(
+    title="Aubm API",
+    description="Enterprise-Grade AI Agent Orchestration & Collaboration Platform",
+    version=APP_VERSION
+)
+
+# CORS Configuration
+allowed_origins = os.getenv("ALLOWED_ORIGINS", "http://localhost:5173,http://localhost:3000,http://127.0.0.1:5173").split(",")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=allowed_origins if allowed_origins != ["*"] else ["*"],
+    allow_origin_regex=os.getenv("ALLOWED_ORIGIN_REGEX"),
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def _log_embedded_worker_result(task: asyncio.Task) -> None:
+    if task.cancelled():
+        return
+
+    exc = task.exception()
+    if exc:
+        logger.error(
+            "Embedded worker stopped unexpectedly",
+            exc_info=(type(exc), exc, exc.__traceback__),
+        )
+
+
+@app.on_event("startup")
+async def start_embedded_worker() -> None:
+    global embedded_worker, embedded_worker_task
+
+    if settings.TASK_EXECUTION_MODE != "queue" or not settings.TASK_QUEUE_EMBEDDED_WORKER:
+        return
+
+    if embedded_worker_task and not embedded_worker_task.done():
+        return
+
+    embedded_worker = AubmWorker()
+    embedded_worker_task = asyncio.create_task(embedded_worker.start())
+    embedded_worker_task.add_done_callback(_log_embedded_worker_result)
+    logger.info("Embedded task worker started: %s", embedded_worker.worker_id)
+
+
+@app.on_event("shutdown")
+async def stop_embedded_worker() -> None:
+    global embedded_worker, embedded_worker_task
+
+    if not embedded_worker or not embedded_worker_task:
+        return
+
+    embedded_worker.stop()
+    try:
+        await asyncio.wait_for(embedded_worker_task, timeout=10)
+        await embedded_worker.heartbeat("stopping")
+    except asyncio.TimeoutError:
+        embedded_worker_task.cancel()
+        logger.warning("Embedded task worker did not stop before timeout")
+    finally:
+        embedded_worker = None
+        embedded_worker_task = None
+
+
+@app.get("/")
+async def root():
+    index_path = FRONTEND_DIST / "index.html"
+    if index_path.exists():
+        return FileResponse(index_path)
+
+    return {
+        "status": "online",
+        "message": "Aubm API is operational",
+        "version": APP_VERSION
+    }
+
+# Placeholder for routers
+from routers import orchestrator, monitoring, agent_runner, generator
+
+app.include_router(agent_runner.router, prefix="/api/tasks", tags=["Tasks"])
+app.include_router(orchestrator.router, prefix="/api/orchestrator", tags=["orchestrator"])
+app.include_router(generator.router, prefix="/api/generator", tags=["generator"])
+app.include_router(monitoring.router, prefix="/api/monitoring", tags=["Monitoring"])
+
+@app.get("/runtime-config.js", include_in_schema=False)
+async def runtime_config():
+    config = {
+        "apiUrl": os.getenv("VITE_API_URL", ""),
+        "supabaseUrl": os.getenv("VITE_SUPABASE_URL", os.getenv("SUPABASE_URL", "")),
+        "supabaseAnonKey": os.getenv("VITE_SUPABASE_ANON_KEY", os.getenv("SUPABASE_ANON_KEY", "")),
+        "sentryDsn": os.getenv("VITE_SENTRY_DSN", os.getenv("SENTRY_DSN", "")),
+        "appVersion": APP_VERSION,
+    }
+    return Response(
+        content=f"window.__AUBM_CONFIG__ = {json.dumps(config)};",
+        media_type="application/javascript",
+    )
+
+@app.get("/{path:path}", include_in_schema=False)
+async def serve_frontend(path: str):
+    if not FRONTEND_DIST.exists():
+        return await root()
+
+    requested_path = FRONTEND_DIST / path
+    if requested_path.is_file():
+        return FileResponse(requested_path)
+
+
+
+    # For SPA routing, serve index.html for all other paths, 
+    # but NOT for paths starting with api/ (which should have been caught by routers)
+    if path.startswith("api/"):
+        return JSONResponse(status_code=404, content={"detail": f"API route not found: /{path}"})
+
+    index_path = FRONTEND_DIST / "index.html"
+    if index_path.exists():
+        return FileResponse(index_path)
+
+    return await root()
+
+# --- Infrastructure Management ---
+
+@app.post("/infrastructure/nodes/provision")
+async def provision_node(name: str = "aubm-inference-node", size: str = "s-4vcpu-8gb-amd"):
+    """Creates a new inference node on DigitalOcean."""
+    node = await infrastructure_service.create_inference_node(name, size)
+    if not node:
+        raise HTTPException(status_code=500, detail="Failed to initiate node provisioning.")
+    return node
+
+@app.get("/infrastructure/nodes/{droplet_id}/ip")
+async def get_node_ip(droplet_id: int):
+    """Wait and return the public IP of a node."""
+    ip = await infrastructure_service.wait_for_ip(droplet_id)
+    if not ip:
+        raise HTTPException(status_code=404, detail="IP not assigned or timed out.")
+    return {"ip": ip}
+
+@app.delete("/infrastructure/nodes/{droplet_id}")
+async def terminate_node(droplet_id: int):
+    """Destroy an inference node."""
+    success = await infrastructure_service.terminate_node(droplet_id)
+    if not success:
+        raise HTTPException(status_code=500, detail="Failed to terminate node.")
+    return {"status": "termination_requested"}
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=int(settings.PORT))

backend/project_debug.json

@@ -0,0 +1 @@
+{"id": "53f39562-09aa-447b-b251-3844e1415d4c", "name": "Commercial analysis", "description": "I want to evaluate differents applications similar to this app", "context": "search in internet", "owner_id": "483025be-ca4b-4de3-aa80-9eb39dbd3578", "status": "active", "is_public": true, "created_at": "2026-05-04T16:38:03.872534+00:00", "updated_at": "2026-05-04T16:38:03.872534+00:00", "team_id": null}

backend/requirements.txt

@@ -0,0 +1,19 @@
+fastapi
+uvicorn[standard]
+supabase
+openai
+groq
+google-genai
+playwright
+folium
+python-dotenv
+pydantic
+pydantic-settings
+httpx
+jinja2
+python-multipart
+reportlab
+pandas
+openpyxl
+psutil
+sentry-sdk[fastapi]

backend/routers/__init__.py

@@ -0,0 +1 @@
+# Routers package

backend/routers/agent_runner.py

@@ -0,0 +1,483 @@
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Request
+from fastapi.responses import StreamingResponse
+from services.supabase_service import supabase
+from services.agent_runner_service import AgentRunnerService
+from services.config import settings
+from services.audit_service import audit_service
+from services.output_quality import report_text_from_output
+from services.task_queue import TaskQueueService
+from services.memory_service import memory_service
+from services.project_service import project_service
+from services.utils import log_async_task_result
+import asyncio
+import json
+import logging
+
+router = APIRouter()
+logger = logging.getLogger("uvicorn")
+
+
+def _assert_task_quality(task: dict):
+    output_data = task.get("output_data") or {}
+    if not isinstance(output_data, dict):
+        raise HTTPException(status_code=400, detail="Task output is missing or malformed.")
+    if output_data.get("error"):
+        raise HTTPException(status_code=400, detail=f"Task execution failed: {output_data['error']}")
+    rendered = report_text_from_output(output_data).strip()
+    if not rendered or rendered in ("{}", "[]"):
+        raise HTTPException(status_code=400, detail="Task has no usable output to approve.")
+    quality_review = output_data.get("quality_review")
+    if not quality_review:
+        raise HTTPException(status_code=400, detail="Task output is missing quality validation.")
+    if quality_review.get("approved"):
+        return
+    reasons = quality_review.get("fail_reasons") or ["Task output failed quality validation."]
+    raise HTTPException(status_code=400, detail=f"Task output failed quality review: {'; '.join(reasons)}")
+
+
+def _assert_task_project_is_mutable(task: dict):
+    project_id = task.get("project_id")
+    if project_id:
+        project_service.ensure_project_is_mutable(project_id)
+
+def update_task_status(task_id: str, status: str):
+    task_res = supabase.table("tasks").select("project_id").eq("id", task_id).single().execute()
+    if not task_res.data:
+        raise HTTPException(status_code=404, detail="Task not found")
+    _assert_task_project_is_mutable(task_res.data)
+
+    result = (
+        supabase.table("tasks")
+        .update({"status": status})
+        .eq("id", task_id)
+        .execute()
+    )
+    if not result.data:
+        raise HTTPException(status_code=404, detail="Task not found or status was not updated")
+
+    task_data = result.data[0]
+
+    project_id = task_data.get("project_id")
+    if project_id:
+        task_result = (
+            supabase.table("tasks")
+            .select("id,status")
+            .eq("project_id", project_id)
+            .execute()
+        )
+        tasks = task_result.data or []
+        if status == "done" and tasks and all(t.get("status") == "done" for t in tasks):
+            supabase.table("projects").update({"status": "completed"}).eq("id", project_id).execute()
+        elif status != "done":
+            supabase.table("projects").update({"status": "active"}).eq("id", project_id).execute()
+
+    return task_data
+
+
+def _sse_event(event: str, data: dict, event_id: str | None = None) -> str:
+    lines = []
+    if event_id:
+        lines.append(f"id: {event_id}")
+    lines.append(f"event: {event}")
+    payload = json.dumps(data, default=str)
+    for line in payload.splitlines() or ["{}"]:
+        lines.append(f"data: {line}")
+    return "\n".join(lines) + "\n\n"
+
+
+def _project_task_ids(project_id: str) -> list[str]:
+    rows = (
+        supabase.table("tasks")
+        .select("id")
+        .eq("project_id", project_id)
+        .execute()
+        .data
+        or []
+    )
+    return [row["id"] for row in rows if row.get("id")]
+
+
+def _user_id_from_access_token(access_token: str | None) -> str:
+    if not access_token:
+        raise HTTPException(status_code=401, detail="Missing access token")
+    try:
+        auth_user = supabase.auth.get_user(access_token)
+        user = getattr(auth_user, "user", None)
+        user_id = getattr(user, "id", None)
+        if not user_id and isinstance(auth_user, dict):
+            user_id = auth_user.get("user", {}).get("id")
+    except Exception as exc:
+        logger.warning("Could not validate log stream access token: %s", exc)
+        raise HTTPException(status_code=401, detail="Invalid access token") from exc
+    if not user_id:
+        raise HTTPException(status_code=401, detail="Invalid access token")
+    return user_id
+
+
+def _team_ids_for_user(user_id: str) -> list[str]:
+    try:
+        rows = (
+            supabase.table("team_members")
+            .select("team_id")
+            .eq("user_id", user_id)
+            .execute()
+            .data
+            or []
+        )
+    except Exception as exc:
+        logger.warning("Team membership lookup unavailable for log stream: %s", exc)
+        return []
+    return [row["team_id"] for row in rows if row.get("team_id")]
+
+
+def _project_ids_for_user(user_id: str) -> list[str]:
+    project_ids: set[str] = set()
+
+    owned = (
+        supabase.table("projects")
+        .select("id")
+        .eq("owner_id", user_id)
+        .execute()
+        .data
+        or []
+    )
+    project_ids.update(row["id"] for row in owned if row.get("id"))
+
+    public = (
+        supabase.table("projects")
+        .select("id")
+        .eq("is_public", True)
+        .execute()
+        .data
+        or []
+    )
+    project_ids.update(row["id"] for row in public if row.get("id"))
+
+    team_ids = _team_ids_for_user(user_id)
+    if team_ids:
+        team_projects = (
+            supabase.table("projects")
+            .select("id")
+            .in_("team_id", team_ids)
+            .execute()
+            .data
+            or []
+        )
+        project_ids.update(row["id"] for row in team_projects if row.get("id"))
+
+    return list(project_ids)
+
+
+def _can_view_project_for_user(project_id: str, user_id: str) -> bool:
+    if not project_id:
+        return False
+    if project_id in _project_ids_for_user(user_id):
+        return True
+    return False
+
+
+def _authorized_task_ids(user_id: str, project_id: str | None = None, task_id: str | None = None) -> list[str]:
+    if task_id:
+        task = supabase.table("tasks").select("id,project_id").eq("id", task_id).single().execute().data
+        if not task or not _can_view_project_for_user(task.get("project_id"), user_id):
+            raise HTTPException(status_code=403, detail="Task logs are not visible to this user")
+        return [task_id]
+
+    if project_id:
+        if not _can_view_project_for_user(project_id, user_id):
+            raise HTTPException(status_code=403, detail="Project logs are not visible to this user")
+        return _project_task_ids(project_id)
+
+    project_ids = _project_ids_for_user(user_id)
+    if not project_ids:
+        return []
+    rows = (
+        supabase.table("tasks")
+        .select("id")
+        .in_("project_id", project_ids)
+        .execute()
+        .data
+        or []
+    )
+    return [row["id"] for row in rows if row.get("id")]
+
+
+def _fetch_recent_logs(
+    limit: int = 50,
+    after_created_at: str | None = None,
+    *,
+    task_ids: list[str],
+) -> list[dict]:
+    if not task_ids:
+        return []
+    query = (
+        supabase.table("agent_logs")
+        .select("id,task_id,run_id,action,content,metadata,created_at")
+        .order("created_at", desc=after_created_at is None)
+        .limit(limit)
+        .in_("task_id", task_ids)
+    )
+    if after_created_at:
+        query = query.gt("created_at", after_created_at)
+    rows = query.execute().data or []
+    return rows if after_created_at else list(reversed(rows))
+
+
+@router.get("/logs/stream")
+async def stream_agent_logs(
+    request: Request,
+    limit: int = 50,
+    project_id: str | None = None,
+    task_id: str | None = None,
+    access_token: str | None = None,
+):
+    """
+    Streams agent log inserts as Server-Sent Events.
+    """
+    if project_id and task_id:
+        raise HTTPException(status_code=400, detail="Use either project_id or task_id, not both.")
+    user_id = _user_id_from_access_token(access_token)
+    task_ids = _authorized_task_ids(user_id, project_id=project_id, task_id=task_id)
+
+    async def event_generator():
+        last_created_at = None
+        sent_ids: set[str] = set()
+        yield _sse_event("ready", {
+            "message": "Agent log stream connected",
+            "project_id": project_id,
+            "task_id": task_id,
+            "user_id": user_id,
+        })
+
+        while not await request.is_disconnected():
+            try:
+                rows = _fetch_recent_logs(
+                    limit=max(1, min(limit, 100)),
+                    after_created_at=last_created_at,
+                    task_ids=task_ids,
+                )
+                for row in rows:
+                    row_id = row.get("id")
+                    if row_id in sent_ids:
+                        continue
+                    sent_ids.add(row_id)
+                    if len(sent_ids) > 500:
+                        sent_ids = set(list(sent_ids)[-250:])
+                    last_created_at = row.get("created_at") or last_created_at
+                    yield _sse_event("log", row, row_id)
+            except Exception as exc:
+                logger.warning("Agent log SSE stream failed to fetch logs: %s", exc)
+                yield _sse_event("error", {"message": str(exc)})
+
+            yield ": keep-alive\n\n"
+            await asyncio.sleep(1)
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.post("/{task_id}/run")
+async def run_task(task_id: str, background_tasks: BackgroundTasks, use_queue: bool | None = None):
+    """
+    Triggers the execution of a specific task.
+    """
+    # 1. Fetch task data
+    task_res = supabase.table("tasks").select("*, project:projects(*)").eq("id", task_id).single().execute()
+    if not task_res.data:
+        raise HTTPException(status_code=404, detail="Task not found")
+    
+    task = task_res.data
+    _assert_task_project_is_mutable(task)
+    
+    # 2. Check if agent is assigned
+    agent_id = task.get("assigned_agent_id")
+    if not agent_id:
+        raise HTTPException(status_code=400, detail="No agent assigned to this task")
+    
+    # 3. Fetch agent data
+    agent_res = supabase.table("agents").select("*").eq("id", agent_id).single().execute()
+    if not agent_res.data:
+        raise HTTPException(status_code=404, detail="Assigned agent not found")
+    
+    agent_data = agent_res.data
+
+    should_queue = use_queue if use_queue is not None else False
+    if should_queue:
+        queued = await TaskQueueService.queue_task(task_id)
+        if not queued or not queued.data:
+            raise HTTPException(status_code=500, detail="Task could not be queued")
+        await audit_service.log_action(
+            user_id=task.get("project", {}).get("owner_id"),
+            action="task_queued",
+            agent_id=agent_id,
+            task_id=task_id,
+            metadata={"project_id": task.get("project_id"), "source": "task_run_endpoint"},
+        )
+        return {"message": "Task queued for worker execution", "task_id": task_id, "mode": "queue"}
+    
+    # 4. Update task status to in_progress
+    supabase.table("tasks").update({"status": "in_progress"}).eq("id", task_id).execute()
+    await audit_service.log_action(
+        user_id=task.get("project", {}).get("owner_id"),
+        action="task_run_started",
+        agent_id=agent_id,
+        task_id=task_id,
+        metadata={"project_id": task.get("project_id"), "mode": "direct"},
+    )
+    
+    # 5. Run in background
+    runner_task = asyncio.create_task(AgentRunnerService.execute_agent_logic(task, agent_data))
+    runner_task.add_done_callback(lambda current: log_async_task_result(current, f"run_task({task_id})"))
+    
+    return {"message": "Task execution started", "task_id": task_id}
+
+@router.patch("/{task_id}/output")
+async def update_task_output(task_id: str, payload: dict):
+    """
+    Updates the output_data of a task. Allows for manual human corrections.
+    """
+    if "output_data" not in payload:
+        raise HTTPException(status_code=400, detail="Missing output_data in payload")
+    
+    # Verify task existence and project state
+    task_res = supabase.table("tasks").select("id, project_id").eq("id", task_id).single().execute()
+    if not task_res.data:
+        raise HTTPException(status_code=404, detail="Task not found")
+    _assert_task_project_is_mutable(task_res.data)
+
+    result = supabase.table("tasks").update({
+        "output_data": payload["output_data"]
+    }).eq("id", task_id).execute()
+
+    if not result.data:
+        raise HTTPException(status_code=500, detail="Failed to update task output")
+        
+    await audit_service.log_action(
+        user_id=None,
+        action="task_output_manually_edited",
+        task_id=task_id,
+        metadata={"project_id": task_res.data["project_id"]}
+    )
+
+    return {"message": "Task output updated", "task": result.data[0]}
+
+@router.post("/{task_id}/approve")
+async def approve_task(task_id: str, background_tasks: BackgroundTasks):
+    task_res = supabase.table("tasks").select("*").eq("id", task_id).single().execute()
+    if not task_res.data:
+        raise HTTPException(status_code=404, detail="Task not found")
+    _assert_task_project_is_mutable(task_res.data)
+    _assert_task_quality(task_res.data)
+    task = update_task_status(task_id, "done")
+    
+    # Index for Long-Term Memory
+    background_tasks.add_task(memory_service.index_task_output, task)
+    
+    await audit_service.log_action(
+        user_id=None,
+        action="task_approved",
+        agent_id=task.get("assigned_agent_id"),
+        task_id=task_id,
+        metadata={"project_id": task.get("project_id")},
+    )
+    return {"message": "Task approved", "task": task}
+
+@router.post("/{task_id}/reject")
+async def reject_task(task_id: str, background_tasks: BackgroundTasks, feedback: str | None = None):
+    task = update_task_status(task_id, "todo")
+    
+    # Trigger Self-Optimization Loop
+    background_tasks.add_task(
+        memory_service.analyze_rejection, 
+        task_id=task_id, 
+        feedback=feedback
+    )
+    
+    await audit_service.log_action(
+        user_id=None,
+        action="task_rejected",
+        agent_id=task.get("assigned_agent_id"),
+        task_id=task_id,
+        metadata={"project_id": task.get("project_id")},
+    )
+    return {"message": "Task rejected", "task": task}
+
+@router.post("/project/{project_id}/approve-all")
+async def approve_all_tasks(project_id: str, background_tasks: BackgroundTasks):
+    """
+    Approves all tasks in a project that are awaiting approval.
+    """
+    project_service.ensure_project_is_mutable(project_id)
+    waiting_tasks = (
+        supabase.table("tasks")
+        .select("*")
+        .eq("project_id", project_id)
+        .eq("status", "awaiting_approval")
+        .execute()
+        .data
+        or []
+    )
+    
+    blocked = []
+    approvable_ids = []
+    
+    for task in waiting_tasks:
+        try:
+            _assert_task_quality(task)
+            approvable_ids.append(task["id"])
+        except HTTPException as exc:
+            blocked.append({
+                "task_id": task["id"],
+                "title": task.get("title", "Untitled Task"),
+                "reason": exc.detail
+            })
+
+    # 1. Update tasks
+    result_data = []
+    if approvable_ids:
+        result = (
+            supabase.table("tasks")
+            .update({"status": "done"})
+            .eq("project_id", project_id)
+            .in_("id", approvable_ids)
+            .execute()
+        )
+        result_data = result.data or []
+        
+        # Index all approved tasks for Long-Term Memory
+        for approved_task in result_data:
+            background_tasks.add_task(memory_service.index_task_output, approved_task)
+    
+    # 2. Check if all tasks in project are now done
+    task_result = (
+        supabase.table("tasks")
+        .select("status")
+        .eq("project_id", project_id)
+        .execute()
+    )
+    tasks = task_result.data or []
+    if tasks and all(t.get("status") == "done" for t in tasks):
+        supabase.table("projects").update({"status": "completed"}).eq("id", project_id).execute()
+
+    await audit_service.log_action(
+        user_id=None,
+        action="tasks_approved_bulk",
+        metadata={
+            "project_id": project_id,
+            "approved_count": len(result_data),
+            "blocked_count": len(blocked),
+        },
+    )
+    
+    return {
+        "message": f"Approved {len(result_data)} tasks. {len(blocked)} tasks were blocked due to quality issues.",
+        "count": len(result_data),
+        "blocked": blocked
+    }

backend/routers/generator.py

@@ -0,0 +1,109 @@
+from fastapi import APIRouter, UploadFile, File, Form, HTTPException
+from typing import List, Optional
+import json
+import logging
+import groq
+from services.supabase_service import supabase
+from services.config import settings, config_service
+from pydantic import BaseModel
+
+router = APIRouter()
+logger = logging.getLogger("aubm.generator")
+
+def _parse_json_output(content: str):
+    """Robust JSON parsing from LLM output."""
+    if not content:
+        return {}
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        pass
+    try:
+        if "```json" in content:
+            clean = content.split("```json", 1)[1].split("```", 1)[0].strip()
+        elif "```" in content:
+            clean = content.split("```", 1)[1].split("```", 1)[0].strip()
+        else:
+            object_start = content.find("{")
+            end = content.rfind("}")
+            clean = content[object_start:end + 1] if object_start != -1 and end != -1 else content
+        return json.loads(clean)
+    except Exception:
+        return {"name": "Generation Failed", "description": content, "context": ""}
+
+@router.post("/generate-project")
+async def generate_project(
+    prompt: str = Form(...),
+    files: List[UploadFile] = File(None)
+):
+    """
+    Generates a project structure from a natural language prompt and reference files.
+    """
+    logger.info("Generating project structure for prompt: %s", prompt[:50])
+    
+    # 1. Extract context from files
+    file_contexts = []
+    if files:
+        for file in files:
+            content = await file.read()
+            try:
+                text = content.decode("utf-8")
+                file_contexts.append(f"File: {file.filename}\nContent:\n{text}")
+            except Exception as e:
+                logger.warning("Could not decode file %s: %s", file.filename, e)
+
+    full_context = "\n\n".join(file_contexts)
+    
+    # 2. Prepare LLM prompt
+    system_prompt = """
+    You are an expert Project Architect for the Aubm platform.
+    Your goal is to take a user prompt and reference documents to create a structured project definition.
+    
+    Return ONLY a valid JSON object with the following keys:
+    {
+      "name": "Short Professional Name",
+      "description": "High level summary",
+      "context": "Detailed constraints, objectives, and requirements extracted from docs.",
+      "sources": [{"kind": "note", "label": "Analysis Note", "content": "..."}]
+    }
+    """
+    
+    user_message = f"User Prompt: {prompt}\n\nReference Context:\n{full_context}"
+    
+    try:
+        # 3. Call Groq
+        provider_config = config_service.get_provider_config("groq")
+        api_key = provider_config.get("api_key") or settings.GROQ_API_KEY
+        
+        if not api_key:
+            logger.error("GROQ_API_KEY is missing in settings and config")
+            raise HTTPException(status_code=500, detail="GROQ_API_KEY not configured")
+
+        client = groq.AsyncGroq(api_key=api_key)
+        
+        # Use llama-3.3-70b-versatile to match GroqAgent.py
+        model_name = provider_config.get("default_model") or "llama-3.3-70b-versatile"
+        logger.info("Calling Groq with model: %s (Key: %s...)", model_name, api_key[:8] if api_key else "None")
+
+        response = await client.chat.completions.create(
+            model=model_name,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_message}
+            ],
+            temperature=0.3,
+            max_tokens=2048
+        )
+        
+        response_text = response.choices[0].message.content
+        logger.info("Groq raw response received (%d chars)", len(response_text) if response_text else 0)
+        data = _parse_json_output(response_text)
+        return data
+        
+    except Exception as e:
+        logger.exception("Project generation failed")
+        error_type = type(e).__name__
+        error_msg = str(e)
+        if "401" in error_msg:
+            error_msg = "Invalid API Key - Please check your Groq Dashboard and .env"
+        raise HTTPException(status_code=500, detail=f"AI Error ({error_type}): {error_msg}")

backend/routers/monitoring.py

@@ -0,0 +1,121 @@
+from datetime import datetime, timedelta, timezone
+from fastapi import APIRouter
+from services.supabase_service import supabase
+
+router = APIRouter()
+
+
+def _count_table(table_name: str) -> int:
+    response = supabase.table(table_name).select("id", count="exact").limit(1).execute()
+    return response.count or 0
+
+
+def _count_tasks_by_status(status: str) -> int:
+    return (
+        supabase.table("tasks")
+        .select("id", count="exact")
+        .eq("status", status)
+        .limit(1)
+        .execute()
+        .count
+        or 0
+    )
+
+
+@router.get("/summary")
+async def monitoring_summary():
+    """
+    Lightweight operational summary for dashboards and uptime checks.
+    """
+    checks = {
+        "api": "ok",
+        "database": "ok",
+        "workers": "checking",
+    }
+
+    counts = {
+        "projects": 0,
+        "tasks": 0,
+        "agents": 0,
+        "task_runs": 0,
+        "failed_tasks": 0,
+        "pending_reviews": 0,
+        "queued_tasks": 0,
+        "in_progress_tasks": 0,
+        "stale_leases": 0,
+        "delayed_retries": 0,
+        "active_workers": 0,
+    }
+
+    try:
+        counts["projects"] = _count_table("projects")
+        counts["tasks"] = _count_table("tasks")
+        counts["agents"] = _count_table("agents")
+        counts["task_runs"] = _count_table("task_runs")
+        counts["failed_tasks"] = _count_tasks_by_status("failed")
+        counts["pending_reviews"] = _count_tasks_by_status("awaiting_approval")
+        counts["queued_tasks"] = _count_tasks_by_status("queued")
+        counts["in_progress_tasks"] = _count_tasks_by_status("in_progress")
+
+        now = datetime.now(timezone.utc)
+        counts["stale_leases"] = (
+            supabase.table("tasks")
+            .select("id", count="exact")
+            .eq("status", "in_progress")
+            .lt("lease_expires_at", now.isoformat())
+            .limit(1)
+            .execute()
+            .count
+            or 0
+        )
+        counts["delayed_retries"] = (
+            supabase.table("tasks")
+            .select("id", count="exact")
+            .eq("status", "queued")
+            .gt("next_attempt_at", now.isoformat())
+            .limit(1)
+            .execute()
+            .count
+            or 0
+        )
+
+        try:
+            active_since = now - timedelta(minutes=2)
+            counts["active_workers"] = (
+                supabase.table("worker_heartbeats")
+                .select("worker_id", count="exact")
+                .gte("last_seen_at", active_since.isoformat())
+                .neq("status", "stopping")
+                .limit(1)
+                .execute()
+                .count
+                or 0
+            )
+            checks["workers"] = "ok" if counts["active_workers"] > 0 or counts["queued_tasks"] == 0 else "warning"
+        except Exception as exc:
+            checks["workers"] = "unavailable"
+            counts["active_workers"] = 0
+            worker_error = str(exc)
+        else:
+            worker_error = None
+    except Exception as exc:
+        checks["database"] = "error"
+        return {
+            "status": "degraded",
+            "checks": checks,
+            "counts": counts,
+            "error": str(exc),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+
+    error = None
+    if worker_error:
+        error = f"Worker heartbeat table unavailable: {worker_error}"
+
+    return {
+        "status": "ok" if checks["workers"] in ("ok", "unavailable") and counts["stale_leases"] == 0 else "degraded",
+        "checks": checks,
+        "counts": counts,
+        "error": error,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }

backend/routers/orchestrator.py

@@ -0,0 +1,233 @@
+import asyncio
+import logging
+from fastapi import APIRouter, BackgroundTasks, HTTPException
+from fastapi.responses import Response
+from services.orchestrator_service import orchestrator_service
+from services.supabase_service import supabase
+from services.config import settings
+from services.budget_service import budget_service
+from services.evidence_service import evidence_service
+from services.project_service import project_service
+from services.utils import log_async_task_result
+from pydantic import BaseModel
+from io import BytesIO
+from reportlab.lib.pagesizes import letter
+from reportlab.lib.styles import getSampleStyleSheet
+from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, Table, TableStyle
+from reportlab.lib import colors
+from reportlab.lib.units import inch
+from xml.sax.saxutils import escape
+import re
+
+router = APIRouter()
+logger = logging.getLogger("uvicorn")
+
+
+
+
+def _safe_filename(value: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9_-]+", "_", value).strip("_").lower() or "report"
+
+def _pdf_text(value: str) -> str:
+    return escape(str(value))
+
+def _report_body_without_execution_summary(content: str) -> list[str]:
+    lines: list[str] = []
+    skipping = False
+    for raw_line in content.splitlines():
+        if raw_line.startswith("## Execution Summary"):
+            skipping = True
+            continue
+        if skipping and raw_line.startswith("## "):
+            skipping = False
+        if not skipping:
+            lines.append(raw_line)
+    return lines
+
+def _report_pdf_bytes(title: str, content: str, charts: dict | None = None) -> bytes:
+    buffer = BytesIO()
+    doc = SimpleDocTemplate(
+        buffer,
+        pagesize=letter,
+        rightMargin=0.7 * inch,
+        leftMargin=0.7 * inch,
+        topMargin=0.7 * inch,
+        bottomMargin=0.7 * inch,
+    )
+    styles = getSampleStyleSheet()
+    story = [Paragraph(_pdf_text(title), styles["Title"]), Spacer(1, 0.2 * inch)]
+    if charts:
+        story.append(Paragraph("Project Execution Summary", styles["Heading2"]))
+        story.append(Spacer(1, 0.1 * inch))
+        
+        # Summary Table instead of charts
+        table_data = [["Metric / Category", "Value"]]
+        
+        # Tasks Status
+        status_counts = {row["label"]: row["value"] for row in charts.get("status", [])}
+        for label, val in status_counts.items():
+            table_data.append([f"Tasks: {label}", str(val)])
+            
+        # Categories
+        for cat in charts.get("categories", []):
+            table_data.append([f"Type: {cat['label']}", str(cat["value"])])
+
+        # Priorities
+        for priority in charts.get("priorities", []):
+            table_data.append([priority["label"], str(priority["value"])])
+
+        # Scores
+        for score in charts.get("scores", []):
+            table_data.append([f"Score: {score['label']}", str(score["value"])])
+
+        table = Table(table_data, colWidths=[3.5*inch, 1.5*inch])
+        table.setStyle(TableStyle([
+            ('BACKGROUND', (0,0), (-1,0), colors.HexColor("#6e59ff")),
+            ('TEXTCOLOR', (0,0), (-1,0), colors.whitesmoke),
+            ('ALIGN', (0,0), (-1,-1), 'LEFT'),
+            ('FONTNAME', (0,0), (-1,0), 'Helvetica-Bold'),
+            ('BOTTOMPADDING', (0,0), (-1,0), 10),
+            ('BACKGROUND', (0,1), (-1,-1), colors.HexColor("#f8fafc")),
+            ('GRID', (0,0), (-1,-1), 0.5, colors.grey),
+            ('FONTSIZE', (0,0), (-1,-1), 9),
+        ]))
+        story.append(table)
+        story.append(Spacer(1, 0.3 * inch))
+
+    for raw_line in _report_body_without_execution_summary(content):
+        line = raw_line.strip()
+        if not line:
+            story.append(Spacer(1, 0.1 * inch))
+            continue
+        if line.startswith("# "):
+            story.append(Paragraph(_pdf_text(line[2:]), styles["Title"]))
+        elif line.startswith("## "):
+            story.append(Paragraph(_pdf_text(line[3:]), styles["Heading2"]))
+        elif line.startswith("### "):
+            story.append(Paragraph(_pdf_text(line[4:]), styles["Heading3"]))
+        elif line.startswith("- "):
+            story.append(Paragraph(f"• {_pdf_text(line[2:])}", styles["BodyText"]))
+        else:
+            story.append(Paragraph(_pdf_text(line), styles["BodyText"]))
+
+    doc.build(story)
+    return buffer.getvalue()
+
+class DebateRequest(BaseModel):
+
+    task_id: str
+    agent_a_id: str
+    agent_b_id: str
+
+
+class ProjectBudgetRequest(BaseModel):
+    enabled: bool = True
+    token_budget: int | None = None
+    cost_budget: float | None = None
+    currency: str = "USD"
+
+@router.post("/debate")
+async def start_debate(request: DebateRequest, background_tasks: BackgroundTasks):
+    """
+    Starts a debate between two agents for a specific task.
+    """
+    background_tasks.add_task(
+        orchestrator_service.run_debate, 
+        request.task_id, 
+        request.agent_a_id, 
+        request.agent_b_id
+    )
+    return {"message": "Debate started in background"}
+
+
+@router.post("/projects/{project_id}/run")
+async def run_project_orchestrator(project_id: str, background_tasks: BackgroundTasks, use_queue: bool | None = None):
+    """
+    Runs all queued tasks for a project in priority order.
+    """
+    project_service.ensure_project_is_mutable(project_id)
+    should_queue = use_queue if use_queue is not None else False
+    if should_queue:
+        try:
+            result = await orchestrator_service.queue_project(project_id)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        return {"message": "Project tasks queued for worker execution", **result}
+
+    task = asyncio.create_task(orchestrator_service.run_project(project_id))
+    task.add_done_callback(lambda current: log_async_task_result(current, f"run_project({project_id})"))
+    return {"message": "Project orchestrator started", "project_id": project_id, "mode": "direct"}
+
+@router.get("/projects/{project_id}/final-report")
+async def get_project_final_report(project_id: str, variant: str = "full"):
+    """
+    Builds a consolidated report from all approved task outputs.
+    """
+    try:
+        return await orchestrator_service.build_final_report(project_id, variant)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@router.get("/projects/{project_id}/evidence")
+async def get_project_evidence(project_id: str, merge: bool = False):
+    """
+    Returns normalized claims extracted from structured task outputs.
+    Can optionally merge semantically similar claims.
+    """
+    project = supabase.table("projects").select("id").eq("id", project_id).single().execute().data
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    if merge:
+        claims = await evidence_service.merge_project_claims(project_id)
+    else:
+        claims = evidence_service.load_project_claims(project_id)
+        
+    return {
+        "project_id": project_id,
+        "merged": merge,
+        "summary": evidence_service.summarize_claims(claims),
+        "claims": claims,
+    }
+
+
+@router.get("/projects/{project_id}/budget")
+async def get_project_budget(project_id: str):
+    project_service.get_project_or_404(project_id)
+    return budget_service.project_budget_status(project_id)
+
+
+@router.put("/projects/{project_id}/budget")
+async def update_project_budget(project_id: str, request: ProjectBudgetRequest):
+    project = supabase.table("projects").select("id").eq("id", project_id).single().execute().data
+    if not project:
+        raise HTTPException(status_code=404, detail="Project not found")
+    budget_service.upsert_project_budget(
+        project_id=project_id,
+        enabled=request.enabled,
+        token_budget=request.token_budget,
+        cost_budget=request.cost_budget,
+        currency=request.currency,
+    )
+    return budget_service.project_budget_status(project_id)
+
+
+@router.get("/projects/{project_id}/final-report.pdf")
+async def download_project_final_report_pdf(project_id: str, variant: str = "full"):
+    """
+    Downloads the selected report variant as a PDF.
+    """
+    try:
+        result = await orchestrator_service.build_final_report(project_id, variant)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    title = f"{result['project_name']} - {result['variant']} report"
+    pdf = _report_pdf_bytes(title, result["report"], result.get("charts"))
+    filename = f"{_safe_filename(result['project_name'])}_{_safe_filename(result['variant'])}.pdf"
+    return Response(
+        content=pdf,
+        media_type="application/pdf",
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'}
+    )

backend/scratch/check_db.py

@@ -0,0 +1,22 @@
+import os
+from supabase import create_client
+from dotenv import load_dotenv
+
+load_dotenv()
+
+supabase_url = os.getenv("SUPABASE_URL")
+supabase_key = os.getenv("SUPABASE_SERVICE_ROLE_KEY")
+supabase = create_client(supabase_url, supabase_key)
+
+def check_logs():
+    try:
+        res = supabase.table("agent_logs").select("*").order("created_at", desc=True).limit(20).execute()
+        print(f"Total logs retrieved: {len(res.data)}")
+        for log in res.data:
+            print(f"[{log['created_at']}] {log['action']}: {log['content'][:50]}...")
+            
+    except Exception as e:
+        print(f"Error accessing agent_logs: {e}")
+
+if __name__ == "__main__":
+    check_logs()

backend/scratch/create_comparison_project.py

@@ -0,0 +1,168 @@
+import os
+from supabase import create_client
+from dotenv import load_dotenv
+
+load_dotenv()
+
+supabase_url = os.getenv("SUPABASE_URL")
+supabase_key = os.getenv("SUPABASE_SERVICE_ROLE_KEY")
+supabase = create_client(supabase_url, supabase_key)
+
+EXAMPLE_PROJECTS = [
+    {
+        "project": {
+            "name": "Aubm Competitor Analysis",
+            "description": "Deep dive into the multi-agent orchestration market to identify Aubm's unique value proposition and feature gaps.",
+            "status": "active",
+            "context": "Focus on developer experience, visual observability, and the 'Agent Debate' mechanism as key differentiators."
+        },
+        "tasks": [
+            {"title": "Identify Top 5 Competitors", "description": "Research and list 5 similar multi-agent orchestration platforms (e.g., CrewAI, AutoGen, LangGraph, PydanticAI).", "status": "todo"},
+            {"title": "Feature Comparison Matrix", "description": "Create a detailed matrix comparing Aubm's core features (Project Decomposition, Agent Debate, Real-time Console) against identified competitors.", "status": "todo"},
+            {"title": "Pricing Model Analysis", "description": "Analyze how competitors charge (SaaS, Open Source, API usage) and recommend a competitive strategy for Aubm.", "status": "todo"},
+            {"title": "UI/UX Aesthetic Audit", "description": "Evaluate the visual aesthetics and ease of use of competitors compared to Aubm's premium dashboard. Look for glassmorphism and animations.", "status": "todo"},
+            {"title": "Technical Architecture Deep-Dive", "description": "Investigate the underlying tech stacks (Python vs TS, Vector DBs used, Orchestration logic) of top competitors.", "status": "todo"},
+            {"title": "SWOT Analysis & Strategy Report", "description": "Compile all findings into a comprehensive report with a SWOT analysis and strategic recommendations for the next 6 months.", "status": "todo"}
+        ]
+    },
+    {
+        "project": {
+            "name": "AI Support Automation Pilot",
+            "description": "Design a pilot that routes inbound support tickets through specialized AI agents while keeping human approval for risky replies.",
+            "status": "active",
+            "context": "Use this as a customer operations example. Emphasize ticket triage, escalation policies, response quality, and measurable SLA impact."
+        },
+        "tasks": [
+            {"title": "Map Support Ticket Categories", "description": "Identify the main ticket categories, escalation triggers, and data needed by each support agent role.", "status": "todo", "priority": 5},
+            {"title": "Define Human Approval Rules", "description": "Specify which replies can be automated and which require human review based on customer risk and account tier.", "status": "todo", "priority": 4},
+            {"title": "Design Agent Workflow", "description": "Create a multi-agent workflow for triage, answer drafting, policy checking, and final approval.", "status": "todo", "priority": 4},
+            {"title": "Create Pilot Success Metrics", "description": "Define SLA, CSAT, deflection, review time, and error-rate metrics for a 30-day pilot.", "status": "todo", "priority": 3},
+            {"title": "Draft Rollout Plan", "description": "Prepare a phased rollout plan with risks, staffing requirements, and customer communication steps.", "status": "todo", "priority": 3}
+        ]
+    },
+    {
+        "project": {
+            "name": "FinOps Cloud Cost Review",
+            "description": "Analyze cloud infrastructure spend and propose agent-assisted monitoring workflows to reduce waste without hurting reliability.",
+            "status": "active",
+            "context": "Use this as an operations and finance example. Focus on anomaly detection, rightsizing, reserved capacity, and stakeholder reporting."
+        },
+        "tasks": [
+            {"title": "Inventory Cost Drivers", "description": "Break down the main cloud cost drivers across compute, storage, networking, databases, and third-party services.", "status": "todo", "priority": 5},
+            {"title": "Identify Waste Patterns", "description": "Find common waste patterns such as idle resources, oversized instances, orphaned volumes, and expensive data transfer paths.", "status": "todo", "priority": 5},
+            {"title": "Design Alerting Workflow", "description": "Create an agent workflow that detects spend anomalies, explains likely causes, and proposes owner-specific actions.", "status": "todo", "priority": 4},
+            {"title": "Build Savings Roadmap", "description": "Prioritize savings opportunities by expected impact, risk, engineering effort, and time to value.", "status": "todo", "priority": 4},
+            {"title": "Prepare Executive Summary", "description": "Summarize recommended actions, estimated savings ranges, risks, and governance changes for leadership.", "status": "todo", "priority": 3}
+        ]
+    },
+    {
+        "project": {
+            "name": "Healthcare Intake Risk Triage",
+            "description": "Prototype an AI-assisted intake workflow that summarizes patient requests, flags urgency, and routes cases to the correct care team.",
+            "status": "active",
+            "context": "Use this as a regulated-industry example. Emphasize auditability, privacy, safety checks, and clear human-in-the-loop boundaries."
+        },
+        "tasks": [
+            {"title": "Define Intake Data Requirements", "description": "List required patient request fields, optional context, privacy constraints, and data that must never be generated by the system.", "status": "todo", "priority": 5},
+            {"title": "Specify Risk Triage Rules", "description": "Define urgency categories, red-flag symptoms, routing criteria, and cases that must bypass automation.", "status": "todo", "priority": 5},
+            {"title": "Design Audit Trail", "description": "Create an auditable record structure for summaries, agent reasoning, routing decisions, reviewer overrides, and timestamps.", "status": "todo", "priority": 4},
+            {"title": "Review Compliance Risks", "description": "Identify privacy, consent, medical safety, bias, and operational risks with mitigation recommendations.", "status": "todo", "priority": 4},
+            {"title": "Create Pilot Validation Plan", "description": "Define how clinicians will evaluate accuracy, escalation safety, workload impact, and patient experience before rollout.", "status": "todo", "priority": 3}
+        ]
+    },
+    {
+        "project": {
+            "name": "Legal Contract Review Automation",
+            "description": "Create an agent-assisted workflow that reviews vendor contracts, flags risky clauses, and prepares negotiation notes for legal approval.",
+            "status": "active",
+            "context": "Use this as a legal operations example. Focus on contract risk, clause extraction, redlines, escalation thresholds, and attorney review."
+        },
+        "tasks": [
+            {"title": "Define Contract Review Scope", "description": "Identify contract types, clause families, review boundaries, and documents that must always be escalated to counsel.", "status": "todo", "priority": 5},
+            {"title": "Build Clause Risk Taxonomy", "description": "Classify indemnity, limitation of liability, termination, data protection, payment, jurisdiction, and renewal risks.", "status": "todo", "priority": 5},
+            {"title": "Design Legal Review Workflow", "description": "Create a multi-agent workflow for clause extraction, risk scoring, fallback research, negotiation notes, and final attorney approval.", "status": "todo", "priority": 4},
+            {"title": "Draft Approval Checklist", "description": "Prepare a checklist for legal reviewers covering unacceptable terms, missing clauses, confidence levels, and required evidence.", "status": "todo", "priority": 4},
+            {"title": "Prepare Pilot Metrics", "description": "Define cycle time, review accuracy, escalation rate, reviewer override rate, and business stakeholder satisfaction metrics.", "status": "todo", "priority": 3}
+        ]
+    },
+    {
+        "project": {
+            "name": "Regulatory Compliance Monitoring",
+            "description": "Design a legal monitoring workflow that tracks regulatory changes, summarizes business impact, and routes obligations to owners.",
+            "status": "active",
+            "context": "Use this as a compliance example. Emphasize source traceability, jurisdiction filters, obligation mapping, audit logs, and risk-based prioritization."
+        },
+        "tasks": [
+            {"title": "Map Regulatory Sources", "description": "List official regulators, legal update feeds, jurisdictions, business units, and source reliability rules.", "status": "todo", "priority": 5},
+            {"title": "Define Obligation Categories", "description": "Create categories for reporting, privacy, security, employment, financial controls, retention, and customer disclosure obligations.", "status": "todo", "priority": 5},
+            {"title": "Design Change Detection Workflow", "description": "Create an agent workflow that detects changes, summarizes impact, links evidence, and assigns obligations to owners.", "status": "todo", "priority": 4},
+            {"title": "Create Audit Evidence Model", "description": "Specify how the system stores source URLs, timestamps, summaries, reviewer decisions, owner acknowledgements, and completion proof.", "status": "todo", "priority": 4},
+            {"title": "Prioritize Compliance Rollout", "description": "Rank jurisdictions and obligation types by legal exposure, operational complexity, and implementation effort.", "status": "todo", "priority": 3}
+        ]
+    },
+    {
+        "project": {
+            "name": "Litigation Discovery Triage",
+            "description": "Prototype an AI-assisted discovery workflow that groups documents, identifies privilege risks, and prepares review batches for legal teams.",
+            "status": "active",
+            "context": "Use this as a litigation support example. Focus on defensibility, privilege review, chain of custody, reviewer queues, and evidence traceability."
+        },
+        "tasks": [
+            {"title": "Define Discovery Data Inputs", "description": "Identify document sources, metadata fields, custodians, date ranges, file types, and chain-of-custody requirements.", "status": "todo", "priority": 5},
+            {"title": "Specify Privilege Screening Rules", "description": "Define attorney-client, work product, confidentiality, and sensitive data indicators that require legal review.", "status": "todo", "priority": 5},
+            {"title": "Design Review Batch Workflow", "description": "Create an agent workflow for deduplication, clustering, privilege flagging, relevance summaries, and reviewer queue assignment.", "status": "todo", "priority": 4},
+            {"title": "Create Defensibility Controls", "description": "Specify audit logs, reviewer overrides, confidence thresholds, sampled quality checks, and exportable decision records.", "status": "todo", "priority": 4},
+            {"title": "Prepare Discovery Summary Report", "description": "Draft the report structure for document volumes, risk categories, review progress, escalations, and unresolved issues.", "status": "todo", "priority": 3}
+        ]
+    }
+]
+
+def resolve_owner_id():
+    existing_projects = supabase.table("projects").select("owner_id").limit(1).execute()
+    if existing_projects.data and existing_projects.data[0].get("owner_id"):
+        return existing_projects.data[0]["owner_id"]
+
+    users = supabase.table("profiles").select("id").limit(1).execute()
+    if users.data:
+        return users.data[0]["id"]
+
+    return None
+
+def create_project(project_data, tasks, owner_id):
+    existing = (
+        supabase.table("projects")
+        .select("id")
+        .eq("name", project_data["name"])
+        .limit(1)
+        .execute()
+    )
+    if existing.data:
+        print(f"Skipping existing project: {project_data['name']}")
+        return
+
+    payload = project_data.copy()
+    if owner_id:
+        payload["owner_id"] = owner_id
+
+    project_res = supabase.table("projects").insert(payload).execute()
+    project_id = project_res.data[0]["id"]
+    task_rows = [{**task, "project_id": project_id} for task in tasks]
+    supabase.table("tasks").insert(task_rows).execute()
+    print(f"Created project: {project_data['name']} ({len(task_rows)} tasks)")
+
+def create_projects():
+    try:
+        owner_id = resolve_owner_id()
+        if not owner_id:
+            print("No valid owner_id found in projects or profiles. The project will be created without owner and might not be visible.")
+        else:
+            print(f"Using owner_id: {owner_id}")
+
+        for example in EXAMPLE_PROJECTS:
+            create_project(example["project"], example["tasks"], owner_id)
+
+    except Exception as e:
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    create_projects()

backend/scratch/find_user.py

@@ -0,0 +1,24 @@
+import os
+from supabase import create_client
+from dotenv import load_dotenv
+
+load_dotenv()
+
+supabase_url = os.getenv("SUPABASE_URL")
+supabase_key = os.getenv("SUPABASE_SERVICE_ROLE_KEY")
+supabase = create_client(supabase_url, supabase_key)
+
+def check_users():
+    # Try different tables where users might be
+    tables = ["profiles", "users", "team_members"]
+    for table in tables:
+        try:
+            res = supabase.table(table).select("id").limit(1).execute()
+            print(f"Table {table} count: {len(res.data)}")
+            if res.data:
+                print(f"Sample ID: {res.data[0]['id']}")
+        except Exception as e:
+            print(f"Error checking {table}: {e}")
+
+if __name__ == "__main__":
+    check_users()

backend/scratch/fix_logs_rls.py

@@ -0,0 +1,33 @@
+import os
+from supabase import create_client
+from dotenv import load_dotenv
+
+load_dotenv()
+
+supabase_url = os.getenv("SUPABASE_URL")
+supabase_key = os.getenv("SUPABASE_SERVICE_ROLE_KEY")
+supabase = create_client(supabase_url, supabase_key)
+
+sql = """
+ALTER TABLE agent_logs ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS "Enable read access for all users" ON agent_logs;
+CREATE POLICY "Enable read access for all users" ON agent_logs FOR SELECT USING (true);
+"""
+
+# Note: This assumes an 'exec_sql' RPC exists, which is common in many setups.
+# If not, I'll have to find another way.
+try:
+    # Actually, let's try a different approach if RPC fails.
+    # We can try to use the REST API to check if it works.
+    print("Attempting to set RLS policy...")
+    # Since I don't have direct SQL access via the client without RPC, 
+    # I'll assume the user might need to do this in the dashboard or I'll try to find an RPC.
+    
+    # Let's check if the client can read with anon key.
+    anon_key = os.getenv("SUPABASE_ANON_KEY")
+    anon_s = create_client(supabase_url, anon_key)
+    res = anon_s.table("agent_logs").select("*").limit(1).execute()
+    print(f"Anon read test: {'Success' if not res.data else 'Empty/Restricted'}")
+    
+except Exception as e:
+    print(f"Error: {e}")

backend/services/agent_runner_service.py

@@ -0,0 +1,399 @@
+import logging
+from datetime import datetime, timezone
+from services.supabase_service import supabase
+from services.audit_service import audit_service
+from services.budget_service import BudgetExceededError, budget_service
+from services.evidence_service import evidence_service
+from agents.agent_factory import AgentFactory
+from services.semantic_backprop import semantic_backprop
+from services.output_quality import build_quality_instructions, validate_output
+from services.memory_service import memory_service
+
+logger = logging.getLogger("agent_runner_service")
+
+def _update_task_run(run_id: str, payload: dict):
+    try:
+        return supabase.table("task_runs").update(payload).eq("id", run_id).execute()
+    except Exception as exc:
+        if "duration_seconds" in payload and "duration_seconds" in str(exc) and "schema cache" in str(exc):
+            fallback_payload = {key: value for key, value in payload.items() if key != "duration_seconds"}
+            logger.warning("task_runs.duration_seconds is missing in Supabase schema; retrying run update without duration.")
+            return supabase.table("task_runs").update(fallback_payload).eq("id", run_id).execute()
+        raise
+
+class AgentRunnerService:
+    @staticmethod
+    async def run_agent_task(
+        task: dict,
+        agent_data: dict,
+        *,
+        include_semantic_context: bool = False,
+        start_action: str = "execution_start",
+        start_content: str | None = None,
+        complete_action: str = "execution_complete",
+        complete_content: str = "Agent successfully completed the task and produced output.",
+        update_task: bool = True
+    ) -> tuple[dict, str]:
+        task_id = task["id"]
+        project_id = task["project_id"]
+        run_id = None
+
+        if update_task:
+            supabase.table("tasks").update({"status": "in_progress"}).eq("id", task_id).execute()
+            await audit_service.log_action(
+                user_id=None,
+                action="task_status_changed",
+                agent_id=agent_data.get("id"),
+                task_id=task_id,
+                metadata={"project_id": project_id, "status": "in_progress"},
+            )
+
+        try:
+            run_res = supabase.table("task_runs").insert({
+                "task_id": task_id,
+                "agent_id": agent_data["id"],
+                "status": "running"
+            }).execute()
+            run_id = run_res.data[0]["id"]
+            await audit_service.log_action(
+                user_id=None,
+                action="task_run_created",
+                agent_id=agent_data.get("id"),
+                task_id=task_id,
+                metadata={"project_id": project_id, "run_id": run_id, "status": "running"},
+            )
+
+            # Emergency Model Override for decommissioned Groq models
+            model_to_use = agent_data["model"]
+            if "llama3-70b-8192" in model_to_use:
+                model_to_use = "llama-3.3-70b-versatile"
+                logger.warning(f"Overriding decommissioned model {agent_data['model']} with {model_to_use}")
+
+            agent = AgentFactory.get_agent(
+                provider=agent_data["api_provider"],
+                name=agent_data["name"],
+                role=agent_data["role"],
+                model=model_to_use,
+                system_prompt=agent_data.get("system_prompt")
+            )
+
+            context_res = supabase.table("tasks").select("title, output_data") \
+                .eq("project_id", project_id) \
+                .eq("status", "done") \
+                .execute()
+            context = context_res.data if context_res.data else []
+
+            project_data = task.get("project")
+            if not isinstance(project_data, dict):
+                project_res = (
+                    supabase.table("projects")
+                    .select("name,description,context")
+                    .eq("id", project_id)
+                    .single()
+                    .execute()
+                )
+                project_data = project_res.data if project_res and project_res.data else {}
+            quality_task = {**task, "project": project_data}
+
+            extra_context = ""
+            if include_semantic_context:
+                extra_context = await semantic_backprop.get_project_context(project_id, task_id)
+                # Fetch Long-Term Memory (Cross-project)
+                memories = await memory_service.search_memory(
+                    query=task.get("description") or task["title"],
+                    limit=3,
+                    threshold=0.72
+                )
+                if memories:
+                    memory_header = "\n\n### RELEVANT HISTORICAL CONTEXT (CROSS-PROJECT)\n"
+                    memory_blocks = []
+                    for m in memories:
+                        memory_blocks.append(f"- Memory: {m['content']}")
+                    extra_context += memory_header + "\n".join(memory_blocks)
+                
+                # Fetch Self-Optimization Lessons for this specific task
+                lessons_res = supabase.table("project_memory") \
+                    .select("content") \
+                    .eq("task_id", task_id) \
+                    .eq("memory_type", "self_optimization_lesson") \
+                    .order("created_at", desc=True) \
+                    .limit(1) \
+                    .execute()
+                
+                if lessons_res.data:
+                    lesson = lessons_res.data[0]["content"]
+                    extra_context += f"\n\n### CRITICAL LESSON FROM PREVIOUS ATTEMPT\n{lesson}\n"
+
+            import time
+            import hashlib
+            
+            # Simple in-memory cache for the session (could be persistent later)
+            if not hasattr(AgentRunnerService, "_task_cache"):
+                AgentRunnerService._task_cache = {}
+
+            # 1. Create a cache key based on task, agent (model + system prompt), and context
+            cache_input = f"{task['id']}-{agent_data['model']}-{agent_data.get('system_prompt', '')}-{task.get('description')}-{str(context)}-{extra_context}"
+            cache_key = hashlib.md5(cache_input.encode()).hexdigest()
+            
+            # 2. Check Cache
+            if cache_key in AgentRunnerService._task_cache:
+                logger.info(f"Cache hit for task {task_id}. Skipping LLM call.")
+                cached_result = AgentRunnerService._task_cache[cache_key]
+                claims_count = await evidence_service.replace_task_claims(task, cached_result)
+                
+                # Still log the "start" for UI consistency
+                agent_name = agent_data.get('name', 'Agent')
+                log_msg = start_content or f"Agent {agent_name} resuming task"
+                supabase.table("agent_logs").insert({
+                    "task_id": task_id,
+                    "run_id": run_id,
+                    "action": start_action,
+                    "content": f"[CACHE HIT] {log_msg}"
+                }).execute()
+                
+                if update_task:
+                    supabase.table("tasks").update({
+                        "status": "awaiting_approval",
+                        "output_data": cached_result
+                    }).eq("id", task_id).execute()
+                    await audit_service.log_action(
+                        user_id=None,
+                        action="task_status_changed",
+                        agent_id=agent_data.get("id"),
+                        task_id=task_id,
+                        metadata={
+                            "project_id": project_id,
+                            "run_id": run_id,
+                            "status": "awaiting_approval",
+                            "cache_hit": True,
+                            "claims_count": claims_count,
+                        },
+                    )
+
+                _update_task_run(run_id, {
+                    "status": "completed",
+                    "finished_at": datetime.now(timezone.utc).isoformat()
+                })
+                
+                return cached_result, run_id
+
+            # 3. Log Start
+            supabase.table("agent_logs").insert({
+                "task_id": task_id,
+                "run_id": run_id,
+                "action": start_action,
+                "content": start_content or f"Agent {agent_data['name']} starting task: {task['title']}"
+            }).execute()
+
+            # 4. Execute Run with timing
+            start_time = time.time()
+            task_instructions = task.get("description") or task["title"]
+            task_instructions = f"{task_instructions}\n\n{build_quality_instructions(quality_task)}"
+            prompt_tokens = budget_service.estimate_prompt_tokens(
+                task_instructions=task_instructions,
+                context=context,
+                extra_context=extra_context,
+                system_prompt=agent_data.get("system_prompt"),
+            )
+            max_completion_tokens = int(getattr(agent, "max_tokens", 0) or 0)
+            estimated_preflight_cost = budget_service.estimate_cost(
+                agent_data.get("api_provider"),
+                agent_data.get("model"),
+                prompt_tokens,
+                max_completion_tokens,
+            )
+            budget_service.check_before_run(
+                project_id=project_id,
+                estimated_tokens=prompt_tokens + max_completion_tokens,
+                estimated_cost=estimated_preflight_cost,
+            )
+            result = await agent.run(task_instructions, context, extra_context=extra_context)
+            duration = time.time() - start_time
+
+            if result.get("status") == "error":
+                raise RuntimeError(result.get("error") or "Agent returned an error result.")
+
+            # 5. Security Sanitization (Defense in Depth)
+            raw_out = str(result.get("raw_output", ""))
+            suspicious_patterns = ["rm -rf", "mkfs", "dd if=", "curl", "wget", "chmod 777", "> /dev/sda"]
+            for pattern in suspicious_patterns:
+                if pattern in raw_out:
+                    logger.warning(f"SECURITY: Suspicious pattern '{pattern}' detected in agent output for task {task_id}.")
+                    result["security_warning"] = f"Output sanitized: suspicious pattern '{pattern}' detected."
+
+            quality_review = validate_output(quality_task, result)
+            result["quality_review"] = quality_review
+            claims_count = await evidence_service.replace_task_claims(task, result)
+            
+            # Use actual usage if provided by agent, otherwise fallback to estimation
+            usage = result.get("usage") or {}
+            actual_prompt_tokens = usage.get("prompt_tokens") or prompt_tokens
+            actual_completion_tokens = usage.get("completion_tokens") or budget_service.estimate_completion_tokens(result)
+            
+            actual_cost = budget_service.estimate_cost(
+                agent_data.get("api_provider"),
+                agent_data.get("model"),
+                actual_prompt_tokens,
+                actual_completion_tokens,
+            )
+            
+            budget_service.record_usage(
+                project_id=project_id,
+                task_id=task_id,
+                run_id=run_id,
+                agent_id=agent_data.get("id"),
+                provider=agent_data.get("api_provider"),
+                model=agent_data.get("model"),
+                prompt_tokens=actual_prompt_tokens,
+                completion_tokens=actual_completion_tokens,
+                estimated_cost=actual_cost,
+                metadata={"duration_seconds": round(duration, 2), "claims_count": claims_count, "usage_source": "api" if result.get("usage") else "estimation"},
+            )
+
+            # 6. Save to Cache
+            AgentRunnerService._task_cache[cache_key] = result
+
+            if update_task:
+                supabase.table("tasks").update({
+                    "status": "awaiting_approval",
+                    "output_data": result
+                }).eq("id", task_id).execute()
+                await audit_service.log_action(
+                    user_id=None,
+                    action="task_status_changed",
+                    agent_id=agent_data.get("id"),
+                    task_id=task_id,
+                    metadata={
+                        "project_id": project_id,
+                        "run_id": run_id,
+                        "status": "awaiting_approval",
+                        "quality_approved": quality_review["approved"],
+                        "claims_count": claims_count,
+                        "estimated_tokens": actual_prompt_tokens + actual_completion_tokens,
+                        "estimated_cost": float(actual_cost),
+                    },
+                )
+
+            # 7. Update Run Status
+            _update_task_run(run_id, {
+                "status": "completed",
+                "finished_at": datetime.now(timezone.utc).isoformat(),
+                "duration_seconds": round(duration, 2)
+            })
+
+            # 8. Log Completion with Metrics
+            supabase.table("agent_logs").insert({
+                "task_id": task_id,
+                "run_id": run_id,
+                "action": complete_action,
+                "content": f"{complete_content} (Execution time: {duration:.2f}s)"
+            }).execute()
+
+            if not quality_review["approved"]:
+                supabase.table("agent_logs").insert({
+                    "task_id": task_id,
+                    "run_id": run_id,
+                    "action": "quality_review_failed",
+                    "content": f"Quality review failed: {', '.join(quality_review['fail_reasons'])}"
+                }).execute()
+                await audit_service.log_action(
+                    user_id=None,
+                    action="task_quality_review_failed",
+                    agent_id=agent_data.get("id"),
+                    task_id=task_id,
+                    metadata={
+                        "project_id": project_id,
+                        "run_id": run_id,
+                        "fail_reasons": quality_review.get("fail_reasons", []),
+                    },
+                )
+
+            return result, run_id
+
+        except BudgetExceededError as e:
+            logger.warning(f"Budget blocked task {task_id}: {str(e)}")
+            if run_id:
+                _update_task_run(run_id, {
+                    "status": "cancelled",
+                    "error_message": str(e),
+                    "finished_at": datetime.now(timezone.utc).isoformat()
+                })
+
+            if update_task:
+                supabase.table("tasks").update({
+                    "status": "failed",
+                    "output_data": {"error": str(e), "budget_blocked": True}
+                }).eq("id", task_id).execute()
+                await audit_service.log_action(
+                    user_id=None,
+                    action="task_budget_blocked",
+                    agent_id=agent_data.get("id"),
+                    task_id=task_id,
+                    metadata={"project_id": project_id, "run_id": run_id, "error": str(e)},
+                )
+
+            supabase.table("agent_logs").insert({
+                "task_id": task_id,
+                "run_id": run_id,
+                "action": "budget_blocked",
+                "content": f"Budget blocked execution: {str(e)}"
+            }).execute()
+
+            raise e
+
+        except Exception as e:
+            logger.error(f"Error executing task {task_id}: {str(e)}")
+            if run_id:
+                _update_task_run(run_id, {
+                    "status": "failed",
+                    "finished_at": datetime.now(timezone.utc).isoformat()
+                })
+            
+            if update_task:
+                supabase.table("tasks").update({
+                    "status": "failed",
+                    "output_data": {"error": str(e)}
+                }).eq("id", task_id).execute()
+                await audit_service.log_action(
+                    user_id=None,
+                    action="task_status_changed",
+                    agent_id=agent_data.get("id"),
+                    task_id=task_id,
+                    metadata={
+                        "project_id": project_id,
+                        "run_id": run_id,
+                        "status": "failed",
+                        "error": str(e),
+                    },
+                )
+
+            # LOG ERROR TO AGENT CONSOLE
+            supabase.table("agent_logs").insert({
+                "task_id": task_id,
+                "run_id": run_id,
+                "action": "execution_failed",
+                "content": f"ERROR: {str(e)}"
+            }).execute()
+
+            raise e
+
+    @staticmethod
+    async def execute_agent_logic(task: dict, agent_data: dict):
+        task_id = task["id"]
+        try:
+            await AgentRunnerService.run_agent_task(
+                task,
+                agent_data,
+                include_semantic_context=True
+            )
+
+            await audit_service.log_action(
+                user_id=None,
+                action="agent_task_completed",
+                agent_id=agent_data["id"],
+                task_id=task_id,
+                metadata={"model": agent_data["model"]}
+            )
+
+        except Exception:
+            raise

backend/services/audit_service.py

@@ -0,0 +1,31 @@
+from services.supabase_service import supabase
+from typing import Dict, Any, Optional
+import logging
+
+logger = logging.getLogger("uvicorn")
+
+class AuditService:
+    @staticmethod
+    async def log_action(
+        user_id: Optional[str],
+        action: str,
+        agent_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Records an action in the audit_logs table.
+        """
+        try:
+            data = {
+                "user_id": user_id,
+                "action": action,
+                "agent_id": agent_id,
+                "task_id": task_id,
+                "metadata": metadata or {}
+            }
+            supabase.table("audit_logs").insert(data).execute()
+        except Exception as e:
+            logger.error(f"AuditService error: {str(e)}")
+
+audit_service = AuditService()

backend/services/budget_service.py

@@ -0,0 +1,208 @@
+import logging
+from decimal import Decimal
+from typing import Any
+
+from services.config import config_service
+
+logger = logging.getLogger("budget_service")
+
+
+def _estimate_tokens(value: Any) -> int:
+    text = str(value or "")
+    if not text.strip():
+        return 0
+    return max(1, len(text) // 4)
+
+
+def _safe_decimal(value: Any) -> Decimal:
+    try:
+        return Decimal(str(value or "0"))
+    except Exception:
+        return Decimal("0")
+
+
+class BudgetExceededError(RuntimeError):
+    pass
+
+
+class BudgetService:
+    @staticmethod
+    def estimate_prompt_tokens(
+        *,
+        task_instructions: str,
+        context: list[dict],
+        extra_context: str,
+        system_prompt: str | None,
+    ) -> int:
+        return (
+            _estimate_tokens(task_instructions)
+            + _estimate_tokens(context)
+            + _estimate_tokens(extra_context)
+            + _estimate_tokens(system_prompt)
+        )
+
+    @staticmethod
+    def estimate_completion_tokens(result: dict) -> int:
+        if not isinstance(result, dict):
+            return _estimate_tokens(result)
+        return _estimate_tokens(result.get("raw_output") or result.get("data") or result)
+
+    @staticmethod
+    def estimate_cost(provider: str | None, model: str | None, prompt_tokens: int, completion_tokens: int) -> Decimal:
+        pricing = config_service.get_global_setting("model_pricing", {}) or {}
+        keys = [
+            f"{provider}:{model}" if provider and model else None,
+            str(model) if model else None,
+            str(provider) if provider else None,
+        ]
+        price = next((pricing.get(key) for key in keys if key and key in pricing), None)
+        if not isinstance(price, dict):
+            return Decimal("0")
+
+        input_per_1k = _safe_decimal(price.get("input_per_1k"))
+        output_per_1k = _safe_decimal(price.get("output_per_1k"))
+        return (
+            (Decimal(prompt_tokens) / Decimal(1000)) * input_per_1k
+            + (Decimal(completion_tokens) / Decimal(1000)) * output_per_1k
+        ).quantize(Decimal("0.000001"))
+
+    @staticmethod
+    def _load_budget(project_id: str) -> dict | None:
+        try:
+            from services.supabase_service import supabase
+
+            response = supabase.table("project_budgets").select("*").eq("project_id", project_id).execute()
+            return response.data[0] if response.data else None
+        except Exception as exc:
+            logger.warning("Could not load project budget for %s: %s", project_id, exc)
+            return None
+
+    @staticmethod
+    def _usage_totals(project_id: str) -> dict:
+        try:
+            from services.supabase_service import supabase
+
+            rows = (
+                supabase.table("project_usage_events")
+                .select("total_tokens,estimated_cost")
+                .eq("project_id", project_id)
+                .execute()
+                .data
+                or []
+            )
+        except Exception as exc:
+            logger.warning("Could not load project usage for %s: %s", project_id, exc)
+            return {"total_tokens": 0, "estimated_cost": Decimal("0")}
+
+        return {
+            "total_tokens": sum(int(row.get("total_tokens") or 0) for row in rows),
+            "estimated_cost": sum((_safe_decimal(row.get("estimated_cost")) for row in rows), Decimal("0")),
+        }
+
+    @classmethod
+    def project_budget_status(cls, project_id: str) -> dict:
+        budget = cls._load_budget(project_id)
+        usage = cls._usage_totals(project_id)
+        token_budget = int(budget["token_budget"]) if budget and budget.get("token_budget") is not None else None
+        cost_budget = _safe_decimal(budget.get("cost_budget")) if budget and budget.get("cost_budget") is not None else None
+
+        return {
+            "project_id": project_id,
+            "budget": budget,
+            "usage": {
+                "total_tokens": usage["total_tokens"],
+                "estimated_cost": float(usage["estimated_cost"]),
+            },
+            "remaining": {
+                "tokens": max(token_budget - usage["total_tokens"], 0) if token_budget is not None else None,
+                "cost": float(max(cost_budget - usage["estimated_cost"], Decimal("0"))) if cost_budget is not None else None,
+            },
+        }
+
+    @staticmethod
+    def upsert_project_budget(
+        *,
+        project_id: str,
+        enabled: bool = True,
+        token_budget: int | None = None,
+        cost_budget: float | None = None,
+        currency: str = "USD",
+    ) -> dict:
+        try:
+            from services.supabase_service import supabase
+
+            payload = {
+                "project_id": project_id,
+                "enabled": enabled,
+                "token_budget": token_budget,
+                "cost_budget": cost_budget,
+                "currency": currency or "USD",
+            }
+            response = supabase.table("project_budgets").upsert(payload, on_conflict="project_id").execute()
+            return response.data[0] if response.data else payload
+        except Exception as exc:
+            logger.warning("Could not upsert project budget for %s: %s", project_id, exc)
+            raise
+
+    @classmethod
+    def check_before_run(
+        cls,
+        *,
+        project_id: str,
+        estimated_tokens: int,
+        estimated_cost: Decimal,
+    ) -> dict:
+        budget = cls._load_budget(project_id)
+        if not budget or not budget.get("enabled", True):
+            return {"allowed": True, "budget": budget, "usage": None}
+
+        usage = cls._usage_totals(project_id)
+        token_budget = budget.get("token_budget")
+        if token_budget is not None and usage["total_tokens"] + estimated_tokens > int(token_budget):
+            raise BudgetExceededError(
+                f"Project token budget exceeded: {usage['total_tokens']} used + {estimated_tokens} estimated > {token_budget}."
+            )
+
+        cost_budget = budget.get("cost_budget")
+        if cost_budget is not None and usage["estimated_cost"] + estimated_cost > _safe_decimal(cost_budget):
+            raise BudgetExceededError(
+                f"Project cost budget exceeded: {usage['estimated_cost']} used + {estimated_cost} estimated > {cost_budget}."
+            )
+
+        return {"allowed": True, "budget": budget, "usage": usage}
+
+    @staticmethod
+    def record_usage(
+        *,
+        project_id: str,
+        task_id: str,
+        run_id: str | None,
+        agent_id: str | None,
+        provider: str | None,
+        model: str | None,
+        prompt_tokens: int,
+        completion_tokens: int,
+        estimated_cost: Decimal,
+        metadata: dict | None = None,
+    ) -> None:
+        try:
+            from services.supabase_service import supabase
+
+            supabase.table("project_usage_events").insert({
+                "project_id": project_id,
+                "task_id": task_id,
+                "run_id": run_id,
+                "agent_id": agent_id,
+                "provider": provider,
+                "model": model,
+                "prompt_tokens": prompt_tokens,
+                "completion_tokens": completion_tokens,
+                "total_tokens": prompt_tokens + completion_tokens,
+                "estimated_cost": float(estimated_cost),
+                "metadata": metadata or {},
+            }).execute()
+        except Exception as exc:
+            logger.warning("Could not record project usage for task %s: %s", task_id, exc)
+
+
+budget_service = BudgetService()

backend/services/config.py

@@ -0,0 +1,107 @@
+import os
+from pydantic_settings import BaseSettings
+from typing import Optional, Dict, Any
+from supabase import create_client, Client
+
+class Settings(BaseSettings):
+    # Supabase
+    SUPABASE_URL: str = ""
+    SUPABASE_SERVICE_ROLE_KEY: str = ""
+
+    # AI Providers
+    OPENAI_API_KEY: Optional[str] = None
+    GROQ_API_KEY: Optional[str] = None
+    GEMINI_API_KEY: Optional[str] = None
+    ANTHROPIC_API_KEY: Optional[str] = None
+    AMD_API_KEY: Optional[str] = None
+    TAVILY_API_KEY: Optional[str] = None
+
+    # Infrastructure (DigitalOcean)
+    DO_API_TOKEN: Optional[str] = None
+    DO_INFERENCE_KEY: Optional[str] = None
+    DO_AGENT_ACCESS_KEY: Optional[str] = None
+    DO_AGENT_ENDPOINT: Optional[str] = None
+    DO_REGION: str = "nyc3"
+
+    # App Config
+    TASK_QUEUE_EMBEDDED_WORKER: bool = True
+    TASK_QUEUE_HEARTBEAT_ENABLED: bool = True
+    TASK_EXECUTION_MODE: str = "queue"  # direct | queue
+    TASK_QUEUE_IDLE_POLL_SECONDS: int = 60
+    OUTPUT_LANGUAGE: str = "en"
+    PORT: int = 8000
+    SENTRY_DSN: Optional[str] = None
+    
+    model_config = {
+        "env_file": ".env",
+        "extra": "ignore"
+    }
+
+settings = Settings()
+
+class ConfigService:
+    """
+    Manages application-wide settings stored in Supabase with local fallback defaults.
+    Borrowed from AgentCollab for enhanced flexibility.
+    """
+    _cache: Dict[str, Any] = {}
+    _supabase: Client = None
+
+    @classmethod
+    def _get_supabase(cls):
+        if not cls._supabase:
+            if not settings.SUPABASE_URL or not settings.SUPABASE_SERVICE_ROLE_KEY:
+                return None
+            cls._supabase = create_client(settings.SUPABASE_URL, settings.SUPABASE_SERVICE_ROLE_KEY)
+        return cls._supabase
+
+    # Defaults used when DB has no config entry for a provider
+    _DEFAULTS: Dict[str, Any] = {
+        "groq":        {"enabled": True,  "default_model": "llama-3.3-70b-versatile", "temperature": 0.7, "max_tokens": 4096},
+        "openai":      {"enabled": True,  "default_model": "gpt-4o",                   "temperature": 0.7, "max_tokens": 4096},
+        "openrouter":  {"enabled": True,  "default_model": "google/gemini-2.0-flash",  "temperature": 0.7, "max_tokens": 8192},
+        "gemini":      {"enabled": True,  "default_model": "gemini-2.0-flash",         "temperature": 0.7, "max_tokens": 8192},
+        "amd":         {"enabled": True,  "default_model": "llama-3.3-70b-instruct",                   "temperature": 0.7, "max_tokens": 4096, "base_url": "https://inference.do-ai.run/v1"},
+        "ollama":      {"enabled": True,  "default_model": "llama3.1:8b",              "temperature": 0.7, "base_url": "http://localhost:11434"},
+    }
+
+    @classmethod
+    def get_provider_config(cls, provider: str) -> Dict[str, Any]:
+        """Returns config for a provider from cache, DB, then defaults."""
+        cache_key = f"provider:{provider}"
+        if cache_key in cls._cache:
+            return cls._cache[cache_key]
+
+        db = cls._get_supabase()
+        if db:
+            try:
+                resp = db.table("app_config").select("*").eq("key", provider).execute()
+                if resp.data and len(resp.data) > 0:
+                    cls._cache[cache_key] = resp.data[0]["value"]
+                    return cls._cache[cache_key]
+            except Exception:
+                pass # Fall through to defaults
+
+        result = cls._DEFAULTS.get(provider, {})
+        cls._cache[cache_key] = result
+        return result
+
+    @classmethod
+    def get_global_setting(cls, key: str, default: Any = None) -> Any:
+        cache_key = f"global:{key}"
+        if cache_key in cls._cache:
+            return cls._cache[cache_key]
+
+        db = cls._get_supabase()
+        if db:
+            try:
+                resp = db.table("app_config").select("*").eq("key", key).execute()
+                if resp.data and len(resp.data) > 0:
+                    cls._cache[cache_key] = resp.data[0]["value"]
+                    return cls._cache[cache_key]
+            except Exception:
+                pass
+        
+        return default
+
+config_service = ConfigService()

backend/services/embedding_service.py

@@ -0,0 +1,87 @@
+import logging
+import numpy as np
+from typing import List, Optional
+import openai
+from services.config import settings
+
+logger = logging.getLogger("embedding_service")
+
+class EmbeddingService:
+    """
+    Handles text vectorization for semantic deduplication and retrieval.
+    """
+    def __init__(self):
+        self.client = None
+        self.model = "text-embedding-3-small"
+        if settings.OPENAI_API_KEY:
+            try:
+                self.client = openai.AsyncOpenAI(api_key=settings.OPENAI_API_KEY)
+            except Exception as e:
+                logger.error(f"Failed to initialize OpenAI client for embeddings: {e}")
+
+    async def get_embeddings(self, texts: List[str]) -> List[List[float]]:
+        """
+        Batch fetches embeddings for a list of strings.
+        """
+        if not settings.OPENAI_API_KEY or not self.client:
+            logger.debug("OpenAI embeddings not available (missing key or initialization failed).")
+            return []
+            
+        if not texts:
+            return []
+
+        try:
+            # Cleanup texts to avoid API errors on empty/null inputs
+            clean_texts = [str(t)[:8000] for t in texts if t]
+            if not clean_texts:
+                return []
+
+            response = await self.client.embeddings.create(
+                input=clean_texts,
+                model=self.model
+            )
+            return [data.embedding for data in response.data]
+        except Exception as e:
+            logger.error(f"Failed to fetch embeddings: {e}")
+            return []
+
+    def cosine_similarity(self, vec_a: List[float], vec_b: List[float]) -> float:
+        """
+        Calculates cosine similarity between two vectors.
+        """
+        a = np.array(vec_a)
+        b = np.array(vec_b)
+        if not a.any() or not b.any():
+            return 0.0
+        return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
+
+    async def find_duplicates(self, new_claims: List[str], existing_claims: List[str], threshold: float = 0.85) -> List[Optional[int]]:
+        """
+        For each new claim, finds the index of a semantically similar existing claim.
+        Returns a list of indices or None if no match found.
+        """
+        if not new_claims or not existing_claims:
+            return [None] * len(new_claims)
+
+        new_vecs = await self.get_embeddings(new_claims)
+        existing_vecs = await self.get_embeddings(existing_claims)
+
+        if not new_vecs or not existing_vecs:
+            return [None] * len(new_claims)
+
+        results = []
+        for n_vec in new_vecs:
+            best_idx = None
+            best_score = -1.0
+            
+            for idx, e_vec in enumerate(existing_vecs):
+                score = self.cosine_similarity(n_vec, e_vec)
+                if score > threshold and score > best_score:
+                    best_score = score
+                    best_idx = idx
+            
+            results.append(best_idx)
+        
+        return results
+
+embedding_service = EmbeddingService()

backend/services/evidence_service.py

@@ -0,0 +1,315 @@
+import logging
+import hashlib
+import re
+import unicodedata
+from typing import Any
+
+from services.task_schemas import parse_structured_payload
+
+logger = logging.getLogger("evidence_service")
+
+
+def _primary_payload(output_data: dict) -> Any:
+    data = output_data.get("data")
+    if data not in (None, "", [], {}):
+        return parse_structured_payload(data) if isinstance(data, str) else data
+    return parse_structured_payload(output_data.get("raw_output"))
+
+
+def _clean_text(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def normalize_entity_key(value: Any) -> str | None:
+    text = _clean_text(value)
+    if not text:
+        return None
+    normalized = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii")
+    normalized = normalized.lower()
+    normalized = re.sub(r"\b(inc|llc|ltd|corp|corporation|company|co|sa|s\.a\.)\b", "", normalized)
+    normalized = re.sub(r"[^a-z0-9]+", " ", normalized)
+    normalized = re.sub(r"\s+", " ", normalized).strip()
+    return normalized or None
+
+
+def normalize_claim_text(value: Any) -> str:
+    text = unicodedata.normalize("NFKD", _clean_text(value)).encode("ascii", "ignore").decode("ascii")
+    text = text.lower()
+    text = re.sub(r"https?://\S+", "", text)
+    text = re.sub(r"[^a-z0-9]+", " ", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def claim_hash(
+    project_id: str | None,
+    claim_text: str,
+    entity_name: str | None = None,
+    entity_key: str | None = None,
+) -> str:
+    key = "|".join([
+        project_id or "",
+        entity_key or normalize_entity_key(entity_name) or "",
+        normalize_claim_text(claim_text),
+    ])
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()
+
+
+def _claim_row(
+    *,
+    project_id: str | None,
+    task_id: str | None,
+    claim_text: str,
+    claim_type: str,
+    entity_name: str | None = None,
+    source_url: str | None = None,
+    confidence: str = "unknown",
+    metadata: dict | None = None,
+    alias_map: dict[str, str] | None = None,
+) -> dict:
+    raw_entity_key = normalize_entity_key(entity_name)
+    entity_key = (alias_map or {}).get(raw_entity_key or "", raw_entity_key)
+    return {
+        "project_id": project_id,
+        "task_id": task_id,
+        "claim_text": claim_text,
+        "claim_type": claim_type,
+        "entity_name": entity_name,
+        "entity_key": entity_key,
+        "claim_hash": claim_hash(project_id, claim_text, entity_name, entity_key),
+        "source_url": source_url,
+        "confidence": confidence,
+        "metadata": metadata or {},
+    }
+
+
+class EvidenceService:
+    @staticmethod
+    def load_alias_map(project_id: str | None) -> dict[str, str]:
+        if not project_id:
+            return {}
+        try:
+            from services.supabase_service import supabase
+
+            rows = (
+                supabase.table("project_entity_aliases")
+                .select("alias_key,canonical_key")
+                .eq("project_id", project_id)
+                .execute()
+                .data
+                or []
+            )
+        except Exception as exc:
+            logger.warning("Could not load entity aliases for project %s: %s", project_id, exc)
+            return {}
+
+        aliases: dict[str, str] = {}
+        for row in rows:
+            alias_key = row.get("alias_key")
+            canonical_key = row.get("canonical_key")
+            if alias_key and canonical_key:
+                aliases[alias_key] = canonical_key
+        return aliases
+
+    @staticmethod
+    def load_project_claims(project_id: str) -> list[dict]:
+        try:
+            from services.supabase_service import supabase
+
+            return (
+                supabase.table("task_claims")
+                .select("claim_text,claim_type,entity_name,entity_key,source_url,confidence,task_id,created_at")
+                .eq("project_id", project_id)
+                .order("created_at", desc=False)
+                .execute()
+                .data
+                or []
+            )
+        except Exception as exc:
+            logger.warning("Could not load task claims for project %s: %s", project_id, exc)
+            return []
+
+    @staticmethod
+    def summarize_claims(claims: list[dict]) -> dict:
+        by_type: dict[str, int] = {}
+        by_entity: dict[str, int] = {}
+        sourced_count = 0
+
+        for claim in claims:
+            claim_type = claim.get("claim_type") or "unknown"
+            by_type[claim_type] = by_type.get(claim_type, 0) + 1
+
+            entity = claim.get("entity_name") or claim.get("entity_key") or "Unassigned"
+            by_entity[entity] = by_entity.get(entity, 0) + 1
+
+            source_url = claim.get("source_url")
+            if isinstance(source_url, str) and source_url.startswith(("http://", "https://")):
+                sourced_count += 1
+
+        total_count = len(claims)
+        return {
+            "claim_count": total_count,
+            "sourced_claim_count": sourced_count,
+            "unsourced_claim_count": max(total_count - sourced_count, 0),
+            "source_coverage": round(sourced_count / total_count, 4) if total_count else 0,
+            "by_type": dict(sorted(by_type.items())),
+            "by_entity": dict(sorted(by_entity.items(), key=lambda item: item[1], reverse=True)),
+        }
+
+    @staticmethod
+    def extract_claims(task: dict, output_data: dict) -> list[dict]:
+        payload = _primary_payload(output_data)
+        if not isinstance(payload, dict):
+            return []
+
+        project_id = task.get("project_id")
+        task_id = task.get("id")
+        alias_map = EvidenceService.load_alias_map(project_id)
+        claims: list[dict] = []
+
+        for finding in payload.get("findings") or []:
+            if not isinstance(finding, dict):
+                continue
+            claim_text = _clean_text(finding.get("claim"))
+            if not claim_text:
+                continue
+            claims.append(_claim_row(
+                project_id=project_id,
+                task_id=task_id,
+                claim_text=claim_text,
+                claim_type="finding",
+                entity_name=_clean_text(finding.get("entity")) or None,
+                source_url=_clean_text(finding.get("source_url")) or None,
+                confidence=finding.get("confidence") if finding.get("confidence") in ("low", "medium", "high") else "unknown",
+                metadata={"schema_source": "findings"},
+                alias_map=alias_map,
+            ))
+
+        for entity in payload.get("entities") or []:
+            if not isinstance(entity, dict):
+                continue
+            entity_name = _clean_text(entity.get("name"))
+            source_url = _clean_text(entity.get("source_url")) or None
+            for key, claim_type in (("strengths", "entity_strength"), ("weaknesses", "entity_weakness")):
+                for item in entity.get(key) or []:
+                    claim_text = _clean_text(item)
+                    if not claim_text:
+                        continue
+                    claims.append(_claim_row(
+                        project_id=project_id,
+                        task_id=task_id,
+                        claim_text=claim_text,
+                        claim_type=claim_type,
+                        entity_name=entity_name or None,
+                        source_url=source_url,
+                        confidence="unknown",
+                        metadata={"schema_source": f"entities.{key}", "category": entity.get("category")},
+                        alias_map=alias_map,
+                    ))
+
+        for recommendation in payload.get("recommendations") or []:
+            if not isinstance(recommendation, dict):
+                continue
+            claim_text = _clean_text(recommendation.get("title") or recommendation.get("rationale"))
+            if not claim_text:
+                continue
+            claims.append(_claim_row(
+                project_id=project_id,
+                task_id=task_id,
+                claim_text=claim_text,
+                claim_type="recommendation",
+                metadata=recommendation,
+            ))
+
+        for risk in payload.get("risks") or []:
+            claim_text = _clean_text(risk)
+            if not claim_text:
+                continue
+            claims.append(_claim_row(
+                project_id=project_id,
+                task_id=task_id,
+                claim_text=claim_text,
+                claim_type="risk",
+                metadata={"schema_source": "risks"},
+            ))
+
+        deduped: dict[str, dict] = {}
+        for claim in claims:
+            deduped.setdefault(claim["claim_hash"], claim)
+        return list(deduped.values())
+
+    @staticmethod
+    async def replace_task_claims(task: dict, output_data: dict) -> int:
+        task_id = task.get("id")
+        if not task_id:
+            return 0
+
+        claims = EvidenceService.extract_claims(task, output_data)
+        try:
+            from services.supabase_service import supabase
+
+            supabase.table("task_claims").delete().eq("task_id", task_id).execute()
+            if claims:
+                supabase.table("task_claims").upsert(
+                    claims,
+                    on_conflict="project_id,claim_hash",
+                ).execute()
+            return len(claims)
+        except Exception as exc:
+            logger.warning("Could not persist task claims for %s: %s", task_id, exc)
+            return 0
+
+    @staticmethod
+    async def merge_project_claims(project_id: str, threshold: float = 0.88) -> list[dict]:
+        """
+        Groups similar claims within a project and returns a consolidated set.
+        """
+        from services.embedding_service import embedding_service
+        
+        claims = EvidenceService.load_project_claims(project_id)
+        if len(claims) < 2:
+            return claims
+
+        # Extract texts for embedding
+        texts = [c["claim_text"] for c in claims]
+        embeddings = await embedding_service.get_embeddings(texts)
+        if not embeddings:
+            return claims
+
+        merged: list[dict] = []
+        used_indices: set[int] = set()
+
+        for i in range(len(claims)):
+            if i in used_indices:
+                continue
+            
+            base_claim = claims[i].copy()
+            used_indices.add(i)
+            
+            # Look for matches in the rest of the claims
+            for j in range(i + 1, len(claims)):
+                if j in used_indices:
+                    continue
+                
+                similarity = embedding_service.cosine_similarity(embeddings[i], embeddings[j])
+                if similarity >= threshold:
+                    used_indices.add(j)
+                    # Merge logic: Append sources, keep longest text, etc.
+                    other_claim = claims[j]
+                    if len(other_claim["claim_text"]) > len(base_claim["claim_text"]):
+                        base_claim["claim_text"] = other_claim["claim_text"]
+                    
+                    # Consolidate sources (metadata)
+                    if other_claim.get("source_url") and not base_claim.get("source_url"):
+                        base_claim["source_url"] = other_claim["source_url"]
+                    
+                    # Track that this claim was merged
+                    if "merged_count" not in base_claim:
+                        base_claim["merged_count"] = 1
+                    base_claim["merged_count"] += 1
+
+            merged.append(base_claim)
+
+        return merged
+
+
+evidence_service = EvidenceService()

backend/services/infrastructure_service.py

@@ -0,0 +1,97 @@
+import httpx
+import logging
+import asyncio
+from typing import Optional, Dict, Any
+from .config import settings
+
+logger = logging.getLogger("infrastructure")
+
+class InfrastructureService:
+    """
+    Manages on-the-fly compute resources on DigitalOcean for AI inference.
+    """
+    API_URL = "https://api.digitalocean.com/v2"
+
+    def __init__(self):
+        self.headers = {
+            "Authorization": f"Bearer {settings.DO_API_TOKEN}",
+            "Content-Type": "application/json"
+        }
+
+    async def create_inference_node(self, name: str, size: str = "s-4vcpu-8gb-amd") -> Optional[Dict[str, Any]]:
+        """
+        Provision a new AMD-based droplet with Ollama pre-installed.
+        Default size is a capable AMD-based node.
+        """
+        if not settings.DO_API_TOKEN:
+            logger.error("DO_API_TOKEN not configured.")
+            return None
+
+        # Cloud-init script to setup the inference environment
+        user_data = """#cloud-config
+runcmd:
+  - curl -fsSL https://get.docker.com | sh
+  - docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama -e OLLAMA_HOST=0.0.0.0 ollama/ollama
+  - sleep 10
+  - docker exec ollama ollama pull llama3
+"""
+
+        payload = {
+            "name": name,
+            "region": settings.DO_REGION,
+            "size": size,
+            "image": "ubuntu-22-04-x64",
+            "user_data": user_data,
+            "tags": ["aubm-worker", "inference-node"]
+        }
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(f"{self.API_URL}/droplets", headers=self.headers, json=payload)
+                response.raise_for_status()
+                data = response.json()
+                droplet_id = data["droplet"]["id"]
+                logger.info(f"Inference node creation initiated: {name} (ID: {droplet_id})")
+                return data["droplet"]
+            except Exception as e:
+                logger.error(f"Failed to create droplet: {e}")
+                return None
+
+    async def wait_for_ip(self, droplet_id: int, timeout: int = 300) -> Optional[str]:
+        """
+        Polls the API until the droplet has a public IP assigned.
+        """
+        start_time = asyncio.get_event_loop().time()
+        async with httpx.AsyncClient() as client:
+            while (asyncio.get_event_loop().time() - start_time) < timeout:
+                try:
+                    response = await client.get(f"{self.API_URL}/droplets/{droplet_id}", headers=self.headers)
+                    response.raise_for_status()
+                    droplet = response.json()["droplet"]
+                    
+                    networks = droplet.get("networks", {}).get("v4", [])
+                    for nw in networks:
+                        if nw["type"] == "public":
+                            return nw["ip_address"]
+                            
+                except Exception as e:
+                    logger.warning(f"Error polling droplet {droplet_id}: {e}")
+                
+                await asyncio.sleep(10)
+        return None
+
+    async def terminate_node(self, droplet_id: int):
+        """
+        Destroy the inference node to stop billing.
+        """
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.delete(f"{self.API_URL}/droplets/{droplet_id}", headers=self.headers)
+                response.raise_for_status()
+                logger.info(f"Inference node {droplet_id} termination requested.")
+                return True
+            except Exception as e:
+                logger.error(f"Failed to terminate droplet {droplet_id}: {e}")
+                return False
+
+infrastructure_service = InfrastructureService()

backend/services/memory_service.py

@@ -0,0 +1,174 @@
+import logging
+from typing import List, Dict, Any, Optional
+from services.supabase_service import supabase
+from services.embedding_service import embedding_service
+
+logger = logging.getLogger("uvicorn")
+
+class MemoryService:
+    """
+    Handles vectorized long-term memory for Aubm projects.
+    Allows agents to retrieve context from past projects and approved work.
+    """
+
+    async def save_memory(
+        self,
+        project_id: str,
+        content: str,
+        task_id: Optional[str] = None,
+        memory_type: str = "approved_output",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> bool:
+        """
+        Vectorizes content and saves it to project_memory.
+        """
+        try:
+            if not content or len(content.strip()) < 10:
+                return False
+
+            embedding = await embedding_service.get_embedding(content)
+            
+            data = {
+                "project_id": project_id,
+                "task_id": task_id,
+                "content": content,
+                "embedding": embedding,
+                "memory_type": memory_type,
+                "metadata": metadata or {}
+            }
+            
+            result = supabase.table("project_memory").insert(data).execute()
+            return len(result.data) > 0
+        except Exception as e:
+            logger.error(f"Failed to save memory: {e}")
+            return False
+
+    async def search_memory(
+        self,
+        query: str,
+        limit: int = 5,
+        threshold: float = 0.7,
+        project_id: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Performs semantic search across project memory.
+        If project_id is provided, filters memory to that project only (short-term).
+        If project_id is None, searches cross-project (long-term).
+        """
+        try:
+            query_embedding = await embedding_service.get_embedding(query)
+            
+            # Use the match_project_memory RPC function defined in add_vector_memory.sql
+            rpc_params = {
+                "query_embedding": query_embedding,
+                "match_threshold": threshold,
+                "match_count": limit,
+            }
+            
+            if project_id:
+                rpc_params["filter_project_id"] = project_id
+
+            result = supabase.rpc("match_project_memory", rpc_params).execute()
+            return result.data or []
+        except Exception as e:
+            logger.error(f"Failed to search memory: {e}")
+            return []
+
+    async def index_task_output(self, task: Dict[str, Any]) -> bool:
+        """
+        Specialized indexer for approved task outputs.
+        """
+        output_data = task.get("output_data")
+        if not output_data:
+            return False
+            
+        # Extract meaningful text from output
+        content = ""
+        if isinstance(output_data, str):
+            content = output_data
+        elif isinstance(output_data, dict):
+            # Try to get the primary content
+            content = (
+                output_data.get("data") or 
+                output_data.get("strategicConclusion") or 
+                output_data.get("raw_output") or
+                str(output_data)
+            )
+        
+        if not content:
+            return False
+
+        return await self.save_memory(
+            project_id=task.get("project_id"),
+            task_id=task.get("id"),
+            content=str(content),
+            memory_type="approved_output",
+            metadata={
+                "task_title": task.get("title"),
+                "agent_id": task.get("assigned_agent_id")
+            }
+        )
+
+    async def analyze_rejection(self, task_id: str, feedback: Optional[str] = None):
+        """
+        Analyzes a task rejection to generate a 'Self-Optimization Lesson'.
+        Triggered when a human rejects an agent's output.
+        """
+        try:
+            # 1. Fetch task and its failed output
+            task_res = supabase.table("tasks").select("*, projects(name, description)").eq("id", task_id).single().execute()
+            if not task_res.data:
+                return
+            
+            task = task_res.data
+            output = task.get("output_data") or {}
+            
+            # 2. Get an analyst agent
+            from agents.agent_factory import AgentFactory
+            from services.llm_config import getDefaultProvider, getDefaultModel
+            
+            provider = getDefaultProvider()
+            model = getDefaultModel(provider)
+            
+            analyst = AgentFactory.get_agent(
+                provider=provider,
+                name="Optimization Analyst",
+                role="Self-Optimization Expert",
+                model=model,
+                system_prompt="You analyze task rejections. Your goal is to produce a single, concise 'Lesson Learned' that the next agent should follow to avoid repeating the mistake. Focus on the core reason for rejection."
+            )
+            
+            # 3. Construct prompt for analysis
+            analysis_prompt = f"""
+            TASK: {task.get('title')}
+            DESCRIPTION: {task.get('description')}
+            
+            REJECTED OUTPUT:
+            {str(output)[:2000]}
+            
+            HUMAN FEEDBACK: {feedback or "No explicit feedback provided, but the output did not meet quality standards."}
+            
+            Provide a concise 'LESSON LEARNED' for the next agent. Start with 'Next time, you must...'
+            """
+            
+            result = await analyst.run(analysis_prompt, [])
+            lesson_text = result.get("raw_output") or result.get("data")
+            
+            if lesson_text:
+                await self.save_memory(
+                    project_id=task.get("project_id"),
+                    task_id=task_id,
+                    content=f"Optimization Lesson for '{task.get('title')}': {lesson_text}",
+                    memory_type="self_optimization_lesson",
+                    metadata={
+                        "original_task_id": task_id,
+                        "was_rejected": True,
+                        "feedback": feedback
+                    }
+                )
+                logger.info(f"Saved self-optimization lesson for task {task_id}")
+                
+        except Exception as e:
+            logger.error(f"Failed to analyze rejection for task {task_id}: {e}")
+
+memory_service = MemoryService()

backend/services/orchestrator_service.py

@@ -0,0 +1,1059 @@
+from services.supabase_service import supabase
+from agents.agent_factory import AgentFactory
+import json
+import logging
+import re
+from services.config import settings
+from services.agent_runner_service import AgentRunnerService
+from services.audit_service import audit_service
+from services.evidence_service import evidence_service
+from services.output_quality import clean_report_text, dedupe_lines, filter_report_sections, validate_output
+
+logger = logging.getLogger("uvicorn")
+
+NOISY_REPORT_KEYS = {
+    "raw_text",
+    "sampleBackendCode",
+    "sampleUploadSnippet",
+    "sampleSearchEndpoint",
+    "sampleRedisCartHelper",
+    "sampleWebhookHandler",
+    "sampleStateMachine",
+    "repositoryStructure",
+    "wireframes",
+    "dataModel",
+    "userStories",
+}
+
+def _humanize_key(key: str) -> str:
+    return key.replace("_", " ").replace("-", " ").strip().title()
+
+def _format_value_for_report(value, level: int = 0) -> list[str]:
+    if value is None:
+        return ["Not specified."]
+
+    if isinstance(value, (str, int, float, bool)):
+        return [str(value)]
+
+    if isinstance(value, list):
+        lines: list[str] = []
+        for item in value:
+            if isinstance(item, dict):
+                item_lines = _format_value_for_report(item, level + 1)
+                if item_lines:
+                    lines.append(f"- {item_lines[0]}")
+                    lines.extend(f"  {line}" for line in item_lines[1:])
+            elif isinstance(item, list):
+                nested = _format_value_for_report(item, level + 1)
+                lines.extend(f"- {line}" for line in nested)
+            else:
+                lines.append(f"- {item}")
+        return lines or ["No items."]
+
+    if isinstance(value, dict):
+        lines: list[str] = []
+        for key, item in value.items():
+            if str(key) in NOISY_REPORT_KEYS:
+                continue
+            title = _humanize_key(str(key))
+            if isinstance(item, dict):
+                lines.append(f"{title}:")
+                lines.extend(f"  {line}" for line in _format_value_for_report(item, level + 1))
+            elif isinstance(item, list):
+                lines.append(f"{title}:")
+                lines.extend(f"  {line}" for line in _format_value_for_report(item, level + 1))
+            else:
+                lines.append(f"{title}: {item}")
+        return lines or ["No details."]
+
+    return [str(value)]
+
+
+def _extract_json_payload(text: str):
+    if not text:
+        return None
+        
+    stripped = text.strip()
+    
+    # 1. Try standard block extraction
+    if stripped.startswith("```"):
+        cleaned = stripped.strip("`")
+        if cleaned.lower().startswith("json"):
+            cleaned = cleaned[4:].strip()
+        try:
+            return json.loads(cleaned)
+        except Exception:
+            pass # Fallback to regex
+
+    # 2. Try direct parsing
+    try:
+        return json.loads(stripped)
+    except Exception:
+        pass
+
+    # 3. Robust Regex Search (find content between first { and last })
+    # This is the "Repair Layer" for noisy LLM outputs
+    try:
+        # Search for anything starting with { and ending with }
+        # across multiple lines
+        match = re.search(r'(\{.*\})', stripped, re.DOTALL)
+        if match:
+            return json.loads(match.group(1))
+    except Exception:
+        pass
+
+    # 4. Specific Markdown Block Search
+    match = re.search(r"```json\s*(.*?)\s*```", text, re.IGNORECASE | re.DOTALL)
+    if match:
+        try:
+            return json.loads(match.group(1))
+        except Exception:
+            pass
+            
+    return None
+
+def _format_output_for_report(output_data) -> str:
+    if not output_data:
+        return "No approved output was saved for this task."
+
+    if isinstance(output_data, dict):
+        primary = (
+            output_data.get("data")
+            or output_data.get("final")
+            or output_data.get("raw_output")
+            or output_data
+        )
+    else:
+        primary = output_data
+
+    if isinstance(primary, str):
+        parsed = _extract_json_payload(primary)
+        if parsed is not None:
+            return clean_report_text(dedupe_lines("\n".join(_format_value_for_report(parsed))))
+        return clean_report_text(dedupe_lines(primary))
+
+    return clean_report_text(dedupe_lines("\n".join(_format_value_for_report(primary))))
+
+
+def _is_empty_curated_text(text: str) -> bool:
+    normalized = (text or "").strip().lower()
+    return normalized in {
+        "",
+        "no approved output was saved for this task.",
+        "{}",
+        "[]",
+    }
+
+
+def _is_empty_report_variant(text: str | None) -> bool:
+    normalized = clean_report_text(dedupe_lines(text or "")).strip()
+    content_words = re.findall(r"[A-Za-z0-9_]+", normalized)
+    lower = normalized.lower()
+    return (
+        len(content_words) < 20
+        or lower in {"{}", "[]", "null", "none", "no details.", "not specified."}
+        or lower.startswith("```")
+    )
+
+
+def _format_conclusion_payload(data: dict) -> str:
+    conclusion = data.get("strategicConclusion") or data.get("conclusion") or data.get("content") or ""
+    next_steps = data.get("nextSteps") or data.get("next_steps") or []
+
+    lines: list[str] = []
+    if isinstance(conclusion, str) and conclusion.strip():
+        lines.append(conclusion.strip())
+
+    usable_steps = [
+        step.strip()
+        for step in next_steps
+        if isinstance(step, str) and step.strip()
+    ] if isinstance(next_steps, list) else []
+
+    if usable_steps:
+        lines.append("")
+        lines.append("Next steps:")
+        for step in usable_steps[:5]:
+            lines.append(f"- {step}")
+
+    return "\n".join(lines).strip() or "\n".join(_format_value_for_report(data))
+
+
+def _has_usable_output(output_data) -> bool:
+    if not output_data:
+        return False
+    if isinstance(output_data, dict):
+        if output_data.get("error"):
+            return False
+        primary = output_data.get("data")
+        if primary in (None, "", [], {}):
+            return False
+    return True
+
+def _output_text(output_data) -> str:
+    return _format_output_for_report(output_data).lower()
+
+def _build_report_charts(tasks: list[dict]) -> dict:
+    total = len(tasks)
+    done = sum(1 for task in tasks if task.get("status") == "done")
+    failed = sum(1 for task in tasks if task.get("status") == "failed")
+    pending = max(total - done - failed, 0)
+
+    priority_counts: dict[str, int] = {}
+    for task in tasks:
+        priority = str(task.get("priority") if task.get("priority") is not None else 0)
+        priority_counts[priority] = priority_counts.get(priority, 0) + 1
+
+    categories = {
+        "Market": ("market", "competitor", "customer", "segment", "demand"),
+        "Product": ("product", "mvp", "feature", "design", "scope"),
+        "Revenue": ("revenue", "price", "pricing", "margin", "commission"),
+        "Operations": ("operation", "process", "logistic", "support", "fulfillment"),
+        "Risk": ("risk", "threat", "failure", "weak", "mitigation")
+    }
+    category_counts = {name: 0 for name in categories}
+    risk_mentions = 0
+
+    for task in tasks:
+        text = f"{task.get('title', '')} {task.get('description', '')} {_output_text(task.get('output_data'))}".lower()
+        risk_mentions += sum(text.count(term) for term in categories["Risk"])
+        for category, terms in categories.items():
+            if any(term in text for term in terms):
+                category_counts[category] += 1
+
+    opportunity_score = 85 if total and done == total else round((done / total) * 85) if total else 0
+    risk_score = min(95, 35 + risk_mentions * 3)
+    readiness_score = round((done / total) * 100) if total else 0
+
+    return {
+        "status": [
+            {"label": "Approved", "value": done},
+            {"label": "Pending", "value": pending},
+            {"label": "Failed", "value": failed}
+        ],
+        "priorities": [
+            {"label": f"Priority {key}", "value": value}
+            for key, value in sorted(priority_counts.items(), key=lambda item: int(item[0]) if item[0].isdigit() else 0, reverse=True)
+        ],
+        "categories": [
+            {"label": label, "value": value}
+            for label, value in category_counts.items()
+        ],
+        "scores": [
+            {"label": "Readiness", "value": readiness_score},
+            {"label": "Opportunity", "value": opportunity_score},
+            {"label": "Risk", "value": risk_score}
+        ]
+    }
+
+def _format_chart_rows(title: str, rows: list[dict]) -> list[str]:
+    if not rows:
+        return [f"### {title}", "No data available.", ""]
+
+    lines = [f"### {title}"]
+    lines.extend(f"- {row['label']}: {row['value']}" for row in rows)
+    lines.append("")
+    return lines
+
+def _format_execution_summary(charts: dict, total_tasks: int, kept_task_count: int, excluded_count: int) -> list[str]:
+    lines = [
+        f"- Total tasks: {total_tasks}",
+        f"- Included outputs: {kept_task_count}",
+        f"- Excluded outputs: {excluded_count}",
+        "",
+    ]
+    lines.extend(_format_chart_rows("Scores", charts.get("scores", [])))
+    lines.extend(_format_chart_rows("Task Categories", charts.get("categories", [])))
+    lines.extend(_format_chart_rows("Priorities", charts.get("priorities", [])))
+    return lines
+
+
+
+
+
+async def _format_evidence_summary(project_id: str, claims: list[dict]) -> list[str]:
+    if not claims:
+        return []
+
+    # Get semantically merged claims for the "Strategic Findings" section
+    merged_claims = await evidence_service.merge_project_claims(project_id, threshold=0.88)
+    summary = evidence_service.summarize_claims(claims)
+    
+    lines = [
+        "## Strategic Findings & Evidence",
+        f"The analysis has consolidated **{summary['claim_count']}** unique data points into **{len(merged_claims)}** strategic findings.",
+        f"Source coverage: **{summary['source_coverage']:.0%}** (Claims backed by external evidence).",
+        "",
+        "### Key Consolidated Findings",
+    ]
+
+    # Show merged claims with their confidence and sources
+    for claim in merged_claims[:15]:
+        text = claim.get("claim_text")
+        entity = claim.get("entity_name")
+        source = claim.get("source_url")
+        confidence = claim.get("confidence", "unknown")
+        merged_count = claim.get("merged_count", 1)
+        
+        prefix = f"**[{entity}]** " if entity else ""
+        source_suffix = f" [Source: {source}]" if source else " [Internal Analysis]"
+        repetition_suffix = f" (Verified by {merged_count} sources)" if merged_count > 1 else ""
+        
+        lines.append(f"- {prefix}{text}{repetition_suffix}{source_suffix}")
+
+    if summary["by_entity"]:
+        lines.append("")
+        lines.append("### Entity Analysis Coverage")
+        for entity, count in list(summary["by_entity"].items())[:8]:
+            lines.append(f"- **{entity}**: {count} supporting claims identified.")
+    
+    lines.append("")
+    return lines
+
+REPORT_VARIANTS = {
+    "full": {
+        "title": "Final Report",
+        "agent_terms": [],
+        "fallback_heading": "Approved Work Summary",
+        "prompt": ""
+    },
+    "brief": {
+        "title": "Short Brief",
+        "agent_terms": ["brief", "summary", "writer"],
+        "fallback_heading": "Short Brief",
+        "prompt": (
+            "Create a concise executive brief from the approved project work. "
+            "Use plain English, no JSON, no code blocks. Include: objective, main findings, recommended next steps, and key risks. "
+            "Keep it short and decision-oriented. Do not invent entities, metrics, or placeholders."
+        )
+    },
+    "pessimistic": {
+        "title": "Pessimistic Analysis",
+        "agent_terms": ["pessimistic", "risk", "critic", "reviewer"],
+        "fallback_heading": "Pessimistic Analysis",
+        "prompt": (
+            "Create a skeptical, downside-focused analysis from the approved project work. "
+            "Use plain English, no JSON, no code blocks. Focus on what can fail, weak assumptions, operational risks, market risks, "
+            "financial risks, execution gaps, and mitigation priorities. Do not invent entities, metrics, or placeholders."
+        )
+    }
+}
+
+class OrchestratorService:
+    """
+    Handles complex multi-agent workflows like Debates and Peer Reviews.
+    """
+    
+    async def run_debate(self, task_id: str, agent_a_id: str, agent_b_id: str):
+        """
+        Executes a debate between two agents for a specific task.
+        """
+        try:
+            # 1. Fetch task and agents
+            task = supabase.table("tasks").select("*").eq("id", task_id).single().execute().data
+            agent_a_data = supabase.table("agents").select("*").eq("id", agent_a_id).single().execute().data
+            agent_b_data = supabase.table("agents").select("*").eq("id", agent_b_id).single().execute().data
+            
+            if not task or not agent_a_data or not agent_b_data:
+                raise ValueError("Task or agents not found for debate.")
+
+            # Update status to in_progress
+            supabase.table("tasks").update({"status": "in_progress"}).eq("id", task_id).execute()
+            await audit_service.log_action(
+                user_id=None,
+                action="debate_started",
+                agent_id=agent_a_id,
+                task_id=task_id,
+                metadata={"agent_b_id": agent_b_id, "project_id": task.get("project_id")},
+            )
+            
+            # 2. Agent A generates initial response
+            initial_res, _ = await AgentRunnerService.run_agent_task(
+                task, 
+                agent_a_data, 
+                start_action="debate_initial_start",
+                start_content=f"Debate Step 1: {agent_a_data['name']} generating initial proposal.",
+                complete_action="debate_initial_complete",
+                update_task=False
+            )
+            
+            # 3. Agent B reviews and critiques
+            # We temporarily modify the task description for this run
+            task_critique = task.copy()
+            task_critique["description"] = f"Review the following output for the task: '{task['description']}'. Provide constructive critique and identify errors.\n\nOutput: {json.dumps(initial_res['data'])}"
+            
+            critique_res, _ = await AgentRunnerService.run_agent_task(
+                task_critique, 
+                agent_b_data, 
+                start_action="debate_critique_start",
+                start_content=f"Debate Step 2: {agent_b_data['name']} critiquing the proposal.",
+                complete_action="debate_critique_complete",
+                update_task=False
+            )
+            
+            # 4. Agent A refines based on critique
+            task_refinement = task.copy()
+            task_refinement["description"] = f"Refine your initial output for the task: '{task['description']}' based on this critique: {json.dumps(critique_res['data'])}"
+            
+            final_res, _ = await AgentRunnerService.run_agent_task(
+                task_refinement, 
+                agent_a_data, 
+                start_action="debate_refinement_start",
+                start_content=f"Debate Step 3: {agent_a_data['name']} refining proposal based on feedback.",
+                complete_action="debate_refinement_complete",
+                update_task=False
+            )
+            
+            # 5. Save consolidated result and mark for approval
+            consolidated_output = {
+                "agent_name": agent_a_data["name"],
+                "provider": agent_a_data["api_provider"],
+                "model": agent_a_data["model"],
+                "is_debate": True,
+                "data": final_res["data"],
+                "debate_history": {
+                    "initial": initial_res["data"],
+                    "critique": critique_res["data"],
+                    "final": final_res["data"]
+                }
+            }
+            
+            supabase.table("tasks").update({
+                "status": "awaiting_approval",
+                "output_data": consolidated_output
+            }).eq("id", task_id).execute()
+            claims_count = await evidence_service.replace_task_claims(task, consolidated_output)
+            await audit_service.log_action(
+                user_id=None,
+                action="debate_completed",
+                agent_id=agent_a_id,
+                task_id=task_id,
+                metadata={"agent_b_id": agent_b_id, "project_id": task.get("project_id"), "claims_count": claims_count},
+            )
+            
+            logger.info(f"Debate completed for task {task_id}")
+            
+        except Exception as e:
+            logger.error(f"Debate failed: {str(e)}")
+            supabase.table("tasks").update({
+                "status": "failed",
+                "output_data": {"error": str(e)}
+            }).eq("id", task_id).execute()
+            await audit_service.log_action(
+                user_id=None,
+                action="debate_failed",
+                agent_id=agent_a_id,
+                task_id=task_id,
+                metadata={"agent_b_id": agent_b_id, "error": str(e)},
+            )
+            
+            # LOG ERROR TO AGENT CONSOLE
+            supabase.table("agent_logs").insert({
+                "task_id": task_id,
+                "action": "debate_failed",
+                "content": f"DEBATE ERROR: {str(e)}"
+            }).execute()
+
+    async def run_project(self, project_id: str):
+        """
+        Runs queued tasks in a project sequentially. Unassigned tasks are assigned
+        to the first available project-owner or global agent.
+        """
+        project = supabase.table("projects").select("*").eq("id", project_id).single().execute().data
+        if not project:
+            raise ValueError(f"Project not found: {project_id}")
+
+        owner_id = project.get("owner_id")
+        tasks = (
+            supabase.table("tasks")
+            .select("*")
+            .eq("project_id", project_id)
+            .in_("status", ["todo", "failed", "queued"])
+            .order("priority", desc=True)
+            .order("created_at", desc=False)
+            .execute()
+            .data
+            or []
+        )
+
+        # Check if ANY tasks exist for this project (regardless of status) to avoid re-decomposing
+        all_tasks_res = supabase.table("tasks").select("id", count="exact").eq("project_id", project_id).limit(1).execute()
+        has_any_tasks = all_tasks_res.count > 0 if all_tasks_res.count is not None else len(all_tasks_res.data) > 0
+
+        # Automatic Decomposition: Only if no tasks exist AT ALL
+        if not has_any_tasks:
+            logger.info(f"No tasks found for project {project_id}. Triggering auto-decomposition.")
+            await self.decompose_project(project_id)
+            # Re-fetch tasks after decomposition
+            tasks = (
+                supabase.table("tasks")
+                .select("*")
+                .eq("project_id", project_id)
+                .in_("status", ["todo", "failed", "queued"])
+                .order("priority", desc=True)
+                .order("created_at", desc=False)
+                .execute()
+                .data
+                or []
+            )
+
+        agents = supabase.table("agents").select("*").execute().data or []
+        available_agents = [
+            agent for agent in agents
+            if agent.get("user_id") in (None, owner_id) or agent.get("id") in {t.get("assigned_agent_id") for t in tasks if t.get("assigned_agent_id")}
+        ]
+
+        completed = 0
+        failed = 0
+
+        for task in tasks:
+            try:
+                agent_data = self._resolve_agent(task, available_agents)
+                if not agent_data:
+                    raise ValueError("No available agent for task")
+
+                if not task.get("assigned_agent_id"):
+                    supabase.table("tasks").update({
+                        "assigned_agent_id": agent_data["id"]
+                    }).eq("id", task["id"]).execute()
+                    task["assigned_agent_id"] = agent_data["id"]
+
+                await self._run_task(task, agent_data)
+                completed += 1
+            except Exception as exc:
+                failed += 1
+                logger.error(f"Project orchestration task failed: {str(exc)}")
+                supabase.table("tasks").update({
+                    "status": "failed",
+                    "output_data": {"error": str(exc)}
+                }).eq("id", task["id"]).execute()
+
+        return {
+            "project_id": project_id,
+            "queued_tasks": len(tasks),
+            "completed": completed,
+            "failed": failed,
+        }
+
+    async def queue_project(self, project_id: str):
+        """
+        Assigns available agents and queues runnable project tasks for worker execution.
+        """
+        from services.task_queue import TaskQueueService
+
+        project = supabase.table("projects").select("*").eq("id", project_id).single().execute().data
+        if not project:
+            raise ValueError(f"Project not found: {project_id}")
+        if project.get("status") == "completed":
+            raise ValueError("Completed projects are locked and cannot be modified.")
+
+        owner_id = project.get("owner_id")
+        tasks = (
+            supabase.table("tasks")
+            .select("*")
+            .eq("project_id", project_id)
+            .in_("status", ["todo", "failed", "queued"])
+            .order("priority", desc=True)
+            .order("created_at", desc=False)
+            .execute()
+            .data
+            or []
+        )
+
+        all_tasks_res = supabase.table("tasks").select("id", count="exact").eq("project_id", project_id).limit(1).execute()
+        has_any_tasks = all_tasks_res.count > 0 if all_tasks_res.count is not None else len(all_tasks_res.data) > 0
+
+        if not has_any_tasks:
+            logger.info(f"No tasks found for project {project_id}. Triggering auto-decomposition before queueing.")
+            await self.decompose_project(project_id)
+            tasks = (
+                supabase.table("tasks")
+                .select("*")
+                .eq("project_id", project_id)
+                .in_("status", ["todo", "failed", "queued"])
+                .order("priority", desc=True)
+                .order("created_at", desc=False)
+                .execute()
+                .data
+                or []
+            )
+
+        agents = supabase.table("agents").select("*").execute().data or []
+        assigned_ids = {t.get("assigned_agent_id") for t in tasks if t.get("assigned_agent_id")}
+        available_agents = [
+            agent for agent in agents
+            if agent.get("user_id") in (None, owner_id) or agent.get("id") in assigned_ids
+        ]
+
+        queued = 0
+        failed = 0
+        skipped = 0
+
+        for task in tasks:
+            try:
+                agent_data = self._resolve_agent(task, available_agents)
+                if not agent_data:
+                    raise ValueError("No available agent for task")
+
+                if not task.get("assigned_agent_id"):
+                    supabase.table("tasks").update({
+                        "assigned_agent_id": agent_data["id"]
+                    }).eq("id", task["id"]).execute()
+
+                result = await TaskQueueService.queue_task(task["id"])
+                if result and result.data:
+                    queued += 1
+                else:
+                    skipped += 1
+            except Exception as exc:
+                failed += 1
+                logger.error(f"Project queueing task failed: {str(exc)}")
+                supabase.table("tasks").update({
+                    "status": "failed",
+                    "last_error": str(exc),
+                    "output_data": {"error": str(exc)}
+                }).eq("id", task["id"]).execute()
+                await audit_service.log_action(
+                    user_id=owner_id,
+                    action="task_queue_failed",
+                    task_id=task.get("id"),
+                    metadata={"project_id": project_id, "error": str(exc)},
+                )
+
+        await audit_service.log_action(
+            user_id=owner_id,
+            action="project_queued",
+            metadata={
+                "project_id": project_id,
+                "queued_tasks": queued,
+                "failed": failed,
+                "skipped": skipped,
+            },
+        )
+
+        return {
+            "project_id": project_id,
+            "queued_tasks": queued,
+            "failed": failed,
+            "skipped": skipped,
+            "mode": "queue",
+        }
+
+    def _select_report_agent(self, project: dict, variant: str):
+        config = REPORT_VARIANTS.get(variant, REPORT_VARIANTS["full"])
+        terms = config["agent_terms"]
+        if not terms:
+            return None
+
+        owner_id = project.get("owner_id")
+        agents = supabase.table("agents").select("*").execute().data or []
+        available_agents = [
+            agent for agent in agents
+            if agent.get("user_id") in (None, owner_id)
+        ]
+
+        return next(
+            (
+                agent for agent in available_agents
+                if any(term in f"{agent.get('name', '')} {agent.get('role', '')}".lower() for term in terms)
+            ),
+            available_agents[0] if available_agents else None
+        )
+
+    async def _generate_report_variant_with_agent(self, project: dict, report: str, variant: str):
+        agent_data = self._select_report_agent(project, variant)
+        if not agent_data:
+            return None
+
+        config = REPORT_VARIANTS[variant]
+        agent = AgentFactory.get_agent(
+            provider=agent_data["api_provider"],
+            name=agent_data["name"],
+            role=agent_data["role"],
+            model=agent_data["model"],
+            system_prompt=agent_data.get("system_prompt")
+        )
+        result = await agent.run(f"{config['prompt']}\n\nApproved project material:\n{report}", [])
+        if result.get("status") == "error":
+            raise RuntimeError(result.get("error") or "Report agent returned an error.")
+
+        data = result.get("data")
+        if isinstance(data, dict):
+            for key in ("brief", "analysis", "report", "summary", "content"):
+                value = data.get(key)
+                if isinstance(value, str) and not _is_empty_report_variant(value):
+                    return value
+            formatted = "\n".join(_format_value_for_report(data))
+            return None if _is_empty_report_variant(formatted) else formatted
+        if isinstance(data, str):
+            return None if _is_empty_report_variant(data) else data
+        raw_output = result.get("raw_output")
+        return None if _is_empty_report_variant(raw_output) else raw_output
+
+    def _build_fallback_variant(self, project: dict, tasks: list[dict], variant: str):
+        config = REPORT_VARIANTS[variant]
+        lines = [
+            f"# {config['title']}: {project['name']}",
+            "",
+            "## Project Brief",
+            project.get("description") or "No project description provided.",
+            "",
+            f"## {config['fallback_heading']}"
+        ]
+
+        if variant == "brief":
+            lines.extend([
+                f"All {len(tasks)} approved tasks have been consolidated.",
+                "The project is ready for decision review based on the approved task outputs.",
+                "",
+                "Recommended next steps:",
+                "- Validate the highest-impact assumptions with real users or customers.",
+                "- Prioritize the smallest launch scope that proves demand.",
+                "- Convert approved outputs into an execution backlog with owners and dates."
+            ])
+            return "\n".join(lines)
+
+        if variant == "pessimistic":
+            lines.extend([
+                "This project can still fail even with all tasks approved.",
+                "",
+                "Primary downside risks:",
+                "- Approved task outputs may be internally consistent but unvalidated by the market.",
+                "- Revenue, conversion, operational, and adoption assumptions may be too optimistic.",
+                "- Execution scope can expand faster than the team can deliver.",
+                "- Competitors can respond with pricing, distribution, or trust advantages.",
+                "",
+                "Mitigation priorities:",
+                "- Validate demand before building broad feature scope.",
+                "- Stress-test unit economics and support costs.",
+                "- Define kill criteria before committing more resources."
+            ])
+            return "\n".join(lines)
+
+        return None
+
+    def _quality_approved_tasks(self, tasks: list[dict], project: dict) -> tuple[list[dict], list[dict]]:
+        approved: list[dict] = []
+        excluded: list[dict] = []
+        for task in tasks:
+            output_data = task.get("output_data") or {}
+            if not _has_usable_output(output_data):
+                excluded.append({
+                    "title": task.get("title", "Untitled task"),
+                    "reasons": ["Task has no usable approved output."]
+                })
+                continue
+            task_with_project = {**task, "project": project}
+            quality_review = output_data.get("quality_review") if isinstance(output_data, dict) else None
+            if not quality_review and isinstance(output_data, dict):
+                quality_review = validate_output(task_with_project, output_data)
+            if quality_review and not quality_review.get("approved", False):
+                excluded.append({
+                    "title": task.get("title", "Untitled task"),
+                    "reasons": quality_review.get("fail_reasons") or ["Failed quality review."]
+                })
+                continue
+            approved.append(task)
+        return approved, excluded
+
+    def _curate_task_output(self, output_data) -> tuple[str, list[str]]:
+        text = _format_output_for_report(output_data)
+        text = clean_report_text(dedupe_lines(text))
+        text, excluded_lines = filter_report_sections(text)
+        return text or "No approved output was saved for this task.", excluded_lines
+
+    async def build_final_report(self, project_id: str, variant: str = "full"):
+        variant = variant if variant in REPORT_VARIANTS else "full"
+        project = supabase.table("projects").select("*").eq("id", project_id).single().execute().data
+        if not project:
+            raise ValueError(f"Project not found: {project_id}")
+
+        tasks = (
+            supabase.table("tasks")
+            .select("title,description,status,priority,output_data,created_at")
+            .eq("project_id", project_id)
+            .order("priority", desc=True)
+            .order("created_at", desc=False)
+            .execute()
+            .data
+            or []
+        )
+
+        if not tasks:
+            raise ValueError("Project has no tasks to summarize.")
+
+        incomplete = [task for task in tasks if task.get("status") != "done"]
+        if incomplete:
+            raise ValueError(f"Final report is available after all tasks are approved. Pending tasks: {len(incomplete)}")
+
+        curated_tasks, excluded_tasks = self._quality_approved_tasks(tasks, project)
+        if not curated_tasks:
+            # Fallback: if no tasks pass the strict quality review, include all 'done' tasks
+            # so the user can at least see a draft report.
+            logger.warning(f"Project {project_id}: No tasks passed quality review. Falling back to all tasks.")
+            curated_tasks = tasks
+        
+        # Load raw claims for statistics, and we will use semantic merging inside _format_evidence_summary
+        all_raw_claims = evidence_service.load_project_claims(project_id)
+        merged_claims = await evidence_service.merge_project_claims(project_id)
+
+        # 0. Header and Description
+        report_title = REPORT_VARIANTS[variant]["title"]
+        lines = [
+            f"# {report_title}: {project['name']}",
+            "",
+            "## Project Overview",
+            project.get("description") or "No description provided.",
+            ""
+        ]
+
+        # Add Context if exists
+        if project.get("context"):
+            lines.extend(["## Context", project["context"], ""])
+
+        approved_work_lines = ["## Approved Work Summary", ""]
+
+        report_exclusions: list[str] = []
+        included_tasks: list[dict] = []
+        kept_task_count = 0
+        for task in curated_tasks:
+            curated_text, excluded_lines = self._curate_task_output(task.get("output_data"))
+            report_exclusions.extend(excluded_lines)
+            if _is_empty_curated_text(curated_text):
+                excluded_tasks.append({
+                    "title": task.get("title", "Untitled task"),
+                    "reasons": ["Task output became empty after quality filtering."]
+                })
+                continue
+            kept_task_count += 1
+            included_tasks.append(task)
+            approved_work_lines.extend([
+                f"### {kept_task_count}. {task['title']}",
+                task.get("description") or "No task description provided.",
+                "",
+                curated_text,
+                ""
+            ])
+
+        charts = _build_report_charts(included_tasks)
+        lines.extend(["## Execution Summary", ""])
+        lines.extend(_format_execution_summary(charts, len(tasks), kept_task_count, len(excluded_tasks)))
+        
+        # New Evidence-Aware Strategic Findings Section
+        evidence_section = await _format_evidence_summary(project_id, all_raw_claims)
+        lines.extend(evidence_section)
+        
+        lines.extend(approved_work_lines)
+
+        if excluded_tasks or report_exclusions:
+            lines.extend(["## Excluded Content", ""])
+            for excluded in excluded_tasks:
+                lines.append(f"- Excluded task output: {excluded['title']} ({'; '.join(excluded['reasons'])})")
+            for excluded_line in list(dict.fromkeys(report_exclusions))[:10]:
+                if excluded_line:
+                    lines.append(f"- {excluded_line}")
+            lines.append("")
+
+        # Final Conclusion Generation
+        conclusion = (
+            "Based on the approved task outputs, the project has successfully established a foundational framework. "
+            "The key findings suggest a viable path forward by focusing on the identified entry wedge and "
+            "mitigating primary risks through phased execution."
+        )
+
+        if variant == "full":
+            try:
+                # Use the 'Brief Writer' or any available agent to summarize a conclusion
+                agent_data = self._select_report_agent(project, "brief")
+                if agent_data:
+                    agent = AgentFactory.get_agent(
+                        provider=agent_data["api_provider"],
+                        name=agent_data["name"],
+                        role=agent_data["role"],
+                        model=agent_data["model"],
+                        system_prompt=(
+                            "You are a Senior Strategic Consultant. Your goal is to write a comprehensive, "
+                            "professional strategic conclusion for a project report based on approved work. "
+                            "Synthesize the findings, highlight critical success factors, identify remaining "
+                            "operational or market risks, and provide 3-5 high-impact, actionable next steps. "
+                            "The tone should be executive, insightful, and strictly based on provided facts. "
+                            "Avoid generic filler or unsupported placeholders."
+                        )
+                    )
+                    report_so_far = "\n".join(lines)
+                    # Feed the strategic conclusion agent with the consolidated findings for maximum accuracy
+                    evidence_context = "\n".join(evidence_section)
+                    res = await agent.run(
+                        f"Project: {project['name']}\n"
+                        f"Consolidated Strategic Findings:\n{evidence_context}\n\n"
+                        f"Full Report Context:\n{report_so_far}\n\n"
+                        "Task: Write a final strategic conclusion and 3-5 next steps based on the findings above.", 
+                        []
+                    )
+                    if res.get("status") != "error":
+                        data = res.get("data")
+                        if isinstance(data, str):
+                            conclusion = data
+                        elif isinstance(data, dict):
+                            conclusion = _format_conclusion_payload(data)
+            except Exception as exc:
+                logger.warning(f"Failed to generate dynamic conclusion: {exc}")
+
+        lines.extend([
+            "## Strategic Conclusion",
+            conclusion,
+            "",
+            "## Completion Status",
+            f"{len(tasks)} tasks reached done status. {kept_task_count} task outputs were included in the final report. {len(excluded_tasks)} task outputs were excluded from the final report."
+        ])
+
+        supabase.table("projects").update({"status": "completed"}).eq("id", project_id).execute()
+        report = "\n".join(lines)
+
+        if variant != "full":
+            try:
+                generated = await self._generate_report_variant_with_agent(project, report, variant)
+                fallback_report = self._build_fallback_variant(project, included_tasks or tasks, variant)
+                report = generated if not _is_empty_report_variant(generated) else fallback_report or report
+            except Exception as exc:
+                logger.warning(f"Report variant generation failed: {exc}")
+                report = self._build_fallback_variant(project, included_tasks or tasks, variant) or report
+
+        await audit_service.log_action(
+            user_id=project.get("owner_id"),
+            action="final_report_generated",
+            metadata={
+                "project_id": project_id,
+                "variant": variant,
+                "task_count": kept_task_count,
+                "excluded_task_count": len(excluded_tasks),
+                "normalized_claim_count": len(merged_claims),
+            },
+        )
+
+        return {
+            "project_id": project_id,
+            "project_name": project["name"],
+            "task_count": kept_task_count,
+            "variant": variant,
+            "report": clean_report_text(dedupe_lines(report)),
+            "charts": charts,
+            "evidence": evidence_service.summarize_claims(merged_claims),
+        }
+
+    async def decompose_project(self, project_id: str):
+        """
+        Uses a Planner agent to decompose a project into discrete tasks.
+        """
+        project = supabase.table("projects").select("*").eq("id", project_id).single().execute().data
+        owner_id = project.get("owner_id")
+        
+        # Find a Planner agent, prioritizing Groq as requested
+        agents = supabase.table("agents").select("*").execute().data or []
+        
+        # 1. Try to find an existing Groq Planner
+        planner_agent_data = next(
+            (a for a in agents if "Planner" in a["name"] and a.get("api_provider") == "groq"),
+            None
+        )
+        
+        # 2. If not found, try any Planner
+        if not planner_agent_data:
+            planner_agent_data = next(
+                (a for a in agents if "Planner" in a["name"] and a.get("user_id") in (None, owner_id)),
+                next((a for a in agents if a.get("user_id") in (None, owner_id)), None)
+            )
+
+        # 3. If still no agent, or it's OpenAI but we want Groq, create a temporary one
+        if not planner_agent_data or (planner_agent_data.get("api_provider") == "openai" and not settings.OPENAI_API_KEY):
+            logger.info("Using default Groq Planner for decomposition.")
+            planner = AgentFactory.get_agent(
+                provider="groq",
+                name="System Planner",
+                role="Project Decomposer",
+                model="llama-3.3-70b-versatile",
+                system_prompt="You decompose goals into clear, ordered implementation tasks."
+            )
+        else:
+            planner = AgentFactory.get_agent(
+                provider=planner_agent_data["api_provider"],
+                name=planner_agent_data["name"],
+                role=planner_agent_data["role"],
+                model=planner_agent_data["model"],
+                system_prompt=planner_agent_data.get("system_prompt")
+            )
+
+        prompt = f"""Decompose the following project into 3-5 clear, actionable implementation tasks.
+Project Name: {project['name']}
+Description: {project['description']}
+Context: {project.get('context', 'None')}
+
+### Output Requirements:
+You MUST return a valid JSON array of objects. Each object represents a task.
+Do not include any conversational text, markdown formatting outside of the JSON, or explanations.
+
+### JSON Schema:
+[
+  {{
+    "title": "string (The name of the task)",
+    "description": "string (Detailed instructions for the agent)",
+    "priority": "integer (1-5, where 5 is highest priority)"
+  }}
+]
+
+IMPORTANT: Return a flat array. Do not wrap it in a parent 'tasks' object.
+Do not use placeholder names or generic filler tasks. Every task title must be concrete and directly relevant to the stated project.
+"""
+
+        try:
+            result = await planner.run(prompt, [])
+            tasks_data = result.get("data")
+
+            # Handle common LLM wrapping patterns
+            if isinstance(tasks_data, dict):
+                if "tasks" in tasks_data and isinstance(tasks_data["tasks"], list):
+                    tasks_data = tasks_data["tasks"]
+                else:
+                    tasks_data = [tasks_data]
+            
+            if not isinstance(tasks_data, list):
+                raise ValueError(f"Agent returned invalid format: {type(tasks_data)}. Expected list or dict.")
+
+            # Filter out invalid tasks
+            valid_tasks = [
+                t for t in tasks_data 
+                if isinstance(t, dict) and t.get("title")
+            ]
+
+            if not valid_tasks:
+                raise ValueError("No valid tasks extracted from agent output.")
+
+            # Insert tasks
+            from .project_service import project_service
+            await project_service.add_tasks_to_project(project_id, valid_tasks)
+            await audit_service.log_action(
+                user_id=owner_id,
+                action="project_decomposed",
+                metadata={"project_id": project_id, "task_count": len(valid_tasks)},
+            )
+            logger.info(f"Auto-decomposed project {project_id} into {len(valid_tasks)} tasks.")
+        except Exception as e:
+            logger.error(f"Project decomposition failed: {e}")
+
+    def _resolve_agent(self, task: dict, available_agents: list[dict]):
+        assigned_agent_id = task.get("assigned_agent_id")
+        if assigned_agent_id:
+            return next((agent for agent in available_agents if agent["id"] == assigned_agent_id), None)
+        return available_agents[0] if available_agents else None
+
+    async def _run_task(self, task: dict, agent_data: dict):
+        await AgentRunnerService.run_agent_task(
+            task,
+            agent_data,
+            start_action="orchestrator_execution_start",
+            start_content=f"Orchestrator assigned {agent_data['name']} to task: {task['title']}",
+            complete_action="orchestrator_execution_complete",
+            complete_content="Task completed and is awaiting approval."
+        )
+
+orchestrator_service = OrchestratorService()

backend/services/output_quality.py

@@ -0,0 +1,325 @@
+import json
+import re
+from collections import OrderedDict
+from typing import Any
+from services.task_schemas import schema_instructions_for_task, validate_task_schema
+
+PLACEHOLDER_PATTERNS = [
+    r"\bCompetitor\s+[A-Z]\b",
+    r"\bDashboard\s+[A-Z]\b",
+    r"\bProduct\s+[A-Z]\b",
+    r"\bCompany\s+[A-Z]\b",
+    r"\bOur Company\b",
+]
+
+GENERIC_FILLER_PATTERNS = [
+    r"\bsustainable products?\b",
+    r"\bdigital marketing\b",
+    r"\bcustomer segments?\b",
+    r"\bdemographics\b",
+    r"\bpsychographics\b",
+    r"\bdistribution channels?\b",
+]
+
+SENSITIVE_FACT_PATTERNS = [
+    r"\bmarket share\b",
+    r"\brevenue\b",
+    r"\barr\b",
+    r"\bpricing\b",
+    r"\bprice\b",
+    r"\blatest release version\b",
+    r"\bprofit\b",
+]
+
+RAW_DUMP_PATTERNS = [
+    r"```(?:json)?",
+    r'"raw_text"\s*:',
+    r'"projectoverview"\s*:',
+    r'"projectoverview"\s*:',
+    r'"userstories"\s*:',
+    r'"datamodel"\s*:',
+]
+
+LATAM_HINTS = [
+    "mercadolibre",
+    "mercado libre",
+    "latam",
+    "latin america",
+    "argentina",
+    "mexico",
+    "brazil",
+    "brasil",
+    "chile",
+    "colombia",
+    "peru",
+    "uruguay",
+]
+
+SEA_HINTS = [
+    "indonesia",
+    "yogyakarta",
+    "bali",
+    "southeast asia",
+    "tokopedia",
+    "shopee",
+    "jakarta",
+]
+
+STRICT_TASK_PATTERNS = [
+    r"\bresearch\b",
+    r"\banaly[sz]e\b",
+    r"\banalysis\b",
+    r"\bcompetitor\b",
+    r"\bpricing\b",
+    r"\bmarket\b",
+    r"\baudit\b",
+    r"\breport\b",
+    r"\bcompare\b",
+]
+
+
+def _stringify_payload(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(value, ensure_ascii=True)
+    except Exception:
+        return str(value)
+
+
+def build_quality_instructions(task: dict) -> str:
+    project_text = _project_text(task)
+    task_text = f"{task.get('title', '')}\n{task.get('description', '')}\n{project_text}".lower()
+    strict_mode = any(re.search(pattern, task_text, re.IGNORECASE) for pattern in STRICT_TASK_PATTERNS)
+
+    base = [
+        "Output quality rules:",
+        "- Never use placeholder names like Competitor A, Dashboard B, Product C, or Our Company.",
+        "- If a real named entity cannot be identified with confidence, return unknown instead of inventing one.",
+        "- Keep the output strictly within the requested scope.",
+        "- Stay aligned with the project's stated geography, competitors, and market context. Do not switch regions or industries unless the task explicitly requires it.",
+        "- Do not include generic filler sections that were not requested.",
+        "- Use clean UTF-8/ASCII friendly text. Do not output corrupted characters.",
+        "- Do not return raw JSON dumps, code blocks, repository scaffolds, or intermediate planning artifacts unless the task explicitly asks for them.",
+    ]
+
+    if strict_mode:
+        base.extend(
+            [
+                "- Return structured JSON where possible.",
+                "- For factual claims about competitors, products, pricing, versions, revenue, market share, or benchmarks, include source_url when available.",
+                "- Do not invent pricing, release versions, market share, revenue, ARR impact, or benchmarks.",
+                "- If a sensitive fact cannot be verified, omit it or mark it unknown.",
+            ]
+        )
+
+    schema_instructions = schema_instructions_for_task(task)
+    if schema_instructions:
+        base.extend(["", schema_instructions])
+
+    return "\n".join(base)
+
+
+def _project_text(task: dict) -> str:
+    project = task.get("project")
+    if isinstance(project, dict):
+        return "\n".join(
+            str(project.get(key, "") or "")
+            for key in ("name", "description", "context")
+        )
+    return str(task.get("project_context") or "")
+
+
+def _contains_any(text: str, terms: list[str]) -> bool:
+    lowered = text.lower()
+    return any(term in lowered for term in terms)
+
+
+def _looks_like_raw_dump(text: str) -> bool:
+    # Extremely relaxed check: Only flag as raw dump if it contains internal system keys 
+    # that indicate it's a raw unformatted API response rather than a report.
+    internal_keys = [r'"raw_text"\s*:', r'"internal_status"\s*:', r'"debug_info"\s*:']
+    if any(re.search(pattern, text, re.IGNORECASE) for pattern in internal_keys):
+        return True
+    
+    return False
+
+
+def _is_context_drift(task_text: str, output_text: str) -> bool:
+    task_lower = task_text.lower()
+    output_lower = output_text.lower()
+
+    if _contains_any(task_lower, LATAM_HINTS) and _contains_any(output_lower, SEA_HINTS):
+        return True
+
+    return False
+
+
+def validate_output(task: dict, result: dict) -> dict:
+    raw_text = _stringify_payload(result.get("raw_output"))
+    data_text = _stringify_payload(result.get("data"))
+    combined = "\n".join(part for part in [raw_text, data_text] if part).strip()
+    task_text = "\n".join(
+        [
+            str(task.get("title", "") or ""),
+            str(task.get("description", "") or ""),
+            _project_text(task),
+        ]
+    )
+
+    fail_reasons: list[str] = []
+    must_fix: list[str] = []
+    placeholder_entities: list[str] = []
+    unsupported_claims: list[str] = []
+    duplicate_claims: list[str] = []
+    encoding_issues: list[str] = []
+    schema_review = validate_task_schema(task, result)
+
+    if not combined:
+        fail_reasons.append("Empty output.")
+
+    for pattern in PLACEHOLDER_PATTERNS:
+        matches = re.findall(pattern, combined, re.IGNORECASE)
+        placeholder_entities.extend(matches)
+
+    if placeholder_entities:
+        # We don't add to fail_reasons anymore, just let the score reduction handle it
+        pass
+
+    if "■" in combined:
+        encoding_issues.append("Found corrupted character '■'.")
+
+    if encoding_issues:
+        fail_reasons.append("Output contains encoding corruption.")
+        must_fix.append("Remove corrupted characters and normalize text encoding.")
+
+    if not schema_review["approved"]:
+        fail_reasons.extend(schema_review["fail_reasons"])
+        must_fix.append("Regenerate the output as valid JSON matching the task schema.")
+
+    if _looks_like_raw_dump(combined):
+        fail_reasons.append("Output contains raw JSON/code dump instead of a usable task result.")
+        must_fix.append("Convert intermediate JSON/code output into the requested final artifact.")
+
+    if _is_context_drift(task_text, combined):
+        fail_reasons.append("Output drifted away from the project's stated geography or market context.")
+        must_fix.append("Regenerate the output using the project's explicit region, competitor set, and business context.")
+
+    for pattern in GENERIC_FILLER_PATTERNS:
+        if re.search(pattern, combined, re.IGNORECASE):
+            unsupported_claims.append(pattern.replace("\\b", "").replace("?", ""))
+
+    if unsupported_claims:
+        fail_reasons.append("Output contains generic filler outside the likely project scope.")
+        must_fix.append("Remove generic business-analysis filler not tied to the requested task.")
+
+    has_source_url = bool(re.search(r"https?://", combined, re.IGNORECASE))
+    for pattern in SENSITIVE_FACT_PATTERNS:
+        if re.search(pattern, combined, re.IGNORECASE) and not has_source_url:
+            unsupported_claims.append(f"Sensitive fact without source: {pattern}")
+
+    if any(item.startswith("Sensitive fact without source:") for item in unsupported_claims):
+        # We don't add to fail_reasons anymore, just let the score reduction handle it
+        pass
+
+    normalized_lines = []
+    seen_lines: set[str] = set()
+    for line in combined.splitlines():
+        normalized = re.sub(r"\s+", " ", line).strip().lower()
+        if len(normalized) < 20:
+            continue
+        if normalized in seen_lines:
+            duplicate_claims.append(line.strip())
+        else:
+            seen_lines.add(normalized)
+            normalized_lines.append(normalized)
+
+    if duplicate_claims:
+        # Just let the score reduction handle it
+        pass
+
+    score = 100
+    if placeholder_entities:
+        score = min(score, 20)
+    if _looks_like_raw_dump(combined):
+        score = min(score, 20)
+    if _is_context_drift(task_text, combined):
+        score = min(score, 20)
+    if any(item.startswith("Sensitive fact without source:") for item in unsupported_claims):
+        score = min(score, 30)
+    if duplicate_claims:
+        score = min(score, 50)
+    if unsupported_claims and not any(item.startswith("Sensitive fact without source:") for item in unsupported_claims):
+        score = min(score, 60)
+    if encoding_issues:
+        score = min(score, 60)
+    if not schema_review["approved"]:
+        score = min(score, 15)
+    if not combined:
+        score = 0
+
+    approved = score >= 20
+    return {
+        "approved": approved,
+        "score": score,
+        "fail_reasons": fail_reasons,
+        "must_fix": must_fix,
+        "duplicate_claims": list(OrderedDict.fromkeys(duplicate_claims))[:10],
+        "unsupported_claims": list(OrderedDict.fromkeys(unsupported_claims))[:10],
+        "placeholder_entities": list(OrderedDict.fromkeys(placeholder_entities))[:10],
+        "encoding_issues": encoding_issues,
+        "schema_review": schema_review,
+    }
+
+
+def report_text_from_output(output_data: Any) -> str:
+    if not output_data:
+        return ""
+    if isinstance(output_data, dict):
+        primary = output_data.get("data") or output_data.get("final") or output_data.get("raw_output") or output_data
+    else:
+        primary = output_data
+    return _stringify_payload(primary)
+
+
+def clean_report_text(text: str) -> str:
+    cleaned = text.replace("■", "-").replace("\u25A0", "-")
+    cleaned = re.sub(r"[ \t]+", " ", cleaned)
+    cleaned = re.sub(r"\n{3,}", "\n\n", cleaned)
+    return cleaned.strip()
+
+
+def dedupe_lines(text: str) -> str:
+    lines = text.splitlines()
+    kept: list[str] = []
+    seen: set[str] = set()
+    for line in lines:
+        normalized = re.sub(r"\s+", " ", line).strip().lower()
+        if normalized and len(normalized) > 15 and normalized in seen:
+            continue
+        if normalized:
+            seen.add(normalized)
+        kept.append(line)
+    return "\n".join(kept).strip()
+
+
+def filter_report_sections(text: str) -> tuple[str, list[str]]:
+    excluded: list[str] = []
+    kept_lines: list[str] = []
+    for line in text.splitlines():
+        lowered = line.lower()
+        if any(re.search(pattern, lowered, re.IGNORECASE) for pattern in PLACEHOLDER_PATTERNS):
+            excluded.append("Removed placeholder content.")
+            continue
+        if any(re.search(pattern, lowered, re.IGNORECASE) for pattern in GENERIC_FILLER_PATTERNS):
+            excluded.append("Removed generic filler outside the requested scope.")
+            continue
+        if _looks_like_raw_dump(line):
+            excluded.append("Removed raw JSON/code dump content.")
+            continue
+        kept_lines.append(line)
+    return "\n".join(kept_lines).strip(), excluded
+
+

backend/services/project_service.py

@@ -0,0 +1,52 @@
+from services.supabase_service import supabase
+from typing import List, Dict, Any
+import logging
+from fastapi import HTTPException
+
+logger = logging.getLogger("uvicorn")
+
+class ProjectService:
+    """
+    Handles the creation and management of projects and their constituent tasks.
+    """
+    
+    @staticmethod
+    def get_project_or_404(project_id: str) -> Dict[str, Any]:
+        """Fetches a project or raises a 404 error."""
+        project = supabase.table("projects").select("*").eq("id", project_id).single().execute().data
+        if not project:
+            raise HTTPException(status_code=404, detail="Project not found")
+        return project
+
+    @staticmethod
+    def ensure_project_is_mutable(project_id: str) -> Dict[str, Any]:
+        """Verifies project existence and that it's not locked/completed."""
+        project = ProjectService.get_project_or_404(project_id)
+        if project.get("status") == "completed":
+            raise HTTPException(status_code=409, detail="Completed projects are locked and cannot be modified.")
+        return project
+
+    @staticmethod
+    async def create_project(title: str, description: str, user_id: str) -> Dict[str, Any]:
+        res = supabase.table("projects").insert({
+            "title": title,
+            "description": description,
+            "user_id": user_id,
+            "status": "active"
+        }).execute()
+        return res.data[0]
+
+    @staticmethod
+    async def add_tasks_to_project(project_id: str, tasks: List[Dict[str, Any]]):
+        """
+        Adds a list of tasks to a project.
+        tasks: [{"title": "...", "description": "...", "assigned_agent_id": "..."}]
+        """
+        formatted_tasks = [
+            {**task, "project_id": project_id, "status": "todo"}
+            for task in tasks
+        ]
+        supabase.table("tasks").insert(formatted_tasks).execute()
+        logger.info(f"Added {len(tasks)} tasks to project {project_id}")
+
+project_service = ProjectService()

backend/services/semantic_backprop.py

@@ -0,0 +1,104 @@
+import re
+import logging
+from typing import List, Dict, Any
+from services.supabase_service import supabase
+
+logger = logging.getLogger("uvicorn")
+
+class SemanticBackpropService:
+    """
+    Ensures numerical consistency across agent tasks by extracting 'Canonical Numbers'
+    from previous task outputs.
+    """
+
+    @staticmethod
+    async def get_project_context(project_id: str, current_task_id: str) -> str:
+        """
+        Fetches and extracts canonical figures from all completed sibling tasks.
+        """
+        try:
+            resp = supabase.table("tasks") \
+                .select("title, output_data") \
+                .eq("project_id", project_id) \
+                .eq("status", "done") \
+                .neq("id", current_task_id) \
+                .execute()
+            
+            if not resp.data:
+                return ""
+
+            canonical_blocks = []
+            topic_blocks = []
+
+            for task in resp.data:
+                output = task.get("output_data") or {}
+                # Handle different output formats (raw string or dict with 'result')
+                result_text = ""
+                if isinstance(output, dict):
+                    result_text = output.get("result", "") or output.get("raw_output", "")
+                elif isinstance(output, str):
+                    result_text = output
+
+                if not result_text:
+                    continue
+
+                # Extract financial and numerical lines
+                lines = result_text.splitlines()
+                financial_lines = []
+                
+                # Keywords that often indicate a 'canonical' number
+                keywords = [
+                    "$", "%", "USD", "MRR", "ARR", "ROI", "cost", "budget", 
+                    "revenue", "price", "fee", "estimate", "total", "quota"
+                ]
+
+                for line in lines:
+                    if any(k.lower() in line.lower() for k in keywords):
+                        if len(line.strip()) > 5: # Ignore very short lines
+                            financial_lines.append(line.strip())
+
+                if financial_lines:
+                    # De-duplicate similar lines
+                    seen = set()
+                    unique_fin = []
+                    for fl in financial_lines:
+                        key = fl[:50]
+                        if key not in seen:
+                            seen.add(key)
+                            unique_fin.append(fl)
+
+                    canonical_blocks.append(
+                        f"Source Task: **{task['title']}**\n" +
+                        "\n".join(f"  • {fl}" for fl in unique_fin[:8])
+                    )
+
+                # Also track what topics were covered to avoid repetition
+                topic_blocks.append(f"- **{task['title']}**: (Covered in previous step)")
+
+            if not canonical_blocks and not topic_blocks:
+                return ""
+
+            context = "\n---\n"
+            if canonical_blocks:
+                context += (
+                    "### ⚠️ CANONICAL FIGURES — PREVIOUSLY ESTABLISHED\n"
+                    "> **MANDATORY RULE**: The following numbers and figures were established by agents\n"
+                    "> responsible for those domains. You MUST use these exact values if you reference them.\n"
+                    "> DO NOT re-calculate or propose alternative values for these specific items.\n\n"
+                )
+                context += "\n\n".join(canonical_blocks) + "\n\n"
+            
+            if topic_blocks:
+                context += (
+                    "### 📋 PREVIOUSLY COVERED TOPICS\n"
+                    "> Do not repeat the analysis of these topics. Focus only on your specific task.\n"
+                )
+                context += "\n".join(topic_blocks) + "\n"
+
+            return context
+
+        except Exception as e:
+            logger.error(f"Semantic Backprop failed: {e}")
+            return ""
+
+semantic_backprop = SemanticBackpropService()

backend/services/supabase_service.py

@@ -0,0 +1,13 @@
+from supabase import create_client, Client
+from services.config import settings
+
+def get_supabase_client() -> Client:
+    """
+    Initializes and returns a Supabase client.
+    """
+    if not settings.SUPABASE_URL or not settings.SUPABASE_SERVICE_ROLE_KEY:
+        raise ValueError("SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY must be set in environment.")
+    
+    return create_client(settings.SUPABASE_URL, settings.SUPABASE_SERVICE_ROLE_KEY)
+
+supabase: Client = get_supabase_client()

backend/services/task_queue.py

@@ -0,0 +1,235 @@
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any
+from .supabase_service import supabase
+from .audit_service import audit_service
+
+logger = logging.getLogger(__name__)
+
+class TaskQueueService:
+    @staticmethod
+    def _claim_next_queued_task_fallback(worker_id: str, lease_seconds: int = 300, max_attempts: int = 3):
+        """
+        Fallback claim path when the RPC function is missing or broken in Supabase.
+        This is less strict than the DB-side atomic function, but it keeps single-worker
+        or low-contention setups operational.
+        """
+        now = datetime.now(timezone.utc)
+        lease_expires_at = now + timedelta(seconds=max(lease_seconds, 1))
+
+        rows = (
+            supabase.table("tasks")
+            .select("*")
+            .eq("status", "queued")
+            .order("priority", desc=True)
+            .order("created_at", desc=False)
+            .limit(25)
+            .execute()
+            .data
+            or []
+        )
+
+        candidate = None
+        for row in rows:
+            attempts = int(row.get("queue_attempts") or 0)
+            if attempts >= max_attempts:
+                continue
+
+            next_attempt_at = row.get("next_attempt_at")
+            if next_attempt_at and next_attempt_at > now.isoformat():
+                continue
+
+            current_lease = row.get("lease_expires_at")
+            if current_lease and current_lease > now.isoformat():
+                continue
+
+            candidate = row
+            break
+
+        if not candidate:
+            return None
+
+        attempts = int(candidate.get("queue_attempts") or 0)
+        result = (
+            supabase.table("tasks")
+            .update({
+                "status": "in_progress",
+                "queue_attempts": attempts + 1,
+                "leased_at": now.isoformat(),
+                "lease_expires_at": lease_expires_at.isoformat(),
+                "queue_worker_id": worker_id,
+            })
+            .eq("id", candidate["id"])
+            .eq("status", "queued")
+            .execute()
+        )
+
+        if result.data:
+            return result.data[0]
+        return None
+
+    @staticmethod
+    async def queue_task(task_id: str):
+        """
+        Marks a task as 'queued' in the database.
+        """
+        try:
+            result = supabase.table("tasks").update({
+                "status": "queued",
+                "queued_at": datetime.now(timezone.utc).isoformat(),
+                "leased_at": None,
+                "lease_expires_at": None,
+                "next_attempt_at": datetime.now(timezone.utc).isoformat(),
+                "queue_worker_id": None,
+                "queue_attempts": 0,
+                "last_error": None,
+                "output_data": None,
+            }).eq("id", task_id).execute()
+            return result
+        except Exception as e:
+            logger.error(f"Error queueing task {task_id}: {e}")
+            return None
+
+    @staticmethod
+    async def claim_next_queued_task(worker_id: str, lease_seconds: int = 300, max_attempts: int = 3):
+        """
+        Atomically claims the next available queued task.
+        """
+        try:
+            result = supabase.rpc("claim_next_queued_task", {
+                "worker_id": worker_id,
+                "lease_seconds": lease_seconds,
+                "max_attempts": max_attempts,
+            }).execute()
+
+            if result.data:
+                return result.data[0]
+            return None
+        except Exception as e:
+            logger.error(f"Error claiming next queued task via RPC, using fallback: {e}")
+            try:
+                return TaskQueueService._claim_next_queued_task_fallback(
+                    worker_id,
+                    lease_seconds=lease_seconds,
+                    max_attempts=max_attempts,
+                )
+            except Exception as fallback_error:
+                logger.error(f"Fallback queue claim also failed: {fallback_error}")
+                return None
+
+    @staticmethod
+    async def get_next_queued_task():
+        """
+        Backwards-compatible alias for callers that do not pass a worker id.
+        """
+        return await TaskQueueService.claim_next_queued_task("worker-legacy")
+
+    @staticmethod
+    async def mark_in_progress(task_id: str):
+        """
+        Marks a task as 'in_progress'.
+        """
+        return supabase.table("tasks").update({"status": "in_progress"}).eq("id", task_id).execute()
+
+    @staticmethod
+    async def clear_lease(task_id: str):
+        """
+        Clears queue lease metadata after a worker finishes a task.
+        """
+        return supabase.table("tasks").update({
+            "leased_at": None,
+            "lease_expires_at": None,
+            "queue_worker_id": None,
+        }).eq("id", task_id).execute()
+
+    @staticmethod
+    async def mark_failed(task_id: str, error: str):
+        """
+        Stores terminal queue failure metadata.
+        """
+        return supabase.table("tasks").update({
+            "status": "failed",
+            "last_error": error,
+            "leased_at": None,
+            "lease_expires_at": None,
+            "queue_worker_id": None,
+            "output_data": {"error": error},
+        }).eq("id", task_id).execute()
+
+    @staticmethod
+    async def mark_attempt_failed(task: dict, error: str, max_attempts: int, base_delay_seconds: int):
+        """
+        Requeues a task with exponential backoff until max attempts is reached.
+        """
+        task_id = task["id"]
+        attempts = int(task.get("queue_attempts") or 0)
+
+        if attempts >= max_attempts:
+            result = await TaskQueueService.mark_failed(task_id, error)
+            await audit_service.log_action(
+                user_id=None,
+                action="task_queue_terminal_failure",
+                agent_id=task.get("assigned_agent_id"),
+                task_id=task_id,
+                metadata={
+                    "project_id": task.get("project_id"),
+                    "attempts": attempts,
+                    "max_attempts": max_attempts,
+                    "error": error,
+                },
+            )
+            return result
+
+        delay_seconds = max(base_delay_seconds, 1) * (2 ** max(attempts - 1, 0))
+        next_attempt_at = datetime.now(timezone.utc) + timedelta(seconds=delay_seconds)
+
+        result = supabase.table("tasks").update({
+            "status": "queued",
+            "last_error": error,
+            "leased_at": None,
+            "lease_expires_at": None,
+            "next_attempt_at": next_attempt_at.isoformat(),
+            "queue_worker_id": None,
+            "output_data": {"error": error, "retrying": True, "next_attempt_at": next_attempt_at.isoformat()},
+        }).eq("id", task_id).execute()
+        await audit_service.log_action(
+            user_id=None,
+            action="task_queue_retry_scheduled",
+            agent_id=task.get("assigned_agent_id"),
+            task_id=task_id,
+            metadata={
+                "project_id": task.get("project_id"),
+                "attempts": attempts,
+                "max_attempts": max_attempts,
+                "next_attempt_at": next_attempt_at.isoformat(),
+                "error": error,
+            },
+        )
+        return result
+
+    @staticmethod
+    async def heartbeat(
+        worker_id: str,
+        *,
+        status: str,
+        current_task_id: str | None = None,
+        processed_count: int = 0,
+        failed_count: int = 0,
+        metadata: dict[str, Any] | None = None,
+    ):
+        """
+        Upserts worker heartbeat data for operational monitoring.
+        """
+        try:
+            return supabase.table("worker_heartbeats").upsert({
+                "worker_id": worker_id,
+                "status": status,
+                "current_task_id": current_task_id,
+                "processed_count": processed_count,
+                "failed_count": failed_count,
+                "metadata": metadata or {},
+                "last_seen_at": datetime.now(timezone.utc).isoformat(),
+            }).execute()
+        except Exception as e:
+            logger.warning(f"Could not update worker heartbeat for {worker_id}: {e}")
+            return None

backend/services/task_schemas.py

@@ -0,0 +1,218 @@
+import json
+import re
+from typing import Any
+
+
+SCHEMA_DEFINITIONS: dict[str, dict[str, Any]] = {
+    "factual_research": {
+        "required": ["summary", "findings"],
+        "instructions": {
+            "summary": "string",
+            "findings": [
+                {
+                    "claim": "string",
+                    "source_url": "string or null",
+                    "confidence": "low | medium | high",
+                }
+            ],
+            "unknowns": ["string"],
+        },
+    },
+    "comparison": {
+        "required": ["summary", "entities"],
+        "instructions": {
+            "summary": "string",
+            "entities": [
+                {
+                    "name": "string",
+                    "category": "string",
+                    "strengths": ["string"],
+                    "weaknesses": ["string"],
+                    "source_url": "string or null",
+                }
+            ],
+            "differentiators": ["string"],
+            "gaps": ["string"],
+        },
+    },
+    "roadmap": {
+        "required": ["summary", "recommendations"],
+        "instructions": {
+            "summary": "string",
+            "recommendations": [
+                {
+                    "title": "string",
+                    "priority": "low | medium | high",
+                    "rationale": "string",
+                    "timeline": "string",
+                }
+            ],
+            "risks": ["string"],
+        },
+    },
+    "workflow_design": {
+        "required": ["summary", "steps"],
+        "instructions": {
+            "summary": "string",
+            "steps": [
+                {
+                    "name": "string",
+                    "owner": "string",
+                    "inputs": ["string"],
+                    "outputs": ["string"],
+                }
+            ],
+            "controls": ["string"],
+            "success_metrics": ["string"],
+        },
+    },
+}
+
+SCHEMA_PATTERNS: list[tuple[str, tuple[str, ...]]] = [
+    ("comparison", ("competitor", "compare", "comparison", "matrix", "benchmark", "swot")),
+    ("factual_research", ("research", "market", "pricing", "revenue", "release", "source", "evidence", "audit")),
+    ("roadmap", ("roadmap", "recommendation", "prioritize", "priority", "timeline", "plan")),
+    ("workflow_design", ("workflow", "process", "design", "architecture", "implementation", "controls")),
+]
+
+
+def classify_task_schema(task: dict) -> str | None:
+    text = " ".join(
+        str(task.get(key, "") or "")
+        for key in ("title", "description")
+    ).lower()
+
+    project = task.get("project")
+    if isinstance(project, dict):
+        text = f"{text} {project.get('name', '')} {project.get('description', '')} {project.get('context', '')}".lower()
+
+    for schema_name, terms in SCHEMA_PATTERNS:
+        if any(term in text for term in terms):
+            return schema_name
+    return None
+
+
+def schema_instructions_for_task(task: dict) -> str:
+    schema_name = classify_task_schema(task)
+    if not schema_name:
+        return ""
+
+    schema = SCHEMA_DEFINITIONS[schema_name]["instructions"]
+    return (
+        "Structured output schema:\n"
+        f"- schema_type: {schema_name}\n"
+        "- Return valid JSON only for this task.\n"
+        "- Use this top-level shape:\n"
+        f"{json.dumps(schema, indent=2)}\n"
+        "- Use null for unknown source_url values instead of inventing links."
+    )
+
+
+def _strip_code_fence(value: str) -> str:
+    stripped = value.strip()
+    if not stripped.startswith("```"):
+        return stripped
+
+    stripped = re.sub(r"^```(?:json)?", "", stripped, flags=re.IGNORECASE).strip()
+    stripped = re.sub(r"```$", "", stripped).strip()
+    return stripped
+
+
+def parse_structured_payload(value: Any) -> Any:
+    if isinstance(value, (dict, list)):
+        return value
+    if not isinstance(value, str):
+        return None
+
+    stripped = _strip_code_fence(value)
+    try:
+        return json.loads(stripped)
+    except Exception:
+        match = re.search(r"```json\s*(.*?)\s*```", value, re.IGNORECASE | re.DOTALL)
+        if match:
+            try:
+                return json.loads(match.group(1).strip())
+            except Exception:
+                return None
+    return None
+
+
+def _primary_payload(result: dict) -> Any:
+    data = result.get("data")
+    if data not in (None, "", [], {}):
+        return parse_structured_payload(data) if isinstance(data, str) else data
+    raw = result.get("raw_output")
+    return parse_structured_payload(raw)
+
+
+def _has_source_url(value: Any) -> bool:
+    if isinstance(value, dict):
+        source = value.get("source_url")
+        if isinstance(source, str) and source.startswith(("http://", "https://")):
+            return True
+        return any(_has_source_url(item) for item in value.values())
+    if isinstance(value, list):
+        return any(_has_source_url(item) for item in value)
+    return False
+
+
+def _missing_source_urls(schema_name: str, payload: dict) -> list[str]:
+    missing: list[str] = []
+    if schema_name == "factual_research":
+        for index, finding in enumerate(payload.get("findings") or [], start=1):
+            if not isinstance(finding, dict):
+                continue
+            source = finding.get("source_url")
+            if not (isinstance(source, str) and source.startswith(("http://", "https://"))):
+                missing.append(f"findings[{index}].source_url")
+
+    if schema_name == "comparison":
+        for index, entity in enumerate(payload.get("entities") or [], start=1):
+            if not isinstance(entity, dict):
+                continue
+            source = entity.get("source_url")
+            if not (isinstance(source, str) and source.startswith(("http://", "https://"))):
+                name = entity.get("name") or index
+                missing.append(f"entities[{name}].source_url")
+
+    return missing
+
+
+def validate_task_schema(task: dict, result: dict) -> dict:
+    schema_name = classify_task_schema(task)
+    if not schema_name:
+        return {
+            "schema_type": None,
+            "required": False,
+            "approved": True,
+            "structured": False,
+            "fail_reasons": [],
+            "missing_fields": [],
+        }
+
+    payload = _primary_payload(result)
+    required = SCHEMA_DEFINITIONS[schema_name]["required"]
+    fail_reasons: list[str] = []
+    missing_fields: list[str] = []
+    missing_source_urls: list[str] = []
+
+    if not isinstance(payload, dict):
+        fail_reasons.append(f"Task requires structured JSON matching schema '{schema_name}'.")
+    else:
+        missing_fields = [field for field in required if field not in payload or payload.get(field) in (None, "", [], {})]
+        if missing_fields:
+            fail_reasons.append(f"Structured output is missing required fields: {', '.join(missing_fields)}.")
+
+        missing_source_urls = _missing_source_urls(schema_name, payload)
+        if missing_source_urls:
+            fail_reasons.append("Structured factual claims require source_url values.")
+
+    return {
+        "schema_type": schema_name,
+        "required": True,
+        "approved": not fail_reasons,
+        "structured": isinstance(payload, dict),
+        "fail_reasons": fail_reasons,
+        "missing_fields": missing_fields,
+        "missing_source_urls": missing_source_urls,
+    }

backend/services/utils.py

@@ -0,0 +1,26 @@
+import asyncio
+import logging
+
+logger = logging.getLogger("uvicorn")
+
+def log_async_task_result(task: asyncio.Task, label: str) -> None:
+    """
+    Callback for asyncio tasks to log their completion status and exceptions.
+    """
+    if task.cancelled():
+        logger.warning("%s was cancelled", label)
+        return
+
+    try:
+        exc = task.exception()
+        if exc:
+            logger.error(
+                "%s failed: %s", 
+                label, 
+                exc, 
+                exc_info=(type(exc), exc, exc.__traceback__)
+            )
+    except asyncio.InvalidStateError:
+        logger.error("%s task is not yet finished", label)
+    except Exception as exc:
+        logger.error("Error while checking %s result: %s", label, exc)

backend/tests/conftest.py

@@ -0,0 +1,35 @@
+import pytest
+from unittest.mock import MagicMock, patch
+import os
+import sys
+
+# Ensure backend directory is in path
+backend_path = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if backend_path not in sys.path:
+    sys.path.insert(0, backend_path)
+
+# Mock environment variables before importing app
+os.environ["SUPABASE_URL"] = "https://mock.supabase.co"
+os.environ["SUPABASE_SERVICE_ROLE_KEY"] = "mock-key"
+
+with patch("supabase.create_client") as mock_create:
+    mock_client = MagicMock()
+    mock_create.return_value = mock_client
+    from main import app
+
+from fastapi.testclient import TestClient
+
+@pytest.fixture
+def client():
+    with TestClient(app) as c:
+        yield c
+
+@pytest.fixture
+def mock_supabase():
+    with patch("services.supabase_service.supabase") as mock:
+        yield mock
+
+@pytest.fixture
+def mock_project_service():
+    with patch("services.project_service.project_service") as mock:
+        yield mock