# Seltz Python SDK

The official Python SDK for the Seltz AI-powered search API.

## Installation

```bash
pip install seltz
```

## Quick Start

```python
from seltz import Seltz

# Initialize with API key
client = Seltz(api_key="your-api-key")

# Perform a search
response = client.search("your search query")

# Access results
for document in response.documents:
    print(f"URL: {document.url}")
    print(f"Content: {document.content}")
```

## API Key

Set your API key using one of these methods:

1. **Environment variable** (recommended):
   ```bash
   export SELTZ_API_KEY="your-api-key"
   ```

2. **Direct parameter**:
   ```python
   client = Seltz(api_key="your-api-key")
   ```

## API Reference

### `Seltz(api_key=None, endpoint="grpc.seltz.ai", insecure=False)`

Creates a new Seltz client instance.

**Parameters:**
- `api_key` (str, optional): API key for authentication. Defaults to `SELTZ_API_KEY` environment variable.
- `endpoint` (str): API endpoint. Defaults to "grpc.seltz.ai".
- `insecure` (bool): Use insecure connection. Defaults to False.

**Returns:** `Seltz` instance

### `client.search(query, *, includes=None, context=None, profile=None)`

Performs a search query.

**Parameters:**
- `query` (str): The search query text. Keep concise for best performance.
- `includes` (Includes, optional): Protobuf `Includes` message configuring result options.
- `context` (str, optional): Additional context for the query. Include as much relevant information as feasible to improve search quality.
- `profile` (str, optional): Search profile to use (contact support for available profiles).

**Returns:** `SearchResponse` — protobuf message. Access results via `response.documents`.

**Examples:**

```python
response = client.search("Python asyncio tutorial")

# With Includes configuration
from seltz import Includes
response = client.search(
    "Python tutorial",
    includes=Includes(max_documents=10)
)

# Iterate results
for doc in response.documents:
    print(f"URL: {doc.url}")
    print(f"Content: {doc.content}")

# Common patterns
first = response.documents[0] if response.documents else None
urls = [doc.url for doc in response.documents if doc.url]
count = len(response.documents)
```

### `Includes`

Protobuf message configuring what to include in search results. Accepts any fields defined in the proto schema — new fields are automatically available as the API evolves.

```python
from seltz import Includes

includes = Includes(max_documents=5)
response = client.search("query", includes=includes)
```

### `SearchResponse` and `Document`

`search()` returns a `SearchResponse` protobuf message directly.

**`SearchResponse` fields:**
- `documents`: Repeated `Document` messages (iterable, supports indexing and `len()`)

**`Document` fields:**
- `url` (str): Document URL. Returns `""` when not set — use `if doc.url:` to check presence.
- `content` (str): Document content. Returns `""` when not set — use `if doc.content:` to check presence.

```python
result = client.search("Python tutorial")

print(f"Found {len(result.documents)} documents")

for doc in result.documents:
    if doc.url:
        print(f"URL: {doc.url}")
    if doc.content:
        print(f"Content: {doc.content[:100]}")

# Index access
first = result.documents[0] if result.documents else None

# Serialize to dict
from google.protobuf.json_format import MessageToDict
as_dict = MessageToDict(result)
```

> **Note on optional fields:** `Document.url` and `Document.content` are proto3 optional string fields. They return `""` (empty string) when unset, not `None`. Both are falsy, so `if doc.url:` works correctly. Avoid `doc.url is not None` checks.

## Error Handling

```python
from seltz import (
    Seltz,
    SeltzConfigurationError,
    SeltzAuthenticationError,
    SeltzConnectionError,
    SeltzAPIError,
    SeltzTimeoutError,
    SeltzRateLimitError,
)

try:
    client = Seltz(api_key="your-api-key")
    response = client.search("query")
except SeltzConfigurationError as e:
    print(f"Configuration error: {e}")
except SeltzAuthenticationError as e:
    print(f"Authentication error: {e}")
except SeltzConnectionError as e:
    print(f"Connection error: {e}")
except SeltzTimeoutError as e:
    print(f"Timeout error: {e}")
except SeltzRateLimitError as e:
    print(f"Rate limit error: {e}")
except SeltzAPIError as e:
    print(f"API error: {e}")
```

## Requirements

- Python 3.8+
- grpcio >= 1.76.0
- protobuf < 6.0
