jevimage 0.1.0__tar.gz

jevimage-0.1.0/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+## Unreleased
+
+Local SDK fixes - input that was accepted and then failed somewhere else, and three
+things that were wrong rather than unclear:
+
+- **`batch=True` no longer fails a whole batch for one bad image.** One caller's
+  truncated upload answered every other caller who rode the same forward pass with an
+  error about a file they never sent - on a server, up to 15 healthy requests at a time.
+  A failing batch is now re-run one item at a time, so each caller gets its own result
+  or its own error.
+- **A head retrained by another process is picked up by `head()` and `ask()`,** not only
+  by `list_heads()`. The freshness check ran on a cache MISS, so once a name was cached
+  every later read served the pre-retrain weights and class names, with no error.
+  Deleting a head propagates the same way.
+- **`HeadStore` is thread-safe for reads again.** Two threads syncing at once both
+  removed the same vanished head, and the loser raised `KeyError` out of `name in store`
+  - the check that gates every `head` question.
+- Two processes saving the same head name no longer collide: the temp file is per
+  writer, so the loser is overwritten instead of failing with a `FileNotFoundError`
+  about a `.pt.tmp` it never named. Retraining a broken head clears it from
+  `heads.broken`.
+- `load()` refuses to rename an encoder instance that is already cached under another
+  registry name, instead of silently renaming it and invalidating every head trained
+  under the first name. `register()` also drops cached ensembles built from that name.
+- `Ensemble` normalises each member before concatenating, as `docs/encoders.md` always
+  said it did. Without it a member whose output is not unit-norm outvoted the others,
+  and the engine's L2 check could not see it.
+- SigLIP entries truncate a caption to the tokeniser's 64 tokens instead of failing with
+  a transformers error about `max_position_embeddings`.
+- A `prompt` or `template` is validated by trial substitution, so `'{} and {}'`,
+  `'a photo of {x}'` and `'{.__class__}'` are refused by name instead of escaping as a
+  raw `IndexError`/`KeyError`, or captioning every option `"<class 'str'>"`. `train()`
+  and `compare()` check `template=` before any work, so a bad one no longer raises
+  *after* the head is on disk.
+- `ask_embedding()` checks what it was handed: a numpy array, a list, a stray batch
+  dimension or the wrong width are named, not left to fail inside the engine.
+- `max_per_class` means one thing in all three `data` shapes: a positive int, or `None`.
+  `0` used to mean "no limit", `-1` dropped different examples in each shape, and a
+  folder was truncated twice - which could delete a whole class.
+- `to_image()` treats `Path` exactly like `str`, truncates what it quotes back, reports a
+  malformed `data:` URL as a `ValueError` naming the URL, and accepts `DATA:`.
+  `read_folder` sorts by filename, not by full path, which is what the docs promised
+  once sub-directories are involved.
+- `temperature` accepts any real number (numpy scalars included) in `1e-6 .. 1e6`, and
+  says so. Outside that range fp32 underflowed and the reported winner could flip. An
+  encoder's `logit_scale` goes through the same guard, so a negative one is an error
+  rather than a confident answer on the wrong option.
+- The singular `instruction` is read again as a spelling of `instructions`, which is
+  what `docs/questions.md` documents. (0.1.0 removed it as "undocumented"; the docs row
+  says otherwise, so the docs win.)
+- `jevimage[local]` requires `transformers>=4.56`: `metaclip2-huge` is `model_type
+  metaclip_2`, which older versions do not recognise, so the old floor allowed an
+  install that could not load a listed encoder.
+- `dfn5b-h-14-384` names the extra it needs when `open_clip` is missing.
+
+Client fixes, all in `jevimage.connect()`:
+
+- `max_edge=` is now actually used. It was stored and never passed to the upload, so
+  every image was downscaled to 384px whatever you asked for, and `None` did nothing.
+- An oversized image is exif-transposed before it is re-encoded for upload. A portrait
+  phone photo used to reach the server sideways, with its Orientation tag dropped by the
+  re-encode, so remote answers disagreed with local ones.
+- A `POST` (`ask`, `embed`, `train`) is no longer silently replayed when a kept
+  connection dies. The failure can surface after the server has done the work, so a
+  `train()` could run twice. `GET` and `DELETE` still reconnect once.
+- `api_key` is validated in `connect()`: a trailing newline or a non-ASCII character
+  used to blow up inside `http.client`, with the key itself in the traceback.
+- `Remote.ask` gives `Jev.ask`'s wording for a bad temperature, `Remote.train` refuses
+  an out-of-range `epochs` (the server's 1..5000) with a sentence instead of a pydantic
+  field dump, a 2xx that is not JSON is a `JevError` naming the URL, and a redirect
+  leads with where it pointed instead of the proxy's HTML page.
+
+Docs:
+
+- **`examples/make_fixtures.py` ships the images the docs read.** Every page's
+  transcripts were run over `ds/`, `shots/` and `colours/` folders that were never in
+  the repo, so no block on any page ran as written, and the stand-in encoders key off
+  raw pixels, so no number could be reproduced either. The script writes all three, and
+  every printed number on quickstart, questions, training, cookbook, encoders, the three
+  references, index and README was re-run against them and re-pasted.
+- Blocks that could not run as printed now run: `import json` in the quickstart's first
+  block, `ToyCalibrated` in the questions prelude, `import base64` and `import tempfile`
+  where the reference and encoders pages use them, a `uvicorn` line for the mounted-app
+  transcript in serving, and `jevimage.load(Toy())` where troubleshooting said
+  `jevimage.load("toy")`, which is not a registry name.
+- `jevimage.encoders` (and any other submodule) resolves after a plain `import
+  jevimage`, so `troubleshooting.md`'s ensemble-name example and the advice in the
+  engine's own "wrap your encoder's output in `jevimage.encoders.unit()`" both work.
+- Claims corrected against measurement: warm `load()` of `siglip2-base-224` is 8-10 s on
+  the 16-thread laptop CPU these docs are measured on, not 4.8/5.0 s; 5000 epochs on
+  4000 examples is about 70 s, not "seconds"; 16 concurrent single-image embeds coalesce
+  into 2 forward passes on the toy encoder rather than staying 16; several keys may be
+  configured so callers can migrate, but withdrawing one is a restart, not zero
+  downtime; and N questions are only near-free once their captions are cached.
+
+## 0.1.0
+
+First release.
+
+- `choice`, `score`, `noul` and `head` questions against one image encode.
+- `jevimage.load()` for in-process use, `jevimage.connect(url)` for a server. Same
+  methods, same return shapes.
+- `jev` CLI: `ask`, `train`, `heads`, `rm`, `encoders`, `serve`. The first four take
+  `--url`.
+- Linear heads trained on a labelled folder, with a per-class comparison against the
+  zero-shot prompts.
+- Seven built-in encoders plus `'+'` ensembles, and `register()` for your own.
+
+Two notes for anyone who tracked the pre-release source:
+
+- `plan()` no longer accepts the singular `instruction` key as an alias for
+  `instructions`. It was undocumented; the singular spelling now raises.
+- `Encoder` has no `preprocess()` / `img_from_px()` pair. Nothing called it, and the
+  cross-request batching it was meant to enable was never wired up. `Batcher` batches
+  whole images through `img()`.

jevimage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the jevimage authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jevimage-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# The sdist is the whole project, not only the importable package: a distro packager or
+# `pip install --no-binary :all:` builds from this archive, and setuptools' defaults ship
+# tests/test_*.py without tests/conftest.py, which holds every fixture they import.
+recursive-include tests *.py
+recursive-include docs *.md
+recursive-include examples *.py
+include mkdocs.yml
+include CHANGELOG.md
+include docs.json

jevimage-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: jevimage
+Version: 0.1.0
+Summary: A probability-first image classifier you can self-host: one encode, many typed questions, calibrated answers.
+Author: the jevimage authors
+License-Expression: MIT
+Project-URL: Documentation, https://docs.jevimage.org
+Project-URL: Source, https://github.com/Per0x1de-1337/jevimage
+Project-URL: Issues, https://github.com/Per0x1de-1337/jevimage/issues
+Keywords: image-classification,zero-shot,clip,siglip,embeddings,calibration,vision,self-hosted
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pillow>=9.0
+Provides-Extra: local
+Requires-Dist: torch>=2.0; extra == "local"
+Requires-Dist: transformers>=4.56; extra == "local"
+Provides-Extra: serve
+Requires-Dist: jevimage[local]; extra == "serve"
+Requires-Dist: fastapi>=0.110; extra == "serve"
+Requires-Dist: uvicorn>=0.27; extra == "serve"
+Provides-Extra: openclip
+Requires-Dist: jevimage[local]; extra == "openclip"
+Requires-Dist: open_clip_torch>=2.24; extra == "openclip"
+Provides-Extra: dev
+Requires-Dist: jevimage[serve]; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# jevimage
+
+jevimage answers typed questions about an image with probabilities instead of prose. The
+image goes through a frozen dual encoder once and becomes a single unit-norm vector.
+Every question after that (pick one of these options, place it on this rubric, yes or
+no, run the head I trained on my own photos) is a matmul against that same vector.
+
+Nothing is generated. An answer is a distribution over names *you* chose, plus a
+confidence rescaled so one threshold works whether the question had two options or fifty.
+So there is no sentence to parse and no retry loop. The same image and question give the
+same numbers, to the six decimals they are printed to, every time, and the tenth question
+about an image costs a matmul rather than another forward pass once its captions are
+cached. A repeated question set is what gets cheap; a caption the process has never
+seen still costs one text-tower pass. When prompts are not good enough you fit a linear
+head on a folder of your own labelled images in seconds — and jevimage tells you, per
+class, whether that head beat the prompts. Sometimes it did not, and it says so.
+
+Full documentation is in [docs/](https://docs.jevimage.org/docs/index/).
+
+## Two ways to use it
+
+Both are first class, and they are the same API. Pick the row you are in.
+
+|  | Use someone's server | Run it yourself |
+|---|---|---|
+| install | `pip install jevimage` | `pip install 'jevimage[local]'` |
+| what that pulls in | pillow and the standard library. **No torch, no transformers, no weights.** | torch, transformers, and encoder weights on first use |
+| entry point | `jevimage.connect(url)` | `jevimage.load()` |
+| where the model runs | on that server | in your process |
+| where your images go | up to that server | nowhere |
+
+The base install is an HTTP client. Asking, embedding, managing heads **and training**
+all work through it, because the encoder that fits the head lives on the server.
+`jev encoders` works with no torch on the machine, and `jev ask/train/heads/rm --url ...`
+(or `$JEV_URL` with `$JEV_API_KEY`) drive a server from the shell.
+
+In that install `jevimage.load()` does not fail obscurely; it names both fixes:
+
+```console
+$ python -c "import jevimage; jevimage.load()"
+ImportError: jevimage.load runs the encoder in this process, which needs torch and
+transformers: pip install 'jevimage[local]'
+To use a server instead - no torch required - call jevimage.connect(url).
+(underlying import error: No module named 'torch')
+```
+
+## Install
+
+Python 3.10+. Four installs, each a superset of the base. The package is **not on PyPI
+yet** — until it is, these mean `pip install .` and `pip install '.[local]'` against a
+clone, as [docs/install.md](https://docs.jevimage.org/docs/install/#from-source) shows:
+
+```bash
+pip install jevimage                # API only: pillow + stdlib. connect(), and the CLI's --url mode.
+pip install 'jevimage[local]'       # + torch, transformers. load() runs the encoder here.
+pip install 'jevimage[serve]'       # + fastapi, uvicorn. `jev serve` hosts it for others.
+pip install 'jevimage[openclip]'    # + open_clip, for the dfn5b-h-14-384 entry (Apple's licence — see below).
+```
+
+`[serve]` and `[openclip]` both include `[local]`, because a server runs the encoder and
+open_clip is an encoder. Sizes, offline and air-gapped use, and what the first `load()`
+downloads: [docs/install.md](https://docs.jevimage.org/docs/install/).
+
+## Quickstart
+
+Three questions, one encode. This runs on the API-only install:
+
+```python
+import jevimage
+
+jev = jevimage.connect("http://127.0.0.1:8123")     # or jevimage.load(), same methods
+
+a = jev.ask("ds/red/0.png", {           # or any image of your own
+    "colour": {"type": "choice",
+               "criteria": {"red": "a red square", "blue": "a blue square"}},
+    "bright": {"type": "score",
+               "criteria": ["a dark square", "a mid-tone square", "a bright square"]},
+    "plain":  {"type": "noul",
+               "criteria": {"true": "one flat colour", "false": "a detailed photo"}},
+})
+
+print(a["colour"])
+print(a["colour"].choice, a["colour"].probabilities, a["colour"].confidence)
+print(a["bright"], a["plain"])
+```
+
+```text
+<choice 'red' p=1.000>
+red {'red': 1.0, 'blue': 0.0} 0.999999
+<score 0.02/2> <noul 0.038>
+```
+
+> That transcript is real, against a red square: `ds/red/0.png`, one of the twelve
+> `python examples/make_fixtures.py` writes. The server was hosting a deterministic
+> stand-in encoder, so the numbers are reproducible and the example costs nothing to
+> re-run; the code, the shapes and the reprs are exactly what you get. On a real encoder
+> the numbers move but the saturation does not necessarily: the same `colour` question on
+> `siglip2-base-224` measured `{'red': 0.997553, 'blue': 0.002447}`, and `bright` came
+> out `<score 1.52/2>` where the stand-in said `0.02`.
+
+An `Answer` is a `dict` subclass with attribute access: `a["colour"].choice` and
+`a["colour"]["choice"]` are the same thing, printing one gives the short repr above, and
+`json.dumps(a)` gives the full shape with no conversion step. Swapping `connect(url)` for
+`load()` changes nothing else in that file.
+
+The four question types are `choice` (one of 2–255 named options), `score` (a position
+on an ordered rubric), `noul` ("no-or-yes level": one yes/no probability) and `head` (a
+classifier you trained). Up to 64 of them ride one encode. See
+[docs/questions.md](https://docs.jevimage.org/docs/questions/).
+
+Training, in one line and with the honest number attached:
+
+```console
+$ jev train colour ds/ --url http://127.0.0.1:8123
+'colour': 12 examples, 2 classes, encoder toy
+
+class   n  zero-shot  trained   delta
+blue    6      50.0%    50.0%    0.0%
+red     6     100.0%    50.0%  -50.0%
+ALL    12      75.0%    50.0%  -25.0%
+
+trained is k-fold held-out; zero-shot needs no holdout so it is scored on every example.
+Training did not beat the prompts here - try more examples per class, or a bigger encoder.
+```
+
+The zero-shot column is what the prompts alone scored on the same images, because
+training does not always help, and the only useful answer is the one for your images,
+per class.
+
+## Documentation
+
+| Page | Read it when |
+|---|---|
+| [Overview](https://docs.jevimage.org/docs/index/) | You want the shape of the whole thing, including what it deliberately does not do. |
+| [Install](https://docs.jevimage.org/docs/install/) | Choosing between the four installs, or working offline. |
+| [Quickstart](https://docs.jevimage.org/docs/quickstart/) | The same walkthrough twice, once against a server and once in-process. |
+| [Question types](https://docs.jevimage.org/docs/questions/) | Writing questions: `choice`, `score`, `noul`, `head`, and the two forms of `noul`. |
+| [Training a head](https://docs.jevimage.org/docs/training/) | Prompts are not good enough and you have labelled images. Also: how to tell whether training helped. |
+| [Choosing an encoder](https://docs.jevimage.org/docs/encoders/) | Picking from the registry, joining two with `+`, or plugging in your own model. |
+| [Serving](https://docs.jevimage.org/docs/serving/) | Running `jev serve` for other people: routes, API keys, limits, deployment. |
+| [CLI reference](https://docs.jevimage.org/docs/reference-cli/) | `jev ask`, `train`, `heads`, `rm`, `encoders`, `serve` — local or `--url`. |
+| [Python reference](https://docs.jevimage.org/docs/reference-python/) | The exact public surface: every function, method and return shape. |
+| [HTTP reference](https://docs.jevimage.org/docs/reference-http/) | The routes, if you are writing your own client. |
+| [Cookbook](https://docs.jevimage.org/docs/cookbook/) | Complete scripts: screening an upload, caching an embedding, routing a directory. |
+| [Troubleshooting](https://docs.jevimage.org/docs/troubleshooting/) | The error's sentence is clear but the reason it fired is not. |
+
+The pages are plain Markdown with relative links, so they read on GitHub as they are.
+[`mkdocs.yml`](https://github.com/Per0x1de-1337/jevimage/blob/main/mkdocs.yml) is there if you want a searchable site instead:
+`pip install 'jevimage[docs]' && mkdocs serve`.
+
+Runnable examples live in [`examples/`](https://github.com/Per0x1de-1337/jevimage/blob/main/examples/). The test suite is
+`pip install 'jevimage[dev]' && python -m pytest tests/ -q`.
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/Per0x1de-1337/jevimage/blob/main/LICENSE).
+
+The model weights are not MIT and are not redistributed here — each one downloads from
+its own source under its own terms. In particular, `dfn5b-h-14-384` pulls Apple's DFN5B
+checkpoint, which carries **Apple's own licence**. Read it before you ship or redistribute
+anything built on that encoder. It sits behind the optional `[openclip]` extra for exactly
+that reason: the choice is yours to make, so it is never installed on your behalf.

jevimage-0.1.0/README.md

@@ -0,0 +1,162 @@
+# jevimage
+
+jevimage answers typed questions about an image with probabilities instead of prose. The
+image goes through a frozen dual encoder once and becomes a single unit-norm vector.
+Every question after that (pick one of these options, place it on this rubric, yes or
+no, run the head I trained on my own photos) is a matmul against that same vector.
+
+Nothing is generated. An answer is a distribution over names *you* chose, plus a
+confidence rescaled so one threshold works whether the question had two options or fifty.
+So there is no sentence to parse and no retry loop. The same image and question give the
+same numbers, to the six decimals they are printed to, every time, and the tenth question
+about an image costs a matmul rather than another forward pass once its captions are
+cached. A repeated question set is what gets cheap; a caption the process has never
+seen still costs one text-tower pass. When prompts are not good enough you fit a linear
+head on a folder of your own labelled images in seconds — and jevimage tells you, per
+class, whether that head beat the prompts. Sometimes it did not, and it says so.
+
+Full documentation is in [docs/](https://docs.jevimage.org/docs/index/).
+
+## Two ways to use it
+
+Both are first class, and they are the same API. Pick the row you are in.
+
+|  | Use someone's server | Run it yourself |
+|---|---|---|
+| install | `pip install jevimage` | `pip install 'jevimage[local]'` |
+| what that pulls in | pillow and the standard library. **No torch, no transformers, no weights.** | torch, transformers, and encoder weights on first use |
+| entry point | `jevimage.connect(url)` | `jevimage.load()` |
+| where the model runs | on that server | in your process |
+| where your images go | up to that server | nowhere |
+
+The base install is an HTTP client. Asking, embedding, managing heads **and training**
+all work through it, because the encoder that fits the head lives on the server.
+`jev encoders` works with no torch on the machine, and `jev ask/train/heads/rm --url ...`
+(or `$JEV_URL` with `$JEV_API_KEY`) drive a server from the shell.
+
+In that install `jevimage.load()` does not fail obscurely; it names both fixes:
+
+```console
+$ python -c "import jevimage; jevimage.load()"
+ImportError: jevimage.load runs the encoder in this process, which needs torch and
+transformers: pip install 'jevimage[local]'
+To use a server instead - no torch required - call jevimage.connect(url).
+(underlying import error: No module named 'torch')
+```
+
+## Install
+
+Python 3.10+. Four installs, each a superset of the base. The package is **not on PyPI
+yet** — until it is, these mean `pip install .` and `pip install '.[local]'` against a
+clone, as [docs/install.md](https://docs.jevimage.org/docs/install/#from-source) shows:
+
+```bash
+pip install jevimage                # API only: pillow + stdlib. connect(), and the CLI's --url mode.
+pip install 'jevimage[local]'       # + torch, transformers. load() runs the encoder here.
+pip install 'jevimage[serve]'       # + fastapi, uvicorn. `jev serve` hosts it for others.
+pip install 'jevimage[openclip]'    # + open_clip, for the dfn5b-h-14-384 entry (Apple's licence — see below).
+```
+
+`[serve]` and `[openclip]` both include `[local]`, because a server runs the encoder and
+open_clip is an encoder. Sizes, offline and air-gapped use, and what the first `load()`
+downloads: [docs/install.md](https://docs.jevimage.org/docs/install/).
+
+## Quickstart
+
+Three questions, one encode. This runs on the API-only install:
+
+```python
+import jevimage
+
+jev = jevimage.connect("http://127.0.0.1:8123")     # or jevimage.load(), same methods
+
+a = jev.ask("ds/red/0.png", {           # or any image of your own
+    "colour": {"type": "choice",
+               "criteria": {"red": "a red square", "blue": "a blue square"}},
+    "bright": {"type": "score",
+               "criteria": ["a dark square", "a mid-tone square", "a bright square"]},
+    "plain":  {"type": "noul",
+               "criteria": {"true": "one flat colour", "false": "a detailed photo"}},
+})
+
+print(a["colour"])
+print(a["colour"].choice, a["colour"].probabilities, a["colour"].confidence)
+print(a["bright"], a["plain"])
+```
+
+```text
+<choice 'red' p=1.000>
+red {'red': 1.0, 'blue': 0.0} 0.999999
+<score 0.02/2> <noul 0.038>
+```
+
+> That transcript is real, against a red square: `ds/red/0.png`, one of the twelve
+> `python examples/make_fixtures.py` writes. The server was hosting a deterministic
+> stand-in encoder, so the numbers are reproducible and the example costs nothing to
+> re-run; the code, the shapes and the reprs are exactly what you get. On a real encoder
+> the numbers move but the saturation does not necessarily: the same `colour` question on
+> `siglip2-base-224` measured `{'red': 0.997553, 'blue': 0.002447}`, and `bright` came
+> out `<score 1.52/2>` where the stand-in said `0.02`.
+
+An `Answer` is a `dict` subclass with attribute access: `a["colour"].choice` and
+`a["colour"]["choice"]` are the same thing, printing one gives the short repr above, and
+`json.dumps(a)` gives the full shape with no conversion step. Swapping `connect(url)` for
+`load()` changes nothing else in that file.
+
+The four question types are `choice` (one of 2–255 named options), `score` (a position
+on an ordered rubric), `noul` ("no-or-yes level": one yes/no probability) and `head` (a
+classifier you trained). Up to 64 of them ride one encode. See
+[docs/questions.md](https://docs.jevimage.org/docs/questions/).
+
+Training, in one line and with the honest number attached:
+
+```console
+$ jev train colour ds/ --url http://127.0.0.1:8123
+'colour': 12 examples, 2 classes, encoder toy
+
+class   n  zero-shot  trained   delta
+blue    6      50.0%    50.0%    0.0%
+red     6     100.0%    50.0%  -50.0%
+ALL    12      75.0%    50.0%  -25.0%
+
+trained is k-fold held-out; zero-shot needs no holdout so it is scored on every example.
+Training did not beat the prompts here - try more examples per class, or a bigger encoder.
+```
+
+The zero-shot column is what the prompts alone scored on the same images, because
+training does not always help, and the only useful answer is the one for your images,
+per class.
+
+## Documentation
+
+| Page | Read it when |
+|---|---|
+| [Overview](https://docs.jevimage.org/docs/index/) | You want the shape of the whole thing, including what it deliberately does not do. |
+| [Install](https://docs.jevimage.org/docs/install/) | Choosing between the four installs, or working offline. |
+| [Quickstart](https://docs.jevimage.org/docs/quickstart/) | The same walkthrough twice, once against a server and once in-process. |
+| [Question types](https://docs.jevimage.org/docs/questions/) | Writing questions: `choice`, `score`, `noul`, `head`, and the two forms of `noul`. |
+| [Training a head](https://docs.jevimage.org/docs/training/) | Prompts are not good enough and you have labelled images. Also: how to tell whether training helped. |
+| [Choosing an encoder](https://docs.jevimage.org/docs/encoders/) | Picking from the registry, joining two with `+`, or plugging in your own model. |
+| [Serving](https://docs.jevimage.org/docs/serving/) | Running `jev serve` for other people: routes, API keys, limits, deployment. |
+| [CLI reference](https://docs.jevimage.org/docs/reference-cli/) | `jev ask`, `train`, `heads`, `rm`, `encoders`, `serve` — local or `--url`. |
+| [Python reference](https://docs.jevimage.org/docs/reference-python/) | The exact public surface: every function, method and return shape. |
+| [HTTP reference](https://docs.jevimage.org/docs/reference-http/) | The routes, if you are writing your own client. |
+| [Cookbook](https://docs.jevimage.org/docs/cookbook/) | Complete scripts: screening an upload, caching an embedding, routing a directory. |
+| [Troubleshooting](https://docs.jevimage.org/docs/troubleshooting/) | The error's sentence is clear but the reason it fired is not. |
+
+The pages are plain Markdown with relative links, so they read on GitHub as they are.
+[`mkdocs.yml`](https://github.com/Per0x1de-1337/jevimage/blob/main/mkdocs.yml) is there if you want a searchable site instead:
+`pip install 'jevimage[docs]' && mkdocs serve`.
+
+Runnable examples live in [`examples/`](https://github.com/Per0x1de-1337/jevimage/blob/main/examples/). The test suite is
+`pip install 'jevimage[dev]' && python -m pytest tests/ -q`.
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/Per0x1de-1337/jevimage/blob/main/LICENSE).
+
+The model weights are not MIT and are not redistributed here — each one downloads from
+its own source under its own terms. In particular, `dfn5b-h-14-384` pulls Apple's DFN5B
+checkpoint, which carries **Apple's own licence**. Read it before you ship or redistribute
+anything built on that encoder. It sits behind the optional `[openclip]` extra for exactly
+that reason: the choice is yours to make, so it is never installed on your behalf.