Skip to content

feat: tier-2 dinov2-server, examples, and stability contract - #20

Merged
espetro merged 7 commits into
mainfrom
feat/tier2-surfaces
Sep 22, 2026
Merged

espetro merged 7 commits into
mainfrom
feat/tier2-surfaces

Conversation

@espetro

@espetro espetro commented Sep 22, 2026

Copy link
Copy Markdown
Owner

Summary

Final tier-2 surfaces: an HTTP embeddings server, two examples, and the stability/tier contract docs. Everything is OFF-by-default, continue-on-error in CI, and cannot affect the tier-1 build.

  • tools/server/dinov2-server behind DINOV2_BUILD_SERVER (OFF): cpp-httplib v0.57.1 vendored single-header (MIT, sha256-verified, same pattern as stb). Sits on the public C API — exercises the tier-1 contract. GET /health, GET /v1/models, GET /version, POST /v1/embeddings (multipart or base64 JSON) returning {cls, pooled, grid, patches?, topk?, meta} with patches/l2_normalize/classify/topk options. Encodes serialized on a mutex.
  • src/image.cpp: load_image_from_memory (stbi_load_from_memory) — the seam server and wasm share for decode-without-filesystem.
  • examples/ci-visual-regression/: copy-paste GitHub Action that downloads a release, verifies SHA256SUMS, embeds baseline vs PR screenshots, fails on cosine drift.
  • examples/dedup/: 121-line stdlib-only dedup script producing cluster report + HTML review page — doubles as the "dedup photos without the cloud" demo.
  • docs/stability.md + docs/tiers.md: the contract — tier-1 (libdinov2, CLI, C API, JSONL schema, converter, GGUF publishing) vs tier-2 (wasm, server, examples); per-surface stability policies; promotion/demotion criteria.
  • extras.yml: server job (build + live curl smoke against the published small GGUF) and examples check, both continue-on-error.

Test plan

  • Default build + ctest 4/4 unaffected
  • Server live smoke: /health, /v1/models, multipart + base64 /v1/embeddings (cls 384, grid 30x44, classify top-1 tench 0.983, l2-norm 1.0), error paths return 400/404
  • dedup.py run on repo assets produces clusters + HTML
  • actionlint, clang-format-18, git diff --check all clean
  • extras.yml server job green on CI (informational by design)

load_image_from_memory wraps stbi_load_from_memory so consumers that
receive image bytes instead of file paths (the tier-2 HTTP server) can
decode uploads without touching disk.
Single-binary HTTP server over the public C API, behind
-DDINOV2_BUILD_SERVER=ON (off by default, isolated in tools/server/).
Vendors cpp-httplib v0.57.1 as a single header, same pattern as the stb
headers in src/.

Endpoints: GET /health, GET /v1/models, GET /version, and
POST /v1/embeddings accepting multipart uploads or JSON {"image":
base64}, with optional patches/l2_normalize/classify/topk flags.
Encodes are serialized on a mutex since a dino_ctx is single-threaded.
Copy-paste workflow for downstream repos: downloads a release tarball,
verifies SHA256SUMS, embeds baseline vs PR screenshots with
--preprocess crop518 --batch, and fails when pooled-vector cosine drops
below a threshold. Example only, not wired into this repo's CI.
Stdlib-only Python script that embeds a directory via dinov2-cli JSONL,
clusters near-duplicates by pooled-vector cosine (single-linkage
union-find), and writes a small HTML review page.
docs/stability.md becomes the full contract page: tier-1 surfaces
(libdinov2, dinov2-cli flags, JSONL schema, GGUF schema/publishing,
C API) vs tier-2 (wasm, server, examples, D2EMB) with the policy for
each, plus deprecation mechanics. docs/tiers.md defines the two tiers,
their hard requirements (off by default, isolated, non-blocking CI,
no compat promise), and the promotion/demotion criteria.
ARCHITECTURE.md: tier-2 layer rule (consumes public/internal headers,
nothing flows back), new tree rows for wasm/, tools/server/, examples/,
and a note on the optional targets. README: tier-2 extras section and
docs list entries. cli.md: see-also pointers.
server: builds -DDINOV2_BUILD_SERVER=ON, downloads the small GGUF via
the HF /resolve/ URL, and curl-smokes /health, /v1/models and both
/v1/embeddings request shapes (multipart + base64 JSON).

examples: py_compile on dedup.py, YAML parse + actionlint on the
visual-regression example. Both jobs continue-on-error per tier-2
policy.
@espetro
espetro merged commit 7237c65 into main Sep 22, 2026
6 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant