Python SDK

The Python SDK is the API / SDK path for app and backend developers. Use it when Snipara is part of your product, sync pipeline, or server-side workflow.

Primary path

For product integration: use API / SDK

Use Hosted MCP for LLM agents. Use the Python SDK when software systems need to upload, sync, query, provision, or inspect Snipara programmatically.

New in v0.1.0

The snipara package consolidates 5 separate configuration systems into a single .snipara.tomlfile, provides a unified async/sync Python API, supports event-driven file synchronization, and can participate in an auto-feedback loop (query → execute → remember).

Installation

Core (context queries, memory, config)

pip install snipara

With file watcher

pip install snipara[watch]

With Snipara code execution

pip install snipara[runtime]

Everything

pip install snipara[all]

Requirements

Python 3.10+ (3.11+ recommended for native TOML support)
snipara-mcp >= 2.3.0 (installed automatically)
watchfiles >= 0.21.0 (optional, for snipara watch)
snipara-sandbox >= 0.1.0 (optional, for snipara execute)

Quick Start

1. Initialize Configuration

snipara init

This creates .snipara.tomlin your project root interactively. You'll be prompted for your project slug, API key, default token budget, search mode, and optional Snipara Sandbox settings.

2. Query Context (Async)

from snipara import Snipara

async with Snipara() as s:

    result = await s.query("how does authentication work?")

    for section in result.get("sections", []):

        print(f"[{section['relevance']:.0%}] {section['title']}")

        print(section["content"][:200])

3. Query Context (Sync)

from snipara import SniparaSync

with SniparaSync() as s:

    result = s.query("how does authentication work?")

    print(result)

Sync client works in Jupyter

SniparaSync handles nested event loops automatically, so it works in Jupyter notebooks without any special setup.

4. Full Feedback Loop

from snipara import Snipara

async with Snipara() as s:

    # query -> execute -> remember (all in one call)

    result = await s.run(

        "fix the rate limiting bug in the API",

        remember_learnings=True,

    print(f"Context tokens: {result.context.total_tokens}")

    print(f"Execution: {result.execution.summary}")

    print(f"Memories stored: {len(result.memories_stored)}")

Configuration

The .snipara.toml file is the single source of truth for all Snipara settings. Place it in your project root (alongside .git/).

PROJECT - Authentication and API connection

[project]

slug = "my-project"

api_key = "snipara_abc123def456..."

api_url = "https://api.snipara.com"

CONTEXT - Query defaults

[context]

max_tokens = 4000

search_mode = "hybrid"

include_summaries = true

shared_context = true

RUNTIME - snipara-sandbox code execution

[runtime]

backend = "anthropic"

model = "claude-sonnet-4-20250514"

environment = "local"

max_depth = 4

SYNC - File watcher patterns

[sync]

include = ["docs/**/*.md", "*.md"]

exclude = ["node_modules/**", ".git/**"]

debounce_ms = 500

Resolution Order

Configuration is resolved with layered priority (highest wins):

Priority	Source	Description
1 (highest)	Environment variables	`SNIPARA_API_KEY`, `SNIPARA_PROJECT_ID`, etc.
2	`.snipara.toml` (project)	Walk up from CWD to git root
3	`~/.config/snipara/config.toml`	Global user defaults
4	Legacy project config	Deprecated — emits warning
5 (lowest)	Built-in defaults	Hardcoded in Pydantic models

1 (highest)Environment variables

SNIPARA_API_KEY, SNIPARA_PROJECT_ID, etc.

2.snipara.toml (project)

Walk up from CWD to git root

3~/.config/snipara/config.toml

Global user defaults

4Legacy project config

Deprecated - emits warning

5 (lowest)Built-in defaults

Hardcoded in Pydantic models

SDK API Reference

The SDK provides both async (Snipara) and sync (SniparaSync) clients with the same API surface. All methods below are shown in async form.

Context Optimization

Method	Description	Key Parameters
`query(query)`	Query for optimized, ranked context sections	`max_tokens`, `search_mode`
`search(pattern)`	Search documentation with regex patterns	`max_results`
`plan(query)`	Generate execution plan for complex queries	`strategy`, `max_tokens`
`multi_query(queries)`	Execute multiple queries with shared budget	`max_tokens`
`shared_context()`	Get merged team shared context	`categories`, `max_tokens`

query(query)

Query for optimized, ranked context sections

Params: max_tokens, search_mode

search(pattern)

Search documentation with regex patterns

Params: max_results

plan(query)

Generate execution plan for complex queries

Params: strategy, max_tokens

multi_query(queries)

Execute multiple queries with shared budget

Params: max_tokens

shared_context()

Get merged team shared context

Params: categories, max_tokens

Document Management

Method	Description	Key Parameters
`upload(path, content)`	Upload or update a single document	`path`, `content`
`sync_documents(documents)`	Bulk sync multiple documents	`delete_missing`

upload(path, content)

Upload or update a single document

Params: path, content

sync_documents(documents)

Bulk sync multiple documents

Params: delete_missing

Agent Memory

Method	Description	Key Parameters
`remember(content)`	Store a memory for later semantic recall	`type`, `scope`, `category`, `ttl_days`
`recall(query)`	Semantically recall relevant memories	`limit`, `min_relevance`, `type`

remember(content)

Store a memory for later semantic recall

Params: type, scope, category, ttl_days

recall(query)

Semantically recall relevant memories

Params: limit, min_relevance, type

Code Execution & Feedback Loop

Method	Description	Key Parameters
`execute(task)`	Execute a task via snipara-sandbox (requires `[runtime]`)	`context`, `environment`, `max_depth`
`run(task)`	Complete feedback loop: query → execute → remember	`context_query`, `remember_learnings`, `memory_types`

execute(task)

Execute a task via snipara-sandbox (requires [runtime])

Params: context, environment, max_depth

run(task)

Complete feedback loop: query > execute > remember

Params: context_query, remember_learnings, memory_types

Result Types

Type	Key Fields	Description
`QueryResult`	`sections`, `total_tokens`, `suggestions`	Context query result
`SearchResult`	`matches`, `total_matches`	Regex search result
`PlanResult`	`steps`, `total_tokens`	Execution plan
`ExecuteResult`	`response`, `trajectory`, `total_cost`	Code execution result
`RunResult`	`context`, `execution`, `memories_stored`	Full feedback loop result
`MemoryResult`	`memory_id`, `memories`	Remember/recall result
`SyncResult`	`created`, `updated`, `deleted`	Bulk sync result

QueryResult

Context query result

Fields: sections, total_tokens, suggestions

SearchResult

Regex search result

Fields: matches, total_matches

PlanResult

Execution plan

Fields: steps, total_tokens

ExecuteResult

Code execution result

Fields: response, trajectory, total_cost

RunResult

Full feedback loop result

Fields: context, execution, memories_stored

MemoryResult

Remember/recall result

Fields: memory_id, memories

SyncResult

Bulk sync result

Fields: created, updated, deleted

CLI Reference

The snipara CLI is installed automatically with the SDK. All commands work from any directory within a project that has a .snipara.toml.

Command	Description	Example
`snipara init`	Create or migrate `.snipara.toml`	`snipara init --migrate`
`snipara config`	View resolved config or file path	`snipara config show`
`snipara status`	Show auth, config, and Snipara Sandbox status	`snipara status`
`snipara login`	Authenticate via browser (device flow)	`snipara login`
`snipara logout`	Clear stored tokens	`snipara logout`
`snipara query`	Query documentation from the CLI	`snipara query "auth" --max-tokens 8000`
`snipara sync`	One-shot sync of local files	`snipara sync --dry-run`
`snipara watch`	Watch and sync changes in real-time	`snipara watch`

snipara init

Create or migrate .snipara.toml

Example: snipara init --migrate

snipara config

View resolved config or file path

Example: snipara config show

snipara status

Show auth, config, and Snipara Sandbox status

Example: snipara status

snipara login

Authenticate via browser (device flow)

Example: snipara login

snipara logout

Clear stored tokens

Example: snipara logout

snipara query

Query documentation from the CLI

Example: snipara query "auth" --max-tokens 8000

snipara sync

One-shot sync of local files

Example: snipara sync --dry-run

snipara watch

Watch and sync changes in real-time

Example: snipara watch

File Watcher

The snipara watch command uses watchfiles (Rust-based, cross-platform, async) to monitor your project for file changes and automatically sync them to Snipara.

snipara watch

Watching /project (2 include, 4 exclude patterns)

Synced: docs/api.md

Synced: docs/auth.md

Configure patterns in the [sync] section of .snipara.toml:

[sync]

include = ["docs/**/*.md", "*.md", "src/**/*.py"]

exclude = ["node_modules/**", ".git/**", "dist/**"]

debounce_ms = 500

Dry run

Lists files, no uploads

snipara sync --dry-run

One-shot

Syncs all files once, then exits

snipara sync

Watch

Continuous sync on file changes

snipara watch

Key behaviors

Debounce: Configurable via sync.debounce_ms (default 500ms)
Binary files: Automatically skipped with a warning
Upload errors: Logged but don't stop the watcher
Exclude patterns checked first, then include patterns

Relationship to snipara-mcp

The snipara SDK may reuse lower-level client code internally, but its public purpose is API / SDK integration for software systems.

Do not present snipara-mcp as the default way to connect assistants. Use Hosted MCP for LLM agents, and use snipara-mcp directly only for local stdio, compatibility, package development, or advanced tests.

Next Steps

MCP Tools Reference

Full documentation for 50+ Snipara MCP tools.

Snipara Sandbox

Safe code execution with Docker isolation and trajectory logging.

Agent Memory

Remember decisions and context across sessions.

Other Integrations

Claude Code, VS Code, Cursor, Windsurf, and more.