doc-code 0.1.0__tar.gz

doc_code-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 André Argôlo (argolo.dev)
+
+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.

doc_code-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: doc-code
+Version: 0.1.0
+Summary: Generate and safely apply AI-assisted source documentation.
+License-Expression: MIT
+Project-URL: Homepage, https://argolo.dev
+Project-URL: Documentation, https://argolo.dev
+Keywords: documentation,docstrings,developer-tools,generative-ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tree-sitter<0.26,>=0.25
+Requires-Dist: tree-sitter-javascript<0.24,>=0.23
+Requires-Dist: tree-sitter-typescript<0.24,>=0.23
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: mypy<2,>=1.11; extra == "dev"
+Requires-Dist: pip-audit<3,>=2.7; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-cov<8,>=5; extra == "dev"
+Requires-Dist: ruff<1,>=0.6; extra == "dev"
+Requires-Dist: commitar<2,>=1.0.0; extra == "dev"
+Requires-Dist: setuptools<84,>=83; extra == "dev"
+Dynamic: license-file
+
+# Doc Code
+
+[Leia em português](README-PTBR.md)
+
+`doc-code` generates documentation for Python, JavaScript, and TypeScript files using OpenAI, Gemini, or Ollama.
+
+By default, it displays a reviewable diff of the generated documentation. Use `--no-show-diff` to keep only the compact summary. To write the changes, run:
+
+```shell
+doc-code --output apply
+```
+
+For automation, combine `--yes` with `--output apply`. Each file is written as soon as its generation and validation complete; a later failure does not roll back files that were already applied. Immediately before writing, the file is compared with the preview. If it changed, `doc-code` does not overwrite it. With `confirm = true`, Doc Code shows and confirms each formatted docstring before applying it; with `confirm = false`, it reviews the complete generated file diff before applying it.
+
+## Installation and requirements
+
+`doc-code` requires Python 3.11 or later and Git on your `PATH`. To process JavaScript, install Node.js. For TypeScript/TSX, also install the `tsc` compiler (for example, `npm install --global typescript`). These executables validate generated syntax before any file is changed.
+
+For development, run `uv sync --locked --all-extras`. To install the published package, run `pip install doc-code`.
+
+## Usage
+
+```shell
+doc-code                         # Git changes: staged, unstaged, and untracked files
+doc-code src/a.py src/b.ts       # one or more specific files or directories
+doc-code --selection repository  # every eligible file
+doc-code --coverage all --format numpy
+doc-code --language Portuguese
+doc-code --request-scope symbol
+doc-code --no-show-diff          # compact preview without the unified diff
+doc-code --check                 # fail CI when symbols are undocumented
+doc-code --continue-on-error     # return status 0 when a file is skipped
+doc-code config init
+doc-code config show
+```
+
+Configuration uses this precedence: flags, `--config`, `DOC_CODE_*` environment variables, `.doc-code.toml`, user configuration, and defaults. Set `language = "Portuguese"` in `[documentation]`, use `DOC_CODE_LANGUAGE`, or pass `--language Portuguese` to control the generated language. Credentials use `OPENAI_API_KEY` or `GEMINI_API_KEY`; Ollama needs no credential.
+
+## Configuration (`.doc-code.toml`)
+
+Create a starter file with `doc-code config init`. The `[ai]`, `[documentation]`, and `[limits]` sections are merged into one configuration. The following are all accepted keys.
+
+### `[ai]`
+
+| Option | Values / default | Purpose |
+| --- | --- | --- |
+| `provider` | `openai`, `gemini`, or `ollama` · `ollama` | Selects the provider that generates descriptions. |
+| `model` | string · provider-dependent | Single model used when `models` is empty: `qwen2.5-coder:14b`, `gpt-5.6-sol`, or `gemini-3.6-flash`. |
+| `models` | list of up to 3 strings · `qwen2.5-coder:14b`, `gemma4:e4b` | Candidates rotated across attempts; takes precedence over `model`. An empty list uses only `model`. |
+| `endpoint` | URL or absent · provider default endpoint | Overrides the provider endpoint. Authenticated providers require HTTPS outside loopback. |
+| `max_input_tokens` | positive integer · `12000` | Estimated limit for the prompt sent to the model. |
+| `context_window_tokens` | positive integer · `32768` | Total model context window; must fit input and output. |
+| `max_output_tokens` | positive integer · `800` | Limit for generated response tokens. |
+| `temperature` | number · `0.2` | Controls variation; must be non-negative and is between 0 and 2 for OpenAI and Gemini. |
+| `timeout_seconds` | positive integer · `60` | Maximum duration of each provider call. |
+
+`max_input_tokens + max_output_tokens` cannot exceed `context_window_tokens`.
+
+### `[documentation]`
+
+| Option | Values / default | Purpose |
+| --- | --- | --- |
+| `selection` | `changes`, `repository` · `changes` | Chooses Git changes or every eligible file. |
+| `coverage` | `missing`, `minimal`, `all` · `missing` | `missing` includes every undocumented symbol; `minimal` includes only undocumented modules and top-level public APIs; `all` generates or replaces documentation for every symbol. |
+| `request_scope` | `file`, `symbol` · `file` | Chooses the context for each call: a complete file or one symbol. It does not change which symbols are eligible. |
+| `language` | non-empty string · `English` | Language requested for generated descriptions. |
+| `python_format` | `google`, `numpy`, `sphinx` · `google` | Parameter-section style for Python docstrings. |
+| `javascript_format` | `jsdoc` · `jsdoc` | Annotation style for JavaScript and TypeScript. |
+| `output` | `preview`, `apply` · `preview` | Shows a preview or writes changes. |
+| `confirm` | boolean · `true` | `true` shows and confirms each formatted docstring before applying it; `false` shows the generated file diff and confirms it before applying it. |
+
+### `[limits]`
+
+| Option | Values / default | Purpose |
+| --- | --- | --- |
+| `max_files_per_request` | positive integer · `50` | Maximum number of files in a scope. |
+| `max_file_bytes` | positive integer · `100000` | Maximum size of each processed file. |
+| `exclude` | list of glob patterns | Removes files from scope. Defaults exclude dependencies, build artifacts, minified files, and `package-lock.json`. |
+| `include` | list of glob patterns · empty list | When provided, keeps only files matching at least one pattern. |
+
+## Python docstring style
+
+Generated Python docstrings follow PEP 257: summaries end in a period; multiline docstrings have a blank line before and after sections, with closing quotes on their own line. Module and class docstrings are separated from the next declaration by one blank line. Empty lines have no indentation whitespace.
+
+Line length also follows the target project. For Python, `doc-code` uses `tool.ruff.line-length` and `tool.ruff.lint.pydocstyle.convention` from the nearest `pyproject.toml` (or 88 and the configured `doc-code` format when absent). Long summaries are separated from the description by a blank line according to D205. For JavaScript and TypeScript, it uses `max-len` from the nearest `eslint.config.js`, `eslint.config.mjs`, or `eslint.config.cjs` (or 100 when no rule exists). Descriptions and JSDoc lines are wrapped while accounting for indentation and delimiters.
+
+The `google`, `numpy`, and `sphinx` styles affect only the parameter section. To rewrite existing docstrings using one of these styles, run:
+
+```shell
+doc-code --coverage all --output apply --yes
+```
+
+For functions and methods, `doc-code` asks the model for a distinct description for every parameter and inserts it in the corresponding parameter section. The structured response must include every requested symbol and parameter; incomplete responses are rejected and generated again. Legacy integrations retain a fallback text for compatibility.
+
+By default, `request_scope = "file"` sends the file and all symbols that require generation in a single request. Use `request_scope = "symbol"` (or `--request-scope symbol`) to send each symbol in a separate request with only its code scope. This reduces context in large files but can increase latency and the number of calls. For modules, it sends a structural index — opening docstring, imports, constants, and public signatures — without bodies. With `output = "apply"` and `confirm = true`, each formatted docstring is reviewed and confirmed individually; a rejected docstring is reported and skipped while the remaining symbols continue. `--yes` applies without prompts. With `confirm = false`, the full file diff is reviewed before any of its changes are written.
+
+Regardless of `request_scope`, `coverage` decides which symbols are eligible and `request_scope` only changes the context unit sent to the model. Use `coverage = "all"` to rewrite existing documentation.
+
+Partial failures return status 1 after all remaining eligible files have been processed. Use `--continue-on-error` only when automation explicitly accepts partial results.

doc_code-0.1.0/README.md

@@ -0,0 +1,99 @@
+# Doc Code
+
+[Leia em português](README-PTBR.md)
+
+`doc-code` generates documentation for Python, JavaScript, and TypeScript files using OpenAI, Gemini, or Ollama.
+
+By default, it displays a reviewable diff of the generated documentation. Use `--no-show-diff` to keep only the compact summary. To write the changes, run:
+
+```shell
+doc-code --output apply
+```
+
+For automation, combine `--yes` with `--output apply`. Each file is written as soon as its generation and validation complete; a later failure does not roll back files that were already applied. Immediately before writing, the file is compared with the preview. If it changed, `doc-code` does not overwrite it. With `confirm = true`, Doc Code shows and confirms each formatted docstring before applying it; with `confirm = false`, it reviews the complete generated file diff before applying it.
+
+## Installation and requirements
+
+`doc-code` requires Python 3.11 or later and Git on your `PATH`. To process JavaScript, install Node.js. For TypeScript/TSX, also install the `tsc` compiler (for example, `npm install --global typescript`). These executables validate generated syntax before any file is changed.
+
+For development, run `uv sync --locked --all-extras`. To install the published package, run `pip install doc-code`.
+
+## Usage
+
+```shell
+doc-code                         # Git changes: staged, unstaged, and untracked files
+doc-code src/a.py src/b.ts       # one or more specific files or directories
+doc-code --selection repository  # every eligible file
+doc-code --coverage all --format numpy
+doc-code --language Portuguese
+doc-code --request-scope symbol
+doc-code --no-show-diff          # compact preview without the unified diff
+doc-code --check                 # fail CI when symbols are undocumented
+doc-code --continue-on-error     # return status 0 when a file is skipped
+doc-code config init
+doc-code config show
+```
+
+Configuration uses this precedence: flags, `--config`, `DOC_CODE_*` environment variables, `.doc-code.toml`, user configuration, and defaults. Set `language = "Portuguese"` in `[documentation]`, use `DOC_CODE_LANGUAGE`, or pass `--language Portuguese` to control the generated language. Credentials use `OPENAI_API_KEY` or `GEMINI_API_KEY`; Ollama needs no credential.
+
+## Configuration (`.doc-code.toml`)
+
+Create a starter file with `doc-code config init`. The `[ai]`, `[documentation]`, and `[limits]` sections are merged into one configuration. The following are all accepted keys.
+
+### `[ai]`
+
+| Option | Values / default | Purpose |
+| --- | --- | --- |
+| `provider` | `openai`, `gemini`, or `ollama` · `ollama` | Selects the provider that generates descriptions. |
+| `model` | string · provider-dependent | Single model used when `models` is empty: `qwen2.5-coder:14b`, `gpt-5.6-sol`, or `gemini-3.6-flash`. |
+| `models` | list of up to 3 strings · `qwen2.5-coder:14b`, `gemma4:e4b` | Candidates rotated across attempts; takes precedence over `model`. An empty list uses only `model`. |
+| `endpoint` | URL or absent · provider default endpoint | Overrides the provider endpoint. Authenticated providers require HTTPS outside loopback. |
+| `max_input_tokens` | positive integer · `12000` | Estimated limit for the prompt sent to the model. |
+| `context_window_tokens` | positive integer · `32768` | Total model context window; must fit input and output. |
+| `max_output_tokens` | positive integer · `800` | Limit for generated response tokens. |
+| `temperature` | number · `0.2` | Controls variation; must be non-negative and is between 0 and 2 for OpenAI and Gemini. |
+| `timeout_seconds` | positive integer · `60` | Maximum duration of each provider call. |
+
+`max_input_tokens + max_output_tokens` cannot exceed `context_window_tokens`.
+
+### `[documentation]`
+
+| Option | Values / default | Purpose |
+| --- | --- | --- |
+| `selection` | `changes`, `repository` · `changes` | Chooses Git changes or every eligible file. |
+| `coverage` | `missing`, `minimal`, `all` · `missing` | `missing` includes every undocumented symbol; `minimal` includes only undocumented modules and top-level public APIs; `all` generates or replaces documentation for every symbol. |
+| `request_scope` | `file`, `symbol` · `file` | Chooses the context for each call: a complete file or one symbol. It does not change which symbols are eligible. |
+| `language` | non-empty string · `English` | Language requested for generated descriptions. |
+| `python_format` | `google`, `numpy`, `sphinx` · `google` | Parameter-section style for Python docstrings. |
+| `javascript_format` | `jsdoc` · `jsdoc` | Annotation style for JavaScript and TypeScript. |
+| `output` | `preview`, `apply` · `preview` | Shows a preview or writes changes. |
+| `confirm` | boolean · `true` | `true` shows and confirms each formatted docstring before applying it; `false` shows the generated file diff and confirms it before applying it. |
+
+### `[limits]`
+
+| Option | Values / default | Purpose |
+| --- | --- | --- |
+| `max_files_per_request` | positive integer · `50` | Maximum number of files in a scope. |
+| `max_file_bytes` | positive integer · `100000` | Maximum size of each processed file. |
+| `exclude` | list of glob patterns | Removes files from scope. Defaults exclude dependencies, build artifacts, minified files, and `package-lock.json`. |
+| `include` | list of glob patterns · empty list | When provided, keeps only files matching at least one pattern. |
+
+## Python docstring style
+
+Generated Python docstrings follow PEP 257: summaries end in a period; multiline docstrings have a blank line before and after sections, with closing quotes on their own line. Module and class docstrings are separated from the next declaration by one blank line. Empty lines have no indentation whitespace.
+
+Line length also follows the target project. For Python, `doc-code` uses `tool.ruff.line-length` and `tool.ruff.lint.pydocstyle.convention` from the nearest `pyproject.toml` (or 88 and the configured `doc-code` format when absent). Long summaries are separated from the description by a blank line according to D205. For JavaScript and TypeScript, it uses `max-len` from the nearest `eslint.config.js`, `eslint.config.mjs`, or `eslint.config.cjs` (or 100 when no rule exists). Descriptions and JSDoc lines are wrapped while accounting for indentation and delimiters.
+
+The `google`, `numpy`, and `sphinx` styles affect only the parameter section. To rewrite existing docstrings using one of these styles, run:
+
+```shell
+doc-code --coverage all --output apply --yes
+```
+
+For functions and methods, `doc-code` asks the model for a distinct description for every parameter and inserts it in the corresponding parameter section. The structured response must include every requested symbol and parameter; incomplete responses are rejected and generated again. Legacy integrations retain a fallback text for compatibility.
+
+By default, `request_scope = "file"` sends the file and all symbols that require generation in a single request. Use `request_scope = "symbol"` (or `--request-scope symbol`) to send each symbol in a separate request with only its code scope. This reduces context in large files but can increase latency and the number of calls. For modules, it sends a structural index — opening docstring, imports, constants, and public signatures — without bodies. With `output = "apply"` and `confirm = true`, each formatted docstring is reviewed and confirmed individually; a rejected docstring is reported and skipped while the remaining symbols continue. `--yes` applies without prompts. With `confirm = false`, the full file diff is reviewed before any of its changes are written.
+
+Regardless of `request_scope`, `coverage` decides which symbols are eligible and `request_scope` only changes the context unit sent to the model. Use `coverage = "all"` to rewrite existing documentation.
+
+Partial failures return status 1 after all remaining eligible files have been processed. Use `--continue-on-error` only when automation explicitly accepts partial results.

doc_code-0.1.0/doc_code/__init__.py

@@ -0,0 +1,3 @@
+"""Doc Code generates and safely applies AI-assisted source documentation."""
+
+__version__ = "0.1.0"

doc_code-0.1.0/doc_code/ai.py

@@ -0,0 +1,206 @@
+"""Provider calls and strict JSON response validation for documentation descriptions."""
+
+from __future__ import annotations
+
+import json
+import os
+from math import ceil
+from typing import Any, cast
+from urllib.error import URLError
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+from .config import Settings
+from .errors import AIProviderError, AITimeoutError, DocGubError, InvalidAIResponseError
+from .symbols import Documentation, Symbol
+
+_MAX_PROVIDER_RESPONSE_BYTES = 1_000_000
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate tokens conservatively from the UTF-8 byte length."""
+    return ceil(len(text.encode("utf-8")) / 3)
+
+
+def prompt(content: str, symbols: list[Symbol], language: str = "English") -> str:
+    """Build the strict JSON prompt sent to a provider."""
+    names = [{"symbol": item.name, "kind": item.kind, "arguments": item.args} for item in symbols]
+    return (
+        "Return only a JSON object mapping each requested symbol to an object with "
+        "`description` (a concise factual description) and `arguments` (an object mapping "
+        "every requested argument name to its specific description). Use an empty `arguments` "
+        "object when a symbol has no arguments. Do not include Markdown or code fences. Write "
+        f"all documentation text in {json.dumps(language, ensure_ascii=False)}. Requested symbols: "
+        + json.dumps(names)
+        + "\n\nSOURCE:\n"
+        + content
+    )
+
+
+def _post(
+    url: str, payload: dict[str, Any], headers: dict[str, str], timeout: int
+) -> dict[str, Any]:
+    """Post JSON and convert transport or decoding failures to domain errors."""
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise AIProviderError("The AI provider endpoint must be an absolute HTTP(S) URL.")
+    try:
+        with urlopen(
+            Request(url, data=json.dumps(payload).encode(), headers=headers, method="POST"),
+            timeout=timeout,
+        ) as response:  # nosec B310 - user-configured endpoint
+            body = response.read(_MAX_PROVIDER_RESPONSE_BYTES + 1)
+            if len(body) > _MAX_PROVIDER_RESPONSE_BYTES:
+                raise AIProviderError("The AI provider response exceeds the supported size.")
+            decoded = json.loads(body)
+            if not isinstance(decoded, dict):
+                raise TypeError("The AI provider response must be a JSON object.")
+            return cast(dict[str, Any], decoded)
+    except TimeoutError as exc:
+        raise AITimeoutError(f"Unable to contact the AI provider: {exc}") from exc
+    except URLError as exc:
+        if isinstance(exc.reason, TimeoutError):
+            raise AITimeoutError(f"Unable to contact the AI provider: {exc.reason}") from exc
+        raise AIProviderError(f"Unable to contact the AI provider: {exc}") from exc
+    except (json.JSONDecodeError, KeyError, IndexError, TypeError) as exc:
+        raise AIProviderError("The AI provider returned an invalid response.") from exc
+
+
+def documentation_for(
+    content: str, symbols: list[Symbol], settings: Settings
+) -> dict[str, Documentation]:
+    """Generate validated documentation for the requested symbols."""
+    body = prompt(content, symbols, settings.language)
+    tokens = estimate_tokens(body)
+    if (
+        tokens > settings.max_input_tokens
+        or tokens + settings.max_output_tokens > settings.context_window_tokens
+    ):
+        raise DocGubError(
+            "AI input exceeds configured token limits; narrow the scope or increase limits."
+        )
+    if settings.provider == "openai":
+        key = os.getenv("OPENAI_API_KEY")
+        if not key:
+            raise DocGubError("OPENAI_API_KEY is not configured.")
+        data = _post(
+            settings.endpoint or "https://api.openai.com/v1/chat/completions",
+            {
+                "model": settings.model,
+                "messages": [{"role": "user", "content": body}],
+                "max_completion_tokens": settings.max_output_tokens,
+                "temperature": settings.temperature,
+            },
+            {"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+            settings.timeout_seconds,
+        )
+        answer = _provider_answer(data, "openai")
+    elif settings.provider == "gemini":
+        key = os.getenv("GEMINI_API_KEY")
+        if not key:
+            raise DocGubError("GEMINI_API_KEY is not configured.")
+        endpoint = settings.endpoint or (
+            "https://generativelanguage.googleapis.com/v1beta/models/"
+            f"{settings.model}:generateContent"
+        )
+        data = _post(
+            endpoint,
+            {"contents": [{"parts": [{"text": body}]}]},
+            {"Content-Type": "application/json", "x-goog-api-key": key},
+            settings.timeout_seconds,
+        )
+        answer = _provider_answer(data, "gemini")
+    else:
+        data = _post(
+            settings.endpoint or "http://localhost:11434/api/generate",
+            {
+                "model": settings.model,
+                "prompt": body,
+                "stream": False,
+                "options": {
+                    "temperature": settings.temperature,
+                    "num_ctx": settings.context_window_tokens,
+                    "num_predict": settings.max_output_tokens,
+                },
+            },
+            {"Content-Type": "application/json"},
+            settings.timeout_seconds,
+        )
+        answer = _provider_answer(data, "ollama")
+    return _documentation_response(answer, symbols)
+
+
+def _provider_answer(data: dict[str, Any], provider: str) -> str:
+    """Extract provider text while keeping malformed envelopes inside the domain boundary."""
+    try:
+        if provider == "openai":
+            answer = data["choices"][0]["message"]["content"]
+        elif provider == "gemini":
+            answer = data["candidates"][0]["content"]["parts"][0]["text"]
+        else:
+            answer = data["response"]
+    except (KeyError, IndexError, TypeError) as exc:
+        raise AIProviderError(f"The {provider} provider returned an invalid response.") from exc
+    if not isinstance(answer, str):
+        raise AIProviderError(f"The {provider} provider returned an invalid response.")
+    return answer
+
+
+def _documentation_response(answer: str, symbols: list[Symbol]) -> dict[str, Documentation]:
+    """Validate and normalize the structured documentation returned by a provider."""
+    if not isinstance(answer, str):
+        raise InvalidAIResponseError("The AI returned documentation in an invalid format.")
+    try:
+        parsed = json.loads(answer)
+    except (json.JSONDecodeError, TypeError) as exc:
+        raise InvalidAIResponseError("The AI returned invalid documentation JSON.") from exc
+    if not isinstance(parsed, dict):
+        raise InvalidAIResponseError("The AI response must be a JSON object of documentation.")
+
+    requested = {symbol.name: symbol for symbol in symbols}
+    if set(parsed) != set(requested):
+        raise InvalidAIResponseError("The AI response must document every requested symbol.")
+    normalized: dict[str, Documentation] = {}
+    for name, value in parsed.items():
+        if not isinstance(name, str) or name not in requested:
+            raise InvalidAIResponseError("The AI response contains an unexpected symbol.")
+        normalized[name] = _normalize_documentation(name, value, requested[name])
+    return normalized
+
+
+def _normalize_documentation(name: str, value: Any, symbol: Symbol) -> Documentation:
+    """Validate one symbol's generated description and argument mapping."""
+    if isinstance(value, str):
+        legacy_description = value.strip()
+        if not legacy_description:
+            raise InvalidAIResponseError("Each symbol must contain a non-empty description.")
+        return Documentation(legacy_description)
+    if not isinstance(value, dict):
+        raise InvalidAIResponseError("Each symbol must contain documentation details.")
+    structured_description = value.get("description")
+    arguments = value.get("arguments", {})
+    valid_arguments = isinstance(arguments, dict) and all(
+        isinstance(argument, str)
+        and isinstance(argument_description, str)
+        and bool(argument_description.strip())
+        for argument, argument_description in arguments.items()
+    )
+    if (
+        not isinstance(structured_description, str)
+        or not structured_description.strip()
+        or not valid_arguments
+    ):
+        raise InvalidAIResponseError(
+            "Each symbol must contain a non-empty description and argument descriptions."
+        )
+    if set(arguments) != set(symbol.args):
+        raise InvalidAIResponseError(
+            f"Documentation for `{name}` must describe every requested argument."
+        )
+    return Documentation(
+        structured_description.strip(),
+        {
+            argument: argument_description.strip()
+            for argument, argument_description in arguments.items()
+        },
+    )