pyprocessors-jev 1.6.1__py3-none-any.whl

pyprocessors_jev/__init__.py

@@ -0,0 +1,3 @@
+"""Processor based on the Jev System One API"""
+
+__version__ = "1.6.1"

pyprocessors_jev/client.py

@@ -0,0 +1,68 @@
+"""Minimal HTTP client for the Jev `System One` API.
+
+The wire protocol is the same for the hosted TypeSafe service and for a
+self-hosted Open-Jev server: `POST {base_url}/v1/systemone` with
+`{"model", "state", "questions"}`, answering `{"model", "answers", "usage"}`.
+Only the base url, the model route and the presence of a bearer token differ,
+so one client serves both and the two processors only carry their defaults.
+
+The official `typesafe_sdk` is deliberately not used: it cannot talk to an
+Open-Jev server, which would mean two code paths for one protocol.
+"""
+
+import random
+import time
+
+import requests
+from log_with_context import Logger
+
+logger = Logger("pymultirole")
+
+# 429 and 529 are the documented back-pressure codes of the hosted API; the 5xx
+# family covers a self-hosted server restarting behind a proxy.
+RETRY_STATUS = frozenset({429, 500, 502, 503, 504, 529})
+
+
+class JevError(RuntimeError):
+    """A Jev call that no retry can fix (bad key, invalid questions, ...)."""
+
+
+class JevClient:
+    def __init__(self, base_url: str, api_key: str | None = None, timeout: float = 60.0, max_retries: int = 3):
+        self.url = base_url.rstrip("/") + "/v1/systemone"
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = requests.Session()
+
+    def system_one(self, model: str, state, questions: dict) -> dict:
+        """Ask every question in ONE call: the API answers them independently and
+        the server reuses the prefix computed from `state`, so splitting the
+        questions into several calls only multiplies latency and input tokens."""
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        payload = {"model": model, "state": state, "questions": questions}
+
+        for attempt in range(self.max_retries + 1):
+            response = self.session.post(self.url, json=payload, headers=headers, timeout=self.timeout)
+            if response.status_code in RETRY_STATUS and attempt < self.max_retries:
+                time.sleep(backoff_delay(attempt, response.headers.get("Retry-After")))
+                continue
+            if response.status_code >= 400:
+                # 401 (key), 422 (questions) and anything left after the retries: the
+                # body carries the only actionable detail, so it goes in the message.
+                raise JevError(f"Jev returned {response.status_code} for {self.url}: {response.text[:512]}")
+            return response.json()
+        raise JevError(f"Jev still unavailable after {self.max_retries} retries: {self.url}")  # pragma: no cover
+
+
+def backoff_delay(attempt: int, retry_after: str | None = None) -> float:
+    """Exponential backoff, jittered, but obeying `Retry-After` when the server
+    sent one — a server that names its own delay knows better than we do."""
+    if retry_after:
+        try:
+            return min(float(retry_after), 60.0)
+        except ValueError:
+            logger.warning(f"Ignoring unparseable Retry-After {retry_after!r}")
+    return min(2.0**attempt, 30.0) * (0.5 + random.random() / 2)  # noqa: S311

pyprocessors_jev/jev.py

@@ -0,0 +1,454 @@
+"""Processor calling the Jev `System One` API.
+
+Jev answers typed questions with calibrated probabilities instead of text, so
+this processor never parses a completion: each question declares where its
+answer goes (`categories`, `metadata`, `annotations`, `altTexts`) and the
+answer is written there. Since the API answers many questions in one call,
+classifying and enriching the metadata of a document costs one HTTP request —
+there is no need for the `--- METADATA ---` add-on section that the text
+completion processor has to split off.
+
+What Jev cannot do bounds what this processor offers: it *chooses* and *rates*,
+it does not write. There is no free-form extraction (use the completion
+processor for that), no new annotation span (no offsets come back), and no
+generated altText — only a selection among texts already on the document.
+"""
+
+import json
+import os
+from enum import StrEnum
+from functools import cache
+from typing import Any, cast
+
+from log_with_context import Logger, add_logging_context
+from pydantic import BaseModel, Field
+from pymultirole_plugins.v1.processor import ProcessorBase, ProcessorParameters
+from pymultirole_plugins.v1.schema import AltText, Category, Document
+
+from .client import JevClient
+
+logger = Logger("pymultirole")
+
+# Stands for the project label set inside a `criteria` of the `questions` map, so
+# that the labels injected by Sherpa do not have to be copied by hand.
+LABELS_PLACEHOLDER = "$labels"
+
+
+class JevTarget(StrEnum):
+    categories = "categories"
+    metadata = "metadata"
+    annotations = "annotations"
+    altTexts = "altTexts"
+
+
+class JevFunction(StrEnum):
+    add_categories = "add_categories"
+    add_multilabel_categories = "add_multilabel_categories"
+    filter_annotations = "filter_annotations"
+    select_altText = "select_altText"
+
+
+class JevParametersBase(ProcessorParameters):
+    base_url: str = Field(None, description="""Jev endpoint base url""", json_schema_extra={"extra": "advanced"})
+    model: str = Field(None, description="""Which Jev model route to use""", json_schema_extra={"extra": "advanced"})
+    function: JevFunction = Field(
+        JevFunction.add_categories,
+        description="""The question to ask, built from `labels`. Ignored as soon as `questions` is
+                        defined. Options currently available:</br>
+                        <li>`add_categories` - one `choice` question over `labels`: every label
+                        scoring above `threshold` becomes a document category, carrying its
+                        probability as score.
+                        <li>`add_multilabel_categories` - one `noul` (yes/no) question per label,
+                        all in the same call: each label above `threshold` becomes a category. Use
+                        this rather than `add_categories` when several labels can hold at once, as
+                        the probabilities of a `choice` are exclusive and sum to 1.
+                        <li>`filter_annotations` - one `noul` question per existing annotation,
+                        keeping those judged correct. The offsets are those of the candidates, so
+                        nothing has to be re-aligned on the text.
+                        <li>`select_altText` - one `choice` question over the alternative texts of
+                        the document (a rerank / judge), the winner being copied to the altText
+                        named by `selected_altText`.""",
+    )
+    instructions: str = Field(
+        "Choose the best category for this text.",
+        description="""Instructions of the question built from `function`""",
+        json_schema_extra={"extra": "multiline"},
+    )
+    labels: dict[str, str] = Field(
+        None,
+        description="""The list of possible labels, as a label name to description mapping. The
+                        description is what Jev reads, the label name is what comes back.""",
+        json_schema_extra={"extra": "advanced,key:label,inject"},
+    )
+    questions: dict[str, str] = Field(
+        None,
+        description="""Questions to ask, by key, in JSON — the general case, which takes precedence
+                        over `function`. Each question carries its Jev `type` (`choice`, `noul` or
+                        `score`), its `instructions`, its `criteria` and the `target` its answer is
+                        written to (`categories`, `metadata` or `altTexts`; `annotations` is only
+                        reachable through the `filter_annotations` function, which needs one
+                        question per span). A `criteria` of `$labels` is replaced by the project
+                        label set. For example:<br/>
+    ```
+    {
+      "topic":      {"target": "categories", "type": "choice", "criteria": "$labels",
+                     "instructions": "What is this document about?"},
+      "is_opinion": {"target": "metadata", "type": "noul",
+                     "instructions": "Is this an editorial?"},
+      "urgency":    {"target": "metadata", "type": "score",
+                     "criteria": ["low", "medium", "high"],
+                     "instructions": "How urgent is it?"}
+    }
+    ```""",
+        json_schema_extra={"extra": "advanced,key:label,val:json"},
+    )
+    state_altText: str = Field(
+        None,
+        description="""<li>If defined: send the alternative text of that name as the state,
+                        <li>if not: send the text of the document.""",
+        json_schema_extra={"extra": "advanced"},
+    )
+    decision_altText: str = Field(
+        None,
+        description="""<li>If defined: keep the questions, the answers and the token usage as an
+                        alternative text of that name — the audit trail of the decision.""",
+        json_schema_extra={"extra": "advanced"},
+    )
+    selected_altText: str = Field(
+        "selected",
+        description="""Name of the alternative text receiving the winner of `select_altText`""",
+        json_schema_extra={"extra": "advanced"},
+    )
+    threshold: float = Field(
+        0.5,
+        description="""Only answers with a probability greater than threshold are kept.
+                        Lowering it below the winner-takes-all point turns a `choice` into a
+                        multilabel decision: every label above the bar becomes a category,
+                        sorted by decreasing probability.""",
+        json_schema_extra={"extra": "advanced"},
+    )
+    keep_best: bool = Field(
+        False,
+        description="""<li>If true: when no answer of a `choice` question reaches `threshold`,
+                        keep the most probable one anyway, so the document never comes back
+                        without a category. <li>Harmless with few labels — with 3 of them the
+                        winner is mechanically above 1/3 — but a large label set can leave every
+                        probability under the bar.""",
+        json_schema_extra={"extra": "advanced"},
+    )
+    max_chars: int = Field(
+        0,
+        description="""Truncate the state to that many characters, 0 to send it whole""",
+        json_schema_extra={"extra": "advanced"},
+    )
+    timeout: float = Field(60.0, description="""Timeout in seconds""", json_schema_extra={"extra": "advanced"})
+    max_retries: int = Field(
+        3,
+        description="""How many times a throttled (429) or overloaded (529) call is retried,
+                        with an exponential backoff""",
+        json_schema_extra={"extra": "advanced"},
+    )
+
+
+class JevParameters(JevParametersBase):
+    base_url: str | None = Field(
+        os.getenv("JEV_API_BASE", os.getenv("TYPESAFE_BASE_URL", "https://api.typesafe.ai")),
+        description="""Jev endpoint base url""",
+        json_schema_extra={"extra": "advanced"},
+    )
+    model: str | None = Field(
+        os.getenv("JEV_MODEL", os.getenv("TYPESAFE_DEFAULT_MODEL", "jev-latest")),
+        description="""Which Jev model route to use""",
+        json_schema_extra={"extra": "advanced"},
+    )
+
+
+class OpenJevParameters(JevParametersBase):
+    base_url: str | None = Field(
+        os.getenv("OPENJEV_API_BASE", "http://127.0.0.1:8791"),
+        description="""Open-Jev endpoint base url""",
+        json_schema_extra={"extra": "advanced"},
+    )
+    model: str | None = Field(
+        os.getenv("OPENJEV_MODEL", "open-jev"),
+        description="""Which Open-Jev model route to use""",
+        json_schema_extra={"extra": "advanced"},
+    )
+
+
+class JevProcessorBase(ProcessorBase):
+    __doc__ = """Ask [Jev](https://typesafe.ai) typed questions about a document and write the
+    answers as categories, metadata, annotations or alternative texts."""
+
+    # Where the api key is read. Empty for the hosted service (`JEV_API_KEY`), `OPEN`
+    # for a self-hosted server (`OPENJEV_API_KEY`), which usually has none.
+    PREFIX: str = ""
+    API_KEY_ENVS: tuple[str, ...] = ()
+
+    def process(self, documents: list[Document], parameters: ProcessorParameters) -> list[Document]:
+        params: JevParametersBase = cast(JevParametersBase, parameters)
+        client = get_client(params.base_url, self.api_key(), params.timeout, params.max_retries)
+
+        for document in documents:
+            with add_logging_context(docid=document.identifier):
+                plan = build_plan(document, params)
+                if not plan:
+                    logger.warning("No question to ask, document left untouched")
+                    continue
+                payload = {qid: item["question"] for qid, item in plan.items()}
+                result = client.system_one(params.model, get_state(document, params), payload)
+                answers = result.get("answers") or {}
+                apply_answers(document, params, plan, answers)
+                if params.decision_altText:
+                    add_decision_altText(document, params, payload, result)
+        return documents
+
+    def api_key(self) -> str | None:
+        for name in (self.PREFIX + "JEV_API_KEY", *self.API_KEY_ENVS):
+            key = os.getenv(name)
+            if key:
+                return key
+        return None
+
+    @classmethod
+    def get_model(cls) -> type[BaseModel]:
+        return JevParametersBase
+
+
+class JevProcessor(JevProcessorBase):
+    __doc__ = """Ask [TypeSafe Jev](https://typesafe.ai) typed questions about a document and write
+    the answers as categories, metadata, annotations or alternative texts."""
+
+    PREFIX = ""
+    API_KEY_ENVS = ("TYPESAFE_API_KEY",)
+
+    @classmethod
+    def get_model(cls) -> type[BaseModel]:
+        return JevParameters
+
+
+class OpenJevProcessor(JevProcessorBase):
+    __doc__ = """Ask a self-hosted [Open-Jev](https://github.com/Zefan-Cai/Open-Jev) server typed
+    questions about a document and write the answers as categories, metadata, annotations or
+    alternative texts."""
+
+    PREFIX = "OPEN"
+
+    @classmethod
+    def get_model(cls) -> type[BaseModel]:
+        return OpenJevParameters
+
+
+@cache
+def get_client(base_url: str, api_key: str | None, timeout: float, max_retries: int) -> JevClient:
+    return JevClient(base_url, api_key=api_key, timeout=timeout, max_retries=max_retries)
+
+
+def get_state(document: Document, params: JevParametersBase) -> str:
+    state = document.text
+    if params.state_altText:
+        texts = [alt.text for alt in (document.altTexts or []) if alt.name == params.state_altText]
+        if texts:
+            state = texts[0]
+        else:
+            logger.warning(f"No altText {params.state_altText!r}, falling back on the document text")
+    state = state or ""
+    return state[: params.max_chars] if params.max_chars > 0 else state
+
+
+def build_plan(document: Document, params: JevParametersBase) -> dict[str, dict[str, Any]]:
+    """Compute, per question id, the question to send, the target its answer goes
+    to and whatever context writing that answer needs. Our own keys never reach
+    the API: it validates the question schema and answers 422 on an unknown field."""
+    if params.questions:
+        return build_declared_plan(params)
+    labels = params.labels or {}
+
+    if params.function == JevFunction.add_categories:
+        if not labels:
+            return {}
+        return {
+            "category": {
+                "target": JevTarget.categories,
+                "question": {"type": "choice", "instructions": params.instructions, "criteria": dict(labels)},
+            }
+        }
+
+    if params.function == JevFunction.add_multilabel_categories:
+        return {
+            name: {
+                "target": JevTarget.categories,
+                "question": {
+                    "type": "noul",
+                    "instructions": f"{params.instructions}\n{label}",
+                    "criteria": {"true": label, "false": f"not: {label}"},
+                },
+            }
+            for name, label in labels.items()
+        }
+
+    if params.function == JevFunction.filter_annotations:
+        plan = {}
+        for i, a in enumerate(document.annotations or []):
+            label = labels.get(a.labelName) or a.label or a.labelName
+            plan[f"annotation_{i}"] = {
+                "target": JevTarget.annotations,
+                "index": i,
+                "question": {
+                    "type": "noul",
+                    "instructions": f"{params.instructions}\nIs {a.text!r} really a {label}?",
+                },
+            }
+        return plan
+
+    candidates = {alt.name: alt.text for alt in (document.altTexts or []) if alt.name not in (params.selected_altText, params.decision_altText)}
+    if len(candidates) < 2:  # a choice needs at least two candidates to mean anything
+        return {}
+    return {
+        params.selected_altText: {
+            "target": JevTarget.altTexts,
+            "candidates": candidates,
+            "question": {"type": "choice", "instructions": params.instructions, "criteria": candidates},
+        }
+    }
+
+
+def build_declared_plan(params: JevParametersBase) -> dict[str, dict[str, Any]]:
+    plan: dict[str, dict[str, Any]] = {}
+    for qid, raw in params.questions.items():
+        try:
+            question = json.loads(raw) if isinstance(raw, str) else dict(raw)
+        except ValueError as err:
+            logger.warning(f"Ignoring question {qid!r}, not valid JSON: {err}")
+            continue
+        target = question.pop("target", JevTarget.metadata)
+        if target == JevTarget.annotations:
+            logger.warning(f"Ignoring question {qid!r}: the annotations target needs the filter_annotations function")
+            continue
+        if question.get("criteria") == LABELS_PLACEHOLDER:
+            question["criteria"] = dict(params.labels or {})
+        plan[qid] = {"target": target, "question": question}
+    return plan
+
+
+def apply_answers(
+    document: Document,
+    params: JevParametersBase,
+    plan: dict[str, dict[str, Any]],
+    answers: dict[str, Any],
+) -> Document:
+    categories: list[Category] = []
+    metadata = dict(document.metadata or {})
+    rejected: set[int] = set()
+
+    for qid, item in plan.items():
+        answer = answers.get(qid)
+        if answer is None:
+            logger.warning(f"No answer for question {qid!r}")
+            continue
+        target = item["target"]
+        if target == JevTarget.categories:
+            categories.extend(categories_of(qid, answer, params))
+        elif target == JevTarget.metadata:
+            metadata.update(metadata_of(qid, answer, params))
+        elif target == JevTarget.annotations:
+            if answer.get("noul", 0.0) < params.threshold:
+                rejected.add(item["index"])
+        else:
+            select_altText(document, qid, item, answer)
+
+    if categories:
+        document.categories = categories
+    if metadata:  # never turn an absent metadata into an empty dict
+        document.metadata = metadata
+    if rejected:
+        document.annotations = [a for i, a in enumerate(document.annotations or []) if i not in rejected]
+    return document
+
+
+def categories_of(qid: str, answer: dict[str, Any], params: JevParametersBase) -> list[Category]:
+    """Only `labelName` is written, never `label`: what `labels` holds is the description
+    Jev reads to decide, often a full sentence, and it has no place in the document — the
+    project label set already carries the display name. It also means an array or string
+    `criteria`, which the API accepts, no longer has to be looked up by choice name."""
+    if answer.get("type") == "noul":
+        # One question per label: the question id IS the label name.
+        probability = answer.get("noul", 0.0)
+        if probability < params.threshold:
+            return []
+        return [Category(labelName=qid, score=probability)]
+
+    confidence = answer.get("confidence")
+    probabilities = answer.get("probabilities") or {}
+    if not probabilities and answer.get("choice"):  # a server may answer the winner only
+        probabilities = {answer["choice"]: 1.0}
+
+    classees = sorted(probabilities.items(), key=lambda kv: kv[1], reverse=True)
+    retenues = [(name, p) for name, p in classees if p >= params.threshold]
+    if not retenues and params.keep_best and classees:
+        # Nothing cleared the bar: with `keep_best` the document still gets its best
+        # answer rather than no category at all. Only meaningful for a `choice`, whose
+        # probabilities compete; a `noul` answers one label on its own above.
+        retenues = classees[:1]
+    return [
+        Category(
+            labelName=name,
+            score=probability,
+            properties={"confidence": confidence} if confidence is not None else None,
+        )
+        for name, probability in retenues
+    ]
+
+
+def metadata_of(qid: str, answer: dict[str, Any], params: JevParametersBase) -> dict[str, Any]:
+    """A `noul` gives a boolean (and keeps its probability aside), a `choice` the
+    chosen key, a `score` its probability-weighted value — never the level label,
+    which `legend` gives back if it is ever needed."""
+    kind = answer.get("type")
+    if kind == "noul":
+        probability = answer.get("noul", 0.0)
+        return {qid: probability >= params.threshold, f"{qid}_probability": probability}
+    if kind == "choice":
+        return {qid: answer.get("choice"), f"{qid}_confidence": answer.get("confidence")}
+    if kind == "score":
+        return {qid: answer.get("score"), f"{qid}_confidence": answer.get("confidence")}
+    logger.warning(f"Unknown answer type {kind!r} for question {qid!r}")
+    return {}
+
+
+def select_altText(document: Document, qid: str, item: dict[str, Any], answer: dict[str, Any]) -> None:
+    chosen = answer.get("choice")
+    candidates = item.get("candidates") or {}
+    if chosen not in candidates:
+        logger.warning(f"Ignoring unknown altText {chosen!r} chosen for question {qid!r}")
+        return
+    altTexts = [alt for alt in (document.altTexts or []) if alt.name != qid]
+    altTexts.append(
+        AltText(
+            name=qid,
+            text=candidates[chosen],
+            properties={
+                "selected": chosen,
+                "confidence": answer.get("confidence"),
+                "probabilities": answer.get("probabilities"),
+            },
+        )
+    )
+    document.altTexts = altTexts
+
+
+def add_decision_altText(
+    document: Document,
+    params: JevParametersBase,
+    payload: dict[str, Any],
+    result: dict[str, Any],
+) -> None:
+    trace = {
+        "model": result.get("model"),
+        "questions": payload,
+        "answers": result.get("answers"),
+        "usage": result.get("usage"),
+    }
+    altTexts = [alt for alt in (document.altTexts or []) if alt.name != params.decision_altText]
+    altTexts.append(AltText(name=params.decision_altText, text=json.dumps(trace, indent=2, ensure_ascii=False)))
+    document.altTexts = altTexts

pyprocessors_jev-1.6.1.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: pyprocessors-jev
+Version: 1.6.1
+Summary: Processor based on the Jev System One API
+Project-URL: Homepage, https://bitbucket.org/kairntech/pyprocessors_jev
+Author-email: Olivier Terrier <olivier.terrier@kairntech.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: log-with-context
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: pymultirole-plugins<1.7.0,>=1.6.0
+Requires-Dist: python-singleton-metaclasses
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: bump2version; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: lxml-html-clean; extra == 'docs'
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Requires-Dist: sphinxcontrib-apidoc; extra == 'docs'
+Provides-Extra: sbom
+Requires-Dist: cyclonedx-bom; extra == 'sbom'
+Requires-Dist: pip-audit; extra == 'sbom'
+Provides-Extra: test
+Requires-Dist: dirty-equals; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-dotenv; extra == 'test'
+Requires-Dist: ruff; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pyprocessors-jev
+
+Processor based on the [Jev](https://typesafe.ai) *System One* API: it asks typed questions about a
+document and gets back **calibrated probabilities** instead of text, so nothing has to be parsed out
+of a completion.
+
+Two providers, one protocol (`POST {base_url}/v1/systemone`):
+
+| entry point | provider | base url | model | api key |
+|-------------|----------|----------|-------|---------|
+| `jev` | hosted TypeSafe | `JEV_API_BASE`, else `TYPESAFE_BASE_URL`, else `https://api.typesafe.ai` | `JEV_MODEL`, else `jev-latest` | `JEV_API_KEY`, else `TYPESAFE_API_KEY` |
+| `openjev` | self-hosted [Open-Jev](https://github.com/Zefan-Cai/Open-Jev) | `OPENJEV_API_BASE`, else `http://127.0.0.1:8791` | `OPENJEV_MODEL`, else `open-jev` | `OPENJEV_API_KEY` (usually none) |
+
+## What it can and cannot do
+
+Jev *chooses* and *rates*; it does not write. That bounds the four outputs:
+
+| output | how | not possible |
+|--------|-----|--------------|
+| `categories` | `choice` over the project labels, or one `noul` per label | — |
+| `metadata` | typed values only: `noul` → boolean, `choice` → key of a closed set, `score` → number | free-form extraction (dates, amounts, names) — use `pyprocessors_openai_completion` |
+| `annotations` | filter existing candidate spans | create spans: no offsets come back |
+| `altTexts` | select among the texts already on the document (rerank / judge) | generate a summary or a translation |
+
+Because the API answers **many questions in one call**, classifying a document and filling its
+metadata costs one HTTP request — there is no `--- METADATA ---` section to split off.
+
+## Usage
+
+```python
+from pymultirole_plugins.v1.schema import Document
+from pyprocessors_jev.jev import JevProcessor, JevParameters
+
+processor = JevProcessor()
+parameters = JevParameters(
+    labels={"billing": "Payments, invoicing, refunds", "technical": "Bugs, outages, integrations"},
+    instructions="Which team should handle this?",
+)
+
+docs = processor.process([Document(text="Help! My payouts have been failing for 3 days.")], parameters)
+for cat in docs[0].categories:
+    print(cat.labelName, cat.score, cat.properties)
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `base_url` | provider default (see above) | Jev endpoint base url |
+| `model` | provider default (see above) | model route |
+| `function` | `add_categories` | question built from `labels`: `add_categories` (one `choice`), `add_multilabel_categories` (one `noul` per label, same call), `filter_annotations` (one `noul` per annotation, offsets preserved), `select_altText` (`choice` over the alternative texts). **Ignored as soon as `questions` is defined.** |
+| `instructions` | `Choose the best category for this text.` | instructions of the question built from `function` |
+| `labels` | – | label name → description mapping, injected from the project label set. The description is what Jev reads to decide; the categories written on the document carry **`labelName` only**, never `label` — a description has no place on the document, and the project label set already holds the display name. |
+| `questions` | – | the general case: one JSON question per key, each declaring `type`, `instructions`, `criteria` and `target` (`categories`, `metadata`, `altTexts`). A `criteria` of `$labels` is replaced by `labels`. Takes precedence over `function`. |
+| `state_altText` | – | send that alternative text as the state instead of the document text; falls back on the text with a warning when it is missing |
+| `decision_altText` | – | keep questions, answers and token usage in that alternative text — the audit trail |
+| `selected_altText` | `selected` | alternative text receiving the winner of `select_altText` |
+| `threshold` | `0.5` | probability below which an answer is dropped (a category, or an annotation kept by `filter_annotations`). Lower it below the winner-takes-all point and a `choice` becomes a multilabel decision: every label above the bar becomes a category, sorted by decreasing probability |
+| `keep_best` | `false` | when no answer of a `choice` reaches `threshold`, keep the most probable one anyway, so the document never comes back without a category. A no-op with 3 labels (the winner is mechanically above 1/3), a safety net with a large label set |
+| `max_chars` | `0` | truncate the state, `0` sends it whole |
+| `timeout` | `60.0` | HTTP timeout, in seconds |
+| `max_retries` | `3` | retries of a throttled (429) or overloaded (529) call, exponential backoff, obeying `Retry-After` |
+
+Answers land in a predictable shape: a category carries the **probability** as its `score` and the
+question `confidence` in its `properties`; a `noul` in metadata writes a boolean under the question
+id plus its probability under `<id>_probability`; a `choice` and a `score` write their value plus
+`<id>_confidence`. A question whose criteria are unknown labels, or an answer naming a label outside
+`labels`, is dropped with a warning rather than invented.
+
+The official `typesafe_sdk` is deliberately not a dependency: it cannot talk to an Open-Jev server,
+which would mean two code paths for one protocol.
+
+## Development
+
+The build is driven by [Task](https://taskfile.dev) and [uv](https://docs.astral.sh/uv/),
+with the shared stages coming from the `python-archetype` submodule.
+
+### Getting started
+
+The stages live in a Git submodule, so **clone with `--recurse-submodules`**:
+
+```bash
+git clone --recurse-submodules git@bitbucket.org:kairntech/pyprocessors_jev.git
+cd pyprocessors_jev
+sh -c "$(curl -sSL https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
+task
+```
+
+Already cloned without it? The submodule directory is empty, and `task` fails on:
+
+```
+task: No Taskfile found at ".../submodules/python-archetype/resources/Taskfile.yml"
+```
+
+which means exactly that, and nothing worse:
+
+```bash
+git submodule update --init
+```
+
+**Task is the only manual prerequisite.** An archetype cannot bootstrap itself: uv and the
+Python interpreter install themselves on demand (every task that runs uv depends on an
+internal `install-python` task), but the thing that runs them does not. Make sure
+`~/.local/bin` is on your `PATH` — that is where `task` and `uv` both land.
+
+### Running the pipeline
+
+```bash
+task stages          # print the pipeline stages, in order
+task                 # run the pipeline up to (but excluding) py:publish
+task -- --skip-tests # same, without the test stage
+task up-to -- py:lint # run the pipeline up to and including one stage
+task jenkins         # run every stage, exactly what Jenkins runs
+```
+
+`task` with no argument is safe by construction: it runs every stage but the last, and that
+bound is computed from the `STAGES` list rather than written down. The last stage is the
+only one with an effect outside your machine.
+
+`STAGES`, declared once in `Taskfile.yml`, is the single definition of the pipeline order —
+so what you run locally is what Jenkins runs.
+
+### Individual stages
+
+| Task                            | Description                                           |
+|---------------------------------|-------------------------------------------------------|
+| `task py:sync`                  | Install the project and its dependencies (uv sync)    |
+| `task py:lint`                  | `ruff check` and `ruff format --check`                |
+| `task py:format`                | Reformat the code with ruff                           |
+| `task py:test`                  | Run the test suite                                    |
+| `task py:test-marker -- <m>`    | Run the tests carrying one pytest marker              |
+| `task py:sbom`                  | Generate a CycloneDX SBOM of the resolved environment |
+| `task py:check-vulnerabilities` | Check for known CVEs                                  |
+| `task py:check-updates`         | Check for dependency updates                          |
+| `task py:build`                 | Build the wheel and sdist (uv build)                  |
+| `task py:publish`               | Publish the distributions (uv publish)                |
+| `task py:version-file`          | Print the path of the file carrying `__version__`     |
+| `task py:set-version VERSION=x` | Write that version into it                            |
+
+`uv.lock` is not versioned here, so `py:sync` always resolves from scratch (`--upgrade`):
+a stale lock lying around on a machine would otherwise make you test and audit versions the
+CI never sees.
+
+### Tests, and where the api key goes
+
+The unit tests never open a socket: the `recorder` fixture replaces `JevClient.system_one`,
+so the whole suite runs without a key and without a server. They check what the processor
+*sends* (the questions built, `$labels` substituted, one call for every label) and how it
+*reads back* the typed answers — not that Jev answers well. That last part is the job of the
+single `integration` test.
+
+Keys for that one live in `tests/.env`, which `.gitignore` keeps out of git
+(`pytest-dotenv` loads it, same convention as `pyprocessors_openai_completion`):
+
+```dotenv
+# tests/.env
+JEV_API_KEY=sk-...
+# or, for a self-hosted server:
+OPENJEV_API_BASE=http://127.0.0.1:8791
+```
+
+A key sitting there does **not** make `task py:test` hit the network: `addopts` carries
+`-m 'not integration'`, so the default run stays hermetic and the live test is asked for
+explicitly (the `-m` of the command line wins over `addopts`):
+
+```bash
+task py:test-marker -- integration
+```
+
+Without a key and without `OPENJEV_API_BASE`, that command skips instead of failing.
+
+### Measuring a real label set
+
+`tests/eval/` holds an evaluation harness for the Cairn question classifier: a frozen
+dev/holdout split over 574 manually labelled questions, five label-description variants
+with what each one scored, paired McNemar comparison, calibration and coverage curves, and
+the saved model outputs so the numbers can be rechecked without spending tokens. It is not
+part of the test suite — no file there is named `test_*`, so `task py:test` ignores it.
+See `tests/eval/README.md`.
+
+`tests/test_cairn_routing.py` pins the delivery configuration of that project — twelve real
+questions of the corpus, the probabilities the API actually answered for them, and what the
+processor must make of them at `threshold=0.25`. It runs offline, like the rest of the suite.

pyprocessors_jev-1.6.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+pyprocessors_jev/__init__.py,sha256=xCCK_V2JWJNUN8b7pnXLB-h2UqKPtI53n39HM0nPWjU,71
+pyprocessors_jev/client.py,sha256=2KAjmROCmBBWj84rIkJovtlFvtaUL97kRrrVZ6lJ_dw,3188
+pyprocessors_jev/jev.py,sha256=YvM4o9fmOgTtLQvo-Cxc0fLLtcnSGk4yWGyw0mTy_5Q,19769
+pyprocessors_jev-1.6.1.dist-info/METADATA,sha256=lm4UMAcMfYpKZ6qEhJuk87ij2lqF6aqcn9wccx9w-vM,12174
+pyprocessors_jev-1.6.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pyprocessors_jev-1.6.1.dist-info/entry_points.txt,sha256=2b5tQgFU7-m1qlB-Z5qGGtOoh9rbkrk5y0KILWWqK10,111
+pyprocessors_jev-1.6.1.dist-info/RECORD,,

pyprocessors_jev-1.6.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pyprocessors_jev-1.6.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pyprocessors.plugins]
+jev = pyprocessors_jev.jev:JevProcessor
+openjev = pyprocessors_jev.jev:OpenJevProcessor