ai-doc-creator 2.2.0__tar.gz

ai_doc_creator-2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dharmik Raval
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_doc_creator-2.2.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: ai-doc-creator
+Version: 2.2.0
+Summary: AI-powered documentation generator for repos and local projects — MCP server + CLI, any LLM provider or keyless via MCP host sampling.
+Author: Dharmik Raval
+License: MIT
+Project-URL: Homepage, https://github.com/dharmikraval1/ai-document-creator
+Project-URL: Repository, https://github.com/dharmikraval1/ai-document-creator
+Project-URL: Issues, https://github.com/dharmikraval1/ai-document-creator/issues
+Keywords: mcp,documentation,ai,llm,docs-generator,model-context-protocol
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.10
+Requires-Dist: langchain>=0.3
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain-community>=0.3
+Requires-Dist: langchain-openai>=0.3
+Requires-Dist: langchain-anthropic>=0.3
+Requires-Dist: langchain-aws>=0.2
+Requires-Dist: langchain-ollama>=0.2
+Requires-Dist: langgraph>=0.3
+Requires-Dist: openai>=1.60
+Requires-Dist: boto3>=1.35
+Requires-Dist: gitpython>=3.1
+Requires-Dist: PyGithub>=2.5
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pydantic>=2.9
+Requires-Dist: tenacity>=8.5
+Requires-Dist: tiktoken>=0.8
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# AI Document Creator
+
+[![CI](https://github.com/dharmikraval1/ai-document-creator/actions/workflows/ci.yml/badge.svg)](https://github.com/dharmikraval1/ai-document-creator/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+
+AI-powered documentation generator, exposed as an **MCP server** and a **CLI**. Point it at a **GitHub repository** or a **local project** and it writes per-file docs plus a synthesized `README.md` — using **any LLM** (Anthropic, OpenAI, Azure OpenAI, AWS Bedrock, Ollama) with your key, or **your MCP host's own model via sampling with no key at all**.
+
+📖 **New here? The step-by-step guide for every setup is in [USAGE.md](USAGE.md).**
+
+## Use it in 60 seconds
+
+### Option A — run it locally in your MCP host (recommended)
+
+With [uv](https://docs.astral.sh/uv/) installed, no clone, no venv:
+
+```bash
+# Claude Code
+claude mcp add ai-doc-creator -- uvx --from ai-doc-creator ai-doc-creator-mcp
+```
+
+Claude Desktop / Cursor / any MCP host (`mcpServers` JSON):
+
+```json
+{
+  "mcpServers": {
+    "ai-doc-creator": {
+      "command": "uvx",
+      "args": ["--from", "ai-doc-creator", "ai-doc-creator-mcp"],
+      "env": { "ANTHROPIC_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+The `env` block is optional — leave it out and the server uses your MCP host's model via sampling (zero API cost).
+
+> Until the package is on PyPI you can substitute
+> `uvx --from git+https://github.com/dharmikraval1/ai-document-creator ai-doc-creator-mcp`.
+
+### Option B — use a hosted endpoint (nothing to install)
+
+Point your MCP host at a deployment's Streamable HTTP endpoint and bring your own key in headers:
+
+```json
+{
+  "mcpServers": {
+    "ai-doc-creator": {
+      "type": "http",
+      "url": "https://<your-deployment-host>/mcp",
+      "headers": {
+        "X-Provider-API-Key": "sk-...",
+        "X-Provider": "anthropic"
+      }
+    }
+  }
+}
+```
+
+Keys travel in **headers**, never in tool arguments, so they stay out of chat transcripts and logs. Legacy clients can still connect via `https://<host>/sse`.
+
+### Option C — GitHub Action (docs that update themselves)
+
+```yaml
+- uses: dharmikraval1/ai-document-creator@v2
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+Regenerates your repo's docs on every push — full workflow example in [USAGE.md](USAGE.md#5-github-action--docs-that-update-themselves).
+
+### Option D — CLI
+
+```bash
+pip install ai-doc-creator     # or: pip install git+https://github.com/dharmikraval1/ai-document-creator
+ai-doc-creator --repo https://github.com/user/repo --output docs
+ai-doc-creator --path . --provider ollama --model llama3.1
+```
+
+The CLI needs a provider key (there is no MCP host to sample from).
+
+## MCP tools
+
+| Tool | What it does |
+|---|---|
+| `document_repo(repo_url, ...)` | Clone a GitHub repo and document it. `push_as_pr=True` opens a PR with the docs; `return_docs=True` inlines the generated markdown in the response (capped by `MAX_INLINE_DOC_KB`). |
+| `document_local_project(path, ...)` | Document a folder on the machine the server runs on. Disabled on hosted deployments unless the operator sets `LOCAL_ROOT`. |
+| `check_doc_drift(path, output_dir)` | Report new/modified/deleted files since the last documentation run (no LLM calls). |
+
+All documentation runs are **incremental** by default: a content-hash manifest skips unchanged files, so re-runs only pay for what changed.
+
+### Diagrams & output profiles
+
+Every generated README ends with **Mermaid architecture diagrams** — a project-structure chart and a module-dependency graph computed by static analysis (Python + JS/TS imports), so they're always syntactically valid. Complex files also get model-drawn flow charts, and every model-drawn diagram is validated before shipping (invalid ones are downgraded to plain text, never broken pages). Disable with `diagrams=false` / `--no-diagrams`.
+
+Pick a documentation style with `profile` (`--profile` on the CLI):
+
+| Profile | Focus |
+|---|---|
+| `readme` (default) | Classic README: overview, install, usage |
+| `api` | API reference: signatures, params, returns, errors |
+| `architecture` | Components, data flow, design decisions + diagrams |
+| `tutorial` | Guided walkthrough for newcomers |
+
+## How it works
+
+Two independent choices over one async pipeline:
+
+- **Source** — `GitSource` (clone a URL) or `LocalSource` (read a path).
+- **Backend** — `ProviderBackend` (any provider, via env key or per-request header key) or `SamplingBackend` (the MCP host's model). `pick_backend` chooses: an explicit key wins; otherwise a configured provider; otherwise host sampling; otherwise a clear error.
+
+The pipeline traverses files, generates per-file docs concurrently (bounded by a semaphore), then synthesizes a top-level `README.md`.
+
+## LLM providers
+
+| Provider | Configure via |
+|---|---|
+| Anthropic | `ANTHROPIC_API_KEY` env, or `X-Provider-API-Key` header |
+| OpenAI | `OPENAI_API_KEY` env, or header |
+| Azure OpenAI | `AZURE_OPENAI_API_KEY` + endpoint/deployment (see `.env.example`), or header |
+| AWS Bedrock | `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (env only) |
+| Ollama (local) | `provider="ollama"` (no key) |
+| None | MCP host sampling — the host's model writes the docs |
+
+## Hosting your own public endpoint
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/dharmikraval1/ai-document-creator)
+
+One click via the included [`render.yaml`](render.yaml) blueprint — it enables auto-deploy on every push to `main`, health checks, and safe public defaults (`BYOK_ONLY=true`, rate limiting on, Render hostname auto-allowed).
+
+The `Dockerfile` also runs anywhere that supplies a `PORT` (Fly.io, Railway, ...). The server serves Streamable HTTP at `/mcp`, legacy SSE at `/sse`, and a health probe at `/health`.
+
+Recommended env for a public deployment:
+
+| Variable | Value | Why |
+|---|---|---|
+| `MCP_ALLOWED_HOSTS` | your public hostname (e.g. `your-app.onrender.com`) | DNS-rebinding protection rejects unknown Host headers |
+| `BYOK_ONLY` | `true` | never spend *your* keys on strangers — users bring keys in headers or use sampling |
+| `RATE_LIMIT_RPM` | `20` (default) | per-client request cap; `0` disables |
+| `LOG_FORMAT` | `json` | structured logs |
+| `MCP_TRANSPORT` | `both` (default) / `streamable-http` / `sse` | which HTTP transports to serve |
+
+## Security model
+
+- **Keys**: header-only intake for remote users; passed explicitly to the provider client; never written to env, logs, or `repr()`; `BYOK_ONLY=true` guarantees the server's own keys are never used for requests.
+- **SSRF**: repo URLs must be HTTPS and must not resolve to private/reserved address space; DNS-rebinding protection on the HTTP transports.
+- **Filesystem**: hosted deployments refuse local-filesystem tools (unless `LOCAL_ROOT` opts in) and write repo docs to per-request temp dirs — callers can't read or write server paths.
+- **Abuse limits**: per-client rate limit, bounded pipeline concurrency, pipeline timeout, repo-size cap, per-file-size cap.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest -q          # 157 tests
+flake8 && mypy ai_doc_creator --ignore-missing-imports
+```
+
+Design specs, implementation plans, and phase status live in [planning/](planning/).
+
+## License
+
+[MIT](LICENSE)

ai_doc_creator-2.2.0/README.md

@@ -0,0 +1,163 @@
+# AI Document Creator
+
+[![CI](https://github.com/dharmikraval1/ai-document-creator/actions/workflows/ci.yml/badge.svg)](https://github.com/dharmikraval1/ai-document-creator/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+
+AI-powered documentation generator, exposed as an **MCP server** and a **CLI**. Point it at a **GitHub repository** or a **local project** and it writes per-file docs plus a synthesized `README.md` — using **any LLM** (Anthropic, OpenAI, Azure OpenAI, AWS Bedrock, Ollama) with your key, or **your MCP host's own model via sampling with no key at all**.
+
+📖 **New here? The step-by-step guide for every setup is in [USAGE.md](USAGE.md).**
+
+## Use it in 60 seconds
+
+### Option A — run it locally in your MCP host (recommended)
+
+With [uv](https://docs.astral.sh/uv/) installed, no clone, no venv:
+
+```bash
+# Claude Code
+claude mcp add ai-doc-creator -- uvx --from ai-doc-creator ai-doc-creator-mcp
+```
+
+Claude Desktop / Cursor / any MCP host (`mcpServers` JSON):
+
+```json
+{
+  "mcpServers": {
+    "ai-doc-creator": {
+      "command": "uvx",
+      "args": ["--from", "ai-doc-creator", "ai-doc-creator-mcp"],
+      "env": { "ANTHROPIC_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+The `env` block is optional — leave it out and the server uses your MCP host's model via sampling (zero API cost).
+
+> Until the package is on PyPI you can substitute
+> `uvx --from git+https://github.com/dharmikraval1/ai-document-creator ai-doc-creator-mcp`.
+
+### Option B — use a hosted endpoint (nothing to install)
+
+Point your MCP host at a deployment's Streamable HTTP endpoint and bring your own key in headers:
+
+```json
+{
+  "mcpServers": {
+    "ai-doc-creator": {
+      "type": "http",
+      "url": "https://<your-deployment-host>/mcp",
+      "headers": {
+        "X-Provider-API-Key": "sk-...",
+        "X-Provider": "anthropic"
+      }
+    }
+  }
+}
+```
+
+Keys travel in **headers**, never in tool arguments, so they stay out of chat transcripts and logs. Legacy clients can still connect via `https://<host>/sse`.
+
+### Option C — GitHub Action (docs that update themselves)
+
+```yaml
+- uses: dharmikraval1/ai-document-creator@v2
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+Regenerates your repo's docs on every push — full workflow example in [USAGE.md](USAGE.md#5-github-action--docs-that-update-themselves).
+
+### Option D — CLI
+
+```bash
+pip install ai-doc-creator     # or: pip install git+https://github.com/dharmikraval1/ai-document-creator
+ai-doc-creator --repo https://github.com/user/repo --output docs
+ai-doc-creator --path . --provider ollama --model llama3.1
+```
+
+The CLI needs a provider key (there is no MCP host to sample from).
+
+## MCP tools
+
+| Tool | What it does |
+|---|---|
+| `document_repo(repo_url, ...)` | Clone a GitHub repo and document it. `push_as_pr=True` opens a PR with the docs; `return_docs=True` inlines the generated markdown in the response (capped by `MAX_INLINE_DOC_KB`). |
+| `document_local_project(path, ...)` | Document a folder on the machine the server runs on. Disabled on hosted deployments unless the operator sets `LOCAL_ROOT`. |
+| `check_doc_drift(path, output_dir)` | Report new/modified/deleted files since the last documentation run (no LLM calls). |
+
+All documentation runs are **incremental** by default: a content-hash manifest skips unchanged files, so re-runs only pay for what changed.
+
+### Diagrams & output profiles
+
+Every generated README ends with **Mermaid architecture diagrams** — a project-structure chart and a module-dependency graph computed by static analysis (Python + JS/TS imports), so they're always syntactically valid. Complex files also get model-drawn flow charts, and every model-drawn diagram is validated before shipping (invalid ones are downgraded to plain text, never broken pages). Disable with `diagrams=false` / `--no-diagrams`.
+
+Pick a documentation style with `profile` (`--profile` on the CLI):
+
+| Profile | Focus |
+|---|---|
+| `readme` (default) | Classic README: overview, install, usage |
+| `api` | API reference: signatures, params, returns, errors |
+| `architecture` | Components, data flow, design decisions + diagrams |
+| `tutorial` | Guided walkthrough for newcomers |
+
+## How it works
+
+Two independent choices over one async pipeline:
+
+- **Source** — `GitSource` (clone a URL) or `LocalSource` (read a path).
+- **Backend** — `ProviderBackend` (any provider, via env key or per-request header key) or `SamplingBackend` (the MCP host's model). `pick_backend` chooses: an explicit key wins; otherwise a configured provider; otherwise host sampling; otherwise a clear error.
+
+The pipeline traverses files, generates per-file docs concurrently (bounded by a semaphore), then synthesizes a top-level `README.md`.
+
+## LLM providers
+
+| Provider | Configure via |
+|---|---|
+| Anthropic | `ANTHROPIC_API_KEY` env, or `X-Provider-API-Key` header |
+| OpenAI | `OPENAI_API_KEY` env, or header |
+| Azure OpenAI | `AZURE_OPENAI_API_KEY` + endpoint/deployment (see `.env.example`), or header |
+| AWS Bedrock | `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (env only) |
+| Ollama (local) | `provider="ollama"` (no key) |
+| None | MCP host sampling — the host's model writes the docs |
+
+## Hosting your own public endpoint
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/dharmikraval1/ai-document-creator)
+
+One click via the included [`render.yaml`](render.yaml) blueprint — it enables auto-deploy on every push to `main`, health checks, and safe public defaults (`BYOK_ONLY=true`, rate limiting on, Render hostname auto-allowed).
+
+The `Dockerfile` also runs anywhere that supplies a `PORT` (Fly.io, Railway, ...). The server serves Streamable HTTP at `/mcp`, legacy SSE at `/sse`, and a health probe at `/health`.
+
+Recommended env for a public deployment:
+
+| Variable | Value | Why |
+|---|---|---|
+| `MCP_ALLOWED_HOSTS` | your public hostname (e.g. `your-app.onrender.com`) | DNS-rebinding protection rejects unknown Host headers |
+| `BYOK_ONLY` | `true` | never spend *your* keys on strangers — users bring keys in headers or use sampling |
+| `RATE_LIMIT_RPM` | `20` (default) | per-client request cap; `0` disables |
+| `LOG_FORMAT` | `json` | structured logs |
+| `MCP_TRANSPORT` | `both` (default) / `streamable-http` / `sse` | which HTTP transports to serve |
+
+## Security model
+
+- **Keys**: header-only intake for remote users; passed explicitly to the provider client; never written to env, logs, or `repr()`; `BYOK_ONLY=true` guarantees the server's own keys are never used for requests.
+- **SSRF**: repo URLs must be HTTPS and must not resolve to private/reserved address space; DNS-rebinding protection on the HTTP transports.
+- **Filesystem**: hosted deployments refuse local-filesystem tools (unless `LOCAL_ROOT` opts in) and write repo docs to per-request temp dirs — callers can't read or write server paths.
+- **Abuse limits**: per-client rate limit, bounded pipeline concurrency, pipeline timeout, repo-size cap, per-file-size cap.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest -q          # 157 tests
+flake8 && mypy ai_doc_creator --ignore-missing-imports
+```
+
+Design specs, implementation plans, and phase status live in [planning/](planning/).
+
+## License
+
+[MIT](LICENSE)

ai_doc_creator-2.2.0/ai_doc_creator/__init__.py

@@ -0,0 +1,3 @@
+"""AI Document Creator — AI-powered documentation generator (MCP server + CLI)."""
+
+__version__ = "2.2.0"

ai_doc_creator-2.2.0/ai_doc_creator/cli.py

@@ -0,0 +1,100 @@
+# ai_doc_creator/cli.py
+import argparse
+import asyncio
+import logging
+import sys
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from .core.config import resolve_config  # noqa: E402
+from .core.backends import pick_backend, BackendError  # noqa: E402
+from .core.sources import GitSource, LocalSource  # noqa: E402
+from .core.file_traverser import FileTraverser  # noqa: E402
+from .core.graph import app  # noqa: E402
+from .core.doc_writer import DocumentationWriter  # noqa: E402
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+
+async def run(source, output_dir, config):
+    repo_path = None
+    try:
+        repo_path = source.prepare()
+        files = list(FileTraverser(repo_path, max_file_size_kb=config.max_file_size_kb).traverse())
+        logger.info("Found %d files to process.", len(files))
+        if not files:
+            logger.warning("No files found to document. Exiting.")
+            return
+
+        backend = pick_backend(config, ctx=None)  # CLI has no host -> requires a provider key
+        final_state = await app.ainvoke(
+            {
+                "repo_path": repo_path,
+                "files": files,
+                "documents": {},
+                "index_content": "",
+                "backend": backend,
+                "max_concurrency": config.max_concurrency,
+                "profile": config.profile,
+                "diagrams": config.diagrams,
+            }
+        )
+
+        DocumentationWriter(output_dir).write_docs(
+            final_state["documents"], final_state["index_content"]
+        )
+        logger.info("Documentation generation complete!")
+    finally:
+        if source:
+            source.cleanup()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="AI Document Creator")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--repo", help="GitHub repository URL")
+    group.add_argument("--path", help="Local project directory")
+    parser.add_argument("--output", default="docs", help="Output directory")
+    parser.add_argument(
+        "--provider", default=None, help="LLM provider (anthropic/openai/azure/bedrock/ollama)"
+    )
+    parser.add_argument("--model", default=None, help="Model name override")
+    parser.add_argument(
+        "--profile",
+        default="readme",
+        choices=["readme", "api", "architecture", "tutorial"],
+        help="Documentation style (default: readme)",
+    )
+    parser.add_argument(
+        "--no-diagrams",
+        action="store_true",
+        help="Disable Mermaid architecture diagrams and flow charts",
+    )
+    args = parser.parse_args()
+
+    config = resolve_config(
+        provider=args.provider,
+        model=args.model,
+        profile=args.profile,
+        diagrams=not args.no_diagrams,
+    )
+    source = GitSource(args.repo) if args.repo else LocalSource(args.path)
+
+    try:
+        asyncio.run(run(source, args.output, config))
+    except BackendError as exc:
+        logger.error("%s", exc)
+        sys.exit(1)
+    except Exception as exc:
+        logger.error("An error occurred: %s", exc)
+        import traceback
+
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ai_doc_creator-2.2.0/ai_doc_creator/core/__init__.py

@@ -0,0 +1 @@
+"""Core pipeline: config, backends, sources, guards, graph, cache, writer."""

ai_doc_creator-2.2.0/ai_doc_creator/core/backends.py

@@ -0,0 +1,126 @@
+# core/backends.py
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+
+from langchain.chat_models import init_chat_model  # imported at top so tests can monkeypatch it
+
+from .config import DocConfig
+
+
+class BackendError(RuntimeError):
+    """Raised when no usable LLM backend can be constructed."""
+
+
+def _content_to_text(content) -> str:
+    """Flatten a chat model response (str, or list of content blocks) to plain text."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict) and block.get("type") == "text":
+                parts.append(block.get("text", ""))
+        return "".join(parts)
+    return str(content)
+
+
+class CompletionBackend(ABC):
+    """Generates text from a prompt. The only thing the pipeline knows about an LLM."""
+
+    @abstractmethod
+    async def complete(self, prompt: str) -> str: ...
+
+
+class FakeBackend(CompletionBackend):
+    """Deterministic backend for tests — never calls a real model."""
+
+    def __init__(self, response: str = "FAKE DOC"):
+        self.response = response
+        self.calls: list[str] = []
+
+    async def complete(self, prompt: str) -> str:
+        self.calls.append(prompt)
+        return self.response
+
+
+class ProviderBackend(CompletionBackend):
+    """Calls a real provider (anthropic/openai/azure/bedrock/ollama) via LangChain."""
+
+    def __init__(self, config: DocConfig):
+        if not config.has_provider:
+            raise BackendError("ProviderBackend requires a provider")
+        if config.provider == "azure":
+            self._model = self._build_azure(config)
+        else:
+            # Pass model + provider separately so model names containing ':'
+            # (e.g. bedrock 'amazon.nova-pro-v1:0') are never mis-parsed.
+            # An explicit per-request key (BYOK) wins over any env credential.
+            extra: dict = {}
+            if config.api_key:
+                extra["api_key"] = config.api_key
+            self._model = init_chat_model(
+                model=config.resolved_model,
+                model_provider=config.lc_provider,
+                temperature=0,
+                **extra,
+            )
+
+    @staticmethod
+    def _build_azure(config: DocConfig):
+        from langchain_openai import AzureChatOpenAI
+
+        from pydantic import SecretStr
+
+        raw_key = config.api_key or os.getenv("AZURE_OPENAI_API_KEY")
+        return AzureChatOpenAI(
+            azure_deployment=config.model or os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME", "gpt-4o"),
+            api_version=os.getenv("AZURE_OPENAI_API_VERSION", "2024-12-01-preview"),
+            azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
+            api_key=SecretStr(raw_key) if raw_key else None,
+            temperature=0,
+        )
+
+    async def complete(self, prompt: str) -> str:
+        result = await self._model.ainvoke(prompt)
+        return _content_to_text(getattr(result, "content", result))
+
+
+class SamplingBackend(CompletionBackend):
+    """Asks the MCP host's own model to generate — zero API cost to the operator."""
+
+    def __init__(self, ctx, max_tokens: int = 4096):
+        self._ctx = ctx
+        self._max_tokens = max_tokens
+
+    async def complete(self, prompt: str) -> str:
+        from mcp.types import SamplingMessage, TextContent
+
+        result = await self._ctx.session.create_message(
+            messages=[
+                SamplingMessage(role="user", content=TextContent(type="text", text=prompt))
+            ],
+            max_tokens=self._max_tokens,
+        )
+        content = result.content
+        return content.text if getattr(content, "type", None) == "text" else str(content)
+
+
+def pick_backend(config: DocConfig, ctx=None) -> CompletionBackend:
+    """Choose a backend: provider key → retry-wrapped ProviderBackend;
+    MCP host ctx → SamplingBackend; otherwise raise BackendError.
+    """
+    from .retry import with_retry
+
+    if config.has_provider:
+        return with_retry(ProviderBackend(config))
+    if ctx is not None:
+        return SamplingBackend(ctx)
+    raise BackendError(
+        "No LLM available. Set a provider key (ANTHROPIC_API_KEY / OPENAI_API_KEY / "
+        "AZURE_OPENAI_API_KEY / AWS credentials), pass provider='ollama' for a local model, "
+        "or run inside an MCP host that supports sampling."
+    )