openai-agents-python-providers 1.0.0__py3-none-any.whl

openai_agents_providers/__init__.py

@@ -0,0 +1,35 @@
+"""Community model providers for the OpenAI Agents SDK.
+
+Provides ready-to-use :class:`~agents.ModelProvider` implementations for
+locally-hosted and OpenAI-compatible backends:
+
+- :class:`~openai_agents_providers.OllamaProvider` — Ollama (``http://localhost:11434/v1``)
+- :class:`~openai_agents_providers.LlamaCppProvider` — llama.cpp, vLLM, and any
+  other OpenAI-compatible server
+
+Usage example::
+
+    import os
+    from agents import Agent, Runner, RunConfig
+    from openai_agents_providers import OllamaProvider
+
+    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.")
+    result = await Runner.run(
+        agent,
+        "What is the capital of France?",
+        run_config=RunConfig(model_provider=provider),
+    )
+    print(result.final_output)
+"""
+
+from .llama_cpp_provider import LlamaCppProvider
+from .ollama_provider import OllamaProvider
+
+__all__ = [
+    "LlamaCppProvider",
+    "OllamaProvider",
+]

openai_agents_providers/llama_cpp_provider.py

@@ -0,0 +1,90 @@
+"""Provider for llama.cpp and other OpenAI-compatible servers (vLLM, Ollama, etc.)."""
+
+from __future__ import annotations
+
+from agents.models.interface import Model, ModelProvider
+from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+
+class LlamaCppProvider(ModelProvider):
+    """A model provider for llama.cpp and other OpenAI-compatible servers.
+
+    This provider creates models that use the OpenAI Chat Completions API
+    against any compatible backend (llama.cpp, vLLM, Ollama, etc.).
+
+    Args:
+        base_url: The OpenAI-compatible API base URL. Must end with ``/v1``.
+            Examples:
+
+            - ``http://localhost:8080/v1`` (llama.cpp server)
+            - ``http://localhost:8080/v1`` (Ollama with ``--api`` flag)
+            - ``https://your-vllm-instance.com/v1`` (vLLM)
+
+        model: The model name to use. Passed to every model instance created
+            by this provider. If ``None``, the backend's default model is used.
+        api_key: API key. Most OpenAI-compatible servers ignore this but the
+            OpenAI SDK requires it. Use anything (e.g. ``"sk-anything"``).
+        **kwargs: Additional keyword arguments passed to ``AsyncOpenAI``.
+
+    Example:
+        >>> provider = LlamaCppProvider(
+        ...     base_url="http://localhost:8080/v1",
+        ...     model="qwen3.6-35b",
+        ...     api_key="sk-anything",
+        ... )
+        >>> agent = Agent(name="Assistant")
+        >>> config = RunConfig(model_provider=provider)
+        >>> result = await Runner.run(agent, "Hello!", run_config=config)
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        model: str | None = None,
+        api_key: str = "sk-anything",
+        **kwargs,
+    ) -> None:
+        """Initialize the LlamaCpp provider.
+
+        Args:
+            base_url: The OpenAI-compatible API base URL (must end with /v1).
+            model: The model name to use. If ``None``, the backend's default is used.
+            api_key: API key (required by OpenAI SDK, usually ignored by the backend).
+            **kwargs: Additional arguments passed to ``AsyncOpenAI``.
+        """
+        self._base_url = base_url
+        self._model = model
+        self._api_key = api_key
+        self._kwargs = kwargs
+        self._client: AsyncOpenAI | None = None
+
+    def _get_client(self) -> AsyncOpenAI:
+        if self._client is None:
+            self._client = AsyncOpenAI(
+                base_url=self._base_url,
+                api_key=self._api_key,
+                max_retries=0,
+                **self._kwargs,
+            )
+        return self._client
+
+    def get_model(self, model_name: str | None) -> Model:
+        """Get a model instance.
+
+        Args:
+            model_name: The model name requested by the agent. If this provider
+                was constructed with a ``model`` argument, that value takes
+                precedence and ``model_name`` is ignored.
+
+        Returns:
+            An ``OpenAIChatCompletionsModel`` instance pointing at the configured base URL.
+        """
+        resolved_model = self._model or model_name or "default"
+        return OpenAIChatCompletionsModel(model=resolved_model, openai_client=self._get_client())
+
+    async def aclose(self) -> None:
+        """Close the underlying OpenAI client."""
+        if self._client is not None:
+            await self._client.close()

openai_agents_providers/ollama_provider.py

@@ -0,0 +1,85 @@
+"""Provider for Ollama.
+
+Ollama exposes an OpenAI-compatible API at /v1/ when started with the --api flag.
+"""
+
+from __future__ import annotations
+
+from agents.models.interface import Model, ModelProvider
+from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+
+class OllamaProvider(ModelProvider):
+    """A model provider for Ollama.
+
+    Ollama exposes an OpenAI-compatible Chat Completions API at ``/v1/`` when
+    started with ``--api`` (enabled by default in recent versions).
+
+    This provider creates models that use the OpenAI Chat Completions API
+    against the Ollama server.
+
+    Args:
+        base_url: The Ollama API base URL. Defaults to ``http://localhost:11434/v1``.
+        model: The Ollama model name to use (e.g. ``"llama3.2"``, ``"qwen3:8b"``).
+            If ``None``, Ollama's default model is used.
+        api_key: API key. Ollama ignores this but the OpenAI SDK requires it.
+        **kwargs: Additional keyword arguments passed to ``AsyncOpenAI``.
+
+    Example:
+        >>> provider = OllamaProvider(model="llama3.2")
+        >>> agent = Agent(name="Assistant")
+        >>> config = RunConfig(model_provider=provider)
+        >>> result = await Runner.run(agent, "Hello!", run_config=config)
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "http://localhost:11434/v1",
+        model: str | None = None,
+        api_key: str = "ollama",
+        **kwargs,
+    ) -> None:
+        """Initialize the Ollama provider.
+
+        Args:
+            base_url: The Ollama API base URL. Defaults to Ollama's default.
+            model: The Ollama model name to use. If ``None``, Ollama's default is used.
+            api_key: API key (required by OpenAI SDK, Ollama ignores it).
+            **kwargs: Additional arguments passed to ``AsyncOpenAI``.
+        """
+        self._base_url = base_url
+        self._model = model
+        self._api_key = api_key
+        self._kwargs = kwargs
+        self._client: AsyncOpenAI | None = None
+
+    def _get_client(self) -> AsyncOpenAI:
+        if self._client is None:
+            self._client = AsyncOpenAI(
+                base_url=self._base_url,
+                api_key=self._api_key,
+                max_retries=0,
+                **self._kwargs,
+            )
+        return self._client
+
+    def get_model(self, model_name: str | None) -> Model:
+        """Get a model instance.
+
+        Args:
+            model_name: The model name requested by the agent. If this provider
+                was constructed with a ``model`` argument, that value takes
+                precedence and ``model_name`` is ignored.
+
+        Returns:
+            An ``OpenAIChatCompletionsModel`` instance pointing at Ollama.
+        """
+        resolved_model = self._model or model_name or "default"
+        return OpenAIChatCompletionsModel(model=resolved_model, openai_client=self._get_client())
+
+    async def aclose(self) -> None:
+        """Close the underlying OpenAI client."""
+        if self._client is not None:
+            await self._client.close()

openai_agents_providers/py.typed

@@ -0,0 +1 @@
+"""Type stubs marker for openai-agents-python-providers."""

openai_agents_python_providers-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+openai_agents_providers/__init__.py,sha256=BctulqLHYuRo2Nb44zPxC9FMHrb5TMht8u0sg5Huhs4,1103
+openai_agents_providers/llama_cpp_provider.py,sha256=WWb9_lgZgMR82jdAlP3M3YZbbdIrnjMNwiXosQusj9U,3421
+openai_agents_providers/ollama_provider.py,sha256=pDGyekG7y0CYsPu0F0Hv4nflvFeyPyYpSBGASOYVFZ0,3081
+openai_agents_providers/py.typed,sha256=p3UHlJheWvOOVAC2IYgJT_mpGMZ7oX96qmJf_e5vIIo,60
+openai_agents_python_providers-1.0.0.dist-info/METADATA,sha256=lH0ynOSCQhgsQzb0QslZeXrkFLvUIW4FXRBZ5Yedkls,5463
+openai_agents_python_providers-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+openai_agents_python_providers-1.0.0.dist-info/licenses/LICENSE,sha256=sUfy39jvRigVcRBv5vgjxTaUsTxWl5WdAZwN_zENKMI,1069
+openai_agents_python_providers-1.0.0.dist-info/RECORD,,

openai_agents_python_providers-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

openai_agents_python_providers-1.0.0.dist-info/licenses/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.