semantic-python 0.1.0a1__py3-none-any.whl

semantic_python/__init__.py

@@ -0,0 +1,50 @@
+"""Opt-in semantic values for ordinary Python syntax."""
+
+from .backends import (
+    BackendBase,
+    DecisionBackend,
+    FakeBackend,
+    LayaBackend,
+    OpenAIBackend,
+)
+from .cache import MemoryDecisionCache, decision_cache_key, state_digest
+from .config import Config, configuration, configure, get_config, reset_config
+from .decision import (
+    BackendError,
+    ConfigurationError,
+    Decision,
+    InvalidComparisonError,
+    SemanticError,
+    TruthPolicy,
+    UncertainDecisionError,
+    UncertaintyPolicy,
+)
+from .replay import DecisionRecorder, ReplayBackend
+from .semantic import Semantic
+
+__all__ = [
+    "BackendBase",
+    "BackendError",
+    "Config",
+    "ConfigurationError",
+    "Decision",
+    "DecisionBackend",
+    "DecisionRecorder",
+    "FakeBackend",
+    "InvalidComparisonError",
+    "LayaBackend",
+    "MemoryDecisionCache",
+    "OpenAIBackend",
+    "ReplayBackend",
+    "Semantic",
+    "SemanticError",
+    "TruthPolicy",
+    "UncertainDecisionError",
+    "UncertaintyPolicy",
+    "configuration",
+    "configure",
+    "decision_cache_key",
+    "get_config",
+    "reset_config",
+    "state_digest",
+]

semantic_python/backends/__init__.py

@@ -0,0 +1,12 @@
+from .base import BackendBase, DecisionBackend
+from .fake import FakeBackend
+from .laya import LayaBackend
+from .openai import OpenAIBackend
+
+__all__ = [
+    "BackendBase",
+    "DecisionBackend",
+    "FakeBackend",
+    "LayaBackend",
+    "OpenAIBackend",
+]

semantic_python/backends/base.py

@@ -0,0 +1,31 @@
+"""Backend-neutral semantic decision protocol."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol, runtime_checkable
+
+from ..decision import Decision
+
+
+@runtime_checkable
+class DecisionBackend(Protocol):
+    @property
+    def identity(self) -> str:
+        """Stable backend/model/version identity used by cache keys."""
+
+    def boolean(self, state: str, proposition: str) -> Decision[bool]: ...
+
+    def choice(self, state: str, options: Sequence[str]) -> Decision[str]: ...
+
+    def score(self, state: str, rubric: str) -> Decision[float]: ...
+
+
+class BackendBase:
+    """Convenience base for boolean-only v0.1 backends."""
+
+    def choice(self, state: str, options: Sequence[str]) -> Decision[str]:
+        raise NotImplementedError("choice decisions are not implemented in v0.1")
+
+    def score(self, state: str, rubric: str) -> Decision[float]:
+        raise NotImplementedError("score decisions are not implemented in v0.1")

semantic_python/backends/fake.py

@@ -0,0 +1,66 @@
+"""Deterministic, offline backend for examples and tests."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import TypeAlias
+
+from ..cache import state_digest
+from ..decision import Decision
+from .base import BackendBase
+
+FakeResult: TypeAlias = bool | float | tuple[bool, float]
+
+
+class FakeBackend(BackendBase):
+    def __init__(
+        self,
+        responses: Mapping[tuple[str, str], FakeResult] | None = None,
+        *,
+        default: FakeResult | None = None,
+        resolver: Callable[[str, str], FakeResult] | None = None,
+        name: str = "fake",
+        model: str = "deterministic-v1",
+    ) -> None:
+        self.responses = dict(responses or {})
+        self.default = default
+        self.resolver = resolver
+        self.name = name
+        self.model = model
+        self.calls = 0
+
+    @property
+    def identity(self) -> str:
+        return f"{self.name}:{self.model}"
+
+    def boolean(self, state: str, proposition: str) -> Decision[bool]:
+        self.calls += 1
+        key = (state, proposition)
+        if key in self.responses:
+            result = self.responses[key]
+        elif self.resolver is not None:
+            result = self.resolver(state, proposition)
+        elif self.default is not None:
+            result = self.default
+        else:
+            raise KeyError(f"no fake response for state/proposition: {key!r}")
+        value, probability = self._coerce(result)
+        return Decision(
+            value=value,
+            probability=probability,
+            backend=self.name,
+            model=self.model,
+            proposition=proposition,
+            state_hash=state_digest(state),
+        )
+
+    @staticmethod
+    def _coerce(result: FakeResult) -> tuple[bool, float]:
+        if isinstance(result, tuple):
+            value, probability = result
+        elif isinstance(result, bool):
+            value, probability = result, 1.0 if result else 0.0
+        else:
+            probability = float(result)
+            value = probability >= 0.5
+        return bool(value), float(probability)

semantic_python/backends/laya.py

@@ -0,0 +1,75 @@
+"""Optional adapter for the local Laya decision engine.
+
+Laya is imported and its model is loaded only when the first decision is made.
+Its zero-shot outputs, especially negation, require application-level evaluation;
+they are probabilities, not proof or authorization for consequential actions.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from ..cache import state_digest
+from ..decision import BackendError, Decision
+from .base import BackendBase
+
+
+class LayaBackend(BackendBase):
+    """Use Laya's ``noul`` head for local proposition decisions.
+
+    Pass an injected router in tests or advanced deployments. Otherwise ``laya``
+    is imported lazily; installing the core package does not import torch.
+    """
+
+    def __init__(self, router: Any | None = None, *, model: str | None = None) -> None:
+        self._router = router
+        self.model = model
+        try:
+            self.version = version("laya")
+        except PackageNotFoundError:
+            self.version = "not-installed" if router is None else "injected"
+
+    @property
+    def identity(self) -> str:
+        return f"laya:{self.version}:{self.model or 'auto'}"
+
+    def _get_router(self) -> Any:
+        if self._router is None:
+            try:
+                from laya import Router  # type: ignore[import-not-found]
+            except ImportError as error:
+                raise BackendError("LayaBackend requires the optional 'laya' package") from error
+            self._router = Router()
+        return self._router
+
+    def boolean(self, state: str, proposition: str) -> Decision[bool]:
+        questions = {
+            "decision": {
+                "type": "noul",
+                "instructions": proposition,
+                "criteria": {
+                    "true": proposition,
+                    "false": f"It is not true that: {proposition}",
+                },
+            }
+        }
+        kwargs = {"model": self.model} if self.model is not None else {}
+        try:
+            result = self._get_router().predict(state, questions, **kwargs)
+            probability = float(result["answers"]["decision"]["noul"])
+            routing = result["routing"]
+            routed_model = str(routing["model"])
+        except BackendError:
+            raise
+        except (KeyError, TypeError, ValueError) as error:
+            raise BackendError(f"Laya returned an invalid decision payload: {error}") from error
+        return Decision(
+            value=probability >= 0.5,
+            probability=probability,
+            backend="laya",
+            model=routed_model,
+            proposition=proposition,
+            state_hash=state_digest(state),
+            metadata={"routing": dict(routing), "provider_version": self.version},
+        )

semantic_python/backends/openai.py

@@ -0,0 +1,118 @@
+"""Optional OpenAI Responses API backend."""
+
+from __future__ import annotations
+
+import json
+import os
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from ..cache import state_digest
+from ..decision import BackendError, Decision
+from .base import BackendBase
+
+_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "value": {
+            "type": "boolean",
+            "description": "Whether the proposition is true; true iff probability is at least 0.5.",
+        },
+        "probability": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": (
+                "P(proposition=true), not confidence in the selected boolean value. "
+                "A false value therefore has probability below 0.5."
+            ),
+        },
+    },
+    "required": ["value", "probability"],
+    "additionalProperties": False,
+}
+
+
+class OpenAIBackend(BackendBase):
+    """Remote semantic decisions using OpenAI Structured Outputs.
+
+    ``probability`` is model-reported and must be calibrated on application data
+    before it is used for consequential automation.
+    """
+
+    def __init__(self, client: Any | None = None, *, model: str = "gpt-6-luna") -> None:
+        self._client = client
+        self.model = model
+        try:
+            self.version = version("openai")
+        except PackageNotFoundError:
+            self.version = "not-installed" if client is None else "injected"
+
+    @property
+    def identity(self) -> str:
+        return f"openai:{self.version}:{self.model}"
+
+    def _get_client(self) -> Any:
+        if self._client is None:
+            try:
+                OpenAI = import_module("openai").OpenAI
+            except ImportError as error:
+                raise BackendError(
+                    "OpenAIBackend requires the optional 'openai' package"
+                ) from error
+            if not os.environ.get("OPENAI_API_KEY"):
+                raise BackendError("OpenAIBackend requires OPENAI_API_KEY")
+            self._client = OpenAI()
+        return self._client
+
+    def boolean(self, state: str, proposition: str) -> Decision[bool]:
+        try:
+            response = self._get_client().responses.create(
+                model=self.model,
+                instructions=(
+                    "Decide whether the proposition is true of the supplied state. "
+                    "Return the boolean judgment and your estimated P(proposition=true). "
+                    "Probability always means probability that the proposition is true, "
+                    "not confidence in whichever boolean you select. Set value=true if and "
+                    "only if probability is at least 0.5."
+                ),
+                input=f"State:\n{state}\n\nProposition:\n{proposition}",
+                text={
+                    "format": {
+                        "type": "json_schema",
+                        "name": "semantic_decision",
+                        "strict": True,
+                        "schema": _SCHEMA,
+                    }
+                },
+            )
+            payload = json.loads(response.output_text)
+            value = payload["value"]
+            probability = float(payload["probability"])
+            response_id = getattr(response, "id", None)
+        except BackendError:
+            raise
+        except Exception as error:
+            raise BackendError(f"OpenAI returned an invalid decision: {error}") from error
+        if not isinstance(value, bool):
+            raise BackendError("OpenAI decision value must be a boolean")
+        if value is not (probability >= 0.5):
+            raise BackendError(
+                "OpenAI returned inconsistent value and P(proposition=true): "
+                f"value={value!r}, probability={probability!r}"
+            )
+        return Decision(
+            value=value,
+            probability=probability,
+            backend="openai",
+            model=self.model,
+            proposition=proposition,
+            state_hash=state_digest(state),
+            metadata={
+                "response_id": response_id,
+                "confidence_kind": "model_reported",
+                "probability_semantics": "p_proposition_true",
+                "provider_version": self.version,
+            },
+        )

semantic_python/cache.py

@@ -0,0 +1,46 @@
+"""Stable cache keys and an in-memory decision cache."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import replace
+from threading import RLock
+from typing import Any
+
+from .decision import Decision
+
+
+def state_digest(state: str) -> str:
+    return hashlib.sha256(state.encode("utf-8")).hexdigest()
+
+
+def decision_cache_key(
+    *, backend_identity: str, state: str, proposition: str, configuration: Any
+) -> str:
+    config = json.dumps(configuration, sort_keys=True, separators=(",", ":"), default=str)
+    material = "\0".join((backend_identity, state_digest(state), proposition, config))
+    return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+
+class MemoryDecisionCache:
+    def __init__(self) -> None:
+        self._items: dict[str, Decision[Any]] = {}
+        self._lock = RLock()
+
+    def get(self, key: str) -> Decision[Any] | None:
+        with self._lock:
+            decision = self._items.get(key)
+        return replace(decision, cached=True) if decision is not None else None
+
+    def put(self, key: str, decision: Decision[Any]) -> None:
+        with self._lock:
+            self._items[key] = replace(decision, cached=False)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._items.clear()
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._items)

semantic_python/config.py

@@ -0,0 +1,101 @@
+"""Runtime configuration scoped with context variables."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+from .backends.base import DecisionBackend
+from .cache import MemoryDecisionCache
+from .decision import ConfigurationError, TruthPolicy, UncertaintyPolicy
+from .replay import DecisionRecorder
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    backend: DecisionBackend | None = None
+    policy: TruthPolicy = field(default_factory=TruthPolicy)
+    cache: MemoryDecisionCache | None = None
+    recorder: DecisionRecorder | None = None
+
+
+def _default_config() -> Config:
+    # Equality followed by inequality should reuse the same underlying judgment.
+    return Config(cache=MemoryDecisionCache())
+
+
+_DEFAULT = _default_config()
+_config: ContextVar[Config] = ContextVar("sem_config", default=_DEFAULT)
+_UNSET = object()
+
+
+def get_config() -> Config:
+    return _config.get()
+
+
+def configure(
+    *,
+    backend: DecisionBackend | object | None = _UNSET,
+    threshold: float | None = None,
+    true_threshold: float | None = None,
+    false_threshold: float | None = None,
+    uncertainty: UncertaintyPolicy | str | None = None,
+    fallback: bool | None = None,
+    cache: MemoryDecisionCache | bool | object | None = _UNSET,
+    recorder: DecisionRecorder | object | None = _UNSET,
+) -> Config:
+    current = get_config()
+    high = threshold if threshold is not None else true_threshold
+    low = (
+        1.0 - threshold
+        if threshold is not None
+        else false_threshold
+        if false_threshold is not None
+        else current.policy.false_threshold
+    )
+    uncertainty_policy = (
+        UncertaintyPolicy(uncertainty) if uncertainty is not None else current.policy.uncertainty
+    )
+    policy = TruthPolicy(
+        false_threshold=low,
+        true_threshold=high if high is not None else current.policy.true_threshold,
+        uncertainty=uncertainty_policy,
+        fallback=fallback if fallback is not None else current.policy.fallback,
+    )
+    selected_cache = MemoryDecisionCache() if cache is True else (None if cache is False else cache)
+    result = Config(
+        backend=current.backend if backend is _UNSET else cast(DecisionBackend | None, backend),
+        policy=policy,
+        cache=(
+            current.cache if cache is _UNSET else cast(MemoryDecisionCache | None, selected_cache)
+        ),
+        recorder=(
+            current.recorder if recorder is _UNSET else cast(DecisionRecorder | None, recorder)
+        ),
+    )
+    _config.set(result)
+    return result
+
+
+def reset_config() -> None:
+    _config.set(_default_config())
+
+
+@contextmanager
+def configuration(**changes: Any) -> Iterator[Config]:
+    previous = get_config()
+    try:
+        configured = configure(**changes)
+        yield configured
+    finally:
+        _config.set(previous)
+
+
+def require_backend() -> DecisionBackend:
+    backend = get_config().backend
+    if backend is None:
+        raise ConfigurationError("no semantic backend configured; call configure(backend=...)")
+    return backend

semantic_python/decision.py

@@ -0,0 +1,125 @@
+"""Structured semantic decisions and their truthiness policy."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from enum import Enum
+from types import MappingProxyType
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class SemanticError(Exception):
+    """Base class for semantic-runtime errors."""
+
+
+class BackendError(SemanticError):
+    """A semantic backend could not produce a decision."""
+
+
+class ConfigurationError(SemanticError):
+    """The semantic runtime is not configured correctly."""
+
+
+class InvalidComparisonError(TypeError, SemanticError):
+    """An operand has no defined implicit semantic comparison."""
+
+
+class UncertaintyPolicy(str, Enum):
+    RAISE = "raise"
+    FALLBACK = "fallback"
+    USE_VALUE = "use_value"
+
+
+class UncertainDecisionError(SemanticError):
+    """Raised when a decision falls inside the configured uncertainty band."""
+
+    def __init__(self, decision: Decision[Any]) -> None:
+        self.decision = decision
+        super().__init__(
+            f"semantic decision is uncertain (probability={decision.probability:.3f}, "
+            f"proposition={decision.proposition!r})"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TruthPolicy:
+    """Controls conversion of a boolean decision to a Python bool."""
+
+    false_threshold: float = 0.15
+    true_threshold: float = 0.85
+    uncertainty: UncertaintyPolicy = UncertaintyPolicy.RAISE
+    fallback: bool = False
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.false_threshold < self.true_threshold <= 1.0:
+            raise ValueError("thresholds must satisfy 0 <= false < true <= 1")
+        object.__setattr__(self, "uncertainty", UncertaintyPolicy(self.uncertainty))
+
+    def resolve(self, decision: Decision[bool]) -> bool:
+        if decision.probability >= self.true_threshold:
+            return True
+        if decision.probability <= self.false_threshold:
+            return False
+        if self.uncertainty is UncertaintyPolicy.FALLBACK:
+            return self.fallback
+        if self.uncertainty is UncertaintyPolicy.USE_VALUE:
+            return decision.value
+        raise UncertainDecisionError(decision)
+
+
+@dataclass(frozen=True, slots=True)
+class Decision(Generic[T]):
+    """A typed result retaining confidence and provenance.
+
+    ``probability`` is the probability that ``proposition`` is true, rather than
+    confidence in the selected value. This makes negation mechanically exact.
+    """
+
+    value: T
+    probability: float
+    backend: str
+    proposition: str
+    state_hash: str
+    model: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    policy: TruthPolicy = field(default_factory=TruthPolicy, repr=False, compare=False)
+    cached: bool = field(default=False, compare=False)
+    replayed: bool = field(default=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.probability <= 1.0:
+            raise ValueError("probability must be between 0 and 1")
+        if not self.backend:
+            raise ValueError("backend must not be empty")
+        if not self.proposition:
+            raise ValueError("proposition must not be empty")
+        if not self.state_hash:
+            raise ValueError("state_hash must not be empty")
+        object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
+
+    def __bool__(self) -> bool:
+        if not isinstance(self.value, bool):
+            raise TypeError("only boolean decisions have truthiness")
+        return self.policy.resolve(self)  # type: ignore[arg-type]
+
+    def negated(self) -> Decision[bool]:
+        if not isinstance(self.value, bool):
+            raise TypeError("only boolean decisions can be negated")
+        return Decision(
+            value=not self.value,
+            probability=1.0 - self.probability,
+            backend=self.backend,
+            model=self.model,
+            proposition=f"not ({self.proposition})",
+            state_hash=self.state_hash,
+            metadata={**self.metadata, "negated_from": self.proposition},
+            policy=self.policy,
+            cached=self.cached,
+            replayed=self.replayed,
+        )
+
+    def with_policy(self, policy: TruthPolicy) -> Decision[T]:
+        return replace(self, policy=policy)

semantic_python/py.typed

@@ -0,0 +1 @@
+# Marker for PEP 561 inline type information.

semantic_python/replay.py

@@ -0,0 +1,80 @@
+"""Privacy-conscious JSONL recording and deterministic replay."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from threading import RLock
+from typing import IO, Any, cast
+
+from .backends.base import BackendBase
+from .cache import state_digest
+from .decision import Decision
+
+
+def decision_to_record(decision: Decision[Any]) -> dict[str, Any]:
+    return {
+        "value": decision.value,
+        "probability": decision.probability,
+        "backend": decision.backend,
+        "model": decision.model,
+        "proposition": decision.proposition,
+        "state_hash": decision.state_hash,
+        "metadata": dict(decision.metadata),
+    }
+
+
+class DecisionRecorder:
+    """Append decisions as JSON lines; raw semantic state is never recorded."""
+
+    def __init__(self, target: str | Path | IO[str]) -> None:
+        self.target = target
+        self._lock = RLock()
+
+    def record(self, decision: Decision[Any]) -> None:
+        line = json.dumps(decision_to_record(decision), sort_keys=True) + "\n"
+        with self._lock:
+            if hasattr(self.target, "write"):
+                stream = cast(IO[str], self.target)
+                stream.write(line)
+                stream.flush()
+            else:
+                with Path(self.target).open("a", encoding="utf-8") as stream:
+                    stream.write(line)
+
+
+class ReplayBackend(BackendBase):
+    """Backend that matches recorded decisions by state hash and proposition."""
+
+    def __init__(self, source: str | Path | IO[str] | Iterable[dict[str, Any]]) -> None:
+        if isinstance(source, (str, Path)):
+            with Path(source).open(encoding="utf-8") as stream:
+                records = [json.loads(line) for line in stream if line.strip()]
+        elif hasattr(source, "read"):
+            replay_stream = cast(IO[str], source)
+            records = [json.loads(line) for line in replay_stream if line.strip()]
+        else:
+            records = list(source)
+        self._records = {(r["state_hash"], r["proposition"]): r for r in records}
+
+    @property
+    def identity(self) -> str:
+        return "replay:jsonl-v1"
+
+    def boolean(self, state: str, proposition: str) -> Decision[bool]:
+        digest = state_digest(state)
+        try:
+            record = self._records[(digest, proposition)]
+        except KeyError as error:
+            raise KeyError(f"no replay decision for {digest}:{proposition}") from error
+        return Decision(
+            value=bool(record["value"]),
+            probability=float(record["probability"]),
+            backend=str(record["backend"]),
+            model=record.get("model"),
+            proposition=proposition,
+            state_hash=digest,
+            metadata=record.get("metadata", {}),
+            replayed=True,
+        )

semantic_python/semantic.py

@@ -0,0 +1,80 @@
+"""The explicit semantic value boundary."""
+
+from __future__ import annotations
+
+from typing import ClassVar, Generic, TypeVar, cast
+
+from .cache import decision_cache_key, state_digest
+from .config import get_config, require_backend
+from .decision import BackendError, Decision, InvalidComparisonError
+
+T = TypeVar("T")
+
+
+class Semantic(Generic[T]):
+    __slots__ = ("_value",)
+    __hash__: ClassVar[None] = None  # type: ignore[assignment]
+
+    def __init__(self, value: T) -> None:
+        if not isinstance(value, str):
+            raise TypeError("v0.1 supports only Semantic[str]")
+        self._value = cast(str, value)
+
+    @property
+    def value(self) -> T:
+        return cast(T, self._value)
+
+    def __repr__(self) -> str:
+        return f"Semantic({self._value!r})"
+
+    def __eq__(self, proposition: object) -> Decision[bool]:  # type: ignore[override]
+        if isinstance(proposition, Semantic):
+            raise InvalidComparisonError(
+                "Semantic-to-Semantic equality is ambiguous; compare explicitly"
+            )
+        if not isinstance(proposition, str):
+            raise InvalidComparisonError(
+                "Semantic[str] can only be compared with a proposition string"
+            )
+        return self._decide(proposition)
+
+    def __ne__(self, proposition: object) -> Decision[bool]:  # type: ignore[override]
+        return self.__eq__(proposition).negated()
+
+    def _decide(self, proposition: str) -> Decision[bool]:
+        config = get_config()
+        backend = require_backend()
+        identity = getattr(backend, "identity", type(backend).__qualname__)
+        key = decision_cache_key(
+            backend_identity=identity,
+            state=self._value,
+            proposition=proposition,
+            configuration={
+                "false_threshold": config.policy.false_threshold,
+                "true_threshold": config.policy.true_threshold,
+                "uncertainty": config.policy.uncertainty.value,
+                "fallback": config.policy.fallback,
+            },
+        )
+        if config.cache is not None:
+            cached = config.cache.get(key)
+            if cached is not None:
+                return cached.with_policy(config.policy)
+        try:
+            raw = backend.boolean(self._value, proposition)
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except Exception as error:
+            if isinstance(error, BackendError):
+                raise
+            raise BackendError(f"backend {identity!r} failed: {error}") from error
+        if not isinstance(raw, Decision) or not isinstance(raw.value, bool):
+            raise BackendError("boolean backend must return Decision[bool]")
+        if raw.proposition != proposition or raw.state_hash != state_digest(self._value):
+            raise BackendError("backend returned mismatched proposition or state hash")
+        decision = raw.with_policy(config.policy)
+        if config.cache is not None:
+            config.cache.put(key, decision)
+        if config.recorder is not None:
+            config.recorder.record(decision)
+        return decision

semantic_python-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: semantic-python
+Version: 0.1.0a1
+Summary: Experimental semantic values for Python
+Project-URL: Homepage, https://github.com/SaiRiteshThela/semantic-python
+Project-URL: Repository, https://github.com/SaiRiteshThela/semantic-python
+Project-URL: Issues, https://github.com/SaiRiteshThela/semantic-python/issues
+Project-URL: Changelog, https://github.com/SaiRiteshThela/semantic-python/blob/main/CHANGELOG.md
+Author: Sai Ritesh Thela
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,decision-models,python,semantic
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Provides-Extra: laya
+Requires-Dist: laya<0.5,>=0.4.0; extra == 'laya'
+Provides-Extra: notebook
+Requires-Dist: ipykernel>=6.29; extra == 'notebook'
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Semantic Python
+
+> Python, but `==` can understand meaning.
+
+Semantic Python is not a model like Laya or Jev. It is an opt-in Python value
+layer that turns backend inference into inspectable decisions for normal Python
+control flow. Only `Semantic(...)` values can invoke a model.
+
+## Install
+
+```bash
+python -m pip install 'semantic-python[openai]'
+export OPENAI_API_KEY="..."
+```
+
+## Demo
+
+Use natural-language intent in ordinary loops and async code:
+
+`functions` · `if` · `try/except` · `for` · `while` · `comprehensions` ·
+`generators` · `classes` · `with` · `async/await`
+
+```python
+import asyncio
+
+from semantic_python import (
+    OpenAIBackend,
+    Semantic,
+    UncertainDecisionError,
+    configure,
+)
+
+STOP = "the user wants to stop"
+
+configure(
+    backend=OpenAIBackend(model="gpt-6-luna"),
+    true_threshold=0.85,
+    false_threshold=0.15,
+    uncertainty="raise",
+)
+
+
+def decide(text: str):
+    return Semantic(text) == STOP
+
+
+messages = [
+    "Continue with the next ticket.",
+    "Save the work and close this session.",
+]
+
+for text in messages:
+    decision = decide(text)
+    print(f"stop={decision.value} p={decision.probability:.2f} model={decision.model}")
+
+    try:
+        if decision:
+            print("Stop requested")
+            break
+    except UncertainDecisionError:
+        print("Send to human review")
+
+
+async def decide_async(text: str):
+    return await asyncio.to_thread(decide, text)
+
+
+async_result = asyncio.run(decide_async(text))
+opposite = Semantic(text) != STOP
+
+print("async cache hit:", async_result.cached)
+print("negated:", opposite.value, opposite.probability)
+```
+
+The comparison returns a bool-coercible `Decision`, so `if` and loops work
+normally while probability, model provenance, caching, and replay remain
+available. `!=` negates the same judgment instead of issuing a second inference.
+
+## More Python patterns
+
+These examples continue with the configured backend and `STOP` proposition from
+the main demo.
+
+### `while`
+
+```python
+queue = iter(["Keep going", "Not yet", "Finished for today"])
+message = Semantic(next(queue))
+
+while message != STOP:
+    print("Processing:", message.value)
+    message = Semantic(next(queue))
+```
+
+### Comprehensions and generators
+
+```python
+texts = ["Continue", "Pause here", "That is all for today"]
+decisions = {text: decide(text) for text in texts}
+
+stop_requests = [text for text, decision in decisions.items() if decision.value]
+
+probabilities = (decision.probability for decision in decisions.values())
+print(stop_requests, list(probabilities))
+```
+
+### Classes
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class IntentRule:
+    proposition: str
+
+    def evaluate(self, text: str):
+        return Semantic(text) == self.proposition
+
+
+stop_rule = IntentRule("the user wants to stop")
+decision = stop_rule.evaluate("Please close the session")
+print(decision.value, decision.probability)
+```
+
+### Context managers and offline tests
+
+```python
+from semantic_python import FakeBackend, configuration
+
+state = "I'm done"
+fixtures = {(state, STOP): (True, 0.99)}
+
+with configuration(backend=FakeBackend(fixtures), cache=False):
+    assert Semantic(state) == STOP
+```
+
+## Backends
+
+Application code stays the same when the configured backend changes.
+
+| Backend | Install | Purpose |
+| --- | --- | --- |
+| `OpenAIBackend` | `semantic-python[openai]` | Hosted inference |
+| `LayaBackend` | `semantic-python[laya]` | Local inference |
+| `FakeBackend` | Included | Deterministic offline tests |
+
+OpenAI receives the wrapped state and proposition. Laya may download model
+checkpoints on first use. FakeBackend performs no network requests.
+
+## Semantics
+
+| Expression | Result |
+| --- | --- |
+| `plain_string == other` | Ordinary Python equality |
+| `Semantic(text) == proposition` | Inspectable semantic `Decision` |
+| `Semantic(text) != proposition` | Negated cached judgment |
+| `semantic is other` | Ordinary Python identity |
+| `Semantic(...) == Semantic(...)` | Rejected as ambiguous |
+| `hash(Semantic(...))` | Rejected; inference is never used for hashing |
+
+Probabilities at or above `0.85` resolve true, probabilities at or below `0.15`
+resolve false, and the default policy raises `UncertainDecisionError` between
+those thresholds. Backend failures are raised rather than converted to `False`.
+
+## Examples
+
+- [OpenAI demo](examples/semantic_python_demo.ipynb)
+- [Python control-flow demo](examples/python_primitives_demo.ipynb)
+- [Stop loop](examples/stop_loop.py)
+- [Ticket routing](examples/ticket_routing.py)
+- [Uncertainty and escalation](examples/escalation.py)
+
+The offline examples run without credentials:
+
+```bash
+python -m pip install -e .
+python examples/stop_loop.py
+python examples/ticket_routing.py
+python examples/escalation.py
+```
+
+## Safety
+
+- Model probability is an estimate, not truth or authorization.
+- Hosted inference can transmit sensitive text and incur cost.
+- Consequential actions should use conservative thresholds and human review.
+
+See [semantics](docs/semantics.md), [backends](docs/backends.md), and
+[uncertainty](docs/uncertainty.md) for the complete behavior.
+
+MIT licensed. Experimental and pre-alpha.

semantic_python-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,16 @@
+semantic_python/__init__.py,sha256=sQP8Wv9-muAi8nuzFK7KJ7b5-SnnWlpVZoUlBDcIU70,1134
+semantic_python/cache.py,sha256=sOfcKJs6JAe-gMbSrNLQ0c8ZlZoAXISRnDRA8KoI9xc,1367
+semantic_python/config.py,sha256=RvGAfO2hVbnnSjeyXGwftEiqsoVlOqDxGU_SRnG0IjY,3198
+semantic_python/decision.py,sha256=lLmARLTXmDwm37b_kyU8sRQw_aw0JpuZNO2nkkq4-lU,4346
+semantic_python/py.typed,sha256=GOJzfT--I5WXaP7ohUQllUQsQIgGVdJh2w-iL5dW-vM,46
+semantic_python/replay.py,sha256=g2OJeZofIa_BN6hjI088x8Ur5qdlgIZIsq01sPV0zv0,2831
+semantic_python/semantic.py,sha256=fkLFcf7rqg9Vka0K5QqCKdmHRXEKJ_Wq5BWLzyaDCX8,3124
+semantic_python/backends/__init__.py,sha256=LERLDCYvr9VxnASNK-jOTSTbQ0bX_bXhodqkk0kMwJw,257
+semantic_python/backends/base.py,sha256=ONQEaGQ1jdQMpc27xR1ux1axfsz6HRh0ri1rO4ixDEE,986
+semantic_python/backends/fake.py,sha256=y2B6peYWxgaiO8YF35FXScQl8b3KQG-JrlHsmDbKxuM,2099
+semantic_python/backends/laya.py,sha256=EpZbFS5WMaCjNUbrM196KC-jfXSc_JeSuECDJ69RS9I,2818
+semantic_python/backends/openai.py,sha256=OCHa00tTGX8yrP5Ueh-rStxGFKPa0Qr2Vcc5uHmY82I,4356
+semantic_python-0.1.0a1.dist-info/METADATA,sha256=U8PW302ALYHUxo7AZYjcFKtaQCiETdUd9vXIGOhFJc4,6675
+semantic_python-0.1.0a1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+semantic_python-0.1.0a1.dist-info/licenses/LICENSE,sha256=Px0VHU5RfTBJkwd499xoGherVtp2ENPcmNnQtZ0XC2g,1085
+semantic_python-0.1.0a1.dist-info/RECORD,,

semantic_python-0.1.0a1.dist-info/WHEEL

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

semantic_python-0.1.0a1.dist-info/licenses/LICENSE

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