Skip to content

Building AI agents, atomically

Refactor DSPy example

KennyVaneetveldee902aca3bdc4
diff --git a/atomic-examples/dspy-integration/dspy_integration/__init__.py b/atomic-examples/dspy-integration/dspy_integration/__init__.py
index 2381e4a..01b078b 100644
--- a/atomic-examples/dspy-integration/dspy_integration/__init__.py
+++ b/atomic-examples/dspy-integration/dspy_integration/__init__.py
@@ -1,20 +1,50 @@
"""
-DSPy + Atomic Agents Integration
+DSPy + Atomic Agents Integration Package.
-This module provides a seamless integration between DSPy's declarative prompt optimization
-framework and Atomic Agents' type-safe structured output system.
+This package demonstrates how to combine DSPy's automatic prompt optimization
+with Atomic Agents' type-safe structured outputs.
-Key Components:
-- DSPyAtomicModule: A DSPy module that wraps Atomic Agents for structured outputs
-- AtomicSignature: Bridge between Pydantic schemas and DSPy signatures
-- Optimization utilities for improving agent performance with few-shot learning
+Package Structure:
+ domain/ - Core business logic (models, datasets, evaluation)
+ stages/ - Demonstration stages (dspy, atomic, combined)
+ presentation/ - UI layer (Rich console output)
+ bridge.py - DSPy ↔ Atomic Agents integration module
+
+Quick Start:
+ >>> from dspy_integration import DSPyAtomicModule, MovieReviewInput, MovieGenreOutput
+ >>> module = DSPyAtomicModule(
+ ... input_schema=MovieReviewInput,
+ ... output_schema=MovieGenreOutput,
+ ... use_chain_of_thought=True,
+ ... )
+ >>> result = module.run_validated(review="Amazing action movie!")
+ >>> print(result.genre) # Type-safe output!
+
+Run Demo:
+ uv run python -m dspy_integration.main
"""
+# Domain exports
+from dspy_integration.domain.models import (
+ GENRES,
+ GenreType,
+ MovieGenreOutput,
+ MovieReviewInput,
+ EvalResult,
+)
+from dspy_integration.domain.datasets import TRAINING_DATASET, TEST_DATASET
+from dspy_integration.domain.evaluation import evaluate_predictions
+
+# Bridge exports
from dspy_integration.bridge import (
DSPyAtomicModule,
- pydantic_to_dspy_fields,
+ DSPyAtomicPipeline,
+ create_dspy_example,
create_dspy_signature_from_schemas,
+ pydantic_to_dspy_fields,
)
+
+# Original schemas (for backwards compatibility)
from dspy_integration.schemas import (
SentimentInputSchema,
SentimentOutputSchema,
@@ -24,14 +54,47 @@ from dspy_integration.schemas import (
SummaryOutputSchema,
)
+# Stage exports (for advanced usage)
+from dspy_integration.stages import (
+ run_stage1_raw_dspy,
+ run_stage2_raw_atomic_agents,
+ run_stage3_combined,
+)
+
+__version__ = "0.1.0"
+
__all__ = [
+ # Version
+ "__version__",
+ # Domain - Types
+ "GENRES",
+ "GenreType",
+ # Domain - Schemas (new)
+ "MovieGenreOutput",
+ "MovieReviewInput",
+ # Domain - Data structures
+ "EvalResult",
+ # Domain - Datasets
+ "TRAINING_DATASET",
+ "TEST_DATASET",
+ # Domain - Evaluation
+ "evaluate_predictions",
+ # Bridge - Core classes
"DSPyAtomicModule",
- "pydantic_to_dspy_fields",
+ "DSPyAtomicPipeline",
+ # Bridge - Utilities
+ "create_dspy_example",
"create_dspy_signature_from_schemas",
+ "pydantic_to_dspy_fields",
+ # Original schemas (backwards compatibility)
"SentimentInputSchema",
"SentimentOutputSchema",
"QuestionInputSchema",
"AnswerOutputSchema",
"SummaryInputSchema",
"SummaryOutputSchema",
+ # Stages - Runners
+ "run_stage1_raw_dspy",
+ "run_stage2_raw_atomic_agents",
+ "run_stage3_combined",
]
diff --git a/atomic-examples/dspy-integration/dspy_integration/bridge.py b/atomic-examples/dspy-integration/dspy_integration/bridge.py
index fb83af9..0737a71 100644
--- a/atomic-examples/dspy-integration/dspy_integration/bridge.py
+++ b/atomic-examples/dspy-integration/dspy_integration/bridge.py
@@ -7,10 +7,11 @@ This module provides the core integration that allows:
3. Applying DSPy optimizers (BootstrapFewShot, MIPROv2, etc.) to improve agent performance
"""
-from typing import Type, Dict, Any, Optional, List, get_type_hints, get_origin, get_args, Literal
+from typing import Any, Dict, List, Literal, Optional, Type, get_args, get_origin
+
import dspy
-from pydantic import BaseModel, Field
-from pydantic.fields import FieldInfo
+from pydantic import BaseModel
+
from atomic_agents.base.base_io_schema import BaseIOSchema
@@ -38,11 +39,11 @@ def python_type_to_dspy_type(python_type: Any) -> Any:
return list
# Handle Optional types
- if origin is type(None) or (hasattr(origin, '__origin__') and origin.__origin__ is type(None)):
+ if origin is type(None) or (hasattr(origin, "__origin__") and origin.__origin__ is type(None)):
return python_type
# Handle Union types (including Optional)
- if hasattr(origin, '__name__') and origin.__name__ == 'UnionType':
+ if hasattr(origin, "__name__") and origin.__name__ == "UnionType":
args = get_args(python_type)
# Filter out NoneType for Optional handling
non_none_args = [a for a in args if a is not type(None)]
@@ -58,8 +59,7 @@ def python_type_to_dspy_type(python_type: Any) -> Any:
def pydantic_to_dspy_fields(
- schema: Type[BaseModel],
- field_type: str = "input"
+ schema: Type[BaseModel], field_type: str = "input"
) -> Dict[str, tuple]:
"""
Convert Pydantic schema fields to DSPy field definitions.
@@ -184,9 +184,7 @@ class DSPyAtomicModule(dspy.Module):
# Create DSPy signature from schemas
self.signature = create_dspy_signature_from_schemas(
- input_schema,
- output_schema,
- instructions
+ input_schema, output_schema, instructions
)
# Create the predictor
@@ -300,7 +298,7 @@ class DSPyAtomicPipeline(dspy.Module):
current_input = {
k: getattr(prediction, k)
for k in dir(prediction)
- if not k.startswith('_') and not callable(getattr(prediction, k))
+ if not k.startswith("_") and not callable(getattr(prediction, k))
}
return results
@@ -336,10 +334,7 @@ def create_dspy_example(
**validated_output.model_dump(),
}
- # Create DSPy example with output fields marked
- output_keys = list(output_schema.model_fields.keys())
- example = dspy.Example(**example_data).with_inputs(
- *list(input_schema.model_fields.keys())
- )
+ # Create DSPy example with input fields marked
+ example = dspy.Example(**example_data).with_inputs(*list(input_schema.model_fields.keys()))
return example
diff --git a/atomic-examples/dspy-integration/dspy_integration/domain/__init__.py b/atomic-examples/dspy-integration/dspy_integration/domain/__init__.py
new file mode 100644
index 0000000..bdbe116
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/domain/__init__.py
@@ -0,0 +1,37 @@
+"""
+Domain layer for DSPy + Atomic Agents integration.
+
+This package contains:
+- models: Pydantic schemas and data transfer objects
+- datasets: Training and test data
+- evaluation: Metrics and evaluation utilities
+
+Following Clean Architecture principles, this layer has no dependencies
+on external frameworks (except Pydantic for data modeling).
+"""
+
+from dspy_integration.domain.models import (
+ GenreType,
+ GENRES,
+ MovieGenreOutput,
+ MovieReviewInput,
+ EvalResult,
+)
+from dspy_integration.domain.datasets import TRAINING_DATASET, TEST_DATASET
+from dspy_integration.domain.evaluation import evaluate_predictions
+
+__all__ = [
+ # Types
+ "GenreType",
+ "GENRES",
+ # Schemas
+ "MovieGenreOutput",
+ "MovieReviewInput",
+ # Data structures
+ "EvalResult",
+ # Datasets
+ "TRAINING_DATASET",
+ "TEST_DATASET",
+ # Evaluation
+ "evaluate_predictions",
+]
diff --git a/atomic-examples/dspy-integration/dspy_integration/domain/datasets.py b/atomic-examples/dspy-integration/dspy_integration/domain/datasets.py
new file mode 100644
index 0000000..5cf9af4
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/domain/datasets.py
@@ -0,0 +1,460 @@
+"""
+Datasets for movie genre classification benchmark.
+
+This module contains the training and test datasets used to demonstrate
+the differences between DSPy, Atomic Agents, and the combined approach.
+
+Dataset Design:
+- Training: 60 examples balanced across 6 genres (10 each)
+- Test: 30 challenging examples testing edge cases
+
+The test set is intentionally difficult, including:
+- Sarcasm and irony
+- Multi-genre signals (primary genre detection)
+- Misleading genre keywords
+- Subverted expectations
+- Subtle/ambiguous signals
+- Cultural references
+"""
+
+from typing import List, TypedDict
+
+
+class MovieExample(TypedDict):
+ """Type definition for a movie review example."""
+
+ review: str
+ genre: str
+
+
+# =============================================================================
+# TRAINING DATASET (60 examples, 10 per genre)
+# =============================================================================
+
+_ACTION_EXAMPLES: List[MovieExample] = [
+ {
+ "review": "Non-stop car chases and explosions! The hero single-handedly took down an army.",
+ "genre": "action",
+ },
+ {
+ "review": "Martial arts sequences were incredible. The final fight scene was epic!",
+ "genre": "action",
+ },
+ {
+ "review": "She trained for 10 years to avenge her family. The fight choreography was poetry in motion.",
+ "genre": "action",
+ },
+ {
+ "review": "Bullets flying, buildings exploding, and our hero diving through glass windows. Peak adrenaline.",
+ "genre": "action",
+ },
+ {
+ "review": "The heist sequence had me on the edge of my seat. Tension and gunfights galore.",
+ "genre": "action",
+ },
+ {
+ "review": "Wow, another chosen one saving the world with a magic sword. Groundbreaking. Still epic though.",
+ "genre": "action",
+ },
+ {
+ "review": "This action film broke my heart. The hero's best friend didn't make it.",
+ "genre": "action",
+ },
+ {
+ "review": "High-octane from start to finish. The stunt work deserves every award.",
+ "genre": "action",
+ },
+ {
+ "review": "A revenge thriller with some of the best choreographed fights I've ever seen.",
+ "genre": "action",
+ },
+ {
+ "review": "Explosions, car chases, and a hero who refuses to give up. Classic action fare done right.",
+ "genre": "action",
+ },
+]
+
+_COMEDY_EXAMPLES: List[MovieExample] = [
+ {
+ "review": "I couldn't stop laughing! The jokes were hilarious and the timing was perfect.",
+ "genre": "comedy",
+ },
+ {
+ "review": "Witty dialogue and absurd situations had the whole theater in stitches.",
+ "genre": "comedy",
+ },
+ {
+ "review": "The jokes were so bad they were good. I hate that I loved this stupid movie.",
+ "genre": "comedy",
+ },
+ {
+ "review": "I cried watching this comedy because I related too much to the sad clown.",
+ "genre": "comedy",
+ },
+ {
+ "review": "A romantic comedy set during a zombie apocalypse. The jokes land even when heads don't.",
+ "genre": "comedy",
+ },
+ {
+ "review": "Slapstick humor meets clever wordplay. My cheeks hurt from laughing.",
+ "genre": "comedy",
+ },
+ {
+ "review": "The funniest movie I've seen all year. Every scene had at least one great gag.",
+ "genre": "comedy",
+ },
+ {
+ "review": "Dark comedy at its finest - you'll feel guilty for laughing but won't be able to stop.",
+ "genre": "comedy",
+ },
+ {
+ "review": "The comedic timing of the leads is impeccable. Chemistry-driven hilarity.",
+ "genre": "comedy",
+ },
+ {
+ "review": "Satirical genius. It skewers modern society while making you snort-laugh.",
+ "genre": "comedy",
+ },
+]
+
+_DRAMA_EXAMPLES: List[MovieExample] = [
+ {
+ "review": "A heart-wrenching story of loss and redemption. I cried for hours.",
+ "genre": "drama",
+ },
+ {
+ "review": "A slow burn exploration of grief and family dysfunction. Beautifully acted.",
+ "genre": "drama",
+ },
+ {
+ "review": "Yes there's a spaceship, but this is really about the captain dealing with his father's death.",
+ "genre": "drama",
+ },
+ {
+ "review": "It's set in space but it's really a courtroom drama about intergalactic law.",
+ "genre": "drama",
+ },
+ {
+ "review": "The performances were raw and honest. A meditation on what it means to be human.",
+ "genre": "drama",
+ },
+ {
+ "review": "Devastating. The final scene left me emotionally wrecked for days.",
+ "genre": "drama",
+ },
+ {
+ "review": "A character study that unfolds like a novel. Patient storytelling at its best.",
+ "genre": "drama",
+ },
+ {
+ "review": "The immigrant experience portrayed with such authenticity and grace.",
+ "genre": "drama",
+ },
+ {
+ "review": "Three generations of trauma, finally addressed. Cathartic and powerful.",
+ "genre": "drama",
+ },
+ {
+ "review": "Oscar-worthy performances in a story about ordinary people facing extraordinary circumstances.",
+ "genre": "drama",
+ },
+]
+
+_HORROR_EXAMPLES: List[MovieExample] = [
+ {
+ "review": "Terrifying! I slept with the lights on for a week after watching this.",
+ "genre": "horror",
+ },
+ {
+ "review": "Jump scares galore! The monster design was genuinely creepy.",
+ "genre": "horror",
+ },
+ {
+ "review": "Zombies attack! But the real horror is the breakdown of society and trust.",
+ "genre": "horror",
+ },
+ {
+ "review": "The horror movie made me laugh - those deaths were so creative!",
+ "genre": "horror",
+ },
+ {
+ "review": "Psychological terror that gets under your skin. No cheap scares, just dread.",
+ "genre": "horror",
+ },
+ {
+ "review": "The creature was nightmare fuel. I'm still seeing it when I close my eyes.",
+ "genre": "horror",
+ },
+ {
+ "review": "A haunted house movie that actually delivers. Genuinely unsettling atmosphere.",
+ "genre": "horror",
+ },
+ {
+ "review": "Gore-fest with a surprising amount of social commentary. Brutal and smart.",
+ "genre": "horror",
+ },
+ {
+ "review": "The slow build of dread was masterful. When it finally hit, I screamed.",
+ "genre": "horror",
+ },
+ {
+ "review": "Found footage done right. I had to keep reminding myself it wasn't real.",
+ "genre": "horror",
+ },
+]
+
+_SCIFI_EXAMPLES: List[MovieExample] = [
+ {
+ "review": "Set in 2150, the space battles and alien technology were mind-blowing.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "Time travel paradoxes and quantum physics made this a thinker.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "The robot fell in love with a human. Surprisingly touching for a sci-fi.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "The sci-fi premise was just an excuse for philosophical debates. Loved every second.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "Cyberpunk aesthetic meets thought-provoking questions about consciousness.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "The worldbuilding is incredible. Every detail of this future feels plausible.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "First contact done differently. The aliens were truly alien, not just humans with makeup.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "Hard sci-fi that doesn't dumb down the science. Refreshingly intelligent.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "Dystopian future that feels uncomfortably close to our present. Chilling and prescient.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "Space exploration with a philosophical bent. What does it mean to be alone in the universe?",
+ "genre": "sci-fi",
+ },
+]
+
+_ROMANCE_EXAMPLES: List[MovieExample] = [
+ {
+ "review": "The chemistry between the leads was electric. A beautiful love story.",
+ "genre": "romance",
+ },
+ {
+ "review": "Swoon-worthy moments and a happily ever after. Pure romantic bliss.",
+ "genre": "romance",
+ },
+ {
+ "review": "They met during an alien invasion. The world was ending but love found a way.",
+ "genre": "romance",
+ },
+ {
+ "review": "Enemies to lovers done perfectly. The tension was delicious.",
+ "genre": "romance",
+ },
+ {
+ "review": "A sweeping love story across decades. Their connection transcended time.",
+ "genre": "romance",
+ },
+ {
+ "review": "Second chance romance that made me believe in love again. Tissues required.",
+ "genre": "romance",
+ },
+ {
+ "review": "The slow burn was worth the wait. When they finally kissed, I cheered.",
+ "genre": "romance",
+ },
+ {
+ "review": "A meet-cute for the ages. Charming leads and witty banter throughout.",
+ "genre": "romance",
+ },
+ {
+ "review": "Forbidden love with actual stakes. Their sacrifice at the end broke me.",
+ "genre": "romance",
+ },
+ {
+ "review": "Holiday romance that's predictable but perfectly executed. Feel-good viewing.",
+ "genre": "romance",
+ },
+]
+
+
+# Combine all training examples
+TRAINING_DATASET: List[MovieExample] = (
+ _ACTION_EXAMPLES
+ + _COMEDY_EXAMPLES
+ + _DRAMA_EXAMPLES
+ + _HORROR_EXAMPLES
+ + _SCIFI_EXAMPLES
+ + _ROMANCE_EXAMPLES
+)
+
+
+# =============================================================================
+# TEST DATASET (30 challenging examples)
+# =============================================================================
+
+# Sarcasm & Irony (5 examples)
+_SARCASM_TESTS: List[MovieExample] = [
+ {
+ "review": "Oh great, another movie where the hero walks away from explosions in slow motion. How original. Still watched it twice though.",
+ "genre": "action",
+ },
+ {
+ "review": "Groundbreaking stuff: man punches bad guys, gets the girl, saves the day. Revolutionary cinema. Loved every predictable second.",
+ "genre": "action",
+ },
+ {
+ "review": "I laughed so hard I cried. Then I just cried. Then I laughed again. What even was this movie?",
+ "genre": "comedy",
+ },
+ {
+ "review": "Wow, they really subverted my expectations by doing exactly what I expected. The jokes were so obvious they circled back to funny.",
+ "genre": "comedy",
+ },
+ {
+ "review": "Another 'scary' movie where the characters make terrible decisions. At least the kills were creative. Actually terrifying creature design though.",
+ "genre": "horror",
+ },
+]
+
+# Multi-Genre / Primary Genre Detection (6 examples)
+_MULTIGENRE_TESTS: List[MovieExample] = [
+ {
+ "review": "The robot's sacrifice to save humanity made me sob uncontrollably. Beautiful storytelling set against a dystopian future.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "A serial killer falls in love with his next victim, but she's also a serial killer. Bloody and romantic.",
+ "genre": "horror",
+ },
+ {
+ "review": "Two detectives solve crimes while slowly falling for each other. The mystery was okay but I shipped them so hard.",
+ "genre": "romance",
+ },
+ {
+ "review": "It's technically a war movie but really it's about two soldiers finding love in the trenches. The battle scenes support the love story.",
+ "genre": "romance",
+ },
+ {
+ "review": "Space opera with a love triangle at its core. The laser battles are cool but I'm here for the drama between the three leads.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "Post-apocalyptic survival with a found family. The zombies are almost secondary to the human connections.",
+ "genre": "drama",
+ },
+]
+
+# Misleading Genre Signals (5 examples)
+_MISLEADING_TESTS: List[MovieExample] = [
+ {
+ "review": "My heart was RACING the entire time! The courtroom scenes were absolutely EXPLOSIVE! Justice was served!",
+ "genre": "drama",
+ },
+ {
+ "review": "The alien invasion was just a backdrop for the family reconciliation story. Dad finally said he was proud.",
+ "genre": "drama",
+ },
+ {
+ "review": "Terrifyingly funny. The ghost just wanted to do stand-up comedy but kept accidentally scaring people.",
+ "genre": "comedy",
+ },
+ {
+ "review": "Action-packed emotional journey! By action I mean arguments, and by packed I mean I cried the whole time.",
+ "genre": "drama",
+ },
+ {
+ "review": "A thriller where the biggest twist was how much I ended up caring about these characters' relationships.",
+ "genre": "romance",
+ },
+]
+
+# Subverted Expectations (5 examples)
+_SUBVERTED_TESTS: List[MovieExample] = [
+ {
+ "review": "Everyone dies at the end. Like, EVERYONE. But somehow it was the most romantic film I've ever seen.",
+ "genre": "romance",
+ },
+ {
+ "review": "The monster wasn't scary at all - it just wanted friends. I cried when they finally accepted it.",
+ "genre": "drama",
+ },
+ {
+ "review": "Started as a slasher, ended as a meditation on trauma and healing. The horror serves the character development.",
+ "genre": "horror",
+ },
+ {
+ "review": "What seemed like a rom-com setup became a profound exploration of self-love and independence. She didn't need him after all.",
+ "genre": "drama",
+ },
+ {
+ "review": "The funniest parts were unintentional. This action movie's dialogue is so bad it's become a comedy classic in my friend group.",
+ "genre": "action",
+ },
+]
+
+# Subtle / Ambiguous (5 examples)
+_SUBTLE_TESTS: List[MovieExample] = [
+ {
+ "review": "Set in 2087, but really it's about loneliness. The AI companion understood him better than any human ever did.",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "Quiet film about two people sharing a meal. Nothing happens and everything happens. Deeply moving.",
+ "genre": "drama",
+ },
+ {
+ "review": "The laughs come from pain, the pain comes from truth. A comedy that understands sadness intimately.",
+ "genre": "comedy",
+ },
+ {
+ "review": "Is it a horror movie if the monster is capitalism? Genuinely unsettling corporate satire.",
+ "genre": "horror",
+ },
+ {
+ "review": "They never say 'I love you' but every frame screams it. Visual storytelling at its most romantic.",
+ "genre": "romance",
+ },
+]
+
+# Cultural Context / Specific References (4 examples)
+_CULTURAL_TESTS: List[MovieExample] = [
+ {
+ "review": "John Wick energy but make it about a retired chef defending his restaurant. Knife fights choreographed like ballet.",
+ "genre": "action",
+ },
+ {
+ "review": "Hereditary meets Little Miss Sunshine. Family dysfunction with supernatural undertones played for dark laughs.",
+ "genre": "comedy",
+ },
+ {
+ "review": "Blade Runner questions wrapped in a Her-style relationship. What is real, and does it matter?",
+ "genre": "sci-fi",
+ },
+ {
+ "review": "Pride and Prejudice but in space. The Darcy character is an alien prince and it absolutely works.",
+ "genre": "romance",
+ },
+]
+
+# Combine all test examples
+TEST_DATASET: List[MovieExample] = (
+ _SARCASM_TESTS
+ + _MULTIGENRE_TESTS
+ + _MISLEADING_TESTS
+ + _SUBVERTED_TESTS
+ + _SUBTLE_TESTS
+ + _CULTURAL_TESTS
+)
diff --git a/atomic-examples/dspy-integration/dspy_integration/domain/evaluation.py b/atomic-examples/dspy-integration/dspy_integration/domain/evaluation.py
new file mode 100644
index 0000000..4985dc9
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/domain/evaluation.py
@@ -0,0 +1,76 @@
+"""
+Evaluation utilities for comparing classification approaches.
+
+This module provides pure functions for evaluating model predictions.
+No side effects, no I/O - just computation.
+
+Design Principles:
+- Pure functions with no side effects
+- Clear input/output contracts
+- Single responsibility (evaluation only)
+"""
+
+from typing import Any, Dict, List
+
+from dspy_integration.domain.models import EvalResult
+
+
+def evaluate_predictions(
+ predictions: List[Dict[str, Any]],
+ test_set: List[Dict[str, str]],
+) -> EvalResult:
+ """
+ Calculate accuracy and gather evaluation statistics.
+
+ Args:
+ predictions: List of prediction dictionaries with 'genre', 'confidence', 'reasoning'
+ test_set: List of ground truth examples with 'review' and 'genre'
+
+ Returns:
+ EvalResult containing accuracy metrics and detailed prediction results
+
+ Example:
+ >>> predictions = [{"genre": "action", "confidence": 0.9, "reasoning": "..."}]
+ >>> test_set = [{"review": "...", "genre": "action"}]
+ >>> result = evaluate_predictions(predictions, test_set)
+ >>> print(f"Accuracy: {result.accuracy:.1%}")
+ """
+ correct = 0
+ results = []
+
+ for pred, truth in zip(predictions, test_set):
+ predicted_genre = pred.get("genre", "").lower()
+ expected_genre = truth["genre"].lower()
+ is_correct = predicted_genre == expected_genre
+
+ if is_correct:
+ correct += 1
+
+ results.append(
+ {
+ "review": _truncate(truth["review"], max_length=50),
+ "expected": truth["genre"],
+ "predicted": pred.get("genre", "ERROR"),
+ "correct": is_correct,
+ "confidence": pred.get("confidence", 0),
+ "reasoning": _truncate(pred.get("reasoning", "N/A"), max_length=60),
+ }
+ )
+
+ total = len(test_set)
+ accuracy = correct / total if total > 0 else 0.0
+
+ return EvalResult(
+ correct=correct,
+ total=total,
+ accuracy=accuracy,
+ predictions=results,
+ avg_time=0.0, # To be set by caller
+ )
+
+
+def _truncate(text: str, max_length: int) -> str:
+ """Truncate text with ellipsis if longer than max_length."""
+ if len(text) <= max_length:
+ return text
+ return text[: max_length - 3] + "..."
diff --git a/atomic-examples/dspy-integration/dspy_integration/domain/models.py b/atomic-examples/dspy-integration/dspy_integration/domain/models.py
new file mode 100644
index 0000000..c4cb775
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/domain/models.py
@@ -0,0 +1,95 @@
+"""
+Domain models for movie genre classification.
+
+This module defines the core data structures used throughout the application.
+All models are framework-agnostic and can be used with both DSPy and Atomic Agents.
+
+Design Principles:
+- Single Responsibility: Each class has one reason to change
+- Open/Closed: Extend via inheritance, don't modify
+- Dependency Inversion: Depend on abstractions (Pydantic BaseModel)
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Literal
+
+from pydantic import Field
+
+from atomic_agents.base.base_io_schema import BaseIOSchema
+
+
+# =============================================================================
+# TYPE DEFINITIONS
+# =============================================================================
+
+GENRES: List[str] = ["action", "comedy", "drama", "horror", "sci-fi", "romance"]
+"""Valid genre categories for movie classification."""
+
+GenreType = Literal["action", "comedy", "drama", "horror", "sci-fi", "romance"]
+"""Type alias constraining genre values to valid options."""
+
+
+# =============================================================================
+# INPUT/OUTPUT SCHEMAS
+# =============================================================================
+
+
+class MovieReviewInput(BaseIOSchema):
+ """
+ Input schema for movie review classification.
+
+ This schema validates and documents the expected input format.
+ Using Pydantic ensures type safety at runtime.
+ """
+
+ review: str = Field(
+ ...,
+ description="The movie review text to classify.",
+ )
+
+
+class MovieGenreOutput(BaseIOSchema):
+ """
+ Output schema for movie genre classification with structured results.
+
+ This schema guarantees:
+ - genre is one of 6 valid options (via Literal type)
+ - confidence is between 0.0 and 1.0 (via ge/le constraints)
+ - reasoning is always provided
+ """
+
+ genre: GenreType = Field(
+ ...,
+ description="The primary genre of the movie based on the review.",
+ )
+ confidence: float = Field(
+ ...,
+ description="Confidence score between 0.0 and 1.0",
+ ge=0.0,
+ le=1.0,
+ )
+ reasoning: str = Field(
+ ...,
+ description="Brief explanation for why this genre was chosen.",
+ )
+
+
+# =============================================================================
+# EVALUATION DATA STRUCTURES
+# =============================================================================
+
+
+@dataclass
+class EvalResult:
+ """
+ Stores evaluation results for comparison across approaches.
+
+ This is a simple data class - no behavior, just data.
+ Following the principle of separating data from behavior.
+ """
+
+ correct: int
+ total: int
+ accuracy: float
+ predictions: List[Dict[str, Any]]
+ avg_time: float
diff --git a/atomic-examples/dspy-integration/dspy_integration/main.py b/atomic-examples/dspy-integration/dspy_integration/main.py
index 3ea4b47..83aae82 100644
--- a/atomic-examples/dspy-integration/dspy_integration/main.py
+++ b/atomic-examples/dspy-integration/dspy_integration/main.py
@@ -1,1168 +1,159 @@
"""
-DSPy + Atomic Agents Integration: A Comprehensive Didactic Example
+DSPy + Atomic Agents Integration: A Comprehensive Didactic Example.
This example teaches you WHY combining DSPy with Atomic Agents is powerful
-by walking through three stages with a large, challenging benchmark:
+by walking through three stages with a large, challenging benchmark.
+Architecture Overview:
┌─────────────────────────────────────────────────────────────────────────────┐
-│ STAGE 1: Raw DSPy (Properly Implemented with Typed Signatures) │
-│ ✓ Automatic prompt optimization │
-│ ✓ Typed signatures with Literal constraints │
-│ ✗ No Pydantic validation ecosystem │
-│ ✗ Limited integration with structured output tools │
+│ main.py (Orchestrator) │
+│ - Entry point, coordinates all stages │
├─────────────────────────────────────────────────────────────────────────────┤
-│ STAGE 2: Raw Atomic Agents │
-│ ✓ Type-safe structured outputs (Pydantic) │
-│ ✓ Guaranteed schema compliance │
-│ ✗ Manual prompt engineering - guesswork │
-│ ✗ No systematic way to improve │
+│ stages/ │ domain/ │
+│ ├── stage1_dspy.py │ ├── models.py (schemas, types) │
+│ ├── stage2_atomic.py │ ├── datasets.py (train/test data) │
+│ └── stage3_combined.py │ └── evaluation.py (metrics) │
├─────────────────────────────────────────────────────────────────────────────┤
-│ STAGE 3: DSPy + Atomic Agents (The Best of Both) │
-│ ✓ Automatic prompt optimization │
-│ ✓ Type-safe structured outputs │
-│ ✓ Measurable, reproducible improvements │
-│ ✓ Full Pydantic ecosystem integration │
+│ presentation/ │ bridge.py │
+│ └── console.py (Rich UI) │ (DSPy ↔ Atomic Agents) │
└─────────────────────────────────────────────────────────────────────────────┘
Run: uv run python -m dspy_integration.main
+
+Clean Architecture Principles Applied:
+- Separation of Concerns: Each module has a single responsibility
+- Dependency Inversion: High-level modules don't depend on low-level details
+- Single Responsibility: Each function/class has one reason to change
+- Open/Closed: Easy to extend (add new stages) without modifying existing code
"""
import os
-import json
-import time
import random
-from typing import List, Literal, Optional, Dict, Any
-from dataclasses import dataclass
-from dotenv import load_dotenv
+import traceback
-import dspy
-import instructor
-import openai
-from pydantic import Field
-from rich.console import Console
-from rich.panel import Panel
-from rich.table import Table
-from rich.syntax import Syntax
-from rich.progress import Progress, SpinnerColumn, TextColumn
-from rich.columns import Columns
-from rich.text import Text
-from rich.rule import Rule
-from rich.tree import Tree
-from rich import box
+from dotenv import load_dotenv
-from atomic_agents.base.base_io_schema import BaseIOSchema
-from atomic_agents.agents.atomic_agent import AtomicAgent, AgentConfig
-from atomic_agents.context.system_prompt_generator import SystemPromptGenerator
+from dspy_integration.domain.models import EvalResult
+from dspy_integration.domain.datasets import TRAINING_DATASET, TEST_DATASET
+from dspy_integration.stages import (
+ run_stage1_raw_dspy,
+ run_stage2_raw_atomic_agents,
+ run_stage3_combined,
+)
+from dspy_integration.presentation.console import (
+ console,
+ display_welcome,
+ display_comparison_table,
+ display_takeaways,
+ display_decision_guide,
+ display_stage_header,
+)
+# Load environment variables
load_dotenv()
-console = Console()
# Set random seed for reproducibility
random.seed(42)
-# ============================================================================
-# THE TASK: Movie Review Classification
-# ============================================================================
-# We'll classify movie reviews into genres based on the review text.
-# This is intentionally tricky - reviews often mention multiple genres,
-# use sarcasm, or have ambiguous language.
-#
-# LARGE BENCHMARK: 60 training examples, 30 test examples
-# ============================================================================
-
-GENRES = ["action", "comedy", "drama", "horror", "sci-fi", "romance"]
-GenreType = Literal["action", "comedy", "drama", "horror", "sci-fi", "romance"]
-
-# ============================================================================
-# TRAINING DATASET (60 examples)
-# ============================================================================
-# Mixed difficulty: clear examples for learning, nuanced examples for teaching
-DATASET = [
- # === ACTION (10 examples) ===
- {"review": "Non-stop car chases and explosions! The hero single-handedly took down an army.", "genre": "action"},
- {"review": "Martial arts sequences were incredible. The final fight scene was epic!", "genre": "action"},
- {"review": "She trained for 10 years to avenge her family. The fight choreography was poetry in motion.", "genre": "action"},
- {"review": "Bullets flying, buildings exploding, and our hero diving through glass windows. Peak adrenaline.", "genre": "action"},
- {"review": "The heist sequence had me on the edge of my seat. Tension and gunfights galore.", "genre": "action"},
- {"review": "Wow, another chosen one saving the world with a magic sword. Groundbreaking. Still epic though.", "genre": "action"},
- {"review": "This action film broke my heart. The hero's best friend didn't make it.", "genre": "action"},
- {"review": "High-octane from start to finish. The stunt work deserves every award.", "genre": "action"},
- {"review": "A revenge thriller with some of the best choreographed fights I've ever seen.", "genre": "action"},
- {"review": "Explosions, car chases, and a hero who refuses to give up. Classic action fare done right.", "genre": "action"},
-
- # === COMEDY (10 examples) ===
- {"review": "I couldn't stop laughing! The jokes were hilarious and the timing was perfect.", "genre": "comedy"},
- {"review": "Witty dialogue and absurd situations had the whole theater in stitches.", "genre": "comedy"},
- {"review": "The jokes were so bad they were good. I hate that I loved this stupid movie.", "genre": "comedy"},
- {"review": "I cried watching this comedy because I related too much to the sad clown.", "genre": "comedy"},
- {"review": "A romantic comedy set during a zombie apocalypse. The jokes land even when heads don't.", "genre": "comedy"},
- {"review": "Slapstick humor meets clever wordplay. My cheeks hurt from laughing.", "genre": "comedy"},
- {"review": "The funniest movie I've seen all year. Every scene had at least one great gag.", "genre": "comedy"},
- {"review": "Dark comedy at its finest - you'll feel guilty for laughing but won't be able to stop.", "genre": "comedy"},
- {"review": "The comedic timing of the leads is impeccable. Chemistry-driven hilarity.", "genre": "comedy"},
- {"review": "Satirical genius. It skewers modern society while making you snort-laugh.", "genre": "comedy"},
-
- # === DRAMA (10 examples) ===
- {"review": "A heart-wrenching story of loss and redemption. I cried for hours.", "genre": "drama"},
- {"review": "A slow burn exploration of grief and family dysfunction. Beautifully acted.", "genre": "drama"},
- {"review": "Yes there's a spaceship, but this is really about the captain dealing with his father's death.", "genre": "drama"},
- {"review": "It's set in space but it's really a courtroom drama about intergalactic law.", "genre": "drama"},
- {"review": "The performances were raw and honest. A meditation on what it means to be human.", "genre": "drama"},
- {"review": "Devastating. The final scene left me emotionally wrecked for days.", "genre": "drama"},
- {"review": "A character study that unfolds like a novel. Patient storytelling at its best.", "genre": "drama"},
- {"review": "The immigrant experience portrayed with such authenticity and grace.", "genre": "drama"},
- {"review": "Three generations of trauma, finally addressed. Cathartic and powerful.", "genre": "drama"},
- {"review": "Oscar-worthy performances in a story about ordinary people facing extraordinary circumstances.", "genre": "drama"},
-
- # === HORROR (10 examples) ===
- {"review": "Terrifying! I slept with the lights on for a week after watching this.", "genre": "horror"},
- {"review": "Jump scares galore! The monster design was genuinely creepy.", "genre": "horror"},
- {"review": "Zombies attack! But the real horror is the breakdown of society and trust.", "genre": "horror"},
- {"review": "The horror movie made me laugh - those deaths were so creative!", "genre": "horror"},
- {"review": "Psychological terror that gets under your skin. No cheap scares, just dread.", "genre": "horror"},
- {"review": "The creature was nightmare fuel. I'm still seeing it when I close my eyes.", "genre": "horror"},
- {"review": "A haunted house movie that actually delivers. Genuinely unsettling atmosphere.", "genre": "horror"},
- {"review": "Gore-fest with a surprising amount of social commentary. Brutal and smart.", "genre": "horror"},
- {"review": "The slow build of dread was masterful. When it finally hit, I screamed.", "genre": "horror"},
- {"review": "Found footage done right. I had to keep reminding myself it wasn't real.", "genre": "horror"},
-
- # === SCI-FI (10 examples) ===
- {"review": "Set in 2150, the space battles and alien technology were mind-blowing.", "genre": "sci-fi"},
- {"review": "Time travel paradoxes and quantum physics made this a thinker.", "genre": "sci-fi"},
- {"review": "The robot fell in love with a human. Surprisingly touching for a sci-fi.", "genre": "sci-fi"},
- {"review": "The sci-fi premise was just an excuse for philosophical debates. Loved every second.", "genre": "sci-fi"},
- {"review": "Cyberpunk aesthetic meets thought-provoking questions about consciousness.", "genre": "sci-fi"},
- {"review": "The worldbuilding is incredible. Every detail of this future feels plausible.", "genre": "sci-fi"},
- {"review": "First contact done differently. The aliens were truly alien, not just humans with makeup.", "genre": "sci-fi"},
- {"review": "Hard sci-fi that doesn't dumb down the science. Refreshingly intelligent.", "genre": "sci-fi"},
- {"review": "Dystopian future that feels uncomfortably close to our present. Chilling and prescient.", "genre": "sci-fi"},
- {"review": "Space exploration with a philosophical bent. What does it mean to be alone in the universe?", "genre": "sci-fi"},
-
- # === ROMANCE (10 examples) ===
- {"review": "The chemistry between the leads was electric. A beautiful love story.", "genre": "romance"},
- {"review": "Swoon-worthy moments and a happily ever after. Pure romantic bliss.", "genre": "romance"},
- {"review": "They met during an alien invasion. The world was ending but love found a way.", "genre": "romance"},
- {"review": "Enemies to lovers done perfectly. The tension was delicious.", "genre": "romance"},
- {"review": "A sweeping love story across decades. Their connection transcended time.", "genre": "romance"},
- {"review": "Second chance romance that made me believe in love again. Tissues required.", "genre": "romance"},
- {"review": "The slow burn was worth the wait. When they finally kissed, I cheered.", "genre": "romance"},
- {"review": "A meet-cute for the ages. Charming leads and witty banter throughout.", "genre": "romance"},
- {"review": "Forbidden love with actual stakes. Their sacrifice at the end broke me.", "genre": "romance"},
- {"review": "Holiday romance that's predictable but perfectly executed. Feel-good viewing.", "genre": "romance"},
-]
-
-# ============================================================================
-# TEST DATASET (30 examples)
-# ============================================================================
-# INTENTIONALLY CHALLENGING: sarcasm, multi-genre, misleading language,
-# subverted expectations, subtle signals, cultural references
-TEST_SET = [
- # === SARCASM & IRONY (5 examples) ===
- {"review": "Oh great, another movie where the hero walks away from explosions in slow motion. How original. Still watched it twice though.", "genre": "action"},
- {"review": "Groundbreaking stuff: man punches bad guys, gets the girl, saves the day. Revolutionary cinema. Loved every predictable second.", "genre": "action"},
- {"review": "I laughed so hard I cried. Then I just cried. Then I laughed again. What even was this movie?", "genre": "comedy"},
- {"review": "Wow, they really subverted my expectations by doing exactly what I expected. The jokes were so obvious they circled back to funny.", "genre": "comedy"},
- {"review": "Another 'scary' movie where the characters make terrible decisions. At least the kills were creative. Actually terrifying creature design though.", "genre": "horror"},
-
- # === MULTI-GENRE / PRIMARY GENRE DETECTION (6 examples) ===
- {"review": "The robot's sacrifice to save humanity made me sob uncontrollably. Beautiful storytelling set against a dystopian future.", "genre": "sci-fi"},
- {"review": "A serial killer falls in love with his next victim, but she's also a serial killer. Bloody and romantic.", "genre": "horror"},
- {"review": "Two detectives solve crimes while slowly falling for each other. The mystery was okay but I shipped them so hard.", "genre": "romance"},
- {"review": "It's technically a war movie but really it's about two soldiers finding love in the trenches. The battle scenes support the love story.", "genre": "romance"},
- {"review": "Space opera with a love triangle at its core. The laser battles are cool but I'm here for the drama between the three leads.", "genre": "sci-fi"},
- {"review": "Post-apocalyptic survival with a found family. The zombies are almost secondary to the human connections.", "genre": "drama"},
-
- # === MISLEADING GENRE SIGNALS (5 examples) ===
- {"review": "My heart was RACING the entire time! The courtroom scenes were absolutely EXPLOSIVE! Justice was served!", "genre": "drama"},
- {"review": "The alien invasion was just a backdrop for the family reconciliation story. Dad finally said he was proud.", "genre": "drama"},
- {"review": "Terrifyingly funny. The ghost just wanted to do stand-up comedy but kept accidentally scaring people.", "genre": "comedy"},
- {"review": "Action-packed emotional journey! By action I mean arguments, and by packed I mean I cried the whole time.", "genre": "drama"},
- {"review": "A thriller where the biggest twist was how much I ended up caring about these characters' relationships.", "genre": "romance"},
-
- # === SUBVERTED EXPECTATIONS (5 examples) ===
- {"review": "Everyone dies at the end. Like, EVERYONE. But somehow it was the most romantic film I've ever seen.", "genre": "romance"},
- {"review": "The monster wasn't scary at all - it just wanted friends. I cried when they finally accepted it.", "genre": "drama"},
- {"review": "Started as a slasher, ended as a meditation on trauma and healing. The horror serves the character development.", "genre": "horror"},
- {"review": "What seemed like a rom-com setup became a profound exploration of self-love and independence. She didn't need him after all.", "genre": "drama"},
- {"review": "The funniest parts were unintentional. This action movie's dialogue is so bad it's become a comedy classic in my friend group.", "genre": "action"},
-
- # === SUBTLE / AMBIGUOUS (5 examples) ===
- {"review": "Set in 2087, but really it's about loneliness. The AI companion understood him better than any human ever did.", "genre": "sci-fi"},
- {"review": "Quiet film about two people sharing a meal. Nothing happens and everything happens. Deeply moving.", "genre": "drama"},
- {"review": "The laughs come from pain, the pain comes from truth. A comedy that understands sadness intimately.", "genre": "comedy"},
- {"review": "Is it a horror movie if the monster is capitalism? Genuinely unsettling corporate satire.", "genre": "horror"},
- {"review": "They never say 'I love you' but every frame screams it. Visual storytelling at its most romantic.", "genre": "romance"},
-
- # === CULTURAL CONTEXT / SPECIFIC REFERENCES (4 examples) ===
- {"review": "John Wick energy but make it about a retired chef defending his restaurant. Knife fights choreographed like ballet.", "genre": "action"},
- {"review": "Hereditary meets Little Miss Sunshine. Family dysfunction with supernatural undertones played for dark laughs.", "genre": "comedy"},
- {"review": "Blade Runner questions wrapped in a Her-style relationship. What is real, and does it matter?", "genre": "sci-fi"},
- {"review": "Pride and Prejudice but in space. The Darcy character is an alien prince and it absolutely works.", "genre": "romance"},
-]
-
-
-# ============================================================================
-# SCHEMA DEFINITIONS
-# ============================================================================
-
-class MovieGenreOutput(BaseIOSchema):
- """Output schema for movie genre classification with structured results."""
-
- genre: Literal["action", "comedy", "drama", "horror", "sci-fi", "romance"] = Field(
- ...,
- description="The primary genre of the movie based on the review.",
- )
- confidence: float = Field(
- ...,
- description="Confidence score between 0.0 and 1.0",
- ge=0.0,
- le=1.0,
- )
- reasoning: str = Field(
- ...,
- description="Brief explanation for why this genre was chosen.",
- )
-
-
-class MovieReviewInput(BaseIOSchema):
- """Input schema for movie review classification."""
-
- review: str = Field(
- ...,
- description="The movie review text to classify.",
- )
-
-
-# ============================================================================
-# EVALUATION UTILITIES
-# ============================================================================
-
-@dataclass
-class EvalResult:
- """Stores evaluation results for comparison."""
- correct: int
- total: int
- accuracy: float
- predictions: List[Dict[str, Any]]
- avg_time: float
-
-
-def evaluate_predictions(predictions: List[Dict], test_set: List[Dict]) -> EvalResult:
- """Calculate accuracy and gather stats."""
- correct = 0
- results = []
-
- for pred, truth in zip(predictions, test_set):
- is_correct = pred.get("genre", "").lower() == truth["genre"].lower()
- if is_correct:
- correct += 1
- results.append({
- "review": truth["review"][:50] + "...",
- "expected": truth["genre"],
- "predicted": pred.get("genre", "ERROR"),
- "correct": is_correct,
- "confidence": pred.get("confidence", 0),
- "reasoning": pred.get("reasoning", "N/A")[:60],
- })
-
- return EvalResult(
- correct=correct,
- total=len(test_set),
- accuracy=correct / len(test_set) if test_set else 0,
- predictions=results,
- avg_time=0,
- )
-
-# ============================================================================
-# STAGE 1: RAW DSPy (Properly Implemented with Typed Signatures)
-# ============================================================================
+# =============================================================================
+# ORCHESTRATION
+# =============================================================================
-# Define a proper typed DSPy signature with Literal constraints
-class MovieGenreSignature(dspy.Signature):
- """Classify a movie review into its primary genre based on the review text.
- Consider the overall focus and tone of the review, not just individual keywords.
- A review mentioning 'explosions' might be a drama if the focus is on characters.
- A 'scary' movie might be a comedy if played for laughs.
+def run_all_stages(api_key: str) -> None:
"""
+ Run all three demonstration stages.
- review: str = dspy.InputField(desc="The movie review text to classify")
- genre: GenreType = dspy.OutputField(desc="The primary genre: action, comedy, drama, horror, sci-fi, or romance")
- confidence: float = dspy.OutputField(desc="Confidence score between 0.0 and 1.0")
- reasoning: str = dspy.OutputField(desc="Brief explanation for the classification")
-
-
-def stage1_raw_dspy(api_key: str) -> tuple[EvalResult, dict]:
- """
- Demonstrate raw DSPy with PROPER typed signatures.
-
- This shows DSPy at its best: typed signatures with Literal constraints,
- automatic optimization, and chain-of-thought reasoning.
- """
- console.print(Rule("[bold blue]STAGE 1: Raw DSPy (Properly Implemented)[/bold blue]", style="blue"))
-
- console.print(Panel(
- "[green]DSPy STRENGTHS:[/green]\n"
- "• Typed signatures with Literal constraints (genre MUST be valid)\n"
- "• Automatic prompt optimization via BootstrapFewShot\n"
- "• Chain-of-thought reasoning for complex decisions\n"
- "• Systematic few-shot example selection\n\n"
- "[yellow]LIMITATIONS vs Atomic Agents:[/yellow]\n"
- "• No Pydantic ecosystem (validators, serializers, etc.)\n"
- "• Less integration with structured output tools like Instructor\n"
- "• Type hints are enforced by DSPy, not Python runtime",
- title="Stage 1 Overview",
- border_style="blue"
- ))
-
- # Configure DSPy
- lm = dspy.LM("openai/gpt-4o-mini", api_key=api_key)
- dspy.configure(lm=lm)
-
- # Show the proper typed signature
- console.print("\n[bold]Step 1.1: Define Typed DSPy Signature[/bold]")
- console.print("DSPy supports class-based signatures with Python type hints:\n")
-
- signature_code = '''from typing import Literal
-
-# DSPy Signature WITH proper type constraints
-class MovieGenreSignature(dspy.Signature):
- """Classify a movie review into its primary genre."""
-
- review: str = dspy.InputField(desc="The movie review text")
-
- # Literal type constrains output to valid genres only!
- genre: Literal["action", "comedy", "drama", "horror", "sci-fi", "romance"] = \\
- dspy.OutputField(desc="The primary genre")
-
- confidence: float = dspy.OutputField(desc="Confidence 0.0-1.0")
- reasoning: str = dspy.OutputField(desc="Brief explanation")
-
-# DSPy enforces the Literal constraint - no more "dramedy" or "thriller"!
-classify = dspy.ChainOfThought(MovieGenreSignature)'''
-
- console.print(Syntax(signature_code, "python", theme="monokai", line_numbers=True))
-
- # Create the classifier with typed signature
- classify = dspy.ChainOfThought(MovieGenreSignature)
-
- # Show what the UNOPTIMIZED prompt looks like
- console.print("\n[bold]Step 1.2: Unoptimized Prompt (What DSPy Generates)[/bold]")
-
- # Run once to see the prompt
- with dspy.context(lm=lm):
- _ = classify(review=DATASET[0]["review"])
-
- # Get the last prompt from history
- unoptimized_prompt = None
- if lm.history:
- last_call = lm.history[-1]
- unoptimized_prompt = last_call.get("messages", [{}])
-
- console.print(Panel(
- "[dim]Notice how DSPy includes the Literal type constraint in the prompt:[/dim]\n\n" +
- json.dumps(unoptimized_prompt, indent=2)[:2000] + "...",
- title="Unoptimized DSPy Prompt (With Type Constraints)",
- border_style="yellow"
- ))
-
- # Now let's OPTIMIZE with BootstrapFewShot
- console.print("\n[bold]Step 1.3: DSPy Optimization (BootstrapFewShot)[/bold]")
- console.print(Panel(
- "[cyan]What BootstrapFewShot does:[/cyan]\n\n"
- "1. Takes your labeled training examples\n"
- "2. Runs the LLM on each to generate 'traces' (reasoning chains)\n"
- "3. Filters traces that produce correct answers\n"
- "4. Selects the best traces as few-shot demonstrations\n"
- "5. Injects these into future prompts automatically\n\n"
- "[yellow]Key insight:[/yellow] DSPy doesn't just use your examples verbatim.\n"
- "It generates NEW reasoning and picks what actually works!",
- title="How DSPy Optimization Works",
- border_style="cyan"
- ))
-
- # Create training set from our larger dataset
- # Use 30 examples for training (half the dataset)
- train_examples = DATASET[:30]
- trainset = [
- dspy.Example(
- review=ex["review"],
- genre=ex["genre"],
- confidence=0.85, # Reasonable default
- reasoning=f"This review demonstrates typical {ex['genre']} characteristics."
- ).with_inputs("review")
- for ex in train_examples
- ]
-
- # Define metric for optimization
- def genre_match(example, prediction, trace=None):
- pred_genre = str(prediction.genre).lower().strip()
- expected_genre = str(example.genre).lower().strip()
- return pred_genre == expected_genre
-
- # Optimize with more demos for better learning
- with Progress(
- SpinnerColumn(),
- TextColumn("[progress.description]{task.description}"),
- console=console,
- ) as progress:
- task = progress.add_task("[cyan]Running DSPy optimization (30 training examples)...", total=None)
-
- optimizer = dspy.BootstrapFewShot(
- metric=genre_match,
- max_bootstrapped_demos=4,
- max_labeled_demos=4,
- max_rounds=1,
- )
- optimized_classify = optimizer.compile(classify, trainset=trainset)
- progress.remove_task(task)
-
- console.print("[green]✓ Optimization complete![/green]\n")
-
- # Show what the OPTIMIZED prompt looks like
- console.print("[bold]Step 1.4: Optimized Prompt (After DSPy Magic)[/bold]")
-
- with dspy.context(lm=lm):
- _ = optimized_classify(review=TEST_SET[0]["review"])
-
- optimized_prompt = None
- if lm.history:
- last_call = lm.history[-1]
- optimized_prompt = last_call.get("messages", [{}])
-
- # Show the prompt
- prompt_str = json.dumps(optimized_prompt, indent=2)
-
- console.print(Panel(
- "[dim]Notice the auto-selected few-shot examples with reasoning:[/dim]\n\n" +
- prompt_str[:3500] + ("\n..." if len(prompt_str) > 3500 else ""),
- title="Optimized DSPy Prompt (With Auto-Selected Examples)",
- border_style="green"
- ))
-
- # Show which demos were selected
- console.print("\n[bold]Step 1.5: Few-Shot Examples DSPy Selected[/bold]")
-
- if hasattr(optimized_classify, 'demos') and optimized_classify.demos:
- tree = Tree("[bold]Selected Demonstrations[/bold]")
- for i, demo in enumerate(optimized_classify.demos[:4]):
- demo_branch = tree.add(f"[cyan]Example {i+1}[/cyan]")
- review_text = str(getattr(demo, 'review', 'N/A'))
- demo_branch.add(f"Review: {review_text[:70]}...")
- demo_branch.add(f"Genre: [green]{getattr(demo, 'genre', 'N/A')}[/green]")
- if hasattr(demo, 'reasoning'):
- reasoning = str(getattr(demo, 'reasoning', ''))[:80]
- demo_branch.add(f"Reasoning: [dim]{reasoning}...[/dim]")
- console.print(tree)
- else:
- console.print("[dim]Demo inspection not available for this predictor type[/dim]")
-
- # Evaluate on test set
- console.print(f"\n[bold]Step 1.6: Evaluation on Test Set ({len(TEST_SET)} challenging examples)[/bold]")
-
- predictions = []
- start_time = time.time()
-
- with Progress(
- SpinnerColumn(),
- TextColumn("[progress.description]{task.description}"),
- console=console,
- ) as progress:
- task = progress.add_task("[cyan]Running predictions...", total=len(TEST_SET))
-
- for test_ex in TEST_SET:
- try:
- result = optimized_classify(review=test_ex["review"])
- # DSPy with typed signatures should return valid genres
- genre_val = str(result.genre).strip().lower()
- # Normalize any edge cases
- if genre_val not in GENRES:
- genre_val = "error" # Mark invalid outputs
-
- predictions.append({
- "genre": genre_val,
- "confidence": float(result.confidence) if hasattr(result, 'confidence') else 0.5,
- "reasoning": str(result.reasoning) if hasattr(result, 'reasoning') else "N/A",
- })
- except Exception as e:
- predictions.append({
- "genre": "error",
- "confidence": 0,
- "reasoning": str(e),
- })
- progress.advance(task)
-
- elapsed = time.time() - start_time
-
- eval_result = evaluate_predictions(predictions, TEST_SET)
- eval_result.avg_time = elapsed / len(TEST_SET)
-
- # Show results
- console.print("\n[bold]Step 1.7: Results[/bold]")
-
- # Show DSPy's strengths AND remaining limitations
- invalid_genres = [p["genre"] for p in predictions if p["genre"] not in GENRES]
-
- console.print(Panel(
- "[green]DSPy TYPED SIGNATURE BENEFITS:[/green]\n"
- f"• Genre constrained to valid options (invalid outputs: {len(invalid_genres)})\n"
- "• Automatic few-shot example selection\n"
- "• Chain-of-thought reasoning included\n\n"
- "[yellow]REMAINING LIMITATIONS:[/yellow]\n"
- "• No Pydantic validation ecosystem\n"
- "• Confidence not guaranteed to be 0-1 (no ge/le constraints)\n"
- "• Can't use Instructor's retry mechanisms\n"
- "• Type enforcement is DSPy-specific, not Python-native",
- title="DSPy Typed Signatures Assessment",
- border_style="blue"
- ))
-
- # Results table
- table = Table(title=f"Stage 1 Results: {eval_result.accuracy:.1%} Accuracy ({eval_result.correct}/{eval_result.total})", box=box.ROUNDED)
- table.add_column("Review", style="cyan", max_width=40)
- table.add_column("Expected", style="green")
- table.add_column("Predicted", style="yellow")
- table.add_column("✓/✗", justify="center")
-
- for pred in eval_result.predictions:
- table.add_row(
- pred["review"],
- pred["expected"],
- pred["predicted"],
- "[green]✓[/green]" if pred["correct"] else "[red]✗[/red]"
- )
-
- console.print(table)
-
- behind_scenes = {
- "unoptimized_prompt_sample": str(unoptimized_prompt)[:500] if unoptimized_prompt else "N/A",
- "optimized_prompt_sample": str(optimized_prompt)[:500] if optimized_prompt else "N/A",
- "num_demos_selected": len(optimized_classify.demos) if hasattr(optimized_classify, 'demos') else "N/A",
- "training_examples": len(trainset),
- "invalid_genre_outputs": len(invalid_genres),
- }
-
- return eval_result, behind_scenes
-
-
-# ============================================================================
-# STAGE 2: RAW ATOMIC AGENTS
-# ============================================================================
-
-def stage2_raw_atomic_agents(api_key: str) -> tuple[EvalResult, dict]:
- """
- Demonstrate raw Atomic Agents: beautiful structured outputs, but manual prompts.
- """
- console.print(Rule("[bold magenta]STAGE 2: Raw Atomic Agents[/bold magenta]", style="magenta"))
-
- console.print(Panel(
- "[green]ATOMIC AGENTS STRENGTHS:[/green]\n"
- "• Full Pydantic ecosystem (validators, serializers, Field constraints)\n"
- "• Instructor integration for robust structured output\n"
- "• Python-native type safety with runtime validation\n"
- "• ge/le constraints on confidence (guaranteed 0-1)\n\n"
- "[yellow]LIMITATIONS:[/yellow]\n"
- "• Manual prompt engineering - no automatic optimization\n"
- "• No systematic few-shot example selection\n"
- "• Prompt improvements require guesswork and iteration",
- title="Stage 2 Overview",
- border_style="magenta"
- ))
-
- console.print("\n[bold]Step 2.1: Define Pydantic Schema[/bold]")
- console.print("Atomic Agents uses Pydantic for type-safe outputs:\n")
-
- schema_code = '''class MovieGenreOutput(BaseIOSchema):
- """Output schema for movie genre classification."""
-
- genre: Literal["action", "comedy", "drama", "horror", "sci-fi", "romance"] = Field(
- ...,
- description="The primary genre of the movie.",
- )
- confidence: float = Field(
- ...,
- ge=0.0, le=1.0, # VALIDATED! Must be between 0 and 1
- description="Confidence score between 0.0 and 1.0",
- )
- reasoning: str = Field(
- ...,
- description="Brief explanation for the classification.",
- )
-
-# The LLM output MUST match this schema or it fails validation.
-# No more parsing "high" vs "0.85" vs "85%" - it's always a float!'''
+ This is the main orchestration function that coordinates
+ the execution of all stages and displays the final comparison.
- console.print(Syntax(schema_code, "python", theme="monokai", line_numbers=True))
-
- console.print("\n[bold]Step 2.2: Manual System Prompt (The Guesswork)[/bold]")
-
- # This is our manually crafted prompt - we're guessing what works!
- manual_system_prompt = SystemPromptGenerator(
- background=[
- "You are a movie genre classification expert.",
- "You analyze movie reviews and determine the primary genre.",
- f"Valid genres are: {', '.join(GENRES)}",
- ],
- steps=[
- "Read the review carefully.",
- "Identify key genre indicators (action words, emotional language, etc.).",
- "Consider the overall tone and subject matter.",
- "Select the single most appropriate genre.",
- "Provide a confidence score based on how clear the genre signals are.",
- ],
- output_instructions=[
- "Be decisive - pick ONE primary genre even if multiple could apply.",
- "Confidence should be 0.7-1.0 for clear cases, 0.5-0.7 for ambiguous ones.",
- "Keep reasoning brief but specific to the review.",
- ],
- )
-
- generated_prompt = manual_system_prompt.generate_prompt()
-
- console.print(Panel(
- "[dim]This is the system prompt WE WROTE BY HAND:[/dim]\n\n" +
- generated_prompt,
- title="Manual System Prompt (Our Best Guess)",
- border_style="yellow"
- ))
-
- console.print(Panel(
- "[red]THE PROBLEM:[/red]\n\n"
- "We wrote this prompt based on intuition. Questions we can't answer:\n\n"
- "• Is 'Be decisive' helping or hurting accuracy?\n"
- "• Should we add few-shot examples? Which ones?\n"
- "• Is the step-by-step instruction actually useful?\n"
- "• Would different wording improve results?\n\n"
- "[yellow]Without DSPy, we're just guessing![/yellow]",
- title="The Manual Prompt Engineering Problem",
- border_style="red"
- ))
-
- # Create Atomic Agent
- console.print("\n[bold]Step 2.3: Create Atomic Agent[/bold]")
-
- client = instructor.from_openai(openai.OpenAI(api_key=api_key))
-
- agent = AtomicAgent[MovieReviewInput, MovieGenreOutput](
- config=AgentConfig(
- client=client,
- model="gpt-4o-mini",
- system_prompt_generator=manual_system_prompt,
- )
- )
-
- console.print("[green]✓ Agent created with schema validation[/green]")
-
- # Show how Instructor enforces the schema
- console.print("\n[bold]Step 2.4: Schema Enforcement in Action[/bold]")
-
- console.print(Panel(
- "[cyan]What happens under the hood:[/cyan]\n\n"
- "1. Atomic Agents sends your prompt + Pydantic schema to the LLM\n"
- "2. Instructor (the library) converts schema to JSON Schema for the LLM\n"
- "3. LLM generates output attempting to match the schema\n"
- "4. Instructor validates the response against Pydantic\n"
- "5. If validation fails, Instructor retries with error feedback\n"
- "6. You get a guaranteed-valid Pydantic object or an exception\n\n"
- "[green]Result:[/green] genre is ALWAYS one of our 6 options,\n"
- "confidence is ALWAYS a float between 0 and 1!",
- title="How Schema Enforcement Works",
- border_style="cyan"
- ))
-
- # Evaluate
- console.print("\n[bold]Step 2.5: Evaluation on Test Set[/bold]")
-
- predictions = []
- start_time = time.time()
-
- with Progress(
- SpinnerColumn(),
- TextColumn("[progress.description]{task.description}"),
- console=console,
- ) as progress:
- task = progress.add_task("[magenta]Running predictions...", total=len(TEST_SET))
-
- for test_ex in TEST_SET:
- try:
- result = agent.run(MovieReviewInput(review=test_ex["review"]))
- predictions.append({
- "genre": result.genre, # Already validated!
- "confidence": result.confidence, # Already a float!
- "reasoning": result.reasoning,
- })
- except Exception as e:
- predictions.append({
- "genre": "error",
- "confidence": 0,
- "reasoning": str(e),
- })
- progress.advance(task)
-
- elapsed = time.time() - start_time
-
- eval_result = evaluate_predictions(predictions, TEST_SET)
- eval_result.avg_time = elapsed / len(TEST_SET)
-
- # Show the BENEFIT - structured outputs
- console.print("\n[bold]Step 2.6: The Benefit - Type-Safe Outputs[/bold]")
-
- console.print(Panel(
- "[green]ATOMIC AGENTS ADVANTAGE:[/green]\n\n"
- "Look at these outputs - perfectly structured:\n" +
- "\n".join([
- f" • genre='{predictions[i]['genre']}' (Literal) confidence={predictions[i]['confidence']:.2f} (float)"
- for i in range(min(3, len(predictions)))
- ]) + "\n\n"
- "[cyan]Benefits:[/cyan]\n"
- "• genre is guaranteed to be one of our 6 valid options\n"
- "• confidence is always a float between 0.0 and 1.0\n"
- "• No parsing needed - direct attribute access\n"
- "• IDE autocomplete works perfectly\n"
- "• Downstream code can trust the types",
- title="Structured Output Benefits",
- border_style="green"
- ))
-
- # Results table
- table = Table(title=f"Stage 2 Results: {eval_result.accuracy:.1%} Accuracy", box=box.ROUNDED)
- table.add_column("Review", style="cyan", max_width=35)
- table.add_column("Expected", style="green")
- table.add_column("Predicted", style="yellow")
- table.add_column("Confidence", justify="right")
- table.add_column("✓/✗", justify="center")
-
- for pred in eval_result.predictions:
- table.add_row(
- pred["review"],
- pred["expected"],
- pred["predicted"],
- f"{pred['confidence']:.2f}",
- "[green]✓[/green]" if pred["correct"] else "[red]✗[/red]"
- )
-
- console.print(table)
-
- behind_scenes = {
- "system_prompt": generated_prompt,
- "schema_enforced": True,
- "manual_engineering": True,
- }
-
- return eval_result, behind_scenes
-
-
-# ============================================================================
-# STAGE 3: DSPy + ATOMIC AGENTS (THE BEST OF BOTH)
-# ============================================================================
-
-def stage3_combined(api_key: str) -> tuple[EvalResult, dict]:
+ Args:
+ api_key: OpenAI API key for LLM access
"""
- Demonstrate the combined approach: DSPy optimization + Atomic Agents structure.
- """
- console.print(Rule("[bold green]STAGE 3: DSPy + Atomic Agents[/bold green]", style="green"))
-
- console.print(Panel(
- "[green]THE SOLUTION:[/green]\n"
- "Combine DSPy's automatic optimization with Atomic Agents' type safety!\n\n"
- "[cyan]WHAT WE GET:[/cyan]\n"
- "• DSPy automatically finds the best prompts and examples\n"
- "• Atomic Agents guarantees output structure\n"
- "• Measurable improvements through optimization\n"
- "• Production-ready typed outputs\n\n"
- "[yellow]THE BEST OF BOTH WORLDS[/yellow]",
- title="Stage 3 Overview",
- border_style="green"
- ))
-
- # Import our bridge
- from dspy_integration.bridge import (
- DSPyAtomicModule,
- create_dspy_example,
- create_dspy_signature_from_schemas,
- )
-
- console.print("\n[bold]Step 3.1: The Bridge - DSPyAtomicModule[/bold]")
-
- bridge_code = '''# The bridge combines both frameworks:
-module = DSPyAtomicModule(
- input_schema=MovieReviewInput, # Pydantic input validation
- output_schema=MovieGenreOutput, # Pydantic output structure
- instructions="Classify the movie review into a genre.",
- use_chain_of_thought=True, # DSPy's reasoning capability
-)
-
-# Behind the scenes:
-# 1. Pydantic schemas are converted to DSPy signatures
-# 2. DSPy handles prompt construction and optimization
-# 3. Outputs are validated against Pydantic schemas
-# 4. You get type-safe results that DSPy optimized!'''
-
- console.print(Syntax(bridge_code, "python", theme="monokai", line_numbers=True))
-
- # Configure DSPy
- lm = dspy.LM("openai/gpt-4o-mini", api_key=api_key)
- dspy.configure(lm=lm)
-
- # Create the module
- module = DSPyAtomicModule(
- input_schema=MovieReviewInput,
- output_schema=MovieGenreOutput,
- instructions="Classify the movie review into its primary genre. Be accurate and provide reasoning.",
- use_chain_of_thought=True,
- )
-
- console.print("\n[bold]Step 3.2: Schema-to-Signature Conversion[/bold]")
-
- # Show the generated signature
- console.print(Panel(
- f"[cyan]Pydantic Schema → DSPy Signature:[/cyan]\n\n"
- f"Input fields: review (str)\n"
- f"Output fields: genre (Literal), confidence (float), reasoning (str)\n\n"
- f"[dim]The bridge automatically converts Pydantic field descriptions\n"
- f"into DSPy field descriptors, preserving all metadata.[/dim]",
- title="Automatic Conversion",
- border_style="cyan"
- ))
-
- # Create typed training examples
- console.print("\n[bold]Step 3.3: Type-Safe Training Examples[/bold]")
-
- console.print(Panel(
- "[cyan]Creating training examples with validation:[/cyan]\n\n"
- "Each example is validated against our Pydantic schemas!\n"
- "If you accidentally put confidence=1.5 or genre='thriller',\n"
- "you get an immediate error - not a silent failure later.",
- title="Validated Training Data",
- border_style="cyan"
- ))
-
- # Create training set with our helper - use more examples for better optimization
- train_examples = DATASET[:40] # Use 40 examples for training
- trainset = []
- for ex in train_examples:
- trainset.append(
- create_dspy_example(
- MovieReviewInput,
- MovieGenreOutput,
- {"review": ex["review"]},
- {
- "genre": ex["genre"],
- "confidence": 0.85, # Reasonable default
- "reasoning": f"The review shows typical {ex['genre']} characteristics.",
- },
- )
- )
-
- console.print(f"[green]✓ Created {len(trainset)} validated training examples[/green]")
-
- # Define metric
- def typed_genre_match(example, prediction, trace=None):
- """Metric that works with our typed outputs."""
- pred_genre = str(prediction.genre).lower().strip()
- expected_genre = str(example.genre).lower().strip()
- return pred_genre == expected_genre
-
- # Optimize
- console.print("\n[bold]Step 3.4: DSPy Optimization (With Schema Awareness)[/bold]")
-
- with Progress(
- SpinnerColumn(),
- TextColumn("[progress.description]{task.description}"),
- console=console,
- ) as progress:
- task = progress.add_task(f"[green]Running optimization ({len(trainset)} training examples)...", total=None)
+ # Stage 1: Raw DSPy
+ stage1_result, _ = run_stage1_raw_dspy(api_key)
+ console.print("\n")
- optimizer = dspy.BootstrapFewShot(
- metric=typed_genre_match,
- max_bootstrapped_demos=4,
- max_labeled_demos=4,
- max_rounds=1,
- )
- optimized_module = optimizer.compile(module, trainset=trainset)
- progress.remove_task(task)
+ # Stage 2: Raw Atomic Agents
+ stage2_result, _ = run_stage2_raw_atomic_agents(api_key)
+ console.print("\n")
- console.print("[green]✓ Optimization complete![/green]")
+ # Stage 3: Combined approach
+ stage3_result, _ = run_stage3_combined(api_key)
+ console.print("\n")
- # Show the optimized prompt
- console.print("\n[bold]Step 3.5: The Optimized Prompt (Exposed!)[/bold]")
+ # Final comparison
+ show_final_comparison(stage1_result, stage2_result, stage3_result)
- # Run once to capture the prompt
- with dspy.context(lm=lm):
- _ = optimized_module(review=TEST_SET[0]["review"])
-
- if lm.history:
- last_call = lm.history[-1]
- optimized_prompt = last_call.get("messages", [{}])
- prompt_str = json.dumps(optimized_prompt, indent=2)
-
- console.print(Panel(
- "[dim]This is what DSPy + Atomic Agents sends to the LLM:[/dim]\n\n" +
- prompt_str[:2500] + ("\n..." if len(prompt_str) > 2500 else ""),
- title="Final Optimized Prompt",
- border_style="green"
- ))
-
- # Evaluate with type-safe outputs
- console.print("\n[bold]Step 3.6: Evaluation with Type-Safe Outputs[/bold]")
-
- predictions = []
- raw_outputs = []
- start_time = time.time()
-
- with Progress(
- SpinnerColumn(),
- TextColumn("[progress.description]{task.description}"),
- console=console,
- ) as progress:
- task = progress.add_task("[green]Running predictions...", total=len(TEST_SET))
-
- for test_ex in TEST_SET:
- try:
- # Get raw DSPy output
- raw_result = optimized_module(review=test_ex["review"])
-
- # Convert to validated Pydantic
- validated_result = optimized_module.run_validated(review=test_ex["review"])
-
- predictions.append({
- "genre": validated_result.genre, # Guaranteed Literal type!
- "confidence": validated_result.confidence, # Guaranteed 0-1 float!
- "reasoning": validated_result.reasoning,
- })
- raw_outputs.append({
- "raw_genre": str(raw_result.genre),
- "validated_genre": validated_result.genre,
- })
- except Exception as e:
- predictions.append({
- "genre": "error",
- "confidence": 0,
- "reasoning": str(e),
- })
- progress.advance(task)
-
- elapsed = time.time() - start_time
-
- eval_result = evaluate_predictions(predictions, TEST_SET)
- eval_result.avg_time = elapsed / len(TEST_SET)
-
- # Show the combined benefits
- console.print("\n[bold]Step 3.7: The Combined Benefits[/bold]")
-
- console.print(Panel(
- "[green]✓ DSPy BENEFITS:[/green]\n"
- "• Automatic few-shot example selection\n"
- "• Optimized prompt instructions\n"
- "• Chain-of-thought reasoning\n"
- "• Measurable improvement through metrics\n\n"
- "[green]✓ ATOMIC AGENTS BENEFITS:[/green]\n"
- "• genre is Literal['action','comedy',...] - always valid\n"
- "• confidence is float with ge=0, le=1 - always in range\n"
- "• Full IDE autocomplete and type checking\n"
- "• Pydantic validation catches any LLM mistakes\n\n"
- "[yellow]COMBINED:[/yellow] Optimized prompts + Guaranteed structure!",
- title="The Best of Both Worlds",
- border_style="green"
- ))
-
- # Results table
- table = Table(title=f"Stage 3 Results: {eval_result.accuracy:.1%} Accuracy", box=box.ROUNDED)
- table.add_column("Review", style="cyan", max_width=35)
- table.add_column("Expected", style="green")
- table.add_column("Predicted", style="yellow")
- table.add_column("Confidence", justify="right")
- table.add_column("✓/✗", justify="center")
-
- for pred in eval_result.predictions:
- table.add_row(
- pred["review"],
- pred["expected"],
- pred["predicted"],
- f"{pred['confidence']:.2f}",
- "[green]✓[/green]" if pred["correct"] else "[red]✗[/red]"
- )
-
- console.print(table)
-
- behind_scenes = {
- "optimized_prompt_sample": prompt_str[:1000] if 'prompt_str' in dir() else "N/A",
- "schema_enforced": True,
- "dspy_optimized": True,
- }
-
- return eval_result, behind_scenes
-
-
-# ============================================================================
-# FINAL COMPARISON
-# ============================================================================
def show_final_comparison(
stage1_result: EvalResult,
stage2_result: EvalResult,
stage3_result: EvalResult,
-):
- """Show side-by-side comparison of all three approaches."""
-
- console.print(Rule("[bold yellow]FINAL COMPARISON[/bold yellow]", style="yellow"))
-
- # Summary table
- table = Table(title="Approach Comparison", box=box.DOUBLE_EDGE)
- table.add_column("Metric", style="bold")
- table.add_column("Stage 1\nRaw DSPy", justify="center", style="blue")
- table.add_column("Stage 2\nRaw Atomic Agents", justify="center", style="magenta")
- table.add_column("Stage 3\nDSPy + Atomic", justify="center", style="green")
-
- table.add_row(
- "Accuracy",
- f"{stage1_result.accuracy:.1%}",
- f"{stage2_result.accuracy:.1%}",
- f"[bold]{stage3_result.accuracy:.1%}[/bold]",
- )
- table.add_row(
- "Correct / Total",
- f"{stage1_result.correct}/{stage1_result.total}",
- f"{stage2_result.correct}/{stage2_result.total}",
- f"[bold]{stage3_result.correct}/{stage3_result.total}[/bold]",
- )
- table.add_row(
- "Avg Time/Query",
- f"{stage1_result.avg_time:.2f}s",
- f"{stage2_result.avg_time:.2f}s",
- f"{stage3_result.avg_time:.2f}s",
- )
- table.add_row(
- "Prompt Optimization",
- "[green]✓ Auto[/green]",
- "[red]✗ Manual[/red]",
- "[green]✓ Auto[/green]",
- )
- table.add_row(
- "Type Safety",
- "[yellow]~ DSPy Literal[/yellow]",
- "[green]✓ Pydantic[/green]",
- "[green]✓ Pydantic[/green]",
- )
- table.add_row(
- "Output Validation",
- "[yellow]~ Basic[/yellow]",
- "[green]✓ Full[/green]",
- "[green]✓ Full[/green]",
- )
- table.add_row(
- "Pydantic Ecosystem",
- "[red]✗ No[/red]",
- "[green]✓ Full[/green]",
- "[green]✓ Full[/green]",
- )
- table.add_row(
- "Few-Shot Selection",
- "[green]✓ Auto[/green]",
- "[red]✗ Manual[/red]",
- "[green]✓ Auto[/green]",
- )
- table.add_row(
- "IDE Support",
- "[yellow]~ Partial[/yellow]",
- "[green]✓ Full[/green]",
- "[green]✓ Full[/green]",
- )
-
- console.print(table)
-
- # Key takeaways
- console.print(Panel(
- "[bold yellow]KEY TAKEAWAYS[/bold yellow]\n\n"
-
- "[blue]RAW DSPy (with typed signatures):[/blue]\n"
- "• Excellent optimization with Literal type constraints\n"
- "• Great for experimentation and iteration\n"
- "• Missing Pydantic ecosystem (validators, Field constraints)\n\n"
-
- "[magenta]RAW ATOMIC AGENTS:[/magenta]\n"
- "• Full Pydantic ecosystem with runtime validation\n"
- "• Instructor integration for robust outputs\n"
- "• Manual prompt engineering limits optimization\n\n"
-
- "[green]DSPy + ATOMIC AGENTS:[/green]\n"
- "• Automatic optimization finds the best prompts\n"
- "• Full Pydantic validation and serialization\n"
- "• Measurable improvements + production-ready types\n"
- "• [bold]The best of both worlds![/bold]",
- title="Summary",
- border_style="yellow"
- ))
-
- # When to use what
- console.print(Panel(
- "[bold]WHEN TO USE EACH APPROACH[/bold]\n\n"
-
- "[blue]Use Raw DSPy when:[/blue]\n"
- "• Quick prototyping and experimentation\n"
- "• Output format doesn't matter much\n"
- "• You'll post-process outputs anyway\n\n"
-
- "[magenta]Use Raw Atomic Agents when:[/magenta]\n"
- "• You need guaranteed output structure NOW\n"
- "• You don't have training data for optimization\n"
- "• The task is simple enough that manual prompts work\n\n"
+) -> None:
+ """
+ Display side-by-side comparison of all three approaches.
- "[green]Use DSPy + Atomic Agents when:[/green]\n"
- "• You have labeled data and want to optimize\n"
- "• Production systems need type-safe outputs\n"
- "• You want measurable, reproducible improvements\n"
- "• Both accuracy AND structure matter",
- title="Decision Guide",
- border_style="cyan"
- ))
+ This provides the key takeaway - showing why combining
+ DSPy with Atomic Agents gives the best results.
+ """
+ display_stage_header("FINAL COMPARISON", "yellow")
+ display_comparison_table(stage1_result, stage2_result, stage3_result)
+ display_takeaways()
+ display_decision_guide()
-# ============================================================================
-# MAIN
-# ============================================================================
+# =============================================================================
+# ENTRY POINT
+# =============================================================================
-def main():
- """Run the complete didactic example with a comprehensive benchmark."""
- console.print(Panel.fit(
- "[bold]DSPy + Atomic Agents: A Comprehensive Didactic Example[/bold]\n\n"
- "This example teaches you WHY combining these frameworks is powerful\n"
- "by walking through three stages with full transparency.\n\n"
- "[dim]Large benchmark: 60 training examples, 30 challenging test cases\n"
- "We'll expose the prompts, show the optimizations,\n"
- "and compare measurable results.[/dim]",
- border_style="bold white",
- ))
+def main() -> None:
+ """
+ Main entry point for the demonstration.
- # Check API key
+ Responsibilities:
+ - Display welcome message
+ - Validate API key
+ - Run all stages
+ - Handle errors gracefully
+ """
+ display_welcome(
+ title="DSPy + Atomic Agents: A Comprehensive Didactic Example",
+ subtitle=(
+ "This example teaches you WHY combining these frameworks is powerful\n"
+ "by walking through three stages with full transparency."
+ ),
+ details=(
+ f"Large benchmark: {len(TRAINING_DATASET)} training examples, "
+ f"{len(TEST_DATASET)} challenging test cases\n"
+ "We'll expose the prompts, show the optimizations,\n"
+ "and compare measurable results."
+ ),
+ )
+
+ # Validate API key
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
console.print("[red]Error: OPENAI_API_KEY environment variable required[/red]")
return
- console.print(f"\n[dim]Using model: gpt-4o-mini[/dim]")
- console.print(f"[dim]Training set: {len(DATASET)} examples (balanced across 6 genres)[/dim]")
- console.print(f"[dim]Test set: {len(TEST_SET)} challenging examples (sarcasm, multi-genre, etc.)[/dim]\n")
+ # Display configuration
+ console.print("\n[dim]Using model: gpt-4o-mini[/dim]")
+ console.print(
+ f"[dim]Training set: {len(TRAINING_DATASET)} examples (balanced across 6 genres)[/dim]"
+ )
+ console.print(
+ f"[dim]Test set: {len(TEST_DATASET)} challenging examples "
+ "(sarcasm, multi-genre, etc.)[/dim]\n"
+ )
- # Run all three stages
+ # Run demonstration
try:
- stage1_result, stage1_behind = stage1_raw_dspy(api_key)
- console.print("\n")
-
- stage2_result, stage2_behind = stage2_raw_atomic_agents(api_key)
- console.print("\n")
-
- stage3_result, stage3_behind = stage3_combined(api_key)
- console.print("\n")
-
- # Final comparison
- show_final_comparison(stage1_result, stage2_result, stage3_result)
-
+ run_all_stages(api_key)
except Exception as e:
console.print(f"[red]Error: {e}[/red]")
- import traceback
console.print(traceback.format_exc())
diff --git a/atomic-examples/dspy-integration/dspy_integration/presentation/__init__.py b/atomic-examples/dspy-integration/dspy_integration/presentation/__init__.py
new file mode 100644
index 0000000..9ae56c1
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/presentation/__init__.py
@@ -0,0 +1,39 @@
+"""
+Presentation layer for DSPy + Atomic Agents integration.
+
+This package handles all console output and visualization using Rich.
+Separating presentation from business logic allows:
+- Testing business logic without UI dependencies
+- Easy swapping of presentation implementation
+- Clean separation of concerns
+
+Following Clean Architecture: presentation depends on domain, not vice versa.
+"""
+
+from dspy_integration.presentation.console import (
+ console,
+ display_welcome,
+ display_stage_header,
+ display_panel,
+ display_code,
+ display_tree,
+ display_results_table,
+ display_comparison_table,
+ display_takeaways,
+ display_decision_guide,
+ create_progress_context,
+)
+
+__all__ = [
+ "console",
+ "display_welcome",
+ "display_stage_header",
+ "display_panel",
+ "display_code",
+ "display_tree",
+ "display_results_table",
+ "display_comparison_table",
+ "display_takeaways",
+ "display_decision_guide",
+ "create_progress_context",
+]
diff --git a/atomic-examples/dspy-integration/dspy_integration/presentation/console.py b/atomic-examples/dspy-integration/dspy_integration/presentation/console.py
new file mode 100644
index 0000000..05d80f5
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/presentation/console.py
@@ -0,0 +1,331 @@
+"""
+Console presentation utilities using Rich.
+
+This module provides a clean API for all console output operations.
+All Rich-specific code is encapsulated here, making it easy to swap
+to a different presentation library if needed.
+
+Design Principles:
+- Encapsulate all Rich dependencies
+- Provide high-level semantic functions (display_results, not print_table)
+- No business logic - only presentation concerns
+"""
+
+from contextlib import contextmanager
+from typing import Any, Dict, Generator, List
+
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.rule import Rule
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.tree import Tree
+
+from dspy_integration.domain.models import EvalResult
+
+
+# Global console instance
+console = Console()
+
+
+# =============================================================================
+# HIGH-LEVEL DISPLAY FUNCTIONS
+# =============================================================================
+
+
+def display_welcome(
+ title: str,
+ subtitle: str,
+ details: str,
+) -> None:
+ """Display welcome banner for the application."""
+ console.print(
+ Panel.fit(
+ f"[bold]{title}[/bold]\n\n{subtitle}\n\n[dim]{details}[/dim]",
+ border_style="bold white",
+ )
+ )
+
+
+def display_stage_header(stage_name: str, style: str) -> None:
+ """Display a stage header with rule line."""
+ console.print(Rule(f"[bold {style}]{stage_name}[/bold {style}]", style=style))
+
+
+def display_panel(
+ content: str,
+ title: str,
+ border_style: str = "blue",
+) -> None:
+ """Display a panel with formatted content."""
+ console.print(Panel(content, title=title, border_style=border_style))
+
+
+def display_code(
+ code: str,
+ language: str = "python",
+ theme: str = "monokai",
+ line_numbers: bool = True,
+) -> None:
+ """Display syntax-highlighted code."""
+ console.print(Syntax(code, language, theme=theme, line_numbers=line_numbers))
+
+
+def display_step_header(step: str) -> None:
+ """Display a step header within a stage."""
+ console.print(f"\n[bold]{step}[/bold]")
+
+
+def display_success(message: str) -> None:
+ """Display a success message."""
+ console.print(f"[green]✓ {message}[/green]")
+
+
+def display_info(message: str) -> None:
+ """Display an info message."""
+ console.print(f"[dim]{message}[/dim]")
+
+
+def display_tree(
+ title: str,
+ items: List[Dict[str, Any]],
+) -> None:
+ """
+ Display a tree structure.
+
+ Args:
+ title: Root node title
+ items: List of dicts with 'title' and optional 'children' keys
+ """
+ tree = Tree(f"[bold]{title}[/bold]")
+
+ for item in items:
+ branch = tree.add(f"[cyan]{item.get('title', 'Item')}[/cyan]")
+ for child in item.get("children", []):
+ branch.add(child)
+
+ console.print(tree)
+
+
+# =============================================================================
+# RESULTS DISPLAY FUNCTIONS
+# =============================================================================
+
+
+def display_results_table(
+ eval_result: EvalResult,
+ title: str,
+ show_confidence: bool = False,
+) -> None:
+ """
+ Display evaluation results in a table format.
+
+ Args:
+ eval_result: Evaluation results to display
+ title: Table title
+ show_confidence: Whether to show confidence column
+ """
+ table = Table(
+ title=f"{title}: {eval_result.accuracy:.1%} Accuracy "
+ f"({eval_result.correct}/{eval_result.total})",
+ box=box.ROUNDED,
+ )
+
+ table.add_column("Review", style="cyan", max_width=40)
+ table.add_column("Expected", style="green")
+ table.add_column("Predicted", style="yellow")
+
+ if show_confidence:
+ table.add_column("Confidence", justify="right")
+
+ table.add_column("✓/✗", justify="center")
+
+ for pred in eval_result.predictions:
+ row = [
+ pred["review"],
+ pred["expected"],
+ pred["predicted"],
+ ]
+
+ if show_confidence:
+ row.append(f"{pred['confidence']:.2f}")
+
+ row.append("[green]✓[/green]" if pred["correct"] else "[red]✗[/red]")
+ table.add_row(*row)
+
+ console.print(table)
+
+
+def display_comparison_table(
+ stage1_result: EvalResult,
+ stage2_result: EvalResult,
+ stage3_result: EvalResult,
+) -> None:
+ """Display side-by-side comparison of all three approaches."""
+ table = Table(title="Approach Comparison", box=box.DOUBLE_EDGE)
+
+ table.add_column("Metric", style="bold")
+ table.add_column("Stage 1\nRaw DSPy", justify="center", style="blue")
+ table.add_column("Stage 2\nRaw Atomic Agents", justify="center", style="magenta")
+ table.add_column("Stage 3\nDSPy + Atomic", justify="center", style="green")
+
+ # Accuracy row
+ table.add_row(
+ "Accuracy",
+ f"{stage1_result.accuracy:.1%}",
+ f"{stage2_result.accuracy:.1%}",
+ f"[bold]{stage3_result.accuracy:.1%}[/bold]",
+ )
+
+ # Correct/Total row
+ table.add_row(
+ "Correct / Total",
+ f"{stage1_result.correct}/{stage1_result.total}",
+ f"{stage2_result.correct}/{stage2_result.total}",
+ f"[bold]{stage3_result.correct}/{stage3_result.total}[/bold]",
+ )
+
+ # Time row
+ table.add_row(
+ "Avg Time/Query",
+ f"{stage1_result.avg_time:.2f}s",
+ f"{stage2_result.avg_time:.2f}s",
+ f"{stage3_result.avg_time:.2f}s",
+ )
+
+ # Feature comparison rows
+ _add_feature_rows(table)
+
+ console.print(table)
+
+
+def _add_feature_rows(table: Table) -> None:
+ """Add feature comparison rows to the table."""
+ features = [
+ (
+ "Prompt Optimization",
+ "[green]✓ Auto[/green]",
+ "[red]✗ Manual[/red]",
+ "[green]✓ Auto[/green]",
+ ),
+ (
+ "Type Safety",
+ "[yellow]~ DSPy Literal[/yellow]",
+ "[green]✓ Pydantic[/green]",
+ "[green]✓ Pydantic[/green]",
+ ),
+ (
+ "Output Validation",
+ "[yellow]~ Basic[/yellow]",
+ "[green]✓ Full[/green]",
+ "[green]✓ Full[/green]",
+ ),
+ (
+ "Pydantic Ecosystem",
+ "[red]✗ No[/red]",
+ "[green]✓ Full[/green]",
+ "[green]✓ Full[/green]",
+ ),
+ (
+ "Few-Shot Selection",
+ "[green]✓ Auto[/green]",
+ "[red]✗ Manual[/red]",
+ "[green]✓ Auto[/green]",
+ ),
+ (
+ "IDE Support",
+ "[yellow]~ Partial[/yellow]",
+ "[green]✓ Full[/green]",
+ "[green]✓ Full[/green]",
+ ),
+ ]
+
+ for feature in features:
+ table.add_row(*feature)
+
+
+# =============================================================================
+# SUMMARY DISPLAY FUNCTIONS
+# =============================================================================
+
+
+def display_takeaways() -> None:
+ """Display key takeaways panel."""
+ content = """[bold yellow]KEY TAKEAWAYS[/bold yellow]
+
+[blue]RAW DSPy (with typed signatures):[/blue]
+• Excellent optimization with Literal type constraints
+• Great for experimentation and iteration
+• Missing Pydantic ecosystem (validators, Field constraints)
+
+[magenta]RAW ATOMIC AGENTS:[/magenta]
+• Full Pydantic ecosystem with runtime validation
+• Instructor integration for robust outputs
+• Manual prompt engineering limits optimization
+
+[green]DSPy + ATOMIC AGENTS:[/green]
+• Automatic optimization finds the best prompts
+• Full Pydantic validation and serialization
+• Measurable improvements + production-ready types
+• [bold]The best of both worlds![/bold]"""
+
+ console.print(Panel(content, title="Summary", border_style="yellow"))
+
+
+def display_decision_guide() -> None:
+ """Display when-to-use-what guide."""
+ content = """[bold]WHEN TO USE EACH APPROACH[/bold]
+
+[blue]Use Raw DSPy when:[/blue]
+• Quick prototyping and experimentation
+• Output format doesn't matter much
+• You'll post-process outputs anyway
+
+[magenta]Use Raw Atomic Agents when:[/magenta]
+• You need guaranteed output structure NOW
+• You don't have training data for optimization
+• The task is simple enough that manual prompts work
+
+[green]Use DSPy + Atomic Agents when:[/green]
+• You have labeled data and want to optimize
+• Production systems need type-safe outputs
+• You want measurable, reproducible improvements
+• Both accuracy AND structure matter"""
+
+ console.print(Panel(content, title="Decision Guide", border_style="cyan"))
+
+
+# =============================================================================
+# PROGRESS CONTEXT MANAGER
+# =============================================================================
+
+
+@contextmanager
+def create_progress_context(
+ description: str,
+ style: str = "cyan",
+) -> Generator[Progress, None, None]:
+ """
+ Create a progress context for long-running operations.
+
+ Args:
+ description: Task description to display
+ style: Color style for the progress text
+
+ Yields:
+ Progress object that can be used to update progress
+
+ Example:
+ >>> with create_progress_context("Processing...", "green") as progress:
+ ... task = progress.add_task("[green]Working...", total=100)
+ ... for i in range(100):
+ ... progress.advance(task)
+ """
+ with Progress(
+ SpinnerColumn(),
+ TextColumn("[progress.description]{task.description}"),
+ console=console,
+ ) as progress:
+ yield progress
diff --git a/atomic-examples/dspy-integration/dspy_integration/stages/__init__.py b/atomic-examples/dspy-integration/dspy_integration/stages/__init__.py
new file mode 100644
index 0000000..b6e0ebd
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/stages/__init__.py
@@ -0,0 +1,21 @@
+"""
+Stages package for DSPy + Atomic Agents integration demo.
+
+Each stage demonstrates a different approach:
+- Stage 1: Raw DSPy with typed signatures
+- Stage 2: Raw Atomic Agents with manual prompts
+- Stage 3: Combined DSPy + Atomic Agents
+
+Following Single Responsibility Principle: each stage module handles
+one approach completely, from setup to evaluation.
+"""
+
+from dspy_integration.stages.stage1_dspy import run_stage1_raw_dspy
+from dspy_integration.stages.stage2_atomic import run_stage2_raw_atomic_agents
+from dspy_integration.stages.stage3_combined import run_stage3_combined
+
+__all__ = [
+ "run_stage1_raw_dspy",
+ "run_stage2_raw_atomic_agents",
+ "run_stage3_combined",
+]
diff --git a/atomic-examples/dspy-integration/dspy_integration/stages/stage1_dspy.py b/atomic-examples/dspy-integration/dspy_integration/stages/stage1_dspy.py
new file mode 100644
index 0000000..86c0736
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/stages/stage1_dspy.py
@@ -0,0 +1,417 @@
+"""
+Stage 1: Raw DSPy with Typed Signatures.
+
+This module demonstrates DSPy's capabilities at their best:
+- Typed signatures with Literal constraints
+- Automatic prompt optimization via BootstrapFewShot
+- Chain-of-thought reasoning
+
+Limitations shown:
+- No Pydantic validation ecosystem
+- Less integration with structured output tools
+- Type enforcement is DSPy-specific, not Python runtime
+
+Design: Single function entry point, internal helpers follow SRP.
+"""
+
+import json
+import time
+from typing import Any, Dict, List, Tuple
+
+import dspy
+
+from dspy_integration.domain.models import (
+ GENRES,
+ GenreType,
+ EvalResult,
+)
+from dspy_integration.domain.datasets import TRAINING_DATASET, TEST_DATASET
+from dspy_integration.domain.evaluation import evaluate_predictions
+from dspy_integration.presentation.console import (
+ console,
+ display_stage_header,
+ display_panel,
+ display_code,
+ display_step_header,
+ display_success,
+ display_tree,
+ display_results_table,
+ create_progress_context,
+)
+
+
+# =============================================================================
+# DSPY SIGNATURE DEFINITION
+# =============================================================================
+
+
+class MovieGenreSignature(dspy.Signature):
+ """
+ Classify a movie review into its primary genre based on the review text.
+
+ Consider the overall focus and tone of the review, not just individual keywords.
+ A review mentioning 'explosions' might be a drama if the focus is on characters.
+ A 'scary' movie might be a comedy if played for laughs.
+ """
+
+ review: str = dspy.InputField(desc="The movie review text to classify")
+ genre: GenreType = dspy.OutputField(
+ desc="The primary genre: action, comedy, drama, horror, sci-fi, or romance"
+ )
+ confidence: float = dspy.OutputField(desc="Confidence score between 0.0 and 1.0")
+ reasoning: str = dspy.OutputField(desc="Brief explanation for the classification")
+
+
+# =============================================================================
+# CODE EXAMPLES FOR DISPLAY
+# =============================================================================
+
+
+SIGNATURE_CODE_EXAMPLE = '''from typing import Literal
+
+# DSPy Signature WITH proper type constraints
+class MovieGenreSignature(dspy.Signature):
+ """Classify a movie review into its primary genre."""
+
+ review: str = dspy.InputField(desc="The movie review text")
+
+ # Literal type constrains output to valid genres only!
+ genre: Literal["action", "comedy", "drama", "horror", "sci-fi", "romance"] = \\
+ dspy.OutputField(desc="The primary genre")
+
+ confidence: float = dspy.OutputField(desc="Confidence 0.0-1.0")
+ reasoning: str = dspy.OutputField(desc="Brief explanation")
+
+# DSPy enforces the Literal constraint - no more "dramedy" or "thriller"!
+classify = dspy.ChainOfThought(MovieGenreSignature)'''
+
+
+# =============================================================================
+# MAIN STAGE FUNCTION
+# =============================================================================
+
+
+def run_stage1_raw_dspy(api_key: str) -> Tuple[EvalResult, Dict[str, Any]]:
+ """
+ Run Stage 1: Raw DSPy demonstration.
+
+ This demonstrates DSPy at its best with proper typed signatures.
+
+ Args:
+ api_key: OpenAI API key
+
+ Returns:
+ Tuple of (evaluation results, behind-the-scenes data)
+ """
+ display_stage_header("STAGE 1: Raw DSPy (Properly Implemented)", "blue")
+ _display_stage_overview()
+
+ # Configure DSPy
+ lm = dspy.LM("openai/gpt-4o-mini", api_key=api_key)
+ dspy.configure(lm=lm)
+
+ # Step 1: Show signature
+ _display_signature_explanation()
+
+ # Step 2: Create classifier and show unoptimized prompt
+ classify = dspy.ChainOfThought(MovieGenreSignature)
+ unoptimized_prompt = _capture_unoptimized_prompt(lm, classify)
+
+ # Step 3: Explain optimization
+ _display_optimization_explanation()
+
+ # Step 4: Run optimization
+ optimized_classify = _run_optimization(lm, classify)
+
+ # Step 5: Show optimized prompt
+ optimized_prompt = _capture_optimized_prompt(lm, optimized_classify)
+
+ # Step 6: Show selected demos
+ _display_selected_demos(optimized_classify)
+
+ # Step 7: Evaluate
+ eval_result, predictions = _evaluate_model(optimized_classify)
+
+ # Step 8: Display results
+ _display_stage_results(eval_result, predictions)
+
+ behind_scenes = _create_behind_scenes_data(
+ unoptimized_prompt, optimized_prompt, optimized_classify
+ )
+
+ return eval_result, behind_scenes
+
+
+# =============================================================================
+# DISPLAY HELPERS
+# =============================================================================
+
+
+def _display_stage_overview() -> None:
+ """Display stage 1 overview panel."""
+ content = """[green]DSPy STRENGTHS:[/green]
+• Typed signatures with Literal constraints (genre MUST be valid)
+• Automatic prompt optimization via BootstrapFewShot
+• Chain-of-thought reasoning for complex decisions
+• Systematic few-shot example selection
+
+[yellow]LIMITATIONS vs Atomic Agents:[/yellow]
+• No Pydantic ecosystem (validators, serializers, etc.)
+• Less integration with structured output tools like Instructor
+• Type hints are enforced by DSPy, not Python runtime"""
+
+ display_panel(content, "Stage 1 Overview", "blue")
+
+
+def _display_signature_explanation() -> None:
+ """Display explanation of DSPy typed signatures."""
+ display_step_header("Step 1.1: Define Typed DSPy Signature")
+ console.print("DSPy supports class-based signatures with Python type hints:\n")
+ display_code(SIGNATURE_CODE_EXAMPLE)
+
+
+def _display_optimization_explanation() -> None:
+ """Display explanation of how DSPy optimization works."""
+ display_step_header("Step 1.3: DSPy Optimization (BootstrapFewShot)")
+
+ content = """[cyan]What BootstrapFewShot does:[/cyan]
+
+1. Takes your labeled training examples
+2. Runs the LLM on each to generate 'traces' (reasoning chains)
+3. Filters traces that produce correct answers
+4. Selects the best traces as few-shot demonstrations
+5. Injects these into future prompts automatically
+
+[yellow]Key insight:[/yellow] DSPy doesn't just use your examples verbatim.
+It generates NEW reasoning and picks what actually works!"""
+
+ display_panel(content, "How DSPy Optimization Works", "cyan")
+
+
+# =============================================================================
+# PROMPT CAPTURE HELPERS
+# =============================================================================
+
+
+def _capture_unoptimized_prompt(
+ lm: dspy.LM,
+ classify: dspy.Module,
+) -> List[Dict[str, Any]]:
+ """Capture the unoptimized prompt from DSPy."""
+ display_step_header("Step 1.2: Unoptimized Prompt (What DSPy Generates)")
+
+ with dspy.context(lm=lm):
+ _ = classify(review=TRAINING_DATASET[0]["review"])
+
+ unoptimized_prompt = []
+ if lm.history:
+ last_call = lm.history[-1]
+ unoptimized_prompt = last_call.get("messages", [{}])
+
+ content = (
+ "[dim]Notice how DSPy includes the Literal type constraint in the prompt:[/dim]\n\n"
+ + json.dumps(unoptimized_prompt, indent=2)[:2000]
+ + "..."
+ )
+ display_panel(content, "Unoptimized DSPy Prompt (With Type Constraints)", "yellow")
+
+ return unoptimized_prompt
+
+
+def _capture_optimized_prompt(
+ lm: dspy.LM,
+ optimized_classify: dspy.Module,
+) -> List[Dict[str, Any]]:
+ """Capture the optimized prompt from DSPy."""
+ display_step_header("Step 1.4: Optimized Prompt (After DSPy Magic)")
+
+ with dspy.context(lm=lm):
+ _ = optimized_classify(review=TEST_DATASET[0]["review"])
+
+ optimized_prompt = []
+ if lm.history:
+ last_call = lm.history[-1]
+ optimized_prompt = last_call.get("messages", [{}])
+
+ prompt_str = json.dumps(optimized_prompt, indent=2)
+ truncated = prompt_str[:3500] + ("..." if len(prompt_str) > 3500 else "")
+
+ content = (
+ "[dim]Notice the auto-selected few-shot examples with reasoning:[/dim]\n\n" + truncated
+ )
+ display_panel(content, "Optimized DSPy Prompt (With Auto-Selected Examples)", "green")
+
+ return optimized_prompt
+
+
+# =============================================================================
+# OPTIMIZATION HELPERS
+# =============================================================================
+
+
+def _run_optimization(lm: dspy.LM, classify: dspy.Module) -> dspy.Module:
+ """Run DSPy optimization with BootstrapFewShot."""
+ # Prepare training set (first 30 examples)
+ train_examples = TRAINING_DATASET[:30]
+ trainset = [
+ dspy.Example(
+ review=ex["review"],
+ genre=ex["genre"],
+ confidence=0.85,
+ reasoning=f"This review demonstrates typical {ex['genre']} characteristics.",
+ ).with_inputs("review")
+ for ex in train_examples
+ ]
+
+ def genre_match(example, prediction, trace=None):
+ """Metric for optimization - checks if genre matches."""
+ pred_genre = str(prediction.genre).lower().strip()
+ expected_genre = str(example.genre).lower().strip()
+ return pred_genre == expected_genre
+
+ with create_progress_context(
+ "[cyan]Running DSPy optimization (30 training examples)..."
+ ) as progress:
+ task = progress.add_task("Optimizing...", total=None)
+
+ optimizer = dspy.BootstrapFewShot(
+ metric=genre_match,
+ max_bootstrapped_demos=4,
+ max_labeled_demos=4,
+ max_rounds=1,
+ )
+ optimized_classify = optimizer.compile(classify, trainset=trainset)
+ progress.remove_task(task)
+
+ display_success("Optimization complete!")
+ return optimized_classify
+
+
+def _display_selected_demos(optimized_classify: dspy.Module) -> None:
+ """Display the few-shot examples DSPy selected."""
+ display_step_header("Step 1.5: Few-Shot Examples DSPy Selected")
+
+ if hasattr(optimized_classify, "demos") and optimized_classify.demos:
+ items = []
+ for i, demo in enumerate(optimized_classify.demos[:4]):
+ review_text = str(getattr(demo, "review", "N/A"))[:70]
+ genre = getattr(demo, "genre", "N/A")
+ reasoning = str(getattr(demo, "reasoning", ""))[:80]
+
+ items.append(
+ {
+ "title": f"Example {i + 1}",
+ "children": [
+ f"Review: {review_text}...",
+ f"Genre: [green]{genre}[/green]",
+ f"Reasoning: [dim]{reasoning}...[/dim]",
+ ],
+ }
+ )
+
+ display_tree("Selected Demonstrations", items)
+ else:
+ console.print("[dim]Demo inspection not available for this predictor type[/dim]")
+
+
+# =============================================================================
+# EVALUATION HELPERS
+# =============================================================================
+
+
+def _evaluate_model(
+ optimized_classify: dspy.Module,
+) -> Tuple[EvalResult, List[Dict[str, Any]]]:
+ """Evaluate the optimized model on test set."""
+ display_step_header(
+ f"Step 1.6: Evaluation on Test Set ({len(TEST_DATASET)} challenging examples)"
+ )
+
+ predictions = []
+ start_time = time.time()
+
+ with create_progress_context("[cyan]Running predictions...") as progress:
+ task = progress.add_task("Predicting...", total=len(TEST_DATASET))
+
+ for test_ex in TEST_DATASET:
+ prediction = _get_single_prediction(optimized_classify, test_ex)
+ predictions.append(prediction)
+ progress.advance(task)
+
+ elapsed = time.time() - start_time
+ eval_result = evaluate_predictions(predictions, TEST_DATASET)
+ eval_result.avg_time = elapsed / len(TEST_DATASET)
+
+ return eval_result, predictions
+
+
+def _get_single_prediction(
+ classifier: dspy.Module,
+ test_example: Dict[str, str],
+) -> Dict[str, Any]:
+ """Get a single prediction from the classifier."""
+ try:
+ result = classifier(review=test_example["review"])
+ genre_val = str(result.genre).strip().lower()
+
+ # Validate genre
+ if genre_val not in GENRES:
+ genre_val = "error"
+
+ return {
+ "genre": genre_val,
+ "confidence": float(result.confidence) if hasattr(result, "confidence") else 0.5,
+ "reasoning": str(result.reasoning) if hasattr(result, "reasoning") else "N/A",
+ }
+ except Exception as e:
+ return {
+ "genre": "error",
+ "confidence": 0,
+ "reasoning": str(e),
+ }
+
+
+# =============================================================================
+# RESULTS DISPLAY
+# =============================================================================
+
+
+def _display_stage_results(
+ eval_result: EvalResult,
+ predictions: List[Dict[str, Any]],
+) -> None:
+ """Display stage 1 results and analysis."""
+ display_step_header("Step 1.7: Results")
+
+ # Count invalid genres
+ invalid_genres = [p["genre"] for p in predictions if p["genre"] not in GENRES]
+
+ content = f"""[green]DSPy TYPED SIGNATURE BENEFITS:[/green]
+• Genre constrained to valid options (invalid outputs: {len(invalid_genres)})
+• Automatic few-shot example selection
+• Chain-of-thought reasoning included
+
+[yellow]REMAINING LIMITATIONS:[/yellow]
+• No Pydantic validation ecosystem
+• Confidence not guaranteed to be 0-1 (no ge/le constraints)
+• Can't use Instructor's retry mechanisms
+• Type enforcement is DSPy-specific, not Python-native"""
+
+ display_panel(content, "DSPy Typed Signatures Assessment", "blue")
+ display_results_table(eval_result, "Stage 1 Results")
+
+
+def _create_behind_scenes_data(
+ unoptimized_prompt: List[Dict[str, Any]],
+ optimized_prompt: List[Dict[str, Any]],
+ optimized_classify: dspy.Module,
+) -> Dict[str, Any]:
+ """Create behind-the-scenes data for comparison."""
+ return {
+ "unoptimized_prompt_sample": str(unoptimized_prompt)[:500],
+ "optimized_prompt_sample": str(optimized_prompt)[:500],
+ "num_demos_selected": (
+ len(optimized_classify.demos) if hasattr(optimized_classify, "demos") else "N/A"
+ ),
+ "training_examples": 30,
+ }
diff --git a/atomic-examples/dspy-integration/dspy_integration/stages/stage2_atomic.py b/atomic-examples/dspy-integration/dspy_integration/stages/stage2_atomic.py
new file mode 100644
index 0000000..969f3ed
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/stages/stage2_atomic.py
@@ -0,0 +1,326 @@
+"""
+Stage 2: Raw Atomic Agents with Manual Prompts.
+
+This module demonstrates Atomic Agents' capabilities:
+- Full Pydantic ecosystem with runtime validation
+- Instructor integration for robust structured outputs
+- Guaranteed schema compliance
+
+Limitations shown:
+- Manual prompt engineering (guesswork)
+- No systematic way to improve prompts
+- No automatic few-shot selection
+
+Design: Single function entry point, internal helpers follow SRP.
+"""
+
+import time
+from typing import Any, Dict, List, Tuple
+
+import instructor
+import openai
+
+from atomic_agents.agents.atomic_agent import AgentConfig, AtomicAgent
+from atomic_agents.context.system_prompt_generator import SystemPromptGenerator
+
+from dspy_integration.domain.models import (
+ GENRES,
+ MovieGenreOutput,
+ MovieReviewInput,
+ EvalResult,
+)
+from dspy_integration.domain.datasets import TEST_DATASET
+from dspy_integration.domain.evaluation import evaluate_predictions
+from dspy_integration.presentation.console import (
+ console,
+ display_stage_header,
+ display_panel,
+ display_code,
+ display_step_header,
+ display_success,
+ display_results_table,
+ create_progress_context,
+)
+
+
+# =============================================================================
+# CODE EXAMPLES FOR DISPLAY
+# =============================================================================
+
+
+SCHEMA_CODE_EXAMPLE = '''class MovieGenreOutput(BaseIOSchema):
+ """Output schema for movie genre classification."""
+
+ genre: Literal["action", "comedy", "drama", "horror", "sci-fi", "romance"] = Field(
+ ...,
+ description="The primary genre of the movie.",
+ )
+ confidence: float = Field(
+ ...,
+ ge=0.0, le=1.0, # VALIDATED! Must be between 0 and 1
+ description="Confidence score between 0.0 and 1.0",
+ )
+ reasoning: str = Field(
+ ...,
+ description="Brief explanation for the classification.",
+ )
+
+# The LLM output MUST match this schema or it fails validation.
+# No more parsing "high" vs "0.85" vs "85%" - it's always a float!'''
+
+
+# =============================================================================
+# MAIN STAGE FUNCTION
+# =============================================================================
+
+
+def run_stage2_raw_atomic_agents(api_key: str) -> Tuple[EvalResult, Dict[str, Any]]:
+ """
+ Run Stage 2: Raw Atomic Agents demonstration.
+
+ This demonstrates Atomic Agents' beautiful structured outputs,
+ but with manual prompt engineering.
+
+ Args:
+ api_key: OpenAI API key
+
+ Returns:
+ Tuple of (evaluation results, behind-the-scenes data)
+ """
+ display_stage_header("STAGE 2: Raw Atomic Agents", "magenta")
+ _display_stage_overview()
+
+ # Step 1: Show Pydantic schema
+ _display_schema_explanation()
+
+ # Step 2: Show manual system prompt
+ system_prompt = _create_system_prompt()
+ generated_prompt = system_prompt.generate_prompt()
+ _display_manual_prompt(generated_prompt)
+ _display_manual_prompt_problem()
+
+ # Step 3: Create agent
+ agent = _create_agent(api_key, system_prompt)
+
+ # Step 4: Show schema enforcement
+ _display_schema_enforcement()
+
+ # Step 5: Evaluate
+ eval_result, predictions = _evaluate_agent(agent)
+
+ # Step 6: Display results
+ _display_stage_results(eval_result, predictions)
+
+ behind_scenes = {
+ "system_prompt": generated_prompt,
+ "schema_enforced": True,
+ "manual_engineering": True,
+ }
+
+ return eval_result, behind_scenes
+
+
+# =============================================================================
+# DISPLAY HELPERS
+# =============================================================================
+
+
+def _display_stage_overview() -> None:
+ """Display stage 2 overview panel."""
+ content = """[green]ATOMIC AGENTS STRENGTHS:[/green]
+• Full Pydantic ecosystem (validators, serializers, Field constraints)
+• Instructor integration for robust structured output
+• Python-native type safety with runtime validation
+• ge/le constraints on confidence (guaranteed 0-1)
+
+[yellow]LIMITATIONS:[/yellow]
+• Manual prompt engineering - no automatic optimization
+• No systematic few-shot example selection
+• Prompt improvements require guesswork and iteration"""
+
+ display_panel(content, "Stage 2 Overview", "magenta")
+
+
+def _display_schema_explanation() -> None:
+ """Display explanation of Pydantic schemas."""
+ display_step_header("Step 2.1: Define Pydantic Schema")
+ console.print("Atomic Agents uses Pydantic for type-safe outputs:\n")
+ display_code(SCHEMA_CODE_EXAMPLE)
+
+
+def _display_manual_prompt(generated_prompt: str) -> None:
+ """Display the manually crafted system prompt."""
+ display_step_header("Step 2.2: Manual System Prompt (The Guesswork)")
+
+ content = "[dim]This is the system prompt WE WROTE BY HAND:[/dim]\n\n" + generated_prompt
+ display_panel(content, "Manual System Prompt (Our Best Guess)", "yellow")
+
+
+def _display_manual_prompt_problem() -> None:
+ """Display the problem with manual prompt engineering."""
+ content = """[red]THE PROBLEM:[/red]
+
+We wrote this prompt based on intuition. Questions we can't answer:
+
+• Is 'Be decisive' helping or hurting accuracy?
+• Should we add few-shot examples? Which ones?
+• Is the step-by-step instruction actually useful?
+• Would different wording improve results?
+
+[yellow]Without DSPy, we're just guessing![/yellow]"""
+
+ display_panel(content, "The Manual Prompt Engineering Problem", "red")
+
+
+def _display_schema_enforcement() -> None:
+ """Display how schema enforcement works."""
+ display_step_header("Step 2.4: Schema Enforcement in Action")
+
+ content = """[cyan]What happens under the hood:[/cyan]
+
+1. Atomic Agents sends your prompt + Pydantic schema to the LLM
+2. Instructor (the library) converts schema to JSON Schema for the LLM
+3. LLM generates output attempting to match the schema
+4. Instructor validates the response against Pydantic
+5. If validation fails, Instructor retries with error feedback
+6. You get a guaranteed-valid Pydantic object or an exception
+
+[green]Result:[/green] genre is ALWAYS one of our 6 options,
+confidence is ALWAYS a float between 0 and 1!"""
+
+ display_panel(content, "How Schema Enforcement Works", "cyan")
+
+
+# =============================================================================
+# AGENT CREATION
+# =============================================================================
+
+
+def _create_system_prompt() -> SystemPromptGenerator:
+ """Create the manually crafted system prompt."""
+ return SystemPromptGenerator(
+ background=[
+ "You are a movie genre classification expert.",
+ "You analyze movie reviews and determine the primary genre.",
+ f"Valid genres are: {', '.join(GENRES)}",
+ ],
+ steps=[
+ "Read the review carefully.",
+ "Identify key genre indicators (action words, emotional language, etc.).",
+ "Consider the overall tone and subject matter.",
+ "Select the single most appropriate genre.",
+ "Provide a confidence score based on how clear the genre signals are.",
+ ],
+ output_instructions=[
+ "Be decisive - pick ONE primary genre even if multiple could apply.",
+ "Confidence should be 0.7-1.0 for clear cases, 0.5-0.7 for ambiguous ones.",
+ "Keep reasoning brief but specific to the review.",
+ ],
+ )
+
+
+def _create_agent(
+ api_key: str,
+ system_prompt: SystemPromptGenerator,
+) -> AtomicAgent:
+ """Create the Atomic Agent with schema validation."""
+ display_step_header("Step 2.3: Create Atomic Agent")
+
+ client = instructor.from_openai(openai.OpenAI(api_key=api_key))
+
+ agent = AtomicAgent[MovieReviewInput, MovieGenreOutput](
+ config=AgentConfig(
+ client=client,
+ model="gpt-4o-mini",
+ system_prompt_generator=system_prompt,
+ )
+ )
+
+ display_success("Agent created with schema validation")
+ return agent
+
+
+# =============================================================================
+# EVALUATION HELPERS
+# =============================================================================
+
+
+def _evaluate_agent(
+ agent: AtomicAgent,
+) -> Tuple[EvalResult, List[Dict[str, Any]]]:
+ """Evaluate the agent on test set."""
+ display_step_header("Step 2.5: Evaluation on Test Set")
+
+ predictions = []
+ start_time = time.time()
+
+ with create_progress_context("[magenta]Running predictions...") as progress:
+ task = progress.add_task("Predicting...", total=len(TEST_DATASET))
+
+ for test_ex in TEST_DATASET:
+ prediction = _get_single_prediction(agent, test_ex)
+ predictions.append(prediction)
+ progress.advance(task)
+
+ elapsed = time.time() - start_time
+ eval_result = evaluate_predictions(predictions, TEST_DATASET)
+ eval_result.avg_time = elapsed / len(TEST_DATASET)
+
+ return eval_result, predictions
+
+
+def _get_single_prediction(
+ agent: AtomicAgent,
+ test_example: Dict[str, str],
+) -> Dict[str, Any]:
+ """Get a single prediction from the agent."""
+ try:
+ result = agent.run(MovieReviewInput(review=test_example["review"]))
+ return {
+ "genre": result.genre, # Already validated by Pydantic!
+ "confidence": result.confidence, # Already a float!
+ "reasoning": result.reasoning,
+ }
+ except Exception as e:
+ return {
+ "genre": "error",
+ "confidence": 0,
+ "reasoning": str(e),
+ }
+
+
+# =============================================================================
+# RESULTS DISPLAY
+# =============================================================================
+
+
+def _display_stage_results(
+ eval_result: EvalResult,
+ predictions: List[Dict[str, Any]],
+) -> None:
+ """Display stage 2 results and analysis."""
+ display_step_header("Step 2.6: The Benefit - Type-Safe Outputs")
+
+ # Show sample outputs
+ samples = "\n".join(
+ [
+ f" • genre='{predictions[i]['genre']}' (Literal) "
+ f"confidence={predictions[i]['confidence']:.2f} (float)"
+ for i in range(min(3, len(predictions)))
+ ]
+ )
+
+ content = f"""[green]ATOMIC AGENTS ADVANTAGE:[/green]
+
+Look at these outputs - perfectly structured:
+{samples}
+
+[cyan]Benefits:[/cyan]
+• genre is guaranteed to be one of our 6 valid options
+• confidence is always a float between 0.0 and 1.0
+• No parsing needed - direct attribute access
+• IDE autocomplete works perfectly
+• Downstream code can trust the types"""
+
+ display_panel(content, "Structured Output Benefits", "green")
+ display_results_table(eval_result, "Stage 2 Results", show_confidence=True)
diff --git a/atomic-examples/dspy-integration/dspy_integration/stages/stage3_combined.py b/atomic-examples/dspy-integration/dspy_integration/stages/stage3_combined.py
new file mode 100644
index 0000000..71b847c
--- /dev/null
+++ b/atomic-examples/dspy-integration/dspy_integration/stages/stage3_combined.py
@@ -0,0 +1,349 @@
+"""
+Stage 3: DSPy + Atomic Agents Combined.
+
+This module demonstrates the best of both worlds:
+- DSPy's automatic prompt optimization
+- Atomic Agents' type-safe structured outputs
+
+The bridge module connects both frameworks, enabling:
+- Pydantic schemas as DSPy signatures
+- DSPy optimizers for Atomic Agents
+- Validated, optimized outputs
+
+Design: Single function entry point, internal helpers follow SRP.
+"""
+
+import json
+import time
+from typing import Any, Dict, List, Tuple
+
+import dspy
+
+from dspy_integration.bridge import DSPyAtomicModule, create_dspy_example
+from dspy_integration.domain.models import (
+ MovieGenreOutput,
+ MovieReviewInput,
+ EvalResult,
+)
+from dspy_integration.domain.datasets import TRAINING_DATASET, TEST_DATASET
+from dspy_integration.domain.evaluation import evaluate_predictions
+from dspy_integration.presentation.console import (
+ display_stage_header,
+ display_panel,
+ display_code,
+ display_step_header,
+ display_success,
+ display_results_table,
+ create_progress_context,
+)
+
+
+# =============================================================================
+# CODE EXAMPLES FOR DISPLAY
+# =============================================================================
+
+
+BRIDGE_CODE_EXAMPLE = """# The bridge combines both frameworks:
+module = DSPyAtomicModule(
+ input_schema=MovieReviewInput, # Pydantic input validation
+ output_schema=MovieGenreOutput, # Pydantic output structure
+ instructions="Classify the movie review into a genre.",
+ use_chain_of_thought=True, # DSPy's reasoning capability
+)
+
+# Behind the scenes:
+# 1. Pydantic schemas are converted to DSPy signatures
+# 2. DSPy handles prompt construction and optimization
+# 3. Outputs are validated against Pydantic schemas
+# 4. You get type-safe results that DSPy optimized!"""
+
+
+# =============================================================================
+# MAIN STAGE FUNCTION
+# =============================================================================
+
+
+def run_stage3_combined(api_key: str) -> Tuple[EvalResult, Dict[str, Any]]:
+ """
+ Run Stage 3: Combined DSPy + Atomic Agents demonstration.
+
+ This demonstrates the best of both worlds - DSPy optimization
+ with Atomic Agents type safety.
+
+ Args:
+ api_key: OpenAI API key
+
+ Returns:
+ Tuple of (evaluation results, behind-the-scenes data)
+ """
+ display_stage_header("STAGE 3: DSPy + Atomic Agents", "green")
+ _display_stage_overview()
+
+ # Configure DSPy
+ lm = dspy.LM("openai/gpt-4o-mini", api_key=api_key)
+ dspy.configure(lm=lm)
+
+ # Step 1: Show bridge module
+ _display_bridge_explanation()
+
+ # Step 2: Create module
+ module = _create_bridge_module()
+
+ # Step 3: Show schema conversion
+ _display_schema_conversion()
+
+ # Step 4: Create training examples
+ trainset = _create_training_set()
+
+ # Step 5: Run optimization
+ optimized_module = _run_optimization(module, trainset)
+
+ # Step 6: Show optimized prompt
+ optimized_prompt = _capture_optimized_prompt(lm, optimized_module)
+
+ # Step 7: Evaluate
+ eval_result, predictions = _evaluate_module(optimized_module)
+
+ # Step 8: Display results
+ _display_stage_results(eval_result)
+
+ behind_scenes = {
+ "optimized_prompt_sample": optimized_prompt[:1000] if optimized_prompt else "N/A",
+ "schema_enforced": True,
+ "dspy_optimized": True,
+ }
+
+ return eval_result, behind_scenes
+
+
+# =============================================================================
+# DISPLAY HELPERS
+# =============================================================================
+
+
+def _display_stage_overview() -> None:
+ """Display stage 3 overview panel."""
+ content = """[green]THE SOLUTION:[/green]
+Combine DSPy's automatic optimization with Atomic Agents' type safety!
+
+[cyan]WHAT WE GET:[/cyan]
+• DSPy automatically finds the best prompts and examples
+• Atomic Agents guarantees output structure
+• Measurable improvements through optimization
+• Production-ready typed outputs
+
+[yellow]THE BEST OF BOTH WORLDS[/yellow]"""
+
+ display_panel(content, "Stage 3 Overview", "green")
+
+
+def _display_bridge_explanation() -> None:
+ """Display explanation of the bridge module."""
+ display_step_header("Step 3.1: The Bridge - DSPyAtomicModule")
+ display_code(BRIDGE_CODE_EXAMPLE)
+
+
+def _display_schema_conversion() -> None:
+ """Display how schemas are converted to signatures."""
+ display_step_header("Step 3.2: Schema-to-Signature Conversion")
+
+ content = """[cyan]Pydantic Schema → DSPy Signature:[/cyan]
+
+Input fields: review (str)
+Output fields: genre (Literal), confidence (float), reasoning (str)
+
+[dim]The bridge automatically converts Pydantic field descriptions
+into DSPy field descriptors, preserving all metadata.[/dim]"""
+
+ display_panel(content, "Automatic Conversion", "cyan")
+
+
+def _display_training_explanation() -> None:
+ """Display explanation of type-safe training examples."""
+ display_step_header("Step 3.3: Type-Safe Training Examples")
+
+ content = """[cyan]Creating training examples with validation:[/cyan]
+
+Each example is validated against our Pydantic schemas!
+If you accidentally put confidence=1.5 or genre='thriller',
+you get an immediate error - not a silent failure later."""
+
+ display_panel(content, "Validated Training Data", "cyan")
+
+
+# =============================================================================
+# MODULE CREATION
+# =============================================================================
+
+
+def _create_bridge_module() -> DSPyAtomicModule:
+ """Create the DSPy-Atomic bridge module."""
+ return DSPyAtomicModule(
+ input_schema=MovieReviewInput,
+ output_schema=MovieGenreOutput,
+ instructions="Classify the movie review into its primary genre. Be accurate and provide reasoning.",
+ use_chain_of_thought=True,
+ )
+
+
+def _create_training_set() -> List[dspy.Example]:
+ """Create validated training examples."""
+ _display_training_explanation()
+
+ # Use 40 examples for training
+ train_examples = TRAINING_DATASET[:40]
+ trainset = []
+
+ for ex in train_examples:
+ trainset.append(
+ create_dspy_example(
+ MovieReviewInput,
+ MovieGenreOutput,
+ {"review": ex["review"]},
+ {
+ "genre": ex["genre"],
+ "confidence": 0.85,
+ "reasoning": f"The review shows typical {ex['genre']} characteristics.",
+ },
+ )
+ )
+
+ display_success(f"Created {len(trainset)} validated training examples")
+ return trainset
+
+
+# =============================================================================
+# OPTIMIZATION HELPERS
+# =============================================================================
+
+
+def _run_optimization(
+ module: DSPyAtomicModule,
+ trainset: List[dspy.Example],
+) -> DSPyAtomicModule:
+ """Run DSPy optimization on the bridge module."""
+ display_step_header("Step 3.4: DSPy Optimization (With Schema Awareness)")
+
+ def typed_genre_match(example, prediction, trace=None):
+ """Metric that works with typed outputs."""
+ pred_genre = str(prediction.genre).lower().strip()
+ expected_genre = str(example.genre).lower().strip()
+ return pred_genre == expected_genre
+
+ with create_progress_context(
+ f"[green]Running optimization ({len(trainset)} training examples)..."
+ ) as progress:
+ task = progress.add_task("Optimizing...", total=None)
+
+ optimizer = dspy.BootstrapFewShot(
+ metric=typed_genre_match,
+ max_bootstrapped_demos=4,
+ max_labeled_demos=4,
+ max_rounds=1,
+ )
+ optimized_module = optimizer.compile(module, trainset=trainset)
+ progress.remove_task(task)
+
+ display_success("Optimization complete!")
+ return optimized_module
+
+
+def _capture_optimized_prompt(
+ lm: dspy.LM,
+ optimized_module: DSPyAtomicModule,
+) -> str:
+ """Capture the optimized prompt."""
+ display_step_header("Step 3.5: The Optimized Prompt (Exposed!)")
+
+ with dspy.context(lm=lm):
+ _ = optimized_module(review=TEST_DATASET[0]["review"])
+
+ prompt_str = ""
+ if lm.history:
+ last_call = lm.history[-1]
+ optimized_prompt = last_call.get("messages", [{}])
+ prompt_str = json.dumps(optimized_prompt, indent=2)
+
+ truncated = prompt_str[:2500] + ("..." if len(prompt_str) > 2500 else "")
+ content = "[dim]This is what DSPy + Atomic Agents sends to the LLM:[/dim]\n\n" + truncated
+ display_panel(content, "Final Optimized Prompt", "green")
+
+ return prompt_str
+
+
+# =============================================================================
+# EVALUATION HELPERS
+# =============================================================================
+
+
+def _evaluate_module(
+ optimized_module: DSPyAtomicModule,
+) -> Tuple[EvalResult, List[Dict[str, Any]]]:
+ """Evaluate the optimized module on test set."""
+ display_step_header("Step 3.6: Evaluation with Type-Safe Outputs")
+
+ predictions = []
+ start_time = time.time()
+
+ with create_progress_context("[green]Running predictions...") as progress:
+ task = progress.add_task("Predicting...", total=len(TEST_DATASET))
+
+ for test_ex in TEST_DATASET:
+ prediction = _get_single_prediction(optimized_module, test_ex)
+ predictions.append(prediction)
+ progress.advance(task)
+
+ elapsed = time.time() - start_time
+ eval_result = evaluate_predictions(predictions, TEST_DATASET)
+ eval_result.avg_time = elapsed / len(TEST_DATASET)
+
+ return eval_result, predictions
+
+
+def _get_single_prediction(
+ module: DSPyAtomicModule,
+ test_example: Dict[str, str],
+) -> Dict[str, Any]:
+ """Get a single validated prediction."""
+ try:
+ # Use run_validated to get Pydantic-validated output
+ validated_result = module.run_validated(review=test_example["review"])
+
+ return {
+ "genre": validated_result.genre, # Guaranteed Literal type!
+ "confidence": validated_result.confidence, # Guaranteed 0-1 float!
+ "reasoning": validated_result.reasoning,
+ }
+ except Exception as e:
+ return {
+ "genre": "error",
+ "confidence": 0,
+ "reasoning": str(e),
+ }
+
+
+# =============================================================================
+# RESULTS DISPLAY
+# =============================================================================
+
+
+def _display_stage_results(eval_result: EvalResult) -> None:
+ """Display stage 3 results and analysis."""
+ display_step_header("Step 3.7: The Combined Benefits")
+
+ content = """[green]✓ DSPy BENEFITS:[/green]
+• Automatic few-shot example selection
+• Optimized prompt instructions
+• Chain-of-thought reasoning
+• Measurable improvement through metrics
+
+[green]✓ ATOMIC AGENTS BENEFITS:[/green]
+• genre is Literal['action','comedy',...] - always valid
+• confidence is float with ge=0, le=1 - always in range
+• Full IDE autocomplete and type checking
+• Pydantic validation catches any LLM mistakes
+
+[yellow]COMBINED:[/yellow] Optimized prompts + Guaranteed structure!"""
+
+ display_panel(content, "The Best of Both Worlds", "green")
+ display_results_table(eval_result, "Stage 3 Results", show_confidence=True)
diff --git a/atomic-examples/dspy-integration/pyproject.toml b/atomic-examples/dspy-integration/pyproject.toml
index 655dde6..b768ce4 100644
--- a/atomic-examples/dspy-integration/pyproject.toml
+++ b/atomic-examples/dspy-integration/pyproject.toml
@@ -24,5 +24,11 @@ dependencies = [
"pydantic>=2.0.0",
]
+[dependency-groups]
+dev = [
+ "black>=24.10.0",
+ "flake8>=7.3.0",
+]
+
[tool.uv.sources]
atomic-agents = { workspace = true }
diff --git a/uv.lock b/uv.lock
index be329ff..5c50e28 100644
--- a/uv.lock
+++ b/uv.lock
@@ -974,6 +974,12 @@ dependencies = [
{ name = "rich" },
]
+[package.dev-dependencies]
+dev = [
+ { name = "black" },
+ { name = "flake8" },
+]
+
[package.metadata]
requires-dist = [
{ name = "atomic-agents", editable = "." },
@@ -985,6 +991,12 @@ requires-dist = [
{ name = "rich", specifier = ">=13.7.0" },
]
+[package.metadata.requires-dev]
+dev = [
+ { name = "black", specifier = ">=24.10.0" },
+ { name = "flake8", specifier = ">=7.3.0" },
+]
+
[[package]]
name = "durationpy"
version = "0.10"