docsmind 0.3.0__tar.gz → 0.4.0__tar.gz

{docsmind-0.3.0 → docsmind-0.4.0}/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-10-31
+
+### Added
+
+- The Mind: a chat agent (orchestrator, planner, tool-using executor, parallel subagents)
+  with a deterministic harness (context builder with prompt-cache breakpoint, summarizer,
+  memory writer). Answers carry verified `[S#]` citations.
+- Provider-neutral LLM layer with OpenAI and Anthropic streaming adapters.
+- Tools: `search`, `grep`, `read_pages`, `get_outline`, `list_documents`, `delegate`;
+  subagents: `researcher`, `change_analyzer`.
+- Migration `0004`: `conversations`, `messages`, `agent_memory` tables (run `docsmind db upgrade`).
+- HTTP: `POST /api/chat` (SSE), `GET/DELETE /api/conversations`, `GET /api/agent`.
+- UI: streaming chat in Workspace with live agent activity, markdown answers, citation chips
+  and source cards that open the PDF at the cited page; Activity lists saved conversations;
+  Agents reads the real registry. New frontend deps: `react-markdown`, `remark-gfm`.
+- `Docsmind.chat_result()`; `chat`/`achat` accept `conversation_id`; `docsmind chat` REPL keeps
+  the conversation.
+- Config: `agent_*` settings, `openai_base_url`, `openai_reasoning_effort`.
+
 ## [0.3.0] - 2026-10-03
 
 ### Added

{docsmind-0.3.0 → docsmind-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docsmind
-Version: 0.3.0
+Version: 0.4.0
 Summary: Chat with your documents. Version-aware retrieval, change analysis, and an editable table workspace, backed by Postgres/pgvector.
 Project-URL: Homepage, https://github.com/yauheniya-ai/docsmind
 Project-URL: Repository, https://github.com/yauheniya-ai/docsmind
@@ -68,9 +68,8 @@ Description-Content-Type: text/markdown
 Chat with your documents. Track what changed between versions, and why it matters.
 
 `docsmind` ingests PDFs (and soon DOCX/text) into a version-aware Postgres/pgvector
-store, and gives you an agent, **the Mind**, to chat with them. A built-in subagent,
-**diffra**, will do change analysis between document versions: what changed, where, and
-its compliance implications, with citations back to exact pages.
+store, and gives you an agent, **the Mind**, to analyze them. Built-in subagents
+will perform specialized tasks.
 
 > **Alpha.** Ingestion and inspection work today. Embeddings, chat and change analysis
 > are designed and scaffolded but not implemented yet; see [What works today](#what-works-today).
@@ -85,7 +84,7 @@ its compliance implications, with citations back to exact pages.
 | ✅ `docsmind doctor` | Checks database, blob storage and API keys, and tells you what to fix |
 | ✅ Table extraction | Extract and store tables skipping repeating ones (e.g. headers or footers) |
 | ✅ server + UI | FastAPI backend (`docsmind serve`) + React UI (`frontend/`): add documents, browse indexed content, image and table galleries |
-| 🚧 Chat agent (the Mind) | `docsmind chat` exists as a command, without an agent behind it yet |
+| ✅ Chat agent (the Mind) | Routes each question, plans complex ones, searches/reads your documents with tools, delegates to subagents, and answers with verified `[S#]` citations. Streams to the UI over SSE; conversations are saved |
 | 🚧 Image captioning | Images are extracted and stored; vision captioning is next |
 | 🚧 Embeddings + hybrid search | Chunks are stored without embeddings for now |
 | 🚧 Change analysis (diffra) | `docsmind diff` exists as a command, without an implementation yet |
@@ -130,8 +129,9 @@ docsmind doctor
 ```
 
 Configuration is environment-driven (`DOCSMIND_*`, or a `.env` file). Copy
-`.env.example` to `.env` to see every option. Model API keys aren't needed yet;
-they'll be required once embeddings and chat land.
+`.env.example` to `.env` to see every option. Chat needs an LLM key
+(`DOCSMIND_LLM_PROVIDER` plus `DOCSMIND_ANTHROPIC_API_KEY` or `DOCSMIND_OPENAI_API_KEY`);
+ingestion and browsing don't.
 
 ### 2. Ingest a PDF
 
@@ -187,13 +187,55 @@ cd ../docsmind
 python scripts/bundle_frontend.py
 ```
 
-### 5. Coming next
+### 5. Ask the Mind
+
+In the UI, open **Workspace** and ask a question (needs `docsmind[openai]` or `docsmind[anthropic]`
+plus an API key). From the terminal or Python:
+
+```bash
+docsmind chat "What are our data retention obligations?"   # one-shot
+docsmind chat                                              # REPL, keeps the conversation
+```
 
 ```python
-print(dm.chat("What are our data retention obligations?"))   # planned
-change_set = dm.compare(v1.id, v2.id)                        # planned (diffra)
+result = dm.chat_result("What are our data retention obligations?")
+print(result.answer, result.citations)
+change_set = dm.compare(v1.id, v2.id)   # planned (diffra)
 ```
 
+## How the Mind works
+
+```
+Question -> Orchestrator --simple--> Executor <-> Tools / Subagents -> Answer
+                 |                       ^
+                 +--complex--> Planner --+        Harness feeds every role:
+                                                  context builder, prompt cache,
+                                                  summarizer, memory
+```
+
+- **Orchestrator**: one cheap call that routes the question (`simple` or `complex`) and rewrites
+  it as a standalone question using the conversation so far.
+- **Planner** (complex only): a short list of steps the executor follows.
+- **Executor**: a bounded tool loop (`search`, `grep`, `read_pages`, `get_outline`,
+  `list_documents`, `delegate`). The last step forces an answer; tool errors go back to the
+  model, not the user; old tool results are elided when the context grows.
+- **Subagents** (`researcher`, `change_analyzer`): fresh context, a subset of the tools, run in
+  parallel, cannot delegate further.
+- **Harness**: deterministic code, not another agent. It orders the prompt stable-first so the
+  prefix caches, summarizes long histories, and saves durable notes to memory after each answer.
+- **Citations**: tools register passages as `S1, S2, ...`; the model cites `[S#]`; invented
+  handles are dropped and the rest renumbered by first appearance. Document text is treated as
+  untrusted data, never as instructions.
+- **Search** is Postgres full-text (ranked) plus exact-text grep until embeddings land.
+
+Tuning (all `DOCSMIND_*`): `AGENT_FAST_MODEL` (router/summarizer/memory model, defaults to
+`LLM_MODEL`), `AGENT_MAX_STEPS`, `AGENT_SUBAGENT_MAX_STEPS`, `AGENT_MEMORY_ENABLED`,
+`OPENAI_REASONING_EFFORT`, `OPENAI_BASE_URL`. See `.env.example`.
+
+HTTP: `POST /api/chat` streams Server-Sent Events (`route`, `plan`, `tool_start`, `tool_end`,
+`subagent_start`, `subagent_end`, `token`, `note`, `answer`, `error`, `done`);
+`GET /api/conversations[/{id}]`, `DELETE /api/conversations/{id}`, `GET /api/agent`.
+
 ## How ingestion works
 
 Ingestion is deliberately simple and predictable. There's no layout guessing, because
@@ -226,7 +268,8 @@ heuristics that work on one PDF break on the next.
 | `docsmind db up` / `upgrade` / `psql` | Start local Postgres, apply migrations, open psql |
 | `docsmind doctor` | Check your setup |
 | `docsmind serve [--host] [--port] [--reload]` | Run the FastAPI backend for the `frontend/` UI |
-| `docsmind chat`, `docsmind diff` | Planned |
+| `docsmind chat [question] [-c <collection>]` | Ask the Mind once, or start a REPL that keeps the conversation |
+| `docsmind diff` | Planned |
 
 ## Architecture
 
@@ -238,7 +281,7 @@ src/docsmind/
 │
 ├── domain/                # pure data + interfaces, no I/O
 │   ├── documents.py       # Document, DocumentVersion, Section, Chunk, Image, ParsedDocument
-│   ├── changes.py         # Change, ChangeSet, ImpactAssessment (diffra)
+│   ├── changes.py         # Change, ChangeSet, ImpactAssessment
 │   ├── citations.py       # Citation
 │   ├── tables.py          # AgentTable, TableRevision
 │   └── ports.py           # LLM, Embedder, VisionCaptioner, VectorStore, BlobStore, Parser
@@ -255,9 +298,9 @@ src/docsmind/
 │   ├── llm/ embeddings/ vision/ tracing/   # planned
 │
 ├── cli/                   # Typer app: ingest, versions, fulltext, outline, chunks, db, doctor
-├── retrieval/             # hybrid vector + keyword search (planned)
-├── agent/                 # the Mind + diffra subagent (planned)
-└── server/                # FastAPI app + routes backing frontend/ (documents: ingest, read back content/images/tables)
+├── retrieval/             # keyword (full-text) search helpers; vector search planned
+├── agent/                 # the Mind: orchestrator, planner, tool loop, tools, subagents, harness
+└── server/                # FastAPI app + routes backing frontend/ (documents, chat SSE, conversations)
 
 alembic/   tests/   examples/   docs/
 ```

{docsmind-0.3.0 → docsmind-0.4.0}/README.md

@@ -11,9 +11,8 @@
 Chat with your documents. Track what changed between versions, and why it matters.
 
 `docsmind` ingests PDFs (and soon DOCX/text) into a version-aware Postgres/pgvector
-store, and gives you an agent, **the Mind**, to chat with them. A built-in subagent,
-**diffra**, will do change analysis between document versions: what changed, where, and
-its compliance implications, with citations back to exact pages.
+store, and gives you an agent, **the Mind**, to analyze them. Built-in subagents
+will perform specialized tasks.
 
 > **Alpha.** Ingestion and inspection work today. Embeddings, chat and change analysis
 > are designed and scaffolded but not implemented yet; see [What works today](#what-works-today).
@@ -28,7 +27,7 @@ its compliance implications, with citations back to exact pages.
 | ✅ `docsmind doctor` | Checks database, blob storage and API keys, and tells you what to fix |
 | ✅ Table extraction | Extract and store tables skipping repeating ones (e.g. headers or footers) |
 | ✅ server + UI | FastAPI backend (`docsmind serve`) + React UI (`frontend/`): add documents, browse indexed content, image and table galleries |
-| 🚧 Chat agent (the Mind) | `docsmind chat` exists as a command, without an agent behind it yet |
+| ✅ Chat agent (the Mind) | Routes each question, plans complex ones, searches/reads your documents with tools, delegates to subagents, and answers with verified `[S#]` citations. Streams to the UI over SSE; conversations are saved |
 | 🚧 Image captioning | Images are extracted and stored; vision captioning is next |
 | 🚧 Embeddings + hybrid search | Chunks are stored without embeddings for now |
 | 🚧 Change analysis (diffra) | `docsmind diff` exists as a command, without an implementation yet |
@@ -73,8 +72,9 @@ docsmind doctor
 ```
 
 Configuration is environment-driven (`DOCSMIND_*`, or a `.env` file). Copy
-`.env.example` to `.env` to see every option. Model API keys aren't needed yet;
-they'll be required once embeddings and chat land.
+`.env.example` to `.env` to see every option. Chat needs an LLM key
+(`DOCSMIND_LLM_PROVIDER` plus `DOCSMIND_ANTHROPIC_API_KEY` or `DOCSMIND_OPENAI_API_KEY`);
+ingestion and browsing don't.
 
 ### 2. Ingest a PDF
 
@@ -130,13 +130,55 @@ cd ../docsmind
 python scripts/bundle_frontend.py
 ```
 
-### 5. Coming next
+### 5. Ask the Mind
+
+In the UI, open **Workspace** and ask a question (needs `docsmind[openai]` or `docsmind[anthropic]`
+plus an API key). From the terminal or Python:
+
+```bash
+docsmind chat "What are our data retention obligations?"   # one-shot
+docsmind chat                                              # REPL, keeps the conversation
+```
 
 ```python
-print(dm.chat("What are our data retention obligations?"))   # planned
-change_set = dm.compare(v1.id, v2.id)                        # planned (diffra)
+result = dm.chat_result("What are our data retention obligations?")
+print(result.answer, result.citations)
+change_set = dm.compare(v1.id, v2.id)   # planned (diffra)
 ```
 
+## How the Mind works
+
+```
+Question -> Orchestrator --simple--> Executor <-> Tools / Subagents -> Answer
+                 |                       ^
+                 +--complex--> Planner --+        Harness feeds every role:
+                                                  context builder, prompt cache,
+                                                  summarizer, memory
+```
+
+- **Orchestrator**: one cheap call that routes the question (`simple` or `complex`) and rewrites
+  it as a standalone question using the conversation so far.
+- **Planner** (complex only): a short list of steps the executor follows.
+- **Executor**: a bounded tool loop (`search`, `grep`, `read_pages`, `get_outline`,
+  `list_documents`, `delegate`). The last step forces an answer; tool errors go back to the
+  model, not the user; old tool results are elided when the context grows.
+- **Subagents** (`researcher`, `change_analyzer`): fresh context, a subset of the tools, run in
+  parallel, cannot delegate further.
+- **Harness**: deterministic code, not another agent. It orders the prompt stable-first so the
+  prefix caches, summarizes long histories, and saves durable notes to memory after each answer.
+- **Citations**: tools register passages as `S1, S2, ...`; the model cites `[S#]`; invented
+  handles are dropped and the rest renumbered by first appearance. Document text is treated as
+  untrusted data, never as instructions.
+- **Search** is Postgres full-text (ranked) plus exact-text grep until embeddings land.
+
+Tuning (all `DOCSMIND_*`): `AGENT_FAST_MODEL` (router/summarizer/memory model, defaults to
+`LLM_MODEL`), `AGENT_MAX_STEPS`, `AGENT_SUBAGENT_MAX_STEPS`, `AGENT_MEMORY_ENABLED`,
+`OPENAI_REASONING_EFFORT`, `OPENAI_BASE_URL`. See `.env.example`.
+
+HTTP: `POST /api/chat` streams Server-Sent Events (`route`, `plan`, `tool_start`, `tool_end`,
+`subagent_start`, `subagent_end`, `token`, `note`, `answer`, `error`, `done`);
+`GET /api/conversations[/{id}]`, `DELETE /api/conversations/{id}`, `GET /api/agent`.
+
 ## How ingestion works
 
 Ingestion is deliberately simple and predictable. There's no layout guessing, because
@@ -169,7 +211,8 @@ heuristics that work on one PDF break on the next.
 | `docsmind db up` / `upgrade` / `psql` | Start local Postgres, apply migrations, open psql |
 | `docsmind doctor` | Check your setup |
 | `docsmind serve [--host] [--port] [--reload]` | Run the FastAPI backend for the `frontend/` UI |
-| `docsmind chat`, `docsmind diff` | Planned |
+| `docsmind chat [question] [-c <collection>]` | Ask the Mind once, or start a REPL that keeps the conversation |
+| `docsmind diff` | Planned |
 
 ## Architecture
 
@@ -181,7 +224,7 @@ src/docsmind/
 │
 ├── domain/                # pure data + interfaces, no I/O
 │   ├── documents.py       # Document, DocumentVersion, Section, Chunk, Image, ParsedDocument
-│   ├── changes.py         # Change, ChangeSet, ImpactAssessment (diffra)
+│   ├── changes.py         # Change, ChangeSet, ImpactAssessment
 │   ├── citations.py       # Citation
 │   ├── tables.py          # AgentTable, TableRevision
 │   └── ports.py           # LLM, Embedder, VisionCaptioner, VectorStore, BlobStore, Parser
@@ -198,9 +241,9 @@ src/docsmind/
 │   ├── llm/ embeddings/ vision/ tracing/   # planned
 │
 ├── cli/                   # Typer app: ingest, versions, fulltext, outline, chunks, db, doctor
-├── retrieval/             # hybrid vector + keyword search (planned)
-├── agent/                 # the Mind + diffra subagent (planned)
-└── server/                # FastAPI app + routes backing frontend/ (documents: ingest, read back content/images/tables)
+├── retrieval/             # keyword (full-text) search helpers; vector search planned
+├── agent/                 # the Mind: orchestrator, planner, tool loop, tools, subagents, harness
+└── server/                # FastAPI app + routes backing frontend/ (documents, chat SSE, conversations)
 
 alembic/   tests/   examples/   docs/
 ```

{docsmind-0.3.0 → docsmind-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docsmind"
-version = "0.3.0"
+version = "0.4.0"
 description = "Chat with your documents. Version-aware retrieval, change analysis, and an editable table workspace, backed by Postgres/pgvector."
 readme = "README.md"
 requires-python = ">=3.10"

docsmind-0.4.0/src/docsmind/adapters/llm/__init__.py

@@ -0,0 +1,31 @@
+"""LLM adapter registry. SDKs are imported lazily inside each adapter, so a
+bare `pip install docsmind` never needs openai/anthropic installed."""
+
+from __future__ import annotations
+
+from docsmind.config import DocsmindConfig
+from docsmind.domain.errors import LLMConfigurationError
+from docsmind.domain.ports import LLM
+
+
+def create_llm(config: DocsmindConfig, *, model: str | None = None) -> LLM:
+    """Build the configured LLM. `model` overrides `config.llm_model` (used
+    for the fast model that routes, summarizes and writes memory)."""
+    provider = config.llm_provider.lower()
+    model = model or config.llm_model
+    if provider == "openai":
+        from docsmind.adapters.llm.openai_llm import OpenAILLM
+
+        return OpenAILLM(
+            api_key=config.openai_api_key,
+            model=model,
+            base_url=config.openai_base_url,
+            reasoning_effort=config.openai_reasoning_effort,
+        )
+    if provider == "anthropic":
+        from docsmind.adapters.llm.anthropic_llm import AnthropicLLM
+
+        return AnthropicLLM(api_key=config.anthropic_api_key, model=model)
+    raise LLMConfigurationError(
+        f"Unknown DOCSMIND_LLM_PROVIDER '{config.llm_provider}'. Use 'anthropic' or 'openai'."
+    )

docsmind-0.4.0/src/docsmind/adapters/llm/anthropic_llm.py

@@ -0,0 +1,152 @@
+"""Anthropic messages adapter.
+
+Prompt caching is explicit on Anthropic: the harness orders system blocks
+stable-first and flags where the stable prefix ends (`SystemBlock.cache`);
+those become `cache_control` breakpoints here. Tools are rendered before the
+system prompt in Anthropic's cache order, so they're covered by the same
+breakpoint.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from docsmind.domain.agent import (
+    LLMResponse,
+    Message,
+    StopReason,
+    SystemBlock,
+    ToolCall,
+    ToolChoice,
+    ToolSpec,
+    Usage,
+)
+from docsmind.domain.errors import LLMConfigurationError
+
+_STOP: dict[str, StopReason] = {
+    "end_turn": "end",
+    "stop_sequence": "end",
+    "tool_use": "tool_use",
+    "max_tokens": "max_tokens",
+}
+
+
+class AnthropicLLM:
+    def __init__(self, *, api_key: str | None, model: str, timeout: float = 120.0) -> None:
+        if not api_key:
+            raise LLMConfigurationError(
+                "Anthropic API key is not set. Add DOCSMIND_ANTHROPIC_API_KEY to your .env "
+                "(or set DOCSMIND_LLM_PROVIDER=openai)."
+            )
+        try:
+            from anthropic import AsyncAnthropic
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise LLMConfigurationError(
+                'The anthropic package is not installed. Run `pip install "docsmind[anthropic]"`.'
+            ) from exc
+        self.model = model
+        self._client = AsyncAnthropic(api_key=api_key, max_retries=3, timeout=timeout)
+
+    @staticmethod
+    def _system(blocks: list[SystemBlock]) -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        for b in blocks:
+            if not b.text.strip():
+                continue
+            item: dict[str, Any] = {"type": "text", "text": b.text}
+            if b.cache:
+                item["cache_control"] = {"type": "ephemeral"}
+            out.append(item)
+        return out
+
+    @staticmethod
+    def _convert(messages: list[Message]) -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        pending_results: list[dict[str, Any]] = []
+
+        def flush() -> None:
+            if pending_results:
+                out.append({"role": "user", "content": list(pending_results)})
+                pending_results.clear()
+
+        for m in messages:
+            if m.role == "tool":
+                # All results for one assistant turn go in a single user message.
+                pending_results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": m.tool_call_id,
+                        "content": m.content or "(empty)",
+                        "is_error": m.is_error,
+                    }
+                )
+                continue
+            flush()
+            if m.role == "user":
+                out.append({"role": "user", "content": m.content})
+            else:
+                blocks: list[dict[str, Any]] = []
+                if m.content.strip():
+                    blocks.append({"type": "text", "text": m.content})
+                blocks.extend(
+                    {"type": "tool_use", "id": c.id, "name": c.name, "input": c.arguments}
+                    for c in m.tool_calls
+                )
+                if blocks:
+                    out.append({"role": "assistant", "content": blocks})
+        flush()
+        return out
+
+    async def complete(
+        self,
+        messages: list[Message],
+        *,
+        system: list[SystemBlock],
+        tools: list[ToolSpec] | None = None,
+        tool_choice: ToolChoice = "auto",
+        max_tokens: int = 1024,
+        on_text: Callable[[str], Awaitable[None]] | None = None,
+    ) -> LLMResponse:
+        kwargs: dict[str, Any] = {
+            "model": self.model,
+            "max_tokens": max_tokens,
+            "system": self._system(system),
+            "messages": self._convert(messages),
+        }
+        if tools:
+            kwargs["tools"] = [
+                {"name": t.name, "description": t.description, "input_schema": t.parameters}
+                for t in tools
+            ]
+            kwargs["tool_choice"] = {"type": tool_choice}
+
+        async with self._client.messages.stream(**kwargs) as stream:
+            async for text in stream.text_stream:
+                if on_text and text:
+                    await on_text(text)
+            final = await stream.get_final_message()
+
+        text_parts: list[str] = []
+        calls: list[ToolCall] = []
+        for block in final.content:
+            if block.type == "text":
+                text_parts.append(block.text)
+            elif block.type == "tool_use":
+                calls.append(
+                    ToolCall(
+                        id=block.id,
+                        name=block.name,
+                        arguments=dict(block.input) if isinstance(block.input, dict) else {},
+                    )
+                )
+        u = final.usage
+        usage = Usage(
+            input_tokens=(u.input_tokens or 0)
+            + (getattr(u, "cache_read_input_tokens", 0) or 0)
+            + (getattr(u, "cache_creation_input_tokens", 0) or 0),
+            output_tokens=u.output_tokens or 0,
+            cached_input_tokens=getattr(u, "cache_read_input_tokens", 0) or 0,
+        )
+        stop: StopReason = "tool_use" if calls else _STOP.get(final.stop_reason or "", "other")
+        return LLMResponse(text="".join(text_parts), tool_calls=calls, stop_reason=stop, usage=usage)

docsmind-0.4.0/src/docsmind/adapters/llm/openai_llm.py

@@ -0,0 +1,182 @@
+"""OpenAI (and OpenAI-compatible) chat-completions adapter.
+
+Prompt caching on OpenAI is automatic for a stable prompt prefix, so this
+adapter just keeps the system blocks in the order the harness gave them
+(stable first) and doesn't need explicit cache markers.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from docsmind.domain.agent import (
+    LLMResponse,
+    Message,
+    StopReason,
+    SystemBlock,
+    ToolCall,
+    ToolChoice,
+    ToolSpec,
+    Usage,
+)
+from docsmind.domain.errors import LLMConfigurationError
+
+_FINISH: dict[str, StopReason] = {"stop": "end", "tool_calls": "tool_use", "length": "max_tokens"}
+log = logging.getLogger(__name__)
+
+
+def parse_tool_arguments(raw: str) -> tuple[dict[str, Any], str | None]:
+    """Models occasionally emit malformed JSON for tool arguments. Don't crash
+    the turn: report it so the tool layer can tell the model to retry."""
+    if not raw.strip():
+        return {}, None
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return {}, f"arguments were not valid JSON ({exc.msg})"
+    if not isinstance(value, dict):
+        return {}, "arguments must be a JSON object"
+    return value, None
+
+
+class OpenAILLM:
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        model: str,
+        base_url: str | None = None,
+        reasoning_effort: str | None = None,
+        timeout: float = 120.0,
+    ) -> None:
+        if not api_key:
+            raise LLMConfigurationError(
+                "OpenAI API key is not set. Add DOCSMIND_OPENAI_API_KEY to your .env "
+                "(or set DOCSMIND_LLM_PROVIDER=anthropic)."
+            )
+        try:
+            from openai import AsyncOpenAI, BadRequestError
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise LLMConfigurationError(
+                'The openai package is not installed. Run `pip install "docsmind[openai]"`.'
+            ) from exc
+        self.model = model
+        self._bad_request = BadRequestError
+        self._reasoning_effort = reasoning_effort
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url, max_retries=3, timeout=timeout)
+
+    @staticmethod
+    def _convert(messages: list[Message], system: list[SystemBlock]) -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        system_text = "\n\n".join(b.text for b in system if b.text.strip())
+        if system_text:
+            out.append({"role": "system", "content": system_text})
+        for m in messages:
+            if m.role == "user":
+                out.append({"role": "user", "content": m.content})
+            elif m.role == "assistant":
+                item: dict[str, Any] = {"role": "assistant", "content": m.content or None}
+                if m.tool_calls:
+                    item["tool_calls"] = [
+                        {
+                            "id": c.id,
+                            "type": "function",
+                            "function": {"name": c.name, "arguments": json.dumps(c.arguments)},
+                        }
+                        for c in m.tool_calls
+                    ]
+                out.append(item)
+            else:
+                out.append({"role": "tool", "tool_call_id": m.tool_call_id, "content": m.content})
+        return out
+
+    async def complete(
+        self,
+        messages: list[Message],
+        *,
+        system: list[SystemBlock],
+        tools: list[ToolSpec] | None = None,
+        tool_choice: ToolChoice = "auto",
+        max_tokens: int = 1024,
+        on_text: Callable[[str], Awaitable[None]] | None = None,
+    ) -> LLMResponse:
+        kwargs: dict[str, Any] = {
+            "model": self.model,
+            "messages": self._convert(messages, system),
+            "max_completion_tokens": max_tokens,
+            "stream": True,
+            "stream_options": {"include_usage": True},
+        }
+        if self._reasoning_effort:
+            kwargs["reasoning_effort"] = self._reasoning_effort
+        if tools:
+            kwargs["tools"] = [
+                {
+                    "type": "function",
+                    "function": {"name": t.name, "description": t.description, "parameters": t.parameters},
+                }
+                for t in tools
+            ]
+            kwargs["tool_choice"] = tool_choice
+
+        text_parts: list[str] = []
+        partial: dict[int, dict[str, str]] = {}
+        finish: str | None = None
+        usage = Usage()
+
+        try:
+            stream = await self._client.chat.completions.create(**kwargs)
+        except self._bad_request as exc:
+            # Some reasoning models refuse function tools on chat-completions
+            # unless reasoning is off. Remember that and retry once.
+            if not (tools and "reasoning_effort" in str(exc) and self._reasoning_effort != "none"):
+                raise
+            log.warning("%s rejects tools with reasoning; retrying with reasoning_effort='none'", self.model)
+            self._reasoning_effort = "none"
+            kwargs["reasoning_effort"] = "none"
+            stream = await self._client.chat.completions.create(**kwargs)
+        async for chunk in stream:
+            if chunk.usage:
+                details = getattr(chunk.usage, "prompt_tokens_details", None)
+                usage = Usage(
+                    input_tokens=chunk.usage.prompt_tokens or 0,
+                    output_tokens=chunk.usage.completion_tokens or 0,
+                    cached_input_tokens=(getattr(details, "cached_tokens", 0) or 0) if details else 0,
+                )
+            if not chunk.choices:
+                continue
+            choice = chunk.choices[0]
+            delta = choice.delta
+            if delta and delta.content:
+                text_parts.append(delta.content)
+                if on_text:
+                    await on_text(delta.content)
+            for tc in (delta.tool_calls or []) if delta else []:
+                slot = partial.setdefault(tc.index, {"id": "", "name": "", "args": ""})
+                if tc.id:
+                    slot["id"] = tc.id
+                if tc.function:
+                    if tc.function.name:
+                        slot["name"] += tc.function.name
+                    if tc.function.arguments:
+                        slot["args"] += tc.function.arguments
+            if choice.finish_reason:
+                finish = choice.finish_reason
+
+        calls: list[ToolCall] = []
+        for index in sorted(partial):
+            slot = partial[index]
+            args, error = parse_tool_arguments(slot["args"])
+            calls.append(
+                ToolCall(
+                    id=slot["id"] or f"call_{index}",
+                    name=slot["name"],
+                    arguments=args,
+                    parse_error=error,
+                )
+            )
+        stop: StopReason = "tool_use" if calls else _FINISH.get(finish or "", "other")
+        return LLMResponse(text="".join(text_parts), tool_calls=calls, stop_reason=stop, usage=usage)