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 halfredOr with poetry:
poetry add halfredQuick 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-dotenvfrom 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 halfredImport 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
Last updated