assay-engine 0.5.0.dev2__py3-none-any.whl

assay/__init__.py

@@ -0,0 +1,83 @@
+"""Assay combines heterogeneous measurements into explainable scores."""
+
+from __future__ import annotations
+
+from assay._version import __version__
+from assay.compose import compose
+from assay.contracts import (
+    AdditiveRequest,
+    AdditiveTerm,
+    ClampPolicy,
+    Component,
+    Direction,
+    ExplainedComponent,
+    Interval,
+    Method,
+    MinimumRequest,
+    NativeScale,
+    Operation,
+    ScoreRequest,
+    ScoreResult,
+    WeightedMeanRequest,
+    parse_request,
+    parse_request_json,
+)
+from assay.errors import ContractValidationError
+from assay.measurement import (
+    AgreementMeasurementRequest,
+    AgreementMeasurementResult,
+    BinaryMeasurementRequest,
+    BinaryMeasurementResult,
+    BinaryMetricControls,
+    MeasurementRequest,
+    MeasurementResult,
+    OrdinalRating,
+    RankingMeasurementRequest,
+    RankingMeasurementResult,
+    RankingMetricControls,
+    RankingQueryInput,
+    RelevanceInput,
+    UncertaintyControls,
+    measure,
+    parse_measurement_json,
+)
+from assay.normalize import normalize
+
+__all__ = [
+    "AdditiveRequest",
+    "AdditiveTerm",
+    "AgreementMeasurementRequest",
+    "AgreementMeasurementResult",
+    "BinaryMeasurementRequest",
+    "BinaryMeasurementResult",
+    "BinaryMetricControls",
+    "ClampPolicy",
+    "Component",
+    "ContractValidationError",
+    "Direction",
+    "ExplainedComponent",
+    "Interval",
+    "MeasurementRequest",
+    "MeasurementResult",
+    "Method",
+    "MinimumRequest",
+    "NativeScale",
+    "Operation",
+    "OrdinalRating",
+    "RankingMeasurementRequest",
+    "RankingMeasurementResult",
+    "RankingMetricControls",
+    "RankingQueryInput",
+    "RelevanceInput",
+    "ScoreRequest",
+    "ScoreResult",
+    "UncertaintyControls",
+    "WeightedMeanRequest",
+    "__version__",
+    "compose",
+    "measure",
+    "normalize",
+    "parse_measurement_json",
+    "parse_request",
+    "parse_request_json",
+]

assay/_cli_app.py

@@ -0,0 +1,102 @@
+"""Typer-backed scoring commands, loaded only after migration dispatch."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+from typer._click.exceptions import ClickException
+
+from assay._cli_io import json_bytes, read_input, write_output
+from assay.compose import compose
+from assay.contracts import ExplainedComponent, Interval, ScoreResult, parse_request_json
+from assay.errors import CliInputInvalid
+from assay.measurement import measure, parse_measurement_json
+
+app = typer.Typer(add_completion=False, no_args_is_help=False, pretty_exceptions_enable=False)
+
+
+@app.callback()
+def root() -> None:
+    """Combine or inspect typed measurements."""
+
+
+@app.command("compose")
+def compose_command(
+    request: Annotated[str, typer.Option("--request")],
+    out: Annotated[str | None, typer.Option("--out")] = None,
+) -> None:
+    """Compose one validated scoring request."""
+    source = read_input(request)
+    result = compose(parse_request_json(source))
+    write_output(json_bytes(result), out, request)
+
+
+@app.command("measure")
+def measure_command(
+    request: Annotated[str, typer.Option("--request")],
+    out: Annotated[str | None, typer.Option("--out")] = None,
+) -> None:
+    """Run one typed optional measurement family."""
+    source = read_input(request)
+    result = measure(parse_measurement_json(source))
+    write_output(json_bytes(result), out, request)
+
+
+def _number(value: float | None) -> str:
+    return "none" if value is None else json.dumps(value, allow_nan=False)
+
+
+def _interval(interval: Interval | None) -> str:
+    if interval is None:
+        return "deterministic"
+    return f"[{_number(interval.low)}, {_number(interval.high)}]"
+
+
+def _selection(component: ExplainedComponent, selected: str | None) -> str:
+    if selected is None:
+        return ""
+    return f"; selected={'yes' if component.id == selected else 'no'}"
+
+
+def _component_line(index: int, row: ExplainedComponent, selected: str | None) -> str:
+    values = (
+        f"raw={_number(row.raw)}; normalized={_number(row.normalized)}",
+        f"operation={row.operation}; coefficient={_number(row.coefficient)}",
+        f"contribution={_number(row.contribution)}{_selection(row, selected)}",
+    )
+    return f"{index}. {row.id}: {'; '.join(values)}"
+
+
+def _explanation(result: ScoreResult) -> str:
+    lines = [
+        "Assay score explanation",
+        f"Method: {result.method.id}@{result.method.version}",
+        f"Score: {_number(result.score)}",
+        f"Interval: {_interval(result.interval)}",
+        "Components:",
+    ]
+    rows = enumerate(result.components, start=1)
+    lines.extend(_component_line(index, row, result.selected_component_id) for index, row in rows)
+    return "\n".join(lines) + "\n"
+
+
+@app.command("explain")
+def explain_command(
+    result: Annotated[str, typer.Option("--result")],
+    out: Annotated[str | None, typer.Option("--out")] = None,
+) -> None:
+    """Replay result invariants and render deterministic arithmetic."""
+    validated = ScoreResult.model_validate_json(read_input(result))
+    write_output(_explanation(validated).encode("utf-8"), out, result)
+
+
+def run(arguments: tuple[str, ...]) -> int:
+    """Run Typer without allowing its usage rendering to cross the boundary."""
+    try:
+        app(args=list(arguments), standalone_mode=False)
+    except (ClickException, SystemExit, ValidationError, RecursionError):
+        raise CliInputInvalid from None
+    return 0

assay/_cli_io.py

@@ -0,0 +1,130 @@
+"""Value-redacted input and output primitives for the command adapter."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import tempfile
+import unicodedata
+from pathlib import Path
+from typing import Final, Protocol
+
+from assay.errors import CliInputInvalid, CliOutputInvalid
+
+_MAX_INPUT_BYTES: Final[int] = 1_048_576
+_READ_CHUNK_BYTES: Final[int] = 65_536
+
+
+class JsonModel(Protocol):
+    """The one serialization operation needed by the CLI."""
+
+    def model_dump_json(self, *, by_alias: bool) -> str: ...
+
+
+def _read_chunks(descriptor: int) -> bytes:
+    chunks: list[bytes] = []
+    total = 0
+    while chunk := os.read(descriptor, _READ_CHUNK_BYTES):
+        total += len(chunk)
+        if total > _MAX_INPUT_BYTES:
+            raise CliInputInvalid
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def _read_regular(descriptor: int) -> bytes:
+    if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+        raise CliInputInvalid
+    return _read_chunks(descriptor)
+
+
+def read_input(path: str) -> bytes:
+    """Read one bounded regular file through a single already-open descriptor."""
+    descriptor = -1
+    try:
+        descriptor = os.open(path, os.O_RDONLY | os.O_CLOEXEC | os.O_NONBLOCK)
+        return _read_regular(descriptor)
+    except OSError:
+        raise CliInputInvalid from None
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+
+
+def json_bytes(model: JsonModel) -> bytes:
+    """Serialize exactly once and terminate the public JSON stream with one LF."""
+    return model.model_dump_json(by_alias=True).encode("utf-8") + b"\n"
+
+
+def _normalized_path(path: Path) -> str:
+    resolved = str(path.resolve(strict=False))
+    return unicodedata.normalize("NFC", resolved).casefold()
+
+
+def _same_existing(first: Path, second: Path) -> bool:
+    try:
+        return first.samefile(second)
+    except OSError:
+        return False
+
+
+def _reject_alias(source: Path, destination: Path) -> None:
+    if _same_existing(source, destination):
+        raise CliOutputInvalid
+    if _normalized_path(source) == _normalized_path(destination):
+        raise CliOutputInvalid
+
+
+def _require_destination(destination: Path) -> None:
+    parent = destination.parent.resolve(strict=True)
+    if not parent.is_dir():
+        raise CliOutputInvalid
+    if destination.is_symlink():
+        raise CliOutputInvalid
+    if destination.exists() and not destination.is_file():
+        raise CliOutputInvalid
+
+
+def _flush_file(descriptor: int, payload: bytes) -> None:
+    with os.fdopen(descriptor, "wb") as stream:
+        stream.write(payload)
+        stream.flush()
+        os.fsync(stream.fileno())
+
+
+def _flush_parent(parent: Path) -> None:
+    descriptor = os.open(parent, os.O_RDONLY | os.O_CLOEXEC)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def _install(payload: bytes, destination: Path) -> None:
+    descriptor, stage = tempfile.mkstemp(prefix=".assay-", dir=destination.parent)
+    try:
+        _flush_file(descriptor, payload)
+        os.replace(stage, destination)
+        _flush_parent(destination.parent)
+    finally:
+        Path(stage).unlink(missing_ok=True)
+
+
+def _write_file(payload: bytes, destination: str, source: str) -> None:
+    output = Path(destination)
+    try:
+        _reject_alias(Path(source), output)
+        _require_destination(output)
+        _install(payload, output)
+    except OSError:
+        raise CliOutputInvalid from None
+
+
+def write_output(payload: bytes, destination: str | None, source: str) -> None:
+    """Write exact bytes to stdout or install them crash-safely beside the destination."""
+    if destination is not None:
+        _write_file(payload, destination, source)
+        return
+    sys.stdout.buffer.write(payload)
+    sys.stdout.buffer.flush()

assay/_json.py

@@ -0,0 +1,34 @@
+"""Dependency-light JSON decoding that rejects ambiguous object members."""
+
+from __future__ import annotations
+
+import json
+
+from assay.errors import AssayError, ContractCode, ContractValidationError
+
+type JsonData = str | bytes | bytearray
+
+
+class _DuplicateMemberError(Exception):
+    """Private control flow for a repeated decoded object key."""
+
+
+def _unique_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise _DuplicateMemberError
+        result[key] = value
+    return result
+
+
+def decode_json(data: JsonData, invalid_error: type[AssayError]) -> object:
+    """Decode one JSON value without last-wins member collapse or raw exceptions."""
+    error: AssayError
+    try:
+        return json.loads(data, object_pairs_hook=_unique_object)
+    except _DuplicateMemberError:
+        error = ContractValidationError(ContractCode.DUPLICATE_FIELD)
+    except (ValueError, UnicodeDecodeError, TypeError, RecursionError):
+        error = invalid_error()
+    raise error from None

assay/_optional.py

@@ -0,0 +1,69 @@
+"""Lazy, redacted boundary for Assay's optional metric dependencies."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import cache
+from importlib import import_module
+from types import ModuleType
+from typing import cast
+
+from assay.errors import MetricsExtraMissing
+
+type OptionalCallable = Callable[..., object]
+
+_FAILED = object()
+
+
+def _try_import(name: str) -> ModuleType | None:
+    try:
+        return import_module(name)
+    except Exception:
+        return None
+
+
+@cache
+def load_module(name: str) -> ModuleType:
+    """Load one exact optional module, caching successful imports only."""
+    module = _try_import(name)
+    if module is None:
+        raise MetricsExtraMissing
+    return module
+
+
+def _try_attribute(module: ModuleType, name: str) -> object:
+    try:
+        return getattr(module, name)
+    except Exception:
+        return _FAILED
+
+
+@cache
+def load_object(module_name: str, name: str) -> object:
+    """Load one exact dependency attribute, never caching a missing attribute."""
+    value = _try_attribute(load_module(module_name), name)
+    if value is _FAILED:
+        raise MetricsExtraMissing
+    return value
+
+
+@cache
+def load_callable(module_name: str, name: str) -> OptionalCallable:
+    """Load one exact dependency callable, caching only a callable result."""
+    value = load_object(module_name, name)
+    if not callable(value):
+        raise MetricsExtraMissing
+    return cast(OptionalCallable, value)
+
+
+def call_dependency(function: OptionalCallable, *args: object, **kwargs: object) -> object:
+    """Call a dependency without allowing its private exception to cross the boundary."""
+    try:
+        return function(*args, **kwargs)
+    except Exception:
+        return _FAILED
+
+
+def dependency_failed(value: object) -> bool:
+    """Return whether a redacted dependency invocation failed."""
+    return value is _FAILED

assay/_version.py

@@ -0,0 +1,5 @@
+"""Single source of truth for the Assay Python distribution version."""
+
+from __future__ import annotations
+
+__version__ = "0.5.0.dev2"

assay/additive.py

@@ -0,0 +1,104 @@
+"""Declared-order additive and subtractive score composition."""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+from assay.composite import canonical_zero, finite_output, inputs_hash, interval_or_none
+from assay.contracts import (
+    AdditiveRequest,
+    AdditiveTerm,
+    ClampPolicy,
+    ExplainedComponent,
+    Interval,
+    Method,
+    Operation,
+    ScoreResult,
+)
+from assay.errors import ContractCode, ContractValidationError
+
+
+def _fail(code: ContractCode) -> NoReturn:
+    raise ContractValidationError(code) from None
+
+
+def _contribution(term: AdditiveTerm, value: float | None = None) -> float:
+    raw = term.value if value is None else value
+    return finite_output(raw * term.coefficient)
+
+
+def _apply(total: float, contribution: float, operation: Operation) -> float:
+    if operation is Operation.ADD:
+        return finite_output(total + contribution)
+    return finite_output(total - contribution)
+
+
+def _final(value: float, policy: ClampPolicy | None) -> float:
+    result = finite_output(value)
+    if policy is None:
+        return result
+    if policy is ClampPolicy.CLAMP:
+        return canonical_zero(min(1.0, max(0.0, result)))
+    if not 0.0 <= result <= 1.0:
+        _fail(ContractCode.OUT_OF_RANGE)
+    return result
+
+
+def _explain(term: AdditiveTerm) -> ExplainedComponent:
+    return ExplainedComponent(
+        id=term.id,
+        raw=term.value,
+        normalized=None,
+        declared_weight=None,
+        operation=term.operation,
+        coefficient=term.coefficient,
+        contribution=_contribution(term),
+        contribution_interval=interval_or_none(*_term_bounds(term)),
+    )
+
+
+def _point(request: AdditiveRequest, rows: tuple[ExplainedComponent, ...]) -> float:
+    total = finite_output(request.intercept)
+    for row in rows:
+        total = _apply(total, row.contribution, row.operation)
+    return _final(total, request.clamp)
+
+
+def _term_bounds(term: AdditiveTerm) -> tuple[float, float]:
+    if term.interval is None:
+        contribution = _contribution(term)
+        return contribution, contribution
+    return _contribution(term, term.interval.low), _contribution(term, term.interval.high)
+
+
+def _advance_bounds(low: float, high: float, term: AdditiveTerm) -> tuple[float, float]:
+    term_low, term_high = _term_bounds(term)
+    if term.operation is Operation.ADD:
+        return finite_output(low + term_low), finite_output(high + term_high)
+    return finite_output(low - term_high), finite_output(high - term_low)
+
+
+def _result_interval(request: AdditiveRequest) -> Interval | None:
+    if not any(term.interval is not None for term in request.terms):
+        return None
+    low = high = finite_output(request.intercept)
+    for term in request.terms:
+        low, high = _advance_bounds(low, high, term)
+    return interval_or_none(_final(low, request.clamp), _final(high, request.clamp))
+
+
+def additive(request: AdditiveRequest) -> ScoreResult:
+    """Compose an explicit left-to-right sum with an optional final unit bound."""
+    validated = AdditiveRequest.model_validate(request)
+    rows = tuple(_explain(term) for term in validated.terms)
+    return ScoreResult(
+        method=Method(id=validated.method, version=validated.method_version),
+        score=_point(validated, rows),
+        interval=_result_interval(validated),
+        clamp=validated.clamp,
+        intercept=validated.intercept,
+        weight_total=None,
+        components=rows,
+        inputs_hash=inputs_hash(validated),
+        selected_component_id=None,
+    )