kigumi 0.1.0

Load-bearing joinery for LLM content pipelines: context injection, validated repair loops, deterministic replay, DAG orchestration.

kigumi (木組)

English | 中文

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

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:

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	Why it is designed this way; layers, boundaries, settled trade-offs
docs/adoption.md	How to adopt it; the path from a single caller to a DAG, plus troubleshooting
docs/contracts/	Which behaviors are promises; invariants, failure behavior, verification coordinates
docs/reviews/	What a review found at a point in time; descriptive records, not specs
CHANGELOG.md	What changed; cache-family rotations and breaking changes are always recorded
AGENTS.md	What an agent reads before entering; red lines and verification commands

License

MIT