jevify 0.1.0__py3-none-any.whl

jevify/__init__.py

@@ -0,0 +1,7 @@
+"""jevify: make a pretrained model answer typed questions in one pass, and measure it."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

jevify/__main__.py

@@ -0,0 +1,9 @@
+"""`python -m jevify` runs the same entry point as the `jevify` console script."""
+
+from __future__ import annotations
+
+import sys
+
+from jevify.cli import main
+
+sys.exit(main())

jevify/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters implement the ports. Only jevify.compose imports them."""

jevify/adapters/embedding/__init__.py

@@ -0,0 +1 @@
+"""The embedding kind: cosine pertinence over an endpoint or an in-process model."""

jevify/adapters/embedding/adapter.py

@@ -0,0 +1,203 @@
+"""EmbeddingBackend: the backend port over an embedding model (ADR-0002 D2, embedding kind).
+
+The state (with the question's instructions, for an instruction-tuned model) becomes one
+query vector; each option becomes one document vector; the answer is the cosine between
+them. Cosines are independent similarities, so the answer is labeled `similarity`; the
+engine's softmax over cosine times the recipe's scale is a ranking convenience, never a
+probability. Only choice questions are answerable: a noul or score question has no menu of
+texts to compare against.
+
+The embedder behind the backend is a narrow inner seam (`Embedder`): one implementation
+posts to an OpenAI-compatible `/v1/embeddings` route, the other runs a model in-process
+behind the `encoder` extra. Both cache option vectors, because a menu repeats across states
+far more often than a state repeats across menus.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import math
+import time
+from collections import OrderedDict
+from collections.abc import Callable, Sequence
+from typing import Protocol
+
+from jevify.adapters.endpoint.client import OpenAICompatibleClient
+from jevify.domain.questions import ChoiceQuestion, Question, State
+from jevify.ports.backend import (
+    BackendError,
+    Capabilities,
+    Dialect,
+    RawAnswer,
+    Rung,
+    StateHandle,
+)
+from jevify.recipes.render import RenderedPrefix
+from jevify.recipes.schema import EmbeddingSpec, Recipe
+
+Clock = Callable[[], float]
+Vector = list[float]
+
+
+def cosine(a: Sequence[float], b: Sequence[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b, strict=True))
+    norm = math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b))
+    return dot / norm if norm else 0.0
+
+
+def _fill(template: str, **fields: str) -> str:
+    for name, value in fields.items():
+        template = template.replace("{" + name + "}", value)
+    return template
+
+
+class Embedder(Protocol):
+    """One batch of texts in, one vector per text out, in order."""
+
+    async def embed(self, texts: Sequence[str]) -> list[Vector]: ...
+
+    def describe(self) -> dict[str, str | None]: ...
+
+
+class EndpointEmbedder:
+    def __init__(self, client: OpenAICompatibleClient, recipe: Recipe) -> None:
+        assert recipe.embedding is not None and recipe.endpoint is not None
+        self.client = client
+        self.recipe = recipe
+        self.path = recipe.embedding.path
+
+    async def embed(self, texts: Sequence[str]) -> list[Vector]:
+        body = {
+            "model": self.recipe.model.name,
+            "input": texts[0] if len(texts) == 1 else list(texts),
+        }
+        response = await self.client.post_v1(self.path, body)
+        data = sorted(response.get("data") or [], key=lambda item: item.get("index", 0))
+        vectors = [list(map(float, item["embedding"])) for item in data]
+        if len(vectors) != len(texts):
+            raise BackendError(
+                f"embedding endpoint returned {len(vectors)} vectors for {len(texts)} inputs"
+            )
+        return vectors
+
+    def describe(self) -> dict[str, str | None]:
+        assert self.recipe.endpoint is not None
+        dialect = self.recipe.endpoint.dialect
+        return {"transport": "endpoint", "dialect": None if dialect == "auto" else dialect}
+
+
+class _Lru:
+    def __init__(self, capacity: int) -> None:
+        self.capacity = capacity
+        self.items: OrderedDict[str, Vector] = OrderedDict()
+
+    def get(self, key: str) -> Vector | None:
+        if key in self.items:
+            self.items.move_to_end(key)
+            return self.items[key]
+        return None
+
+    def put(self, key: str, value: Vector) -> None:
+        self.items[key] = value
+        self.items.move_to_end(key)
+        while len(self.items) > self.capacity:
+            self.items.popitem(last=False)
+
+
+class EmbeddingBackend:
+    def __init__(
+        self, embedder: Embedder, recipe: Recipe, *, clock: Clock = time.perf_counter
+    ) -> None:
+        if recipe.embedding is None:
+            raise BackendError("an embedding backend needs an embedding section")
+        self.embedder = embedder
+        self.recipe = recipe
+        self.spec: EmbeddingSpec = recipe.embedding
+        self.clock = clock
+        self.queries = _Lru(64)
+        self.options = _Lru(4096)
+
+    async def probe(self) -> Capabilities:
+        try:
+            [vector] = await self.embedder.embed(["probe"])
+        except BackendError as exc:
+            raise BackendError(f"embedding model did not answer the probe: {exc}") from exc
+        described = self.embedder.describe()
+        dialect = described.get("dialect")
+        return Capabilities(
+            kind="embedding",
+            model=self.recipe.model.name,
+            dialect=Dialect(dialect) if dialect else None,
+            modalities=frozenset({"text"}),
+            rungs=frozenset(),
+            token_ids_verified=False,
+            probed_at=dt.datetime.now(dt.UTC).isoformat(timespec="seconds"),
+            notes=(
+                f"embedding dimension {len(vector)}",
+                f"transport {described.get('transport')}",
+                "choice questions only; cosine similarity, labeled similarity",
+            ),
+        )
+
+    async def warm(self, state: State) -> StateHandle:
+        if state.modalities - {"text"}:
+            raise BackendError(
+                "the embedding kind compares text only; the state carries image parts"
+            )
+        prefix = RenderedPrefix(mode="embedding", text=state.text)
+        state_id = hashlib.sha256(state.text.encode("utf-8")).hexdigest()
+        return StateHandle(state_id=state_id, prefix=prefix)
+
+    async def evaluate(self, handle: StateHandle, questions: Sequence[Question]) -> list[RawAnswer]:
+        return [await self._answer(handle, q) for q in questions]
+
+    def _option_texts(self, question: ChoiceQuestion) -> list[str]:
+        return [
+            _fill(
+                self.spec.option,
+                key=option.key,
+                description=(self.spec.description_sep + option.description)
+                if option.description
+                else "",
+                text=option.description or option.key,
+            )
+            for option in question.options
+        ]
+
+    async def _answer(self, handle: StateHandle, question: Question) -> RawAnswer:
+        if not isinstance(question, ChoiceQuestion):
+            raise BackendError(
+                "the embedding kind answers choice questions only; a noul or score question "
+                "needs a readout-capable or rerank recipe"
+            )
+        started = self.clock()
+        calls = 0
+        query_text = _fill(
+            self.spec.query, instructions=question.instructions or "", state=handle.prefix.text
+        )
+        query = self.queries.get(query_text)
+        if query is None:
+            [query] = await self.embedder.embed([query_text])
+            self.queries.put(query_text, query)
+            calls += 1
+        texts = self._option_texts(question)
+        missing = list(dict.fromkeys(t for t in texts if self.options.get(t) is None))
+        if missing:
+            for text, vector in zip(missing, await self.embedder.embed(missing), strict=True):
+                self.options.put(text, vector)
+            calls += 1
+        cosines = {
+            label: cosine(query, self.options.get(text) or [])
+            for label, text in zip(question.labels, texts, strict=True)
+        }
+        return RawAnswer(
+            question_id=question.id,
+            logprobs={label: value * self.spec.scale for label, value in cosines.items()},
+            semantics="similarity",
+            rung=Rung.NATIVE,
+            latency_ms=(self.clock() - started) * 1000.0,
+            calls=calls,
+            composition="per_option",
+            raw={"cosine": cosines, "scale": self.spec.scale, "query_cached": calls == 0},
+        )

jevify/adapters/embedding/local.py

@@ -0,0 +1,82 @@
+"""LocalEmbedder: an in-process embedding model behind the `encoder` extra.
+
+Ported from decision-poc's `Embedding`: left padding, last-token pooling (Qwen3-Embedding's
+reference recipe) or mean pooling, float16 off CPU. torch and transformers are imported
+inside methods so that importing this module never needs the extra; a missing extra fails
+at first use with the install command named.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from jevify.ports.backend import BackendError
+from jevify.recipes.schema import LocalModelSpec
+
+_BATCH = 16
+
+
+class LocalEmbedder:
+    def __init__(self, spec: LocalModelSpec) -> None:
+        self.spec = spec
+        self._model: Any = None
+        self._tokenizer: Any = None
+        self._device: Any = None
+
+    def _load(self) -> None:
+        if self._model is not None:
+            return
+        try:
+            import torch
+            from transformers import AutoModel, AutoTokenizer
+        except ImportError as exc:  # pragma: no cover - exercised only without the extra
+            raise BackendError(
+                "the local embedding kind needs the encoder extra: "
+                "uv tool install 'jevify[encoder]' (or pip install 'jevify[encoder]')"
+            ) from exc
+        name = self.spec.device
+        if name == "auto":
+            name = (
+                "cuda"
+                if torch.cuda.is_available()
+                else ("mps" if torch.backends.mps.is_available() else "cpu")
+            )
+        self._device = torch.device(name)
+        self._tokenizer = AutoTokenizer.from_pretrained(self.spec.path, padding_side="left")
+        self._model = (
+            AutoModel.from_pretrained(
+                self.spec.path,
+                dtype=torch.float32 if self._device.type == "cpu" else torch.float16,
+            )
+            .to(self._device)
+            .eval()
+            .requires_grad_(False)
+        )
+
+    async def embed(self, texts: Sequence[str]) -> list[list[float]]:
+        self._load()
+        import torch
+
+        vectors: list[list[float]] = []
+        for start in range(0, len(texts), _BATCH):
+            batch = list(texts[start : start + _BATCH])
+            encoded = self._tokenizer(batch, padding=True, return_tensors="pt")
+            if encoded.input_ids.shape[1] > self.spec.max_tokens:
+                raise BackendError(
+                    f"input exceeds the recipe's local.max_tokens={self.spec.max_tokens} "
+                    f"({encoded.input_ids.shape[1]} tokens)"
+                )
+            encoded = encoded.to(self._device)
+            with torch.no_grad():
+                hidden = self._model(**encoded, use_cache=False).last_hidden_state.float()
+            if self.spec.pooling == "last":
+                pooled = hidden[:, -1]  # left padding puts every last real token at -1
+            else:
+                mask = encoded.attention_mask.unsqueeze(-1).float()
+                pooled = (hidden * mask).sum(1) / mask.sum(1).clamp(min=1.0)
+            vectors.extend(pooled.cpu().tolist())
+        return vectors
+
+    def describe(self) -> dict[str, str | None]:
+        return {"transport": "local", "dialect": None}

jevify/adapters/encoder/__init__.py

@@ -0,0 +1 @@
+"""The encoder kind: an in-process sequence-classification head read at each option."""

jevify/adapters/encoder/adapter.py

@@ -0,0 +1,165 @@
+"""EncoderBackend: the backend port over an in-process encoder classifier (ADR-0002 D2,
+encoder kind).
+
+The `nli` layout: the state is the premise; each option, level or statement is a
+hypothesis; the head's entailment and contradiction logits at each pair are the readout.
+A choice or score answer carries, per label, the entailment-minus-contradiction logit (the
+engine's softmax across labels ranks them, the same per-option composition the endpoint
+kind uses for a yes/no reranker); a noul answer is the two-way distribution at the one
+pair. The scores are the head's own outputs at the answer position, so the label is
+`readout`. One forward pass scores every pair of a question.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import math
+import time
+from collections.abc import Callable, Sequence
+from typing import Protocol
+
+from jevify.domain.questions import (
+    ChoiceQuestion,
+    NoulQuestion,
+    Question,
+    ScoreQuestion,
+    State,
+)
+from jevify.ports.backend import BackendError, Capabilities, RawAnswer, Rung, StateHandle
+from jevify.recipes.render import RenderedPrefix
+from jevify.recipes.schema import EncoderSpec, Recipe
+
+Clock = Callable[[], float]
+Pair = tuple[str, str]
+
+
+def _fill(template: str, **fields: str) -> str:
+    for name, value in fields.items():
+        template = template.replace("{" + name + "}", value)
+    return template
+
+
+class Scorer(Protocol):
+    """Premise/hypothesis pairs in, the head's logits by lower-cased label name out."""
+
+    async def score(self, pairs: Sequence[Pair]) -> list[dict[str, float]]: ...
+
+    def describe(self) -> dict[str, str | None]: ...
+
+
+class EncoderBackend:
+    def __init__(self, scorer: Scorer, recipe: Recipe, *, clock: Clock = time.perf_counter) -> None:
+        if recipe.encoder is None:
+            raise BackendError("an encoder backend needs an encoder section")
+        self.scorer = scorer
+        self.recipe = recipe
+        self.spec: EncoderSpec = recipe.encoder
+        self.clock = clock
+
+    async def probe(self) -> Capabilities:
+        try:
+            [logits] = await self.scorer.score([("probe", "probe")])
+        except BackendError as exc:
+            raise BackendError(f"encoder model did not answer the probe: {exc}") from exc
+        wanted = {self.spec.entailment_label.lower(), self.spec.contradiction_label.lower()}
+        if not wanted <= set(logits):
+            raise BackendError(
+                f"the head's labels {sorted(logits)} lack the recipe's "
+                f"{sorted(wanted)}; set encoder.entailment_label and encoder.contradiction_label"
+            )
+        described = self.scorer.describe()
+        return Capabilities(
+            kind="encoder",
+            model=self.recipe.model.name,
+            dialect=None,
+            modalities=frozenset({"text"}),
+            rungs=frozenset({Rung.NATIVE}),
+            token_ids_verified=False,
+            probed_at=dt.datetime.now(dt.UTC).isoformat(timespec="seconds"),
+            notes=(
+                f"layout {self.spec.layout}; head labels {', '.join(sorted(logits))}",
+                f"transport {described.get('transport')}",
+                "text only; one forward pass per question",
+            ),
+        )
+
+    async def warm(self, state: State) -> StateHandle:
+        if state.modalities - {"text"}:
+            raise BackendError("the encoder kind reads text only; the state carries image parts")
+        premise = _fill(self.spec.premise, state=state.text)
+        prefix = RenderedPrefix(mode="encoder", text=premise)
+        return StateHandle(
+            state_id=hashlib.sha256(premise.encode("utf-8")).hexdigest(), prefix=prefix
+        )
+
+    async def evaluate(self, handle: StateHandle, questions: Sequence[Question]) -> list[RawAnswer]:
+        return [await self._answer(handle, q) for q in questions]
+
+    def _hypotheses(self, question: Question) -> list[str]:
+        instructions = question.instructions or ""
+        if isinstance(question, ChoiceQuestion):
+            return [
+                _fill(
+                    self.spec.hypothesis,
+                    instructions=instructions,
+                    key=option.key,
+                    description=(self.spec.description_sep + option.description)
+                    if option.description
+                    else "",
+                    text=option.description or option.key,
+                )
+                for option in question.options
+            ]
+        if isinstance(question, ScoreQuestion):
+            return [
+                _fill(
+                    self.spec.hypothesis,
+                    instructions=instructions,
+                    key=level,
+                    description="",
+                    text=level,
+                )
+                for level in question.levels
+            ]
+        assert isinstance(question, NoulQuestion)
+        return [_fill(self.spec.noul_hypothesis, instructions=instructions)]
+
+    async def _answer(self, handle: StateHandle, question: Question) -> RawAnswer:
+        hypotheses = self._hypotheses(question)
+        started = self.clock()
+        scored = await self.scorer.score([(handle.prefix.text, h) for h in hypotheses])
+        latency_ms = (self.clock() - started) * 1000.0
+        entail, contra = self.spec.entailment_label.lower(), self.spec.contradiction_label.lower()
+        gaps = []
+        for logits in scored:
+            if entail not in logits or contra not in logits:
+                raise BackendError(
+                    f"the head returned labels {sorted(logits)}, not {entail!r}/{contra!r}"
+                )
+            gaps.append(logits[entail] - logits[contra])
+        if isinstance(question, NoulQuestion):
+            [gap] = gaps
+            p_true = 1.0 / (1.0 + math.exp(-gap))
+            logprobs = {
+                "false": math.log(max(1.0 - p_true, 1e-12)),
+                "true": math.log(max(p_true, 1e-12)),
+            }
+            keys: tuple[str, ...] = ("true",)
+        else:
+            keys = question.labels
+            logprobs = dict(zip(keys, gaps, strict=True))
+        return RawAnswer(
+            question_id=question.id,
+            logprobs=logprobs,
+            semantics="readout",
+            rung=Rung.NATIVE,
+            latency_ms=latency_ms,
+            calls=1,
+            composition="per_option",
+            raw={
+                "layout": self.spec.layout,
+                "hypotheses": dict(zip(keys, hypotheses, strict=True)),
+                "logits": dict(zip(keys, scored, strict=True)),
+            },
+        )

jevify/adapters/encoder/local.py

@@ -0,0 +1,77 @@
+"""NliScorer: a sequence-classification head run in-process behind the `encoder` extra.
+
+torch and transformers are imported inside methods so that importing this module never
+needs the extra; a missing extra fails at first use with the install command named.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from jevify.ports.backend import BackendError
+from jevify.recipes.schema import LocalModelSpec
+
+_BATCH = 16
+
+
+class NliScorer:
+    def __init__(self, spec: LocalModelSpec) -> None:
+        self.spec = spec
+        self._model: Any = None
+        self._tokenizer: Any = None
+        self._device: Any = None
+        self._labels: list[str] = []
+
+    def _load(self) -> None:
+        if self._model is not None:
+            return
+        try:
+            import torch
+            from transformers import AutoModelForSequenceClassification, AutoTokenizer
+        except ImportError as exc:  # pragma: no cover - exercised only without the extra
+            raise BackendError(
+                "the encoder kind needs the encoder extra: "
+                "uv tool install 'jevify[encoder]' (or pip install 'jevify[encoder]')"
+            ) from exc
+        name = self.spec.device
+        if name == "auto":
+            name = (
+                "cuda"
+                if torch.cuda.is_available()
+                else ("mps" if torch.backends.mps.is_available() else "cpu")
+            )
+        self._device = torch.device(name)
+        self._tokenizer = AutoTokenizer.from_pretrained(self.spec.path)
+        self._model = (
+            AutoModelForSequenceClassification.from_pretrained(self.spec.path)
+            .to(self._device)
+            .eval()
+            .requires_grad_(False)
+        )
+        id2label = self._model.config.id2label
+        self._labels = [str(id2label[i]).lower() for i in range(len(id2label))]
+
+    async def score(self, pairs: Sequence[tuple[str, str]]) -> list[dict[str, float]]:
+        self._load()
+        import torch
+
+        out: list[dict[str, float]] = []
+        for start in range(0, len(pairs), _BATCH):
+            batch = list(pairs[start : start + _BATCH])
+            encoded = self._tokenizer(
+                [p for p, _ in batch], [h for _, h in batch], padding=True, return_tensors="pt"
+            )
+            if encoded.input_ids.shape[1] > self.spec.max_tokens:
+                raise BackendError(
+                    f"input exceeds the recipe's local.max_tokens={self.spec.max_tokens} "
+                    f"({encoded.input_ids.shape[1]} tokens)"
+                )
+            with torch.no_grad():
+                logits = self._model(**encoded.to(self._device)).logits.float().cpu()
+            for row in logits.tolist():
+                out.append(dict(zip(self._labels, row, strict=True)))
+        return out
+
+    def describe(self) -> dict[str, str | None]:
+        return {"transport": "local", "dialect": None}

jevify/adapters/endpoint/__init__.py

@@ -0,0 +1 @@
+"""The endpoint adapter: any OpenAI-compatible server, with dialect extras detected by the probe."""