Metadata-Version: 2.4
Name: halfred
Version: 0.2.0
Summary: Python SDK for the Halfred service API
Author-email: Halfred <support@halfred.com>
License: MIT
Keywords: halfred,api,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Halfred Python SDK

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

## Installation

```bash
pip install halfred
```

Or install from source:

```bash
pip install -e .
```

## Quick Start

```python
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:

```python
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:

```python
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

```python
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

```python
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

```python
from halfred import Halfred

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

## Development

### Setup

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

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
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.

## License

MIT
