> For the complete documentation index, see [llms.txt](https://docs.halfred.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.halfred.ai/02-sdk-integration/02-python.md).

# Halfred Python SDK

Official Halfred SDK for Python applications with modern features, type hints, and easy integration.

## Installation

Install the Halfred SDK using pip:

```bash
pip install halfred
```

Or with poetry:

```bash
poetry add halfred
```

## Quick Start

### Basic Setup

```python
from halfred import Halfred

client = Halfred(api_key="halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")

completion = client.chat.completions.create(
    model="standard",
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ]
)

print(completion.choices[0].message.content)
```

### With Environment Variables

```bash
# .env file or environment
export HALFRED_API_KEY="halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

```python
import os
from halfred import Halfred

client = Halfred(api_key=os.environ.get("HALFRED_API_KEY"))
```

Or use python-dotenv:

```bash
pip install python-dotenv
```

```python
from dotenv import load_dotenv
from halfred import Halfred

load_dotenv()
client = Halfred(api_key=os.environ.get("HALFRED_API_KEY"))
```

## Chat Completions

### Simple Completion

```python
completion = client.chat.completions.create(
    model="standard",
    messages=[
        {"role": "user", "content": "Hello, Halfred!"}
    ]
)

print(completion.choices[0].message.content)
```

### With System Message

```python
completion = client.chat.completions.create(
    model="standard",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful programming assistant."
        },
        {
            "role": "user",
            "content": "How do I create an async function in Python?"
        }
    ]
)

print(completion.choices[0].message.content)
```

### Conversation History

```python
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What's the weather like?"},
    {"role": "assistant", "content": "I don't have access to real-time weather data."},
    {"role": "user", "content": "What can you help me with?"}
]

completion = client.chat.completions.create(
    model="standard",
    messages=messages
)

print(completion.choices[0].message.content)
```

### With Options

```python
completion = client.chat.completions.create(
    model="deepthink",
    messages=[
        {"role": "user", "content": "Explain quantum computing"}
    ],
    temperature=0.7,  # Control randomness (0.0 - 2.0)
    max_tokens=500,  # Limit response length
)
```

## Choosing a Model Profile

Halfred offers different profiles optimized for various use cases:

```python
# LITE - Fast and cost-effective
lite = client.chat.completions.create(
    model="lite",
    messages=[{"role": "user", "content": "Quick question..."}]
)

# STANDARD - Balanced performance (recommended)
standard = client.chat.completions.create(
    model="standard",
    messages=[{"role": "user", "content": "General query..."}]
)

# DEEPTHINK - Advanced reasoning
deepthink = client.chat.completions.create(
    model="deepthink",
    messages=[{"role": "user", "content": "Complex analysis..."}]
)

# DEV - Free for testing
dev = client.chat.completions.create(
    model="dev",
    messages=[{"role": "user", "content": "Test message..."}]
)
```

Learn more about profiles in our [Model Profiles guide](https://docs.halfred.ai/03-concepts/01-profiles.md).

## Response Format

### JSON Mode

Request JSON-formatted responses:

```python
import json

completion = client.chat.completions.create(
    model="standard",
    messages=[
        {
            "role": "user",
            "content": "List three programming languages in JSON format"
        }
    ],
    response_format={"type": "json_object"}
)

data = json.loads(completion.choices[0].message.content)
print(data)
# Expected output:
# {
#   "languages": ["JavaScript", "Python", "Go"]
# }
```

### JSON Schema Mode

Enforce a specific JSON structure using JSON Schema:

```python
import json

completion = client.chat.completions.create(
    model="standard",
    messages=[
        {
            "role": "user",
            "content": "Generate information about three programming languages"
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "programming_languages",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "languages": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "year_created": {"type": "number"},
                                "paradigm": {"type": "string"},
                                "popular_frameworks": {
                                    "type": "array",
                                    "items": {"type": "string"},
                                },
                            },
                            "required": ["name", "year_created", "paradigm"],
                            "additionalProperties": False,
                        },
                    },
                },
                "required": ["languages"],
                "additionalProperties": False,
            },
        },
    }
)

data = json.loads(completion.choices[0].message.content)
print(data)
# Expected output:
# {
#   "languages": [
#     {
#       "name": "JavaScript",
#       "year_created": 1995,
#       "paradigm": "Multi-paradigm",
#       "popular_frameworks": ["React", "Vue", "Angular"]
#     },
#     {
#       "name": "Python",
#       "year_created": 1991,
#       "paradigm": "Multi-paradigm",
#       "popular_frameworks": ["Django", "Flask", "FastAPI"]
#     },
#     {
#       "name": "Go",
#       "year_created": 2009,
#       "paradigm": "Concurrent",
#       "popular_frameworks": ["Gin", "Echo", "Fiber"]
#     }
#   ]
# }
```

## Error Handling

```python
from halfred import Halfred, HalfredError

client = Halfred(api_key=os.environ.get("HALFRED_API_KEY"))

try:
    completion = client.chat.completions.create(
        model="standard",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(completion.choices[0].message.content)

except HalfredError as e:
    if e.status_code == 401:
        print("Invalid API key")
    elif e.status_code == 429:
        print("Rate limit exceeded or insufficient credits")
    elif e.status_code == 400:
        print(f"Bad request: {e.message}")
    else:
        print(f"API error: {e.message}")
```

## Type Hints Support

The SDK includes full type hints for better IDE support:

```python
from halfred import Halfred
from halfred.types import (
    ChatCompletion,
    ChatCompletionMessage,
    ChatCompletionCreateParams
)

client: Halfred = Halfred(api_key=os.environ.get("HALFRED_API_KEY"))

messages: list[ChatCompletionMessage] = [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "Hello!"}
]

params: ChatCompletionCreateParams = {
    "model": "standard",
    "messages": messages,
    "temperature": 0.7
}

completion: ChatCompletion = client.chat.completions.create(**params)
```

## Streaming Responses (Coming Soon)

Real-time streaming support is coming soon. Contact support for early access.

```python
# Coming soon
stream = client.chat.completions.create(
    model="standard",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

## List Available Models

```python
models = client.models.list()

for model in models.data:
    print(f"Model: {model.id}")
```

## Best Practices

### 1. Use Environment Variables

```python
# ✅ Good
import os
client = Halfred(api_key=os.environ.get("HALFRED_API_KEY"))

# ❌ Bad
client = Halfred(api_key="halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")
```

### 2. Handle Errors Gracefully

```python
def get_completion(prompt: str) -> str:
    try:
        completion = client.chat.completions.create(
            model="standard",
            messages=[{"role": "user", "content": prompt}]
        )
        return completion.choices[0].message.content
    except HalfredError as e:
        print(f"Failed to get completion: {e}")
        return "Sorry, I couldn't process that request."
```

### 3. Choose the Right Profile

```python
# Simple UI responses - use lite
ui_response = client.chat.completions.create(
    model="lite",
    messages=[{"role": "user", "content": "Format this date"}]
)

# Complex analysis - use deepthink
analysis = client.chat.completions.create(
    model="deepthink",
    messages=[{"role": "user", "content": "Analyze this business strategy..."}]
)
```

### 4. Monitor Token Usage

```python
completion = client.chat.completions.create(
    model="standard",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(f"Tokens used: {completion.usage.total_tokens}")
print(f"Prompt tokens: {completion.usage.prompt_tokens}")
print(f"Completion tokens: {completion.usage.completion_tokens}")
```

## Troubleshooting

### Package Not Found

```bash
# Make sure the package is installed
pip install halfred
```

### Import Errors

```python
# Check if package is installed correctly
import halfred
print(halfred.__version__)
```

### API Key Issues

```python
import os

# Check if API key is loaded
api_key = os.environ.get("HALFRED_API_KEY")
if not api_key:
    raise ValueError("HALFRED_API_KEY environment variable is required")

client = Halfred(api_key=api_key)
```

## Support

* **Documentation**: <https://docs.halfred.ai>
* **Email**: <support@halfred.ai>
* **Discord**: [Join our community](https://discord.gg/wS2awX4EV7)
* **GitHub**: [Report issues](https://github.com/halfred-ai/halfred-python)

## Next Steps

* Learn about [Model Profiles](https://docs.halfred.ai/03-concepts/01-profiles.md)
* Explore the [REST API Reference](https://docs.halfred.ai/04-api-reference/01-endpoints.md)
* Check out [Best Practices](https://docs.halfred.ai/05-advanced/01-best-practices.md)
