API reference

The SDK supports independent requests with supplied context, source definitions, and bounded research. Executable plugin discovery in the design remains planned.

sourcesift

SourceSift: a Python SDK for requests with explicit document context.

SourceSift

Run independent requests through the shared application.

Parameters:

Name Type Description Default
settings Settings | None

Explicit resolved settings; bypasses file/environment loading.

 None
config_path str | Path | None

Optional TOML path when settings are not supplied.

 None
model str | None

Explicit OpenRouter model ID overriding config/environment values.

 None

register_source(source: Source) -> None

Add a definition for future runs; duplicate identities are rejected.

Call before starting requests. Each run snapshots the immutable registry. Third-party executable plugins are a later capability.

run(request: str | Request, *, files: Sequence[str | Path] = (), stdin: BinaryIO | None = None) -> Result async

Run one request with optional files and an explicitly supplied input stream.

No previous run's context or conversation is retained. The SDK never reads process stdin implicitly. Use Request for labeled context or plain output.

run_sync(request: str | Request, *, files: Sequence[str | Path] = (), stdin: BinaryIO | None = None) -> Result

Run from an ordinary script; use await run() inside an active event loop.

session(*, files: Sequence[str | Path] = ()) -> Session

Create an independent in-memory conversation with snapshotted context.

Session

One bounded in-memory conversation. Failed/cancelled turns never commit.

Create with app.session(). Settings, sources, and configured context are snapshotted. reset() reloads context files and clears completed turns. Only one turn may run at a time; cancel its asyncio task to interrupt it.

busy: bool property

Whether a turn is active (including cleanup after cancellation).

context: tuple[ContextDocument, ...] property

The loaded context snapshot, including explicit personal guidance.

turns: tuple[tuple[str, Result], ...] property

Completed user prompts and validated results in order.

reset() -> None

Start fresh and reload files; a read error preserves the old session.

run(request: str | Request, *, files: Sequence[str | Path] = (), on_event: EventHandler | None = None) -> Result async

Run a follow-up; optional synchronous callback receives provisional events.

Callbacks should return quickly without blocking. The returned Result is authoritative; drafts can be replaced during citation repair or discarded on cancellation/error. Tool/HTTP/model budgets restart for each turn.

SessionEvent

Bases: Contract

UI-independent progress; streamed drafts are provisional until run returns.

Request

Bases: Contract

One independent request; documents are context, not system instructions.

ContextDocument

Bases: Contract

Text supplied by the user, with a label rather than an external citation.

Reference

Bases: Contract

Retrieved evidence behind one citation; URLs and dates come from adapters.

ResearchWindow

Bases: Contract

Inclusive window start and retrieval-time end, with the configured zone.

Source

Bases: Contract

Publication metadata used for semantic selection, not keyword routing.

Feed access means recent entries only. A website without feeds uses bounded RSS/Atom discovery; article access does not imply search or archive access.

SourceRegistry

Validated catalog. Duplicate IDs, names, or aliases fail explicitly.

list() -> tuple[Source, ...]

Return enabled definitions in registration order.

resolve(name: str) -> Source | None

Resolve a known ID/name/alias; never silently substitute a publication.

SourcesSettings

Bases: Contract

Enabled catalog additions and freshness settings; selection stays semantic.

Result

Bases: Contract

Answer, explicit capability limitations, and reported usage.

Usage

Bases: Contract

Token counts reported by the model runtime; not a billing estimate.

Settings

Bases: Contract

Resolved application settings shared by the SDK and CLI.

AgentSettings

Bases: Contract

OpenRouter model and credential. No model is selected implicitly.

ContextSettings

Bases: Contract

Ordered background files, resolved relative to their configuration file.

Limits

Bases: Contract

Request and session limits. Byte limits count UTF-8 data, not model tokens.

SourceSiftError

Bases: Exception

Base class for expected application failures.

ConfigurationError

Bases: SourceSiftError

Configuration or credentials are missing or invalid.

InputError

Bases: SourceSiftError

A request or context input cannot be used.

ModelError

Bases: SourceSiftError

The configured model could not complete the request.

load_settings(config_path: str | Path | None = None, *, overrides: dict[str, Any] | None = None) -> Settings

Load defaults < TOML < environment < explicit nested overrides.

An absent default config is allowed. An explicitly selected config must exist. Supported environment variables are SOURCESIFT_CONFIG, SOURCESIFT_MODEL, SOURCESIFT_REASONING_EFFORT, and OPENROUTER_API_KEY. No dotenv files or working-directory config are loaded.

hello() -> str

Return the original scaffold greeting, retained for compatibility.