aihi-models 0.1.0__tar.gz

aihi_models-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+node_modules/
+.pnpm-store/
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.aihi/settings.local.json
+.aihi/audit.jsonl
+.DS_Store
+
+# Local legacy SQLite compatibility fixture and SQLite WAL sidecars.
+/tests/fixtures/session_schema_v1.sqlite3*
+
+# Superpowers working documents: local process artefacts, not project docs.
+/docs/superpowers/
+
+# Architecture decision records and RFC drafts are local working notes.
+/docs/adr/
+/docs/rfcs/

aihi_models-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: aihi-models
+Version: 0.1.0
+Summary: Provider-neutral model contracts and provider adapters for AIHI
+License: MIT
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# aihi-models
+
+[English] | [简体中文](README.zh-CN.md)
+
+Provider-neutral model contracts and provider adapters for AIHI.
+
+`aihi-models` is the lowest Python layer in the repository. It normalizes messages, streamed output, tool definitions, usage, provider failures, and wire serialization so the agent runtime does not depend on one vendor SDK.
+
+## Why this package exists
+
+The package deliberately owns model-facing primitives only:
+
+- immutable request/response and content-block contracts;
+- normalized streaming chunks for text and tool input;
+- provider adapters and transport abstractions;
+- typed provider errors and context-length classification;
+- versioned message serialization and token estimation.
+
+It does **not** own model routing, a gateway, application configuration, prompt policy, sessions, tools, or an agent loop. Those belong to the application/runtime layers.
+
+## Supported providers
+
+| Adapter | Use case | Notes |
+| --- | --- | --- |
+| `OpenAIProvider` | OpenAI Chat Completions | Configure the endpoint and API key explicitly. |
+| `AnthropicProvider` | Anthropic Messages API | Normalizes Anthropic content blocks to the common stream model. |
+| `DeepSeekProvider` | DeepSeek chat models | Uses DeepSeek's OpenAI-compatible API by default. |
+| `OpenAICompatibleProvider` | Other OpenAI-compatible endpoints | Requires an explicit full `base_url` for the chat-completions endpoint. |
+| `FakeProvider` | Tests and local contract fixtures | Deterministic scripted responses; no network access. |
+
+Providers are flat modules under `src/aihi/models/providers`. Credentials and model selection are supplied by the application; constructors do not silently read environment variables.
+
+## Installation
+
+From the repository workspace:
+
+```bash
+uv sync
+```
+
+For a local editable install:
+
+```bash
+uv pip install -e packages/aihi/models
+```
+
+The package requires Python 3.11+ and depends on `httpx` for the default HTTP transport.
+
+## Minimal example
+
+```python
+import asyncio
+
+from aihi.models import FakeProvider, FakeStep, Message, ModelRequest
+
+provider = FakeProvider([
+    FakeStep(text="Hello from a deterministic provider."),
+])
+
+request = ModelRequest(
+    model="fake-model",
+    messages=[Message.text("user", "Say hello.")],
+)
+
+async def main() -> None:
+    chunks = [chunk async for chunk in provider.stream(request)]
+    print(chunks[-1])
+
+
+asyncio.run(main())
+```
+
+Providers also expose normalized asynchronous streaming. A stream is made of typed chunks such as `BlockStart`, `TextDelta`, `ToolInputDelta`, and `MessageEnd`, allowing the runtime to render or persist output without vendor-specific branching.
+
+## Public API
+
+The package root re-exports the stable building blocks:
+
+- Contracts: `Message`, `ModelRequest`, `ModelResponse`, `ModelToolDefinition`, `Capabilities`, content blocks, and `Usage`.
+- Providers: `OpenAIProvider`, `AnthropicProvider`, `DeepSeekProvider`, `OpenAICompatibleProvider`, and `FakeProvider`.
+- Errors: `ProviderError`, `ProviderHTTPError`, `ProviderProtocolError`, `ProviderTimeout`, and `ProviderContextLengthError`.
+- Serialization: `encode_message`, `decode_message`, `ModelMessageEnvelope`, and `MESSAGE_SCHEMA_VERSION`.
+- Transport: `HttpxTransport`, `JsonTransport`, and `HttpRequest`.
+
+Import from `aihi.models` rather than reaching into private modules.
+
+## Compatibility and errors
+
+Provider adapters map vendor responses into one common response/stream vocabulary and classify failures into stable error types. Callers should handle `ProviderTimeout`, HTTP failures, protocol failures, and context-length failures separately when deciding whether to retry, compact context, or surface an error.
+
+Message envelopes are versioned. Unknown schema versions raise `UnsupportedMessageSchema`; applications should persist the versioned envelope rather than relying on a provider's native JSON.
+
+## Development
+
+Run package tests and repository-wide static checks from the root:
+
+```bash
+uv run pytest packages/aihi/models/tests
+uv run ruff check packages/aihi/models
+uv run mypy
+```
+
+Build a wheel without resolving dependencies from the network:
+
+```bash
+uv run python -m build --wheel --no-isolation packages/aihi/models
+```
+
+## Security notes
+
+- Pass API keys from the application boundary and keep them out of model messages and persisted events.
+- Treat provider response text and tool arguments as untrusted input.
+- Use the default `httpx` transport or provide a transport with equivalent timeout and TLS behavior.
+- The fake provider is intended for tests; it is not a fallback for production failures.
+
+## Related packages
+
+- [`aihi-agent`](../agent/README.md) builds the provider-neutral runtime on these contracts.
+- [`aihi-code-agent`](../code-agent/README.md) composes providers into a coding-agent application.
+- [Repository architecture](../../../docs/ARCHITECTURE.md)

aihi_models-0.1.0/README.md

@@ -0,0 +1,120 @@
+# aihi-models
+
+[English] | [简体中文](README.zh-CN.md)
+
+Provider-neutral model contracts and provider adapters for AIHI.
+
+`aihi-models` is the lowest Python layer in the repository. It normalizes messages, streamed output, tool definitions, usage, provider failures, and wire serialization so the agent runtime does not depend on one vendor SDK.
+
+## Why this package exists
+
+The package deliberately owns model-facing primitives only:
+
+- immutable request/response and content-block contracts;
+- normalized streaming chunks for text and tool input;
+- provider adapters and transport abstractions;
+- typed provider errors and context-length classification;
+- versioned message serialization and token estimation.
+
+It does **not** own model routing, a gateway, application configuration, prompt policy, sessions, tools, or an agent loop. Those belong to the application/runtime layers.
+
+## Supported providers
+
+| Adapter | Use case | Notes |
+| --- | --- | --- |
+| `OpenAIProvider` | OpenAI Chat Completions | Configure the endpoint and API key explicitly. |
+| `AnthropicProvider` | Anthropic Messages API | Normalizes Anthropic content blocks to the common stream model. |
+| `DeepSeekProvider` | DeepSeek chat models | Uses DeepSeek's OpenAI-compatible API by default. |
+| `OpenAICompatibleProvider` | Other OpenAI-compatible endpoints | Requires an explicit full `base_url` for the chat-completions endpoint. |
+| `FakeProvider` | Tests and local contract fixtures | Deterministic scripted responses; no network access. |
+
+Providers are flat modules under `src/aihi/models/providers`. Credentials and model selection are supplied by the application; constructors do not silently read environment variables.
+
+## Installation
+
+From the repository workspace:
+
+```bash
+uv sync
+```
+
+For a local editable install:
+
+```bash
+uv pip install -e packages/aihi/models
+```
+
+The package requires Python 3.11+ and depends on `httpx` for the default HTTP transport.
+
+## Minimal example
+
+```python
+import asyncio
+
+from aihi.models import FakeProvider, FakeStep, Message, ModelRequest
+
+provider = FakeProvider([
+    FakeStep(text="Hello from a deterministic provider."),
+])
+
+request = ModelRequest(
+    model="fake-model",
+    messages=[Message.text("user", "Say hello.")],
+)
+
+async def main() -> None:
+    chunks = [chunk async for chunk in provider.stream(request)]
+    print(chunks[-1])
+
+
+asyncio.run(main())
+```
+
+Providers also expose normalized asynchronous streaming. A stream is made of typed chunks such as `BlockStart`, `TextDelta`, `ToolInputDelta`, and `MessageEnd`, allowing the runtime to render or persist output without vendor-specific branching.
+
+## Public API
+
+The package root re-exports the stable building blocks:
+
+- Contracts: `Message`, `ModelRequest`, `ModelResponse`, `ModelToolDefinition`, `Capabilities`, content blocks, and `Usage`.
+- Providers: `OpenAIProvider`, `AnthropicProvider`, `DeepSeekProvider`, `OpenAICompatibleProvider`, and `FakeProvider`.
+- Errors: `ProviderError`, `ProviderHTTPError`, `ProviderProtocolError`, `ProviderTimeout`, and `ProviderContextLengthError`.
+- Serialization: `encode_message`, `decode_message`, `ModelMessageEnvelope`, and `MESSAGE_SCHEMA_VERSION`.
+- Transport: `HttpxTransport`, `JsonTransport`, and `HttpRequest`.
+
+Import from `aihi.models` rather than reaching into private modules.
+
+## Compatibility and errors
+
+Provider adapters map vendor responses into one common response/stream vocabulary and classify failures into stable error types. Callers should handle `ProviderTimeout`, HTTP failures, protocol failures, and context-length failures separately when deciding whether to retry, compact context, or surface an error.
+
+Message envelopes are versioned. Unknown schema versions raise `UnsupportedMessageSchema`; applications should persist the versioned envelope rather than relying on a provider's native JSON.
+
+## Development
+
+Run package tests and repository-wide static checks from the root:
+
+```bash
+uv run pytest packages/aihi/models/tests
+uv run ruff check packages/aihi/models
+uv run mypy
+```
+
+Build a wheel without resolving dependencies from the network:
+
+```bash
+uv run python -m build --wheel --no-isolation packages/aihi/models
+```
+
+## Security notes
+
+- Pass API keys from the application boundary and keep them out of model messages and persisted events.
+- Treat provider response text and tool arguments as untrusted input.
+- Use the default `httpx` transport or provide a transport with equivalent timeout and TLS behavior.
+- The fake provider is intended for tests; it is not a fallback for production failures.
+
+## Related packages
+
+- [`aihi-agent`](../agent/README.md) builds the provider-neutral runtime on these contracts.
+- [`aihi-code-agent`](../code-agent/README.md) composes providers into a coding-agent application.
+- [Repository architecture](../../../docs/ARCHITECTURE.md)

aihi_models-0.1.0/README.zh-CN.md

@@ -0,0 +1,67 @@
+# aihi-models
+
+[English](README.md) | **简体中文**
+
+AIHI 的 Provider-neutral 模型契约和 Provider 适配器。它是仓库中最低层的 Python 包，负责统一
+消息、流式输出、工具定义、用量、Provider 错误、序列化和 token 估算。
+
+## 职责边界
+
+- 不可变的请求、响应和 Content Block 契约。
+- 文本、工具输入和推理载荷的标准化 Stream Chunk。
+- Provider Protocol、HTTP transport 和 Provider adapters。
+- 类型化 Provider 错误、Context Length 分类和 Message Schema 版本化 codec。
+
+本包不负责 ModelRouter、ModelGateway、应用配置、Prompt、Session、ToolSpec 或 Agent loop。
+这些能力由应用层或 `aihi-agent` 负责。
+
+## 支持的 Provider
+
+| Adapter | 用途 |
+| --- | --- |
+| `OpenAIProvider` | OpenAI Chat Completions |
+| `AnthropicProvider` | Anthropic Messages API |
+| `DeepSeekProvider` | DeepSeek；复用 OpenAI-compatible 协议 |
+| `OpenAICompatibleProvider` | 其他兼容 OpenAI API 的服务；必须传入完整 endpoint |
+| `FakeProvider` | 测试和离线 fixture |
+
+Provider 是扁平模块，凭据、模型选择和多个 Provider 的组合由应用层提供，不会静默读取环境变量。
+
+## 安装
+
+```bash
+uv sync
+uv pip install -e packages/aihi/models
+```
+
+要求 Python 3.11+，默认 HTTP transport 依赖 `httpx`。
+
+## 最小示例
+
+```python
+from aihi.models import Message, ModelRequest
+from aihi.models.providers.fake import FakeProvider
+
+provider = FakeProvider()
+request = ModelRequest(
+    model="fake-model",
+    messages=(Message.user("Say hello"),),
+)
+async for chunk in provider.stream(request):
+    print(chunk)
+```
+
+## 公共 API 与兼容性
+
+跨包只使用 `aihi.models` 顶层导出。Message codec 使用独立版本号；旧事件缺少版本时按 v1 读取。
+Provider stream 在首个 chunk 之后不得自动切换 Provider，错误必须包含稳定 code 和 `retryable`。
+
+## 开发
+
+```bash
+pytest packages/aihi/models/tests
+ruff check packages/aihi/models
+mypy packages/aihi/models/src
+```
+
+详见仓库 [架构文档](../../../docs/ARCHITECTURE.zh-CN.md)。

aihi_models-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aihi-models"
+version = "0.1.0"
+description = "Provider-neutral model contracts and provider adapters for AIHI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+  "httpx>=0.27",
+]
+classifiers = [
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aihi"]
+artifacts = ["src/aihi/models/py.typed"]

aihi_models-0.1.0/src/aihi/models/__init__.py

@@ -0,0 +1,115 @@
+"""Public API for model contracts and Provider adapters."""
+
+from aihi.models.base import (
+    BlockEnd,
+    BlockStart,
+    MessageEnd,
+    MessageStart,
+    Provider,
+    StreamChunk,
+    TextDelta,
+    ThinkingDelta,
+    ToolInputDelta,
+)
+from aihi.models.errors import (
+    ModelsError,
+    ProviderContextLengthError,
+    ProviderError,
+    ProviderFailure,
+    ProviderHTTPError,
+    ProviderProtocolError,
+    ProviderTimeout,
+)
+from aihi.models.providers import (
+    AnthropicProvider,
+    DeepSeekProvider,
+    OpenAICompatibleProvider,
+    OpenAIProvider,
+)
+from aihi.models.providers.anthropic import AnthropicConfig
+from aihi.models.providers.deepseek import DeepSeekConfig
+from aihi.models.providers.fake import FakeProvider, FakeStep
+from aihi.models.providers.openai import OpenAIConfig
+from aihi.models.serialization import (
+    MESSAGE_SCHEMA_VERSION,
+    ModelMessageEnvelope,
+    UnsupportedMessageSchema,
+    decode_message,
+    encode_message,
+)
+from aihi.models.tokens import estimate_messages_tokens, estimate_text_tokens
+from aihi.models.transport import HttpRequest, HttpxTransport, JsonTransport
+from aihi.models.types import (
+    Capabilities,
+    ContentBlock,
+    ImageBlock,
+    JsonObject,
+    Message,
+    ModelRequest,
+    ModelResponse,
+    ModelToolDefinition,
+    Role,
+    StopReason,
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    Usage,
+    block_from_dict,
+)
+
+__all__ = [
+    "AnthropicConfig",
+    "AnthropicProvider",
+    "BlockEnd",
+    "BlockStart",
+    "Capabilities",
+    "ContentBlock",
+    "DeepSeekConfig",
+    "DeepSeekProvider",
+    "FakeProvider",
+    "FakeStep",
+    "HttpRequest",
+    "HttpxTransport",
+    "ImageBlock",
+    "JsonObject",
+    "JsonTransport",
+    "MESSAGE_SCHEMA_VERSION",
+    "Message",
+    "MessageEnd",
+    "MessageStart",
+    "ModelMessageEnvelope",
+    "ModelRequest",
+    "ModelResponse",
+    "ModelToolDefinition",
+    "ModelsError",
+    "OpenAICompatibleProvider",
+    "OpenAIConfig",
+    "OpenAIProvider",
+    "Provider",
+    "ProviderContextLengthError",
+    "ProviderError",
+    "ProviderFailure",
+    "ProviderHTTPError",
+    "ProviderProtocolError",
+    "ProviderTimeout",
+    "Role",
+    "StopReason",
+    "StreamChunk",
+    "TextBlock",
+    "TextDelta",
+    "ThinkingBlock",
+    "ThinkingDelta",
+    "ToolCallBlock",
+    "ToolInputDelta",
+    "ToolResultBlock",
+    "UnsupportedMessageSchema",
+    "Usage",
+    "block_from_dict",
+    "decode_message",
+    "encode_message",
+    "estimate_messages_tokens",
+    "estimate_text_tokens",
+]
+
+__version__ = "0.1.0"

aihi_models-0.1.0/src/aihi/models/_ids.py

@@ -0,0 +1,13 @@
+"""Private identifiers for model-protocol value objects."""
+
+from __future__ import annotations
+
+import secrets
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{secrets.token_hex(12)}"
+
+
+def new_message_id() -> str:
+    return new_id("msg")

aihi_models-0.1.0/src/aihi/models/base.py

@@ -0,0 +1,70 @@
+"""Provider protocol and normalized wire-level streaming chunks."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Literal, Protocol, TypeAlias
+
+from aihi.models.types import Capabilities, ModelRequest, ModelResponse
+
+
+@dataclass(frozen=True, slots=True)
+class MessageStart:
+    model: str
+    kind: Literal["message_start"] = "message_start"
+
+
+@dataclass(frozen=True, slots=True)
+class BlockStart:
+    index: int
+    block_kind: str
+    kind: Literal["block_start"] = "block_start"
+
+
+@dataclass(frozen=True, slots=True)
+class TextDelta:
+    index: int
+    text: str
+    kind: Literal["text_delta"] = "text_delta"
+
+
+@dataclass(frozen=True, slots=True)
+class ThinkingDelta:
+    index: int
+    text: str
+    kind: Literal["thinking_delta"] = "thinking_delta"
+
+
+@dataclass(frozen=True, slots=True)
+class ToolInputDelta:
+    index: int
+    partial_json: str
+    kind: Literal["tool_input_delta"] = "tool_input_delta"
+
+
+@dataclass(frozen=True, slots=True)
+class BlockEnd:
+    index: int
+    kind: Literal["block_end"] = "block_end"
+
+
+@dataclass(frozen=True, slots=True)
+class MessageEnd:
+    response: ModelResponse
+    kind: Literal["message_end"] = "message_end"
+
+
+StreamChunk: TypeAlias = (
+    MessageStart | BlockStart | TextDelta | ThinkingDelta | ToolInputDelta | BlockEnd | MessageEnd
+)
+
+
+class Provider(Protocol):
+    name: str
+
+    def capabilities(self, model: str) -> Capabilities: ...
+
+    def stream(self, request: ModelRequest) -> AsyncIterator[StreamChunk]: ...
+
+    async def count_tokens(self, request: ModelRequest) -> int: ...

aihi_models-0.1.0/src/aihi/models/errors.py

@@ -0,0 +1,79 @@
+"""Stable Provider error taxonomy."""
+
+from __future__ import annotations
+
+
+class ModelsError(Exception):
+    code = "models_error"
+    retryable = False
+
+    def __init__(self, message: str, *, details: dict[str, object] | None = None) -> None:
+        super().__init__(message)
+        self.details = details or {}
+
+
+class ProviderError(ModelsError):
+    code = "provider_failure"
+
+
+class ProviderProtocolError(ProviderError):
+    code = "provider_protocol_error"
+
+
+class ProviderHTTPError(ProviderError):
+    code = "provider_http_error"
+
+
+class ProviderContextLengthError(ProviderHTTPError):
+    code = "provider_context_length"
+
+
+class ProviderTimeout(ProviderError):
+    code = "provider_timeout"
+    retryable = True
+
+
+def is_context_length_message(message: str) -> bool:
+    normalized = message.casefold().replace("-", "_").replace(" ", "_")
+    explicit_markers = (
+        "context_length",
+        "context_window",
+        "maximum_context",
+        "max_context",
+        "context_exceeded",
+        "context_limit",
+        "context_size",
+    )
+    if any(marker in normalized for marker in explicit_markers):
+        return True
+    if not any(term in normalized for term in ("context", "prompt", "input")):
+        return False
+    return any(
+        marker in normalized
+        for marker in (
+            "prompt_is_too_long",
+            "prompt_too_long",
+            "input_is_too_long",
+            "input_too_long",
+            "too_many_tokens",
+            "token_limit",
+            "maximum_tokens",
+            "max_tokens",
+        )
+    )
+
+
+# Compatibility name for the stable provider-failure contract.
+ProviderFailure = ProviderError
+
+
+__all__ = [
+    "ModelsError",
+    "ProviderContextLengthError",
+    "ProviderError",
+    "ProviderFailure",
+    "ProviderHTTPError",
+    "ProviderProtocolError",
+    "ProviderTimeout",
+    "is_context_length_message",
+]

aihi_models-0.1.0/src/aihi/models/providers/__init__.py

@@ -0,0 +1,13 @@
+"""Built-in model provider adapters."""
+
+from aihi.models.providers.anthropic import AnthropicProvider
+from aihi.models.providers.deepseek import DeepSeekProvider
+from aihi.models.providers.openai import OpenAIProvider
+from aihi.models.providers.openai_compatible import OpenAICompatibleProvider
+
+__all__ = [
+    "AnthropicProvider",
+    "DeepSeekProvider",
+    "OpenAICompatibleProvider",
+    "OpenAIProvider",
+]