starlens 0.1.1

Certified-isomorphic compression — smaller LLM inputs with a sealed fidelity proof (an s2ar.dev product).

starlens — certified-isomorphic compression

A stardata.foundation product. Live: https://api.stardata.foundation/v1

Smaller inputs, with a sealed proof your model's answer doesn't move.

Everyone feeding images to a vision-LLM bleeds tokens — and images are billed by dimensions, not bytes, and can't ride prompt caches. Generic compressors (TinyPNG, Cloudinary) shrink bytes; they can't tell you whether the model's decision survived. starlens shrinks the payload in the currency you pay — provider tokens — and returns a fidelity certificate: a reproducible measurement that the model reads the same thing, sealed with a record_sha256 anyone can re-verify. When no compression is safe, you get a certified refusal — the image untouched, and you pay nothing.

Try it in 60 seconds

cd examples/quickstart && python quickstart.py     # real cert, committed output in its README

2560×1440 web screenshot → 827×465, 67% of Anthropic tokens saved, OCR-witnessed, seal verified — then a dense-text image the witness refuses. The flagship demo is a deterministic falling-sand world that grades the models with machine-checkable answers: stardata.foundation/starlens/sim.html (source + frames in examples/sim_census/).

Use it in your agent

Sign in at api.stardata.foundation/app (free in-browser tries, self-serve key), then add the MCP to Claude Code / Codex so your agent compresses screenshots before it sends them — docs/mcp.md:

claude mcp add starlens -e STARLENS_API_KEY=sk-lens-… -- python -m starlens.mcp_server

Raw-API users get the same via the in-flight proxy hook (docs/mcp.md).

Pricing: a share of what the certificate proves

charge = saved_tokens(target model) × its input $/Mtok × 20% — you keep 80% of measured savings; refusals are free; the invoice traces line-by-line to certificate hashes. Settlement is prepaid credits (first image free). GET /v1/models publishes the price table; GET /v1/usage your balance.

Why this is one product with the gameability certification

starlens and stardata's gameability/difficulty certification are the same instrument pointed two ways — ∆(what-matters) under a meaning-preserving transform, measured against a tolerance, sealed as a replayable certificate:

	transformation	faithful means…	gamed / lossy means…
gameability cert	meaning-preserving re-render of a passing solution	the reward score stays put	a cheap variant moves the score
compression cert	shrink the input	the model's output stays put	over-compression moves the output

The epistemics are stardata's, verbatim: don't trust the auditor — re-run the seed. Deterministic witnesses (OCR stability, gradient energy, SSIM, their composite) carry the guarantee; model-in-loop probes are labeled non-deterministic. The measured story — which witness is safe on which content, for which model, and where coverage guarantees genuinely hold — is the working preprint: stardata.foundation/starlens/paper.html.

The offer

• Compress + certify — OpenAI-compatible /v1/chat/completions: images in, smaller images + sealed certificates out (examples/quickstart/).
• Certify only — /v1/certify: bring your own compression (or a competitor's); we grade it. The audit product.
• Verify — /v1/verify/{record_sha256} re-derives any seal.

Ideal first customers: screenshot-per-turn agents and batch multimodal workloads (document OCR, frame analysis, dataset prep) — exactly where prompt caching can't help. Measured latency and ops posture: docs/ops-runbook.md (preprocessing/batch price-performance, stated honestly).

Layout

src/starlens/
  compress.py      compress_to_fidelity / _budget — the engine
  perturb.py       witnesses (recon/ocr/grad/ssim/dual/hashes) + auto-routing
  fidelity.py      the isomorphic-band search
  certificate.py   the sealed, replayable Certificate
  tokens.py        provider image→token estimators (anthropic/openai/gemini)
  models.py        per-model calibrated profiles (calibration/tiers.json)
  pricing.py       savings-share pricing (the certificate is the price tag)
  billing*.py      OUR keys/usage/credit ledgers + provider adapters (stripe live, polar dormant)
  api.py           FastAPI service + /admin ops control center (mesh-only)
examples/          quickstart (60s) · sim_census (the flagship demo)
corpus/            calibration corpora incl. the license-verified public set
docs/              design, calibration reports, ops runbook, research/ (paper)

Status

Live. Deployed on staros-work1 behind Caddy TLS; 11 models calibrated on the public corpus; 89-test suite; every research number replays from the sealed answer cache at zero API cost.