docsmith-ai 0.2.1__tar.gz

docsmith_ai-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Run tests
+        run: pytest --cov=docsmith --cov-report=term-missing
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

docsmith_ai-0.2.1/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project
+docsmith-output/
+*.log
+
+# Config (user secrets)
+# Note: ~/.docsmith/ is in home dir, not repo
+
+# Prompt file (development only)
+prompt.txt

docsmith_ai-0.2.1/AGENTS.md

@@ -0,0 +1,119 @@
+# AGENTS.md — DocSmith Repository Intelligence
+
+> This file provides repository-level instructions for AI coding agents.
+> Consult this before making any changes.
+
+---
+
+## Project Vision
+
+DocSmith is an AI-powered documentation engineer CLI that analyzes GitHub repositories,
+understands their structure, extracts intelligence, and generates production-ready documentation.
+
+**Core Principle:** Every generated document must contain repository-specific information.
+No generic AI slop. The output should feel like it was written by a human maintainer
+who deeply understands the codebase.
+
+---
+
+## Architecture Rules
+
+### Pipeline
+
+```
+Repository URL → GitHub Fetcher → Parser → Analyzer → RepoContext → Planner → Writer → Reviewer → Scorer → Output
+```
+
+### Module Responsibilities
+
+| Module | Responsibility |
+|--------|---------------|
+| `docsmith/github/` | Fetch repository data via GitHub REST API |
+| `docsmith/analysis/` | Extract structured intelligence from raw repo data |
+| `docsmith/ai/` | AI provider abstraction + prompt management |
+| `docsmith/generation/` | Plan, write, review, score documentation |
+| `docsmith/generation/evidence.py` | Build the bounded, redacted evidence brief that grounds every model call |
+| `docsmith/config/` | Settings management and persistent storage |
+| `docsmith/output/` | File output, preview, and summary display |
+| `docsmith/models/` | Pydantic data models shared across modules |
+
+### Key Constraints
+
+1. **Never send raw repository content to the LLM.** All model input goes through the
+   analysis pipeline and `docsmith/generation/evidence.py`, which selects, caps, and
+   redacts what is sent. Prompt templates must consume the `{{ evidence }}` block and
+   must not invent facts that are absent from it.
+2. **Provider abstraction is mandatory.** All AI calls go through the provider interface.
+3. **Pydantic models everywhere.** All data structures use Pydantic for validation.
+4. **Rich terminal output.** All user-facing output uses the Rich library.
+5. **Graceful error handling.** Every failure mode has an actionable error message.
+
+---
+
+## Coding Standards
+
+- **Python 3.10+** with type hints on all function signatures
+- **Pydantic v2** for all data models
+- **`ruff`** for linting (`ruff check .`)
+- **`ruff format`** for formatting (`ruff format .`)
+- **`pytest`** for testing (`pytest -v`)
+- **Docstrings** on all public classes and functions (Google style)
+- **No wildcard imports**
+- **No mutable default arguments**
+- **Async-ready** where applicable (AI providers)
+
+---
+
+## Testing Commands
+
+```bash
+# Run all tests
+pytest -v
+
+# Run with coverage
+pytest --cov=docsmith --cov-report=term-missing
+
+# Run specific test module
+pytest tests/test_analyzer.py -v
+
+# Lint
+ruff check .
+
+# Format
+ruff format .
+```
+
+---
+
+## File Naming Conventions
+
+- Snake_case for all Python files
+- Models use singular nouns (`repo_context.py`, not `repo_contexts.py`)
+- Providers use `<name>_provider.py` pattern (except Gemini which is `gemini.py`)
+- Prompt templates use `.txt` extension in `docsmith/ai/prompts/`
+
+---
+
+## Dependencies
+
+Core: `typer`, `rich`, `questionary`, `requests`, `pyperclip`, `pydantic`, `jinja2`
+
+AI Providers: `google-genai`, `openai`, `anthropic`, `mistralai`
+
+Dev: `pytest`, `pytest-cov`, `ruff`, `pytest-mock`
+
+---
+
+## Configuration
+
+User config stored at `~/.docsmith/config.json`
+Cache stored at `~/.docsmith/cache/`
+
+First-run triggers an interactive setup wizard for provider selection and API key input.
+
+Environment variables override the config file and work without one:
+`DOCSMITH_PROVIDER`, `DOCSMITH_<PROVIDER>_API_KEY`, `DOCSMITH_MODEL`, and
+`DOCSMITH_GITHUB_TOKEN`. Conventional names such as `GEMINI_API_KEY`,
+`OPENAI_API_KEY`, and `GITHUB_TOKEN` are also accepted. Environment keys must
+never be persisted to disk. Non-interactive runs must use `--quick`; commands
+fail fast instead of prompting when no TTY is attached.

docsmith_ai-0.2.1/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to DocSmith will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1] - 2026-10-20
+
+### Added
+- **Evidence-grounded generation**: a new evidence builder
+  (`docsmith/generation/evidence.py`) assembles a bounded, redacted brief from
+  repository facts, file layout, dependencies, code intelligence, existing README
+  commands, and selected source excerpts. Every prompt now receives this evidence
+  and is instructed to state only what the evidence supports.
+- Prompt templates for the three document types that previously fell back to a
+  generic prompt: `CHANGELOG`, `DEVELOPMENT_GUIDE`, and `QUICKSTART`. All eight
+  document types now ship a template and consume the `{{ evidence }}` block.
+- Silent credential redaction and `.env` exclusion in source excerpts.
+- Template placeholders (for example `<YOUR_GIT_URL>`) are stripped from the
+  existing-README evidence before it reaches the model.
+- Gemini support now uses the supported `google-genai` SDK instead of the
+  end-of-life `google-generativeai` package.
+- `python -m docsmith` is now a supported entry point.
+- Environment-first configuration: `DOCSMITH_PROVIDER`, `DOCSMITH_<PROVIDER>_API_KEY`,
+  `DOCSMITH_MODEL`, and `DOCSMITH_GITHUB_TOKEN` work without a config file.
+  Conventional names such as `GEMINI_API_KEY`, `OPENAI_API_KEY`, and
+  `GITHUB_TOKEN` are also accepted. Environment keys are never written to disk.
+- Non-interactive mode: commands fail fast with actionable instructions when no
+  terminal is available, and `--quick` lets CI run end-to-end without prompts.
+- Friendly CLI error handling through the `docsmith.main:cli` wrapper, with
+  `DOCSMITH_DEBUG=1` available for full tracebacks.
+
+### Changed
+- Reviewer now validates generated shell commands against the detected dependency
+  set, validates documented endpoints, and flags placeholder values. Unsupported
+  commands and placeholders are reported as refinable issues. `needs_refinement()`
+  decides the refinement pass, so warnings are no longer ignored when only
+  critical issues used to trigger a rewrite.
+- Refiner receives the same evidence as the writer, refuses to introduce new
+  claims, keeps the original document when the model returns nothing, and
+  re-applies the emoji preference after rewriting.
+- AI retries now use exponential backoff and only retry transient failures
+  (429/5xx/timeouts). Missing SDKs, bad API keys, and permission errors fail
+  immediately instead of being retried three times.
+- GitHub API layer retries transient failures (timeouts, connection errors, 429,
+  5xx) with exponential backoff, reports rate limits versus permission errors
+  separately, honours `Retry-After`, and warns about truncated trees.
+- GitHub file selection ranks the shallowest copy of each manifest first and
+  deprioritises `examples/`, `docs/`, `tests/`, and vendor directories, so real
+  project code is no longer crowded out by sample apps. Real `.env` files are
+  never fetched; only `.env.example`/`.env.sample`/`.env.template`.
+- Evidence budgeting now truncates the tail of the source-excerpt section instead
+  of dropping it, so real code survives budget pressure.
+- pyproject dependency parsing now understands PEP 621, Poetry, and dependency
+  groups, and duplicate declarations are collapsed.
+- Config and cache writes are atomic and owner-only (`0600`).
+- `docsmith config` now merges into the existing configuration instead of
+  replacing it, preserving other provider keys, tokens, and preferences.
+- `--quick` uses the configured audience and tone, and the output directory
+  follows `output_dir` unless `--output` is passed.
+- README rewritten around the evidence pipeline, with an install matrix
+  (pip/uvx/pipx), document-type and CLI tables, a live generated excerpt, an
+  FAQ, and custom SVG banner/pipeline visuals.
+- `SECURITY.md` now points to GitHub private vulnerability reporting instead of
+  an unreachable email address.
+
+### Fixed
+- Old cache files that contained `.env` contents are scrubbed when loaded.
+- Repository descriptions containing bracket characters no longer crash the
+  analysis table.
+- The corrupted-config message now prints the actual config path instead of the
+  literal `{CONFIG_FILE}`.
+- `pyproject.toml` project URLs now point to the real repository, the publish job
+  keeps `contents: read`, and the deprecated `typer[all]` extra was removed.
+- `ruff format --check` now passes across the repository.
+
+### Refactored
+- Extracted magic numbers into constants in `scorer.py` and `reviewer.py`
+- Simplified framework detection with data-driven lookup
+- Reused Markdown responses clean up utility between writer and refiner
+- Removed redundant continue/empty instructions and comments across modules
+
+## [0.1.0] - 2026-06-04
+
+### Added
+
+- **Core CLI** with `generate`, `analyze`, `config`, `cache`, and `version` commands
+- **GitHub integration** with intelligent file selection and rate limit handling
+- **Repository analysis engine**:
+  - Dependency detection (Python, JavaScript, Rust, Go)
+  - Framework detection (FastAPI, Flask, Django, Express, Typer, Click, and more)
+  - API route detection (FastAPI, Flask, Django, Express)
+  - CLI command detection (Typer, Click)
+  - Code intelligence extraction (classes, functions, env variables)
+- **Multi-provider AI support**:
+  - Google Gemini (default)
+  - OpenAI (GPT-4o)
+  - Anthropic (Claude)
+  - Mistral AI
+- **Documentation generation pipeline**:
+  - Intelligent planner with context-aware section planning
+  - Jinja2 prompt templates for consistent output
+  - Quality reviewer (catches hallucinations, missing sections, placeholders)
+  - Multi-dimensional scorer (completeness, correctness, examples, usability, maintainability)
+  - Auto-refiner for fixing review issues
+- **9 document types**: README, CONTRIBUTING, SECURITY, ARCHITECTURE, API_REFERENCE, CHANGELOG, DEVELOPMENT_GUIDE, QUICKSTART, LICENSE
+- **Interactive questionnaire** for customizing generation options
+- **First-run setup wizard** for provider configuration
+- **Repository analysis caching** with configurable TTL
+- **Rich terminal UI** with progress bars, tables, and Markdown preview
+- **Preview mode** for terminal output without file writing
+- **65 unit tests** covering models, analysis, generation, and configuration
+- **CI pipeline** with GitHub Actions (Python 3.10–3.13 matrix)

docsmith_ai-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# Contributing to DocSmith
+
+Thank you for considering contributing to DocSmith! 
+
+## Getting Started
+
+1. **Fork** the repository
+2. **Clone** your fork:
+   ```bash
+   git clone https://github.com/<your-username>/DocSmith.git
+   cd DocSmith
+   ```
+3. **Set up** the development environment:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+   pip install -e ".[dev,all-providers]"
+   ```
+
+## Development Workflow
+
+### Branch naming
+
+- `feat/description` — new features
+- `fix/description` — bug fixes
+- `docs/description` — documentation changes
+- `refactor/description` — code refactoring
+
+### Making changes
+
+1. Create a branch: `git checkout -b feat/my-feature`
+2. Make your changes
+3. Run tests: `pytest -v`
+4. Run lints: `ruff check . && ruff format --check .`
+5. Commit: `git commit -m "feat: add my feature"`
+6. Push: `git push origin feat/my-feature`
+7. Open a Pull Request
+
+## Testing
+
+```bash
+# Run all tests
+pytest -v
+
+# Run with coverage
+pytest --cov=docsmith --cov-report=term-missing
+
+# Run a specific test file
+pytest tests/test_analyzer.py -v
+```
+
+## Code Style
+
+We use **ruff** for both linting and formatting:
+
+```bash
+# Check for issues
+ruff check .
+
+# Auto-fix issues
+ruff check . --fix
+
+# Format code
+ruff format .
+```
+
+### Style rules
+
+- Python 3.10+ with type hints on all function signatures
+- Pydantic v2 for all data models
+- Google-style docstrings on all public classes and functions
+- No wildcard imports
+- No mutable default arguments
+
+## Project Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| `docsmith/ai/` | AI provider abstraction + prompts |
+| `docsmith/analysis/` | Code intelligence extraction |
+| `docsmith/config/` | Settings and persistent storage |
+| `docsmith/generation/` | Evidence builder, planning, writing, review, scoring |
+| `docsmith/github/` | GitHub API integration |
+| `docsmith/models/` | Pydantic data models |
+| `docsmith/output/` | File output and terminal preview |
+| `tests/` | Test suite |
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` — new feature
+- `fix:` — bug fix
+- `docs:` — documentation
+- `test:` — tests
+- `refactor:` — code refactoring
+- `chore:` — maintenance
+
+## Reporting Bugs
+
+Open an issue with:
+- DocSmith version (`docsmith version`)
+- Python version
+- Steps to reproduce
+- Expected vs actual behavior
+
+## Feature Requests
+
+Open an issue with the `enhancement` label describing:
+- The problem you're trying to solve
+- Your proposed solution
+- Alternative approaches you've considered
+
+---
+
+Thank you for helping make DocSmith better! 

docsmith_ai-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DocSmith Contributors
+
+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.