Metadata-Version: 2.4
Name: wrg-rule-lab
Version: 0.1.6
Summary: WinstonRedGuard local-first deterministic rule evaluation engine (formerly rule-lab on PyPI, republished under WRG namespace)
Author: WinstonRedGuard
License-Expression: MIT
Project-URL: Homepage, https://github.com/WRG-11/wrg-rule-lab
Project-URL: Repository, https://github.com/WRG-11/wrg-rule-lab
Project-URL: Documentation, https://github.com/WRG-11/wrg-rule-lab#readme
Project-URL: Issues, https://github.com/WRG-11/wrg-rule-lab/issues
Project-URL: Changelog, https://github.com/WRG-11/wrg-rule-lab/blob/main/CHANGELOG.md
Project-URL: Author, https://yakuphanycl.github.io
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Dynamic: license-file

# wrg-rule-lab

A lightweight, local-first, deterministic rule evaluation engine for Python.

Define rules in JSON, evaluate them against any context, detect conflicts, and simulate outcomes -- with zero external dependencies.

[![PyPI version](https://img.shields.io/pypi/v/wrg-rule-lab.svg)](https://pypi.org/project/wrg-rule-lab/)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/wrg-rule-lab.svg)](https://pypi.org/project/wrg-rule-lab/)
[![CI](https://github.com/WRG-11/wrg-rule-lab/actions/workflows/ci.yml/badge.svg)](https://github.com/WRG-11/wrg-rule-lab/actions/workflows/ci.yml)
[![CodeQL](https://github.com/WRG-11/wrg-rule-lab/actions/workflows/codeql.yml/badge.svg)](https://github.com/WRG-11/wrg-rule-lab/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **Note:** Previously published as `rule-lab` on PyPI. Access to that account was lost; releases continue here as `wrg-rule-lab` under the WRG namespace. The import path `rule_lab` is unchanged.

## Installation
```bash
pip install wrg-rule-lab
```

## Quick Start
```python
from rule_lab import load_rules_from_dict, evaluate_rules

ruleset = {
    "rules": [
        {
            "rule_id": "r1",
            "name": "Block high risk",
            "conditions": [{"field": "risk_score", "op": "gt", "value": 80}],
            "action": "block",
            "priority": 10
        }
    ]
}

rules = load_rules_from_dict(ruleset)
result = evaluate_rules(rules, context={"risk_score": 95})

print(result.matched_count)    # 1
print(result.results[0].action)  # block
```

## CLI
```bash
# Validate a rule file
rule-lab validate --rules rules.json

# Simulate rules against a list of contexts
rule-lab simulate --rules rules.json --contexts contexts.json

# Detect conflicting rules
rule-lab diff --rules rules.json
```

## API Reference

| Function | Description |
|---|---|
| `load_rules_from_file(path)` | Load rules from a JSON file |
| `load_rules_from_dict(data)` | Load rules from a dict |
| `load_rules_from_list(rules)` | Load rules from a list |
| `evaluate_rule(rule, context)` | Evaluate a single rule |
| `evaluate_rules(rules, context)` | Evaluate a list of rules |
| `simulate(rules, contexts)` | Simulate multiple contexts |

## Rule Format
```json
{
  "rules": [
    {
      "rule_id": "unique-id",
      "name": "Human readable name",
      "conditions": [
        {"field": "score", "op": "gt", "value": 50}
      ],
      "action": "approve",
      "priority": 10,
      "tags": ["finance", "v1"],
      "metadata": {}
    }
  ]
}
```

## Supported Operators

The `op` field in a condition accepts these 10 operators (canonical set in `src/rule_lab/core/conditions.py`):

| Operator | Purpose | Example |
|---|---|---|
| `eq` | Equality | `{"field": "status", "op": "eq", "value": "active"}` |
| `neq` | Not equal | `{"field": "status", "op": "neq", "value": "banned"}` |
| `gt` | Greater than (numeric) | `{"field": "score", "op": "gt", "value": 50}` |
| `gte` | Greater than or equal (numeric) | `{"field": "score", "op": "gte", "value": 50}` |
| `lt` | Less than (numeric) | `{"field": "age", "op": "lt", "value": 18}` |
| `lte` | Less than or equal (numeric) | `{"field": "age", "op": "lte", "value": 18}` |
| `contains` | Substring match | `{"field": "email", "op": "contains", "value": "@example.com"}` |
| `not_contains` | Substring absent | `{"field": "tags", "op": "not_contains", "value": "blocked"}` |
| `exists` | Field present in context | `{"field": "user_id", "op": "exists"}` |
| `not_exists` | Field absent | `{"field": "ban_reason", "op": "not_exists"}` |

## Use Cases

- **AI release gating** -- validate LLM app outputs before production
- **Policy enforcement** -- define and run compliance rules as code
- **Decision engines** -- replace hardcoded if/else logic with JSON rules
- **Audit trails** -- every rule evaluation is traceable and reproducible

## Design Principles

- **Zero dependencies** -- stdlib only, no surprise installs
- **Deterministic** -- same input always produces same output
- **Local-first** -- no network calls, no cloud required
- **Testable** -- every rule is independently verifiable

## Sister WRG-11 packages

Part of the WRG-11 PyPI portfolio:

- [`instinct-mcp`](https://pypi.org/project/instinct-mcp/) -- MCP server for capturing recurring patterns into structured memory
- [`wrg-devguard`](https://pypi.org/project/wrg-devguard/) -- Developer-first AI safety: prompt-policy lint + secret scanning + log scanning with PII detection
- [`wrg-mcp-server`](https://pypi.org/project/wrg-mcp-server/) -- MCP bridge for the WinstonRedGuard monorepo
- [`ai-security-toolkit`](https://github.com/WRG-11/ai-security-toolkit) -- Offensive + defensive AI/LLM security tools, labs, CTF writeups, research

## License

MIT -- built by [WinstonRedGuard](https://github.com/WRG-11)
