Python SDK — overview & install

Python SDK

aiotic-sdk is the reference implementation of everything in this guide. Use it as a library, as a ready-made service, or as a source of patterns for another language.

Rendering diagram…

Modules and how they connect.

Install

pip install "aiotic-sdk[all]"          # client + FastAPI service + CLI
pip install aiotic-sdk                 # client and pipeline only (httpx, pydantic)

Python ≥ 3.11. Extras: server (FastAPI, uvicorn), cli (typer, rich).

Modules

Module	What it gives you	Guide page
aiotic.AioticClient / AsyncAioticClient	Every public endpoint as a typed method; retries with backoff; token-bucket rate limit; automatic sync-key routing; orders.wait()	Client reference
aiotic.models	Pydantic v2 models pinned to the public OpenAPI (PurchaseOrder, OrderStatus, ErpReceiveRequest, …)	Purchase-order model
aiotic.receive	ErpReceiver (framework-free) + create_receive_router (FastAPI): key check, idempotency, pipeline, correct response	ERP receive endpoint
aiotic.pipeline	Sanitizers → validators → business rules with built-ins	Pipeline
aiotic.erp	ErpPort, CatalogPort, CustomerPort; templates FunctionalApiAdapter, DataApiAdapter; InMemoryErp	ERP adapters
aiotic.sync	SyncEngine, ChangeEvent, HashStateStore, PollingChangeSource, reconcile()	Sync engine
aiotic.watch	OrderWatcher — status transitions from polling	Order watcher
aiotic.webhooks	Processing-webhook receiver, ERP change-event endpoint, HMAC verifier	Webhooks & receivers
aiotic.service	build_app() — one call, complete service	Bootstrapping
aiotic.cli	aiotic init · doctor · orders · sync · serve · mock	CLI
aiotic.mock	A mock AIOTIC tenant (aiotic mock)	Mock server

Configuration

Settings.from_env() reads AIOTIC_* environment variables (and a .env file in the working directory):

Variable	Purpose
AIOTIC_BASE_URL	https://acme.aiotic.ai
AIOTIC_API_KEY	integration key
AIOTIC_SYNC_API_KEY	optional sync key (used automatically for master-data calls)
AIOTIC_ERP_RECEIVE_KEY	key AIOTIC sends to your receive endpoint
AIOTIC_WEBHOOK_KEY	key AIOTIC sends to your processing webhook
AIOTIC_TIMEOUT, AIOTIC_MAX_RETRIES, AIOTIC_RATE_LIMIT	30 s · 3 · 10 req/s

Design principles

• The API is the truth. Models carry the exact field names and nullability of the OpenAPI document; unknown fields are preserved, so a newer tenant never breaks an older SDK.
• The integration layer validates. Because some ERPs cannot. Every check is a small class you can add, remove or reorder.
• Never a full re-upload. The sync engine sends a record only when its fingerprint changed.
• Framework-free core. ErpReceiver.handle(), Pipeline.run(), SyncEngine.apply() are plain Python. FastAPI routers are thin wrappers; use Flask, Django or a queue consumer if you prefer.
• Tested against the mock. The SDK's own test-suite runs the mock tenant in-process; your tests can too.

Versioning

The SDK's aiotic.API_VERSION names the API version it was verified against; the guide's changelog lists breaking changes (there have been none: the API evolves additively).