Repository navigation
Releases
MicroLLM v0.4.1 — Portable Vault Configuration, Release Hygiene & Reproducible Packaging
MicroLLM v0.4.1 — Portable Vault Configuration, Release Hygiene & Reproducible Packaging
MicroLLM v0.4.1 (micro-jev) is a maintenance, privacy-hygiene, and packaging reproducibility patch release following v0.4.0. It aligns published PyPI (sdist / wheel), GitHub Release, and Docker Hub artifacts with the scrubbed Git tree, generalizes Hugging Face credential resolution for portable environments, and reinforces CI standalone-wheel and repository hygiene checks.
Key Highlights
- Portable KeePass Vault Resolution (
microllm.hf_publishing):- Generalized
get_vault_paths()andresolve_hf_token()to use environment variables (MICROLLM_KEEPASS_DB,KEEPASS_DB,KEEPASS_DB_PATHandMICROLLM_KEEPASS_KEY,KEEPASS_KEY,KEEPASS_KEY_PATH) with a clean cross-platform default fallback at~/.config/microllm/vault.kdbx(#269). - Removed legacy workstation-specific path references from packaged distributions (
wheelandsdist).
- Generalized
- Repository Privacy & Packaging Hygiene Suite:
- Added automated CI regression suite (
tests/test_repo_privacy_hygiene.py) enforcing.gitignorecoverage on local vault files (*.kdbx,*.keyx) and private outreach artifacts, zero hardcoded OS user paths, and zero leaked personal contact metadata across all tracked files (#269). - Re-aligned cryptographic
SHA256SUMS.txt, PyPI distributions, and Git tag provenance (RCA-093,RCA-095).
- Added automated CI regression suite (
- CI Standalone Wheel & Version Synchronization Guardrails:
- Updated isolated out-of-tree wheel integration assertions in
.github/workflows/ci.yml(#267,RCA-092). - Added
test_all_version_surfaces_synchronizedintests/test_packaging_ci.pyto guarantee lockstep alignment acrosspyproject.toml,microllm.__version__, FastAPIcreate_app().version, MCPserverInfo.version, and.github/workflows/ci.yml. - Hardened
packaged_wheelfixture intests/test_audit18_m4_cicd_packaging.pyso standalone packaging checks build the wheel on demand ifdist/is empty.
- Updated isolated out-of-tree wheel integration assertions in
- Documentation & Governance Traceability:
- Updated
docs/ACTION_LOGBOOK.md(ACT-121–ACT-124) anddocs/RCA_REGISTER.md(RCA-092–RCA-095).
- Updated
Quality & Performance Summary
- Test Suite:
1,371unit, integration, adversarial, and privacy-hygiene tests passing (0failed,1skipped;92%code coverage across9,449statements),0flake8/mypyissues,16/16LaTeX math syntax checks passing. - Core v0.4.x Engine Capabilities Preserved:
- Logit-space
S1-SHAPcounterfactual attribution (original_log_odds,logit_drop). - Inter-clause evidence-competition hijack defense (
x_hijack_suspected,x_abstain=True). - Coding-agent
policy_boundaries(allowed/forbidden) with remainder-based destructive hazard inspection and NFKC Unicode normalization. - Verified CPU throughput:
0.013 msp50 (38,917 decisions/sontest_cases_11000) across the 12-suite / 28-dataset benchmark campaign.
- Logit-space
Installation & Quickstart
1. Package Upgrade
pip install --upgrade micro-jev==0.4.1Or run via multi-arch Docker (linux/amd64, linux/arm64):
docker pull jmrenouard/microllm:v0.4.1
docker run --rm -p 8000:8000 jmrenouard/microllm:v0.4.12. Python SDK Quickstart
from microllm import MicroJevClient
client = MicroJevClient()
decision = client.choice(
state="Payment gateway reports timeout on transaction #TX-98421.",
question_id="recovery_action",
question_text="Select the recommended recovery action.",
options=[
("retry_idempotent", "Retry with idempotent key"),
("reverse", "Reverse transaction and refund"),
("alert_oncall", "Alert engineering oncall"),
],
)
print(decision.best_option, round(decision.confidence, 4), decision.x_abstain)3. CLI Server
microllm serve --host 0.0.0.0 --port 8000 --strategy auto --neural-model minilmWhat's Changed
- docs(blog): record FR/EN mass-data essay readability overhaul and RCA-094 (#271) by @jmrenouard in #272
- chore(deps): bump docker/setup-buildx-action from 3 to 4 by @dependabot[bot] in #236
- chore(deps): bump docker/login-action from 3 to 4 by @dependabot[bot] in #233
- chore(deps): bump docker/build-push-action from 6 to 7 by @dependabot[bot] in #234
- chore(deps): bump docker/setup-qemu-action from 3 to 4 by @dependabot[bot] in #235
- chore(release): publish MicroLLM v0.4.1 production release (#273) by @jmrenouard in #274
New Contributors
- @dependabot[bot] made their first contribution in #236
Full Changelog: v0.4.0...v0.4.1
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 outre...
MicroLLM v0.3.0 — Calibrated Multilingual System-1 Decision Engine
MicroLLM v0.3.0 — Calibrated Multilingual System-1 Decision Engine
We are thrilled to announce the production release of MicroLLM v0.3.0 (micro-jev), delivering a complete, high-performance, calibrated Multilingual System-1 Decision Engine across English (EN), French (FR), Spanish (ES), and Portuguese (PT).
MicroLLM v0.3.0 eliminates the heavy latency, memory, and operational costs of generative autoregressive LLMs for deterministic classification, workflow routing, and AI safety guardrails, executing certified probabilistic decisions locally on standard CPU hardware with sub-millisecond speed and mathematically bounded confidence.
🚀 Key Highlights & Verified Production Metrics
- Dual-Gear Multilingual Architecture:
- Strategy 1 (Fast Lightweight Engine / Gear 1): Pure Python stdlib execution (
unicodedata,re,functools) with zero third-party runtime dependencies. Delivers sub-millisecond latency (p50 < 0.2 ms, SLA< 1.0 ms) with localized concept clusters, fast Unicode unaccenting (NFKD), rule-based light suffix stemming, fast language detection (detect_language_fast), and localized stopword/negation/connector tables across EN, FR, ES, and PT. - Strategy 2 (Neural Multilingual Models / Gear 2): Dual ONNX INT8 cross-encoder models—
multilingual-MiniLMv2-L6-mnli-xnli(~48 MB INT8,< 8 ms) andmDeBERTa-v3-base-mnli-xnli(~134 MB INT8,< 20 ms). Dynamiclabel2identailment index resolution (RCA-075) and localized source-language hypothesis templates eliminate cross-lingual transfer drift.
- Strategy 1 (Fast Lightweight Engine / Gear 1): Pure Python stdlib execution (
- Unified Strategy Cascade & Serving:
- Flexible strategy selection via
multilingual_strategy("fast","neural","auto") andneural_model("minilm","mdeberta"), fully accessible across FastAPI (POST /v1/systemone), Python SDK (MicroJevClient), CLI (microllm serve), and Model Context Protocol (microllm mcp).
- Flexible strategy selection via
- Interactive Multilingual Decision Studio:
- Full multilingual strategy selection and ticket evaluation presets (billing, shipping, technical support) in the Gradio web application (
src/microllm/gradio_app.py), synchronized with the Hugging Face Spacejmrenouard/microllm-decision-studio.
- Full multilingual strategy selection and ticket evaluation presets (billing, shipping, technical support) in the Gradio web application (
- Comprehensive E2E Opaque-Box & Adversarial Test Validation:
- 913 executable unit tests passed (100% pass rate), including 194 comprehensive opaque-box and adversarial tests (
tests/e2e_multilingual/) verifying end-user contracts across all 4 languages. - Zero static typing errors under
mypy src/microllm --ignore-missing-imports --check-untyped-defs. - 100% LaTeX math formatting compliance verified by
pytest tests/test_docs_math_syntax.py.
- 913 executable unit tests passed (100% pass rate), including 194 comprehensive opaque-box and adversarial tests (
- Reproducible Multilingual Benchmarks:
- Synthetic probe tickets across billing, shipping, and tech support in EN, FR, ES, and PT with isolated benchmark telemetry recorded in
benchmarks/multilingual_benchmarks_results.jsonand documented inBENCHMARKS.md §11. - Hugging Face Hub dataset publishing utilities under
jmrenouard/microllm-multilingual-benchmarkswith--dry-runand live token resolution.
- Synthetic probe tickets across billing, shipping, and tech support in EN, FR, ES, and PT with isolated benchmark telemetry recorded in
- In-Depth Failure Modes & Architectural Critiques:
- Comparative critique of lightweight vs neural strategies and detailed worst-case failure mode analysis documented in
docs/FAILURE_MODES_AND_WORST_CASES.mdanddocs/MULTILINGUAL_STRATEGIES_SUMMARY.md.
- Comparative critique of lightweight vs neural strategies and detailed worst-case failure mode analysis documented in
🛠 Features & Capabilities
1. Strategy 1: Lightweight Multilingual Engine
- Localized Lexicons: Package
microllm.lexiconscontaining curated lexicons foren.py,fr.py,es.py, andpt.py. - Multilingual Normalizer: Fast unaccenting (
strip_accents), rule-based stemming (light_stem), normalized tokenization (tokenize_multilingual_normalized), and O(1) heuristic language detection (detect_language_fast). - Concept Clusters: Expanded
CONCEPT_CLUSTERSspanning 10 domain categories activating the first 16 slots of the 256-D embedding space. - Negation & Connectors: Multi-word negation phrases, double negations, and localized sentence connectors preventing false-positive sentiment and intent flips.
2. Strategy 2: Neural Multilingual Models
- Dynamic Entailment Resolution: Resolves entailment label indices dynamically via ONNX
config.json(label2id), resolving hardcoded index assumptions. - Native Hypothesis Templates: Localized templates in
format_nli_hypothesisacross EN ("It is {opt}: {desc}."), FR ("Il s'agit de {opt}: {desc}."), ES ("Se trata de {opt}: {desc}."), and PT ("Trata-se de {opt}: {desc}."). - Dual Profiles: Support for
multilingual-minilm-int8(ultra-fast INT8) andmultilingual-mdeberta-int8(high-capacity multilingual NLI).
3. Dual-Gear Cascade
- Automatically commits Gear 1 when confidence exceeds the calibration threshold
$\tau$ . - Transparently escalates ambiguous tickets to Gear 2 neural cross-encoders with adaptive probability fusion:
4. Interactive Studio & Cloud Sync
- Interactive Gradio Decision Studio supporting live switching between Fast, MiniLM, mDeBERTa, and Auto cascade modes.
- Seamless synchronization workflow to Hugging Face Spaces (
jmrenouard/microllm-decision-studio).
📦 Getting Started
1. Installation
Install via pip:
pip install micro-jevOr 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()
# Evaluate multilingual support state with Fast Strategy (Sub-millisecond)
response = client.choice(
state="Client mécontent: la facture #9823 comporte un prélèvement en double.",
question_id="ticket_category",
question_text="Quelle est la catégorie de cette demande?",
options=[
("billing", "Problème de facturation ou paiement"),
("shipping", "Expédition ou livraison de colis"),
("tech_support", "Assistance technique ou panne"),
],
multilingual_strategy="fast",
)
print(f"Decision: {response.best_option}")
print(f"Confidence: {response.confidence:.4f}")
print(f"Abstain: {response.x_abstain}")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": "Mi pedido no ha llegado y el número de seguimiento no funciona.",
"multilingual_strategy": "auto",
"neural_model": "minilm",
"questions": [
{
"id": "departamento",
"type": "choice",
"question": "¿A qué departamento corresponde esta consulta?",
"options": [
{"name": "facturacion", "description": "Consultas sobre facturas o pagos"},
{"name": "envios", "description": "Seguimiento y entrega de paquetes"},
{"name": "soporte", "description": "Problemas técnicos con el servicio"}
]
}
]
}'📋 Full Milestone Summary (M1–M10)
| Milestone | Scope | Key Deliverables | PR |
|---|---|---|---|
| M1 | Strategy 1: Lightweight Multilingual Engine | src/microllm/lexicons/ (en, fr, es, pt), normalizer, concept clusters, negation |
PR #154 |
| M2 | Strategy 2: Neural Multilingual Models | ONNX entailment fix, localized hypothesis templates, dual model profiles (minilm, mdeberta) |
PR #156 |
| M3 | Strategy Selection Options | Runtime configuration in create_app, SystemOneRequest, MicroJevClient, and CLI |
PR #158 |
| M4 | Multilingual Benchmark Translation | Translated probe tickets in microllm_multilingual_corpus.jsonl, 4-language runner |
PR #160 |
| M5 | Hugging Face Publishing Utilities | Dataset upload (microllm-multilingual-benchmarks), model profiles, KeePass token resolution |
PR #162 |
| M6 | Isolated Benchmark Execution | Automated benchmark runner, multilingual_benchmarks_results.json, BENCHMARKS.md §11 |
PR #164 |
| M7 | Gradio Application & HF Space Sync | Strategy selection & multilingual ticket testing in gradio_app.py, Space sync automation |
PR #166 |
| M8 | Documentation & Critiques | Comparative critique, worst-case analysis in docs/FAILURE_MODES_AND_WORST_CASES.md |
PR #168 |
| M9 | Full E2E Pass & Hardening | 194 opaque-box and adversarial tests passed (100%), latency SLA hardening, typing fixes | PR #170 |
| M10 | Production Release Publication | v0.3.0 version bump across 8 files, release notes, changelog, git tag, and GitHub Release | PR #228 |
What's Changed
- feat(studio): upgrade Decision Studio usability across all 3 pillars with Gradio engine & mode switchers (#117) by @jmrenouard in #120
- ci: use microllm-jev as PyPI fallback package name (#121) by @jmrenouard in #122
- fix: import create_app in _HeadlessGradioComponent.launch (#123) by @jmrenouard in #124
- feat(studio): add consumer-friendly per-type tabs alongside advanced studio & custom parameters (#125) by @jmrenouard in #126
- feat: Add MCP tool safety annotations and M8ven Trust Index badge (#127) by @jmrenouard in #128
- fix: set PyPI distribution package name to micro-jev in pyproject.toml (#130) by @jmrenouard in #131
- docs: Update M8ven badge in README.md with verified publisher token (#132) by @jmrenouard in #133
- docs: improve Markdown readability and visual spacing across GitHub and Hugging Face repositories (#129) by @...
MicroLLM v0.1.0 — Calibrated System-1 Probabilistic Decision Engine
MicroLLM v0.1.0 — Calibrated, Sub-Millisecond System-1 Decision Engine for AI Agents
We are thrilled to announce the official v0.1.0 release of MicroLLM, an open-source (Apache-2.0) local probabilistic decision engine designed to eliminate the "System-2 Generative LLM tax" on structured agent routing, classification, compliance verification, and guardrail tasks.
🚀 Key Highlights & Verified Production Metrics
-
128,497 Evaluated Items / 130,839 Decisions across 9 Benchmark Suites:
-
100% reproducible on a single laptop CPU thread (
AMD Ryzen AI 9 365,32 GB RAM,0% GPU / 0% NPU,< 85 MBRSS memory footprint,$0.00API cost) viamicrollm benchmark --all-suites(scripts/run_all_benchmarks.py).
-
100% reproducible on a single laptop CPU thread (
-
Exact
0.000000Option-Order Drift Guarantee:- Implements AnyJev
$L_0$ log-space circular rotation with a binary-reflected Van der Corput schedule and dynamic early stopping ($\mu(\bar{z}) \ge \tau$ ). - Evaluated on 1,867 external bias audit items (
ChoiceBench1,531 +Callo-Bias336) and 60 core permutations:0.000000Order-Flip Rate and0.000000Max Probability Drift while saving 78.3% of rotation passes.
- Implements AnyJev
-
32/32 MUSTSpecification Compliance:- Full adherence to the
jevcompat 0.1standard across all typed decision primitives (noul,choice,score,multi), RFC 8259 float safety, and HTTP 422 error contract.
- Full adherence to the
-
11,000 Structured Enterprise & Universal Test Cases:
-
99.75% raw accuracy (
10,973 / 11,000) and 100.00% selective accuracy across 18 industry domains (p50 = 0.076–0.190 ms, up to 8,601 decisions/sec on CPU). Every ambiguous edge case is caught by conformal abstention (x_abstain = True).
-
99.75% raw accuracy (
-
114,018 Unsampled Rows across 16 Public External Datasets:
- Evaluates complete official splits with zero cherry-picking:
Banking77(98.74% selective acc),Yelp Full 50k(99.97%),AG News(99.51%),Amazon Reviews(99.24%),RouteLLM(92.60%),MultiNLI,BoolQ,CLINC150,GoEmotions,Reuters,WildGuardMix, andToxicChat. Overall selective accuracy: 87.49% (p50 = 0.369–0.938 ms).
- Evaluates complete official splits with zero cherry-picking:
-
Mathematical Calibration & Conformal Safety:
- Two-Stage OpenJev-RLCD² (
Stage 1 Pathwise BrierwithBeta(8,2)difficulty weighting +Stage 2 Leave-One-Out REINFORCE with KL Anchor) reducing Expected Calibration Error from15.85%down to6.15%(3.67%onG5). -
Split Conformal Prediction ($C_\alpha(x)$) with
98.75%empirical coverage at$1 - \alpha = 90%$ .
- Two-Stage OpenJev-RLCD² (
🛠 Features & Architecture
-
Dual-Gear StartLux Cascade:
-
Gear 1 (
FastEncoderBackend): Sub-millisecond CPU NLI cross-encoder with multi-resolutionBLAKE2bhashing, clause-salient max-pooling, and per-$K$ temperature scaling. -
Gear 2 (
AnyJevPrefillBackend$L_0$ ): Algebraic option-bias cancellation over cyclic permutations. -
Cascade Gating: Automatic fast auto-commit on high confidence; smooth escalation (
$p = 0.25 p_0 + 0.75 p_1$ ) or hierarchical 25-way tournament up to 255 options.
-
Gear 1 (
-
Interactive Decision Studio Web UI:
- Hosted at
http://127.0.0.1:8000/(microllm serve): visual question builder, token attribution heatmaps, live AnyJev order-flip audit, code export (Python SDK, TypeScript, cURL), 4-Rubric Guardrail shield, and RLCD² calibration curves.
- Hosted at
-
Developer Experience:
-
Typed Python SDK:
MicroJevClientwith type-safeNoul,Choice,Score, andMultiwrappers. -
Native Model Context Protocol (MCP): JSON-RPC 2.0 server over stdio (
microllm mcp) and HTTP (POST /v1/mcp). -
LightPath Presentation Deck: 12-slide interactive widescreen deck (
docs/slides.html/http://127.0.0.1:8000/slides).
-
Typed Python SDK:
-
Complete Transparent Governance:
- Living Action Logbook (
docs/ACTION_LOGBOOK.md), RCA Register of errors, dead-ends, approximations, and ideas (docs/RCA_REGISTER.md), Algorithmic Reference (docs/ALGORITHMS.md), and Engineering Syllabus (docs/SYLLABUS.md).
- Living Action Logbook (
📦 Getting Started
# Install via pip
pip install microllm
# Pull the lightweight ONNX INT8 CPU profile (~58 MB)
microllm pull fast-cpu-int8
# Run all 9 reproducible benchmark suites (128,497 items)
microllm benchmark --all-suites
# Launch the FastAPI server & Decision Studio UI
microllm serveFull Documentation: https://github.com/jmrenouard/MicroLLM
What's Changed
- chore(rules): add mandatory GitHub Issue/Branch/PR/Merge project rules (#1) by @jmrenouard in #6
- ci(tests): add GitHub Actions workflow for automated unit tests (#2) by @jmrenouard in #8
- fix(ci): add environment.yml and fix Conda GitHub Actions workflow (#7) by @jmrenouard in #9
- docs(governance): inscrire le Journal de Bord et le Registre RCA alimentés à chaque demande/changement/résultat (#5) by @jmrenouard in #11
- ci: implémenter toutes les GitHub Actions nécessaires pour un projet Python (#4) by @jmrenouard in #12
- ci(pypi): Add GitHub Actions for PyPI publication & packaging metadata (#3) by @jmrenouard in #23
- docs(governance): log ACT-011 and RCA-009 for Conda CI fix (#7) by @jmrenouard in #30
- docs(governance): rename and translate Action Logbook and RCA Register to English (#29) by @jmrenouard in #31
- fix(ci): support Python 3.10 in test_packaging_ci.py (#33) by @jmrenouard in #34
- fix(docs): replace raw LaTeX delimiters with native HTML/CSS and Unicode math (#35) by @jmrenouard in #36
- feat(benchmark): 540-item 5-track evaluation corpus & 1-command benchmark runner (#37) by @jmrenouard in #38
- feat(ui): add Obsidian Craft SVG logo & hero header banner across docs and Studio (#40) by @jmrenouard in #41
- docs(readme): add 'Why MicroLLM?' section and top-of-README 1-command benchmark table (#44) by @jmrenouard in #45
- feat(roadmap): 20 high-impact architectural & engineering improvements + English project rules (#10) by @jmrenouard in #39
- fix(docs): ensure strict UTF-8 encoding in ACTION_LOGBOOK.md and RCA_REGISTER.md (#10) by @jmrenouard in #46
- docs(governance): merge docs/ROADMAP_20_IDEAS.md into docs/RCA_REGISTER.md (#43) by @jmrenouard in #47
- test(quality): Complete Test Plan & 750–1,000 Case Performance/Quality Validation Suite (#32) by @jmrenouard in #49
- docs(benchmark): add Section 13 to docs/index.html and sync <3ms CPU latency (#44) by @jmrenouard in #53
- fix(ci): resolve Mypy union-attr errors and Bandit B615 revision pinning (#48) by @jmrenouard in #54
- feat: build 500-to-1,000 structured test case entries and publish evaluation metrics (#52) by @jmrenouard in #55
- docs(papers): 104-paper Jev, RLCD & System-1 academic literature review and /v1/papers catalog (#42) by @jmrenouard in #57
- feat(brand): colorful System-2 herd vs MicroLLM logo header banner (#50) by @jmrenouard in #60
- feat: add 10,000 product-independent test cases (11,000 total) and publish metrics (#58) by @jmrenouard in #62
- chore(deps): integrate 15 Dependabot PRs for GitHub Actions and Python dependencies (#51) by @jmrenouard in #59
- docs: add BENCHMARKS.md with published evaluation results and link from README.md (#63) by @jmrenouard in #64
- feat(benchmarks): Comprehensive Web Dataset Survey & Adapters for MicroLLM Validation (#56) by @jmrenouard in #66
- feat(papers): download all 104 arXiv PDF documents locally & add CLI --download-pdfs / --verify-pdfs (#67) by @jmrenouard in #68
- feat(rca): automated sequential RCA non-regression verification runner & CLI (#65) by @jmrenouard in #69
- feat(research): challenge code/design against research papers and enrich RCA Register with 12 hypotheses & validation tests (#61) by @jmrenouard in #71
- docs: write comprehensive Product Documentation and Technical Specifications (#70) by @jmrenouard in #72
- chore: enforce English-only rule for all project documentation and code (#74) by @jmrenouard in #75
- feat(benchmarks): implement 16 external dataset adapters and benchmark suite (#73) by @jmrenouard in #76
- docs(benchmarks): document complete benchmark procedure and hardware resource profile (#77) by @jmrenouard in #78
- fix(ci): resolve Bandit B108 tempfile warning and Mypy assignment error (#79) by @jmrenouard in #80
- feat(benchmarks): run full unsampled 114,018-row external datasets benchmark and document results (#81) by @jmrenouard in #82
- fix: harden full-split external benchmark loader, adapters, CLI/API flags, and docs (#83) by @jmrenouard in #84
- docs: add comprehensive results c...