Product contract

openai-sdk-helpers complements the official openai and openai-agents Python packages. It provides reusable production primitives without replacing the SDKs, hiding API calls, owning application prompts, or becoming a universal agent framework.

Every public helper should be:

• typed and predictable;
• thin enough that official SDK concepts remain recognizable;
• explicit about network calls, resource ownership, and cleanup;
• usable without unrelated optional integrations;
• tested without requiring paid API calls in pull-request CI;
• backward-compatible or accompanied by deliberate migration guidance.

See PRODUCT.md for the full product vision and feature acceptance test.

Installation

The core package installs both official OpenAI Python SDKs and no UI or LangExtract dependency:

pip install openai-sdk-helpers

Optional profiles:

pip install "openai-sdk-helpers[extract]"  # LangExtract-backed extraction
pip install "openai-sdk-helpers[ui]"       # Streamlit application helpers
pip install "openai-sdk-helpers[all]"      # All current optional capabilities

Python 3.10–3.13 is validated in CI. The distribution includes py.typed. See docs/installation.md for profile details, feature-specific SDK requirements, and missing-extra behavior.

Choose a surface

Responses

Use openai_sdk_helpers.response when the application needs direct control of Responses API inputs, response identifiers, message history, custom tool handlers, files, or raw streaming events.

from openai_sdk_helpers import OpenAISettings
from openai_sdk_helpers.response import ResponseBase

settings = OpenAISettings.from_env()

with ResponseBase(
    name="reviewer",
    instructions="Review the supplied code.",
    tools=None,
    output_structure=None,
    tool_handlers={},
    openai_settings=settings,
) as response:
    result = response.run_sync("Review: def add(a, b): return a + b")
    print(result)

Agents

Use openai_sdk_helpers.agent when the application benefits from the official Agents SDK loop, tools, sessions, guardrails, handoffs, or tracing.

from openai_sdk_helpers.agent import SummarizerAgent

agent = SummarizerAgent(default_model="your-model")
result = agent.run_sync("Summarize this text in one sentence.")
print(result.text)

Managed Agents API

Use openai_sdk_helpers.managed_agents when the application needs OpenAI-managed durable agent sessions and the managed execution harness. This surface requires an OpenAI Python SDK exposing beta.agents.sessions (3.13.0 or later) without raising the package-wide SDK minimum for other helpers.

from openai import OpenAI
from openai_sdk_helpers.managed_agents import ManagedAgentsClient

client = OpenAI()
managed = ManagedAgentsClient(client)
session = managed.create_session(
    environment={"type": "openai_hosted"},
    agent_id="agent_123",
    input="Inspect the repository.",
)

Streaming, artifacts, subagents, and other evolving beta resources remain available directly through managed.sessions and managed.agents. See docs/managed-agents.md for compatibility and execution boundaries.

Decisions

Use openai_sdk_helpers.decisions for fast typed predicates, fixed choices, and ordered scoring when generation or an agent loop would be unnecessary. This surface requires an OpenAI Python SDK exposing client.decisions.create (3.26.0 or later) without raising the package-wide SDK minimum.

from openai import OpenAI
from openai_sdk_helpers.decisions import DecisionsClient

decision = DecisionsClient(OpenAI())
answer = decision.predicate(
    "The request asks for a routine account lookup.",
    instructions="Should this request use the standard support path?",
    name="standard_path",
)

Batch questions, multimodal inputs, usage, refusals, and future model identifiers remain available through the official SDK-shaped interface. See docs/decisions.md for the execution boundary and examples.

Codex plugins

Use openai_sdk_helpers.codex when a separately packaged capability should register typed commands through deterministic entry-point discovery.

openai-helpers codex plugins
openai-helpers codex commands

See docs/codex-plugins.md for the plugin protocol, lifecycle, discovery, compatibility, and packaging guide.

Direct SDK calls

Use the official SDK directly when a package helper would only rename parameters or obscure the underlying client, resource, response, event, or exception. Access to underlying SDK objects is part of this project's escape- hatch policy.

The canonical inventory of shipped and planned surfaces is docs/capabilities.md.

Core capabilities

• centralized OpenAI settings and client creation;
• optional shared operation metadata and lifecycle observers;
• explicit conversation-state ownership and persistence contracts;
• Responses API orchestration, structured outputs, files, tools, and websocket helpers;
• Agents SDK wrappers, runners, search workflows, and reusable text agents;
• capability-gated managed Agents API session lifecycle helpers;
• capability-gated Decisions API helpers for predicates, choices, and scores;
• typed Pydantic structures and Jinja prompt rendering;
• file and vector-store helpers;
• output validation and shared tool contracts;
• deterministic Codex plugin registration, discovery, inspection, and lifecycle;
• optional LangExtract and Streamlit integrations;
• local CLI inspection without hidden API calls.

Detailed maturity, installation, execution, and escape-hatch information lives only in the capability matrix.

Configuration

OpenAISettings loads standard configuration from environment variables or a local .env file and creates official SDK clients:

from openai_sdk_helpers import OpenAISettings

settings = OpenAISettings.from_env()
client = settings.create_client()

Common variables include OPENAI_API_KEY, OPENAI_ORG_ID, OPENAI_PROJECT_ID, OPENAI_BASE_URL, OPENAI_MODEL, OPENAI_TIMEOUT, and OPENAI_MAX_RETRIES. Uncommon official client parameters remain available through extra_client_kwargs.

Security

Report suspected vulnerabilities through the repository's confidential GitHub private vulnerability reporting flow, not a public issue. Never include real credentials, customer prompts, model responses, uploaded files, or production logs. See SECURITY.md for supported versions, reporting guidance, and trust boundaries.

Documentation

• Capability matrix — canonical feature inventory and maturity
• Public API — intentional import surface
• Operation context — lifecycle hooks, usage, diagnostics, and SDK boundaries
• Conversation state — ownership modes, compatibility, persistence, and migration
• Managed Agents API — managed session helpers, compatibility, streaming, and escape hatches
• Decisions API — fast predicate, choice, and score helpers with compatibility boundaries
• Installation profiles — core, optional dependencies, and feature-specific SDK requirements
• Supported examples — executable and illustrative example policy
• Security policy — confidential reporting and supported versions
• Release checklist — security and publication gates
• Codex plugins — protocol, lifecycle, discovery, and packaging
• 0.8 Codex migration — compatibility guidance
• Publishing — OIDC release process and recovery
• Product vision — mission, users, principles, and non-goals
• Roadmap — shipped foundations and release gates
• Changelog — user-visible changes

Development

git clone https://github.com/fatmambot33/openai-sdk-helpers.git
cd openai-sdk-helpers
pip install -e ".[dev]"

pydocstyle src
black --check --diff .
pyright src
pytest -q --cov=src --cov-report=term-missing --cov-fail-under=70
python scripts/check_markdown_links.py

Additional CI validates Python 3.10–3.13, minimum and latest compatible OpenAI SDK versions, built distributions, installed entry points, supported examples, and isolated core, extract, ui, and all profiles.

See CONTRIBUTING.md and AGENTS.md before changing public behavior.

Scope boundaries

This project is not an end-user application, hosted platform, replacement SDK, universal agent framework, prompt catalog, storage service, protocol implementation, or transport framework. Application-specific business logic belongs in consuming projects.

Managed Agents API helpers shipped in 0.10.0. Decisions API helpers are the next priority because they add a distinct OpenAI execution primitive; Realtime API helpers follow afterward. Issue order and release gates are tracked in ROADMAP.md.

License

Licensed under the MIT License.