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 theOpenAI(...)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_KEYtakes precedence over a key inopenai_initwhen 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.