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.

Published on PyPI: ai-lib-python 1.2.0. Python 3.10+.

Note: Git main may include protocol/identity work landed after the last PyPI cut (e.g. marketplace alias resolve). Match dependency versions to the tag you intend; see CHANGELOG Unreleased.

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 default AiClient chat path)

What extras actually do

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

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: optional max_inflight backpressure via builder (also AI_LIB_MAX_INFLIGHT).
• Opt-in policy layer: ai_lib_python.resilience (retry, rate limiter, circuit breaker) — use production_ready() or explicit ResilientConfig.
• Not auto-enabled on AiClient.create().

Protocol manifests

Resolution order:

1. AiClientBuilder.protocol_path(...) / ProtocolLoader(base_path=...)
2. AI_PROTOCOL_DIR / AI_PROTOCOL_PATH (local dir; GitHub raw URL supported for remote load)
3. Dev paths: ai-protocol/, ../ai-protocol/, …
4. 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)

1. Explicit override on builder / AiClient.create(..., api_key=...)
2. Manifest-declared env from endpoint.auth / top-level auth
3. <PROVIDER_ID>_API_KEY (recommended for CI/containers)
4. OS keyring when keyring is installed (HAS_KEYRING; included in [full])

Environment variables

Cross-runtime proxy semantics: CROSS_RUNTIME.md.

Standard error codes (V2)

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

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.