OpenRouter Agent for Pydantic AI

A Python library that extends the Pydantic AI framework to support OpenRouter models.

Overview
Installation
Configuring Your API Key via Environment Variable
- Method 1: Using a .env File (Recommended for Projects)
- Method 2: Setting Temporarily in Your Terminal Session
Usage
Class Reference
- OpenRouterModel
- OpenRouterAgent
Environment Variables
Available Models
License

Overview

This package provides integration between Pydantic AI and OpenRouter, allowing you to use any model available on OpenRouter with the Pydantic AI framework. The implementation leverages the OpenAI-compatible API provided by OpenRouter.

Installation

# Install from the repository in editable mode to make changes
pip install -e .

# Or you can install through PyPi
pip install openrouter-agent

You'll also need to set up your OpenRouter API key. You can either:

Set the OPENROUTER_API_KEY environment variable
Pass the API key directly when initializing the agent

Configuring Your API Key via Environment Variable

Using an environment variable (OPENROUTER_API_KEY) is the recommended way to provide your API key securely. Here’s how you can set it:

Method 1: Using a `.env` File (Recommended for Projects)

This method keeps your key associated with your project without hardcoding it.

Create or Copy: In your project's main directory, create a file named .env. If your project includes a .env-sample or .env.example file, you can copy it to .env.
Add Your Key: Open the .env file and add the following line, replacing your_actual_api_key with the key you generated on OpenRouter Keys:
```
OPENROUTER_API_KEY=your_actual_api_key
```
Load the Variable: For your Python code to access this variable, you usually need a library like python-dotenv. Install it (pip install python-dotenv) and load it early in your script:
```
from dotenv import load_dotenv
load_dotenv()
# Now os.getenv("OPENROUTER_API_KEY") or libraries that check env vars will find it.
```
(Note: Some frameworks or tools might load .env files automatically.)

Method 2: Setting Temporarily in Your Terminal Session

This is useful for quick tests but needs to be done every time you open a new terminal session.

Get Your Key: Copy your API key from OpenRouter Keys.
Run the Command: Execute the command specific to your terminal, replacing your_actual_api_key with your key:
- Linux, macOS, Git Bash (or other sh-like shells):
```
export OPENROUTER_API_KEY='your_actual_api_key'
```
- Windows Command Prompt (cmd.exe):
```
set OPENROUTER_API_KEY=your_actual_api_key
```
- Windows PowerShell:
```
$env:OPENROUTER_API_KEY = 'your_actual_api_key'
```
Run Your Code: Now you can run your Python script or the openrouter-agent CLI command from the same terminal window.

Important: Avoid committing your .env file (if it contains secrets) to version control like Git. Add .env to your .gitignore file.

Usage

Command Line Interface

The package includes a command-line interface (CLI) that allows you to generate and execute shell commands:

# Install the package with CLI support
pip install .

# Generate a command without executing it (copies to clipboard)
openrouter-agent query "show me all .txt files in the current directory"

# Generate and execute a command
openrouter-agent execute "show me all .txt files in the current directory"

Or run directly with Python:

# Generate a command without executing it (copies to clipboard)
python src/cli.py query "show me all .txt files in the current directory"

# Generate and execute a command
python src/cli.py execute "show me all .txt files in the current directory"

Python API Example

from openrouter_agent import Agent

# Initialize with default settings (uses openrouter/quasar-alpha model)
agent = Agent()

# Run a simple completion
result = agent.run("What is the capital of France?")
print(result)

You can also import the specific classes if needed:

from openrouter_agent import OpenRouterAgent, OpenRouterModel

Custom Configuration

from openrouter_agent import Agent

# Initialize with custom settings
agent = Agent(
    agent_name="explanation_agent",
    system_prompt="You are a helpful assistant that explains complex topics in simple terms.",
    openrouter_model_name="anthropic/claude-3-opus-20240229",
    temp=0.7,
    max_result_retries=5,
    openrouter_api_key="your-api-key-here"  # Or use environment variable
)

# Use the agent
result = agent.run_sync("Explain quantum computing in simple terms.")
print(result.data)

Class Reference

OpenRouterModel

The OpenRouterModel class inherits from OpenAIModel and configures it to work with OpenRouter:

OpenRouterModel(
    openrouter_model_name: str = "openrouter/quasar-alpha",
    openrouter_url: str = "https://openrouter.ai/api/v1",
    openrouter_api_key: Optional[str] = os.getenv("OPENROUTER_API_KEY")
)