From 84495433765c8a4f0b021f80433d7f3c0b7f5702 Mon Sep 17 00:00:00 2001 From: Jason Liu Date: Thu, 7 Sep 2023 17:12:03 -0500 Subject: [PATCH] Improve Documentation (#96) * maybe * everything --- .vscode/settings.json | 6 +++++ docs/examples/index.md | 9 ++++--- docs/maybe.md | 57 ++++++++++++++++++++++++++++++++++++------ docs/multitask.md | 6 ++--- mkdocs.yml | 23 +++++++++-------- 5 files changed, 75 insertions(+), 26 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..d99f2f3 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,6 @@ +{ + "[python]": { + "editor.defaultFormatter": "ms-python.black-formatter" + }, + "python.formatting.provider": "none" +} \ No newline at end of file diff --git a/docs/examples/index.md b/docs/examples/index.md index 81247c8..f657156 100644 --- a/docs/examples/index.md +++ b/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. diff --git a/docs/maybe.md b/docs/maybe.md index d021393..2fbb7bf 100644 --- a/docs/maybe.md +++ b/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,17 +19,15 @@ 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 @@ -29,4 +35,39 @@ import instructor MaybeUser = instructor.Maybe(UserDetail) ``` -This allows you to quickly create a Maybe type for any class, streamlining the process. \ No newline at end of file +## 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. \ No newline at end of file diff --git a/docs/multitask.md b/docs/multitask.md index f8fa28b..5464d47 100644 --- a/docs/multitask.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index ac90fe4..13793f1 100644 --- a/mkdocs.yml +++ b/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