> ## Documentation Index
> Fetch the complete documentation index at: https://futureagi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic Prompt Optimization

> A hands-on guide to optimizing your first prompt using the agent-opt Python library with a simple Random Search strategy.

This cookbook provides a step-by-step walkthrough for optimizing a prompt using the `agent-opt` Python library. We will use the `RandomSearchOptimizer` to demonstrate the core workflow of generating prompt variations and selecting the best one based on performance.

## 1. Installation and Setup

First, install the library and set up your environment variables. You can get your API keys from the [Future AGI dashboard](https://app.futureagi.com/dashboard/keys).

```bash theme={null}
pip install agent-opt
```

```python theme={null}
import os

os.environ["FI_API_KEY"] = "YOUR_API_KEY"
os.environ["FI_SECRET_KEY"] = "YOUR_SECRET_KEY"
```

## 2. Prepare Your Dataset

Optimization requires a dataset to evaluate prompt performance. A dataset is a simple list of Python dictionaries. For this example, we'll create a small dataset for a summarization task.

```python theme={null}
dataset = [
    {
        "article": "The James Webb Space Telescope has captured stunning new images of the Pillars of Creation, revealing intricate details of gas and dust clouds where new stars are forming.",
        "target_summary": "The JWST has taken new, detailed pictures of the Pillars of Creation."
    },
    {
        "article": "Researchers have discovered a new enzyme that can break down plastics at record speed, offering a potential solution to the global plastic pollution crisis.",
        "target_summary": "A new enzyme that rapidly breaks down plastics has been found."
    },
]
```

## 3. Configure and Run the Optimization

Next, we'll set up the necessary components:

* **`Evaluator`**: To score our prompts based on a metric.
* **`DataMapper`**: To map our dataset fields to the optimizer's expected inputs.
* **`RandomSearchOptimizer`**: To generate and test prompt variations.

```python theme={null}
from fi.opt.optimizers import RandomSearchOptimizer
from fi.opt.generators import LiteLLMGenerator
from fi.opt.datamappers import BasicDataMapper
from fi.opt.base.evaluator import Evaluator

# a. Define the generator with the initial prompt to be optimized
initial_prompt = "Summarize this: {article}"
initial_generator = LiteLLMGenerator(
    model="gpt-4o-mini",
    prompt_template=initial_prompt
)

# b. Setup the evaluator to score prompt performance
evaluator = Evaluator(
    eval_template="summary_quality",  # A built-in template for summarization
    eval_model_name="turing_flash"    # The model to perform the evaluation
)

# c. Setup the data mapper to link dataset fields
data_mapper = BasicDataMapper(
    key_map={"input": "article", "output": "generated_output"}
)

# d. Initialize the Random Search optimizer
optimizer = RandomSearchOptimizer(
    generator=initial_generator,
    teacher_model="gpt-4o",  # A powerful model to generate prompt ideas
    num_variations=5         # Generate 5 different versions of our prompt
)

# e. Run the optimization
result = optimizer.optimize(
    evaluator=evaluator,
    data_mapper=data_mapper,
    dataset=dataset
)
```

## 4. Analyze the Results

The `result` object contains the best prompt found and its final score. You can also inspect the history of all variations that were tried.

```python theme={null}
# Print the best prompt and its score
print(f"--- Optimization Complete ---")
print(f"Final Score: {result.final_score:.4f}")
print(f"Best Prompt Found:\n{result.best_generator.get_prompt_template()}")

# Review the history of all tried variations
for i, iteration in enumerate(result.history):
    print(f"\n--- Variation {i+1} ---")
    print(f"Score: {iteration.average_score:.4f}")
    print(f"Prompt: {iteration.prompt}")
```

This basic workflow is the foundation for all other optimization tasks. You can now explore more advanced optimizers and evaluation techniques.