seltz 0.1.3

Seltz Python SDK for AI-powered search

Seltz Python SDK

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

Installation

pip install seltz

Quick Start

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

   export SELTZ_API_KEY="your-api-key"
   

2. Direct parameter:

   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:

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

from seltz import Includes

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

Fluent Builder Pattern (complex cases):

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:

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:

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

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