halfred 0.4.0

Python SDK for the Halfred service API

Halfred Python SDK

A Python SDK for consuming the Halfred service API. The API is fully compatible with the OpenAI API standard.

Installation

pip install halfred

Or install from source:

pip install -e .

Quick Start

from halfred import Halfred

# Initialize the client with your API key
client = Halfred(api_key="halfred_xxxxxxxxxxxxxxxx")

# List available models
models = client.models.list()
print(models)

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

Usage

List Models

Get a list of available models:

from halfred import Halfred

client = Halfred(api_key="halfred_xxxxxxxxxxxxxxxxx")
models = client.models.list()

# Access the list of models
for model in models.data:
    print(f"Model ID: {model.id}")

Create Chat Completions

Create a chat completion:

from halfred import Halfred

client = Halfred(api_key="halfred_xxxxxxxxxxxxxxxxx")

completion = client.chat.completions.create(
    model="lite",
    messages=[
        {"role": "user", "content": "What is Python?"}
    ]
)

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

Chat Completion Parameters

completion = client.chat.completions.create(
    model="lite",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    temperature=0.7,              # Sampling temperature (0-2)
    max_tokens=100,              # Maximum tokens to generate
    max_completion_tokens=50,     # Maximum completion tokens
    response_format={"type": "json_object"},  # Response format (optional)
    stream=False                 # Whether to stream the response
)

Error Handling

from halfred import Halfred, HalfredAPIError, HalfredAuthenticationError

client = Halfred(api_key="halfred_xxxxxxxxxxxxxxxxx")

try:
    completion = client.chat.completions.create(
        model="dev",
        messages=[{"role": "user", "content": "Hello"}]
    )
except HalfredAuthenticationError:
    print("Authentication failed. Check your API key.")
except HalfredAPIError as e:
    print(f"API error: {e}")
    print(f"Status code: {e.status_code}")

Custom Configuration

from halfred import Halfred

# Custom base URL and timeout
client = Halfred(
    api_key="halfred_xxxxxxxxxxxxxxxxx",
    base_url="https://api.halfred.ai/v1",  # Optional, defaults to https://api.halfred.ai/v1
    timeout=30  # Optional, defaults to 30 seconds
)

Development

Setup

# Install development dependencies
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black halfred/

API Compatibility

This SDK is designed to be compatible with the OpenAI API standard. The API endpoints and request/response formats follow the same structure as OpenAI's API, making it easy to switch between providers.

The response objects use attribute-based access (e.g., completion.choices[0].message.content) just like the OpenAI Python SDK, ensuring full compatibility with code written for OpenAI's client library.

License

MIT