graxella 0.1.1

Accountable change-control for agent behavior.

Your agents already work. Can you prove what they changed — and undo it if it was wrong?

The problem

Traditional software governs behavior change through a whole discipline: version control, review, CI gates, deploys, audit logs. Every change is proposed, approved, recorded, and reversible.

Agents have none of that — yet their behavior mutates continuously:

• A tool contract changes underneath them. The carrier renames order_id to tracking_ref. Your agent starts asking customers for a tracking number it was supposed to look up itself.
• They loop. Two agents hand the same task back and forth until something runs out — usually your budget.
• They "learn" invisibly. Something works once, gets reused forever, and nobody approved it or can point at why.
• There is no paper trail. "Why did it do that?" has no answer that survives the chat scrollback.

The usual fix is a smarter prompt or a retry. That is expensive at runtime, non-deterministic, and unauditable.

What graxella does

It sits underneath your agents — you keep writing plain LangChain or LangGraph — and turns behavior change into something with a process:

tool breaks  →  repaired once  →  cited proposal  →  you approve  →  permanent rule
                                                                          ↓
                                                    evidence turns bad → auto-demoted

One rule explains the whole design: the LLM may propose; the evidence decides. Routing, promotion, demotion, and every verdict are deterministic and recorded. A model appears in exactly one place — the drift healer's proposal step — and even there its output is validated against the real fallback before it is ever trusted twice.

The code you actually write

import graxella
from pydantic import BaseModel

grx = graxella.Session("support-desk", domain="support")

class TrackRequest(BaseModel):                 # the carrier's NEW schema
    tracking_ref: str                          # ...it used to be order_id

def carrier_v2(args: dict) -> str:
    req = TrackRequest(**args)                 # a real, validating client
    return f"parcel {req.tracking_ref}: out for delivery"

@grx.tool(fallback=carrier_v2)                 # <- the only graxella line
def track_shipment(order_id: str) -> str:
    """track a shipment's delivery status by order id"""
    return carrier_v2({"order_id": order_id})  # drifts: the old field name

That's it. @grx.tool returns a real LangChain BaseTool, so it drops into create_agent(llm, [track_shipment]) unchanged.

The first time the drift happens, graxella repairs it, caches the repair as a deterministic recipe, and files a cited proposal for you:

track_shipment.invoke({"order_id": "A-1042"})
# -> 'parcel A-1042: out for delivery'      the customer never saw a failure

grx.healer_calls          # 1  — repaired once, never again
grx.pending()             # 1  — nothing was promoted silently
print(grx.why(grx.pending()[0]))   # the cited reasoning behind the verdict

Approve it and it becomes a permanent rule. Later, if the evidence turns against that rule, grx.reconcile() demotes it on its own — no human, no LLM, just the posterior:

reconcile(): promoted=1  demoted=1
  demoted apr_581870be...: status=rolled_back
  reason='posterior 0.29 < 0.5 over 5 uses (1 ok / 4 failed)'

That last part — un-learning — is the piece most agent-memory systems don't have. Anything can accumulate rules. Removing one on evidence is what makes it change-control rather than a cache.

Install

pip install graxella            # everything above works
pip install "graxella[heal]"    # + the built-in drift healer (DSPy/Ollama)

One command, no extras needed. Extras are only for things you might genuinely not want: [heal] (a local model runtime for repairing ambiguous drift), [langgraph] (the graph runtime, for the mesh adapters and tutorials 08+), [embed] (local sentence-transformers), [otel], [mcp].

Nothing calls out to a hosted service — the healer runs against a local Ollama by default, and without one, drift fails loudly rather than faking a repair.

Measured, not asserted

Every number here comes from a script in this repo that you can run. The runs are on small local models (qwen2.5:7b, nomic-embed-text).

What these numbers are not: single-run results on one small domain, not a statistically powered benchmark. The CI scorecard exists so they fail loudly when they stop being true.

Learn it

tutorials/ is a graded path — 01–06 need no LLM at all:

Honest limits

This project's whole claim is accountability, so the limits are stated rather than buried:

• It does not make your model smarter, and it does not claim a lower hallucination rate. Tutorial 11 contains a live probe where the governed agent hallucinated exactly as badly as the ungoverned one, and the built-in claim-detector missed it on both sides. That result is kept in the notebook. What differs is that the governed side's tool trail makes the false claim checkable afterwards.
• Governance is detection-only. graxella flags reasoning/action mismatches and constitution violations; it does not silently block or rewrite your agent's output.
• 0.1.0, alpha. The API surface is small and tested, but it will move.
• The drift healer needs a local model (or your own @grx.healer). Without one, drift fails loudly — it never fakes a repair.

Where it sits

Not a competitor to your agent framework — a layer under it.

Guardrails and NeMo answer "is this one output acceptable?". graxella answers "what changed in my agent's behavior, who approved it, and can I undo it?" — a different question, and they compose fine.

Docs

• docs/FIRST_CUT_SCOPE.md — the problem, and what this first cut does and doesn't claim
• docs/HEALING.md — the heal ladder, drift taxonomy, recipe capabilities
• docs/specs/ — the binding Promotion and Disclosure specs
• CONTRIBUTING.md — setup, and the honesty contract for changes

License

Apache-2.0 — see LICENSE.