jev2semopt 0.1.0__py3-none-any.whl

jev2semopt/__init__.py

@@ -0,0 +1,14 @@
+"""Public bounded semantic operators; importing does not register pandas accessors."""
+from llm2jev import Choice, Noul, Score
+
+from .adapters.llm2jev import LLM2JevBackend
+from .adapters.jev import JevAPIError, JevBackend
+from .contracts import BoundDecision, DecisionBackend
+from .decorators import decision
+from .engine import SemEngine
+from .execution import EvaluationError
+
+__all__ = [
+    "BoundDecision", "Choice", "DecisionBackend", "EvaluationError", "LLM2JevBackend",
+    "JevAPIError", "JevBackend", "Noul", "Score", "SemEngine", "decision",
+]

jev2semopt/adapters/__init__.py

@@ -0,0 +1 @@
+"""Provider adapters translate public decision APIs into the execution ports."""

jev2semopt/adapters/jev.py

@@ -0,0 +1,123 @@
+"""Translate the documented TypeSafe HTTP contract into borrowed typed decisions."""
+from copy import deepcopy
+from typing import Any, Dict, Optional, Protocol
+
+from llm2jev import Answer, Choice, ChoiceAnswer, JSONValue, Noul, NoulAnswer, Question, Score, ScoreAnswer, State
+
+from ..contracts import BoundDecision
+from ..execution import EvaluationError, snapshot, validate_answer
+
+
+class _Response(Protocol):
+    """The narrow HTTP response surface consumed by the official API adapter."""
+
+    status_code: int
+
+    # Decode the response without exposing its contents in adapter diagnostics.
+    def json(self) -> Any:
+        ...
+
+
+class _Client(Protocol):
+    """A caller-owned HTTP client, structurally satisfied by httpx.Client."""
+
+    # Authentication, base URL, timeouts, and connection lifetimes belong to the client.
+    def post(self, url: str, *, json: Any) -> _Response:
+        ...
+
+
+class JevAPIError(EvaluationError):
+    """Sanitized official API failure with optional HTTP status, never response bodies."""
+
+    # Retain only a numeric status useful for caller-controlled retry or authentication handling.
+    def __init__(self, message: str, *, status_code: Optional[int] = None) -> None:
+        super().__init__(message, status_code=status_code)
+
+
+# Canonical decimal rubric keys prevent collisions such as '0' and '00' during conversion.
+def _levels(value: object) -> Dict[int, Any]:
+    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
+        raise ValueError("invalid rubric map")
+    expected = {str(i) for i in range(len(value))}
+    if set(value) != expected:
+        raise ValueError("invalid rubric positions")
+    return {int(key): description for key, description in value.items()}
+
+
+# Delegate numeric invariants to the existing public domain constructors, preserving confidence.
+def _answer(payload: object, question: Question) -> Answer:
+    if not isinstance(payload, dict) or payload.get("type") != question.type:
+        raise ValueError("unexpected answer family")
+    if isinstance(question, Noul):
+        return NoulAnswer(noul=payload["noul"])
+    if isinstance(question, Choice):
+        answer = ChoiceAnswer(choice=payload["choice"], confidence=payload["confidence"],
+                              probabilities=payload["probabilities"])
+        return answer
+    if isinstance(question, Score):
+        scored = ScoreAnswer(score=payload["score"], confidence=payload["confidence"],
+                             legend=_levels(payload["legend"]), probabilities=_levels(payload["probabilities"]))
+        return scored
+    raise TypeError("unsupported question")
+
+
+class _BoundJev:
+    """An immutable rule snapshot sharing a borrowed authenticated HTTP connection pool."""
+
+    # Store a detached rule; no record state or authentication data is retained by the binding.
+    def __init__(self, client: _Client, model: str, question: Question) -> None:
+        self._client = client
+        self._model = model
+        self._question = deepcopy(question)
+
+    # Make one request per record; fail closed without retries or generated-text fallbacks.
+    def evaluate(self, *, state: State) -> Answer:
+        if not isinstance(state, (str, dict, list)):
+            raise ValueError("Jev state must be a string, object, or array")
+        detached = snapshot(state)[1]
+        try:
+            response = self._client.post("systemone", json={
+                "model": self._model, "state": detached,
+                "questions": {"decision": self._question.to_dict()},
+            })
+        except Exception:
+            raise JevAPIError("Jev request failed") from None
+        if response.status_code != 200:
+            raise JevAPIError("Jev returned an unsuccessful HTTP status", status_code=response.status_code)
+        try:
+            body = response.json()
+            if not isinstance(body, dict) or not isinstance(body.get("model"), str) or not body["model"]:
+                raise ValueError("invalid response envelope")
+            answers = body["answers"]
+            if not isinstance(answers, dict) or set(answers) != {"decision"}:
+                raise ValueError("invalid answer envelope")
+            answer = _answer(answers["decision"], self._question)
+            validate_answer(self._question, answer)
+            return answer
+        except Exception:
+            raise JevAPIError("Jev returned an invalid decision response") from None
+
+
+class JevBackend:
+    """Use the official TypeSafe API through a caller-owned HTTP client.
+
+    Configure the client's base_url as https://api.typesafe.ai/v1/ and its
+    Authorization header as Bearer <key>. This adapter never closes the client.
+    """
+
+    # Model aliases are explicit; the default follows the official documented public alias.
+    def __init__(self, client: _Client, *, model: str = "jev-latest") -> None:
+        if not isinstance(model, str) or not model.strip():
+            raise ValueError("model must be a nonempty string")
+        self._client = client
+        self._model = model
+
+    # Validate API-specific limits before any request, including on empty tables.
+    def bind(self, *, question: Question) -> BoundDecision:
+        if not isinstance(question, (Noul, Choice, Score)):
+            raise TypeError("question must be Noul, Choice, or Score")
+        if question.instructions is None or question.instructions == "":
+            raise ValueError("official Jev questions require instructions")
+        if isinstance(question, Choice) and not 2 <= len(question.criteria) <= 255:
+            raise ValueError("JevBackend supports 2 through 255 choice options")
+        return _BoundJev(self._client, self._model, question)

jev2semopt/adapters/llm2jev.py

@@ -0,0 +1,31 @@
+"""Borrow an LLM2Jev service without owning, importing, or closing model providers."""
+from llm2jev import JSONValue, Answer, BoundEvaluator, LLM2Jev, Question, State
+
+from ..contracts import BoundDecision
+
+
+class _BoundLLM2Jev:
+    """Extract a single named answer from a public LLM2Jev response."""
+
+    # The adapter owns only the binding; the caller owns runtime shutdown.
+    def __init__(self, evaluator: BoundEvaluator) -> None:
+        self._evaluator = evaluator
+
+    # Missing answers remain errors, never synthetic negative decisions.
+    def evaluate(self, *, state: State) -> Answer:
+        return self._evaluator.evaluate(state=state).answers["decision"]
+
+
+class LLM2JevBackend:
+    """Adapt an explicitly configured LLM2Jev service and model name."""
+
+    # Keep encoder, distribution policy, and device configuration on the service.
+    def __init__(self, client: LLM2Jev, *, model: str) -> None:
+        if not isinstance(model, str) or not model.strip():
+            raise ValueError("model must be a nonempty string")
+        self._client = client
+        self._model = model
+
+    # Compile reusable questions once for each relational operation or decorated function.
+    def bind(self, *, question: Question) -> BoundDecision:
+        return _BoundLLM2Jev(self._client.bind(model=self._model, questions={"decision": question}))

jev2semopt/contracts.py

@@ -0,0 +1,20 @@
+"""Typed decision ports isolate relational execution from model providers."""
+from typing import Protocol
+
+from llm2jev import JSONValue, Answer, Question, State
+
+
+class BoundDecision(Protocol):
+    """A reusable question with no ownership of the underlying model runtime."""
+
+    # Evaluate one detached state and return the answer family requested at binding.
+    def evaluate(self, *, state: State) -> Answer:
+        ...
+
+
+class DecisionBackend(Protocol):
+    """Bind questions independently of records and provider resource lifetimes."""
+
+    # Invalid rules must fail at binding, including for empty tables.
+    def bind(self, *, question: Question) -> BoundDecision:
+        ...

jev2semopt/decorators.py

@@ -0,0 +1,27 @@
+"""Decorators turn state-building functions into reusable typed decisions."""
+from functools import wraps
+from inspect import iscoroutinefunction, isgeneratorfunction, isasyncgenfunction
+from typing import Any, Callable
+
+from llm2jev import JSONValue, Answer, Question, State
+
+from .engine import SemEngine
+
+
+# Bind once at decoration time; each call evaluates fresh state without cross-call caching.
+def decision(engine: SemEngine, *, question: Question) -> Callable[[Callable[..., State]], Callable[..., Answer]]:
+    """Decorate a synchronous JSON state builder; return its typed Jev answer."""
+    session = engine._session(question)
+
+    # Preserve the state builder's metadata so debugging still identifies application intent.
+    def decorate(builder: Callable[..., State]) -> Callable[..., Answer]:
+        if not callable(builder) or iscoroutinefunction(builder) or isgeneratorfunction(builder) or isasyncgenfunction(builder):
+            raise TypeError("decision requires a synchronous JSON state builder")
+        # Builder failures belong to application code and propagate without reinterpretation.
+        @wraps(builder)
+        def evaluate(*args: Any, **kwargs: Any) -> Answer:
+            return session.run([builder(*args, **kwargs)])[0]
+
+        return evaluate
+
+    return decorate

jev2semopt/engine.py

@@ -0,0 +1,152 @@
+"""Relational operators consume typed decisions and preserve positional row identity."""
+import math
+from itertools import product
+from typing import Iterable, List, Optional, Sequence, Tuple, cast
+
+import pandas as pd
+from llm2jev import JSONValue, Choice, ChoiceAnswer, Noul, NoulAnswer, Question, Score, ScoreAnswer, State
+
+from .contracts import DecisionBackend
+from .execution import EvaluationSession
+from .table import output_column, records, validate_frame
+
+
+# A threshold is model support, not an assertion about calibrated correctness.
+def _threshold(value: float) -> None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or not 0 <= value <= 1:
+        raise ValueError("threshold must be finite and between zero and one")
+
+
+# Instructions remain reusable rules; row values are never interpolated into them.
+def _predicate(instructions: str) -> Noul:
+    if not isinstance(instructions, str) or not instructions.strip():
+        raise ValueError("instructions must be a nonempty string")
+    return Noul(instructions=instructions)
+
+
+class SemEngine:
+    """Explicit backend configuration with no process-global settings or owned runtime."""
+
+    # Duplicate reuse is opt-in because stochastic/stateful backends can change their answers.
+    def __init__(self, backend: DecisionBackend, *, deduplicate: bool = False) -> None:
+        if not isinstance(deduplicate, bool):
+            raise ValueError("deduplicate must be boolean")
+        self._backend = backend
+        self._deduplicate = deduplicate
+
+    # Share the evaluation policy across dataframe operators and function decorators.
+    def _session(self, question: Question) -> EvaluationSession:
+        return EvaluationSession(self._backend, question, deduplicate=self._deduplicate)
+
+    # Keep rows at or above the threshold, retaining duplicate index labels in input order.
+    def sem_filter(
+        self, frame: pd.DataFrame, instructions: str, *, threshold: float = 0.5,
+        columns: Optional[Sequence[str]] = None, probability_column: Optional[str] = None,
+    ) -> pd.DataFrame:
+        _threshold(threshold)
+        if probability_column is not None:
+            output_column(frame, probability_column)
+        states = records(frame, columns)
+        session = self._session(_predicate(instructions))
+        probabilities = [cast(NoulAnswer, answer).noul for answer in session.run(states)]
+        positions = [i for i, probability in enumerate(probabilities) if probability >= threshold]
+        result = frame.iloc[positions].copy()
+        if probability_column is not None:
+            result[probability_column] = pd.array([probabilities[i] for i in positions], dtype="float64")
+        return result
+
+    # A bounded map adds chosen labels; it never parses generated text or invents categories.
+    def sem_map(
+        self, frame: pd.DataFrame, question: Choice, *, output: str,
+        columns: Optional[Sequence[str]] = None,
+    ) -> pd.DataFrame:
+        if not isinstance(question, Choice):
+            raise TypeError("sem_map requires a Choice question")
+        output_column(frame, output)
+        states = records(frame, columns)
+        answers = self._session(question).run(states)
+        result = frame.copy()
+        result[output] = pd.array([cast(ChoiceAnswer, answer).choice for answer in answers], dtype="object")
+        return result
+
+    # Scores are expectations over an explicit ordinal rubric, not pairwise comparisons.
+    def sem_score(
+        self, frame: pd.DataFrame, question: Score, *, output: str = "_score",
+        columns: Optional[Sequence[str]] = None,
+    ) -> pd.DataFrame:
+        if not isinstance(question, Score):
+            raise TypeError("sem_score requires a Score question")
+        output_column(frame, output)
+        states = records(frame, columns)
+        answers = self._session(question).run(states)
+        result = frame.copy()
+        result[output] = pd.array([cast(ScoreAnswer, answer).score for answer in answers], dtype="float64")
+        return result
+
+    # Stable descending ranking breaks ties by original row position, including duplicate indices.
+    def sem_topk(
+        self, frame: pd.DataFrame, question: Score, *, k: int,
+        output: str = "_score", columns: Optional[Sequence[str]] = None,
+    ) -> pd.DataFrame:
+        if isinstance(k, bool) or not isinstance(k, int) or k < 0:
+            raise ValueError("k must be a nonnegative integer")
+        validate_frame(frame)
+        source = frame.iloc[:0] if k == 0 else frame
+        scored = self.sem_score(source, question, output=output, columns=columns)
+        return scored.sort_values(output, ascending=False, kind="mergesort").iloc[:k].copy()
+
+    # Inner join evaluates explicit positional pairs; candidate pruning changes recall scope.
+    def sem_join(
+        self, left: pd.DataFrame, right: pd.DataFrame, instructions: str, *,
+        threshold: float = 0.5, left_columns: Optional[Sequence[str]] = None,
+        right_columns: Optional[Sequence[str]] = None,
+        candidates: Optional[Iterable[Tuple[int, int]]] = None, max_pairs: int = 100000,
+    ) -> pd.DataFrame:
+        _threshold(threshold)
+        if isinstance(max_pairs, bool) or not isinstance(max_pairs, int) or max_pairs < 0:
+            raise ValueError("max_pairs must be a nonnegative integer")
+        validate_frame(left)
+        validate_frame(right)
+        if candidates is None and len(left) * len(right) > max_pairs:
+            raise ValueError("join exceeds max_pairs; supply a shortlist or raise the limit")
+        pairs = self._pairs(left, right, candidates, max_pairs)
+        left_states = records(left, left_columns)
+        right_states = records(right, right_columns)
+        states: List[State] = [{"left": left_states[i], "right": right_states[j]} for i, j in pairs]
+        answers = self._session(_predicate(instructions)).run(states)
+        selected = [(i, j, cast(NoulAnswer, answer).noul)
+                    for (i, j), answer in zip(pairs, answers)
+                    if cast(NoulAnswer, answer).noul >= threshold]
+        # iloc avoids label-based multiplication when either index contains duplicates.
+        lpart = left.iloc[[i for i, _, _ in selected]].reset_index(drop=True).add_prefix("left.")
+        rpart = right.iloc[[j for _, j, _ in selected]].reset_index(drop=True).add_prefix("right.")
+        result = pd.concat([lpart, rpart], axis=1)
+        result["_left_position"] = pd.Series([i for i, _, _ in selected], dtype="int64")
+        result["_right_position"] = pd.Series([j for _, j, _ in selected], dtype="int64")
+        result["_probability"] = pd.Series([p for _, _, p in selected], dtype="float64")
+        return result
+
+    # Validate all candidate pairs before model work; each pair occurs at most once.
+    @staticmethod
+    def _pairs(
+        left: pd.DataFrame, right: pd.DataFrame,
+        candidates: Optional[Iterable[Tuple[int, int]]], max_pairs: int,
+    ) -> List[Tuple[int, int]]:
+        source = product(range(len(left)), range(len(right))) if candidates is None else candidates
+        pairs: List[Tuple[int, int]] = []
+        seen = set()
+        for count, pair in enumerate(source):
+            if count >= max_pairs:
+                raise ValueError("candidate stream exceeds max_pairs")
+            if not isinstance(pair, (tuple, list)) or len(pair) != 2:
+                raise ValueError("each candidate must contain two integer positions")
+            i, j = pair
+            if any(isinstance(x, bool) or not isinstance(x, int) for x in (i, j)):
+                raise ValueError("candidate positions must be integers")
+            if not 0 <= i < len(left) or not 0 <= j < len(right):
+                raise ValueError("candidate position out of range")
+            if (i, j) in seen:
+                raise ValueError("candidate pairs must be unique")
+            seen.add((i, j))
+            pairs.append((i, j))
+        return pairs

jev2semopt/execution.py

@@ -0,0 +1,102 @@
+"""Operation-local evaluation owns validation, duplicate reuse, and safe failures."""
+import json
+import math
+from copy import deepcopy
+from typing import Dict, Iterable, List, Optional, Tuple, Type
+
+from llm2jev import JSONValue, Answer, Choice, ChoiceAnswer, Noul, NoulAnswer, Question, Score, ScoreAnswer, State
+
+from .contracts import BoundDecision, DecisionBackend
+
+
+_ANSWER_TYPES: Dict[Type[object], Type[object]] = {Noul: NoulAnswer, Choice: ChoiceAnswer, Score: ScoreAnswer}
+
+
+class EvaluationError(RuntimeError):
+    """A backend failed or violated its answer contract; messages omit payloads."""
+
+    # Only a checked HTTP status crosses the safe failure boundary alongside generic messages.
+    def __init__(self, message: str, *, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+# Validate JSON recursively without coercing keys, tuples, dates, or missing values.
+def _check_json(value: object) -> None:
+    if value is None or isinstance(value, (str, bool, int)):
+        return
+    if isinstance(value, float) and math.isfinite(value):
+        return
+    if isinstance(value, list):
+        for item in value:
+            _check_json(item)
+        return
+    if isinstance(value, dict) and all(isinstance(key, str) for key in value):
+        for item in value.values():
+            _check_json(item)
+        return
+    raise ValueError("state must contain finite JSON values and string object keys")
+
+
+# JSON round-tripping detaches nested state before a backend can mutate caller data.
+def snapshot(state: State) -> Tuple[str, State]:
+    try:
+        _check_json(state)
+        encoded = json.dumps(state, sort_keys=True, ensure_ascii=True, allow_nan=False)
+        return encoded, json.loads(encoded)
+    except (ValueError, TypeError, RecursionError, OverflowError):
+        raise ValueError("state must contain finite, acyclic JSON values") from None
+
+
+# One contract check serves both direct adapter bindings and dataframe execution.
+def validate_answer(question: Question, answer: Answer) -> None:
+    if type(question) not in _ANSWER_TYPES or not isinstance(answer, _ANSWER_TYPES[type(question)]):
+        raise TypeError("unexpected answer family")
+    if isinstance(question, Choice) and isinstance(answer, ChoiceAnswer):
+        if set(answer.probabilities) != set(question.criteria):
+            raise ValueError("unexpected choice labels")
+    if isinstance(question, Score) and isinstance(answer, ScoreAnswer):
+        if dict(answer.legend) != dict(enumerate(question.criteria)):
+            raise ValueError("unexpected score rubric")
+
+
+class EvaluationSession:
+    """One question binding; cache lifetime is exactly one operator execution."""
+
+    # Binding before reading rows makes invalid rules fail even on empty inputs.
+    def __init__(self, backend: DecisionBackend, question: Question, *, deduplicate: bool) -> None:
+        if type(question) not in _ANSWER_TYPES:
+            raise TypeError("question must be Noul, Choice, or Score")
+        self._question = deepcopy(question)
+        self._deduplicate = deduplicate
+        try:
+            self._bound: BoundDecision = backend.bind(question=deepcopy(self._question))
+        except Exception:
+            raise EvaluationError("decision binding failed") from None
+
+    # Fail closed on family/schema mismatch; a typed answer alone does not prove rule alignment.
+    def _evaluate(self, state: State, position: int) -> Answer:
+        try:
+            answer = self._bound.evaluate(state=state)
+            validate_answer(self._question, answer)
+            return deepcopy(answer)
+        except Exception as error:
+            status = error.status_code if isinstance(error, EvaluationError) else None
+            if isinstance(status, bool) or not isinstance(status, int) or not 100 <= status <= 599:
+                status = None
+            raise EvaluationError("decision evaluation failed at position {}".format(position), status_code=status) from None
+
+    # Cache keys include the full projected state, never dataframe indices or mutable globals.
+    def run(self, states: Iterable[State]) -> List[Answer]:
+        cache: Dict[str, Answer] = {}
+        answers: List[Answer] = []
+        for position, state in enumerate(states):
+            key, detached = snapshot(state)
+            if self._deduplicate and key in cache:
+                answer = cache[key]
+            else:
+                answer = self._evaluate(detached, position)
+                if self._deduplicate:
+                    cache[key] = answer
+            answers.append(answer)
+        return answers

jev2semopt/pandas.py

@@ -0,0 +1,36 @@
+"""Opt-in pandas accessor registration delegates all semantics to an explicit engine."""
+from typing import Any
+
+import pandas as pd
+from llm2jev import Choice, Score
+
+from .engine import SemEngine
+
+
+@pd.api.extensions.register_dataframe_accessor("jev")
+class JevAccessor:
+    """Use df.jev.sem_filter(engine, ...) without process-global model settings."""
+
+    # Pandas owns the accessor lifetime; it never retains a runtime or a decision cache.
+    def __init__(self, frame: pd.DataFrame) -> None:
+        self._frame = frame
+
+    # All validation and threshold semantics stay with the relational implementation.
+    def sem_filter(self, engine: SemEngine, instructions: str, **kwargs: Any) -> pd.DataFrame:
+        return engine.sem_filter(self._frame, instructions, **kwargs)
+
+    # Forward bounded mapping without maintaining a second operator implementation.
+    def sem_map(self, engine: SemEngine, question: Choice, **kwargs: Any) -> pd.DataFrame:
+        return engine.sem_map(self._frame, question, **kwargs)
+
+    # Keep rubric interpretation exclusively inside the shared score operator.
+    def sem_score(self, engine: SemEngine, question: Score, **kwargs: Any) -> pd.DataFrame:
+        return engine.sem_score(self._frame, question, **kwargs)
+
+    # Delegate tie handling and k validation to the engine.
+    def sem_topk(self, engine: SemEngine, question: Score, **kwargs: Any) -> pd.DataFrame:
+        return engine.sem_topk(self._frame, question, **kwargs)
+
+    # Explicit engine injection prevents model configuration from leaking across dataframes.
+    def sem_join(self, engine: SemEngine, right: pd.DataFrame, instructions: str, **kwargs: Any) -> pd.DataFrame:
+        return engine.sem_join(self._frame, right, instructions, **kwargs)

jev2semopt/table.py

@@ -0,0 +1,40 @@
+"""Dataframe boundaries preserve row positions while isolating decision state."""
+from typing import List, Optional, Sequence
+
+import pandas as pd
+from llm2jev import JSONValue, State
+
+from .execution import snapshot
+
+
+# Flat unique string columns make state field ownership unambiguous.
+def validate_frame(frame: pd.DataFrame) -> None:
+    if not isinstance(frame, pd.DataFrame):
+        raise TypeError("expected a pandas DataFrame")
+    if not frame.columns.is_unique or any(not isinstance(key, str) for key in frame.columns):
+        raise ValueError("dataframe columns must be unique strings")
+
+
+# Snapshot only explicitly selected fields; dataframe index labels never enter model state.
+def records(frame: pd.DataFrame, columns: Optional[Sequence[str]]) -> List[State]:
+    validate_frame(frame)
+    if isinstance(columns, (str, bytes)):
+        raise ValueError("columns must be a sequence of column names")
+    selected = list(frame.columns) if columns is None else list(columns)
+    if any(not isinstance(key, str) for key in selected) or len(set(selected)) != len(selected):
+        raise ValueError("selected columns must be unique strings")
+    if any(key not in frame.columns for key in selected):
+        raise ValueError("selected column is absent from the dataframe")
+    if not selected:
+        return [{} for _ in range(len(frame))]
+    return [snapshot(dict(zip(selected, values)))[1]
+            for values in frame.loc[:, selected].itertuples(index=False, name=None)]
+
+
+# Reject overwrites before inference to avoid wasted calls and silent data loss.
+def output_column(frame: pd.DataFrame, name: str) -> None:
+    validate_frame(frame)
+    if not isinstance(name, str) or not name:
+        raise ValueError("output column must be a nonempty string")
+    if name in frame.columns:
+        raise ValueError("output column already exists")

jev2semopt-0.1.0.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: jev2semopt
+Version: 0.1.0
+Summary: Bounded semantic dataframe operators powered by Jev-style decisions
+Project-URL: Repository, https://github.com/Qingbolan/Jev2SemOpt
+Project-URL: Documentation, https://github.com/Qingbolan/Jev2SemOpt/tree/main/docs
+Author-email: "Silan.Hu" <silan.hu@u.nus.edu>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: dataframe,jev,llm,semantic-operators
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: llm2jev<0.3,>=0.2.1
+Requires-Dist: pandas<3,>=1.5
+Provides-Extra: jev
+Requires-Dist: httpx<1,>=0.27; extra == 'jev'
+Provides-Extra: ollama
+Requires-Dist: llm2jev[ollama]<0.3,>=0.2.1; extra == 'ollama'
+Provides-Extra: transformers
+Requires-Dist: llm2jev[transformers]<0.3,>=0.2.1; extra == 'transformers'
+Description-Content-Type: text/markdown
+
+# Jev2SemOpt — Typed decisions over tables
+
+**Filter tickets. Assign queues. Rank records. Match pairs.**
+
+A support pipeline needs to keep refund requests, assign a fixed queue, and count
+the resulting tickets. Jev2SemOpt makes those dataset operations explicit: select
+the fields the model may see, bind a typed question once, evaluate each record,
+and apply the result with ordinary Pandas operations.
+
+Jev2SemOpt is an independent, early-stage Python library inspired by
+[LOTUS semantic operators](https://github.com/lotus-data/lotus), using
+[LLM2Jev](https://github.com/Qingbolan/llm2jev-releases) for Jev-style decisions.
+The Jev interface concepts and `Choice`, `Score`, `Noul` vocabulary originate with
+[TypeSafe](https://typesafe.ai/blog/introducing-system-one-models-and-jev).
+Use a local LLM2Jev runtime or the official TypeSafe HTTP API through `JevBackend`.
+The HTTP adapter is contract-tested; hosted Jev accuracy has not been measured.
+
+## Install and run
+
+Python **3.8+**. The core requires Pandas and LLM2Jev; model providers are opt-in.
+
+```bash
+pip install jev2semopt
+# Official hosted Jev (requires a TypeSafe API key):
+pip install 'jev2semopt[jev]'
+# Local providers:
+pip install 'jev2semopt[transformers]'
+# or: pip install 'jev2semopt[ollama]'
+```
+
+For a model-free example or development:
+
+```bash
+git clone https://github.com/Qingbolan/Jev2SemOpt.git
+cd Jev2SemOpt
+uv sync --group dev
+uv run python examples/refund_pipeline.py
+uv run python examples/decorated_decision.py
+```
+
+These examples use synthetic scores and require no model or API key. Production
+and development dependencies resolve from PyPI. See [release verification](docs/releasing.md).
+
+## A refund pipeline
+
+Configure execution explicitly. The application owns the runtime and closes it;
+Jev2SemOpt only borrows it. The following requires compatible local model weights
+and a model-appropriate LLM2Jev encoder/label configuration; it is an API example,
+not a validated inference configuration.
+
+```python
+import pandas as pd
+from llm2jev import LLM2Jev, TransformersRuntime
+from jev2semopt import LLM2JevBackend, SemEngine, Choice
+
+tickets = pd.DataFrame({
+    "id": [101, 102],
+    "text": ["Please refund my order.", "Where is my parcel?"],
+})
+
+with TransformersRuntime("/path/to/local/model", device="cpu") as runtime:
+    engine = SemEngine(LLM2JevBackend(
+        LLM2Jev(runtime=runtime, model_identity=runtime.identity),
+        model=runtime.identity.name,
+    ))
+    refunds = engine.sem_filter(
+        tickets, "Does text explicitly request a refund?",
+        columns=["text"], threshold=0.7, probability_column="refund_support",
+    )
+    routed = engine.sem_map(
+        refunds,
+        Choice(instructions="Which team should handle text?", criteria={
+            "billing": "Payments, invoices, or refunds",
+            "delivery": "Shipping, tracking, or missing parcels",
+            "other": "Requests outside billing and delivery",
+        }),
+        columns=["text"], output="queue",
+    )
+    counts = routed.groupby("queue").size()
+```
+
+Only `text` enters the decision state. IDs remain available in the output. Column
+names in instructions refer to keys in that state; there is **no `{column}` string
+interpolation**. Thresholds require validation on your own labeled workload.
+
+## Operators and boundaries
+
+Official hosted Jev is also supported through `JevBackend`, using a caller-owned
+HTTP client and TypeSafe API key. See the [official API integration](docs/official-jev.md)
+for setup and verification limits. An OpenRouter key does not authenticate TypeSafe.
+
+| Operator | Jev decision | Output and scope |
+| --- | --- | --- |
+| `sem_filter(frame, instructions, ...)` | `Noul` | Rows with support **≥ threshold**, original order and index |
+| `sem_map(frame, Choice(...), output=...)` | `Choice` | All rows plus a chosen label from supplied alternatives |
+| `sem_score(frame, Score(...), ...)` | `Score` | All rows plus expected ordinal rubric level |
+| `sem_topk(frame, Score(...), k=...)` | `Score` | Largest expected levels; stable source-order ties |
+| `sem_join(left, right, instructions, ...)` | `Noul` | Inner join over candidate pairs; namespaced source fields and positions |
+
+LOTUS provides a broader semantic operator model, including generated projections,
+extraction, aggregation, and comparator-based ranking. Jev2SemOpt deliberately
+restricts mappings to finite alternatives and ranks by an explicit ordinal rubric.
+It is not a drop-in LOTUS replacement. Free-text extraction, summaries, vector
+search, learned cascades, SQL planning, asynchronous execution, and distributed
+execution are not implemented. Count/group/sum the typed outputs with Pandas;
+there is no misleading `sem_agg` alias for a generative summary.
+
+```python
+from jev2semopt import Score
+
+ranked = engine.sem_topk(
+    tickets,
+    Score(instructions="How urgent is text?", criteria=[
+        "Routine request", "Time-sensitive issue", "Immediate safety or service emergency",
+    ]),
+    columns=["text"], k=10, output="urgency",
+)
+
+matches = engine.sem_join(
+    tickets, policies,
+    "Does left.text describe a case covered by right.policy?",
+    left_columns=["text"], right_columns=["policy"],
+    candidates=[(0, 1), (1, 0)],  # row POSITIONS, not index labels
+    threshold=0.8,
+)
+```
+
+The join output includes `left.<column>`, `right.<column>`, `_left_position`,
+`_right_position`, and `_probability`. Without candidates it evaluates every pair,
+subject to a default 100,000-pair limit. A shortlist can reduce work but can also
+exclude true matches; the caller owns its recall. See [API contracts](docs/api.md).
+
+## Python-native integration
+
+The Pandas accessor is opt-in and uses Pandas' registration decorator. It forwards
+to the same engine implementation and does not install global model settings:
+
+```python
+import jev2semopt.pandas
+
+refunds = tickets.jev.sem_filter(
+    engine, "Does text request a refund?", columns=["text"], threshold=0.7,
+)
+```
+
+Use `@decision` when application code already builds the state for one decision:
+
+```python
+from jev2semopt import Noul, decision
+
+@decision(engine, question=Noul(instructions="Does text explicitly request a refund?"))
+def refund_requested(text):
+    return {"text": text}
+
+answer = refund_requested("Please refund my order.")
+print(answer.noul)
+```
+
+The decorator binds once, preserves function metadata with `functools.wraps`, and
+evaluates new state on each call. It does not cache results across calls. Decorated
+functions must be synchronous JSON-state builders and now return typed answers.
+
+## Measured results
+
+On **50 balanced SciFact records**, the same GPT-4o-mini scored **31/50 with LOTUS**
+and **32/50 with Jev-style / LLM2Jev**. The one-record difference does not establish
+an accuracy improvement: the paired 95% interval spans −8 to +12 percentage points.
+Jev-style improves precision but lowers recall and F1 in this run.
+
+![Small-sample accuracy, precision, recall and F1 for LOTUS and Jev-style](https://raw.githubusercontent.com/Qingbolan/Jev2SemOpt/v0.1.0/docs/assets/scifact-small-sample.png)
+
+On **400 local Qwen2.5-0.5B candidate pairs**, Jev-style filtering was 1.97× faster,
+but both filters had roughly 4% precision. Three-level Jev-style scoring was 2.70×
+slower than LOTUS scoring and reduced ranking quality. BM25 had the highest nDCG.
+
+![Local ranking quality and operator time, including the BM25 baseline](https://raw.githubusercontent.com/Qingbolan/Jev2SemOpt/v0.1.0/docs/assets/scifact-local.png)
+
+These are **official SciFact dataset subsets with adapted protocols**, not full
+LOTUS paper reproduction or measurements of TypeSafe's hosted Jev model. Unjudged
+documents count as negatives under the qrel convention. Prompts differ between
+operators; these experiments do not isolate probability assembly as the cause.
+[Sampling, confusion matrices, costs, raw observations, and reproduction](https://github.com/Qingbolan/Jev2SemOpt/blob/v0.1.0/benchmarks/README.md).
+
+## Execution cost and score meaning
+
+`SemEngine(backend, deduplicate=True)` reuses identical selected JSON state **within
+one operation**. This is opt-in and assumes the backend is deterministic and has no
+per-call side effects. There is no global cache and no stale reuse across operations.
+Question binding avoids recompilation; it is not a KV cache or a batched model call.
+
+For `N` rows, filtering requires `N` one-candidate evaluations; mapping with `C`
+choices requires `N × C` binary candidates; scoring with `R` rubric levels requires
+`N × R`. An exhaustive join needs `L × R` pair evaluations. Duplicate reuse reduces
+these counts to unique selected states. Calls are sequential. Join candidates and
+results are materialized in memory; this version targets bounded in-memory tables.
+
+No end-to-end speedup, calibrated correctness, or equivalence to LOTUS quality is
+claimed. `Noul` is label-conditioned support; `Score` is an expected equally spaced
+rubric index. These are decision signals, not probabilities that the answer is right.
+LLM2Jev's Transformers adapter reads next-token logits; its Ollama adapter requests
+one token to obtain exact binary logprobs. Jev2SemOpt never parses generated prose.
+See [evaluation protocol](docs/evaluation.md).
+
+## Architecture and development
+
+```text
+DataFrame API / @decision
+          ↓
+SemEngine — positional relational semantics
+          ↓
+EvaluationSession — one rule, detached state, operation-local reuse
+          ↓
+DecisionBackend.bind → BoundDecision.evaluate → typed Answer
+          ↓
+├─ LLM2JevBackend → public LLM2Jev API → caller-owned runtime
+└─ JevBackend → TypeSafe HTTP API → caller-owned HTTP client
+```
+
+The engine depends on a backend protocol, not Ollama or Transformers. Models,
+prompts, device configuration, binary labels, and runtime lifecycle stay in
+LLM2Jev for local execution; hosted execution uses the supplied HTTP client. There is no new resource lifecycle to duplicate in the table layer.
+
+```text
+src/jev2semopt/
+├── contracts.py       Backend and bound-decision protocols
+├── execution.py       State isolation, answer checks, safe failure boundary
+├── engine.py          Filter/map/score/top-k/join semantics
+├── table.py           Dataframe schema and state projection
+├── decorators.py      Function-to-decision binding
+├── pandas.py          Opt-in accessor registration
+└── adapters/          LLM2Jev service and official Jev HTTP integration
+```
+
+Run the checks in [CONTRIBUTING.md](CONTRIBUTING.md). Architectural decisions,
+privacy constraints, and delivery status are documented in
+[architecture](docs/architecture.md), [privacy](docs/privacy.md), and
+[implementation plan](docs/implementation-plan.md). Attribution is recorded in
+[NOTICE](NOTICE). Licensed under [MIT](LICENSE); [dependency and benchmark attribution](docs/licenses.md).
+
+[Local verification record](docs/verification.md): 50 deterministic tests passed
+on Python 3.8, 3.12, and 3.14. Real-model observations are recorded separately in
+the [benchmark report](benchmarks/README.md).

jev2semopt-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+jev2semopt/__init__.py,sha256=DfrWETT5xRzGcahIXLz2tdkjj1guIBmiDwUuA09BHUk,556
+jev2semopt/contracts.py,sha256=PWHLZH7HvXH61joLzMXZV1OxKGDm7JhBzkXes34FLwk,686
+jev2semopt/decorators.py,sha256=8Rm68mkq8Bq_60B78wKq60UIXlHl0tkw1hPWlQdKEXs,1303
+jev2semopt/engine.py,sha256=XnFoiD3VRDQAZtTY2ZR17FZJpErtsQDhwp8m2v0-r-Q,7973
+jev2semopt/execution.py,sha256=e_t0ORM-QxjzIlFxw7SdSfjp9eUafVVo9KS79NF4yqE,4648
+jev2semopt/pandas.py,sha256=DjkKl1D0vU0imJxVtW1KC6vFvi-k1oNgcj7-J3DRDWk,1755
+jev2semopt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jev2semopt/table.py,sha256=NRmg761DdImnFKkAuabSm3V6SfQZUkkHt0WhRx2B2y4,1859
+jev2semopt/adapters/__init__.py,sha256=DYTwzYMUX1Tn4xZruJfMLlE5CZSHGL9L8li1Sb4KYxg,81
+jev2semopt/adapters/jev.py,sha256=BCkDst93KK50Op5KnXqf6MEVU3_c8MmHk6AjBh65NhQ,5705
+jev2semopt/adapters/llm2jev.py,sha256=6PYgT72RKuw7djoDXjFZGEvynCYTmIFvrM9ZPUrg_9I,1349
+jev2semopt-0.1.0.dist-info/METADATA,sha256=hy-Fsv1kfRPyN53cCYQDR_sJQu6TsPZi4ANWbOuOi48,12060
+jev2semopt-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+jev2semopt-0.1.0.dist-info/licenses/LICENSE,sha256=dOMFrR-h0QzbHz5boUZGzEEl3ZnRDObocLTx1FJa3EI,1093
+jev2semopt-0.1.0.dist-info/licenses/NOTICE,sha256=xrBwCjFzAALOziyyK1gaZZHAgKetmTHLO6FChzR9mVY,1057
+jev2semopt-0.1.0.dist-info/RECORD,,

jev2semopt-0.1.0.dist-info/WHEEL

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

jev2semopt-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silan.Hu and Jev2SemOpt contributors
+
+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.

jev2semopt-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,20 @@
+Jev2SemOpt
+Copyright (c) 2026 Silan.Hu and Jev2SemOpt contributors
+
+The semantic-operator model and operator vocabulary are inspired by LOTUS:
+https://github.com/lotus-data/lotus
+https://arxiv.org/abs/2407.11418
+LOTUS is Apache-2.0 licensed. Its operator implementation is an external
+benchmark dependency, not part of the Jev2SemOpt runtime. The reranking benchmark
+objective/prompt is adapted from its llm-eval experiment; see
+docs/licenses/LOTUS-Apache-2.0.txt for the upstream license.
+
+Jev state/questions and Choice, Score, Noul interface concepts originate with TypeSafe:
+https://typesafe.ai/blog/introducing-system-one-models-and-jev
+This project is independent. Its HTTP adapter targets the documented TypeSafe
+API; hosted model behavior and accuracy have not been verified.
+
+LLM2Jev provides public decision types and execution as an external dependency:
+https://github.com/Qingbolan/llm2jev-releases
+Its architectural separation and documentation structure informed this project.
+LLM2Jev is MIT licensed, copyright (c) 2026 LLM2Jev contributors.