mizan 0.1.0__tar.gz

mizan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mousa Abumazin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mizan-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: mizan
+Version: 0.1.0
+Summary: The reliability scale for AI agents: restore, balance, classify, constrain, verify, weigh.
+Author: Mousa Abumazin
+License: MIT
+Keywords: ai,agents,reliability,arabic,tool-calling,preflight
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: mcpscan
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Dynamic: license-file
+
+# 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:
+
+```bash
+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**](docs/MCP_POISONING_BENCHMARK.md)
+— 0 hard false positives across all tiers, ~63% recall on genuinely novel attacks.
+
+## Use
+
+```python
+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):
+
+```python
+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):
+
+```python
+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):
+
+```python
+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`](examples/end_to_end.py) runs a tool call through the whole scale:
+
+```text
+=== 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
+
+```mermaid
+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](https://github.com/Moshe-ship/jabr) | restore | Reversible prompt-context restoration, 31 tests | Publish as part of one preflight package |
+| Pre-LLM input integrity | [muqabalah](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/wasl) | connect | Arabic MCP server, 30 tools | Register and demo as the Arabic tool substrate for agents |
+| Agent runtime | [hurmoz](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/faraid) | demonstrate | Working inheritance calculator plus al-Khwarizmi six-case algebra, 16 tests | Use as a precise public example of the case method |
+
+## Pipeline
+
+```text
+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.**

mizan-0.1.0/README.md

@@ -0,0 +1,213 @@
+# 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:
+
+```bash
+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**](docs/MCP_POISONING_BENCHMARK.md)
+— 0 hard false positives across all tiers, ~63% recall on genuinely novel attacks.
+
+## Use
+
+```python
+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):
+
+```python
+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):
+
+```python
+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):
+
+```python
+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`](examples/end_to_end.py) runs a tool call through the whole scale:
+
+```text
+=== 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
+
+```mermaid
+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](https://github.com/Moshe-ship/jabr) | restore | Reversible prompt-context restoration, 31 tests | Publish as part of one preflight package |
+| Pre-LLM input integrity | [muqabalah](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/wasl) | connect | Arabic MCP server, 30 tools | Register and demo as the Arabic tool substrate for agents |
+| Agent runtime | [hurmoz](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/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](https://github.com/Moshe-ship/faraid) | demonstrate | Working inheritance calculator plus al-Khwarizmi six-case algebra, 16 tests | Use as a precise public example of the case method |
+
+## Pipeline
+
+```text
+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.**

mizan-0.1.0/mizan/__init__.py

@@ -0,0 +1,132 @@
+"""Mizan ميزان — the reliability scale for AI agents.
+
+One front door for the input-integrity half of the stack:
+
+    >>> from mizan import preflight, PreflightContext
+    >>> r = preflight("send it. cancel it.",
+    ...               PreflightContext(contradiction_predicates=[("send", "cancel")]))
+    >>> r.ok
+    False
+    >>> r.contradiction is not None
+    True
+
+The qadiya case primitives are re-exported for the dispatch/tool layer, and
+the shared :class:`Receipt` is the one audit format every stage appends to.
+"""
+
+from __future__ import annotations
+
+from mizan.preflight import (
+    PreflightContext,
+    PreflightResult,
+    preflight,
+    strip_tags,
+)
+from mizan.receipt import (
+    Receipt,
+    StageRecord,
+    STAGE_BALANCE,
+    STAGE_CLASSIFY,
+    STAGE_CONSTRAIN,
+    STAGE_RESTORE,
+    STAGE_SCAN,
+    STAGE_VERIFY,
+)
+from mizan.integrations import (
+    record_from_mtg,
+    record_from_toolproof,
+    constrain,
+)
+from mizan.otel import receipt_to_spans, emit as emit_otel
+
+# Re-export the qadiya case layer (classify + dispatch) for tool gating.
+# Imported defensively so `import mizan` still works if qadiya is absent.
+try:
+    from qadiya import (  # noqa: F401
+        Case,
+        Constraint,
+        CaseRegistry,
+        Classifier,
+        Dispatch,
+        DispatchResult,
+        DispatchOutcome,
+        NoMatchingCase,
+        AmbiguousCases,
+        enumerate_cases,
+    )
+    from mizan.toolgate import (  # noqa: F401
+        ToolGate,
+        GateDecision,
+        equals_constraint,
+        predicate_constraint,
+        OTHER,
+    )
+
+    _HAS_QADIYA = True
+except Exception:  # noqa: BLE001
+    _HAS_QADIYA = False
+
+# mcpscan needs mtg; import defensively so `import mizan` works without it.
+try:
+    from mizan.mcpscan import (  # noqa: F401
+        scan_tool,
+        scan_tools,
+        ScanResult,
+        Finding,
+        ScanConfig,
+        Decision,
+        decide,
+        report,
+    )
+
+    _HAS_MCPSCAN = True
+except Exception:  # noqa: BLE001
+    _HAS_MCPSCAN = False
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "preflight",
+    "PreflightContext",
+    "PreflightResult",
+    "strip_tags",
+    "Receipt",
+    "StageRecord",
+    "STAGE_RESTORE",
+    "STAGE_BALANCE",
+    "STAGE_CLASSIFY",
+    "STAGE_CONSTRAIN",
+    "STAGE_SCAN",
+    "STAGE_VERIFY",
+    "record_from_mtg",
+    "record_from_toolproof",
+    "constrain",
+    "receipt_to_spans",
+    "emit_otel",
+    "__version__",
+]
+
+if _HAS_QADIYA:
+    __all__ += [
+        "Case",
+        "Constraint",
+        "CaseRegistry",
+        "Classifier",
+        "Dispatch",
+        "DispatchResult",
+        "DispatchOutcome",
+        "NoMatchingCase",
+        "AmbiguousCases",
+        "enumerate_cases",
+        "ToolGate",
+        "GateDecision",
+        "equals_constraint",
+        "predicate_constraint",
+        "OTHER",
+    ]
+
+if _HAS_MCPSCAN:
+    __all__ += [
+        "scan_tool", "scan_tools", "ScanResult", "Finding",
+        "ScanConfig", "Decision", "decide", "report",
+    ]