diff --git a/examples/uncommonroute/README.md b/examples/uncommonroute/README.md new file mode 100644 index 000000000..f40fefb52 --- /dev/null +++ b/examples/uncommonroute/README.md @@ -0,0 +1,49 @@ +# AgentOps + UncommonRoute: Track and Optimize LLM Costs + +[AgentOps](https://github.com/AgentOps-AI/agentops) tracks what your agents spend. [UncommonRoute](https://github.com/CommonstackAI/UncommonRoute) cuts that spend by routing each request to the cheapest model that can handle it. + +Together they close the loop: **observe → optimize → verify**. + +## How it works + +``` +Your Agent → UncommonRoute (local proxy) → cheapest capable model + ↓ +AgentOps (traces every call, tracks cost per request) +``` + +UncommonRoute analyzes each request using three signals (metadata, embeddings, structural complexity) and routes it to the optimal model: + +| Task complexity | Routed to | Example | +|----------------|-----------|---------| +| Trivial | nano model (~$0.0008) | "hello" | +| Simple | budget model (~$0.001) | "fix the typo on line 3" | +| Medium | mid-tier (~$0.03) | "refactor this function" | +| Complex | premium (~$0.05) | "design a distributed scheduler" | + +**Result**: ~82% cost reduction with 93.4% task completion rate. + +## Setup + +```bash +# Install dependencies +pip install -r requirements.txt + +# Initialize UncommonRoute (one-time setup) +uncommon-route init + +# Start the local proxy +uncommon-route serve + +# Set your AgentOps API key +export AGENTOPS_API_KEY="***" + +# Run the example +python uncommonroute_cost_optimization.py +``` + +## What you'll see in the AgentOps dashboard + +- Cost breakdown per LLM call +- Which model UncommonRoute selected for each task +- Total session cost (compare with always-premium routing) \ No newline at end of file diff --git a/examples/uncommonroute/requirements.txt b/examples/uncommonroute/requirements.txt new file mode 100644 index 000000000..8b3cc1020 --- /dev/null +++ b/examples/uncommonroute/requirements.txt @@ -0,0 +1,4 @@ +agentops +openai +python-dotenv +uncommon-route \ No newline at end of file diff --git a/examples/uncommonroute/uncommonroute_cost_optimization.py b/examples/uncommonroute/uncommonroute_cost_optimization.py new file mode 100644 index 000000000..5afa0da47 --- /dev/null +++ b/examples/uncommonroute/uncommonroute_cost_optimization.py @@ -0,0 +1,99 @@ +""" +AgentOps + UncommonRoute: Track and Optimize LLM Costs + +This example shows how to combine AgentOps (cost tracking) with +UncommonRoute (cost optimization) to get full visibility into your +LLM spending and automatically reduce it by ~82%. + +Setup: + pip install agentops openai + pipx install uncommon-route + uncommon-route init + uncommon-route serve + +Environment variables: + AGENTOPS_API_KEY - your AgentOps API key + OPENAI_API_KEY - your OpenAI API key (used by UncommonRoute upstream) + ANTHROPIC_API_KEY - your Anthropic API key (optional, for more routing options) +""" + +from openai import OpenAI +import agentops +import os +from dotenv import load_dotenv + +load_dotenv() + +os.environ["AGENTOPS_API_KEY"] = os.getenv("AGENTOPS_API_KEY", "your_api_key_here") + +# --- Initialize AgentOps FIRST (before any LLM calls) --- +agentops.init( + auto_start_session=True, + trace_name="UncommonRoute Cost Optimization", + tags=["uncommonroute", "cost-optimization", "agentops-example"], +) + +tracer = agentops.start_trace( + trace_name="UncommonRoute Cost Optimization", + tags=["uncommonroute", "cost-optimization"], +) + +# --- Point the OpenAI client at UncommonRoute's local proxy --- +# UncommonRoute runs on localhost:8403 and is fully OpenAI-compatible. +# It analyzes each request and routes to the cheapest capable model. +client = OpenAI( + base_url="http://localhost:8403/v1", + api_key="not-needed", # UR uses your provider keys configured during `uncommon-route init` +) + +# --- Task 1: Simple greeting (routed to a cheap/fast model) --- +print("=== Task 1: Simple greeting ===") +response = client.chat.completions.create( + model="uncommon-route/auto", + messages=[{"role": "user", "content": "Say hello in three languages."}], +) +print(f"Response: {response.choices[0].message.content}\n") + +# --- Task 2: Medium complexity (routed to a mid-tier model) --- +print("=== Task 2: Code explanation ===") +response = client.chat.completions.create( + model="uncommon-route/auto", + messages=[ + { + "role": "user", + "content": "Explain the difference between a mutex and a semaphore. Give a short code example in Python.", + } + ], +) +print(f"Response: {response.choices[0].message.content}\n") + +# --- Task 3: Complex reasoning (routed to a premium model) --- +print("=== Task 3: Architecture design ===") +response = client.chat.completions.create( + model="uncommon-route/auto", + messages=[ + { + "role": "system", + "content": "You are a senior distributed systems architect.", + }, + { + "role": "user", + "content": ( + "Design a rate limiter for a multi-region API gateway that handles " + "100k requests/second. Consider consistency vs availability tradeoffs, " + "clock skew, and burst handling. Provide a detailed architecture." + ), + }, + ], +) +print(f"Response: {response.choices[0].message.content}\n") + +# --- End trace and show results --- +agentops.end_trace(tracer, end_state="Success") + +print("=" * 60) +print("Check your AgentOps dashboard to see:") +print(" - Cost breakdown per request") +print(" - Which model UncommonRoute selected for each task") +print(" - Total spend vs. what it would have cost with a single premium model") +print("=" * 60) \ No newline at end of file