pixie-examples 0.0.1__tar.gz

pixie_examples-0.0.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: pixie-examples
+Version: 0.0.1
+Summary: examples for using Pixie
+License: MIT
+Author: Yiou Li
+Author-email: yol@gopixie.ai
+Requires-Python: >=3.11,<3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: beautifulsoup4 (>=4.14.3,<5.0.0)
+Requires-Dist: langchain (>=1.2.3,<2.0.0)
+Requires-Dist: langchain-openai (>=1.1.7,<2.0.0)
+Requires-Dist: langchain-text-splitters (>=1.1.0,<2.0.0)
+Requires-Dist: langgraph (>=1.0.5,<2.0.0)
+Requires-Dist: lxml (>=6.0.2,<7.0.0)
+Requires-Dist: numpy (>=2.4.1,<3.0.0)
+Requires-Dist: openai-agents (>=0.6.5,<0.7.0)
+Requires-Dist: openinference-instrumentation-crewai (>=0.1.17,<0.2.0)
+Requires-Dist: openinference-instrumentation-dspy (>=0.1.33,<0.2.0)
+Requires-Dist: openinference-instrumentation-google-adk (>=0.1.8,<0.2.0)
+Requires-Dist: openinference-instrumentation-openai-agents (>=1.4.0,<2.0.0)
+Requires-Dist: pixie-sdk (>=0.0.1b0,<0.0.2)
+Requires-Dist: pydantic (>=2.7.4,<3.0.0)
+Requires-Dist: pydantic-ai-slim (>=1.39.0,<2.0.0)
+Requires-Dist: pymarkdownlnt (>=0.9.34,<0.10.0)
+Requires-Dist: requests (>=2.32.5,<3.0.0)
+Requires-Dist: sqlalchemy (>=2.0.45,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Pixie Examples
+
+[![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue?style=flat-square)](https://www.python.org/downloads/)
+[![Discord](https://img.shields.io/discord/1459772566528069715?style=flat-square&logo=Discord&logoColor=white&label=Discord&color=%23434EE4)](https://discord.gg/YMNYu6Z3)
+
+This repository contains a collection of example applications integrated with [**Pixie SDK**](https://github.com/yiouli/pixie-sdk-py) for interactive debugging.
+
+## Get Started
+
+> You can play with the demo site [here](https://gopixie.ai/?url=https://demo.yiouli.us/graphql) withou any setup.
+
+### 1. Setup
+
+Clone this repository:
+
+Install `pixie-examples` python package:
+
+```bash
+pip install pixie-examples
+```
+
+Create a `.env` file with your API keys:
+
+```ini
+# .env
+OPENAI_API_KEY=...
+# Add other API keys as needed for specific examples
+```
+
+Start the Pixie server:
+
+```bash
+pixie
+```
+
+### 2. Debug with Web UI
+
+Visit [gopixie.ai](https://gopixie.ai) to interact with and debug your applications through the web interface.
+
+## Important Links
+
+- [**Pixie SDK**](https://github.com/yiouli/pixie-sdk-py)
+- [**Documentation**](https://yiouli.github.io/pixie-sdk-py/)
+- [**Discord**](https://discord.gg/YMNYu6Z3)
+
+## Examples Catelog
+
+### Quickstart
+
+- **Basic Example**: Simple hello world application to get started with Pixie SDK
+
+### Pydantic AI Examples
+
+- **Bank Support**: Multi-turn chatbot for banking customer support
+- **Flight Booking**: Multi-agent system for flight booking
+- **Question Graph**: Graph-based question answering system
+- **SQL Generation**: Multi-step workflow for generating SQL queries
+- **Structured Output**: Examples of structured data handling
+
+### OpenAI Agents SDK Examples
+
+- **Customer Service**: Multi-agent customer service system
+- **Financial Research Agent**: Multi-step financial research workflow
+- **LLM-as-a-Judge**: Evaluation and judging patterns
+- **Routing**: Agent routing and handoffs
+
+### LangChain Examples
+
+- **Basic Agent**: Simple LangChain agent integration
+- **Customer Support**: Customer support chatbot
+- **Personal Assistant**: Multi-agent personal assistant
+- **SQL Agent**: SQL query generation with LangChain
+
+### LangGraph Examples
+
+- **RAG System**: Retrieval-augmented generation with LangGraph
+- **SQL Agent**: SQL agent built with LangGraph state machines
+

pixie_examples-0.0.1/README.md

@@ -0,0 +1,78 @@
+# Pixie Examples
+
+[![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue?style=flat-square)](https://www.python.org/downloads/)
+[![Discord](https://img.shields.io/discord/1459772566528069715?style=flat-square&logo=Discord&logoColor=white&label=Discord&color=%23434EE4)](https://discord.gg/YMNYu6Z3)
+
+This repository contains a collection of example applications integrated with [**Pixie SDK**](https://github.com/yiouli/pixie-sdk-py) for interactive debugging.
+
+## Get Started
+
+> You can play with the demo site [here](https://gopixie.ai/?url=https://demo.yiouli.us/graphql) withou any setup.
+
+### 1. Setup
+
+Clone this repository:
+
+Install `pixie-examples` python package:
+
+```bash
+pip install pixie-examples
+```
+
+Create a `.env` file with your API keys:
+
+```ini
+# .env
+OPENAI_API_KEY=...
+# Add other API keys as needed for specific examples
+```
+
+Start the Pixie server:
+
+```bash
+pixie
+```
+
+### 2. Debug with Web UI
+
+Visit [gopixie.ai](https://gopixie.ai) to interact with and debug your applications through the web interface.
+
+## Important Links
+
+- [**Pixie SDK**](https://github.com/yiouli/pixie-sdk-py)
+- [**Documentation**](https://yiouli.github.io/pixie-sdk-py/)
+- [**Discord**](https://discord.gg/YMNYu6Z3)
+
+## Examples Catelog
+
+### Quickstart
+
+- **Basic Example**: Simple hello world application to get started with Pixie SDK
+
+### Pydantic AI Examples
+
+- **Bank Support**: Multi-turn chatbot for banking customer support
+- **Flight Booking**: Multi-agent system for flight booking
+- **Question Graph**: Graph-based question answering system
+- **SQL Generation**: Multi-step workflow for generating SQL queries
+- **Structured Output**: Examples of structured data handling
+
+### OpenAI Agents SDK Examples
+
+- **Customer Service**: Multi-agent customer service system
+- **Financial Research Agent**: Multi-step financial research workflow
+- **LLM-as-a-Judge**: Evaluation and judging patterns
+- **Routing**: Agent routing and handoffs
+
+### LangChain Examples
+
+- **Basic Agent**: Simple LangChain agent integration
+- **Customer Support**: Customer support chatbot
+- **Personal Assistant**: Multi-agent personal assistant
+- **SQL Agent**: SQL query generation with LangChain
+
+### LangGraph Examples
+
+- **RAG System**: Retrieval-augmented generation with LangGraph
+- **SQL Agent**: SQL agent built with LangGraph state machines

pixie_examples-0.0.1/examples/langchain/README.md

@@ -0,0 +1,39 @@
+# LangChain Examples
+
+This directory contains LangChain examples integrated with Pixie SDK.
+
+## Examples
+
+1. **basic_agent.py** - A simple quickstart agent that can answer questions and call tools
+2. **personal_assistant.py** - Multi-agent personal assistant with subagents for calendar and email
+3. **customer_support.py** - Customer support agent with state machine pattern (handoffs)
+4. **sql_agent.py** - SQL database query agent (multi-turn & multi-step)
+5. **langgraph_sql_agent.py** - Custom SQL agent built with LangGraph primitives
+6. **langgraph_rag.py** - Custom RAG (Retrieval Augmented Generation) agent with LangGraph
+
+## Setup
+
+Install the required dependencies:
+
+```bash
+poetry add langchain langchain-openai langchain-community langgraph langchain-text-splitters beautifulsoup4
+```
+
+Set up environment variables in `.env`:
+
+```bash
+OPENAI_API_KEY=your_openai_api_key
+ANTHROPIC_API_KEY=your_anthropic_api_key
+LANGSMITH_API_KEY=your_langsmith_api_key  # Optional, for tracing
+LANGSMITH_TRACING=true  # Optional
+```
+
+## Running Examples
+
+Start the Pixie server:
+
+```bash
+poetry run pixie
+```
+
+Then use GraphiQL at `http://127.0.0.1:8000/graphql` to run the agents.

pixie_examples-0.0.1/examples/langchain/__init__.py

@@ -0,0 +1 @@
+# LangChain examples for Pixie SDK

pixie_examples-0.0.1/examples/langchain/basic_agent.py

@@ -0,0 +1,100 @@
+"""
+Basic LangChain Agent Example (Quickstart)
+
+This example demonstrates a simple agent that can answer questions and call tools.
+Based on: https://docs.langchain.com/oss/python/langchain/quickstart
+"""
+
+from langchain.agents import create_agent
+from langchain.chat_models import init_chat_model
+
+from langfuse.langchain import CallbackHandler
+import pixie
+
+
+langfuse_handler = CallbackHandler()
+
+
+def get_weather(city: str) -> str:
+    """Get weather for a given city."""
+    return f"It's always sunny in {city}!"
+
+
+@pixie.app
+async def langchain_basic_weather_agent(query: str) -> str:
+    """A simple weather agent that can answer questions using tools.
+
+    Args:
+        query: User's question about weather
+
+    Returns:
+        AI-generated response
+    """
+    # Initialize the model
+    model = init_chat_model("gpt-4o-mini", temperature=0)
+
+    # Create agent with the weather tool
+    agent = create_agent(
+        model=model,
+        tools=[get_weather],
+        system_prompt="You are a helpful weather assistant",
+    )
+
+    # Run the agent
+    result = agent.invoke(
+        {"messages": [{"role": "user", "content": query}]},
+        config={"callbacks": [langfuse_handler]},
+    )
+
+    # Return the final response
+    return result["messages"][-1].content
+
+
+@pixie.app
+async def langchain_interactive_weather_agent() -> pixie.PixieGenerator[str, str]:
+    """An interactive weather chatbot that maintains conversation.
+
+    This agent can have multi-turn conversations with the user.
+
+    Yields:
+        AI responses to user questions
+    """
+    # Initialize the model
+    model = init_chat_model("gpt-4o-mini", temperature=0)
+
+    # Create agent with the weather tool
+    agent = create_agent(
+        model=model,
+        tools=[get_weather],
+        system_prompt="You are a helpful weather assistant that answers questions about weather.",
+    )
+
+    # Send welcome message
+    yield "Hello! I'm a weather assistant. Ask me about the weather in any city!"
+
+    # Initialize conversation history
+    messages = []
+
+    while True:
+        # Get user input
+        user_query = yield pixie.InputRequired(str)
+
+        # Check for exit commands
+        if user_query.lower() in {"exit", "quit", "bye", "goodbye"}:
+            yield "Goodbye! Have a great day!"
+            break
+
+        # Add user message to history
+        messages.append({"role": "user", "content": user_query})
+
+        # Run agent with full conversation history
+        result = agent.invoke(
+            {"messages": messages}, config={"callbacks": [langfuse_handler]}
+        )
+
+        # Update history with AI response
+        messages = result["messages"]
+
+        # Yield the AI's response
+        ai_response = result["messages"][-1].content
+        yield ai_response

pixie_examples-0.0.1/examples/langchain/customer_support.py

@@ -0,0 +1,238 @@
+"""
+Customer Support with Handoffs (State Machine)
+
+This example demonstrates the state machine pattern where an agent's behavior changes
+as it moves through different states of a workflow.
+
+Based on: https://docs.langchain.com/oss/python/langchain/multi-agent/handoffs-customer-support
+"""
+
+from typing import Literal, NotRequired
+from langchain.agents import create_agent, AgentState
+from langchain.chat_models import init_chat_model
+from langchain.tools import tool, ToolRuntime
+from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.types import Command
+from typing import Callable
+
+from langfuse.langchain import CallbackHandler
+import pixie
+
+
+langfuse_handler = CallbackHandler()
+
+
+# Define the possible workflow steps
+SupportStep = Literal["warranty_collector", "issue_classifier", "resolution_specialist"]
+
+
+class SupportState(AgentState):
+    """State for customer support workflow."""
+
+    current_step: NotRequired[SupportStep]
+    warranty_status: NotRequired[Literal["in_warranty", "out_of_warranty"]]
+    issue_type: NotRequired[Literal["hardware", "software"]]
+
+
+# Define tools that manage workflow state
+@tool
+def record_warranty_status(
+    status: Literal["in_warranty", "out_of_warranty"],
+    runtime: ToolRuntime[None, SupportState],
+) -> Command:
+    """Record the customer's warranty status and transition to issue classification."""
+    return Command(
+        update={
+            "messages": [
+                {
+                    "role": "tool",
+                    "content": f"Warranty status recorded as: {status}",
+                    "tool_call_id": runtime.tool_call_id,
+                }
+            ],
+            "warranty_status": status,
+            "current_step": "issue_classifier",
+        }
+    )
+
+
+@tool
+def record_issue_type(
+    issue_type: Literal["hardware", "software"],
+    runtime: ToolRuntime[None, SupportState],
+) -> Command:
+    """Record the type of issue and transition to resolution specialist."""
+    return Command(
+        update={
+            "messages": [
+                {
+                    "role": "tool",
+                    "content": f"Issue type recorded as: {issue_type}",
+                    "tool_call_id": runtime.tool_call_id,
+                }
+            ],
+            "issue_type": issue_type,
+            "current_step": "resolution_specialist",
+        }
+    )
+
+
+@tool
+def escalate_to_human(reason: str) -> str:
+    """Escalate the case to a human support specialist."""
+    return f"Escalating to human support. Reason: {reason}"
+
+
+@tool
+def provide_solution(solution: str) -> str:
+    """Provide a solution to the customer's issue."""
+    return f"Solution provided: {solution}"
+
+
+# Step prompts
+WARRANTY_COLLECTOR_PROMPT = """You are a customer support agent collecting warranty information.
+
+CURRENT STAGE: Warranty Verification
+
+Ask the customer if their device is under warranty. Once you have this information,
+use the record_warranty_status tool to record it and move to the next step.
+
+Be polite and professional."""
+
+ISSUE_CLASSIFIER_PROMPT = """You are a customer support agent classifying technical issues.
+
+CURRENT STAGE: Issue Classification
+CUSTOMER INFO: Warranty status is {warranty_status}
+
+Ask the customer to describe their issue, then determine if it's:
+- HARDWARE: Physical problems (cracked screen, battery, ports, buttons)
+- SOFTWARE: App crashes, performance, settings, updates
+
+Use record_issue_type to record the classification and move to resolution."""
+
+RESOLUTION_SPECIALIST_PROMPT = """You are a customer support agent helping with device issues.
+
+CURRENT STAGE: Resolution
+CUSTOMER INFO: Warranty status is {warranty_status}, issue type is {issue_type}
+
+At this step, you need to:
+1. For SOFTWARE issues: provide troubleshooting steps using provide_solution
+2. For HARDWARE issues:
+   - If IN WARRANTY: explain warranty repair process using provide_solution
+   - If OUT OF WARRANTY: escalate_to_human for paid repair options
+
+Be specific and helpful in your solutions."""
+
+# Step configuration
+STEP_CONFIG = {
+    "warranty_collector": {
+        "prompt": WARRANTY_COLLECTOR_PROMPT,
+        "tools": [record_warranty_status],
+        "requires": [],
+    },
+    "issue_classifier": {
+        "prompt": ISSUE_CLASSIFIER_PROMPT,
+        "tools": [record_issue_type],
+        "requires": ["warranty_status"],
+    },
+    "resolution_specialist": {
+        "prompt": RESOLUTION_SPECIALIST_PROMPT,
+        "tools": [provide_solution, escalate_to_human],
+        "requires": ["warranty_status", "issue_type"],
+    },
+}
+
+
+# Create step-based middleware
+@wrap_model_call
+def apply_step_config(
+    request: ModelRequest, handler: Callable[[ModelRequest], ModelResponse]
+) -> ModelResponse:
+    """Configure agent behavior based on the current step."""
+    # Get current step (defaults to warranty_collector for first interaction)
+    current_step = request.state.get("current_step", "warranty_collector")
+
+    # Look up step configuration
+    stage_config = STEP_CONFIG[current_step]
+
+    # Validate required state exists
+    for key in stage_config["requires"]:
+        if request.state.get(key) is None:
+            raise ValueError(f"{key} must be set before reaching {current_step}")
+
+    # Format prompt with state values
+    # Note: In a production implementation, you would inject the formatted prompt
+    # and tools into the request. For simplicity, we'll let the handler process
+    # the request and handle tool selection based on state.
+    _ = stage_config["prompt"].format(**request.state)
+
+    # The middleware pattern here would need deeper integration with LangChain's
+    # internal APIs. For now, we pass through to the handler.
+    return handler(request)
+
+
+@pixie.app
+async def langchain_customer_support() -> pixie.PixieGenerator[str, str]:
+    """Customer support agent with state machine workflow.
+
+    The agent progresses through three stages:
+    1. Warranty verification
+    2. Issue classification (hardware/software)
+    3. Resolution (solution or escalation)
+
+    Yields:
+        AI responses guiding the support workflow
+    """
+    # Initialize model
+    model = init_chat_model("gpt-4o-mini", temperature=0)
+
+    # Collect all tools
+    all_tools = [
+        record_warranty_status,
+        record_issue_type,
+        provide_solution,
+        escalate_to_human,
+    ]
+
+    # Create agent with step-based configuration
+    agent = create_agent(
+        model,
+        tools=all_tools,
+        state_schema=SupportState,
+        middleware=[apply_step_config],
+        checkpointer=InMemorySaver(),
+    )
+
+    # Send welcome message
+    yield "Welcome to customer support! I'm here to help with your device issue."
+
+    # Initialize conversation
+    thread_id = "support_thread"
+    config = {"configurable": {"thread_id": thread_id}, "callbacks": [langfuse_handler]}
+
+    while True:
+        # Get user input
+        user_message = yield pixie.InputRequired(str)
+
+        # Check for exit
+        if user_message.lower() in {"exit", "quit", "bye"}:
+            yield "Thank you for contacting support. Have a great day!"
+            break
+
+        # Process with agent
+        result = agent.invoke(
+            {"messages": [{"role": "user", "content": user_message}]}, config  # type: ignore
+        )
+
+        # Yield the agent's response
+        yield result["messages"][-1].content
+
+        # Check if we've reached a resolution
+        current_state = result
+        if current_state.get("current_step") == "resolution_specialist" and any(
+            msg.get("role") == "tool"
+            and msg.get("name") in ["provide_solution", "escalate_to_human"]
+            for msg in result.get("messages", [])
+        ):
+            yield "Is there anything else I can help you with? (Type 'exit' to end)"