langparse 0.1.0__py3-none-any.whl

langparse/workbooks/modeling/openai_adapter.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from .config import WorkbookModelConfig, resolve_workbook_model_config
+from .ports import WorkbookModelResponseError, WorkbookStructureModelAdapter
+from .types import ModelIdentity, ProviderReply, WorkbookModelRequest
+
+_DECISION_COMMON_PROPERTIES = {
+    "case_id": {"type": "string"},
+    "status": {"type": "string"},
+    "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+    "reason_codes": {"type": "array", "items": {"type": "string"}},
+}
+
+_WORKBOOK_RESPONSE_SCHEMA = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["schema_version", "request_checksum", "decisions"],
+    "properties": {
+        "schema_version": {"type": "integer", "const": 1},
+        "request_checksum": {"type": "string"},
+        "decisions": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 1,
+            "items": {
+                "anyOf": [
+                    {
+                        "type": "object",
+                        "additionalProperties": False,
+                        "required": [
+                            "case_id",
+                            "status",
+                            "choice_id",
+                            "confidence",
+                            "reason_codes",
+                        ],
+                        "properties": {
+                            **_DECISION_COMMON_PROPERTIES,
+                            "status": {"type": "string", "const": "selected"},
+                            "choice_id": {"type": "string"},
+                        },
+                    },
+                    {
+                        "type": "object",
+                        "additionalProperties": False,
+                        "required": ["case_id", "status", "confidence", "reason_codes"],
+                        "properties": {
+                            **_DECISION_COMMON_PROPERTIES,
+                            "status": {"type": "string", "const": "abstained"},
+                        },
+                    },
+                ]
+            },
+        },
+    },
+}
+
+
+class OpenAIWorkbookStructureAdapter(WorkbookStructureModelAdapter):
+    """Adapter invoking OpenAI Chat Completions API for workbook structure disambiguation."""
+
+    def __init__(self, config: WorkbookModelConfig) -> None:
+        self._config = config
+        self._identity = ModelIdentity(
+            provider="openai",
+            model=config.model,
+            revision=None,
+        )
+        self._client = None
+
+    @property
+    def identity(self) -> ModelIdentity:
+        return self._identity
+
+    @property
+    def config(self) -> WorkbookModelConfig:
+        return self._config
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        cli_model: str | None = None,
+        cli_api_key: str | None = None,
+        cli_base_url: str | None = None,
+        cli_timeout_seconds: float | None = None,
+    ) -> OpenAIWorkbookStructureAdapter:
+        config = resolve_workbook_model_config(
+            cli_model=cli_model,
+            cli_api_key=cli_api_key,
+            cli_base_url=cli_base_url,
+            cli_timeout_seconds=cli_timeout_seconds,
+            from_env=True,
+        )
+        return cls(config)
+
+    def _get_client(self, timeout_seconds: float):
+        import openai
+
+        if self._client is None:
+            self._client = openai.OpenAI(
+                api_key=self._config.api_key,
+                base_url=self._config.base_url,
+                timeout=timeout_seconds,
+            )
+        return self._client
+
+    def complete(
+        self,
+        request: WorkbookModelRequest,
+        *,
+        timeout_seconds: float,
+    ) -> ProviderReply:
+        try:
+            import openai
+
+            if openai is None:
+                raise ImportError("openai module is None")
+        except (ImportError, TypeError) as exc:
+            raise ImportError(
+                "The 'openai' package is required for model disambiguation. "
+                "Install it with 'pip install \"langparse[model]\"'."
+            ) from exc
+
+        effective_timeout = min(timeout_seconds, self._config.timeout_seconds)
+        try:
+            client = self._get_client(effective_timeout)
+            response = client.chat.completions.create(
+                model=self._config.model,
+                messages=[
+                    {
+                        "role": "system",
+                        "content": (
+                            "You are an Excel layout disambiguation adjudicator. "
+                            "Analyze the cell cues, structural feature summary, and registered choice reasons, "
+                            "then select the registered choice that best explains the region. "
+                            "Use 'unclassified' only when no registered typed choice is supported by the facts. "
+                            "Return only one JSON object matching the supplied response contract. "
+                            "If you choose a registered choice_id, status MUST be exactly 'selected'. "
+                            "If you do not choose one, status MUST be exactly 'abstained' and choice_id "
+                            "MUST be omitted. Never use 'resolved', 'chosen', or any other status. "
+                            "Copy schema_version, request_checksum, and case_id exactly from the request. "
+                            "choice_id MUST be copied exactly from that case's registered choices."
+                        ),
+                    },
+                    {
+                        "role": "user",
+                        "content": request.body.decode("utf-8"),
+                    },
+                ],
+                response_format={
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": "workbook_region_decision",
+                        "strict": True,
+                        "schema": _WORKBOOK_RESPONSE_SCHEMA,
+                    },
+                },
+                seed=0,
+                temperature=0,
+                timeout=effective_timeout,
+            )
+        except Exception as exc:
+            if isinstance(exc, ImportError):
+                raise
+            raise WorkbookModelResponseError(
+                f"OpenAI completion failed ({type(exc).__name__})"
+            ) from exc
+
+        if not response.choices:
+            raise WorkbookModelResponseError("OpenAI returned an empty choices list")
+
+        message_content = response.choices[0].message.content or ""
+        reply_body = message_content.encode("utf-8")
+
+        usage_dict: dict[str, int] = {}
+        if getattr(response, "usage", None) is not None:
+            usage = response.usage
+            if getattr(usage, "prompt_tokens", None) is not None:
+                usage_dict["prompt_tokens"] = usage.prompt_tokens
+            if getattr(usage, "completion_tokens", None) is not None:
+                usage_dict["completion_tokens"] = usage.completion_tokens
+            if getattr(usage, "total_tokens", None) is not None:
+                usage_dict["total_tokens"] = usage.total_tokens
+
+        provider_request_id = getattr(response, "id", None)
+
+        return ProviderReply(
+            body=reply_body,
+            provider_request_id=provider_request_id,
+            usage=usage_dict,
+        )

langparse/workbooks/modeling/policy.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .ports import WorkbookModelConfigurationError, WorkbookStructureModelAdapter
+from .types import WorkbookModelMode, WorkbookModelPolicy
+
+if TYPE_CHECKING:
+    from .disambiguation import WorkbookRegionDisambiguator
+
+
+@dataclass(frozen=True)
+class WorkbookDisambiguation:
+    mode: WorkbookModelMode = WorkbookModelMode.OFF
+    adapter: WorkbookStructureModelAdapter | None = None
+    policy: WorkbookModelPolicy = WorkbookModelPolicy()
+    _runtime: WorkbookRegionDisambiguator | None = field(
+        init=False,
+        default=None,
+        repr=False,
+        compare=False,
+    )
+
+    def __post_init__(self) -> None:
+        mode = WorkbookModelMode(self.mode)
+        object.__setattr__(self, "mode", mode)
+
+        if self.policy is None:
+            object.__setattr__(self, "policy", WorkbookModelPolicy())
+        elif not isinstance(self.policy, WorkbookModelPolicy):
+            raise WorkbookModelConfigurationError("policy must be a WorkbookModelPolicy")
+
+        if mode is WorkbookModelMode.OFF and self.adapter is not None:
+            raise WorkbookModelConfigurationError(
+                "off workbook disambiguation cannot carry an adapter"
+            )
+        if mode is WorkbookModelMode.AUTO and self.adapter is None:
+            raise WorkbookModelConfigurationError(
+                "auto workbook disambiguation requires an adapter"
+            )
+        if mode is WorkbookModelMode.REQUIRED and self.adapter is None:
+            raise WorkbookModelConfigurationError(
+                "required workbook disambiguation requires an adapter"
+            )
+        if mode is not WorkbookModelMode.OFF:
+            from .disambiguation import WorkbookRegionDisambiguator
+
+            object.__setattr__(self, "_runtime", WorkbookRegionDisambiguator())
+
+    @classmethod
+    def off(cls) -> WorkbookDisambiguation:
+        return cls(mode=WorkbookModelMode.OFF)
+
+    @classmethod
+    def auto(
+        cls,
+        adapter: WorkbookStructureModelAdapter,
+        *,
+        policy: WorkbookModelPolicy | None = None,
+    ) -> WorkbookDisambiguation:
+        return cls(
+            mode=WorkbookModelMode.AUTO,
+            adapter=adapter,
+            policy=WorkbookModelPolicy() if policy is None else policy,
+        )
+
+    @classmethod
+    def required(
+        cls,
+        adapter: WorkbookStructureModelAdapter,
+        *,
+        policy: WorkbookModelPolicy | None = None,
+    ) -> WorkbookDisambiguation:
+        return cls(
+            mode=WorkbookModelMode.REQUIRED,
+            adapter=adapter,
+            policy=WorkbookModelPolicy() if policy is None else policy,
+        )

langparse/workbooks/modeling/ports.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from langparse.types import ParseDiagnostics
+
+from .types import ModelIdentity, ProviderReply, WorkbookModelRequest
+
+
+class WorkbookModelError(Exception):
+    """Base error for workbook model disambiguation."""
+
+
+class WorkbookModelConfigurationError(WorkbookModelError, ValueError):
+    """Raised when model disambiguation is configured inconsistently."""
+
+
+class InvalidRegionAmbiguityCaseError(WorkbookModelError, ValueError):
+    """Raised when an ambiguity case does not satisfy its contract."""
+
+
+class WorkbookModelResponseError(WorkbookModelError, ValueError):
+    """Raised when a provider response cannot be accepted."""
+
+
+class RequiredWorkbookDisambiguationError(WorkbookModelError):
+    """Raised when required model disambiguation leaves cases unresolved."""
+
+    def __init__(self, case_ids: tuple[str, ...], diagnostics: ParseDiagnostics):
+        super().__init__(f"Workbook model disambiguation unresolved: {', '.join(case_ids)}")
+        self.case_ids = case_ids
+        self.diagnostics = diagnostics
+
+
+class WorkbookStructureModelAdapter(Protocol):
+    @property
+    def identity(self) -> ModelIdentity: ...
+
+    def complete(
+        self,
+        request: WorkbookModelRequest,
+        *,
+        timeout_seconds: float,
+    ) -> ProviderReply: ...

langparse/workbooks/modeling/pricing.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+def calculate_cost_usd(
+    prompt_tokens: int,
+    completion_tokens: int,
+    *,
+    input_cost_usd_per_million: float,
+    output_cost_usd_per_million: float,
+) -> float:
+    """Calculate observed cost using deployment-supplied, versioned policy rates."""
+    if prompt_tokens <= 0 and completion_tokens <= 0:
+        return 0.0
+
+    prompt_cost = (prompt_tokens / 1_000_000.0) * input_cost_usd_per_million
+    completion_cost = (completion_tokens / 1_000_000.0) * output_cost_usd_per_million
+    return prompt_cost + completion_cost

langparse/workbooks/modeling/types.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from numbers import Real
+from types import MappingProxyType
+from typing import Literal, TypeAlias
+
+REGION_SCHEMA_VERSION = 1
+REGION_PROMPT_VERSION = "region-choice-v2"
+REGION_RULE_VERSION = "region-rules-v1"
+REGION_VALIDATOR_VERSION = "region-validator-v1"
+REGION_PRIVACY_VERSION = "region-privacy-v1"
+
+RegionFeatureScalar: TypeAlias = str | int | float | bool | None
+
+
+def _is_region_feature_scalar(value: object) -> bool:
+    return value is None or type(value) in (str, int, float, bool)
+
+
+class WorkbookModelMode(str, Enum):
+    OFF = "off"
+    AUTO = "auto"
+    REQUIRED = "required"
+
+
+@dataclass(frozen=True)
+class WorkbookModelPolicy:
+    timeout_seconds: float = 20.0
+    workbook_timeout_seconds: float = 60.0
+    max_attempts: int = 2
+    max_cases: int = 8
+    max_calls: int = 4
+    max_cells_per_case: int = 500
+    max_request_bytes: int = 256_000
+    max_response_bytes: int = 128_000
+    kill_switch: bool = False
+    max_tokens_per_workbook: int | None = None
+    max_cost_usd_per_workbook: float | None = None
+    input_cost_usd_per_million: float | None = None
+    output_cost_usd_per_million: float | None = None
+    cost_pricing_version: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.kill_switch, bool):
+            raise ValueError("kill_switch must be a bool")
+        for name in ("timeout_seconds", "workbook_timeout_seconds"):
+            value = getattr(self, name)
+            if (
+                isinstance(value, bool)
+                or not isinstance(value, Real)
+                or not math.isfinite(value)
+                or value <= 0
+            ):
+                raise ValueError(f"{name} must be a finite positive real")
+        for name in (
+            "max_attempts",
+            "max_cases",
+            "max_calls",
+            "max_cells_per_case",
+            "max_request_bytes",
+            "max_response_bytes",
+        ):
+            value = getattr(self, name)
+            if type(value) is not int or value <= 0:
+                raise ValueError(f"{name} must be an exact positive integer")
+        if self.max_tokens_per_workbook is not None:
+            if type(self.max_tokens_per_workbook) is not int or self.max_tokens_per_workbook <= 0:
+                raise ValueError("max_tokens_per_workbook must be an exact positive integer")
+        if self.max_cost_usd_per_workbook is not None:
+            if (
+                isinstance(self.max_cost_usd_per_workbook, bool)
+                or not isinstance(self.max_cost_usd_per_workbook, Real)
+                or not math.isfinite(self.max_cost_usd_per_workbook)
+                or self.max_cost_usd_per_workbook <= 0
+            ):
+                raise ValueError("max_cost_usd_per_workbook must be a finite positive real")
+            for name in (
+                "input_cost_usd_per_million",
+                "output_cost_usd_per_million",
+            ):
+                value = getattr(self, name)
+                if (
+                    isinstance(value, bool)
+                    or not isinstance(value, Real)
+                    or not math.isfinite(value)
+                    or value < 0
+                ):
+                    raise ValueError(
+                        "cost pricing requires finite non-negative input and output rates"
+                    )
+            version = self.cost_pricing_version
+            if (
+                not isinstance(version, str)
+                or not 0 < len(version.strip()) <= 64
+                or not version.isascii()
+                or not all(character.isalnum() or character in "._-" for character in version)
+            ):
+                raise ValueError("cost_pricing_version must be a non-empty safe ASCII identifier")
+            object.__setattr__(self, "cost_pricing_version", version.strip())
+        elif any(
+            value is not None
+            for value in (
+                self.input_cost_usd_per_million,
+                self.output_cost_usd_per_million,
+                self.cost_pricing_version,
+            )
+        ):
+            raise ValueError("cost pricing fields require max_cost_usd_per_workbook")
+
+
+@dataclass(frozen=True)
+class ModelIdentity:
+    provider: str
+    model: str
+    revision: str | None = None
+
+
+@dataclass(frozen=True)
+class RegionChoice:
+    choice_id: str
+    kind: Literal["logical_table", "form", "matrix", "text", "unclassified"]
+    local_score: float
+    reason_codes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class RegionCellCue:
+    coordinate: str
+    display_text: str
+    value_type: str
+    style_fingerprint: str
+    merge_anchor: str | None
+    rowspan: int
+    colspan: int
+
+
+@dataclass(frozen=True)
+class RegionAmbiguityCase:
+    case_id: str
+    sheet_name: str
+    sheet_visibility: str
+    source_range: str
+    fact_digest: str
+    cells: tuple[RegionCellCue, ...]
+    feature_summary: tuple[tuple[str, RegionFeatureScalar], ...]
+    choices: tuple[RegionChoice, ...]
+    fallback_choice_id: str
+    ambiguity_codes: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.feature_summary, tuple):
+            raise TypeError("feature_summary must be a tuple of (str, scalar) entries")
+        for entry in self.feature_summary:
+            if not isinstance(entry, tuple) or len(entry) != 2:
+                raise TypeError("feature_summary must contain (str, scalar) tuples")
+            key, value = entry
+            if type(key) is not str or not _is_region_feature_scalar(value):
+                raise TypeError("feature_summary entries must contain a string and scalar value")
+
+
+@dataclass(frozen=True)
+class WorkbookModelRequest:
+    schema_version: int
+    prompt_version: str
+    privacy_version: str
+    request_checksum: str
+    body: bytes
+    case_ids: tuple[str, ...]
+    choice_ids_by_case: tuple[tuple[str, tuple[str, ...]], ...]
+
+
+@dataclass(frozen=True)
+class ProviderReply:
+    body: bytes
+    provider_request_id: str | None
+    usage: Mapping[str, int] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.body, (bytes, bytearray, memoryview)):
+            raise TypeError("body must be bytes-like")
+        object.__setattr__(self, "body", bytes(self.body))
+        if self.provider_request_id is not None and type(self.provider_request_id) is not str:
+            raise TypeError("provider_request_id must be a string or None")
+        if not isinstance(self.usage, Mapping):
+            raise TypeError("usage must be a mapping of string keys to integer values")
+        copied_usage: dict[str, int] = {}
+        for key, value in self.usage.items():
+            if not isinstance(key, str):
+                raise TypeError("usage keys must be strings")
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise TypeError("usage values must be non-bool integers")
+            if value < 0:
+                raise TypeError("usage values must be non-negative integers")
+            copied_usage[key] = value
+        object.__setattr__(self, "usage", MappingProxyType(copied_usage))
+
+
+@dataclass(frozen=True)
+class RegionModelDecision:
+    case_id: str
+    status: Literal["selected", "abstained"]
+    choice_id: str | None
+    reported_confidence: float | None
+    reason_codes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ModelCallAudit:
+    case_id: str
+    source_range: str
+    mode: str
+    schema_version: int
+    prompt_version: str
+    rule_version: str
+    validator_version: str
+    privacy_version: str
+    rule_confidence: float
+    provider: str | None
+    model: str | None
+    model_revision: str | None
+    request_checksum: str | None
+    response_checksum: str | None
+    cache_status: str
+    attempts: int
+    elapsed_ms: int
+    request_bytes: int
+    response_bytes: int
+    outcome: str
+    selected_choice_id: str | None
+    reported_confidence: float | None
+    validation_codes: tuple[str, ...] = ()
+    reason_codes: tuple[str, ...] = ()
+    error_type: str | None = None
+
+
+@dataclass(frozen=True)
+class RegionResolution:
+    case_id: str
+    choice_id: str
+    status: Literal["local_fallback", "model_selected", "cache_selected"]
+    audit: ModelCallAudit | None = None
+
+
+@dataclass(frozen=True)
+class RegionResolutionBatch:
+    resolutions: tuple[RegionResolution, ...]
+    unresolved_case_ids: tuple[str, ...] = ()