e9b37e86df35c08d024ccc40f9bbd5b204c9328d
3 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 justin
|
e9b37e86df |
feat: implement Phases 9 / 11 / 12 / 13 — diff/lessons/inconsistencies/digest
Eight new MCP tools on top of the Phase 3 baseline. Each one uses
TimedCall so calls show up in usage.jsonl alongside search/get/list.
Phase 9 — multi-version diff:
* list_cluster(bundle_id, page_id) — cross-version peers from the
synthesized topic_cluster (same GUID across 8.1.x versions).
* diff_versions(bundle_id, page_id, against_bundle_id) — unified
diff between two bundles; uses topic_cluster first, falls back to
same page_id (which works because HVM GUIDs are stable cross-version).
* bundle_changelog(new, old) — page-level adds/removes/churn summary,
sorted by lines moved; uses _diff_churn helper.
Phase 11 — curated knowledge:
* hvm_api_lessons(topic?) — surfaces docs_mcp/api_lessons.md (manager
sizing, upgrade ordering, plugin/worker version compat, backups
setup, console keyboard, elevation, ops gotchas). topic= filters to
matching H2 sections. Marked "call proactively for HVM scripting /
integration / upgrade questions" in the docstring so the LLM uses it.
Phase 12 — doc-bug workflow:
* find_doc_inconsistencies(scope_query, ...) — read-only scan with two
checks: cross_version_drift (line-diff vs cluster peers, in-band
10-60% of file = high confidence) and redirect_chain (short body
that's mostly a "see [other page]" pointer).
* submit_doc_bug(page_url, content, ...) — env-gated OFF
(DOC_BUG_SUBMIT_ENABLED) AND requires DOC_BUG_API_URL. Refuses
cleanly with a manual-fallback message when either is unset.
Allowlist: support.hpe.com only. Mandatory operator-confirmation
pattern in the docstring; loud "do not loop" warning. The actual
HPE feedback endpoint hasn't been sniffed yet — when it is, set
both env vars and verify the payload shape against the schema.
Phase 13 — weekly digest:
* _digest_history() reads corpus/.digest/history.jsonl (built by
scrape.changelog --history-out in the CI refresh workflow).
* weekly_digest(days, version?, platform?, ...) aggregates corpus-
touching commits in the window. Post-filter totals so version /
platform filters give honest "X page changes" numbers, not the
pre-filter commit count.
* corpus_status() reports image build time, latest upstream Published
date, total bundles/pages/chunks, and the 5 most-recently-edited
bundles.
Tool count now: 11 registered (search_docs, get_page, list_versions,
list_cluster, diff_versions, bundle_changelog, weekly_digest,
corpus_status, hvm_api_lessons, find_doc_inconsistencies, submit_doc_bug).
Verified end-to-end via MCP stdio tools/list.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
justin
|
dda044eb95 |
search: BM25-default + cross-encoder rerank, hybrid behind env gate
Phase 3/6/7/8 in one pass since they depend on each other.
* docs_mcp/server.py
- Wire search_docs / get_page / list_versions tool bodies.
- search_docs flow: BM25 first (rag.bm25 FTS5) → over-fetch RERANK_POOL
chunks → POST to RERANK_URL/v1/rerank → return top-k. Dense is the
fallback when BM25 finds nothing. HYBRID_SEARCH=true switches to
dense+BM25+RRF (fused via the new _rrf_fuse helper).
- All retrieval failures are caught and fall back to the next layer,
so a dead reranker or missing BM25 db never blocks a search.
- Source URLs built from the bundle's docId so results link straight
into support.hpe.com.
* eval/
- 22 hand-curated golden queries grounded in real corpus page titles.
- DenseRetriever / BM25Retriever / HybridRetriever / RerankedRetriever
+ MRR/Recall@K/nDCG@K harness. RERANK_URL env activates the
reranked variants.
- Committed eval/results/baseline.md. On this corpus:
dense: MRR 0.539
bm25: MRR 0.880
hybrid_rrf: MRR 0.692
bm25+rerank: MRR 0.920 (winner)
hybrid_rrf+rerank: MRR 0.875
HPE structured docs use controlled vocabulary, so lexical match
dominates. Hybrid loses because dense pollutes the fused pool.
* scripts/rerank_server.py
- Minimal HTTP /v1/rerank over sentence-transformers
cross-encoder/ms-marco-MiniLM-L-6-v2. Cohere-style request/response.
- This is the dev/CPU fallback; production replaces it with the
llama.cpp + jina-reranker-v2-base GGUF sidecar (same wire protocol).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
justin
|
9ba615c8ee |
initial: docs-mcp-template — build guide + scaffolded server
Template for building hosted MCP servers over a product's public
documentation. Distilled from one production build; everything
product-specific has been factored out.
Contents:
- PLAN.md — comprehensive build guide. 13 phases from project
skeleton through weekly_digest. Includes the gotchas
("fetch-depth: 0 always", reranker per-pair token limit,
Cloudflare body cap, dash-not-bash on Gitea runners), the
decisions worth carrying forward, and a per-product
customization checklist.
- CLAUDE.md — guidance for Claude Code working in a clone of this
template. Phase identification table, conventions (env-gating +
operator confirmation for side-effecting tools, defensive
fallback for retrieval components), common commands.
- README.md — quick-start summary.
Scaffolded code (all signature-stable, with NotImplementedError
stubs where phase-specific work is required):
docs_mcp/server.py FastMCP server, stateless_http=True, with
search_docs / get_page / list_versions
baseline tools and commented stubs for the
rest of the phase set.
docs_mcp/usage.py TimedCall telemetry, JSONL, daily rotation,
90-day retention. Reusable as-is.
rag/embeddings.py Ollama embedder (nomic-embed-text default),
load-balanced across N URLs. Reusable.
rag/chunk.py Paragraph-aware chunker with synthetic
chunk 0. Per-product tunable.
rag/index.py Chroma + BM25 builder. --rebuild and
--bm25-only flags.
rag/bm25.py SQLite FTS5 lexical index. Reusable.
scrape/changelog.py --cached / --ref / --json / --history-out.
Reusable.
scrape/README.md What you write per-product.
eval/queries.jsonl.example
Curate ~25 hand-labeled queries here.
eval/retrievers.py Retriever protocol + stub classes.
eval/run_eval.py MRR / Recall@K / nDCG@K harness skeleton.
scripts/usage_report.py
Standalone log analyzer; the
FOLLOW-UP CHECKS pattern noted in the
module docstring.
scripts/registry_gc.py
Gitea container registry cleanup. Reusable.
Deployment + CI:
Dockerfile Python 3.12-slim; COPY corpus + chroma
+ bm25 last for cache efficiency.
deploy/docker-compose.yml MCP + reranker sidecar + Watchtower.
Templated with <placeholders>.
.gitea/workflows/refresh.yml Weekly cron + manual dispatch.
fetch-depth: 0, retry-on-race,
three-tag image scheme.
.gitea/workflows/image-only.yml Code-only ship cycle, ~18min.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|