pi-ai-python 1.3.0__tar.gz

pi_ai_python-1.3.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+.env
+auth.json

pi_ai_python-1.3.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner (pi, https://github.com/earendil-works/pi)
+Copyright (c) 2026 nivalume (pi-py Python port)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pi_ai_python-1.3.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: pi-ai-python
+Version: 1.3.0
+Summary: Python port of pi's AI libraries: a unified LLM API (pi_ai) and a stateful agent runtime (pi_agent)
+Project-URL: Homepage, https://github.com/nivalume/pi-py
+Project-URL: Source, https://github.com/nivalume/pi-py
+Project-URL: Upstream, https://github.com/earendil-works/pi
+Author: nivalume
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,anthropic,bedrock,gemini,llm,openai,streaming,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: anthropic>=1.15
+Requires-Dist: google-genai>=2.31
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=3.35
+Provides-Extra: all
+Requires-Dist: boto3>=1.43; extra == 'all'
+Requires-Dist: orjson>=3.10; extra == 'all'
+Requires-Dist: pydantic>=2.6; extra == 'all'
+Requires-Dist: websockets>=13; extra == 'all'
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.43; extra == 'bedrock'
+Provides-Extra: fast
+Requires-Dist: orjson>=3.10; extra == 'fast'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.6; extra == 'pydantic'
+Provides-Extra: websocket
+Requires-Dist: websockets>=13; extra == 'websocket'
+Description-Content-Type: text/markdown
+
+# pi-py
+
+Python port of [pi](https://github.com/earendil-works/pi)'s core libraries, published on
+PyPI as one package, `pi-ai-python`, with two import packages:
+
+| Import | Upstream | What it does |
+| --- | --- | --- |
+| [`pi_ai`](https://github.com/nivalume/pi-py/blob/main/packages/ai/README.md) | `@earendil-works/pi-ai` | Unified LLM API: provider collections, auth resolution (API keys, OAuth), streaming events, token and cost tracking, tool calling, cross-provider context hand-off, image generation, classification |
+| [`pi_agent`](https://github.com/nivalume/pi-py/blob/main/packages/agent/README.md) | `@earendil-works/pi-agent-core` | Stateful agent: tool execution (parallel or sequential), steering and follow-up queues, lifecycle events, hooks |
+
+```bash
+pip install pi-ai-python               # httpx + official SDKs: anthropic, openai, google-genai
+pip install "pi-ai-python[bedrock]"    # + boto3 for Amazon Bedrock
+pip install "pi-ai-python[all]"        # + orjson, websockets, pydantic, boto3
+```
+
+中文说明见 [README.zh-CN.md](https://github.com/nivalume/pi-py/blob/main/README.zh-CN.md)。
+
+```python
+import asyncio
+
+from pi_ai import Context, UserMessage
+from pi_ai.providers.all import builtin_models
+
+
+async def main() -> None:
+    models = builtin_models()  # every built-in provider; auth comes from env vars such as ANTHROPIC_API_KEY
+    model = models.get_model("anthropic", "claude-sonnet-4-5")
+    stream = models.stream(model, Context(system_prompt="Be brief.", messages=[UserMessage("Hello!")]))
+    async for event in stream:
+        if event.type == "text_delta":
+            print(event.delta, end="", flush=True)
+    message = await stream.result()
+    print(f"\n{message.usage.input} in / {message.usage.output} out, ${message.usage.cost.total:.4f}")
+
+
+asyncio.run(main())
+```
+
+```python
+from pi_agent import Agent, AgentInitialState, agent_tool
+
+
+@agent_tool
+async def get_time(timezone: str = "UTC") -> str:
+    """Get the current time.
+
+    Args:
+        timezone: IANA timezone name.
+    """
+    ...
+
+
+agent = Agent(
+    initial_state=AgentInitialState(system_prompt="You are helpful.", model=model, tools=[get_time]),
+    stream_fn=models.stream_simple,
+)
+async for event in agent.events("What time is it in Tokyo?"):
+    print(event.type)
+```
+
+## Same API, Python conventions
+
+The port keeps pi's architecture and semantics: the same `Models`/`Provider`
+runtime, the same event protocol (`start` → `text_delta`… → `done`/`error`), the
+same transcript model (system prompt and tools carried by system messages), the
+same auth precedence rules, the same model catalog, and the same agent loop.
+Names follow Python conventions:
+
+| TypeScript | Python |
+| --- | --- |
+| `createModels()`, `models.streamSimple(...)` | `create_models()`, `models.stream_simple(...)` |
+| `{ apiKey, sessionId, maxTokens }` options | `api_key=..., session_id=..., max_tokens=...` keyword arguments (or a dict) |
+| `message.stopReason`, `usage.cacheRead` | `message.stop_reason`, `usage.cache_read` |
+| `{ role: "user", content: "hi", timestamp }` | `UserMessage("hi")` (timestamp defaults to now) |
+| `Type.Object({...})` (TypeBox) | `Type.Object({...})` (built in) or a Pydantic model |
+| `AbortController` / `signal` | `pi_ai.AbortController` / `signal=` |
+| `for await (const e of stream)` / `await stream.result()` | `async for e in stream` / `await stream.result()` |
+| `agent.continue()` | `agent.continue_()` (alias `agent.resume()`) |
+
+String values that appear on the wire or in persisted transcripts are unchanged
+(`"toolUse"`, `"toolResult"`, `"text_delta"`, API ids, provider ids), and
+`pi_ai.serialization` reads and writes pi's camelCase JSON, so sessions, model
+definitions and `auth.json` credential files are interchangeable with TypeScript pi.
+
+## Design notes
+
+* **Official vendor SDKs.** As in pi, the Anthropic, OpenAI (Chat Completions,
+  Responses, Azure, OpenRouter images), Google (Gemini, Vertex) and Bedrock adapters use
+  the vendors' official SDKs: `anthropic`, `openai`, `google-genai` and `boto3`
+  (`pi-ai-python[bedrock]`). The SDK clients share one pooled `httpx.AsyncClient` per event loop.
+  APIs that pi calls without an SDK (Mistral, OpenAI Codex, pi-messages, classifiers)
+  use `httpx` directly.
+* **Fast streaming path.** Slotted data classes, an allocation-light event queue,
+  zero-copy forwarding between wrapped streams, an incremental partial-JSON parser
+  for tool-call arguments (about 60x faster than re-parsing each delta on large
+  arguments), linear-time accumulation of streamed text, optional `orjson` decoding,
+  and compiled, cached tool-argument validators. On one core the anthropic-messages
+  adapter processes about 110,000 stream events per second and openai-completions about
+  70,000, where the openai SDK's SSE decoder is the limit (see `benchmarks/`).
+* **Lazy everything.** Model catalogs load per provider on first use; API
+  implementations and OAuth flows import on first request.
+* **Async-native cancellation.** `AbortSignal` aborts interrupt pending network reads
+  immediately (task cancellation scoped by `abort_scope`), and aborted requests end
+  their stream with `stop_reason == "aborted"` instead of raising.
+* **Python-friendly additions.** Pydantic models as tool parameter schemas,
+  `@agent_tool` to build tools from typed functions, `Agent.events()` as an async
+  iterator, `FileCredentialStore` (pi's `auth.json` format with cross-process locking),
+  keyword-argument options, streams that can be created outside an event loop and
+  closed with `async with`.
+
+## Development
+
+```bash
+uv sync                      # create .venv with the package (editable) and dev tools
+uv run pytest                # run all tests (offline; HTTP is mocked)
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+uv run python benchmarks/bench_partial_json.py
+uv run python benchmarks/bench_stream.py
+```
+
+Model catalog data (`packages/ai/src/pi_ai/providers/data/*.json`) is the generated
+catalog shipped with `@earendil-works/pi-ai` 1.3.0.
+
+## License
+
+MIT. Based on pi by Mario Zechner and contributors.

pi_ai_python-1.3.0/README.md

@@ -0,0 +1,128 @@
+# pi-py
+
+Python port of [pi](https://github.com/earendil-works/pi)'s core libraries, published on
+PyPI as one package, `pi-ai-python`, with two import packages:
+
+| Import | Upstream | What it does |
+| --- | --- | --- |
+| [`pi_ai`](https://github.com/nivalume/pi-py/blob/main/packages/ai/README.md) | `@earendil-works/pi-ai` | Unified LLM API: provider collections, auth resolution (API keys, OAuth), streaming events, token and cost tracking, tool calling, cross-provider context hand-off, image generation, classification |
+| [`pi_agent`](https://github.com/nivalume/pi-py/blob/main/packages/agent/README.md) | `@earendil-works/pi-agent-core` | Stateful agent: tool execution (parallel or sequential), steering and follow-up queues, lifecycle events, hooks |
+
+```bash
+pip install pi-ai-python               # httpx + official SDKs: anthropic, openai, google-genai
+pip install "pi-ai-python[bedrock]"    # + boto3 for Amazon Bedrock
+pip install "pi-ai-python[all]"        # + orjson, websockets, pydantic, boto3
+```
+
+中文说明见 [README.zh-CN.md](https://github.com/nivalume/pi-py/blob/main/README.zh-CN.md)。
+
+```python
+import asyncio
+
+from pi_ai import Context, UserMessage
+from pi_ai.providers.all import builtin_models
+
+
+async def main() -> None:
+    models = builtin_models()  # every built-in provider; auth comes from env vars such as ANTHROPIC_API_KEY
+    model = models.get_model("anthropic", "claude-sonnet-4-5")
+    stream = models.stream(model, Context(system_prompt="Be brief.", messages=[UserMessage("Hello!")]))
+    async for event in stream:
+        if event.type == "text_delta":
+            print(event.delta, end="", flush=True)
+    message = await stream.result()
+    print(f"\n{message.usage.input} in / {message.usage.output} out, ${message.usage.cost.total:.4f}")
+
+
+asyncio.run(main())
+```
+
+```python
+from pi_agent import Agent, AgentInitialState, agent_tool
+
+
+@agent_tool
+async def get_time(timezone: str = "UTC") -> str:
+    """Get the current time.
+
+    Args:
+        timezone: IANA timezone name.
+    """
+    ...
+
+
+agent = Agent(
+    initial_state=AgentInitialState(system_prompt="You are helpful.", model=model, tools=[get_time]),
+    stream_fn=models.stream_simple,
+)
+async for event in agent.events("What time is it in Tokyo?"):
+    print(event.type)
+```
+
+## Same API, Python conventions
+
+The port keeps pi's architecture and semantics: the same `Models`/`Provider`
+runtime, the same event protocol (`start` → `text_delta`… → `done`/`error`), the
+same transcript model (system prompt and tools carried by system messages), the
+same auth precedence rules, the same model catalog, and the same agent loop.
+Names follow Python conventions:
+
+| TypeScript | Python |
+| --- | --- |
+| `createModels()`, `models.streamSimple(...)` | `create_models()`, `models.stream_simple(...)` |
+| `{ apiKey, sessionId, maxTokens }` options | `api_key=..., session_id=..., max_tokens=...` keyword arguments (or a dict) |
+| `message.stopReason`, `usage.cacheRead` | `message.stop_reason`, `usage.cache_read` |
+| `{ role: "user", content: "hi", timestamp }` | `UserMessage("hi")` (timestamp defaults to now) |
+| `Type.Object({...})` (TypeBox) | `Type.Object({...})` (built in) or a Pydantic model |
+| `AbortController` / `signal` | `pi_ai.AbortController` / `signal=` |
+| `for await (const e of stream)` / `await stream.result()` | `async for e in stream` / `await stream.result()` |
+| `agent.continue()` | `agent.continue_()` (alias `agent.resume()`) |
+
+String values that appear on the wire or in persisted transcripts are unchanged
+(`"toolUse"`, `"toolResult"`, `"text_delta"`, API ids, provider ids), and
+`pi_ai.serialization` reads and writes pi's camelCase JSON, so sessions, model
+definitions and `auth.json` credential files are interchangeable with TypeScript pi.
+
+## Design notes
+
+* **Official vendor SDKs.** As in pi, the Anthropic, OpenAI (Chat Completions,
+  Responses, Azure, OpenRouter images), Google (Gemini, Vertex) and Bedrock adapters use
+  the vendors' official SDKs: `anthropic`, `openai`, `google-genai` and `boto3`
+  (`pi-ai-python[bedrock]`). The SDK clients share one pooled `httpx.AsyncClient` per event loop.
+  APIs that pi calls without an SDK (Mistral, OpenAI Codex, pi-messages, classifiers)
+  use `httpx` directly.
+* **Fast streaming path.** Slotted data classes, an allocation-light event queue,
+  zero-copy forwarding between wrapped streams, an incremental partial-JSON parser
+  for tool-call arguments (about 60x faster than re-parsing each delta on large
+  arguments), linear-time accumulation of streamed text, optional `orjson` decoding,
+  and compiled, cached tool-argument validators. On one core the anthropic-messages
+  adapter processes about 110,000 stream events per second and openai-completions about
+  70,000, where the openai SDK's SSE decoder is the limit (see `benchmarks/`).
+* **Lazy everything.** Model catalogs load per provider on first use; API
+  implementations and OAuth flows import on first request.
+* **Async-native cancellation.** `AbortSignal` aborts interrupt pending network reads
+  immediately (task cancellation scoped by `abort_scope`), and aborted requests end
+  their stream with `stop_reason == "aborted"` instead of raising.
+* **Python-friendly additions.** Pydantic models as tool parameter schemas,
+  `@agent_tool` to build tools from typed functions, `Agent.events()` as an async
+  iterator, `FileCredentialStore` (pi's `auth.json` format with cross-process locking),
+  keyword-argument options, streams that can be created outside an event loop and
+  closed with `async with`.
+
+## Development
+
+```bash
+uv sync                      # create .venv with the package (editable) and dev tools
+uv run pytest                # run all tests (offline; HTTP is mocked)
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+uv run python benchmarks/bench_partial_json.py
+uv run python benchmarks/bench_stream.py
+```
+
+Model catalog data (`packages/ai/src/pi_ai/providers/data/*.json`) is the generated
+catalog shipped with `@earendil-works/pi-ai` 1.3.0.
+
+## License
+
+MIT. Based on pi by Mario Zechner and contributors.

pi_ai_python-1.3.0/README.zh-CN.md

@@ -0,0 +1,114 @@
+# pi-py
+
+[pi](https://github.com/earendil-works/pi) 核心库的 Python 实现，包含两个模块：
+
+| Import 名 | 对应上游 | 作用 |
+| --- | --- | --- |
+| [`pi_ai`](packages/ai/README.md) | `@earendil-works/pi-ai` | 统一的 LLM API：provider 集合、鉴权解析（API key / OAuth）、流式事件、token 与费用统计、工具调用、跨 provider 上下文切换、图像生成、分类 |
+| [`pi_agent`](packages/agent/README.md) | `@earendil-works/pi-agent-core` | 有状态 Agent：工具执行（并行/串行）、steering 与 follow-up 队列、生命周期事件、钩子 |
+
+两者在 PyPI 上作为同一个包 `pi-ai-python` 发布。
+
+## 安装
+
+```bash
+pip install pi-ai-python                  # 依赖 httpx 和官方 SDK：anthropic、openai、google-genai
+pip install "pi-ai-python[bedrock]"       # 可选：boto3，用于 Amazon Bedrock
+pip install "pi-ai-python[fast]"          # 可选：orjson 加速 JSON 解码
+pip install "pi-ai-python[all]"           # 可选：orjson + websockets + pydantic + boto3
+```
+
+开发环境：
+
+```bash
+uv sync
+uv run pytest
+```
+
+## 快速开始
+
+```python
+import asyncio
+
+from pi_ai import Context, UserMessage
+from pi_ai.providers.all import builtin_models
+
+
+async def main() -> None:
+    models = builtin_models()                     # 注册全部内置 provider，鉴权读取 ANTHROPIC_API_KEY 等环境变量
+    model = models.get_model("anthropic", "claude-sonnet-4-5")
+    stream = models.stream(model, Context(system_prompt="回答要简洁。", messages=[UserMessage("你好！")]))
+    async for event in stream:
+        if event.type == "text_delta":
+            print(event.delta, end="", flush=True)
+    message = await stream.result()
+    print(f"\n输入 {message.usage.input} / 输出 {message.usage.output} tokens，费用 ${message.usage.cost.total:.4f}")
+
+
+asyncio.run(main())
+```
+
+Agent：
+
+```python
+from pi_agent import Agent, AgentInitialState, agent_tool
+
+
+@agent_tool
+async def get_weather(city: str) -> str:
+    """查询天气。
+
+    Args:
+        city: 城市名。
+    """
+    return f"{city}：晴，25°C"
+
+
+agent = Agent(
+    initial_state=AgentInitialState(system_prompt="你是一个助手。", model=model, tools=[get_weather]),
+    stream_fn=models.stream_simple,
+)
+async for event in agent.events("北京天气怎么样？"):
+    if event.type == "message_update" and event.assistant_message_event.type == "text_delta":
+        print(event.assistant_message_event.delta, end="")
+```
+
+## 与 pi 保持一致的 API
+
+架构与语义与 TypeScript 版一致：同样的 `Models`/`Provider` 运行时、同样的事件协议
+（`start` → `text_delta`… → `done`/`error`）、同样的 transcript 模型（系统提示词和工具由
+system message 承载）、同样的鉴权优先级、同样的模型目录和 Agent 循环。命名遵循 Python 习惯：
+
+| TypeScript | Python |
+| --- | --- |
+| `createModels()`、`models.streamSimple(...)` | `create_models()`、`models.stream_simple(...)` |
+| `{ apiKey, sessionId, maxTokens }` | 关键字参数 `api_key=..., session_id=..., max_tokens=...`（也可传 dict） |
+| `message.stopReason`、`usage.cacheRead` | `message.stop_reason`、`usage.cache_read` |
+| `{ role: "user", content: "hi", timestamp }` | `UserMessage("hi")`（timestamp 默认为当前时间） |
+| TypeBox `Type.Object({...})` | 内置 `Type.Object({...})` 或 Pydantic 模型 |
+| `AbortController` / `signal` | `pi_ai.AbortController` / `signal=` |
+| `agent.continue()` | `agent.continue_()`（别名 `agent.resume()`） |
+
+线上协议和持久化中出现的字符串值保持不变（`"toolUse"`、`"toolResult"`、`"text_delta"`、API id、
+provider id）。`pi_ai.serialization` 读写 pi 的 camelCase JSON，会话记录、模型定义和
+`auth.json` 凭据文件都可以与 TypeScript 版互通。
+
+## 设计改进
+
+* **使用厂商官方 SDK**：与 pi 一致，Anthropic、OpenAI（Chat Completions、Responses、Azure、OpenRouter 图片）、
+  Google（Gemini、Vertex）和 Bedrock 适配器分别使用官方 SDK `anthropic`、`openai`、`google-genai`、`boto3`
+  （`pi-ai-python[bedrock]`），各 SDK 客户端共用每个事件循环一个的 `httpx.AsyncClient` 连接池。
+  pi 本身不经 SDK 调用的 API（Mistral、OpenAI Codex、pi-messages、分类器）直接使用 `httpx`。
+* **性能**：slots 数据类、低分配的事件队列、包装流之间零拷贝转发、增量式部分 JSON 解析
+  （大参数工具调用比逐 delta 全量重解析快约 60 倍）、流式文本线性时间累加、可选 orjson、编译并缓存的参数校验器。
+  单核每秒处理流事件：anthropic-messages 约 11 万，openai-completions 约 7 万（瓶颈在 openai SDK 的 SSE 解码，见 `benchmarks/`）。
+* **全面懒加载**：模型目录按 provider 首次访问时加载；API 实现和 OAuth 流程在首次请求时导入。
+* **原生异步取消**：`AbortSignal` 可立即中断挂起的网络读取，被中止的请求以 `stop_reason == "aborted"` 结束而不是抛异常。
+* **Python 友好的扩展**：Pydantic 模型作为工具参数、`@agent_tool` 从类型注解生成工具、`Agent.events()` 异步迭代器、
+  `FileCredentialStore`（pi 的 `auth.json` 格式，带跨进程锁）、事件循环外创建的流、`async with` 关闭流。
+
+详细文档：[pi_ai](packages/ai/README.md)、[pi_agent](packages/agent/README.md)。
+
+## 许可证
+
+MIT，基于 Mario Zechner 等人的 pi。