diff --git a/README.md b/README.md index f181387..a54279b 100644 --- a/README.md +++ b/README.md @@ -45,22 +45,47 @@ assert user.name == "Jason" assert user.age == 25 ``` -!!! note "Using `openai<1.0.0`" +**"Using `openai<1.0.0`"** - If you're using `openai<1.0.0` then make sure you `pip install instructor<0.3.0` - where you can patch a global client like so: +If you're using `openai<1.0.0` then make sure you `pip install instructor<0.3.0` +where you can patch a global client like so: - ```python hl_lines="4 8" - import openai - import instructor +```python hl_lines="4 8" +import openai +import instructor - instructor.patch() +instructor.patch() - user = openai.ChatCompletion.create( - ..., - response_model=UserDetail, - ) - ``` +user = openai.ChatCompletion.create( + ..., + response_model=UserDetail, +) +``` + +**"Using async clients"** + +For async clients you must use apatch vs patch like so: + +```py +import instructor +from openai import AsyncOpenAI + +aclient = instructor.apatch(AsyncOpenAI()) + +class UserExtract(BaseModel): + name: str + age: int + +model = await aclient.chat.completions.create( + model="gpt-3.5-turbo", + response_model=UserExtract, + messages=[ + {"role": "user", "content": "Extract jason is 25 years old"}, + ], +) + +assert isinstance(model, UserExtract) +``` ## Installation diff --git a/docs/index.md b/docs/index.md index 6fcf68b..62e2135 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,11 +2,9 @@ _Structured extraction in Python, powered by OpenAI's function calling api, designed for simplicity, transparency, and control._ -Built to interact solely with openai's function calling api from python. It's designed to be intuitive, easy to use, and provide great visibility into your prompts. - --- -[Star us on Github!](https://jxnl.github.io/instructor) +[Star us on Github!](https://jxnl.github.io/instructor). [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow)](https://www.buymeacoffee.com/jxnlco) [![Downloads](https://img.shields.io/pypi/dm/instructor.svg)](https://pypi.python.org/pypi/instructor) @@ -19,12 +17,12 @@ Built to interact solely with openai's function calling api from python. It's de [![PyPI version](https://img.shields.io/pypi/v/instructor.svg)](https://pypi.python.org/pypi/instructor) [![PyPI pyversions](https://img.shields.io/pypi/pyversions/instructor.svg)](https://pypi.python.org/pypi/instructor) ---- +Built to interact solely with openai's function calling api from python. It's designed to be intuitive, easy to use, and provide great visibility into your prompts. ## Usage ```py hl_lines="5 13" -from openai import OpenAI() +from openai import OpenAI import instructor # Enables `response_model` @@ -47,7 +45,7 @@ assert user.name == "Jason" assert user.age == 25 ``` -!!! note "Using `openai<1.0.0`" +!!! warning "Using `openai<1.0.0`" If you're using `openai<1.0.0` then make sure you `pip install instructor<0.3.0` where you can patch a global client like so: @@ -64,6 +62,31 @@ assert user.age == 25 ) ``` +!!! note "Using async clients" + + For async clients you must use apatch vs patch like so: + + ```py + import instructor + from openai import AsyncOpenAI + + aclient = instructor.apatch(AsyncOpenAI()) + + class UserExtract(BaseModel): + name: str + age: int + + model = await aclient.chat.completions.create( + model="gpt-3.5-turbo", + response_model=UserExtract, + messages=[ + {"role": "user", "content": "Extract jason is 25 years old"}, + ], + ) + + assert isinstance(model, UserExtract) + ``` + ## Installation To get started you need to install it using `pip`. Run the following command in your terminal: @@ -89,9 +112,10 @@ The patch introduces 3 features to the `ChatCompletion` class: First, import the required libraries and apply the patch function to the OpenAI module. This exposes new functionality with the response_model parameter. -```python hl_lines="6" +```python import instructor from openai import OpenAI +from pydantic import BaseModel # This enables response_model keyword # from client.chat.completions.create @@ -115,7 +139,7 @@ class UserDetail(BaseModel): Use the `client.chat.completions.create` method to send a prompt and extract the data into the Pydantic object. The response_model parameter specifies the Pydantic model to use for extraction. Its helpful to annotate the variable with the type of the response model. which will help your IDE provide autocomplete and spell check. -```python hl_lines="3" +```python user: UserDetail = client.chat.completions.create( model="gpt-3.5-turbo", response_model=UserDetail, @@ -128,7 +152,7 @@ assert user.name == "Jason" assert user.age == 25 ``` -## Advanced: Pydantic Validation +## Pydantic Validation Validation can also be plugged into the same Pydantic model. Here, if the answer attribute contains content that violates the rule "don't say objectionable things," Pydantic will raise a validation error. @@ -155,20 +179,20 @@ except ValidationError as e: Its important to not here that the error message is generated by the LLM, not the code, so it'll be helpful for re asking the model. -```plaintext hl_lines="3" +```plaintext 1 validation error for QuestionAnswer answer Assertion failed, The statement is objectionable. (type=assertion_error) ``` -## Advanced: Reask on validation error +## Reask on validation error Here, the `UserDetails` model is passed as the `response_model`, and `max_retries` is set to 2. -```python hl_lines="15-18 22 23 29" +```python +from openai import OpenAI import instructor -from openai import OpenAI from pydantic import BaseModel, field_validator # Apply the patch to the OpenAI client diff --git a/instructor/__init__.py b/instructor/__init__.py index 0417839..b03ccf7 100644 --- a/instructor/__init__.py +++ b/instructor/__init__.py @@ -1,7 +1,7 @@ from .function_calls import OpenAISchema, openai_function, openai_schema from .distil import FinetuneFormat, Instructions from .dsl import MultiTask, Maybe, llm_validator, CitationMixin -from .patch import patch +from .patch import patch, apatch __all__ = [ "OpenAISchema", @@ -11,6 +11,7 @@ __all__ = [ "Maybe", "openai_schema", "patch", + "apatch", "llm_validator", "FinetuneFormat", "Instructions", diff --git a/instructor/patch.py b/instructor/patch.py index 61c2cf3..bdf9507 100644 --- a/instructor/patch.py +++ b/instructor/patch.py @@ -134,9 +134,7 @@ def retry_sync( raise e -def wrap_chatcompletion(func: Callable) -> Callable: - is_async = inspect.iscoroutinefunction(func) - +def wrap_chatcompletion(func: Callable, is_async: bool = None) -> Callable: @wraps(func) async def new_chatcompletion_async( response_model=None, @@ -211,7 +209,7 @@ def apatch(client): - `validation_context` parameter to validate the response using the pydantic model - `strict` parameter to use strict json parsing """ - client.chat.completions.acreate = wrap_chatcompletion( - client.chat.completions.acreate + client.chat.completions.create = wrap_chatcompletion( + client.chat.completions.create, is_async=True ) return client diff --git a/pyproject.toml b/pyproject.toml index df14706..f17742b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "instructor" -version = "0.3.1" +version = "0.3.2" description = "Helper functions that allow us to improve openai's function_call ergonomics" authors = ["Jason Liu "] license = "MIT" diff --git a/tests/test_patch.py b/tests/test_patch.py index a3a1ea9..3029a49 100644 --- a/tests/test_patch.py +++ b/tests/test_patch.py @@ -1,9 +1,32 @@ +import pytest + from pydantic import BaseModel -from openai import OpenAI +from openai import OpenAI, AsyncOpenAI import instructor client = instructor.patch(OpenAI()) +aclient = instructor.apatch(AsyncOpenAI()) + + +@pytest.mark.asyncio +async def test_async_runmodel(): + class UserExtract(BaseModel): + name: str + age: int + + model = await aclient.chat.completions.create( + model="gpt-3.5-turbo", + response_model=UserExtract, + messages=[ + {"role": "user", "content": "Extract jason is 25 years old"}, + ], + ) + assert isinstance(model, UserExtract), "Should be instance of UserExtract" + assert model.name.lower() == "jason" + assert hasattr( + model, "_raw_response" + ), "The raw response should be available from OpenAI" def test_runmodel(): diff --git a/tutorials/1.introduction.ipynb b/tutorials/1.introduction.ipynb index df03abb..1b16acc 100644 --- a/tutorials/1.introduction.ipynb +++ b/tutorials/1.introduction.ipynb @@ -38,7 +38,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We have a `name` field, which is a string, and an `age` field, which is an integer. However, if we were to load this into a dictionary, we would have no way of knowing if the data is valid. For example, we could have a string for the age, or we could have a float for the age. We could also have a string for the name, or we could have a list for the name. We have no way of knowing if the data is valid, and we have no way of knowing if the data is valid." + "We have a `name` field, which is a string, and an `age` field, which is an integer. However, if we were to load this into a dictionary, we would have no way of knowing if the data is valid. For example, we could have a string for the age, or we could have a float for the age. We could also have a string for the name, or we could have a list for the name." ] }, { @@ -486,7 +486,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now you can see that when we set response_model create call will now return a pydantic model, and we can use that to validate the data. and work with it as if it was a python object." + "Now you can see that when we set `response_model` create call will now return a pydantic model, and we can use that to validate the data. and work with it as if it was a python object." ] } ], diff --git a/tutorials/2.applications-rag.ipynb b/tutorials/2.applications-rag.ipynb index 718e9ff..39aaed4 100644 --- a/tutorials/2.applications-rag.ipynb +++ b/tutorials/2.applications-rag.ipynb @@ -107,7 +107,7 @@ "source": [ "### Example 1) Improving Extractions\n", "\n", - "One of the big limitations is that often times the query we embed and the text \n", + "One of the big limitations is that often times the query we embed and the text that we want to retrieve are not sufficiently close in the semantic space.\n", "A common method of using structured output is to extract information from a document and use it to answer a question. Directly, we can be creative in how we extract, summarize and generate potential questions in order for our embeddings to do better. \n", "\n", "For example, instead of using just a text chunk we could try to:\n", @@ -511,9 +511,9 @@ "source": [ "### Example 4) Decomposing questions \n", "\n", - "Lastly, a lightly more complex example of a problem that can be solved with structured output is decomposing questions. Where you ultimately want to decompose a question into a series of sub-questions that can be answered by a search backend. For example \n", + "Lastly, a lightly more complex example of a problem that can be solved with structured output is decomposing questions. Where you ultimately want to decompose a question into a series of sub-questions that can be answered by a search backend. For example:\n", "\n", - "\"Whats the difference in populations of jason's home country and canadata?\"\n", + "\"Whats the difference in populations of jason's home country and canada?\"\n", "\n", "You'd ultimately need to know a few things\n", "\n", @@ -525,11 +525,6 @@ "This would not be done correctly as a single query, nor would it be done in parallel, however there are some opportunities try to be parallel since not all of the sub-questions are dependent on each other." ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [] - }, { "cell_type": "code", "execution_count": 35,