From 56e69d4378da391cb05670f3823bb6e9cdbf36d3 Mon Sep 17 00:00:00 2001
From: Jason Liu <jxnl@users.noreply.github.com>
Date: Mon, 12 Feb 2024 09:43:41 -0500
Subject: [PATCH] docs(patching): introduce new patching methods and modes,
 update documentation (#431)

---
 docs/concepts/patching.md | 75 ++++++++++++++++++++++-----------------
 1 file changed, 42 insertions(+), 33 deletions(-)

diff --git a/docs/concepts/patching.md b/docs/concepts/patching.md
index faf7e96..a9538fa 100644
--- a/docs/concepts/patching.md
+++ b/docs/concepts/patching.md
@@ -1,4 +1,4 @@
-# Patching
+# Patching the OpenAI Client
 
 Instructor enhances client functionality with three new keywords for backwards compatibility. This allows use of the enhanced client as usual, with structured output benefits.
 
@@ -6,13 +6,44 @@ Instructor enhances client functionality with three new keywords for backwards c
 - `max_retries`: Determines retry attempts for failed `chat.completions.create` validations.
 - `validation_context`: Provides extra context to the validation process.
 
-There are three methods for structured output:
+There are two ways to patch the OpenAI client: patching the client itself, or patching a specific function. The former is more general, while the latter is more specific.
+
+Then there are a handful of modes to choose from:
 
 1. **Function Calling**: The primary method. Use this for stability and testing.
 2. **Tool Calling**: Useful in specific scenarios; lacks the reasking feature of OpenAI's tool calling API.
 3. **JSON Mode**: Offers closer adherence to JSON but with more potential validation errors. Suitable for specific non-function calling clients.
+4. **Markdown JSON Mode**: Experimental, not recommended.
+5. **JSON Schema Mode**: Only available with the [Together](../blog/posts/together.md) and [Anyscale](../blog/posts/anyscale.md) patches.
 
-## Function Calling
+## Patching Modes
+
+We support two kinds of patches One that patches anything isomorphic to the OpenAI client and the other to a specific create call
+
+### Patch Client
+
+```python
+import instructor
+from openai import OpenAI
+
+client = instructor.patch(OpenAI())
+```
+
+### Patch Create
+
+This allows you to patch any function that is isomorphic to `chat.completions.create`. function with messages and other parameters.
+
+```python
+import instructor
+from openai import OpenAI
+
+create_fn = OpenAI().chat.completions.create
+create = instructor.patch(create=create_fn)
+```
+
+## Patching Modes
+
+### Function Calling
 
 ```python
 import instructor
@@ -21,7 +52,7 @@ from openai import OpenAI
 client = instructor.patch(OpenAI(), mode=instructor.Mode.FUNCTIONS)
 ```
 
-## Tool Calling
+### Tool Calling
 
 ```python
 import instructor
@@ -30,7 +61,7 @@ from openai import OpenAI
 client = instructor.patch(OpenAI(), mode=instructor.Mode.TOOLS)
 ```
 
-## JSON Mode
+### JSON Mode
 
 ```python
 import instructor
@@ -40,7 +71,7 @@ from openai import OpenAI
 client = instructor.patch(OpenAI(), mode=Mode.JSON)
 ```
 
-## Markdown JSON Mode
+### Markdown JSON Mode
 
 !!! warning "Experimental"
 
@@ -53,37 +84,15 @@ from openai import OpenAI
 client = instructor.patch(OpenAI(), mode=instructor.Mode.MD_JSON)
 ```
 
-### Schema Integration
+### JSON Schema Mode
 
-In JSON Mode, the schema is part of the system message:
+This is only available with the [Together](../blog/posts/together.md) and [Anyscale](../blog/posts/anyscale.md) patches.
 
 ```python
 import instructor
 from openai import OpenAI
 
-client = instructor.patch(OpenAI())
-
-
-class UserExtract(instructor.OpenAISchema):
-    name: str
-    age: int
-
-
-response = client.chat.completions.create(
-    model="gpt-3.5-turbo-1106",
-    response_format={"type": "json_object"},
-    messages=[
-        {
-            "role": "system",
-            "content": f"Match your response to this json_schema: \n{UserExtract.model_json_schema()['properties']}",
-        },
-        {
-            "role": "user",
-            "content": "Extract jason is 25 years old",
-        },
-    ],
-)
-user = UserExtract.from_response(response, mode=instructor.Mode.JSON)
-print(user)
-#> name='Jason' age=25
+client = instructor.patch(OpenAI(
+    ...
+), mode=instructor.Mode.JSON_SCHEMA)
 ```