Metadata-Version: 2.4
Name: confluence-knowledge
Version: 0.4.1
Summary: Local, GET-only Confluence subtree indexer + grounded-Q&A MCP service
License: MIT
Project-URL: Repository, https://github.com/nkunal1992/agents
Project-URL: Documentation, https://github.com/nkunal1992/agents/blob/main/docs/confluence-knowledge.md
Project-URL: Issues, https://github.com/nkunal1992/agents/issues
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: numpy>=1.26
Requires-Dist: keyring>=25.2
Requires-Dist: mcp<2,>=1.6
Requires-Dist: pip-system-certs>=5.0
Provides-Extra: models
Requires-Dist: sentence-transformers<4.0,>=3.0; extra == "models"
Requires-Dist: huggingface-hub>=0.26; extra == "models"
Provides-Extra: files
Requires-Dist: python-docx>=1.1; extra == "files"
Requires-Dist: pypdf>=4.0; extra == "files"
Requires-Dist: python-pptx>=1.0; extra == "files"
Requires-Dist: openpyxl>=3.1; extra == "files"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

# confluence-knowledge (local MCP service)

Local companion service for the `confluence-knowledge` Copilot agent.
See `../../docs/confluence-knowledge.md` for the full guide.

- GET-only `ConfluenceClient` — non-GET raises `SecurityException` pre-flight.
- Recursive subtree crawl (Cloud v2 + Data Center), resumable.
- Local embeddings (`all-MiniLM-L6-v2`) + local reranker
  (`ms-marco-MiniLM-L6-v2`) — Apache-2.0, pinned in `models.lock.json`,
  never a cloud embedding call.
- SQLite + FTS5 + vector-blob index under `.conf_knowledge_index/`.
- Credentials via OS keyring / env var / chmod-600 `.conf_auth.json`.

## Dev

```bash
python3.11+ -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest        # all offline — no network needed
.venv/bin/python -m ruff check src tests
```

Before every release, run the end-to-end smoke test. It spawns the real stdio
server through the MCP client SDK and uses the real models against a fake
Confluence on localhost, with simulated network latency:

```bash
.venv/bin/pip install -e '.[models]'
CONF_KNOWLEDGE_HOME=/tmp/ck/home .venv/bin/confluence-knowledge prepare-models
CONF_KNOWLEDGE_HOME=/tmp/ck/home .venv/bin/python scripts/e2e_smoke.py   # ends with "E2E OK"
```

`e2e_bootstrap.py` goes further — it replays the agent's entire install flow
in a sandboxed $HOME (python discovery → venv → `pip install` from the
shipped `dist/` bundle → models → credentials → `register` → the real server
over stdio → a full Q&A round-trip). Run it before every release:

```bash
CK_MODEL_CACHE=/tmp/ck/home/models .venv/bin/python scripts/e2e_bootstrap.py  # "E2E BOOTSTRAP OK"
```

## CLI

| Command | Purpose |
|---|---|
| `confluence-knowledge setup` | guided env/site/token setup (hidden input, keyring) |
| `confluence-knowledge prepare-models` | fetch pinned local models once |
| `confluence-knowledge doctor` | verify config + heartbeat + models |
| `confluence-knowledge serve` | run the stdio MCP server (what the IDE launches) |
| `confluence-knowledge clean` | delete the local index (`~/.confluence-knowledge/work` unless `CONF_KNOWLEDGE_WORKDIR` is set) |
