aiyallm 0.1.0__tar.gz

aiyallm-0.1.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: aiyallm
+Version: 0.1.0
+Summary: A small, provider-agnostic gateway for OpenAI/Anthropic-style language and vision models.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=1.66
+Requires-Dist: anthropic>=0.49
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8.3; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+
+# Aiya
+
+Aiya is a lightweight Python gateway for OpenAI/Anthropic-style language and vision models.
+
+> Aiya does not ship a built-in model catalog and does not read API keys implicitly. Every provider, `base_url`, API key, and model is declared by the application.
+
+## Table of Contents
+
+- [Features](#features)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Provider Configuration](#provider-configuration)
+- [Routing](#routing)
+- [Vision and Capability Filtering](#vision-and-capability-filtering)
+- [Usage Ledger](#usage-ledger)
+- [Cost Calculation](#cost-calculation)
+- [Streaming and Async](#streaming-and-async)
+- [Extending Providers](#extending-providers)
+
+## Features
+
+- OpenAI and OpenAI-compatible providers
+- Anthropic and Anthropic-compatible providers
+- Chinese OpenAI-compatible providers such as DeepSeek, Qwen/DashScope, Moonshot/Kimi, Zhipu GLM, and SiliconFlow
+- Explicit model selection, `provider/model` references, and provider route lists
+- Routing policies: `fallback`, `first`, `round_robin`, `random`, and `least_used`
+- Vision and multimodal message passthrough with capability filtering
+- Sync and async chat and streaming
+- Detailed token accounting with cache hit/miss fields
+- Optional SQLite or JSONL usage persistence
+- Optional cost calculation from an application-owned price book
+
+## Install
+
+```bash
+pip install -e .
+```
+
+Runtime dependencies are:
+
+- `openai`
+- `anthropic`
+- `httpx`
+
+## Quick Start
+
+There are no default providers. Pass them explicitly.
+
+```python
+from aiya import Aiya
+
+client = Aiya(
+    providers=[
+        {
+            "name": "deepseek",
+            "account": "billing-deepseek",
+            "type": "openai_compatible",
+            "base_url": "https://api.deepseek.com",
+            "api_key": "your-deepseek-key",
+            "models": ["deepseek-chat", "deepseek-reasoner"],
+        }
+    ]
+)
+
+response = client.chat(
+    "用一句话解释什么是路由。",
+    model="deepseek/deepseek-chat",
+)
+
+print(response.text)
+print(response.usage)
+```
+
+> `models` is optional when the provider allows unknown models. Configured providers default to `allow_unknown_models=True`, but the provider itself must still be declared.
+
+## Provider Configuration
+
+Each provider accepts these common fields.
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Unique provider name used by `provider/model` routes |
+| `account` | Optional billing or account name recorded in usage |
+| `type` | `openai`, `openai_compatible`, `anthropic`, or `anthropic_compatible` |
+| `base_url` | Endpoint for compatible services |
+| `api_key` | API key, or use `api_key_env` to read an environment variable |
+| `models` | Optional model names or `{"id", "capabilities", ...}` mappings |
+| `allow_unknown_models` | Allow model IDs not listed in `models`; defaults to `True` |
+| `timeout` | SDK timeout |
+
+### OpenAI-Compatible Examples
+
+```python
+providers = [
+    {
+        "name": "deepseek",
+        "type": "openai_compatible",
+        "base_url": "https://api.deepseek.com",
+        "api_key_env": "DEEPSEEK_API_KEY",
+    },
+    {
+        "name": "qwen",
+        "type": "openai_compatible",
+        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "api_key_env": "DASHSCOPE_API_KEY",
+    },
+    {
+        "name": "moonshot",
+        "type": "openai_compatible",
+        "base_url": "https://api.moonshot.cn/v1",
+        "api_key_env": "MOONSHOT_API_KEY",
+    },
+    {
+        "name": "glm",
+        "type": "openai_compatible",
+        "base_url": "https://open.bigmodel.cn/api/paas/v4",
+        "api_key_env": "ZHIPU_API_KEY",
+    },
+]
+```
+
+Use the `base_url` from each provider's current documentation. Aiya does not hard-code any endpoint or model name.
+
+## Routing
+
+Use `provider/model` to target a provider.
+
+```python
+response = client.chat("Hello", model="qwen/qwen-plus")
+```
+
+Use a route list for fallback.
+
+```python
+response = client.chat(
+    "Hello",
+    model=["deepseek/deepseek-chat", "qwen/qwen-plus"],
+    route_policy="fallback",
+)
+```
+
+Available policies:
+
+- `fallback` - try candidates in order
+- `first` - use only the first candidate
+- `round_robin` - rotate through candidates
+- `random` - choose a random candidate
+- `least_used` - choose the candidate with the lowest recorded token usage
+
+The default policy is `fallback`.
+
+## Vision and Capability Filtering
+
+Declare capabilities in `models` and pass `require_vision=True` when a request needs image input.
+
+```python
+from aiya import Aiya
+
+client = Aiya(
+    providers=[
+        {
+            "name": "qwen",
+            "type": "openai_compatible",
+            "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+            "api_key": "your-key",
+            "models": [
+                {"id": "qwen-vl-plus", "capabilities": ["text", "vision"]}
+            ],
+        }
+    ]
+)
+
+response = client.chat(
+    [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "What is in this image?"},
+                {
+                    "type": "image_url",
+                    "image_url": {"url": "https://example.com/image.jpg"},
+                },
+            ],
+        }
+    ],
+    model="qwen/qwen-vl-plus",
+    require_vision=True,
+)
+```
+
+## Usage Ledger
+
+Every successful completion is recorded.
+
+```python
+response = client.chat("Hello", model="deepseek/deepseek-chat")
+
+print(response.usage.input_tokens)
+print(response.usage.output_tokens)
+print(response.usage.input_cache_hit_tokens)
+print(response.usage.input_cache_miss_tokens)
+print(response.usage.output_cache_hit_tokens)
+print(response.usage.output_cache_miss_tokens)
+print(response.usage.account)
+print(response.usage.reasoning_tokens)
+
+print(client.ledger.total())
+print(client.ledger.by_model())
+print(client.ledger.by_provider())
+print(client.ledger.by_account())
+
+client.ledger.export_jsonl("usage.jsonl")
+```
+
+For persistent accounting, pass a SQLite path.
+
+```python
+from aiya import UsageLedger
+
+ledger = UsageLedger(sqlite_path="data/usage.sqlite3")
+client = Aiya(providers=providers, ledger=ledger)
+```
+
+## Cost Calculation
+
+Token counts are always recorded. Cost is calculated only when the application supplies a price.
+
+```python
+from aiya import Aiya, Price, PriceBook
+
+price_book = PriceBook(
+    {
+        "deepseek-chat": Price(
+            input_per_mtok=0.27,
+            output_per_mtok=1.10,
+        )
+    }
+)
+
+client = Aiya(providers=providers, price_book=price_book)
+response = client.chat("Hello", model="deepseek/deepseek-chat")
+
+print(response.usage.cost_usd)
+```
+
+Prices are US dollars per million tokens.
+
+## Streaming and Async
+
+```python
+for chunk in client.stream("Hello", model="deepseek/deepseek-chat"):
+    print(chunk.content, end="", flush=True)
+```
+
+```python
+import asyncio
+
+
+async def main():
+    response = await client.achat("Hello", model="deepseek/deepseek-chat")
+    print(response.text)
+
+    async for chunk in client.astream("Hello", model="deepseek/deepseek-chat"):
+        print(chunk.content, end="", flush=True)
+
+
+asyncio.run(main())
+```
+
+## Extending Providers
+
+For a non-standard provider, subclass `aiya.BaseProvider` and implement `complete`, `acomplete`, `stream`, and `astream`.
+
+```python
+from aiya import Aiya, BaseProvider
+
+
+class MyProvider(BaseProvider):
+    def complete(self, request):
+        ...
+```
+
+Then register the instance directly.
+
+```python
+client = Aiya(providers=[MyProvider(name="my-provider", models=["my-model"])])
+```

aiyallm-0.1.0/README.md

@@ -0,0 +1,287 @@
+# Aiya
+
+Aiya is a lightweight Python gateway for OpenAI/Anthropic-style language and vision models.
+
+> Aiya does not ship a built-in model catalog and does not read API keys implicitly. Every provider, `base_url`, API key, and model is declared by the application.
+
+## Table of Contents
+
+- [Features](#features)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Provider Configuration](#provider-configuration)
+- [Routing](#routing)
+- [Vision and Capability Filtering](#vision-and-capability-filtering)
+- [Usage Ledger](#usage-ledger)
+- [Cost Calculation](#cost-calculation)
+- [Streaming and Async](#streaming-and-async)
+- [Extending Providers](#extending-providers)
+
+## Features
+
+- OpenAI and OpenAI-compatible providers
+- Anthropic and Anthropic-compatible providers
+- Chinese OpenAI-compatible providers such as DeepSeek, Qwen/DashScope, Moonshot/Kimi, Zhipu GLM, and SiliconFlow
+- Explicit model selection, `provider/model` references, and provider route lists
+- Routing policies: `fallback`, `first`, `round_robin`, `random`, and `least_used`
+- Vision and multimodal message passthrough with capability filtering
+- Sync and async chat and streaming
+- Detailed token accounting with cache hit/miss fields
+- Optional SQLite or JSONL usage persistence
+- Optional cost calculation from an application-owned price book
+
+## Install
+
+```bash
+pip install -e .
+```
+
+Runtime dependencies are:
+
+- `openai`
+- `anthropic`
+- `httpx`
+
+## Quick Start
+
+There are no default providers. Pass them explicitly.
+
+```python
+from aiya import Aiya
+
+client = Aiya(
+    providers=[
+        {
+            "name": "deepseek",
+            "account": "billing-deepseek",
+            "type": "openai_compatible",
+            "base_url": "https://api.deepseek.com",
+            "api_key": "your-deepseek-key",
+            "models": ["deepseek-chat", "deepseek-reasoner"],
+        }
+    ]
+)
+
+response = client.chat(
+    "用一句话解释什么是路由。",
+    model="deepseek/deepseek-chat",
+)
+
+print(response.text)
+print(response.usage)
+```
+
+> `models` is optional when the provider allows unknown models. Configured providers default to `allow_unknown_models=True`, but the provider itself must still be declared.
+
+## Provider Configuration
+
+Each provider accepts these common fields.
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Unique provider name used by `provider/model` routes |
+| `account` | Optional billing or account name recorded in usage |
+| `type` | `openai`, `openai_compatible`, `anthropic`, or `anthropic_compatible` |
+| `base_url` | Endpoint for compatible services |
+| `api_key` | API key, or use `api_key_env` to read an environment variable |
+| `models` | Optional model names or `{"id", "capabilities", ...}` mappings |
+| `allow_unknown_models` | Allow model IDs not listed in `models`; defaults to `True` |
+| `timeout` | SDK timeout |
+
+### OpenAI-Compatible Examples
+
+```python
+providers = [
+    {
+        "name": "deepseek",
+        "type": "openai_compatible",
+        "base_url": "https://api.deepseek.com",
+        "api_key_env": "DEEPSEEK_API_KEY",
+    },
+    {
+        "name": "qwen",
+        "type": "openai_compatible",
+        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "api_key_env": "DASHSCOPE_API_KEY",
+    },
+    {
+        "name": "moonshot",
+        "type": "openai_compatible",
+        "base_url": "https://api.moonshot.cn/v1",
+        "api_key_env": "MOONSHOT_API_KEY",
+    },
+    {
+        "name": "glm",
+        "type": "openai_compatible",
+        "base_url": "https://open.bigmodel.cn/api/paas/v4",
+        "api_key_env": "ZHIPU_API_KEY",
+    },
+]
+```
+
+Use the `base_url` from each provider's current documentation. Aiya does not hard-code any endpoint or model name.
+
+## Routing
+
+Use `provider/model` to target a provider.
+
+```python
+response = client.chat("Hello", model="qwen/qwen-plus")
+```
+
+Use a route list for fallback.
+
+```python
+response = client.chat(
+    "Hello",
+    model=["deepseek/deepseek-chat", "qwen/qwen-plus"],
+    route_policy="fallback",
+)
+```
+
+Available policies:
+
+- `fallback` - try candidates in order
+- `first` - use only the first candidate
+- `round_robin` - rotate through candidates
+- `random` - choose a random candidate
+- `least_used` - choose the candidate with the lowest recorded token usage
+
+The default policy is `fallback`.
+
+## Vision and Capability Filtering
+
+Declare capabilities in `models` and pass `require_vision=True` when a request needs image input.
+
+```python
+from aiya import Aiya
+
+client = Aiya(
+    providers=[
+        {
+            "name": "qwen",
+            "type": "openai_compatible",
+            "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+            "api_key": "your-key",
+            "models": [
+                {"id": "qwen-vl-plus", "capabilities": ["text", "vision"]}
+            ],
+        }
+    ]
+)
+
+response = client.chat(
+    [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "What is in this image?"},
+                {
+                    "type": "image_url",
+                    "image_url": {"url": "https://example.com/image.jpg"},
+                },
+            ],
+        }
+    ],
+    model="qwen/qwen-vl-plus",
+    require_vision=True,
+)
+```
+
+## Usage Ledger
+
+Every successful completion is recorded.
+
+```python
+response = client.chat("Hello", model="deepseek/deepseek-chat")
+
+print(response.usage.input_tokens)
+print(response.usage.output_tokens)
+print(response.usage.input_cache_hit_tokens)
+print(response.usage.input_cache_miss_tokens)
+print(response.usage.output_cache_hit_tokens)
+print(response.usage.output_cache_miss_tokens)
+print(response.usage.account)
+print(response.usage.reasoning_tokens)
+
+print(client.ledger.total())
+print(client.ledger.by_model())
+print(client.ledger.by_provider())
+print(client.ledger.by_account())
+
+client.ledger.export_jsonl("usage.jsonl")
+```
+
+For persistent accounting, pass a SQLite path.
+
+```python
+from aiya import UsageLedger
+
+ledger = UsageLedger(sqlite_path="data/usage.sqlite3")
+client = Aiya(providers=providers, ledger=ledger)
+```
+
+## Cost Calculation
+
+Token counts are always recorded. Cost is calculated only when the application supplies a price.
+
+```python
+from aiya import Aiya, Price, PriceBook
+
+price_book = PriceBook(
+    {
+        "deepseek-chat": Price(
+            input_per_mtok=0.27,
+            output_per_mtok=1.10,
+        )
+    }
+)
+
+client = Aiya(providers=providers, price_book=price_book)
+response = client.chat("Hello", model="deepseek/deepseek-chat")
+
+print(response.usage.cost_usd)
+```
+
+Prices are US dollars per million tokens.
+
+## Streaming and Async
+
+```python
+for chunk in client.stream("Hello", model="deepseek/deepseek-chat"):
+    print(chunk.content, end="", flush=True)
+```
+
+```python
+import asyncio
+
+
+async def main():
+    response = await client.achat("Hello", model="deepseek/deepseek-chat")
+    print(response.text)
+
+    async for chunk in client.astream("Hello", model="deepseek/deepseek-chat"):
+        print(chunk.content, end="", flush=True)
+
+
+asyncio.run(main())
+```
+
+## Extending Providers
+
+For a non-standard provider, subclass `aiya.BaseProvider` and implement `complete`, `acomplete`, `stream`, and `astream`.
+
+```python
+from aiya import Aiya, BaseProvider
+
+
+class MyProvider(BaseProvider):
+    def complete(self, request):
+        ...
+```
+
+Then register the instance directly.
+
+```python
+client = Aiya(providers=[MyProvider(name="my-provider", models=["my-model"])])
+```

aiyallm-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aiyallm"
+version = "0.1.0"
+description = "A small, provider-agnostic gateway for OpenAI/Anthropic-style language and vision models."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "openai>=1.66",
+    "anthropic>=0.49",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

aiyallm-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aiyallm-0.1.0/src/aiya/__init__.py

@@ -0,0 +1,49 @@
+"""Aiya: provider-agnostic LLM and vision model gateway."""
+
+__version__ = "0.1.0"
+
+from .client import Aiya
+from .exceptions import (
+    AiyaError,
+    AuthenticationError,
+    ConfigurationError,
+    ModelNotSupportedError,
+    NoAvailableProviderError,
+    ProviderError,
+    RateLimitError,
+)
+from .models import Capability, ChatChunk, ChatResponse, ModelInfo, ToolCall
+from .providers import (
+    AnthropicCompatibleProvider,
+    BaseProvider,
+    OpenAICompatibleProvider,
+)
+from .registry import RouteTarget
+from .router import RoutePolicy, Router
+from .usage import Price, PriceBook, Usage, UsageLedger
+
+__all__ = [
+    "Aiya",
+    "AiyaError",
+    "AnthropicCompatibleProvider",
+    "AuthenticationError",
+    "BaseProvider",
+    "Capability",
+    "ChatChunk",
+    "ChatResponse",
+    "ConfigurationError",
+    "ModelInfo",
+    "ModelNotSupportedError",
+    "NoAvailableProviderError",
+    "OpenAICompatibleProvider",
+    "Price",
+    "PriceBook",
+    "ProviderError",
+    "RateLimitError",
+    "RoutePolicy",
+    "RouteTarget",
+    "Router",
+    "ToolCall",
+    "Usage",
+    "UsageLedger",
+]