forge/apps/api/README.md

Forge API

FastAPI backend for Forge - the self-hosted agent platform. Built directly on the MIT-licensed LangChain v1 + LangGraph v1 framework. Never depends on langgraph-api (Elastic 2.0) or LangSmith (commercial).

Local dev (zero external infra)

The default local stack needs no Docker, Postgres, or Redis:

Concern	Local default	Production swap (config-only)
Relational DB	SQLite (aiosqlite)	Postgres 16 (asyncpg / psycopg)
Run durability	langgraph-checkpoint-sqlite	langgraph-checkpoint-postgres
Vectors	Chroma (embedded, persistent)	pgvector in the same Postgres - set vector_backend=pgvector
Cache / queue	in-process	Redis 7 + arq
Secrets	Fernet (local key file)	Vault / cloud KMS

cd apps/api
python -m venv .venv
.venv\Scripts\activate            # Windows  (source .venv/bin/activate on *nix)
pip install -e ".[dev]"           # core + test deps only
pip install -e ".[dev,all]"       # full local stack (vectors + providers + knowledge + MCP)

cp ../../.env.example .env
uvicorn forge.main:app --reload --port 8000
pytest                            # validate the engine

Layout

apps/api/
  forge/
    main.py              FastAPI app factory + lifespan (DB init, checkpointer, scheduler/reaper)
    config.py            Settings (pydantic-settings, env-driven) + production hardening guard
    deps.py              FastAPI dependencies: session, auth/tenant resolution, RBAC
    security.py          Auth primitives: bcrypt password hashing + JWT mint/verify
    audit_middleware.py  ASGI middleware that audits successful mutations
    queue.py, worker.py  Optional arq/Redis queue + worker for offloaded runs (prod)
    db/                  async engine, session, tenant scoping, dev seed/bootstrap
    models/              SQLAlchemy ORM (tenants, projects, workflows, runs, traces, ...)
    schemas/             Pydantic request/response DTOs + shared JSON-Schema loader/validator
    services/            business logic (ProjectSvc, WorkflowSvc, RunSvc, assistant,
                         portability import/export, tool_sets, ...)
    routers/             HTTP + SSE endpoints (incl. assistant, runs, mcp_server, mcp_oauth,
                         mcp_tokens, tool_sets, connections, models, versions, embed)
    engine/              the heart: registry, compiler, state, middleware_compiler, context
    nodes/               node-type factories (start, end, agent, llm, tool_call, flow, rag, triggers)
    tools/               tool materialization (rest, graphql, code, sql, mcp, builtin) + projection
    auth_providers/      Auth Provider resolver (csrf_session, oauth2, bearer, ...)
    secrets/             Fernet-encrypted, reference-only secret store
    channels/            email deployment surface
    knowledge/           EmbeddingStore (Chroma), ingestion/crawl, splitter, hybrid + rerank
    tracing/             ForgeTracer callback + span sink + pricing + tool-I/O capture
    util/                cross-cutting helpers (SSRF guard, http client, rate limit, mailer, ...)
    assistant_skills/    skill(s) the in-product build assistant loads
  migrations/            Alembic migrations (prod schema path; SQLite auto-creates in dev)
  tests/                 pytest suite (engine, tools, knowledge, auth, security, ...)