instructor/docs/examples/maybe.md

# Error Handling Using Maybe Pattern

## 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
    role: Optional[str] = Field(default=None)

class MaybeUser(BaseModel):
    result: Optional[UserDetail] = Field(default=None)
    error: bool = Field(default=False)
    message: Optional[str] = Field(default=None)

    def __bool__(self):
        return self.result is not None
```

## Implementing `Maybe` Pattern with `instructor`

You can use `instructor` to generalize the `Maybe` pattern.

```python
import instructor

MaybeUser = instructor.Maybe(UserDetail)
```

## 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.