mizan 0.1.0

The reliability scale for AI agents: restore, balance, classify, constrain, verify, weigh.

Mizan ميزان

The reliability scale for AI agents.

Restore the prompt, balance contradictions, classify the case, constrain the arguments, verify the execution, then weigh the evidence.

Mizan is built Arabic-first because Arabic exposes failures English often hides: morphology, dialect drift, transliteration, right-to-left text, BiDi safety, and token cost. Those are the same blind spots that hide tool-poisoning attacks generic English scanners miss — which is why Mizan ships a multilingual MCP scanner (mizan.mcpscan) alongside the reliability pipeline.

This repository is the spine for the Mizan stack. It does not replace the existing repos. It makes them read as one system.

Thesis

Agents need a scale before autonomy. Every prompt transformation should be restorable, every contradiction should be balanced or escalated, every tool argument should be constrained, and every execution should leave a receipt that can be weighed against what the agent claims.

Quickstart — scan an MCP server for poisoning

The scanner is dependency-free (detectors are vendored), so it runs from a bare install:

pip install "mizan[mcpscan]"          # or just: pip install mizan
python -m mizan.mcpscan examples/mcp_tools_poisoned.json --mode audit

You get a per-tool report — rule ID, severity, evidence, remediation — plus an audit/warn/block decision. Try examples/mcp_tools_clean.json to see clean tools pass (legitimate Arabic, benign "token"/"secret" names, and a secret_key param that only warns, never blocks). The rest of the pipeline (preflight, verify) needs the optional git extras; the scanner does not.

How well does it work? See the honest, three-tier benchmark (consistency / held-out / fresh held-out): docs/MCP_POISONING_BENCHMARK.md — 0 hard false positives across all tiers, ~63% recall on genuinely novel attacks.

Use

from mizan import preflight, PreflightContext

r = preflight(
    "send it. cancel it.",
    PreflightContext(contradiction_predicates=[("send", "cancel")]),
)
r.ok            # False — contradiction is fail-loud, not silently resolved
r.contradiction # the conflict, surfaced for a clarifying question
r.receipt.to_dict()  # the weighable trail (restore + balance stages)

Scan an MCP tool descriptor for multilingual/Unicode poisoning (the scan step):

from mizan import scan_tool, decide, ScanConfig

res = scan_tool({"name": "get_weather", "description": "Weather. ‮ hidden reversed directive"})
res.ok                                    # False — BiDi control flagged
[f.rule_id for f in res.findings]         # ['R-BIDI-001']
decide(res, ScanConfig(mode="block")).action   # 'block' (audit/warn/block modes)

mizan.mcpscan catches BiDi, invisible/TAG, homoglyph, Arabizi, Arabic/English code-switch, and (advisory) semantic-exfiltration vectors. Structural findings are high (block-worthy); semantic-language findings are medium (warn — confirm intent, since legitimate security tools mention these terms). Also a CLI: python -m mizan.mcpscan tools.json --mode audit.

Export any receipt as OpenTelemetry-compatible spans (interop) with a signed receipt (the tamper-evidence OTel lacks):

from mizan import receipt_to_spans
spans = receipt_to_spans(result.receipt, secret="…")   # one parent + one span per stage
spans[0]["attributes"]["mizan.receipt.signature"]        # HMAC-SHA256 over the canonical receipt
# emit_otel(receipt, secret="…")  # pushes real spans if `pip install mizan[otel]`

See examples/otel_trace.py for a full scan → preflight → gate → constrain → verify trace.

Constraint-driven tool gating (the qadiya step):

from mizan import ToolGate, equals_constraint

gate = ToolGate(
    [equals_constraint("tool", "tool_name", ["read_file", "search"])],
    allowed_case_ids=["tool=read_file", "tool=search"],
)
gate.check({"tool_name": "rm_rf", "args": {}}).allowed  # False — escalated, never silently run

The three primitives (jabr, muqabalah, qadiya) are not yet on PyPI. In a dev tree, mizan adds local checkouts under ~/Projects to sys.path; to install, run pip install -e ../jabr -e ../muqabalah -e ../qadiya -e ..

End to end — one receipt across all five stages

mizan folds the back half (mtg argument constraint, toolproof execution verification) into the same receipt via adapters (constrain, record_from_mtg, record_from_toolproof). examples/end_to_end.py runs a tool call through the whole scale:

=== Clean Arabic request — survives every stage ===
ok=True  blocked_by=[]
  [ok ] restore   jabr
  [ok ] balance   muqabalah
  [ok ] classify  qadiya
  [ok ] constrain mtg
  [ok ] verify    toolproof

=== Failure path — transliteration + hallucinated claim ===
ok=False  blocked_by=['mtg', 'toolproof']
  [ok ] restore   jabr
  [ok ] balance   muqabalah
  [ok ] classify  qadiya
  [BLOCK] constrain mtg       # "Riyadh" — Arabic argument transliterated
  [BLOCK] verify    toolproof # claimed a tool call that never ran

Stack

flowchart LR
    A[User input] --> B[jabr: restore]
    B --> C[muqabalah: balance]
    C --> D[qadiya: classify + dispatch]
    D --> E[MTG: constrain arguments]
    E --> F[ToolProof: verify execution]
    F --> G[Signed receipts]

    H[case-eval] -. measures .-> B
    H -. measures .-> C
    H -. measures .-> D
    I[arabic-agent-eval] -. scores .-> E
    J[wasl] -. supplies tools .-> D
    K[hurmoz + khwarizmi-hermes-plugin] -. operates inside Hermes .-> A
    L[artok] -. shows Arabic token cost .-> A
    M[faraid] -. demonstrates exact case method .-> D

Repo Map

Stage	Repo	Verb	Current state	Next improvement
Tool-surface inspection	mizan.mcpscan (this repo)	scan	Multilingual MCP poisoning scanner: 6 rule families, audit/warn/block modes, 43 tests, 25/25 corpus recall @ 0 high-FP	OTel export; held-out adversarial corpus; real mcp-scan comparison
Pre-LLM input integrity	jabr	restore	Reversible prompt-context restoration, 31 tests	Publish as part of one preflight package
Pre-LLM input integrity	muqabalah	balance	Reversible cancellation and fail-loud contradiction handling, 19 tests	Share a common receipt format with the rest of the stack
Pre-LLM input integrity	qadiya	classify + dispatch	Constraint-driven case registry, 15 tests	Done — exposed as mizan.ToolGate and wired into the Hermes plugin
Proof it works	case-eval	measure	272 ambiguous prompts, deterministic and LLM-in-the-loop modes, 28 tests	Keep results reproducible and publish the key tables from fresh runs
During tool selection	mtg	constrain	Morphological Type Guards for multilingual tool arguments, v0.1 advisory mode. Emits a mizan receipt via mizan.constrain	Move from advisory diagnostics toward enforceable policy modes
Post execution	toolproof	verify	Pre-execution gating, signed receipts, 95 tests, v0.5.0. Emits a mizan receipt via mizan.record_from_toolproof	Publish the adversarial dataset and methodology behind headline claims
Benchmark	arabic-agent-eval	score	51 Arabic function-calling items, 6 categories, 5 dialect variants, 22 functions	Reframe as open/installable/dialect-split, publish HF dataset and leaderboard
Tool layer	wasl	connect	Arabic MCP server, 30 tools	Register and demo as the Arabic tool substrate for agents
Agent runtime	hurmoz	operate	63 Arabic Hermes skills	Keep as the Arabic skills layer and link the reliability stack from relevant skills
Agent runtime	khwarizmi-hermes-plugin	operate	Thin Hermes adapter over mizan: preflight + qadiya tool gate (all four ops)	Rename to mizan-hermes-plugin when stable
Funnel	artok	reveal	Arabic Token Tax calculator across 18 tokenizers	Publish as a Hugging Face Space and use it as top-of-funnel
Method showcase	faraid	demonstrate	Working inheritance calculator plus al-Khwarizmi six-case algebra, 16 tests	Use as a precise public example of the case method

Pipeline

tool surface
  -> scan for multilingual/Unicode poisoning  mizan.mcpscan
user input
  -> restore missing context                  jabr
  -> balance duplication and contradictions   muqabalah
  -> classify + dispatch into explicit cases   qadiya
  -> constrain multilingual tool arguments     mtg
  -> execute, verify, and sign the receipt     toolproof + mizan.Receipt
  -> export OTel-compatible spans              mizan.otel
  -> score and publish evidence                case-eval + arabic-agent-eval

Why It Is Called Mizan

A mizan is a scale: it brings two sides into balance and it measures. Both meanings are the point.

The operations that bring an agent's input into balance are the same operations that gave algebra its name. Al-Khwarizmi's book titled them al-jabr (restoration) and al-muqabalah (balancing):

• jabr restores missing terms instead of letting a model silently guess.
• muqabalah balances duplicates and contradictions instead of letting a model silently choose.
• qadiya turns the remaining request into explicit cases instead of vague intent routing.
• mtg gives multilingual tool arguments stronger types than plain strings.
• toolproof records what actually ran, then verifies claims against signed receipts.

Mizan is the scale those operations serve. The brand is useful only if the engineering stays literal: a scale for agents means explicit operations, complete cases, reversible transformations, and auditable, weighable outcomes.

Honest Boundaries

• This repo now ships a small mizan package (preflight, ToolGate, and the mtg/toolproof receipt adapters); the underlying primitives still live in their own repos.
• The full pipeline (restore → balance → classify → constrain → verify) chains into one Receipt; see examples/end_to_end.py. mtg/toolproof are optional imports — the adapters accept native results, so mizan installs without them.
• The Hermes plugin now runs all four operations: jabr + muqabalah via mizan.preflight, and qadiya via mizan.ToolGate. The tool gate is a tool-name allowlist today; richer constraints (arg scope, target sensitivity) are supported by ToolGate but not yet surfaced in config.
• MTG is advisory in v0.1.0. It logs violations but does not block calls.
• ToolProof's strongest headline claims need a published dataset and reproducible methodology before they should be used in investor/customer copy.
• arabic-agent-eval, wasl, and hurmoz should avoid "first" or "largest" claims unless those claims are actively re-verified. Safer framing: open, installable, Arabic-first, dialect-aware.

Classification Rule

Every repo should have one job:

Class	Rule	Examples
Core	Part of the reliability pipeline	jabr, muqabalah, qadiya, case-eval, mtg, toolproof, arabic-agent-eval, wasl, hurmoz, khwarizmi-hermes-plugin, artok
Proof	Shows credibility or a worked method	faraid, Tarminal, Lisan, bidi-guard
Suite	Belongs under an Arabic AI developer toolkit umbrella	samt, mukhtasar, sarih, safha, qalam, raqeeb, naql, majal, jadwal, khalas
Port	Valuable but on the older runtime surface	mkhlab into Hermes/Hurmoz
Client/cash	Funds the work and tests it in production	performancemax, localbiz, yalla-ads, pmax-core
Archive	One-off with no role, no proof value, and no cash value	Decide after audit, not blindly

Status & next moves

Done: preflight (all four ops) wired into the Hermes plugin · arabic-agent-eval published as a HF dataset + static leaderboard · receipts chained across jabr/muqabalah/qadiya/mtg/toolproof (examples/end_to_end.py) · hurmoz/plugin/wasl submitted to awesome-hermes-agent · mizan.mcpscan shipped with the labeled corpus eval + Hermes plugin audit mode · mizan.otel exports receipts as OTel-compatible spans with HMAC signatures.

Next:

1. Harden mcpscan against v2 held-out gaps (ZWNJ/joiner, tab-spacing, semantic vocabulary), then author a fresh v3 set. Held-out generalization so far: ~63% recall on novel attacks, 0 hard false positives across two sets (audit/warn-ready, not default-block). Run the real mcp-scan for the generic-scanner comparison when a public claim is wanted.
2. arabic-agent-eval v2: format-instruction adherence, a code-switch split, and outcome/policy-level scoring.
3. Eventually: real PyPI versions (or vendoring) for jabr/muqabalah/qadiya/mtg instead of git extras; a formal receipt spec once the shape is stable.

One-Line Pitch

Mizan is an Arabic-first reliability scale for AI agents: restore the prompt, balance contradictions, classify the case, constrain the arguments, verify the execution, and weigh the evidence.