docforge-cli 0.2.0__py3-none-any.whl

docforge_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: docforge-cli
+Version: 0.2.0
+Summary: Forge searchable context from Confluence and git repos for AI coding assistants
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: asyncpg>=0.30
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: sentence-transformers>=5.0
+Requires-Dist: pgvector>=0.3
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.34
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: testcontainers[postgres]>=4.0; extra == "dev"
+Provides-Extra: entra
+Requires-Dist: fastapi-azure-auth>=5.0; extra == "entra"
+Requires-Dist: azure-identity>=1.19; extra == "entra"
+Requires-Dist: aiohttp>=3.10; extra == "entra"
+Dynamic: license-file
+
+# docforge
+
+**The self-hosted context engine for AI coding assistants.**
+
+Point docforge at your Confluence spaces and local git repositories. It indexes, embeds, and serves them over MCP — so Claude Code, Cursor, Copilot, and any assistant that speaks MCP can search your team's knowledge without your data leaving your infrastructure.
+
+docforge doesn't replace your AI assistant. It feeds it — turning Claude Code, Cursor, Copilot, and anything else that speaks MCP into tools that actually know your team's docs and code.
+
+[![CI](https://github.com/GranatenUdo/docforge/actions/workflows/ci.yml/badge.svg)](https://github.com/GranatenUdo/docforge/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/docforge-cli.svg)](https://pypi.org/project/docforge-cli/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+## Why docforge
+
+| Tool | Self-hosted | Integration | Confluence + code | Footprint | Complements AI assistants? |
+|---|---|---|---|---|---|
+| **docforge** | ✓ | MCP server | ✓ (Confluence + local git) | Minimal (PG + 1 container) | ✓ (any MCP client) |
+| [Atlassian Rovo MCP](https://www.atlassian.com/blog/announcements/atlassian-rovo-mcp-ga) | ✗ (Cloud-only) | MCP server | Confluence only (Cloud) | SaaS | ✓ |
+| [zilliztech/claude-context](https://github.com/zilliztech/claude-context) | ✓ | MCP server | Code only | Minimal | ✓ |
+| [Onyx](https://github.com/onyx-dot-app/onyx) | ✓ | MCP + chat UI | ✓ (50+ connectors) | Heavy (Standard) / Minimal (Lite) | ✓ (+ its own UI) |
+| Cursor codebase index + @Docs | ✗ | Proprietary | Code + public web docs | SaaS | — (built into Cursor only) |
+| [Copilot Spaces](https://github.com/orgs/community/discussions/180894) | ✗ | Proprietary (MCP for actions) | Code + attachments | SaaS | — (built into Copilot only) |
+| [Sourcegraph Cody](https://sourcegraph.com/docs/cody/enterprise/features) | ✓ (Enterprise) | OpenCtx / MCP | ✓ (via OpenCtx) | Heavy (Sourcegraph platform) | — (built into Cody only) |
+| LangChain / LlamaIndex DIY | ✓ | Whatever you build | You wire it | Depends | Depends |
+
+docforge is the narrow, focused option in this landscape: minimal footprint, MCP-native so it works with every assistant, and combines Confluence + code out of the box. It doesn't compete on connector count (Onyx wins there), visual UX (Cursor and Cody win), or SaaS convenience (Rovo). It competes on being **small, legible, vendor-neutral, and self-hosted** — four properties no commercial option offers together.
+
+### ✅ When docforge fits
+
+- You run Confluence Data Center/Server, or you want to self-host.
+- Your team uses MCP-capable assistants (Claude Code, Cursor with MCP, Copilot with MCP, etc.).
+- You want Confluence + git repos indexed together with one tool.
+- Operational simplicity matters — one Postgres, one container, MIT-licensed code you can audit in an afternoon.
+
+### ❌ When docforge is the wrong choice
+
+- You need 50+ connectors (Slack, Jira, Gmail, Drive, Notion) → use **[Onyx](https://github.com/onyx-dot-app/onyx)** or **[Glean](https://www.glean.com/)**.
+- You need per-document ACLs enforced at query time → not yet supported; use **Onyx**.
+- You need a chat UI for non-developers → docforge has no UI; use **Onyx**, **Glean**, or **Cody**.
+- You're on Atlassian Cloud and happy with SaaS → **[Atlassian Rovo MCP](https://www.atlassian.com/blog/announcements/atlassian-rovo-mcp-ga)** is free and official.
+- You need SSO / SCIM / RBAC → out of scope; docforge authenticates but doesn't authorize per-resource.
+- Your corpus is very large (>100K pages/chunks) → dense-only retrieval without hybrid starts to degrade; on the [roadmap](ROADMAP.md).
+- You need near-real-time updates → ingest is batch; no webhook-driven continuous sync yet.
+- You need multilingual search evaluated → EmbeddingGemma is multilingual, but docforge has no eval coverage on non-English corpora yet.
+
+## Quick Start
+
+```bash
+pip install docforge-cli
+docforge init my-project
+cd my-project
+# Edit docforge.yml with your Confluence URL
+# Edit sources.yml with your page IDs and local git repo paths
+# Edit .env with your credentials
+docker compose up -d db
+docforge init-db
+docforge ingest
+docforge serve
+```
+
+**Note:** The git crawler indexes **local filesystem paths** — docforge does not clone GitHub URLs. Clone first, then point docforge at the checkout path in `sources.yml`.
+
+## How It Works
+
+1. **Configure** your Confluence URL, page IDs, and local git repo paths in `sources.yml`.
+2. **Ingest** crawls pages and files, chunks text (~500 tokens), generates vector embeddings (768-dim).
+3. **Serve** exposes an MCP server that AI assistants query automatically.
+
+When an AI assistant needs cross-team context, it calls docforge's `search_documentation` MCP tool behind the scenes and gets relevant documentation chunks with source attribution.
+
+### Architecture
+
+![docforge architecture: Confluence and local git repos flow through docforge ingest into Postgres with pgvector, then docforge serve exposes an MCP server consumed by Claude Code, Cursor, and Copilot](docs/assets/architecture.svg)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `docforge init <name>` | Scaffold a new project with config templates |
+| `docforge init-db` | Initialize the PostgreSQL database schema |
+| `docforge ingest` | Crawl all sources, embed, store in PostgreSQL |
+| `docforge search "<query>"` | Test search from terminal |
+| `docforge serve` | Run MCP server for AI assistants |
+| `docforge serve --api` | Run FastAPI search API (for hosted deployment) |
+| `docforge status` | Show index stats and health |
+
+## Deploy to your infrastructure
+
+For team-wide use, deploy the search API to Azure (~$35/month at default SKUs):
+
+- PostgreSQL Flexible Server (Burstable B1ms, 32 GB) with pgvector.
+- Container App running the FastAPI search API.
+- Container Registry, Key Vault, Log Analytics, managed environment.
+- Team members use a lightweight MCP client that calls the hosted API.
+
+See [`deploy/azure/`](deploy/azure/) for Bicep templates and a full cost breakdown.
+
+## Configuration
+
+See `docs/` for the full configuration reference, including `docforge.yml` and `sources.yml` schemas.
+
+## Contributing
+
+Contributions welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, branch conventions, and PR expectations. Bug reports and feature requests go through [GitHub Issues](https://github.com/GranatenUdo/docforge/issues); open-ended questions and ideas live in [Discussions](https://github.com/GranatenUdo/docforge/discussions).
+
+## Evaluation & retrieval quality
+
+docforge ships with a retrieval-quality eval harness at [`docforge/scripts/eval_search.py`](docforge/scripts/eval_search.py). It measures recall@1, recall@k, and MRR against a ground-truth query set you maintain. The harness is designed for **drift detection** — run it after `sources.yml` changes, embedding-model updates, or ranking tweaks, and compare against your baseline. There is no absolute quality threshold; the metric magnitude depends on how closely your ground-truth queries match source titles. See [`docforge/scripts/README.md`](docforge/scripts/README.md) for details.
+
+## FAQ
+
+### "Cannot connect to PostgreSQL"
+
+Check that the database is running: `docker compose up -d db`. Verify `DATABASE_URL` in `.env` points to `postgresql://docforge:localdev@localhost:5432/docforge` (or your custom value).
+
+### "HF_TOKEN required" or model download fails
+
+The embedding model `google/embeddinggemma-300m` requires a Hugging Face token with access to the gated model. Create one at https://huggingface.co/settings/tokens, accept the model license at https://huggingface.co/google/embeddinggemma-300m, and set `HF_TOKEN=hf_...` in `.env`.
+
+### "No results found" after ingest
+
+Run `docforge status` to confirm sources and chunks exist. If counts are zero, check the ingest logs for per-source failures — the summary at the end lists sources that failed.
+
+### First ingest / first container start is very slow
+
+The first run downloads the 300M embedding model (~1.2 GB) from Hugging Face. Locally, the model is cached at `~/.cache/huggingface/`. In the Docker image, it is cached at `/app/.cache/huggingface/` — **mount this as a volume** so container restarts do not re-download: `docker run -v docforge-hf-cache:/app/.cache/huggingface ...`.
+
+### "Ingest skipped everything"
+
+docforge skips sources whose `content_hash` matches the stored hash (no changes detected). To force re-ingest, clear the hash: `UPDATE sources SET content_hash = NULL;` then run `docforge ingest`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Credits
+
+docforge stands on open shoulders:
+
+- [EmbeddingGemma-300M](https://huggingface.co/google/embeddinggemma-300m) — open-weights embedding model under the Gemma license.
+- [pgvector](https://github.com/pgvector/pgvector) — vector similarity for Postgres.
+- [FastMCP](https://github.com/PrefectHQ/fastmcp) — MCP server framework.
+- [FastAPI](https://fastapi.tiangolo.com/), [Typer](https://typer.tiangolo.com/), [asyncpg](https://magicstack.github.io/asyncpg/), [sentence-transformers](https://www.sbert.net/) — core infrastructure.

docforge_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+docforge/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docforge/__main__.py,sha256=cZeNOY01TCuT_v3-Rmgb2ehdG3nP_2BvCSOyR6F2HMI,115
+docforge/api.py,sha256=RCAo0otKR-id29TZgo4wmHV1_silj7EMyU5f91qC6Jc,8780
+docforge/cli.py,sha256=fN32vrmSBrF7F3HfMGRLiL4Xo0npo1wrQEUUCTaXT1Q,9480
+docforge/config.py,sha256=UNveJ1ksWj9dIPtOdiE5Z1XXP21TdGyx968ykrOTIyU,3372
+docforge/db.py,sha256=Q5wVCz6ltJgoINfUuIhwUeUmvuSmGYuw86fNIQEmECo,1643
+docforge/ingest.py,sha256=XlGrdx7JedXo2b2DuZYL9F3RVNf-EUbwhvTAnI_ABAo,15102
+docforge/lint.py,sha256=TU9OAYRdhqOH-_TiHfdZ43usIqK6Cr-SDnEv2BPfOxU,3030
+docforge/mcp_server.py,sha256=k0i-Q-Gho8QUA2HDo7aAiPgGyrQNeOn_-p7JigyPIxI,5884
+docforge/query_log.py,sha256=6mkEAhKS3Cge7EcfT31_Ye6TwdLDjWOmOjIHlTGXHqI,1294
+docforge/ranking.py,sha256=KDD7WW2RlOKKU9BfJfDWMS_bwRDufUF-7h8qpp3eYfg,685
+docforge/sources.py,sha256=hkXg5TXqTTKcKNuLRO1mRyDtbKZ9aAVUAjlfK9Xem_s,1097
+docforge/crawlers/__init__.py,sha256=xoelR0ZwJ2TSCpUGqpV6Teu1ayrtwjVm1vCfqgaHpV8,79
+docforge/crawlers/confluence.py,sha256=bMuqdHGz6A0EA-O69935d_fn2j0uvHzZfTAzdhCXOt8,3111
+docforge/crawlers/git.py,sha256=l7WKDu_T7-w1AaYOC8S9EpiZ-_jkP441IJK-NGdndFQ,2242
+docforge/processors/__init__.py,sha256=2iDniNCSBaXe0If4FHyb6cqq2twnLSD4XK0J_o1pKUE,70
+docforge/processors/chunker.py,sha256=et7zFUylVa4UYfE6ehj0RQjHTE5k98dGBAan8YqOupg,4190
+docforge/processors/embedder.py,sha256=7xvZEzd3Al96hwL8Ge0kjFF3GKxHy6EDJyllGHP16jI,2947
+docforge/processors/parser.py,sha256=O43gidPROgjsdrcSUby4hoDmMlVDf8lDXaQxDEq8EzA,4469
+docforge/scripts/__init__.py,sha256=DnOvKXALsxsGpGaDzHMvVAD3PuwIWBTTEgqoXNAQcR0,83
+docforge/scripts/eval_search.py,sha256=xcn8JG5LTx5lGzSE0Umt4xJoAyJIdAFvQa3eRia0rQs,8518
+docforge/scripts/latency_report.py,sha256=9imjMkl6nPIDknh8gWzaRjZlUzhy9fDxXyHheiWRIyk,5056
+docforge/sql/schema.sql,sha256=ljoWstTWxzc2wVZNGacMBu5px2Gva2j17pO9TxEF__U,913
+docforge/sql/migrations/001_add_source_identifier.sql,sha256=CmmleA8-gyOCSO1MsD8FjFuMgtAa5l5HdSjvgW6d0g4,208
+docforge/sql/migrations/002_add_status_index.sql,sha256=mxImhHBTZomMHqzeBbGnX96M-iD62bbzZkU1ukV9lN0,67
+docforge/sql/migrations/003_add_source_tags.sql,sha256=hhBYHHpXpoUKOyVmYmNJR3Zbn2PTT8IWKTRInbt1MwM,158
+docforge/sql/migrations/004_add_query_log.sql,sha256=9ssAvsddQhELUaPMxFI_qWEFYi2fnqLlSVtlF5q6Gfc,357
+docforge/sql/migrations/005_add_query_log_user_oid.sql,sha256=awceItGNTKcNYHtM9jyWNfBKOw6USiWMa5JUjlAtg-I,137
+docforge/sql/migrations/006_add_query_log_request_ms.sql,sha256=9Z0KZRH2pYA5hlubMkeZRI9-5f7_Kh9Z8cKZ3MqXxMU,63
+docforge/templates/docforge.yml,sha256=U8HgPM1maiizRjX2FA1fWDT547yQk6qEb9EHe-fGL8w,281
+docforge/templates/docker-compose.yml,sha256=vStUTu7CALeV8gJU1tZuLuGOmGVcf3Xk68wTxhPe_sI,263
+docforge/templates/mcp_client.py,sha256=hxycesqhYd40Vn6a5PICRjgFCHXBO0iupBzDByBRIf4,2452
+docforge/templates/sources.yml,sha256=sjowhY815K3fMG-f2iSqXsniHYwC8PmI7SIVCrGZOYs,579
+docforge_cli-0.2.0.dist-info/licenses/LICENSE,sha256=ptj0dMlIQCo0V543Y59JS-LS85XB0elflc8lzEkmBaY,1067
+docforge_cli-0.2.0.dist-info/METADATA,sha256=rWfpmn9hyO2QmPVW9yr2cmirPU_pN9uk8zwCMEHLEsY,10615
+docforge_cli-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+docforge_cli-0.2.0.dist-info/entry_points.txt,sha256=DEtuKPHBeq5uk_eq_faz2Y4pO9KApeP3UVWrcN72l4g,46
+docforge_cli-0.2.0.dist-info/top_level.txt,sha256=B9iWib2I605hT4bJa5LqDE6RmAdd9ldaW75ODDg9inY,9
+docforge_cli-0.2.0.dist-info/RECORD,,

docforge_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

docforge_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docforge = docforge.cli:app

docforge_cli-0.2.0.dist-info/licenses/LICENSE

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

docforge_cli-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+docforge