# Lithio Python SDK

A Python SDK for the Lithio API, designed with an OpenAI/xAI/Anthropic-style interface.

## Installation

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

Or install from a directory:

```bash
cd /path/to/sdk
pip install .
```

## Usage

### Basic Usage

```python
from lithio import Client

# Initialize the client
client = Client(
    api_key="your-api-key",
    base_url="https://api.example.com"
)

# Add a query
response = client.add(
    query="This is an example query",
    space="my-space",
    properties={"custom": "property"}
)
print(response.request)  # "processing"

# Search
results = client.search(
    query="search query",
    limit=10,
    match_threshold=0.5,
    rerank_alpha=0.3,
    space="my-space"
)
print(results.results)
```

### Using Client Properties

You can set default properties on the client that will be included in all requests:

```python
client = Client(
    api_key="your-api-key",
    base_url="https://api.example.com",
    properties={
        "environment": "production",
        "version": "1.0"
    }
)

# These properties will be automatically included
client.add(query="test query")
client.search(query="test search")

# You can override or add more properties per request
client.add(
    query="test query",
    properties={"additional": "property"}
)
```

### Context Manager

The client can be used as a context manager to ensure proper cleanup:

```python
with Client(api_key="your-api-key", base_url="https://api.example.com") as client:
    response = client.add(query="example")
    results = client.search(query="example")
```

### Manual Cleanup

```python
client = Client(api_key="your-api-key", base_url="https://api.example.com")
try:
    response = client.add(query="example")
finally:
    client.close()
```

## API Reference

### Client

#### `Client.__init__(api_key, base_url="http://localhost:8000", properties=None, timeout=30.0)`

Initialize the Lithio client.

**Parameters:**
- `api_key` (str): Your Lithio API key
- `base_url` (str): Base URL for the API (default: `http://localhost:8000`)
- `properties` (dict, optional): Default properties to include in all requests
- `timeout` (float): Request timeout in seconds (default: `30.0`)

#### `Client.add(query, space=None, properties=None) -> AddResponse`

Add a query to the system.

**Parameters:**
- `query` (str): The query string to add
- `space` (str, optional): Optional space identifier
- `properties` (dict, optional): Optional properties (merged with client defaults)

**Returns:**
- `AddResponse`: Response containing the request status

#### `Client.search(query, limit=None, match_threshold=None, rerank_alpha=None, space=None, properties=None) -> SearchResponse`

Search for results.

**Parameters:**
- `query` (str): The search query string
- `limit` (int, optional): Maximum number of results (default: 5)
- `match_threshold` (float, optional): Minimum match threshold (default: 0.4)
- `rerank_alpha` (float, optional): Reranking alpha parameter (default: 0.2)
- `space` (str, optional): Optional space identifier
- `properties` (dict, optional): Optional properties (merged with client defaults)

**Returns:**
- `SearchResponse`: Response containing the search results

## Error Handling

The SDK raises `httpx.HTTPError` for HTTP errors. You can handle them like this:

```python
import httpx
from lithio import Client

client = Client(api_key="your-api-key", base_url="https://api.example.com")

try:
    response = client.add(query="example")
except httpx.HTTPStatusError as e:
    if e.response.status_code == 401:
        print("Invalid API key")
    else:
        print(f"HTTP error: {e}")
except httpx.RequestError as e:
    print(f"Request error: {e}")
```

