RULER turns rigorously stated natural-language sources into formal knowledge bases, checked decisions, and traceable explanations. It combines generative interpretation with deterministic validation and logic or optimization backends. The result retains source evidence, accepted facts and rules, assumptions, solver outputs, counterfactuals, and grounded explanations.
- Formal KB releases: manage source-grounded facts and rules with immutable identities and explicit scope.
- Controlled autoformalization: propose, validate, execute, and review formal statements before acceptance.
- Solver-backed decisions: use declared logic, optimization, or scheduling capabilities for the computed result.
- Case-based reasoning: retrieve governed precedents, then verify the current case against current rules.
- Separate authority: generative interpretation and explanation cannot promote rules or replace formal inference; unknown remains distinct from false.
Use Python 3.12 or newer, Git, and uv. From the repository root:
uv sync --extra dev
uv run ruler validate deps
uv run ruler --helpSWI-Prolog is a separate system executable required by workflows that declare Prolog acceptance checks. The complete gate also requires browser and report preparation; follow getting started before running it. For agent skill discovery, see the plugin guide.
Product integrations use four MCP workflows: prepare knowledge, prepare a request, execute reasoning, and retrieve results. The plugin exports only these workflows; see the MCP guide for inputs and release requirements.
The CLI supports macOS, Linux, and Windows. For repository development, install
hooks with uv run python scripts/install_hooks.py and check portability with
uv run ruler validate cross-platform.
Run two release-pinned evaluation cases:
uv run ruler evaluate regulatory-proof --case satisfied_boundary
uv run ruler evaluate regulatory-proof --case open_world_unknownThese contrast a satisfied boundary with an explicitly unknown outcome. For a full cost, schedule, proof, and sensitivity report:
uv run ruler workflow resource-portfolio-demonstrator --kb-profile expandedThe detailed project guide preserves
the complete workflow catalog, diagrams, inputs, outputs, checks, and live-testing
profiles. Generated outputs belong under build/ruler/.
source evidence → semantic basis → candidate facts and rules → acceptance gates
→ immutable formal KB → inference / optimization
→ decision packet, counterfactuals, and grounded explanation
ruler/ implements the canonical CLI, typed contracts, ingestion, KB management,
reasoning, interfaces, and runtime adapters. kb/ holds declarative knowledge;
skills/ holds runtime skills; proj_skills/ holds maintenance skills.
Agent bridges and MCP invoke the same CLI and contracts.
Read the system architecture, trust model, and repository walkthrough.
Start with the documentation index. All project documentation uses the same reading areas; specialist collections retain their stable paths.
- Getting started — Install the environment and complete a first example.
- Concepts — Understand the project model, terminology, and evidence boundaries.
- Guides — Carry out tasks and interpret their outputs.
- Architecture — Understand components, data flow, contracts, and extension points.
- Reference — Look up commands, skills, workflows, and documentation sources.
- Development — Change the project and run the relevant checks.
- Operations — Configure, run, observe, and release maintained workflows.
- Governance — Check licensing, provenance, review, and publication requirements.
- Archive — Find historical material and distinguish plans from current behavior.
Use AGENTS.md and contributing. Start with checks appropriate to the changed surface. Before the complete gate, install SWI-Prolog and prepare the required browser and reports:
uv run playwright install chromium
uv run ruler prepare checks
uv run ruler validate allOn Linux CI, use uv run playwright install --with-deps chromium.
Preparation uses recorded local evidence. Validators must not generate or repair
their inputs. The full offline gate includes tests, Ruff, and whitespace checks;
live acquisition and generative evaluations remain separate operations.
The computed result is conditional on the declared source, release, facts, assumptions, and backend capability. Solver success does not supply absent evidence, causal truth, or permission to act. Historical approval is not transferred to a new case. Generative outputs remain candidates until their explicit acceptance gates pass. Demonstrations and fixture metrics have the scope stated in their reports.
RULER is licensed for non-commercial research and educational use only; see LICENSE. Its PostgreSQL adapter uses pg8000 under BSD-3-Clause. See dependency licenses for the dependency inventory and upstream terms. The software-disclosure guide explains source-only and development branches, restored evidence, and CI boundaries.