SDK Reference

Python SDK

The official Python client for SkillRouter. Discover, route, and execute AI skills from any Python application.

View on GitHub

Installation

Install the SkillRouter Python SDK using pip. Python 3.8 or higher is required.

pip install skillrouter

Or with Poetry: poetry add skillrouter

Quick Start

Get up and running in under a minute. Initialize the client with your API key and start discovering skills.

from skillrouter import SkillRouter

# Initialize the client
client = SkillRouter(api_key="sr_your_api_key")

# Discover the best skill for a task
result = client.discover("Send a welcome email to new users")
print(result.skill.name)       # "sendgrid-send-email"
print(result.confidence)        # 0.97

# Execute the skill
response = client.execute(
    skill_id=result.skill.id,
    params={
        "to": "user@example.com",
        "subject": "Welcome!",
        "body": "Thanks for signing up."
    }
)
print(response.status)  # "success"

Client Initialization

The SkillRouter client accepts several configuration options at initialization.

from skillrouter import SkillRouter

client = SkillRouter(
    api_key="sr_your_api_key",     # Required. Your API key.
    base_url="https://api.skillrouter.dev",  # Optional. API base URL.
    timeout=30,                     # Optional. Request timeout in seconds.
    max_retries=3,                  # Optional. Number of retry attempts.
)

# Or use an environment variable (SKILLROUTER_API_KEY)
client = SkillRouter()  # reads from env automatically

Core Methods

discover(query, **kwargs)

Finds the best matching skill for a natural language query. Uses semantic matching to identify the most relevant skill from the registry.

result = client.discover(
    query="Process a credit card payment",
    category="payments",       # Optional. Filter by category.
    top_k=3,                   # Optional. Return top K matches.
    threshold=0.8              # Optional. Minimum confidence score.
)

# Access the top result
print(result.skill.id)          # "stripe-checkout"
print(result.skill.provider)    # "stripe"
print(result.confidence)         # 0.95

# Access multiple results when top_k > 1
for match in result.matches:
    print(f"{match.skill.name}: {match.confidence}")

execute(skill_id, params)

Executes a skill with the given parameters. SkillRouter handles authentication, rate limiting, and retries automatically.

response = client.execute(
    skill_id="stripe-checkout",
    params={
        "amount": 2999,
        "currency": "usd",
        "customer_email": "buyer@example.com"
    }
)

print(response.status)          # "success"
print(response.data)            # {"payment_id": "pi_abc123", ...}
print(response.latency_ms)      # 230

list_skills(**kwargs)

Returns a paginated list of all available skills. Supports filtering by category, provider, and status.

skills = client.list_skills(
    category="payments",       # Optional. Filter by category.
    provider="stripe",         # Optional. Filter by provider.
    page=1,                    # Optional. Page number.
    per_page=20                # Optional. Results per page.
)

for skill in skills.items:
    print(f"{skill.id}: {skill.name}")

print(f"Total: {skills.total}")  # Total available skills

Async Support

The SDK ships with first-class async support via AsyncSkillRouter. All core methods are available as coroutines.

import asyncio
from skillrouter import AsyncSkillRouter

async def main():
    client = AsyncSkillRouter(api_key="sr_your_api_key")

    # All methods are awaitable
    result = await client.discover("Send a Slack notification")
    response = await client.execute(
        skill_id=result.skill.id,
        params={"channel": "#general", "message": "Hello!"}
    )
    print(response.status)

    # Concurrent discovery
    results = await asyncio.gather(
        client.discover("Send an email"),
        client.discover("Create a calendar event"),
        client.discover("Process a payment"),
    )
    for r in results:
        print(r.skill.name)

asyncio.run(main())

Error Handling

The SDK raises typed exceptions for different failure modes, making it easy to handle errors gracefully.

from skillrouter.exceptions import (
    SkillRouterError,          # Base exception
    AuthenticationError,       # Invalid or missing API key
    RateLimitError,            # Rate limit exceeded
    SkillNotFoundError,        # Skill ID does not exist
    ExecutionError,            # Skill execution failed
    ValidationError,           # Invalid parameters
)

try:
    response = client.execute(
        skill_id="stripe-checkout",
        params={"amount": 2999}
    )
except AuthenticationError:
    print("Check your API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Invalid params: {e.errors}")
except ExecutionError as e:
    print(f"Execution failed: {e.message}")
except SkillRouterError as e:
    print(f"Unexpected error: {e}")

Tip: Always catch SkillRouterError as a fallback. All SDK exceptions inherit from it.

Next Steps

Quick Start Guide GitHub Repository