pixie-examples 0.1.1.dev3__py3-none-any.whl

examples/openai_agents_sdk/financial_research_agent.py

@@ -0,0 +1,328 @@
+"""
+Financial Research Agent - Multi-Step Workflow - Pixie Integration
+
+This example demonstrates a structured financial research workflow with multiple
+specialized agents working together to produce comprehensive financial analysis reports.
+
+Pattern: Multi-Step Workflow with Multi-Agent
+Original: https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent
+
+Architecture:
+1. Planner Agent - Creates search plan
+2. Search Agent - Performs web searches
+3. Specialist Analysts - Financial fundamentals & risk analysis
+4. Writer Agent - Synthesizes final report
+5. Verifier Agent - Quality checks the report
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+
+from pydantic import BaseModel
+from agents import Agent, Runner, RunResult, RunResultStreaming, WebSearchTool
+import pixie
+
+
+# ============================================================================
+# AGENT DEFINITIONS
+# ============================================================================
+
+
+# --- Planner Agent ---
+class FinancialSearchItem(BaseModel):
+    """A single search to perform"""
+
+    reason: str
+    """Your reasoning for why this search is relevant."""
+
+    query: str
+    """The search term to feed into a web (or file) search."""
+
+
+class FinancialSearchPlan(BaseModel):
+    """Plan of searches to perform"""
+
+    searches: list[FinancialSearchItem]
+    """A list of searches to perform."""
+
+
+PLANNER_PROMPT = (
+    "You are a financial research planner. Given a request for financial analysis, "
+    "produce a set of web searches to gather the context needed. Aim for recent "
+    "headlines, earnings calls or 10‑K snippets, analyst commentary, and industry background. "
+    "Output between 5 and 15 search terms to query for."
+)
+
+planner_agent = Agent(
+    name="FinancialPlannerAgent",
+    instructions=PLANNER_PROMPT,
+    model="o3-mini",
+    output_type=FinancialSearchPlan,
+)
+
+
+# --- Search Agent ---
+SEARCH_INSTRUCTIONS = (
+    "You are a research assistant specializing in financial topics. "
+    "Given a search term, use web search to retrieve up‑to‑date context and "
+    "produce a short summary of at most 300 words. Focus on key numbers, events, "
+    "or quotes that will be useful to a financial analyst."
+)
+
+search_agent = Agent(
+    name="FinancialSearchAgent",
+    model="gpt-5.2",
+    instructions=SEARCH_INSTRUCTIONS,
+    tools=[WebSearchTool()],
+)
+
+
+# --- Analyst Agents ---
+class AnalysisSummary(BaseModel):
+    """Analysis output from specialist agents"""
+
+    summary: str
+    """Short text summary for this aspect of the analysis."""
+
+
+FINANCIALS_PROMPT = (
+    "You are a financial analyst focused on company fundamentals such as revenue, "
+    "profit, margins and growth trajectory. Given a collection of web (and optional file) "
+    "search results about a company, write a concise analysis of its recent financial "
+    "performance. Pull out key metrics or quotes. Keep it under 2 paragraphs."
+)
+
+financials_agent = Agent(
+    name="FundamentalsAnalystAgent",
+    instructions=FINANCIALS_PROMPT,
+    output_type=AnalysisSummary,
+)
+
+RISK_PROMPT = (
+    "You are a risk analyst looking for potential red flags in a company's outlook. "
+    "Given background research, produce a short analysis of risks such as competitive threats, "
+    "regulatory issues, supply chain problems, or slowing growth. Keep it under 2 paragraphs."
+)
+
+risk_agent = Agent(
+    name="RiskAnalystAgent",
+    instructions=RISK_PROMPT,
+    output_type=AnalysisSummary,
+)
+
+
+# --- Writer Agent ---
+class FinancialReportData(BaseModel):
+    """Final report output"""
+
+    short_summary: str
+    """A short 2‑3 sentence executive summary."""
+
+    markdown_report: str
+    """The full markdown report."""
+
+    follow_up_questions: list[str]
+    """Suggested follow‑up questions for further research."""
+
+
+WRITER_PROMPT = (
+    "You are a senior financial analyst. You will be provided with the original query and "
+    "a set of raw search summaries. Your task is to synthesize these into a long‑form markdown "
+    "report (at least several paragraphs) including a short executive summary and follow‑up "
+    "questions. If needed, you can call the available analysis tools (e.g. fundamentals_analysis, "
+    "risk_analysis) to get short specialist write‑ups to incorporate."
+)
+
+writer_agent = Agent(
+    name="FinancialWriterAgent",
+    instructions=WRITER_PROMPT,
+    model="gpt-5.2",
+    output_type=FinancialReportData,
+)
+
+
+# --- Verifier Agent ---
+class VerificationResult(BaseModel):
+    """Verification outcome"""
+
+    verified: bool
+    """Whether the report seems coherent and plausible."""
+
+    issues: str
+    """If not verified, describe the main issues or concerns."""
+
+
+VERIFIER_PROMPT = (
+    "You are a meticulous auditor. You have been handed a financial analysis report. "
+    "Your job is to verify the report is internally consistent, clearly sourced, and makes "
+    "no unsupported claims. Point out any issues or uncertainties."
+)
+
+verifier_agent = Agent(
+    name="VerificationAgent",
+    instructions=VERIFIER_PROMPT,
+    model="gpt-5.2",
+    output_type=VerificationResult,
+)
+
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+
+async def _summary_extractor(run_result: RunResult | RunResultStreaming) -> str:
+    """Custom output extractor for sub‑agents that return an AnalysisSummary."""
+    return str(run_result.final_output.summary)
+
+
+async def _plan_searches(query: str) -> FinancialSearchPlan:
+    """Create a search plan for the given query"""
+    result = await Runner.run(planner_agent, f"Query: {query}")
+    return result.final_output_as(FinancialSearchPlan)
+
+
+async def _perform_search(item: FinancialSearchItem) -> str | None:
+    """Perform a single search"""
+    input_data = f"Search term: {item.query}\nReason: {item.reason}"
+    try:
+        result = await Runner.run(search_agent, input_data)
+        return str(result.final_output)
+    except Exception:
+        return None
+
+
+async def _perform_searches(search_plan: FinancialSearchPlan) -> Sequence[str]:
+    """Perform all searches in parallel"""
+    tasks = [
+        asyncio.create_task(_perform_search(item)) for item in search_plan.searches
+    ]
+    results: list[str] = []
+
+    for task in asyncio.as_completed(tasks):
+        result = await task
+        if result is not None:
+            results.append(result)
+
+    return results
+
+
+async def _write_report(
+    query: str, search_results: Sequence[str]
+) -> FinancialReportData:
+    """Write the final report using specialist tools"""
+    # Expose the specialist analysts as tools
+    fundamentals_tool = financials_agent.as_tool(
+        tool_name="fundamentals_analysis",
+        tool_description="Use to get a short write‑up of key financial metrics",
+        custom_output_extractor=_summary_extractor,
+    )
+    risk_tool = risk_agent.as_tool(
+        tool_name="risk_analysis",
+        tool_description="Use to get a short write‑up of potential red flags",
+        custom_output_extractor=_summary_extractor,
+    )
+
+    writer_with_tools = writer_agent.clone(tools=[fundamentals_tool, risk_tool])
+    input_data = f"Original query: {query}\nSummarized search results: {search_results}"
+
+    result = await Runner.run(writer_with_tools, input_data)
+    return result.final_output_as(FinancialReportData)
+
+
+async def _verify_report(report: FinancialReportData) -> VerificationResult:
+    """Verify report quality"""
+    result = await Runner.run(verifier_agent, report.markdown_report)
+    return result.final_output_as(VerificationResult)
+
+
+# ============================================================================
+# PIXIE APP
+# ============================================================================
+
+
+@pixie.app
+async def openai_agents_financial_research(
+    query: str,
+) -> pixie.PixieGenerator[str, None]:
+    """
+    Comprehensive financial research agent with multi-step workflow.
+
+    This agent orchestrates a full research workflow:
+    1. Plans searches based on the query
+    2. Executes web searches in parallel
+    3. Analyzes fundamentals and risks using specialist agents
+    4. Synthesizes a comprehensive markdown report
+    5. Verifies the report for quality and consistency
+
+    Args:
+        query: Financial research question or company to analyze
+
+    Yields:
+        Progress updates and the final comprehensive report
+
+    Example queries:
+        - "Write up an analysis of Apple Inc.'s most recent quarter."
+        - "Analyze Tesla's financial performance and growth prospects"
+        - "What are the key risks facing Microsoft in 2026?"
+    """
+    yield f"🔍 Starting financial research for: {query}\n"
+
+    # Step 1: Planning
+    yield "📋 Planning searches..."
+    search_plan = await _plan_searches(query)
+    num_searches = len(search_plan.searches)
+    yield f"✓ Will perform {num_searches} searches\n"
+
+    # Show search plan
+    yield "Search plan:"
+    for i, item in enumerate(search_plan.searches[:5], 1):  # Show first 5
+        yield f"  {i}. {item.query} - {item.reason}"
+    if num_searches > 5:
+        yield f"  ... and {num_searches - 5} more"
+    yield ""
+
+    # Step 2: Searching
+    yield f"🔎 Executing {num_searches} searches in parallel..."
+    search_results = await _perform_searches(search_plan)
+    yield f"✓ Completed {len(search_results)} successful searches\n"
+
+    # Step 3: Writing report
+    yield "✍️ Analyzing data and writing comprehensive report..."
+    yield "(This may take a minute as specialist analysts are consulted...)"
+    report = await _write_report(query, search_results)
+    yield "✓ Report complete\n"
+
+    # Step 4: Verification
+    yield "🔍 Verifying report quality..."
+    verification = await _verify_report(report)
+    if verification.verified:
+        yield "✓ Report verified\n"
+    else:
+        yield f"⚠️ Verification issues found: {verification.issues}\n"
+
+    # Output summary
+    yield "=" * 60
+    yield "EXECUTIVE SUMMARY"
+    yield "=" * 60
+    yield report.short_summary
+    yield ""
+
+    # Full report
+    yield "=" * 60
+    yield "FULL REPORT"
+    yield "=" * 60
+    yield report.markdown_report
+    yield ""
+
+    # Follow-up questions
+    yield "=" * 60
+    yield "SUGGESTED FOLLOW-UP QUESTIONS"
+    yield "=" * 60
+    for i, question in enumerate(report.follow_up_questions, 1):
+        yield f"{i}. {question}"
+
+    yield ""
+    yield "✓ Financial research complete!"

examples/openai_agents_sdk/llm_as_a_judge.py

@@ -0,0 +1,108 @@
+"""
+LLM as a Judge Pattern - Pixie Integration
+
+This example demonstrates the LLM as a judge pattern where one agent generates content
+and another agent evaluates it iteratively until quality standards are met.
+
+Pattern: Multi-Step Workflow
+Original: https://github.com/openai/openai-agents-python/blob/main/examples/agent_patterns/llm_as_a_judge.py
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from agents import Agent, ItemHelpers, Runner, TResponseInputItem
+import pixie
+
+
+# Story outline generator agent
+story_outline_generator = Agent(
+    name="story_outline_generator",
+    instructions=(
+        "You generate a very short story outline based on the user's input. "
+        "If there is any feedback provided, use it to improve the outline."
+    ),
+)
+
+
+@dataclass
+class EvaluationFeedback:
+    """Feedback from the evaluator agent"""
+
+    feedback: str
+    score: Literal["pass", "needs_improvement", "fail"]
+
+
+# Evaluator agent that judges the story outline
+evaluator = Agent[None](
+    name="evaluator",
+    instructions=(
+        "You evaluate a story outline and decide if it's good enough. "
+        "If it's not good enough, you provide feedback on what needs to be improved. "
+        "Never give it a pass on the first try. After 5 attempts, you can give "
+        "it a pass if the story outline is good enough - do not go for perfection"
+    ),
+    output_type=EvaluationFeedback,
+)
+
+
+@pixie.app
+async def openai_agents_llm_as_a_judge(topic: str) -> pixie.PixieGenerator[str, None]:
+    """
+    Generate a story outline using LLM-as-a-judge pattern.
+
+    The story generator creates an outline, which is then evaluated by a judge agent.
+    The process repeats until the judge is satisfied with the quality.
+
+    Args:
+        topic: The story topic to generate an outline for
+
+    Yields:
+        Status updates and the final story outline
+    """
+    yield f"Starting story generation for: {topic}"
+
+    input_items: list[TResponseInputItem] = [{"content": topic, "role": "user"}]
+    latest_outline: str | None = None
+
+    iteration = 0
+    max_iterations = 10
+
+    while iteration < max_iterations:
+        iteration += 1
+        yield f"\n--- Iteration {iteration} ---"
+
+        # Generate story outline
+        yield "Generating story outline..."
+        story_outline_result = await Runner.run(
+            story_outline_generator,
+            input_items,
+        )
+        input_items = story_outline_result.to_input_list()
+        latest_outline = ItemHelpers.text_message_outputs(
+            story_outline_result.new_items
+        )
+        yield f"Story outline generated:\n{latest_outline}"
+
+        # Evaluate the outline
+        yield "\nEvaluating outline..."
+        evaluator_result = await Runner.run(evaluator, input_items)
+        result: EvaluationFeedback = evaluator_result.final_output
+
+        yield f"Evaluator score: {result.score}"
+
+        if result.score == "pass":
+            yield "\n✓ Story outline is good enough!"
+            break
+
+        # Provide feedback for next iteration
+        yield f"Feedback: {result.feedback}"
+        yield "Re-running with feedback..."
+        input_items.append({"content": f"Feedback: {result.feedback}", "role": "user"})
+
+    if iteration >= max_iterations:
+        yield f"\n⚠ Reached maximum iterations ({max_iterations})"
+
+    yield f"\n=== Final Story Outline ===\n{latest_outline}"

examples/openai_agents_sdk/routing.py

@@ -0,0 +1,177 @@
+"""
+Routing/Handoffs Pattern - Pixie Integration
+
+This example demonstrates agent routing where a triage agent hands off to specialized
+language agents based on the user's language preference.
+
+Pattern: Graph/State-Machine (Routing)
+Original: https://github.com/openai/openai-agents-python/blob/main/examples/agent_patterns/routing.py
+"""
+
+from __future__ import annotations
+
+
+from openai.types.responses import ResponseContentPartDoneEvent, ResponseTextDeltaEvent
+from agents import Agent, RawResponsesStreamEvent, Runner, TResponseInputItem
+import pixie
+
+
+# ============================================================================
+# LANGUAGE AGENTS
+# ============================================================================
+
+french_agent = Agent(
+    name="french_agent",
+    instructions="You only speak French",
+)
+
+spanish_agent = Agent(
+    name="spanish_agent",
+    instructions="You only speak Spanish",
+)
+
+english_agent = Agent(
+    name="english_agent",
+    instructions="You only speak English",
+)
+
+triage_agent = Agent(
+    name="triage_agent",
+    instructions="Handoff to the appropriate agent based on the language of the request.",
+    handoffs=[french_agent, spanish_agent, english_agent],
+)
+
+
+@pixie.app
+async def openai_multilingual_routing() -> pixie.PixieGenerator[str, str]:
+    """
+    Multi-agent language routing system with streaming responses.
+
+    The triage agent receives messages and hands off to the appropriate language
+    specialist agent (French, Spanish, or English) based on the detected language.
+
+    Responses are streamed in real-time to provide immediate feedback.
+
+    Yields:
+        Streamed agent responses
+
+    Receives:
+        User messages in any supported language via InputRequired
+    """
+    agent = triage_agent
+    inputs: list[TResponseInputItem] = []
+
+    yield "Hi! We speak French, Spanish and English. How can I help?"
+    yield "(Type 'exit' to quit)"
+
+    while True:
+        # Get user message
+        user_msg = yield pixie.InputRequired(str)
+
+        # Check for exit
+        if user_msg.lower() in {"exit", "quit", "bye"}:
+            yield "Goodbye! Au revoir! ¡Adiós!"
+            break
+
+        inputs.append({"content": user_msg, "role": "user"})
+
+        # Run agent with streaming
+        result = Runner.run_streamed(
+            agent,
+            input=inputs,
+        )
+
+        # Stream the response
+        current_response = []
+        async for event in result.stream_events():
+            if not isinstance(event, RawResponsesStreamEvent):
+                continue
+
+            data = event.data
+
+            if isinstance(data, ResponseTextDeltaEvent):
+                # Stream text deltas
+                current_response.append(data.delta)
+                yield data.delta
+
+            elif isinstance(data, ResponseContentPartDoneEvent):
+                # Content part complete
+                yield "\n"
+
+        # Update state for next turn
+        inputs = result.to_input_list()
+        agent = result.current_agent
+
+        # Show which agent handled the request
+        agent_name = agent.name
+        yield f"\n[Handled by: {agent_name}]"
+
+
+@pixie.app
+async def openai_multilingual_routing_simple(
+    initial_message: str,
+) -> pixie.PixieGenerator[str, str]:
+    """
+    Simplified multilingual routing with single initial message.
+
+    This version accepts an initial message and then enters an interactive loop.
+    Good for testing with a specific language right away.
+
+    Args:
+        initial_message: The first message to send (in any supported language)
+
+    Yields:
+        Streamed agent responses
+
+    Receives:
+        Follow-up user messages via InputRequired
+    """
+    agent = triage_agent
+    inputs: list[TResponseInputItem] = [{"content": initial_message, "role": "user"}]
+
+    yield f"Processing your message: {initial_message[:50]}...\n"
+
+    # Process initial message
+    result = Runner.run_streamed(agent, input=inputs)
+
+    async for event in result.stream_events():
+        if not isinstance(event, RawResponsesStreamEvent):
+            continue
+
+        data = event.data
+        if isinstance(data, ResponseTextDeltaEvent):
+            yield data.delta
+        elif isinstance(data, ResponseContentPartDoneEvent):
+            yield "\n"
+
+    inputs = result.to_input_list()
+    agent = result.current_agent
+    yield f"\n[Agent: {agent.name}]"
+
+    # Continue conversation
+    yield "\nContinue the conversation (type 'exit' to quit):"
+
+    while True:
+        user_msg = yield pixie.InputRequired(str)
+
+        if user_msg.lower() in {"exit", "quit", "bye"}:
+            yield "Session ended. Merci! ¡Gracias! Thank you!"
+            break
+
+        inputs.append({"content": user_msg, "role": "user"})
+
+        result = Runner.run_streamed(agent, input=inputs)
+
+        async for event in result.stream_events():
+            if not isinstance(event, RawResponsesStreamEvent):
+                continue
+
+            data = event.data
+            if isinstance(data, ResponseTextDeltaEvent):
+                yield data.delta
+            elif isinstance(data, ResponseContentPartDoneEvent):
+                yield "\n"
+
+        inputs = result.to_input_list()
+        agent = result.current_agent
+        yield f"\n[Agent: {agent.name}]"

examples/pydantic_ai/.env.example

@@ -0,0 +1,26 @@
+# API Keys for PydanticAI Examples
+# Copy this file to .env and add your actual API keys
+
+# OpenAI API Key (required for GPT models)
+# Get yours at: https://platform.openai.com/api-keys
+OPENAI_API_KEY=your-openai-api-key-here
+
+# Google Gemini API Key (optional, for Gemini models)
+# Get yours at: https://makersuite.google.com/app/apikey
+GEMINI_API_KEY=your-gemini-api-key-here
+
+# Groq API Key (optional, for Groq models)
+# Get yours at: https://console.groq.com/keys
+GROQ_API_KEY=your-groq-api-key-here
+
+# Pydantic Logfire Token (optional, for observability)
+# Get yours at: https://logfire.pydantic.dev/
+LOGFIRE_TOKEN=your-logfire-token-here
+
+# Weather API Key (optional, for weather_agent with real data)
+# Get yours at: https://www.tomorrow.io/weather-api/
+WEATHER_API_KEY=your-weather-api-key-here
+
+# Geocoding API Key (optional, for weather_agent with real data)
+# Get yours at: https://geocode.maps.co/
+GEO_API_KEY=your-geo-api-key-here