Metadata-Version: 2.4
Name: eisfi-weaver
Version: 0.1.1
Summary: An integrity and provenance layer for agentic AI toolchains: append-only content-addressed transition chains with void semantics.
Author: Aaron Brown
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Eru-Iluvatar-the-One/weaver
Project-URL: Repository, https://github.com/Eru-Iluvatar-the-One/weaver
Project-URL: Issues, https://github.com/Eru-Iluvatar-the-One/weaver/issues
Project-URL: Documentation, https://github.com/Eru-Iluvatar-the-One/weaver/tree/main/docs
Keywords: agents,integrity,provenance,blake3,langchain,ai-safety,auditability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: blake3
Requires-Dist: blake3>=0.4; extra == "blake3"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: blake3>=0.4; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# Weaver

**An integrity and provenance layer for agentic AI toolchains.**

Weaver hashes every agent state transition into an append-only, content-addressed chain, **voids** transitions that fail an integrity precondition (a failed transition writes *no state*, rather than writing state a checker later has to catch), and makes what an AI agent actually did auditable after the fact — cryptographically, not from application logs.

Alongside the middleware, this repository carries two things the field currently lacks:

- **An open corpus of real, dated agentic failure specimens** — not synthetic benchmarks. Every specimen in [`corpus/`](https://github.com/Eru-Iluvatar-the-One/weaver/tree/main/corpus) was captured live on a production multi-agent estate that has run continuously for 24 months, instrumented *before* the failures arrived. See the [corpus README](https://github.com/Eru-Iluvatar-the-One/weaver/blob/main/corpus/README.md) for the provenance statement.
- **A five-class taxonomy of silent failure** in agentic systems — the conceptual scaffolding the detectors are built against. See [`docs/TAXONOMY.md`](https://github.com/Eru-Iluvatar-the-One/weaver/blob/main/docs/TAXONOMY.md).

## The problem, in one paragraph

Agentic frameworks — LangChain, AutoGen, the OpenAI SDK — have become base infrastructure, and none of them ships an integrity layer. The failure class that matters most is the one that doesn't surface: a reference still resolves, an identifier stays stable, a wire format still parses, **and the meaning underneath has silently changed**. No exception. No log line. Downstream artifacts embed the mutation as truth, and by the time anyone needs to reconstruct what the agent actually did, the causal chain has been overwritten. Contract tests pass (the output matches the schema). Adversarial evals pass (the output matches no known attack). The system is wrong anyway. We call this class **Homomorphic Drift**, and standard evaluation misses it *by construction*, because standard evaluation inspects surfaces.

## What exists today (v0, honest status)

| Component | Status |
|---|---|
| Content-addressed transition chain with void semantics ([`src/eisfi_weaver/chain.py`](https://github.com/Eru-Iluvatar-the-One/weaver/blob/main/src/eisfi_weaver/chain.py)) | **Working code, tested** |
| Deterministic canonical serialization ([`src/eisfi_weaver/canonical.py`](https://github.com/Eru-Iluvatar-the-One/weaver/blob/main/src/eisfi_weaver/canonical.py)) | **Working code, tested** |
| LangChain `BaseCallbackHandler` adapter ([`src/eisfi_weaver/adapters/langchain_handler.py`](https://github.com/Eru-Iluvatar-the-One/weaver/blob/main/src/eisfi_weaver/adapters/langchain_handler.py)) | Working, minimal — hooks `on_llm_start`, `on_tool_start`, `on_agent_action` |
| Failure-specimen corpus ([`corpus/`](https://github.com/Eru-Iluvatar-the-One/weaver/tree/main/corpus)) | 5 published; **10 confirmed** by census 2026-08-13 (an earlier unbacked claim of ~50 is corrected in the [corpus README](https://github.com/Eru-Iluvatar-the-One/weaver/blob/main/corpus/README.md)), publication ongoing |
| Taxonomy specification ([`docs/TAXONOMY.md`](https://github.com/Eru-Iluvatar-the-One/weaver/blob/main/docs/TAXONOMY.md)) | Complete v1 |
| AutoGen adapter, OpenAI-SDK proxy, benchmark harness | Roadmap (see below) |

This is a young public repository wrapping an old private practice. The foundations of this architecture were laid in late 2024, and a five-node, multi-agent research estate has run on them continuously since as its operating substrate; the working record behind every claim here is preserved in GPG-signed, dated commits and is available to funders and auditors on request. Three US provisional patent filings (April 7, May 20, and August 14, 2026 — the third a consolidated instrument prepared with counsel) anchor the architecture's priority **for open release, not commercial exclusion** — this repository is Apache-2.0 and will remain so.

## Quick start

```bash
pip install eisfi-weaver
python -c "
from eisfi_weaver.chain import TransitionChain
chain = TransitionChain()
entry = chain.append({'actor': 'agent-1', 'action': 'tool_call', 'tool': 'search', 'input': 'hello'})
print('appended:', entry['entry_hash'][:16])
print('chain verifies:', chain.verify())
"
```

Void semantics in one example:

```python
from eisfi_weaver.chain import TransitionChain, VoidedTransition

chain = TransitionChain()

def content_matches_store(payload):
    # your precondition: e.g. compare document hash against the document store's own hash
    return payload.get("doc_hash") == payload.get("store_hash")

result = chain.append(
    {"action": "read_document", "doc_hash": "abc", "store_hash": "DIFFERENT"},
    precondition=content_matches_store,
)
assert isinstance(result, VoidedTransition)   # the transition FAILED...
assert len(chain) == 0                        # ...and wrote NOTHING. No state to route around.
```

That last line is the design thesis of the whole project: **enforcement surfaces get routed around by optimizing systems; a precondition that voids the transition leaves nothing to route around.** Structural prevention, not behavioral control.

## Using the LangChain adapter

```python
from eisfi_weaver.adapters.langchain_handler import WeaverCallbackHandler

handler = WeaverCallbackHandler(chain_path="./weaver-chain.jsonl")
# pass `callbacks=[handler]` to your LangChain runnable / agent executor
```

Every LLM start, tool start, and agent action is canonically serialized, hashed, and appended. Tamper with any historical entry and `chain.verify()` fails at exactly that link.

## Roadmap

1. **Hardening + release engineering** — packaging, CI across Python/LangChain versions, threat-model doc stating plainly what this layer does and does not guarantee.
2. **Independent security audit** of the chain implementation — an integrity layer whose own trust anchor is unaudited is a contradiction; findings will be published here.
3. **AutoGen middleware hooks and an OpenAI-SDK transparent proxy**, with a shared conformance suite so all three integrations enforce identical semantics.
4. **Benchmark harness** — detection rate under adversarial input, false-positive rate on legitimate traffic, instrumentation overhead vs. baseline — public and reproducible.
5. **Corpus scale-up** to ~200 specimens with a verification-gated public contribution mechanism.
6. **Formal specification** of the integrity model (chain format, canonicalization, void semantics, precondition interface) so that implementations other than this one can exist.

## Author

Aaron Brown ([@Eru-Iluvatar-the-One](https://github.com/Eru-Iluvatar-the-One)) — independent researcher, Denver, Colorado.
Research umbrella: [thesecretfire.net](https://thesecretfire.net)

*Weaver is a codename, and it is load-bearing: a weaver records the whole history into the tapestry without altering a single thread. That is this project's remediation posture in one image — when you enter a system that never had an integrity layer, you do not rewrite its past; you reconstruct the true weave from the threads that survive, nondestructively, and anchor everything forward from there. The project's formal title in grant and patent filings is "Integrity and provenance middleware for agentic AI toolchains."*

## License

[Apache-2.0](https://github.com/Eru-Iluvatar-the-One/weaver/blob/main/LICENSE). Documentation CC-BY-4.0. Corpus specimens released under CC-BY-4.0 with provenance metadata intact.
