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

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.

examples/langchain/__init__.py

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

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

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)"

examples/langchain/personal_assistant.py

@@ -0,0 +1,163 @@
+"""
+Personal Assistant with Subagents (Multi-Agent)
+
+This example demonstrates the supervisor pattern where a central supervisor agent
+coordinates specialized worker agents (calendar and email agents).
+
+Based on: https://docs.langchain.com/oss/python/langchain/multi-agent/subagents-personal-assistant
+"""
+
+from langchain.agents import create_agent
+from langchain.chat_models import init_chat_model
+from langchain.tools import tool
+from langgraph.checkpoint.memory import InMemorySaver
+
+from langfuse.langchain import CallbackHandler
+import pixie
+
+
+langfuse_handler = CallbackHandler()
+
+
+# Define calendar tools (stubs for demonstration)
+@tool
+def create_calendar_event(
+    title: str,
+    start_time: str,  # ISO format: "2024-01-15T14:00:00"
+    end_time: str,  # ISO format: "2024-01-15T15:00:00"
+    attendees: list[str],  # email addresses
+    location: str = "",
+) -> str:
+    """Create a calendar event. Requires exact ISO datetime format."""
+    return f"Event created: {title} from {start_time} to {end_time} with {len(attendees)} attendees"
+
+
+@tool
+def get_available_time_slots(
+    attendees: list[str], date: str, duration_minutes: int  # ISO format: "2024-01-15"
+) -> list[str]:
+    """Check calendar availability for given attendees on a specific date."""
+    return ["09:00", "14:00", "16:00"]
+
+
+@tool
+def send_email(to: list[str], subject: str, body: str, cc: list[str] = []) -> str:
+    """Send an email via email API. Requires properly formatted addresses."""
+    return f"Email sent to {', '.join(to)} - Subject: {subject}"
+
+
+# System prompts for specialized agents
+CALENDAR_AGENT_PROMPT = (
+    "You are a calendar scheduling assistant. "
+    "Parse natural language scheduling requests (e.g., 'next Tuesday at 2pm') "
+    "into proper ISO datetime formats. "
+    "Use get_available_time_slots to check availability when needed. "
+    "Use create_calendar_event to schedule events. "
+    "Always confirm what was scheduled in your final response."
+)
+
+EMAIL_AGENT_PROMPT = (
+    "You are an email assistant. "
+    "Compose professional emails based on natural language requests. "
+    "Extract recipient information and craft appropriate subject lines and body text. "
+    "Use send_email to send the message. "
+    "Always confirm what was sent in your final response."
+)
+
+SUPERVISOR_PROMPT = (
+    "You are a helpful personal assistant. "
+    "You can schedule calendar events and send emails. "
+    "Break down user requests into appropriate tool calls and coordinate the results. "
+    "When a request involves multiple actions, use multiple tools in sequence."
+)
+
+
+@pixie.app
+async def langchain_personal_assistant() -> pixie.PixieGenerator[str, str]:
+    """Multi-agent personal assistant with calendar and email subagents.
+
+    The supervisor coordinates specialized worker agents:
+    - Calendar agent: handles scheduling and availability
+    - Email agent: manages communication and drafts
+
+    Yields:
+        AI responses to user requests
+    """
+    # Initialize model
+    model = init_chat_model("gpt-4o-mini", temperature=0)
+
+    # Create calendar subagent
+    calendar_agent = create_agent(
+        model,
+        tools=[create_calendar_event, get_available_time_slots],
+        system_prompt=CALENDAR_AGENT_PROMPT,
+    )
+
+    # Create email subagent
+    email_agent = create_agent(
+        model,
+        tools=[send_email],
+        system_prompt=EMAIL_AGENT_PROMPT,
+    )
+
+    # Wrap subagents as tools for the supervisor
+    @tool
+    def schedule_event(request: str) -> str:
+        """Schedule calendar events using natural language.
+
+        Use this when the user wants to create, modify, or check calendar appointments.
+        Handles date/time parsing, availability checking, and event creation.
+        """
+        result = calendar_agent.invoke(
+            {"messages": [{"role": "user", "content": request}]},
+            config={"callbacks": [langfuse_handler]},
+        )
+        return result["messages"][-1].content
+
+    @tool
+    def manage_email(request: str) -> str:
+        """Send emails using natural language.
+
+        Use this when the user wants to send notifications, reminders, or any email
+        communication. Handles recipient extraction, subject generation, and email composition.
+        """
+        result = email_agent.invoke(
+            {"messages": [{"role": "user", "content": request}]},
+            config={"callbacks": [langfuse_handler]},
+        )
+        return result["messages"][-1].content
+
+    # Create supervisor agent with checkpointer for conversation memory
+    supervisor_agent = create_agent(
+        model,
+        tools=[schedule_event, manage_email],
+        system_prompt=SUPERVISOR_PROMPT,
+        checkpointer=InMemorySaver(),
+    )
+
+    # Send welcome message
+    yield (
+        "Hello! I'm your personal assistant. I can help you schedule events "
+        "and send emails. What would you like me to do?"
+    )
+
+    # Initialize conversation
+    thread_id = "personal_assistant_thread"
+    config = {"configurable": {"thread_id": thread_id}, "callbacks": [langfuse_handler]}
+
+    while True:
+        # Get user request
+        user_request = yield pixie.InputRequired(str)
+
+        # Check for exit
+        if user_request.lower() in {"exit", "quit", "bye", "goodbye"}:
+            yield "Goodbye! Let me know if you need anything else."
+            break
+
+        # Process request with supervisor
+        result = supervisor_agent.invoke(
+            {"messages": [{"role": "user", "content": user_request}]}, config  # type: ignore
+        )
+
+        # Yield the supervisor's response
+        yield result["messages"][-1].content