chore: import upstream snapshot with attribution

docs/learning/patterns/nested_structure.md

@@ -0,0 +1,357 @@
+---
+title: Nested Structure Extraction with Instructor
+description: Learn how to extract complex nested data structures from LLMs using hierarchical Pydantic models.
+---
+
+# Simple Nested Structure
+
+This guide explains how to extract nested structured data using Instructor. Nested structures allow you to represent complex, hierarchical data relationships.
+
+## Understanding Nested Structures
+
+Nested structures are objects that contain other objects as fields. They're useful for representing:
+
+1. Parent-child relationships
+2. Complex entities with sub-components
+3. Hierarchical data
+4. Related data that belongs together
+
+## Basic Nested Structure Example
+
+Here's a simple example of extracting a nested structure:
+
+```python
+from pydantic import BaseModel, Field
+import instructor
+from typing import List, Optional
+# Initialize the client
+client = instructor.from_provider("openai/gpt-5-nano")
+
+# Define nested models
+class Address(BaseModel):
+    street: str
+    city: str
+    state: str
+    zip_code: str
+
+class Person(BaseModel):
+    name: str
+    age: int
+    address: Address  # Nested structure
+
+# Extract the nested data
+response = client.create(
+    model="gpt-5.4-mini",
+    messages=[
+        {"role": "user", "content": """
+        John Smith is 35 years old.
+        He lives at 123 Main Street, Boston, MA 02108.
+        """}
+    ],
+    response_model=Person
+)
+
+# Access the nested data
+print(f"Name: {response.name}")
+print(f"Age: {response.age}")
+print(f"Address: {response.address.street}, {response.address.city}, "
+      f"{response.address.state} {response.address.zip_code}")
+```
+
+## Multiple Levels of Nesting
+
+You can use multiple levels of nesting for more complex structures:
+
+```python
+from pydantic import BaseModel, Field
+import instructor
+from typing import List, Optional
+client = instructor.from_provider("openai/gpt-5-nano")
+
+class EmployeeDetails(BaseModel):
+    department: str
+    position: str
+    start_date: str
+
+class ContactInfo(BaseModel):
+    phone: str
+    email: str
+
+class Address(BaseModel):
+    street: str
+    city: str
+    state: str
+    zip_code: str
+
+class Person(BaseModel):
+    name: str
+    age: int
+    contact: ContactInfo  # First level nesting
+    address: Address      # First level nesting
+    employment: Optional[EmployeeDetails] = None  # Optional nested structure
+
+# Extract deeply nested data
+response = client.create(
+    model="gpt-5.4-mini",
+    messages=[
+        {"role": "user", "content": """
+        Employee Profile:
+        Name: Jane Doe
+        Age: 32
+        Phone: (555) 123-4567
+        Email: jane.doe@example.com
+        Address: 456 Oak Avenue, Chicago, IL 60601
+        Department: Engineering
+        Position: Senior Developer
+        Start Date: 2021-03-15
+        """}
+    ],
+    response_model=Person
+)
+```
+
+## Nested Lists
+
+You can combine nesting with lists to represent complex collections:
+
+```python
+from pydantic import BaseModel, Field
+import instructor
+from typing import List
+client = instructor.from_provider("openai/gpt-5-nano")
+
+class Ingredient(BaseModel):
+    name: str
+    amount: str
+    unit: str
+
+class Recipe(BaseModel):
+    title: str
+    description: str
+    ingredients: List[Ingredient]  # Nested list of ingredients
+    steps: List[str]  # List of strings
+
+# Extract nested list data
+response = client.create(
+    model="gpt-5.4-mini",
+    messages=[
+        {"role": "user", "content": """
+        Recipe: Chocolate Chip Cookies
+
+        Description: Classic homemade chocolate chip cookies that are soft in the middle and crispy on the edges.
+
+        Ingredients:
+        - 2 1/4 cups all-purpose flour
+        - 1 teaspoon baking soda
+        - 1 teaspoon salt
+        - 1 cup butter
+        - 3/4 cup white sugar
+        - 3/4 cup brown sugar
+        - 2 eggs
+        - 2 teaspoons vanilla extract
+        - 2 cups chocolate chips
+
+        Instructions:
+        1. Preheat oven to 375°F (190°C)
+        2. Mix flour, baking soda, and salt
+        3. Cream butter and sugars, then add eggs and vanilla
+        4. Gradually add dry ingredients
+        5. Stir in chocolate chips
+        6. Drop by rounded tablespoons onto ungreased baking sheets
+        7. Bake for 9 to 11 minutes or until golden brown
+        8. Cool on wire racks
+        """}
+    ],
+    response_model=Recipe
+)
+```
+
+For more information on working with lists, see the [List Extraction](list_extraction.md) guide.
+
+## Handling Optional Nested Fields
+
+Sometimes parts of a nested structure might be missing. Use Optional to handle this:
+
+```python
+from pydantic import BaseModel, Field
+import instructor
+from typing import Optional
+client = instructor.from_provider("openai/gpt-5-nano")
+
+class SocialMedia(BaseModel):
+    twitter: Optional[str] = None
+    linkedin: Optional[str] = None
+    instagram: Optional[str] = None
+
+class ContactInfo(BaseModel):
+    email: str
+    phone: Optional[str] = None
+    social: Optional[SocialMedia] = None  # Optional nested structure
+
+class Person(BaseModel):
+    name: str
+    contact: ContactInfo
+```
+
+For more information on optional fields, see the [Optional Fields](optional_fields.md) guide.
+
+## Nested Structure Validation
+
+You can add validation to nested structures at any level:
+
+```python
+from pydantic import BaseModel, Field, field_validator, model_validator
+import instructor
+import re
+client = instructor.from_provider("openai/gpt-5-nano")
+
+class EmailContact(BaseModel):
+    email: str
+
+    @field_validator('email')
+    @classmethod
+    def validate_email(cls, v):
+        pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+        if not re.match(pattern, v):
+            raise ValueError("Invalid email format")
+        return v
+
+class Customer(BaseModel):
+    name: str
+    contact: EmailContact  # Nested structure with its own validation
+
+    @model_validator(mode='after')
+    def validate_name_email_match(self):
+        name_part = self.name.lower().split()[0]
+        if name_part not in self.contact.email.lower():
+            print(f"Warning: Email {self.contact.email} may not match name {self.name}")
+        return self
+```
+
+For more on validation, see [Field Validation](field_validation.md) and [Validation Basics](../validation/basics.md).
+
+## Working with Recursive Structures
+
+For more complex hierarchical data, you can use recursive structures:
+
+```python
+from typing import List, Optional
+from pydantic import BaseModel, Field
+import instructor
+client = instructor.from_provider("openai/gpt-5-nano")
+
+class Comment(BaseModel):
+    text: str
+    author: str
+    replies: List["Comment"] = []  # Recursive structure
+
+# Update the Comment class reference for Pydantic
+Comment.model_rebuild()
+
+class Post(BaseModel):
+    title: str
+    content: str
+    author: str
+    comments: List[Comment] = []
+
+# Extract recursive nested data
+response = client.create(
+    model="gpt-5.4-mini",
+    messages=[
+        {"role": "user", "content": """
+        Blog Post: "Python Tips and Tricks"
+        Author: John Smith
+        Content: Here are some helpful Python tips for beginners...
+
+        Comments:
+        1. Alice: "Great post! Very helpful."
+           - Bob: "I agree, I learned a lot."
+             - Alice: "Bob, did you try the last example?"
+           - Charlie: "Thanks for sharing this."
+        2. David: "Could you explain the second tip more?"
+           - John: "Sure, I'll add more details."
+        """}
+    ],
+    response_model=Post
+)
+```
+
+For more advanced recursive structures, see the [Recursive Structures](../../examples/recursive.md) guide.
+
+## Real-world Example: Organization Structure
+
+Here's a more complete example extracting an organization structure:
+
+```python
+from typing import List, Optional
+from pydantic import BaseModel, Field
+import instructor
+client = instructor.from_provider("openai/gpt-5-nano")
+
+class Employee(BaseModel):
+    name: str
+    title: str
+
+class Department(BaseModel):
+    name: str
+    head: Employee
+    employees: List[Employee]
+    sub_departments: List["Department"] = []
+
+# Update for Pydantic's recursive model support
+Department.model_rebuild()
+
+class Organization(BaseModel):
+    name: str
+    ceo: Employee
+    departments: List[Department]
+
+# Extract organization structure
+response = client.create(
+    model="gpt-5.4-mini",
+    messages=[
+        {"role": "user", "content": """
+        Acme Corporation
+        CEO: Jane Smith, Chief Executive Officer
+
+        Departments:
+
+        1. Engineering
+           Head: Bob Johnson, CTO
+           Employees:
+           - Sarah Lee, Senior Engineer
+           - Tom Brown, Software Developer
+
+           Sub-departments:
+           - Frontend Team
+             Head: Lisa Wang, Frontend Lead
+             Employees:
+             - Mike Chen, UI Developer
+             - Ana Garcia, UX Designer
+
+           - Backend Team
+             Head: David Kim, Backend Lead
+             Employees:
+             - James Wright, Database Engineer
+             - Rachel Patel, API Developer
+
+        2. Marketing
+           Head: Michael Davis, CMO
+           Employees:
+           - Jennifer Miller, Marketing Specialist
+           - Robert Chen, Content Creator
+        """}
+    ],
+    response_model=Organization
+)
+```
+
+
+## Related Resources
+
+- [Simple Object Extraction](./simple_object.md) - Extracting basic objects
+- [List Extraction](./list_extraction.md) - Working with lists of objects
+- [Optional Fields](./optional_fields.md) - Handling optional data
+- [Recursive Structures](../../examples/recursive.md) - Building more complex hierarchies
+- [Field Validation](./field_validation.md) - Adding validation to your fields
+