oro-env-runtime 0.1.0__py3-none-any.whl

oro_env_runtime/__init__.py

@@ -0,0 +1,23 @@
+"""Portable sealed-pack execution and verification for Oro environments."""
+
+from oro_env_runtime.contracts import (
+    ENV_CONTRACT_VERSION,
+    RESULT_SCHEMA_VERSION,
+    RUNTIME_VERSION,
+    TOOL_CONTRACT_VERSION,
+    VERIFIER_VERSION,
+)
+from oro_env_runtime.pack import COMPILED_EPOCH_VERSION
+from oro_env_runtime.runtime import TaskSession
+from oro_env_runtime.validation import validate_epoch
+
+__all__ = [
+    "COMPILED_EPOCH_VERSION",
+    "ENV_CONTRACT_VERSION",
+    "RESULT_SCHEMA_VERSION",
+    "RUNTIME_VERSION",
+    "TOOL_CONTRACT_VERSION",
+    "TaskSession",
+    "VERIFIER_VERSION",
+    "validate_epoch",
+]

oro_env_runtime/acceptance.py

@@ -0,0 +1,171 @@
+"""Terminal acceptance contracts for compiled commerce tasks.
+
+The search/filter tools expose raw catalog strings. Reward should not. This module converts
+catalog labels into a small canonical layer so verifier correctness tracks the shopper-visible
+contract rather than exact retailer category or brand spellings.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from .attributes import attribute_matches
+from .catalog import Catalog
+from .schema import (
+    CandidateRef,
+    HardConstraints,
+)
+
+_CATEGORY_ALIASES: dict[str, str] = {
+    "video cards": "graphics_card",
+    "graphics cards": "graphics_card",
+    "video graphics cards": "graphics_card",
+    "gpu": "graphics_card",
+    "gpus": "graphics_card",
+    "mobile phones": "smartphone",
+    "cell phones": "smartphone",
+    "phones": "smartphone",
+    "smartphones": "smartphone",
+    "unlocked phones": "smartphone",
+    "smart phones": "smartphone",
+    "wi fi": "networking",
+    "wifi": "networking",
+    "smartwatches": "smartwatch",
+    "smart watches": "smartwatch",
+}
+
+
+def _norm(text: str | None) -> str:
+    return " ".join(re.findall(r"[a-z0-9]+", (text or "").casefold()))
+
+
+def _tokens(text: str | None) -> set[str]:
+    return set(re.findall(r"[a-z0-9]+", (text or "").casefold()))
+
+
+def _stemmed_tokens(text: str | None) -> set[str]:
+    out: set[str] = set()
+    for token in _tokens(text):
+        out.add(token)
+        if len(token) > 3 and token.endswith("s"):
+            out.add(token[:-1])
+    return out
+
+
+def canonical_category_labels(labels: Iterable[str | None]) -> set[str]:
+    out: set[str] = set()
+    for label in labels:
+        low = _norm(label)
+        if not low:
+            continue
+        out.add(low)
+        out.add(_CATEGORY_ALIASES.get(low, low))
+    return out
+
+
+def _path_has(candidate_path: Iterable[str | None], labels: Iterable[str]) -> bool:
+    path_labels = canonical_category_labels(candidate_path)
+    wanted = canonical_category_labels(labels)
+    return bool(path_labels & wanted)
+
+
+def _title_category_fallback(
+    expected: str, candidate_path: Iterable[str | None], title: str | None
+) -> bool:
+    tokens = _stemmed_tokens(title)
+    exp = _norm(expected)
+    if exp in {"gaming monitors", "gaming monitor"}:
+        return (
+            _path_has(candidate_path, ["Monitors", "Computer Monitors"])
+            and {"gaming", "monitor"} <= tokens
+        )
+    if exp in {"over ear", "over-ear", "over ear headphones", "over-ear headphones"}:
+        return _path_has(candidate_path, ["Headphones"]) and (
+            {"over", "ear"} <= tokens or "overear" in tokens or "circumaural" in tokens
+        )
+    return False
+
+
+def category_matches(
+    expected: str | None,
+    candidate_path: Iterable[str | None],
+    *,
+    title: str | None = None,
+) -> bool:
+    if not expected:
+        return True
+    expected_labels = canonical_category_labels([expected])
+    candidate_labels = canonical_category_labels(candidate_path)
+    if expected_labels & candidate_labels:
+        return True
+    return _title_category_fallback(expected, candidate_path, title)
+
+
+def brand_matches(
+    expected: str | None, actual: str | None, *, title: str | None = None
+) -> bool:
+    if not expected:
+        return True
+    exp = _norm(expected)
+    act = _norm(actual)
+    if not exp:
+        return True
+    if exp == act:
+        return True
+    exp_tokens = _tokens(expected)
+    actual_tokens = _tokens(actual)
+    if exp_tokens and exp_tokens <= actual_tokens:
+        return True
+    return False
+
+
+def candidate_satisfies_hard(
+    catalog: Catalog, ref: CandidateRef, hard: HardConstraints
+) -> bool:
+    if not catalog.exists(ref):
+        return False
+    meta = catalog.meta(ref)
+    rec = catalog.by_id(ref.product_id)
+    if hard.require_in_stock and not meta.in_stock:
+        return False
+    if meta.price > hard.budget_usd + 0.01:
+        return False
+    if not category_matches(
+        hard.category, meta.category_path, title=str(rec.get("title") or "")
+    ):
+        return False
+    if not brand_matches(hard.brand, meta.brand, title=str(rec.get("title") or "")):
+        return False
+    # Attribute gates further restrict the eligible pool; keys are pre-validated at HardConstraints construction.
+    for key, wanted in hard.attributes.items():
+        if not attribute_matches(rec, key, wanted):
+            return False
+    return True
+
+
+def hard_constraint_refs(catalog: Catalog, hard: HardConstraints) -> list[CandidateRef]:
+    refs = [
+        meta.ref
+        for meta in catalog.all_candidates()
+        if candidate_satisfies_hard(catalog, meta.ref, hard)
+    ]
+    return _dedupe_refs(refs)
+
+
+def _dedupe_refs(refs: Iterable[CandidateRef]) -> list[CandidateRef]:
+    seen: set[str] = set()
+    out: list[CandidateRef] = []
+    for ref in refs:
+        if ref.key() not in seen:
+            seen.add(ref.key())
+            out.append(ref)
+    return out
+
+
+__all__ = [
+    "brand_matches",
+    "candidate_satisfies_hard",
+    "category_matches",
+    "hard_constraint_refs",
+]

oro_env_runtime/agent_tools.py

@@ -0,0 +1,127 @@
+"""Agent tool surface: function-calling specs + dispatch into the environment."""
+
+from __future__ import annotations
+
+_TOOLS = [
+    (
+        "search",
+        "Full-text search the catalog. Returns up to 10 products.",
+        {
+            "query": {"type": "string"},
+            "k": {"type": "integer"},
+            "in_stock": {"type": "boolean"},
+        },
+        ["query"],
+    ),
+    (
+        "filter",
+        "Filter the catalog by structured constraints. Returns up to 10 candidates.",
+        {
+            "category": {"type": "string"},
+            "brand": {"type": "string"},
+            "max_price": {"type": "number"},
+            "in_stock": {"type": "boolean"},
+            "k": {"type": "integer"},
+        },
+        [],
+    ),
+    (
+        "view",
+        "View one product, raw product facts, and its variants (sku, current price, current stock).",
+        {"product_id": {"type": "string"}},
+        ["product_id"],
+    ),
+    (
+        "compare",
+        "Compare up to 5 products side by side, including raw product facts.",
+        {"product_ids": {"type": "array", "items": {"type": "string"}}},
+        ["product_ids"],
+    ),
+    (
+        "inspect_stock",
+        "Check the CURRENT stock and price of a specific variant. Use this to verify before ordering.",
+        {"product_id": {"type": "string"}, "sku": {"type": "string"}},
+        ["product_id", "sku"],
+    ),
+    ("inspect_cart", "Inspect the current cart.", {}, []),
+    (
+        "add_to_cart",
+        "Add a specific variant to the cart.",
+        {"product_id": {"type": "string"}, "sku": {"type": "string"}},
+        ["product_id", "sku"],
+    ),
+    (
+        "remove_from_cart",
+        "Remove a variant from the cart.",
+        {"product_id": {"type": "string"}, "sku": {"type": "string"}},
+        ["product_id", "sku"],
+    ),
+    (
+        "message",
+        "Send a short message to the shopper.",
+        {"content": {"type": "string"}},
+        ["content"],
+    ),
+    (
+        "place_test_order",
+        "Place the order for a variant in the cart. Ends the session. "
+        "When the shopper asked for a reason, include structured justification claims grounded in viewed facts.",
+        {
+            "product_id": {"type": "string"},
+            "sku": {"type": "string"},
+            "justification": {
+                "type": "object",
+                "properties": {
+                    "summary": {"type": "string"},
+                    "claims": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "field": {
+                                    "type": "string",
+                                    "description": "One of category, resolution, refresh_rate, screen_size, price, in_stock, brand, streaming, microphone, privacy_cover, autofocus, hdr.",
+                                },
+                                "value": {
+                                    "type": "string",
+                                    "description": "The claimed value, e.g. Webcams, 4k, 49.98, true, Adesso.",
+                                },
+                                "evidence": {
+                                    "type": "string",
+                                    "description": "Short source phrase from view/compare/inspect_stock.",
+                                },
+                            },
+                            "required": ["field", "value"],
+                        },
+                    },
+                },
+            },
+        },
+        [],
+    ),
+]
+
+
+def tool_specs(*, exclude_names: set[str] | frozenset[str] = frozenset()) -> list[dict]:
+    specs = []
+    for name, desc, props, required in _TOOLS:
+        if name in exclude_names:
+            continue
+        specs.append(
+            {
+                "type": "function",
+                "function": {
+                    "name": name,
+                    "description": desc,
+                    "parameters": {
+                        "type": "object",
+                        "properties": props,
+                        "required": required,
+                    },
+                },
+            }
+        )
+    return specs
+
+
+__all__ = ["tool_specs"]

oro_env_runtime/attributes.py

@@ -0,0 +1,216 @@
+"""Attribute-reliability gate for hard constraints.
+
+The `attributes` layer is LLM-synthesized and noisy, so only a canonical concept whose
+resolved value is unambiguous and cross-checkable may carry a HARD gate
+(``HardConstraints.attributes``); every other concept must be a shadow ``latent_pref``.
+
+The raw `attributes` dict is too sparse and fragmented to trust directly (the same concept
+splits across `ram`/`memory`/`system memory (ram)`, `resolution`/`maximum resolution`, etc.),
+so the resolver reads the richer `specification` field and the product title, canonicalizing
+fragmented spellings. The gate allowlist is derived offline from a reliability audit: a concept
+is gate-worthy only at coverage >= 8% AND title-agreement >= 90% over N >= 40 samples. High
+coverage alone does not qualify a concept -- `color` has the widest coverage yet stays
+shadow-only.
+"""
+
+from __future__ import annotations
+
+import re
+
+# canonical concept -> the raw key spellings it may appear under in specification/attributes
+_GATE_RAW_KEYS: dict[str, tuple[str, ...]] = {
+    "ram": (
+        "ram",
+        "memory",
+        "system memory (ram)",
+        "memory (ram)",
+        "installed memory",
+        "system memory",
+    ),
+    "resolution": (
+        "resolution",
+        "screen resolution",
+        "maximum resolution",
+        "native resolution",
+        "display resolution",
+    ),
+    "screen_size": ("screen size", "display size", "screen_size", "screen size (in)"),
+    "refresh_rate": ("refresh rate", "maximum refresh rate", "refresh rate (max)"),
+}
+
+# a key may carry a HARD gate only if it is here; anything else stays a shadow latent_pref
+RELIABLE_GATE_KEYS: frozenset[str] = frozenset(_GATE_RAW_KEYS)
+# concepts measured but rejected by the gate bar; kept for families choosing a shadow scoring field
+SHADOW_ONLY_KEYS: frozenset[str] = frozenset(
+    {"storage", "color", "processor", "operating_system", "connectivity"}
+)
+
+_GB_RE = re.compile(r"(\d+(?:\.\d+)?)\s*(tb|gb)\b", re.I)
+_INCH_RE = re.compile(r"(\d+(?:\.\d+)?)\s*(?:inch|in|\")", re.I)
+_HZ_RE = re.compile(r"(\d+(?:\.\d+)?)\s*hz", re.I)
+_WXH_RE = re.compile(r"(\d{3,5})\s*[x×]\s*(\d{3,5})")
+# the concept word must immediately follow the number, so "16GB Memory - 512GB SSD" and a GPU
+# "RTX 4070Ti 16GB" do not resolve ram from the storage or VRAM figure.
+_RAM_TITLE = re.compile(r"(\d+(?:\.\d+)?)\s*gb\s*(?:ram|memory|unified memory)\b", re.I)
+
+
+def _first(v: object) -> str | None:
+    if isinstance(v, list):
+        return str(v[0]) if v else None
+    return str(v) if v is not None else None
+
+
+def _norm_gb(text: str | None) -> str | None:
+    if not text:
+        return None
+    m = _GB_RE.search(text)
+    if not m:
+        return None
+    val = float(m.group(1)) * (1024 if m.group(2).lower() == "tb" else 1)
+    return f"{val:g}gb"
+
+
+def _norm_inch(text: str | None) -> str | None:
+    if not text:
+        return None
+    m = _INCH_RE.search(text)
+    return f"{float(m.group(1)):g}in" if m else None
+
+
+def _norm_hz(text: str | None) -> str | None:
+    if not text:
+        return None
+    m = _HZ_RE.search(text)
+    return f"{float(m.group(1)):g}hz" if m else None
+
+
+def _norm_res(text: str | None) -> str | None:
+    if not text:
+        return None
+    low = text.lower()
+    m = _WXH_RE.search(low)
+    if m:
+        w = int(m.group(1))
+        return (
+            "4k" if w >= 3840 else "qhd" if w >= 2560 else "fhd" if w >= 1920 else "hd"
+        )
+    if "4k" in low or "uhd" in low or "2160" in low:
+        return "4k"
+    if "qhd" in low or "1440" in low:
+        return "qhd"
+    if "fhd" in low or "1080" in low or "full hd" in low:
+        return "fhd"
+    if re.search(r"\b(hd|720)\b", low):
+        return "hd"
+    return None
+
+
+_NORMALIZERS = {
+    "ram": _norm_gb,
+    "resolution": _norm_res,
+    "screen_size": _norm_inch,
+    "refresh_rate": _norm_hz,
+}
+
+
+def _normalize(key: str, text: str | None) -> str | None:
+    norm = _NORMALIZERS.get(key)
+    return norm(text) if norm else None
+
+
+def _title_value(key: str, title: str) -> str | None:
+    if key == "ram":
+        m = _RAM_TITLE.search(title)
+        return f"{float(m.group(1)):g}gb" if m else None
+    if key in ("resolution", "screen_size", "refresh_rate"):
+        return _normalize(key, title)
+    return None
+
+
+def resolve_attribute(rec: dict, key: str) -> str | None:
+    """Canonical value for a candidate's product record, or None when unreliable/absent.
+
+    Reads the best reliable source in order: specification, attributes, then the product
+    title. Returns None for any key outside :data:`RELIABLE_GATE_KEYS`.
+    """
+    if key not in RELIABLE_GATE_KEYS:
+        return None
+    raw_keys = _GATE_RAW_KEYS[key]
+    for src_name in ("specification", "attributes"):
+        src = rec.get(src_name)
+        if not isinstance(src, dict):
+            continue
+        low = {k.strip().lower(): v for k, v in src.items()}
+        for rk in raw_keys:
+            if rk in low:
+                val = _normalize(key, _first(low[rk]))
+                if val:
+                    return val
+    return _title_value(key, str(rec.get("title") or ""))
+
+
+def attribute_matches(rec: dict, key: str, wanted: str) -> bool:
+    """True iff the candidate's reliable value for ``key`` equals the normalized ``wanted``."""
+    got = resolve_attribute(rec, key)
+    if got is None:
+        return False
+    want = _normalize(key, str(wanted))
+    return want is not None and got == want
+
+
+def _variant_options_values(key: str, text: str) -> set[str]:
+    """Every value the concept's adjacency oracle finds in a variant options string: the number
+    must sit next to its concept word/unit, so a storage or VRAM GB figure is never read as RAM."""
+    if key == "ram":
+        return {f"{float(n):g}gb" for n in _RAM_TITLE.findall(text)}
+    if key == "screen_size":
+        return {f"{float(m.group(1)):g}in" for m in _INCH_RE.finditer(text)}
+    if key == "refresh_rate":
+        return {f"{float(m.group(1)):g}hz" for m in _HZ_RE.finditer(text)}
+    v = _norm_res(text)  # resolution is a keyword/WxH label, single-valued per string
+    return {v} if v else set()
+
+
+def resolve_variant_attribute(rec: dict, options: str | None, key: str) -> str | None:
+    """Per-variant value TF3 gates on, read from the SKU ``options`` string via the adjacency oracle.
+
+    ``resolve_attribute`` is product-level and cannot separate a 16GB SKU from an 8GB SKU of one
+    product. This reads ``options`` first (the number must be adjacent to its concept word/unit),
+    so "16GB RAM / 512GB SSD" -> ram=16gb while the 512GB storage and a bare GPU VRAM "16GB" are
+    never read as RAM. An options string encoding two or more distinct values is ambiguous and
+    returns None. Only when options is silent on the concept does it fall back to the product-level
+    resolver. Returns None for any key outside :data:`RELIABLE_GATE_KEYS`.
+
+    NOTE: the fallback is product-level, so a caller gating on ``ram`` MUST category-scope to
+    system-RAM categories (laptops/desktops/phones/tablets) -- a GPU's VRAM ``memory`` key resolves
+    here otherwise. TF3 enforces that scope in ``env/families/constraint_satisfaction.py``.
+    """
+    if key not in RELIABLE_GATE_KEYS:
+        return None
+    vals = _variant_options_values(key, options or "")
+    if len(vals) > 1:  # ambiguous options string -> refuse to gate
+        return None
+    if vals:
+        return next(iter(vals))
+    return resolve_attribute(rec, key)
+
+
+def assert_gate_keys(attributes: dict[str, str]) -> None:
+    """Compile-time gate: every hard-gated attribute key must be reliable, else it must be a shadow
+    latent_pref. Raised at ``HardConstraints`` construction (task compile time)."""
+    bad = sorted(k for k in attributes if k not in RELIABLE_GATE_KEYS)
+    if bad:
+        raise ValueError(
+            f"HardConstraints.attributes may gate only on reliable keys "
+            f"{sorted(RELIABLE_GATE_KEYS)}; {bad} is not gate-reliable and must be a latent_pref."
+        )
+
+
+__all__ = [
+    "RELIABLE_GATE_KEYS",
+    "SHADOW_ONLY_KEYS",
+    "resolve_attribute",
+    "resolve_variant_attribute",
+    "attribute_matches",
+    "assert_gate_keys",
+]