DocsGPT

Use this operating graph for DocsGPT 0.18-era administration, integration, and extension tasks. It is a task router, not a replacement for the focused references below.

Start here

1. Identify whether the task targets a source checkout, a running DocsGPT deployment, or an external client.
2. Choose the owning sub-skill from the routing table.
3. Establish prerequisites before changing state: Postgres for user data, Redis for cache/Celery/events, an LLM and embeddings path, and any optional vector-store, connector, or sandbox service.
4. Prefer read-only checks and dry-run/plan endpoints before migrations, re-ingestion, imports, schedules, or state-mutating tools.
5. Validate the result at the narrowest useful layer, then check the integrated API or UI path.

Route by task

Task signal	Read
install, local development, Docker, Kubernetes, environment variables, model providers, OIDC/SCIM/RBAC, Postgres, Redis, S3, observability, upgrades	deploy-configure
upload, parse, OCR, audio, URL/sitemap/crawler, GitHub/Reddit/S3 source, Google Drive, SharePoint, Confluence, chunking, ingestion worker, re-ingestion	ingest-sources
embeddings, FAISS, pgvector, Qdrant, Milvus, MongoDB Atlas, Elasticsearch, classic/hybrid RAG, pre-screening, GraphRAG, retrieval quality	retrieval-vectorstores
classic/agentic/research/workflow agent, workflow nodes, CEL, schedules, webhooks, seeding, agent export/import	agents-workflows
built-in tools, generic API tool, MCP, artifacts, code execution, Read Document, sandbox, remote device, widget, Chatwoot	tools-integrations
/api/answer, /stream, attachments, SSE, reconnect, /v1/chat/completions, structured output, multimodal clients, idempotency, /mcp	api-client-operations

Runtime topology rule

Use the ASGI composition for full behavior:

uvicorn application.asgi:asgi_app --host 0.0.0.0 --port 7091

The Flask development server exposes the WSGI app only. It omits /mcp and the native-async reconnect reader at GET /api/messages/<id>/events; use Flask only for a deliberately reduced inner loop.

A full deployment normally has:

• the ASGI web application;
• Postgres as the canonical user-data store;
• Redis for cache, Celery broker/results, schedules, and realtime coordination;
• at least one Celery worker (a bare worker consumes all queues; split docsgpt and parsing only when needed);
• the frontend or another API client;
• optional vector-store, sandbox, object-storage, OAuth connector, and model-provider services.

Read architecture and terminology before changing boundaries across these components.

Minimal readiness checks

For a source-development checkout, use Python 3.12 and install the backend requirements into an isolated environment. This bundle includes the exact 0.18.0 backend requirements snapshot; use the target release's manifest only after checking provenance/version drift. Do not run bootstrap setup scripts during ordinary feature work when explicit environment configuration is sufficient.

From the runtime skill root:

python -m pip install -r references/backend-requirements-0.18.0.txt
python -c "from application.version import get_version; print(get_version())"
python -c "from application.asgi import asgi_app; print(type(asgi_app).__name__)"

For a running service, use the bundled read-only checker:

python scripts/check_deployment.py --base-url http://localhost:7091

Add --token only for a non-production test credential or pass --token-env so the credential is not written into shell history. Read the script help before probing a shared deployment.

Safety and verification

• Treat .env, API keys, OAuth client secrets, JWT secrets, SCIM tokens, S3 credentials, and sandbox tokens as secrets. Never place them in logs or exported agent YAML.
• Back up Postgres and object storage before migrations or backfills. Do not infer success from a Celery task id; poll status and inspect the resulting source/artifact.
• Changing chunking or embedding dimensions requires re-ingestion. Query-time retrieval settings usually do not.
• GraphRAG requires both pgvector and its feature flag. Hybrid keyword retrieval is pgvector-specific; other stores fall back to vector behavior.
• Tool calls can perform external side effects. Use per-action approval and idempotent APIs for writes.
• Imported agents are drafts and exported secrets are stripped. Preview import plans before committing.

Read cross-cutting troubleshooting when failures span multiple components.

Version and staleness

Read repository provenance before relying on exact routes, settings, schemas, or defaults in a different checkout. Refresh this graph when the commit, package version, public API, or major evidence paths change.