# 09 - Encyclopedia

**Notebook:** `09-encyclopedia.ipynb`

## Video

<iframe width="720" height="406" src="https://www.youtube.com/embed/_6gcpKUGKPQ?si=kp5HbqesLKyf-7W-" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## The Challenge

Now is Notebook 9, and this one is **the challenge**.

We've given you all the building blocks required to create your encyclopedia of birds in famous poems. We're going to encourage you to think about **forking this** and making it your own over the coming week—make it even cooler if you have time for the individual project.

---

## What We're Going to Do

This notebook takes you through the process of:

1. **Connecting to OpenAI** — Setting up your API client
2. **Connecting to your Google Drive** — Mounting and setting up paths
3. **Setting up a folder full of texts** — Put in some bird poems (you're welcome to use ours, or if you want to do your own encyclopedia, put in poems of your own and look for something other than birds)
4. **Looping through the texts** — Send each one to OpenAI to get back structured data with all the properties we need for an encyclopedia entry
5. **Generating images** — As a bonus, use the image generation API to create an image for each bird
6. **Creating the output** — Save it all as your encyclopedia

---

## The Big Picture

Here's what's happening at a high level:

[Folder of poem text files]
        ↓
    Loop through each file
        ↓
    Send text to OpenAI → Get structured entry back
        ↓
    Use art_prompt to generate image
        ↓
    Store entry + image path
        ↓
[Save as JSON encyclopedia]

Every piece we've learned comes together here.

---

## The Schema: Defining What You Want Back

This is where you decide what your encyclopedia entries look like:

class EncyclopediaEntry(BaseModel):
    title: str
    bird_species: str
    literary_significance: str
    themes: list[str]
    era: str
    art_prompt: str

Think of this like designing a spreadsheet:
- Every entry will have these exact columns
- `themes` is a list because a poem might have multiple themes
- `art_prompt` is clever—we're asking OpenAI to write a prompt we'll feed to DALL-E

**This is yours to customize.** Want more fields? Add them. Want different fields? Change them.

---

## The generate_entry Function

This is the heart of the pipeline:

def generate_entry(text: str, filename: str) -> EncyclopediaEntry:
    response = client.responses.parse(
        model="gpt-5-mini",
        input=[{
            "role": "user",
            "content": f"""Analyze this poem and extract information about the bird mentioned.

Filename: {filename}

Text:
{text}

Provide a detailed encyclopedia entry about the bird's role in this poem."""
        }],
        text_format=EncyclopediaEntry
    )
    return response.output_parsed

Let's break down what's happening:

1. **Input**: We pass in the poem text and filename
2. **The prompt**: We're asking OpenAI to analyze the poem
3. **text_format**: We demand the response match our schema
4. **Output**: We get back an `EncyclopediaEntry` object with all our fields filled in

The magic is that OpenAI reads the poem, understands it, and fills in every field of our schema automatically.

---

## The Main Loop

Here's where scale happens:

entries = []

for file_data in source_files:
    print(f"Processing: {file_data['filename']}")

    # Get structured analysis from OpenAI
    entry = generate_entry(file_data['text'], file_data['filename'])

    # Generate an image using DALL-E
    image_path = create_image(entry.art_prompt, file_data['filename'])

    # Store the results
    entries.append({
        **entry.model_dump(),  # Convert entry to dictionary
        "image_path": str(image_path)
    })

    print(f"  → {entry.title}: {entry.bird_species}")

For **every single poem** in your folder:
1. Send it to OpenAI
2. Get back structured data
3. Generate an image based on the art prompt
4. Add it to our list

Whether you have 3 poems or 300, the code is the same.

---

## Generating Images with DALL-E

One of the coolest parts of this project is generating artwork for each entry:

def create_image(prompt: str, filename: str) -> Path:
    response = client.images.generate(
        model="dall-e-3",
        prompt=prompt,
        size="1024x1024"
    )

    image_url = response.data[0].url

    # Download and save the image
    image_path = OUTPUT_DIR / f"{filename}.png"
    # ... save image code ...

    return image_path

The `art_prompt` field from your structured output becomes the input for image generation. So OpenAI is essentially writing a prompt for itself!

---

## Saving Your Encyclopedia

At the end, save everything as JSON:

import json

with open(OUTPUT_DIR / "encyclopedia.json", "w") as f:
    json.dump(entries, f, indent=2)

Your JSON file will look something like:

[
  {
    "title": "The Raven",
    "bird_species": "Common Raven",
    "literary_significance": "Symbol of death and loss...",
    "themes": ["grief", "madness", "memory"],
    "era": "American Romanticism",
    "art_prompt": "A dark raven perched on a marble bust...",
    "image_path": "output/the_raven.png"
  },
  ...
]

---

## Common Issues

**"I'm getting errors about the API key"**
- Make sure you've added your key to Colab Secrets
- Make sure it's named exactly `OPENAI_API_KEY`
- Run the cell that sets up `os.environ` before making API calls

**"My Drive isn't showing up"**
- Run the `drive.mount()` cell and grant permissions
- Click the refresh button in the file browser
- Sometimes you need to wait a moment

**"The structured output has weird values"**
- Try adjusting your prompt to be more specific
- Add examples of what you want in the prompt
- Check that your schema field names are clear

**"Image generation is slow"**
- DALL-E takes 10-20 seconds per image—this is normal
- For testing, you might want to skip images at first

---

## Remix Ideas

Once you've got it working, think about:

### Different Topics

- Instead of birds, what about **flowers in poems**?
- **Monsters in mythology**?
- **Food in literature**?
- **Weather in Shakespeare**?

### Different Properties

What other fields would make your encyclopedia more interesting?

- Historical context
- Emotional tone
- Related works
- Fun facts

### Different Output Formats

- Could you generate a **PDF**?
- A **website**?
- **Pokemon-style cards**?
- A **slideshow presentation**?

---

## You Have Superpowers Now

Remember what we said at the beginning?

> **Once you can loop through a large list of stuff—like a giant list of poems—and then you can do something that can become really complex with every single element in that list... well then you kind of have superpowers.**

You've built up all the tools:

- **Variables** — storing values
- **Lists** — holding multiple items
- **Loops** — doing things at scale
- **Dictionaries** — complex data structures
- **Functions** — reusable code
- **API Calls** — talking to AI
- **Structured Output** — getting predictable data
- **Files** — reading and writing

Now put them all together and make something amazing!

---

## We Can't Wait to See What You Come Up With!

---

## Summary

In this capstone notebook, you:

- Combined **all the building blocks** from the previous lessons
- Created a complete **processing pipeline**
- Generated **structured data** and **images** at scale
- Built your own **encyclopedia of birds in famous poems**

This is just the beginning. Take what you've learned and **make it your own**!