Metadata-Version: 2.4
Name: starlens
Version: 0.1.1
Summary: Certified-isomorphic compression — smaller LLM inputs with a sealed fidelity proof (an s2ar.dev product).
Project-URL: Homepage, https://s2ar.dev/
Project-URL: Documentation, https://s2ar.dev/whitepaper.html
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=10.0
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == 'api'
Requires-Dist: httpx>=0.27; extra == 'api'
Requires-Dist: python-multipart>=0.0.9; extra == 'api'
Requires-Dist: uvicorn>=0.29; extra == 'api'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: embed
Requires-Dist: open-clip-torch>=2.24; extra == 'embed'
Provides-Extra: mcp
Requires-Dist: httpx>=0.27; extra == 'mcp'
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: ocr
Requires-Dist: pytesseract>=0.3.10; extra == 'ocr'
Description-Content-Type: text/markdown

# 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

```bash
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](https://stardata.foundation/starlens/sim.html)
(source + frames in `examples/sim_census/`).

## Use it in your agent

Sign in at [api.stardata.foundation/app](https://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`](docs/mcp.md):

```bash
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](https://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.
