Improve Documentation (instructor-ai#96)

* maybe

* everything

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "[python]": {
+        "editor.defaultFormatter": "ms-python.black-formatter"
+    },
+    "python.formatting.provider": "none"
+}

docs/examples/index.md

@@ -5,12 +5,12 @@ Welcome to the examples page. Here you will find emails that highlight a range o
 ## Quick Links 
 
 - [Classifying Text](classification.md)
-- [Identifying Action Items with dependencies](action_items.md)
-- [Segmenting search requests into multiple search queries](search.md)
+- [Extracting search requests into multiple search queries](search.md)
+- [Exact citations using regex](exact_citations.md)
 - [One shot query planning](planning-tasks.md)
 - [Using recursive schema](recursive.md)
-- [Exact citations using regex](exact_citations.md)
 - [Automated database extraction from text](autodataframe.md)
+- [Identifying Action Items with dependencies](action_items.md)
 - [Creating multiple file programs](gpt-engineer.md)
 
 ## Details
@@ -19,7 +19,6 @@ In this section, you will find examples demonstrating different aspects of our p
 
 - [Classfying Text](classification.md): Doing single and multi class prediction using enums.
 
-- [Identifying Action Items with dependencies](action_items.md): Scanning a transcript to generate action items with subtasks.
 
 - [Segmented Search](search.md): Learn how to perform segmented search using a multi task definition using function calling
 
@@ -33,6 +32,8 @@ In this section, you will find examples demonstrating different aspects of our p
 
 - [Creating Multiple File Programs](gpt-engineer.md): Master how to create multiple file programs based on specification using function calling.
 
+- [Identifying Action Items with dependencies](action_items.md): Scanning a transcript to generate action items with subtasks.
+
 Feel free to explore these examples to gain a better understanding of various patterns on how creative prompting, description, and structuring of `OpenAISchema` and unlock new capabilities.
 
 If you have any questions or need further assistance, please refer to the specific example documentation or reach out to our support team.

docs/maybe.md

@@ -1,8 +1,16 @@
-# Handling Errors Within Function Calls
+# Error Handling Using Maybe Pattern
 
-You can create a wrapper class to hold either the result of an operation or an error message. This allows you to remain within a function call even if an error occurs, facilitating better error handling without breaking the code flow.
+## Introduction
+
+The `Maybe` pattern is a functional programming concept used for error handling. Instead of raising exceptions or returning `None`, you can use a `Maybe` type to encapsulate both the result and possible errors.
+
+## Define Models with Pydantic
+
+Using Pydantic, define the `UserDetail` and `MaybeUser` classes.
 
 ```python
+from pydantic import BaseModel, Field, Optional
+
 class UserDetail(BaseModel):
     age: int
     name: str
@@ -11,22 +19,55 @@ class UserDetail(BaseModel):
 class MaybeUser(BaseModel):
     result: Optional[UserDetail] = Field(default=None)
     error: bool = Field(default=False)
-    message: Optional[str]
+    message: Optional[str] = Field(default=None)
 
     def __bool__(self):
         return self.result is not None
 ```
 
-With the `MaybeUser` class, you can either receive a `UserDetail` object in result or get an error message in message.
+## Implementing `Maybe` Pattern with `instructor`
 
-## Simplification with the Maybe Pattern
-
-You can further simplify this using instructor to create the `Maybe` pattern.
+You can use `instructor` to generalize the `Maybe` pattern.
 
 ```python
 import instructor
 
 MaybeUser = instructor.Maybe(UserDetail)
 ```
 
-This allows you to quickly create a Maybe type for any class, streamlining the process.
+## Function Example: `get_user_detail`
+
+Here's a function example that returns a `MaybeUser` instance. The function simulates an API call to get user details.
+
+```python
+from typing import Optional
+import random
+
+def get_user_detail(string: str) -> MaybeUser:
+    ...
+    return
+
+# Example usage
+user1 = get_user_detail("Jason is a 25 years old scientist")
+{
+  "result": {
+    "age": 25,
+    "name": "Jason",
+    "role": "scientist"
+  },
+  "error": false,
+  "message": null
+}
+
+
+user2 = get_user_detail("Unknown user")
+{
+  "result": null,
+  "error": true,
+  "message": "User not found"
+}
+```
+
+## Conclusion
+
+The `Maybe` pattern enables a more structured approach to error handling. This example illustrated its implementation using Python and Pydantic.

docs/multitask.md

@@ -1,4 +1,4 @@
-# Patterns for Multiple Extraction
+# Patterns for Extracting Multiple Items
 
 A common use case of structured extraction is defining a single schema class and then making another schema to create a list to do multiple extraction
 
@@ -16,14 +16,14 @@ Defining a task and creating a list of classes is a common enough pattern that w
 1. Dynamic docstrings and class name baed on the task
 2. Helper method to support streaming by collectin function_call tokens until a object back out.
 
-## Extracting Tasks
+## Extracting Tasks using MultiTask
 
 By using multitask you get a very convient class with prompts and names automatically defined. You get `from_response` just like any other `OpenAISchema` you're able to extract the list of objects data you want with `MultTask.tasks`.
 
 ```python hl_lines="13"
 from instructor import OpenAISchema, MultiTask
 
-class User(OpenAISchema):
+class User(BaseModel):
     name: str
     age: int
 

mkdocs.yml

@@ -45,29 +45,30 @@ markdown_extensions:
 nav:
   - Introduction: 
       - Getting Started: 'index.md'
-      - MultiTask: "multitask.md"
-      - Maybe: "maybe.md"
+      - Prompt Engineering Tips: 'tips/index.md'
+      - Meta Functions:
+        - Multiple Extractions: "multitask.md"
+        - Handling Missing Content: "maybe.md"
       - Philosophy: 'philosophy.md'
   - Use Cases:
       - 'Overview': 'examples/index.md'
-      - 'Classifying Text': 'examples/classification.md'
-      - 'Extracting Action Items': 'examples/action_items.md'
-      - 'Segmented Search': 'examples/search.md'
+      - 'Text Classification': 'examples/classification.md'
+      - 'Exact Citations for RAG': 'examples/exact_citations.md'
+      - 'Extracting Multiple Search Queries': 'examples/search.md'
       - 'One shot Query Planning': 'examples/planning-tasks.md'
       - 'Recursive Schemas': 'examples/recursive.md'
-      - 'Exact Citations': 'examples/exact_citations.md'
       - 'Automated Dataframe Extraction': "examples/autodataframe.md"
+      - 'Extracting Action Items from Transcript': 'examples/action_items.md'
       - 'Creating multiple file programs': "examples/gpt-engineer.md"
-  - Prompt Engineering Tips: 'tips/index.md'
+  - CLI Reference:
+      - "Introduction": "cli/index.md"
+      - "Usage Tracking": "cli/usage.md"
+      - "Finetuning GPT": "cli/finetune.md"
   - API Reference:
       - 'OpenAISchema': 'openai_schema.md'
       - 'MultiTask': 'api_multitask.md'
       - "Introduction: Writing Prompts": "writing-prompts.md"
       - "Prompting Templates": "chat-completion.md"
-  - CLI Reference:
-      - "Introduction": "cli/index.md"
-      - "Usage Tracking": "cli/usage.md"
-      - "Finetuning GPT": "cli/finetune.md"
 extra:
   analytics:
     provider: google