DeepDoc Chat API Integration

What This Integration Does

The DeepDoc Chat API provides conversational AI capabilities within the DeepDoc documentation platform. It enables interactive Q&A, code and artifact citation, and context-aware responses for users browsing generated documentation sites. The integration allows DeepDoc to serve a chatbot backend—either locally or remotely—which powers the /query endpoint for answering user questions about the codebase, citing relevant code, artifacts, and documentation.

Business Role:

• Powers the documentation site's chat sidebar and Q&A widgets.
• Enables users to ask natural language questions about code, features, and artifacts.
• Returns answers with code citations, artifact references, and documentation links.
• Supports advanced retrieval, chunking, and reranking logic for high-quality responses.

Where It Enters the Codebase

The DeepDoc Chat API is integrated at several key points in the codebase:

• Backend Scaffold Generation:
  • scaffold_chatbot_backend() (deepdoc/chatbot/scaffold.py:11)
    Generates a FastAPI-based backend scaffold (chatbot_backend/) if chatbot mode is enabled in config.
• Backend App Entrypoint:
  • app.py (generated by _app_py() in deepdoc/chatbot/scaffold.py:30)
    Loads the chatbot backend, exposing /query and /health endpoints.
• Configuration & Settings:
  • chatbot_enabled() (deepdoc/chatbot/settings.py:81)
    Checks if chatbot integration is enabled.
  • chatbot_site_api_base_url() (deepdoc/chatbot/settings.py:97)
    Resolves the base URL for the Chat API.
• Environment Variables:
  • .env.example (generated by _env_example() in deepdoc/chatbot/scaffold.py:114)
    Documents required environment variables: DEEPDOC_CHAT_API_KEY, DEEPDOC_EMBED_API_KEY.
• CLI Integration:
  • _start_chatbot_backend() (deepdoc/cli.py:889)
    Starts the backend locally for preview/serve workflows.
  • init command (deepdoc/cli.py:131)
    Enables chatbot integration during project setup.
• Config Management:
  • DEFAULT_CONFIG and DEFAULT_CHATBOT_CONFIG (deepdoc/config.py:11, deepdoc/chatbot/settings.py:13)
    Define config structure for chatbot integration.

Participating Features & Endpoints

The DeepDoc Chat API is used by:

• Documentation Site Chat Widgets:
  • The frontend (see Site Generation & Frontend Integration Overview) communicates with the backend /query endpoint for chat.
• Public API Endpoints:
  • /query (POST): Accepts chat questions and returns answers with citations.
  • /health (GET): Health check endpoint for backend readiness.

Related Pages:

• Runtime Services & Chatbot Engine
• Public API Endpoints
• Webhook Integrations (for webhook-based triggers and event handling)

Request/Response or Message Flow

The typical interaction pattern between the documentation frontend and the DeepDoc Chat API backend is as follows:

Request Payload

Defined in QueryRequest (chatbot_backend/schemas.py generated by _schemas_py() in deepdoc/chatbot/scaffold.py:68):

class QueryRequest(BaseModel):
    question: str
    history: list[dict[str, str]] = Field(default_factory=list)

• question: The user's question (string, required).
• history: List of previous chat messages (optional, for context).

Response Payload

Defined in QueryResponse (chatbot_backend/schemas.py):

class QueryResponse(BaseModel):
    answer: str
    code_citations: list[dict[str, Any]]
    artifact_citations: list[dict[str, Any]]
    doc_links: list[dict[str, Any]]
    used_chunks: int

• answer: The generated answer (string).
• code_citations: List of code references (dicts).
• artifact_citations: List of artifact references (dicts).
• doc_links: List of documentation links (dicts).
• used_chunks: Number of context chunks used for the answer (int).

Example Request

POST /query
{
  "question": "How does the authentication middleware work?",
  "history": [
    {"role": "user", "content": "Tell me about authentication."},
    {"role": "assistant", "content": "Authentication uses JWT tokens..."}
  ]
}

Example Response

{
  "answer": "The authentication middleware validates JWT tokens and checks user roles...",
  "code_citations": [
    {"file": "auth/middleware.py", "lines": [10, 45]}
  ],
  "artifact_citations": [
    {"artifact": "JWT_SECRET", "location": ".env"}
  ],
  "doc_links": [
    {"title": "Authentication", "url": "/auth"}
  ],
  "used_chunks": 3
}

Auth & Configuration

Environment Variables

The following environment variables must be set for the Chat API backend to function:

These are documented in .env.example (generated by _env_example() in deepdoc/chatbot/scaffold.py:114):

DEEPDOC_CHAT_API_KEY=
DEEPDOC_EMBED_API_KEY=

Configuration Keys

• Base URL:
  • Set via chatbot.backend.base_url in .deepdoc.yaml or resolved by chatbot_site_api_base_url() (deepdoc/chatbot/settings.py:97).
• Allowed Origins:
  • Controlled by chatbot.backend.allowed_origins in config and dynamically extended by DEEPDOC_CHATBOT_PREVIEW_PORT (deepdoc/chatbot/settings.py:126).

Setup Steps

Retry, Reconciliation & Failure Handling

Startup Errors

• If the backend fails to start (e.g., missing config, invalid API key), the fallback FastAPI app is loaded (see _app_py() in deepdoc/chatbot/scaffold.py:30).
• /health returns a JSON error with details.
• /query returns HTTP 503 with {"error": "startup_failed", "detail": ...}.

Request Errors

• If the backend is unreachable or returns an error, the frontend receives a clear error response.
• No explicit retry logic is implemented in the backend scaffold; retries must be handled by the frontend or orchestrator.
• If the Chat API is disabled (chatbot_enabled() in deepdoc/chatbot/settings.py:81), the backend is not started.

Fallbacks

• If a remote backend is configured (chatbot.backend.base_url), DeepDoc uses it directly and does not start a local backend.
• If the configured backend URL is a loopback address, DeepDoc attempts to start the backend locally.

Operational Gotchas

• Rate Limits:
  No explicit rate limiting is enforced in the scaffold; external API rate limits (if any) must be handled by the embedding or LLM providers.
• Timeouts:
  Not explicitly set in the scaffold; FastAPI/Uvicorn defaults apply.
• Payload Size Limits:
  No explicit limits in the backend scaffold, but large history payloads may impact performance.
• Version Compatibility:
  The backend requires compatible versions of fastapi, uvicorn, httpx, and other dependencies as specified in requirements.txt (see _requirements_txt() in deepdoc/chatbot/scaffold.py:99).
• Monitoring:
  Health status is available at /health. For production, add logging and monitoring as needed.
• Frontend/Backend Coordination:
  The frontend must use the correct base URL, which is set via NEXT_PUBLIC_DEEPDOC_CHATBOT_BASE_URL during deepdoc serve (see _start_chatbot_backend() in deepdoc/cli.py:889).

Diagrams

Integration Flow

See Also

integration_overview

TODO: This section (integration_overview) needs to be filled in with details from the source files listed above.

authentication

TODO: This section (authentication) needs to be filled in with details from the source files listed above.

api_usage

TODO: This section (api_usage) needs to be filled in with details from the source files listed above.

error_handling

TODO: This section (error_handling) needs to be filled in with details from the source files listed above.