Commit Graph

6 Commits

Author SHA1 Message Date
justin 9fa920d0ce rag: resilient embedder — rotate/split on endpoint errors; 4-GPU embed pool
Port of zerto-docs PR #45. OllamaEmbeddings previously made a single
attempt per batch — any transient connection drop or HTTP error from
one endpoint failed the entire index rebuild.

- _embed() now rotates to the next endpoint and retries with backoff
  (5 attempts) on transport errors, and additionally halves the input
  (floor 16) on HTTP status errors: the .0.125 Windows Ollama (4090)
  400s when its model runner dies on an oversized input array. Error
  response bodies are logged instead of swallowed.
- CI workflows: OLLAMA_URLS extended from the two ripper instances to
  the full 4-endpoint GPU pool (+ .0.125 4090, + .0.126). At the
  64-chunk batches this indexer already uses, .0.125 is the fastest
  embedder in the fleet (242 embeds/s measured on seed-mcp).

Verified against the live pool: 64-text happy path, dead-endpoint
rotation, and a forced 512-text 400 on .0.125 that split and completed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-10 15:46:45 -04:00
justin 6b11993688 ci: use zerto-docs's load-balanced Ollama GPU pool on the Gitea host
Match the OLLAMA_URLS pattern from zerto-docs-rag so every docs MCP
build fans out across the same two GPU-pinned Ollama containers on
192.168.0.2 (:11435 Titan X, :11436 1080 Ti). The host's primary
Ollama on :11434 is left alone for OpenWebUI.

rag.embeddings now reads OLLAMA_URLS (plural CSV) preferentially with
fallback to OLLAMA_URL, defaulting to http://192.168.0.2:11434 — same
shape as zerto's embeddings.py. The OllamaEmbeddings class already
round-robins per batch, so both GPUs run in parallel during the
chroma rebuild.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 13:22:59 -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 43728320bf ci: default PRODUCT_NAME to repo name (caught by template dispatch test)
First dispatch on the empty template failed at Chroma collection
creation because PRODUCT_NAME was the literal string "<product>"
(YAML doesn't expand placeholders), and Chroma rejects collection
names containing characters outside [a-zA-Z0-9._-]:

  chromadb.errors.InvalidArgumentError: Validation error: name:
  Expected a name containing 3-512 characters from [a-zA-Z0-9._-],
  starting and ending with a character in [a-zA-Z0-9]. Got:
  <product>_docs

Same fix as the IMAGE env: derive from the repo name dynamically
via ${{ github.event.repository.name }}. Cloners can still override
explicitly, but a fresh clone now runs the index-rebuild step
cleanly out of the box.

Verified by re-dispatch — should fail next at docker login (placeholder
REGISTRY_PUSH hostname), which is the next-expected fail point and a
real per-deployment config the cloner has to fill in.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 09:37:07 -04:00
justin 33b0fd652e ci: derive image name + package linking from repo, add link step
Both workflows had a static IMAGE env (<owner>/<product>-docs-mcp)
and a static --package arg in the GC step. Switch both to Gitea
Actions context variables so a clone of the template into any repo
name works on the first CI run without find/replace:

  IMAGE: ${{ github.repository_owner }}/${{ github.event.repository.name }}
  --owner ${{ github.repository_owner }}
  --package ${{ github.event.repository.name }}

Also add the "Link container package to this repo" step that was
missing from the template (and which, naively copy-pasted from the
reference build, would have linked everything back to docs-mcp-
template). The new step derives owner + package + link-target all
from the running repo's context.

The github.* namespace is Gitea Actions' inherited GitHub-Actions
context — values come from the Gitea server, not github.com. Same
mechanism the reference build's $GITHUB_SHA tag-builder uses.

CLAUDE.md updated to note that image and package naming are
repo-derived; only registry endpoints and the Ollama URL need
per-clone editing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 09:34:26 -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