feat: Responses API documentation and implementation (#109)

* feat: Responses API documentation and implementation

* warning dialog

Author: njbrake

README.md

@@ -95,3 +95,23 @@ response = completion(
 )
 print(response.choices[0].message.content)
 ```
+
+### Responses API
+
+For providers that implement the OpenAI-style Responses API, use [`responses`](https://mozilla-ai.github.io/any-llm/api/responses/) or `aresponses`:
+
+```python
+from any_llm import responses
+
+result = responses(
+    model="openai/gpt-4o-mini",
+    input_data=[
+        {"role": "user", "content": [
+            {"type": "text", "text": "Summarize this in one sentence."}
+        ]}
+    ],
+)
+
+# Non-streaming returns an OpenAI-compatible Responses object alias
+print(result.output_text)
+```

docs/api/responses.md

@@ -0,0 +1,10 @@
+## Responses
+
+
+!!! warning
+
+    This API is experimental and subject to changes based upon our experience as we integrate additional providers.
+    Use with caution.
+
+::: any_llm.responses
+::: any_llm.aresponses

docs/index.md

@@ -12,7 +12,7 @@ Refer to the [Quickstart](./quickstart.md) for instructions on installation and
 
 ### Parameters
 
-For a complete list of available functions and their parameters, see the [completion API documentation](./api/completion.md).
+For a complete list of available functions and their parameters, see the [completion](./api/completion.md), [embedding](./api/embedding.md), and [responses](./api/responses.md) API documentation.
 
 ### Error Handling
 

mkdocs.yml

@@ -10,6 +10,7 @@ nav:
   - API Reference:
     - Completion: api/completion.md
     - Embedding: api/embedding.md
+    - Responses: api/responses.md
     - Exceptions: api/exceptions.md
     - Helpers: api/helpers.md
 theme:

src/any_llm/api.py

@@ -252,9 +252,35 @@ def responses(
     user: Optional[str] = None,
     **kwargs: Any,
 ) -> Response | Iterator[ResponseStreamEvent]:
-    """Create a response using the Responses API.
+    """Create a response using the OpenAI-style Responses API.
 
-    This normalizes to the same ChatCompletion/Chunk types for compatibility.
+    This follows the OpenAI Responses API shape and returns the aliased
+    `any_llm.types.responses.Response` type. If `stream=True`, an iterator of
+    `any_llm.types.responses.ResponseStreamEvent` items is returned.
+
+    Args:
+        model: Model identifier in format 'provider/model' (e.g., 'openai/gpt-4o')
+        input_data: The input payload accepted by provider's Responses API.
+            For OpenAI-compatible providers, this is typically a list mixing
+            text, images, and tool instructions, or a dict per OpenAI spec.
+        tools: Optional tools for tool calling (Python callables or OpenAI tool dicts)
+        tool_choice: Controls which tools the model can call
+        max_output_tokens: Maximum number of output tokens to generate
+        temperature: Controls randomness in the response (0.0 to 2.0)
+        top_p: Controls diversity via nucleus sampling (0.0 to 1.0)
+        stream: Whether to stream response events
+        api_key: API key for the provider
+        api_base: Base URL for the provider API
+        timeout: Request timeout in seconds
+        user: Unique identifier for the end user
+        **kwargs: Additional provider-specific parameters
+
+    Returns:
+        Either a `Response` object (non-streaming) or an iterator of
+        `ResponseStreamEvent` (streaming).
+
+    Raises:
+        NotImplementedError: If the selected provider does not support the Responses API.
     """
     provider_key, model_name = ProviderFactory.split_model_provider(model)
 
@@ -304,6 +330,36 @@ async def aresponses(
     user: Optional[str] = None,
     **kwargs: Any,
 ) -> Response | Iterator[ResponseStreamEvent]:
+    """Create a response using the OpenAI-style Responses API.
+
+    This follows the OpenAI Responses API shape and returns the aliased
+    `any_llm.types.responses.Response` type. If `stream=True`, an iterator of
+    `any_llm.types.responses.ResponseStreamEvent` items is returned.
+
+    Args:
+        model: Model identifier in format 'provider/model' (e.g., 'openai/gpt-4o')
+        input_data: The input payload accepted by provider's Responses API.
+            For OpenAI-compatible providers, this is typically a list mixing
+            text, images, and tool instructions, or a dict per OpenAI spec.
+        tools: Optional tools for tool calling (Python callables or OpenAI tool dicts)
+        tool_choice: Controls which tools the model can call
+        max_output_tokens: Maximum number of output tokens to generate
+        temperature: Controls randomness in the response (0.0 to 2.0)
+        top_p: Controls diversity via nucleus sampling (0.0 to 1.0)
+        stream: Whether to stream response events
+        api_key: API key for the provider
+        api_base: Base URL for the provider API
+        timeout: Request timeout in seconds
+        user: Unique identifier for the end user
+        **kwargs: Additional provider-specific parameters
+
+    Returns:
+        Either a `Response` object (non-streaming) or an iterator of
+        `ResponseStreamEvent` (streaming).
+
+    Raises:
+        NotImplementedError: If the selected provider does not support the Responses API.
+    """
     provider_key, model_name = ProviderFactory.split_model_provider(model)
 
     config: dict[str, str] = {}

tests/unit/test_api_signature.py

@@ -1,5 +1,5 @@
 import inspect
-from any_llm.api import completion, acompletion
+from any_llm.api import completion, acompletion, responses, aresponses
 
 
 def test_completion_and_acompletion_have_same_signature() -> None:
@@ -62,3 +62,50 @@ def test_completion_and_acompletion_parameter_details() -> None:
         assert completion_param.kind == acompletion_param.kind, (
             f"Parameter '{param_name}' should have identical parameter kinds"
         )
+
+
+def test_responses_and_aresponses_have_same_signature() -> None:
+    """Test that responses and aresponses have identical signatures."""
+    responses_sig = inspect.signature(responses)
+    aresponses_sig = inspect.signature(aresponses)
+
+    assert responses_sig.parameters == aresponses_sig.parameters, (
+        "responses and aresponses should have identical parameters"
+    )
+
+    assert responses_sig.return_annotation == aresponses_sig.return_annotation, (
+        "responses and aresponses should have identical return annotations"
+    )
+
+
+def test_responses_and_aresponses_have_same_docstring() -> None:
+    """Test that responses and aresponses have identical docstrings."""
+    responses_doc = responses.__doc__
+    aresponses_doc = aresponses.__doc__
+
+    assert responses_doc is not None, "responses should have a docstring"
+    assert aresponses_doc is not None, "aresponses should have a docstring"
+
+    assert responses_doc == aresponses_doc, "responses and aresponses should have identical docstrings"
+
+
+def test_responses_and_aresponses_parameter_details() -> None:
+    """Test that responses and aresponses parameters have identical details."""
+    responses_sig = inspect.signature(responses)
+    aresponses_sig = inspect.signature(aresponses)
+
+    for param_name in responses_sig.parameters:
+        responses_param = responses_sig.parameters[param_name]
+        aresponses_param = aresponses_sig.parameters[param_name]
+
+        assert responses_param.annotation == aresponses_param.annotation, (
+            f"Parameter '{param_name}' should have identical annotations"
+        )
+
+        assert responses_param.default == aresponses_param.default, (
+            f"Parameter '{param_name}' should have identical default values"
+        )
+
+        assert responses_param.kind == aresponses_param.kind, (
+            f"Parameter '{param_name}' should have identical parameter kinds"
+        )

tests/unit/test_responses.py

@@ -0,0 +1,39 @@
+import pytest
+from unittest.mock import Mock, patch
+
+from any_llm import responses
+from any_llm.provider import ProviderName
+
+
+def test_responses_invalid_model_format_no_slash() -> None:
+    """Test responses raises ValueError for model without slash."""
+    with pytest.raises(ValueError, match="Invalid model format. Expected 'provider/model', got 'gpt-5-nano'"):
+        responses("gpt-5-nano", input_data=[{"role": "user", "content": "Hello"}])
+
+
+def test_responses_invalid_model_format_empty_provider() -> None:
+    """Test responses raises ValueError for model with empty provider."""
+    with pytest.raises(ValueError, match="Invalid model format"):
+        responses("/model", input_data=[{"role": "user", "content": "Hello"}])
+
+
+def test_responses_invalid_model_format_empty_model() -> None:
+    """Test responses raises ValueError for model with empty model name."""
+    with pytest.raises(ValueError, match="Invalid model format"):
+        responses("provider/", input_data=[{"role": "user", "content": "Hello"}])
+
+
+def test_responses_invalid_model_format_multiple_slashes() -> None:
+    """Test responses handles multiple slashes correctly (should work - takes first split)."""
+    mock_provider = Mock()
+    mock_provider.responses.return_value = Mock()
+
+    with patch("any_llm.api.ProviderFactory") as mock_factory:
+        mock_factory.get_supported_providers.return_value = ["provider"]
+        mock_factory.get_provider_enum.return_value = ProviderName.OPENAI  # Using a valid provider
+        mock_factory.split_model_provider.return_value = (ProviderName.OPENAI, "model/extra")
+        mock_factory.create_provider.return_value = mock_provider
+
+        responses("provider/model/extra", input_data=[{"role": "user", "content": "Hello"}])
+
+        mock_provider.responses.assert_called_once_with("model/extra", [{"role": "user", "content": "Hello"}])