From c393b34491a06f1c49f94578523df36b1c7d0436 Mon Sep 17 00:00:00 2001
From: Pierce Freeman <piercefreeman@gmail.com>
Date: Thu, 24 Aug 2023 14:36:53 -0700
Subject: [PATCH] Update docs

---
 README.md              | 14 +++++++-------
 gpt_json/fn_calling.py | 12 +++++++++---
 2 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index f154aac..2e177d6 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@ Respond with the following JSON schema:
 
 async def runner():
     gpt_json = GPTJSON[SentimentSchema](API_KEY)
-    response, _ = await gpt_json.run(
+    payload = await gpt_json.run(
         messages=[
             GPTMessage(
                 role=GPTMessageRole.SYSTEM,
@@ -51,8 +51,8 @@ async def runner():
             )
         ]
     )
-    print(response)
-    print(f"Detected sentiment: {response.sentiment}")
+    print(payload.response)
+    print(f"Detected sentiment: {payload.response.sentiment}")
 
 asyncio.run(runner())
 ```
@@ -102,7 +102,7 @@ Generate fictitious quotes that are {sentiment}.
 """
 
 gpt_json = GPTJSON[QuoteSchema](API_KEY)
-response, _ = await gpt_json.run(
+response = await gpt_json.run(
     messages=[
         GPTMessage(
             role=GPTMessageRole.SYSTEM,
@@ -126,7 +126,7 @@ Generate fictitious quotes that are {sentiment}.
 """
 
 gpt_json = GPTJSON[QuoteSchema](API_KEY)
-response, _ = await gpt_json.run(
+response = await gpt_json.run(
     messages=[
         GPTMessage(
             role=GPTMessageRole.SYSTEM,
@@ -214,9 +214,9 @@ GPT (especially GPT-4) is relatively good at formatting responses at JSON, but i
 When calling `gpt_json.run()`, we return a tuple of values:
 
 ```python
-response, transformations = await gpt_json.run(...)
+payload = await gpt_json.run(...)
 
-print(transformations)
+print(transformations.fix_transforms)
 ```
 
 ```bash
diff --git a/gpt_json/fn_calling.py b/gpt_json/fn_calling.py
index 185cec0..f83e3d3 100644
--- a/gpt_json/fn_calling.py
+++ b/gpt_json/fn_calling.py
@@ -99,9 +99,15 @@ def get_base_type(field_type):
 
 def resolve_refs(schema, defs=None):
     """
-    Given a JSON-Schema, resolve all $ref references to their definitions. This is supported
-    by the OpenAPI spec, but not by Pydantic. It makes for a cleaner API definition for use in
-    the GPT API.
+    Given a JSON-Schema, replace all $ref references to their definitions.
+
+    When JSON Schemas are exported by pydantic, use of nested fields (like enums) will be defined
+    in a separate $defs lookup table. This is a valid OpenAPI schema but makes for a less-obvious
+    definition for the GPT API. Additionally, none of the docs use the $defs format, so conceivably
+    the model was not fine-tuned on this particular format.
+
+    This function takes a schema complete with $defs and resolves all the references to their
+    full definition. The resulting payload is what we send to the GPT API.
 
     """
     if defs is None: