openai-agents-python-providers 1.0.0__tar.gz

openai_agents_python_providers-1.0.0/.env.example

@@ -0,0 +1,11 @@
+# Temporal Configuration
+# Use 'host.docker.internal:7233' if running in Docker and Temporal is on the host
+TEMPORAL_ADDRESS=localhost:7233
+TASK_QUEUE=temporal-openai-agents-demo
+
+# Model Provider Configuration
+# PROVIDER_TYPE can be 'ollama' or 'llamacpp'
+PROVIDER_TYPE=ollama
+# Use 'http://host.docker.internal:11434/v1' if running in Docker and Ollama is on the host
+PROVIDER_URL=http://localhost:11434/v1
+MODEL_NAME=llama3.2

openai_agents_python_providers-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --group dev --group temporal
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Run tests
+        run: uv run python -m pytest -v

openai_agents_python_providers-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: Semantic release
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.version_check.outputs.will_release }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --group dev --group temporal
+
+      - name: Check for releasable commits
+        id: version_check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          version=$(uv run semantic-release version --print 2>/dev/null || true)
+          if [ -n "$version" ]; then
+            echo "will_release=true" >> $GITHUB_OUTPUT
+          else
+            echo "will_release=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run semantic release
+        if: steps.version_check.outputs.will_release == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run semantic-release version --push
+
+      - name: Build package
+        if: steps.version_check.outputs.will_release == 'true'
+        run: uv build
+
+      - name: Upload build artifacts
+        if: steps.version_check.outputs.will_release == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

openai_agents_python_providers-1.0.0/.gitignore

@@ -0,0 +1,36 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+*.log
+site/

openai_agents_python_providers-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-05-10)
+
+- Initial Release

openai_agents_python_providers-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Toscano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openai_agents_python_providers-1.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: openai-agents-python-providers
+Version: 1.0.0
+Summary: Ollama and llama.cpp providers for the OpenAI Agents SDK
+Project-URL: Homepage, https://github.com/GethosTheWalrus/openai-agents-python-providers
+Project-URL: Repository, https://github.com/GethosTheWalrus/openai-agents-python-providers
+Project-URL: Issues, https://github.com/GethosTheWalrus/openai-agents-python-providers/issues
+Author-email: Mike Toscano <mike@miketoscano.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,llama.cpp,llm,ollama,openai,providers
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: openai-agents<1,>=0.16.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: temporal
+Requires-Dist: httpx>=0.27.0; extra == 'temporal'
+Requires-Dist: temporalio[openai-agents,opentelemetry]>=1.7.0; extra == 'temporal'
+Description-Content-Type: text/markdown
+
+# openai-agents-python-providers
+
+Community model providers for the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python).
+
+Because OpenAI's SDK is intentionally focused on first-party integrations, this package provides ready-to-use `ModelProvider` implementations for locally-hosted and OpenAI-compatible backends:
+
+| Provider | Backend |
+|---|---|
+| `OllamaProvider` | [Ollama](https://ollama.com/) |
+| `LlamaCppProvider` | [llama.cpp](https://github.com/ggerganov/llama.cpp), [vLLM](https://github.com/vllm-project/vllm), and any OpenAI-compatible server |
+
+## Installation
+
+```bash
+pip install openai-agents-python-providers
+
+# or with temporal support
+pip install "openai-agents-python-providers[temporal]"
+```
+
+## Quickstart
+
+### Ollama
+
+Make sure Ollama is running and you have a model pulled:
+
+```python
+import asyncio
+import os
+from agents import Agent, Runner, RunConfig
+from openai_agents_providers import OllamaProvider
+
+# Configure via environment or parameters
+provider = OllamaProvider(
+    model=os.getenv("MODEL_NAME", "llama3.2"),
+    base_url=os.getenv("PROVIDER_URL", "http://localhost:11434/v1")
+)
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+)
+
+async def main():
+    result = await Runner.run(
+        agent,
+        "What is the capital of France?",
+        run_config=RunConfig(model_provider=provider),
+    )
+    print(result.final_output)
+
+asyncio.run(main())
+```
+
+### llama.cpp
+
+Start a llama.cpp server:
+
+```bash
+llama-server --model my-model.gguf --port 8080
+```
+
+```python
+import asyncio
+import os
+from agents import Agent, Runner, RunConfig
+from openai_agents_providers import LlamaCppProvider
+
+provider = LlamaCppProvider(
+    base_url=os.getenv("PROVIDER_URL", "http://localhost:8080/v1"),
+    model=os.getenv("MODEL_NAME"),  # optional
+    api_key="sk-anything",
+)
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+)
+
+async def main():
+    result = await Runner.run(
+        agent,
+        "Explain quantum entanglement in one sentence.",
+        run_config=RunConfig(model_provider=provider),
+    )
+    print(result.final_output)
+
+asyncio.run(main())
+```
+
+### Temporal Integration
+
+This package works seamlessly with the [Temporal OpenAI Agents Plugin](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents). You can use local providers like `OllamaProvider` or `LlamaCppProvider` while running agents durably in Temporal workflows.
+
+See [examples/temporal/](examples/temporal/) for a complete "tool-as-activity" demonstration.
+
+```bash
+# Install temporal dependencies
+uv sync --group temporal
+
+# Start the worker (pointing to your infrastructure)
+TEMPORAL_ADDRESS="temporal.example.com:7233" \
+PROVIDER_TYPE="ollama" \
+MODEL_NAME="llama3.2" \
+uv run examples/temporal/worker.py
+
+# Start the workflow
+TEMPORAL_ADDRESS="temporal.example.com:7233" \
+uv run examples/temporal/starter.py "What is the weather where I am?"
+```
+
+## API Reference
+
+### `OllamaProvider`
+
+```python
+OllamaProvider(
+    *,
+    base_url: str = "http://localhost:11434/v1",
+    model: str | None = None,
+    api_key: str = "ollama",
+    **kwargs,          # forwarded to AsyncOpenAI
+)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `base_url` | `http://localhost:11434/v1` | Ollama API base URL |
+| `model` | `None` | Model name (e.g. `"llama3.2"`, `"qwen3:8b"`). Overrides any name passed by the agent. |
+| `api_key` | `"ollama"` | Ignored by Ollama; required by the OpenAI SDK. |
+
+### `LlamaCppProvider`
+
+```python
+LlamaCppProvider(
+    *,
+    base_url: str,
+    model: str | None = None,
+    api_key: str = "sk-anything",
+    **kwargs,          # forwarded to AsyncOpenAI
+)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `base_url` | *(required)* | OpenAI-compatible API base URL, e.g. `http://localhost:8080/v1`. |
+| `model` | `None` | Model name. Overrides any name passed by the agent. |
+| `api_key` | `"sk-anything"` | Ignored by most backends; required by the OpenAI SDK. |
+
+## License
+
+MIT

openai_agents_python_providers-1.0.0/README.md

@@ -0,0 +1,152 @@
+# openai-agents-python-providers
+
+Community model providers for the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python).
+
+Because OpenAI's SDK is intentionally focused on first-party integrations, this package provides ready-to-use `ModelProvider` implementations for locally-hosted and OpenAI-compatible backends:
+
+| Provider | Backend |
+|---|---|
+| `OllamaProvider` | [Ollama](https://ollama.com/) |
+| `LlamaCppProvider` | [llama.cpp](https://github.com/ggerganov/llama.cpp), [vLLM](https://github.com/vllm-project/vllm), and any OpenAI-compatible server |
+
+## Installation
+
+```bash
+pip install openai-agents-python-providers
+
+# or with temporal support
+pip install "openai-agents-python-providers[temporal]"
+```
+
+## Quickstart
+
+### Ollama
+
+Make sure Ollama is running and you have a model pulled:
+
+```python
+import asyncio
+import os
+from agents import Agent, Runner, RunConfig
+from openai_agents_providers import OllamaProvider
+
+# Configure via environment or parameters
+provider = OllamaProvider(
+    model=os.getenv("MODEL_NAME", "llama3.2"),
+    base_url=os.getenv("PROVIDER_URL", "http://localhost:11434/v1")
+)
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+)
+
+async def main():
+    result = await Runner.run(
+        agent,
+        "What is the capital of France?",
+        run_config=RunConfig(model_provider=provider),
+    )
+    print(result.final_output)
+
+asyncio.run(main())
+```
+
+### llama.cpp
+
+Start a llama.cpp server:
+
+```bash
+llama-server --model my-model.gguf --port 8080
+```
+
+```python
+import asyncio
+import os
+from agents import Agent, Runner, RunConfig
+from openai_agents_providers import LlamaCppProvider
+
+provider = LlamaCppProvider(
+    base_url=os.getenv("PROVIDER_URL", "http://localhost:8080/v1"),
+    model=os.getenv("MODEL_NAME"),  # optional
+    api_key="sk-anything",
+)
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+)
+
+async def main():
+    result = await Runner.run(
+        agent,
+        "Explain quantum entanglement in one sentence.",
+        run_config=RunConfig(model_provider=provider),
+    )
+    print(result.final_output)
+
+asyncio.run(main())
+```
+
+### Temporal Integration
+
+This package works seamlessly with the [Temporal OpenAI Agents Plugin](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents). You can use local providers like `OllamaProvider` or `LlamaCppProvider` while running agents durably in Temporal workflows.
+
+See [examples/temporal/](examples/temporal/) for a complete "tool-as-activity" demonstration.
+
+```bash
+# Install temporal dependencies
+uv sync --group temporal
+
+# Start the worker (pointing to your infrastructure)
+TEMPORAL_ADDRESS="temporal.example.com:7233" \
+PROVIDER_TYPE="ollama" \
+MODEL_NAME="llama3.2" \
+uv run examples/temporal/worker.py
+
+# Start the workflow
+TEMPORAL_ADDRESS="temporal.example.com:7233" \
+uv run examples/temporal/starter.py "What is the weather where I am?"
+```
+
+## API Reference
+
+### `OllamaProvider`
+
+```python
+OllamaProvider(
+    *,
+    base_url: str = "http://localhost:11434/v1",
+    model: str | None = None,
+    api_key: str = "ollama",
+    **kwargs,          # forwarded to AsyncOpenAI
+)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `base_url` | `http://localhost:11434/v1` | Ollama API base URL |
+| `model` | `None` | Model name (e.g. `"llama3.2"`, `"qwen3:8b"`). Overrides any name passed by the agent. |
+| `api_key` | `"ollama"` | Ignored by Ollama; required by the OpenAI SDK. |
+
+### `LlamaCppProvider`
+
+```python
+LlamaCppProvider(
+    *,
+    base_url: str,
+    model: str | None = None,
+    api_key: str = "sk-anything",
+    **kwargs,          # forwarded to AsyncOpenAI
+)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `base_url` | *(required)* | OpenAI-compatible API base URL, e.g. `http://localhost:8080/v1`. |
+| `model` | `None` | Model name. Overrides any name passed by the agent. |
+| `api_key` | `"sk-anything"` | Ignored by most backends; required by the OpenAI SDK. |
+
+## License
+
+MIT

openai_agents_python_providers-1.0.0/examples/README.md

@@ -0,0 +1,76 @@
+# Examples
+
+This directory contains examples of how to use the `openai-agents-python-providers` package.
+
+## Configuration
+
+All examples can be configured using environment variables. You can set these directly in your shell or use a `.env` file in the project root (see `.env.example` for a template).
+
+| Variable | Default | Description |
+|---|---|---|
+| `MODEL_NAME` | `llama3.2` | The LLM model name. |
+| `PROVIDER_URL` | *(varies)* | The API endpoint for the provider (Ollama or llama.cpp). |
+| `TEMPORAL_ADDRESS` | `localhost:7233` | Address of the Temporal server (Temporal demo only). |
+
+## Standalone Examples
+
+Located in `examples/standalone/`. These demonstrate using the providers directly with the OpenAI Agents SDK in a standard Python script.
+
+### Ollama
+
+```bash
+# Optional: override default model or URL
+export MODEL_NAME="qwen2.5:7b"
+export PROVIDER_URL="http://192.168.1.10:11434/v1"
+
+uv run examples/standalone/ollama_example.py
+```
+
+### llama.cpp
+
+```bash
+# Optional: override default URL
+export PROVIDER_URL="http://localhost:8080/v1"
+
+uv run examples/standalone/llama_cpp_example.py
+```
+
+---
+
+## Temporal Integration Example
+
+This is a comprehensive "tool-as-activity" demonstration showing how to run durable agents in [Temporal](https://temporal.io/).
+
+**Location:** [examples/temporal/](temporal/)
+
+### Quick Start (Local)
+
+```bash
+# Install temporal dependencies via extra
+pip install "openai-agents-python-providers[temporal]"
+
+# Or if using uv locally
+uv sync --group temporal
+
+# Start the worker (configure as needed)
+TEMPORAL_ADDRESS="temporal.example.com:7233" \
+PROVIDER_TYPE="ollama" \
+MODEL_NAME="llama3.2" \
+uv run examples/temporal/worker.py
+
+# Start the workflow
+TEMPORAL_ADDRESS="temporal.example.com:7233" \
+uv run examples/temporal/starter.py "What is the weather where I am?"
+```
+
+### Dockerized Test
+
+If you have Temporal or model providers running externally, you can run the demo in Docker:
+
+```bash
+cd examples/temporal
+docker-compose up --build worker
+docker-compose run --rm starter "What is the weather where I am?"
+```
+
+See the [Temporal README](temporal/README.md) for more configuration options.

openai_agents_python_providers-1.0.0/examples/standalone/llama_cpp_example.py

@@ -0,0 +1,47 @@
+"""Example: use LlamaCppProvider to run an agent against a local llama.cpp server.
+
+Prerequisites:
+  1. Install llama.cpp: https://github.com/ggerganov/llama.cpp
+  2. Start the server:
+       llama-server --model /path/to/your-model.gguf --port 8080
+  3. Install this package: pip install openai-agents-python-providers
+"""
+
+import asyncio
+import os
+
+from agents import Agent, RunConfig, Runner
+from dotenv import load_dotenv
+
+from openai_agents_providers import LlamaCppProvider
+
+
+async def main() -> None:
+    load_dotenv()
+    # Use environment variables for configuration
+    model = os.getenv("MODEL_NAME")  # optional for llama.cpp
+    base_url = os.getenv("PROVIDER_URL", "http://localhost:8080/v1")
+
+    print(f"Using model: {model or 'server default'} at {base_url}")
+
+    provider = LlamaCppProvider(
+        base_url=base_url,
+        model=model,
+        api_key="sk-anything",
+    )
+
+    agent = Agent(
+        name="Assistant",
+        instructions="You are a concise, helpful assistant.",
+    )
+
+    result = await Runner.run(
+        agent,
+        "Explain the phrase 'to err is human' in one sentence.",
+        run_config=RunConfig(model_provider=provider),
+    )
+    print(f"Result: {result.final_output}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

openai_agents_python_providers-1.0.0/examples/standalone/ollama_example.py

@@ -0,0 +1,42 @@
+"""Example: use OllamaProvider to run an agent against a local Ollama server.
+
+Prerequisites:
+  1. Install Ollama: https://ollama.com/
+  2. Pull a model: ollama pull llama3.2
+  3. Install this package: pip install openai-agents-python-providers
+"""
+
+import asyncio
+import os
+
+from agents import Agent, RunConfig, Runner
+from dotenv import load_dotenv
+
+from openai_agents_providers import OllamaProvider
+
+
+async def main() -> None:
+    load_dotenv()
+    # Use environment variables for configuration
+    model = os.getenv("MODEL_NAME", "llama3.2")
+    base_url = os.getenv("PROVIDER_URL", "http://localhost:11434/v1")
+
+    print(f"Using model: {model} at {base_url}")
+
+    provider = OllamaProvider(model=model, base_url=base_url)
+
+    agent = Agent(
+        name="Assistant",
+        instructions="You are a concise, helpful assistant.",
+    )
+
+    result = await Runner.run(
+        agent,
+        "What is the capital of France? Answer in one word.",
+        run_config=RunConfig(model_provider=provider),
+    )
+    print(f"Result: {result.final_output}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())