seltz 0.2.0

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

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.

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.

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

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