Skip to main content

Tollara Service SDK (Python)

Package: tollara-service-sdk (PyPI). Import: import tollara_service_sdk.

Verify HMAC on incoming gateway requests, validate service keys, run usage pre-flight (service-key and JWT paths), gateway invoke, report usage, progress/completion, and poll async job status on the gateway.

This README covers the public SDK contract and usage examples.

Configuration

Use TollaraClient with one API origin (scheme + host, optional port).

Setting Default Notes
API origin https://api.tollara.ai (TollaraClient.DEFAULT_API_URL) Override with api_url=..., or env TOLLARA_API_URL for staging/tests — no trailing slash required
Service identity From env TOLLARA_SERVICE_ID, or service_id=... Optional if Core can infer the service from the key
Service secret From env TOLLARA_SERVICE_SECRET, or service_secret=... Required (Usage HMAC + Core response verification)

Progress / completion still use the full progress_url / callback_url strings from the gateway (including query params).

Usage report (§3): JSON body includes an ISO-8601 timestamp; X-Tollara-Timestamp is Unix epoch seconds for signing. For report_usage_at, pass timestamp as epoch seconds (or omit for “now”); values above 1e11 are treated as milliseconds and converted.

Constructor arguments override environment variables when both are set.

Environment variables

Variable Purpose
TOLLARA_API_URL Optional. Overrides the default production API origin when set (staging, local stacks, tests).
TOLLARA_SERVICE_ID Service UUID if you omit service_id=... (optional)
TOLLARA_SERVICE_SECRET Service secret if you omit service_secret=... (required one way or the other)

In code, names are also available as TollaraClient.ENV_API_URL, ENV_SERVICE_ID, and ENV_SERVICE_SECRET. The default base URL is TollaraClient.DEFAULT_API_URL.

Requirements

Python 3.10+

Install

pip install tollara-service-sdk

HTTP features (validate, usage, gateway, progress):

pip install tollara-service-sdk[http]

Examples

Verify inbound HMAC (agent backend)

Pass a header map (keys matched case-insensitively) and the raw body the gateway signed (same bytes as in the canonical string). Header names follow TollaraHeaders (X-Tollara-*). Verification defaults to signing version v2 (newer user-context suffix, no quota segment in the signed material).

Preferred: verify and read user context in one step (None if the HMAC is invalid):

from tollara_service_sdk import verify_inbound_context

ctx = verify_inbound_context(service_secret, headers, raw_body)
if ctx is not None:
    # ctx.user_id, ctx.plan, ...
    ...

The former name verify_signature_from_headers_and_get_user_context remains available as an alias of verify_inbound_context.

Or verify and read separately:

from tollara_service_sdk import verify_signature_from_headers, get_user_context

if verify_signature_from_headers(service_secret, headers, raw_body):
    ctx = get_user_context(headers)

For full control, build InboundHmacRequest with SignedUserContext and call verify_inbound_hmac(service_secret, req).

Caller / backend HTTP APIs (single client)

from tollara_service_sdk import TollaraClient, CompletionStatus

# Default API origin is production; pass api_url=... or set TOLLARA_API_URL only to override.
# service_secret is required (here or via TOLLARA_SERVICE_SECRET).
client = TollaraClient(
    service_id=service_id,
    service_secret=service_secret,
)

validation = client.validate_service_key("bearer-token")
# validation.service_key_id — Core key id when present

estimate = client.estimate_usage("bearer-token", 1.0)
if estimate is not None:
    allowed = estimate.would_allow
    status = estimate.http_status

# JWT usage estimate (unsigned): bearer JWT + internal Core user id + service id
# client.estimate_usage_with_jwt(jwt, core_user_id, service_id, 1.0)

# Gateway invoke: method, service_id, endpoint_id, service_key, optional body=..., async_=...
# client.invoke_service("POST", service_id, endpoint_id, service_key, body="{}", async_=False)

usage_resp = client.report_usage(user_id, service_id, 1.0)

client.send_progress_update(progress_url, request_id, "some processing info", 50)

client.send_completion(
    callback_url, request_id, CompletionStatus.COMPLETED, units=1.0, result="some result"
)

status = client.get_request_status(request_id, service_key)
result = client.get_request_result(request_id, service_key)

Tests (from source)

cd sdk-python
pip install -e ".[dev,http]"
pytest

Release (PyPI)

  1. Version — Bump version in pyproject.toml under [project] (PEP 440 / SemVer). Each upload must use a new version; PyPI will reject duplicates.

  2. Verify — Run tests (see above). Optionally run from a clean tree.

  3. Build distributions — Install tooling if needed (pip install build twine), then from sdk-python:

    python -m build
    

    This creates dist/*.whl and dist/*.tar.gz.

  4. Check — twine check dist/*

  5. Upload — Use PyPI (or Test PyPI for a dry run):

    twine upload dist/*
    

    Configure credentials via ~/.pypirc, environment variables, or a trusted publisher / API token as described in PyPI’s publishing docs.

  6. Tag — Tag the Git commit that matches the released version.

Project metadata (name tollara-service-sdk, license, URLs) lives in pyproject.toml.

The SDK methods shown in this README cover invoke, validate, estimates, usage reporting, and gateway polling flows.

Metadata

Release files for tollara-service-sdk 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tollara-service-sdk 0.0.1
File Size Uploaded Provenance Actions
tollara_service_sdk-0.0.1.tar.gz 24.6 kB Without provenance Details for tollara_service_sdk-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tollara-service-sdk 0.0.1
File Interpreter ABI Platform Actions
tollara_service_sdk-0.0.1-py3-none-any.whl Python 3 none any Details for tollara_service_sdk-0.0.1-py3-none-any.whl

Total release size: 47.0 kB

Release files / tollara_service_sdk-0.0.1.tar.gz

Download URL tollara_service_sdk-0.0.1.tar.gz
Size 24.6 kB
Tags Source
SHA-256 checksum
How to use checksums
249fec4196b41d676861dcdcb2ec7f2359643871111861ae0c36321fbd8cc4d4
BLAKE2b-256 checksum
How to use checksums
001bdf707c0ea2162890864ed54d5f89e809f9814168abc24b17ffd8a489ba54
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.11

Release files / tollara_service_sdk-0.0.1-py3-none-any.whl

Download URL tollara_service_sdk-0.0.1-py3-none-any.whl
Size 22.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fb0b6b6d8256e9bf77f299caf943e8997a67adf37f82153b85caa607ef28ce46
BLAKE2b-256 checksum
How to use checksums
781f59453b03c1f2defa30a7598cc53c1099eef72e34c6249708a888325a8b10
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.11

Security for tollara-service-sdk 0.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page