kigumi 0.1.0__tar.gz

kigumi-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+uv.lock
+dist/
+.pytest_cache/
+.ruff_cache/
+tmp/
+.omx/

kigumi-0.1.0/AGENTS.md

@@ -0,0 +1,30 @@
+# kigumi coding-agent 指南
+
+kigumi 是给 LLM 内容流水线提供确定性调用、可验证产物与 DAG 编排边界的 Python 库；
+修改时优先保护缓存、重放和人工审批的可观测性。
+
+常用命令：
+
+```bash
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+uv run kigumi trace <run_id>
+uv run kigumi call <key_prefix> --field response
+```
+
+`kigumi` CLI 负责项目运维（guard、runs、approve、diff、gc 等）；`dag.cli()` 负责已注册图的 check、plan、graph、explain、describe。
+
+硬规矩：
+
+- 改动任一缓存键成分就是缓存换族，必须同步更新 `CHANGELOG.md`。
+- `raw-llm-ok` 与 `raw-io-ok` 豁免都必须写清理由，二者不得互相代替。
+- 行为变更先写会失败的测试，再实现到测试转绿；不要以文档替代回归测试。
+- 不绕过 `canonical_json`、`artifacts.sha`、节点声明和审批 payload 绑定。
+
+文档地图：
+
+- [DESIGN.md](DESIGN.md) 说明设计哲学、边界和止损线。
+- [docs/adoption.md](docs/adoption.md) 说明接入方式与使用约定。
+- [docs/contracts/](docs/contracts/) 是可验证不变式的权威文本；修改实现时先读对应契约。
+- [CHANGELOG.md](CHANGELOG.md) 记录面向使用者的发布变化，不在此重复细节。

kigumi-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# 变更日志
+
+本项目遵循 Keep a Changelog 体例记录面向使用者的变更。
+
+## [未发布]
+
+### 变更
+
+- `kigumi` 键成分改为联合覆盖 `prompt.py` 与 `repair.py` 的 prompt 生成字节，并以
+  `CACHE_SCHEMA` 管理显式缓存语义版本；**本版本导致 L3 节点缓存全量失效（键成分
+  `kigumi` 换构）。**
+- 执行信封收敛至私有 `kigumi._execution`，并公开 `observe()` 以收集上下文内的
+  `LLMCaller` 调用；差分探针已验证键成分与 sidecar 字节不变。
+- 新增 `bench` / `Variant`：以唯一现状对照和显式假设约束结构切法探索，产出可归档的
+  变体×样例×种子评估报告、样例级 judgments 与调用成本；不包含胜负裁决或自动接线，
+  **不改变任何缓存键成分。**
+- 新增 coding-agent 可观测性 CLI：`kigumi trace` 从 run 直接联接节点/map 项、键成分、
+  LLM 调用与 L1 载荷；`kigumi call` 用 key 前缀读取完整输入输出；`kigumi diff` 增加
+  键成分差分与 `--json`。新增独立的 `llm_cache_dir` 配置，默认
+  `artifacts/_llm`；**不改变任何缓存键或 L1 载荷结构。**
+- `2174f73`：raw-I/O 守卫补齐注册、项目扫描和测试三环；run 目录改为数字感知排序；
+  并发失败保留其余失败附注。真实请求标记统一为 `live`，旧 `kigumi_live` 已移除，
+  运行 live 测试必须显式设置 `KIGUMI_LIVE=1`。
+- `4ac2b60`：四种 DAG 渲染迁入 `kigumi.views`，运行态渲染数据提取为共用边界，
+  缩小 `dag.py` 的职责面。
+- `db87336`：节点键成分收敛到 `Dag._key_components` 单点；run、plan、explain
+  分别注入已解析的上游结果，并以差分探针确认键字节不变。
+- `1e40b20`：`libs` 哈希改为剥离 docstring/注释后的 AST 归一化；语法残破文件退回
+  原文哈希。**这是 `libs` 成分的缓存换族，所有既有节点缓存必须视为失效。**
+
+### 移除
+
+- 移除四个兼容入口：`from kigumi.dag import approve_checkpoint` 等存储层转发、
+  `FakeTransport.calls`、点分顶层键解析，以及私有 `_next_run_id`。

kigumi-0.1.0/DESIGN.md

@@ -0,0 +1,285 @@
+# kigumi 设计文档
+
+木组(kigumi):无钉咬合的木工工艺。本库是 LLM 内容流水线的承重结构层——
+项目(屋顶)与模型(立柱)之间靠精确咬合连接,不合榫就打回重做。
+
+## 定位
+
+给"用 coding agent 开发 LLM 流水线"的场景提供地基:上下文注入、结构化校验与
+修复、确定性重放、DAG 编排,以及一套让规矩自动执行的工具链。
+
+主要用户是 coding agent:agent 的行为由环境反馈塑形,库必须把"正道"做成
+阻力最小的路径,把"歪路"做成走不通的路径。
+
+## 起源与实证依据
+
+抽取自三个实战项目的共同模式(comic-script-rewrite / drama2script /
+screen-writer),干净重写,不搬运代码。旧代码注释里的每条 live 教训
+(缓存不动点、回显截断不收敛、extra_forbidden 剥壳、键序漂移换缓存族等)
+转化为本库的 RED 测试用例,而非复制实现。
+
+已被否决的路线,不再重走:
+- 重基建编排(Temporal/server/DB):script-factory 实验已证死路。
+- 纯 vendored 模板:漂移成本实证过高(screen-writer 三个修复环变体)。
+- 采用现成 DAG 库:2026-07 调研结论,无一同时提供内容寻址缓存(含代码
+  哈希)+ 人工检查点 + 确定性重放;且 helper 哈希与 prompt 文件哈希
+  是自研 runtime 独有的领先点。
+
+## 包结构
+
+```
+kigumi/
+├── _execution.py   #     私有执行信封:缓存、审批、物化与 sidecar
+├── __init__.py     #     顶层公开 API
+├── artifacts.py    #     原子写入、规范 JSON 与 sidecar 基础件
+├── blobs.py        #     内容寻址二进制仓
+├── calling.py      # L1  调用:内容寻址缓存 / dry-run 熔断 / 溯源 / 预算记账
+├── cli.py          #     项目运维 CLI:kigumi
+├── config.py       #     项目配置、路径发现与环境装载
+├── dag.py          # L3  编排:@node / foreach / checkpoint / 节点缓存
+├── enforce.py      #     守卫检查器
+├── evals.py        #     评估与进化层的指标、评委与门禁
+├── optimize.py     #     评估与进化层的提示词候选演化
+├── prompt.py       # L1.5 拼接:inject / 严格渲染 / Section / schema 格式段 / clip
+├── repair.py       # L2  修复环:repair_loop + call_validated;rebuild/continue 双模式
+├── slots.py        #     跨进程限流与自适应容量
+├── store.py        #     存储布局:run、缓存、归档、物化、审批与 GC
+├── testing.py      #     pytest 插件(面向用户项目)
+└── transport.py    # L0  传输:complete(messages);LiteLLM 默认实现,stdlib 后备
+```
+
+依赖:pydantic 为内核依赖;litellm 为 optional extra(`kigumi[litellm]`,
+transport 已惰性导入,stdlib 后备保证无 extra 也可用)。L0–L2 不依赖 L3;
+命令式链项目只取底层。pytest11 入口在非 kigumi 项目中必须严格 no-op。
+
+## 项目配置约定(`[tool.kigumi]`)
+
+库装进 site-packages 后的发现问题统一由项目 pyproject 的 `[tool.kigumi]` 回答,
+全部有默认值,零配置可跑:
+
+```toml
+[tool.kigumi]
+prompts_dir = "prompts"          # 严格渲染与 dry-render 测试的模板根
+artifacts_dir = "artifacts"      # runs/ 与缓存的根(cache 在其下 _cache/)
+source_dirs = ["nodes", "lib"]   # helper 哈希与 guard 扫描的目录集(=同一集合)
+env_file = ".env"                # KIGUMI_MODEL_DEFAULT / KIGUMI_MODEL_PRO / api keys
+```
+
+`kigumi runs list` / `diff` / `gc` / guard / dry-render 全部从这份配置解析路径。
+各层不得自带另一套发现逻辑。
+
+## 各层要点
+
+### L0 transport
+- 唯一接口 `complete(messages, model, **params) -> Response`
+  (text / usage / finish_reason / reasoning / model),外加
+  `resolve(model) -> str`(别名 → 具体模型名,供 L1 构缓存键)。
+- 默认实现走 LiteLLM;纯标准库 OpenAI 兼容实现作后备。自愈策略共享,不复制。
+- **params 契约(归一化词汇表,冻结于 P1.1)**:`json_mode=True` →
+  `response_format={"type":"json_object"}`;`system="…"` → 前插 system 消息;
+  `reasoning_effort` 透传;其余透传。词汇表进缓存键语义,事后扩充只增不改。
+- 故障自愈(全部有界):429/5xx 指数退避、`finish_reason=length` 且调用方
+  显式设了 max_tokens → 加倍重试(至多 2 次);未设 max_tokens 的截断 →
+  抛 TruncatedResponseError(静默返回残文即下游投毒);空响应 → 退避重试,
+  耗尽即抛 EmptyResponseError,**绝不返回空文本**。
+- StdlibTransport 必须带默认超时(300s);所有重试路径都有退避 sleep。
+- 多档模型别名(default/pro)映射到不同模型/供应商,节点只说档位。
+
+### L1 calling
+- `LLMCaller(transport, cache_dir, seed, budget, dry)`,依赖注入,测试可替换。
+- 内容寻址缓存:键 = messages + **resolved model**(经 transport.resolve,
+  换 .env 模型 = 换缓存键,防跨模型回放旧答案)+ params + seed;
+  撕裂缓存按 miss;**空响应拒入缓存**(transport 违约时的第二道闸)。
+- 溯源 meta 同记 model_alias 与 resolved model;**先记 calls 再 budget.record**
+  (超限异常不得吞掉最贵那次调用的溯源)。
+- dry-run 熔断:到达真调用即抛错;缓存命中时不熔断继续走(特性,非 bug:
+  dry-run 的定义是"不发新请求",不是"不消费历史")。
+- 线程安全:Budget 加锁;calls 加锁;同键 in-flight 去重(并发同键只打一次)。
+- seed 仅是缓存命名空间,不传给 provider,不承诺采样可复现。
+- 大块内容按引用:消息体里的大负载(视频/图像 base64)以
+  `{"kigumi_file": 路径}` 内容件表示,缓存键取文件内容哈希,缓存 payload
+  存引用不存字节(接口 P1.1 预留,实现随 P6a)。
+- 跨进程限流(fcntl.flock 请求槽,多进程共享 provider 配额)归 P6a。
+- token 预算记账,超限中止 run。
+
+### L1.5 prompt(七能力)
+1. `inject(obj)`:材料注入唯一入口——强制 sort_keys、稳定缩进、统一围栏
+   与标题定界。保证同数据 → 逐字节同片段(bf06 键序漂移事故的结构性解)。
+   有序数据必须用 list;检测到数字串键的 dict 时告警(JSON round-trip 后
+   int 键变 str,sort_keys 按字典序 1,10,11,…,2 排乱剧集/场次)。
+2. 严格渲染:prompts/*.md + {{槽位}};缺槽/多槽都报错;模板保持声明式,
+   条件逻辑一律在 Python。
+3. `Section`:具名条件段,值为 None 整段(含标题定界)不渲染,
+   消灭"为 null 则跳过"式自然语言指令。
+4. schema → 格式说明段:从 pydantic model(含 Field description)自动生成
+   输出格式段与示例,prompt 与校验器单一真相源;"只输出 JSON 不解释"类
+   固定措辞收编为唯一常量。
+5. 裁剪:`clip(text, limit, boundary="line|sentence")` 安全边界截断;
+   领域摘要函数不进库(约定:返回 str 即可作槽值)。
+6. `render_items(items, format="json|bullets")`:列表渲染(table 无使用
+   实证,暂缓;有第二个项目要再加)。
+7. 修复段措辞常量(供 L2 引用,全库唯一一份)。
+
+贯穿不变式:同输入 → 逐字节同输出(缓存键与确定性重放压在此上)。
+公共 prompt 成分(措辞常量、schema 格式段模板、inject 围栏)以 golden
+snapshot 测试锁字节;任何改动 = 全项目缓存换族,CHANGELOG 必须标注
+"本版本导致缓存失效"。
+
+截断三铁律:
+1. 库永不默认截断;上限必须显式写在调用方。
+2. 截断永不无声:prompt 内自动标注"(已截断:原文 N 字,注入前 M 字)",
+   事件记入 sidecar `clips: [{slot, from, to}]`。
+3. 修复环默认不截:continue 模式输出天然在对话历史;rebuild 模式
+   echo 默认不限。
+
+### L2 repair
+- `repair_loop(caller, messages, validate, *, reminder=None,
+  mode="rebuild"|"continue", max_repairs=2, sink=None, on_event=None, **params)`。
+- **默认 rebuild**(三个源项目实证过的形态);continue(输出作 assistant
+  消息接回对话再追加纠正指令,免回显、前缀缓存友好)标记为实验特性,
+  经磁带机 + L3 统计对比跑赢后再转正——库 API 决策同样吃 RED/GREEN 纪律。
+  已知风险:失败历史锚定坏输出;部分 OpenAI 兼容代理对
+  assistant 消息 + response_format 组合不可靠。
+- validate(raw) 抛 ValueError 即触发修复,返回值即结果——pydantic 解析、
+  文本解析+门禁、组装+linter 全部套此签名。
+- 固化学费:轮次编号进 prompt(防缓存不动点)、原样重交检测(stuck)、
+  失败现场落盘(经显式 sink 参数,L2 不依赖 L3 的目录结构)、修复事件记录。
+- `call_validated(caller, prompt, model_cls, extra_check=None, ...)`:
+  JSON+pydantic 特化 = repair_loop + 确定性剥壳(extra_forbidden 机械删键、
+  strict=False 控制字符容错)。
+
+### 评估与进化(evals / optimize)
+- `evals.py` 与 `optimize.py` 是库内的评估与进化层，不是独立产品；它们骑在
+  L1 caller 之上，评委调用天然复用 L1 缓存。
+- optimize 的 `(候选, 样例)` 判分状态文件只服务断点续跑，不绕过 L1；胜出文本
+  不自动落盘，须经人工审阅后才进入 `prompts/`。
+- `bench.py` 为同一流水线的结构切法生产变体×样例×种子的可归档证据，不裁决胜负，
+  不自动接线；每个变体独立持有 caller，固定种子仍可复用 L1。
+
+### L3 dag
+- 自研 runtime 为底座(screen-writer 771 行思路,干净重写),吸收:
+  - redun `File`:外部文件声明为输入、内容进缓存键(prompts_hash 的推广);
+  - Hamilton code_version:源码哈希忽略 docstring/注释;
+  - LangGraph interrupt():检查点恢复语义(批准数据注回节点);
+  - Metaflow foreach:一等公民动态 fan-out 原语(替代 f-string 拼节点名
+    +循环闭包注册;episode_chain 的既知压力点)。
+- 缓存键 = 节点源码哈希 + helper/库哈希(source_dirs)+ 上游产物哈希
+  + prompt 文件哈希 + 参数 + **kigumi prompt 相关模块哈希 + pydantic 版本**
+  (库现在拥有 prompt 字节的生成权:inject 围栏/格式段/措辞常量变了,
+  节点键必须失效,否则升级库后回放陈旧渲染的产物)。
+- 文件物化是一等能力:artifact 带 `files: {相对路径: 内容}` 时落盘到
+  项目目录,缓存命中也执行(subprocess 门禁靠磁盘文件工作;
+  screen-writer _materialize 的收编硬依赖)。另留 post-node hook。
+- 检查点与 artifact 键的绑定声明式化(旧代码为硬编码)。
+- 链式上文显式化为节点输入(禁止节点闭包携带跨迭代可变状态)。
+- 新增:`diff <runA> <runB>`、缓存 GC(--keep-last N)、历史归档、
+  人工检查点、token 预算。
+- **止损线**:若第二个接入项目对 dag 提出 _materialize 级别的特化且
+  post-node hook 接不住,dag 退回 vendored 模板,库只保 L0–L2。
+  此线现在写下,将来才有勇气执行。
+
+### 存储与容量
+- `store.py` 是存储布局层，依赖方向固定为 `dag -> store`；它管理 run、节点缓存、
+  归档、物化、审批与 GC，不能反向理解图或调度。
+- `blobs.py` 是内容寻址二进制仓；`slots.py` 负责跨进程限流与自适应容量。
+
+### enforce(守卫三环)
+1. 注册环:@node 注册时 AST 检查节点函数体，是精确且权威的边界；循环内裸调
+   `.call(`/`.llm(` 或节点体直接 raw-io，且无对应理由豁免 → 拒绝注册。
+   **边界诚实声明**:运行环只覆盖 dag 项目;命令式项目(如 drama2script)
+   主责在测试环与提交环。
+2. 测试环:pytest 插件自动收集守卫检查 + 全模板 dry-render 测试;
+   **新增豁免注释即告警**(waiver 是 agent 的自助逃生通道,必须留痕上报)。
+3. 提交环:`kigumi init` 安装 git hook(core.hooksPath=.githooks,
+   pre-commit 跑 `uv run kigumi guard --changed`);guard 输出含 waiver 清单。
+
+source_dirs 级扫描只属于 dag check、测试环与提交环。raw-io 在这些环节用
+`@*.node/map/scan/foreach(...)` 装饰器作启发式过滤，只扫匹配函数的最外层函数体：
+这避免 helper 合法读文件的误报，但可能漏报；注册环仍是兜底。
+
+### testing(pytest 插件,面向用户项目)
+- 磁带机夹具:FakeTransport 录制/回放——真实模型的畸形输出(幻觉多余键、
+  控制字符、原样重交)打真实修复环代码,消灭 fixture 喂养测试的结构性盲区。
+- dry-render 全覆盖:prompts_dir 下每模板自动生成槽位可填满测试。
+- L3 活体采样:@pytest.mark.live + 预算夹具(超限 skip 不烧钱)。
+- `live` 是唯一的真实请求标记：插件激活时还要求 `KIGUMI_LIVE=1`，再与
+  `skip_unless_env` 的凭证门叠加，形成显式双确认。
+- 守卫即测试(三环之二)。
+
+### 格式化/质量
+复用 ruff(lint+format),脚手架交付 [tool.ruff] 预设;不自造工具。
+
+### 契约层
+可验证不变式的权威文本在 [docs/contracts/](docs/contracts/)；这里保留设计哲学、模块边界与
+止损线，不复制可由测试锁定的实现细节。改动缓存键、确定性字节、守卫、检查点或保留语义时，
+必须先更新对应契约和锁定测试，再记录发布影响。
+
+### CLI
+```
+kigumi init          # 脚手架:prompts/ nodes/ tests/ + hooks + ruff/pytest 预设
+kigumi guard [--changed]
+kigumi doctor        # API key / 缓存目录 / hooks 体检
+kigumi runs list / show <id>
+kigumi diff <runA> <runB>
+kigumi gc [--keep-last N]
+kigumi render <node> --dry
+```
+`kigumi`(cli.py) 是不需要图注册表的项目运维入口：init、guard、doctor、render、runs、
+approve、diff、gc。`dag.cli()` 是需要注册表的图检查入口：check、plan、graph、explain、
+describe；两者不互相代替。
+`kigumi init` 是 developing-ai-workflows skill 的落地点:新项目起步从
+"复制模板"改为"跑 init"。
+
+## 构建顺序
+
+1. 仓库 + L0/L1 + artifacts ✅(commit b42bc1b)
+   1.1 评审修正包:空响应耗尽即抛+拒缓存、resolved model 进缓存键、
+       params 契约、Stdlib 超时、溯源先于记账、线程安全+in-flight 去重、
+       litellm 降 extra、File 引用接口预留
+2. prompt.py 七能力 + 截断三铁律 + golden snapshot(先于 repair:
+   修复段措辞常量住在这里)
+3. repair.py 双模式(默认 rebuild),验收关 = 在 worktree 里真实移植
+   screen-writer 最难的一个循环(lint_fix,含跨轮事件累积与按错误类型
+   定制指令),纸面对齐不算过关
+4. enforce.py(纯函数形态 AST 检查器)+ testing.py(磁带机/dry-render);
+   与 @node 的接线留给 P5,规格写明防止造假注册表
+5. dag.py(foreach/diff/gc/物化/检查点绑定)+ cli.py + 运行环接线
+6. 前置 6a:跨进程限流 + File 引用实现 + 并发路径验证;然后 drama2script
+   试点、screen-writer 收编、skill 更新(不只加红旗判例——skill
+   "frameworks are banned" 不变量须重写为"物理层用库,编排逻辑必须
+   一屏可读",否则遵循 skill 的 agent 会系统性抵触本库)
+
+每步配套:旧项目 live 教训 → 本库 RED 用例,先红后绿。
+每包审查新增机械动作:对照旧实现(llm_client.py / runtime.py /
+progressive_annotation_pipeline.py)的 docstring 与注释提取能力清单逐条
+勾兑——P1 曾带着 4 处对旧实现的退化过审,教训在此。
+
+## 修订记录
+
+- 2026-07-13 新增 segment bench：以假设和唯一现状对照约束结构探索，生成稳定的
+  变体×样例×种子证据报告与按变体归集的调用成本；裁决和接线始终留在库外。
+
+- 2026-07-13 新增 agent 可观测层：`inspect.py` 只读联接 run sidecar 与 L1 载荷，
+  不导入 DAG、不发请求、不触碰缓存键成分；CLI 因而可完整追溯节点、map 项和调用证据。
+
+- 2026-07-13 新增契约层：缓存键、确定性字节、守卫环与豁免、检查点审批、缓存与产物保留
+  的可验证不变式统一收敛至 `docs/contracts/`；本设计文档只保留边界、哲学和止损线。
+
+- 2026-07-13 libs 哈希对齐 code_version 原则：source_dirs 模块统一剥
+  docstring/注释后按 AST 哈希，语法残破文件退回原文；此变更让 libs 成分
+  全体换族，既有节点缓存一次性失效（greenfield 内无外部用户，直接执行）。
+
+- 2026-07-13 第一轮整改：包结构补齐为实际 16 个模块；明确 evals/optimize、
+  store/blobs/slots 的边界；守卫三环如实区分注册环与 source_dirs 启发式 raw-io
+  扫描；记录双 CLI 分工与 `live` 标记统一为双确认门。
+
+- 2026-07-10 独立评审(18 条)采纳合并:上述 params 契约、resolved model
+  进键、空响应双闸、[tool.kigumi] 约定、node key 含库版本、物化一等能力、
+  守卫边界诚实化、continue 降实验特性、dag 止损线、litellm 降 extra 等。
+  驳回/缓办:table 渲染与 clip 滑窗(无使用实证,砍);多模态 File 引用
+  实现与跨进程限流(归 6a,接口先行)。
+
+## 命名记录
+
+2026-07-10 定名 kigumi(木组)。曾用工作名 scriptkit(否决:不应剧本化)、
+sunmao(PyPI 已占)。候选 dougong/rabbet/treenail 均可用,最终选 kigumi。

kigumi-0.1.0/LICENSE

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

kigumi-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: kigumi
+Version: 0.1.0
+Summary: Load-bearing joinery for LLM content pipelines: context injection, validated repair loops, deterministic replay, DAG orchestration.
+Project-URL: Repository, https://github.com/Oxidane-bot/kigumi
+Project-URL: Changelog, https://github.com/Oxidane-bot/kigumi/blob/master/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: content-addressed-cache,dag,deterministic-replay,llm,llm-pipelines
+Classifier: Development Status :: 4 - Beta
+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: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.60; extra == 'litellm'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Oxidane-bot/kigumi/master/docs/assets/kigumi-logo.png">
+    <img src="https://raw.githubusercontent.com/Oxidane-bot/kigumi/master/docs/assets/kigumi-logo-light.png" alt="kigumi logo" width="220">
+  </picture>
+</p>
+
+# kigumi (木組)
+
+English | [中文](https://github.com/Oxidane-bot/kigumi/blob/master/README.zh-CN.md)
+
+Nail-free interlocking joinery. The load-bearing structural layer for LLM
+content pipelines — connecting your project (the roof) to the model (the
+pillars) through precise joints: output that does not fit the mortise gets
+sent back for rework.
+
+A foundation for building LLM pipelines with coding agents:
+
+- **Injection and assembly**: a single entry point for material injection,
+  strict template rendering, format sections auto-generated from schemas
+- **Repair loop**: failed validation turns into corrective instructions,
+  model context is preserved, retries are bounded, lessons are locked in
+- **Deterministic replay**: content-addressed caching — same input,
+  byte-identical output
+- **DAG orchestration** (optional): per-node caching, dynamic fan-out,
+  human checkpoints, run diffs
+- **Three guard rings**: runtime refusal / pytest auto-collection /
+  git hooks, so the rules enforce themselves
+
+## Quick start
+
+```python
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from kigumi import LiteLLMTransport, LLMCaller, call_validated
+
+
+class Verdict(BaseModel):
+    score: int
+    reason: str
+
+
+transport = LiteLLMTransport(aliases={"default": "anthropic/claude-sonnet-5"})
+caller = LLMCaller(transport, cache_dir=Path("artifacts/_llm"), seed=20260713)
+
+verdict = call_validated(caller, "Score this opening scene and explain why: ...", Verdict)
+```
+
+`call_validated` automatically appends a format section generated from
+`Verdict`; a response that does not fit is sent back with the validation
+errors for a bounded number of retries (2 by default). The whole exchange
+lands in a content-addressed cache, so the same input replays byte-for-byte
+with no further API cost.
+
+## Status
+
+0.1.0, API not frozen. All four core layers are in place, with 278 tests,
+refined through three clean-room pilots (structured extraction /
+multimodal / DAG orchestration). Not yet published to PyPI.
+
+## Install
+
+Until the PyPI release, install from Git:
+
+```bash
+uv add "kigumi[litellm] @ git+https://github.com/Oxidane-bot/kigumi"
+```
+
+After release: `uv add "kigumi[litellm]"`. Without the litellm extra you
+can use `StdlibTransport` (pure-stdlib HTTP) or implement your own
+transport.
+
+## Documentation map
+
+Documentation is currently written in Chinese.
+
+| Document | The question it answers |
+| --- | --- |
+| [DESIGN.md](https://github.com/Oxidane-bot/kigumi/blob/master/DESIGN.md) | Why it is designed this way; layers, boundaries, settled trade-offs |
+| [docs/adoption.md](https://github.com/Oxidane-bot/kigumi/blob/master/docs/adoption.md) | How to adopt it; the path from a single caller to a DAG, plus troubleshooting |
+| [docs/contracts/](https://github.com/Oxidane-bot/kigumi/blob/master/docs/contracts/) | Which behaviors are promises; invariants, failure behavior, verification coordinates |
+| [docs/reviews/](https://github.com/Oxidane-bot/kigumi/blob/master/docs/reviews/) | What a review found at a point in time; descriptive records, not specs |
+| [CHANGELOG.md](https://github.com/Oxidane-bot/kigumi/blob/master/CHANGELOG.md) | What changed; cache-family rotations and breaking changes are always recorded |
+| [AGENTS.md](https://github.com/Oxidane-bot/kigumi/blob/master/AGENTS.md) | What an agent reads before entering; red lines and verification commands |
+
+## License
+
+[MIT](https://github.com/Oxidane-bot/kigumi/blob/master/LICENSE)

kigumi-0.1.0/README.md

@@ -0,0 +1,90 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Oxidane-bot/kigumi/master/docs/assets/kigumi-logo.png">
+    <img src="https://raw.githubusercontent.com/Oxidane-bot/kigumi/master/docs/assets/kigumi-logo-light.png" alt="kigumi logo" width="220">
+  </picture>
+</p>
+
+# kigumi (木組)
+
+English | [中文](https://github.com/Oxidane-bot/kigumi/blob/master/README.zh-CN.md)
+
+Nail-free interlocking joinery. The load-bearing structural layer for LLM
+content pipelines — connecting your project (the roof) to the model (the
+pillars) through precise joints: output that does not fit the mortise gets
+sent back for rework.
+
+A foundation for building LLM pipelines with coding agents:
+
+- **Injection and assembly**: a single entry point for material injection,
+  strict template rendering, format sections auto-generated from schemas
+- **Repair loop**: failed validation turns into corrective instructions,
+  model context is preserved, retries are bounded, lessons are locked in
+- **Deterministic replay**: content-addressed caching — same input,
+  byte-identical output
+- **DAG orchestration** (optional): per-node caching, dynamic fan-out,
+  human checkpoints, run diffs
+- **Three guard rings**: runtime refusal / pytest auto-collection /
+  git hooks, so the rules enforce themselves
+
+## Quick start
+
+```python
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from kigumi import LiteLLMTransport, LLMCaller, call_validated
+
+
+class Verdict(BaseModel):
+    score: int
+    reason: str
+
+
+transport = LiteLLMTransport(aliases={"default": "anthropic/claude-sonnet-5"})
+caller = LLMCaller(transport, cache_dir=Path("artifacts/_llm"), seed=20260713)
+
+verdict = call_validated(caller, "Score this opening scene and explain why: ...", Verdict)
+```
+
+`call_validated` automatically appends a format section generated from
+`Verdict`; a response that does not fit is sent back with the validation
+errors for a bounded number of retries (2 by default). The whole exchange
+lands in a content-addressed cache, so the same input replays byte-for-byte
+with no further API cost.
+
+## Status
+
+0.1.0, API not frozen. All four core layers are in place, with 278 tests,
+refined through three clean-room pilots (structured extraction /
+multimodal / DAG orchestration). Not yet published to PyPI.
+
+## Install
+
+Until the PyPI release, install from Git:
+
+```bash
+uv add "kigumi[litellm] @ git+https://github.com/Oxidane-bot/kigumi"
+```
+
+After release: `uv add "kigumi[litellm]"`. Without the litellm extra you
+can use `StdlibTransport` (pure-stdlib HTTP) or implement your own
+transport.
+
+## Documentation map
+
+Documentation is currently written in Chinese.
+
+| Document | The question it answers |
+| --- | --- |
+| [DESIGN.md](https://github.com/Oxidane-bot/kigumi/blob/master/DESIGN.md) | Why it is designed this way; layers, boundaries, settled trade-offs |
+| [docs/adoption.md](https://github.com/Oxidane-bot/kigumi/blob/master/docs/adoption.md) | How to adopt it; the path from a single caller to a DAG, plus troubleshooting |
+| [docs/contracts/](https://github.com/Oxidane-bot/kigumi/blob/master/docs/contracts/) | Which behaviors are promises; invariants, failure behavior, verification coordinates |
+| [docs/reviews/](https://github.com/Oxidane-bot/kigumi/blob/master/docs/reviews/) | What a review found at a point in time; descriptive records, not specs |
+| [CHANGELOG.md](https://github.com/Oxidane-bot/kigumi/blob/master/CHANGELOG.md) | What changed; cache-family rotations and breaking changes are always recorded |
+| [AGENTS.md](https://github.com/Oxidane-bot/kigumi/blob/master/AGENTS.md) | What an agent reads before entering; red lines and verification commands |
+
+## License
+
+[MIT](https://github.com/Oxidane-bot/kigumi/blob/master/LICENSE)

kigumi-0.1.0/README.zh-CN.md

@@ -0,0 +1,77 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/kigumi-logo.png">
+    <img src="docs/assets/kigumi-logo-light.png" alt="kigumi logo" width="220">
+  </picture>
+</p>
+
+# kigumi(木組)
+
+[English](README.md) | 中文
+
+无钉咬合的木工工艺。LLM 内容流水线的承重结构层——项目(屋顶)与模型(立柱)
+之间靠精确咬合连接,不合榫就打回重做。
+
+给"用 coding agent 开发 LLM 流水线"提供地基:
+
+- **注入与拼接**:材料注入唯一入口,严格模板渲染,schema 自动生成格式说明段
+- **修复环**:校验不达标 → 纠正指令打回,保留模型上文,有界重试,学费固化
+- **确定性重放**:内容寻址缓存,同输入逐字节同输出
+- **DAG 编排**(可选):节点级缓存、动态 fan-out、人工检查点、run diff
+- **守卫三环**:运行时拒载 / pytest 自动收集 / git hook,让规矩自动执行
+
+## 快速上手
+
+```python
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from kigumi import LiteLLMTransport, LLMCaller, call_validated
+
+
+class Verdict(BaseModel):
+    score: int
+    reason: str
+
+
+transport = LiteLLMTransport(aliases={"default": "anthropic/claude-sonnet-5"})
+caller = LLMCaller(transport, cache_dir=Path("artifacts/_llm"), seed=20260713)
+
+verdict = call_validated(caller, "给这段开场白打分并给出理由:……", Verdict)
+```
+
+`call_validated` 自动附上由 `Verdict` 生成的格式说明段;返回若不合榫,
+带着校验错误打回重试(默认至多 2 次)。整次交互内容寻址落缓存,
+同输入重跑逐字节复现,不再计费。
+
+## 状态
+
+0.1.0,API 未冻结。核心四层齐备,278 项测试,经三个 clean-room
+试点(结构化抽取 / 多模态 / DAG 编排)回写打磨。尚未发布到 PyPI。
+
+## 安装
+
+发布到 PyPI 前,从 Git 安装:
+
+```bash
+uv add "kigumi[litellm] @ git+https://github.com/Oxidane-bot/kigumi"
+```
+
+发布后:`uv add "kigumi[litellm]"`。不装 litellm extra 时可用
+`StdlibTransport`(纯标准库 HTTP)或自实现 transport。
+
+## 文档地图
+
+| 文档 | 回答的问题 |
+| --- | --- |
+| [DESIGN.md](DESIGN.md) | 为什么这样设计;分层、边界与已裁决的取舍 |
+| [docs/adoption.md](docs/adoption.md) | 怎么接入;从单 caller 到 DAG 的路径与排障 |
+| [docs/contracts/](docs/contracts/) | 哪些行为是承诺;不变式、失效行为与验证坐标 |
+| [docs/reviews/](docs/reviews/) | 某个时点审查出了什么;实然记录,不是规范 |
+| [CHANGELOG.md](CHANGELOG.md) | 什么变了;缓存换族与破坏性变更必录 |
+| [AGENTS.md](AGENTS.md) | agent 进场先读什么;红线与验证命令 |
+
+## 许可证
+
+[MIT](LICENSE)