🛡️

v0.1 ships today: schema validation, feature engineering, rule mining, and an explainable XGBoost classifier — hardened, license-clean, and CI-tested.

aegis

Config-driven ML triage for false-positive sanctions alerts.

Classical ML and rule mining only — no LLMs in the runtime. Score alerts for auto-clearing, mine exception rules for Fircosoft, and keep every decision auditable.

View on GitHub → Quickstart

Why aegis

No LLMs in the runtime

Every decision runs through XGBoost, SHAP, and a RIPPER rule miner. Deterministic, seeded, and reproducible — the same training set always exports the same rules.

Dual, auditable output

A per-alert probability with its SHAP attribution, and mined IF-THEN rules exportable straight to a Fircosoft exception list, each carrying the support and confidence it was measured at.

Config-driven

Thresholds, feature toggles, and rule-mining parameters live in one YAML file, not code. Ship a new config to recalibrate, not a new release.

Built for adoption

Schema-validated inputs, PII-safe error messages, an all-permissive (MIT/BSD/Apache) dependency tree, and no model persistence or pickle deserialization anywhere.

How it works

Every alert flows through the same validated feature matrix — a classifier and a rule miner both learn from it, producing two complementary outputs.

Raw alerts ──▶ schema validation ──▶ feature engineering ──┬──▶ XGBoost + SHAP ──▶ cleared_probability (PaymentAlertInput) (string distance, corporate │ + top-3 explanation suffix, country match, │ raw screening score) └──▶ RIPPER rule miner ──▶ Fircosoft exception rules (support + confidence)

Country fields resolve to ISO 3166-1 alpha-2 by exact match only — fuzzy matching is deliberately avoided, since it silently resolves placeholder values like XX or NONE to real countries. Both fit and predict_batch validate every row and use the coerced result, so a numeric-string score actually reaches the model instead of leaving an object-dtype column behind.

Rule export contract

generate_fircosoft_rules() returns exception rules whose conditions mirror the discretizer's actual bin semantics — no Infinity in the JSON, no ambiguity about which edge is inclusive:

Operator	Meaning
`between`	`low < x <= high` — low-exclusive, high-inclusive, matching the miner's own bins
`>`	open-ended top bin, `x > value`
`<=`	open-ended bottom bin, `x <= value`
`==`	categorical/binary features, or a continuous feature too low-cardinality to bin

A rule ships only when support >= rule_mining.min_support and confidence >= rule_mining.min_confidence (default 0.99) — an exported rule permanently suppresses every future alert it matches, so the bar for exporting one is deliberately high.

Config keys

Key	Controls
`thresholds.auto_clear`	Probability at or above which `predict_batch` sets `auto_clear` (default 0.992)
`features.enabled`	Which transformers run: string distance, corporate-suffix normalization, geographic match, raw screening score
`rule_mining.min_support`	Minimum fraction of training alerts a rule must cover to be exported (default 0.02)
`rule_mining.max_depth`	Maximum conditions per mined rule (default 4)
`rule_mining.min_confidence`	Minimum fraction of a rule's covered alerts that analysts actually cleared (default 0.99)
`model.params`	Passed straight to `XGBClassifier` (default 200 estimators, depth 4, lr 0.05, seeded)

Quickstart

# Install:
pip install aegis-triage

# df needs PaymentAlertInput columns (+ disposition, for training)
from aegis.main import TriagePipeline

pipeline = TriagePipeline.from_config()      # packaged default config
pipeline.fit(df_train)
pipeline.generate_fircosoft_rules()          # IF-THEN rules for Fircosoft
pipeline.predict_batch(df_test)              # cleared_probability, SHAP, auto_clear

See example_usage.py for a full runnable example, and config.yaml for every tunable key.

Regulatory use: auto-clearing a sanctions alert is a regulated decision. This library ships no model-validation evidence — calibrate thresholds.auto_clear and rule_mining.min_confidence against your own labelled alert history, and have a human review every mined rule before it enters a Fircosoft exception list.

Roadmap

Done v0.1 — Schema layer, config layer, feature engineering (string distance, corporate suffix, geographic match), RIPPER rule miner, XGBoost + SHAP classifier, TriagePipeline API
Done Hardening — confidence-gated rule export, real ISO country matching, schema enforcement at the pipeline boundary, PII-safe validation errors, seeded/reproducible outputs, MIT-only dependency tree, CI, PyPI packaging
Planned v0.2 — persistence for a fitted pipeline (save/load for audit reproducibility), broader Python-version support as upstream wheels catch up