Anthropic Integration

What This Integration Does

The Anthropic integration provides access to Anthropic's LLM (Large Language Model) APIs for chat and completion services. DeepDoc uses Anthropic as its default LLM provider to generate documentation, cluster features, and perform advanced code analysis tasks. This integration enables DeepDoc to leverage state-of-the-art AI models (e.g., Claude 3.5 Sonnet) for natural language understanding, summarization, and planning.

Where It Enters the Codebase

Anthropic API usage is orchestrated through a thin abstraction layer, ensuring that model calls are consistent and configurable. The main entry points are:

• LLM Client Abstraction:
  • LLMClient (deepdoc/llm/client.py:12):
    • Handles all LLM chat/completion requests.
    • Wraps the LiteLLM library, which supports Anthropic, OpenAI, Ollama, and others.
    • Sets up API keys and model parameters from config.
    • Methods:
      • complete() (deepdoc/llm/client.py:30): Sends a synchronous chat completion request.
      • complete_stream() (deepdoc/llm/client.py:59): Streams completion responses chunk-by-chunk.
• Configuration Management:
  • DEFAULT_CONFIG (deepdoc/config.py:11):
    • Contains the default LLM provider, model, and environment variable names for API keys.
  • resolve_api_key() (deepdoc/config.py:230):
    • Looks up the Anthropic API key from the configured environment variable.
• CLI Initialization:
  • init() (deepdoc/cli.py:131):
    • When run with --provider anthropic, sets up .deepdoc.yaml with Anthropic defaults.
    • Ensures the correct model and API key environment variable (ANTHROPIC_API_KEY) are set.
• Feature Clustering and Integration Discovery:
  • cluster_giant_file() (deepdoc/scan_v2.py:65):
    • Uses LLMClient to group symbols in large files by business domain.
  • discover_integrations() (deepdoc/scan_v2.py:572):
    • Optionally uses Anthropic via LLMClient to normalize integration signals.

File References:

• deepdoc/llm/client.py
• deepdoc/config.py
• deepdoc/cli.py
• deepdoc/scan_v2.py

Participating Features & Endpoints

Anthropic integration is foundational to several DeepDoc features:

• Documentation Generation:
  • All documentation generation flows (deepdoc/cli.py:246, deepdoc/cli.py:362) rely on LLM completions for summarization, planning, and page writing.
• Feature Clustering:
  • Giant-file clustering (deepdoc/scan_v2.py:65) uses Anthropic to group symbols into logical business features.
• Integration Normalization:
  • Integration discovery (deepdoc/scan_v2.py:572) uses Anthropic to group and normalize detected integration signals.
• CLI Commands:
  • deepdoc init, deepdoc generate, deepdoc update (CLI Commands & Tooling)
• Site Generation:
  • The generated documentation site (Site Generation & Frontend Integration Overview) is powered by content produced via Anthropic completions.

Request/Response or Message Flow

All Anthropic API calls are made via the LiteLLM library, abstracted by LLMClient (deepdoc/llm/client.py). The typical flow for a chat completion request is as follows:

Request Construction:

• Model:
  • Configured via .deepdoc.yaml (llm.model), e.g., claude-3-5-sonnet-20241022.
• API Key:
  • Pulled from the environment variable specified in llm.api_key_env (default: ANTHROPIC_API_KEY).
• Payload:
  • messages: List of dicts with role (system/user) and content.
  • temperature, max_tokens, base_url (optional).

Example (from LLMClient.complete()):

kwargs: dict[str, Any] = {
    "model": self.model,
    "messages": [
        {"role": "system", "content": system},
        {"role": "user", "content": user},
    ],
    "temperature": self.temperature,
}
if self.max_tokens:
    kwargs["max_tokens"] = self.max_tokens
if self.base_url:
    kwargs["base_url"] = self.base_url

response = litellm.completion(**kwargs)
return response.choices[0].message.content or ""

— deepdoc/llm/client.py:38

Authentication:

• API key is set in the environment (ANTHROPIC_API_KEY) before the request is made.

Streaming:

• For streaming completions, complete_stream() sets "stream": True and yields text chunks as they arrive.

Auth & Configuration

Anthropic integration requires an API key, which must be provided via environment variable. Configuration is managed through .deepdoc.yaml and environment variables.

Relevant Config Fields (deepdoc/config.py:11):

Environment Variable:

How to Set Up:

Retry, Reconciliation & Failure Handling

Error Handling in LLM Calls:

• All LLM requests are wrapped in try/except blocks in LLMClient (deepdoc/llm/client.py:30, deepdoc/llm/client.py:59).
• If litellm is not installed, a RuntimeError is raised with a clear message.
• Any other exceptions are caught and re-raised as RuntimeError with the error details.

Example:

try:
    litellm = prepare_litellm()
    # ... make request ...
except ImportError:
    raise RuntimeError(
        "litellm not installed. Run: pip install litellm"
    )
except Exception as e:
    raise RuntimeError(f"LLM request failed: {e}") from e

— deepdoc/llm/client.py:44

No Built-in Retries:

• There is no explicit retry or circuit breaker logic in LLMClient. If the Anthropic API is down or returns an error, the request fails and the error is surfaced to the CLI or calling process.
• Upstream CLI commands (e.g., deepdoc generate) will abort on LLM errors and print the error message to the user.

Operational Gotchas

• Rate Limits:
  • Anthropic enforces per-key and per-organization rate limits. Exceeding these will result in HTTP 429 errors.
  • There is no built-in rate limit handling or backoff in DeepDoc; you must manage usage at the workflow level.
• Timeouts:
  • Requests may time out if the Anthropic API is slow or unresponsive. These will raise exceptions in LLMClient.
• Payload Size:
  • The maximum prompt and output size is determined by the Anthropic model and your account limits.
  • The max_tokens config can be set to cap output, but defaults to unlimited.
• Model Versioning:
  • The default model is claude-3-5-sonnet-20241022. You can override this in .deepdoc.yaml.
  • Model names must match those supported by your Anthropic account.
• API Key Leaks:
  • Never commit your .env file or API keys to version control.
  • The CLI will not print API keys, but always audit your environment for accidental exposure.
• Dependency:
  • The litellm Python package must be installed (pip install litellm).
  • If missing, LLM requests will fail with a clear error message.

Diagrams

Integration Flow:

See Also

• Setup & Getting Started
• CLI Commands & Tooling
• Documentation Chunking and Summarization
• Webhook Integrations
• Site Generation & Frontend Integration Overview
• Site Builder Workflow and Frontend Integration
• DeepDoc Chat API Integration
• DeepDoc Embedding API Integration