Skip to main content


Sinapsis
Sinapsis OpenAI

OpenAI APIs as dynamic, type-checked Sinapsis Templates.

Overview

sinapsis-openai integrates OpenAI's chat completions, speech transcription and translation, speech synthesis, image creation, image-to-image generation, and image inpainting into Sinapsis Agents. Input and output are handled through the framework's DataContainer and typed packets, so an OpenAI request can sit between readers, retrieval steps, local models, postprocessors and writers.

Dynamic Templates, not a hard-coded model catalogue

The integration is built on Sinapsis's BaseDynamicWrapperTemplate. Rather than manually maintaining a new Pydantic schema for every parameter introduced by the OpenAI Python SDK, each wrapper introspects SDK client and endpoint signatures and generates its Template class and configuration fields on demand.

This matters in a fast-moving API: when a compatible newer openai SDK exposes additional parameters or model identifiers, the dynamic wrappers can pick them up without a corresponding hand-written Sinapsis wrapper for every variant. The source of truth is the installed SDK and the provider's API, not an out-of-date, fixed list in this README. Installing this package does not automatically upgrade the OpenAI SDK or guarantee that every new endpoint is already wrapped.

The wrapper also keeps the boundary between the two kinds of configuration clear:

  • openai_init: parameters passed to the OpenAI(...) client, such as connection options, retries, or an API key.
  • model: model identifier selected for the Template's endpoint.
  • create / generate / edit: request-specific parameters reflected from the corresponding SDK method (depending on the Template).

The generated attributes are Pydantic-backed, so invalid or incompatible configurations can be surfaced during validation rather than scattered through custom integration code.

Bring your own OpenAI account and API key

Calls are made with your OpenAI API credentials and provider entitlements. The usual setup is an environment variable:

export OPENAI_API_KEY="your-openai-api-key"

The implementation also accepts a key through openai_init.api_key when using per-Template client configuration. In the current implementation a non-empty OPENAI_API_KEY environment variable takes precedence over openai_init.api_key. For multiple accounts or projects, configure the environment and client values deliberately. Do not commit credentials in Agent YAML files.

Requests use the account's model access, quotas, and billing; the package does not provide or proxy shared OpenAI credentials.

Installation

Python 3.13+ is required. Install the package from PyPI:

uv pip install sinapsis-openai
# or
pip install sinapsis-openai

For the runnable text-input example below, the data-readers extra installs the TextInput Template:

uv pip install "sinapsis-openai[data-readers]"

Optional features and dependencies

The base installation includes the dependencies required by the package. The following extras are declared in this package’s pyproject.toml; install only those needed by your workflow. They are standard Python optional dependencies, not separate execution profiles.

Extra Adds / when to select it
webapp-gradio Interactive Gradio demonstration. Dependencies: sinapsis[webapp]
data-readers Input adapters for example workflows. Dependencies: sinapsis-data-readers
all Bundle declared by this package; its manifest includes webapp-gradio, data-readers, audio-generation, image-generation, encode-results. It does not include data-writers.
audio-generation Audio generation and related audio-output dependencies. Dependencies: pydub, sinapsis-openai[encode-results]
image-generation Image generation and related image-output dependencies. Dependencies: numpy, pillow, sinapsis-openai[encode-results]
encode-results Encode generated results into useful Sinapsis data representations. Dependencies: sinapsis-generic-data-tools
data-writers Output adapters for example workflows. Dependencies: sinapsis-data-writers

For example:

uv pip install "sinapsis-openai[webapp-gradio]"

The manifest also defines development-only dependency groups: dev (ruff, pre-commit, ty). These support source development and testing and are not runtime extras.

Template families

Template What enters the Agent What it provides
OpenAIChatWrapper Text packets Chat completions returned as new TextPacket items.
OpenAIAudioTranscriptionWrapper Audio content / files Speech-to-text output for downstream text processing.
OpenAIAudioTranslationWrapper Audio content / files Audio translation to text using the supported translation endpoint.
OpenAIAudioCreationWrapper Text packets Generated audio for playback, storage or further processing.
OpenAIImageCreationWrapper Text prompt Generated images returned through the configured result representation.
OpenAIImageToImageGenerationWrapper Image and prompt Image generation conditioned on an existing image.
OpenAIImageInpaintingWrapper Image, optional mask, and prompt Editing of selected image regions.

The wrappers are defined in openai_chat.py, openai_audio.py, and openai_images.py. Actual generated class names and valid attribute fields depend on the installed SDK; inspect them with:

sinx templates show-all
sinx templates docstring OpenAIChatWrapper
sinx templates example-config OpenAIChatWrapper

Practical example: text input → OpenAI chat → result packet

Create my_openai_agent.yaml:

agent:
  name: my_openai_agent
  description: "Answer an incoming question through OpenAI"

templates:
  - template_name: Input
    class_name: InputTemplate
    attributes: {}

  - template_name: Question
    class_name: TextInput
    template_input: Input
    attributes:
      text: "Explain why native binary payloads matter in an AI pipeline."

  - template_name: Answer
    class_name: OpenAIChatWrapper
    template_input: Question
    attributes:
      model: gpt-4o-mini  # Replace with any supported model accessible to your account
      openai_init: {}
      create: {}
export OPENAI_API_KEY="your-openai-api-key"
sinx jobs run my_openai_agent.yaml

TextInput is provided by sinapsis-data-readers and installed through the data-readers extra shown above. The graph feeds a TextPacket to the chat wrapper and appends the generated response as another text packet. You can then chain validation, persistence, a search index or another model without adopting an OpenAI-specific data contract.

This example uses a commonly supported model identifier for illustration, not a permanent recommendation or list of currently available models. Models must be supported by the installed SDK and your OpenAI account.

Additional workflows

The package includes reference configurations for chat, audio generation, audio translation, image creation, image-to-image generation, and inpainting.

For example, a content workflow might generate a concise explanation with chat, turn the text into speech, and save both packets. An image workflow may start with a reference image and use inpainting only on designated regions. These examples share the same Agent graph model, but the required input packet type and endpoint parameters differ.

Runtime considerations

  • Network and cost: calls are remote API operations; latency, quotas, rate limits and billing come from OpenAI.
  • Credentials: pass your own key securely. OPENAI_API_KEY takes precedence over a key in openai_init when set.
  • API evolution: dynamic signatures reduce wrapper maintenance, but new SDK functionality still requires installing an SDK version that exposes it. Test model and endpoint compatibility when upgrading.
  • Packet output: generation and decoding are still governed by the chosen Template and its output mode; downstream steps should expect the appropriate text, image or audio packets.

Resources

License

Sinapsis open-source components are available under your choice of the MIT License or the Apache License 2.0, unless otherwise noted.

Metadata

Release files for sinapsis-openai 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sinapsis-openai 1.0.0
File Size Uploaded Provenance Actions
sinapsis_openai-1.0.0.tar.gz 77.6 kB Without provenance Details for sinapsis_openai-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sinapsis-openai 1.0.0
File Interpreter ABI Platform Actions
sinapsis_openai-1.0.0-py3-none-any.whl Python 3 none any Details for sinapsis_openai-1.0.0-py3-none-any.whl

Total release size: 106.8 kB

Release files / sinapsis_openai-1.0.0.tar.gz

Download URL sinapsis_openai-1.0.0.tar.gz
Size 77.6 kB
Tags Source
SHA-256 checksum
How to use checksums
96c6987fc7b073ddfc4b92df4157fc70975a55696c9cfc3d6f878fe655778741
BLAKE2b-256 checksum
How to use checksums
a7d5655fd0f38abd7a2cf0f487fb83699a36fe3c35db8dddaf3cd46c7f579b44
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.17

Release files / sinapsis_openai-1.0.0-py3-none-any.whl

Download URL sinapsis_openai-1.0.0-py3-none-any.whl
Size 29.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
188b8eeda3634a7e079318910ccdf97ec8284f502eef2a21aa030e090490ecc0
BLAKE2b-256 checksum
How to use checksums
d5f17d564bb33ad46bb5e6a57e911073b5d571bd8c220fa0e87db3cbd5c55683
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.17

Security for sinapsis-openai 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page