jevframe 0.1.0__py3-none-any.whl

jevframe/__init__.py

@@ -0,0 +1,9 @@
+"""Semantic dataframe evaluation using TypeSafe Jev.
+
+Import ``jevframe.pandas`` or ``jevframe.polars`` to register the native accessor.
+"""
+
+from ._cache import MemoryCache
+from ._types import EvaluationError, EvaluationWarning, Progress, RowFailure
+
+__all__ = ["EvaluationError", "EvaluationWarning", "MemoryCache", "Progress", "RowFailure"]

jevframe/_accessor.py

@@ -0,0 +1,126 @@
+"""The common public API; integrations supply only row and result conversion."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+from typing import Any, Generic, TypeVar
+
+from typesafe_sdk import AsyncTypeSafeClient, JSONContent, Noul, Score
+
+from ._cache import MemoryCache
+from ._context import RowSource
+from ._engine import Options, evaluate_rows
+from ._schema import QuestionPlan, choice_question, make_plan
+from ._types import Errors, Nulls, Output, ProgressCallback, Question, State
+
+FrameT = TypeVar("FrameT")
+SeriesT = TypeVar("SeriesT")
+
+
+def _validate_output(output: Output) -> None:
+    if output not in ("columns", "struct"):
+        raise ValueError("output must be 'columns' or 'struct'")
+
+
+class BaseAccessor(ABC, Generic[FrameT, SeriesT]):
+    @abstractmethod
+    def _source(self, state: State) -> RowSource: ...
+
+    @abstractmethod
+    def _frame(
+        self, values: list[tuple[Any, ...]], plan: QuestionPlan, source: RowSource, output: Output
+    ) -> FrameT: ...
+
+    @abstractmethod
+    def _series(self, values: list[tuple[Any, ...]], source: RowSource) -> SeriesT: ...
+
+    async def noul(
+        self,
+        question: str,
+        *,
+        state: State,
+        client: AsyncTypeSafeClient | None = None,
+        model: str | None = None,
+        max_concurrency: int = 16,
+        cache: MemoryCache | None = None,
+        progress: bool | ProgressCallback = False,
+        errors: Errors = "raise",
+        nulls: Nulls = "include",
+    ) -> SeriesT:
+        """Return a yes-probability Series, without thresholding or changing rows."""
+        options = Options(client, model, max_concurrency, cache, progress, errors, nulls)
+        plan = make_plan({"result": Noul(instructions=question)}, prefix=False)
+        source = self._source(state)
+        values = await evaluate_rows(source, state, plan, options)
+        return self._series(values, source)
+
+    async def choice(
+        self,
+        question: str,
+        *,
+        choices: Sequence[str] | Mapping[str, JSONContent | None],
+        state: State,
+        output: Output = "columns",
+        client: AsyncTypeSafeClient | None = None,
+        model: str | None = None,
+        max_concurrency: int = 16,
+        cache: MemoryCache | None = None,
+        progress: bool | ProgressCallback = False,
+        errors: Errors = "raise",
+        nulls: Nulls = "include",
+    ) -> FrameT:
+        """Return labels, confidence, and probabilities as columns or one result struct."""
+        _validate_output(output)
+        options = Options(client, model, max_concurrency, cache, progress, errors, nulls)
+        plan = make_plan({"result": choice_question(question, choices)}, prefix=False)
+        source = self._source(state)
+        values = await evaluate_rows(source, state, plan, options)
+        return self._frame(values, plan, source, output)
+
+    async def score(
+        self,
+        question: str,
+        *,
+        levels: Sequence[JSONContent],
+        state: State,
+        output: Output = "columns",
+        client: AsyncTypeSafeClient | None = None,
+        model: str | None = None,
+        max_concurrency: int = 16,
+        cache: MemoryCache | None = None,
+        progress: bool | ProgressCallback = False,
+        errors: Errors = "raise",
+        nulls: Nulls = "include",
+    ) -> FrameT:
+        """Return level/label, expected score, and probabilities as columns or a struct."""
+        _validate_output(output)
+        options = Options(client, model, max_concurrency, cache, progress, errors, nulls)
+        if isinstance(levels, (str, bytes)) or not isinstance(levels, Sequence):
+            raise TypeError("levels must be an ordered sequence of descriptions")
+        plan = make_plan({"result": Score(instructions=question, criteria=levels)}, prefix=False)
+        source = self._source(state)
+        values = await evaluate_rows(source, state, plan, options)
+        return self._frame(values, plan, source, output)
+
+    async def evaluate(
+        self,
+        *,
+        state: State,
+        questions: Mapping[str, Question],
+        output: Output = "columns",
+        client: AsyncTypeSafeClient | None = None,
+        model: str | None = None,
+        max_concurrency: int = 16,
+        cache: MemoryCache | None = None,
+        progress: bool | ProgressCallback = False,
+        errors: Errors = "raise",
+        nulls: Nulls = "include",
+    ) -> FrameT:
+        """Evaluate questions per row, with prefixed fields in columns or a result struct."""
+        _validate_output(output)
+        options = Options(client, model, max_concurrency, cache, progress, errors, nulls)
+        plan = make_plan(questions, prefix=True)
+        source = self._source(state)
+        values = await evaluate_rows(source, state, plan, options)
+        return self._frame(values, plan, source, output)

jevframe/_cache.py

@@ -0,0 +1,66 @@
+"""Explicit, bounded process-local caching; no credentials or row text as keys."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from threading import RLock
+from typing import Any
+from weakref import WeakKeyDictionary
+
+_client_tokens: WeakKeyDictionary[Any, object] = WeakKeyDictionary()
+_client_lock = RLock()
+
+
+def client_token(client: Any) -> object:
+    # Keep an opaque token in keys: a collected client's id must never be reused.
+    with _client_lock:
+        if client not in _client_tokens:
+            _client_tokens[client] = object()
+        return _client_tokens[client]
+
+
+class MemoryCache:
+    """LRU cache of successful complete row evaluations.
+
+    Pass the same instance to subsequent calls to reuse results. Model aliases
+    can move; call ``clear()`` when fresh inference is required. Cache contents
+    are process-local and never written to disk.
+    """
+
+    def __init__(self, max_entries: int = 10_000):
+        if isinstance(max_entries, bool) or not isinstance(max_entries, int) or max_entries < 1:
+            raise ValueError("max_entries must be a positive integer")
+        self._max_entries = max_entries
+        self._entries: OrderedDict[tuple[Any, ...], tuple[Any, ...]] = OrderedDict()
+        self._lock = RLock()
+        self._generation = 0
+
+    @property
+    def max_entries(self) -> int:
+        return self._max_entries
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._entries)
+
+    def clear(self) -> None:
+        """Discard entries, including results of requests already in progress."""
+        with self._lock:
+            self._entries.clear()
+            self._generation += 1
+
+    def _get(self, key: tuple[Any, ...]) -> tuple[Any, ...] | None:
+        with self._lock:
+            result = self._entries.get(key)
+            if result is not None:
+                self._entries.move_to_end(key)
+            return result
+
+    def _put(self, key: tuple[Any, ...], value: tuple[Any, ...], generation: int) -> None:
+        with self._lock:
+            if generation != self._generation:
+                return
+            self._entries[key] = value
+            self._entries.move_to_end(key)
+            while len(self._entries) > self.max_entries:
+                self._entries.popitem(last=False)

jevframe/_context.py

@@ -0,0 +1,103 @@
+"""Context construction without importing either dataframe library."""
+
+from __future__ import annotations
+
+import datetime as dt
+import inspect
+import math
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+from ._types import State
+
+
+def identity(value: Any) -> Any:
+    return value
+
+
+@dataclass
+class RowSource:
+    rows: Iterator[dict[str, Any]]
+    count: int
+    convert_scalar: Callable[[Any], Any] = identity
+    index: Any = None
+
+
+def selected_columns(columns: Sequence[Any], state: State) -> list[str]:
+    """Validate selection before inference; callable context sees every column."""
+    if callable(state):
+        if inspect.iscoroutinefunction(state):
+            raise TypeError("state must be a synchronous callable")
+        selected = list(columns)
+    elif isinstance(state, str):
+        selected = [state]
+    elif isinstance(state, Sequence) and not isinstance(state, bytes):
+        selected = list(state)
+    else:
+        raise TypeError("state must be a column name, sequence of names, or synchronous callable")
+    if not selected and not callable(state):
+        raise ValueError("state must select at least one column")
+    if any(not isinstance(name, str) for name in selected):
+        raise TypeError("Context column names must be strings")
+    if len(set(selected)) != len(selected):
+        raise ValueError("Context column names must be unique")
+    for name in selected:
+        occurrences = list(columns).count(name)
+        if occurrences == 0:
+            raise ValueError(f"Unknown context column: {name!r}")
+        if occurrences > 1:
+            raise ValueError(f"Ambiguous context column: {name!r}")
+    return selected
+
+
+def normalize(value: Any, convert_scalar: Callable[[Any], Any] = identity) -> Any:
+    """Return strict JSON values, keeping map/list order and temporal precision."""
+    value = convert_scalar(value)
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float):
+        if math.isnan(value):
+            return None
+        if not math.isfinite(value):
+            raise ValueError("Infinite numbers are not valid context")
+        return value
+    if isinstance(value, (dt.datetime, dt.date, dt.time)):
+        return value.isoformat()
+    if isinstance(value, dt.timedelta):
+        # Timedeltas are exact at Python's microsecond resolution, including negatives.
+        microseconds = (value.days * 86400 + value.seconds) * 1_000_000 + value.microseconds
+        sign = "-" if microseconds < 0 else ""
+        seconds, micros = divmod(abs(microseconds), 1_000_000)
+        return f"{sign}PT{seconds}.{micros:06d}S"
+    if isinstance(value, Mapping):
+        if any(not isinstance(key, str) for key in value):
+            raise TypeError("Context object keys must be strings")
+        return {key: normalize(item, convert_scalar) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [normalize(item, convert_scalar) for item in value]
+    raise TypeError(f"Unsupported context type: {type(value).__name__}")
+
+
+def construct_context(row: Mapping[str, Any], state: State, source: RowSource) -> Any:
+    # Deep copying is necessary: pandas object columns can contain lists/dicts.
+    value = state(deepcopy(dict(row))) if callable(state) else row
+    if inspect.isawaitable(value):
+        if inspect.iscoroutine(value):
+            value.close()
+        raise TypeError("state must return context synchronously")
+    result = normalize(value, source.convert_scalar)
+    if not isinstance(result, (str, dict, list)):
+        raise TypeError("Constructed state must be text, an object, or an array")
+    return result
+
+
+def contains_null(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, dict):
+        return any(contains_null(item) for item in value.values())
+    if isinstance(value, list):
+        return any(contains_null(item) for item in value)
+    return False

jevframe/_engine.py

@@ -0,0 +1,206 @@
+"""Bounded async row evaluation, independent of pandas and Polars."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import inspect
+import os
+import warnings
+from dataclasses import dataclass
+from typing import Any
+
+from typesafe_sdk import AsyncTypeSafeClient, constants
+
+from ._cache import MemoryCache, client_token
+from ._context import RowSource, construct_context, contains_null
+from ._schema import QuestionPlan, encode, flatten
+from ._types import (
+    Errors,
+    EvaluationError,
+    EvaluationWarning,
+    Nulls,
+    Progress,
+    ProgressCallback,
+    RowFailure,
+    State,
+)
+
+
+@dataclass(frozen=True)
+class Options:
+    client: AsyncTypeSafeClient | None = None
+    model: str | None = None
+    max_concurrency: int = 16
+    cache: MemoryCache | None = None
+    progress: bool | ProgressCallback = False
+    errors: Errors = "raise"
+    nulls: Nulls = "include"
+
+    def __post_init__(self) -> None:
+        if self.client is not None and not isinstance(self.client, AsyncTypeSafeClient):
+            raise TypeError("client must be an official AsyncTypeSafeClient")
+        if self.model is not None and (not isinstance(self.model, str) or not self.model.strip()):
+            raise ValueError("model must be a nonempty string")
+        if (
+            isinstance(self.max_concurrency, bool)
+            or not isinstance(self.max_concurrency, int)
+            or self.max_concurrency < 1
+        ):
+            raise ValueError("max_concurrency must be a positive integer")
+        if self.cache is not None and not isinstance(self.cache, MemoryCache):
+            raise TypeError("cache must be a MemoryCache instance or None")
+        if not isinstance(self.progress, bool) and not callable(self.progress):
+            raise TypeError("progress must be a bool or synchronous callback")
+        if inspect.iscoroutinefunction(self.progress):
+            raise TypeError("progress callback must be synchronous")
+        if self.errors not in ("raise", "coerce"):
+            raise ValueError("errors must be 'raise' or 'coerce'")
+        if self.nulls not in ("include", "skip", "raise"):
+            raise ValueError("nulls must be 'include', 'skip', or 'raise'")
+
+
+def _create_client(**kwargs: Any) -> AsyncTypeSafeClient:
+    return AsyncTypeSafeClient(**kwargs)
+
+
+async def evaluate_rows(
+    source: RowSource, state: State, plan: QuestionPlan, options: Options
+) -> list[tuple[Any, ...]]:
+    """One request per row, with a fixed number of workers and positional output."""
+    missing = (None,) * len(plan.columns)
+    results = [missing] * source.count
+    rows = enumerate(source.rows)
+    cache = options.cache
+    failures: list[RowFailure] = []
+    client = options.client
+    owned = client is None
+
+    # Resolve owned configuration once, using only documented SDK constants.
+    # A supplied client captures its own defaults: isolate its cache by identity.
+    model = options.model
+    client_kwargs: dict[str, Any] = {}
+    if owned:
+        model = model or os.environ.get(constants.DEFAULT_MODEL_ENV, "").strip()
+        model = model or constants.DEFAULT_MODEL
+        base_url = os.environ.get(constants.BASE_URL_ENV, "").strip() or constants.DEFAULT_BASE_URL
+        api_key = os.environ.get(constants.API_KEY_ENV, "").strip() or None
+        client_kwargs = {"api_key": api_key, "model": model, "base_url": base_url}
+        credential_fingerprint = hashlib.sha256((api_key or "").encode()).digest()
+        scope: tuple[Any, ...] = ("owned", base_url.rstrip("/"), model, credential_fingerprint)
+    else:
+        scope = ("supplied", client_token(client), model) if cache is not None else ()
+
+    # Futures are only created for active distinct requests, not for every row.
+    # Store outcomes as values so failed owners cannot leave unobserved exceptions.
+    pending: dict[
+        tuple[Any, ...], asyncio.Future[tuple[tuple[Any, ...] | None, Exception | None]]
+    ] = {}
+    completed = failed = skipped = cache_hits = 0
+    bar: Any = None
+
+    def report(*, failure: bool = False, skip: bool = False, hit: bool = False) -> None:
+        nonlocal completed, failed, skipped, cache_hits
+        completed += 1
+        failed += int(failure)
+        skipped += int(skip)
+        cache_hits += int(hit)
+        if bar is not None:
+            bar.update(1)
+        if callable(options.progress):
+            returned = options.progress(
+                Progress(completed, source.count, failed, skipped, cache_hits)
+            )
+            if inspect.isawaitable(returned):
+                if inspect.iscoroutine(returned):
+                    returned.close()
+                raise TypeError("progress callback must return synchronously")
+
+    async def infer(context: Any) -> tuple[tuple[Any, ...], bool]:
+        key = None
+        generation = 0
+        if cache is not None:
+            generation = cache._generation
+            digest = hashlib.sha256(encode([context, plan.serialized]).encode()).digest()
+            key = (generation, scope, digest)
+            cached = cache._get(key)
+            if cached is not None:
+                return cached, True
+            if key in pending:
+                value, error = await asyncio.shield(pending[key])
+                if error is not None:
+                    raise error
+                assert value is not None
+                return value, True
+            pending[key] = asyncio.get_running_loop().create_future()
+        try:
+            assert client is not None
+            response = await client.system_one(state=context, questions=plan.questions, model=model)
+            value = flatten(response, plan)
+            if cache is not None and key is not None:
+                cache._put(key, value, generation)
+                pending[key].set_result((value, None))
+            return value, False
+        except Exception as error:
+            if key is not None:
+                pending[key].set_result((None, error))
+            raise
+        finally:
+            if key is not None:
+                future = pending.pop(key)
+                if not future.done():
+                    future.cancel()
+
+    async def worker() -> None:
+        nonlocal client
+        for position, row in rows:
+            try:
+                context = construct_context(row, state, source)
+                has_null = contains_null(context)
+                if has_null and options.nulls == "raise":
+                    raise ValueError("Row context contains null values")
+            except Exception as error:
+                raise EvaluationError(position, error, phase="context construction") from error
+            if has_null and options.nulls == "skip":
+                report(skip=True)
+            else:
+                # Client configuration errors are never converted to missing probabilities.
+                # No await occurs here, so exactly one owned client is created.
+                if client is None:
+                    client = _create_client(**client_kwargs)
+                try:
+                    results[position], hit = await infer(context)
+                except Exception as error:
+                    if options.errors == "raise":
+                        raise EvaluationError(position, error) from error
+                    failures.append(RowFailure(position, error))
+                    report(failure=True)
+                else:
+                    report(hit=hit)
+            # Cached and skipped rows otherwise never yield, starving cancellation/UI.
+            await asyncio.sleep(0)
+
+    tasks: list[asyncio.Task[None]] = []
+    try:
+        if options.progress is True:
+            from tqdm.auto import tqdm
+
+            bar = tqdm(total=source.count, desc="Evaluating", unit="row")
+        tasks = [
+            asyncio.create_task(worker()) for _ in range(min(source.count, options.max_concurrency))
+        ]
+        await asyncio.gather(*tasks)
+    finally:
+        for task in tasks:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        try:
+            if owned and client is not None:
+                await client.aclose()
+        finally:
+            if bar is not None:
+                bar.close()
+    if failures:
+        warnings.warn(EvaluationWarning(failures), stacklevel=3)
+    return results

jevframe/_schema.py

@@ -0,0 +1,189 @@
+"""Frozen request definitions and deterministic native result columns."""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from typesafe_sdk import (
+    Choice,
+    ChoiceAnswer,
+    Noul,
+    NoulAnswer,
+    Score,
+    ScoreAnswer,
+    SystemOneResponse,
+    TypeSafeError,
+)
+
+from ._types import Question
+
+# Allow floating-point/API rounding, without repairing or renormalizing values.
+PROBABILITY_TOLERANCE = 1e-6
+
+
+def encode(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+
+
+@dataclass(frozen=True)
+class Column:
+    name: str
+    kind: Literal["float", "int", "str"]
+
+
+@dataclass(frozen=True)
+class QuestionPlan:
+    questions: dict[str, Question]
+    columns: tuple[Column, ...]
+    serialized: str
+
+
+def pack_rows(values: list[tuple[Any, ...]], plan: QuestionPlan) -> list[dict[str, Any] | None]:
+    """Pack validated scalar fields, keeping failed/skipped rows wholly missing.
+
+    Build fresh dictionaries so callers cannot mutate other rows or cached values.
+    Field names and order exactly match the expanded column schema.
+    """
+    names = [column.name for column in plan.columns]
+    return [
+        None if all(value is None for value in row) else dict(zip(names, row, strict=True))
+        for row in values
+    ]
+
+
+def make_plan(questions: Mapping[str, Question], *, prefix: bool) -> QuestionPlan:
+    if not isinstance(questions, Mapping) or not questions:
+        raise ValueError("questions must be a nonempty mapping of names to SDK question objects")
+    snapshots: dict[str, Question] = {}
+    columns: list[Column] = []
+    for name, question in questions.items():
+        if not isinstance(name, str) or not name:
+            raise ValueError("Question names must be nonempty strings")
+        if not isinstance(question, (Noul, Choice, Score)):
+            raise TypeError("questions values must be official SDK Noul, Choice, or Score objects")
+        cls = (
+            Noul
+            if isinstance(question, Noul)
+            else Choice
+            if isinstance(question, Choice)
+            else Score
+        )
+        # These SDK models are mutable; validation of a dumped copy prevents drift.
+        snapshot = cls.model_validate(question.model_dump(mode="json"))
+        snapshots[name] = snapshot
+        fields: list[tuple[str, Literal["float", "int", "str"]]]
+        if isinstance(snapshot, Noul):
+            fields = [("probability", "float")]
+        elif isinstance(snapshot, Choice):
+            if not 1 <= len(snapshot.criteria) <= 255:
+                raise ValueError("Choice requires 1 to 255 options")
+            fields = [("label", "str"), ("confidence", "float")]
+            fields += [(f"p__{label}", "float") for label in snapshot.criteria]
+        else:
+            if not 2 <= len(snapshot.criteria) <= 10:
+                raise ValueError("Score requires 2 to 10 ordered levels")
+            fields = [
+                ("level", "int"),
+                ("label", "str"),
+                ("score", "float"),
+                ("confidence", "float"),
+            ]
+            fields += [(f"p__{i}", "float") for i in range(len(snapshot.criteria))]
+        columns.extend(
+            Column(f"{name}__{field}" if prefix else field, kind) for field, kind in fields
+        )
+    names = [column.name for column in columns]
+    if len(set(names)) != len(names):
+        raise ValueError("Generated result column names collide; rename questions or choice labels")
+    serialized = encode({name: q.model_dump(mode="json") for name, q in snapshots.items()})
+    return QuestionPlan(snapshots, tuple(columns), serialized)
+
+
+def choice_question(instructions: str, choices: Sequence[str] | Mapping[str, Any]) -> Choice:
+    if isinstance(choices, Mapping):
+        criteria = dict(choices)
+    elif isinstance(choices, Sequence) and not isinstance(choices, (str, bytes)):
+        if any(not isinstance(label, str) for label in choices):
+            raise TypeError("Choice labels must be strings")
+        if len(set(choices)) != len(choices):
+            raise ValueError("Choice labels must be unique")
+        criteria = dict.fromkeys(choices)
+    else:
+        raise TypeError("choices must be a sequence of labels or a mapping of descriptions")
+    return Choice(instructions=instructions, criteria=criteria)
+
+
+def probability(value: Any) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError("Expected a numeric probability")
+    number = float(value)
+    if not math.isfinite(number) or not 0 <= number <= 1:
+        raise ValueError("Probability must be finite and between zero and one")
+    return number
+
+
+def distribution(values: Mapping[Any, float], keys: Sequence[Any]) -> list[float]:
+    if set(values) != set(keys):
+        raise ValueError("Probability distribution keys differ from the requested criteria")
+    result = [probability(values[key]) for key in keys]
+    if not math.isclose(math.fsum(result), 1, rel_tol=0, abs_tol=PROBABILITY_TOLERANCE):
+        raise ValueError("Probability distribution must sum to one")
+    return result
+
+
+def flatten(response: SystemOneResponse, plan: QuestionPlan) -> tuple[Any, ...]:
+    if not isinstance(response, SystemOneResponse):
+        raise TypeError("Expected an official SDK SystemOneResponse")
+    # The SDK omits unknown answer types. Check raw names too, so an unexpected
+    # future answer cannot disappear before our exact question-set validation.
+    try:
+        raw_names = response.raw_http_response.json().get("answers", {})
+    except TypeSafeError:
+        raw_names = response.answers  # SDK models constructed directly, e.g. in tests.
+    if not isinstance(raw_names, dict) or set(raw_names) != set(plan.questions):
+        raise ValueError("Response question names differ from the request")
+    if set(response.answers) != set(plan.questions):
+        raise ValueError("Response question names differ from the request")
+    result: list[Any] = []
+    for name, question in plan.questions.items():
+        answer = response.answers[name]
+        if isinstance(question, Noul):
+            if not isinstance(answer, NoulAnswer):
+                raise ValueError("Expected a Noul answer")
+            result.append(probability(answer.noul))
+        elif isinstance(question, Choice):
+            if not isinstance(answer, ChoiceAnswer):
+                raise ValueError("Expected a Choice answer")
+            probabilities = distribution(answer.probabilities, list(question.criteria))
+            if answer.choice not in question.criteria:
+                raise ValueError("Selected choice is outside the requested criteria")
+            result.extend([answer.choice, probability(answer.confidence), *probabilities])
+        else:
+            if not isinstance(answer, ScoreAnswer):
+                raise ValueError("Expected a Score answer")
+            levels = list(question.criteria)
+            probabilities = distribution(answer.probabilities, list(range(len(levels))))
+            if answer.legend != dict(enumerate(levels)):
+                raise ValueError("Score legend differs from the requested levels")
+            score = answer.score
+            expected = math.fsum(i * p for i, p in enumerate(probabilities))
+            if (
+                isinstance(score, bool)
+                or not isinstance(score, (int, float))
+                or not math.isfinite(score)
+                or not 0 <= score <= len(levels) - 1
+                or not math.isclose(
+                    score, expected, rel_tol=0, abs_tol=PROBABILITY_TOLERANCE * len(levels)
+                )
+            ):
+                raise ValueError("Score is not the expected zero-based level")
+            level = max(range(len(levels)), key=probabilities.__getitem__)
+            label = levels[level] if isinstance(levels[level], str) else encode(levels[level])
+            result.extend(
+                [level, label, float(score), probability(answer.confidence), *probabilities]
+            )
+    return tuple(result)

jevframe/_types.py

@@ -0,0 +1,70 @@
+"""Public controls and diagnostics shared by both dataframe integrations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal, TypeAlias
+
+from typesafe_sdk import Choice, JSONContent, Noul, Score
+
+Question: TypeAlias = Noul | Choice | Score
+State: TypeAlias = str | Sequence[str] | Callable[[Mapping[str, Any]], JSONContent]
+Errors: TypeAlias = Literal["raise", "coerce"]
+Nulls: TypeAlias = Literal["include", "skip", "raise"]
+Output: TypeAlias = Literal["columns", "struct"]
+
+
+@dataclass(frozen=True)
+class Progress:
+    """A completion snapshot. Counts refer to rows, never request attempts.
+
+    ``cache_hits`` includes rows sharing another row's in-flight request.
+    Successful rows equal ``completed - failed - skipped``.
+    """
+
+    completed: int
+    total: int
+    failed: int = 0
+    skipped: int = 0
+    cache_hits: int = 0
+
+
+ProgressCallback: TypeAlias = Callable[[Progress], None]
+
+
+@dataclass(frozen=True)
+class RowFailure:
+    """A failed inference at a zero-based position in the evaluated dataframe."""
+
+    position: int
+    cause: Exception
+
+
+class EvaluationError(RuntimeError):
+    """A row failed inference, validation, or context construction.
+
+    ``position`` is authoritative even with duplicate indexes. The underlying
+    exception is available as ``cause`` and through exception chaining.
+    """
+
+    def __init__(self, position: int, cause: Exception, *, phase: str = "inference"):
+        self.position = position
+        self.cause = cause
+        self.phase = phase
+        # Avoid copying SDK response bodies or user context into our diagnostics.
+        super().__init__(f"Row {position}: {phase} failed ({type(cause).__name__})")
+
+
+class EvaluationWarning(UserWarning):
+    """Coerced row failures. Inspect ``failures`` for positions and causes."""
+
+    def __init__(self, failures: Sequence[RowFailure]):
+        self.failures = tuple(sorted(failures, key=lambda failure: failure.position))
+        positions = ", ".join(str(f.position) for f in self.failures[:10])
+        if len(self.failures) > 10:
+            positions += ", …"
+        super().__init__(
+            f"Inference failed for {len(self.failures)} row(s) at positions {positions}; "
+            "all results for these rows are missing. Inspect .failures for causes."
+        )

jevframe/pandas.py

@@ -0,0 +1,73 @@
+"""Import this module to register ``pandas.DataFrame.jev``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import numpy as np
+    import pandas as pd
+except ImportError as error:
+    raise ImportError("Install jevframe[pandas] to use the pandas integration") from error
+
+from ._accessor import BaseAccessor
+from ._context import RowSource, selected_columns
+from ._schema import QuestionPlan, pack_rows
+from ._types import Output, State
+
+
+def _scalar(value: Any) -> Any:
+    if value is pd.NA or value is pd.NaT:
+        return None
+    if isinstance(value, (np.datetime64, np.timedelta64)):
+        if np.isnat(value):
+            return None
+        if isinstance(value, np.datetime64):
+            return str(value)
+        return pd.Timedelta(value).isoformat()
+    if isinstance(value, pd.Timedelta):
+        return value.isoformat()
+    if isinstance(value, np.generic):
+        return value.item()
+    if isinstance(value, np.ndarray):
+        return list(value) if value.ndim else _scalar(value[()])
+    return value
+
+
+@pd.api.extensions.register_dataframe_accessor("jev")
+class JevAccessor(BaseAccessor[pd.DataFrame, pd.Series]):
+    """Async semantic operations preserving pandas row positions and indexes."""
+
+    def __init__(self, frame: pd.DataFrame):
+        self._data = frame
+
+    def _source(self, state: State) -> RowSource:
+        columns = selected_columns(list(self._data.columns), state)
+        data = self._data.loc[:, columns]
+        rows = (
+            dict(zip(columns, row, strict=True)) for row in data.itertuples(index=False, name=None)
+        )
+        if not columns:
+            # itertuples(index=False) yields no rows when there are no columns.
+            rows = ({} for _ in range(len(data)))
+        return RowSource(rows, len(data), _scalar, self._data.index.copy(deep=True))
+
+    def _frame(
+        self, values: list[tuple[Any, ...]], plan: QuestionPlan, source: RowSource, output: Output
+    ) -> pd.DataFrame:
+        types = {"float": "float64", "int": "Int64", "str": "string"}
+        if output == "struct":
+            return pd.DataFrame(
+                {"result": pd.array(pack_rows(values, plan), dtype="object")}, index=source.index
+            )
+        # Arrays, not index-keyed dicts/Series: duplicate index labels must not align.
+        arrays = {
+            column.name: pd.array([row[i] for row in values], dtype=types[column.kind])
+            for i, column in enumerate(plan.columns)
+        }
+        return pd.DataFrame(arrays, index=source.index)
+
+    def _series(self, values: list[tuple[Any, ...]], source: RowSource) -> pd.Series:
+        return pd.Series(
+            [row[0] for row in values], index=source.index, dtype="float64", name="probability"
+        )

jevframe/polars.py

@@ -0,0 +1,85 @@
+"""Import this module to register eager ``polars.DataFrame.jev``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import polars as pl
+except ImportError as error:
+    raise ImportError("Install jevframe[polars] to use the Polars integration") from error
+
+from ._accessor import BaseAccessor
+from ._context import RowSource, selected_columns
+from ._schema import QuestionPlan, pack_rows
+from ._types import Output, State
+
+
+def _duration(value: int, unit: str) -> str:
+    nanos = value * {"ns": 1, "us": 1_000, "ms": 1_000_000}[unit]
+    sign = "-" if nanos < 0 else ""
+    seconds, fractional = divmod(abs(nanos), 1_000_000_000)
+    return f"{sign}PT{seconds}.{fractional:09d}S"
+
+
+def _lossless_temporal(expr: pl.Expr, dtype: pl.DataType) -> pl.Expr:
+    # iter_rows converts temporal values to Python, which truncates nanoseconds.
+    # Convert before extraction, including temporal values nested in containers.
+    if isinstance(dtype, pl.Datetime):
+        fmt = "%Y-%m-%dT%H:%M:%S%.f" + ("%:z" if dtype.time_zone else "")
+        return expr.dt.to_string(fmt)
+    if dtype == pl.Time:
+        return expr.dt.to_string("%H:%M:%S%.f")
+    if isinstance(dtype, pl.Duration):
+        return expr.cast(pl.Int64).map_elements(
+            lambda value: _duration(value, dtype.time_unit), return_dtype=pl.String
+        )
+    if isinstance(dtype, pl.List):
+        return expr.list.eval(_lossless_temporal(pl.element(), dtype.inner))
+    if isinstance(dtype, pl.Array):
+        return expr.arr.to_list().list.eval(_lossless_temporal(pl.element(), dtype.inner))
+    if isinstance(dtype, pl.Struct):
+        if not dtype.fields:
+            return expr
+        fields = [
+            _lossless_temporal(expr.struct.field(field.name), field.dtype).alias(field.name)
+            for field in dtype.fields
+        ]
+        return pl.when(expr.is_null()).then(None).otherwise(pl.struct(fields))
+    return expr
+
+
+@pl.api.register_dataframe_namespace("jev")
+class JevNamespace(BaseAccessor[pl.DataFrame, pl.Series]):
+    """Async semantic operations for eager Polars; outputs stay native."""
+
+    def __init__(self, frame: pl.DataFrame):
+        self._data = frame
+
+    def _source(self, state: State) -> RowSource:
+        columns = selected_columns(self._data.columns, state)
+        data = self._data.select(
+            _lossless_temporal(pl.col(name), self._data.schema[name]).alias(name)
+            for name in columns
+        )
+        rows = (dict(zip(columns, row, strict=True)) for row in data.iter_rows())
+        return RowSource(rows, data.height)
+
+    def _frame(
+        self, values: list[tuple[Any, ...]], plan: QuestionPlan, source: RowSource, output: Output
+    ) -> pl.DataFrame:
+        types = {"float": pl.Float64, "int": pl.Int64, "str": pl.String}
+        if output == "struct":
+            dtype = pl.Struct({column.name: types[column.kind] for column in plan.columns})
+            return pl.DataFrame(pl.Series("result", pack_rows(values, plan), dtype=dtype))
+        return pl.DataFrame(
+            {
+                column.name: pl.Series(
+                    column.name, [row[i] for row in values], dtype=types[column.kind]
+                )
+                for i, column in enumerate(plan.columns)
+            }
+        )
+
+    def _series(self, values: list[tuple[Any, ...]], source: RowSource) -> pl.Series:
+        return pl.Series("probability", [row[0] for row in values], dtype=pl.Float64)

jevframe-0.1.0.dist-info/METADATA

@@ -0,0 +1,289 @@
+Metadata-Version: 2.5
+Name: jevframe
+Version: 0.1.0
+Summary: Typed semantic decisions for pandas and Polars with TypeSafe Jev
+Project-URL: Repository, https://github.com/ktaletsk/jevframe
+Project-URL: Issues, https://github.com/ktaletsk/jevframe/issues
+Author: Konstantin Taletskiy
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: tqdm<5,>=4.66
+Requires-Dist: typesafe-sdk<0.8,>=0.7
+Provides-Extra: examples
+Requires-Dist: altair<7,>=5; extra == 'examples'
+Requires-Dist: marimo<1,>=0.19; extra == 'examples'
+Requires-Dist: pandas<4,>=2.2; extra == 'examples'
+Provides-Extra: pandas
+Requires-Dist: pandas<4,>=2.2; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars<2,>=1; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# jevframe
+
+[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/github/ktaletsk/jevframe/blob/main/examples/reviews.py)
+
+Ask the same semantic questions about every row of a dataframe using
+[TypeSafe Jev](https://docs.typesafe.ai/). Get ordinary pandas or Polars results,
+with bounded async inference and complete probability distributions.
+
+## Install
+
+```sh
+uv add 'jevframe[pandas]==0.1.0'     # in your uv project
+# Or: uv add 'jevframe[polars]==0.1.0' / 'jevframe[pandas,polars]==0.1.0'
+export TYPESAFE_API_KEY='your-key'
+```
+
+Python 3.10+; the official `typesafe-sdk>=0.7,<0.8` handles inference. Dataframe
+dependencies are optional. Importing an integration registers its `.jev` accessor.
+
+On **molab**, open the notebook's **Secrets** sidebar panel and add
+`TYPESAFE_API_KEY` with your key as its value. molab loads it automatically and
+persists it between sessions; `.env` secrets are excluded from forks.
+[Molab's secrets documentation](https://marimo.io/pages/molab/storage#secrets-stay-with-your-notebook).
+Then click **Evaluate reviews** in the demo. You do not need to put the key in a code cell.
+
+## pandas
+
+These examples use notebook top-level `await`. In a script, put them inside an
+`async def main()` and call `asyncio.run(main())`.
+
+```python
+import pandas as pd
+import jevframe.pandas
+from typesafe_sdk import Choice, Noul
+
+df = pd.DataFrame(
+    {
+        "title": ["Charged twice", "Great update"],
+        "review": ["Please refund the duplicate charge today.", "Everything works well!"],
+    }
+)
+
+df["dissatisfied"] = await df.jev.noul(
+    "Is this customer dissatisfied?",
+    state=["title", "review"],
+)
+
+topics = await df.jev.choice(
+    "What is the main issue?",
+    choices=["billing", "bug", "other"],
+    state="review",
+)
+
+grades = await df.jev.score(
+    "How positive is this review?",
+    levels=["Negative", "Neutral", "Positive"],
+    state="review",
+)
+
+results = await df.jev.evaluate(
+    state=["title", "review"],
+    questions={
+        "urgent": Noul(instructions="Does the customer need help today?"),
+        "topic": Choice(
+            instructions="What is the main issue?",
+            criteria={"billing": "Charges and refunds", "bug": "Broken behavior", "other": None},
+        ),
+    },
+)
+```
+
+| Method | Result columns |
+| --- | --- |
+| `noul` | Series named `probability`, the probability of yes |
+| `choice` | `label`, `confidence`, `p__billing`, `p__bug`, … |
+| `score` | `level`, `label`, `score`, `confidence`, `p__0`, `p__1`, … |
+| `evaluate` | Fields prefixed by question name, e.g. `urgent__probability`, `topic__p__billing` |
+
+`score` is the expected **zero-based** level, not a probability: with five levels it
+ranges from 0 to 4. `level`/`label` identify the highest-probability level, with ties
+resolved by level order. Structured SDK level descriptions appear as JSON text in
+`label`. Confidence comes from the SDK; it is separate from the selected option's
+probability. No result is thresholded or silently renormalized.
+
+Question and criterion order determine column order. Row order and pandas indexes,
+including duplicates and MultiIndexes, are preserved. The input is never mutated.
+
+### Output layout
+
+`choice`, `score`, and `evaluate` accept `output="columns"` (the default) or
+`output="struct"`. Both return a DataFrame with one row per input row.
+The struct layout has a single column named `result`: dictionaries in pandas
+(`object` dtype), or a native `Struct` in Polars. Its fields have exactly the same
+names, order, and values as the separate columns, including all probabilities.
+`evaluate` keeps question prefixes inside the struct too.
+
+```python
+packed = await df.jev.evaluate(
+    state="review",
+    questions={
+        "dissatisfied": Noul(instructions="Is this customer dissatisfied?"),
+        "urgent": Noul(instructions="Does the customer need help today?"),
+    },
+    output="struct",
+)
+df["decisions"] = packed["result"]
+# Each successful cell: {"dissatisfied__probability": 0.9, "urgent__probability": 0.8}
+# Illustrative probabilities; actual values come from Jev.
+```
+
+Failed or skipped rows have a missing `result` cell (`None` in pandas, null in
+Polars). Empty results retain their output dtype, including the full Polars struct
+schema. Layout affects only presentation: switching it makes no extra requests
+when you reuse a cache. `noul` always returns its single probability Series.
+
+## How requests and results map to rows
+
+The engine sends **one input row per request**, with up to 16 row requests in flight
+by default (`max_concurrency`). With `evaluate()`, every question about that row
+shares the same context and request. Different rows are evaluated independently.
+
+For example, 100 rows with three questions produce 100 initial requests and 100
+result rows, with answers in separate columns or one structured column. Retries can add
+requests; skipped or cached rows need none. This does not expand one input row
+into multiple generated records. The demo evaluates dissatisfaction, urgency,
+and topic together for each review.
+
+## Row selection and context
+
+Select rows with the dataframe library before evaluation:
+
+```python
+subset = await df.iloc[:10].jev.noul("Is this urgent?", state="review")
+
+custom = await df.jev.noul(
+    "Is this urgent?",
+    state=lambda row: {"text": f"{row['title']}: {row['review']}"},
+)
+```
+
+`state="review"` sends `{"review": value}`; a list sends those named columns.
+Indexes are never sent implicitly. Selected column names must be unique strings;
+unrelated duplicate columns are allowed. A synchronous context callable receives
+a detached mapping of all columns and returns text, an object, or an array. It
+runs once per row before cache lookup. Polars temporal values in these mappings
+are ISO strings to retain nanosecond precision.
+
+Missing scalars become JSON null; lists and objects are normalized recursively.
+Dates/times become ISO text. Unsupported objects and infinities raise a row-aware
+context error. Supply a callable to convert custom values. Context errors always
+raise, even under `errors="coerce"`.
+
+## Eager Polars
+
+```python
+import polars as pl
+import jevframe.polars
+
+df = pl.DataFrame({"review": ["Charged twice", "Works perfectly"]})
+probabilities = await df.jev.noul("Is this customer dissatisfied?", state="review")
+df = df.with_columns(probabilities.alias("dissatisfied"))
+topics = await df.filter(pl.col("dissatisfied") > 0.5).jev.choice(
+    "What is the issue?",
+    choices=["billing", "bug", "other"],
+    state="review",
+)
+```
+
+The API and columns match pandas; outputs are native `pl.Series`/`pl.DataFrame`.
+Polars uses nulls for missing results; pandas uses NaN for floating outputs and
+native nullable string/integer columns. Empty outputs retain their schemas.
+LazyFrame expressions are outside v0.
+
+## Controls, errors, and caching
+
+Every method accepts these keyword arguments:
+
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `client` | `None` | Reuse an official `AsyncTypeSafeClient`; caller owns its lifetime |
+| `model` | `None` | Inherit SDK client/environment default (`jev-latest` otherwise) |
+| `max_concurrency` | `16` | Maximum simultaneous row evaluations, including retries |
+| `cache` | `None` | Opt in with a reusable `MemoryCache` |
+| `progress` | `False` | `True` for tqdm, or a synchronous `Progress` callback |
+| `errors` | `"raise"` | `"coerce"` returns missing results and an `EvaluationWarning` |
+| `nulls` | `"include"` | `"skip"` skips rows with any null context; `"raise"` rejects them |
+
+Null policy applies **after** constructing context, including nested nulls. A row
+failure makes every question result for that row missing. `EvaluationError.position`
+and `.cause`, or `EvaluationWarning.failures` (`RowFailure.position`/`.cause`), identify
+failures without confusing duplicate index labels. Positions refer to the evaluated
+frame, starting at zero. Inspect warnings with `warnings.catch_warnings(record=True)`.
+Progress snapshots expose `completed`, `total`, `failed`, `skipped`, and `cache_hits`.
+Callback exceptions and cancellation propagate, and outstanding workers are drained.
+
+All questions for a row share one request. SDK retries handle transient failures and
+backoff (two retries by default); configure its policy and timeouts directly:
+
+```python
+from jevframe import MemoryCache
+from typesafe_sdk import AsyncTypeSafeClient, RetryPolicy
+
+cache = MemoryCache(max_entries=10_000)
+async with AsyncTypeSafeClient(timeout=30, retry=RetryPolicy(max_retries=3)) as client:
+    result = await df.jev.noul(
+        "Is this urgent?",
+        state="review",
+        client=client,
+        max_concurrency=8,
+        cache=cache,
+        progress=True,
+    )
+```
+
+The memory cache stores only successful, validated complete responses, including
+all probabilities. Identical in-flight rows within one evaluation share a request.
+Questions, criteria order, context, model, and client/configuration identity affect
+cache keys; indexes do not. Supplied clients have separate cache namespaces. Default
+clients reuse entries across calls when their environment configuration matches.
+There is no disk cache. Model aliases can change: use a pinned model for reproducible
+work and `cache.clear()` when fresh results are needed.
+
+No API call runs merely by importing the library. Evaluation sends the chosen
+context to TypeSafe. Late context errors can occur after other rows have completed;
+completed requests cannot be undone. Credentials are read from the environment or
+the SDK client; the library does not discover or load dotenv files.
+
+## marimo example and development
+
+From a checkout:
+
+```sh
+# For library development only: uv sync --extra pandas (or --extra polars)
+uv sync --extra examples
+uv run marimo edit examples/reviews.py
+```
+
+Edit the three questions, choose an output layout, and click **Evaluate reviews**
+to see the results and probability histograms. The eight synthetic reviews need eight initial
+requests, each containing all three questions; repeated evaluations reuse the cache.
+The example makes no requests until the button is clicked and a key is configured.
+
+The badge opens the GitHub notebook preview. Fork it into your molab workspace to
+add your own secret and run it on a server. The notebook includes inline dependency
+metadata that installs `jevframe[pandas]==0.1.0` from PyPI. The badge requires the
+notebook to be available on this repository's `main` branch.
+
+For development checks, install all extras:
+
+```sh
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run marimo check --strict examples/reviews.py
+uv build
+```
+
+Tests use the official SDK with mocked HTTP transport; no API key or live calls
+are required. v0 focuses on row-wise decisions, with no chat interface, automatic
+analysis, generated code, custom dtypes, Excel integration, or provider framework.

jevframe-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+jevframe/__init__.py,sha256=X3DuHbP91raH8AbGZbFvqtllQYkDJ7u5OD6LFDINA4c,344
+jevframe/_accessor.py,sha256=36ekzb-jTdlQLXODUwyqT4nt1L5-Dnzw3_QZdOEAM0s,4897
+jevframe/_cache.py,sha256=8j2pCU7TK92pMUKPkT1dpkwjIEBoa672u1NRMEASKnI,2312
+jevframe/_context.py,sha256=dVl9aYV4Ezn6rJcSPWz0iqVT3RtcKY00hVq-iOTc0nM,4064
+jevframe/_engine.py,sha256=Wp4kQbzxXr_Qre_57zYDjmlGxfTPl6Ac2piXjbc9HcA,8347
+jevframe/_schema.py,sha256=xNofkvl717Nhu_w9SPgX0hgTCGAwsMgnTwNv1LgX7pc,8186
+jevframe/_types.py,sha256=RzyLEtb3LaKfGJnsjPvY8vlmAItzHnW3kbOVnOQWPAU,2396
+jevframe/pandas.py,sha256=45_GFtL_IejrYqlQTJjDjEOD2nbV080Py6oJjWoaKDc,2762
+jevframe/polars.py,sha256=o9ZqAkxUhOdS7MssfSvA2ZpSkGA59gDilJXUD31PVAA,3445
+jevframe/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jevframe-0.1.0.dist-info/METADATA,sha256=mt87cl3blS_ZrLjAKBXotMEcPPBGLRhWpDljwyuoCkU,11931
+jevframe-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+jevframe-0.1.0.dist-info/licenses/LICENSE,sha256=hxDP0vRWF0rfwJfmoycmbVnE92XOZpn0kNQ7kY9lnYo,1077
+jevframe-0.1.0.dist-info/RECORD,,

jevframe-0.1.0.dist-info/WHEEL

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

jevframe-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantin Taletskiy
+
+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.