feat(api): completely redesigned API

.gitignore

@@ -1,10 +1,12 @@
+__pycache__/
 .mypy_cache/
 .pytest_cache/
 .tox/
 .venv/
 .vscode/
-__pycache__/
 dist/
 nbs/
+site/
 
 *.lock
+.plan

CHANGELOG.md

@@ -1,18 +1,55 @@
 # Changelog
 
+## 0.3.0
+
+> [!IMPORTANT]
+> **Breaking change**: Completely redesigned API
+
+Introducing an all-new API that is both simpler to use and much more flexible. See [docs](https://mharrisb1.github.io/openai-responses-python) for more.
+
+In addition to a new API, this release closed these issues:
+
+- [#1: feat: ability to raise exceptions](https://github.com/mharrisb1/openai-responses-python/issues/1)
+- [#9: feat: base url override](https://github.com/mharrisb1/openai-responses-python/issues/9)
+- [#28: feat: automatically share state between chained mocks](https://github.com/mharrisb1/openai-responses-python/issues/28)
+
+Additional notes:
+
+- Removes token estimation. This is now the responsibility of the user to provided mock token count
+- Adds more example files
+- Still not completely happy with current state of mocking run steps. Will likely change in the near future.
+
+## 0.2.1
+
+> [!WARNING]
+> Deprecated
+
+Fixes issue where messages included in run create params (using `additional_messages`) was ignored.
+
+- [#10: fix: create run ignores additional_messages](https://github.com/mharrisb1/openai-responses-python/issues/10)
+
 ## 0.2.0
 
+> [!CAUTION]
+> Yanked
+
 Migrates assistant endpoints to Assistants V2
 
 - [#8: feat: assistants v2](https://github.com/mharrisb1/openai-responses-python/issues/8)
 - [#13: feat(endpoints): add token usage estimates to chat endpoint](https://github.com/mharrisb1/openai-responses-python/issues/13)
 
 ## 0.1.1
 
+> [!CAUTION]
+> Yanked
+
 Fixes some issues with chat completions and other stateless mocks
 
 - [#7: fix(endpoints): fix issues with chat completions endpoint](https://github.com/mharrisb1/openai-responses-python/issues/7)
 
 ## 0.1.0
 
+> [!CAUTION]
+> Yanked
+
 Initial release with minimally useful support for what I needed.

CONTRIBUTING.md

@@ -33,18 +33,18 @@ I (Michael) am the BDFL of the project and can and will arbitrarily rank issues
 - _Effort_ is a rough estimate of whether something will take a lot of work, some work, or little work to implement
 - _Impact_ is a rough estimate of how important something is
 
-Both are unscientific flawed but they allow me to try to focus on maximizing impact while minimizing effort which is important for an open source project.
+Both are unscientific and flawed but they allow me to try to focus on what to work on when.
 
-If you look at the [project's issues](https://github.com/mharrisb1/openai-responses-python/issues), you'll see they are labeled with some non-standard labels.
+If you look at the [project's issues](https://github.com/mharrisb1/openai-responses-python/issues), you'll see they are labeled with some non-standard issue labels.
 
-| Label                                                                                  | Description   |
-| -------------------------------------------------------------------------------------- | ------------- |
-| <span style='background-color: green; padding: 2px; border-radius: 5px'>e0 🌵</span>   | Low effort    |
+| Label                                                                                | Description   |
+| ------------------------------------------------------------------------------------ | ------------- |
+| <span style='background-color: green; padding: 2px; border-radius: 5px'>e0 🌵</span>  | Low effort    |
 | <span style='background-color: yellow; padding: 2px; border-radius: 5px'>e1 ⚡️</span> | Medium effort |
-| <span style='background-color: red; padding: 2px; border-radius: 5px'>e2 🔥</span>     | High effort   |
-| <span style='background-color: green; padding: 2px; border-radius: 5px'>i0 🌵</span>   | Low impact    |
+| <span style='background-color: red; padding: 2px; border-radius: 5px'>e2 🔥</span>    | High effort   |
+| <span style='background-color: green; padding: 2px; border-radius: 5px'>i0 🌵</span>  | Low impact    |
 | <span style='background-color: yellow; padding: 2px; border-radius: 5px'>i1 ⚡️</span> | Medium impact |
-| <span style='background-color: red; padding: 2px; border-radius: 5px'>i2 🔥</span>     | High impact   |
+| <span style='background-color: red; padding: 2px; border-radius: 5px'>i2 🔥</span>    | High impact   |
 
 Ranking is evaluated according to this quadrant where the priority is ordered from top to bottom and left to right.
 
@@ -75,33 +75,3 @@ poetry install --with dev                   # install deps including development
 poetry shell                                # activate venv
 tox run                                     # run lint, static analysis, unit tests, and examples
 ```
-
-## Design Overview
-
-### Mocks
-
-Mocks are classes that are responsible for encapsulating all request patching of a given endpoint.
-
-Endpoints are classified as either _stateless_ or _stateful_ mocks. Right now, the only difference between `StatelessMock` and `StatefulMock` is the injection of `used_state` (see [state store](#state-store) below for more).
-
-```mermaid
-classDiagram
-    Mock <-- StatelessMock
-    Mock <-- StatefulMock
-
-    StatelessMock <-- ChatCompletionMock
-    StatelessMock <-- EmbeddingsMock
-
-    StatefulMock <-- FilesMock
-    StatefulMock <-- AssistantsMock
-    StatefulMock <-- ThreadsMock
-    StatefulMock <-- MessagesMock
-    StatefulMock <-- RunsMock
-    StatefulMock <-- RunStepsMock
-```
-
-### State store
-
-The state store is responsible for managing the state of all mocked objects throughout the lifetime of the test scope (function, module, session).
-
-The current implementation of the state store is just a naive dictionary-based KV stores with support for common CRUD operations.

README.md

@@ -1,48 +1,44 @@
 # 🧪🤖 openai-responses
 
-Pytest plugin for automatically mocking OpenAI requests. Built on top of [RESPX](https://github.com/lundberg/respx).
+Pytest plugin for automatically mocking OpenAI requests. Powered by [RESPX](https://github.com/lundberg/respx).
 
-## Supported endpoints
+[![sdk support](https://img.shields.io/badge/SDK_Support-v1.25+-white?logo=openai&logoColor=black&labelColor=white)](https://github.com/openai/openai-python)
+
+## Supported Routes
 
 - `/v1/chat/completions`
 - `/v1/embeddings`
 - `/v1/files`
 - `/v1/assistants`
 - `/v1/threads` (+ messages, runs, and steps)
 
-View full support coverage [here](https://mharrisb1.github.io/openai-responses-python/endpoints/).
+View full support coverage [here](https://mharrisb1.github.io/openai-responses-python/routes).
 
 ## Usage
 
-Simply decorate any test function that contains code that makes a call to an OpenAI endpoint. See [docs](https://mharrisb1.github.io/openai-responses-python) for more.
+Just decorate any test function that makes a call to the OpenAI API (either using the [official Python SDK](https://github.com/openai/openai-python) or with [HTTPX](https://www.python-httpx.org/)).
 
 ```python
+import openai
+
 import openai_responses
-from openai import OpenAI
-
-
-@openai_responses.mock.chat.completions(
-    choices=[
-        {"message": {"content": "Hello, how can I help?"}},
-        {"message": {"content": "Hi! I'm here to help!"}},
-        {"message": {"content": "How can I help?"}},
-    ],
-)
-def test_create_completion_with_multiple_choices():
-    client = OpenAI(api_key="fakeKey")
-    completion = client.chat.completions.create(
-        model="gpt-3.5-turbo",
-        messages=[
-            {"role": "system", "content": "You are a helpful assistant."},
-            {"role": "user", "content": "Hello!"},
-        ],
-        n=3,
+
+
+@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 len(completion.choices) == 3
+
+    assert assistant.name == "Math Tutor"
 ```
 
-> [!IMPORTANT]
-> This project does not try to generate fake responses from the models. Any part of a response that would be generated by a model will need to be defined by the user or will fallback to a default value.
+See [examples](https://github.com/mharrisb1/openai-responses-python/tree/main/examples) or [docs](https://mharrisb1.github.io/openai-responses-python) for more.
 
 ## Installation