TaskForge

TaskForge

Multi-agent crisis logistics coordinator built with FastAPI, Gemini, MCP, PostgreSQL, and pgvector.

TaskForge turns a crisis request such as "Flood in Odisha causing food shortage across 3 districts" into a structured logistics plan. The app coordinates specialist agents, records task state in PostgreSQL, exposes MCP tools over SSE, and keeps deterministic fallbacks so the demo still produces operational output when the LLM is unavailable.

Live demo: https://taskforge-demo.mangoglacier-b3ad215d.southeastasia.azurecontainerapps.io/

What Is In This Repo

| Area | Path | What it does | |---|---|---| | FastAPI app | app/main.py | Mounts health, task/demo, static UI, and MCP endpoints. | | Agent pipeline | app/agents/ | Orchestrator, resource audit, planning, execution, and replanning agents. | | MCP tools | app/tools/ | Task, route, weather, calendar, and knowledge tools registered at startup. | | Database | app/db/, alembic/ | Async SQLAlchemy models, repositories, seed data, and migrations. | | Memory/RAG | app/memory/, app/llm/ | Context assembly, embeddings, Gemini client, and pgvector-backed knowledge. | | API routes | app/api/ | Health and task execution endpoints. | | Static UI | app/static/index.html, ui/app.py | Browser dashboard and optional Streamlit UI. | | Tests | tests/ | Health, CRUD, validation, Gemini client, execution, and hardening tests. |

Architecture

User query
  -> FastAPI /execute or /api/v1/tasks
  -> OrchestratorAgent
       -> ResourceAgent      inventory and shortage analysis
       -> PlanningAgent      source depot, route, cost, ETA
       -> ExecutionAgent     subtasks, delivery schedule, dispatch actions
       -> ReplanningAgent    disruption reroute when crisis keywords appear
  -> Task repository + memory context
  -> JSON response with plan, tasks, risk notes, agent flow, and reliability fields

The app also mounts an MCP server:

• GET /mcp/sse for MCP SSE connections.
• POST /mcp/messages/ for MCP message handling.

Registered tool modules are imported during FastAPI startup:

• task_tools
• knowledge_tool
• calendar_tool
• weather_tool
• route_tool

API Surface

Core routes are mounted from app/api/routes_health.py and app/api/routes_tasks.py.

Common local routes:

| Route | Purpose | |---|---| | GET / | Static dashboard when app/static/index.html exists. | | GET /health | Service readiness and startup status. | | POST /execute | Run the crisis logistics agent pipeline. | | GET /api/v1/tasks | List stored tasks. | | POST /api/v1/tasks | Create a task. | | DELETE /api/v1/tasks/{task_id} | Delete a task. | | GET /docs | Swagger UI. | | GET /mcp/sse | MCP SSE transport. |

Local Development

TaskForge expects PostgreSQL with pgvector for the full path. The included compose file starts the database service.

git clone https://github.com/mangod12/TaskForge.git
cd TaskForge

python -m venv .venv
. .venv/Scripts/activate  # Windows PowerShell users can use .venv\Scripts\Activate.ps1
pip install -r requirements.txt

docker compose up -d db
uvicorn app.main:app --reload --port 8000

Open:

• Dashboard: http://localhost:8000
• Swagger: http://localhost:8000/docs
• Health: http://localhost:8000/health

Run a scenario:

curl -X POST http://localhost:8000/execute ^
  -H "Content-Type: application/json" ^
  -d "{\"query\":\"Flood in Odisha causing food shortage across 3 districts\"}"

Configuration

Start from .env.example.

Important settings:

| Variable | Purpose | |---|---| | DATABASE_URL | Async SQLAlchemy database URL. | | GEMINI_API_KEY | Gemini API key for LLM-backed agent output. | | GEMINI_MODEL | Model name. CI currently uses gemini-2.0-flash; deployment config uses gemini-2.5-flash. | | USE_VERTEX_AI | Enables Vertex AI path when configured. | | LOG_LEVEL | Runtime logging level. |

When no LLM path is available, the agents use fallback logic for credible demo output.

Tests

python -m pytest tests/ -v --tb=short

The CI workflow starts pgvector/pgvector:pg16, installs dependencies, and runs the full tests/ directory.

Deployment

The repo includes:

• Dockerfile
• docker-compose.yml
• .github/workflows/ci.yml
• .github/workflows/deploy.yml

The Azure Container Apps deploy workflow builds an image, deploys service taskforge-demo, enables scale-to-zero, sets demo-safe configuration, and verifies /health.

The GitHub repository homepage and the live demo link above point to the current Azure Container Apps deployment.

Current Limitations

• Startup DB initialization and preset warmup are deferred; /health should be checked before demos.
• pgvector is required for the intended PostgreSQL-backed memory path.
• The static dashboard is a lightweight reviewer surface, not a full operations console.
• MCP transport is SSE-based and intended for compatible MCP clients.

License

MIT. See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mangod12
• Source: mangod12/TaskForge
• License: MIT
• Homepage: https://taskforge-demo.mangoglacier-b3ad215d.southeastasia.azurecontainerapps.io/

Install and usage instructions live in the source repository linked above.