sparkrules

The business rule engine that Python was missing. Drools-style DRL syntax, explainable decisions, regulatory-grade audit trails - from laptop to lakehouse, no JVM required.

Design scope and known gaps: docs/KNOWN_LIMITATIONS.md (Spark vs Python regex, strategy limits, production checklist).

from sparkrules.executor import RuleExecutor

result = RuleExecutor().run(
    {"amount": 1500, "region": "US"},
    'rule "high-value" when $f : Fact( amount > 1000 ) then result.risk = "high"; end',
)
print(result.fired)          # True
print(result.action_output)  # {'risk': 'high'}

Install

pip install sparkrules          # core engine only
pip install sparkrules[api]     # + FastAPI server and Workbench UI
pip install sparkrules[spark]   # + PySpark cluster integration
# Optional Rust Tier-1 (sparkrules-native): not on PyPI yet — build in sparkrules_native/ or use CI wheel artifacts; see docs/NATIVE_TIER1.md
pip install sparkrules[all]     # everything

Running uvicorn sparkrules.api.app:create_app without [api] installed raises a clear ImportError pointing at pip install 'sparkrules[api]'. See also docs/KNOWN_LIMITATIONS.md.

Who is this for?

Why SparkRules over alternatives?

SparkRules' unique position: governance + DQ + business rules + adverse-action reasons in one versioned, auditable package - from laptop to lakehouse.

What's inside

Rule engine

Write rules in Drools-style DRL. Evaluate facts. Get explainable results with bound fields, action outputs, and reason codes. Supports salience priority, agenda groups, activation groups, and multi-pattern rules.

Decision tables

Define rules as spreadsheet-style tables with hit policies (UNIQUE, FIRST, PRIORITY, COLLECT). Import/export XLSX. Business analysts can author rules without writing DRL.

Regulatory compliance (new in 1.0.1)

build_adverse_action_notice() aggregates reason codes from rule evaluations into structured notices for ECOA/FCRA (US) and GDPR Article 22 (EU). Up to 4 principal reasons per ECOA standard, deduplicated and priority-ordered.

from sparkrules.executor import RuleExecutor, build_adverse_action_notice

results = [executor.run(applicant, drl) for drl in credit_rules]
notice = build_adverse_action_notice(results, decision="decline", fact_id="app-123")
# notice.principal_reasons = ("CR001", "CR002", "IN001")

Data quality + profiling (new in 1.0.1)

Built-in DQ checks (not-null, range, in-set, regex, uniqueness, freshness) plus statistical profiling - completeness, uniqueness, mean/stddev/percentiles, top-N values. Run DQ checks before rules, governed by the same versioning and namespace system.

from sparkrules.dq import profile_rows

profile = profile_rows(batch_of_facts)
# profile.fields[0].completeness = 0.98
# profile.fields[0].numeric_stats.mean = 45000.0

API + Rules Workbench

FastAPI server with OpenAPI docs, health endpoint, rule CRUD, and a browser-based Rules Workbench with Monaco DRL editor, real-time LSP diagnostics, simulation, and interactive Chart.js dashboards.

Simulation modes

Test rules before deploying: default, shadow (compare two rule sets), coverage (which rules fire?), counterfactual (what-if analysis), and chain (ordered multi-rule evaluation with stop-on-fire).

DMN (minimal Camunda-style decision tables)

Evaluate a small DMN 1.3 XML subset (decision tables with hit policies including COLLECT variants) without the JVM.

• HTTP: POST /dmn/evaluate and POST /dmn/counterfactual (XML plus JSON environment; see OpenAPI when the API is running).
• CLI: sparkrules-cli dmn-evaluate and sparkrules-cli dmn-counterfactual (in-process, no server).
• Python: sparkrules.dmn.evaluate_dmn_decision_table_xml / counterfactual_dmn_decision_table_xml, or SreClient.dmn_evaluate / dmn_counterfactual over HTTP.

In-process simulation CLI (same behavior as HTTP chain/shadow/coverage): sparkrules-cli simulate-chain, sparkrules-cli simulate-shadow, and sparkrules-cli simulate-coverage (see sparkrules-cli --help for flags). Over HTTP, use SreClient.simulate_chain, simulate_shadow, and simulate_coverage.

AI, Ranger, and compliance notice templates

• AI: By default the API uses offline structural suggestions (no generative model). For OpenAI-compatible Chat Completions, set SPARKRULES_AI_PROVIDER=openai and SPARKRULES_OPENAI_API_KEY on the server (optional: SPARKRULES_OPENAI_BASE_URL, SPARKRULES_OPENAI_MODEL, SPARKRULES_OPENAI_TIMEOUT_SECONDS).
• Ranger-style HTTP policy: When SPARKRULES_RANGER_BASE_URL is set, ranger_allow_stub() delegates to query_ranger_allowed() (optional SPARKRULES_RANGER_EVAL_PATH, SPARKRULES_RANGER_RESULT_FIELD). Without it, the function keeps the local dev behavior (deny empty user; otherwise allow).
• Adverse-action (compliance): build_adverse_action_notice() emits jurisdiction-framed templates for legal review; use appendix_lines=... for institution-specific paragraphs.

Time-travel debug

Capture rule execution snapshots. Replay them later with different facts. Deterministic re-runs for audit and debugging.

Governance

Version every rule. Scope by namespace. Promote through dev → stage → prod. Deprecate with propose → approve → enforce workflow. Full audit trail.

Spark integration (optional)

Pure Python by default. When you need cluster scale, wire apply_drl(df, drl) into your PySpark job - same rules, distributed via mapPartitions. Compatible with Spark 3.x+. Deploy on AWS Glue, Databricks, GCP Dataproc, Azure Synapse, or Kubernetes - config-driven, no code changes.

Scope and trade-offs are documented in docs/KNOWN_LIMITATIONS.md.

Performance (new in 1.0.1)

DRL parse caching (LRU 256) gives 5-10x throughput boost on repeated evaluations.

Quick start

From PyPI

pip install sparkrules[api]
python -m uvicorn sparkrules.api.app:create_app --factory --port 8042
# → http://127.0.0.1:8042/workbench/

From source

git clone https://github.com/vaquarkhan/sparkrules.git
cd sparkrules
pip install -e ".[test]"
pytest tests/ -q

Docker

docker compose up --build
# → http://127.0.0.1:8042/workbench/

Use cases

5 complete end-to-end examples with DRL, sample data, and Spark jobs: examples/usecases/

Jupyter notebooks

Start with notebook 06 for the architecture overview, then 01 for hands-on basics.

Platform support

How it works

1. Author rules in DRL or decision-table form
2. Parse and validate with LSP diagnostics
3. Simulate with shadow, counterfactual, and chain modes
4. Deploy with versioning, namespace scoping, and promotion pins
5. Evaluate facts and get explainable, auditable results
6. Replay any historical decision deterministically

Documentation

Full docs: sparkrules.readthedocs.io

Quality

• 840+ tests - unit, property-based (Hypothesis), integration, cross-path equivalence, performance
• 100% line coverage enforced in CI (fail_under=100)
• Python 3.11 / 3.12 / 3.13 tested in CI matrix
• Ruff lint + format enforced
• pip-audit dependency security scanning
• Apache 2.0 license - use it anywhere, commercially or otherwise

License

Licensed under the Apache License, Version 2.0.

Copyright 2026 Vaquar Khan. See CITATION.cff for citation details.