ai-lib-python
Protocol runtime for AI-Protocol — async Python reference implementation (v1.2.0).
ai-lib-python is a single package with execution / policy module separation (E/P at the module level). Most apps import from the root:
from ai_lib_python import AiClient, Message, StreamingEvent
How it works
Default chat path: AiClient loads a provider manifest → builds a Pipeline from manifest operators → sends HTTP via HttpTransport (httpx). Streaming frames are normalized to StreamingEvent.
This is protocol-driven for chat, but not “zero provider code”: the repo also ships provider-specific decoders/mappers, optional ProviderDriver implementations (advanced / tests), and standalone HTTP clients for embeddings, STT, TTS, and rerank.
| Layer | Packages / modules | Responsibility |
|---|---|---|
| Execution (E) | client, protocol, pipeline, transport, types, structured, optional capability modules |
Deterministic execution, manifest loading, HTTP |
| Policy (P) | resilience, cache, routing, plugins, guardrails, batch, telemetry, tokens, registry |
Retry, rate limits, routing, telemetry — opt-in beside the client |
| Facade | ai_lib_python (root) |
Stable imports + examples + compliance tests |
Published on PyPI: ai-lib-python 1.2.0. Python 3.10+.
Note: Git
mainmay include protocol/identity work landed after the last PyPI cut (e.g. marketplace alias resolve). Match dependency versions to the tag you intend; see CHANGELOGUnreleased.
Quick start
pip install ai-lib-python
export DEEPSEEK_API_KEY="your-key"
import asyncio
from ai_lib_python import AiClient, Message
async def main() -> None:
client = await AiClient.create("deepseek/deepseek-chat")
response = await (
client.chat()
.messages([
Message.system("You are a helpful assistant."),
Message.user("Hello!"),
])
.temperature(0.7)
.max_tokens(500)
.execute()
)
print(response.content)
await client.close()
asyncio.run(main())
Same example: python examples/basic_chat.py (requires OPENAI_API_KEY or change the model).
The fluent builder also supports .system() / .user() shorthands on client.chat().
Streaming
import asyncio
from ai_lib_python import AiClient
async def main() -> None:
client = await AiClient.create("deepseek/deepseek-chat")
async for event in (
client.chat()
.user("Write a haiku about Python.")
.stream()
):
if event.is_content_delta:
print(event.as_content_delta.content, end="", flush=True)
elif event.is_stream_end:
break
await client.close()
asyncio.run(main())
Same example: python examples/streaming.py.
Call statistics
ChatResponse does not embed stats. Use execute_with_stats() or stream_with_stats():
response, stats = await client.chat().user("Hello!").execute_with_stats()
print(stats.latency_ms, stats.input_tokens, stats.output_tokens)
Production resilience (opt-in)
client = await (
AiClient.builder()
.model("deepseek/deepseek-chat")
.production_ready() # ResilientConfig.production() defaults
.build()
)
production_ready() wires the policy-layer resilience module. It is not enabled by AiClient.create() alone.
Public API (package root)
Always exported from ai_lib_python:
- Client:
AiClient,AiClientBuilder,ChatResponse,CallStats - Types:
Message,MessageRole,MessageContent,ContentBlock,StreamingEvent,ToolCall,ToolDefinition - Errors:
AiLibError,ProtocolError,TransportError - Feature probes:
HAS_VISION,HAS_AUDIO,HAS_TELEMETRY,HAS_TOKENIZER,HAS_WATCHDOG,HAS_KEYRING,require_extra - Version:
__version__(from installed distribution metadata)
Subpackages (import explicitly when needed):
- Execution:
ai_lib_python.pipeline,protocol,transport,structured,embeddings,stt,tts,rerank,multimodal,mcp,computer_use - Types (extended):
ai_lib_python.types—ExecutionResult,ExecutionMetadata,ExecutionUsage, text-tool / TTC (StandardTextToolParser,ToolCallingPolicy,TextToolConfig, …) - Policy:
ai_lib_python.resilience,cache,routing,plugins,guardrails,batch,telemetry,tokens,registry - Advanced:
ai_lib_python.drivers—ProviderDriver,create_driver(not used by defaultAiClientchat path)
What extras actually do
| Extra | What you get | Notes |
|---|---|---|
vision |
Pillow-backed image blocks | Marked via HAS_VISION |
audio |
Audio helpers (soundfile) |
HAS_AUDIO |
embeddings |
EmbeddingClient |
Protocolized builders: from_model / from_manifest (no silent OpenAI host default) |
structured |
Structured / JSON mode helpers | Marker extra (code always importable) |
stt / tts / reranking |
SttClient, TtsClient, RerankerClient |
Standalone service clients; rerank supports from_model / from_manifest |
batch / agentic |
Batch / agentic markers | Policy / capability markers |
contact |
Policy-layer install marker | Routing, resilience, guardrails, batch, plugins, telemetry — physical split deferred |
telemetry |
OpenTelemetry sinks | HAS_TELEMETRY; feedback types in telemetry subpackage |
tokenizer |
Token counting (tiktoken) | HAS_TOKENIZER |
full |
All capability extras + watchdog + keyring |
Includes contact |
dev / docs / jupyter |
Tooling only | pytest/mypy/ruff; mkdocs; ipywidgets |
pip install ai-lib-python[full]
Many extras are markers (empty dependency lists): the modules ship in the wheel; install the extra when you want an explicit capability contract or when real deps are needed (vision, audio, telemetry, tokenizer, full).
Honest capability boundaries
| Area | In the package | Not included |
|---|---|---|
MCP (mcp module) |
McpToolBridge format conversion |
MCP server transport wired into AiClient |
Computer Use (computer_use) |
ComputerAction, SafetyPolicy validation |
Screenshot / input execution environment |
| Hot reload | AiClientBuilder.hot_reload() flag + in-memory cache; ProtocolLoader.clear_cache() |
Automatic file watching (needs watchdog; HAS_WATCHDOG) — no auto-reload today |
ProviderDriver |
Public drivers module |
Default AiClient chat path |
| Rate limit env | Configure via AiClientBuilder / resilience |
AI_LIB_RPS / AI_LIB_RPM are not read by the runtime |
Advanced: ProviderDriver
ai_lib_python.drivers exposes ProviderDriver, create_driver, and OpenAI / Anthropic / Gemini drivers. AiClient does not use this path for chat; it uses Pipeline from manifests. Drivers are for compliance tests and custom integrations.
Resilience
- Built into
AiClient: optionalmax_inflightbackpressure via builder (alsoAI_LIB_MAX_INFLIGHT). - Opt-in policy layer:
ai_lib_python.resilience(retry, rate limiter, circuit breaker) — useproduction_ready()or explicitResilientConfig. - Not auto-enabled on
AiClient.create().
Protocol manifests
Resolution order:
AiClientBuilder.protocol_path(...)/ProtocolLoader(base_path=...)AI_PROTOCOL_DIR/AI_PROTOCOL_PATH(local dir; GitHub raw URL supported for remote load)- Dev paths:
ai-protocol/,../ai-protocol/, … - Fallback: GitHub raw
ailib-official/ai-protocol(main)
Per base path: dist/v2/providers/<id>.json → dist/v1/providers/<id>.json → source v2 / v1 YAML/JSON degrade.
Identity / aliases (on main, see Unreleased): load_provider resolves marketplace aliases via dist/provider-identity.json (multi-family map), e.g. google → gemini, kimi → moonshot. Parse/validation errors are not masked by alias lookup.
Manifest cache: in-memory. hot_reload=True stores a flag but does not watch files — call ProtocolLoader.clear_cache() or rebuild the client after manifest changes.
API keys (BYOK chain)
- Explicit override on builder /
AiClient.create(..., api_key=...) - Manifest-declared env from
endpoint.auth/ top-levelauth <PROVIDER_ID>_API_KEY(recommended for CI/containers)- OS keyring when
keyringis installed (HAS_KEYRING; included in[full])
Environment variables
| Variable | Purpose |
|---|---|
AI_PROTOCOL_DIR / AI_PROTOCOL_PATH |
Local manifest directory or GitHub raw base URL |
AI_PROXY_URL |
Explicit proxy when AI_HTTP_TRUST_ENV=1 |
HTTP_PROXY / HTTPS_PROXY |
Standard proxy vars (with AI_HTTP_TRUST_ENV=1) |
NO_PROXY / AI_PROXY_NO_PROXY |
Hosts that bypass proxy |
AI_HTTP_TIMEOUT_SECS |
HTTP timeout |
AI_LIB_MAX_INFLIGHT |
Concurrency backpressure (also via builder) |
Cross-runtime proxy semantics: CROSS_RUNTIME.md.
Standard error codes (V2)
| Code | Name | Retryable | Fallbackable |
|---|---|---|---|
| E1001 | invalid_request |
No | No |
| E1002 | authentication |
No | Yes |
| E1003 | permission_denied |
No | No |
| E1004 | not_found |
No | No |
| E1005 | request_too_large |
No | No |
| E2001 | rate_limited |
Yes | Yes |
| E2002 | quota_exhausted |
No | Yes |
| E3001 | server_error |
Yes | Yes |
| E3002 | overloaded |
Yes | Yes |
| E3003 | timeout |
Yes | Yes |
| E4001 | conflict |
Yes | No |
| E4002 | cancelled |
No | No |
| E9999 | unknown |
No | No |
Testing
pip install -e ".[dev]"
pytest tests/unit/ -v
Compliance (cross-runtime YAML):
# POSIX
COMPLIANCE_DIR=../ai-protocol/tests/compliance pytest tests/compliance/ -v
# Windows PowerShell
$env:COMPLIANCE_DIR = "D:\ai-protocol\tests\compliance"
pytest tests/compliance/ -v
Mock server integration (requires ai-protocol-mock):
MOCK_HTTP_URL=http://localhost:4010 pytest tests/integration/ -v
Examples
| Example | Topic |
|---|---|
basic_chat.py |
Quick start, execute_with_stats |
streaming.py |
is_content_delta, stream_with_stats |
resilience.py |
Policy layer |
multimodal.py |
Vision extra |
tool_calling.py |
Tools |
multi_provider_production.py |
Routing / fallbacks |
guardrails_production.py |
Guardrails |
concurrent_production.py |
Concurrency |
providers.py |
Provider switching |
Related
- AI-Protocol — specification & manifests
- ai-lib-rust — Rust runtime
- ai-lib-ts — TypeScript runtime
- ai-lib-go — Go runtime
License
Dual-licensed under Apache-2.0 or MIT.
Metadata
Release files for ai-lib-python 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_lib_python-1.2.0.tar.gz | 170.1 kB | Without provenance | Details for ai_lib_python-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_lib_python-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for ai_lib_python-1.2.0-py3-none-any.whl |
Total release size: 396.1 kB
Release files / ai_lib_python-1.2.0.tar.gz
| Download URL | ai_lib_python-1.2.0.tar.gz |
|---|---|
| Size | 170.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4c55e15e31dbf5039983a54a5a6dbff78de9ffcb9e4f0368528368eb9d9cd8d8
|
|
BLAKE2b-256 checksum How to use checksums |
273bc5d0a96e696c7ead08bab6c6cddc08275c57b307bff91a76b23e6e79b265
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ai_lib_python-1.2.0-py3-none-any.whl
| Download URL | ai_lib_python-1.2.0-py3-none-any.whl |
|---|---|
| Size | 226.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f64aea014700845b80dffce90d9467f1a725457a03cc6a76605fbe282930b44e
|
|
BLAKE2b-256 checksum How to use checksums |
8b7e7f0f2973a051815f285dafd73f9f936506ce83eabd7273bb35ed0b48ae07
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for ai-lib-python 1.2.0
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.