Installation & Setup

Install and configure the TurnWise Python SDK

Installation & Setup

Prerequisites

• Python 3.10 or higher
• TurnWise account with API key
• OpenRouter API key (or other supported LLM provider)

Installation

Install the SDK using pip:

pip install turnwise-sdk

Or with poetry:

poetry add turnwise

Getting Your API Keys

TurnWise API Key

1. Log in to TurnWise
2. Go to Settings → API Keys
3. Click “Create API Key”
4. Copy your API key (starts with tw_)

OpenRouter API Key

1. Sign up at OpenRouter
2. Go to Keys page
3. Create a new API key
4. Copy your API key (starts with sk-or-)

Configuration

Environment Variables (Recommended)

Set your API keys as environment variables:

export TURNWISE_API_KEY="tw_your_api_key_here"
export OPENROUTER_API_KEY="sk-or-your_key_here"

Then initialize the client without passing keys:

from turnwise import TurnWiseClient

client = TurnWiseClient()

Direct Configuration

Pass keys directly when creating the client:

from turnwise import TurnWiseClient

client = TurnWiseClient(
    turnwise_api_key="tw_your_api_key",
    openrouter_api_key="sk-or-your_key"
)

Configuration File

Create a .env file in your project root:

TURNWISE_API_KEY=tw_your_api_key
OPENROUTER_API_KEY=sk-or-your_key

Then load it:

from dotenv import load_dotenv
from turnwise import TurnWiseClient

load_dotenv()
client = TurnWiseClient()

Verify Installation

Test your setup:

import asyncio
from turnwise import TurnWiseClient

async def main():
    client = TurnWiseClient()
    
    # Verify API key
    result = await client.verify()
    print(f"Connected as user: {result.user_id}")
    
    await client.close()

asyncio.run(main())

Optional Configuration

Custom Base URL

For self-hosted instances or testing:

client = TurnWiseClient(
    turnwise_api_key="tw_xxx",
    openrouter_api_key="sk-or-xxx",
    turnwise_base_url="https://your-instance.com"
)

Default Model

Set a default model for all evaluations:

client = TurnWiseClient(
    turnwise_api_key="tw_xxx",
    openrouter_api_key="sk-or-xxx",
    default_model="openai/gpt-4o-mini"
)

Troubleshooting

Import Errors

If you get import errors, ensure you’re using Python 3.10+:

python --version  # Should be 3.10 or higher

Authentication Errors

If you see authentication errors:

1. Verify your API keys are correct
2. Check that keys are set in environment variables
3. Ensure keys haven’t expired or been revoked

Connection Errors

If you can’t connect to TurnWise:

1. Check your internet connection
2. Verify the base URL is correct
3. Check if TurnWise is experiencing downtime

Next Steps

Basic Usage

Run your first evaluation

API Reference

Explore the full API