Docs! Help wanted, adding examples. (#44)

* add docs

* bump

docs/help.md

@@ -0,0 +1,3 @@
+# Docs are incomplete
+
+Help wanted! 

docs/index.md

@@ -0,0 +1,72 @@
+# Welcome to OpenAI Function Call
+
+We try to provides a powerful and efficient approach to output parsing when interacting with OpenAI's Function Call API. One that is framework agnostic and minimizes any dependencies. It leverages the data validation capabilities of the Pydantic library to handle output parsing in a more structured and reliable manner. If you have any feedback, leave an issue or hit me up on [twitter](https://twitter.com/jxnlco). 
+
+## Installation
+
+```python
+pip install openai_function_call
+```
+
+## Usage
+
+This module simplifies the interaction with the OpenAI API, enabling a more structured outputs. Below are examples showcasing the use of function calls and schemas with OpenAI and Pydantic. In later modoules we'll go over a wide array of more creative uses.
+
+### Example 1: Function Calls
+
+```python
+import openai
+from openai_function_call import openai_function
+
+@openai_function
+def sum(a:int, b:int) -> int:
+    """Sum description adds a + b"""
+    return a + b
+
+completion = openai.ChatCompletion.create(
+        model="gpt-3.5-turbo-0613",
+        temperature=0,
+        functions=[sum.openai_schema],
+        function_call={"name": sum.openai_schema["name"]},
+        messages=[
+            {
+                "role": "system",
+                "content": "You must use the `sum` function instead of adding yourself.",
+            },
+            {
+                "role": "user",
+                "content": "What is 6+3",
+            },
+        ],
+    )
+
+result = sum.from_response(completion)
+print(result)  # 9
+```
+
+### Example 2: Schema Extraction
+
+```python
+import openai
+from openai_function_call import OpenAISchema
+
+from pydantic import Field
+
+class UserDetails(OpenAISchema):
+    """Details of a user"""
+    name: str = Field(..., description="users's full name")
+    age: int
+
+completion = openai.ChatCompletion.create(
+    model="gpt-3.5-turbo-0613",
+    functions=[UserDetails.openai_schema],
+    function_call={"name": UserDetails.openai_schema["name"]},
+    messages=[
+        {"role": "system", "content": "Extract user details from my requests"},
+        {"role": "user", "content": "My name is John Doe and I'm 30 years old."},
+    ],
+)
+
+user_details = UserDetails.from_response(completion)
+print(user_details)  # name="John Doe", age=30
+```

docs/openai_schema.md

@@ -0,0 +1,58 @@
+# OpenAI Schema
+
+The most generic helper is a light weight extention of Pydantic's BaseModel `OpenAISchema`.
+It has a method to help you produce the schema and parse the result of function calls
+
+This library is moreso a list of examples and a helper class so I'll keep the example as just structured extraction.
+
+## Where does the prompts go?
+
+Instead of defining your prompts in the messages the prompts you would usually use are now defined as part of the dostring of your class and the field descriptions. This is nice since it allows you to colocate the schema with the class you use to represent the structure.
+
+## Structured Extraction
+
+```python
+import openai
+from openai_function_call import OpenAISchema
+
+from pydantic import Field
+
+class UserDetails(OpenAISchema):
+    """Details of a user"""
+    name: str = Field(..., description="users's full name")
+    age: int
+
+completion = openai.ChatCompletion.create(
+    model="gpt-3.5-turbo-0613",
+    functions=[UserDetails.openai_schema],
+    function_call={"name": UserDetails.openai_schema["name"]},
+    messages=[
+        {"role": "system", "content": "Extract user details from my requests"},
+        {"role": "user", "content": "My name is John Doe and I'm 30 years old."},
+    ],
+)
+
+user_details = UserDetails.from_response(completion)
+print(user_details)  # name="John Doe", age=30
+```
+
+## Using the decorator 
+
+You can also use a decorator but i recommend the class since you get nice autocompletes with VSCode
+
+```python
+import openai
+from openai_function_call import openai_schema
+
+from pydantic import Field, BaseModel
+
+@openai_schema
+class UserDetails(BaseModel):
+    """Details of a user"""
+    name: str = Field(..., description="users's full name")
+    age: int
+```
+
+## OpenAISchema
+
+::: openai_function_call.OpenAISchema

mkdocs.yml

@@ -0,0 +1,35 @@
+site_name: OpenAI Function call 
+theme:
+  name: material
+  icon:
+    repo: fontawesome/brands/github
+  features:
+    - navigation.instant
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            members_order: alphabetical
+repo_url: https://github.com/jxnl/openai_function_call
+markdown_extensions:
+  - pymdownx.critic
+  - pymdownx.caret
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.tilde
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - attr_list
+  - md_in_html
+nav:
+  - Home: 'index.md'
+  - Module:
+      - 'Schemas': 'openai_schema.md'
+  - Examples:
+      - 'Missing': 'help.md'

openai_function_call/function_calls.py

@@ -84,6 +84,9 @@ class OpenAISchema(BaseModel):
     @classmethod
     @property
     def openai_schema(cls):
+        """
+        Return the schema of the class in the format of OpenAI's schema
+        """
         schema = cls.schema()
         parameters = {
             k: v for k, v in schema.items() if k not in ("title", "description")
@@ -98,6 +101,7 @@ class OpenAISchema(BaseModel):
 
     @classmethod
     def from_response(cls, completion, throw_error=True):
+        """Execute the function from the response of an openai chat completion"""
         message = completion.choices[0].message
 
         if throw_error:
@@ -116,7 +120,7 @@ def openai_schema(cls):
         raise TypeError("Class must be a subclass of pydantic.BaseModel")
 
     @wraps(cls, updated=())
-    class Wrapper(cls, OpenAISchema):
+    class Wrapper(cls, OpenAISchema):  # type: ignore
         pass
 
     return Wrapper