Metadata-Version: 2.5
Name: interlace-py
Version: 0.2.0
Summary: An extensible microkernel for typed graphs and event workflows
Project-URL: Homepage, https://github.com/KKKKKKKEM/interlace
Project-URL: Repository, https://github.com/KKKKKKKEM/interlace.git
Author-email: Kem <531144129@qq.com>
License: MIT
License-File: LICENSE
Keywords: automation,engine,graph,state-machine,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.10
Provides-Extra: service
Requires-Dist: fastapi<1,>=0.115; extra == 'service'
Requires-Dist: jsonrpcserver<6,>=5; extra == 'service'
Requires-Dist: pydantic<3,>=2.9; extra == 'service'
Requires-Dist: uvicorn<1,>=0.30; extra == 'service'
Description-Content-Type: text/markdown

# Interlace

Interlace 是一个可扩展的 Python 编排微内核：Graph 内以 `Output` 和 `Edge` 传递局部数据，Graph 间以
`Event` 和 `Runtime` 连接领域工作流。

核心实现通过公开协议替换，功能通过插件和领域节点扩展，Graph 与 Execution 的公共契约保持稳定。
运行时没有第三方依赖；爬虫模型、下载器与下载节点由独立的 [Bricks](https://github.com/KKKKKKKEM/bricks) 提供。

## 安装

发行包名为 `interlace-py`，导入名为 `interlace`。当前通过 Git 安装，尚未发布到 PyPI：

```bash
uv pip install "interlace-py @ git+https://github.com/KKKKKKKEM/interlace.git"
```

生产项目应将 Git 依赖固定到经过验证的提交。开发本仓库可使用 `uv sync`。

### 发布到 PyPI

仓库的 `.github/workflows/python-publish.yml` 在 GitHub Release 发布后运行完整 CI、构建 wheel/sdist、
检查发行元数据，并通过 PyPI Trusted Publishing 上传同一批已验证产物。Release 标签必须与项目版本一致：
当前版本为 `0.2.0`，对应标签 `v0.2.0`。尚未完成首次上传，不能把上述 Git 安装命令改成索引安装。

首次发布前，在 PyPI 的 Publishing 页面添加 pending publisher：

- PyPI 项目：`interlace-py`（`interlace` 在 PyPI 禁用名单中）
- GitHub owner：`KKKKKKKEM`
- GitHub repository：`interlace`
- Workflow filename：`python-publish.yml`
- Environment：`pypi`

发布工作流只在上传作业授予 OIDC `id-token: write`，不借用其他仓库的 PyPI Token。
维护者应在 GitHub 配置 `pypi` environment 的审批与标签限制，再发布对应 Release。
上传成功后先确认 PyPI 可安装该版本，再让下游更新依赖与锁文件；不要用本地目录替换下游正式依赖。

本地检查发行包：

```bash
uv build --no-sources
uv tool run twine check --strict dist/*
```

构建与元数据检查通过不代表已经上传，也不代表 PyPI 已授予项目发布权限。

```text
Node -- Output / Edge --> Node
Graph -- Event / Runtime --> Graph
```

顶层 API 还提供进程内的 `Slot` 与 `SlotPool`：队列 Work 可以在同一进程中跨 Consumer 传递并复用代理、Cookie、
连接等执行状态，而不依赖具体线程。Slot 不跨进程或消息边界传输。

执行默认不限步数、时长和 Graph 内积压；`run()`、`start()` 和事件 route 可按需设置 `max_steps`、Graph `timeout`
与待消费输入上限 `max_queued`，单次 Node firing 的时限由该 Node 的 `timeout` 属性声明。`start()` 返回可查询和
协作式取消的 `Execution`。
`Execution` 可调用 `result()`、直接 `await`，也可同步或异步迭代 terminal Output；`Runtime.iter()` 和
`Runtime.aiter()` 提供对应便利入口。

所有节点统一继承 `Node`。`execute()` 可以使用普通 `def` 或 `async def`；普通函数返回的 Awaitable 也由
Engine 等待，再按相同的 Output 契约处理结果。

## 最小示例

```python
from interlace import Graph, Node, Output, Runtime


class Upper(Node):
    inputs = {"text": str}
    outputs = {"result": str}
    timeout = 5

    def execute(self, inputs, context):
        del context
        return Output(inputs["text"].upper(), "result")


graph = Graph.compose(nodes={"upper": Upper()}, entrypoint="upper")

with Runtime() as runtime:
    runtime.register("upper.graph", graph)
    print(runtime.run("upper.graph", "interlace"))
```

完整内容按一本手册组织，从[文档目录](https://github.com/KKKKKKKEM/interlace/blob/main/docs/README.md)开始：

1. [设计哲学与心智模型](https://github.com/KKKKKKKEM/interlace/blob/main/docs/01-design-philosophy.md)
2. [第一张 Graph](https://github.com/KKKKKKKEM/interlace/blob/main/docs/02-first-graph.md)
3. [Graph 数据流](https://github.com/KKKKKKKEM/interlace/blob/main/docs/03-graph-dataflow.md)
4. [Event 与跨图工作流](https://github.com/KKKKKKKEM/interlace/blob/main/docs/04-events-and-workflows.md)
5. [Execution、并发与失败](https://github.com/KKKKKKKEM/interlace/blob/main/docs/05-execution.md)
6. [Runtime 内部架构](https://github.com/KKKKKKKEM/interlace/blob/main/docs/06-runtime-architecture.md)
7. [插件、SPI 与适配器开发](https://github.com/KKKKKKKEM/interlace/blob/main/docs/07-plugins.md)
8. [编排模式](https://github.com/KKKKKKKEM/interlace/blob/main/docs/08-patterns.md)
9. [RPC 与图服务](https://github.com/KKKKKKKEM/interlace/blob/main/docs/09-service.md)

## 可选 RPC 与图服务

官方服务 extra 提供 HTTP/JSON 调用、JSON-RPC 2.0、SSE 输出流，以及图编辑发布、项目管理与运行历史接口。
服务只提供数据接口，不托管前端页面；基础安装仍保持零运行时依赖，不自动启动服务。

```bash
uv pip install "interlace-py[service] @ git+https://github.com/KKKKKKKEM/interlace.git"
uv run --extra service python examples/service.py
```

启动后在 `http://127.0.0.1:8000/docs` 查看 OpenAPI 文档。已有代码图直接支持远程调用和运行查看；登记节点工厂与
配置模型后，还可以通过编辑文档校验、保存草稿与发布不可变版本。

已有 Runtime 可直接接入：

```python
from interlace.service import GraphService

# runtime 为已经注册 Graph 的运行时，由调用方管理生命周期。
service = GraphService(runtime, database=".interlace/service.sqlite3")
service.serve()
```

安装、节点目录、HTTP/JSON-RPC 调用及服务所有权见[第九章](https://github.com/KKKKKKKEM/interlace/blob/main/docs/09-service.md)。

## 当前范围

默认实现通过内建 `LocalRuntimePlugin` 提供内存事件分发、线程池队列并发和 Graph 执行；它与第三方扩展一样由
统一 `PluginHost` 装配。EventBus、任务传输、GraphExecutor、输入策略、Node Hook 和 Runtime Observer 均可受控
扩展，但 Graph 的类型、冻结和 Execution 语义保持固定。默认实现不提供持久化、broker ack、进程恢复、定时器、
死信队列或 exactly-once 语义。

源码按 `engine`、`runtime`、`plugins`、`spi`、`adapters` 和可复用 `nodes` 分层；各包职责、目录树和允许的
依赖方向见[Runtime 内部架构](https://github.com/KKKKKKKEM/interlace/blob/main/docs/06-runtime-architecture.md#源码目录与包职责)。

```bash
uv run python examples/linear.py
uv run python examples/fan_in.py
uv run python examples/cycle.py
uv run python examples/event_routing.py
uv run python examples/async_node.py
uv run python examples/output_stream.py
uv run python examples/domain_context.py
uv run pytest -q
```
