interlacing 0.11.0__tar.gz

interlacing-0.11.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+build/
+dist/

interlacing-0.11.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Versions before 1.0 may change any interface; each change is listed here. From 1.0 on, the names exported
+by `interlacing` and the formats of graph files, run directories and journals change incompatibly only
+with a new major version.
+
+## 0.11.0
+
+First release on the package index.
+
+- Nodes (`FunctionNode`, `AgentNode`, `ProcessNode`, `SourceNode`, `SinkNode`, `HumanNode`, `GraphNode`),
+  protocols (`value`, `latest`, `state`, `signal`, `stream`, `call`, `artifact`, `file`) and methods (`Chain`, `Loop`,
+  `Fan`, `Tree`, `Star`, `Governed`, `Pool`).
+- The engine: workers, journal and `resume`, time limits, budgets, an observer, output checks with repairs.
+- `Block`, `seq`, `par`; graphs as JSON with `Catalog`; `SpawnNode` for graphs written during a run.
+- `Desk`: a node that takes in from several places, sorts, and hands out to several; `Fan` joins a split and a
+  join to its branches by name, and shows everything they take and give.
+- Run directories, the `interlacing` command, and an MCP server over stdio.
+- Graphs that are not trusted are held to the run's time limit, node count and workers (`firm`, `strict`).

interlacing-0.11.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 li2o0577
+
+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.

interlacing-0.11.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: interlacing
+Version: 0.11.0
+Summary: Nodes, edges and methods: join models, programs, devices and people into graphs, and run them
+Project-URL: Homepage, https://github.com/Li2O0577/interlacing
+Project-URL: Documentation, https://github.com/Li2O0577/interlacing/blob/main/docs/GRAPH.md
+Project-URL: Changelog, https://github.com/Li2O0577/interlacing/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Li2O0577/interlacing/issues
+Author: li2o0577
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,graph,mcp,multi-agent,orchestration,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# interlacing
+
+**English** · [中文](https://github.com/Li2O0577/interlacing/blob/main/README.zh-CN.md)
+
+Join anything into a graph and run it.
+
+- A **node** is anything that takes information in and gives information out: a model, a function, an external program, a device, a person, or another graph.
+- An **edge** carries information from one node to another under a written protocol: queued values, latest value only, state, signals, streams, calls that are answered, files passed by path.
+- A **method** is a ready-made way of joining nodes: chain, loop, fan-out and join, tree, star, a tree that needs a person's consent, a pool of members that appear when called.
+
+The engine runs the graph and looks after the run: outputs are checked, usage is counted against a budget, activations are timed, everything is journaled so an interrupted run carries on, and an observer is told what happens as it happens. The package is a kernel to build frameworks on. It depends on the Python standard library and nothing else.
+
+## Install
+
+```sh
+pip install interlacing
+pip install -e .            # or from a checkout
+```
+
+Python 3.11 or later, on Linux, macOS and Windows.
+
+## A first graph
+
+```python
+from interlacing import DEFAULT, Chain, Engine, FunctionNode, Port
+
+double = FunctionNode("double", lambda x: x * 2, inputs=[Port("x", int)], outputs=[Port("y", int)])
+show = FunctionNode("show", lambda x: f"={x}", inputs=[Port("x", int)], outputs=[Port("y", str)])
+
+graph = Chain(double, show).build(DEFAULT)
+print(Engine(graph, DEFAULT).run({"in": 21}).last("out"))     # =42
+```
+
+## What it does
+
+**A model with tools.** A tool is a call edge to an ordinary node, so a dictionary, a program and a robot arm are all answered the same way.
+
+```python
+from interlacing import AgentNode, GraphBuilder, SinkNode, Tool
+
+agent = AgentNode("agent", model, system="...", tools=[Tool("lookup", "Look a word up"), Tool("move", "Move the arm")])
+graph = (GraphBuilder().add(agent, dictionary, SinkNode("arm", arm.move, answers=True))
+         .connect("agent.lookup", "dictionary.x", "call")
+         .connect("agent.move", "arm.x", "call")
+         .input("in", "agent.task").output("out", "agent.out").compile(DEFAULT))
+```
+
+`model` is any object with `chat(system, messages, tools, max_tokens)`. `interlacing.models` has an Anthropic interface, an OpenAI-compatible interface, and `FakeProvider` for tests.
+
+**Outputs that are checked.** A port says what may leave through it and what happens when something else does: the node fails, the payload goes on with a warning, or the node is told what is wrong and may send again.
+
+```python
+Port("plan", dict, check=valid_plan, repairs=2)      # a model is told why its plan was refused, twice at most
+```
+
+**Files passed by path.** Nodes send relative paths, not contents. The file is checked when it is sent and again when it arrives.
+
+```python
+protocols = with_files(DEFAULT, "work")
+Port("chart", FileOf(".png", max_size=5_000_000), repairs=2)
+builder.connect("draw.chart", "report.chart", "file")
+```
+
+**Designs used as units.** A graph that has been worked out becomes a block, used many times and joined with others.
+
+```python
+review = Block(lambda: Loop(writer(), critic(), max_rounds=3), name="review")
+study = seq(clean, par(review, review, review), publish)       # in a row, side by side, nested
+graph = Chain(intake, study("study"), report).build(DEFAULT)
+```
+
+**Desks at the doors of a block.** A `Desk` takes in what arrives from several places, sorts it, and hands it out to several places. At the way into a block it shares the work among the members; at the way out it makes one answer of what they gave. Where the sorting needs judgement, an agent with the same inputs and outputs stands in the same place.
+
+```python
+team = Fan(analyst, modeller,                                   # each member gets its own part, by name
+           split=Desk("door", takes=["brief", "data"], gives=["analyst", "modeller"], sort=share),
+           join=Desk("exit", takes=["analyst", "modeller"], sort=report))
+```
+
+**Graphs that are not fixed in advance.** `Pool` keeps places for members that do nothing until they are called for. `SpawnNode` builds and runs a graph that a node wrote during the run, within limits set by whoever made the node.
+
+```python
+grow = SpawnNode("grow", Catalog(allow=["my_steps"]), max_nodes=20)
+graph = Chain(planner, grow).build(DEFAULT)                    # planner sends {"graph": ..., "inputs": ...}
+```
+
+**Runs that are looked after.**
+
+```python
+engine = Engine(graph, DEFAULT, workers=4,
+                journal=Journal("run.jsonl"),                  # an interrupted run is taken up with resume()
+                time_limit=600,                                # the longest one activation may take
+                budget={"tokens": 2_000_000},                  # nodes report what they use; over it, the run stops
+                observe=print)                                 # every event, as it happens
+```
+
+A node that must not do something twice outside the graph uses `ctx.key`, which stays the same when an interrupted activation runs again.
+
+**Graphs written as data.** A graph file holds the structure and whatever differs from the defaults; a prompt is a file that is referred to.
+
+```json
+{
+  "defaults": {"agent": {"model": "anthropic:some-model", "time_limit": 600}},
+  "method": "pool", "size": 10, "max_rounds": 3,
+  "root": {"id": "lead", "kind": "agent", "system": {"file": "prompts/lead.md"}, "firing": "any",
+           "inputs": ["task", {"name": "reply", "required": false}], "outputs": ["out", "send"]},
+  "member": {"kind": "agent", "system": {"file": "prompts/scout.md"}}
+}
+```
+
+```sh
+cd examples/data && export PYTHONPATH=.
+interlacing check  release.json --allow steps
+interlacing run    release.json --dir /tmp/run --allow steps --input topic=tides    # waiting for a person, exit code 3
+interlacing answer --dir /tmp/run --json '{"approved": true}'
+interlacing resume --dir /tmp/run                                                   # done, exit code 0
+```
+
+A run is a directory. A person in the graph who has not answered yet does not keep a process waiting: the command exits, and the run goes on once the answer has been given. One process at a time runs a directory.
+
+**As an MCP server.** The same operations can be offered to a model in another application. What its graphs may reach, how much they may use and how long a node may take are set on the command line by whoever starts the server, and the client cannot change them.
+
+```json
+{"mcpServers": {"interlacing": {"command": "interlacing",
+  "args": ["serve", "--runs", "/path/to/runs", "--allow", "mypkg", "--budget", "tokens=500000"]}}}
+```
+
+Model keys are read from the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and their `_BASE_URL`), and are never written to a graph file, a run directory or a journal.
+
+## What it is for
+
+Three worked cases are in [docs/CASES.md](https://github.com/Li2O0577/interlacing/blob/main/docs/CASES.md) (in Chinese). In short:
+
+| Case | How it is built |
+|---|---|
+| A physical agent: a multimodal model plans gripper poses as points in space, a controller executes, and the next observation decides what follows | `Loop(observe, planning, act)`; the model's measuring tools are nodes on call edges; the action contract is a check on the plan port, so a bad plan goes back to the model with the reason and never reaches the controller; plans and seconds are budgets. Runnable with stand-ins: [examples/graphs/planner_and_arm.py](https://github.com/Li2O0577/interlacing/blob/main/examples/graphs/planner_and_arm.py) |
+| A modelling assistant: a lead, one owner per question, a solver and a critic who argue until the answer is proved, a person who may step in anywhere | each question is a `Block` holding a `Loop(solve, critic)`; "no proof, not done" is a port check; questions run in `seq`; the person is the operator of a `Governed` tree; the run directory survives restarts |
+| A mathematician: a lead sends out explorers in parallel, each hands its work to a proof checker and reports back when it passes | `Pool(lead, explorer, size=10)` with `workers`; each explorer is a `Loop(prove, check)`; three directions given, three explorers exist |
+
+The kernel carries information and looks after the run. How a model thinks, how an arm moves and how a paper is typeset are the business of the nodes.
+
+## Layout
+
+| Layer | Package | Main names |
+|---|---|---|
+| Abstractions | `interlacing.base` | `Node`, `Port`, `Schema`, `Edge`, `Protocol`, `Envelope`, `Graph`, `GraphBuilder`, `Method`, `Context` |
+| Engine | `interlacing.engine` | `Engine`, `Result`, `RunError`, `Journal`, `Transport` |
+| Parts | `interlacing.nodes`, `.protocols`, `.methods`, `.models` | `FunctionNode`, `AgentNode`, `ProcessNode`, `SourceNode`, `SinkNode`, `HumanNode`, `GraphNode`, `Desk`; `Chain`, `Loop`, `Fan`, `Tree`, `Star`, `Governed`, `Pool` |
+| Blocks | `interlacing.blocks` | `Block`, `seq`, `par` |
+| Graphs as data | `interlacing.spec` | `dump`, `load`, `read`, `write`, `Catalog`, `SpawnNode` |
+| Outside | `interlacing.runs`, `interlacing.cli`, `interlacing.serve` | `Run`; the command `interlacing`; the MCP server |
+
+Each layer uses only the layers below it. The engine knows no particular node, protocol or method; a test in `tests/test_engine.py` holds it to that.
+
+The full description is [docs/GRAPH.md](https://github.com/Li2O0577/interlacing/blob/main/docs/GRAPH.md) (in Chinese). Nine examples that run as they stand are in [examples/graphs/](https://github.com/Li2O0577/interlacing/tree/main/examples/graphs), and graphs written as JSON in [examples/data/](https://github.com/Li2O0577/interlacing/tree/main/examples/data).
+
+## Tests
+
+```sh
+python -m pip install -e . pytest
+python -m pytest -q tests
+python scripts/bench_engine.py       # what the engine adds per envelope (about 11 microseconds)
+```
+
+The tests run on Linux, macOS and Windows, with scripted models and stand-in devices. They include runs broken at random places, with the journal cut short as a dying process leaves it, which must end as unbroken runs do. The package passes `mypy`.
+
+## Limits
+
+- Taking a run up again is at-least-once: an interrupted node runs again, and what it did outside the graph is done again unless the node uses `ctx.key` to prevent it.
+- Delivery is in-process only. `Transport` is the place for carrying envelopes between processes or machines, and nothing is there yet.
+- Both model interfaces have been tried once, with very small requests, against one compatible service. Thinking output, picture input and retries on rate limits have not been tried against a real service. Device nodes have only met stand-ins.
+- A node that overruns its time is abandoned, not killed: a thread cannot be stopped from outside. A program started by `ProcessNode` is killed.
+- `allow` is a list of modules whose functions a graph may name. It is not a sandbox.
+- The MCP server speaks over stdio only, handles one call at a time, and has not been tried with a real client.
+- There is no asynchronous interface; the engine uses threads.
+
+## License
+
+MIT

interlacing-0.11.0/README.md

@@ -0,0 +1,179 @@
+# interlacing
+
+**English** · [中文](https://github.com/Li2O0577/interlacing/blob/main/README.zh-CN.md)
+
+Join anything into a graph and run it.
+
+- A **node** is anything that takes information in and gives information out: a model, a function, an external program, a device, a person, or another graph.
+- An **edge** carries information from one node to another under a written protocol: queued values, latest value only, state, signals, streams, calls that are answered, files passed by path.
+- A **method** is a ready-made way of joining nodes: chain, loop, fan-out and join, tree, star, a tree that needs a person's consent, a pool of members that appear when called.
+
+The engine runs the graph and looks after the run: outputs are checked, usage is counted against a budget, activations are timed, everything is journaled so an interrupted run carries on, and an observer is told what happens as it happens. The package is a kernel to build frameworks on. It depends on the Python standard library and nothing else.
+
+## Install
+
+```sh
+pip install interlacing
+pip install -e .            # or from a checkout
+```
+
+Python 3.11 or later, on Linux, macOS and Windows.
+
+## A first graph
+
+```python
+from interlacing import DEFAULT, Chain, Engine, FunctionNode, Port
+
+double = FunctionNode("double", lambda x: x * 2, inputs=[Port("x", int)], outputs=[Port("y", int)])
+show = FunctionNode("show", lambda x: f"={x}", inputs=[Port("x", int)], outputs=[Port("y", str)])
+
+graph = Chain(double, show).build(DEFAULT)
+print(Engine(graph, DEFAULT).run({"in": 21}).last("out"))     # =42
+```
+
+## What it does
+
+**A model with tools.** A tool is a call edge to an ordinary node, so a dictionary, a program and a robot arm are all answered the same way.
+
+```python
+from interlacing import AgentNode, GraphBuilder, SinkNode, Tool
+
+agent = AgentNode("agent", model, system="...", tools=[Tool("lookup", "Look a word up"), Tool("move", "Move the arm")])
+graph = (GraphBuilder().add(agent, dictionary, SinkNode("arm", arm.move, answers=True))
+         .connect("agent.lookup", "dictionary.x", "call")
+         .connect("agent.move", "arm.x", "call")
+         .input("in", "agent.task").output("out", "agent.out").compile(DEFAULT))
+```
+
+`model` is any object with `chat(system, messages, tools, max_tokens)`. `interlacing.models` has an Anthropic interface, an OpenAI-compatible interface, and `FakeProvider` for tests.
+
+**Outputs that are checked.** A port says what may leave through it and what happens when something else does: the node fails, the payload goes on with a warning, or the node is told what is wrong and may send again.
+
+```python
+Port("plan", dict, check=valid_plan, repairs=2)      # a model is told why its plan was refused, twice at most
+```
+
+**Files passed by path.** Nodes send relative paths, not contents. The file is checked when it is sent and again when it arrives.
+
+```python
+protocols = with_files(DEFAULT, "work")
+Port("chart", FileOf(".png", max_size=5_000_000), repairs=2)
+builder.connect("draw.chart", "report.chart", "file")
+```
+
+**Designs used as units.** A graph that has been worked out becomes a block, used many times and joined with others.
+
+```python
+review = Block(lambda: Loop(writer(), critic(), max_rounds=3), name="review")
+study = seq(clean, par(review, review, review), publish)       # in a row, side by side, nested
+graph = Chain(intake, study("study"), report).build(DEFAULT)
+```
+
+**Desks at the doors of a block.** A `Desk` takes in what arrives from several places, sorts it, and hands it out to several places. At the way into a block it shares the work among the members; at the way out it makes one answer of what they gave. Where the sorting needs judgement, an agent with the same inputs and outputs stands in the same place.
+
+```python
+team = Fan(analyst, modeller,                                   # each member gets its own part, by name
+           split=Desk("door", takes=["brief", "data"], gives=["analyst", "modeller"], sort=share),
+           join=Desk("exit", takes=["analyst", "modeller"], sort=report))
+```
+
+**Graphs that are not fixed in advance.** `Pool` keeps places for members that do nothing until they are called for. `SpawnNode` builds and runs a graph that a node wrote during the run, within limits set by whoever made the node.
+
+```python
+grow = SpawnNode("grow", Catalog(allow=["my_steps"]), max_nodes=20)
+graph = Chain(planner, grow).build(DEFAULT)                    # planner sends {"graph": ..., "inputs": ...}
+```
+
+**Runs that are looked after.**
+
+```python
+engine = Engine(graph, DEFAULT, workers=4,
+                journal=Journal("run.jsonl"),                  # an interrupted run is taken up with resume()
+                time_limit=600,                                # the longest one activation may take
+                budget={"tokens": 2_000_000},                  # nodes report what they use; over it, the run stops
+                observe=print)                                 # every event, as it happens
+```
+
+A node that must not do something twice outside the graph uses `ctx.key`, which stays the same when an interrupted activation runs again.
+
+**Graphs written as data.** A graph file holds the structure and whatever differs from the defaults; a prompt is a file that is referred to.
+
+```json
+{
+  "defaults": {"agent": {"model": "anthropic:some-model", "time_limit": 600}},
+  "method": "pool", "size": 10, "max_rounds": 3,
+  "root": {"id": "lead", "kind": "agent", "system": {"file": "prompts/lead.md"}, "firing": "any",
+           "inputs": ["task", {"name": "reply", "required": false}], "outputs": ["out", "send"]},
+  "member": {"kind": "agent", "system": {"file": "prompts/scout.md"}}
+}
+```
+
+```sh
+cd examples/data && export PYTHONPATH=.
+interlacing check  release.json --allow steps
+interlacing run    release.json --dir /tmp/run --allow steps --input topic=tides    # waiting for a person, exit code 3
+interlacing answer --dir /tmp/run --json '{"approved": true}'
+interlacing resume --dir /tmp/run                                                   # done, exit code 0
+```
+
+A run is a directory. A person in the graph who has not answered yet does not keep a process waiting: the command exits, and the run goes on once the answer has been given. One process at a time runs a directory.
+
+**As an MCP server.** The same operations can be offered to a model in another application. What its graphs may reach, how much they may use and how long a node may take are set on the command line by whoever starts the server, and the client cannot change them.
+
+```json
+{"mcpServers": {"interlacing": {"command": "interlacing",
+  "args": ["serve", "--runs", "/path/to/runs", "--allow", "mypkg", "--budget", "tokens=500000"]}}}
+```
+
+Model keys are read from the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and their `_BASE_URL`), and are never written to a graph file, a run directory or a journal.
+
+## What it is for
+
+Three worked cases are in [docs/CASES.md](https://github.com/Li2O0577/interlacing/blob/main/docs/CASES.md) (in Chinese). In short:
+
+| Case | How it is built |
+|---|---|
+| A physical agent: a multimodal model plans gripper poses as points in space, a controller executes, and the next observation decides what follows | `Loop(observe, planning, act)`; the model's measuring tools are nodes on call edges; the action contract is a check on the plan port, so a bad plan goes back to the model with the reason and never reaches the controller; plans and seconds are budgets. Runnable with stand-ins: [examples/graphs/planner_and_arm.py](https://github.com/Li2O0577/interlacing/blob/main/examples/graphs/planner_and_arm.py) |
+| A modelling assistant: a lead, one owner per question, a solver and a critic who argue until the answer is proved, a person who may step in anywhere | each question is a `Block` holding a `Loop(solve, critic)`; "no proof, not done" is a port check; questions run in `seq`; the person is the operator of a `Governed` tree; the run directory survives restarts |
+| A mathematician: a lead sends out explorers in parallel, each hands its work to a proof checker and reports back when it passes | `Pool(lead, explorer, size=10)` with `workers`; each explorer is a `Loop(prove, check)`; three directions given, three explorers exist |
+
+The kernel carries information and looks after the run. How a model thinks, how an arm moves and how a paper is typeset are the business of the nodes.
+
+## Layout
+
+| Layer | Package | Main names |
+|---|---|---|
+| Abstractions | `interlacing.base` | `Node`, `Port`, `Schema`, `Edge`, `Protocol`, `Envelope`, `Graph`, `GraphBuilder`, `Method`, `Context` |
+| Engine | `interlacing.engine` | `Engine`, `Result`, `RunError`, `Journal`, `Transport` |
+| Parts | `interlacing.nodes`, `.protocols`, `.methods`, `.models` | `FunctionNode`, `AgentNode`, `ProcessNode`, `SourceNode`, `SinkNode`, `HumanNode`, `GraphNode`, `Desk`; `Chain`, `Loop`, `Fan`, `Tree`, `Star`, `Governed`, `Pool` |
+| Blocks | `interlacing.blocks` | `Block`, `seq`, `par` |
+| Graphs as data | `interlacing.spec` | `dump`, `load`, `read`, `write`, `Catalog`, `SpawnNode` |
+| Outside | `interlacing.runs`, `interlacing.cli`, `interlacing.serve` | `Run`; the command `interlacing`; the MCP server |
+
+Each layer uses only the layers below it. The engine knows no particular node, protocol or method; a test in `tests/test_engine.py` holds it to that.
+
+The full description is [docs/GRAPH.md](https://github.com/Li2O0577/interlacing/blob/main/docs/GRAPH.md) (in Chinese). Nine examples that run as they stand are in [examples/graphs/](https://github.com/Li2O0577/interlacing/tree/main/examples/graphs), and graphs written as JSON in [examples/data/](https://github.com/Li2O0577/interlacing/tree/main/examples/data).
+
+## Tests
+
+```sh
+python -m pip install -e . pytest
+python -m pytest -q tests
+python scripts/bench_engine.py       # what the engine adds per envelope (about 11 microseconds)
+```
+
+The tests run on Linux, macOS and Windows, with scripted models and stand-in devices. They include runs broken at random places, with the journal cut short as a dying process leaves it, which must end as unbroken runs do. The package passes `mypy`.
+
+## Limits
+
+- Taking a run up again is at-least-once: an interrupted node runs again, and what it did outside the graph is done again unless the node uses `ctx.key` to prevent it.
+- Delivery is in-process only. `Transport` is the place for carrying envelopes between processes or machines, and nothing is there yet.
+- Both model interfaces have been tried once, with very small requests, against one compatible service. Thinking output, picture input and retries on rate limits have not been tried against a real service. Device nodes have only met stand-ins.
+- A node that overruns its time is abandoned, not killed: a thread cannot be stopped from outside. A program started by `ProcessNode` is killed.
+- `allow` is a list of modules whose functions a graph may name. It is not a sandbox.
+- The MCP server speaks over stdio only, handles one call at a time, and has not been tried with a real client.
+- There is no asynchronous interface; the engine uses threads.
+
+## License
+
+MIT

interlacing-0.11.0/README.zh-CN.md

@@ -0,0 +1,179 @@
+# interlacing
+
+[English](README.md) · **中文**
+
+把任何东西连成一张图，然后运行它。
+
+- **节点**是任何接收信息并给出信息的东西：模型、函数、外部程序、设备、人，或者另一张图。
+- **边**按一份写明的协议把信息从一个节点带到另一个节点：排队的值、只留最新值、状态、信号、流、有应答的调用、按路径传递的文件。
+- **方法**是把节点连起来的现成方式：链、环、分发再汇合、树、星形、需要人同意的树、成员在被叫到时才出现的池。
+
+引擎运行这张图并照看这次运行：输出要经过检查，用量按预算计数，每次激活都计时，所有事情写入日志，被打断的运行可以接着跑，观察者在事情发生的当时就被告知。这个包是一个内核，用来在它上面搭框架。它只依赖 Python 标准库。
+
+## 安装
+
+```sh
+pip install interlacing
+pip install -e .            # 或者从代码检出安装
+```
+
+需要 Python 3.11 或更高版本，支持 Linux、macOS 和 Windows。
+
+## 第一张图
+
+```python
+from interlacing import DEFAULT, Chain, Engine, FunctionNode, Port
+
+double = FunctionNode("double", lambda x: x * 2, inputs=[Port("x", int)], outputs=[Port("y", int)])
+show = FunctionNode("show", lambda x: f"={x}", inputs=[Port("x", int)], outputs=[Port("y", str)])
+
+graph = Chain(double, show).build(DEFAULT)
+print(Engine(graph, DEFAULT).run({"in": 21}).last("out"))     # =42
+```
+
+## 能做什么
+
+**带工具的模型。** 工具是一条通向普通节点的调用边，所以一本词典、一个程序和一条机械臂的应答方式完全一样。
+
+```python
+from interlacing import AgentNode, GraphBuilder, SinkNode, Tool
+
+agent = AgentNode("agent", model, system="...", tools=[Tool("lookup", "查一个词"), Tool("move", "移动机械臂")])
+graph = (GraphBuilder().add(agent, dictionary, SinkNode("arm", arm.move, answers=True))
+         .connect("agent.lookup", "dictionary.x", "call")
+         .connect("agent.move", "arm.x", "call")
+         .input("in", "agent.task").output("out", "agent.out").compile(DEFAULT))
+```
+
+`model` 是任何带有 `chat(system, messages, tools, max_tokens)` 的对象。`interlacing.models` 里有 Anthropic 接口、OpenAI 兼容接口，以及测试用的 `FakeProvider`。
+
+**经过检查的输出。** 端口写明什么可以从它出去，以及出去的是别的东西时怎么办：节点失败，或者带着警告继续走，或者告诉节点哪里不对并允许它重发。
+
+```python
+Port("plan", dict, check=valid_plan, repairs=2)      # 模型会被告知计划为什么被拒，最多两次
+```
+
+**按路径传递的文件。** 节点发送的是相对路径，不是内容。文件在发出时检查一次，到达时再检查一次。
+
+```python
+protocols = with_files(DEFAULT, "work")
+Port("chart", FileOf(".png", max_size=5_000_000), repairs=2)
+builder.connect("draw.chart", "report.chart", "file")
+```
+
+**把设计当作单元使用。** 一张已经想清楚的图成为一个块，可以多次使用，也可以和别的块拼接。
+
+```python
+review = Block(lambda: Loop(writer(), critic(), max_rounds=3), name="review")
+study = seq(clean, par(review, review, review), publish)       # 顺排、并排、嵌套
+graph = Chain(intake, study("study"), report).build(DEFAULT)
+```
+
+**块门口的收发台。** `Desk` 接收从多处到来的东西，整理之后分发到多处。放在块的入口，它把工作分给块内的成员；放在块的出口，它把成员给出的结果整合成一份答复。整理需要判断力时，换成一个输入输出相同的模型节点站在同一个位置。
+
+```python
+team = Fan(analyst, modeller,                                   # 每个成员按名字拿到自己的那一份
+           split=Desk("door", takes=["brief", "data"], gives=["analyst", "modeller"], sort=share),
+           join=Desk("exit", takes=["analyst", "modeller"], sort=report))
+```
+
+**不事先固定的图。** `Pool` 为成员留好位置，成员在被叫到之前什么也不做。`SpawnNode` 构建并运行一张由节点在运行中写出的图，范围由创建这个节点的人限定。
+
+```python
+grow = SpawnNode("grow", Catalog(allow=["my_steps"]), max_nodes=20)
+graph = Chain(planner, grow).build(DEFAULT)                    # planner 发出 {"graph": ..., "inputs": ...}
+```
+
+**被照看的运行。**
+
+```python
+engine = Engine(graph, DEFAULT, workers=4,
+                journal=Journal("run.jsonl"),                  # 被打断的运行用 resume() 接着跑
+                time_limit=600,                                # 一次激活最长可以用多久
+                budget={"tokens": 2_000_000},                  # 节点上报用量；超出则运行停止
+                observe=print)                                 # 每个事件，在发生的当时
+```
+
+不能在图外把同一件事做两遍的节点使用 `ctx.key`，被打断的激活重跑时它保持不变。
+
+**写成数据的图。** 图文件里只有结构和与默认值不同的部分；提示词是一个被引用的文件。
+
+```json
+{
+  "defaults": {"agent": {"model": "anthropic:some-model", "time_limit": 600}},
+  "method": "pool", "size": 10, "max_rounds": 3,
+  "root": {"id": "lead", "kind": "agent", "system": {"file": "prompts/lead.md"}, "firing": "any",
+           "inputs": ["task", {"name": "reply", "required": false}], "outputs": ["out", "send"]},
+  "member": {"kind": "agent", "system": {"file": "prompts/scout.md"}}
+}
+```
+
+```sh
+cd examples/data && export PYTHONPATH=.
+interlacing check  release.json --allow steps
+interlacing run    release.json --dir /tmp/run --allow steps --input topic=tides    # 在等人回答，退出码 3
+interlacing answer --dir /tmp/run --json '{"approved": true}'
+interlacing resume --dir /tmp/run                                                   # 完成，退出码 0
+```
+
+一次运行就是一个目录。图里的人还没有回答时，不会有进程一直等着：命令退出，等回答给出后运行再继续。同一个目录同一时间只由一个进程运行。
+
+**作为 MCP 服务。** 同样的操作可以提供给另一个应用里的模型。它的图能触及什么、能用多少、一个节点能跑多久，由启动服务的人在命令行上设定，客户端改不了。
+
+```json
+{"mcpServers": {"interlacing": {"command": "interlacing",
+  "args": ["serve", "--runs", "/path/to/runs", "--allow", "mypkg", "--budget", "tokens=500000"]}}}
+```
+
+模型密钥从环境变量读取（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 以及对应的 `_BASE_URL`），不会写入图文件、运行目录或日志。
+
+## 用来做什么
+
+三个展开讲的案例在 [docs/CASES.md](docs/CASES.md)。简要如下：
+
+| 案例 | 怎么搭 |
+|---|---|
+| 具身智能体：多模态模型把夹爪位姿规划成空间中的点，控制器执行，下一次观测决定接下来做什么 | `Loop(observe, planning, act)`；模型的测量工具是调用边上的节点；动作约定是计划端口上的检查，所以坏计划带着原因回到模型手里，到不了控制器；计划次数和秒数是预算。用替身可以直接运行：[examples/graphs/planner_and_arm.py](examples/graphs/planner_and_arm.py) |
+| 建模助手：一个组长，每个问题一个负责人，求解者和质疑者争论到答案被证明为止，人可以在任何地方介入 | 每个问题是一个装着 `Loop(solve, critic)` 的 `Block`；“没有证明就不算完成”是一个端口检查；问题用 `seq` 依次进行；人是 `Governed` 树的操作者；运行目录在重启后仍然有效 |
+| 数学家：组长并行派出探索者，每个探索者把成果交给证明检查器，通过后才汇报 | `Pool(lead, explorer, size=10)` 加 `workers`；每个探索者是一个 `Loop(prove, check)`；给出三个方向，就只存在三个探索者 |
+
+内核负责传递信息和照看运行。模型怎么想、机械臂怎么动、论文怎么排版，是节点自己的事。
+
+## 组成
+
+| 层 | 包 | 主要名字 |
+|---|---|---|
+| 抽象 | `interlacing.base` | `Node`、`Port`、`Schema`、`Edge`、`Protocol`、`Envelope`、`Graph`、`GraphBuilder`、`Method`、`Context` |
+| 引擎 | `interlacing.engine` | `Engine`、`Result`、`RunError`、`Journal`、`Transport` |
+| 部件 | `interlacing.nodes`、`.protocols`、`.methods`、`.models` | `FunctionNode`、`AgentNode`、`ProcessNode`、`SourceNode`、`SinkNode`、`HumanNode`、`GraphNode`、`Desk`；`Chain`、`Loop`、`Fan`、`Tree`、`Star`、`Governed`、`Pool` |
+| 块 | `interlacing.blocks` | `Block`、`seq`、`par` |
+| 写成数据的图 | `interlacing.spec` | `dump`、`load`、`read`、`write`、`Catalog`、`SpawnNode` |
+| 对外 | `interlacing.runs`、`interlacing.cli`、`interlacing.serve` | `Run`；命令 `interlacing`；MCP 服务 |
+
+每一层只使用它下面的层。引擎不认识任何具体的节点、协议或方法，`tests/test_engine.py` 里有一个测试守着这一点。
+
+完整说明见 [docs/GRAPH.md](docs/GRAPH.md)。九个可以直接运行的例子在 [examples/graphs/](examples/graphs/)，写成 JSON 的图在 [examples/data/](examples/data/)。
+
+## 测试
+
+```sh
+python -m pip install -e . pytest
+python -m pytest -q tests
+python scripts/bench_engine.py       # 引擎给每个信封增加的开销（约 11 微秒）
+```
+
+测试在 Linux、macOS 和 Windows 上运行，使用按脚本应答的模型和替身设备。其中包括在随机位置打断的运行，日志像进程突然死掉时那样被截断，这些运行必须和没被打断的运行得到同样的结局。这个包通过 `mypy` 检查。
+
+## 限制
+
+- 接着跑是“至少一次”：被打断的节点会重跑，它在图外做过的事会再做一遍，除非节点用 `ctx.key` 防止。
+- 投递只在进程内。`Transport` 是在进程或机器之间传递信封的位置，目前那里什么都没有。
+- 两种模型接口各用很小的请求在一个兼容服务上试过一次。思考输出、图片输入和限流重试还没有在真实服务上试过。设备节点只接触过替身。
+- 超时的节点是被放弃，而不是被杀掉：线程无法从外部停止。`ProcessNode` 启动的程序会被杀掉。
+- `allow` 是一份模块清单，图可以点名其中的函数。它不是沙箱。
+- MCP 服务只走 stdio，一次处理一个调用，还没有接过真实客户端。
+- 没有异步接口；引擎使用线程。
+
+## 许可
+
+MIT