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

examples/openai_agents_sdk/README.md

@@ -0,0 +1,299 @@
+# OpenAI Agents SDK Examples - Pixie Integration
+
+This directory contains Pixie-integrated versions of OpenAI Agents SDK examples, demonstrating various agent patterns and workflows.
+
+## Examples Overview
+
+### 1. LLM as a Judge (`llm_as_a_judge.py`)
+
+**Pattern**: Multi-Step Workflow
+**Original**: [GitHub](https://github.com/openai/openai-agents-python/blob/main/examples/agent_patterns/llm_as_a_judge.py)
+
+Demonstrates the LLM-as-a-judge pattern where one agent generates content and another evaluates it iteratively.
+
+**Features**:
+
+- Story outline generator
+- Quality evaluator agent
+- Iterative improvement loop
+- Feedback incorporation
+
+**Pixie Handler**: `llm_judge_story_generator(topic: str)`
+
+**Usage**:
+
+```python
+# Via Pixie GraphQL API
+subscription {
+  run(name: "llm_judge_story_generator", inputData: "a sci-fi adventure") {
+    runId
+    status
+    data
+  }
+}
+```
+
+---
+
+### 2. Customer Service (`customer_service.py`)
+
+**Pattern**: Multi-Agent & Multi-Turn
+**Original**: [GitHub](https://github.com/openai/openai-agents-python/blob/main/examples/customer_service/main.py)
+
+A complete customer service system for an airline with multiple specialized agents that hand off to each other.
+
+**Features**:
+
+- Multi-agent architecture (Triage, FAQ, Seat Booking)
+- Agent handoffs based on customer needs
+- Shared context across agents
+- Tool usage (FAQ lookup, seat updates)
+- Interactive multi-turn conversation
+
+**Pixie Handler**: `airline_customer_service()`
+
+**Agents**:
+
+- **Triage Agent**: Routes requests to appropriate specialists
+- **FAQ Agent**: Answers common questions about baggage, seats, wifi
+- **Seat Booking Agent**: Handles seat change requests
+
+**Usage**:
+
+```python
+# Via Pixie GraphQL API
+subscription {
+  run(name: "airline_customer_service", inputData: null) {
+    runId
+    status
+    data
+  }
+}
+```
+
+---
+
+### 3. Routing/Handoffs (`routing.py`)
+
+**Pattern**: Graph/State-Machine
+**Original**: [GitHub](https://github.com/openai/openai-agents-python/blob/main/examples/agent_patterns/routing.py)
+
+Language-based routing where a triage agent hands off to specialized language agents.
+
+**Features**:
+
+- Automatic language detection
+- Agent routing based on language
+- Streaming responses
+- Support for French, Spanish, and English
+
+**Pixie Handlers**:
+
+- `multilingual_routing()` - No initial message required
+- `multilingual_routing_simple(initial_message: str)` - Start with a message
+
+**Usage**:
+
+```python
+# Interactive version
+subscription {
+  run(name: "multilingual_routing", inputData: null) {
+    runId
+    status
+    data
+  }
+}
+
+# With initial message
+subscription {
+  run(name: "multilingual_routing_simple", inputData: "Bonjour, comment allez-vous?") {
+    runId
+    status
+    data
+  }
+}
+```
+
+---
+
+### 4. Financial Research Agent (`financial_research_agent.py`)
+
+**Pattern**: Multi-Step Workflow with Multi-Agent
+**Original**: [GitHub](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent)
+
+Comprehensive financial research workflow with specialized agents for analysis.
+
+**Features**:
+
+- Structured research workflow
+- Parallel web searches
+- Specialist analysts (fundamentals, risk)
+- Report synthesis
+- Quality verification
+- Markdown report generation
+
+**Architecture**:
+
+1. **Planner Agent** - Creates search strategy
+2. **Search Agent** - Performs web searches
+3. **Fundamentals Analyst** - Analyzes financial metrics
+4. **Risk Analyst** - Identifies risk factors
+5. **Writer Agent** - Synthesizes final report
+6. **Verifier Agent** - Quality checks
+
+**Pixie Handler**: `financial_research(query: str)`
+
+**Usage**:
+
+```python
+# Via Pixie GraphQL API
+subscription {
+  run(
+    name: "financial_research",
+    inputData: "Write up an analysis of Apple Inc.'s most recent quarter."
+  ) {
+    runId
+    status
+    data
+  }
+}
+```
+
+**Example Queries**:
+
+- "Analyze Tesla's financial performance and growth prospects"
+- "What are the key risks facing Microsoft in 2026?"
+- "Provide a comprehensive analysis of NVIDIA's market position"
+
+---
+
+## Setup
+
+### 1. Install Dependencies
+
+The OpenAI Agents SDK is already installed in the project:
+
+```bash
+poetry install
+```
+
+### 2. Configure Environment Variables
+
+Make sure you have your OpenAI API key configured in `.env`:
+
+```bash
+OPENAI_API_KEY=sk-...
+```
+
+### 3. Run Pixie Server
+
+Start the Pixie server to access the examples:
+
+```bash
+poetry run pixie
+```
+
+Then navigate to `http://127.0.0.1:8000/graphql` to use the GraphiQL interface.
+
+---
+
+## Key Patterns Demonstrated
+
+### Multi-Turn Conversations
+
+Examples use `PixieGenerator[str, str]` with `UserInputRequirement(str)` for interactive dialogues:
+
+```python
+@app
+async def my_chatbot(_: None) -> PixieGenerator[str, str]:
+    yield "Hello! How can I help?"
+
+    while True:
+        user_input = yield UserInputRequirement(str)
+        # Process and respond
+```
+
+### Agent Handoffs
+
+Multiple agents collaborate by handing off to specialists:
+
+```python
+triage_agent = Agent(
+    handoffs=[specialist_agent_1, specialist_agent_2]
+)
+```
+
+### Streaming Responses
+
+Real-time response streaming for better UX:
+
+```python
+result = Runner.run_streamed(agent, inputs)
+async for event in result.stream_events():
+    if isinstance(data, ResponseTextDeltaEvent):
+        yield data.delta
+```
+
+### Structured Outputs
+
+Using Pydantic models for type-safe outputs:
+
+```python
+class ReportData(BaseModel):
+    summary: str
+    full_report: str
+
+agent = Agent(output_type=ReportData)
+```
+
+---
+
+## Differences from Original Examples
+
+These Pixie-integrated versions differ from the originals in several ways:
+
+1. **Async Generators**: Use `PixieGenerator` for streaming outputs
+2. **User Input**: Use `UserInputRequirement` instead of `input()`
+3. **Instrumentation**: Pixie automatically handles tracing
+4. **No Main Loop**: No `if __name__ == "__main__"` - runs via Pixie server
+5. **GraphQL Interface**: Accessed via GraphQL subscriptions instead of CLI
+
+---
+
+## Testing
+
+Check for syntax errors:
+
+```bash
+poetry run python -m py_compile examples/openai_agents_sdk/*.py
+```
+
+Verify imports:
+
+```bash
+poetry run python -c "from examples.openai_agents_sdk.llm_as_a_judge import llm_judge_story_generator"
+poetry run python -c "from examples.openai_agents_sdk.customer_service import airline_customer_service"
+poetry run python -c "from examples.openai_agents_sdk.routing import multilingual_routing"
+poetry run python -c "from examples.openai_agents_sdk.financial_research_agent import financial_research"
+```
+
+---
+
+## Resources
+
+- [OpenAI Agents SDK Documentation](https://github.com/openai/openai-agents-python)
+- [Pixie SDK Documentation](../.github/copilot-instructions.md)
+- [Original Examples](https://github.com/openai/openai-agents-python/tree/main/examples)
+
+---
+
+## Contributing
+
+To add more OpenAI Agents SDK examples:
+
+1. Create a new `.py` file in this directory
+2. Import required modules from `agents` and `pixie`
+3. Define your agents and tools
+4. Create a Pixie handler with `@app` decorator
+5. Use `PixieGenerator` for multi-turn or streaming applications
+6. Update this README with example details

examples/openai_agents_sdk/customer_service.py

@@ -0,0 +1,258 @@
+"""
+Customer Service - Multi-Agent & Multi-Turn Chatbot - Pixie Integration
+
+This example demonstrates a customer service system with multiple specialized agents
+that can hand off to each other based on customer needs.
+
+Pattern: Multi-Agent & Multi-Turn
+Original: https://github.com/openai/openai-agents-python/blob/main/examples/customer_service/main.py
+"""
+
+from __future__ import annotations
+
+import random
+
+from pydantic import BaseModel
+from agents import (
+    Agent,
+    HandoffOutputItem,
+    ItemHelpers,
+    MessageOutputItem,
+    RunContextWrapper,
+    Runner,
+    ToolCallItem,
+    ToolCallOutputItem,
+    TResponseInputItem,
+    function_tool,
+    handoff,
+)
+from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
+import pixie
+
+
+# ============================================================================
+# CONTEXT
+# ============================================================================
+
+
+class AirlineAgentContext(BaseModel):
+    """Shared context across all airline customer service agents"""
+
+    passenger_name: str | None = None
+    confirmation_number: str | None = None
+    seat_number: str | None = None
+    flight_number: str | None = None
+
+
+# ============================================================================
+# TOOLS
+# ============================================================================
+
+
+@function_tool(
+    name_override="faq_lookup_tool",
+    description_override="Lookup frequently asked questions.",
+)
+async def faq_lookup_tool(question: str) -> str:
+    """Simulates FAQ lookup for common airline questions"""
+    question_lower = question.lower()
+
+    if any(
+        keyword in question_lower
+        for keyword in [
+            "bag",
+            "baggage",
+            "luggage",
+            "carry-on",
+            "hand luggage",
+            "hand carry",
+        ]
+    ):
+        return (
+            "You are allowed to bring one bag on the plane. "
+            "It must be under 50 pounds and 22 inches x 14 inches x 9 inches."
+        )
+    elif any(
+        keyword in question_lower for keyword in ["seat", "seats", "seating", "plane"]
+    ):
+        return (
+            "There are 120 seats on the plane. "
+            "There are 22 business class seats and 98 economy seats. "
+            "Exit rows are rows 4 and 16. "
+            "Rows 5-8 are Economy Plus, with extra legroom."
+        )
+    elif any(
+        keyword in question_lower
+        for keyword in [
+            "wifi",
+            "internet",
+            "wireless",
+            "connectivity",
+            "network",
+            "online",
+        ]
+    ):
+        return "We have free wifi on the plane, join Airline-Wifi"
+
+    return "I'm sorry, I don't know the answer to that question."
+
+
+@function_tool
+async def update_seat(
+    context: RunContextWrapper[AirlineAgentContext],
+    confirmation_number: str,
+    new_seat: str,
+) -> str:
+    """
+    Update the seat for a given confirmation number.
+
+    Args:
+        confirmation_number: The confirmation number for the flight.
+        new_seat: The new seat to update to.
+    """
+    # Update the context based on the customer's input
+    context.context.confirmation_number = confirmation_number
+    context.context.seat_number = new_seat
+
+    # Ensure that the flight number has been set by the incoming handoff
+    assert context.context.flight_number is not None, "Flight number is required"
+
+    return f"Updated seat to {new_seat} for confirmation number {confirmation_number}"
+
+
+# ============================================================================
+# HOOKS
+# ============================================================================
+
+
+async def on_seat_booking_handoff(
+    context: RunContextWrapper[AirlineAgentContext],
+) -> None:
+    """Generate a flight number when handing off to seat booking agent"""
+    flight_number = f"FLT-{random.randint(100, 999)}"
+    context.context.flight_number = flight_number
+
+
+# ============================================================================
+# AGENTS
+# ============================================================================
+
+faq_agent = Agent[AirlineAgentContext](
+    name="FAQ Agent",
+    handoff_description="A helpful agent that can answer questions about the airline.",
+    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
+
+    You are an FAQ agent. If you are speaking to a customer, you probably were
+    transferred to from the triage agent.
+
+    Use the following routine to support the customer.
+
+    # Routine
+    1. Identify the last question asked by the customer.
+    2. Use the faq lookup tool to answer the question. Do not rely on your own knowledge.
+    3. If you cannot answer the question, transfer back to the triage agent.""",
+    tools=[faq_lookup_tool],
+)
+
+seat_booking_agent = Agent[AirlineAgentContext](
+    name="Seat Booking Agent",
+    handoff_description="A helpful agent that can update a seat on a flight.",
+    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
+
+    You are a seat booking agent. If you are speaking to a customer, you probably were
+    transferred to from the triage agent.
+
+    Use the following routine to support the customer.
+
+    # Routine
+    1. Ask for their confirmation number.
+    2. Ask the customer what their desired seat number is.
+    3. Use the update seat tool to update the seat on the flight.
+
+    If the customer asks a question that is not related to the routine, transfer back to the
+    triage agent.""",
+    tools=[update_seat],
+)
+
+triage_agent = Agent[AirlineAgentContext](
+    name="Triage Agent",
+    handoff_description="A triage agent that can delegate a customer's request to the appropriate agent.",
+    instructions=(
+        f"{RECOMMENDED_PROMPT_PREFIX} "
+        "You are a helpful triaging agent. You can use your tools to delegate questions to other appropriate agents."
+    ),
+    handoffs=[
+        faq_agent,
+        handoff(agent=seat_booking_agent, on_handoff=on_seat_booking_handoff),
+    ],
+)
+
+# Set up bidirectional handoffs
+faq_agent.handoffs.append(triage_agent)
+seat_booking_agent.handoffs.append(triage_agent)
+
+
+@pixie.app
+async def openai_agents_airline_customer_service() -> pixie.PixieGenerator[str, str]:
+    """
+    Multi-agent customer service chatbot for an airline.
+
+    This system uses three specialized agents:
+    - Triage Agent: Routes customer requests to appropriate agents
+    - FAQ Agent: Answers common questions using FAQ lookup
+    - Seat Booking Agent: Handles seat change requests
+
+    Agents can hand off to each other based on customer needs.
+
+    Yields:
+        Agent responses and status updates
+
+    Receives:
+        User messages via InputRequired
+    """
+    current_agent: Agent[AirlineAgentContext] = triage_agent
+    input_items: list[TResponseInputItem] = []
+    context = AirlineAgentContext()
+
+    yield "Welcome to Airline Customer Service! How can I help you today?"
+    yield "(Type 'exit', 'quit', or 'bye' to end the conversation)"
+
+    while True:
+        # Get user input
+        user_input = yield pixie.InputRequired(str)
+
+        # Check for exit commands
+        if user_input.lower() in {"exit", "quit", "bye"}:
+            yield "Thank you for contacting us. Have a great flight!"
+            break
+
+        # Add user message to input
+        input_items.append({"content": user_input, "role": "user"})
+
+        # Run the current agent
+        result = await Runner.run(current_agent, input_items, context=context)
+
+        # Process and yield all new items from the result
+        for new_item in result.new_items:
+            agent_name = new_item.agent.name
+
+            if isinstance(new_item, MessageOutputItem):
+                message_text = ItemHelpers.text_message_output(new_item)
+                yield f"{agent_name}: {message_text}"
+
+            elif isinstance(new_item, HandoffOutputItem):
+                handoff_msg = (
+                    f"[Handed off from {new_item.source_agent.name} "
+                    f"to {new_item.target_agent.name}]"
+                )
+                yield handoff_msg
+
+            elif isinstance(new_item, ToolCallItem):
+                yield f"{agent_name}: [Calling a tool...]"
+
+            elif isinstance(new_item, ToolCallOutputItem):
+                yield f"{agent_name}: [Tool result: {new_item.output}]"
+
+        # Update state for next iteration
+        input_items = result.to_input_list()
+        current_agent = result.last_agent