### Interactive Session Start Example

Source: https://dspy.ai/tutorials/sample_code_generation

Demonstrates the initial prompts and user interactions when starting the interactive learning system for a library like FastAPI.

```text
🎯 Welcome to the Interactive Library Learning System!
This system will help you learn any Python library from its documentation.

============================================================
🚀 LIBRARY LEARNING SESSION
============================================================

📚 Enter the library name you want to learn (or 'quit' to exit): FastAPI

🔗 Enter documentation URLs for FastAPI (one per line, empty line to finish):
  URL: https://fastapi.tiangolo.com/
  URL: https://fastapi.tiangolo.com/tutorial/first-steps/
  URL: https://fastapi.tiangolo.com/tutorial/path-params/
  URL: 

🎯 Define use cases for FastAPI (optional, press Enter for defaults):
   Default use cases will be: Basic setup, Common operations, Advanced usage
   Do you want to define custom use cases? (y/n): y
   Enter your use cases (one per line, empty line to finish):
     Use case: Create a REST API with authentication
     Use case: Build a file upload endpoint
     Use case: Add database integration with SQLAlchemy
     Use case: 
```

--------------------------------

### Initialize and Prepare Dataset

Source: https://dspy.ai/tutorials/gepa_facilitysupportanalyzer

Loads a dataset from a URL, converts it into DSPy examples, shuffles, and splits it into training, validation, and test sets. Ensure the 'requests', 'dspy', 'json', and 'random' libraries are installed.

```python
import requests
import dspy
import json
import random

def init_dataset():
    # Load from the url
    url = "https://raw.githubusercontent.com/meta-llama/llama-prompt-ops/refs/heads/main/use-cases/facility-support-analyzer/dataset.json"
    dataset = json.loads(requests.get(url).text)
    dspy_dataset = [
        dspy.Example({
            "message": d['fields']['input'],
            "answer": d['answer'],
        }).with_inputs("message")
        for d in dataset
    ]
    random.Random(0).shuffle(dspy_dataset)
    train_set = dspy_dataset[:int(len(dspy_dataset) * 0.33)]
    val_set = dspy_dataset[int(len(dspy_dataset) * 0.33):int(len(dspy_dataset) * 0.66)]
    test_set = dspy_dataset[int(len(dspy_dataset) * 0.66):]

    return train_set, val_set, test_set

```

--------------------------------

### Install BM25s and JAX

Source: https://dspy.ai/tutorials/rl_multihop

Install the bm25s library for retrieval and JAX with CPU support. These are necessary for the retrieval component of the tutorial.

```bash
> pip install -U bm25s PyStemmer "jax[cpu]"

```

--------------------------------

### Display Example from Dataset

Source: https://dspy.ai/tutorials/agents

Prints the claim and the required supporting pages for the first example in the training set.

```python
example = trainset[0]

print("Claim:", example.claim)
print("Pages that must be retrieved:", example.titles)
```

--------------------------------

### Install BM25S and JAX

Source: https://dspy.ai/tutorials/multihop_search

Install the BM25S library for retrieval, PyStemmer for text processing, and JAX with CPU support.

```bash
> pip install -U bm25s PyStemmer "jax[cpu]"
```

--------------------------------

### Install Datasets Package

Source: https://dspy.ai/tutorials/rl_multihop

Install a specific version of the datasets package required for the tutorial.

```bash
pip install datasets==3.6.0
```

--------------------------------

### Install DSPy and Dependencies

Source: https://dspy.ai/tutorials/sample_code_generation

Install the necessary libraries for DSPy, requests, and HTML parsing.

```bash
pip install dspy requests beautifulsoup4 html2text

```

--------------------------------

### Install MATH Dataset

Source: https://dspy.ai/tutorials/math

Installs the MATH dataset from GitHub, which is used for training and evaluating math reasoning models.

```bash
%pip install git+https://github.com/hendrycks/math.git

```

--------------------------------

### Install Dependencies

Source: https://dspy.ai/tutorials/yahoo_finance_react

Install the necessary Python packages for DSPy, LangChain, and Yahoo Finance.

```bash
pip install dspy langchain langchain-community yfinance

```

--------------------------------

### Install Arbor and DSPy

Source: https://dspy.ai/tutorials/rl_papillon

Install the Arbor RL framework and DSPy from the main branch. Ensure you have the latest versions for compatibility.

```bash
pip install -U arbor-ai

```

```bash
pip install -U git+https://github.com/stanfordnlp/dspy.git@main

```

--------------------------------

### View Example Task

Source: https://dspy.ai/tutorials/games

Initializes an environment for a specific task from the training set and prints the task description.

```python
example = trainset[0]

with alfworld.POOL.session() as env:
    task, info = env.init(**example.inputs())

print(task)
```

--------------------------------

### Safely Get Value from DSPy Example

Source: https://dspy.ai/api/primitives/Example

The `get()` method allows you to retrieve a field's value from an Example. It safely handles missing fields by returning a specified default value instead of raising an error.

```python
>>> import dspy
>>> ex = dspy.Example(name="Alice")
>>> ex.get("name")
'Alice'
>>> ex.get("city", "Unknown")
'Unknown'
```

--------------------------------

### Install SGLang for Inference

Source: https://dspy.ai/tutorials/classification_finetuning

Installs SGLang and its dependencies for running local inference servers. It's recommended to follow the official installation guide for the most up-to-date commands.

```bash
> pip install --upgrade pip
> pip install uv
> uv pip install "sglang[all]>=0.4.4.post3" --find-links https://flashinfer.ai/whl/cu124/torch2.5/flashinfer-python

```

--------------------------------

### Multimodal Request with Instructions

Source: https://dspy.ai/community/normalized-lm-api-migration

This example demonstrates making a multimodal request with system instructions and an image. Note: Image support is coming soon.

```python
from dspy.core.types import LMImagePart

with dspy.context(experimental=True):
    response = lm(
        dspy.System("Be concise."),
        dspy.User("Describe this image.", dspy.Image("https://example.com/dog.png")), #Coming soon!
        temperature=0.2,
    )

```

--------------------------------

### Get Field Value from DSPy Example

Source: https://dspy.ai/api/evaluation/EvaluationResult

Retrieves the value of a specified field from a DSPy Example. Returns a default value if the field does not exist. Useful for safely accessing example attributes.

```python
def get(self, key, default=None):
    """Return the value for `key`, or `default` if the field doesn't exist.

    Args:
        key: Field name to look up.
        default: Value to return when `key` is missing.

    Examples:
        >>> import dspy
        >>> ex = dspy.Example(name="Alice")
        >>> ex.get("name")
        'Alice'
        >>> ex.get("city", "Unknown")
        'Unknown'
    """
    return self._store.get(key, default)
```

--------------------------------

### Build dspy.Example from keyword arguments

Source: https://dspy.ai/api/primitives/Example

Create an Example by passing fields as keyword arguments. Use .with_inputs() to specify which fields are inputs for a module.

```python
>>> import dspy
>>> example = dspy.Example(
...     question="What is the capital of France?",
...     answer="Paris",
... ).with_inputs("question")
>>> example.question
'What is the capital of France?'
>>> example.answer
'Paris'
>>> example.inputs().toDict()
{'question': 'What is the capital of France?'}
```

--------------------------------

### Get Labels from DSPy Example

Source: https://dspy.ai/api/evaluation/EvaluationResult

Returns a new Example containing only the label (non-input) fields. Requires `with_inputs` to have been called first.

```python
>>> import dspy
>>> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
>>> ex.labels()
Example({'answer': 'Because.'}) (input_keys=None)
```

--------------------------------

### Initialize MCP Client and Gather Tools

Source: https://dspy.ai/tutorials/mcp

This snippet demonstrates how to set up an MCP client, connect to the server, list available tools, and convert them into DSPy Tool objects. Ensure the server parameters correctly point to your MCP server script.

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Create server parameters for stdio connection
server_params = StdioServerParameters(
    command="python",  # Executable
    args=["path_to_your_working_directory/mcp_server.py"],
    env=None,
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the connection
            await session.initialize()
            # List available tools
            tools = await session.list_tools()

            # Convert MCP tools to DSPy tools
            dspy_tools = []
            for tool in tools.tools:
                dspy_tools.append(dspy.Tool.from_mcp_tool(session, tool))

            print(len(dspy_tools))
            print(dspy_tools[0].args)

if __name__ == "__main__":
    import asyncio

    asyncio.run(run())
```

--------------------------------

### Initialize DSPy LM and Configure

Source: https://dspy.ai/tutorials/image_generation_prompting

Import necessary libraries, load environment variables, and configure the DSPy language model.

```python
import dspy

from PIL import Image
from io import BytesIO
import requests
import fal_client

from dotenv import load_dotenv
load_dotenv()

# import display
from IPython.display import display

lm = dspy.LM(model="gpt-4o-mini", temperature=0.5)
dspy.configure(lm=lm)

```

--------------------------------

### Get Values from DSPy Example

Source: https://dspy.ai/api/evaluation/EvaluationResult

Returns field values from a DSPy Example, similar to `dict.values()`. By default, it excludes internal fields prefixed with `dspy_`.

```python
>>> import dspy
>>> dspy.Example(question="Why?", answer="Because.").values()
['Why?', 'Because.']
```

--------------------------------

### Get Example Keys (Field Names)

Source: https://dspy.ai/api/evaluation/EvaluationResult

Returns a list of field names for the example, similar to `dict.keys()`. By default, it excludes internal fields prefixed with `dspy_`.

```python
>>> import dspy
>>> dspy.Example(question="Why?", answer="Because.").keys()
['question', 'answer']
```

--------------------------------

### Get Example Items (Field-Value Pairs)

Source: https://dspy.ai/api/evaluation/EvaluationResult

Returns a list of (field_name, value) tuples for the example, similar to `dict.items()`. By default, it excludes internal fields prefixed with `dspy_`.

```python
>>> import dspy
>>> dspy.Example(question="Why?", answer="Because.").items()
[('question', 'Why?'), ('answer', 'Because.')]
```

--------------------------------

### BetterTogether Strategy Execution Example

Source: https://dspy.ai/api/optimizers/BetterTogether

Demonstrates a strategy string 'p -> w -> p' to sequence prompt and weight optimizers. The optimizer names in the strategy string correspond to the keyword arguments from initialization.

```python
compiled = optimizer.compile(
    student,
    trainset=trainset,
    valset=valset,
    strategy="p -> w -> p"
)
```

--------------------------------

### Optimized Prompt Instruction Example

Source: https://dspy.ai/tutorials/rag

This snippet shows an example of an instruction constructed by the optimized prompt. It guides the model on how to use provided context and question to generate a response.

```text
Using the provided `context` and `question`, analyze the information step by step to generate a comprehensive and informative `response`. Ensure that the response clearly explains the concepts involved, highlights any complexities noted in the context.
```

--------------------------------

### Initialize BetterTogether with Different Optimizers

Source: https://dspy.ai/api/optimizers/BetterTogether

Illustrates initializing BetterTogether with different prompt optimizers like MIPROv2 and GEPA, demonstrating flexibility in combining various optimizers.

```python
optimizer = BetterTogether(
    metric=metric,
    mipro=MIPROv2(metric=metric, auto="light"),
    gepa=GEPA(metric=metric, auto="light")
)
```

--------------------------------

### Initialize DSPy and Configure LM

Source: https://dspy.ai/tutorials/sample_code_generation

Import necessary libraries, initialize the DSPy language model, and configure DSPy.

```python
import dspy
import requests
from bs4 import BeautifulSoup
import html2text
from typing import List, Dict, Any
import json
from urllib.parse import urljoin, urlparse
import time

# Configure DSPy
lm = dspy.LM(model='openai/gpt-4o-mini')
dspy.configure(lm=lm)

```

--------------------------------

### get(key, default=None)

Source: https://dspy.ai/api/primitives/Example

Retrieves the value associated with a given key from the example. If the key does not exist, it returns a specified default value.

```APIDOC
## get(key, default=None)

### Description
Retrieves the value associated with a given key from the example. If the key does not exist, it returns a specified default value.

### Method
`get`

### Parameters
#### Path Parameters
- **key** (string) - Required - The name of the field to look up.
- **default** (any) - Optional - The value to return if the key is not found. (Default: `None`)

### Request Example
```python
import dspy

ex = dspy.Example(name="Alice")
print(ex.get("name"))
print(ex.get("city", "Unknown"))
```

### Response
#### Success Response
Returns the value of the specified field, or the default value if the field is not present.

#### Response Example
```
'Alice'
'Unknown'
```
```

--------------------------------

### Generate Library Code Examples

Source: https://dspy.ai/tutorials/sample_code_generation

This function generates code examples for a given library based on its documentation and predefined use cases. It demonstrates basic setup, common operations, and advanced usage, printing the generated code, imports, explanations, and best practices.

```python
def generate_examples_for_library(library_info: Dict, library_name: str):
    """Generate code examples for any library based on its documentation."""

    # Define generic use cases that can apply to most libraries
    use_cases = [
        {
            "name": "Basic Setup and Hello World",
            "description": f"Create a minimal working example with {library_name}",
            "requirements": "Include installation, imports, and basic usage"
        },
        {
            "name": "Common Operations",
            "description": f"Demonstrate the most common {library_name} operations",
            "requirements": "Show typical workflow and best practices"
        },
        {
            "name": "Advanced Usage",
            "description": f"Create a more complex example showcasing {library_name} capabilities",
            "requirements": "Include error handling and optimization"
        }
    ]

    generated_examples = []

    print(f"\n🔧 Generating examples for {library_name}...")

    for use_case in use_cases:
        print(f"\n📝 {use_case['name']}")
        print(f"Description: {use_case['description']}")

        example = agent.generate_example(
            library_info=library_info,
            use_case=use_case['description'],
            requirements=use_case['requirements']
        )

        print("\n💻 Generated Code:")
        print("```python")
        print(example['code'])
        print("```")

        print("\n📦 Required Imports:")
        for imp in example['imports']:
            print(f"  • {imp}")

        print("\n📝 Explanation:")
        print(example['explanation'])

        print("\n✅ Best Practices:")
        for practice in example['best_practices']:
            print(f"  • {practice}")

        generated_examples.append({
            "use_case": use_case['name'],
            "code": example['code'],
            "imports": example['imports'],
            "explanation": example['explanation'],
            "best_practices": example['best_practices']
        })

        print("-" * 80)

    return generated_examples

# Generate examples for both libraries
print("🎯 Generating FastAPI Examples:")
fastapi_examples = generate_examples_for_library(fastapi_info, "FastAPI")

print("\n\n🎯 Generating Streamlit Examples:")
streamlit_examples = generate_examples_for_library(streamlit_info, "Streamlit")

```

--------------------------------

### GEPA Optimizer Setup and Compilation

Source: https://dspy.ai/tutorials/gepa_trusted_monitor

This snippet shows the setup for the GEPA optimizer, including model directory creation, LM initialization, and program compilation with training and validation sets. It then saves the optimized monitor program.

```python
MODEL_DIR = Path("models")
MODEL_DIR.mkdir(exist_ok=True)
MONITOR_GEPA_MODEL_PATH = MODEL_DIR / "gepa.json"

lm = dspy.LM(
    MONITOR_MODEL_NAME,
    cache=False,
    temperature=1.0,
    max_tokens=20000,
    api_key=OPENAI_API_KEY,
)
monitor_program = dspy_monitor_program(lm)
monitor_trainer_program = MonitorTrainerProgram(monitor_program)

gepa_optimizer = dspy.GEPA(
    max_full_evals=2,
    metric=metric_for_example,
    num_threads=8,
    reflection_minibatch_size=3,
    track_stats=True,
    reflection_lm=dspy.LM("openai/gpt-5", temperature=1.0, max_tokens=32000, api_key=OPENAI_API_KEY),
)
gepa_trainer_program = gepa_optimizer.compile(
    monitor_trainer_program,
    trainset=train_examples,
    valset=val_examples,
)

gepa_program = gepa_trainer_program.monitor_program
gepa_program.save(MONITOR_GEPA_MODEL_PATH)
```

--------------------------------

### Run Financial Analysis Demo

Source: https://dspy.ai/tutorials/yahoo_finance_react

Sets up and runs a demonstration of the financial analysis agent with predefined queries. It iterates through queries, prints them, and displays the agent's analysis response.

```python
def run_financial_demo():
    """Demo of the financial analysis agent."""

    # Initialize agent
    agent = FinancialAnalysisAgent()

    # Example queries
    queries = [
        "What's the latest news about Apple (AAPL) and how might it affect the stock price?",
        "Compare AAPL, GOOGL, and MSFT performance",
        "Find recent Tesla news and analyze sentiment"
    ]

    for query in queries:
        print(f"Query: {query}")
        response = agent(financial_query=query)
        print(f"Analysis: {response.analysis_response}")
        print("-" * 50)

# Run the demo
if __name__ == "__main__":
    run_financial_demo()

```

--------------------------------

### Library Analyzer DSPy Signature

Source: https://dspy.ai/tutorials/sample_code_generation

Defines a DSPy signature for analyzing library documentation to extract core concepts, common patterns, key methods, installation info, and code examples.

```python
class LibraryAnalyzer(dspy.Signature):
    """Analyze library documentation to understand core concepts and patterns."""
    library_name: str = dspy.InputField(desc="Name of the library to analyze")
    documentation_content: str = dspy.InputField(desc="Combined documentation content")

    core_concepts: list[str] = dspy.OutputField(desc="Main concepts and components")
    common_patterns: list[str] = dspy.OutputField(desc="Common usage patterns")
    key_methods: list[str] = dspy.OutputField(desc="Important methods and functions")
    installation_info: str = dspy.OutputField(desc="Installation and setup information")
    code_examples: list[str] = dspy.OutputField(desc="Example code snippets found")

```

--------------------------------

### format_examples

Source: https://dspy.ai/api/optimizers/InferRules

Formats a list of demonstrations into a string suitable for inclusion in program instructions.

```APIDOC
## `format_examples(demos, signature)`

### Description
Formats a list of demonstrations into a structured string.

### Parameters
- **demos** (list) - A list of dictionaries, where each dictionary represents a demonstration.
- **signature** (dspy.Signature) - The signature of the predictor to format examples for.

### Returns
- **str** - A formatted string of examples.
```

--------------------------------

### Synchronous Streaming Example

Source: https://dspy.ai/tutorials/streaming

This snippet shows how to set `async_streaming=False` when streamifying a DSPy program to get a synchronous generator. It iterates through the output chunks, printing stream responses and capturing the final prediction.

```python
import os

import dspy

os.environ["OPENAI_API_API_KEY"] = "your_api_key"

dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))

predict = dspy.Predict("question->answer")

# Enable streaming for the 'answer' field
stream_predict = dspy.streamify(
    predict,
    stream_listeners=[dspy.streaming.StreamListener(signature_field_name="answer")],
    async_streaming=False,
)

output = stream_predict(question="why did a chicken cross the kitchen?")

program_output = None
for chunk in output:
    if isinstance(chunk, dspy.streaming.StreamResponse):
        print(chunk)
    elif isinstance(chunk, dspy.Prediction):
        program_output = chunk
print(f"Program output: {program_output}")

```

--------------------------------

### Basic DSPy Program Setup

Source: https://dspy.ai/tutorials/deployment

Initializes DSPy with a language model and defines a simple ChainOfThought program.

```python
import dspy

dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
dspy_program = dspy.ChainOfThought("question -> answer")

```

--------------------------------

### Basic BestOfN Usage for One-Word Answers

Source: https://dspy.ai/tutorials/output_refinement/best-of-n-and-refine

Use BestOfN to run a module multiple times and return the best prediction based on a reward function. This example aims to get a single-word answer.

```python
import dspy

def one_word_answer(args, pred: dspy.Prediction) -> float:
    return 1.0 if len(pred.answer.split()) == 1 else 0.0

best_of_3 = dspy.BestOfN(
    module=dspy.ChainOfThought("question -> answer"), 
    N=3, 
    reward_fn=one_word_answer, 
    threshold=1.0
)

result = best_of_3(question="What is the capital of Belgium?")
print(result.answer)  # Brussels

```

--------------------------------

### GEPA Proposed Predict Text

Source: https://dspy.ai/tutorials/gepa_aime

Example of GEPA proposing new text for a 'predict' step, outlining the required output format for math problems. This guides the model's response structure.

```log
2025/08/12 23:29:37 INFO dspy.teleprompt.gepa.gepa: Iteration 21: Proposed new text for predict: Your job
- Solve exactly one math problem and return exactly two top-level JSON-like fields:
  - reasoning: a concise, logically ordered solution that leverages structure (identities, modular arithmetic, symmetry) and ends with a quick verification.
  - answer: the final requested number/expression only (no extra words or formatting).

Formatting
- Use exactly the two fields “reasoning” and “answer.”
- Keep the reasoning succinct but complete; bullet lists are fine.
- The answer field must contain only the final value requested (e.g., 227, 585, 601).
- Avoid heavy formatting (no LaTeX blocks, tables). Bullet lists are acceptable.

General problem-solving guidance
- Identify the problem type early (e.g., base/digit relations, repeating decimals, palindromes across bases, symmetric sums with fixed totals, intersecting subset families, avoiding arithmetic progressions, order statistics with absolute-sum constraints, floor-sum optimization, circle/geometry with radical axes or cyclic quadrilaterals, logarithm equations with shared unknowns, counting rectangles via chord-direction classes, equilateral hexagon with opposite sides parallel via support-triangle similarity).
- Enforce domain constraints strictly:
  • Base-b digits are in 0..b−1; leading digit nonzero if a positional numeral.
  • Logarithms: argument > 0, base > 0 and ≠ 1; respect any excluded x-values given.
  • Ordered vs unordered; strictly increasing where specified.
- Prefer structural arguments over brute force:
  • Factorization, completing the square, modular arithmetic, symmetry/reflection, similar triangles, cyclic identities, Ptolemy’s theorem, Law of Cosines/Sines, power of a point, bounding plus construction for extremals.
- For greatest/least questions, derive a tight bound and exhibit a construction attaining it.
- Always verify at the end (e.g., plug back into conditions, check modular constraints, recompute a key equality numerically).

Domain-specific strategies and pitfalls

A) Base conversion/digit equations
- Translate positional notation correctly: abc (base 10) = 100a + 10b + c; (a b c)_b = a·b^2 + b·b + c.
- Enforce digit ranges: in base 9, digits ∈ {0,…,8}. Leading digit in base-b must be 1..b−1 if a k-digit numeral.
- Use modular constraints to prune search (e.g., mod 9 or mod 71 from coefficient comparison).
- Verify numerically by converting the base-b representation back to decimal.

B) Repeating decimals 0.
-overline{abcd} and counting reduced numerators
- 0.
-overline{abcd} = m/9999 with 9999 = 3^2·11·101.
- Reduced numerator is x = m / gcd(m, 9999).
- Characterize x via existence of y | 9999 with y ≥ x and gcd(x, y) = 1 (since m = x·(9999/y) ≤ 9999).
- Use inclusion–exclusion over divisibility by 3, 9, 11, 101 carefully; treat “3 vs 9” distinctly.
```

--------------------------------

### DSPy Program with Backtracking and Refined Query

Source: https://dspy.ai/learn/programming/7-assertions

This example demonstrates a DSPy program after backtracking, incorporating a 'Past Query' and 'Instructions' to refine the generated 'Query'. The instructions guide the LM to produce a shorter, more concise query.

```dspy
Write a simple search query that will help answer a complex question.

---

Follow the following format.

Context: may contain relevant facts

Question: ${question}

Past Query: past output with errors

Instructions: Some instructions you must satisfy

Query: ${query}

---

Context:
[1] «Kerry Condon | Kerry Condon (born 4 January 1983) is an Irish television and film actress, best known for her role as Octavia of the Julii in the HBO/BBC series "Rome," as Stacey Ehrmantraut in AMC's "Better Call Saul" and as the voice of F.R.I.D.A.Y. in various films in the Marvel Cinematic Universe. She is also the youngest actress ever to play Ophelia in a Royal Shakespeare Company production of "Hamlet."»
[2] «Corona Riccardo | Corona Riccardo (c. 1878October 15, 1917) was an Italian born American actress who had a brief Broadway stage career before leaving to become a wife and mother. Born in Naples she came to acting in 1894 playing a Mexican girl in a play at the Empire Theatre. Wilson Barrett engaged her for a role in his play "The Sign of the Cross" which he took on tour of the United States. Riccardo played the role of Ancaria and later played Berenice in the same play. Robert B. Mantell in 1898 who struck by her beauty also cast her in two Shakespeare plays, "Romeo and Juliet" and "Othello". Author Lewis Strang writing in 1899 said Riccardo was the most promising actress in America at the time. Towards the end of 1898 Mantell chose her for another Shakespeare part, Ophelia im Hamlet. Afterwards she was due to join Augustin Daly's Theatre Company but Daly died in 1899. In 1899 she gained her biggest fame by playing Iras in the first stage production of Ben-Hur.»

Question: Who acted in the shot film The Shore and is also the youngest actress ever to play Ophelia in a Royal Shakespeare Company production of "Hamlet." ?

Past Query: "actress who played Ophelia in Royal Shakespeare Company production of Hamlet" + "actress in short film The Shore"

Instructions: Query should be short and less than 100 characters

Query: "actress Ophelia RSC Hamlet" + "actress The Shore"
```

--------------------------------

### Build dspy.Example from an existing record

Source: https://dspy.ai/api/primitives/Example

Create an Example by unpacking a dictionary. Use .with_inputs() to specify input fields and .labels() to access non-input fields.

```python
>>> record = {"question": "What is 2+2?", "answer": "4"}
>>> example = dspy.Example(**record).with_inputs("question")
>>> example["question"]
'What is 2+2?'
>>> example.labels().answer
'4'
```

--------------------------------

### Stream DSPy Program with Custom Status Messages

Source: https://dspy.ai/api/utils/streamify

Wrap a DSPy program with a custom status message provider to control progress updates. This example defines a `MyStatusMessageProvider` to customize messages for module starts and tool endings.

```python
import asyncio
import dspy

dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))

class MyStatusMessageProvider(StatusMessageProvider):
    def module_start_status_message(self, instance, inputs):
        return f"Predicting..."

    def tool_end_status_message(self, outputs):
        return f"Tool calling finished with output: {outputs}!"

# Create the program and wrap it with streaming functionality
program = dspy.streamify(dspy.Predict("q->a"), status_message_provider=MyStatusMessageProvider())

# Use the program with streaming output
async def use_streaming():
    output = program(q="Why did a chicken cross the kitchen?")
    return_value = None
    async for value in output:
        if isinstance(value, dspy.Prediction):
            return_value = value
        else:
            print(value)
    return return_value

output = asyncio.run(use_streaming())
print(output)
```

--------------------------------

### Initialize FastMCP Server

Source: https://dspy.ai/tutorials/mcp

Create an instance of FastMCP to build an MCP server. Provide a name for the agent.

```python
import random
import string

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel

# Create an MCP server
mcp = FastMCP("Airline Agent")


class Date(BaseModel):
    # Somehow LLM is bad at specifying `datetime.datetime`
    year: int
    month: int
    day: int
    hour: int


class UserProfile(BaseModel):
    user_id: str
    name: str
    email: str


class Flight(BaseModel):
    flight_id: str
    date_time: Date
    origin: str
    destination: str
    duration: float
    price: float


class Itinerary(BaseModel):
    confirmation_number: str
    user_profile: UserProfile
    flight: Flight


class Ticket(BaseModel):
    user_request: str
    user_profile: UserProfile


user_database = {
    "Adam": UserProfile(user_id="1", name="Adam", email="adam@gmail.com"),
    "Bob": UserProfile(user_id="2", name="Bob", email="bob@gmail.com"),
    "Chelsie": UserProfile(user_id="3", name="Chelsie", email="chelsie@gmail.com"),
    "David": UserProfile(user_id="4", name="David", email="david@gmail.com"),
}

flight_database = {
    "DA123": Flight(
        flight_id="DA123",
        origin="SFO",
        destination="JFK",
        date_time=Date(year=2025, month=9, day=1, hour=1),
        duration=3,
        price=200,
    ),
    "DA125": Flight(
        flight_id="DA125",
        origin="SFO",
        destination="JFK",
        date_time=Date(year=2025, month=9, day=1, hour=7),
        duration=9,
        price=500,
    ),
    "DA456": Flight(
        flight_id="DA456",
        origin="SFO",
        destination="SNA",
        date_time=Date(year=2025, month=10, day=1, hour=1),
        duration=2,
        price=100,
    ),
    "DA460": Flight(
        flight_id="DA460",
        origin="SFO",
        destination="SNA",
        date_time=Date(year=2025, month=10, day=1, hour=9),
        duration=2,
        price=120,
    ),
}

itinery_database = {}
ticket_database = {}


@mcp.tool()
def fetch_flight_info(date: Date, origin: str, destination: str):
    """Fetch flight information from origin to destination on the given date"""
    flights = []

    for flight_id, flight in flight_database.items():
        if (
            flight.date_time.year == date.year
            and flight.date_time.month == date.month
            and flight.date_time.day == date.day
            and flight.origin == origin
            and flight.destination == destination
        ):
            flights.append(flight)
    return flights


@mcp.tool()
def fetch_itinerary(confirmation_number: str):
    """Fetch a booked itinerary information from database"""
    return itinery_database.get(confirmation_number)


@mcp.tool()
def pick_flight(flights: list[Flight]):
    """Pick up the best flight that matches users' request."""
    sorted_flights = sorted(
        flights,
        key=lambda x: (
            x.get("duration") if isinstance(x, dict) else x.duration,
            x.get("price") if isinstance(x, dict) else x.price,
        ),
    )
    return sorted_flights[0]


def generate_id(length=8):
    chars = string.ascii_lowercase + string.digits
    return "".join(random.choices(chars, k=length))


@mcp.tool()
def book_itinerary(flight: Flight, user_profile: UserProfile):
    """Book a flight on behalf of the user."""
    confirmation_number = generate_id()
    while confirmation_number in itinery_database:
        confirmation_number = generate_id()
    itinery_database[confirmation_number] = Itinerary(
        confirmation_number=confirmation_number,
        user_profile=user_profile,
        flight=flight,
    )
    return confirmation_number, itinery_database[confirmation_number]


@mcp.tool()
def cancel_itinerary(confirmation_number: str, user_profile: UserProfile):
    """Cancel an itinerary on behalf of the user."""
    if confirmation_number in itinery_database:
        del itinery_database[confirmation_number]
        return
    raise ValueError("Cannot find the itinerary, please check your confirmation number.")


@mcp.tool()
def get_user_info(name: str):
    """Fetch the user profile from database with given name."""
    return user_database.get(name)


@mcp.tool()
def file_ticket(user_request: str, user_profile: UserProfile):
    """File a customer support ticket if this is something the agent cannot handle."""
    ticket_id = generate_id(length=6)
    ticket_database[ticket_id] = Ticket(
        user_request=user_request,
        user_profile=user_profile,
    )
    return ticket_id


if __name__ == "__main__":
    mcp.run()

```

--------------------------------

### dspy.Refine Module Example

Source: https://dspy.ai/api/modules/Refine

Demonstrates how to use the dspy.Refine module to improve predictions. It defines a question-answering module, a reward function to check for single-word answers, and then creates a refined module that attempts up to 3 times to get a valid answer.

```python
import dspy

dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))

# Define a QA module with chain of thought
qa = dspy.ChainOfThought("question -> answer")

# Define a reward function that checks for one-word answers
def one_word_answer(args, pred):
    return 1.0 if len(pred.answer.split()) == 1 else 0.0

# Create a refined module that tries up to 3 times
best_of_3 = dspy.Refine(module=qa, N=3, reward_fn=one_word_answer, threshold=1.0)

# Use the refined module
result = best_of_3(question="What is the capital of Belgium?").answer
# Returns: Brussels
```

--------------------------------

### Install Audio Dependencies

Source: https://dspy.ai/tutorials/audio

Install necessary libraries for handling audio data, including datasets, soundfile, and specific PyTorch versions with CUDA support if available.

```bash
pip install datasets soundfile torch==2.0.1+cu118 torchaudio==2.0.2+cu118

```

--------------------------------

### Implement a Custom Metric for GEPA Feedback

Source: https://dspy.ai/api/optimizers/GEPA/overview

Implement a metric function to provide feedback to the GEPA optimizer. This function can receive gold examples, predictions, and execution traces. It should return a score and optional textual feedback for guiding the optimization.

```python
def metric(
    gold: Example,
    pred: Prediction,
    trace: Optional[DSPyTrace] = None,
    pred_name: Optional[str] = None,
    pred_trace: Optional[DSPyTrace] = None,
) -> float | ScoreWithFeedback:
    """
    This function is called with the following arguments:
    - gold: The gold example.
    - pred: The predicted output.
    - trace: Optional. The trace of the program's execution.
    - pred_name: Optional. The name of the target predictor currently being optimized by GEPA, for which
        the feedback is being requested.
    - pred_trace: Optional. The trace of the target predictor's execution GEPA is seeking feedback for.

    Note the `pred_name` and `pred_trace` arguments. During optimization, GEPA will call the metric to obtain
    feedback for individual predictors being optimized. GEPA provides the name of the predictor in `pred_name`
    and the sub-trace (of the trace) corresponding to the predictor in `pred_trace`.
    If available at the predictor level, the metric should return {'score': float, 'feedback': str} corresponding
    to the predictor.
    If not available at the predictor level, the metric can also return a text feedback at the program level
    (using just the gold, pred and trace).
    If no feedback is returned, GEPA will use a simple text feedback consisting of just the score:
    f"This trajectory got a score of {score}."
    """
    ...
```

--------------------------------

### Learn Library from Documentation URLs

Source: https://dspy.ai/tutorials/sample_code_generation

This function takes a library name and a list of documentation URLs to learn about the library. It prints the analysis results including sources, core concepts, patterns, methods, installation, and code examples. It handles potential errors during the learning process.

```python
def learn_library_from_urls(library_name: str, documentation_urls: list[str]) -> Dict:
    """Learn about any library from its documentation URLs."""

    try:
        library_info = agent.learn_from_urls(library_name, documentation_urls)

        print(f"\n🔍 Library Analysis Results for {library_name}:")
        print(f"Sources: {len(library_info['source_urls'])} successful fetches")
        print(f"Core Concepts: {library_info['core_concepts']}")
        print(f"Common Patterns: {library_info['patterns']}")
        print(f"Key Methods: {library_info['methods']}")
        print(f"Installation: {library_info['installation']}")
        print(f"Found {len(library_info['examples'])} code examples")

        return library_info

    except Exception as e:
        print(f"❌ Error learning library: {e}")
        raise

# Example 1: Learn FastAPI from official documentation
fastapi_urls = [
    "https://fastapi.tiangolo.com/",
    "https://fastapi.tiangolo.com/tutorial/first-steps/",
    "https://fastapi.tiangolo.com/tutorial/path-params/",
    "https://fastapi.tiangolo.com/tutorial/query-params/"
]

print("🚀 Learning FastAPI from official documentation...")
fastapi_info = learn_library_from_urls("FastAPI", fastapi_urls)

# Example 2: Learn a different library (you can replace with any library)
streamlit_urls = [
    "https://docs.streamlit.io/",
    "https://docs.streamlit.io/get-started",
    "https://docs.streamlit.io/develop/api-reference"
]

print("\n\n📊 Learning Streamlit from official documentation...")
streamlit_info = learn_library_from_urls("Streamlit", streamlit_urls)
```

--------------------------------

### Initialize Student and Teacher LMs

Source: https://dspy.ai/tutorials/classification_finetuning

Sets up a local Llama-3.2-1B-Instruct model as the student and GPT-4o-mini as the teacher LM. Ensure local models are configured correctly.

```python
from dspy.clients.lm_local import LocalProvider

student_lm_name = "meta-llama/Llama-3.2-1B-Instruct"
student_lm = dspy.LM(model=f"openai/local:{student_lm_name}", provider=LocalProvider(), max_tokens=2000)
teacher_lm = dspy.LM('openai/gpt-4o-mini', max_tokens=3000)
```

--------------------------------

### Configure Finetuning Environment (Optional)

Source: https://dspy.ai/tutorials/classification_finetuning

Optional configuration for bootstrapped finetuning. Set environment variables to control the directory for checkpoints and fine-tuning data, and specify the GPU to use.

```python
# Optional:
# [1] You can set `DSPY_FINETUNEDIR` environment variable to control where the directory that will be used to store the
#     checkpoints and fine-tuning data. If this is not set, `DSPY_CACHEDIR` is used by default.
# [2] You can set the `CUDA_VISIBLE_DEVICES` environment variable to control the GPU that will be used for fine-tuning
#     and inference. If this is not set and the default GPU that's used by HuggingFace's `transformers` library is
#     occupied, an OutOfMemoryError might be raised.
#
# import os
# os.environ["CUDA_VISIBLE_DEVICES"] = "0"
# os.environ["DSPY_FINETUNEDIR"] = "/path/to/dir"
```

--------------------------------

### Install MLflow

Source: https://dspy.ai/tutorials/custom_module

Install MLflow, an LLMOps tool that integrates with DSPy for experiment tracking and explainability. Ensure you install version 3.0.0 or higher.

```bash
%pip install mlflow>=3.0.0

```

--------------------------------

### Initializing BetterTogether with Default Optimizers

Source: https://dspy.ai/api/optimizers/BetterTogether

Shows how to initialize BetterTogether using its default optimizers by only providing the required metric.

```python
optimizer = BetterTogether(metric=metric)
```

--------------------------------

### Create DSPy Examples from DataFrame

Source: https://dspy.ai/deep-dive/data-handling/loading-custom-data

Iterates through a Pandas DataFrame and creates a list of DSPy `Example` objects. Each example is configured with specific input keys.

```python
import dspy

dataset = []

for context, question, answer in df.values:
    dataset.append(dspy.Example(context=context, question=question, answer=answer).with_inputs("context", "question"))

print(dataset[:3])
```

--------------------------------

### Code Generation Summary and Example 1

Source: https://dspy.ai/tutorials/sample_code_generation

Displays the summary of generated examples for FastAPI and the beginning of the first generated example: 'Create a REST API with authentication'.

```text
📝 Generating example 1/3: Create a REST API with authentication

✅ Successfully learned FastAPI!

📊 Learning Summary for FastAPI:
   • Core concepts: 4 identified
   • Common patterns: 3 found
   • Examples generated: 3

👀 Do you want to see the generated examples for FastAPI? (y/n): y

──────────────────────────────────────────────────
📝 Example 1: Create a REST API with authentication
──────────────────────────────────────────────────

💻 Generated Code:

```

--------------------------------

### Serve FastAPI Application

Source: https://dspy.ai/tutorials/deployment

Starts a local development server for the FastAPI application.

```bash
> uvicorn fastapi_dspy:app --reload

```

--------------------------------

### Iterate Over DSPy Example Items

Source: https://dspy.ai/deep-dive/data-handling/examples

Demonstrates iterating over the key-value pairs of a DSPy Example object, similar to a Python dictionary. This is useful for processing all fields within an example.

```python
for k, v in article_summary.items():
    print(f"{k} = {v}")
```

--------------------------------

### Initializing BetterTogether with Custom Optimizers

Source: https://dspy.ai/api/optimizers/BetterTogether

Demonstrates initializing BetterTogether with custom optimizers, GEPA and BootstrapFinetune, assigned to specific names ('p' and 'w') for use in strategy strings.

```python
from dspy.teleprompt import GEPA, BootstrapFinetune
optimizer = BetterTogether(
    metric=metric,
    p=GEPA(metric=metric, auto="medium"),
    w=BootstrapFinetune(metric=metric)
)
```

--------------------------------

### Install Control Arena and Dependencies

Source: https://dspy.ai/tutorials/gepa_trusted_monitor

Installs the necessary Python packages for the tutorial, including control-arena, inspect-ai, plotly, kaleido, and nbformat.

```bash
!pip install -q control-arena==8.0.0 inspect-ai==0.3.137 plotly kaleido nbformat

```