> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchport.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK Quickstart

> Get started with the Switchport Python SDK in 5 minutes

## Prerequisites

* Python 3.8 or higher
* A Switchport account ([sign up at switchport.ai](https://switchport.ai))
* Your Switchport API key

## Installation

Install the Switchport SDK using pip:

```bash theme={null}
pip install switchport
```

Or install from source:

```bash theme={null}
git clone https://github.com/switchport-ai/switchport-python.git
cd switchport-python
pip install -e .
```

## Get Your API Key

<Steps>
  <Step title="Sign in to Switchport">
    Go to [switchport.ai](https://switchport.ai) and log in to your account.
  </Step>

  <Step title="Navigate to Settings">
    Go to **Settings** → **API Keys** in the dashboard.
  </Step>

  <Step title="Copy your API key">
    Copy your API key (it starts with `sp_`).
  </Step>
</Steps>

## Set Your API Key

Set your API key as an environment variable:

<CodeGroup>
  ```bash Linux/Mac theme={null}
  export SWITCHPORT_API_KEY=sp_your_key_here
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:SWITCHPORT_API_KEY="sp_your_key_here"
  ```

  ```bash .env file theme={null}
  echo "SWITCHPORT_API_KEY=sp_your_key_here" >> .env
  ```
</CodeGroup>

## Create Your First Prompt

Before using the SDK, you need to create a prompt in the Switchport dashboard:

<Steps>
  <Step title="Create a prompt config">
    1. Go to **Prompts** → **New Prompt Config**
    2. Name: "Welcome Message"
    3. Key: `welcome-message`
    4. Click **Create**
  </Step>

  <Step title="Add a version">
    1. Click **Add Version**
    2. Model: Select `gpt-5` (or another model)
    3. Prompt: `Write a friendly welcome message for {{name}}.`
    4. Click **Save**
  </Step>

  <Step title="Publish the version">
    Click **Publish** on the version you just created.
  </Step>
</Steps>

## Configure LLM API Keys

The SDK calls LLMs on your behalf, so you need to configure your LLM API keys:

<Steps>
  <Step title="Go to Organization Settings">
    Navigate to **Settings** → **Organization Settings**
  </Step>

  <Step title="Add your LLM API keys">
    Add API keys for the LLM providers you want to use:

    * OpenAI API key (for GPT models)
    * Anthropic API key (for Claude models)
    * Google API key (for Gemini models)
  </Step>

  <Step title="Save">
    Click **Save** to store your API keys securely.
  </Step>
</Steps>

## Execute Your First Prompt

Create a file `test_switchport.py`:

```python theme={null}
from switchport import Switchport

# Initialize client (reads API key from environment)
client = Switchport()

# Execute a prompt
response = client.prompts.execute(
    prompt_key="welcome-message",
    variables={"name": "Alice"}
)

print("Generated text:")
print(response.text)
print(f"\nModel: {response.model}")
print(f"Version: {response.version_name}")
```

Run it:

```bash theme={null}
python test_switchport.py
```

You should see output like:

```
Generated text:
Hello Alice! Welcome to our platform. We're excited to have you here!

Model: gpt-5
Version: v1
```

## Record Your First Metric

Now let's track a metric. First, create a metric definition in the dashboard:

<Steps>
  <Step title="Create metric definition">
    1. Go to **Metrics** → **New Metric**
    2. Key: `satisfaction`
    3. Name: "User Satisfaction"
    4. Type: `float`
    5. Click **Create**
  </Step>
</Steps>

Then record a metric in your code:

```python theme={null}
from switchport import Switchport

client = Switchport()

# Execute prompt with subject identification
response = client.prompts.execute(
    prompt_key="welcome-message",
    subject={"user_id": "user_123"},
    variables={"name": "Alice"}
)

# Simulate user feedback (1-5 stars)
user_rating = 4.5

# Record metric with same subject
result = client.metrics.record(
    metric_key="satisfaction",
    value=user_rating,
    subject={"user_id": "user_123"}  # Same context!
)

print(f"Metric recorded! Event ID: {result.metric_event_id}")
```

<Warning>
  Always use the same subject when executing prompts and recording metrics. This ensures metrics are correctly aggregated per prompt version.
</Warning>

## Next Steps

<Columns cols={2}>
  <Card title="A/B Testing" icon="flask" href="/sdk/python/ab-testing">
    Learn how to run A/B tests with multiple prompt versions
  </Card>

  <Card title="API Reference" icon="code" href="/sdk/python/reference/client">
    Explore the full API reference
  </Card>

  <Card title="Examples" icon="book" href="/sdk/python/examples/basic-usage">
    See more code examples
  </Card>

  <Card title="Core Concepts" icon="lightbulb" href="/concepts/core-concepts">
    Understand key concepts
  </Card>
</Columns>