Seltz Python SDK

Official Python SDK for Seltz, the Web search engine for AI agents.

💾 Installation

pip install seltz

Requires Python 3.9 or higher.

⚡️ Quick Start

from seltz import Seltz

client = Seltz(api_key="your-api-key")

# Search the Web
response = client.search("best ai search engines", max_results=10)

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

Output:

URL: https://www.best-ai-search-engines.com
Content: Generative AI can make finding information faster and more intuitive.
If you’re tired of traditional search, explore some of the best AI-powered
search engines we've tested...

Answer

Get a natural-language answer grounded in Web search results, with citations:

from seltz import Seltz

client = Seltz(api_key="your-api-key")

response = client.answer("Who is Apple's next CEO?")

print(response.answer)
for citation in response.citations:
    print(f"Source: {citation.url}")

Pass model to pick an answer tier. It defaults to seltz-base; seltz-pro runs agentic RAG over a single grounding search:

response = client.answer("Who is Apple's next CEO?", model="seltz-pro")

Pass response_format (an OpenAI-style object) to get structured output. response.answer then carries a JSON string matching your schema instead of Markdown; response.citations are still returned:

response = client.answer(
    "Who is Apple's next CEO?",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "news_summary",
            "schema": {
                "type": "object",
                "properties": {"summary": {"type": "string"}},
                "required": ["summary"],
                "additionalProperties": False,
            },
        },
    },
)

import json
print(json.loads(response.answer)["summary"])

Pass system_prompt to steer how the answer is presented — tone, voice, format:

response = client.answer(
    "Who is Apple's next CEO?",
    system_prompt="Answer in British English. Open with a one-line summary, then the detail.",
)

Answer (streaming)

Stream an answer as it is generated, instead of waiting for the full response. answer_stream yields events as they arrive: a citations event first, then text_delta chunks, then a terminal finish_reason. Inspect each event with event.WhichOneof("event"):

from seltz import Seltz

client = Seltz(api_key="your-api-key")

for event in client.answer_stream("Who is Apple's next CEO?"):
    kind = event.WhichOneof("event")
    if kind == "citations":
        for citation in event.citations.citations:
            print(f"Source: {citation.url}")
    elif kind == "text_delta":
        print(event.text_delta, end="", flush=True)
    elif kind == "finish_reason":
        print()

Streaming is also available asynchronously via AsyncSeltz — async for over the events:

import asyncio

from seltz import AsyncSeltz


async def main():
    async with AsyncSeltz(api_key="your-api-key") as client:
        async for event in client.answer_stream("Who is Apple's next CEO?"):
            kind = event.WhichOneof("event")
            if kind == "citations":
                for citation in event.citations.citations:
                    print(f"Source: {citation.url}")
            elif kind == "text_delta":
                print(event.text_delta, end="", flush=True)
            elif kind == "finish_reason":
                print()


asyncio.run(main())

Agent runs

An agent run researches a question with Seltz search and returns a grounded, cited answer. Runs are asynchronous — create one and poll it, or let the SDK wait for you:

from seltz import Seltz

client = Seltz(api_key="your-api-key")

run = client.agent.create_and_wait(
    "Who are the current CEOs of OpenAI, Anthropic and Mistral AI?"
)
print(run.output.text)  # cited markdown; [n] markers cite output.sources
for source in run.output.sources:
    print(f"  [{source.id}] {source.url}")

wait and create_and_wait return once the run reaches a terminal status (AGENT_RUN_STATUS_COMPLETED, _FAILED, or _CANCELLED — compare with the AgentRunStatus enum); run.stop_reason says why it ended.

Pass an OpenAI-style response_format object as output_schema to also get structured output (run.output.structured, a JSON string shaped by your schema, with per-field citations in run.output.grounding):

run = client.agent.create_and_wait(
    "Who are the current CEOs of OpenAI, Anthropic and Mistral AI?",
    output_schema={
        "type": "json_schema",
        "json_schema": {
            "name": "companies",
            "schema": {
                "type": "object",
                "properties": {
                    "companies": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "ceo": {"type": "string"},
                            },
                        },
                    }
                },
            },
        },
    },
)
print(run.output.structured)

The lower-level pieces are there when you need them: client.agent.create returns the pending run at once, client.agent.get(run_id) polls it, client.agent.wait(run_id) polls to completion (an optional timeout bounds the wait client-side; the run keeps executing), client.agent.cancel(run_id) stops a run, and client.agent.list() pages through past runs newest-first via its next cursor.

Fetch

Turn URLs into LLM-ready Markdown. Up to 20 per call, fetched concurrently:

from seltz import FetchStatus, Seltz

client = Seltz(api_key="your-api-key")

response = client.fetch(["https://example.com/"])

for result in response.results:
    if result.status == FetchStatus.FETCH_STATUS_OK:
        print(result.markdown)
    else:
        print(f"{result.requested_url}: {result.error.code}")

A page that cannot be fetched is not a call failure. Every requested URL gets a result, in the order requested, and a failed one carries status = FetchStatus.FETCH_STATUS_ERROR and an error.code.

Async

The same API is available asynchronously via AsyncSeltz — await each call:

import asyncio

from seltz import AsyncSeltz


async def main():
    client = AsyncSeltz(api_key="your-api-key")

    response = await client.search("best ai search engines", max_results=10)

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


asyncio.run(main())

To close the connection deterministically rather than leaving it to garbage collection, use AsyncSeltz as an async context manager (async with) or call await client.close() when done.

📚 Documentation

Browse the documentation for more details.