### Setup Development Environment with Poetry

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/CONTRIBUTING.md

Commands to set up the development environment using Poetry. This includes installing Poetry, configuring virtual environments, installing dependencies, activating the virtual environment, and running tests with tox.

```shell
pipx install poetry==1.8                    # if not already installed
poetry config virtualenvs.in-project true   # recommended
poetry install --with dev                   # install deps including development deps
poetry shell                                # activate venv
tox run                                     # run lint, static analysis, unit tests, and examples
```

--------------------------------

### Install openai-responses via Pip

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/README.md

This command shows how to install the openai-responses Python package using pip. It fetches the latest version from PyPI, making the library available for use in your Python projects for mocking OpenAI API calls.

```bash
pip install openai-responses

```

--------------------------------

### Execute and Cancel Assistant Runs on Threads

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Shows how to set up an assistant and a thread, create a run for the assistant on the thread, and then cancel the run. It verifies the run's initial status, the cancellation process, and the final status after retrieval. The example uses openai-responses for mocking.

```python
import openai
import openai_responses
from openai_responses import OpenAIMock


@openai_responses.mock()
def test_create_and_cancel_run(openai_mock: OpenAIMock):
    client = openai.Client(api_key="sk-fake123")

    # Setup assistant and thread
    assistant = client.beta.assistants.create(
        instructions="You are a helpful assistant.",
        name="Helper",
        tools=[{"type": "code_interpreter"}],
        model="gpt-4-turbo",
    )
    thread = client.beta.threads.create()

    # Create run
    run = client.beta.threads.runs.create(
        thread.id,
        assistant_id=assistant.id,
        metadata={"task": "greeting"},
    )
    assert run.thread_id == thread.id
    assert run.assistant_id == assistant.id
    assert run.status == "queued"

    # Cancel run
    cancelled = client.beta.threads.runs.cancel(run.id, thread_id=thread.id)
    assert cancelled.status == "cancelling"

    # Retrieve to see final status
    found = client.beta.threads.runs.retrieve(run.id, thread_id=thread.id)
    assert found.status == "cancelled"

    assert openai_mock.beta.threads.runs.create.route.call_count == 1
    assert openai_mock.beta.threads.runs.cancel.route.call_count == 1
```

--------------------------------

### List and Retrieve Models with OpenAI API

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Demonstrates how to list all available OpenAI models and retrieve information about a specific model using the OpenAI Python client. This example is tested using the openai-responses mock library.

```python
import openai
import openai_responses
from openai_responses import OpenAIMock


@openai_responses.mock()
def test_list_and_retrieve_models(openai_mock: OpenAIMock):
    client = openai.Client(api_key="sk-fake123")

    # List all models - returns predefined OpenAI models
    models = client.models.list()
    assert len(models.data) > 0

    # Retrieve specific model
    model = client.models.retrieve("gpt-3.5-turbo-instruct")
    assert model

    assert openai_mock.models.list.route.call_count == 1
    assert openai_mock.models.retrieve.route.call_count == 1
```

--------------------------------

### Mock Vector Stores for File Search (Python)

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Shows how to mock the creation and management of vector stores for file search using the Assistants API. This example covers uploading a file, creating a vector store, listing files within it, updating, and deleting the vector store. It depends on 'openai' and 'openai-responses'.

```python
import openai
import openai_responses
from openai_responses import OpenAIMock


@openai_responses.mock()
def test_vector_store_with_files(openai_mock: OpenAIMock):
    client = openai.Client(api_key="sk-fake123")

    # Upload a file first
    file = client.files.create(
        file=open("examples/example.json", "rb"),
        purpose="assistants",
    )

    # Create vector store with file
    vector_store = client.vector_stores.create(
        name="Support FAQ",
        file_ids=[file.id]
    )
    assert vector_store.name == "Support FAQ"

    # List files in vector store
    vs_files = client.vector_stores.files.list(vector_store.id)
    assert len(vs_files.data) == 1

    # Update vector store
    updated = client.vector_stores.update(
        vector_store.id,
        name="Support FAQ Updated",
    )
    assert updated.name == "Support FAQ Updated"

    # Delete vector store
    assert client.vector_stores.delete(vector_store.id).deleted

    assert openai_mock.vector_stores.create.route.call_count == 1
    assert openai_mock.vector_stores.files.list.route.call_count == 1
```

--------------------------------

### Request Feature Issue Title Example

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/CONTRIBUTING.md

An example of how to format the title when requesting a new feature. The title should be prefixed with 'feat:'.

```markdown
feat: lorem ipsum
```

--------------------------------

### Setting Mock Response for Chat Completions in Python

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/overview.md

Provides an example of how to set a specific mock response for the chat.completions.create route using the `response` setter. The response can be a partial object, a full object, an HTTPX Response, or a function.

```python
openai_mock.chat.completions.create.response = {
    "choices": [
        {
            "index": 0,
            "finish_reason": "stop",
            "message": {"content": "Hello! How can I help?", "role": "assistant"},
        }
    ]
}

```

--------------------------------

### Manage Files with OpenAI API

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Illustrates file operations including uploading a file for fine-tuning, retrieving file metadata, fetching file content, listing all uploaded files, and deleting a file. This example uses the openai-responses mock to simulate these actions.

```python
import openai
import openai_responses
from openai_responses import OpenAIMock


@openai_responses.mock()
def test_file_operations(openai_mock: OpenAIMock):
    client = openai.Client(api_key="sk-fake123")

    # Upload file
    file = client.files.create(
        file=open("examples/example.json", "rb"),
        purpose="fine-tune",
    )
    assert file.filename == "example.json"

    # Retrieve file metadata
    found = client.files.retrieve(file.id)
    assert found.id == file.id

    # Get file content
    content = client.files.content(file.id)
    assert content.content == b'{\n  "foo": "bar",\n  "fizz": "buzz"\n}'

    # List all files
    files = client.files.list()
    assert len(files.data) == 1

    # Delete file
    assert client.files.delete(file.id).deleted

    assert openai_mock.files.create.route.call_count == 1
    assert openai_mock.files.retrieve.route.call_count == 1
```

--------------------------------

### Report Bug Issue Title Example

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/CONTRIBUTING.md

An example of how to format the title when reporting a bug in the issue tracker. The title should be prefixed with 'bug:'.

```markdown
bug: lorem ipsum
```

--------------------------------

### Install openai-responses with Poetry

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/index.md

Adds the openai-responses library as a development dependency using Poetry, a dependency management tool for Python. This ensures the library is available during development and testing.

```shell
poetry add --group dev openai-responses
```

--------------------------------

### Stateful CRUD Operations for Assistants API in Python

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Illustrates how to perform stateful Create, Retrieve, Update, and Delete (CRUD) operations for the Assistants API using `openai-responses`. The library automatically manages resource state, allowing tests to verify assistant creation, retrieval, updates, and deletions without manual response setup for each operation.

```python
import openai
import openai_responses
from openai_responses import OpenAIMock


@openai_responses.mock()
def test_assistant_crud_operations(openai_mock: OpenAIMock):
    client = openai.Client(api_key="sk-fake123")

    # Create assistant - response is automatically generated
    assistant = client.beta.assistants.create(
        instructions="You are a personal math tutor.",
        name="Math Tutor",
        tools=[{"type": "code_interpreter"}],
        model="gpt-4-turbo",
    )
    assert assistant.name == "Math Tutor"

    # Retrieve assistant - uses internal state store
    found = client.beta.assistants.retrieve(assistant.id)
    assert found.name == assistant.name

    # Update assistant
    updated = client.beta.assistants.update(
        assistant.id,
        name="Math Tutor (Slim)",
        model="gpt-3.5-turbo",
    )
    assert updated.name == "Math Tutor (Slim)"
    assert updated.model == "gpt-3.5-turbo"

    # Delete assistant
    assert client.beta.assistants.delete(assistant.id).deleted

    # Verify call counts
    assert openai_mock.beta.assistants.create.route.call_count == 1
    assert openai_mock.beta.assistants.retrieve.route.call_count == 1
    assert openai_mock.beta.assistants.update.route.call_count == 1
    assert openai_mock.beta.assistants.delete.route.call_count == 1
```

--------------------------------

### Mock Embedding API Responses in Python

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Shows how to mock responses from the OpenAI Embeddings API. The example sets a predefined list of embedding vectors to be returned, allowing tests to verify embedding generation logic without external API calls. It asserts the model name, data length, and the content of the returned embeddings.

```python
import openai
import openai_responses
from openai_responses import OpenAIMock


EMBEDDING = [0.0023064255, -0.009327292, -0.0028842222]


@openai_responses.mock()
def test_create_embedding(openai_mock: OpenAIMock):
    openai_mock.embeddings.create.response = {
        "data": [
            {
                "object": "embedding",
                "embedding": EMBEDDING,
                "index": 0,
            },
        ]
    }

    client = openai.Client(api_key="sk-fake123")
    embeddings = client.embeddings.create(
        model="text-embedding-ada-002",
        input="The food was delicious and the waiter...",
        encoding_format="float",
    )

    assert embeddings.model == "text-embedding-ada-002"
    assert len(embeddings.data) == 1
    assert embeddings.data[0].embedding == EMBEDDING
    assert openai_mock.embeddings.create.route.call_count == 1
```

--------------------------------

### State Store Injection in Response Functions (Python)

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/responses.md

This Python example shows how to inject a state store into a response function for stateful routes. The function signature includes `state_store: StateStore` as a keyword-only argument, which is automatically provided by the openai-responses library. This allows functions to access and manage state across multiple requests.

```python
import openai_responses
from openai_responses import OpenAIMock
from openai_responses.stores import StateStore
from openai_responses.ext.httpx import Request, Response, post
from openai_responses.ext.respx import Route

def polled_get_run_responses(
    request: Request,
    route: Route,
    *, 
    state_store: StateStore,
) -> Response:
    ...

```

--------------------------------

### Custom HTTP Transport with OpenAIMock and httpx

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Integrates OpenAIMock with existing transport-based test setups by using a custom HTTPX transport. This allows for mocking OpenAI API calls within a test environment using the httpx library.

```python
import openai
from openai import DefaultHttpxClient
from openai_responses import OpenAIMock
from openai_responses.ext.httpx import MockTransport


def test_with_custom_transport():
    openai_mock = OpenAIMock()
    openai_mock.chat.completions.create.response = {
        "choices": [
            {
                "index": 0,
                "finish_reason": "stop",
                "message": {"content": "Hello!", "role": "assistant"},
            }
        ]
    }

    client = openai.Client(
        api_key="sk-fake123",
        http_client=DefaultHttpxClient(
            transport=MockTransport(openai_mock.router.handler)
        ),
    )

    completion = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": "Hello!"}],
    )

    assert completion.choices[0].message.content == "Hello!"

```

--------------------------------

### Simulate Server Failure with HTTPX Response (Python)

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/responses.md

Tests handling of server failures by setting the mock response to a raw HTTPX Response object with a 500 status code. This example uses pytest and `openai_responses` to raise an `APIStatusError` when the client attempts to create a chat completion. It requires importing `Response` from `openai_responses.ext.httpx`.

```python
import pytest

import openai
from openai import APIStatusError

import openai_responses
from openai_responses import OpenAIMock
from openai_responses.ext.httpx import Response


@openai_responses.mock()
def test_create_chat_completion_failure(openai_mock: OpenAIMock):
    openai_mock.chat.completions.create.response = Response(500)

    client = openai.Client(api_key="sk-fake123", max_retries=0)

    with pytest.raises(APIStatusError):
        client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[
                {"role": "system", "content": "You are a helpful assistant."},
                {"role": "user", "content": "Hello!"},
            ],
        )
```

--------------------------------

### Providing Custom Initial State for OpenAIMock

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/state.md

Shows how to initialize the OpenAIMock object with a custom state store. This involves creating a StateStore instance, populating it with initial data, and then passing it to the `openai_responses.mock` decorator.

```python
from openai.type.beta import Assistant

import openai_responses
from openai_responses import OpenAIMock
from openai_responses.store import StateStore

my_custom_state = StateStore()
my_custom_state.beta.assistants.put(Assistant(...))

@openai_responses.mock(state=my_custom_state)
def my_test_function(openai_mock: OpenAIMock):
    ...
```

--------------------------------

### Configuring HTTPX Client with MockTransport in Python

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/overview.md

Shows how to integrate the OpenAIMock with an HTTPX client by creating a MockTransport. This is useful for existing codebases that rely on swapping HTTPX transports for different environments.

```python
import openai
from openai import DefaultHttpxClient

from openai_responses import OpenAIMock
from openai_responses.ext.httpx import MockTransport

def test_create_chat_completion():
    openai_mock = OpenAIMock()
    client = openai.Client(
        api_key="sk-fake123",
        http_client=DefaultHttpxClient(
            transport=MockTransport(openai_mock.router.handler)
        ),
    )

```

--------------------------------

### Using OpenAIMock as a Context Manager in Python

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/overview.md

Illustrates how to use the OpenAIMock class as a context manager for scenarios where the decorator pattern is not suitable. This allows manual instantiation and control over the mock's lifecycle.

```python
from openai_responses import OpenAIMock

def test_create_chat_completion():
    openai_mock = OpenAIMock()
    with openai_mock.router:
      ...

```

--------------------------------

### Using Pytest Fixture for Custom State Management

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/state.md

Illustrates how to use a Pytest fixture to manage and pass around a custom state store for testing. The fixture creates a StateStore, and tests can then assign this state to the OpenAIMock object.

```python
import pytest

import openai

import openai_responses
from openai_responses import OpenAIMock
from openai_responses.stores import StateStore


@pytest.fixture(scope="module")
def shared_state():
    return StateStore()


@openai_responses.mock()
def test_create_assistant(openai_mock: OpenAIMock, shared_state: StateStore):
    openai_mock.state = shared_state
    ...

@openai_responses.mock()
def test_retrieve_assistant(openai_mock: OpenAIMock, shared_state: StateStore):
    openai_mock.state = shared_state
    ...
```

--------------------------------

### Using OpenAIMock as a Decorator in Python

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/overview.md

Demonstrates how to use the openai_responses.mock() decorator to wrap a test function, providing an OpenAIMock instance as a fixture. This is the primary method for integrating the mock with Pytest.

```python
import openai_responses

@openai_responses.mock()
def my_test_function(openai_mock):
  ...

```

--------------------------------

### Mock Chat Completion Responses in Python

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Demonstrates how to mock chat completion responses using the `openai-responses` library. It uses a decorator to mock the API call and sets a predefined response for the chat completions endpoint. This allows testing chat-based interactions without actual API calls.

```python
import openai
import openai_responses
from openai_responses import OpenAIMock


@openai_responses.mock()
def test_create_chat_completion(openai_mock: OpenAIMock):
    openai_mock.chat.completions.create.response = {
        "choices": [
            {
                "index": 0,
                "finish_reason": "stop",
                "message": {"content": "Hello! How can I help?", "role": "assistant"},
            }
        ]
    }

    client = openai.Client(api_key="sk-fake123")
    completion = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Hello!"},
        ],
    )

    assert len(completion.choices) == 1
    assert completion.choices[0].message.content == "Hello! How can I help?"
    assert openai_mock.chat.completions.create.route.call_count == 1
```

--------------------------------

### Mock Async Client Chat Completions with pytest-asyncio (Python)

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Illustrates mocking chat completion requests using OpenAI's AsyncClient with the `pytest-asyncio` marker. This approach is suitable for testing asynchronous code. It requires 'pytest', 'openai', and 'openai-responses'.

```python
import pytest
import openai
import openai_responses
from openai_responses import OpenAIMock


@pytest.mark.asyncio
@openai_responses.mock()
async def test_async_chat_completion(openai_mock: OpenAIMock):
    openai_mock.chat.completions.create.response = {
        "choices": [
            {
                "index": 0,
                "finish_reason": "stop",
                "message": {"content": "Hello! How can I help?", "role": "assistant"},
            }
        ]
    }

    client = openai.AsyncClient(api_key="sk-fake123")
    completion = await client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Hello!"},
        ],
    )

    assert len(completion.choices) == 1
    assert completion.choices[0].message.content == "Hello! How can I help?"
    assert openai_mock.chat.completions.create.route.call_count == 1
```

--------------------------------

### Mock Chat Completions Stream with Python

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/streaming.md

This snippet demonstrates how to mock the OpenAI chat completions API to return a streaming response. It defines a custom event stream class that inherits from `EventStream` and overrides the `generate` method to yield mock `ChatCompletionChunk` objects. The mock is then set up using the `@openai_responses.mock()` decorator and tested by making a client call and asserting the received chunks.

```python
from typing import Generator
from typing_extensions import override

import openai
from openai.types.chat import ChatCompletionChunk

import openai_responses
from openai_responses import OpenAIMock
from openai_responses.streaming import EventStream
from openai_responses.ext.httpx import Request, Response


class CreateChatCompletionEventStream(EventStream[ChatCompletionChunk]): # (1)
    @override
    def generate(self) -> Generator[ChatCompletionChunk, None, None]: # (2)
        yield ChatCompletionChunk.model_validate( # (3)
            {
                "id": "chatcmpl-123",
                "object": "chat.completion.chunk",
                "created": 1694268190,
                "model": "gpt-4o",
                "system_fingerprint": "fp_44709d6fcb",
                "choices": [
                    {
                        "index": 0,
                        "delta": {"role": "assistant", "content": ""},
                        "logprobs": None,
                        "finish_reason": None,
                    }
                ],
            }
        )

        yield ChatCompletionChunk.model_validate(
            {
                "id": "chatcmpl-123",
                "object": "chat.completion.chunk",
                "created": 1694268190,
                "model": "gpt-4o",
                "system_fingerprint": "fp_44709d6fcb",
                "choices": [
                    {
                        "index": 0,
                        "delta": {"content": "Hello"},
                        "logprobs": None,
                        "finish_reason": None,
                    }
                ],
            }
        )

        yield ChatCompletionChunk.model_validate(
            {
                "id": "chatcmpl-123",
                "object": "chat.completion.chunk",
                "created": 1694268190,
                "model": "gpt-4o",
                "system_fingerprint": "fp_44709d6fcb",
                "choices": [
                    {
                        "index": 0,
                        "delta": {},
                        "logprobs": None,
                        "finish_reason": "stop",
                    }
                ],
            }
        )


def create_chat_completion_response(request: Request) -> Response:
    stream = CreateChatCompletionEventStream() # (4)
    return Response(201, content=stream, request=request) # (5)


@openai_responses.mock()
def test_create_chat_completion_stream(openai_mock: OpenAIMock):
    openai_mock.chat.completions.create.response = create_chat_completion_response

    client = openai.Client(api_key="sk-fake123")
    completion = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Hello!"},
        ],
        stream=True,
    )

    received_chunks = 0

    for chunk in completion:
        received_chunks += 1
        assert chunk.id

    assert received_chunks == 3

```

--------------------------------

### Share State Across Tests using Custom StateStore in Python

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Demonstrates how to use a custom StateStore to share state, such as created assistants, between multiple tests. This is achieved by defining a pytest fixture that provides a StateStore instance to the mock.

```python
import pytest
import openai
import openai_responses
from openai_responses import OpenAIMock
from openai_responses.stores import StateStore


@pytest.fixture(scope="module")
def shared_state():
    return StateStore()


@openai_responses.mock()
def test_create_assistant(openai_mock: OpenAIMock, shared_state: StateStore):
    openai_mock.state = shared_state

    client = openai.Client(api_key="sk-fake123")
    assistant = client.beta.assistants.create(
        name="Shared Assistant",
        model="gpt-4-turbo",
    )
    assert assistant.name == "Shared Assistant"


@openai_responses.mock()
def test_retrieve_shared_assistant(openai_mock: OpenAIMock, shared_state: StateStore):
    openai_mock.state = shared_state

    client = openai.Client(api_key="sk-fake123")
    # Can retrieve assistant created in previous test
    assistants = client.beta.assistants.list()
    assert len(assistants.data) == 1
    assert assistants.data[0].name == "Shared Assistant"

```

--------------------------------

### Mock Chat Completions using Context Manager (Python)

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Demonstrates using `OpenAIMock` as a context manager for more granular control over the mocking scope. This method is useful when you need to apply mocks to specific blocks of code rather than entire test functions. It requires the 'openai' and 'openai-responses' libraries.

```python
import openai
from openai_responses import OpenAIMock


def test_with_context_manager():
    openai_mock = OpenAIMock()

    with openai_mock.router:
        openai_mock.chat.completions.create.response = {
            "choices": [
                {
                    "index": 0,
                    "finish_reason": "stop",
                    "message": {"content": "Hello!", "role": "assistant"},
                }
            ]
        }

        client = openai.Client(api_key="sk-fake123")
        completion = client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[{"role": "user", "content": "Hi!"}],
        )

        assert completion.choices[0].message.content == "Hello!"
        assert openai_mock.chat.completions.create.route.call_count == 1
```

--------------------------------

### Manage Threads and Messages with OpenAI API

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Demonstrates creating threads, adding initial messages, appending user messages, listing all messages, and updating thread metadata using the OpenAI Python client. It utilizes the openai-responses mock for testing without actual API calls.

```python
import openai
import openai_responses
from openai_responses import OpenAIMock


@openai_responses.mock()
def test_thread_with_messages(openai_mock: OpenAIMock):
    client = openai.Client(api_key="sk-fake123")

    # Create thread with initial messages
    thread = client.beta.threads.create(
        messages=[{"role": "assistant", "content": "How can I help?"}]
    )
    assert thread.id

    # Add more messages
    for i in range(5):
        client.beta.threads.messages.create(
            thread_id=thread.id,
            role="user",
            content=f"Message {i}",
        )

    # List all messages
    messages = client.beta.threads.messages.list(thread.id)
    assert len(messages.data) == 6  # 1 initial + 5 added

    # Update thread metadata
    updated = client.beta.threads.update(thread.id, metadata={"session": "abc123"})
    assert updated.metadata == {"session": "abc123"}

    assert openai_mock.beta.threads.create.route.call_count == 1
    assert openai_mock.beta.threads.messages.create.route.call_count == 5
    assert openai_mock.beta.threads.messages.list.route.call_count == 1
```

--------------------------------

### Accessing State Store via OpenAIMock

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/state.md

Demonstrates how to access the state store for an instance of an OpenAIMock object using the `state` property. This follows the design of the official Python client library for consistency.

```python
openai_mock.state
```

```python
openai_mock.state.beta.threads.messages
```

--------------------------------

### Fine-tuning API Endpoints

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/coverage.md

This section details the status of the Fine-tuning API endpoints. All listed fine-tuning job endpoints are currently unsupported.

```APIDOC
## Fine-tuning API Endpoints

### Description

This section covers the status of various fine-tuning job related API endpoints. All listed fine-tuning endpoints are currently unsupported.

### Method

N/A (Unsupported Endpoints)

### Endpoint

N/A

### Parameters

N/A

### Request Example

N/A

### Response

N/A

#### Success Response (200)

N/A

#### Response Example

N/A
```

--------------------------------

### Mock Moderations API with Custom Flags (Python)

Source: https://context7.com/mharrisb1/openai-responses-python/llms.txt

Demonstrates how to mock the Moderations API to return custom flagging results. This is useful for testing how your application handles content moderation outcomes. It requires the 'openai' and 'openai-responses' libraries.

```python
import openai
import openai_responses
from openai_responses import OpenAIMock


@openai_responses.mock()
def test_moderation_with_flags(openai_mock: OpenAIMock):
    openai_mock.moderations.create.response = {
        "results": [
            {
                "flagged": True,
                "categories": {"harassment": True, "violence/graphic": True},
                "category_scores": {"harassment": 0.9, "violence/graphic": 0.8},
            }
        ]
    }

    client = openai.Client(api_key="sk-fake123")
    result = client.moderations.create(input="Test input")

    assert len(result.results) == 1
    assert result.results[0].flagged is True
    assert result.results[0].categories.harassment is True
    assert openai_mock.moderations.create.route.call_count == 1
```

--------------------------------

### Simulate API Failures with Function Responses (Python)

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/responses.md

This Python code snippet demonstrates how to use a function to define a mock API response that simulates initial failures before succeeding. It utilizes the openai-responses library to mock chat completions and httpx for request/response handling. The function checks the call count to determine whether to return an error or a successful response.

```python
import openai

import openai_responses
from openai_responses import OpenAIMock
from openai_responses.ext.httpx import Request, Response
from openai_responses.ext.respx import Route
from openai_responses.helpers.builders.chat import chat_completion_from_create_request


def completion_with_failures(request: Request, route: Route) -> Response:
    """Simulate 2 failures before sending successful response"""
    if route.call_count < 2:
        return Response(500)

    completion = chat_completion_from_create_request(request)

    return Response(201, json=completion.model_dump())


@openai_responses.mock()
def test_create_chat_completion(openai_mock: OpenAIMock):
    openai_mock.chat.completions.create.response = completion_with_failures

    client = openai.Client(api_key="sk-fake123", max_retries=3)
    client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Hello!"},
        ],
    )

    assert openai_mock.chat.completions.create.calls.call_count == 3

```

--------------------------------

### Test Synchronous OpenAI Chat Completion with openai-responses

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/async.md

This snippet demonstrates how to test a synchronous OpenAI chat completion call. It uses the openai_responses.mock() decorator to mock the API response and an openai.Client to make the call. No special decorators are needed for synchronous tests.

```python
import openai

import openai_responses
from openai_responses import OpenAIMock


@openai_responses.mock()
def test_create_chat_completion(openai_mock: OpenAIMock):
    openai_mock.chat.completions.create.response = {
        "choices": [
            {
                "index": 0,
                "finish_reason": "stop",
                "message": {"content": "Hello! How can I help?", "role": "assistant"},
            }
        ]
    }

    client = openai.Client(api_key="sk-fake123")
    completion = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Hello!"},
        ],
    )

    assert len(completion.choices) == 1
    assert completion.choices[0].message.content == "Hello! How can I help?"
    assert openai_mock.chat.completions.create.calls.call_count == 1

```

--------------------------------

### Audio API Endpoints

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/coverage.md

This section details the status of the Audio API endpoints. Currently, none of the audio-related endpoints are supported.

```APIDOC
## Audio API Endpoints

### Description

This section covers the status of various audio-related API endpoints. All listed audio endpoints are currently unsupported.

### Method

N/A (Unsupported Endpoints)

### Endpoint

N/A

### Parameters

N/A

### Request Example

N/A

### Response

N/A

#### Success Response (200)

N/A

#### Response Example

N/A
```

--------------------------------

### Test Asynchronous OpenAI Chat Completion with openai-responses

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/async.md

This snippet shows how to test an asynchronous OpenAI chat completion call. It requires the pytest-asyncio plugin and the @pytest.mark.asyncio decorator. The openai_responses.mock() decorator is used to mock the API response, and an openai.AsyncClient is used to make the call.

```python
import pytest

import openai

import openai_responses
from openai_responses import OpenAIMock


@pytest.mark.asyncio
@openai_responses.mock()
async def test_async_create_chat_completion(openai_mock: OpenAIMock):
    openai_mock.chat.completions.create.response = {
        "choices": [
            {
                "index": 0,
                "finish_reason": "stop",
                "message": {"content": "Hello! How can I help?", "role": "assistant"},
            }
        ]
    }

    client = openai.AsyncClient(api_key="sk-fake123")
    completion = await client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Hello!"},
        ],
    )

    assert len(completion.choices) == 1
    assert completion.choices[0].message.content == "Hello! How can I help?"
    assert openai_mock.chat.completions.create.calls.call_count == 1

```

--------------------------------

### Manually Set Run Status using Model (Python)

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/responses.md

Demonstrates manually setting the status of a run object and assigning it as the response for the retrieve run endpoint. This is useful for simulating specific states like 'in_progress' for polling scenarios. It involves creating a run, modifying its status, and then setting the mock response.

```python
# create run
run = client.beta.threads.runs.create(thread.id, assistant_id=assistant.id)

# manually change status and assign updated run as response for retrieve call
run.status = "in_progress"openai_mock.beta.threads.runs.retrieve.response = run

# retrieve run
run = client.beta.threads.runs.retrieve(run.id, thread_id=thread.id)
assert run.status == "in_progress"
```

--------------------------------

### Define Chat Completion Response using Partial (Python)

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/responses.md

Sets a partial response for the chat completions create endpoint. This allows specifying only certain fields, like the 'choices' array, while letting other fields default. Autocompletion for field names is supported due to Python's TypedDict.

```python
openai_mock.chat.completions.create.response = {
    "choices": [
        {
            "index": 0,
            "finish_reason": "stop",
            "message": {"content": "Hello! How can I help?", "role": "assistant"},
        }
    ]
}
```

--------------------------------

### Assistants API Endpoints

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/coverage.md

This section details the status of the Assistants API endpoints. All listed assistant management endpoints are supported.

```APIDOC
## Assistants API Endpoints

### Description

This section covers the status of the Assistants API endpoints. All operations related to creating, listing, retrieving, modifying, and deleting assistants are supported.

### Method

POST, GET, DELETE

### Endpoint

/v1/assistants
/v1/assistants/{assistant_id}

### Parameters

#### Path Parameters

- **assistant_id** (string) - Required - The ID of the assistant to operate on.

#### Query Parameters

- **limit** (integer) - Optional - Maximum number of assistants to return.
- **order** (string) - Optional - Sort order for assistants (`asc` or `desc`).
- **after** (string) - Optional - A cursor for use in pagination.

#### Request Body

For Create assistant:
- **name** (string) - Optional - The name of the assistant.
- **description** (string) - Optional - The description of the assistant.
- **model** (string) - Required - The ID of the model to use.
- **instructions** (string) - Optional - The instructions that the assistant uses.
- **tools** (array) - Optional - Override the model's default tools.

For Modify assistant:
- Fields to update (same as create assistant).

### Request Example

**Create Assistant:**
```json
{
  "name": "Math Tutor",
  "model": "gpt-4",
  "instructions": "You are a personal math tutor. Write and run code to answer math questions.",
  "tools": [{"type": "code_interpreter"}]
}
```

**List Assistants:**
```http
GET /v1/assistants?limit=5 HTTP/1.1
Host: api.openai.com

```

### Response

#### Success Response (200)

For List assistants:
- **object** (string) - The type of object returned, usually `list`.
- **data** (array) - A list of assistant objects.
- **has_more** (boolean) - Indicates if there are more assistants to retrieve.

For Retrieve/Modify assistant:
- **id** (string) - The assistant ID.
- **object** (string) - The type of object returned, usually `assistant`.
- **created_at** (integer) - Unix timestamp of when the assistant was created.
- **name** (string) - The name of the assistant.
- **description** (string) - The description of the assistant.
- **model** (string) - The model used by the assistant.
- **instructions** (string) - The instructions for the assistant.
- **tools** (array) - The tools available to the assistant.

#### Response Example

**List Assistants:**
```json
{
  "object": "list",
  "data": [
    {
      "id": "asst_abc123xyz",
      "object": "assistant",
      "created_at": 1698967200,
      "name": "Math Tutor",
      "description": null,
      "model": "gpt-4",
      "instructions": "You are a personal math tutor. Write and run code to answer math questions.",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "has_more": false
}
```

**Retrieve Assistant:**
```json
{
  "id": "asst_abc123xyz",
  "object": "assistant",
  "created_at": 1698967200,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-4",
  "instructions": "You are a personal math tutor. Write and run code to answer math questions.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ]
}
```
```

--------------------------------

### Files API Endpoints

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/coverage.md

This section details the status of the Files API endpoints. All listed file management endpoints are supported.

```APIDOC
## Files API Endpoints

### Description

This section covers the status of the Files API endpoints. All file management operations, including upload, list, retrieve, delete, and retrieve content, are supported.

### Method

POST, GET, DELETE

### Endpoint

/v1/files
/v1/files/{file_id}
/v1/files/{file_id}/content

### Parameters

#### Path Parameters

- **file_id** (string) - Required - The ID of the file to operate on.

#### Query Parameters

- **purpose** (string) - Optional - The intended purpose of the file (e.g., `fine-tune`).

#### Request Body

For Upload file:
- **file** (file) - Required - The file to upload.
- **purpose** (string) - Required - The purpose of the file (e.g., `fine-tune`).

### Request Example

**Upload File:**
```http
POST /v1/files HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="purpose"

fine-tune
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="my_training_data.jsonl"
Content-Type: application/jsonl

{"prompt": "<<HP>> What is the capital of France?", "completion": "<<ED>> Paris."}

------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

**Retrieve File Content:**
```http
GET /v1/files/{file_id}/content HTTP/1.1
Host: api.openai.com

```

### Response

#### Success Response (200)

For List files:
- **object** (string) - The type of object returned, usually `list`.
- **data** (array) - A list of file objects.
- **has_more** (boolean) - Indicates if there are more files to retrieve.

For Retrieve file:
- **id** (string) - The file ID.
- **object** (string) - The type of object returned, usually `file`.
- **bytes** (integer) - The size of the file in bytes.
- **created_at** (integer) - The Unix timestamp of when the file was created.
- **filename** (string) - The name of the file.
- **purpose** (string) - The purpose of the file.

For Retrieve file content:
- File content (binary data)

#### Response Example

**List Files:**
```json
{
  "object": "list",
  "data": [
    {
      "id": "file-abc123xyz",
      "object": "file",
      "bytes": 500,
      "created_at": 1677652288,
      "filename": "my_training_data.jsonl",
      "purpose": "fine-tune"
    }
  ],
  "has_more": false
}
```

**Retrieve File:**
```json
{
  "id": "file-abc123xyz",
  "object": "file",
  "bytes": 500,
  "created_at": 1677652288,
  "filename": "my_training_data.jsonl",
  "purpose": "fine-tune"
}
```
```

--------------------------------

### Asserting Route Call Count in Python

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/overview.md

Demonstrates how to access and assert the call count of a specific mock route. This is useful for verifying that API endpoints were called the expected number of times during tests.

```python
assert openai_mock.chat.completions.create.route.call_count == 1

```

--------------------------------

### Mock OpenAI API Request in Pytest

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/README.md

This Python code snippet demonstrates how to use the openai-responses library to mock an OpenAI API request within a pytest function. It decorates the test function with `@openai_responses.mock()`, initializes an OpenAI client, and makes a call to create an assistant. The assertion verifies that the assistant's name is correctly set, showcasing the mocking functionality.

```python
import openai

import openai_responses


@openai_responses.mock()
def test_create_assistant():
    client = openai.Client(api_key="sk-fake123")

    assistant = client.beta.assistants.create(
        instructions="You are a personal math tutor.",
        name="Math Tutor",
        tools=[{"type": "code_interpreter"}],
        model="gpt-4-turbo",
    )

    assert assistant.name == "Math Tutor"

```

--------------------------------

### Mock External API POST Request with RESPX

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/user_guide/external.md

This snippet demonstrates how to mock a POST request to an external API using the RESPX router exposed by the OpenAIMock object. It sets up a mock response for a specific URL, returning a 200 status code with a JSON payload. This is useful for testing integrations with external services without making actual network calls.

```python
openai_mock.router.post(url="https://api.myweatherapi.com").mock(Response(200, json={"value": "57"}))
```

--------------------------------

### Batch API Endpoints

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/coverage.md

This section details the status of the Batch API endpoints. All listed batch endpoints are currently unsupported.

```APIDOC
## Batch API Endpoints

### Description

This section covers the status of various batch job related API endpoints. All listed batch endpoints are currently unsupported.

### Method

N/A (Unsupported Endpoints)

### Endpoint

N/A

### Parameters

N/A

### Request Example

N/A

### Response

N/A

#### Success Response (200)

N/A

#### Response Example

N/A
```

--------------------------------

### Chat API Endpoints

Source: https://github.com/mharrisb1/openai-responses-python/blob/main/docs/coverage.md

This section details the status of the Chat API endpoints. The 'Create chat completion' endpoint is supported, including streaming.

```APIDOC
## Chat API Endpoints

### Description

This section covers the status of the Chat API endpoints. The 'Create chat completion' endpoint is fully supported and allows for streaming responses.

### Method

POST

### Endpoint

/v1/chat/completions

### Parameters

#### Path Parameters

N/A

#### Query Parameters

N/A

#### Request Body

- **model** (string) - Required - The model to use for chat completion.
- **messages** (array) - Required - A list of messages comprising the conversation.
- **stream** (boolean) - Optional - Whether to stream back partial message deltas as they are generated.

### Request Example

```json
{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Who won the world series in 2020?"}
  ],
  "stream": true
}
```

### Response

#### Success Response (200)

- **id** (string) - The ID of the chat completion.
- **object** (string) - The type of object returned, usually `chat.completion`.
- **created** (integer) - Unix timestamp of when the completion was created.
- **model** (string) - The model used for the completion.
- **choices** (array) - A list of chat completion choices.
- **usage** (object) - Usage statistics for the completion.

#### Response Example

```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo-0613",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The Los Angeles Dodgers won the World Series in 2020."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}
```
```