iil-docs-agent 0.2.0__tar.gz

iil_docs_agent-0.2.0/.github/workflows/ci-docs-agent.yml

@@ -0,0 +1,42 @@
+name: Docs Agent CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "packages/docs-agent/**"
+  pull_request:
+    branches: [main]
+    paths:
+      - "packages/docs-agent/**"
+
+concurrency:
+  group: docs-agent-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/docs-agent
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install typer rich pytest pytest-cov libcst
+
+      - name: Run tests
+        run: |
+          python -m pytest tests/ -v --tb=short
+
+      - name: Smoke test CLI
+        run: |
+          PYTHONPATH=src python -m docs_agent.cli audit ../../ --scope docstrings --output json

iil_docs_agent-0.2.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*\.class
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+# Django
+*.log
+db.sqlite3
+media/
+staticfiles/
+# Environment
+.env
+.env.local
+.env.prod
+
+# Secrets (ADR-045) — NEVER commit plaintext
+secrets.env
+!secrets.enc.env
+# IDE
+.idea/
+.vscode/
+*.swp
+# OS
+.DS_Store
+Thumbs.db
+# Large files
+*.sqlite3
+*.log
+output_batch/
+app_backup/
+docs_legacy/
+# Sphinx build output
+docs/_build/
+*:Zone.Identifier
+# Local Windsurf/MCP config — machine-specific, never commit
+.windsurf/mcp_config.json
+# Local infra plaintext secrets — NEVER commit
+infra/*.env
+infra/*.key
+# Validate-ports CI draft (not yet integrated)
+.github/workflows/validate-ports.yml
+# Markdownlint local config override
+.markdownlint.json
+# Concept review drafts (local working copies, not for VCS)
+docs/concepts/REVIEW-*
+env_loader.py

iil_docs_agent-0.2.0/.pre-commit-hooks.yaml

@@ -0,0 +1,17 @@
+- id: docs-agent-coverage
+  name: docs-agent docstring coverage
+  description: Check docstring coverage meets minimum threshold
+  entry: docs-agent audit --scope docstrings --output table
+  language: python
+  types: [python]
+  pass_filenames: false
+  additional_dependencies: ["typer>=0.12.0", "rich>=13.0.0"]
+
+- id: docs-agent-coverage-strict
+  name: docs-agent coverage (strict)
+  description: Fail if docstring coverage is below 50%
+  entry: docs-agent audit --scope docstrings --min-coverage 50
+  language: python
+  types: [python]
+  pass_filenames: false
+  additional_dependencies: ["typer>=0.12.0", "rich>=13.0.0"]

iil_docs_agent-0.2.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: iil-docs-agent
+Version: 0.2.0
+Summary: AI-assisted documentation quality agent — AST scanner, DIATAXIS classifier, CLI
+Author: Achim Dehnert
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: libcst>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: httpx>=0.27.0; extra == 'llm'
+Requires-Dist: libcst>=1.1.0; extra == 'llm'
+Requires-Dist: openai>=1.0.0; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# Docs Agent
+
+AI-assisted documentation quality tool for Python projects.
+
+Scans codebases for docstring coverage, classifies documentation files using the
+[DIATAXIS framework](https://diataxis.fr/), and generates missing docstrings via LLM.
+
+## Features
+
+- **Docstring Coverage Audit** — AST-based scanning of Python files with per-module reporting
+- **DIATAXIS Classification** — Heuristic + LLM-powered classification of docs into tutorial/guide/reference/explanation
+- **LLM Docstring Generation** — Batch generation of Google-style docstrings via llm_mcp gateway or OpenAI API
+- **Non-Destructive Code Insertion** — Insert generated docstrings using libcst while preserving all formatting
+- **Pre-Commit Hooks** — Enforce coverage thresholds in CI/CD pipelines
+- **CI Integration** — GitHub Actions workflow for automated testing
+
+## Installation
+
+```bash
+# From platform monorepo (editable, recommended)
+pip install -e packages/docs-agent
+
+# With LLM support (httpx, openai, libcst)
+pip install -e "packages/docs-agent[llm]"
+
+# With dev tools (pytest, coverage)
+pip install -e "packages/docs-agent[dev]"
+
+# From GitHub (in requirements.txt)
+docs-agent @ git+https://github.com/achimdehnert/platform.git@main#subdirectory=packages/docs-agent
+```
+
+## Quick Start
+
+```bash
+# Audit docstring coverage
+docs-agent audit /path/to/repo
+
+# Audit only apps/ directory
+docs-agent audit /path/to/repo --apps-only
+
+# JSON output for CI
+docs-agent audit /path/to/repo --output json
+
+# Fail if coverage < 60%
+docs-agent audit /path/to/repo --min-coverage 60
+
+# DIATAXIS only
+docs-agent audit /path/to/repo --scope diataxis
+
+# Refine low-confidence classifications via LLM
+docs-agent audit /path/to/repo --scope diataxis --refine
+```
+
+## CLI Reference
+
+### `docs-agent audit`
+
+Audit a repository for documentation quality.
+
+```text
+Usage: docs-agent audit [OPTIONS] REPO_PATH
+
+Arguments:
+  REPO_PATH    Path to the repository root [required]
+
+Options:
+  --scope TEXT           Audit scope: docstrings, diataxis, or all [default: all]
+  --apps-only            Only scan apps/ directory for docstrings
+  --min-coverage FLOAT   Fail if docstring coverage is below this %
+  --output TEXT          Output format: table or json [default: table]
+  --refine               Use LLM to refine low-confidence DIATAXIS classifications
+  --llm-url TEXT         URL of the llm_mcp HTTP gateway [default: http://localhost:8100]
+```
+
+### `docs-agent generate`
+
+Generate docstrings for undocumented code items via LLM.
+
+```text
+Usage: docs-agent generate [OPTIONS] REPO_PATH
+
+Arguments:
+  REPO_PATH    Path to the repository root [required]
+
+Options:
+  --apps-only            Only scan apps/ directory
+  --dry-run / --apply    Preview changes (default) or apply them
+  --max-items INTEGER    Maximum items to generate docstrings for [default: 20]
+  --llm-url TEXT         URL of the llm_mcp HTTP gateway [default: http://localhost:8100]
+  --model TEXT           LLM model name [default: gpt-4o-mini]
+```
+
+## Example Output
+
+### Docstring Coverage Table
+
+```text
+                    Module Coverage
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
+┃ Module                        ┃ Items ┃ Documented ┃ Coverage ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╉━━━━━━━╉━━━━━━━━━━━━╉━━━━━━━━━━┩
+│ apps/core/models.py           │    12 │          8 │ 67%      │
+│ apps/core/services.py         │     6 │          6 │ 100%     │
+│ apps/core/views.py            │     9 │          3 │ 33%      │
+└───────────────────────────────┴───────┴────────────┴──────────┘
+
+Total: 17/27 items documented (63.0%)
+```
+
+### DIATAXIS Classification
+
+```text
+              DIATAXIS Classification
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Document                    ┃  Quadrant   ┃ Confidence ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╉━━━━━━━━━━━━━╉━━━━━━━━━━━━┩
+│ docs/getting-started.md     │  tutorial   │        85% │
+│ docs/deploy-guide.md        │    guide    │        72% │
+│ docs/api-reference.md       │  reference  │        90% │
+│ docs/adr/ADR-001.md         │ explanation │        78% │
+└─────────────────────────────┴─────────────┴────────────┘
+```
+
+## Pre-Commit Integration
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/achimdehnert/platform
+    rev: main
+    hooks:
+      - id: docs-agent-coverage
+        args: ["--scope", "docstrings", "--min-coverage", "50"]
+```
+
+## Architecture
+
+```text
+docs_agent/
+├── analyzer/
+│   ├── ast_scanner.py          # AST-based docstring coverage scanning
+│   ├── diataxis_classifier.py  # Heuristic DIATAXIS classification
+│   └── llm_classifier.py       # LLM fallback for low-confidence docs
+├── generator/
+│   ├── docstring_gen.py         # Batch LLM docstring generation
+│   └── code_inserter.py         # Non-destructive libcst insertion
+├── cli.py                       # Typer CLI (audit + generate commands)
+├── llm_client.py                # HTTP gateway + OpenAI fallback
+├── models.py                    # Data models (CodeItem, Coverage, etc.)
+└── prompts.py                   # LLM prompt templates
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `DOCS_AGENT_LLM_URL` | `http://localhost:8100` | llm_mcp gateway URL |
+| `DOCS_AGENT_LLM_MODEL` | `gpt-4o-mini` | LLM model name |
+| `OPENAI_API_KEY` | — | Direct OpenAI fallback (optional) |
+
+### LLM Backend
+
+The docs-agent tries backends in this order:
+
+1. **llm_mcp HTTP gateway** (default, `http://localhost:8100`) — production setup
+2. **Direct OpenAI API** — fallback if gateway is down and `OPENAI_API_KEY` is set
+
+## Development
+
+```bash
+cd packages/docs-agent
+
+# Install with dev + LLM extras
+pip install -e ".[dev,llm]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=docs_agent --cov-report=term-missing
+```
+
+## Related
+
+- **ADR-046**: Documentation Quality Standards (defines the docs-agent specification)
+- **DIATAXIS**: <https://diataxis.fr/> — Documentation framework
+- **Platform**: <https://github.com/achimdehnert/platform> — Monorepo
+
+## License
+
+MIT

iil_docs_agent-0.2.0/README.md

@@ -0,0 +1,195 @@
+# Docs Agent
+
+AI-assisted documentation quality tool for Python projects.
+
+Scans codebases for docstring coverage, classifies documentation files using the
+[DIATAXIS framework](https://diataxis.fr/), and generates missing docstrings via LLM.
+
+## Features
+
+- **Docstring Coverage Audit** — AST-based scanning of Python files with per-module reporting
+- **DIATAXIS Classification** — Heuristic + LLM-powered classification of docs into tutorial/guide/reference/explanation
+- **LLM Docstring Generation** — Batch generation of Google-style docstrings via llm_mcp gateway or OpenAI API
+- **Non-Destructive Code Insertion** — Insert generated docstrings using libcst while preserving all formatting
+- **Pre-Commit Hooks** — Enforce coverage thresholds in CI/CD pipelines
+- **CI Integration** — GitHub Actions workflow for automated testing
+
+## Installation
+
+```bash
+# From platform monorepo (editable, recommended)
+pip install -e packages/docs-agent
+
+# With LLM support (httpx, openai, libcst)
+pip install -e "packages/docs-agent[llm]"
+
+# With dev tools (pytest, coverage)
+pip install -e "packages/docs-agent[dev]"
+
+# From GitHub (in requirements.txt)
+docs-agent @ git+https://github.com/achimdehnert/platform.git@main#subdirectory=packages/docs-agent
+```
+
+## Quick Start
+
+```bash
+# Audit docstring coverage
+docs-agent audit /path/to/repo
+
+# Audit only apps/ directory
+docs-agent audit /path/to/repo --apps-only
+
+# JSON output for CI
+docs-agent audit /path/to/repo --output json
+
+# Fail if coverage < 60%
+docs-agent audit /path/to/repo --min-coverage 60
+
+# DIATAXIS only
+docs-agent audit /path/to/repo --scope diataxis
+
+# Refine low-confidence classifications via LLM
+docs-agent audit /path/to/repo --scope diataxis --refine
+```
+
+## CLI Reference
+
+### `docs-agent audit`
+
+Audit a repository for documentation quality.
+
+```text
+Usage: docs-agent audit [OPTIONS] REPO_PATH
+
+Arguments:
+  REPO_PATH    Path to the repository root [required]
+
+Options:
+  --scope TEXT           Audit scope: docstrings, diataxis, or all [default: all]
+  --apps-only            Only scan apps/ directory for docstrings
+  --min-coverage FLOAT   Fail if docstring coverage is below this %
+  --output TEXT          Output format: table or json [default: table]
+  --refine               Use LLM to refine low-confidence DIATAXIS classifications
+  --llm-url TEXT         URL of the llm_mcp HTTP gateway [default: http://localhost:8100]
+```
+
+### `docs-agent generate`
+
+Generate docstrings for undocumented code items via LLM.
+
+```text
+Usage: docs-agent generate [OPTIONS] REPO_PATH
+
+Arguments:
+  REPO_PATH    Path to the repository root [required]
+
+Options:
+  --apps-only            Only scan apps/ directory
+  --dry-run / --apply    Preview changes (default) or apply them
+  --max-items INTEGER    Maximum items to generate docstrings for [default: 20]
+  --llm-url TEXT         URL of the llm_mcp HTTP gateway [default: http://localhost:8100]
+  --model TEXT           LLM model name [default: gpt-4o-mini]
+```
+
+## Example Output
+
+### Docstring Coverage Table
+
+```text
+                    Module Coverage
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
+┃ Module                        ┃ Items ┃ Documented ┃ Coverage ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╉━━━━━━━╉━━━━━━━━━━━━╉━━━━━━━━━━┩
+│ apps/core/models.py           │    12 │          8 │ 67%      │
+│ apps/core/services.py         │     6 │          6 │ 100%     │
+│ apps/core/views.py            │     9 │          3 │ 33%      │
+└───────────────────────────────┴───────┴────────────┴──────────┘
+
+Total: 17/27 items documented (63.0%)
+```
+
+### DIATAXIS Classification
+
+```text
+              DIATAXIS Classification
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Document                    ┃  Quadrant   ┃ Confidence ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╉━━━━━━━━━━━━━╉━━━━━━━━━━━━┩
+│ docs/getting-started.md     │  tutorial   │        85% │
+│ docs/deploy-guide.md        │    guide    │        72% │
+│ docs/api-reference.md       │  reference  │        90% │
+│ docs/adr/ADR-001.md         │ explanation │        78% │
+└─────────────────────────────┴─────────────┴────────────┘
+```
+
+## Pre-Commit Integration
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/achimdehnert/platform
+    rev: main
+    hooks:
+      - id: docs-agent-coverage
+        args: ["--scope", "docstrings", "--min-coverage", "50"]
+```
+
+## Architecture
+
+```text
+docs_agent/
+├── analyzer/
+│   ├── ast_scanner.py          # AST-based docstring coverage scanning
+│   ├── diataxis_classifier.py  # Heuristic DIATAXIS classification
+│   └── llm_classifier.py       # LLM fallback for low-confidence docs
+├── generator/
+│   ├── docstring_gen.py         # Batch LLM docstring generation
+│   └── code_inserter.py         # Non-destructive libcst insertion
+├── cli.py                       # Typer CLI (audit + generate commands)
+├── llm_client.py                # HTTP gateway + OpenAI fallback
+├── models.py                    # Data models (CodeItem, Coverage, etc.)
+└── prompts.py                   # LLM prompt templates
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `DOCS_AGENT_LLM_URL` | `http://localhost:8100` | llm_mcp gateway URL |
+| `DOCS_AGENT_LLM_MODEL` | `gpt-4o-mini` | LLM model name |
+| `OPENAI_API_KEY` | — | Direct OpenAI fallback (optional) |
+
+### LLM Backend
+
+The docs-agent tries backends in this order:
+
+1. **llm_mcp HTTP gateway** (default, `http://localhost:8100`) — production setup
+2. **Direct OpenAI API** — fallback if gateway is down and `OPENAI_API_KEY` is set
+
+## Development
+
+```bash
+cd packages/docs-agent
+
+# Install with dev + LLM extras
+pip install -e ".[dev,llm]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=docs_agent --cov-report=term-missing
+```
+
+## Related
+
+- **ADR-046**: Documentation Quality Standards (defines the docs-agent specification)
+- **DIATAXIS**: <https://diataxis.fr/> — Documentation framework
+- **Platform**: <https://github.com/achimdehnert/platform> — Monorepo
+
+## License
+
+MIT

iil_docs_agent-0.2.0/docs/Makefile

@@ -0,0 +1,12 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

iil_docs_agent-0.2.0/docs/api/analyzer.rst

@@ -0,0 +1,38 @@
+Analyzer
+========
+
+AST Scanner
+-----------
+
+.. module:: docs_agent.analyzer.ast_scanner
+   :synopsis: AST-based docstring coverage scanning.
+
+.. autofunction:: scan_repo
+
+.. autofunction:: scan_module
+
+DIATAXIS Classifier (Heuristic)
+-------------------------------
+
+.. module:: docs_agent.analyzer.diataxis_classifier
+   :synopsis: Heuristic DIATAXIS classification via trigger words.
+
+.. autofunction:: classify_file
+
+.. autofunction:: classify_repo
+
+.. autodata:: DOC_EXTENSIONS
+
+.. autodata:: SKIP_DIRS
+
+DIATAXIS Classifier (LLM)
+--------------------------
+
+.. module:: docs_agent.analyzer.llm_classifier
+   :synopsis: LLM-based fallback classifier for low-confidence documents.
+
+.. autofunction:: reclassify_low_confidence
+
+.. autodata:: DEFAULT_THRESHOLD
+
+.. autodata:: PREVIEW_CHARS

iil_docs_agent-0.2.0/docs/api/cli.rst

@@ -0,0 +1,9 @@
+CLI Module
+==========
+
+.. module:: docs_agent.cli
+   :synopsis: Typer-based CLI for docs-agent.
+
+.. autofunction:: audit
+
+.. autofunction:: generate

iil_docs_agent-0.2.0/docs/api/generator.rst

@@ -0,0 +1,30 @@
+Generator
+=========
+
+Docstring Generator
+-------------------
+
+.. module:: docs_agent.generator.docstring_gen
+   :synopsis: LLM-based batch docstring generation.
+
+.. autoclass:: GeneratedDocstring
+   :members:
+   :undoc-members:
+
+.. autofunction:: generate_docstrings
+
+.. autodata:: BATCH_SIZE
+
+Code Inserter
+-------------
+
+.. module:: docs_agent.generator.code_inserter
+   :synopsis: Non-destructive docstring insertion via libcst.
+
+.. autoclass:: InsertionResult
+   :members:
+   :undoc-members:
+
+.. autofunction:: insert_docstrings
+
+.. autodata:: MODULE_DOCSTRING_KEY

iil_docs_agent-0.2.0/docs/api/llm_client.rst

@@ -0,0 +1,15 @@
+LLM Client
+==========
+
+.. module:: docs_agent.llm_client
+   :synopsis: Async LLM client with HTTP gateway and OpenAI fallback.
+
+.. autoclass:: LLMConfig
+   :members:
+   :undoc-members:
+
+.. autoclass:: LLMResponse
+   :members:
+   :undoc-members:
+
+.. autofunction:: generate

iil_docs_agent-0.2.0/docs/api/models.rst

@@ -0,0 +1,29 @@
+Data Models
+===========
+
+.. module:: docs_agent.models
+   :synopsis: Data models for docs-agent analysis results.
+
+.. autoclass:: ItemKind
+   :members:
+   :undoc-members:
+
+.. autoclass:: DiaxisQuadrant
+   :members:
+   :undoc-members:
+
+.. autoclass:: CodeItem
+   :members:
+   :undoc-members:
+
+.. autoclass:: ModuleCoverage
+   :members:
+   :undoc-members:
+
+.. autoclass:: RepoCoverage
+   :members:
+   :undoc-members:
+
+.. autoclass:: DiaxisClassification
+   :members:
+   :undoc-members:

iil_docs_agent-0.2.0/docs/api/prompts.rst

@@ -0,0 +1,21 @@
+Prompt Templates
+================
+
+.. module:: docs_agent.prompts
+   :synopsis: LLM prompt templates for docstring generation and DIATAXIS classification.
+
+Docstring Generation
+--------------------
+
+.. autodata:: SYSTEM_DOCSTRING
+
+.. autodata:: PROMPT_DOCSTRING_SINGLE
+
+.. autodata:: PROMPT_DOCSTRING_BATCH
+
+DIATAXIS Classification
+-----------------------
+
+.. autodata:: SYSTEM_DIATAXIS
+
+.. autodata:: PROMPT_DIATAXIS_CLASSIFY