Merge pull request #63 from Anichris-koded/feat/025-active-learning

feat: implement active learning pipeline

Author: Inkman007

.env.example

@@ -10,6 +10,12 @@ WATCHED_ASSET_PAIRS=USDC:GA5Z...,XLM:native
 # Rolling window sizes (hours) used by the Benford engine
 BENFORD_WINDOWS_HOURS=1,4,24,168,720
 
+# Time window used when comparing transactions across asset pairs
+CROSS_PAIR_SYNCHRONY_WINDOW_SECONDS=30
+
+# Minimum trades required before scoring a wallet
+MIN_TRADES_FOR_SCORING=20
+
 # Risk score thresholds
 RISK_SCORE_FLAG_THRESHOLD=70
 
@@ -57,6 +63,8 @@ POISON_LABEL_RATIO_THRESHOLD=0.15
 # WARNING: Never commit this value to version control.
 ANNOTATION_HMAC_SECRET=
 
+ANNOTATION_HMAC_SECRET=
+
 # ---------------------------------------------------------------------------
 # Adversarial training (disabled by default)
 # ---------------------------------------------------------------------------
@@ -65,3 +73,23 @@ ANNOTATION_HMAC_SECRET=
 # --adversarial-augmentation is passed to detection/model_training.py.
 # 0.0 = disabled (default).  Typical useful range: 0.25–1.0.
 ADVERSARIAL_AUG_RATIO=0.0
+
+# ---------------------------------------------------------------------------
+# Active learning
+# ---------------------------------------------------------------------------
+
+# Query strategy for selecting wallets to annotate.
+# Options: least_confidence, margin, entropy, coreset, badge, committee_disagreement
+AL_QUERY_STRATEGY=committee_disagreement
+
+# Number of wallets to select per active learning run
+AL_BATCH_SIZE=20
+
+# Minimum new labelled samples to trigger a full retrain (vs warm-start)
+AL_RETRAIN_THRESHOLD=50
+
+# Maximum allowed AUC-ROC drop before rolling back a model update
+AL_ROLLBACK_AUC_DROP=0.01
+
+# Path to the annotation queue JSON file
+AL_QUEUE_PATH=data/annotation_queue.json

.github/workflows/active_learning.yml

@@ -0,0 +1,57 @@
+name: Active Learning Pipeline
+
+on:
+  schedule:
+    # Run every Monday at 08:00 UTC
+    - cron: "0 8 * * 1"
+  workflow_dispatch:
+    inputs:
+      strategy:
+        description: "Query strategy"
+        default: "committee_disagreement"
+        required: false
+      batch_size:
+        description: "Number of wallets to select"
+        default: "20"
+        required: false
+      pool_path:
+        description: "Path to unscored wallet parquet"
+        default: "data/unscored_wallets.parquet"
+        required: false
+
+jobs:
+  active-learning:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Run active learning loop
+        env:
+          AL_QUERY_STRATEGY: ${{ github.event.inputs.strategy || 'committee_disagreement' }}
+          AL_BATCH_SIZE: ${{ github.event.inputs.batch_size || '20' }}
+          AL_QUEUE_PATH: data/annotation_queue.json
+          ANNOTATION_HMAC_SECRET: ${{ secrets.ANNOTATION_HMAC_SECRET }}
+          MODEL_DIR: ${{ vars.MODEL_DIR || './models' }}
+        run: |
+          python -m scripts.run_active_learning \
+            --pool "${{ github.event.inputs.pool_path || 'data/unscored_wallets.parquet' }}" \
+            --strategy "$AL_QUERY_STRATEGY" \
+            --batch-size "$AL_BATCH_SIZE" \
+            --queue "$AL_QUEUE_PATH"
+
+      - name: Upload annotation queue artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: annotation-queue-${{ github.run_id }}
+          path: data/annotation_queue.json
+          retention-days: 30

.github/workflows/ci.yml

@@ -31,5 +31,29 @@ jobs:
           ruff check .
           black --check .
 
+      - name: Check verify_chain called after every joblib.load in detection/
+        run: |
+          python - <<'EOF'
+          import re, sys, pathlib
+
+          issues = []
+          for f in pathlib.Path("detection").rglob("*.py"):
+              lines = f.read_text().splitlines()
+              for i, line in enumerate(lines):
+                  if re.search(r"joblib\.load\(", line):
+                      # Check the next 5 lines for verify_chain
+                      window = "\n".join(lines[i : i + 6])
+                      if "verify_chain" not in window:
+                          issues.append(f"{f}:{i+1}: joblib.load without nearby verify_chain call")
+
+          if issues:
+              print("verify_chain enforcement failures:")
+              for issue in issues:
+                  print(" ", issue)
+              sys.exit(1)
+          else:
+              print("verify_chain check passed.")
+          EOF
+
       - name: Test
         run: pytest -q

README.md

@@ -328,6 +328,36 @@ See [`scripts/README.md`](scripts/README.md) for detailed usage of:
 - `retrain_if_drifted.py` — automated drift detection and retraining trigger
 - `list_model_versions.py` — list archived models with training dates and metrics
 
+## Active Learning
+
+LedgerLens includes an active learning pipeline that intelligently selects the most informative
+wallets for analyst annotation, minimising labelling effort while maximising model improvement.
+
+```bash
+# Populate the annotation queue (selects 20 wallets by committee disagreement):
+python -m scripts.run_active_learning --pool data/unscored_wallets.parquet
+
+# Annotate wallets interactively:
+python -m scripts.annotate --annotator-id yourname
+
+# Export annotations and update models:
+python -m scripts.annotate --export data/annotated.parquet
+python -m scripts.run_active_learning \
+    --pool data/unscored_wallets.parquet \
+    --update data/annotated.parquet
+```
+
+The pipeline runs automatically every Monday at 08:00 UTC via
+`.github/workflows/active_learning.yml`. See [`docs/active_learning.md`](docs/active_learning.md)
+for the full query strategy comparison, annotation workflow, and incremental update policy.
+
+| Variable | Default | Description |
+|---|---|---|
+| `AL_QUERY_STRATEGY` | `committee_disagreement` | Query strategy |
+| `AL_BATCH_SIZE` | `20` | Wallets selected per run |
+| `AL_RETRAIN_THRESHOLD` | `50` | Min labels for full retrain |
+| `AL_ROLLBACK_AUC_DROP` | `0.01` | Max AUC drop before rollback |
+
 ## Development
 
 ```bash
@@ -514,6 +544,33 @@ defines the relevant shared type before inventing a new one.
 - [ ] SDK for protocol integrations (Python + JavaScript)
 - [x] Open dataset release: labelled SDEX wash trade patterns — see [`data/dataset_card.md`](data/dataset_card.md)
 
+## Security
+
+LedgerLens includes a hardened inference stack to protect against adversarial attacks on the model layer itself. See [`docs/security.md`](docs/security.md) for full details.
+
+### Artifact Integrity (Ed25519 Trust Chain)
+
+Every trained model artifact is verified through a four-step chain before loading:
+
+1. SHA-256 of the `.joblib` file matches the value recorded in `metrics.json`
+2. `metrics.json` carries a valid Ed25519 detached signature (`metrics.json.sig`)
+3. The signing key fingerprint matches `TRUSTED_SIGNING_KEY_FINGERPRINT`
+4. The training dataset SHA-256 matches the recorded provenance (optional)
+
+`ModelIntegrityError` is raised on any failure. A CI grep check enforces that every `joblib.load` in `detection/` is immediately followed by `verify_chain`.
+
+### Byzantine-Fault-Tolerant Ensemble Voting
+
+The three models (RF, XGBoost, LightGBM) vote using a **trimmed mean / median** scheme. If the spread across model scores exceeds `BFT_SCORE_DIVERGENCE_THRESHOLD` (default 30 points), the outlier scores are trimmed and the median is used — ensuring a single compromised model cannot shift the final score by more than ~17 points. Divergence events are logged, counted in a Prometheus counter (`bft_divergence_detected_total`), and surfaced in the score response as `bft_divergence: true`.
+
+### Label Poisoning Detection
+
+Each training run records the SHA-256 of the input dataset and the label distribution. If the wash-trade ratio has shifted more than `POISON_LABEL_RATIO_THRESHOLD` (default 15%) from the stored baseline, training is aborted and an alert is written to `reports/poisoning_alert_{timestamp}.json`.
+
+### Annotation Queue Integrity
+
+Each annotation in `data/annotation_queue.json` is protected by an HMAC-SHA256 computed over `wallet|label|annotator_id|annotated_at`, keyed by `ANNOTATION_HMAC_SECRET`. Tampered annotations are rejected before they can influence a training run.
+
 ## Why This Matters
 
 A DEX where volume figures cannot be trusted is one that institutional participants and serious traders will avoid. LedgerLens is an **open-source public good** — its scores, methodology, and training data are fully transparent and auditable, and will always be free to query.

config.py

@@ -65,9 +65,24 @@ def validate(self, require_onchain: bool = True) -> None:
             raise ValueError("LEDGERLENS_CONTRACT_ID is not configured")
 
     # Adversarial training augmentation
-    # Ratio of adversarially-perturbed copies to add per clean training sample.
-    # Only active when --adversarial-augmentation flag is passed to model_training.py.
     ADVERSARIAL_AUG_RATIO: float = float(os.getenv("ADVERSARIAL_AUG_RATIO", "0.0"))
 
+    # Model integrity & BFT voting
+    MODEL_SIGNING_PRIVATE_KEY_PATH: str = os.getenv("MODEL_SIGNING_PRIVATE_KEY_PATH", "")
+    TRUSTED_SIGNING_KEY_FINGERPRINT: str = os.getenv("TRUSTED_SIGNING_KEY_FINGERPRINT", "")
+    BFT_SCORE_DIVERGENCE_THRESHOLD: int = int(os.getenv("BFT_SCORE_DIVERGENCE_THRESHOLD", "30"))
+    BFT_MIN_CONSENSUS: int = int(os.getenv("BFT_MIN_CONSENSUS", "2"))
+    POISON_LABEL_RATIO_THRESHOLD: float = float(os.getenv("POISON_LABEL_RATIO_THRESHOLD", "0.15"))
+
+    # Annotation integrity
+    ANNOTATION_HMAC_SECRET: str = os.getenv("ANNOTATION_HMAC_SECRET", "")
+
+    # Active learning
+    AL_QUERY_STRATEGY: str = os.getenv("AL_QUERY_STRATEGY", "committee_disagreement")
+    AL_BATCH_SIZE: int = int(os.getenv("AL_BATCH_SIZE", "20"))
+    AL_RETRAIN_THRESHOLD: int = int(os.getenv("AL_RETRAIN_THRESHOLD", "50"))
+    AL_ROLLBACK_AUC_DROP: float = float(os.getenv("AL_ROLLBACK_AUC_DROP", "0.01"))
+    AL_QUEUE_PATH: str = os.getenv("AL_QUEUE_PATH", "data/annotation_queue.json")
+
 
 config = Config()

detection/active_learning/__init__.py

@@ -0,0 +1,7 @@
+"""Active learning package for LedgerLens."""
+
+from detection.active_learning.annotation_queue import AnnotationQueue
+from detection.active_learning.incremental_trainer import IncrementalTrainer
+from detection.active_learning.query_strategies import STRATEGY_REGISTRY, get_strategy
+
+__all__ = ["AnnotationQueue", "IncrementalTrainer", "STRATEGY_REGISTRY", "get_strategy"]