python-examples: starter examples for agents and workflows

Author: ndeodhar

orchestrator/src/main.rs

@@ -786,13 +786,36 @@ async fn main() -> anyhow::Result<()> {
                 .allow_credentials(true)
                 .expose_headers([axum::http::header::CONTENT_TYPE]);
 
-            // Use the exact origin from CORS_ORIGIN env var
-            let cors_origin = std::env::var("CORS_ORIGIN")
-                .unwrap_or_else(|_| "http://localhost:5173".to_string());
-            let origin_value: axum::http::HeaderValue = cors_origin
-                .parse()
-                .unwrap_or_else(|_| "http://localhost:5173".parse().unwrap());
-            cors_layer.allow_origin(tower_http::cors::AllowOrigin::exact(origin_value))
+            // In local mode, allow both localhost and 127.0.0.1 variants
+            let local_mode = std::env::var("POLOS_LOCAL_MODE")
+                .map(|v| v.to_lowercase() == "true")
+                .unwrap_or(false);
+
+            if local_mode {
+                // Extract port from CORS_ORIGIN or use default
+                let cors_origin = std::env::var("CORS_ORIGIN")
+                    .unwrap_or_else(|_| "http://localhost:5173".to_string());
+                let port = cors_origin
+                    .rsplit(':')
+                    .next()
+                    .and_then(|p| p.parse::<u16>().ok())
+                    .unwrap_or(5173);
+
+                // Allow both localhost and 127.0.0.1
+                let origins = [
+                    format!("http://localhost:{}", port).parse().unwrap(),
+                    format!("http://127.0.0.1:{}", port).parse().unwrap(),
+                ];
+                cors_layer.allow_origin(tower_http::cors::AllowOrigin::list(origins))
+            } else {
+                // Production: use exact origin from CORS_ORIGIN env var
+                let cors_origin = std::env::var("CORS_ORIGIN")
+                    .unwrap_or_else(|_| "http://localhost:5173".to_string());
+                let origin_value: axum::http::HeaderValue = cors_origin
+                    .parse()
+                    .unwrap_or_else(|_| "http://localhost:5173".parse().unwrap());
+                cors_layer.allow_origin(tower_http::cors::AllowOrigin::exact(origin_value))
+            }
         })
         .with_state(state);
 

python-examples/.gitignore

@@ -0,0 +1,19 @@
+# Environment
+.env
+.venv/
+venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# uv
+uv.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp

python-examples/01-weather-agent/.env.example

@@ -0,0 +1,16 @@
+# Required - indicates that we are running Polos locally in dev mode
+POLOS_LOCAL_MODE=true
+
+# Required: Polos project ID.
+# You can get this from the output printed by `polos-server start` or from the UI page at
+# http://localhost:5173/projects/settings (the ID will be below the project name 'default')
+POLOS_PROJECT_ID=your-project-id
+
+# Required: OpenAI API key for the agent
+OPENAI_API_KEY=sk-...
+
+# Optional: Orchestrator URL (defaults to http://localhost:8080)
+# POLOS_API_URL=http://localhost:8080
+
+# Optional: Deployment ID for routing workflows to specific workers
+POLOS_DEPLOYMENT_ID=python-examples

python-examples/01-weather-agent/README.md

@@ -0,0 +1,113 @@
+# Weather agent Example
+
+A simple example demonstrating the basics of Polos:
+- Creating agent with tool
+- Running a worker to execute the agent
+
+## Prerequisites
+
+1. **Polos Server** - The orchestrator that manages workflow execution
+2. **Python 3.10+**
+3. **Polos project ID** - Get this from the UI page http://localhost:5173/settings
+3. **OpenAI API Key** - For the weather agent
+
+## Setup
+
+### 1. Start the Polos Server
+
+Install and start the Polos server (orchestrator):
+
+```bash
+# Install polos-server
+curl -fsSL https://install.polos.dev/install.sh | bash
+
+# Start the server
+polos-server start
+```
+
+Example output:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎉 Polos server is running!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📡 Orchestrator API: http://127.0.0.1:8080
+🌐 UI:              http://127.0.0.1:5173
+🔑 Project ID:      8348be0b-bee2-4b28-bd7a-3d5a873c01ab
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+The server runs at `http://localhost:8080` by default.
+
+### 2. Install Dependencies
+
+```bash
+# Using uv (recommended)
+uv sync
+
+# Or using pip
+pip install -e .
+```
+
+### 3. Configure Environment
+
+Create a `.env` file:
+
+```bash
+# Required: Your project ID.
+# You can get this from the output printed by `polos-server start` or from the UI page at
+# http://localhost:5173/projects/settings (the ID will be below the project name 'default')
+POLOS_PROJECT_ID=my-project
+
+# Required: OpenAI API key for the agent
+OPENAI_API_KEY=sk-...
+
+# Optional: Orchestrator URL (defaults to http://localhost:8080)
+# POLOS_API_URL=http://localhost:8080
+```
+
+## Running the Example
+
+### Terminal 1: Start the Worker
+
+The worker executes workflows and agents:
+
+```bash
+python worker.py
+```
+
+You should see:
+```
+Starting worker...
+  Project ID: <my-project>
+  Agents: ['weather_agent']
+  Press Ctrl+C to stop
+```
+
+### Terminal 2: Run the Example
+
+In a separate terminal, run:
+
+```bash
+python main.py
+```
+
+You should see:
+```
+Invoking weather_agent...
+Result: 'The weather in New York is...'
+```
+
+## What's Happening?
+
+1. **main.py** invokes `weather_agent` with input "What's the weather like in New York?"
+2. **Polos Server** receives the workflow (agent) and queues it for execution
+3. **worker.py** picks up the agent request and executes it:
+   - Starts the weather agent to get weather information
+   - The agent uses the `get_weather` tool
+4. The result is returned through Polos Server to the caller
+
+## Files
+
+- `agents.py` - Defines the `weather_agent` agent
+- `tools.py` - Defines the `get_weather` tool with mock weather data
+- `worker.py` - Runs the worker that executes workflows
+- `main.py` - Invokes the workflow and displays results

python-examples/01-weather-agent/agents.py

@@ -0,0 +1,17 @@
+"""Example workflows and agents for the Hello World example."""
+
+from polos import Agent, max_steps, MaxStepsConfig
+from tools import get_weather
+
+
+# Define a weather agent that can look up weather information
+weather_agent = Agent(
+    id="weather_agent",
+    provider="openai",
+    model="gpt-4o-mini",
+    system_prompt="You are a helpful weather assistant. Use the get_weather tool to look up weather information when asked.",
+    tools=[get_weather],
+    stop_conditions=[
+        max_steps(MaxStepsConfig(limit=10)),
+    ],
+)

python-examples/01-weather-agent/main.py

@@ -0,0 +1,54 @@
+"""
+Run the weather agent.
+
+This script invokes the weather agent and waits for the result.
+
+Run with:
+    python main.py
+
+Environment variables:
+    POLOS_PROJECT_ID - Your project ID (required)
+    POLOS_API_URL - Orchestrator URL (default: http://localhost:8080)
+"""
+
+import asyncio
+import os
+
+from dotenv import load_dotenv
+from polos import PolosClient
+
+from agents import weather_agent
+
+load_dotenv()
+
+
+async def main():
+    """Run the weather agent."""
+    # Get project_id from environment
+    project_id = os.getenv("POLOS_PROJECT_ID")
+    if not project_id:
+        raise ValueError(
+            "POLOS_PROJECT_ID environment variable is required. "
+            "Set it to your project ID (e.g., export POLOS_PROJECT_ID=my-project). "
+            "You can get this from the output printed by `polos-server start` or from the UI page at "
+            "http://localhost:5173/projects/settings (the ID will be below the project name 'default')"
+        )
+
+    # Create Polos client
+    client = PolosClient(
+        project_id=project_id,
+        api_url=os.getenv("POLOS_API_URL", "http://localhost:8080"),
+        deployment_id="python-examples",
+    )
+
+    print("Invoking weather_agent...")
+
+    result = await weather_agent.run(
+        client, "What's the weather like in New York?"
+    )
+
+    print(result.result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python-examples/01-weather-agent/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "polos-hello-world"
+version = "0.1.0"
+description = "Hello World example for Polos SDK"
+requires-python = ">=3.10"
+dependencies = [
+    "polos-sdk[openai]",
+    "python-dotenv>=1.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.1.0",
+]

python-examples/01-weather-agent/tools.py

@@ -0,0 +1,107 @@
+"""Example tools for agents."""
+
+from pydantic import BaseModel
+from polos import tool, WorkflowContext
+
+
+# Pre-canned weather data for various cities
+WEATHER_DATA = {
+    "new york": {
+        "city": "New York",
+        "temperature": 72,
+        "condition": "Partly Cloudy",
+        "humidity": 65,
+        "wind_speed": 10,
+        "unit": "F",
+    },
+    "san francisco": {
+        "city": "San Francisco",
+        "temperature": 68,
+        "condition": "Foggy",
+        "humidity": 80,
+        "wind_speed": 8,
+        "unit": "F",
+    },
+    "london": {
+        "city": "London",
+        "temperature": 15,
+        "condition": "Rainy",
+        "humidity": 85,
+        "wind_speed": 12,
+        "unit": "C",
+    },
+    "tokyo": {
+        "city": "Tokyo",
+        "temperature": 22,
+        "condition": "Sunny",
+        "humidity": 60,
+        "wind_speed": 5,
+        "unit": "C",
+    },
+    "paris": {
+        "city": "Paris",
+        "temperature": 18,
+        "condition": "Cloudy",
+        "humidity": 70,
+        "wind_speed": 9,
+        "unit": "C",
+    },
+}
+
+
+class WeatherInput(BaseModel):
+    """Input schema for weather tool."""
+
+    city: str
+
+
+class WeatherOutput(BaseModel):
+    """Output schema for weather tool."""
+
+    city: str
+    temperature: int
+    condition: str
+    humidity: int
+    wind_speed: int
+    unit: str
+    error: str | None = None
+
+
+@tool(description="Get the current weather information for a given city")
+async def get_weather(ctx: WorkflowContext, input: WeatherInput) -> WeatherOutput:
+    """
+    Tool that returns weather information for a city.
+
+    This is a simple example tool that the agent can call.
+    In a real scenario, this would query a weather API.
+    """
+    city = input.city.strip().lower()
+    weather = WEATHER_DATA.get(city)
+
+    if not weather:
+        # Try to find a partial match
+        for key, value in WEATHER_DATA.items():
+            if city in key or key in city:
+                weather = value
+                break
+
+    if not weather:
+        return WeatherOutput(
+            city=city.title(),
+            temperature=0,
+            condition="Unknown",
+            humidity=0,
+            wind_speed=0,
+            unit="C",
+            error=f"Weather data not available for '{city}'.",
+        )
+
+    return WeatherOutput(
+        city=weather["city"],
+        temperature=weather["temperature"],
+        condition=weather["condition"],
+        humidity=weather["humidity"],
+        wind_speed=weather["wind_speed"],
+        unit=weather["unit"],
+        error=None,
+    )