jevimage 0.1.0__py3-none-any.whl

jevimage/__init__.py

@@ -0,0 +1,119 @@
+"""jevimage - a probability-first image classifier you can self-host.
+
+One image encode, many typed questions read against it. Nothing is generated: every
+answer is a calibrated probability distribution, so you get a number you can threshold
+instead of a sentence you have to parse.
+
+There are two ways to use this, and both are first class.
+
+RUN IT YOURSELF - the models execute in your process, nothing leaves the machine:
+
+    pip install 'jevimage[local]'
+
+    import jevimage
+    jev = jevimage.load()                       # siglip2-base-224 by default
+    a = jev.ask("photo.jpg", {
+        "scene": {"type": "choice",
+                  "criteria": {"indoor": "an indoor scene",
+                               "outdoor": "an outdoor scene"}},
+    })
+    a["scene"].choice           # 'outdoor'
+    a["scene"].probabilities    # {'indoor': 0.07, 'outdoor': 0.93}
+    a["scene"].confidence       # 0.86
+
+USE A SERVER - someone else runs the encoder; you need no torch, no weights, no GPU:
+
+    pip install jevimage                        # a few hundred KB, stdlib + pillow
+
+    jev = jevimage.connect("https://jev.example.com", api_key="...")
+    a = jev.ask("photo.jpg", {...})             # the same call, the same Answer objects
+
+`connect()` is a drop-in for `load()`: same method names, same return shapes. Write
+against one and switch later by changing that line.
+
+HOST IT FOR OTHERS:
+
+    pip install 'jevimage[serve]'
+    jev serve --host 0.0.0.0 --port 8000
+
+Zero-shot not good enough? Train a head on your own labelled images. The encoder stays
+frozen, so this takes about a second and costs nothing at query time - and it works the
+same locally or through a server:
+
+    head = jev.train("street", "dataset/")      # dataset/bus/*.jpg, dataset/bike/*.jpg
+    head.accuracy                               # held-out, k-fold
+    jev.ask("photo.jpg", {"q": {"type": "head", "head": "street"}})
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# Only the light things are imported eagerly. torch and transformers live behind
+# __getattr__ below, so `import jevimage` costs milliseconds and an API-only install
+# never needs them on disk at all.
+from .answers import Answer, confidence, normalise_questions
+from .images import IMAGE_SUFFIXES, Head, as_examples, read_folder, to_image
+
+__all__ = ["load", "connect", "register", "available", "Jev", "Head", "Answer",
+           "Encoder", "JevError", "to_image", "read_folder", "as_examples",
+           "confidence", "IMAGE_SUFFIXES", "DEFAULT", "__version__"]
+
+_LAZY = {
+    "load": ("local", "load"),
+    "Jev": ("local", "Jev"),
+    "Encoder": ("encoders", "Encoder"),
+    "register": ("encoders", "register"),
+    "available": ("encoders", "available"),
+    "DEFAULT": ("encoders", "DEFAULT"),
+    "JevError": ("client", "JevError"),
+}
+
+
+def __getattr__(name):
+    """Resolve the rest of the API on first use.
+
+    `load` and `Jev` need torch; the encoder-registry names and `JevError` do not - they
+    are here to keep `import jevimage` down to milliseconds. Importing the heavy half
+    lazily is what lets `pip install jevimage` be a small HTTP client, while
+    `pip install 'jevimage[local]'` is the full framework under the identical name.
+    """
+    target = _LAZY.get(name)
+    if target is None:
+        # submodules too: error messages and the docs say jevimage.encoders.unit(),
+        # and a plain `import jevimage` should be enough to reach one.
+        import importlib.util
+        if importlib.util.find_spec(f".{name}", __name__) is None:
+            raise AttributeError(f"module 'jevimage' has no attribute {name!r}")
+        target = (name, None)
+    module, attr = target
+    try:
+        import importlib
+        mod = importlib.import_module(f".{module}", __name__)
+        return mod if attr is None else getattr(mod, attr)
+    except ImportError as e:
+        raise ImportError(
+            f"jevimage.{name} runs the encoder in this process, which needs torch and "
+            f"transformers: pip install 'jevimage[local]'\n"
+            f"To use a server instead - no torch required - call "
+            f"jevimage.connect(url).\n(underlying import error: {e})") from e
+
+
+def __dir__():
+    return sorted(__all__)
+
+
+def connect(url: str, *, api_key: str | None = None, timeout: float = 60.0,
+            max_edge: int | None = 384):
+    """Talk to a `jev serve` instance. Same methods as `load()`, over HTTP.
+
+    Needs no torch and downloads no weights, so this is the whole dependency footprint
+    of an API-only install.
+
+    `max_edge` downscales an image before uploading it, because no encoder reads more
+    than 384px and on a fresh connection the upload is most of the latency. Pass None
+    to send originals.
+    The returned object keeps one connection open; close it with `.close()`, or use it
+    as a context manager.
+    """
+    from .client import Remote
+    return Remote(url, api_key=api_key, timeout=timeout, max_edge=max_edge)

jevimage/answers.py

@@ -0,0 +1,125 @@
+"""The shapes a request and its answers take, with no dependency on torch.
+
+This module is deliberately pure Python. An API-only install - someone who just calls a
+`jev serve` instance over HTTP - gets the same Answer objects as someone running the
+models locally, without installing a deep-learning stack to do it.
+"""
+from __future__ import annotations
+
+import math
+import numbers
+
+__all__ = ["Answer", "check_template", "confidence", "normalise_questions",
+           "positive_temperature", "TEMPERATURE_RANGE"]
+
+# The usable range. Probabilities are reported to six decimals, so below the floor every
+# distribution is one-hot and above the ceiling every one is uniform to the last digit
+# printed - and past about 1e38 the fp32 division underflows to zero, which made the
+# ANSWER flip to whichever option was listed first. Both ends are the same failure inf
+# is refused for: a well-formed answer carrying no signal.
+TEMPERATURE_RANGE = (1e-6, 1e6)
+
+
+def positive_temperature(temperature):
+    """A negative temperature inverts every softmax - the least similar option wins, and
+    the answer still reports high confidence - so it must never reach one.
+
+    Here rather than in `core`, so the torch-free client can refuse a bad temperature
+    with the same three sentences a local `Jev` gives instead of its own wording.
+    """
+    # numbers.Real, not (int, float): a numpy scalar is a number, and refusing
+    # np.float32(0.5) with "must be a number greater than 0, got 0.5" states a falsehood
+    # about the value it prints - while np.float64 sailed through for subclassing float.
+    if isinstance(temperature, bool) or not isinstance(temperature, numbers.Real):
+        raise ValueError(f"temperature must be a number greater than 0, "
+                         f"got {temperature!r}")
+    if not temperature > 0:
+        raise ValueError(f"temperature must be greater than 0, got {temperature!r}")
+    # inf is "greater than 0" and divides every logit to zero, so every option comes
+    # back equally likely and confidence 0 - a well-formed answer carrying no signal,
+    # which is worse than an error because nothing downstream can tell.
+    if not math.isfinite(temperature):
+        raise ValueError(f"temperature must be finite, got {temperature!r}; an infinite "
+                         "temperature makes every option equally likely")
+    lo, hi = TEMPERATURE_RANGE
+    if not lo <= temperature <= hi:
+        raise ValueError(f"temperature must be between {lo:g} and {hi:g}, got "
+                         f"{temperature!r}; outside that range every option comes back "
+                         "equally likely, or exactly one does, whatever the image says")
+    return float(temperature)
+
+
+def check_template(tpl, field: str = "prompt"):
+    """A caption template must substitute exactly once.
+
+    Testing for a literal '{}' is not enough: 'a photo of {x}', '{} and {}' and '{ {}'
+    all contain a brace, all passed, and all then blew up inside str.format with a raw
+    stdlib error naming neither the field nor the question. A trial substitution answers
+    the only question that matters - can this template turn one option into one caption.
+    """
+    probe = "\x00probe\x00"
+    try:
+        if isinstance(tpl, str) and tpl.format(probe).count(probe) == 1:
+            return tpl
+    except (IndexError, KeyError, ValueError):
+        pass
+    # without exactly one placeholder every option gets the same caption, so the answer
+    # is a uniform distribution over identical strings and `choice` is whichever came first
+    raise ValueError(f"{field} {tpl!r} has no '{{}}' placeholder, so every option "
+                     "would get the same caption; write e.g. 'a photo of {}'")
+
+
+class Answer(dict):
+    """One question's answer. A plain dict, so it serialises to JSON unchanged, with
+    attribute access because `a.choice` reads better than `a["choice"]`."""
+
+    def __getattr__(self, k):
+        try:
+            return self[k]
+        except KeyError:
+            raise AttributeError(
+                f"{self.get('type', 'answer')!r} answers have no {k!r}; "
+                f"this one has: {', '.join(self)}") from None
+
+    def __repr__(self):
+        if "choice" in self:
+            return (f"<{self['type']} {self['choice']!r} "
+                    f"p={max(self['probabilities'].values()):.3f}>")
+        if "noul" in self:
+            return f"<noul {self['noul']:.3f}>"
+        if "score" in self:
+            return f"<score {self['score']:.2f}/{len(self['legend']) - 1}>"
+        return f"<{self.get('type', 'answer')}>"
+
+
+def confidence(p) -> float:
+    """How peaked a distribution is, rescaled so uniform is 0 and certain is 1.
+
+    Raw max-probability is not comparable across questions: 0.5 is lukewarm over two
+    options and emphatic over fifty. (max - 1/K) / (1 - 1/K) removes that dependence,
+    so one threshold works for every question you ask.
+    """
+    k = len(p)
+    return (max(p) - 1 / k) / (1 - 1 / k) if k > 1 else 1.0
+
+
+def normalise_questions(questions) -> dict:
+    """A dict keyed by id, or a list that gets q1, q2, ... . Both are common at call
+    sites; neither should need a wrapper."""
+    if isinstance(questions, dict):
+        return questions
+    if isinstance(questions, (list, tuple)):
+        out = {}
+        for i, q in enumerate(questions):
+            if not isinstance(q, dict):
+                # same sentence core.plan gives for the dict form, so a malformed
+                # question reads the same whichever shape it arrived in - and an
+                # AttributeError below would escape as a 500 rather than a 422
+                raise ValueError(f"a question must be an object, got {type(q).__name__}")
+            qid = q.get("id") or f"q{i + 1}"
+            if qid in out:
+                # the dict would keep only the last: two questions in, one answer out
+                raise ValueError(f"two questions share the id {qid!r}; ids must be unique")
+            out[qid] = q
+        return out
+    raise TypeError("questions must be a {id: question} object or a list of questions")

jevimage/batcher.py

@@ -0,0 +1,212 @@
+"""Dynamic batching for the image encoder.
+
+One image through the encoder costs 9.7ms; eight together cost 20.6ms - 2.6ms each.
+The GPU is idle between the small matmuls of a single image, so the marginal image in a
+batch is nearly free. Measured on the A10G:
+
+    batch  1   9.68 ms/img   103 img/s
+    batch  8   2.57 ms/img   388 img/s   3.8x
+    batch 16   2.05 ms/img   487 img/s   4.7x
+
+Requests arriving within a few milliseconds of each other are therefore worth holding
+briefly so they can ride one forward pass. The wait is bounded and small: under load the
+batch fills before the timer, and when traffic is thin a request waits at most
+`max_wait` and still beats the un-batched path on throughput while losing only that.
+
+Thread-based on purpose - the server's handlers are sync and uvicorn runs them in its
+threadpool, so this batches whatever that pool is holding without making anything async.
+"""
+from __future__ import annotations
+
+import threading
+import time
+
+__all__ = ["Batcher"]
+
+
+class Batcher:
+    """Collect concurrent calls into one call of `fn(list) -> list`."""
+
+    def __init__(self, fn, max_batch: int = 16, max_wait: float = 0.006,
+                 name: str = "batch"):
+        self.fn = fn
+        self.max_batch = max_batch
+        self.max_wait = max_wait
+        self.name = name
+        self._q = []                       # [(item, slot)]
+        self._ema = 1.0                    # recent batch size; drives the adaptive wait
+        self._lock = threading.Lock()
+        self._wake = threading.Condition(self._lock)
+        self._worker = None
+        self.stats = {"calls": 0, "batches": 0, "items": 0, "max_seen": 0}
+
+    def _ensure_worker(self):
+        # started lazily so importing this module never spawns a thread, and so a
+        # forked uvicorn worker gets its own rather than inheriting a dead one
+        if self._worker is None or not self._worker.is_alive():
+            self._worker = threading.Thread(target=self._run, daemon=True,
+                                            name=f"batcher-{self.name}")
+            self._worker.start()
+
+    def submit(self, item):
+        """Queue one item and block until its result is ready. Raises what fn raised."""
+        slot = {"event": threading.Event(), "out": None, "err": None}
+        self.stats["calls"] += 1
+        with self._wake:
+            self._q.append((item, slot))
+            self._ensure_worker()
+            self._wake.notify()
+        slot["event"].wait()
+        if slot["err"] is not None:
+            raise slot["err"]
+        return slot["out"]
+
+    def _drain(self):
+        """Wait for work, then let a batch accumulate for at most max_wait.
+
+        The wait is ADAPTIVE. Holding a request for 6ms only pays if someone else
+        arrives inside that window; on an idle service nobody does, and every request
+        pays the delay for nothing - measured as p50 13ms -> 20ms at concurrency 1.
+        So the recent batch size decides: while traffic is thin the batch goes straight
+        through, and the wait switches on only once batches are actually forming.
+        """
+        with self._wake:
+            while not self._q:
+                self._wake.wait(0.5)
+                if not self._q:
+                    return []
+            wait = self.max_wait if self._ema >= 1.5 else 0.0
+            if wait:
+                deadline = time.monotonic() + wait
+                while len(self._q) < self.max_batch:
+                    left = deadline - time.monotonic()
+                    if left <= 0:
+                        break
+                    self._wake.wait(left)
+            batch, self._q = self._q[:self.max_batch], self._q[self.max_batch:]
+            # a queue that refilled while we worked is itself evidence of load, so count
+            # the backlog too - otherwise the EMA can never climb out of "thin"
+            self._ema = 0.7 * self._ema + 0.3 * (len(batch) + min(len(self._q), 4))
+            return batch
+
+    def _run(self):
+        while True:
+            batch = self._drain()
+            if not batch:
+                continue
+            items = [b[0] for b in batch]
+            try:
+                out = self.fn(items)
+                if len(out) != len(items):
+                    raise RuntimeError(f"batched fn returned {len(out)} for {len(items)}")
+                for (_, slot), o in zip(batch, out):
+                    slot["out"] = o
+            except BaseException as e:      # one bad batch must not kill the worker
+                # Nor may it fail its neighbours. Batching is an internal throughput
+                # trick, so one caller's undecodable image must not answer seven other
+                # callers with an error about a file they never sent. Re-run the batch
+                # one item at a time and route each result - or each failure - to the
+                # caller it belongs to. Only on the error path, so it costs nothing
+                # when nothing is wrong.
+                for item, slot in batch:
+                    if len(batch) == 1:
+                        slot["err"] = e
+                        continue
+                    try:
+                        out = self.fn([item])
+                        if len(out) != 1:
+                            raise RuntimeError(f"batched fn returned {len(out)} for 1")
+                        slot["out"] = out[0]
+                    except BaseException as e2:
+                        slot["err"] = e2
+            finally:
+                self.stats["batches"] += 1
+                self.stats["items"] += len(batch)
+                self.stats["max_seen"] = max(self.stats["max_seen"], len(batch))
+                for _, slot in batch:
+                    slot["event"].set()
+
+
+def demo() -> None:
+    """python3 batcher.py - proves batching, ordering, errors and the wait bound."""
+    seen = []
+
+    def fn(xs):
+        seen.append(len(xs))
+        time.sleep(0.005)
+        return [x * 2 for x in xs]
+
+    b = Batcher(fn, max_batch=8, max_wait=0.02)
+
+    # concurrent callers share a pass, and each gets ITS OWN answer back
+    out = {}
+    def call(i):
+        out[i] = b.submit(i)
+    ts = [threading.Thread(target=call, args=(i,)) for i in range(8)]
+    for t in ts:
+        t.start()
+    for t in ts:
+        t.join()
+    assert out == {i: i * 2 for i in range(8)}, out
+    assert max(seen) > 1, f"nothing batched: {seen}"
+
+    # a lone caller on a quiet batcher pays no waiting penalty at all
+    quiet = Batcher(lambda xs: xs, max_batch=8, max_wait=0.050)
+    quiet.submit(1)                                   # prime the worker
+    t0 = time.perf_counter()
+    assert quiet.submit(21) == 21
+    solo = time.perf_counter() - t0
+    assert solo < 0.010, f"idle solo call waited {solo*1000:.0f}ms, should not wait"
+
+    # an exception reaches every caller in the batch, and the worker survives
+    def boom(xs):
+        raise ValueError("upstream failed")
+    b2 = Batcher(boom, max_batch=4, max_wait=0.01)
+    errs = []
+    def call2(i):
+        try:
+            b2.submit(i)
+        except ValueError as e:
+            errs.append(str(e))
+    ts = [threading.Thread(target=call2, args=(i,)) for i in range(4)]
+    for t in ts:
+        t.start()
+    for t in ts:
+        t.join()
+    assert len(errs) == 4 and all("upstream failed" in e for e in errs), errs
+
+    # ONE bad item must not fail the callers who rode the same pass. This is the whole
+    # point: on a server, one truncated upload used to error every concurrent request.
+    def picky(xs):
+        if any(x == "bad" for x in xs):
+            raise ValueError("cannot decode 'bad'")
+        return [x * 2 for x in xs]
+    b4 = Batcher(picky, max_batch=8, max_wait=0.02)
+    got = {}
+    def call4(i, x):
+        try:
+            got[i] = b4.submit(x)
+        except ValueError as e:
+            got[i] = f"ERR {e}"
+    ts = [threading.Thread(target=call4, args=(i, i)) for i in range(7)]
+    ts.append(threading.Thread(target=call4, args=(7, "bad")))
+    for t in ts:
+        t.start()
+    for t in ts:
+        t.join()
+    assert got[7] == "ERR cannot decode 'bad'", got[7]
+    assert all(got[i] == i * 2 for i in range(7)), got
+
+    # a wrong-length return is an error, not silent misrouting of answers
+    b3 = Batcher(lambda xs: xs[:-1], max_batch=4, max_wait=0.01)   # always short by one
+    try:
+        b3.submit(1)
+        raise AssertionError("short return was not caught")
+    except RuntimeError:
+        pass
+
+    print(f"batcher selftest ok - batches {seen}, solo wait {solo*1000:.0f}ms")
+
+
+if __name__ == "__main__":
+    demo()