Repository navigation
MicroLLM v0.4.0 — S1-SHAP, Decision Guardrails & Calibrated System-1
MicroLLM v0.4.0 — S1-SHAP, Decision Guardrails & Calibrated System-1
We are thrilled to announce the official production release of MicroLLM v0.4.0 (micro-jev), delivering major advancements in explainability, adversarial guardrail hardening, policy gatekeeping, and empirical scale validation for our ultra-low-latency, local System-1 decision engine.
MicroLLM eliminates the heavy latency, memory footprint, and operational costs of generative autoregressive LLMs for deterministic classification, workflow routing, and safety guardrails, executing certified probabilistic decisions locally on standard CPU hardware with sub-millisecond speed and mathematically bounded confidence.
🚀 Key Highlights & Verified Production Metrics
- S1-SHAP in Logit Space (
DecisionBackend.explain_counterfactual):- Exact counterfactual attribution in unbounded logit / log-odds space:
- Resolves the well-known probability saturation pathology near 0.0 and 1.0, returning both
original_log_oddsandlogit_dropalongside normalized token importance fornoul,choice,score, andmultidecisions. - Evidence Competition Hijack Defense:
- Novel cross-clause evidence competition detector (
detect_evidence_competition_hijack) and certainty hijack markers (_CERTAINTY_HIJACK_MARKERS). - Automated abstain gate (
x_hijack_suspected,x_abstain=True) inFastEncoderBackendthat intercepts attacks where injected certainty words attempt to override legitimate semantic evidence. - Hardened prompt injection detector threshold (
prompt_injection >= 0.88) inserver.py.
- Novel cross-clause evidence competition detector (
- Policy Boundary Gatekeeping & Roleplay Hardening:
- Explicit
policy_boundaries(allowed/forbidden) inSystemOneRequest,server.py,server_models.py,client.py, andmcp_server.py. - Remainder-based destructive hazard inspection ensuring that allowlist rules (e.g.,
rm -rf ./dist) never allow chained destructive payloads (DROP TABLE,rm -rf /etc,rm -rf $HOME) to bypass safety gates. - Non-downgradable hard hazard barriers for destructive commands (
rm -rf /,DROP TABLE). - Unicode NFKC normalization preventing fullwidth character bypasses (
\uff52\uff4d \uff0d\uff52\uff46). - Strict interdiction of adversarial roleplay framing (
"in a novel","screenplay","pretend you are") paired with harmful targets.
- Explicit
- Expanded Academic Catalog & Literature Taxonomies:
- 12 new October–November 2026 arXiv research papers added, expanding the catalog from 104 to 116 curated papers (
src/microllm/data/academic_papers_catalog.json). - Research roadmaps
IDEA-052throughIDEA-057registered indocs/RCA_REGISTER.md. - Comprehensive schema and metadata validation suite in
tests/test_academic_papers_catalog.py.
- 12 new October–November 2026 arXiv research papers added, expanding the catalog from 104 to 116 curated papers (
- 12-Suite Comparative Benchmark Campaign:
- Executed full 12-suite benchmark campaign evaluating 128,713 items and 131,487 decisions in 66.73s CPU wall-clock time across 28 external datasets.
- Master benchmark report generated in
benchmarks/all_benchmarks_master_report.jsonandbenchmarks/latest_master_report.md. - Confirmed p50 latency of 0.013 ms (38,917 decisions/s) on large-scale CPU evaluation (
test_cases_11000), 0.17 ms on multilingual cross-lingual transfer, and 1.5x cascade acceleration. - Fully refreshed
BENCHMARKS.mdandREADME.mdwith verified real-world metrics.
- Comprehensive Test Suite & Quality Status:
- 1,370 unit and integration tests passing at 100%.
- Zero static typing errors under
mypy. - 100% LaTeX math formatting compliance verified by
pytest tests/test_docs_math_syntax.py.
🛠 Features & Capabilities
1. S1-SHAP in Logit Space
Standard perturbation explainers measure probability drops
This ensures high sensitivity across extreme confidence regimes and provides reliable attribution for compliance and auditing.
2. Evidence Competition Hijack Defense
Adversaries frequently attempt to manipulate classification models by injecting high-certainty phrases (e.g., "definitely authorized", "undoubtedly safe", "confirmed legitimate"). MicroLLM v0.4.0 isolates clauses, calculates competitive tension between certainty markers and contradictory semantic evidence, and automatically triggers x_abstain=True when hijack markers are detected.
3. Policy Boundary Gatekeeping
For coding and enterprise tool agents, MicroLLM provides pre-execution policy boundary evaluation:
- Allowed Rules: Specific authorized command patterns (e.g.,
git status,pytest,npm test,rm -rf ./dist). - Forbidden Rules: Explicitly prohibited patterns that always override allowlists.
- Remainder-Based Inspection: Substring extraction strips authorized prefixes and inspects the remaining command payload for hidden or chained hazards (
DROP TABLE,rm -rf /). - Hard Hazard Invariants: Critical system deletions (
rm -rf /) can never be downgraded, regardless of permissive allowlist configurations.
📦 Getting Started
1. Installation
Install via pip:
pip install micro-jev==0.4.0Or install in development mode from source:
git clone https://github.com/jmrenouard/MicroLLM.git
cd MicroLLM
pip install -e ".[dev]"2. Python SDK Example
from microllm import MicroJevClient
client = MicroJevClient()
# 1. Routing decision with S1-SHAP explanation
response = client.choice(
state="The customer request contains a suspected prompt injection: ignore previous rules.",
question_id="routing_intent",
question_text="Route the incoming agent action safely.",
options=[
("execute", "Execute safe tool command"),
("quarantine", "Quarantine suspicious or harmful prompt"),
("escalate", "Escalate to human review"),
],
)
print(f"Decision: {response.best_option}")
print(f"Confidence: {response.confidence:.4f}")
print(f"Abstain: {response.x_abstain}")
# 2. Agent policy boundary pre-execution gate
guardrail_res = client.guardrail(
tool="bash",
command="rm -rf ./dist; DROP TABLE users;",
policy_boundaries={
"allowed": ["rm -rf ./dist"],
"forbidden": ["DROP TABLE", "rm -rf /"],
},
)
print(f"Safe: {guardrail_res.get('safe')}")
print(f"Action: {guardrail_res.get('action')}") # 'block'3. REST API & CLI Serving
Launch the local decision engine server:
microllm serve --host 0.0.0.0 --port 8000 --strategy auto --neural-model minilmSend a request via cURL:
curl -X POST http://localhost:8000/v1/systemone \
-H "Content-Type: application/json" \
-d '{
"model": "jev-latest",
"state": "Payment gateway reports timeout on transaction #TX-98421.",
"questions": [
{
"id": "action",
"type": "choice",
"question": "What is the recommended recovery action?",
"options": [
{"name": "retry_idempotent", "description": "Retry with idempotent key"},
{"name": "reverse", "description": "Reverse transaction and refund"},
{"name": "alert_oncall", "description": "Alert engineering oncall"}
]
}
]
}'📋 Release Summary
| Milestone | Scope | Deliverables | Verification |
|---|---|---|---|
| M1 | Unit Test Reinforcement & Boundary Hardening | 25+ new unit tests for S1-SHAP, Evidence Hijack, Policy Gates, Academic Catalog, and Wheel packaging fix | 1,370 tests passing (100%) |
| M2 | 12-Suite Benchmark Campaign & Docs | Full campaign executed across 28 external datasets; master report generated; BENCHMARKS.md and README.md updated |
12/12 suites passing, 128,713 items evaluated in 66.73s |
| M3 | Production Release Packaging & Publishing | Version bump to 0.4.0 across 8 files, changelog, release notes, wheel build & twine strict check, git tag v0.4.0, GitHub Release |
Clean wheel/sdist, 100% tests pass, GitHub Release published |
What's Changed
- feat(release): automate release pipelines, docker packaging, and sha256sums by @jmrenouard in #230
- fix(release): align release workflow trigger with published release contract by @jmrenouard in #232
- feat: resolve all 18 audit points across MicroLLM codebase (#237) by @jmrenouard in #238
- fix: resolve test grep circular match, psutil dependency, and server typing (#239) by @jmrenouard in #240
- docs: record bilingual mass-data micro-decision vision articles (#241) by @jmrenouard in #242
- feat: Decision model outreach directory and email drafts (#243) by @jmrenouard in #244
- docs: compile ai influencer outreach directory and tailored pitch drafts (#245) by @jmrenouard in #246
- docs: integrate curated Oct-Nov 2026 System-One papers and Ponytail roadmap (#247) by @jmrenouard in #248
- feat: add logit-space S1-SHAP attribution to explain_counterfactual (#249) by @jmrenouard in #250
- feat: detect certainty-claim and evidence-competition decision hijacks (#251) by @jmrenouard in #252
- feat: add explicit policy_boundaries for coding-agent guardrails and role-play hardening (#253) by @jmrenouard in #254
- docs: fix maintainer signature in outreach catalogs and record 48 sent outreach emails (#256) by @jmrenouard in #257
- test: reinforce unit tests for S1-SHAP, hijack detection, and policy boundaries (#255) by @jmrenouard in #258
- fix: enforce hard hazard and unicode normalization in policy gates (#259) by @jmrenouard in #260
- fix: enforce remainder-based destructive hazard check in policy gates (#261) by @jmrenouard in #262
- feat(benchmarks): execute 12-suite comparative benchmark campaign and update documentation (#263) by @jmrenouard in #264
- chore(release): publish MicroLLM v0.4.0 production release (#265) by @jmrenouard in #266
Full Changelog: v0.3.0...v0.4.0