seltz 0.1.4
Seltz Python SDK for AI-powered search
Requires Python: >=3.9
Keywords: search, ai, sdk, api

# 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 | int, optional): What to include in results.
- `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:** `SearchResult` with documents and helper methods.

**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)
)

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

# Or use helper methods
first_doc = response.first()
all_urls = response.get_urls()
```

### `Includess`

Configuration for what to include in search results.

**Parameters:**
- `max_documents` (int, optional): Maximum number of documents to return.

**Constructor Pattern (simple cases):**
```python
from seltz import Includes

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

**Fluent Builder Pattern (complex cases):**
```python
from seltz import Includes

# Single field
includes = Includes().max_documents(10)

# Mixed approach
includes = Includes(max_documents=5).max_documents(10)
```

### `SearchResult`

Search result wrapper with helper methods.

**Properties:**
- `documents`: List of Document objects

**Methods:**
- `__len__()`: Get number of documents (`len(result)`)
- `__iter__()`: Iterate over documents (`for doc in result:`)
- `__getitem__(index)`: Get document by index (`result[0]`, `result[-1]`)
- `first()`: Get first document (or None if empty)
- `get_urls()`: Get list of all URLs
- `get_contents()`: Get list of all contents
- `to_dict()`: Convert to dictionary for JSON serialization

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

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

for doc in result:
    print(doc.url)

first = result.first()
if first:
    print(f"Top result: {first.url}")

urls = result.get_urls()

import json
json_data = json.dumps(result.to_dict())
```

### `Document`

Individual search result document.

**Properties:**
- `url`: Document URL (optional)
- `content`: Document content (optional)

**Methods:**
- `has_url()`: Check if URL exists
- `has_content()`: Check if content exists
- `to_dict()`: Convert to dictionary

**Example:**
```python
doc = result[0]

if doc.has_url():
    print(f"URL: {doc.url}")

if doc.has_content():
    print(f"Content: {doc.content[:100]}")

doc_dict = doc.to_dict()
```

## 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