docforge-cli 0.2.1__tar.gz → 0.4.0__tar.gz

{docforge_cli-0.2.1/src/docforge_cli.egg-info → docforge_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docforge-cli
-Version: 0.2.1
+Version: 0.4.0
 Summary: Forge searchable context from Confluence and git repos for AI coding assistants
 License: MIT
 Project-URL: Homepage, https://GranatenUdo.github.io/docforge/
@@ -11,29 +11,32 @@ Project-URL: Documentation, https://GranatenUdo.github.io/docforge/
 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
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: asyncpg<1.0,>=0.30
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.9
+Requires-Dist: pydantic-settings<3.0,>=2.6
+Requires-Dist: beautifulsoup4<5.0,>=4.12
+Requires-Dist: sentence-transformers<6.0,>=5.0
+Requires-Dist: pgvector<1.0,>=0.3
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: fastmcp<4.0,>=3.0
+Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: uvicorn<1.0,>=0.34
+Requires-Dist: numpy<3.0,>=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"
+Requires-Dist: pytest<10.0,>=9.0; extra == "dev"
+Requires-Dist: pytest-asyncio<2.0,>=1.0; extra == "dev"
+Requires-Dist: pytest-cov<8.0,>=7.0; extra == "dev"
+Requires-Dist: ruff<1.0,>=0.8; extra == "dev"
+Requires-Dist: testcontainers[postgres]<5.0,>=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"
+Requires-Dist: fastapi-azure-auth<6.0,>=5.0; extra == "entra"
+Requires-Dist: azure-identity<2.0,>=1.19; extra == "entra"
+Requires-Dist: aiohttp<4.0,>=3.10; extra == "entra"
+Provides-Extra: azure
+Requires-Dist: azure-identity<2.0,>=1.19; extra == "azure"
+Requires-Dist: aiohttp<4.0,>=3.10; extra == "azure"
 Dynamic: license-file
 
 # docforge
@@ -83,15 +86,22 @@ docforge is the narrow, focused option in this landscape: minimal footprint, MCP
 - 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.
 
+For the full trust model, accepted risks, and assumptions docforge makes about its operating environment, see [`docs/threat-model.md`](docs/threat-model.md).
+
 ## Quick Start
 
+**Prerequisites:**
+- Python 3.12+
+- Docker (for the local Postgres + pgvector container)
+- A [Hugging Face token](https://huggingface.co/settings/tokens) with access to the gated [EmbeddingGemma-300M](https://huggingface.co/google/embeddinggemma-300m) model. Accept the model license on the model page first.
+
 ```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
+# Edit .env with your credentials (CONFLUENCE_API_TOKEN, HF_TOKEN, DATABASE_URL)
 docker compose up -d db
 docforge init-db
 docforge ingest
@@ -126,15 +136,102 @@ When an AI assistant needs cross-team context, it calls docforge's `search_docum
 
 ## Deploy to your infrastructure
 
-For team-wide use, deploy the search API to Azure (~$35/month at default SKUs):
+For team-wide use, deploy the search API to Azure (~$90/month at default SKUs with embedder always-on for production; ~$55/month with the default scale-to-zero embedder):
 
 - PostgreSQL Flexible Server (Burstable B1ms, 32 GB) with pgvector.
 - Container App running the FastAPI search API.
-- Container Registry, Key Vault, Log Analytics, managed environment.
+- Container App running the embedder service (EmbeddingGemma-300M, model baked into the image).
+- Container Registry (Standard), 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.
 
+## Use a hosted instance (no local DB required)
+
+If your team already operates a docforge deployment and you only want to *use* it from your editor (Claude Code, etc.), you don't need to clone, ingest, or run Postgres locally:
+
+```bash
+# Generic (no auth)
+pip install docforge-cli
+claude mcp add -s user -e DOCFORGE_API_URL=https://docforge.example.com \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL
+
+# Static Bearer token
+pip install docforge-cli
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_API_TOKEN=eyJ... \
+  -e DOCFORGE_AUTH=bearer \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth bearer
+
+# Entra (Azure AD)
+pip install docforge-cli[azure]
+az login --tenant <your-tenant-id>
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_AUDIENCE=api://<app-registration-uri> \
+  -e DOCFORGE_AUTH=azure \
+  -e DOCFORGE_TEAM=your-team \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth azure
+```
+
+With `--auth azure`, `user_name` is bound to your Entra JWT subject — you can't (and don't need to) configure it.
+
+`DOCFORGE_TEAM` is optional but recommended for team-tag relevance boosting in search results.
+
+## Self-hosting / forking
+
+The embedder image bakes the EmbeddingGemma-300M model at build time,
+which requires a HuggingFace access token. Forks and adopters need to:
+
+1. Get an HF token at https://huggingface.co/settings/tokens.
+2. Accept the EmbeddingGemma license at
+   https://huggingface.co/google/embeddinggemma-300m.
+3. Add a repo secret `HF_TOKEN` under
+   `Settings → Secrets and variables → Actions`.
+
+The CI workflow forwards the secret to BuildKit via
+`--mount=type=secret,id=hf_token`; the token never enters any image
+layer. If you fork this repo and run the CI workflow, it will build the
+embedder image automatically on commits to `master` and PRs (without
+pushing unless on `master`). To enable pushes to a registry, also add
+secrets `ACR_LOGIN_SERVER`, `ACR_USERNAME`, and `ACR_PASSWORD`.
+
+## Upgrading the embedding model
+
+The dimension-mismatch guard in `RemoteEmbedder` makes an
+embedder/search API mismatch loud (`HTTP 503` with a clear log line)
+rather than silent. Upgrade procedure:
+
+1. **Pick the new model.** Note its output dimensionality `D` (e.g.
+   `768` for EmbeddingGemma, `1024` for many newer models).
+
+2. **Update config.** Set `embedding_model: <new>` and
+   `embedding_dimensions: D` in the search API's deployment config
+   (Bicep parameters + Key Vault, or `docforge.yml` for self-hosters).
+
+3. **Build the embedder image** with the new model:
+   ```bash
+   docker build \
+     --build-arg EMBEDDING_MODEL=<new> \
+     --secret id=hf_token,env=HF_TOKEN \
+     -f Dockerfile.embedder \
+     -t docforge-embedder:<tag> .
+   ```
+
+4. **Apply schema migration.** Add a new vector column:
+   ```sql
+   ALTER TABLE chunks ADD COLUMN embedding_new vector(D);
+   ```
+   Re-ingest to populate the new column. Until backfill completes, the
+   search API serves from the old column.
+
+5. **Cut over.** Deploy the new embedder image first, then the new
+   search API. The dim-mismatch guard ensures search refuses to serve
+   wrong-dim vectors.
+
+6. **Drop the old column** after a confidence interval.
+
 ## Configuration
 
 See `docs/` for the full configuration reference, including `docforge.yml` and `sources.yml` schemas.
@@ -170,6 +267,16 @@ Check that the database is running: `docker compose up -d db`. Verify `DATABASE_
 
 MIT. See [LICENSE](LICENSE).
 
+## License compatibility
+
+docforge is MIT-licensed; the default embedding model,
+[EmbeddingGemma-300M](https://huggingface.co/google/embeddinggemma-300m), is
+distributed under the [Gemma Terms of Use](https://ai.google.dev/gemma/terms),
+which restrict harmful use and building products that compete with Gemma. Swap
+to a permissively-licensed alternative via `embedding_model` in `docforge.yml`
+if those constraints don't fit your use case (see
+[microsite FAQ — Can I use a different embedding model?](https://GranatenUdo.github.io/docforge/faq/#can-i-use-a-different-embedding-model)).
+
 ## Credits
 
 docforge stands on open shoulders:

docforge_cli-0.2.1/PKG-INFO → docforge_cli-0.4.0/README.md

@@ -1,41 +1,3 @@
-Metadata-Version: 2.4
-Name: docforge-cli
-Version: 0.2.1
-Summary: Forge searchable context from Confluence and git repos for AI coding assistants
-License: MIT
-Project-URL: Homepage, https://GranatenUdo.github.io/docforge/
-Project-URL: Source, https://github.com/GranatenUdo/docforge
-Project-URL: Issues, https://github.com/GranatenUdo/docforge/issues
-Project-URL: Changelog, https://github.com/GranatenUdo/docforge/blob/master/CHANGELOG.md
-Project-URL: Documentation, https://GranatenUdo.github.io/docforge/
-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.**
@@ -83,15 +45,22 @@ docforge is the narrow, focused option in this landscape: minimal footprint, MCP
 - 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.
 
+For the full trust model, accepted risks, and assumptions docforge makes about its operating environment, see [`docs/threat-model.md`](docs/threat-model.md).
+
 ## Quick Start
 
+**Prerequisites:**
+- Python 3.12+
+- Docker (for the local Postgres + pgvector container)
+- A [Hugging Face token](https://huggingface.co/settings/tokens) with access to the gated [EmbeddingGemma-300M](https://huggingface.co/google/embeddinggemma-300m) model. Accept the model license on the model page first.
+
 ```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
+# Edit .env with your credentials (CONFLUENCE_API_TOKEN, HF_TOKEN, DATABASE_URL)
 docker compose up -d db
 docforge init-db
 docforge ingest
@@ -126,15 +95,102 @@ When an AI assistant needs cross-team context, it calls docforge's `search_docum
 
 ## Deploy to your infrastructure
 
-For team-wide use, deploy the search API to Azure (~$35/month at default SKUs):
+For team-wide use, deploy the search API to Azure (~$90/month at default SKUs with embedder always-on for production; ~$55/month with the default scale-to-zero embedder):
 
 - PostgreSQL Flexible Server (Burstable B1ms, 32 GB) with pgvector.
 - Container App running the FastAPI search API.
-- Container Registry, Key Vault, Log Analytics, managed environment.
+- Container App running the embedder service (EmbeddingGemma-300M, model baked into the image).
+- Container Registry (Standard), 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.
 
+## Use a hosted instance (no local DB required)
+
+If your team already operates a docforge deployment and you only want to *use* it from your editor (Claude Code, etc.), you don't need to clone, ingest, or run Postgres locally:
+
+```bash
+# Generic (no auth)
+pip install docforge-cli
+claude mcp add -s user -e DOCFORGE_API_URL=https://docforge.example.com \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL
+
+# Static Bearer token
+pip install docforge-cli
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_API_TOKEN=eyJ... \
+  -e DOCFORGE_AUTH=bearer \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth bearer
+
+# Entra (Azure AD)
+pip install docforge-cli[azure]
+az login --tenant <your-tenant-id>
+claude mcp add -s user \
+  -e DOCFORGE_API_URL=https://docforge.example.com \
+  -e DOCFORGE_AUDIENCE=api://<app-registration-uri> \
+  -e DOCFORGE_AUTH=azure \
+  -e DOCFORGE_TEAM=your-team \
+  docforge -- docforge serve --remote-api $DOCFORGE_API_URL --auth azure
+```
+
+With `--auth azure`, `user_name` is bound to your Entra JWT subject — you can't (and don't need to) configure it.
+
+`DOCFORGE_TEAM` is optional but recommended for team-tag relevance boosting in search results.
+
+## Self-hosting / forking
+
+The embedder image bakes the EmbeddingGemma-300M model at build time,
+which requires a HuggingFace access token. Forks and adopters need to:
+
+1. Get an HF token at https://huggingface.co/settings/tokens.
+2. Accept the EmbeddingGemma license at
+   https://huggingface.co/google/embeddinggemma-300m.
+3. Add a repo secret `HF_TOKEN` under
+   `Settings → Secrets and variables → Actions`.
+
+The CI workflow forwards the secret to BuildKit via
+`--mount=type=secret,id=hf_token`; the token never enters any image
+layer. If you fork this repo and run the CI workflow, it will build the
+embedder image automatically on commits to `master` and PRs (without
+pushing unless on `master`). To enable pushes to a registry, also add
+secrets `ACR_LOGIN_SERVER`, `ACR_USERNAME`, and `ACR_PASSWORD`.
+
+## Upgrading the embedding model
+
+The dimension-mismatch guard in `RemoteEmbedder` makes an
+embedder/search API mismatch loud (`HTTP 503` with a clear log line)
+rather than silent. Upgrade procedure:
+
+1. **Pick the new model.** Note its output dimensionality `D` (e.g.
+   `768` for EmbeddingGemma, `1024` for many newer models).
+
+2. **Update config.** Set `embedding_model: <new>` and
+   `embedding_dimensions: D` in the search API's deployment config
+   (Bicep parameters + Key Vault, or `docforge.yml` for self-hosters).
+
+3. **Build the embedder image** with the new model:
+   ```bash
+   docker build \
+     --build-arg EMBEDDING_MODEL=<new> \
+     --secret id=hf_token,env=HF_TOKEN \
+     -f Dockerfile.embedder \
+     -t docforge-embedder:<tag> .
+   ```
+
+4. **Apply schema migration.** Add a new vector column:
+   ```sql
+   ALTER TABLE chunks ADD COLUMN embedding_new vector(D);
+   ```
+   Re-ingest to populate the new column. Until backfill completes, the
+   search API serves from the old column.
+
+5. **Cut over.** Deploy the new embedder image first, then the new
+   search API. The dim-mismatch guard ensures search refuses to serve
+   wrong-dim vectors.
+
+6. **Drop the old column** after a confidence interval.
+
 ## Configuration
 
 See `docs/` for the full configuration reference, including `docforge.yml` and `sources.yml` schemas.
@@ -170,6 +226,16 @@ Check that the database is running: `docker compose up -d db`. Verify `DATABASE_
 
 MIT. See [LICENSE](LICENSE).
 
+## License compatibility
+
+docforge is MIT-licensed; the default embedding model,
+[EmbeddingGemma-300M](https://huggingface.co/google/embeddinggemma-300m), is
+distributed under the [Gemma Terms of Use](https://ai.google.dev/gemma/terms),
+which restrict harmful use and building products that compete with Gemma. Swap
+to a permissively-licensed alternative via `embedding_model` in `docforge.yml`
+if those constraints don't fit your use case (see
+[microsite FAQ — Can I use a different embedding model?](https://GranatenUdo.github.io/docforge/faq/#can-i-use-a-different-embedding-model)).
+
 ## Credits
 
 docforge stands on open shoulders:

{docforge_cli-0.2.1 → docforge_cli-0.4.0}/pyproject.toml

@@ -4,25 +4,25 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "docforge-cli"
-version = "0.2.1"
+version = "0.4.0"
 description = "Forge searchable context from Confluence and git repos for AI coding assistants"
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.12"
 dependencies = [
-    "typer>=0.12",
-    "asyncpg>=0.30",
-    "httpx>=0.27",
-    "pydantic>=2.9",
-    "pydantic-settings>=2.6",
-    "beautifulsoup4>=4.12",
-    "sentence-transformers>=5.0",
-    "pgvector>=0.3",
-    "pyyaml>=6.0",
-    "fastmcp>=2.0",
-    "fastapi>=0.115",
-    "uvicorn>=0.34",
-    "numpy>=1.26",
+    "typer>=0.12,<1.0",
+    "asyncpg>=0.30,<1.0",
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.9,<3.0",
+    "pydantic-settings>=2.6,<3.0",
+    "beautifulsoup4>=4.12,<5.0",
+    "sentence-transformers>=5.0,<6.0",
+    "pgvector>=0.3,<1.0",
+    "pyyaml>=6.0,<7.0",
+    "fastmcp>=3.0,<4.0",
+    "fastapi>=0.115,<1.0",
+    "uvicorn>=0.34,<1.0",
+    "numpy>=1.26,<3.0",   # both 1.x and 2.x tested
 ]
 
 [project.urls]
@@ -37,17 +37,21 @@ docforge = "docforge.cli:app"
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=8.0",
-    "pytest-asyncio>=0.24",
-    "pytest-cov>=7.0",
-    "ruff>=0.8",
-    "testcontainers[postgres]>=4.0",
+    "pytest>=9.0,<10.0",
+    "pytest-asyncio>=1.0,<2.0",
+    "pytest-cov>=7.0,<8.0",
+    "ruff>=0.8,<1.0",
+    "testcontainers[postgres]>=4.0,<5.0",
 ]
 entra = [
-    "fastapi-azure-auth>=5.0",
-    "azure-identity>=1.19",
+    "fastapi-azure-auth>=5.0,<6.0",
+    "azure-identity>=1.19,<2.0",
     # aiohttp is required by azure-identity.aio's async pipeline
-    "aiohttp>=3.10",
+    "aiohttp>=3.10,<4.0",
+]
+azure = [
+    "azure-identity>=1.19,<2.0",
+    "aiohttp>=3.10,<4.0",  # required by azure-identity.aio
 ]
 
 [tool.setuptools.packages.find]
@@ -68,7 +72,7 @@ select = ["E", "F", "I", "W"]
 asyncio_mode = "auto"
 testpaths = ["tests"]
 markers = [
-    "integration: requires Docker (pgvector container)",
+    "integration: tests requiring real external resources (Docker for Postgres, network for embedding model)",
 ]
 addopts = "--cov=src/docforge"