Repository navigation
feat: tier-2 dinov2-server, examples, and stability contract - #20
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Final tier-2 surfaces: an HTTP embeddings server, two examples, and the stability/tier contract docs. Everything is OFF-by-default,
continue-on-errorin CI, and cannot affect the tier-1 build.tools/server/dinov2-serverbehindDINOV2_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}withpatches/l2_normalize/classify/topkoptions. 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.continue-on-error.Test plan
git diff --checkall clean