precedent-ai 0.2.2

Website · Quick start · How it works · Integrations · Live results · Safety · Design · Demo guide

Your AI agent doesn't know how your business makes decisions. When to refund. Who approves a discount. What to say about allergies. What never to do. Precedent learns those rules from the conversations your team is already having, has a person approve every one, and puts a deterministic gate in front of every action your agents take.

_{Real output from bash examples/demo.sh (offline, no API key). Long lines shortened to fit.}

🧭 The problem

Every agent deployment hits the same wall: the agent is capable, but it doesn't know the house rules.

The real process lives in the moments when someone asks a colleague "how do we handle X?" and gets an answer. Precedent treats those moments as the source, a person as the authority, and the agent's uncertainty as the signal for what to learn next.

✨ What you get

🚀 Quick start

No API key needed. Python 3.10+.

pip install precedent-ai

The package on PyPI is precedent-ai; you import it and run it as precedent.

See the whole loop in about 20 seconds on a sample bakery WhatsApp group:

git clone https://github.com/burhan-mujahid/precedent && cd precedent
pip install -e .
bash examples/demo.sh            # offline
bash examples/demo.sh --live     # with GEMINI_API_KEY / MOONSHOT_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY set
bash examples/demo.sh --pause    # step by step, for presenting

Or on your own team's chat:

precedent init my-rulebook --pack support     # packs: general support ops sales finance hr oncall
cd my-rulebook
precedent ingest ~/Downloads/"WhatsApp Chat with Ops.txt"
precedent review                              # approve / edit / reject drafts, with the source messages shown
precedent ask "Customer says the birthday cake arrived damaged"

[NEEDS APPROVAL] D-20261109T1154-1eadcb90d0  confidence 0.88  risk high
  answer : Ask for a photo first. If the damage is clear we remake it for free or refund in full, their choice. Don't argue about it, it's never worth the review.
  rules  : R-003 v1
  why    : reasoner: matched R-003 on: arrived, cake, customer, damaged
  why    : high-risk action: a human must approve

🔍 How it works

flowchart LR
    subgraph sources ["Where the knowledge already is"]
        A["💬 WhatsApp / Slack / JSONL"]
        B["📝 Session notes"]
        C["✋ Human overrides"]
    end

    A -- "mine Q&A threads" --> P["📋 Proposals<br/>(drafts with evidence)"]
    B -- "precedent wrap" --> P
    C -- "precedent feedback" --> P
    G["🕳️ Gaps"] -- "a person answers once" --> P

    P -- "a person approves" --> R[("📚 Rulebook<br/>versioned YAML, in git")]

    AG["🤖 Agent"] -- "consult_rulebook" --> GATES{"🚦 5 gates"}
    R --> GATES

    GATES --> ACT["🟢 ACT<br/>cites rule versions"]
    GATES --> APP["🟡 NEEDS APPROVAL<br/>high-risk: a human signs off"]
    GATES --> ESC["🔴 ESCALATE<br/>logged as a gap"]
    ESC --> G

    ACT -- "each step + after Done" --> CHK{"🛑 check_action"}
    APP -- "after sign-off" --> CHK
    CHK --> CONT["continue"]
    CHK --> HALT["HALT<br/>halt record · run stopped"]
    HALT -- "a person answers once" --> G

The five gates

Every consult_rulebook call goes through these, in order. The first failure wins, and every failure opens a gap for a human to answer.

🛑 The execution gate: halting a run that's already going

The five gates decide whether an action may start. They can't stop one that's already running, and they never see what actually happened. So there is a second gate. While acting, the agent calls check_action (or kb.check, or precedent check) with its decision id before each step that changes something, and once more after Done. Every call returns continue or halt. None of the checks calls a model.

Every halt is a halt record in logs/events.jsonl: the decision, the run, the cited rule versions, the stage (during or after), the reason, and who created it. That's precedent:check for the checks above, or the person or probe that called precedent halt. Halts are final. Once a run is halted, every later check in it halts too, so an agent can't retry its way past one. Out-of-scope and external halts also open a gap, so a person's answer becomes a rule fix and a regression test.

> check: Refunding 5000 to the customer's card
[HALT] H-20261109T1428-e1f2fb8921  D-20261109T1428-2ed8117143  during  run run-cake
  why    : out_of_scope: the step uses 5000, which the decision did not authorise
  gap    : G-20261109T1428-80363d1ecc

> check: Refunded the cake in full
[HALT] H-20261109T1428-e1f2fb8921  D-20261109T1428-2ed8117143  after  run run-cake
  why    : halted: H-20261109T1428-e1f2fb8921 (out_of_scope) already stopped this decision; a person starts a new run

Bring your own monitor. If something outside Precedent halts a run, such as an execution monitor or a person watching, it calls report_outcome with verdict: "halt" (or precedent halt D-… "why" --fix "what should happen"). Precedent records the halt, stops the rest of the run, opens a gap and drafts the rule fix. Approving the fix adds a regression case.

🔌 Plug it into your agent

Precedent isn't an agent framework or a memory store. It's the decision layer underneath whatever you already use.

from precedent import Precedent

kb = Precedent.open("./my-rulebook")
d = kb.resolve("Customer wants a refund, order arrived 3 days late", context={"order_value": 4500},
               run_id="run-42")

if d.outcome == "answer":            # act; d.cited == [{"id": "R-004", "version": 2, "sha": "f1733b9bf477"}]
    ...
elif d.outcome == "needs_approval":  # covered, but high risk: a human signs off (kb.sign_off(d.id, "owner"))
    ...
else:                                # "escalate": a gap was logged and will come back as a rule
    ...

# While acting: before each step, and once after Done
if kb.check(d.id, "Refunding 4500 to the original card").halted:
    stop_the_run()
kb.check(d.id, "Refunded 4500", stage="after")

{ "mcpServers": { "precedent": { "command": "precedent", "args": ["mcp", "--root", "/path/to/my-rulebook"] } } }

precedent ask "Supplier emailed saying their bank account has changed" --json

precedent export skill      # an Agent Skills folder (agentskills.io): Claude, Codex, Cursor, Gemini CLI, Hermes...
precedent export agents     # an AGENTS.md / CLAUDE.md block
precedent export parlant    # a script that loads every approved rule as a Parlant guideline
precedent export json | markdown

- run: precedent eval --min-pass 1.0
- run: precedent health --strict

🧪 Results with real models

The same sample chat and five situations, run through Gemini, Kimi and the offline baseline. Nothing below is edited; full transcripts and token counts are in docs/LIVE-RESULTS.md.

_{¹ Kimi rated "message the customer and add a free cookie box" as high risk when drafting; a reviewer settles that once, at approval. ² The keyword baseline matched only "cancel" and "order" (confidence 0.52, under the 0.55 approval floor), so a person decides. The models worked out that "the day after tomorrow" is more than 24 hours away.}

Ingest of the 9 Q&A threads: Gemini 9.4 s, Kimi 57 s, offline 0.3 s. Each decision is one model call (none when the coverage gate escalates first).

🗓️ The weekly loop: about 30 minutes for a founder

precedent cycle

One digest, in order of leverage:

1. Answer these. Escalations clustered by similarity ("7 cases about supplier bank details"). One answer per cluster becomes a draft rule.
2. Review these drafts. From chat mining, overrides, session wraps and drift checks.
3. Rulebook health. Stale, overridden, unused and duplicate rules, and the escalation rate.
4. Failing regression cases, if a change broke something that used to work.

🤖 Using a model

The offline reasoner is a deterministic keyword baseline for tests and demos. For real use, pick a provider in precedent.yaml, export its key, and run precedent doctor. It lists the models your key can use, makes a test call, and runs one real decision.

provider:
  kind: gemini
  model: <a current Flash model: see `precedent doctor --filter flash`>

Model names change often, so Precedent never hard-codes one. If a model rejects temperature or reasoning_effort, the client drops it and retries. Mining runs ingest.workers (default 4) model calls in parallel and prints the calls and tokens it used.

policy:
  min_confidence: { low: 0.55, medium: 0.70, high: 1.01 }   # > 1.0 = never act alone
  approval_floor: 0.55        # high-risk matches below this escalate instead of going to sign-off
  stale_penalty: 0.8          # confidence multiplier for rules past their review date
runtime:
  redact: true                # strip personal data and secrets before the model and the log
  max_situation_chars: 4000
  decision_ttl_minutes: 60    # how long a decision (or its sign-off) authorises action
retrieval: { top_k: 5, min_coverage: 0.30 }
rules:     { review_days: 90 }
drift:     { unused_days: 60, override_limit: 2, duplicate_similarity: 0.6 }
ingest:    { redact: true, episode_window_hours: 12, episode_max_replies: 8, workers: 4 }
risk:      { high_terms: [], medium_terms: [] }               # domain packs fill these in

🔐 Safety by design

Precedent's job is deciding when an agent may act alone, so it's built to fail closed: when anything is in doubt, a person decides.

• 🧱 The model is untrusted. It can only cite rules it was shown. An answer with a number found in neither the rule nor the situation (a prompt-injected "refund 5000") escalates. Model errors escalate. Agents also receive the approved rule text word for word.
• 🙈 Privacy floor. API keys, tokens, passwords, private keys, emails, phone numbers, card and IBAN numbers, IPs and URL query strings are redacted before anything is stored or sent to a model, both at ingest and at runtime. Use ollama and nothing leaves your machine.
• 🛑 Halts are deterministic and final. The execution gate halts a step that goes beyond its decision, a decision reused after Done or past its lifetime, and any run whose rules changed underneath it. A halted run stays halted.
• 🧾 Audit trail. Every decision records the id, version and content hash of each rule it relied on. Logs are append-only, and any past decision can be replayed against the rulebook as it stood that day.
• 🔒 Hardened storage. Ids are validated before they become file names, approvals take a cross-process lock, API keys only travel over HTTPS, and inputs and responses are size-capped.
• 🧬 Supply chain. One runtime dependency. CI runs pip-audit, Actions are pinned to commit SHAs, releases ship with signed build provenance.

The full threat model, what is not defended, and how to report a vulnerability: SECURITY.md.

🗺️ How it compares

The pieces exist separately; the combination doesn't.

Precedent can export to Parlant, so it complements rather than competes. Details and related research: docs/DESIGN.md §9.

🏗️ Project layout

precedent/
  ingest/        WhatsApp, Slack and JSONL parsers, redaction, Q&A episode detection
  retrieve.py    dependency-free BM25 + coverage scoring
  reasoner.py    extract / decide / wrap: model-backed and deterministic offline versions
  runtime.py     the five gates
  guard.py       the execution gate: check during and after an action, halt records, sign-off
  loop.py        mining, review, gaps, feedback, session wrap
  drift.py       health checks           evals.py     regression replay
  calibrate.py   evidence-based thresholds  export.py  Skill / AGENTS.md / Parlant / JSON
  mcp.py         stdio MCP server        packs.py     domain packs        cli.py
skill/precedent/   use Precedent from Claude or any Agent Skills client
examples/          sample WhatsApp export, end-to-end demo, integration snippets
docs/              DESIGN.md · LIVE-RESULTS.md · DEMO.md

📍 Status and limits

v0.2.2, alpha. 139 tests, run by CI on Linux (Python 3.10 to 3.13), macOS and Windows; ruff and strict mypy clean. Known limits:

• The offline reasoner is lexical. It's a deterministic baseline for tests and demos; real deployments should use a model for extract and decide.
• Retrieval is BM25. It suits rulebooks of tens to low thousands of rules written in the team's own words. Stemming is English-only; Urdu and Roman Urdu chats parse fine, but rules match on exact words. An embedding retriever can drop in behind the same one-method interface.
• Calibration needs evidence. Thresholds are only recommended once a risk tier has enough regression cases.
• No built-in authentication. Whoever can write the rulebook folder can approve rules. Keep it in a git repo with reviewed pull requests (SECURITY.md).

Roadmap: direct connectors (Slack, WhatsApp Business, Gmail, helpdesks) · an optional embedding retriever · agreement across several model samples as a confidence signal · a static review UI · multi-reviewer quorum for high-risk rules.

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md. Good first issues: more chat formats (Teams, Discord, Telegram, email), domain packs, an embedding retriever, a review UI.

pip install -e ".[dev]" && pytest -q && ruff check . && mypy

Live provider tests (skipped without keys): GEMINI_API_KEY=… MOONSHOT_API_KEY=… pytest -m live.

📚 Citing

If Precedent helps your research or product, please cite it. GitHub's "Cite this repository" button (from CITATION.cff) gives APA and BibTeX:

@software{mujahid_precedent_2026,
  author  = {Mujahid, Muhammad Burhan},
  title   = {Precedent: human-approved operating rules and deterministic action gates for AI agents},
  year    = {2026},
  version = {0.2.2},
  url     = {https://github.com/burhan-mujahid/precedent}
}

📬 Contact

Muhammad Burhan Mujahid: burhanmujahid552@gmail.com · @burhan-mujahid

Questions and ideas: Discussions. Bugs: Issues. Security reports: privately, please.

📄 License

MIT © Muhammad Burhan Mujahid