Halfred Python SDK

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

Installation

Install the Halfred SDK using pip:

pip install halfred

Or with poetry:

poetry add halfred

Quick Start

Basic Setup

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

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

import os
from halfred import Halfred

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

Or use python-dotenv:

pip install python-dotenv

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

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

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

With System Message

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

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

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:

# 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.

Response Format

JSON Mode

Request JSON-formatted responses:

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:

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

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:

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.

# 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

models = client.models.list()

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

Best Practices

1. Use Environment Variables

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

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

2. Handle Errors Gracefully

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

# 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

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

# Make sure the package is installed
pip install halfred

Import Errors

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

API Key Issues

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: [email protected]

• Discord: Join our community

• GitHub: Report issues

Next Steps

• Learn about Model Profiles

• Explore the REST API Reference

• Check out Best Practices