hvm-docs

justin/hvm-docs

Fork 0

Commit Graph

Author	SHA1	Message	Date
justin	41d431670f	remove submit_doc_bug tool	2026-05-24 07:44:39 -04:00
justin	fd376fab77	ci+deploy: target git.jpaul.io registry, PRODUCT_NAME=hvm Phase 4/5 — adapt the template workflows to Justin's self-hosted Gitea + act_runner setup (see reference_gitea_server memory): * PUSH via LAN endpoint 192.168.0.2:1234 (bypasses Cloudflare's 100 MB request-body cap on the Free plan); PULL via git.jpaul.io. * buildx with config-inline insecure-registry for the LAN endpoint — docker/login-action can't be used there (host daemon rejects HTTP). Auth is written into ~/.docker/config.json so buildx reads it directly. * docker/metadata-action labels org.opencontainers.image.source with the PUBLIC URL so Gitea auto-links the package; explicit POST to /api/v1/packages/.../-/link/{repo} as belt-and-suspenders (201 newly linked, 400 already linked, both treated as success). * deploy/docker-compose.yml: substitute <product> placeholders, point image at git.jpaul.io/justin/hvm-docs:latest, set HYBRID_SEARCH=false to match the eval winner (bm25+rerank), keep the llama.cpp + jina GGUF reranker sidecar as the production target. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-22 13:07:15 -04:00
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>	2026-05-22 09:18:17 -04:00

Author

SHA1

Message

Date

justin

41d431670f

remove submit_doc_bug tool

2026-05-24 07:44:39 -04:00

justin

fd376fab77

ci+deploy: target git.jpaul.io registry, PRODUCT_NAME=hvm

Phase 4/5 — adapt the template workflows to Justin's self-hosted Gitea
+ act_runner setup (see reference_gitea_server memory):

* PUSH via LAN endpoint 192.168.0.2:1234 (bypasses Cloudflare's 100 MB
  request-body cap on the Free plan); PULL via git.jpaul.io.
* buildx with config-inline insecure-registry for the LAN endpoint —
  docker/login-action can't be used there (host daemon rejects HTTP).
  Auth is written into ~/.docker/config.json so buildx reads it
  directly.
* docker/metadata-action labels org.opencontainers.image.source with
  the PUBLIC URL so Gitea auto-links the package; explicit POST to
  /api/v1/packages/.../-/link/{repo} as belt-and-suspenders (201 newly
  linked, 400 already linked, both treated as success).

* deploy/docker-compose.yml: substitute <product> placeholders, point
  image at git.jpaul.io/justin/hvm-docs:latest, set HYBRID_SEARCH=false
  to match the eval winner (bm25+rerank), keep the llama.cpp + jina
  GGUF reranker sidecar as the production target.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-22 13:07:15 -04:00

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>

2026-05-22 09:18:17 -04:00

3 Commits