nl2data-openai 0.1.0__py3-none-any.whl

nl2data_openai/__init__.py

@@ -0,0 +1,15 @@
+"""OpenAI structured-output provider for ``nl2data-core``.
+
+An independent optional distribution implementing the provider-neutral
+``ModelProvider`` contract.  The OpenAI SDK is never imported at package
+import time; clients are constructed lazily on first generation from
+injected credentials or a client factory, so core imports and capability
+inspection stay fully offline.
+"""
+
+from __future__ import annotations
+
+from .config import OpenAIProviderConfig
+from .provider import OpenAIModelProvider
+
+__all__ = ["OpenAIProviderConfig", "OpenAIModelProvider"]

nl2data_openai/client.py

@@ -0,0 +1,88 @@
+"""Lazy optional OpenAI SDK boundary for the provider package.
+
+The ``openai`` package is loaded only inside this module through
+:func:`importlib.import_module`, so importing ``nl2data_openai``, the core,
+or the provider never imports the SDK.  Client construction happens lazily
+on first generation; no import-time or capability-time network access
+exists.  Error predicates duck-type by class name so injected fake clients
+raise structurally identical errors without the SDK installed.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.util import find_spec
+from typing import Any
+
+from nl2data_core.ai.errors import ModelErrorCode, ModelInvocationError
+
+from .config import OpenAIProviderConfig
+
+
+def driver_available() -> bool:
+    """Whether the optional ``openai`` SDK is installed."""
+    return find_spec("openai") is not None
+
+
+def build_openai_client(config: OpenAIProviderConfig, *, api_key: str) -> Any:
+    """Lazily import the SDK and build a bounded ``AsyncOpenAI`` client.
+
+    Raises a normalized ``PROVIDER_UNAVAILABLE`` error when the SDK is
+    missing or the client cannot be constructed; the key and any driver
+    exception text never enter the error.
+    """
+    if not driver_available():
+        raise ModelInvocationError(
+            ModelErrorCode.PROVIDER_UNAVAILABLE,
+            "the openai SDK is not installed; install the 'nl2data-openai' package",
+            details={"cause_type": "ImportError"},
+        )
+    try:
+        openai = import_module("openai")
+        kwargs: dict[str, Any] = {"api_key": api_key, "timeout": config.timeout_seconds}
+        if config.base_url is not None:
+            kwargs["base_url"] = config.base_url
+        if config.organization is not None:
+            kwargs["organization"] = config.organization
+        return openai.AsyncOpenAI(**kwargs)
+    except ModelInvocationError:
+        raise
+    except Exception as error:
+        raise ModelInvocationError(
+            ModelErrorCode.PROVIDER_UNAVAILABLE,
+            "the openai client could not be constructed",
+            details={"cause_type": type(error).__name__},
+        ) from error
+
+
+def _class_name(error: BaseException) -> str:
+    return error.__class__.__name__
+
+
+def is_timeout_error(error: BaseException) -> bool:
+    """SDK or builtin timeout signals (duck-typed by class name)."""
+    if isinstance(error, TimeoutError):
+        return True
+    return _class_name(error) == "APITimeoutError"
+
+
+def is_connection_error(error: BaseException) -> bool:
+    """Connection failure signals (duck-typed by class name)."""
+    if isinstance(error, ConnectionError):
+        return True
+    return _class_name(error) in {"APIConnectionError", "APIConnectionPoolTimeoutError"}
+
+
+def is_rate_limit_error(error: BaseException) -> bool:
+    """Rate-limit signals (duck-typed by class name)."""
+    return _class_name(error) == "RateLimitError"
+
+
+def is_authentication_error(error: BaseException) -> bool:
+    """Credential-rejection signals (duck-typed by class name)."""
+    return _class_name(error) in {"AuthenticationError", "PermissionDeniedError"}
+
+
+def is_status_error(error: BaseException) -> bool:
+    """Any SDK status error exposing an HTTP status code (duck-typed)."""
+    return _class_name(error) == "APIStatusError" or hasattr(error, "status_code")

nl2data_openai/config.py

@@ -0,0 +1,63 @@
+"""Immutable credential-free configuration for the OpenAI provider.
+
+The configuration carries model selection and bounded invocation settings
+only.  API keys never enter this model: hosts inject credentials through an
+``api_key_resolver`` callable or a ``client_factory`` at provider
+construction, so keys cannot appear in configuration fingerprints, request
+metadata, workflow state, telemetry, or error records.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from nl2data_core.canonical import strict_sha256_fingerprint
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+_FINGERPRINT_PATTERN = r"^sha256:[0-9a-f]{64}$"
+_MAX_OUTPUT_TOKENS = 131_072
+
+
+class OpenAIProviderConfig(BaseModel):
+    """Immutable bounded OpenAI invocation settings.
+
+    ``model_name`` selects the vendor model; all other fields bound the
+    invocation.  ``base_url`` and ``organization`` are optional host-owned
+    endpoint overrides that never appear in normalized errors.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    model_name: str = Field(min_length=1, max_length=128)
+    max_input_chars: int = Field(default=100_000, ge=1_000, le=1_000_000)
+    max_output_tokens: int = Field(default=4096, ge=1, le=_MAX_OUTPUT_TOKENS)
+    temperature: float | None = Field(default=None, ge=0.0, le=2.0)
+    timeout_seconds: float = Field(default=30.0, gt=0.0, le=3600.0)
+    base_url: str | None = Field(default=None, max_length=512)
+    organization: str | None = Field(default=None, max_length=256)
+    merge_developer_into_system: bool = False
+    fingerprint: str = Field(default="", pattern=_FINGERPRINT_PATTERN)
+
+    @model_validator(mode="after")
+    def _compute_fingerprint(self) -> OpenAIProviderConfig:
+        object.__setattr__(self, "fingerprint", strict_sha256_fingerprint(self.safe_payload()))
+        return self
+
+    def safe_payload(self) -> dict[str, Any]:
+        """Serializable payload with no credential-bearing fields."""
+        return {
+            "model_name": self.model_name,
+            "max_input_chars": self.max_input_chars,
+            "max_output_tokens": self.max_output_tokens,
+            "temperature": self.temperature,
+            "timeout_seconds": self.timeout_seconds,
+            "base_url": self.base_url,
+            "organization": self.organization,
+            "merge_developer_into_system": self.merge_developer_into_system,
+        }
+
+    def safe_dump(self) -> dict[str, Any]:
+        """Diagnostics-safe serialization; contains no secrets."""
+        payload = self.safe_payload()
+        payload["fingerprint"] = self.fingerprint
+        return payload

nl2data_openai/live_evaluation.py

@@ -0,0 +1,286 @@
+"""Opt-in live OpenAI evaluation profile for the AI evaluation foundation.
+
+Runs a deterministic :class:`AIEvaluationDataset` through the real
+:class:`IntentResolver` with :class:`OpenAIModelProvider` and classifies
+every case as ``verified``, ``unavailable``, or ``skipped``.  The profile
+is opt-in: without injected credentials/factory (or the
+``OPENAI_API_KEY`` environment variable) every case is ``skipped``, so
+default CI needs no credentials and makes no network access.  Evidence
+carries only protected fingerprints and normalized codes - never keys,
+raw prompts, raw provider payloads, or native clients.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable, Mapping
+from datetime import datetime
+from typing import Any, Literal
+
+from nl2data_core.ai.config import ModelConfig
+from nl2data_core.ai.context import SemanticReference, assemble_model_context
+from nl2data_core.ai.errors import (
+    ModelErrorCode,
+    ModelErrorRecord,
+    ModelInvocationError,
+    normalize_model_error,
+)
+from nl2data_core.ai.evaluation.models import (
+    AIEvaluationDataset,
+    AIProtectedEvidence,
+    LiveAICaseResult,
+    LiveAIEvaluationReport,
+    LiveAvailability,
+)
+from nl2data_core.ai.instructions import assemble_instruction_bundle
+from nl2data_core.ai.models import (
+    ClarificationRequired,
+    RejectedIntent,
+    ResolvedIntent,
+    ResolvedMultiEntityIntent,
+)
+from nl2data_core.ai.resolver import IntentResolver
+from nl2data_core.fixtures.models import FIXED_TIMEZONE, TIME_ANCHOR
+from nl2data_core.planning.validation import AuthorizedView
+
+from .config import OpenAIProviderConfig
+from .provider import OpenAIModelProvider
+
+#: Rejection codes that mean the provider call itself failed (auth,
+#: unreachable, timeout, rate limit, or unknown).  Content-level rejections
+#: (malformed/unsafe/bounds) prove the service was reachable and therefore
+#: count as verified evidence, never as an unavailable provider.
+_UNREACHABLE_CODES = frozenset(
+    {
+        ModelErrorCode.MODEL_TIMEOUT,
+        ModelErrorCode.PROVIDER_UNAVAILABLE,
+        ModelErrorCode.RETRY_EXHAUSTED,
+        ModelErrorCode.UNKNOWN_MODEL_ERROR,
+        ModelErrorCode.INVALID_REQUEST,
+    }
+)
+
+
+async def run_live_openai_evaluation(
+    *,
+    dataset: AIEvaluationDataset,
+    run_id: str,
+    view: AuthorizedView,
+    provider_config: OpenAIProviderConfig,
+    semantic_references: Mapping[str, SemanticReference] | None = None,
+    model_config: ModelConfig | None = None,
+    api_key_resolver: Callable[[], str] | None = None,
+    client_factory: Callable[[], Any] | None = None,
+    min_confidence: float = 0.6,
+    time_anchor: datetime = TIME_ANCHOR,
+    timezone: str = FIXED_TIMEZONE,
+    progress_callback: Callable[[str, str, LiveAICaseResult], None] | None = None,
+) -> LiveAIEvaluationReport:
+    """Run the dataset against the live OpenAI provider and classify cases.
+
+    Cases are ``skipped`` when the profile is not configured (no injected
+    credentials/factory and no ``OPENAI_API_KEY``); ``unavailable`` when a
+    provider call fails (credentials rejected, unreachable, timeout, or
+    rate-limited) or a rejection carries a provider-level error code;
+    ``verified`` when the provider call completed and protected evidence
+    was collected - including cases whose output was rejected by the
+    resolver gates, since those prove the live service behaved as
+    configured.
+    """
+    references = dict(semantic_references or {})
+    resolver_config = model_config or ModelConfig()
+    if not _credentials_available(api_key_resolver, client_factory):
+        return _skipped_report(
+            dataset, run_id, provider_config, time_anchor, timezone
+        )
+    provider = OpenAIModelProvider(
+        provider_config,
+        api_key_resolver=api_key_resolver,
+        client_factory=client_factory,
+    )
+    results: list[LiveAICaseResult] = []
+    try:
+        for case in dataset.cases:
+            if progress_callback is not None:
+                progress_callback("start", case.case_id, _pending_case(case.case_id))
+            result = await _run_case(
+                case=case,
+                provider=provider,
+                view=view,
+                references=references,
+                resolver_config=resolver_config,
+                min_confidence=min_confidence,
+            )
+            results.append(result)
+            if progress_callback is not None:
+                progress_callback("complete", case.case_id, result)
+    finally:
+        await provider.close()
+    return LiveAIEvaluationReport(
+        dataset_id=dataset.dataset_id,
+        run_id=run_id,
+        provider_name="openai",
+        model_name=provider_config.model_name,
+        time_anchor=time_anchor,
+        timezone=timezone,
+        results=tuple(results),
+    )
+
+
+def _pending_case(case_id: str) -> LiveAICaseResult:
+    """Create a safe progress placeholder before a case starts."""
+    return LiveAICaseResult(case_id=case_id, availability=LiveAvailability.SKIPPED)
+
+
+def _credentials_available(
+    api_key_resolver: Callable[[], str] | None,
+    client_factory: Callable[[], Any] | None,
+) -> bool:
+    if api_key_resolver is not None or client_factory is not None:
+        return True
+    return bool(os.environ.get("OPENAI_API_KEY"))
+
+
+def _skipped_report(
+    dataset: AIEvaluationDataset,
+    run_id: str,
+    provider_config: OpenAIProviderConfig,
+    time_anchor: datetime,
+    timezone: str,
+) -> LiveAIEvaluationReport:
+    results = tuple(
+        LiveAICaseResult(
+            case_id=case.case_id,
+            availability=LiveAvailability.SKIPPED,
+            skip_reason="live OpenAI profile is not configured",
+        )
+        for case in dataset.cases
+    )
+    return LiveAIEvaluationReport(
+        dataset_id=dataset.dataset_id,
+        run_id=run_id,
+        provider_name="openai",
+        model_name=provider_config.model_name,
+        time_anchor=time_anchor,
+        timezone=timezone,
+        results=results,
+    )
+
+
+async def _run_case(
+    *,
+    case: Any,
+    provider: OpenAIModelProvider,
+    view: AuthorizedView,
+    references: dict[str, SemanticReference],
+    resolver_config: ModelConfig,
+    min_confidence: float,
+) -> LiveAICaseResult:
+    started = time.perf_counter()
+    if case.skip_reason:
+        return LiveAICaseResult(
+            case_id=case.case_id,
+            availability=LiveAvailability.SKIPPED,
+            skip_reason=case.skip_reason,
+            duration_ms=0,
+        )
+    calls_before = provider.call_count
+    try:
+        outcome = await IntentResolver(
+            view=view,
+            semantic_references=references,
+            config=resolver_config,
+            min_confidence=min_confidence,
+        ).resolve(case.request, provider)
+        if (
+            isinstance(outcome, RejectedIntent)
+            and outcome.error.code in _UNREACHABLE_CODES
+        ):
+            return LiveAICaseResult(
+                case_id=case.case_id,
+                availability=LiveAvailability.UNAVAILABLE,
+                error=outcome.error,
+                duration_ms=int((time.perf_counter() - started) * 1000),
+            )
+        evidence = _build_evidence(
+            case,
+            outcome,
+            view,
+            references,
+            resolver_config,
+            call_count=provider.call_count - calls_before,
+        )
+        return LiveAICaseResult(
+            case_id=case.case_id,
+            availability=LiveAvailability.VERIFIED,
+            evidence=evidence,
+            duration_ms=int((time.perf_counter() - started) * 1000),
+        )
+    except ModelInvocationError as error:
+        return LiveAICaseResult(
+            case_id=case.case_id,
+            availability=LiveAvailability.UNAVAILABLE,
+            error=error.to_record(),
+            duration_ms=int((time.perf_counter() - started) * 1000),
+        )
+    except Exception as error:
+        return LiveAICaseResult(
+            case_id=case.case_id,
+            availability=LiveAvailability.UNAVAILABLE,
+            error=normalize_model_error(error),
+            duration_ms=int((time.perf_counter() - started) * 1000),
+        )
+
+
+def _build_evidence(
+    case: Any,
+    outcome: (
+        ResolvedIntent
+        | ResolvedMultiEntityIntent
+        | ClarificationRequired
+        | RejectedIntent
+    ),
+    view: AuthorizedView,
+    references: dict[str, SemanticReference],
+    resolver_config: ModelConfig,
+    *,
+    call_count: int = 1,
+) -> AIProtectedEvidence:
+    context = assemble_model_context(
+        request=case.request,
+        view=view,
+        semantic_references=references,
+        max_output_tokens=resolver_config.max_output_tokens,
+    )
+    instruction = assemble_instruction_bundle(
+        request=case.request,
+        context=context,
+        view=view,
+    )
+    if isinstance(outcome, (ResolvedIntent, ResolvedMultiEntityIntent)):
+        resolution: Literal["resolved", "clarification", "rejected"] = "resolved"
+        intent_fingerprint = outcome.intent.fingerprint
+        clarification_fingerprint: str | None = None
+        error: ModelErrorRecord | None = None
+    elif isinstance(outcome, ClarificationRequired):
+        resolution = "clarification"
+        intent_fingerprint = None
+        clarification_fingerprint = outcome.clarification.fingerprint
+        error = None
+    else:
+        resolution = "rejected"
+        intent_fingerprint = None
+        clarification_fingerprint = None
+        error = outcome.error
+    return AIProtectedEvidence(
+        case_id=case.case_id,
+        outcome=resolution,
+        intent_fingerprint=intent_fingerprint,
+        clarification_fingerprint=clarification_fingerprint,
+        error=error,
+        call_count=call_count,
+        context_fingerprint=context.fingerprint,
+        instruction_fingerprint=instruction.fingerprint,
+        output_schema_fingerprint=instruction.output_contract.fingerprint,
+    )

nl2data_openai/mapping.py

@@ -0,0 +1,413 @@
+"""OpenAI request/response mapping for the provider-neutral contract.
+
+The validated provider-neutral instruction bundle is mapped onto the
+system/developer message channels; the user prompt always stays a separate
+user message.  Structured output requests a strict JSON envelope matching
+the bounded provider response contract, and extraction fails closed on
+refusal, truncation, malformed JSON, schema mismatches, unsafe shapes, and
+output-bound violations - raw SDK payloads never cross the boundary.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from typing import Any
+
+from nl2data_core.ai.errors import ModelErrorCode, ModelInvocationError
+from nl2data_core.ai.instructions import ModelInstructionBundle
+from nl2data_core.ai.models import ModelInvocationRequest, ModelResponse, ModelUsage
+from nl2data_core.ai.resolver import scan_unsafe_output
+
+from .config import OpenAIProviderConfig
+
+#: Top-level envelope keys a structured response may carry.
+_ALLOWED_ENVELOPE_KEYS = frozenset({"intent", "clarification", "alternatives"})
+
+#: Bound on nested JSON container sizes (mirrors the core contract).
+_MAX_JSON_KEYS = 128
+
+#: Approximate token size used to enforce the output size bound.
+_MAX_CHARS_PER_TOKEN = 4
+_MAX_TOKEN_COUNT = 1_000_000_000
+
+#: Vendor response ids are opaque strings; the fallback is bounded.
+_RESPONSE_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_\-\.]{0,127}$")
+
+
+def build_messages(
+    request: ModelInvocationRequest,
+    *,
+    merge_developer_into_system: bool = False,
+) -> list[dict[str, str]]:
+    """Map the instruction bundle and prompt to system/developer/user messages.
+
+    The system channel carries the role and allowed behavior; the developer
+    channel carries safety constraints, the output contract, authorized
+    context references, and provenance fingerprints.  The user prompt is
+    never merged into either channel, so user text cannot rewrite system
+    instructions through formatting.
+    """
+    messages: list[dict[str, str]] = []
+    instruction = request.instruction
+    if instruction is not None:
+        system_message = _system_message(instruction)
+        developer_message = _developer_message(instruction)
+        if merge_developer_into_system:
+            system_message = f"{system_message}\n\n{developer_message}"
+            messages.append({"role": "system", "content": system_message})
+        else:
+            messages.append({"role": "system", "content": system_message})
+            messages.append({"role": "developer", "content": developer_message})
+    messages.append({"role": "user", "content": request.prompt})
+    return messages
+
+
+def _system_message(instruction: ModelInstructionBundle) -> str:
+    sections = [instruction.role.role]
+    if instruction.behavior.behavior:
+        sections.append(instruction.behavior.behavior)
+    return "\n\n".join(sections)
+
+
+def _developer_message(instruction: ModelInstructionBundle) -> str:
+    sections: list[str] = []
+    constraints = instruction.safety_constraints
+    if constraints:
+        sections.append(
+            "Safety constraints:\n"
+            + "\n".join(
+                f"- [{constraint.reason_code}] {constraint.instruction}"
+                for constraint in constraints
+            )
+        )
+    contract = instruction.output_contract
+    sections.append(
+        "Output contract: "
+        f"schema_id={contract.schema_id}; schema_version={contract.schema_version}; "
+        f"response_mode={contract.response_mode.value}; fingerprint={contract.fingerprint}"
+    )
+    references = instruction.context_references
+    if references:
+        sections.append(
+            "Authorized context references:\n"
+            + "\n".join(
+                f"- {reference.field_id}: {reference.label}" for reference in references
+            )
+        )
+    provenance_parts = [
+        (name, value)
+        for name, value in (
+            ("view", instruction.provenance.view_fingerprint),
+            ("model_bundle", instruction.provenance.model_bundle_fingerprint),
+            ("policy", instruction.provenance.policy_fingerprint),
+            ("tenant_scope", instruction.provenance.tenant_scope_fingerprint),
+        )
+        if value is not None
+    ]
+    if provenance_parts:
+        sections.append(
+            "Provenance fingerprints:\n"
+            + "\n".join(f"- {name}={value}" for name, value in provenance_parts)
+        )
+    return "\n\n".join(sections)
+
+
+def build_request_params(
+    request: ModelInvocationRequest, config: OpenAIProviderConfig
+) -> dict[str, Any]:
+    """One bounded structured-output request for ``chat.completions.create``.
+
+    The request carries the mapped messages, a strict JSON envelope schema,
+    and the bounded output-token budget; only the bounded prompt and
+    authorized JSON-compatible context of the invocation are sent.
+    """
+    temperature = (
+        request.temperature if request.temperature is not None else config.temperature
+    )
+    params: dict[str, Any] = {
+        "model": config.model_name,
+        "messages": build_messages(
+            request,
+            merge_developer_into_system=config.merge_developer_into_system,
+        ),
+        "response_format": {
+            "type": "json_schema",
+            "json_schema": {
+                "name": "structured_intent_envelope",
+                "strict": True,
+                "schema": build_envelope_schema(),
+            },
+        },
+        "max_completion_tokens": request.max_output_tokens,
+    }
+    if temperature is not None:
+        params["temperature"] = temperature
+    return params
+
+
+def build_envelope_schema() -> dict[str, Any]:
+    """The strict JSON schema for the bounded structured-intent envelope.
+
+    All envelope keys are required-but-nullable so the schema satisfies
+    OpenAI strict structured-output constraints while keeping the envelope
+    flexible; the resolver performs the authoritative semantic validation
+    after extraction.
+    """
+    selection_schema = {
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["selection_id", "field_id", "alias", "aggregation"],
+        "properties": {
+            "selection_id": {"type": "string"},
+            "field_id": {"type": "string"},
+            "alias": {"anyOf": [{"type": "string"}, {"type": "null"}]},
+            "aggregation": {"type": "string"},
+        },
+    }
+    scalar = {"anyOf": [{"type": "string"}, {"type": "number"}, {"type": "boolean"}]}
+    filter_schema = {
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["filter_id", "field_id", "operator", "value"],
+        "properties": {
+            "filter_id": {"type": "string"},
+            "field_id": {"type": "string"},
+            "operator": {"type": "string"},
+            "value": {"anyOf": [{"type": "array", "items": scalar}, scalar, {"type": "null"}]},
+        },
+    }
+    ordering_schema = {
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["ordering_id", "field_id", "direction"],
+        "properties": {
+            "ordering_id": {"type": "string"},
+            "field_id": {"type": "string"},
+            "direction": {"type": "string"},
+        },
+    }
+    option_schema = {
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["option_id", "label", "detail"],
+        "properties": {
+            "option_id": {"type": "string"},
+            "label": {"type": "string"},
+            "detail": {"anyOf": [{"type": "string"}, {"type": "null"}]},
+        },
+    }
+    intent_schema = {
+        "type": "object",
+        "additionalProperties": False,
+        "required": [
+            "source_id",
+            "root_entity_id",
+            "selections",
+            "filters",
+            "orderings",
+            "limit",
+            "confidence",
+        ],
+        "properties": {
+            "source_id": {"type": "string"},
+            "root_entity_id": {"type": "string"},
+            "selections": {"type": "array", "items": selection_schema},
+            "filters": {"type": "array", "items": filter_schema},
+            "orderings": {"type": "array", "items": ordering_schema},
+            "limit": {"anyOf": [{"type": "integer"}, {"type": "null"}]},
+            "confidence": {"type": "number"},
+        },
+    }
+    clarification_schema = {
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["question", "options"],
+        "properties": {
+            "question": {"type": "string"},
+            "options": {"type": "array", "items": option_schema},
+        },
+    }
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["intent", "clarification", "alternatives"],
+        "properties": {
+            "intent": {"anyOf": [intent_schema, {"type": "null"}]},
+            "clarification": {"anyOf": [clarification_schema, {"type": "null"}]},
+            "alternatives": {
+                "anyOf": [{"type": "array", "items": option_schema}, {"type": "null"}]
+            },
+        },
+    }
+
+
+def extract_response(
+    response: Any, request: ModelInvocationRequest
+) -> ModelResponse:
+    """Normalize one SDK response into the core structured envelope.
+
+    Fails closed on refusal, truncation, content-filter rejection, missing
+    content, malformed JSON, non-object output, unsupported envelope keys,
+    non-JSON-compatible values, and output-bound violations.  The raw SDK
+    object and its payload never appear in the returned values or errors.
+
+    Strict OpenAI structured output requires every schema key on the wire,
+    including ``null`` placeholders; the resolver interprets key presence as
+    a request (for example ``clarification``), so ``null`` envelope values
+    are normalized to absent keys before the core envelope is built.
+    """
+    if response is None or not getattr(response, "choices", None):
+        raise ModelInvocationError(
+            ModelErrorCode.MALFORMED_RESPONSE,
+            "provider returned an empty response",
+            details={"request_id": request.request_id},
+        )
+    choice = response.choices[0]
+    finish_reason = getattr(choice, "finish_reason", None)
+    if finish_reason == "length":
+        raise ModelInvocationError(
+            ModelErrorCode.OUTPUT_LIMIT_EXCEEDED,
+            "provider output was truncated at the token bound",
+            details={"request_id": request.request_id, "finish_reason": "length"},
+        )
+    if finish_reason == "content_filter":
+        raise ModelInvocationError(
+            ModelErrorCode.UNSAFE_OUTPUT,
+            "provider output was blocked by content filtering",
+            details={"request_id": request.request_id, "finish_reason": "content_filter"},
+        )
+    message = getattr(choice, "message", None)
+    if message is None:
+        raise ModelInvocationError(
+            ModelErrorCode.MALFORMED_RESPONSE,
+            "provider response is missing its message content",
+            details={"request_id": request.request_id},
+        )
+    refusal = getattr(message, "refusal", None)
+    if isinstance(refusal, str) and refusal.strip():
+        raise ModelInvocationError(
+            ModelErrorCode.MALFORMED_RESPONSE,
+            "provider refused the request",
+            details={"request_id": request.request_id},
+        )
+    content = getattr(message, "content", None)
+    if not isinstance(content, str) or not content.strip():
+        raise ModelInvocationError(
+            ModelErrorCode.MALFORMED_RESPONSE,
+            "provider returned no structured content",
+            details={"request_id": request.request_id},
+        )
+    try:
+        parsed = json.loads(content)
+    except (TypeError, ValueError) as error:
+        raise ModelInvocationError(
+            ModelErrorCode.MALFORMED_RESPONSE,
+            "provider returned malformed JSON",
+            details={"request_id": request.request_id, "cause_type": type(error).__name__},
+        ) from error
+    if not isinstance(parsed, dict):
+        raise ModelInvocationError(
+            ModelErrorCode.MALFORMED_RESPONSE,
+            "provider output is not a JSON object",
+            details={"request_id": request.request_id},
+        )
+    unsupported = [key for key in parsed if key not in _ALLOWED_ENVELOPE_KEYS]
+    if unsupported:
+        raise ModelInvocationError(
+            ModelErrorCode.MALFORMED_RESPONSE,
+            "provider output contains unsupported envelope fields",
+            details={
+                "request_id": request.request_id,
+                "fields": ",".join(sorted(unsupported)[:8]),
+            },
+        )
+    try:
+        _check_json_compatible(parsed, "content")
+    except ValueError as error:
+        raise ModelInvocationError(
+            ModelErrorCode.MALFORMED_RESPONSE,
+            "provider output contains non-JSON-compatible values",
+            details={"request_id": request.request_id, "cause_type": type(error).__name__},
+        ) from error
+    violation = scan_unsafe_output(parsed)
+    if violation is not None:
+        raise ModelInvocationError(
+            ModelErrorCode.UNSAFE_OUTPUT,
+            "provider output contains executable or injected content",
+            details={"request_id": request.request_id, "reason": violation},
+        )
+    max_chars = request.max_output_tokens * _MAX_CHARS_PER_TOKEN
+    if len(content) > max_chars:
+        raise ModelInvocationError(
+            ModelErrorCode.OUTPUT_LIMIT_EXCEEDED,
+            "provider output exceeds the configured size bound",
+            details={"request_id": request.request_id, "max_chars": str(max_chars)},
+        )
+    usage = map_usage(getattr(response, "usage", None))
+    if usage.completion_tokens > request.max_output_tokens:
+        raise ModelInvocationError(
+            ModelErrorCode.OUTPUT_LIMIT_EXCEEDED,
+            "provider output exceeds the configured token bound",
+            details={
+                "request_id": request.request_id,
+                "max_output_tokens": str(request.max_output_tokens),
+            },
+        )
+    response_id = getattr(response, "id", None)
+    if not isinstance(response_id, str) or not _RESPONSE_ID_PATTERN.match(response_id):
+        response_id = f"openai-{uuid.uuid4().hex[:16]}"
+    content = {key: value for key, value in parsed.items() if value is not None}
+    return ModelResponse(
+        response_id=response_id,
+        request_id=request.request_id,
+        content=content,
+        usage=usage,
+    )
+
+
+def map_usage(usage: Any) -> ModelUsage:
+    """Map valid OpenAI usage fields into consistent bounded usage.
+
+    Missing or invalid fields become zero; a vendor-reported total that is
+    inconsistent with prompt + completion is recomputed so the bounded
+    ``ModelUsage`` invariant (total equals prompt plus completion) holds.
+    """
+    prompt = _bounded_token_count(getattr(usage, "prompt_tokens", None))
+    completion = _bounded_token_count(getattr(usage, "completion_tokens", None))
+    total = _bounded_token_count(getattr(usage, "total_tokens", None))
+    if total != prompt + completion:
+        total = prompt + completion
+    return ModelUsage(
+        prompt_tokens=prompt, completion_tokens=completion, total_tokens=total
+    )
+
+
+def _bounded_token_count(value: Any) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        return 0
+    if value < 0 or value > _MAX_TOKEN_COUNT:
+        return 0
+    return value
+
+
+def _check_json_compatible(value: Any, path: str) -> None:
+    """Reject anything that cannot cross a JSON wire boundary (bounded)."""
+    if isinstance(value, (str, int, float, bool, type(None))):
+        return
+    if isinstance(value, dict):
+        if len(value) > _MAX_JSON_KEYS:
+            raise ValueError(f"{path} exceeds the bounded key count {_MAX_JSON_KEYS}")
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise ValueError(f"{path} contains a non-string key")
+            _check_json_compatible(item, f"{path}.{key}")
+        return
+    if isinstance(value, list):
+        if len(value) > _MAX_JSON_KEYS:
+            raise ValueError(f"{path} exceeds the bounded item count {_MAX_JSON_KEYS}")
+        for index, item in enumerate(value):
+            _check_json_compatible(item, f"{path}[{index}]")
+        return
+    raise ValueError(f"{path} contains a non-JSON-compatible value ({type(value).__name__})")

nl2data_openai/provider.py

@@ -0,0 +1,261 @@
+"""The OpenAI structured-output provider implementing the core contract.
+
+``OpenAIModelProvider`` is an independent distribution implementing the
+provider-neutral async :class:`ModelProvider` port.  The vendor client is
+built lazily on first generation - never at import, construction, or
+capability inspection - from an injected client factory, an injected
+API-key resolver, or the ``OPENAI_API_KEY`` environment variable.
+Credentials are consumed only during client construction and never enter
+core models, request metadata, workflow state, telemetry, or errors.  The
+provider performs exactly one bounded vendor request per ``generate()``;
+retry and timeout policy stays with :class:`IntentResolver`.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from typing import Any
+
+from nl2data_core.ai.errors import ModelErrorCode, ModelInvocationError
+from nl2data_core.ai.instructions import ResponseMode
+from nl2data_core.ai.models import ModelInvocationRequest, ModelResponse
+from nl2data_core.ai.protocol import ModelCapabilities
+from nl2data_core.canonical import canonical_json
+
+from .client import (
+    build_openai_client,
+    is_authentication_error,
+    is_connection_error,
+    is_rate_limit_error,
+    is_status_error,
+    is_timeout_error,
+)
+from .config import OpenAIProviderConfig
+from .mapping import build_messages, build_request_params, extract_response
+
+
+class OpenAIModelProvider:
+    """OpenAI structured-output provider satisfying :class:`ModelProvider`.
+
+    Credentials are host-injected through ``api_key_resolver`` (a zero- or
+    one-argument callable returning the key) or ``client_factory`` (a
+    callable returning a ready client - fake or host-managed).  Without
+    either, the ``OPENAI_API_KEY`` environment variable is used at client
+    build time.  Keys are never stored on the provider, in requests, or in
+    errors.
+    """
+
+    def __init__(
+        self,
+        config: OpenAIProviderConfig,
+        *,
+        api_key_resolver: Callable[[], str] | None = None,
+        client_factory: Callable[[], Any] | None = None,
+    ) -> None:
+        self._config = config
+        self._api_key_resolver = api_key_resolver
+        self._client_factory = client_factory
+        self._client: Any = None
+        self._call_count = 0
+        self._closed = False
+        self._capabilities = ModelCapabilities(
+            provider_name="openai",
+            supports_structured_output=True,
+            max_input_chars=config.max_input_chars,
+            max_output_tokens=config.max_output_tokens,
+            usage_accounting=True,
+            instruction_versions=frozenset({1}),
+            features=frozenset({"structured_output", "json_schema"}),
+        )
+
+    @property
+    def call_count(self) -> int:
+        """Number of vendor requests issued (one per ``generate()``)."""
+        return self._call_count
+
+    def capabilities(self) -> ModelCapabilities:
+        """Configuration-derived capabilities; no network or SDK access."""
+        return self._capabilities
+
+    async def generate(self, request: ModelInvocationRequest) -> ModelResponse:
+        """Generate one bounded structured response.
+
+        One vendor request per call; failures are raised as normalized
+        :class:`ModelInvocationError` values.  Retry and timeout policy is
+        owned by the resolver, never by this provider.
+        """
+        if self._closed:
+            raise ModelInvocationError(
+                ModelErrorCode.PROVIDER_UNAVAILABLE,
+                "provider is closed",
+                details={"request_id": request.request_id},
+            )
+        self._check_bounds(request)
+        self._check_instruction(request)
+        client = self._get_client()
+        params = build_request_params(request, self._config)
+        self._call_count += 1
+        try:
+            response = await client.chat.completions.create(**params)
+        except Exception as error:
+            raise self._map_error(error, request) from error
+        return extract_response(response, request)
+
+    async def close(self) -> None:
+        """Release the lazily built client exactly once (idempotent).
+
+        Native client exceptions are swallowed so provider internals never
+        leak across the contract boundary.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        client = self._client
+        self._client = None
+        close = getattr(client, "close", None)
+        if close is None:
+            return
+        try:
+            await close()
+        except Exception:
+            return
+
+    def _check_bounds(self, request: ModelInvocationRequest) -> None:
+        message_chars = sum(
+            len(message["content"])
+            for message in build_messages(
+                request,
+                merge_developer_into_system=self._config.merge_developer_into_system,
+            )
+        )
+        input_chars = message_chars + len(canonical_json(request.context))
+        if input_chars > self._config.max_input_chars:
+            raise ModelInvocationError(
+                ModelErrorCode.INVALID_REQUEST,
+                "invocation input exceeds the provider maximum",
+                details={
+                    "input_chars": str(input_chars),
+                    "max_input_chars": str(self._config.max_input_chars),
+                },
+            )
+        if request.max_output_tokens > self._config.max_output_tokens:
+            raise ModelInvocationError(
+                ModelErrorCode.OUTPUT_LIMIT_EXCEEDED,
+                "requested output exceeds the provider output bound",
+                details={"max_output_tokens": str(self._config.max_output_tokens)},
+            )
+
+    def _check_instruction(self, request: ModelInvocationRequest) -> None:
+        instruction = request.instruction
+        if instruction is None:
+            return
+        if instruction.bundle_version not in self._capabilities.instruction_versions:
+            raise ModelInvocationError(
+                ModelErrorCode.INSTRUCTION_VERSION_INCOMPATIBLE,
+                "provider does not support the instruction bundle version",
+                details={"instruction_version": str(instruction.bundle_version)},
+            )
+        if instruction.output_contract.response_mode is not ResponseMode.STRUCTURED:
+            raise ModelInvocationError(
+                ModelErrorCode.INVALID_REQUEST,
+                "provider only supports structured output",
+                details={"response_mode": instruction.output_contract.response_mode.value},
+            )
+
+    def _get_client(self) -> Any:
+        if self._client is None:
+            self._client = self._build_client()
+        return self._client
+
+    def _build_client(self) -> Any:
+        if self._client_factory is not None:
+            client = self._client_factory()
+            if client is None:
+                raise ModelInvocationError(
+                    ModelErrorCode.PROVIDER_UNAVAILABLE,
+                    "the injected client factory returned no client",
+                    details={"cause_type": "ClientFactoryError"},
+                )
+            return client
+        api_key: str | None = None
+        if self._api_key_resolver is not None:
+            api_key = self._api_key_resolver()
+        if not api_key:
+            api_key = os.environ.get("OPENAI_API_KEY") or None
+        if api_key is None:
+            raise ModelInvocationError(
+                ModelErrorCode.PROVIDER_UNAVAILABLE,
+                "no OpenAI credentials are configured",
+                details={"cause_type": "MissingCredentials"},
+            )
+        return build_openai_client(self._config, api_key=api_key)
+
+    @staticmethod
+    def _map_error(
+        error: BaseException, request: ModelInvocationRequest
+    ) -> ModelInvocationError:
+        """Map SDK failures to the existing safe error taxonomy.
+
+        Authentication and configuration failures are non-retryable;
+        timeout, connection, and rate-limit failures are retryable
+        availability errors; request/schema failures are non-retryable
+        request errors.  Vendor exception text, endpoints, and credentials
+        never enter the mapped error.
+        """
+        request_id = request.request_id
+        if is_timeout_error(error):
+            return ModelInvocationError(
+                ModelErrorCode.MODEL_TIMEOUT,
+                "model call timed out",
+                details={"request_id": request_id, "cause_type": type(error).__name__},
+                cause=error,
+            )
+        if is_rate_limit_error(error):
+            return ModelInvocationError(
+                ModelErrorCode.PROVIDER_UNAVAILABLE,
+                "provider rate limit exceeded",
+                details={"request_id": request_id, "cause_type": type(error).__name__},
+                cause=error,
+            )
+        if is_connection_error(error):
+            return ModelInvocationError(
+                ModelErrorCode.PROVIDER_UNAVAILABLE,
+                "provider is unreachable",
+                details={"request_id": request_id, "cause_type": type(error).__name__},
+                cause=error,
+            )
+        if is_authentication_error(error):
+            return ModelInvocationError(
+                ModelErrorCode.INVALID_REQUEST,
+                "provider rejected the request credentials",
+                details={"request_id": request_id, "cause_type": type(error).__name__},
+                cause=error,
+            )
+        if is_status_error(error):
+            status = getattr(error, "status_code", None)
+            error_details = {
+                "request_id": request_id,
+                "cause_type": type(error).__name__,
+            }
+            if isinstance(status, int):
+                error_details["status_code"] = str(status)
+            if isinstance(status, int) and (status >= 500 or status == 429):
+                return ModelInvocationError(
+                    ModelErrorCode.PROVIDER_UNAVAILABLE,
+                    "provider service error",
+                    details=error_details,
+                    cause=error,
+                )
+            return ModelInvocationError(
+                ModelErrorCode.INVALID_REQUEST,
+                "provider rejected the request",
+                details=error_details,
+                cause=error,
+            )
+        return ModelInvocationError(
+            ModelErrorCode.UNKNOWN_MODEL_ERROR,
+            "unexpected provider error",
+            details={"request_id": request_id, "cause_type": type(error).__name__},
+            cause=error,
+        )

nl2data_openai-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: nl2data-openai
+Version: 0.1.0
+Summary: OpenAI structured-output provider for the nl2data-core model provider boundary.
+Author: NL2Data Contributors
+License: Apache-2.0
+Keywords: nl2data,openai,structured output,model provider
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: nl2data-core>=0.1.0
+Requires-Dist: openai<3,>=1.40
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+
+# nl2data-openai
+
+An optional OpenAI structured-output provider for
+[nl2data-core](https://github.com/emmansun/nl2data-core). It implements the
+provider-neutral asynchronous `ModelProvider` contract: bounded
+`ModelInvocationRequest` in, typed `ModelResponse`/normalized
+`ModelInvocationError` out, with the OpenAI SDK isolated to this package.
+
+The core import boundary never loads the OpenAI SDK; this package imports
+it **lazily** at client build time — never at import, construction, or
+capability inspection.
+
+## Install
+
+```bash
+pip install nl2data-openai
+```
+
+Requires Python 3.11+, `nl2data-core>=0.1.0`, and `openai>=1.40,<3`.
+
+From a source checkout:
+
+```bash
+pip install -e ".[dev]"                 # from the repository root (core)
+pip install -e packages/nl2data-openai  # this package (editable)
+```
+
+## Public surface
+
+```python
+from nl2data_openai import OpenAIProviderConfig, OpenAIModelProvider
+```
+
+- `OpenAIProviderConfig` — vendor `model_name` plus bounded invocation
+  settings: `max_input_chars`, `max_output_tokens`, `temperature`,
+  `timeout_seconds`, optional `base_url` and `organization`. Capabilities are derived from this
+  configuration **without any network call**.
+- `OpenAIModelProvider` — the `ModelProvider` port implementation.
+  `close()` is idempotent and never leaks native clients or exceptions.
+
+## Credential injection
+
+API keys never enter core models, configuration fingerprints, request
+metadata, workflow state, telemetry, or errors. Inject them through one
+of:
+
+1. An `api_key_resolver` callable at provider construction, or
+2. A `client_factory` at provider construction, or
+3. The `OPENAI_API_KEY` environment variable — read **only when the
+   client is first built**.
+
+```python
+import os
+
+from nl2data_openai import OpenAIProviderConfig, OpenAIModelProvider
+
+provider = OpenAIModelProvider(
+    config=OpenAIProviderConfig(model_name="gpt-4o-mini"),
+    api_key_resolver=lambda: os.environ["OPENAI_API_KEY"],  # host-owned
+)
+```
+
+See [Secrets and live testing](../../docs/operations/secrets.md) for the
+full credential-handling contract.
+
+## Gateway compatibility
+
+Set `base_url` to point at any OpenAI-compatible gateway (OpenAI,
+Azure OpenAI-compatible endpoints, or a self-hosted proxy):
+
+```python
+OpenAIProviderConfig(
+    model_name="deployed-model",
+    base_url="https://your-gateway.example/v1",   # host-owned endpoint
+    timeout_seconds=60,
+)
+```
+
+`base_url` and `organization` are bounded configuration fields; the
+endpoint itself is a host-owned setting and never part of core
+configuration or evidence.
+
+## Model selection and limits
+
+`OpenAIProviderConfig` carries `model_name` plus bounded invocation
+settings (`max_input_chars`, `max_output_tokens`, `temperature`,
+`timeout_seconds`, optional `base_url`, `organization`). Provider calls
+are bounded by the resolver's attempt budget; the provider performs
+**exactly one vendor request per `generate()` call** — timeout, retry,
+and attempt-budget policy belong to `IntentResolver`.
+
+## Failure classification
+
+| Condition | Normalized result |
+| --- | --- |
+| Authentication/configuration failure | Non-retryable `INVALID_REQUEST` |
+| Timeout, connection, rate-limit, transient service error | Retryable `MODEL_TIMEOUT` / `PROVIDER_UNAVAILABLE` |
+
+## Live testing
+
+An opt-in live evaluation profile (`run_live_openai_evaluation` in
+`nl2data_openai.live_evaluation`) runs the deterministic AI dataset
+against the real provider and classifies every case as `verified`,
+`unavailable`, or `skipped`. Without injected credentials/factory or
+`OPENAI_API_KEY`, every case is `skipped` — default CI needs no
+credentials and makes no network access.
+
+Local run from the repository root (credentials from the environment
+only — the script never writes them to disk or includes them in output):
+
+```bash
+$env:OPENAI_API_KEY = "..."          # host secret injection, never committed
+$env:OPENAI_BASE_URL = "https://api.openai.com/v1"
+$env:OPENAI_MODEL = "gpt-4o-mini"
+$env:OPENAI_TIMEOUT_SECONDS = "60"   # optional
+$env:OPENAI_LIVE_CASES = "normal-intent"  # optional, comma-separated
+python scripts/run_openai_live.py
+```
+
+Exit code is 0 only when every selected case is `verified`. Evidence
+carries only protected fingerprints and normalized codes.
+
+## Rollback
+
+Swap the provider back to the core's deterministic `FakeModelProvider`
+(`nl2data_core.ai.fake` — contributor-only) at composition time to remove
+the SDK dependency and network access while keeping the same resolver,
+governance, and evaluation gates. No runtime migration is involved: the
+provider is a composition input, so rollback is a deployment decision.
+
+## More documentation
+
+- [Documentation index](../../docs/README.md)
+- [Adding a model provider](../../docs/development/adding-adapter-or-provider.md)
+- [Secrets and live testing](../../docs/operations/secrets.md)
+- [Capabilities and support](../../docs/reference/capabilities.md)

nl2data_openai-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+nl2data_openai/__init__.py,sha256=DhExTiTU9vWrPyYR-wbVl1ZGhM-yon3wVajQG7b4quo,575
+nl2data_openai/client.py,sha256=cXS9qxrTYVsyY4kIPdBXhXfiQlediMvrCL04EHMgg6M,3424
+nl2data_openai/config.py,sha256=CbuLcmRUmg4WZZfreW72-TrevdYHrhmbSVki3DheaTw,2645
+nl2data_openai/live_evaluation.py,sha256=fudITPskP7Bbqt7Tg8-S-uSz6jmdwLe64duCtdCDEFU,10228
+nl2data_openai/mapping.py,sha256=p1XDiFaaI1dnHZE7ECDJWCFNT4PkmJ2Qc82ChOxlE1Y,16856
+nl2data_openai/provider.py,sha256=aKVOITFWJNqApolmmbbq4jGqeJydY1YSVv4LvFv1Mv4,10886
+nl2data_openai-0.1.0.dist-info/METADATA,sha256=HlL6PRTxY3eYbmqXz80LMfo-ngFPbIbSoTn1PxlR-MY,5856
+nl2data_openai-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nl2data_openai-0.1.0.dist-info/top_level.txt,sha256=Z_Ug_yukpXrNBcJa7iNBXg4wTFk5u8mXRfhfzUQxbrI,15
+nl2data_openai-0.1.0.dist-info/RECORD,,

nl2data_openai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nl2data_openai-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nl2data_openai