Metadata-Version: 2.5
Name: ordin
Version: 0.1.0
Summary: Platform-independent runtime for centrally orchestrated agent execution
License: MIT
Requires-Python: >=3.12
Requires-Dist: openai>=2.53.0
Requires-Dist: pydantic>=2.11.0
Requires-Dist: pyyaml>=6.0.2
Description-Content-Type: text/markdown

# Ordin Agent Runtime

Ordin 是一个模型中立、平台无关的 Python Agent Runtime。宿主平台提供已认证身份、持久化的用户消息、
Conversation 引用、不可变资源快照和运行时 Ports；Ordin 执行完整 Agent 链路：意图识别、
direct/clarify/Mission 路由、Task DAG、动态 sub-Agent、Context/LLM/Tool 循环、结果验收与最终聚合。

Ordin Core 不实现消息队列、Worker host、PostgreSQL 或具体对象存储。它定义领域模型、窄 Port、
CAS/原子提交/fencing/effect-ledger 合同，并在 `arbor.testing` 提供可执行的内存参考 Adapter。

PyPI distribution 名称是 `ordin`，当前稳定 Python 导入命名空间是 `arbor`。

## 安装与校验

从 PyPI 安装：

```bash
pip install ordin
```

源码开发与完整校验：

```bash
uv sync
uv run python scripts/docs.py --check
uv run pytest tests/test_docs.py
uv run ruff format .
uv run ruff check .
uv run ty check
uv run pytest
```

## 最小示例

下面用内存 Adapter 模拟平台先持久化 `UserMessage`、再提交 `ExecutionRequest`。生产平台应以自己的
事务存储和对象存储实现相同 Ports。

```python
from arbor.agent import Agent
from arbor.common import Identity
from arbor.llm import LLMCallPipeline, LLMProfile
from arbor.mission import ConcatAggregator, SingleTaskPlanner
from arbor.observability import EventBroker
from arbor.runtime import Runtime
from arbor.testing import InMemoryObjectStore, InMemoryRuntimeBackend

backend = InMemoryRuntimeBackend()
events = EventBroker(backend)
llm_calls = LLMCallPipeline(
    provider=my_llm_provider,
    recorder=backend,
    event_sink=events,
)
runtime = Runtime(
    llm_calls=llm_calls,
    events=events,
    llm_profile=LLMProfile(id="private-model"),
    backend=backend,
    object_store=InMemoryObjectStore(),
    direct_agent=Agent[None](name="direct", instructions="Answer the request."),
    planner=SingleTaskPlanner(),
    aggregator=ConcatAggregator(),
    enable_memory_tools=False,
)

identity = Identity(user_id="u-1")
request = await backend.prepare_execution(
    "实现一个可测试的分析流程",
    identity=identity,
)
result = await runtime.execute(request, context=None)
```

`Runtime.start()` 返回 direct/clarify 结果或 `MissionHandle`；`Runtime.execute()` 等待完整执行完成。
两者都只接受平台已经装配好的 `ExecutionRequest`，不会接收并持久化原始用户消息。

当同一 Branch 已有活跃 Execution 时，平台不应再创建并发 Execution，而应在同一事务追加
Conversation `UserMessage` 和 `SupervisorMessage`。Supervisor 会把消息分类为指导、目标修订、状态
查询、取消、暂停、恢复或后继目标。内存参考 Adapter 的 `append_supervisor_text()` 展示了该原子入口。

## 生产组合

推荐使用 PostgreSQL 保存 Conversation、Execution/Mission、Plan/Task、command cursor、LLM call、
effect ledger 和 Artifact metadata，使用 S3/MinIO 等对象存储保存大字节。队列、lease、Worker 部署、
认证、租户、配额和资源授权都由宿主平台负责。平台的 execution authority 必须在每次关键提交前
检查所有权；外部 Tool 副作用仍需幂等键、对账和 `needs_attention`，不能宣称 exactly-once。

## 文档

- [文档入口](docs/index.md)
- [架构总览](docs/architecture/overview.md)
- [Runtime 与 Supervisor](docs/architecture/runtime.md)
- [Ports 与生产 Adapter](docs/architecture/persistence.md)
- [快速开始](docs/guides/quickstart.md)
- [平台 Adapter 指南](docs/guides/platform-adapters.md)
- [代码树](docs/reference/code-tree.md) 与 [公开 API](docs/reference/public-api.md)
- [ADR-0007：平台无关 Runtime](docs/adr/0007-platform-independent-runtime.md)
- [ADR-0008：Supervisor Inbox](docs/adr/0008-supervisor-inbox.md)

可运行示例位于 `examples/`；其中 `examples/csv_subagent.py` 展示平台冻结资源快照并构造
`ExecutionScope` 的完整离线路径。
