nl2data-openai 0.1.0__tar.gz

nl2data_openai-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,136 @@
+# 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/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nl2data-openai"
+version = "0.1.0"
+description = "OpenAI structured-output provider for the nl2data-core model provider boundary."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "NL2Data Contributors" }]
+keywords = ["nl2data", "openai", "structured output", "model provider"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "nl2data-core>=0.1.0",
+    "openai>=1.40,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.10",
+    "ruff>=0.5",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src"]
+mypy_path = ["../../src"]
+check_untyped_defs = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

nl2data_openai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nl2data_openai-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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