tokensaver-sdk 0.1.9

Python SDK for the TokenSaver API: pipelines, chat sessions, and pricing estimates

TokenSaver SDK

Python client for the TokenSaver API (POST /pipelines/run, RAG, chat sessions, pricing).
Only HTTP transport and response normalization run in this package; all pipeline logic stays on the server.

Get started (public) : sign up or sign in at platform.tokensaver.fr, open your workspace in the console, then the API Reference page (examples, parameters, SDK methods).

Also : tokensaver.fr — product marketing / positioning. https://api.tokensaver.fr/api/v1 — HTTP API this SDK calls by default (base_url); override base_url only for another deployment.

Installation

pip install tokensaver-sdk

Development inside the monorepo:

cd packages/sdk
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

Maintainers with a clone of the private repository can read the long-form architecture notes at docs/ARCHITECTURE-SDK-TOKENSAVER.md (repo root). That path is not published on PyPI.

Configuration

• api_key (required): TokenSaver API key (ts_...).
• base_url (optional): API base URL; default https://api.tokensaver.fr/api/v1.
• provider_api_key (optional): Ephemeral LLM API key sent on every ask / run_pipeline when set; overrides organisation keys for that run only; never persisted. You can also pass provider_api_key= on a single call.

LLM providers (hosted vs self-hosted)

On the default public API (base_url omitted or https://api.tokensaver.fr/api/v1), the product matches the console today: only OpenAI is supported for provider / models (demo and Free plan; Anthropic, Google Gemini, and Mistral keys are not configurable in the UI yet). The SDK rejects other provider values client-side on that URL so behaviour stays aligned with the front.

The HTTP API and backend can route additional providers when enabled; API_PIPELINE_LLM_PROVIDERS in the SDK lists those codes for reference. For Anthropic / Google / Mistral today, use a custom base_url pointed at a deployment where those providers are enabled, or wait until the hosted offering expands.

Constants (optional imports): HOSTED_SAAS_LLM_PROVIDERS, API_PIPELINE_LLM_PROVIDERS, DEFAULT_PUBLIC_API_BASE_URL. Wrong provider on the hosted URL raises ValidationError with code HOSTED_LLM_PROVIDER (ERROR_HOSTED_LLM_PROVIDER).

The API also rejects provider / model pairs that are not in the active llm_models catalogue (HTTP 400, LLM_MODEL_NOT_SUPPORTED) — the SDK maps that to ValidationError (ERROR_LLM_MODEL_NOT_SUPPORTED). List allowed pairs with GET /api/v1/llm-reference/models.

from tokensaver_sdk import TokenSaver

ts = TokenSaver(api_key="ts_...")
# Local backend:
# ts = TokenSaver(api_key="ts_...", base_url="http://localhost:8000/api/v1")
# Default LLM key for all runs (optional):
# ts = TokenSaver(api_key="ts_...", provider_api_key="sk-...")

Pipeline calls (ask / run_pipeline)

ask() returns a RunResult (.text, .metrics, .trace, .context).
run_pipeline() returns the raw API JSON.

Module flags (off by default in the SDK, same as in the console):
use_cache, use_rag, use_compression, use_pii_filter, stream.

Advanced parameters (aligned with PipelineRunRequest / console) — passed through to the JSON body as-is:

Parameter	Purpose
temperature	LLM temperature (0–2).
rag_similarity_threshold	RAG similarity threshold (0–1).
cache_similarity_threshold	Semantic cache similarity threshold (0–1).
compression_level	Compression level 1–5.
rag_options	Dict: document_ids, top_k, query_image_url.
pii_options	Dict: engine, strategy, confidence_threshold, entity_types, language, regex_fallback.
context_layers	Canonical shape (instructions, knowledge, interaction, token_budget).
system_prompt, profile_context, workspace_instructions	Legacy flat fields (if no context_layers).
provider_api_key	SDK: ephemeral LLM key for this run; overrides DB keys; not persisted.

IDE helpers: from tokensaver_sdk import RagOptions, PiiOptions (TypedDict).

result = ts.ask(
    "Your question",
    provider="openai",
    model="gpt-4o",
    use_rag=True,
    rag_similarity_threshold=0.55,
    rag_options={"document_ids": ["uuid-doc"], "top_k": 8},
)

RAG (documents)

Method	Role
rag_list_documents()	Lists indexed documents in the workspace.
rag_upload_document(path, …)	Multipart upload (no wait). Correct MIME per extension (PDF, TXT, MD, CSV, JSON, DOCX). Raises ValidationError (RAG_FILE_NOT_FOUND / RAG_UNSUPPORTED_FILE_TYPE) if the path is missing or the extension is not supported.
rag_get_document(id)	Status / metadata.
rag_wait_document_ready(id, …)	Wait for ingestion.
rag_upload_and_wait(path, …)	Upload + wait.
rag_ensure_document(path, …)	Reuses an already ingested file (same file name) or upload + wait.

Minimal example with a question over an indexed document (any supported type, e.g. PDF or DOCX):

doc = ts.rag_ensure_document("handbook.pdf")
ts.ask(
    "What are the key points?",
    provider="openai",
    model="gpt-4o",
    use_rag=True,
    rag_options={"document_ids": [doc["document_id"]]},
)

Constants (aligned with the platform API): RAG_UPLOAD_EXTENSIONS, mime_type_for_rag_filename, ERROR_RAG_UNSUPPORTED_FILE_TYPE.

Chat sessions

from tokensaver_sdk import HISTORY_NONE, HISTORY_LOCAL, HISTORY_SERVER

# Stateless (default for ask: history=HISTORY_NONE)
ts.ask("…", provider="openai", model="gpt-4o", history=HISTORY_NONE)

# Server-side persistence
session = ts.chat.session(history=HISTORY_SERVER, name="My chat")
session.ask("…", provider="openai", model="gpt-4o")

Chat + knowledge (same idea as “+” in the console)

1. Index a file (or pick an existing document_id from rag_list_documents()).
2. Either pass rag_options={"document_ids": [...]} on each ask, or attach IDs once on the session and reuse them on every turn:

session = ts.chat.session(history=HISTORY_SERVER, name="Support")
doc = ts.rag_ensure_document("policy.docx")
session.attach_knowledge(doc["document_id"])
session.ask(
    "What is the refund policy?",
    provider="openai",
    model="gpt-4o",
    use_rag=True,
)
session.clear_knowledge()  # optional: stop merging these IDs into later asks

Per-call rag_options["document_ids"] are merged with session attachments (session IDs first, then duplicates removed).

Cost estimate (no LLM call)

ts.estimate_cost(1200, 300, provider="openai", model="gpt-4o")

Errors

from tokensaver_sdk import ERROR_RAG_FILE_NOT_FOUND, ERROR_RAG_UNSUPPORTED_FILE_TYPE
from tokensaver_sdk.errors import (
    TokenSaverError,
    AuthenticationError,
    ProviderKeyMissingError,
    QuotaExceededError,
    RateLimitError,
    ValidationError,
    ServerError,
    TimeoutError,
)

HTTP errors map to these exceptions. For RAG uploads (rag_upload_document, rag_upload_and_wait, rag_ensure_document when a file is sent), a missing file path on the client raises ValidationError with code="RAG_FILE_NOT_FOUND" (compare to ERROR_RAG_FILE_NOT_FOUND); the raw payload includes "path" among other fields. An unsupported extension raises RAG_UNSUPPORTED_FILE_TYPE before any HTTP call. The API accepts the same document types as the platform (PDF, TXT, MD, CSV, JSON, DOCX).

Tests & quality

pytest
ruff check src tests && ruff format src tests

Useful variables for integration tests: TOKENSAVER_API_KEY, base URL depending on your deployment.

Publishing to PyPI

1. Version: bump __version__ in src/tokensaver_sdk/__init__.py (single source of truth for the build).
2. Build & check: python -m build then twine check dist/* (dev deps: pip install -e ".[dev]").
3. Upload: twine upload dist/* (PyPI username: __token__, password: your API token). Try TestPyPI first with --repository testpypi.
4. CI: after adding the PYPI_API_TOKEN repository secret, pushing tag sdk-v0.1.0 (same as __version__) triggers the Publish SDK to PyPI workflow.

Further reference

• Product site: tokensaver.fr — positioning and presentation.
• TokenSaver app: platform.tokensaver.fr — sign in, workspace, API Reference (examples, SDK methods).
• HTTP API (SDK default): https://api.tokensaver.fr/api/v1.
• Architecture & decisions: internal to the TokenSaver monorepo (docs/ARCHITECTURE-SDK-TOKENSAVER.md); not linked here because source repositories are private.