feat: implement active learning pipeline (#40)

- Add 6 query strategies (LeastConfidence, Margin, Entropy, CoreSet, BADGE, CommitteeDisagreement)
- Add AnnotationQueue with push/pop_batch/annotate/export_labelled, atomic writes, HMAC integrity, 0o600 permissions
- Add IncrementalTrainer with warm-start / full-retrain paths, AUC-based rollback with SHA-256 verification
- Add scripts/annotate.py interactive CLI annotation loop
- Add scripts/run_active_learning.py integration loop (weekly via GitHub Actions)
- Add .github/workflows/active_learning.yml (every Monday 08:00 UTC)
- Add docs/active_learning.md: strategy comparison, annotation workflow, update policy
- Update config.py with AL_QUERY_STRATEGY, AL_BATCH_SIZE, AL_RETRAIN_THRESHOLD, AL_ROLLBACK_AUC_DROP, AL_QUEUE_PATH
- Update .env.example and README.md with active learning section
- Add tests/test_query_strategies.py (23 tests), test_annotation_queue.py (22 tests), test_incremental_trainer.py (7 tests)
- All 116 tests pass, make lint clean

Closes #40

Author: Anichris-koded

.env.example

@@ -63,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)
 # ---------------------------------------------------------------------------

.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

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

detection/active_learning/__init__.py

@@ -1 +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"]