Update docs

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

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: