Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends     gcc     && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install CPU-only PyTorch first (smaller)
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
+
+# Install remaining dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY app/ ./app/
+COPY src/ ./src/
+COPY results/ ./results/
+COPY app_wrapper.py .
+
+# Create models directory (will be populated at runtime)
+RUN mkdir -p models
+
+# HF Spaces expects port 7860
+EXPOSE 7860
+
+# Run the wrapper that downloads models then starts uvicorn
+CMD ["python", "app_wrapper.py"]

README.md

@@ -1,10 +1,31 @@
 ---
-title: Panacea Api
-emoji: 🐢
-colorFrom: yellow
-colorTo: gray
+title: Panacea Satellite Collision Avoidance API
+colorFrom: indigo
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Panacea -- Satellite Collision Avoidance API
+
+FastAPI backend for the Panacea satellite collision avoidance system.
+
+## Endpoints
+
+- `GET /api/health` -- Health check, lists loaded models
+- `POST /api/predict-conjunction` -- Run inference on a CDM sequence
+- `GET /api/model-comparison` -- Pre-computed model comparison results
+- `GET /api/experiment-results` -- Staleness experiment results
+- `POST /api/bulk-screen` -- Screen TLE pairs for potential conjunctions
+
+## Models
+
+Three models are loaded at startup from [DTanzillo/panacea-models](https://huggingface.co/DTanzillo/panacea-models):
+
+1. **Baseline** -- Orbital shell density prior (AUC-PR: 0.061)
+2. **XGBoost** -- Classical ML on engineered CDM features (AUC-PR: 0.988)
+3. **PI-TFT** -- Physics-Informed Temporal Fusion Transformer (AUC-PR: 0.511)
+
+Built for AIPI 540 (Duke University).

app/__init__.py

@@ -0,0 +1 @@
+# Generated by Claude Code -- 2026-02-13

app/main.py

@@ -0,0 +1,481 @@
+# Generated by Claude Code -- 2026-02-13
+"""FastAPI backend for Panacea collision avoidance inference."""
+
+import json
+import os
+import numpy as np
+import torch
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+import sys
+
+ROOT = Path(__file__).parent.parent
+sys.path.insert(0, str(ROOT))
+
+from src.model.baseline import OrbitalShellBaseline
+from src.model.classical import XGBoostConjunctionModel
+from src.model.deep import PhysicsInformedTFT
+from src.model.triage import classify_urgency
+from src.data.sequence_builder import TEMPORAL_FEATURES, STATIC_FEATURES, MAX_SEQ_LEN
+
+HF_REPO_ID = "DTanzillo/panacea-models"
+
+# Global model storage
+models = {}
+
+
+def download_models_from_hf(model_dir: Path, results_dir: Path):
+    """Download models from HuggingFace Hub if not available locally."""
+    try:
+        from huggingface_hub import snapshot_download
+        token = os.environ.get("HF_TOKEN")
+        local = snapshot_download(
+            HF_REPO_ID,
+            token=token,
+            allow_patterns=["models/*", "results/*"],
+        )
+        local = Path(local)
+        # Copy files to expected locations
+        for src in (local / "models").iterdir():
+            dst = model_dir / src.name
+            if not dst.exists():
+                import shutil
+                shutil.copy2(src, dst)
+                print(f"  Downloaded {src.name} from HF Hub")
+        for src in (local / "results").iterdir():
+            dst = results_dir / src.name
+            if not dst.exists():
+                import shutil
+                shutil.copy2(src, dst)
+                print(f"  Downloaded {src.name} from HF Hub")
+    except Exception as e:
+        print(f"  HF Hub download skipped: {e}")
+
+
+def load_models():
+    """Load all 3 models at startup. Downloads from HF Hub if missing."""
+    model_dir = ROOT / "models"
+    results_dir = ROOT / "results"
+    model_dir.mkdir(exist_ok=True)
+    results_dir.mkdir(exist_ok=True)
+
+    # Try downloading from HF Hub if local models are missing
+    if not (model_dir / "baseline.json").exists():
+        print("  Local models not found, trying HuggingFace Hub...")
+        download_models_from_hf(model_dir, results_dir)
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+    baseline_path = model_dir / "baseline.json"
+    if baseline_path.exists():
+        models["baseline"] = OrbitalShellBaseline.load(baseline_path)
+        print("  Loaded baseline model")
+
+    xgboost_path = model_dir / "xgboost.pkl"
+    if xgboost_path.exists():
+        models["xgboost"] = XGBoostConjunctionModel.load(xgboost_path)
+        print("  Loaded XGBoost model")
+
+    pitft_path = model_dir / "transformer.pt"
+    if pitft_path.exists():
+        checkpoint = torch.load(pitft_path, map_location=device, weights_only=False)
+        config = checkpoint["config"]
+
+        model = PhysicsInformedTFT(
+            n_temporal_features=config["n_temporal"],
+            n_static_features=config["n_static"],
+            d_model=config.get("d_model", 128),
+            n_heads=config.get("n_heads", 4),
+            n_layers=config.get("n_layers", 2),
+        ).to(device)
+        # strict=False for backward compat: old checkpoints lack pc_head weights
+        model.load_state_dict(checkpoint["model_state"], strict=False)
+        model.eval()
+
+        models["pitft"] = model
+        models["pitft_checkpoint"] = checkpoint
+        models["pitft_device"] = device
+        temp = checkpoint.get("temperature", 1.0)
+        has_pc = checkpoint.get("has_pc_head", False)
+        print(f"  Loaded PI-TFT (epoch {checkpoint['epoch']}, T={temp:.3f}, pc_head={'yes' if has_pc else 'no'})")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    print("Loading models ...")
+    load_models()
+    loaded = [k for k in models if not k.startswith("pitft_")]
+    print(f"Models loaded: {loaded}")
+    yield
+    models.clear()
+
+
+app = FastAPI(
+    title="Panacea — Satellite Collision Avoidance API",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# --- Pydantic models ---
+
+class CDMFeatures(BaseModel):
+    """A sequence of CDM feature snapshots for one conjunction event."""
+    event_id: Optional[int] = None
+    cdm_sequence: list[dict]
+
+
+class BulkScreenRequest(BaseModel):
+    """TLE data for pairwise screening."""
+    tles: list[dict]
+    top_k: int = 10
+
+
+# --- Endpoints ---
+
+@app.get("/api/health")
+async def health():
+    loaded = []
+    if "baseline" in models:
+        loaded.append("baseline")
+    if "xgboost" in models:
+        loaded.append("xgboost")
+    if "pitft" in models:
+        loaded.append("pitft")
+
+    device = str(models.get("pitft_device", "cpu"))
+    return {
+        "status": "healthy",
+        "models_loaded": loaded,
+        "device": device,
+        "n_models": len(loaded),
+    }
+
+
+@app.post("/api/predict-conjunction")
+async def predict_conjunction(features: CDMFeatures):
+    """Run inference on a single conjunction event across all loaded models."""
+    results = {}
+    cdm_seq = features.cdm_sequence
+    if not cdm_seq:
+        return {"error": "Empty CDM sequence"}
+
+    last_cdm = cdm_seq[-1]
+    altitude = last_cdm.get("t_h_apo", last_cdm.get("c_h_apo", 500.0))
+
+    # Baseline prediction
+    if "baseline" in models:
+        risk_probs, miss_preds = models["baseline"].predict(np.array([altitude]))
+        triage = classify_urgency(float(risk_probs[0]))
+        results["baseline"] = {
+            "risk_probability": float(risk_probs[0]),
+            "miss_distance_km": float(np.expm1(miss_preds[0])),
+            "triage": {
+                "tier": triage.tier.value,
+                "color": triage.color,
+                "recommendation": triage.recommendation,
+            },
+        }
+
+    # XGBoost prediction
+    if "xgboost" in models:
+        xgb_features = _build_xgboost_features(cdm_seq)
+        risk_probs, miss_km = models["xgboost"].predict(xgb_features)
+        triage = classify_urgency(float(risk_probs[0]))
+        results["xgboost"] = {
+            "risk_probability": float(risk_probs[0]),
+            "miss_distance_km": float(miss_km[0]),
+            "triage": {
+                "tier": triage.tier.value,
+                "color": triage.color,
+                "recommendation": triage.recommendation,
+            },
+        }
+
+    # PI-TFT prediction
+    if "pitft" in models:
+        risk_prob, miss_log, pc_log10 = _run_pitft_inference(cdm_seq)
+        triage = classify_urgency(risk_prob)
+        results["pitft"] = {
+            "risk_probability": risk_prob,
+            "miss_distance_km": float(np.expm1(miss_log)),
+            "collision_probability": float(10 ** pc_log10),
+            "collision_probability_log10": pc_log10,
+            "triage": {
+                "tier": triage.tier.value,
+                "color": triage.color,
+                "recommendation": triage.recommendation,
+            },
+        }
+
+    return results
+
+
+@app.get("/api/model-comparison")
+async def model_comparison():
+    """Return pre-computed model comparison results."""
+    results = []
+
+    comparison_path = ROOT / "results" / "model_comparison.json"
+    if comparison_path.exists():
+        with open(comparison_path) as f:
+            results = json.load(f)
+
+    deep_path = ROOT / "results" / "deep_model_results.json"
+    if deep_path.exists():
+        with open(deep_path) as f:
+            deep = json.load(f)
+        pitft_entry = {
+            "model": deep["model"],
+            **deep["test"],
+        }
+        results.append(pitft_entry)
+
+    return results
+
+
+@app.get("/api/experiment-results")
+async def experiment_results():
+    """Return staleness experiment results."""
+    exp_path = ROOT / "results" / "staleness_experiment.json"
+    if exp_path.exists():
+        with open(exp_path) as f:
+            return json.load(f)
+    return {"error": "No experiment results found. Run: python scripts/run_experiment.py"}
+
+
+@app.post("/api/bulk-screen")
+async def bulk_screen(request: BulkScreenRequest):
+    """Screen TLE pairs for potential conjunctions using orbital filtering."""
+    tles = request.tles
+    top_k = request.top_k
+
+    if len(tles) < 2:
+        return {"pairs": [], "n_candidates": 0, "n_total": len(tles)}
+
+    n = len(tles)
+    names = [t.get("OBJECT_NAME", f"Object {i}") for i, t in enumerate(tles)]
+    norad_ids = [t.get("NORAD_CAT_ID", 0) for t in tles]
+
+    # Compute altitude from mean motion: a = (mu / n^2)^(1/3), alt = a - R_earth
+    MU = 398600.4418  # km^3/s^2
+    R_EARTH = 6371.0  # km
+
+    mean_motions = np.array([t.get("MEAN_MOTION", 15.0) for t in tles])
+    n_rad = mean_motions * 2 * np.pi / 86400.0
+    n_rad = np.clip(n_rad, 1e-10, None)
+    sma = (MU / (n_rad ** 2)) ** (1.0 / 3.0)
+
+    eccentricities = np.array([t.get("ECCENTRICITY", 0.0) for t in tles])
+    apogee = sma * (1 + eccentricities) - R_EARTH
+    perigee = sma * (1 - eccentricities) - R_EARTH
+
+    raan = np.array([t.get("RA_OF_ASC_NODE", 0.0) for t in tles])
+
+    # Pairwise filtering via broadcasting
+    alt_overlap = ((apogee[:, None] >= perigee[None, :]) &
+                   (apogee[None, :] >= perigee[:, None]))
+
+    raan_diff = np.abs(raan[:, None] - raan[None, :])
+    raan_diff = np.minimum(raan_diff, 360.0 - raan_diff)
+    raan_close = raan_diff < 30.0
+
+    candidates = alt_overlap & raan_close
+    np.fill_diagonal(candidates, False)
+    candidates = np.triu(candidates, k=1)
+
+    pairs_i, pairs_j = np.where(candidates)
+
+    if len(pairs_i) == 0:
+        return {"pairs": [], "n_candidates": 0, "n_total": n}
+
+    # Score candidates using baseline model
+    if "baseline" in models:
+        pair_altitudes = (apogee[pairs_i] + apogee[pairs_j]) / 2.0
+        risk_scores, miss_estimates = models["baseline"].predict(pair_altitudes)
+    else:
+        risk_scores = np.ones(len(pairs_i)) * 0.5
+        miss_estimates = np.zeros(len(pairs_i))
+
+    top_indices = np.argsort(-risk_scores)[:top_k]
+
+    result_pairs = []
+    for idx in top_indices:
+        i, j = int(pairs_i[idx]), int(pairs_j[idx])
+        result_pairs.append({
+            "name_1": names[i],
+            "name_2": names[j],
+            "norad_1": norad_ids[i],
+            "norad_2": norad_ids[j],
+            "risk_score": float(risk_scores[idx]),
+            "altitude_km": float((apogee[i] + apogee[j]) / 2),
+            "miss_estimate_km": (float(np.expm1(miss_estimates[idx]))
+                                 if miss_estimates[idx] > 0 else 0.0),
+        })
+
+    return {
+        "pairs": result_pairs,
+        "n_candidates": int(len(pairs_i)),
+        "n_total": n,
+    }
+
+
+# --- Helper functions ---
+
+def _build_xgboost_features(cdm_sequence: list[dict]) -> np.ndarray:
+    """Build XGBoost feature vector from a CDM sequence (dict format).
+
+    Replicates events_to_flat_features() logic for a single event.
+    """
+    last = cdm_sequence[-1]
+
+    exclude = {"event_id", "time_to_tca", "risk", "mission_id"}
+    feature_keys = sorted([
+        k for k in last.keys()
+        if isinstance(last.get(k), (int, float)) and k not in exclude
+    ])
+
+    base = np.array([float(last.get(k, 0.0)) for k in feature_keys], dtype=np.float32)
+
+    miss_values = np.array([float(s.get("miss_distance", 0.0)) for s in cdm_sequence])
+    risk_values = np.array([float(s.get("risk", -10.0)) for s in cdm_sequence])
+    tca_values = np.array([float(s.get("time_to_tca", 0.0)) for s in cdm_sequence])
+
+    n_cdms = len(cdm_sequence)
+    miss_mean = float(np.mean(miss_values))
+    miss_std = float(np.std(miss_values)) if n_cdms > 1 else 0.0
+
+    miss_trend = 0.0
+    if n_cdms > 1 and np.std(tca_values) > 0:
+        miss_trend = float(np.polyfit(tca_values, miss_values, 1)[0])
+
+    risk_trend = 0.0
+    if n_cdms > 1 and np.std(tca_values) > 0:
+        risk_trend = float(np.polyfit(tca_values, risk_values, 1)[0])
+
+    temporal_feats = np.array([
+        n_cdms,
+        miss_mean,
+        miss_std,
+        miss_trend,
+        risk_trend,
+        float(miss_values[0] - miss_values[-1]) if n_cdms > 1 else 0.0,
+        float(last.get("time_to_tca", 0.0)),
+        float(last.get("relative_speed", 0.0)),
+    ], dtype=np.float32)
+
+    combined = np.concatenate([base, temporal_feats])
+    combined = np.nan_to_num(combined, nan=0.0, posinf=0.0, neginf=0.0)
+    X = combined.reshape(1, -1)
+
+    # Pad features if model was trained on augmented data with more columns
+    if "xgboost" in models:
+        expected = models["xgboost"].scaler.n_features_in_
+        if X.shape[1] < expected:
+            padding = np.zeros((X.shape[0], expected - X.shape[1]), dtype=X.dtype)
+            X = np.hstack([X, padding])
+        elif X.shape[1] > expected:
+            X = X[:, :expected]
+
+    return X
+
+
+def _run_pitft_inference(cdm_sequence: list[dict]) -> tuple[float, float, float]:
+    """Run PI-TFT inference on a single CDM sequence.
+
+    Returns: (risk_probability, miss_log)
+    """
+    checkpoint = models["pitft_checkpoint"]
+    device = models["pitft_device"]
+    model = models["pitft"]
+    norm = checkpoint["normalization"]
+    temperature = checkpoint.get("temperature", 1.0)
+    temporal_cols = checkpoint.get("temporal_cols", TEMPORAL_FEATURES)
+    static_cols = checkpoint.get("static_cols", STATIC_FEATURES)
+
+    # Extract temporal features: (S, F_t)
+    temporal = np.array([
+        [float(cdm.get(col, 0.0)) for col in temporal_cols]
+        for cdm in cdm_sequence
+    ], dtype=np.float32)
+    temporal = np.nan_to_num(temporal, nan=0.0, posinf=0.0, neginf=0.0)
+
+    # Compute deltas
+    if len(temporal) > 1:
+        deltas = np.diff(temporal, axis=0)
+        deltas = np.concatenate(
+            [np.zeros((1, deltas.shape[1]), dtype=np.float32), deltas], axis=0
+        )
+    else:
+        deltas = np.zeros_like(temporal)
+
+    # Normalize
+    t_mean = np.array(norm["temporal_mean"], dtype=np.float32)
+    t_std = np.array(norm["temporal_std"], dtype=np.float32)
+    d_mean = np.array(norm["delta_mean"], dtype=np.float32)
+    d_std = np.array(norm["delta_std"], dtype=np.float32)
+    s_mean = np.array(norm["static_mean"], dtype=np.float32)
+    s_std = np.array(norm["static_std"], dtype=np.float32)
+
+    temporal = (temporal - t_mean) / t_std
+    deltas = (deltas - d_mean) / d_std
+    temporal = np.concatenate([temporal, deltas], axis=1)
+
+    # Static features from last CDM
+    last_cdm = cdm_sequence[-1]
+    static = np.array(
+        [float(last_cdm.get(col, 0.0)) for col in static_cols], dtype=np.float32
+    )
+    static = np.nan_to_num(static, nan=0.0, posinf=0.0, neginf=0.0)
+    static = (static - s_mean) / s_std
+
+    # Time-to-TCA
+    tca_mean = norm["tca_mean"]
+    tca_std = norm["tca_std"]
+    tca = np.array(
+        [float(cdm.get("time_to_tca", 0.0)) for cdm in cdm_sequence], dtype=np.float32
+    ).reshape(-1, 1)
+    tca = (tca - tca_mean) / tca_std
+
+    # Pad/truncate to MAX_SEQ_LEN
+    seq_len = len(temporal)
+    if seq_len > MAX_SEQ_LEN:
+        temporal = temporal[-MAX_SEQ_LEN:]
+        tca = tca[-MAX_SEQ_LEN:]
+        seq_len = MAX_SEQ_LEN
+
+    pad_len = MAX_SEQ_LEN - seq_len
+    if pad_len > 0:
+        temporal = np.pad(temporal, ((pad_len, 0), (0, 0)), constant_values=0)
+        tca = np.pad(tca, ((pad_len, 0), (0, 0)), constant_values=0)
+
+    mask = np.zeros(MAX_SEQ_LEN, dtype=bool)
+    mask[pad_len:] = True
+
+    # Convert to tensors
+    temporal_t = torch.tensor(temporal, dtype=torch.float32).unsqueeze(0).to(device)
+    static_t = torch.tensor(static, dtype=torch.float32).unsqueeze(0).to(device)
+    tca_t = torch.tensor(tca, dtype=torch.float32).unsqueeze(0).to(device)
+    mask_t = torch.tensor(mask, dtype=torch.bool).unsqueeze(0).to(device)
+
+    with torch.no_grad():
+        risk_logit, miss_log, pc_log10, _ = model(temporal_t, static_t, tca_t, mask_t)
+
+    risk_prob = float(torch.sigmoid(risk_logit / temperature).cpu().item())
+    miss_log_val = float(miss_log.cpu().item())
+    pc_log10_val = float(pc_log10.cpu().item())
+
+    return risk_prob, miss_log_val, pc_log10_val

app_wrapper.py

@@ -0,0 +1,80 @@
+"""Startup wrapper for HuggingFace Spaces deployment.
+
+Downloads models from DTanzillo/panacea-models on first run,
+then starts the FastAPI application on port 7860.
+"""
+
+import os
+import sys
+import shutil
+from pathlib import Path
+
+# Ensure the app root is on the Python path
+ROOT = Path(__file__).parent
+sys.path.insert(0, str(ROOT))
+
+
+def download_models():
+    """Download models from HuggingFace Hub if not present locally."""
+    model_dir = ROOT / "models"
+    results_dir = ROOT / "results"
+    model_dir.mkdir(exist_ok=True)
+    results_dir.mkdir(exist_ok=True)
+
+    # Check if models already exist
+    needed_files = ["baseline.json", "xgboost.pkl", "transformer.pt"]
+    all_present = all((model_dir / f).exists() for f in needed_files)
+
+    if all_present:
+        print("Models already present, skipping download.")
+        return
+
+    print("Downloading models from DTanzillo/panacea-models ...")
+    try:
+        from huggingface_hub import snapshot_download
+
+        token = os.environ.get("HF_TOKEN")
+        local = Path(snapshot_download(
+            "DTanzillo/panacea-models",
+            token=token,
+            allow_patterns=["models/*", "results/*"],
+        ))
+
+        # Copy model files
+        hf_models = local / "models"
+        if hf_models.exists():
+            for src_file in hf_models.iterdir():
+                dst_file = model_dir / src_file.name
+                if not dst_file.exists():
+                    shutil.copy2(src_file, dst_file)
+                    print(f"  Copied {src_file.name}")
+
+        # Copy result files (only if missing)
+        hf_results = local / "results"
+        if hf_results.exists():
+            for src_file in hf_results.iterdir():
+                dst_file = results_dir / src_file.name
+                if not dst_file.exists():
+                    shutil.copy2(src_file, dst_file)
+                    print(f"  Copied result: {src_file.name}")
+
+        print("Model download complete.")
+    except Exception as e:
+        print(f"WARNING: Model download failed: {e}")
+        print("The API will start but models may not be available.")
+
+
+if __name__ == "__main__":
+    # Step 1: Download models
+    download_models()
+
+    # Step 2: Start uvicorn
+    import uvicorn
+    port = int(os.environ.get("PORT", 7860))
+    print(f"Starting Panacea API on port {port} ...")
+    uvicorn.run(
+        "app.main:app",
+        host="0.0.0.0",
+        port=port,
+        log_level="info",
+    )

requirements.txt

@@ -0,0 +1,7 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+xgboost==2.1.4
+scikit-learn==1.6.1
+pandas==2.2.3
+numpy==2.2.2
+huggingface-hub>=0.27.0

results/deep_model_results.json

@@ -0,0 +1,670 @@
+{
+  "model": "PI-TFT (Physics-Informed Temporal Fusion Transformer)",
+  "best_epoch": 36,
+  "training_time_minutes": 13.175001474221547,
+  "optimal_threshold": 0.2639383375644684,
+  "temperature": 0.6179193258285522,
+  "use_density": true,
+  "test": {
+    "loss": 0.021245601093944383,
+    "auc_pr": 0.5076785607710974,
+    "auc_roc": 0.946749355627952,
+    "f1_at_50": 0.0,
+    "n_positive": 73,
+    "n_total": 2167,
+    "pos_rate": 0.03368712589144707,
+    "f1": 0.5185185137773299,
+    "optimal_threshold": 0.2639383375644684,
+    "threshold": 0.2639383375644684,
+    "recall_at_prec_30": 0.7808219178082192,
+    "recall_at_prec_50": 0.4931506849315068,
+    "recall_at_prec_70": 0.2876712328767123,
+    "mae_log": 0.10174570232629776,
+    "rmse_log": 0.15394317551905587,
+    "mae_km": 1533.616943359375,
+    "median_abs_error_km": 926.875
+  },
+  "test_calibrated": {
+    "auc_pr": 0.5076785607710974,
+    "auc_roc": 0.946749355627952,
+    "f1_at_50": 0.0,
+    "n_positive": 73,
+    "n_total": 2167,
+    "pos_rate": 0.03368712589144707,
+    "f1": 0.5185185137773299,
+    "optimal_threshold": 0.15979407727718353,
+    "threshold": 0.15979407727718353,
+    "recall_at_prec_30": 0.7808219178082192,
+    "recall_at_prec_50": 0.4931506849315068,
+    "recall_at_prec_70": 0.2876712328767123
+  },
+  "history": [
+    {
+      "epoch": 1,
+      "train_loss": 6.801268232190931,
+      "val_loss": 5.25680010659354,
+      "val_auc_pr": 0.007896529454622946,
+      "val_f1": 0.019323671026161646,
+      "val_mae_log": 7.11151123046875
+    },
+    {
+      "epoch": 2,
+      "train_loss": 3.834329532932591,
+      "val_loss": 2.7224787643977573,
+      "val_auc_pr": 0.010594418921027337,
+      "val_f1": 0.023529411193771638,
+      "val_mae_log": 5.041237831115723
+    },
+    {
+      "epoch": 3,
+      "train_loss": 1.955074778118649,
+      "val_loss": 1.1283516032355172,
+      "val_auc_pr": 0.008480584727743306,
+      "val_f1": 0.021505376131344667,
+      "val_mae_log": 3.112034797668457
+    },
+    {
+      "epoch": 4,
+      "train_loss": 0.6309667991625296,
+      "val_loss": 0.2000983421291624,
+      "val_auc_pr": 0.047413803659580166,
+      "val_f1": 0.11764705467128042,
+      "val_mae_log": 1.1961653232574463
+    },
+    {
+      "epoch": 5,
+      "train_loss": 0.13499785540877163,
+      "val_loss": 0.02656353052173342,
+      "val_auc_pr": 0.05766442486817594,
+      "val_f1": 0.15999999680000007,
+      "val_mae_log": 0.29869771003723145
+    },
+    {
+      "epoch": 6,
+      "train_loss": 0.07689017317182309,
+      "val_loss": 0.02750414184161595,
+      "val_auc_pr": 0.134885373440643,
+      "val_f1": 0.27272726921487606,
+      "val_mae_log": 0.3075650930404663
+    },
+    {
+      "epoch": 7,
+      "train_loss": 0.08175783813805193,
+      "val_loss": 0.07211375555821828,
+      "val_auc_pr": 0.18529914529914526,
+      "val_f1": 0.4285714239795918,
+      "val_mae_log": 0.6812126040458679
+    },
+    {
+      "epoch": 8,
+      "train_loss": 0.07750273872468923,
+      "val_loss": 0.027415024914911816,
+      "val_auc_pr": 0.13237697916045849,
+      "val_f1": 0.3157894698060942,
+      "val_mae_log": 0.35104697942733765
+    },
+    {
+      "epoch": 9,
+      "train_loss": 0.06653158048520218,
+      "val_loss": 0.01911477212394987,
+      "val_auc_pr": 0.20693184703085693,
+      "val_f1": 0.374999995703125,
+      "val_mae_log": 0.2960411608219147
+    },
+    {
+      "epoch": 10,
+      "train_loss": 0.0626621154917253,
+      "val_loss": 0.020604882389307022,
+      "val_auc_pr": 0.3348872180451128,
+      "val_f1": 0.5454545404958678,
+      "val_mae_log": 0.23688556253910065
+    },
+    {
+      "epoch": 11,
+      "train_loss": 0.0617836594581604,
+      "val_loss": 0.012763384197439467,
+      "val_auc_pr": 0.1294155844155844,
+      "val_f1": 0.22222221920438956,
+      "val_mae_log": 0.1817978173494339
+    },
+    {
+      "epoch": 12,
+      "train_loss": 0.05554375463240856,
+      "val_loss": 0.01185049262962171,
+      "val_auc_pr": 0.24263038548752833,
+      "val_f1": 0.36363635867768596,
+      "val_mae_log": 0.15147316455841064
+    },
+    {
+      "epoch": 13,
+      "train_loss": 0.05319682077781574,
+      "val_loss": 0.017937806567975452,
+      "val_auc_pr": 0.2786109128966272,
+      "val_f1": 0.33333333055555564,
+      "val_mae_log": 0.21772687137126923
+    },
+    {
+      "epoch": 14,
+      "train_loss": 0.05603743799634882,
+      "val_loss": 0.012255215285612004,
+      "val_auc_pr": 0.1654839208410637,
+      "val_f1": 0.3076923029585799,
+      "val_mae_log": 0.12889182567596436
+    },
+    {
+      "epoch": 15,
+      "train_loss": 0.052231158416818926,
+      "val_loss": 0.008827194571495056,
+      "val_auc_pr": 0.30569487983281085,
+      "val_f1": 0.4705882311418686,
+      "val_mae_log": 0.11871597170829773
+    },
+    {
+      "epoch": 16,
+      "train_loss": 0.050459702796227225,
+      "val_loss": 0.006688231070126806,
+      "val_auc_pr": 0.3174495864073329,
+      "val_f1": 0.33333333055555564,
+      "val_mae_log": 0.11670727282762527
+    },
+    {
+      "epoch": 17,
+      "train_loss": 0.05048987201943591,
+      "val_loss": 0.012136828287371568,
+      "val_auc_pr": 0.209023569023569,
+      "val_f1": 0.3529411723183391,
+      "val_mae_log": 0.15395033359527588
+    },
+    {
+      "epoch": 18,
+      "train_loss": 0.05087649694367035,
+      "val_loss": 0.007568871269800833,
+      "val_auc_pr": 0.2673856209150327,
+      "val_f1": 0.3999999962500001,
+      "val_mae_log": 0.1411171853542328
+    },
+    {
+      "epoch": 19,
+      "train_loss": 0.050642090935159374,
+      "val_loss": 0.0066412134495164666,
+      "val_auc_pr": 0.27475908192734455,
+      "val_f1": 0.3999999955555556,
+      "val_mae_log": 0.0915408581495285
+    },
+    {
+      "epoch": 20,
+      "train_loss": 0.04991532632628003,
+      "val_loss": 0.0055730888686542,
+      "val_auc_pr": 0.24940384615384617,
+      "val_f1": 0.33333332932098775,
+      "val_mae_log": 0.10347151011228561
+    },
+    {
+      "epoch": 21,
+      "train_loss": 0.049406778288854133,
+      "val_loss": 0.008397463309977735,
+      "val_auc_pr": 0.22877207681961503,
+      "val_f1": 0.2857142816326531,
+      "val_mae_log": 0.15620921552181244
+    },
+    {
+      "epoch": 22,
+      "train_loss": 0.04929839575008766,
+      "val_loss": 0.0075396452365177015,
+      "val_auc_pr": 0.3359158185268243,
+      "val_f1": 0.33333333055555564,
+      "val_mae_log": 0.11639901250600815
+    },
+    {
+      "epoch": 23,
+      "train_loss": 0.04896112705606061,
+      "val_loss": 0.007832049591732877,
+      "val_auc_pr": 0.3431446821152704,
+      "val_f1": 0.36363636012396694,
+      "val_mae_log": 0.10894307494163513
+    },
+    {
+      "epoch": 24,
+      "train_loss": 0.048813931744646384,
+      "val_loss": 0.0061542981836412635,
+      "val_auc_pr": 0.3559577677224736,
+      "val_f1": 0.36363636012396694,
+      "val_mae_log": 0.07847719639539719
+    },
+    {
+      "epoch": 25,
+      "train_loss": 0.04768835706888019,
+      "val_loss": 0.006223144009709358,
+      "val_auc_pr": 0.3659761291340239,
+      "val_f1": 0.421052627700831,
+      "val_mae_log": 0.14390207827091217
+    },
+    {
+      "epoch": 26,
+      "train_loss": 0.04840076712740434,
+      "val_loss": 0.0067752449374113765,
+      "val_auc_pr": 0.2586657651566374,
+      "val_f1": 0.34782608355387534,
+      "val_mae_log": 0.1449323147535324
+    },
+    {
+      "epoch": 27,
+      "train_loss": 0.047609428044509246,
+      "val_loss": 0.0065139371103474075,
+      "val_auc_pr": 0.34384112619406737,
+      "val_f1": 0.34782608355387534,
+      "val_mae_log": 0.09073375165462494
+    },
+    {
+      "epoch": 28,
+      "train_loss": 0.04662630880201185,
+      "val_loss": 0.006256445976240295,
+      "val_auc_pr": 0.33832141293241863,
+      "val_f1": 0.33333333055555564,
+      "val_mae_log": 0.07596895098686218
+    },
+    {
+      "epoch": 29,
+      "train_loss": 0.04634691820152708,
+      "val_loss": 0.005017333896830678,
+      "val_auc_pr": 0.336514012303486,
+      "val_f1": 0.33333333055555564,
+      "val_mae_log": 0.07677556574344635
+    },
+    {
+      "epoch": 30,
+      "train_loss": 0.04663669626052315,
+      "val_loss": 0.004762223763723991,
+      "val_auc_pr": 0.24682988580047405,
+      "val_f1": 0.36363636012396694,
+      "val_mae_log": 0.08992886543273926
+    },
+    {
+      "epoch": 31,
+      "train_loss": 0.046282403110652355,
+      "val_loss": 0.003826435888186097,
+      "val_auc_pr": 0.2284485407066052,
+      "val_f1": 0.3999999962500001,
+      "val_mae_log": 0.06141701713204384
+    },
+    {
+      "epoch": 32,
+      "train_loss": 0.04575154318197353,
+      "val_loss": 0.005115043604746461,
+      "val_auc_pr": 0.3611255411255411,
+      "val_f1": 0.3999999962500001,
+      "val_mae_log": 0.09008380770683289
+    },
+    {
+      "epoch": 33,
+      "train_loss": 0.046043931763317135,
+      "val_loss": 0.004483342935730304,
+      "val_auc_pr": 0.36333333333333334,
+      "val_f1": 0.3809523773242631,
+      "val_mae_log": 0.10232321172952652
+    },
+    {
+      "epoch": 34,
+      "train_loss": 0.04492839058307377,
+      "val_loss": 0.007276699944798436,
+      "val_auc_pr": 0.3461904761904762,
+      "val_f1": 0.3809523773242631,
+      "val_mae_log": 0.10686437785625458
+    },
+    {
+      "epoch": 35,
+      "train_loss": 0.04576677558188503,
+      "val_loss": 0.004259714224774923,
+      "val_auc_pr": 0.37718954248366016,
+      "val_f1": 0.3999999962500001,
+      "val_mae_log": 0.0769796371459961
+    },
+    {
+      "epoch": 36,
+      "train_loss": 0.044130372638637956,
+      "val_loss": 0.004274079659288483,
+      "val_auc_pr": 0.4215151515151515,
+      "val_f1": 0.4444444395061729,
+      "val_mae_log": 0.09318451583385468
+    },
+    {
+      "epoch": 37,
+      "train_loss": 0.04556343443691731,
+      "val_loss": 0.0053521015548280305,
+      "val_auc_pr": 0.3828373015873016,
+      "val_f1": 0.421052627700831,
+      "val_mae_log": 0.11446798592805862
+    },
+    {
+      "epoch": 38,
+      "train_loss": 0.04497031863476779,
+      "val_loss": 0.005016647595246988,
+      "val_auc_pr": 0.38186813186813184,
+      "val_f1": 0.3809523773242631,
+      "val_mae_log": 0.11497646570205688
+    },
+    {
+      "epoch": 39,
+      "train_loss": 0.04312905277553442,
+      "val_loss": 0.003749881671475513,
+      "val_auc_pr": 0.3595238095238095,
+      "val_f1": 0.3809523773242631,
+      "val_mae_log": 0.05548140034079552
+    },
+    {
+      "epoch": 40,
+      "train_loss": 0.04352163130769859,
+      "val_loss": 0.005372332009885993,
+      "val_auc_pr": 0.3503288825869471,
+      "val_f1": 0.34782608355387534,
+      "val_mae_log": 0.08230870962142944
+    },
+    {
+      "epoch": 41,
+      "train_loss": 0.043740846146200156,
+      "val_loss": 0.0039979582319834405,
+      "val_auc_pr": 0.41458333333333336,
+      "val_f1": 0.3999999962500001,
+      "val_mae_log": 0.08734633028507233
+    },
+    {
+      "epoch": 42,
+      "train_loss": 0.04409235781310378,
+      "val_loss": 0.005109895303446267,
+      "val_auc_pr": 0.2524756335282651,
+      "val_f1": 0.33333333003472226,
+      "val_mae_log": 0.07870446890592575
+    },
+    {
+      "epoch": 43,
+      "train_loss": 0.043179894389735685,
+      "val_loss": 0.005041864268215639,
+      "val_auc_pr": 0.26508912655971484,
+      "val_f1": 0.36363636012396694,
+      "val_mae_log": 0.07578516006469727
+    },
+    {
+      "epoch": 44,
+      "train_loss": 0.04234155755792115,
+      "val_loss": 0.0038543779269925187,
+      "val_auc_pr": 0.3427519893899204,
+      "val_f1": 0.33333333055555564,
+      "val_mae_log": 0.06378159672021866
+    },
+    {
+      "epoch": 45,
+      "train_loss": 0.043199574021068776,
+      "val_loss": 0.00448337330349854,
+      "val_auc_pr": 0.38693977591036416,
+      "val_f1": 0.36363636012396694,
+      "val_mae_log": 0.08112290501594543
+    },
+    {
+      "epoch": 46,
+      "train_loss": 0.04324697579282361,
+      "val_loss": 0.004593804511906845,
+      "val_auc_pr": 0.3657142857142857,
+      "val_f1": 0.3809523773242631,
+      "val_mae_log": 0.12126877903938293
+    },
+    {
+      "epoch": 47,
+      "train_loss": 0.042983541144309814,
+      "val_loss": 0.0034202520120223717,
+      "val_auc_pr": 0.36703703703703705,
+      "val_f1": 0.3809523773242631,
+      "val_mae_log": 0.05318637564778328
+    },
+    {
+      "epoch": 48,
+      "train_loss": 0.04088504479543583,
+      "val_loss": 0.0037384599480511887,
+      "val_auc_pr": 0.35812684047978166,
+      "val_f1": 0.38461538150887575,
+      "val_mae_log": 0.0607416033744812
+    },
+    {
+      "epoch": 49,
+      "train_loss": 0.0411647165143812,
+      "val_loss": 0.0038923417118244936,
+      "val_auc_pr": 0.37444444444444447,
+      "val_f1": 0.3809523773242631,
+      "val_mae_log": 0.07454186677932739
+    },
+    {
+      "epoch": 50,
+      "train_loss": 0.04235347539589212,
+      "val_loss": 0.0035431724141484927,
+      "val_auc_pr": 0.3718181818181818,
+      "val_f1": 0.3809523773242631,
+      "val_mae_log": 0.05186235159635544
+    },
+    {
+      "epoch": 51,
+      "train_loss": 0.03975096909782371,
+      "val_loss": 0.003855357279202768,
+      "val_auc_pr": 0.37,
+      "val_f1": 0.3809523773242631,
+      "val_mae_log": 0.08433445543050766
+    },
+    {
+      "epoch": 52,
+      "train_loss": 0.040304526777283564,
+      "val_loss": 0.003954493274380054,
+      "val_auc_pr": 0.36705882352941177,
+      "val_f1": 0.36363636012396694,
+      "val_mae_log": 0.0650041252374649
+    },
+    {
+      "epoch": 53,
+      "train_loss": 0.041316902365636184,
+      "val_loss": 0.0044658422370308214,
+      "val_auc_pr": 0.37444444444444447,
+      "val_f1": 0.39999999680000003,
+      "val_mae_log": 0.08514165133237839
+    },
+    {
+      "epoch": 54,
+      "train_loss": 0.041085500773545856,
+      "val_loss": 0.003584100299381784,
+      "val_auc_pr": 0.36991596638655466,
+      "val_f1": 0.36363636012396694,
+      "val_mae_log": 0.04943912476301193
+    },
+    {
+      "epoch": 55,
+      "train_loss": 0.04048956327543066,
+      "val_loss": 0.003669723236401166,
+      "val_auc_pr": 0.366961926961927,
+      "val_f1": 0.34782608355387534,
+      "val_mae_log": 0.0743192732334137
+    },
+    {
+      "epoch": 56,
+      "train_loss": 0.04016674624101536,
+      "val_loss": 0.004304527521266469,
+      "val_auc_pr": 0.3745588235294118,
+      "val_f1": 0.39999999680000003,
+      "val_mae_log": 0.08440288156270981
+    }
+  ],
+  "conformal": {
+    "alpha_0.01": {
+      "conformal_metrics": {
+        "alpha": 0.01,
+        "target_coverage": 0.99,
+        "marginal_coverage": 0.9700046146746655,
+        "coverage_guarantee_met": false,
+        "avg_set_size": 2.1033687125057683,
+        "efficiency": 0.4741578218735579,
+        "positive_coverage": 0.136986301369863,
+        "negative_coverage": 0.9990448901623686,
+        "set_size_distribution": {
+          "2": 1948,
+          "3": 214,
+          "4": 5
+        },
+        "n_test": 2167,
+        "mean_interval_width": 0.35249775648117065,
+        "median_interval_width": 0.3299492597579956
+      },
+      "conformal_state": {
+        "is_calibrated": true,
+        "alpha": 0.01,
+        "q_hat": 0.31530878875241947,
+        "q_residual": 0.31530878875241947,
+        "n_cal": 527,
+        "tiers": {
+          "LOW": [
+            0.0,
+            0.1
+          ],
+          "MODERATE": [
+            0.1,
+            0.4
+          ],
+          "HIGH": [
+            0.4,
+            0.7
+          ],
+          "CRITICAL": [
+            0.7,
+            1.0
+          ]
+        }
+      }
+    },
+    "alpha_0.05": {
+      "conformal_metrics": {
+        "alpha": 0.05,
+        "target_coverage": 0.95,
+        "marginal_coverage": 0.9487771112136595,
+        "coverage_guarantee_met": true,
+        "avg_set_size": 1.9856945085371482,
+        "efficiency": 0.503576372865713,
+        "positive_coverage": 0.0,
+        "negative_coverage": 0.9818529130850048,
+        "set_size_distribution": {
+          "1": 31,
+          "2": 2136
+        },
+        "n_test": 2167,
+        "mean_interval_width": 0.14139389991760254,
+        "median_interval_width": 0.1266784965991974
+      },
+      "conformal_state": {
+        "is_calibrated": true,
+        "alpha": 0.05,
+        "q_hat": 0.1120380280677236,
+        "q_residual": 0.1120380280677236,
+        "n_cal": 527,
+        "tiers": {
+          "LOW": [
+            0.0,
+            0.1
+          ],
+          "MODERATE": [
+            0.1,
+            0.4
+          ],
+          "HIGH": [
+            0.4,
+            0.7
+          ],
+          "CRITICAL": [
+            0.7,
+            1.0
+          ]
+        }
+      }
+    },
+    "alpha_0.1": {
+      "conformal_metrics": {
+        "alpha": 0.1,
+        "target_coverage": 0.9,
+        "marginal_coverage": 0.9284725426857406,
+        "coverage_guarantee_met": true,
+        "avg_set_size": 1.103830179972312,
+        "efficiency": 0.724042455006922,
+        "positive_coverage": 0.0,
+        "negative_coverage": 0.9608404966571156,
+        "set_size_distribution": {
+          "1": 1942,
+          "2": 225
+        },
+        "n_test": 2167,
+        "mean_interval_width": 0.060726769268512726,
+        "median_interval_width": 0.05510023236274719
+      },
+      "conformal_state": {
+        "is_calibrated": true,
+        "alpha": 0.1,
+        "q_hat": 0.04045976169647709,
+        "q_residual": 0.04045976169647709,
+        "n_cal": 527,
+        "tiers": {
+          "LOW": [
+            0.0,
+            0.1
+          ],
+          "MODERATE": [
+            0.1,
+            0.4
+          ],
+          "HIGH": [
+            0.4,
+            0.7
+          ],
+          "CRITICAL": [
+            0.7,
+            1.0
+          ]
+        }
+      }
+    },
+    "alpha_0.2": {
+      "conformal_metrics": {
+        "alpha": 0.2,
+        "target_coverage": 0.8,
+        "marginal_coverage": 0.9220119981541302,
+        "coverage_guarantee_met": true,
+        "avg_set_size": 1.054453161052146,
+        "efficiency": 0.7363867097369635,
+        "positive_coverage": 0.0,
+        "negative_coverage": 0.9541547277936963,
+        "set_size_distribution": {
+          "1": 2049,
+          "2": 118
+        },
+        "n_test": 2167,
+        "mean_interval_width": 0.04071307182312012,
+        "median_interval_width": 0.039181869477033615
+      },
+      "conformal_state": {
+        "is_calibrated": true,
+        "alpha": 0.2,
+        "q_hat": 0.024541400479014954,
+        "q_residual": 0.024541400479014954,
+        "n_cal": 527,
+        "tiers": {
+          "LOW": [
+            0.0,
+            0.1
+          ],
+          "MODERATE": [
+            0.1,
+            0.4
+          ],
+          "HIGH": [
+            0.4,
+            0.7
+          ],
+          "CRITICAL": [
+            0.7,
+            1.0
+          ]
+        }
+      }
+    }
+  }
+}

results/model_comparison.json

@@ -0,0 +1,40 @@
+[
+  {
+    "model": "Orbital Shell Baseline",
+    "auc_pr": 0.061184346220415166,
+    "auc_roc": 0.6374507725922728,
+    "f1_at_50": 0.0,
+    "n_positive": 73,
+    "n_total": 2167,
+    "pos_rate": 0.03368712505768343,
+    "f1": 0.13223140017211957,
+    "optimal_threshold": 0.03237410071942446,
+    "threshold": 0.03237410071942446,
+    "recall_at_prec_30": 0.0,
+    "recall_at_prec_50": 0.0,
+    "recall_at_prec_70": 0.0,
+    "mae_log": 0.9927019602313063,
+    "rmse_log": 1.2867684153860748,
+    "mae_km": 10600.126897201788,
+    "median_abs_error_km": 7222.8428976622645
+  },
+  {
+    "model": "XGBoost (Engineered Features)",
+    "auc_pr": 0.9884220304219559,
+    "auc_roc": 0.9995944054114168,
+    "f1_at_50": 0.9411764705882353,
+    "n_positive": 73,
+    "n_total": 2167,
+    "pos_rate": 0.03368712505768343,
+    "f1": 0.9473684160604224,
+    "optimal_threshold": 0.5539590716362,
+    "threshold": 0.5539590716362,
+    "recall_at_prec_30": 1.0,
+    "recall_at_prec_50": 1.0,
+    "recall_at_prec_70": 1.0,
+    "mae_log": 0.011742588180292227,
+    "rmse_log": 0.03972278871639667,
+    "mae_km": 80.85688587394668,
+    "median_abs_error_km": 42.99218749998545
+  }
+]

results/staleness_experiment.json

@@ -0,0 +1,355 @@
+{
+  "cutoffs": [
+    2.0,
+    2.5,
+    3.0,
+    3.5,
+    4.0,
+    5.0,
+    6.0
+  ],
+  "n_test_events": 2167,
+  "n_positive": 73,
+  "baseline": [
+    {
+      "auc_pr": 0.061184346220415166,
+      "auc_roc": 0.6374507725922728,
+      "f1_at_50": 0.0,
+      "n_positive": 73,
+      "n_total": 2167,
+      "pos_rate": 0.03368712505768343,
+      "f1": 0.13223140017211957,
+      "optimal_threshold": 0.03237410071942446,
+      "threshold": 0.03237410071942446,
+      "recall_at_prec_30": 0.0,
+      "recall_at_prec_50": 0.0,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 2.0,
+      "n_events": 2167
+    },
+    {
+      "auc_pr": 0.061184346220415166,
+      "auc_roc": 0.6374507725922728,
+      "f1_at_50": 0.0,
+      "n_positive": 73,
+      "n_total": 2167,
+      "pos_rate": 0.03368712505768343,
+      "f1": 0.13223140017211957,
+      "optimal_threshold": 0.03237410071942446,
+      "threshold": 0.03237410071942446,
+      "recall_at_prec_30": 0.0,
+      "recall_at_prec_50": 0.0,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 2.5,
+      "n_events": 2167
+    },
+    {
+      "auc_pr": 0.061184346220415166,
+      "auc_roc": 0.6374507725922728,
+      "f1_at_50": 0.0,
+      "n_positive": 73,
+      "n_total": 2167,
+      "pos_rate": 0.03368712505768343,
+      "f1": 0.13223140017211957,
+      "optimal_threshold": 0.03237410071942446,
+      "threshold": 0.03237410071942446,
+      "recall_at_prec_30": 0.0,
+      "recall_at_prec_50": 0.0,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 3.0,
+      "n_events": 2167
+    },
+    {
+      "auc_pr": 0.061184346220415166,
+      "auc_roc": 0.6374507725922728,
+      "f1_at_50": 0.0,
+      "n_positive": 73,
+      "n_total": 2167,
+      "pos_rate": 0.03368712505768343,
+      "f1": 0.13223140017211957,
+      "optimal_threshold": 0.03237410071942446,
+      "threshold": 0.03237410071942446,
+      "recall_at_prec_30": 0.0,
+      "recall_at_prec_50": 0.0,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 3.5,
+      "n_events": 2167
+    },
+    {
+      "auc_pr": 0.061184346220415166,
+      "auc_roc": 0.6374507725922728,
+      "f1_at_50": 0.0,
+      "n_positive": 73,
+      "n_total": 2167,
+      "pos_rate": 0.03368712505768343,
+      "f1": 0.13223140017211957,
+      "optimal_threshold": 0.03237410071942446,
+      "threshold": 0.03237410071942446,
+      "recall_at_prec_30": 0.0,
+      "recall_at_prec_50": 0.0,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 4.0,
+      "n_events": 2167
+    },
+    {
+      "auc_pr": 0.061184346220415166,
+      "auc_roc": 0.6374507725922728,
+      "f1_at_50": 0.0,
+      "n_positive": 73,
+      "n_total": 2167,
+      "pos_rate": 0.03368712505768343,
+      "f1": 0.13223140017211957,
+      "optimal_threshold": 0.03237410071942446,
+      "threshold": 0.03237410071942446,
+      "recall_at_prec_30": 0.0,
+      "recall_at_prec_50": 0.0,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 5.0,
+      "n_events": 2167
+    },
+    {
+      "auc_pr": 0.061184346220415166,
+      "auc_roc": 0.6374507725922728,
+      "f1_at_50": 0.0,
+      "n_positive": 73,
+      "n_total": 2167,
+      "pos_rate": 0.03368712505768343,
+      "f1": 0.13223140017211957,
+      "optimal_threshold": 0.03237410071942446,
+      "threshold": 0.03237410071942446,
+      "recall_at_prec_30": 0.0,
+      "recall_at_prec_50": 0.0,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 6.0,
+      "n_events": 2167
+    }
+  ],
+  "xgboost": [
+    {
+      "auc_pr": 0.9883137899600032,
+      "auc_roc": 0.9995878635632139,
+      "f1_at_50": 0.935064935064935,
+      "n_positive": 73,
+      "n_total": 2167,
+      "pos_rate": 0.03368712505768343,
+      "f1": 0.9411764655987015,
+      "optimal_threshold": 0.5284891724586487,
+      "threshold": 0.5284891724586487,
+      "recall_at_prec_30": 1.0,
+      "recall_at_prec_50": 1.0,
+      "recall_at_prec_70": 1.0,
+      "cutoff": 2.0,
+      "n_events": 2167
+    },
+    {
+      "auc_pr": 0.9123203140942627,
+      "auc_roc": 0.9903418565869928,
+      "f1_at_50": 0.8421052631578947,
+      "n_positive": 70,
+      "n_total": 2126,
+      "pos_rate": 0.03292568203198495,
+      "f1": 0.8467153234695509,
+      "optimal_threshold": 0.9780168533325195,
+      "threshold": 0.9780168533325195,
+      "recall_at_prec_30": 0.9857142857142858,
+      "recall_at_prec_50": 0.9714285714285714,
+      "recall_at_prec_70": 0.9285714285714286,
+      "cutoff": 2.5,
+      "n_events": 2126
+    },
+    {
+      "auc_pr": 0.7112636105696798,
+      "auc_roc": 0.9702624390685601,
+      "f1_at_50": 0.7012987012987013,
+      "n_positive": 67,
+      "n_total": 2045,
+      "pos_rate": 0.03276283618581907,
+      "f1": 0.722222217246335,
+      "optimal_threshold": 0.9061354398727417,
+      "threshold": 0.9061354398727417,
+      "recall_at_prec_30": 0.9104477611940298,
+      "recall_at_prec_50": 0.8507462686567164,
+      "recall_at_prec_70": 0.7164179104477612,
+      "cutoff": 3.0,
+      "n_events": 2045
+    },
+    {
+      "auc_pr": 0.7224173760553306,
+      "auc_roc": 0.9779084384250436,
+      "f1_at_50": 0.6666666666666666,
+      "n_positive": 65,
+      "n_total": 1962,
+      "pos_rate": 0.033129459734964326,
+      "f1": 0.6802721039104078,
+      "optimal_threshold": 0.8590014576911926,
+      "threshold": 0.8590014576911926,
+      "recall_at_prec_30": 0.9384615384615385,
+      "recall_at_prec_50": 0.8615384615384616,
+      "recall_at_prec_70": 0.6153846153846154,
+      "cutoff": 3.5,
+      "n_events": 1962
+    },
+    {
+      "auc_pr": 0.6392429519999454,
+      "auc_roc": 0.9669743064869061,
+      "f1_at_50": 0.5921052631578947,
+      "n_positive": 62,
+      "n_total": 1890,
+      "pos_rate": 0.0328042328042328,
+      "f1": 0.6370370320702333,
+      "optimal_threshold": 0.8714247941970825,
+      "threshold": 0.8714247941970825,
+      "recall_at_prec_30": 0.8870967741935484,
+      "recall_at_prec_50": 0.8064516129032258,
+      "recall_at_prec_70": 0.41935483870967744,
+      "cutoff": 4.0,
+      "n_events": 1890
+    },
+    {
+      "auc_pr": 0.42295193898950256,
+      "auc_roc": 0.9482351744481741,
+      "f1_at_50": 0.5419354838709678,
+      "n_positive": 58,
+      "n_total": 1753,
+      "pos_rate": 0.03308613804905876,
+      "f1": 0.5454545404630832,
+      "optimal_threshold": 0.9965507984161377,
+      "threshold": 0.9965507984161377,
+      "recall_at_prec_30": 0.7931034482758621,
+      "recall_at_prec_50": 0.5689655172413793,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 5.0,
+      "n_events": 1753
+    },
+    {
+      "auc_pr": 0.3219032626600778,
+      "auc_roc": 0.9162752848174842,
+      "f1_at_50": 0.4027777777777778,
+      "n_positive": 55,
+      "n_total": 1619,
+      "pos_rate": 0.033971587399629403,
+      "f1": 0.42592592092764064,
+      "optimal_threshold": 0.9984425902366638,
+      "threshold": 0.9984425902366638,
+      "recall_at_prec_30": 0.5818181818181818,
+      "recall_at_prec_50": 0.12727272727272726,
+      "recall_at_prec_70": 0.01818181818181818,
+      "cutoff": 6.0,
+      "n_events": 1619
+    }
+  ],
+  "pitft": [
+    {
+      "auc_pr": 0.5108315323239697,
+      "auc_roc": 0.9467689811725608,
+      "f1_at_50": 0.0,
+      "n_positive": 73,
+      "n_total": 2167,
+      "pos_rate": 0.03368712505768343,
+      "f1": 0.5325443737908337,
+      "optimal_threshold": 0.18103967607021332,
+      "threshold": 0.18103967607021332,
+      "recall_at_prec_30": 0.7808219178082192,
+      "recall_at_prec_50": 0.5068493150684932,
+      "recall_at_prec_70": 0.2876712328767123,
+      "cutoff": 2.0,
+      "n_events": 2167
+    },
+    {
+      "auc_pr": 0.40929547300496166,
+      "auc_roc": 0.9342620900500278,
+      "f1_at_50": 0.028169014084507043,
+      "n_positive": 70,
+      "n_total": 2126,
+      "pos_rate": 0.03292568203198495,
+      "f1": 0.45121950730220106,
+      "optimal_threshold": 0.18565748631954193,
+      "threshold": 0.18565748631954193,
+      "recall_at_prec_30": 0.6571428571428571,
+      "recall_at_prec_50": 0.35714285714285715,
+      "recall_at_prec_70": 0.2,
+      "cutoff": 2.5,
+      "n_events": 2126
+    },
+    {
+      "auc_pr": 0.3126159912723518,
+      "auc_roc": 0.9086669785551514,
+      "f1_at_50": 0.056338028169014086,
+      "n_positive": 67,
+      "n_total": 2045,
+      "pos_rate": 0.03276283618581907,
+      "f1": 0.3968253918455531,
+      "optimal_threshold": 0.2572215497493744,
+      "threshold": 0.2572215497493744,
+      "recall_at_prec_30": 0.4626865671641791,
+      "recall_at_prec_50": 0.208955223880597,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 3.0,
+      "n_events": 2045
+    },
+    {
+      "auc_pr": 0.32548992974654617,
+      "auc_roc": 0.9031263939013017,
+      "f1_at_50": 0.058823529411764705,
+      "n_positive": 65,
+      "n_total": 1962,
+      "pos_rate": 0.033129459734964326,
+      "f1": 0.3716814110423683,
+      "optimal_threshold": 0.28492599725723267,
+      "threshold": 0.28492599725723267,
+      "recall_at_prec_30": 0.46153846153846156,
+      "recall_at_prec_50": 0.26153846153846155,
+      "recall_at_prec_70": 0.015384615384615385,
+      "cutoff": 3.5,
+      "n_events": 1962
+    },
+    {
+      "auc_pr": 0.286925285041537,
+      "auc_roc": 0.892249594127197,
+      "f1_at_50": 0.0,
+      "n_positive": 62,
+      "n_total": 1890,
+      "pos_rate": 0.0328042328042328,
+      "f1": 0.3736263691341626,
+      "optimal_threshold": 0.16788320243358612,
+      "threshold": 0.16788320243358612,
+      "recall_at_prec_30": 0.45161290322580644,
+      "recall_at_prec_50": 0.22580645161290322,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 4.0,
+      "n_events": 1890
+    },
+    {
+      "auc_pr": 0.23877494536053875,
+      "auc_roc": 0.867622825755264,
+      "f1_at_50": 0.0625,
+      "n_positive": 58,
+      "n_total": 1753,
+      "pos_rate": 0.03308613804905876,
+      "f1": 0.33082706275086216,
+      "optimal_threshold": 0.21164827048778534,
+      "threshold": 0.21164827048778534,
+      "recall_at_prec_30": 0.3103448275862069,
+      "recall_at_prec_50": 0.1896551724137931,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 5.0,
+      "n_events": 1753
+    },
+    {
+      "auc_pr": 0.1838323482889146,
+      "auc_roc": 0.8097419204836084,
+      "f1_at_50": 0.06666666666666667,
+      "n_positive": 55,
+      "n_total": 1619,
+      "pos_rate": 0.033971587399629403,
+      "f1": 0.2741935434508325,
+      "optimal_threshold": 0.21228547394275665,
+      "threshold": 0.21228547394275665,
+      "recall_at_prec_30": 0.18181818181818182,
+      "recall_at_prec_50": 0.07272727272727272,
+      "recall_at_prec_70": 0.0,
+      "cutoff": 6.0,
+      "n_events": 1619
+    }
+  ]
+}

src/data/augment.py

@@ -0,0 +1,297 @@
+# Generated by Claude Code -- 2026-02-08
+"""Data augmentation for the conjunction prediction dataset.
+
+The fundamental problem: only 67 high-risk events out of 13,154 in training (0.5%).
+This module provides two augmentation strategies:
+
+1. SPACE-TRACK INTEGRATION: Merge real high-risk CDMs from Space-Track's cdm_public
+   feed. These have fewer features (16 vs 103) but provide real positive examples.
+
+2. TIME-SERIES AUGMENTATION: Create synthetic variants of existing high-risk events
+   by applying realistic perturbations:
+   - Gaussian noise on covariance/position/velocity features
+   - Temporal jittering (shift CDM creation times slightly)
+   - Feature dropout (randomly zero out some features, simulating missing data)
+   - Sequence truncation (remove early CDMs, simulating late detection)
+
+Both strategies are physics-aware: they don't generate impossible configurations
+(e.g., negative miss distances or covariance values).
+"""
+
+import numpy as np
+import pandas as pd
+from pathlib import Path
+
+
+def augment_event_noise(
+    event_df: pd.DataFrame,
+    noise_scale: float = 0.05,
+    n_augments: int = 5,
+    rng: np.random.Generator = None,
+) -> list[pd.DataFrame]:
+    """
+    Create n_augments noisy variants of a single conjunction event.
+
+    Applies Gaussian noise to numeric features, scaled by each column's
+    standard deviation within the event. Preserves event_id structure and
+    ensures physical constraints (non-negative distances, etc.).
+    """
+    if rng is None:
+        rng = np.random.default_rng(42)
+
+    # Identify numeric columns to perturb (exclude IDs and targets)
+    exclude = {"event_id", "time_to_tca", "risk", "mission_id", "source"}
+    numeric_cols = event_df.select_dtypes(include=[np.number]).columns
+    perturb_cols = [c for c in numeric_cols if c not in exclude]
+
+    augmented = []
+    for i in range(n_augments):
+        aug = event_df.copy()
+
+        for col in perturb_cols:
+            values = aug[col].values.astype(float)
+            col_std = np.std(values)
+            if col_std < 1e-10:
+                col_std = np.abs(np.mean(values)) * 0.01 + 1e-10
+
+            noise = rng.normal(0, noise_scale * col_std, size=len(values))
+            aug[col] = values + noise
+
+        # Physical constraints
+        if "miss_distance" in aug.columns:
+            aug["miss_distance"] = aug["miss_distance"].clip(lower=0)
+        if "relative_speed" in aug.columns:
+            aug["relative_speed"] = aug["relative_speed"].clip(lower=0)
+
+        # Ensure covariance sigma columns stay positive
+        sigma_cols = [c for c in perturb_cols if "sigma" in c.lower()]
+        for col in sigma_cols:
+            aug[col] = aug[col].clip(lower=0)
+
+        augmented.append(aug)
+
+    return augmented
+
+
+def augment_event_truncate(
+    event_df: pd.DataFrame,
+    min_keep: int = 3,
+    n_augments: int = 3,
+    rng: np.random.Generator = None,
+) -> list[pd.DataFrame]:
+    """
+    Create truncated variants by removing early CDMs.
+
+    Simulates late-detection scenarios where only the most recent CDMs
+    are available (closer to TCA).
+    """
+    if rng is None:
+        rng = np.random.default_rng(42)
+
+    # Sort by time_to_tca descending (first CDM = furthest from TCA)
+    event_df = event_df.sort_values("time_to_tca", ascending=False)
+    n_cdms = len(event_df)
+
+    if n_cdms <= min_keep:
+        return []
+
+    augmented = []
+    for _ in range(n_augments):
+        # Keep between min_keep and n_cdms-1 CDMs (always keep the last few)
+        n_keep = rng.integers(min_keep, n_cdms)
+        aug = event_df.iloc[-n_keep:].copy()
+        augmented.append(aug)
+
+    return augmented
+
+
+def augment_positive_events(
+    df: pd.DataFrame,
+    target_ratio: float = 0.05,
+    noise_scale: float = 0.05,
+    seed: int = 42,
+) -> pd.DataFrame:
+    """
+    Augment the positive (high-risk) class to reach target_ratio.
+
+    Args:
+        df: full training DataFrame with event_id, risk columns
+        target_ratio: desired fraction of high-risk events (default 5%)
+        noise_scale: std dev of Gaussian noise as fraction of feature std
+        seed: random seed
+
+    Returns:
+        Augmented DataFrame with new synthetic positive events appended
+    """
+    rng = np.random.default_rng(seed)
+
+    # Find positive events
+    event_risks = df.groupby("event_id")["risk"].last()
+    pos_event_ids = event_risks[event_risks > -5].index.tolist()
+    neg_event_ids = event_risks[event_risks <= -5].index.tolist()
+
+    n_pos = len(pos_event_ids)
+    n_neg = len(neg_event_ids)
+    n_total = n_pos + n_neg
+
+    # How many positive events do we need?
+    target_pos = int(target_ratio * (n_total / (1 - target_ratio)))
+    n_needed = max(0, target_pos - n_pos)
+
+    if n_needed == 0:
+        print(f"Already at target ratio ({n_pos}/{n_total} = {n_pos/n_total:.1%})")
+        return df
+
+    print(f"Augmenting: {n_pos} positive events → {n_pos + n_needed} "
+          f"(target {target_ratio:.0%} of {n_total + n_needed})")
+
+    # Generate augmented events
+    max_event_id = df["event_id"].max()
+    augmented_dfs = []
+    generated = 0
+
+    while generated < n_needed:
+        # Pick a random positive event to augment
+        src_event_id = rng.choice(pos_event_ids)
+        src_event = df[df["event_id"] == src_event_id]
+
+        # Apply noise augmentation
+        aug_variants = augment_event_noise(
+            src_event, noise_scale=noise_scale, n_augments=1, rng=rng
+        )
+
+        # Also try truncation sometimes
+        if rng.random() < 0.3 and len(src_event) > 3:
+            trunc_variants = augment_event_truncate(
+                src_event, n_augments=1, rng=rng
+            )
+            aug_variants.extend(trunc_variants)
+
+        for aug_df in aug_variants:
+            if generated >= n_needed:
+                break
+            max_event_id += 1
+            aug_df = aug_df.copy()
+            aug_df["event_id"] = max_event_id
+            aug_df["source"] = "augmented"
+            augmented_dfs.append(aug_df)
+            generated += 1
+
+    if augmented_dfs:
+        augmented = pd.concat(augmented_dfs, ignore_index=True)
+        result = pd.concat([df, augmented], ignore_index=True)
+
+        # Verify
+        event_risks = result.groupby("event_id")["risk"].last()
+        new_pos = (event_risks > -5).sum()
+        new_total = len(event_risks)
+        print(f"Result: {new_pos} positive / {new_total} total "
+              f"({new_pos/new_total:.1%})")
+        return result
+
+    return df
+
+
+def integrate_spacetrack_positives(
+    kelvins_df: pd.DataFrame,
+    spacetrack_path: Path,
+) -> pd.DataFrame:
+    """
+    Add Space-Track emergency CDMs as additional positive training examples.
+
+    Since Space-Track cdm_public has only 16 features vs Kelvins' 103,
+    missing features are filled with 0. The model will learn to use whatever
+    features are available.
+    """
+    if not spacetrack_path.exists():
+        print(f"No Space-Track data at {spacetrack_path}")
+        return kelvins_df
+
+    from src.data.merge_sources import (
+        load_spacetrack_cdms, group_into_events, merge_datasets
+    )
+
+    st_df = load_spacetrack_cdms(spacetrack_path)
+    st_df = group_into_events(st_df)
+
+    merged = merge_datasets(kelvins_df, st_df)
+    return merged
+
+
+def build_augmented_training_set(
+    data_dir: Path,
+    target_positive_ratio: float = 0.05,
+    noise_scale: float = 0.05,
+    seed: int = 42,
+) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Build the full augmented training set from all available sources.
+
+    Steps:
+    1. Load ESA Kelvins train/test
+    2. Merge Space-Track emergency CDMs into training set
+    3. Apply time-series augmentation to positive events
+    4. Return (augmented_train, original_test)
+
+    Test set is NEVER augmented — it stays as Kelvins-only for fair evaluation.
+    """
+    from src.data.cdm_loader import load_dataset
+
+    print("=" * 60)
+    print("  Building Augmented Training Set")
+    print("=" * 60)
+
+    # Step 1: Load Kelvins
+    print("\n1. Loading ESA Kelvins dataset ...")
+    train_df, test_df = load_dataset(data_dir / "cdm")
+
+    # Defragment and tag source
+    train_df = train_df.copy()
+    test_df = test_df.copy()
+    train_df["source"] = "kelvins"
+    test_df["source"] = "kelvins"
+
+    # Count initial positives
+    event_risks = train_df.groupby("event_id")["risk"].last()
+    n_pos_initial = (event_risks > -5).sum()
+    n_total_initial = len(event_risks)
+    print(f"   Initial: {n_pos_initial} positive / {n_total_initial} total "
+          f"({n_pos_initial/n_total_initial:.2%})")
+
+    # Step 2: Space-Track integration
+    st_path = data_dir / "cdm_spacetrack" / "cdm_spacetrack_emergency.csv"
+    if st_path.exists():
+        print(f"\n2. Integrating Space-Track emergency CDMs ...")
+        train_df = integrate_spacetrack_positives(train_df, st_path)
+    else:
+        print(f"\n2. No Space-Track data found (skipping)")
+
+    # Step 3: Time-series augmentation
+    print(f"\n3. Augmenting positive events (target ratio: {target_positive_ratio:.0%}) ...")
+    train_df = augment_positive_events(
+        train_df,
+        target_ratio=target_positive_ratio,
+        noise_scale=noise_scale,
+        seed=seed,
+    )
+
+    # Final stats
+    event_risks = train_df.groupby("event_id")["risk"].last()
+    event_sources = train_df.groupby("event_id")["source"].first()
+    n_kelvins = (event_sources == "kelvins").sum()
+    n_spacetrack = (event_sources == "spacetrack").sum()
+    n_augmented = (event_sources == "augmented").sum()
+    n_pos_final = (event_risks > -5).sum()
+    n_total_final = len(event_risks)
+
+    print(f"\n{'=' * 60}")
+    print(f"  Final Training Set:")
+    print(f"    Kelvins events:     {n_kelvins}")
+    print(f"    Space-Track events: {n_spacetrack}")
+    print(f"    Augmented events:   {n_augmented}")
+    print(f"    Total events:       {n_total_final}")
+    print(f"    Positive events:    {n_pos_final} ({n_pos_final/n_total_final:.1%})")
+    print(f"    Total CDM rows:     {len(train_df)}")
+    print(f"{'=' * 60}")
+
+    return train_df, test_df

src/data/cdm_loader.py

@@ -0,0 +1,205 @@
+# Generated by Claude Code -- 2026-02-08
+"""Load and parse ESA Kelvins CDM dataset into structured formats."""
+
+import pandas as pd
+import numpy as np
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class CDMSnapshot:
+    """A single Conjunction Data Message update."""
+    time_to_tca: float
+    miss_distance: float
+    relative_speed: float
+    risk: float
+    features: np.ndarray  # all numeric columns as a flat vector
+
+
+@dataclass
+class ConjunctionEvent:
+    """A complete conjunction event = sequence of CDM snapshots."""
+    event_id: int
+    cdm_sequence: List[CDMSnapshot] = field(default_factory=list)
+    risk_label: int = 0  # 1 if any CDM in sequence has high risk
+    final_miss_distance: float = 0.0
+    altitude_km: float = 0.0
+    object_type: str = ""
+
+
+# Columns we use for the feature vector (numeric only, excluding IDs/targets)
+EXCLUDE_COLS = {"event_id", "time_to_tca", "risk", "mission_id"}
+
+
+def load_cdm_csv(path: Path) -> pd.DataFrame:
+    """Load a CDM CSV and do basic cleaning."""
+    df = pd.read_csv(path)
+
+    # Identify numeric columns for features
+    numeric_cols = df.select_dtypes(include=[np.number]).columns.tolist()
+    feature_cols = [c for c in numeric_cols if c not in EXCLUDE_COLS]
+
+    # Fill NaN with 0 for numeric features (some covariance cols are sparse)
+    df[feature_cols] = df[feature_cols].fillna(0)
+
+    return df
+
+
+def load_dataset(data_dir: Path) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """Load train and test CDM DataFrames."""
+    # Find the CSV files (may be in subdirectory after extraction)
+    train_candidates = list(data_dir.rglob("*train*.csv"))
+    test_candidates = list(data_dir.rglob("*test*.csv"))
+
+    if not train_candidates:
+        raise FileNotFoundError(f"No train CSV found in {data_dir}")
+    if not test_candidates:
+        raise FileNotFoundError(f"No test CSV found in {data_dir}")
+
+    train_path = train_candidates[0]
+    test_path = test_candidates[0]
+
+    print(f"Loading train: {train_path}")
+    print(f"Loading test:  {test_path}")
+
+    train_df = load_cdm_csv(train_path)
+    test_df = load_cdm_csv(test_path)
+
+    print(f"Train: {len(train_df)} rows, {train_df['event_id'].nunique()} events")
+    print(f"Test:  {len(test_df)} rows, {test_df['event_id'].nunique()} events")
+
+    return train_df, test_df
+
+
+def get_feature_columns(df: pd.DataFrame) -> list[str]:
+    """Get the list of numeric feature columns (excluding IDs and targets)."""
+    numeric_cols = df.select_dtypes(include=[np.number]).columns.tolist()
+    return [c for c in numeric_cols if c not in EXCLUDE_COLS]
+
+
+def build_events(df: pd.DataFrame, feature_cols: list[str] = None) -> list[ConjunctionEvent]:
+    """Group CDM rows by event_id into ConjunctionEvent objects (vectorized).
+
+    Args:
+        df: CDM DataFrame
+        feature_cols: optional fixed list of feature columns (for train/test consistency)
+    """
+    if feature_cols is None:
+        feature_cols = get_feature_columns(df)
+    else:
+        # Ensure all requested columns exist; fill missing with 0
+        for col in feature_cols:
+            if col not in df.columns:
+                df = df.copy()
+                df[col] = 0.0
+    events = []
+
+    # Pre-extract feature matrix as float64 (avoids per-row pandas indexing)
+    feature_matrix = df[feature_cols].values  # (N, F) float64
+    feature_matrix = np.nan_to_num(feature_matrix, nan=0.0, posinf=0.0, neginf=0.0)
+
+    # Sort entire dataframe by event_id then time_to_tca descending
+    df = df.copy()
+    df["_row_idx"] = np.arange(len(df))
+    df = df.sort_values(["event_id", "time_to_tca"], ascending=[True, False])
+
+    # Determine altitude column
+    alt_col = None
+    for col in ["t_h_apo", "c_h_apo"]:
+        if col in df.columns:
+            alt_col = col
+            break
+
+    has_miss = "miss_distance" in df.columns
+    has_speed = "relative_speed" in df.columns
+    has_risk = "risk" in df.columns
+    has_obj_type = "c_object_type" in df.columns
+
+    for event_id, group in df.groupby("event_id", sort=True):
+        row_indices = group["_row_idx"].values
+
+        # Build CDM sequence using pre-extracted arrays
+        cdm_seq = []
+        for ridx in row_indices:
+            snap = CDMSnapshot(
+                time_to_tca=float(df.iloc[ridx]["time_to_tca"]) if "time_to_tca" in df.columns else 0.0,
+                miss_distance=float(df.iloc[ridx]["miss_distance"]) if has_miss else 0.0,
+                relative_speed=float(df.iloc[ridx]["relative_speed"]) if has_speed else 0.0,
+                risk=float(df.iloc[ridx]["risk"]) if has_risk else 0.0,
+                features=feature_matrix[ridx].astype(np.float32),
+            )
+            cdm_seq.append(snap)
+
+        final_cdm = cdm_seq[-1]
+        risk_label = 1 if final_cdm.risk > -5 else 0
+        alt = float(group[alt_col].iloc[-1]) if alt_col else 0.0
+        obj_type = str(group["c_object_type"].iloc[0]) if has_obj_type else "unknown"
+
+        events.append(ConjunctionEvent(
+            event_id=int(event_id),
+            cdm_sequence=cdm_seq,
+            risk_label=risk_label,
+            final_miss_distance=final_cdm.miss_distance,
+            altitude_km=alt,
+            object_type=obj_type,
+        ))
+
+    n_high = sum(e.risk_label for e in events)
+    print(f"Built {len(events)} events, {n_high} high-risk ({100*n_high/len(events):.1f}%)")
+    return events
+
+
+def events_to_flat_features(events: list[ConjunctionEvent]) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Extract flat feature vectors from events for classical ML.
+    Uses the LAST CDM snapshot (closest to TCA) + temporal trend features.
+
+    Returns: (X, y_risk, y_miss)
+    """
+    X_list = []
+    y_risk = []
+    y_miss = []
+
+    for event in events:
+        seq = event.cdm_sequence
+        last = seq[-1]
+        base = last.features.copy()
+
+        miss_values = np.array([s.miss_distance for s in seq])
+        risk_values = np.array([s.risk for s in seq])
+        tca_values = np.array([s.time_to_tca for s in seq])
+
+        n_cdms = len(seq)
+        miss_mean = float(np.mean(miss_values)) if n_cdms > 0 else 0.0
+        miss_std = float(np.std(miss_values)) if n_cdms > 1 else 0.0
+
+        miss_trend = 0.0
+        if n_cdms > 1 and np.std(tca_values) > 0:
+            miss_trend = float(np.polyfit(tca_values, miss_values, 1)[0])
+
+        risk_trend = 0.0
+        if n_cdms > 1 and np.std(tca_values) > 0:
+            risk_trend = float(np.polyfit(tca_values, risk_values, 1)[0])
+
+        temporal_feats = np.array([
+            n_cdms,
+            miss_mean,
+            miss_std,
+            miss_trend,
+            risk_trend,
+            float(miss_values[0] - miss_values[-1]) if n_cdms > 1 else 0.0,
+            last.time_to_tca,
+            last.relative_speed,
+        ], dtype=np.float32)
+
+        combined = np.concatenate([base, temporal_feats])
+        X_list.append(combined)
+        y_risk.append(event.risk_label)
+        y_miss.append(np.log1p(max(event.final_miss_distance, 0.0)))
+
+    X = np.stack(X_list)
+    X = np.nan_to_num(X, nan=0.0, posinf=0.0, neginf=0.0)
+
+    return X, np.array(y_risk), np.array(y_miss)

src/data/counterfactual.py

@@ -0,0 +1,458 @@
+"""SGP4 counterfactual propagation — "what if no maneuver?" simulation.
+
+For each likely-avoidance maneuver, propagates the pre-maneuver TLE forward
+to estimate whether a close approach would have occurred. This generates
+counterfactual "would-have-collided" labels for training enrichment.
+
+Uses the sgp4 library for efficient satellite propagation.
+"""
+
+import math
+import numpy as np
+from datetime import datetime, timedelta, timezone
+
+try:
+    from sgp4.api import Satrec, WGS72
+    from sgp4 import exporter
+    SGP4_AVAILABLE = True
+except ImportError:
+    SGP4_AVAILABLE = False
+
+# Earth parameters
+EARTH_RADIUS_KM = 6378.137
+
+# Counterfactual thresholds
+COLLISION_THRESHOLD_KM = 1.0    # "Would have collided" if closer than this
+NEARBY_ALT_BAND_KM = 50.0      # Altitude proximity for neighbor selection
+NEARBY_RAAN_BAND_DEG = 30.0    # RAAN proximity for neighbor selection
+
+
+def celestrak_json_to_satrec(tle_json: dict) -> "Satrec":
+    """Convert a CelesTrak GP JSON record to an sgp4 Satrec object.
+
+    CelesTrak JSON includes TLE_LINE1/TLE_LINE2 when available. Falls
+    back to constructing from orbital elements via sgp4init().
+
+    Args:
+        tle_json: CelesTrak GP JSON dict with orbital elements.
+
+    Returns:
+        sgp4 Satrec object ready for propagation.
+
+    Raises:
+        ImportError: If sgp4 is not installed.
+        ValueError: If TLE data is insufficient.
+    """
+    if not SGP4_AVAILABLE:
+        raise ImportError("sgp4 library is required: pip install sgp4")
+
+    # Prefer TLE lines if available (most reliable)
+    line1 = tle_json.get("TLE_LINE1", "")
+    line2 = tle_json.get("TLE_LINE2", "")
+    if line1 and line2:
+        return Satrec.twoline2rv(line1, line2)
+
+    # Construct from JSON orbital elements using sgp4init
+    satrec = Satrec()
+
+    # Parse epoch
+    epoch_str = tle_json.get("EPOCH", "")
+    if not epoch_str:
+        raise ValueError("No EPOCH in TLE JSON")
+
+    epoch_dt = datetime.fromisoformat(epoch_str.replace("Z", "+00:00"))
+    if epoch_dt.tzinfo is None:
+        epoch_dt = epoch_dt.replace(tzinfo=timezone.utc)
+
+    # Convert to Julian date pair for sgp4
+    year = epoch_dt.year
+    mon = epoch_dt.month
+    day = epoch_dt.day
+    hr = epoch_dt.hour
+    minute = epoch_dt.minute
+    sec = epoch_dt.second + epoch_dt.microsecond / 1e6
+
+    # sgp4init expects elements in specific units
+    no_kozai = float(tle_json.get("MEAN_MOTION", 0)) * (2.0 * math.pi / 1440.0)  # rev/day -> rad/min
+    ecco = float(tle_json.get("ECCENTRICITY", 0))
+    inclo = math.radians(float(tle_json.get("INCLINATION", 0)))
+    nodeo = math.radians(float(tle_json.get("RA_OF_ASC_NODE", 0)))
+    argpo = math.radians(float(tle_json.get("ARG_OF_PERICENTER", 0)))
+    mo = math.radians(float(tle_json.get("MEAN_ANOMALY", 0)))
+    bstar = float(tle_json.get("BSTAR", 0))
+    norad_id = int(tle_json.get("NORAD_CAT_ID", 0))
+
+    # Epoch in Julian date
+    jd_base = _datetime_to_jd(epoch_dt)
+    epoch_jd = jd_base
+    # sgp4init epoch is minutes since 1949-12-31 00:00 UTC
+    # But the Python API uses (jdsatepoch, jdsatepochF) pair
+    jd_whole = int(epoch_jd)
+    jd_frac = epoch_jd - jd_whole
+
+    satrec.sgp4init(
+        WGS72,           # gravity model
+        'i',             # 'a' = old AFSPC mode, 'i' = improved
+        norad_id,        # NORAD catalog number
+        (epoch_jd - 2433281.5),  # epoch in days since 1949 Dec 31 00:00 UT
+        bstar,           # BSTAR drag term
+        0.0,             # ndot (not used in sgp4init 'i' mode)
+        0.0,             # nddot (not used)
+        ecco,            # eccentricity
+        argpo,           # argument of perigee (radians)
+        inclo,           # inclination (radians)
+        mo,              # mean anomaly (radians)
+        no_kozai,        # mean motion (radians/minute)
+        nodeo,           # RAAN (radians)
+    )
+
+    return satrec
+
+
+def _datetime_to_jd(dt: datetime) -> float:
+    """Convert datetime to Julian Date."""
+    if dt.tzinfo is not None:
+        dt = dt.astimezone(timezone.utc).replace(tzinfo=None)
+    a = (14 - dt.month) // 12
+    y = dt.year + 4800 - a
+    m = dt.month + 12 * a - 3
+    jdn = dt.day + (153 * m + 2) // 5 + 365 * y + y // 4 - y // 100 + y // 400 - 32045
+    jd = jdn + (dt.hour - 12) / 24.0 + dt.minute / 1440.0 + dt.second / 86400.0
+    return jd
+
+
+def _propagate_positions(satrec: "Satrec", start_jd: float, hours: float, step_min: float) -> np.ndarray:
+    """Propagate a satellite and return position array (N x 3) in km.
+
+    Returns empty array if propagation fails.
+    """
+    n_steps = int(hours * 60 / step_min) + 1
+    positions = []
+
+    for i in range(n_steps):
+        minutes_since_epoch = (start_jd - satrec.jdsatepoch - satrec.jdsatepochF) * 1440.0 + i * step_min
+        e, r, v = satrec.sgp4(satrec.jdsatepoch, satrec.jdsatepochF + minutes_since_epoch / 1440.0)
+        if e != 0:
+            continue
+        positions.append(r)
+
+    if not positions:
+        return np.array([]).reshape(0, 3)
+    return np.array(positions)
+
+
+def find_nearby_satellites(
+    maneuvered_tle: dict,
+    all_tles: list[dict],
+    alt_band_km: float = NEARBY_ALT_BAND_KM,
+    raan_band_deg: float = NEARBY_RAAN_BAND_DEG,
+) -> list[dict]:
+    """Find satellites in similar orbital shell to the maneuvered object."""
+    from src.data.maneuver_detector import mean_motion_to_sma, sma_to_altitude
+
+    norad_id = int(maneuvered_tle.get("NORAD_CAT_ID", 0))
+    mm = float(maneuvered_tle.get("MEAN_MOTION", 0))
+    target_alt = sma_to_altitude(mean_motion_to_sma(mm))
+    target_raan = float(maneuvered_tle.get("RA_OF_ASC_NODE", 0))
+
+    nearby = []
+    for tle in all_tles:
+        tid = int(tle.get("NORAD_CAT_ID", 0))
+        if tid == norad_id or tid <= 0:
+            continue
+
+        t_mm = float(tle.get("MEAN_MOTION", 0))
+        t_alt = sma_to_altitude(mean_motion_to_sma(t_mm))
+        t_raan = float(tle.get("RA_OF_ASC_NODE", 0))
+
+        alt_diff = abs(t_alt - target_alt)
+        raan_diff = abs(t_raan - target_raan)
+        raan_diff = min(raan_diff, 360.0 - raan_diff)
+
+        if alt_diff < alt_band_km and raan_diff < raan_band_deg:
+            nearby.append(tle)
+
+    return nearby
+
+
+def propagate_counterfactual(
+    pre_maneuver_tle: dict,
+    nearby_tles: list[dict],
+    hours_forward: float = 24.0,
+    step_minutes: float = 10.0,
+) -> dict:
+    """Simulate "what if no maneuver?" using SGP4 propagation.
+
+    Propagates the pre-maneuver TLE (before orbit change) forward and
+    checks for close approaches with nearby satellites.
+
+    Args:
+        pre_maneuver_tle: Yesterday's TLE for the maneuvered satellite.
+        nearby_tles: Current TLEs for nearby satellites.
+        hours_forward: How far to propagate (hours).
+        step_minutes: Time step for propagation (minutes).
+
+    Returns:
+        Dict with: min_distance_km, time_of_closest_approach,
+                   would_have_collided, closest_norad_id, n_neighbors_checked.
+    """
+    if not SGP4_AVAILABLE:
+        return {
+            "min_distance_km": None,
+            "would_have_collided": False,
+            "error": "sgp4 not installed",
+        }
+
+    try:
+        target_sat = celestrak_json_to_satrec(pre_maneuver_tle)
+    except (ValueError, Exception) as e:
+        return {
+            "min_distance_km": None,
+            "would_have_collided": False,
+            "error": f"target TLE parse failed: {e}",
+        }
+
+    # Use current time as propagation start
+    now = datetime.now(timezone.utc)
+    start_jd = _datetime_to_jd(now)
+
+    # Propagate maneuvered satellite (pre-maneuver orbit)
+    target_positions = _propagate_positions(target_sat, start_jd, hours_forward, step_minutes)
+    if len(target_positions) == 0:
+        return {
+            "min_distance_km": None,
+            "would_have_collided": False,
+            "error": "target propagation failed",
+        }
+
+    global_min_dist = float("inf")
+    closest_norad = 0
+    closest_time_offset_min = 0.0
+    n_checked = 0
+
+    for neighbor_tle in nearby_tles:
+        try:
+            neighbor_sat = celestrak_json_to_satrec(neighbor_tle)
+        except (ValueError, Exception):
+            continue
+
+        neighbor_positions = _propagate_positions(neighbor_sat, start_jd, hours_forward, step_minutes)
+        if len(neighbor_positions) == 0:
+            continue
+
+        n_checked += 1
+
+        # Compute distances at each timestep (use min of overlapping steps)
+        n_common = min(len(target_positions), len(neighbor_positions))
+        diffs = target_positions[:n_common] - neighbor_positions[:n_common]
+        distances = np.linalg.norm(diffs, axis=1)
+        min_idx = np.argmin(distances)
+        min_dist = distances[min_idx]
+
+        if min_dist < global_min_dist:
+            global_min_dist = min_dist
+            closest_norad = int(neighbor_tle.get("NORAD_CAT_ID", 0))
+            closest_time_offset_min = min_idx * step_minutes
+
+    if global_min_dist == float("inf"):
+        return {
+            "min_distance_km": None,
+            "would_have_collided": False,
+            "n_neighbors_checked": n_checked,
+            "error": "no valid neighbors propagated",
+        }
+
+    tca_dt = now + timedelta(minutes=closest_time_offset_min)
+
+    return {
+        "min_distance_km": round(global_min_dist, 3),
+        "time_of_closest_approach": tca_dt.isoformat(),
+        "would_have_collided": global_min_dist < COLLISION_THRESHOLD_KM,
+        "closest_norad_id": closest_norad,
+        "n_neighbors_checked": n_checked,
+    }
+
+
+def compute_forward_trajectory(
+    tle_1: dict,
+    tle_2: dict,
+    hours_forward: float = 120.0,
+    step_minutes: float = 20.0,
+) -> list[dict] | None:
+    """Compute full trajectory time series for two satellites.
+
+    Returns list of trajectory points with ECI positions and separation
+    distance, suitable for baking into the webapp alerts JSON so the
+    frontend doesn't need to do SGP4 propagation or load TLE data.
+
+    Args:
+        tle_1: CelesTrak GP JSON for satellite 1.
+        tle_2: CelesTrak GP JSON for satellite 2.
+        hours_forward: How far to propagate (default 120h = 5 days).
+        step_minutes: Time step for propagation (minutes).
+
+    Returns:
+        List of dicts with: h (hours from start), d (distance km),
+        s1 [x,y,z] ECI km, s2 [x,y,z] ECI km. None if propagation fails.
+    """
+    if not SGP4_AVAILABLE:
+        return None
+
+    try:
+        sat1 = celestrak_json_to_satrec(tle_1)
+        sat2 = celestrak_json_to_satrec(tle_2)
+    except (ValueError, Exception):
+        return None
+
+    now = datetime.now(timezone.utc)
+    start_jd = _datetime_to_jd(now)
+
+    n_steps = int(hours_forward * 60 / step_minutes) + 1
+    points = []
+
+    for i in range(n_steps):
+        mins = i * step_minutes
+        target_jd = start_jd + mins / 1440.0
+        jd_whole = int(target_jd)
+        jd_frac = target_jd - jd_whole
+
+        e1, r1, _ = sat1.sgp4(jd_whole, jd_frac)
+        e2, r2, _ = sat2.sgp4(jd_whole, jd_frac)
+
+        if e1 != 0 or e2 != 0:
+            continue
+        if not all(math.isfinite(v) for v in r1 + r2):
+            continue
+
+        dx = r1[0] - r2[0]
+        dy = r1[1] - r2[1]
+        dz = r1[2] - r2[2]
+        dist = math.sqrt(dx * dx + dy * dy + dz * dz)
+
+        points.append({
+            "h": round(mins / 60.0, 2),
+            "d": round(dist, 1),
+            "s1": [round(r1[0], 1), round(r1[1], 1), round(r1[2], 1)],
+            "s2": [round(r2[0], 1), round(r2[1], 1), round(r2[2], 1)],
+        })
+
+    return points if points else None
+
+
+def compute_tca_trail(
+    tle_1: dict,
+    tle_2: dict,
+    tca_hours: float,
+    half_window_min: float = 30.0,
+    step_minutes: float = 0.25,
+) -> list[dict] | None:
+    """Compute dense trail around TCA for globe orbital path visualization.
+
+    Returns 15-sec resolution positions for ±30 min around TCA.
+
+    Args:
+        tle_1: CelesTrak GP JSON for satellite 1.
+        tle_2: CelesTrak GP JSON for satellite 2.
+        tca_hours: Hours from now to TCA (from compute_forward_tca).
+        half_window_min: Half window in minutes around TCA.
+        step_minutes: Time step in minutes.
+
+    Returns:
+        List of dicts with s1 [x,y,z] and s2 [x,y,z] ECI km. None if fails.
+    """
+    if not SGP4_AVAILABLE:
+        return None
+
+    try:
+        sat1 = celestrak_json_to_satrec(tle_1)
+        sat2 = celestrak_json_to_satrec(tle_2)
+    except (ValueError, Exception):
+        return None
+
+    now = datetime.now(timezone.utc)
+    start_jd = _datetime_to_jd(now)
+
+    tca_min = tca_hours * 60.0
+    t_start = tca_min - half_window_min
+    t_end = tca_min + half_window_min
+    n_steps = int((t_end - t_start) / step_minutes) + 1
+
+    trail = []
+    for i in range(n_steps):
+        mins = t_start + i * step_minutes
+        target_jd = start_jd + mins / 1440.0
+        jd_whole = int(target_jd)
+        jd_frac = target_jd - jd_whole
+
+        e1, r1, _ = sat1.sgp4(jd_whole, jd_frac)
+        e2, r2, _ = sat2.sgp4(jd_whole, jd_frac)
+
+        if e1 != 0 or e2 != 0:
+            continue
+        if not all(math.isfinite(v) for v in r1 + r2):
+            continue
+
+        dx = r1[0] - r2[0]
+        dy = r1[1] - r2[1]
+        dz = r1[2] - r2[2]
+        dist = math.sqrt(dx * dx + dy * dy + dz * dz)
+
+        trail.append({
+            "h": round(mins / 60.0, 3),
+            "d": round(dist, 1),
+            "s1": [round(r1[0], 1), round(r1[1], 1), round(r1[2], 1)],
+            "s2": [round(r2[0], 1), round(r2[1], 1), round(r2[2], 1)],
+        })
+
+    return trail if trail else None
+
+
+def compute_forward_tca(
+    tle_1: dict,
+    tle_2: dict,
+    hours_forward: float = 120.0,
+    step_minutes: float = 10.0,
+) -> dict:
+    """Compute forward Time of Closest Approach between two satellites.
+
+    Propagates both satellites forward using SGP4 and finds the minimum
+    separation distance and when it occurs.
+
+    Args:
+        tle_1: CelesTrak GP JSON for satellite 1.
+        tle_2: CelesTrak GP JSON for satellite 2.
+        hours_forward: How far to propagate (default 120h = 5 days).
+        step_minutes: Time step for propagation (minutes).
+
+    Returns:
+        Dict with: tca_hours, tca_min_distance_km, or error.
+    """
+    if not SGP4_AVAILABLE:
+        return {"tca_hours": None, "tca_min_distance_km": None}
+
+    try:
+        sat1 = celestrak_json_to_satrec(tle_1)
+        sat2 = celestrak_json_to_satrec(tle_2)
+    except (ValueError, Exception) as e:
+        return {"tca_hours": None, "tca_min_distance_km": None}
+
+    now = datetime.now(timezone.utc)
+    start_jd = _datetime_to_jd(now)
+
+    pos1 = _propagate_positions(sat1, start_jd, hours_forward, step_minutes)
+    pos2 = _propagate_positions(sat2, start_jd, hours_forward, step_minutes)
+
+    if len(pos1) == 0 or len(pos2) == 0:
+        return {"tca_hours": None, "tca_min_distance_km": None}
+
+    n_common = min(len(pos1), len(pos2))
+    diffs = pos1[:n_common] - pos2[:n_common]
+    distances = np.linalg.norm(diffs, axis=1)
+    min_idx = int(np.argmin(distances))
+    min_dist = float(distances[min_idx])
+    tca_hours = min_idx * step_minutes / 60.0
+
+    return {
+        "tca_hours": round(tca_hours, 1),
+        "tca_min_distance_km": round(min_dist, 1),
+    }

src/data/density_features.py

@@ -0,0 +1,259 @@
+# Generated by Claude Code — 2026-02-13
+"""Orbital density features derived from the CRASH Clock framework.
+
+Computes population-level orbital density metrics for each conjunction event,
+based on the altitude distribution of all events in the training set.
+
+The key insight from Thiele et al. (2025) "An Orbital House of Cards":
+collision rate scales as n² * A_col * v_r — so a conjunction at a crowded
+altitude (550 km Starlink shell) is fundamentally riskier than the same
+miss_distance at a sparse altitude (1200 km).
+
+These features are computed from the TRAINING set only and applied to
+validation/test sets to prevent data leakage.
+"""
+
+import json
+import numpy as np
+import pandas as pd
+from pathlib import Path
+
+# Physical constants
+EARTH_RADIUS_KM = 6371.0
+GM_M3_S2 = 3.986004418e14  # Earth gravitational parameter (m³/s²)
+
+# CRASH Clock cross-sections from Thiele et al. Table (10m-5m-10cm)
+A_COL_SAT_SAT = 300.0     # m² (satellite-satellite, 10m approach)
+A_COL_SAT_DEBRIS = 79.0   # m² (satellite-debris, 5m approach)
+
+# Altitude binning
+BIN_WIDTH_KM = 25  # km per altitude bin
+ALT_MIN_KM = 150
+ALT_MAX_KM = 2100
+
+# Feature names that will be added to DataFrames
+DENSITY_FEATURES = [
+    "shell_density",           # events per km³ in altitude bin
+    "shell_collision_rate",    # Γ from CRASH Clock Eq. 2 (per second)
+    "local_crash_clock_log",   # log10(seconds to expected collision in shell)
+    "altitude_percentile",     # CDF position in event altitude distribution
+    "n_events_in_shell",       # raw count of training events at this altitude
+    "shell_risk_rate",         # fraction of high-risk events in this altitude bin
+]
+
+
+def _orbital_speed_kms(altitude_km: float) -> float:
+    """Circular orbital speed in km/s at a given altitude."""
+    r_m = (EARTH_RADIUS_KM + altitude_km) * 1000.0
+    return np.sqrt(GM_M3_S2 / r_m) / 1000.0  # m/s → km/s
+
+
+def _mean_relative_speed_kms(altitude_km: float) -> float:
+    """Average relative encounter speed: v_r = (4/3) * v_orbital (Eq. 7)."""
+    return (4.0 / 3.0) * _orbital_speed_kms(altitude_km)
+
+
+def _shell_volume_km3(altitude_km: float, width_km: float) -> float:
+    """Volume of a spherical shell at given altitude with given width."""
+    r_inner = EARTH_RADIUS_KM + altitude_km - width_km / 2.0
+    r_outer = EARTH_RADIUS_KM + altitude_km + width_km / 2.0
+    return (4.0 / 3.0) * np.pi * (r_outer**3 - r_inner**3)
+
+
+class OrbitalDensityComputer:
+    """Computes orbital density features from a training DataFrame.
+
+    Fit on training data, then transform any DataFrame (train/val/test)
+    to add density-based static features per event.
+
+    The density is computed from event altitudes, NOT from a full TLE
+    catalog, so it represents the conjunction density distribution rather
+    than the full RSO population. For the Kelvins dataset, this captures
+    where conjunction events cluster (which correlates with RSO density).
+    """
+
+    def __init__(self, bin_width_km: float = BIN_WIDTH_KM):
+        self.bin_width_km = bin_width_km
+        self.bin_edges = np.arange(ALT_MIN_KM, ALT_MAX_KM + bin_width_km, bin_width_km)
+        self.bin_centers = (self.bin_edges[:-1] + self.bin_edges[1:]) / 2.0
+        self.n_bins = len(self.bin_centers)
+
+        # Fitted state (populated by fit())
+        self.event_counts = None      # events per bin
+        self.density_per_bin = None   # events / km³ per bin
+        self.collision_rate = None    # Γ per bin (events/s)
+        self.crash_clock_log = None   # log10(seconds to collision) per bin
+        self.risk_rate_per_bin = None  # fraction high-risk per bin
+        self.altitude_cdf = None      # cumulative distribution
+        self.is_fitted = False
+
+    def _event_altitude(self, df: pd.DataFrame) -> np.ndarray:
+        """Compute conjunction altitude for each event (last CDM row).
+
+        Uses mean of target and chaser perigee altitudes as the approximate
+        conjunction altitude. Falls back to semi-major axis minus Earth radius.
+        """
+        event_df = df.groupby("event_id").last()
+
+        # Primary: mean of perigee altitudes (where most conjunctions happen)
+        t_alt = np.zeros(len(event_df))
+        c_alt = np.zeros(len(event_df))
+
+        if "t_h_per" in event_df.columns:
+            t_alt = event_df["t_h_per"].fillna(0).values
+        elif "t_j2k_sma" in event_df.columns:
+            t_alt = event_df["t_j2k_sma"].fillna(EARTH_RADIUS_KM).values - EARTH_RADIUS_KM
+
+        if "c_h_per" in event_df.columns:
+            c_alt = event_df["c_h_per"].fillna(0).values
+        elif "c_j2k_sma" in event_df.columns:
+            c_alt = event_df["c_j2k_sma"].fillna(EARTH_RADIUS_KM).values - EARTH_RADIUS_KM
+
+        altitudes = (t_alt + c_alt) / 2.0
+        # Clamp to valid range
+        altitudes = np.clip(altitudes, ALT_MIN_KM, ALT_MAX_KM - 1)
+        return altitudes, event_df.index.values
+
+    def fit(self, train_df: pd.DataFrame) -> "OrbitalDensityComputer":
+        """Fit density distribution from training data.
+
+        Must be called before transform(). Only uses training data
+        to prevent information leakage into validation/test sets.
+        """
+        altitudes, event_ids = self._event_altitude(train_df)
+
+        # Histogram: count events per altitude bin
+        self.event_counts, _ = np.histogram(altitudes, bins=self.bin_edges)
+
+        # Density: events per km³ in each shell
+        volumes = np.array([
+            _shell_volume_km3(c, self.bin_width_km)
+            for c in self.bin_centers
+        ])
+        self.density_per_bin = self.event_counts / np.maximum(volumes, 1e-6)
+
+        # Collision rate per shell: Γ = (1/2) * n² * A_col * v_r * V
+        # Using satellite-satellite cross-section as the primary concern
+        self.collision_rate = np.zeros(self.n_bins)
+        for i, (center, density, volume) in enumerate(
+            zip(self.bin_centers, self.density_per_bin, volumes)
+        ):
+            v_r = _mean_relative_speed_kms(center)  # km/s
+            # Convert A_col from m² to km², v_r already in km/s
+            a_col_km2 = A_COL_SAT_SAT / 1e6  # m² → km²
+            # Γ = 0.5 * n² * A * v_r * V  (units: per second)
+            gamma = 0.5 * density**2 * a_col_km2 * v_r * volume
+            self.collision_rate[i] = gamma
+
+        # CRASH Clock per shell: τ = 1/Γ (in seconds), log10 for feature
+        with np.errstate(divide="ignore"):
+            tau = 1.0 / np.maximum(self.collision_rate, 1e-30)
+        self.crash_clock_log = np.log10(np.clip(tau, 1.0, 1e15))
+
+        # Risk rate per bin: fraction of positive events
+        risk_per_event = train_df.groupby("event_id")["risk"].last()
+        is_high_risk = (risk_per_event > -5).astype(float).values
+
+        self.risk_rate_per_bin = np.zeros(self.n_bins)
+        for i in range(self.n_bins):
+            mask = (altitudes >= self.bin_edges[i]) & (altitudes < self.bin_edges[i + 1])
+            if mask.sum() > 0:
+                self.risk_rate_per_bin[i] = is_high_risk[mask].mean()
+
+        # Cumulative altitude distribution for percentile feature
+        sorted_alts = np.sort(altitudes)
+        self.altitude_cdf = sorted_alts
+
+        self.is_fitted = True
+        print(f"  OrbitalDensityComputer fitted on {len(event_ids)} events")
+        print(f"    Altitude range: {altitudes.min():.0f} - {altitudes.max():.0f} km")
+        print(f"    Peak density bin: {self.bin_centers[np.argmax(self.density_per_bin)]:.0f} km "
+              f"({self.event_counts.max()} events)")
+        peak_idx = np.argmax(self.collision_rate)
+        if self.collision_rate[peak_idx] > 0:
+            print(f"    Highest collision rate: {self.bin_centers[peak_idx]:.0f} km "
+                  f"(tau = {10**self.crash_clock_log[peak_idx]:.0f} s)")
+
+        return self
+
+    def _get_bin_index(self, altitudes: np.ndarray) -> np.ndarray:
+        """Map altitudes to bin indices."""
+        indices = np.digitize(altitudes, self.bin_edges) - 1
+        return np.clip(indices, 0, self.n_bins - 1)
+
+    def _altitude_percentile(self, altitudes: np.ndarray) -> np.ndarray:
+        """Compute percentile in the training altitude distribution."""
+        return np.searchsorted(self.altitude_cdf, altitudes) / len(self.altitude_cdf)
+
+    def transform(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Add density features to a CDM DataFrame.
+
+        Features are computed per event_id and broadcast to all CDM rows
+        (they're static features — same for every CDM in the sequence).
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must call fit() before transform()")
+
+        df = df.copy()
+        altitudes, event_ids = self._event_altitude(df)
+        bin_indices = self._get_bin_index(altitudes)
+
+        # Build event-level features
+        event_features = {}
+        for i, eid in enumerate(event_ids):
+            bi = bin_indices[i]
+            event_features[eid] = {
+                "shell_density": self.density_per_bin[bi],
+                "shell_collision_rate": self.collision_rate[bi],
+                "local_crash_clock_log": self.crash_clock_log[bi],
+                "altitude_percentile": self._altitude_percentile(
+                    np.array([altitudes[i]])
+                )[0],
+                "n_events_in_shell": float(self.event_counts[bi]),
+                "shell_risk_rate": self.risk_rate_per_bin[bi],
+            }
+
+        # Map features to all CDM rows via event_id
+        for col in DENSITY_FEATURES:
+            df[col] = df["event_id"].map(
+                {eid: feats[col] for eid, feats in event_features.items()}
+            ).fillna(0.0)
+
+        return df
+
+    def save(self, path: Path):
+        """Save fitted state to JSON for inference."""
+        if not self.is_fitted:
+            raise RuntimeError("Must call fit() before save()")
+        state = {
+            "bin_width_km": self.bin_width_km,
+            "bin_edges": self.bin_edges.tolist(),
+            "bin_centers": self.bin_centers.tolist(),
+            "event_counts": self.event_counts.tolist(),
+            "density_per_bin": self.density_per_bin.tolist(),
+            "collision_rate": self.collision_rate.tolist(),
+            "crash_clock_log": self.crash_clock_log.tolist(),
+            "risk_rate_per_bin": self.risk_rate_per_bin.tolist(),
+            "altitude_cdf": self.altitude_cdf.tolist(),
+        }
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            json.dump(state, f, indent=2)
+
+    @classmethod
+    def load(cls, path: Path) -> "OrbitalDensityComputer":
+        """Load fitted state from JSON."""
+        with open(path) as f:
+            state = json.load(f)
+        obj = cls(bin_width_km=state["bin_width_km"])
+        obj.bin_edges = np.array(state["bin_edges"])
+        obj.bin_centers = np.array(state["bin_centers"])
+        obj.n_bins = len(obj.bin_centers)
+        obj.event_counts = np.array(state["event_counts"])
+        obj.density_per_bin = np.array(state["density_per_bin"])
+        obj.collision_rate = np.array(state["collision_rate"])
+        obj.crash_clock_log = np.array(state["crash_clock_log"])
+        obj.risk_rate_per_bin = np.array(state["risk_rate_per_bin"])
+        obj.altitude_cdf = np.array(state["altitude_cdf"])
+        obj.is_fitted = True
+        return obj

src/data/firebase_client.py

@@ -0,0 +1,159 @@
+# Generated by Claude Code -- 2026-02-13
+"""Firebase Firestore client for prediction logging.
+
+Stores daily conjunction predictions and maneuver detection outcomes.
+Uses the Firestore REST API to avoid heavy SDK dependencies.
+Falls back to local JSONL logging if Firebase is not configured.
+
+Environment variables:
+    FIREBASE_SERVICE_ACCOUNT: JSON string of the service account key
+    FIREBASE_PROJECT_ID: Project ID (auto-detected from service account if not set)
+"""
+
+import os
+import json
+import time
+import numpy as np
+from pathlib import Path
+from datetime import datetime, timezone
+
+
+def _json_default(obj):
+    """Handle numpy types that json.dumps can't serialize."""
+    if isinstance(obj, (np.integer,)):
+        return int(obj)
+    if isinstance(obj, (np.floating,)):
+        return float(obj)
+    if isinstance(obj, (np.bool_,)):
+        return bool(obj)
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+# Try to import google-cloud-firestore (lightweight)
+try:
+    from google.cloud.firestore import Client as FirestoreClient
+    from google.oauth2.service_account import Credentials
+    HAS_FIRESTORE = True
+except ImportError:
+    HAS_FIRESTORE = False
+
+
+class PredictionLogger:
+    """Log predictions to Firebase Firestore with local JSONL fallback."""
+
+    def __init__(self, local_dir: Path = None):
+        self.db = None
+        self.local_dir = local_dir or Path("data/prediction_logs")
+        self.local_dir.mkdir(parents=True, exist_ok=True)
+        self._init_firebase()
+
+    def _init_firebase(self):
+        """Initialize Firebase Firestore client from environment."""
+        sa_json = os.environ.get("FIREBASE_SERVICE_ACCOUNT", "")
+        if not sa_json or not HAS_FIRESTORE:
+            if not HAS_FIRESTORE:
+                print("  Firebase SDK not installed (pip install google-cloud-firestore)")
+            print("  Using local JSONL logging only")
+            return
+
+        try:
+            sa_info = json.loads(sa_json)
+            creds = Credentials.from_service_account_info(sa_info)
+            project_id = sa_info.get("project_id", os.environ.get("FIREBASE_PROJECT_ID", ""))
+            self.db = FirestoreClient(project=project_id, credentials=creds)
+            print(f"  Firebase Firestore connected (project: {project_id})")
+        except Exception as e:
+            print(f"  Firebase init failed: {e}")
+            print("  Falling back to local JSONL logging")
+
+    def log_predictions(self, date_str: str, predictions: list[dict]):
+        """Log a batch of daily predictions.
+
+        Args:
+            date_str: Date string (YYYY-MM-DD)
+            predictions: List of prediction dicts with keys:
+                sat1_norad, sat2_norad, sat1_name, sat2_name,
+                risk_score, altitude_km, model_used
+        """
+        # Always save locally
+        local_file = self.local_dir / f"{date_str}.jsonl"
+        with open(local_file, "a") as f:
+            for pred in predictions:
+                pred["date"] = date_str
+                pred["logged_at"] = datetime.now(timezone.utc).isoformat()
+                f.write(json.dumps(pred, default=_json_default) + "\n")
+        print(f"  Saved {len(predictions)} predictions to {local_file}")
+
+        # Firebase upload
+        if self.db:
+            try:
+                batch = self.db.batch()
+                collection = self.db.collection("predictions").document(date_str)
+                collection.set({"date": date_str, "count": len(predictions)})
+
+                for i, pred in enumerate(predictions):
+                    doc_ref = self.db.collection("predictions").document(date_str) \
+                        .collection("pairs").document(f"pair_{i:04d}")
+                    batch.set(doc_ref, pred)
+
+                batch.commit()
+                print(f"  Uploaded {len(predictions)} predictions to Firebase")
+            except Exception as e:
+                print(f"  Firebase upload failed: {e}")
+
+    def log_outcomes(self, date_str: str, outcomes: list[dict]):
+        """Log maneuver detection outcomes for a previous prediction date.
+
+        Args:
+            date_str: Original prediction date (YYYY-MM-DD)
+            outcomes: List of outcome dicts with keys:
+                sat1_norad, sat2_norad, sat1_maneuvered, sat2_maneuvered,
+                sat1_delta_a_m, sat2_delta_a_m, validated_at
+        """
+        local_file = self.local_dir / f"{date_str}_outcomes.jsonl"
+        with open(local_file, "a") as f:
+            for outcome in outcomes:
+                outcome["prediction_date"] = date_str
+                outcome["validated_at"] = datetime.now(timezone.utc).isoformat()
+                f.write(json.dumps(outcome, default=_json_default) + "\n")
+        print(f"  Saved {len(outcomes)} outcomes to {local_file}")
+
+        if self.db:
+            try:
+                batch = self.db.batch()
+                for i, outcome in enumerate(outcomes):
+                    doc_ref = self.db.collection("outcomes").document(date_str) \
+                        .collection("results").document(f"result_{i:04d}")
+                    batch.set(doc_ref, outcome)
+                batch.commit()
+                print(f"  Uploaded {len(outcomes)} outcomes to Firebase")
+            except Exception as e:
+                print(f"  Firebase upload failed: {e}")
+
+    def log_daily_summary(self, date_str: str, summary: dict):
+        """Log a daily summary (n_predictions, n_maneuvers_detected, accuracy, etc)."""
+        local_file = self.local_dir / "daily_summaries.jsonl"
+        summary["date"] = date_str
+        with open(local_file, "a") as f:
+            f.write(json.dumps(summary, default=_json_default) + "\n")
+
+        if self.db:
+            try:
+                self.db.collection("daily_summaries").document(date_str).set(summary)
+                print(f"  Uploaded daily summary to Firebase")
+            except Exception as e:
+                print(f"  Firebase summary upload failed: {e}")
+
+    def get_predictions_for_date(self, date_str: str) -> list[dict]:
+        """Retrieve predictions for a date (from local files)."""
+        local_file = self.local_dir / f"{date_str}.jsonl"
+        if not local_file.exists():
+            return []
+        predictions = []
+        with open(local_file) as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    predictions.append(json.loads(line))
+        return predictions

src/data/maneuver_classifier.py

@@ -0,0 +1,143 @@
+"""Classify detected satellite maneuvers into avoidance vs routine.
+
+Enriches each maneuver with:
+  - magnitude_class: micro/small/medium/large based on delta-v
+  - constellation: starlink/oneweb/iridium/other
+  - is_stationkeeping: regularity-based detection from maneuver history
+  - likely_avoidance: heuristic combining all signals
+
+These enrichments improve training label quality for PI-TFT fine-tuning
+without changing the model's feature space.
+"""
+
+import re
+import numpy as np
+from datetime import datetime
+
+
+# Delta-v magnitude bins (m/s)
+MAGNITUDE_BINS = [
+    ("micro", 0.0, 0.5),
+    ("small", 0.5, 2.0),
+    ("medium", 2.0, 10.0),
+    ("large", 10.0, float("inf")),
+]
+
+# Constellation name patterns
+CONSTELLATION_PATTERNS = [
+    ("starlink", re.compile(r"STARLINK", re.IGNORECASE)),
+    ("oneweb", re.compile(r"ONEWEB", re.IGNORECASE)),
+    ("iridium", re.compile(r"IRIDIUM", re.IGNORECASE)),
+]
+
+# Stationkeeping regularity threshold (coefficient of variation of intervals)
+STATIONKEEPING_CV_THRESHOLD = 0.3
+MIN_HISTORY_FOR_SK = 3  # Need at least 3 past maneuvers to detect pattern
+
+
+def classify_magnitude(delta_v_m_s: float) -> str:
+    """Bin delta-v into magnitude class."""
+    dv = abs(delta_v_m_s)
+    for label, lo, hi in MAGNITUDE_BINS:
+        if lo <= dv < hi:
+            return label
+    return "large"
+
+
+def detect_constellation(name: str) -> str:
+    """Identify constellation from satellite name."""
+    for constellation, pattern in CONSTELLATION_PATTERNS:
+        if pattern.search(name):
+            return constellation
+    return "other"
+
+
+def detect_stationkeeping(history: list[dict]) -> bool:
+    """Detect stationkeeping from regularity of past maneuver intervals.
+
+    If the coefficient of variation (std/mean) of time intervals between
+    consecutive maneuvers is below threshold, it's likely stationkeeping.
+
+    Args:
+        history: Past maneuver records for this NORAD ID, each with
+                 'detected_at' ISO timestamp.
+
+    Returns:
+        True if maneuver pattern suggests stationkeeping.
+    """
+    if not history or len(history) < MIN_HISTORY_FOR_SK:
+        return False
+
+    # Parse timestamps and sort
+    timestamps = []
+    for h in history:
+        ts_str = h.get("detected_at", "")
+        if not ts_str:
+            continue
+        try:
+            ts = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
+            timestamps.append(ts.timestamp())
+        except (ValueError, TypeError):
+            continue
+
+    if len(timestamps) < MIN_HISTORY_FOR_SK:
+        return False
+
+    timestamps.sort()
+    intervals = np.diff(timestamps)
+
+    if len(intervals) < 2:
+        return False
+
+    mean_interval = np.mean(intervals)
+    if mean_interval <= 0:
+        return False
+
+    cv = np.std(intervals) / mean_interval
+    return cv < STATIONKEEPING_CV_THRESHOLD
+
+
+def classify_maneuver(maneuver: dict, history: list[dict] = None) -> dict:
+    """Classify a detected maneuver with enrichment flags.
+
+    Args:
+        maneuver: Maneuver dict from detect_maneuvers() with keys:
+                  norad_id, name, delta_v_m_s, delta_a_m, etc.
+        history: Past maneuver records for same NORAD ID (optional).
+
+    Returns:
+        Dict with enrichment fields added to the original maneuver.
+    """
+    delta_v = maneuver.get("delta_v_m_s", 0.0)
+    name = maneuver.get("name", "")
+
+    magnitude_class = classify_magnitude(delta_v)
+    constellation = detect_constellation(name)
+    is_sk = detect_stationkeeping(history) if history else False
+
+    # Likely avoidance heuristic
+    likely_avoidance = False
+
+    if not is_sk and magnitude_class in ("micro", "small") and delta_v < 5.0:
+        likely_avoidance = True
+
+    # Starlink CAMs are typically very small (< 1 m/s)
+    if constellation == "starlink" and delta_v < 1.0:
+        likely_avoidance = True
+
+    enriched = dict(maneuver)
+    enriched.update({
+        "magnitude_class": magnitude_class,
+        "constellation": constellation,
+        "is_stationkeeping": is_sk,
+        "likely_avoidance": likely_avoidance,
+        "enrichment_version": 1,
+        # Phase B/C defaults — overwritten later if data is available
+        "has_cdm": False,
+        "cdm_pc": None,
+        "cdm_miss_distance_km": None,
+        "counterfactual_min_distance_km": None,
+        "would_have_collided": False,
+        "counterfactual_closest_norad": None,
+    })
+    return enriched

src/data/maneuver_detector.py

@@ -0,0 +1,205 @@
+# Generated by Claude Code -- 2026-02-13
+"""Detect satellite maneuvers from TLE data changes.
+
+Compares successive TLEs for the same satellite. An abrupt change in
+semi-major axis (> threshold) indicates a maneuver — either collision
+avoidance, orbit maintenance, or orbit raising.
+
+Based on Kelecy (2007) and Patera & Peterson (2021).
+"""
+
+import json
+import math
+import numpy as np
+from pathlib import Path
+from datetime import datetime, timedelta, timezone
+
+
+# Earth parameters (WGS84)
+MU_EARTH = 398600.4418  # km^3/s^2
+EARTH_RADIUS_KM = 6378.137
+
+# Maneuver detection thresholds
+DEFAULT_DELTA_A_THRESHOLD_M = 200  # meters — below this is noise
+STARLINK_DELTA_A_THRESHOLD_M = 100  # Starlink maneuvers can be smaller
+
+
+def mean_motion_to_sma(n_rev_per_day: float) -> float:
+    """Convert mean motion (rev/day) to semi-major axis (km)."""
+    if n_rev_per_day <= 0:
+        return 0.0
+    n_rad_per_sec = n_rev_per_day * 2 * math.pi / 86400.0
+    return (MU_EARTH / (n_rad_per_sec ** 2)) ** (1.0 / 3.0)
+
+
+def sma_to_altitude(sma_km: float) -> float:
+    """Convert semi-major axis to approximate altitude (km)."""
+    return sma_km - EARTH_RADIUS_KM
+
+
+def parse_tle_epoch(epoch_str: str) -> datetime:
+    """Parse a CelesTrak JSON epoch string (ISO 8601 format)."""
+    # CelesTrak uses: "2026-02-13T12:00:00.000000"
+    for fmt in ("%Y-%m-%dT%H:%M:%S.%f", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(epoch_str, fmt)
+        except ValueError:
+            continue
+    raise ValueError(f"Cannot parse epoch: {epoch_str}")
+
+
+def extract_orbital_elements(tle_json: dict) -> dict:
+    """Extract key orbital elements from a CelesTrak JSON TLE entry."""
+    norad_id = int(tle_json.get("NORAD_CAT_ID", 0))
+    name = tle_json.get("OBJECT_NAME", "UNKNOWN")
+    mean_motion = float(tle_json.get("MEAN_MOTION", 0))
+    eccentricity = float(tle_json.get("ECCENTRICITY", 0))
+    inclination = float(tle_json.get("INCLINATION", 0))
+    raan = float(tle_json.get("RA_OF_ASC_NODE", 0))
+    epoch_str = tle_json.get("EPOCH", "")
+
+    sma = mean_motion_to_sma(mean_motion)
+    altitude = sma_to_altitude(sma)
+
+    epoch = None
+    if epoch_str:
+        try:
+            epoch = parse_tle_epoch(epoch_str)
+        except ValueError:
+            pass
+
+    return {
+        "norad_id": norad_id,
+        "name": name,
+        "mean_motion": mean_motion,
+        "eccentricity": eccentricity,
+        "inclination": inclination,
+        "raan": raan,
+        "sma_km": sma,
+        "altitude_km": altitude,
+        "epoch": epoch,
+        "epoch_str": epoch_str,
+    }
+
+
+def detect_maneuvers(
+    prev_tles: list[dict],
+    curr_tles: list[dict],
+    threshold_m: float = DEFAULT_DELTA_A_THRESHOLD_M,
+) -> list[dict]:
+    """Compare two TLE snapshots and detect maneuvers.
+
+    Args:
+        prev_tles: Previous TLE snapshot (CelesTrak JSON format)
+        curr_tles: Current TLE snapshot (CelesTrak JSON format)
+        threshold_m: Semi-major axis change threshold in meters
+
+    Returns:
+        List of detected maneuvers with details
+    """
+    # Index previous TLEs by NORAD ID
+    prev_by_id = {}
+    for tle in prev_tles:
+        elem = extract_orbital_elements(tle)
+        if elem["norad_id"] > 0 and elem["sma_km"] > 0:
+            prev_by_id[elem["norad_id"]] = elem
+
+    maneuvers = []
+    for tle in curr_tles:
+        elem = extract_orbital_elements(tle)
+        norad_id = elem["norad_id"]
+
+        if norad_id not in prev_by_id or elem["sma_km"] <= 0:
+            continue
+
+        prev = prev_by_id[norad_id]
+        delta_a_km = elem["sma_km"] - prev["sma_km"]
+        delta_a_m = abs(delta_a_km) * 1000
+
+        if delta_a_m > threshold_m:
+            # Classify maneuver type
+            if delta_a_km > 0:
+                maneuver_type = "orbit_raise"
+            else:
+                maneuver_type = "orbit_lower"
+
+            # Estimate delta-v (Hohmann approximation)
+            v_circular = math.sqrt(MU_EARTH / prev["sma_km"])  # km/s
+            delta_v = abs(delta_a_km) / (2 * prev["sma_km"]) * v_circular * 1000  # m/s
+
+            maneuvers.append({
+                "norad_id": norad_id,
+                "name": elem["name"],
+                "prev_sma_km": prev["sma_km"],
+                "curr_sma_km": elem["sma_km"],
+                "delta_a_m": delta_a_m,
+                "delta_a_km": delta_a_km,
+                "delta_v_m_s": round(delta_v, 3),
+                "maneuver_type": maneuver_type,
+                "altitude_km": elem["altitude_km"],
+                "prev_epoch": prev["epoch_str"],
+                "curr_epoch": elem["epoch_str"],
+                "detected_at": datetime.now(timezone.utc).isoformat(),
+            })
+
+    # Sort by delta_a descending (largest maneuvers first)
+    maneuvers.sort(key=lambda m: m["delta_a_m"], reverse=True)
+    return maneuvers
+
+
+def detect_maneuvers_dual_threshold(
+    prev_tles: list[dict],
+    curr_tles: list[dict],
+) -> list[dict]:
+    """Detect maneuvers using constellation-aware thresholds.
+
+    Uses 100m threshold for Starlink (smaller maneuvers) and
+    200m for everything else. Merges results, deduplicating by NORAD ID.
+    """
+    # Split current TLEs by constellation
+    starlink_curr = []
+    other_curr = []
+    for tle in curr_tles:
+        name = tle.get("OBJECT_NAME", "")
+        if "STARLINK" in name.upper():
+            starlink_curr.append(tle)
+        else:
+            other_curr.append(tle)
+
+    # Split previous TLEs the same way
+    starlink_prev = []
+    other_prev = []
+    for tle in prev_tles:
+        name = tle.get("OBJECT_NAME", "")
+        if "STARLINK" in name.upper():
+            starlink_prev.append(tle)
+        else:
+            other_prev.append(tle)
+
+    # Detect with appropriate thresholds
+    starlink_maneuvers = detect_maneuvers(
+        starlink_prev, starlink_curr,
+        threshold_m=STARLINK_DELTA_A_THRESHOLD_M,
+    )
+    other_maneuvers = detect_maneuvers(
+        other_prev, other_curr,
+        threshold_m=DEFAULT_DELTA_A_THRESHOLD_M,
+    )
+
+    # Merge and sort by delta_a descending
+    all_maneuvers = starlink_maneuvers + other_maneuvers
+    all_maneuvers.sort(key=lambda m: m["delta_a_m"], reverse=True)
+    return all_maneuvers
+
+
+def load_tle_snapshot(path: Path) -> list[dict]:
+    """Load a TLE snapshot from a JSON file."""
+    with open(path) as f:
+        return json.load(f)
+
+
+def save_tle_snapshot(tles: list[dict], path: Path):
+    """Save a TLE snapshot to a JSON file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(tles, f)

src/data/merge_sources.py

@@ -0,0 +1,270 @@
+# Generated by Claude Code -- 2026-02-08
+"""Merge CDM data from multiple sources into unified training format.
+
+Combines:
+  1. ESA Kelvins dataset (103 features, labeled)
+  2. Space-Track cdm_public (16 features, unlabeled — derive risk from PC)
+
+Strategy:
+  - Space-Track CDMs are grouped into "conjunction events" by (SAT_1_ID, SAT_2_ID, TCA_date)
+  - Each event gets a time series of CDMs ordered by CREATED date
+  - Risk label derived from final PC: high risk if PC > 1e-5 (same threshold as Kelvins)
+  - Features that exist in both sources get unified column names
+  - Missing features (e.g., covariance in Space-Track) are filled with 0
+
+This gives us far more positive examples for training the risk classifier,
+even though the Space-Track data has fewer features per CDM.
+"""
+
+import numpy as np
+import pandas as pd
+from pathlib import Path
+from datetime import timedelta
+
+
+# Mapping from Space-Track CDM_PUBLIC fields → unified column names
+SPACETRACK_COLUMN_MAP = {
+    "CDM_ID": "cdm_id",
+    "CREATED": "created",
+    "TCA": "tca",
+    "MIN_RNG": "miss_distance",      # km in Space-Track
+    "PC": "collision_probability",
+    "SAT_1_ID": "sat_1_id",
+    "SAT_1_NAME": "sat_1_name",
+    "SAT1_OBJECT_TYPE": "t_object_type",
+    "SAT1_RCS": "t_rcs",
+    "SAT_1_EXCL_VOL": "t_excl_vol",
+    "SAT_2_ID": "sat_2_id",
+    "SAT_2_NAME": "sat_2_name",
+    "SAT2_OBJECT_TYPE": "c_object_type",
+    "SAT2_RCS": "c_rcs",
+    "SAT_2_EXCL_VOL": "c_excl_vol",
+    "EMERGENCY_REPORTABLE": "emergency_reportable",
+}
+
+# Risk threshold: PC > 1e-5 = high risk (matches ESA Kelvins: risk > -5)
+RISK_THRESHOLD = 1e-5
+
+
+def load_spacetrack_cdms(csv_path: Path) -> pd.DataFrame:
+    """Load Space-Track CDM CSV and do initial cleaning."""
+    df = pd.read_csv(csv_path)
+
+    # Rename columns to unified format
+    df = df.rename(columns=SPACETRACK_COLUMN_MAP)
+
+    # Parse dates
+    for col in ["created", "tca"]:
+        if col in df.columns:
+            df[col] = pd.to_datetime(df[col], errors="coerce")
+
+    # Convert miss_distance to float
+    if "miss_distance" in df.columns:
+        df["miss_distance"] = pd.to_numeric(df["miss_distance"], errors="coerce")
+        # Space-Track MIN_RNG is in km; ESA Kelvins miss_distance is in meters
+        # Convert to meters for consistency
+        df["miss_distance"] = df["miss_distance"] * 1000.0
+
+    # Convert collision_probability to float
+    if "collision_probability" in df.columns:
+        df["collision_probability"] = pd.to_numeric(df["collision_probability"], errors="coerce")
+
+    # Derive risk column (log10 of PC, matching ESA format)
+    if "collision_probability" in df.columns:
+        df["risk"] = np.where(
+            df["collision_probability"] > 0,
+            np.log10(df["collision_probability"].clip(lower=1e-30)),
+            -30.0,
+        )
+
+    print(f"Loaded {len(df)} Space-Track CDMs from {csv_path.name}")
+    return df
+
+
+def group_into_events(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Group Space-Track CDMs into conjunction events.
+
+    An 'event' is a sequence of CDMs for the same object pair with TCA
+    values within 1 day of each other. Each event gets a unique event_id.
+    """
+    if df.empty:
+        return df
+
+    # Sort by object pair and TCA
+    df = df.sort_values(["sat_1_id", "sat_2_id", "tca", "created"]).reset_index(drop=True)
+
+    # Assign event IDs: same pair + TCA within 1 day = same event
+    event_ids = []
+    current_event = 0
+    prev_sat1 = None
+    prev_sat2 = None
+    prev_tca = None
+
+    for _, row in df.iterrows():
+        sat1 = row.get("sat_1_id")
+        sat2 = row.get("sat_2_id")
+        tca = row.get("tca")
+
+        same_pair = (sat1 == prev_sat1 and sat2 == prev_sat2)
+        close_tca = False
+        if same_pair and prev_tca is not None and pd.notna(tca) and pd.notna(prev_tca):
+            close_tca = abs((tca - prev_tca).total_seconds()) < 86400  # 1 day
+
+        if not (same_pair and close_tca):
+            current_event += 1
+
+        event_ids.append(current_event)
+        prev_sat1 = sat1
+        prev_sat2 = sat2
+        prev_tca = tca
+
+    df["event_id"] = event_ids
+
+    # Compute time_to_tca: days from CDM creation to TCA (for each CDM in event)
+    if "created" in df.columns and "tca" in df.columns:
+        df["time_to_tca"] = (df["tca"] - df["created"]).dt.total_seconds() / 86400.0
+        df["time_to_tca"] = df["time_to_tca"].clip(lower=0.0)
+
+    n_events = df["event_id"].nunique()
+    n_high_risk = 0
+    if "risk" in df.columns:
+        event_risks = df.groupby("event_id")["risk"].last()
+        n_high_risk = (event_risks > -5).sum()
+
+    print(f"Grouped into {n_events} events ({n_high_risk} high-risk)")
+    return df
+
+
+def compute_relative_speed_from_excl_vol(df: pd.DataFrame) -> pd.DataFrame:
+    """Estimate relative speed from exclusion volumes if available."""
+    # excl_vol is in km, but we can't derive speed from it alone
+    # Just ensure the column exists for compatibility
+    if "relative_speed" not in df.columns:
+        df["relative_speed"] = 0.0
+    return df
+
+
+def align_with_kelvins_schema(
+    spacetrack_df: pd.DataFrame,
+    kelvins_df: pd.DataFrame,
+) -> pd.DataFrame:
+    """
+    Align Space-Track data columns with Kelvins schema.
+    Missing columns get filled with 0.
+    """
+    # Get all columns from Kelvins
+    kelvins_cols = set(kelvins_df.columns)
+    st_cols = set(spacetrack_df.columns)
+
+    # Add missing numeric columns as 0
+    for col in kelvins_cols:
+        if col not in st_cols:
+            spacetrack_df[col] = 0.0
+
+    # Keep only columns that exist in Kelvins + our extra metadata
+    extra_cols = {"sat_1_id", "sat_2_id", "sat_1_name", "sat_2_name",
+                  "t_object_type", "collision_probability", "created", "tca",
+                  "cdm_id", "emergency_reportable", "t_rcs", "c_rcs",
+                  "t_excl_vol", "c_excl_vol", "source"}
+    keep_cols = list(kelvins_cols | extra_cols)
+    available = [c for c in keep_cols if c in spacetrack_df.columns]
+    return spacetrack_df[available]
+
+
+def merge_datasets(
+    kelvins_train_df: pd.DataFrame,
+    spacetrack_df: pd.DataFrame,
+    offset_event_ids: bool = True,
+) -> pd.DataFrame:
+    """
+    Merge Kelvins training data with Space-Track CDMs.
+
+    Args:
+        kelvins_train_df: ESA Kelvins training DataFrame
+        spacetrack_df: Space-Track CDMs (already grouped into events)
+        offset_event_ids: shift Space-Track event_ids to avoid collisions
+
+    Returns:
+        Combined DataFrame ready for model training
+    """
+    # Tag sources
+    kelvins_train_df = kelvins_train_df.copy()
+    kelvins_train_df["source"] = "kelvins"
+
+    spacetrack_df = spacetrack_df.copy()
+    spacetrack_df["source"] = "spacetrack"
+
+    # Offset Space-Track event IDs to avoid collision with Kelvins IDs
+    if offset_event_ids and "event_id" in kelvins_train_df.columns:
+        max_kelvins_id = kelvins_train_df["event_id"].max()
+        spacetrack_df["event_id"] = spacetrack_df["event_id"] + max_kelvins_id + 1
+
+    # Align columns
+    spacetrack_df = align_with_kelvins_schema(spacetrack_df, kelvins_train_df)
+
+    # Concatenate
+    combined = pd.concat([kelvins_train_df, spacetrack_df], ignore_index=True)
+
+    # Fill any remaining NaN
+    numeric_cols = combined.select_dtypes(include=[np.number]).columns
+    combined[numeric_cols] = combined[numeric_cols].fillna(0)
+
+    n_kelvins = kelvins_train_df["event_id"].nunique()
+    n_st = spacetrack_df["event_id"].nunique()
+    n_total = combined["event_id"].nunique()
+
+    # Count high-risk events per source
+    event_risk = combined.groupby(["event_id", "source"])["risk"].last().reset_index()
+    n_hr_kelvins = ((event_risk["source"] == "kelvins") & (event_risk["risk"] > -5)).sum()
+    n_hr_st = ((event_risk["source"] == "spacetrack") & (event_risk["risk"] > -5)).sum()
+
+    print(f"\nMerged dataset:")
+    print(f"  Kelvins:     {n_kelvins} events ({n_hr_kelvins} high-risk)")
+    print(f"  Space-Track: {n_st} events ({n_hr_st} high-risk)")
+    print(f"  Total:       {n_total} events ({n_hr_kelvins + n_hr_st} high-risk)")
+    print(f"  Columns:     {len(combined.columns)}")
+
+    return combined
+
+
+def load_and_merge_all(data_dir: Path) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Load all available data sources and merge into train/test DataFrames.
+
+    Returns (train_df, test_df) — test is Kelvins-only (for fair comparison).
+    """
+    from src.data.cdm_loader import load_dataset
+
+    # Load ESA Kelvins
+    kelvins_dir = data_dir / "cdm"
+    kelvins_train, kelvins_test = load_dataset(kelvins_dir)
+
+    # Load Space-Track data if available
+    spacetrack_dir = data_dir / "cdm_spacetrack"
+    spacetrack_files = list(spacetrack_dir.glob("cdm_*.csv")) if spacetrack_dir.exists() else []
+
+    if not spacetrack_files:
+        print("\nNo Space-Track data found. Using Kelvins only.")
+        return kelvins_train, kelvins_test
+
+    # Load and merge all Space-Track CSVs
+    st_dfs = []
+    for f in spacetrack_files:
+        if f.name.startswith("checkpoint"):
+            continue
+        df = load_spacetrack_cdms(f)
+        df = group_into_events(df)
+        df = compute_relative_speed_from_excl_vol(df)
+        st_dfs.append(df)
+
+    if st_dfs:
+        all_st = pd.concat(st_dfs, ignore_index=True)
+        # Re-assign event IDs after concatenation
+        all_st = group_into_events(all_st)
+        merged_train = merge_datasets(kelvins_train, all_st)
+    else:
+        merged_train = kelvins_train
+
+    # Test set stays Kelvins-only for fair benchmarking
+    return merged_train, kelvins_test

src/data/sequence_builder.py

@@ -0,0 +1,497 @@
+# Generated by Claude Code -- 2026-02-08
+"""Build padded CDM sequences for the Temporal Fusion Transformer.
+
+Each conjunction event is a variable-length time series of CDM snapshots.
+This module handles:
+  - Selecting temporal vs static features
+  - Padding/truncating to fixed length
+  - Creating attention masks for padded positions
+  - Train/val/test splitting with stratification
+"""
+
+import numpy as np
+import pandas as pd
+import torch
+from torch.utils.data import Dataset
+from sklearn.model_selection import train_test_split
+from pathlib import Path
+
+# Maximum CDM sequence length (95th percentile of real data is ~25)
+MAX_SEQ_LEN = 30
+
+# Features that change with each CDM update (time-varying)
+TEMPORAL_FEATURES = [
+    "miss_distance",
+    "relative_speed",
+    "relative_position_r", "relative_position_t", "relative_position_n",
+    "relative_velocity_r", "relative_velocity_t", "relative_velocity_n",
+    "max_risk_estimate", "max_risk_scaling",
+    # Target object covariance
+    "t_sigma_r", "t_sigma_t", "t_sigma_n",
+    "t_sigma_rdot", "t_sigma_tdot", "t_sigma_ndot",
+    # Chaser object covariance
+    "c_sigma_r", "c_sigma_t", "c_sigma_n",
+    "c_sigma_rdot", "c_sigma_tdot", "c_sigma_ndot",
+]
+
+# Features that are constant per event (object properties)
+STATIC_FEATURES = [
+    "t_h_apo", "t_h_per", "t_j2k_sma", "t_j2k_inc", "t_ecc",
+    "c_h_apo", "c_h_per", "c_j2k_sma", "c_j2k_inc", "c_ecc",
+    "t_span", "c_span",
+]
+
+# Orbital density features from CRASH Clock analysis (added by OrbitalDensityComputer)
+DENSITY_FEATURES = [
+    "shell_density",
+    "shell_collision_rate",
+    "local_crash_clock_log",
+    "altitude_percentile",
+    "n_events_in_shell",
+    "shell_risk_rate",
+]
+
+
+def find_available_features(df: pd.DataFrame, candidates: list[str]) -> list[str]:
+    """Filter feature list to only columns that exist in the DataFrame."""
+    available = [c for c in candidates if c in df.columns]
+    missing = [c for c in candidates if c not in df.columns]
+    if missing:
+        print(f"  Note: {len(missing)} features not in dataset, using {len(available)}")
+    return available
+
+
+class CDMSequenceDataset(Dataset):
+    """
+    PyTorch Dataset that serves padded CDM sequences for the Transformer.
+
+    Each item contains:
+      - temporal_features: (S, F_t) tensor of time-varying CDM features
+      - static_features:   (F_s,) tensor of object properties
+      - time_to_tca:       (S, 1) tensor of time-to-closest-approach values
+      - mask:              (S,) boolean mask (True = real data, False = padding)
+      - risk_label:        scalar binary target
+      - miss_distance_log: scalar log1p(final_miss_distance) target
+    """
+
+    def __init__(
+        self,
+        df: pd.DataFrame,
+        max_seq_len: int = MAX_SEQ_LEN,
+        temporal_cols: list[str] = None,
+        static_cols: list[str] = None,
+    ):
+        self.max_seq_len = max_seq_len
+
+        # Find available features
+        self.temporal_cols = temporal_cols or find_available_features(df, TEMPORAL_FEATURES)
+        self.static_cols = static_cols or find_available_features(df, STATIC_FEATURES)
+
+        print(f"  Temporal features: {len(self.temporal_cols)}")
+        print(f"  Static features:   {len(self.static_cols)}")
+
+        # Group by event_id
+        self.events = []
+        for event_id, group in df.groupby("event_id"):
+            # Sort by time_to_tca descending (first CDM = furthest from TCA)
+            group = group.sort_values("time_to_tca", ascending=False)
+            # Track data source for domain weighting
+            source = "kelvins"
+            if "source" in group.columns:
+                source = group["source"].iloc[0]
+            self.events.append({
+                "event_id": event_id,
+                "group": group,
+                "source": source,
+            })
+
+        # Compute global normalization stats from training data
+        self.temporal_mean = df[self.temporal_cols].mean().values.astype(np.float32)
+        self.temporal_std = df[self.temporal_cols].std().values.astype(np.float32)
+        self.temporal_std[self.temporal_std < 1e-8] = 1.0  # avoid div by zero
+
+        self.static_mean = df[self.static_cols].mean().values.astype(np.float32)
+        self.static_std = df[self.static_cols].std().values.astype(np.float32)
+        self.static_std[self.static_std < 1e-8] = 1.0
+
+        # Normalize time_to_tca
+        self.tca_mean = float(df["time_to_tca"].mean())
+        self.tca_std = float(df["time_to_tca"].std())
+        if self.tca_std < 1e-8:
+            self.tca_std = 1.0
+
+        # Compute delta normalization stats (approx from per-step differences)
+        # Deltas have different magnitude than raw features, need separate stats
+        self._compute_delta_stats(df)
+
+    def _compute_delta_stats(self, df: pd.DataFrame):
+        """Estimate normalization stats for temporal first-order differences."""
+        # Sample a subset of events to estimate delta distributions
+        delta_samples = []
+        for _, group in df.groupby("event_id"):
+            if len(group) < 2:
+                continue
+            vals = group[self.temporal_cols].values.astype(np.float32)
+            vals = np.nan_to_num(vals, nan=0.0, posinf=0.0, neginf=0.0)
+            deltas = np.diff(vals, axis=0)
+            delta_samples.append(deltas)
+            if len(delta_samples) >= 2000:  # cap for speed
+                break
+        if delta_samples:
+            all_deltas = np.concatenate(delta_samples, axis=0)
+            self.delta_mean = all_deltas.mean(axis=0).astype(np.float32)
+            self.delta_std = all_deltas.std(axis=0).astype(np.float32)
+            self.delta_std[self.delta_std < 1e-8] = 1.0
+        else:
+            n = len(self.temporal_cols)
+            self.delta_mean = np.zeros(n, dtype=np.float32)
+            self.delta_std = np.ones(n, dtype=np.float32)
+
+    def set_normalization(self, other: "CDMSequenceDataset"):
+        """Copy normalization stats from another dataset (e.g., training set)."""
+        self.temporal_mean = other.temporal_mean
+        self.temporal_std = other.temporal_std
+        self.static_mean = other.static_mean
+        self.static_std = other.static_std
+        self.tca_mean = other.tca_mean
+        self.tca_std = other.tca_std
+        self.delta_mean = other.delta_mean
+        self.delta_std = other.delta_std
+
+    def __len__(self):
+        return len(self.events)
+
+    def __getitem__(self, idx):
+        event = self.events[idx]
+        group = event["group"]
+
+        # Extract temporal features: (seq_len, n_temporal)
+        temporal = group[self.temporal_cols].values.astype(np.float32)
+        temporal = np.nan_to_num(temporal, nan=0.0, posinf=0.0, neginf=0.0)
+
+        # Compute first-order differences (deltas) for temporal features
+        # This captures trends: is miss_distance shrinking? Is covariance tightening?
+        if len(temporal) > 1:
+            deltas = np.diff(temporal, axis=0)  # (seq_len-1, n_temporal)
+            # Prepend zeros for the first timestep (no prior to diff against)
+            deltas = np.concatenate([np.zeros((1, deltas.shape[1]), dtype=np.float32), deltas], axis=0)
+        else:
+            deltas = np.zeros_like(temporal)
+
+        # Normalize raw features and deltas separately
+        temporal = (temporal - self.temporal_mean) / self.temporal_std
+        deltas = (deltas - self.delta_mean) / self.delta_std
+
+        # Concatenate: (seq_len, n_temporal * 2)
+        temporal = np.concatenate([temporal, deltas], axis=1)
+
+        # Extract static features from last row (they're constant per event)
+        static = group[self.static_cols].iloc[-1].values.astype(np.float32)
+        static = np.nan_to_num(static, nan=0.0, posinf=0.0, neginf=0.0)
+
+        # Time-to-TCA values: (seq_len, 1)
+        tca = group["time_to_tca"].values.astype(np.float32).reshape(-1, 1)
+
+        # Normalize
+        static = (static - self.static_mean) / self.static_std
+        tca = (tca - self.tca_mean) / self.tca_std
+
+        # Truncate or pad to max_seq_len
+        seq_len = len(temporal)
+        if seq_len > self.max_seq_len:
+            # Keep the most recent CDMs (closest to TCA = most informative)
+            temporal = temporal[-self.max_seq_len:]
+            tca = tca[-self.max_seq_len:]
+            seq_len = self.max_seq_len
+
+        # Pad (left-pad so the most recent CDM is always at position -1)
+        pad_len = self.max_seq_len - seq_len
+        if pad_len > 0:
+            temporal = np.pad(temporal, ((pad_len, 0), (0, 0)), constant_values=0)
+            tca = np.pad(tca, ((pad_len, 0), (0, 0)), constant_values=0)
+
+        # Attention mask: True for real positions, False for padding
+        mask = np.zeros(self.max_seq_len, dtype=bool)
+        mask[pad_len:] = True
+
+        # Target: risk label from final CDM's risk column
+        # risk > -5 means collision probability > 1e-5 (high risk)
+        final_risk = group["risk"].iloc[-1]
+        risk_label = 1.0 if final_risk > -5 else 0.0
+
+        # Target: log1p of final miss distance
+        final_miss = group["miss_distance"].iloc[-1] if "miss_distance" in group.columns else 0.0
+        miss_log = np.log1p(max(final_miss, 0.0))
+
+        # Target: log10(Pc) — the Kelvins `risk` column is already log10(Pc).
+        # Clamp to [-20, 0] (Pc ranges from ~1e-20 to ~1)
+        pc_log10 = float(max(min(final_risk, 0.0), -20.0))
+
+        # Domain weight: Kelvins events get full weight, Space-Track events
+        # get reduced weight since they have sparse features (16 vs 103 columns).
+        # This prevents the model from learning shortcuts on zero-padded features.
+        source = event.get("source", "kelvins")
+        domain_weight = 1.0 if source == "kelvins" else 0.3
+
+        return {
+            "temporal": torch.tensor(temporal, dtype=torch.float32),
+            "static": torch.tensor(static, dtype=torch.float32),
+            "time_to_tca": torch.tensor(tca, dtype=torch.float32),
+            "mask": torch.tensor(mask, dtype=torch.bool),
+            "risk_label": torch.tensor(risk_label, dtype=torch.float32),
+            "miss_log": torch.tensor(miss_log, dtype=torch.float32),
+            "pc_log10": torch.tensor(pc_log10, dtype=torch.float32),
+            "domain_weight": torch.tensor(domain_weight, dtype=torch.float32),
+        }
+
+
+class PretrainDataset(Dataset):
+    """Simplified CDM dataset for self-supervised pre-training (no labels needed).
+
+    Returns only temporal features, static features, time_to_tca, and mask.
+    Can process combined train+test data since labels aren't used.
+    """
+
+    def __init__(
+        self,
+        df: pd.DataFrame,
+        max_seq_len: int = MAX_SEQ_LEN,
+        temporal_cols: list[str] = None,
+        static_cols: list[str] = None,
+    ):
+        self.max_seq_len = max_seq_len
+
+        self.temporal_cols = temporal_cols or find_available_features(df, TEMPORAL_FEATURES)
+        self.static_cols = static_cols or find_available_features(df, STATIC_FEATURES)
+
+        print(f"  PretrainDataset — Temporal: {len(self.temporal_cols)}, Static: {len(self.static_cols)}")
+
+        # Group by event_id
+        self.events = []
+        for event_id, group in df.groupby("event_id"):
+            group = group.sort_values("time_to_tca", ascending=False)
+            self.events.append({"event_id": event_id, "group": group})
+
+        # Compute global normalization stats
+        self.temporal_mean = df[self.temporal_cols].mean().values.astype(np.float32)
+        self.temporal_std = df[self.temporal_cols].std().values.astype(np.float32)
+        self.temporal_std[self.temporal_std < 1e-8] = 1.0
+
+        self.static_mean = df[self.static_cols].mean().values.astype(np.float32)
+        self.static_std = df[self.static_cols].std().values.astype(np.float32)
+        self.static_std[self.static_std < 1e-8] = 1.0
+
+        self.tca_mean = float(df["time_to_tca"].mean())
+        self.tca_std = float(df["time_to_tca"].std())
+        if self.tca_std < 1e-8:
+            self.tca_std = 1.0
+
+        self._compute_delta_stats(df)
+
+    def _compute_delta_stats(self, df: pd.DataFrame):
+        """Estimate normalization stats for temporal first-order differences."""
+        delta_samples = []
+        for _, group in df.groupby("event_id"):
+            if len(group) < 2:
+                continue
+            vals = group[self.temporal_cols].values.astype(np.float32)
+            vals = np.nan_to_num(vals, nan=0.0, posinf=0.0, neginf=0.0)
+            deltas = np.diff(vals, axis=0)
+            delta_samples.append(deltas)
+            if len(delta_samples) >= 2000:
+                break
+        if delta_samples:
+            all_deltas = np.concatenate(delta_samples, axis=0)
+            self.delta_mean = all_deltas.mean(axis=0).astype(np.float32)
+            self.delta_std = all_deltas.std(axis=0).astype(np.float32)
+            self.delta_std[self.delta_std < 1e-8] = 1.0
+        else:
+            n = len(self.temporal_cols)
+            self.delta_mean = np.zeros(n, dtype=np.float32)
+            self.delta_std = np.ones(n, dtype=np.float32)
+
+    def set_normalization(self, other):
+        """Copy normalization stats from another dataset."""
+        self.temporal_mean = other.temporal_mean
+        self.temporal_std = other.temporal_std
+        self.static_mean = other.static_mean
+        self.static_std = other.static_std
+        self.tca_mean = other.tca_mean
+        self.tca_std = other.tca_std
+        self.delta_mean = other.delta_mean
+        self.delta_std = other.delta_std
+
+    def __len__(self):
+        return len(self.events)
+
+    def __getitem__(self, idx):
+        event = self.events[idx]
+        group = event["group"]
+
+        # Extract temporal features
+        temporal = group[self.temporal_cols].values.astype(np.float32)
+        temporal = np.nan_to_num(temporal, nan=0.0, posinf=0.0, neginf=0.0)
+
+        # Compute first-order differences
+        if len(temporal) > 1:
+            deltas = np.diff(temporal, axis=0)
+            deltas = np.concatenate([np.zeros((1, deltas.shape[1]), dtype=np.float32), deltas], axis=0)
+        else:
+            deltas = np.zeros_like(temporal)
+
+        # Normalize
+        temporal = (temporal - self.temporal_mean) / self.temporal_std
+        deltas = (deltas - self.delta_mean) / self.delta_std
+        temporal = np.concatenate([temporal, deltas], axis=1)
+
+        # Static features
+        static = group[self.static_cols].iloc[-1].values.astype(np.float32)
+        static = np.nan_to_num(static, nan=0.0, posinf=0.0, neginf=0.0)
+
+        # Time-to-TCA
+        tca = group["time_to_tca"].values.astype(np.float32).reshape(-1, 1)
+
+        static = (static - self.static_mean) / self.static_std
+        tca = (tca - self.tca_mean) / self.tca_std
+
+        # Truncate or pad
+        seq_len = len(temporal)
+        if seq_len > self.max_seq_len:
+            temporal = temporal[-self.max_seq_len:]
+            tca = tca[-self.max_seq_len:]
+            seq_len = self.max_seq_len
+
+        pad_len = self.max_seq_len - seq_len
+        if pad_len > 0:
+            temporal = np.pad(temporal, ((pad_len, 0), (0, 0)), constant_values=0)
+            tca = np.pad(tca, ((pad_len, 0), (0, 0)), constant_values=0)
+
+        mask = np.zeros(self.max_seq_len, dtype=bool)
+        mask[pad_len:] = True
+
+        return {
+            "temporal": torch.tensor(temporal, dtype=torch.float32),
+            "static": torch.tensor(static, dtype=torch.float32),
+            "time_to_tca": torch.tensor(tca, dtype=torch.float32),
+            "mask": torch.tensor(mask, dtype=torch.bool),
+        }
+
+
+def build_datasets(
+    train_df: pd.DataFrame,
+    test_df: pd.DataFrame,
+    val_fraction: float = 0.1,
+    use_density: bool = False,
+    cal_fraction: float = 0.0,
+) -> tuple:
+    """
+    Build train, validation, and test datasets with shared normalization.
+
+    Splits training data into train + val by event_id (stratified by risk).
+
+    Args:
+        train_df: Training CDM DataFrame
+        test_df: Test CDM DataFrame
+        val_fraction: Fraction of Kelvins training events for validation
+        use_density: If True, include DENSITY_FEATURES in static features
+        cal_fraction: If > 0, further split validation into val + calibration
+                      for conformal prediction. Returns 4-tuple instead of 3.
+
+    Returns:
+        If cal_fraction == 0: (train_ds, val_ds, test_ds)
+        If cal_fraction > 0:  (train_ds, val_ds, cal_ds, test_ds)
+    """
+    # Compute density features if requested
+    if use_density:
+        from src.data.density_features import OrbitalDensityComputer
+        density_computer = OrbitalDensityComputer()
+        density_computer.fit(train_df)
+        train_df = density_computer.transform(train_df)
+        test_df = density_computer.transform(test_df)
+    else:
+        density_computer = None
+
+    # Static columns: base (filtered to available) + optional density
+    static_cols = [c for c in STATIC_FEATURES if c in train_df.columns]
+    if use_density:
+        static_cols = static_cols + [
+            f for f in DENSITY_FEATURES if f in train_df.columns
+        ]
+
+    # Determine risk label per event for stratification
+    has_source = "source" in train_df.columns
+    agg_dict = {"risk": ("risk", "last")}
+    if has_source:
+        agg_dict["source"] = ("source", "first")
+    event_meta = train_df.groupby("event_id").agg(**agg_dict).reset_index()
+    event_meta["label"] = (event_meta["risk"] > -5).astype(int)
+
+    # Split validation from KELVINS-ONLY events for fair model selection.
+    # Space-Track events (sparse features, all high-risk) inflate val metrics.
+    if has_source:
+        kelvins_events = event_meta[event_meta["source"] == "kelvins"]
+        other_events = event_meta[event_meta["source"] != "kelvins"]
+
+        kelvins_ids = kelvins_events["event_id"].values
+        kelvins_labels = kelvins_events["label"].values
+
+        # Stratified split on Kelvins events only
+        k_train_ids, val_ids = train_test_split(
+            kelvins_ids, test_size=val_fraction, stratify=kelvins_labels, random_state=42
+        )
+        # Training = Kelvins train split + all Space-Track events
+        train_ids = np.concatenate([k_train_ids, other_events["event_id"].values])
+    else:
+        event_ids = event_meta["event_id"].values
+        labels = event_meta["label"].values
+        train_ids, val_ids = train_test_split(
+            event_ids, test_size=val_fraction, stratify=labels, random_state=42
+        )
+
+    # Further split validation into val + calibration for conformal prediction
+    cal_ids = np.array([])
+    if cal_fraction > 0 and len(val_ids) > 20:
+        val_labels = event_meta[event_meta["event_id"].isin(val_ids)]["label"].values
+        val_ids_arr = val_ids
+        val_ids, cal_ids = train_test_split(
+            val_ids_arr,
+            test_size=cal_fraction,
+            stratify=val_labels,
+            random_state=123,  # different seed from train/val split
+        )
+
+    train_sub = train_df[train_df["event_id"].isin(train_ids)]
+    val_sub = train_df[train_df["event_id"].isin(val_ids)]
+
+    print(f"Building datasets:")
+    print(f"  Train events: {len(train_ids)}")
+    if has_source:
+        n_k = train_sub[train_sub["source"] == "kelvins"]["event_id"].nunique()
+        n_s = train_sub[train_sub["source"] != "kelvins"]["event_id"].nunique()
+        print(f"    (Kelvins: {n_k}, Space-Track: {n_s})")
+    if use_density:
+        print(f"  Static features: {len(static_cols)} (base: {len(STATIC_FEATURES)}, "
+              f"density: {len(static_cols) - len(STATIC_FEATURES)})")
+
+    train_ds = CDMSequenceDataset(train_sub, static_cols=static_cols)
+
+    print(f"  Val events:   {len(val_ids)} (Kelvins-only)")
+    val_ds = CDMSequenceDataset(val_sub, static_cols=static_cols)
+    val_ds.set_normalization(train_ds)  # use training stats
+
+    print(f"  Test events:  {test_df['event_id'].nunique()}")
+    test_ds = CDMSequenceDataset(test_df, temporal_cols=train_ds.temporal_cols, static_cols=static_cols)
+    test_ds.set_normalization(train_ds)
+
+    # Store density computer on train_ds for checkpoint saving
+    if density_computer is not None:
+        train_ds._density_computer = density_computer
+
+    if cal_fraction > 0 and len(cal_ids) > 0:
+        cal_sub = train_df[train_df["event_id"].isin(cal_ids)]
+        print(f"  Cal events:   {len(cal_ids)} (for conformal prediction)")
+        cal_ds = CDMSequenceDataset(cal_sub, static_cols=static_cols)
+        cal_ds.set_normalization(train_ds)
+        return train_ds, val_ds, cal_ds, test_ds
+
+    return train_ds, val_ds, test_ds

src/data/spacetrack_crossref.py

@@ -0,0 +1,185 @@
+"""Cross-reference detected maneuvers with Space-Track.org CDM data.
+
+Queries the CDM_PUBLIC class for recent conjunction data messages
+involving maneuvered satellites. CDM confirmation is the strongest
+signal that a maneuver was collision-avoidance.
+
+Requires SPACETRACK_USER and SPACETRACK_PASS environment variables.
+Fails silently if credentials are not set (purely enrichment).
+"""
+
+import os
+import json
+import time
+import requests
+from pathlib import Path
+from datetime import datetime, timedelta, timezone
+
+# Rate limiting: max 30 requests/min to Space-Track
+MAX_REQUESTS_PER_MIN = 30
+BATCH_SIZE = 100  # Max NORAD IDs per query
+CACHE_EXPIRY_DAYS = 7
+
+SPACETRACK_BASE = "https://www.space-track.org"
+LOGIN_URL = f"{SPACETRACK_BASE}/ajaxauth/login"
+CDM_QUERY_URL = f"{SPACETRACK_BASE}/basicspacedata/query/class/cdm_public"
+
+
+def _get_credentials() -> tuple[str, str]:
+    """Get Space-Track credentials from environment."""
+    user = os.environ.get("SPACETRACK_USER", "")
+    passwd = os.environ.get("SPACETRACK_PASS", "")
+    return user, passwd
+
+
+def _load_cache(cache_path: Path) -> dict:
+    """Load CDM cache, filtering expired entries."""
+    if not cache_path.exists():
+        return {}
+
+    try:
+        with open(cache_path) as f:
+            cache = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+    # Filter expired entries
+    cutoff = (datetime.now(timezone.utc) - timedelta(days=CACHE_EXPIRY_DAYS)).isoformat()
+    return {
+        k: v for k, v in cache.items()
+        if v.get("cached_at", "") > cutoff
+    }
+
+
+def _save_cache(cache: dict, cache_path: Path):
+    """Save CDM cache to disk."""
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(cache_path, "w") as f:
+        json.dump(cache, f, indent=2)
+
+
+def check_cdm_for_norad_ids(
+    norad_ids: list[int],
+    lookback_days: int = 7,
+    min_pc: float = 1e-7,
+    cache_dir: Path = None,
+) -> dict[int, list[dict]]:
+    """Query Space-Track CDM_PUBLIC for recent CDMs involving given satellites.
+
+    Args:
+        norad_ids: NORAD catalog IDs to check.
+        lookback_days: How far back to search for CDMs.
+        min_pc: Minimum probability of collision to include.
+        cache_dir: Directory for CDM cache file. Defaults to data/prediction_logs/.
+
+    Returns:
+        Map of norad_id -> list of CDM records with PC, TCA, MISS_DISTANCE.
+        Empty dict if credentials not set or query fails.
+    """
+    user, passwd = _get_credentials()
+    if not user or not passwd:
+        return {}
+
+    if cache_dir is None:
+        cache_dir = Path(__file__).parent.parent.parent / "data" / "prediction_logs"
+
+    cache_path = cache_dir / "cdm_cache.json"
+    cache = _load_cache(cache_path)
+
+    # Check which IDs need fresh queries
+    results = {}
+    uncached_ids = []
+
+    for nid in norad_ids:
+        key = str(nid)
+        if key in cache:
+            results[nid] = cache[key].get("cdms", [])
+        else:
+            uncached_ids.append(nid)
+
+    if not uncached_ids:
+        return results
+
+    # Authenticate with Space-Track
+    try:
+        session = requests.Session()
+        resp = session.post(LOGIN_URL, data={
+            "identity": user,
+            "password": passwd,
+        }, timeout=30)
+        resp.raise_for_status()
+    except Exception as e:
+        print(f"  Space-Track login failed: {e}")
+        return results
+
+    # Query in batches
+    now_str = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    lookback_str = (datetime.now(timezone.utc) - timedelta(days=lookback_days)).strftime("%Y-%m-%d")
+
+    for batch_start in range(0, len(uncached_ids), BATCH_SIZE):
+        batch = uncached_ids[batch_start:batch_start + BATCH_SIZE]
+        ids_str = ",".join(str(nid) for nid in batch)
+
+        query_url = (
+            f"{CDM_QUERY_URL}"
+            f"/SAT1_NORAD_CAT_ID/{ids_str}"
+            f"/TCA/>{lookback_str}"
+            f"/orderby/TCA desc"
+            f"/format/json"
+        )
+
+        try:
+            resp = session.get(query_url, timeout=60)
+            resp.raise_for_status()
+            cdm_records = resp.json()
+        except Exception as e:
+            print(f"  Space-Track CDM query failed: {e}")
+            # Cache empty results for failed IDs to avoid re-querying
+            for nid in batch:
+                cache[str(nid)] = {
+                    "cdms": [],
+                    "cached_at": datetime.now(timezone.utc).isoformat(),
+                }
+            continue
+
+        # Process CDM records
+        batch_results: dict[int, list[dict]] = {nid: [] for nid in batch}
+
+        for cdm in cdm_records:
+            try:
+                pc = float(cdm.get("PC", 0) or 0)
+                if pc < min_pc:
+                    continue
+
+                sat1_id = int(cdm.get("SAT1_NORAD_CAT_ID", 0))
+                record = {
+                    "tca": cdm.get("TCA", ""),
+                    "pc": pc,
+                    "miss_distance_km": float(cdm.get("MISS_DISTANCE", 0) or 0) / 1000.0,
+                    "sat1_name": cdm.get("SAT1_NAME", ""),
+                    "sat2_name": cdm.get("SAT2_NAME", ""),
+                    "sat2_norad": int(cdm.get("SAT2_NORAD_CAT_ID", 0) or 0),
+                }
+
+                if sat1_id in batch_results:
+                    batch_results[sat1_id].append(record)
+            except (ValueError, TypeError):
+                continue
+
+        # Update cache and results
+        for nid in batch:
+            cdms = batch_results.get(nid, [])
+            results[nid] = cdms
+            cache[str(nid)] = {
+                "cdms": cdms,
+                "cached_at": datetime.now(timezone.utc).isoformat(),
+            }
+
+        # Rate limiting between batches
+        if batch_start + BATCH_SIZE < len(uncached_ids):
+            time.sleep(60.0 / MAX_REQUESTS_PER_MIN)
+
+    # Save updated cache
+    _save_cache(cache, cache_path)
+
+    return results

src/evaluation/conformal.py

@@ -0,0 +1,307 @@
+# Generated by Claude Code — 2026-02-13
+"""Conformal prediction for calibrated risk bounds.
+
+Provides distribution-free prediction sets with guaranteed marginal coverage:
+    P(true_label ∈ prediction_set) ≥ 1 - alpha
+
+This directly addresses NASA CARA's criticism about uncertainty quantification
+in ML-based collision risk assessment. Instead of a single probability, we
+output a prediction set (e.g., {LOW, MODERATE}) that provably covers the
+true risk tier at the specified confidence level.
+
+Method: Split conformal prediction (Vovk et al. 2005, Lei et al. 2018)
+- Calibrate on a held-out set separate from training AND model selection
+- Compute nonconformity scores
+- Use quantile of calibration scores to construct prediction sets at test time
+
+References:
+- Vovk, Gammerman, Shafer (2005) "Algorithmic Learning in a Random World"
+- Lei et al. (2018) "Distribution-Free Predictive Inference for Regression"
+- Angelopoulos & Bates (2021) "A Gentle Introduction to Conformal Prediction"
+"""
+
+import numpy as np
+from dataclasses import dataclass
+
+
+@dataclass
+class ConformalResult:
+    """Result of conformal prediction for a single example."""
+    prediction_set: list[str]      # e.g., ["LOW", "MODERATE"]
+    set_size: int                  # |prediction_set|
+    risk_prob: float               # raw model probability
+    lower_bound: float             # lower probability bound
+    upper_bound: float             # upper probability bound
+
+
+class ConformalPredictor:
+    """Split conformal prediction for binary risk classification.
+
+    Workflow:
+    1. Train model on training set
+    2. Select model (early stopping) on validation set
+    3. calibrate() on a SEPARATE calibration set (held out from validation)
+    4. predict() on test data with coverage guarantee
+
+    The calibration set must NOT be used for training or model selection,
+    otherwise the coverage guarantee is invalidated.
+    """
+
+    # Risk tiers with thresholds
+    TIERS = {
+        "LOW": (0.0, 0.10),
+        "MODERATE": (0.10, 0.40),
+        "HIGH": (0.40, 0.70),
+        "CRITICAL": (0.70, 1.0),
+    }
+
+    def __init__(self):
+        self.quantile_lower = None  # q_hat for lower bound
+        self.quantile_upper = None  # q_hat for upper bound
+        self.alpha = None
+        self.n_cal = 0
+        self.is_calibrated = False
+
+    def calibrate(
+        self,
+        cal_probs: np.ndarray,
+        cal_labels: np.ndarray,
+        alpha: float = 0.10,
+    ) -> dict:
+        """Calibrate conformal predictor on held-out calibration set.
+
+        Args:
+            cal_probs: Model predicted probabilities on calibration set, shape (n,)
+            cal_labels: True binary labels on calibration set, shape (n,)
+            alpha: Desired miscoverage rate. 1-alpha = coverage level.
+                   alpha=0.10 → 90% coverage guarantee.
+
+        Returns:
+            Calibration summary dict with quantiles and statistics
+        """
+        n = len(cal_probs)
+        if n < 10:
+            raise ValueError(f"Calibration set too small: {n} examples (need >= 10)")
+
+        self.alpha = alpha
+        self.n_cal = n
+
+        # Nonconformity score: how "wrong" is the model on each calibration example?
+        # For binary classification with probabilities:
+        #   score = 1 - P(true class)
+        # High score = model is wrong/uncertain
+        scores = np.where(
+            cal_labels == 1,
+            1.0 - cal_probs,    # positive: score = 1 - P(positive)
+            cal_probs,           # negative: score = P(positive) = 1 - P(negative)
+        )
+
+        # Conformal quantile: includes finite-sample correction
+        # q_hat = ceil((n+1)(1-alpha))/n -th quantile of scores
+        adjusted_level = np.ceil((n + 1) * (1 - alpha)) / n
+        adjusted_level = min(adjusted_level, 1.0)
+        self.q_hat = float(np.quantile(scores, adjusted_level))
+
+        # For prediction intervals on the probability itself:
+        # We also compute quantiles for constructing upper/lower prob bounds
+        # Using calibration residuals: |P(positive) - is_positive|
+        residuals = np.abs(cal_probs - cal_labels.astype(float))
+        self.q_residual = float(np.quantile(residuals, adjusted_level))
+
+        self.is_calibrated = True
+
+        # Report calibration statistics
+        empirical_coverage = np.mean(scores <= self.q_hat)
+
+        summary = {
+            "alpha": alpha,
+            "target_coverage": 1 - alpha,
+            "n_calibration": n,
+            "q_hat": self.q_hat,
+            "q_residual": self.q_residual,
+            "empirical_coverage_cal": float(empirical_coverage),
+            "mean_score": float(scores.mean()),
+            "median_score": float(np.median(scores)),
+            "cal_pos_rate": float(cal_labels.mean()),
+        }
+
+        print(f"  Conformal calibration (alpha={alpha}):")
+        print(f"    Calibration set: {n} examples ({cal_labels.sum():.0f} positive)")
+        print(f"    q_hat (nonconformity): {self.q_hat:.4f}")
+        print(f"    q_residual:         {self.q_residual:.4f}")
+        print(f"    Empirical coverage (cal): {empirical_coverage:.4f}")
+
+        return summary
+
+    def predict(self, test_probs: np.ndarray) -> list[ConformalResult]:
+        """Produce conformal prediction sets for test examples.
+
+        For each test example, returns:
+        - Prediction set: set of risk tiers that could contain the true risk
+        - Probability bounds: [lower, upper] interval on the true probability
+
+        Coverage guarantee: P(true_tier ∈ prediction_set) ≥ 1 - alpha
+        """
+        if not self.is_calibrated:
+            raise RuntimeError("Must call calibrate() before predict()")
+
+        results = []
+        for p in test_probs:
+            # Probability bounds from residual quantile
+            lower = max(0.0, p - self.q_residual)
+            upper = min(1.0, p + self.q_residual)
+
+            # Prediction set: all tiers that overlap with [lower, upper]
+            pred_set = []
+            for tier_name, (tier_lo, tier_hi) in self.TIERS.items():
+                if lower < tier_hi and upper > tier_lo:
+                    pred_set.append(tier_name)
+
+            results.append(ConformalResult(
+                prediction_set=pred_set,
+                set_size=len(pred_set),
+                risk_prob=float(p),
+                lower_bound=lower,
+                upper_bound=upper,
+            ))
+
+        return results
+
+    def evaluate(
+        self,
+        test_probs: np.ndarray,
+        test_labels: np.ndarray,
+    ) -> dict:
+        """Evaluate conformal prediction on test set.
+
+        Reports:
+        - Marginal coverage: fraction of test examples where true label
+          falls within prediction set
+        - Average set size: how informative are the predictions
+        - Coverage by tier: per-tier coverage (conditional coverage)
+        - Efficiency: 1 - (avg_set_size / n_tiers)
+        """
+        if not self.is_calibrated:
+            raise RuntimeError("Must call calibrate() before evaluate()")
+
+        results = self.predict(test_probs)
+
+        # Map labels to tiers for coverage check
+        def label_to_tier(prob: float) -> str:
+            for tier_name, (lo, hi) in self.TIERS.items():
+                if lo <= prob < hi:
+                    return tier_name
+            return "CRITICAL"  # prob == 1.0
+
+        # True "tier" based on actual probability (binary: 0 or 1)
+        true_tiers = [label_to_tier(float(l)) for l in test_labels]
+
+        # Marginal coverage: does the prediction set contain the true tier?
+        covered = [
+            true_tier in result.prediction_set
+            for true_tier, result in zip(true_tiers, results)
+        ]
+        marginal_coverage = np.mean(covered)
+
+        # Average set size
+        set_sizes = [r.set_size for r in results]
+        avg_set_size = np.mean(set_sizes)
+
+        # Coverage by true label value
+        pos_mask = test_labels == 1
+        neg_mask = test_labels == 0
+        pos_coverage = np.mean([c for c, m in zip(covered, pos_mask) if m]) if pos_mask.sum() > 0 else 0.0
+        neg_coverage = np.mean([c for c, m in zip(covered, neg_mask) if m]) if neg_mask.sum() > 0 else 0.0
+
+        # Set size distribution
+        size_counts = {}
+        for s in set_sizes:
+            size_counts[s] = size_counts.get(s, 0) + 1
+
+        # Efficiency: lower set sizes = more informative
+        efficiency = 1.0 - (avg_set_size / len(self.TIERS))
+
+        # Interval width statistics
+        widths = [r.upper_bound - r.lower_bound for r in results]
+
+        metrics = {
+            "alpha": self.alpha,
+            "target_coverage": 1 - self.alpha,
+            "marginal_coverage": float(marginal_coverage),
+            "coverage_guarantee_met": bool(marginal_coverage >= (1 - self.alpha - 0.01)),
+            "avg_set_size": float(avg_set_size),
+            "efficiency": float(efficiency),
+            "positive_coverage": float(pos_coverage),
+            "negative_coverage": float(neg_coverage),
+            "set_size_distribution": {str(k): v for k, v in sorted(size_counts.items())},
+            "n_test": len(test_labels),
+            "mean_interval_width": float(np.mean(widths)),
+            "median_interval_width": float(np.median(widths)),
+        }
+
+        print(f"\n  Conformal Prediction Evaluation (alpha={self.alpha}):")
+        print(f"    Target coverage:   {1 - self.alpha:.1%}")
+        print(f"    Marginal coverage: {marginal_coverage:.1%} "
+              f"{'OK' if metrics['coverage_guarantee_met'] else 'VIOLATION'}")
+        print(f"    Positive coverage: {pos_coverage:.1%}")
+        print(f"    Negative coverage: {neg_coverage:.1%}")
+        print(f"    Avg set size:      {avg_set_size:.2f} / {len(self.TIERS)} tiers")
+        print(f"    Efficiency:        {efficiency:.1%}")
+        print(f"    Mean interval:     [{np.mean([r.lower_bound for r in results]):.3f}, "
+              f"{np.mean([r.upper_bound for r in results]):.3f}]")
+        print(f"    Set size dist:     {size_counts}")
+
+        return metrics
+
+    def save_state(self) -> dict:
+        """Serialize calibration state for checkpoint saving."""
+        if not self.is_calibrated:
+            return {"is_calibrated": False}
+        return {
+            "is_calibrated": True,
+            "alpha": self.alpha,
+            "q_hat": self.q_hat,
+            "q_residual": self.q_residual,
+            "n_cal": self.n_cal,
+            "tiers": {k: list(v) for k, v in self.TIERS.items()},
+        }
+
+    @classmethod
+    def from_state(cls, state: dict) -> "ConformalPredictor":
+        """Restore from serialized state."""
+        obj = cls()
+        if state.get("is_calibrated", False):
+            obj.alpha = state["alpha"]
+            obj.q_hat = state["q_hat"]
+            obj.q_residual = state["q_residual"]
+            obj.n_cal = state["n_cal"]
+            obj.is_calibrated = True
+        return obj
+
+
+def run_conformal_at_multiple_levels(
+    cal_probs: np.ndarray,
+    cal_labels: np.ndarray,
+    test_probs: np.ndarray,
+    test_labels: np.ndarray,
+    alphas: list[float] = None,
+) -> dict:
+    """Run conformal prediction at multiple coverage levels.
+
+    Useful for reporting: "at 90% coverage, avg set size = X;
+    at 95%, avg set size = Y; at 99%, avg set size = Z"
+    """
+    if alphas is None:
+        alphas = [0.01, 0.05, 0.10, 0.20]
+
+    all_results = {}
+    for alpha in alphas:
+        cp = ConformalPredictor()
+        cp.calibrate(cal_probs, cal_labels, alpha=alpha)
+        eval_metrics = cp.evaluate(test_probs, test_labels)
+        all_results[f"alpha_{alpha}"] = {
+            "conformal_metrics": eval_metrics,
+            "conformal_state": cp.save_state(),
+        }
+
+    return all_results

src/evaluation/metrics.py

@@ -0,0 +1,128 @@
+# Generated by Claude Code -- 2026-02-08
+"""Evaluation metrics for conjunction prediction models."""
+
+import numpy as np
+from sklearn.metrics import (
+    average_precision_score,
+    roc_auc_score,
+    f1_score,
+    precision_recall_curve,
+    mean_absolute_error,
+    mean_squared_error,
+    classification_report,
+)
+
+
+def find_optimal_threshold(y_true: np.ndarray, y_prob: np.ndarray) -> tuple[float, float]:
+    """Find the threshold that maximizes F1 score on the precision-recall curve."""
+    precisions, recalls, thresholds = precision_recall_curve(y_true, y_prob)
+    # precision_recall_curve returns len(thresholds) = len(precisions) - 1
+    # Compute F1 for each threshold
+    f1_scores = 2 * (precisions[:-1] * recalls[:-1]) / (precisions[:-1] + recalls[:-1] + 1e-8)
+    best_idx = np.argmax(f1_scores)
+    return float(thresholds[best_idx]), float(f1_scores[best_idx])
+
+
+def evaluate_risk(y_true: np.ndarray, y_prob: np.ndarray, threshold: float = 0.5) -> dict:
+    """
+    Evaluate risk classification predictions.
+
+    Args:
+        y_true: binary ground truth labels
+        y_prob: predicted probabilities
+        threshold: classification threshold (used for f1_at_50)
+
+    Returns: dict of metrics including optimal threshold F1
+    """
+    y_pred_fixed = (y_prob >= threshold).astype(int)
+
+    results = {
+        "auc_pr": float(average_precision_score(y_true, y_prob)) if y_true.sum() > 0 else 0.0,
+        "auc_roc": float(roc_auc_score(y_true, y_prob)) if len(np.unique(y_true)) > 1 else 0.0,
+        "f1_at_50": float(f1_score(y_true, y_pred_fixed, zero_division=0)),
+        "n_positive": int(y_true.sum()),
+        "n_total": int(len(y_true)),
+        "pos_rate": float(y_true.mean()),
+    }
+
+    # Find optimal threshold that maximizes F1
+    if y_true.sum() > 0:
+        opt_threshold, opt_f1 = find_optimal_threshold(y_true, y_prob)
+        results["f1"] = opt_f1
+        results["optimal_threshold"] = opt_threshold
+        results["threshold"] = opt_threshold
+    else:
+        results["f1"] = results["f1_at_50"]
+        results["optimal_threshold"] = threshold
+        results["threshold"] = threshold
+
+    # Recall at fixed precision levels
+    if y_true.sum() > 0:
+        precisions, recalls, thresholds = precision_recall_curve(y_true, y_prob)
+        for target_precision in [0.3, 0.5, 0.7]:
+            mask = precisions >= target_precision
+            if mask.any():
+                best_recall = recalls[mask].max()
+                results[f"recall_at_prec_{int(target_precision*100)}"] = float(best_recall)
+            else:
+                results[f"recall_at_prec_{int(target_precision*100)}"] = 0.0
+
+    return results
+
+
+def evaluate_miss_distance(y_true_log: np.ndarray, y_pred_log: np.ndarray) -> dict:
+    """
+    Evaluate miss distance regression (log-scale).
+
+    Args:
+        y_true_log: log1p(miss_distance_km) ground truth
+        y_pred_log: log1p(miss_distance_km) predictions
+
+    Returns: dict of metrics
+    """
+    mae_log = float(mean_absolute_error(y_true_log, y_pred_log))
+    rmse_log = float(np.sqrt(mean_squared_error(y_true_log, y_pred_log)))
+
+    # Convert back to km for interpretable metrics
+    y_true_km = np.expm1(y_true_log)
+    y_pred_km = np.expm1(y_pred_log)
+    mae_km = float(mean_absolute_error(y_true_km, y_pred_km))
+
+    return {
+        "mae_log": mae_log,
+        "rmse_log": rmse_log,
+        "mae_km": mae_km,
+        "median_abs_error_km": float(np.median(np.abs(y_true_km - y_pred_km))),
+    }
+
+
+def full_evaluation(
+    model_name: str,
+    y_risk_true: np.ndarray,
+    y_risk_prob: np.ndarray,
+    y_miss_true_log: np.ndarray,
+    y_miss_pred_log: np.ndarray,
+) -> dict:
+    """Run full evaluation suite for a model."""
+    risk_metrics = evaluate_risk(y_risk_true, y_risk_prob)
+    miss_metrics = evaluate_miss_distance(y_miss_true_log, y_miss_pred_log)
+
+    results = {"model": model_name, **risk_metrics, **miss_metrics}
+
+    print(f"\n{'='*60}")
+    print(f"  {model_name}")
+    print(f"{'='*60}")
+    print(f"  Risk Classification:")
+    print(f"    AUC-PR:     {risk_metrics['auc_pr']:.4f}")
+    print(f"    AUC-ROC:    {risk_metrics['auc_roc']:.4f}")
+    print(f"    F1 (opt):   {risk_metrics['f1']:.4f}  (threshold={risk_metrics.get('optimal_threshold', 0.5):.3f})")
+    print(f"    F1 (0.50):  {risk_metrics['f1_at_50']:.4f}")
+    print(f"    Positives:  {risk_metrics['n_positive']}/{risk_metrics['n_total']} "
+          f"({risk_metrics['pos_rate']:.1%})")
+    print(f"  Miss Distance:")
+    print(f"    MAE (log): {miss_metrics['mae_log']:.4f}")
+    print(f"    MAE (km):  {miss_metrics['mae_km']:.2f}")
+    print(f"    Median AE: {miss_metrics['median_abs_error_km']:.2f} km")
+    print(f"{'='*60}")
+
+    return results

src/evaluation/staleness.py

@@ -0,0 +1,263 @@
+# Generated by Claude Code -- 2026-02-13
+"""TLE Staleness Sensitivity Experiment.
+
+Evaluates how model performance degrades as CDM data becomes stale.
+Simulates staleness by filtering CDM sequences to only include updates
+received at least `cutoff_days` before TCA.
+
+The Kelvins test set has time_to_tca in [2.0, 7.0] days, so meaningful
+cutoffs are in that range. A cutoff of 2.0 keeps all data (baseline),
+while a cutoff of 6.0 keeps only the earliest CDMs.
+
+Ground-truth labels always come from the ORIGINAL (untruncated) test set —
+we're measuring how well models predict with less-recent information.
+"""
+
+import numpy as np
+import pandas as pd
+import torch
+from torch.utils.data import DataLoader
+
+from src.data.cdm_loader import build_events, events_to_flat_features, get_feature_columns
+from src.data.sequence_builder import CDMSequenceDataset
+from src.evaluation.metrics import evaluate_risk
+
+# Staleness cutoffs (days before TCA)
+# 2.0 = keep all data (baseline), 6.0 = only very early CDMs
+DEFAULT_CUTOFFS = [2.0, 2.5, 3.0, 3.5, 4.0, 5.0, 6.0]
+QUICK_CUTOFFS = [2.0, 4.0, 6.0]
+
+
+def truncate_cdm_dataframe(df: pd.DataFrame, cutoff_days: float) -> pd.DataFrame:
+    """Filter CDM rows to only those with time_to_tca >= cutoff_days.
+
+    Simulates data staleness: if cutoff=4.0, the model only sees CDMs
+    that arrived 4+ days before closest approach.
+    """
+    return df[df["time_to_tca"] >= cutoff_days].copy()
+
+
+def get_ground_truth_labels(df: pd.DataFrame) -> dict:
+    """Extract per-event ground truth labels from the FULL (untruncated) dataset.
+
+    Labels come from the final CDM per event (closest to TCA).
+    Returns: {event_id: {"risk_label": int, "miss_log": float, "altitude_km": float}}
+    """
+    labels = {}
+    for event_id, group in df.groupby("event_id"):
+        group = group.sort_values("time_to_tca", ascending=True)
+        final = group.iloc[0]
+        risk_label = 1 if final["risk"] > -5 else 0
+        miss_log = float(np.log1p(max(final.get("miss_distance", 0.0), 0.0)))
+        alt = float(final.get("t_h_apo", 0.0))
+        labels[int(event_id)] = {
+            "risk_label": risk_label,
+            "miss_log": miss_log,
+            "altitude_km": alt,
+        }
+    return labels
+
+
+def evaluate_baseline_at_cutoff(baseline_model, ground_truth: dict, cutoff: float) -> dict:
+    """Evaluate baseline model. Uses altitude only, unaffected by staleness."""
+    altitudes = np.array([gt["altitude_km"] for gt in ground_truth.values()])
+    y_true = np.array([gt["risk_label"] for gt in ground_truth.values()])
+    risk_probs, _ = baseline_model.predict(altitudes)
+    metrics = evaluate_risk(y_true, risk_probs)
+    metrics["cutoff"] = cutoff
+    metrics["n_events"] = len(y_true)
+    return metrics
+
+
+def evaluate_xgboost_at_cutoff(
+    xgboost_model,
+    truncated_df: pd.DataFrame,
+    ground_truth: dict,
+    feature_cols: list[str],
+    cutoff: float,
+) -> dict:
+    """Evaluate XGBoost on truncated CDM data."""
+    events = build_events(truncated_df, feature_cols)
+    if len(events) == 0:
+        return {"auc_pr": 0.0, "f1": 0.0, "n_events": 0, "cutoff": cutoff}
+
+    X, _, _ = events_to_flat_features(events)
+
+    # Pad features if model was trained on augmented data with more columns
+    expected_features = xgboost_model.scaler.n_features_in_
+    if X.shape[1] < expected_features:
+        padding = np.zeros((X.shape[0], expected_features - X.shape[1]), dtype=X.dtype)
+        X = np.hstack([X, padding])
+
+    event_ids = [e.event_id for e in events]
+    valid_mask = np.array([eid in ground_truth for eid in event_ids])
+    X = X[valid_mask]
+    valid_ids = [eid for eid in event_ids if eid in ground_truth]
+    y_true = np.array([ground_truth[eid]["risk_label"] for eid in valid_ids])
+
+    if len(y_true) == 0 or y_true.sum() == 0:
+        return {"auc_pr": 0.0, "f1": 0.0, "n_events": len(y_true), "cutoff": cutoff}
+
+    # Pad features if model expects more (e.g., trained on augmented data)
+    expected = xgboost_model.scaler.n_features_in_
+    if X.shape[1] < expected:
+        pad_width = expected - X.shape[1]
+        X = np.pad(X, ((0, 0), (0, pad_width)), constant_values=0)
+    elif X.shape[1] > expected:
+        X = X[:, :expected]
+
+    risk_probs = xgboost_model.predict_risk(X)
+    metrics = evaluate_risk(y_true, risk_probs)
+    metrics["cutoff"] = cutoff
+    metrics["n_events"] = len(y_true)
+    return metrics
+
+
+def evaluate_pitft_at_cutoff(
+    model,
+    truncated_df: pd.DataFrame,
+    ground_truth: dict,
+    train_ds: CDMSequenceDataset,
+    device: torch.device,
+    temperature: float = 1.0,
+    cutoff: float = 0.0,
+    batch_size: int = 128,
+) -> dict:
+    """Evaluate PI-TFT on truncated CDM data with temperature scaling."""
+    # Ensure all required columns exist (pad missing with 0)
+    df = truncated_df.copy()
+    for col in train_ds.temporal_cols + train_ds.static_cols:
+        if col not in df.columns:
+            df[col] = 0.0
+
+    test_ds = CDMSequenceDataset(
+        df,
+        temporal_cols=train_ds.temporal_cols,
+        static_cols=train_ds.static_cols,
+    )
+    test_ds.set_normalization(train_ds)
+
+    if len(test_ds) == 0:
+        return {"auc_pr": 0.0, "f1": 0.0, "n_events": 0, "cutoff": cutoff}
+
+    # Get event IDs from the dataset
+    event_ids = [e["event_id"] for e in test_ds.events]
+
+    loader = DataLoader(test_ds, batch_size=batch_size, shuffle=False, num_workers=0)
+
+    model.eval()
+    all_probs = []
+
+    with torch.no_grad():
+        for batch in loader:
+            temporal = batch["temporal"].to(device)
+            static = batch["static"].to(device)
+            tca = batch["time_to_tca"].to(device)
+            mask = batch["mask"].to(device)
+
+            risk_logit, _, _, _ = model(temporal, static, tca, mask)
+            probs = torch.sigmoid(risk_logit / temperature).cpu().numpy().flatten()
+            all_probs.append(probs)
+
+    risk_probs = np.concatenate(all_probs)
+
+    # Match predictions to ground truth
+    valid_mask = np.array([eid in ground_truth for eid in event_ids])
+    risk_probs = risk_probs[valid_mask]
+    valid_ids = [eid for eid in event_ids if eid in ground_truth]
+    y_true = np.array([ground_truth[eid]["risk_label"] for eid in valid_ids])
+
+    if len(y_true) == 0 or y_true.sum() == 0:
+        return {"auc_pr": 0.0, "f1": 0.0, "n_events": len(y_true), "cutoff": cutoff}
+
+    metrics = evaluate_risk(y_true, risk_probs)
+    metrics["cutoff"] = cutoff
+    metrics["n_events"] = int(len(y_true))
+    return metrics
+
+
+def run_staleness_experiment(
+    baseline_model,
+    xgboost_model,
+    pitft_model,
+    pitft_checkpoint: dict,
+    test_df: pd.DataFrame,
+    train_ds: CDMSequenceDataset,
+    feature_cols: list[str],
+    device: torch.device,
+    cutoffs: list[float] = None,
+    quick: bool = False,
+) -> dict:
+    """Run the full staleness experiment across all cutoffs and models.
+
+    Args:
+        baseline_model: OrbitalShellBaseline instance
+        xgboost_model: XGBoostConjunctionModel instance
+        pitft_model: PhysicsInformedTFT (eval mode), or None to skip
+        pitft_checkpoint: checkpoint dict with temperature
+        test_df: ORIGINAL (untruncated) test DataFrame
+        train_ds: CDMSequenceDataset from training data (for normalization)
+        feature_cols: list of feature column names for XGBoost
+        device: torch device
+        cutoffs: list of staleness cutoffs (days before TCA)
+        quick: if True, use fewer cutoffs
+    """
+    if cutoffs is None:
+        cutoffs = QUICK_CUTOFFS if quick else DEFAULT_CUTOFFS
+
+    ground_truth = get_ground_truth_labels(test_df)
+    n_pos = sum(1 for gt in ground_truth.values() if gt["risk_label"] == 1)
+    print(f"\nGround truth: {len(ground_truth)} events, {n_pos} positive")
+
+    temperature = 1.0
+    if pitft_checkpoint:
+        temperature = pitft_checkpoint.get("temperature", 1.0)
+
+    results = {
+        "cutoffs": cutoffs,
+        "n_test_events": len(ground_truth),
+        "n_positive": n_pos,
+        "baseline": [],
+        "xgboost": [],
+        "pitft": [],
+    }
+
+    for cutoff in cutoffs:
+        print(f"\n{'='*50}")
+        print(f"Staleness cutoff: {cutoff:.1f} days")
+        print(f"{'='*50}")
+
+        truncated = truncate_cdm_dataframe(test_df, cutoff)
+        n_events = truncated["event_id"].nunique()
+        n_rows = len(truncated)
+        print(f"  Surviving: {n_events} events, {n_rows} CDMs")
+
+        # Baseline (uses altitude only — constant across cutoffs)
+        bl = evaluate_baseline_at_cutoff(baseline_model, ground_truth, cutoff)
+        results["baseline"].append(bl)
+        print(f"  Baseline  AUC-PR={bl.get('auc_pr', 0):.4f}, F1={bl.get('f1', 0):.4f}")
+
+        # XGBoost
+        if n_events > 0:
+            xgb = evaluate_xgboost_at_cutoff(
+                xgboost_model, truncated, ground_truth, feature_cols, cutoff
+            )
+        else:
+            xgb = {"auc_pr": 0.0, "f1": 0.0, "n_events": 0, "cutoff": cutoff}
+        results["xgboost"].append(xgb)
+        print(f"  XGBoost   AUC-PR={xgb.get('auc_pr', 0):.4f}, "
+              f"F1={xgb.get('f1', 0):.4f} ({xgb.get('n_events', 0)} events)")
+
+        # PI-TFT
+        if n_events > 0 and pitft_model is not None:
+            tft = evaluate_pitft_at_cutoff(
+                pitft_model, truncated, ground_truth, train_ds,
+                device, temperature=temperature, cutoff=cutoff,
+            )
+        else:
+            tft = {"auc_pr": 0.0, "f1": 0.0, "n_events": 0, "cutoff": cutoff}
+        results["pitft"].append(tft)
+        print(f"  PI-TFT    AUC-PR={tft.get('auc_pr', 0):.4f}, "
+              f"F1={tft.get('f1', 0):.4f}")
+
+    return results

src/model/baseline.py

@@ -0,0 +1,107 @@
+# Generated by Claude Code -- 2026-02-08
+"""Model 1: Naive Baseline -- Orbital Shell Density Prior.
+
+Predicts collision risk based solely on the altitude band of the conjunction,
+using historical base rates. This establishes that altitude alone is predictive
+(LEO is more crowded) but insufficient for actionable conjunction assessment.
+"""
+
+import json
+import numpy as np
+from pathlib import Path
+from collections import defaultdict
+
+
+class OrbitalShellBaseline:
+    """
+    Altitude-band collision rate baseline.
+
+    For any conjunction event, predict the average risk and miss distance
+    for that altitude regime. Bins events into 50km altitude bands.
+    """
+
+    def __init__(self, bin_width_km: float = 50.0):
+        self.bin_width = bin_width_km
+        self.bins: dict[int, dict] = {}
+        self.global_stats: dict = {}
+
+    def _altitude_to_bin(self, alt_km: float) -> int:
+        return int(round(alt_km / self.bin_width) * self.bin_width)
+
+    def fit(self, altitudes: np.ndarray, y_risk: np.ndarray, y_miss_log: np.ndarray):
+        """
+        Fit baseline from altitude array and labels.
+
+        Args:
+            altitudes: altitude in km for each event
+            y_risk: binary risk labels
+            y_miss_log: log1p(miss_distance_km) targets
+        """
+        # Global fallback stats
+        self.global_stats = {
+            "mean_risk": float(np.mean(y_risk)),
+            "mean_miss_log": float(np.mean(y_miss_log)),
+            "count": int(len(y_risk)),
+        }
+
+        # Per-bin statistics
+        bin_data = defaultdict(lambda: {"risks": [], "misses": []})
+
+        for alt, risk, miss in zip(altitudes, y_risk, y_miss_log):
+            b = self._altitude_to_bin(alt)
+            bin_data[b]["risks"].append(risk)
+            bin_data[b]["misses"].append(miss)
+
+        self.bins = {}
+        for b, data in bin_data.items():
+            self.bins[b] = {
+                "mean_risk": float(np.mean(data["risks"])),
+                "mean_miss_log": float(np.mean(data["misses"])),
+                "count": len(data["risks"]),
+                "risk_rate": float(np.sum(data["risks"]) / len(data["risks"])),
+            }
+
+        print(f"Baseline fit: {len(self.bins)} altitude bins, "
+              f"global risk rate = {self.global_stats['mean_risk']:.4f}")
+
+    def predict(self, altitudes: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Predict risk probability and log miss distance for each altitude.
+
+        Returns: (risk_probs, miss_log_preds)
+        """
+        risk_preds = []
+        miss_preds = []
+
+        for alt in altitudes:
+            b = self._altitude_to_bin(alt)
+            if b in self.bins:
+                risk_preds.append(self.bins[b]["risk_rate"])
+                miss_preds.append(self.bins[b]["mean_miss_log"])
+            else:
+                risk_preds.append(self.global_stats["mean_risk"])
+                miss_preds.append(self.global_stats["mean_miss_log"])
+
+        return np.array(risk_preds), np.array(miss_preds)
+
+    def save(self, path: Path):
+        """Save model to JSON."""
+        data = {
+            "bin_width": self.bin_width,
+            "bins": {str(k): v for k, v in self.bins.items()},
+            "global_stats": self.global_stats,
+        }
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2)
+        print(f"Baseline saved to {path}")
+
+    @classmethod
+    def load(cls, path: Path) -> "OrbitalShellBaseline":
+        """Load model from JSON."""
+        with open(path) as f:
+            data = json.load(f)
+        model = cls(bin_width_km=data["bin_width"])
+        model.bins = {int(k): v for k, v in data["bins"].items()}
+        model.global_stats = data["global_stats"]
+        return model

src/model/classical.py

@@ -0,0 +1,115 @@
+# Generated by Claude Code -- 2026-02-08
+"""Model 2: Classical ML -- XGBoost on engineered CDM features.
+
+Dual-head model:
+  - Risk classifier (binary: high-risk vs safe)
+  - Miss distance regressor (log-scale km)
+"""
+
+import pickle
+import numpy as np
+from pathlib import Path
+from xgboost import XGBClassifier, XGBRegressor
+from sklearn.preprocessing import StandardScaler
+
+
+class XGBoostConjunctionModel:
+    """XGBoost with engineered CDM features."""
+
+    def __init__(self):
+        self.scaler = StandardScaler()
+
+        self.risk_classifier = XGBClassifier(
+            n_estimators=500,
+            max_depth=8,
+            learning_rate=0.05,
+            scale_pos_weight=50,  # severe class imbalance
+            eval_metric="aucpr",
+            tree_method="hist",
+            random_state=42,
+        )
+
+        self.miss_regressor = XGBRegressor(
+            n_estimators=500,
+            max_depth=8,
+            learning_rate=0.05,
+            objective="reg:squaredlogerror",
+            tree_method="hist",
+            random_state=42,
+        )
+
+    def fit(
+        self,
+        X_train: np.ndarray,
+        y_risk: np.ndarray,
+        y_miss_log: np.ndarray,
+        X_val: np.ndarray = None,
+        y_risk_val: np.ndarray = None,
+        y_miss_val: np.ndarray = None,
+    ):
+        """Train both heads."""
+        # Scale features
+        X_scaled = self.scaler.fit_transform(X_train)
+
+        # Risk classifier
+        print(f"Training risk classifier (pos_rate={y_risk.mean():.4f}) ...")
+        eval_set = None
+        if X_val is not None:
+            eval_set = [(self.scaler.transform(X_val), y_risk_val)]
+        self.risk_classifier.fit(
+            X_scaled, y_risk,
+            eval_set=eval_set,
+            verbose=50,
+        )
+
+        # Miss distance regressor (log-scale, must be > 0 for squaredlogerror)
+        y_miss_positive = np.clip(y_miss_log, 1e-6, None)
+        print("Training miss distance regressor ...")
+        eval_set_miss = None
+        if X_val is not None:
+            y_miss_val_pos = np.clip(y_miss_val, 1e-6, None)
+            eval_set_miss = [(self.scaler.transform(X_val), y_miss_val_pos)]
+        self.miss_regressor.fit(
+            X_scaled, y_miss_positive,
+            eval_set=eval_set_miss,
+            verbose=50,
+        )
+
+    def predict(self, X: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Predict risk probability and miss distance.
+
+        Returns: (risk_probs, miss_distance_km)
+        """
+        X_scaled = self.scaler.transform(X)
+        risk_probs = self.risk_classifier.predict_proba(X_scaled)[:, 1]
+        miss_log = self.miss_regressor.predict(X_scaled)
+        miss_km = np.expm1(miss_log)
+        return risk_probs, miss_km
+
+    def predict_risk(self, X: np.ndarray) -> np.ndarray:
+        """Predict risk probability only."""
+        X_scaled = self.scaler.transform(X)
+        return self.risk_classifier.predict_proba(X_scaled)[:, 1]
+
+    def save(self, path: Path):
+        """Save all components."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "wb") as f:
+            pickle.dump({
+                "scaler": self.scaler,
+                "risk_classifier": self.risk_classifier,
+                "miss_regressor": self.miss_regressor,
+            }, f)
+        print(f"XGBoost model saved to {path}")
+
+    @classmethod
+    def load(cls, path: Path) -> "XGBoostConjunctionModel":
+        """Load all components."""
+        with open(path, "rb") as f:
+            data = pickle.load(f)
+        model = cls()
+        model.scaler = data["scaler"]
+        model.risk_classifier = data["risk_classifier"]
+        model.miss_regressor = data["miss_regressor"]
+        return model

src/model/deep.py

@@ -0,0 +1,448 @@
+# Generated by Claude Code -- 2026-02-08
+"""Model 3: Physics-Informed Temporal Fusion Transformer (PI-TFT).
+
+Architecture overview (think of it like reading serial lab values):
+
+1. VARIABLE SELECTION: Not all 22 CDM features matter equally. The model
+   learns attention weights over features -- e.g., miss_distance and
+   covariance shrinkage rate might matter more than raw orbital elements.
+   This is like a doctor learning which labs to focus on.
+
+2. STATIC CONTEXT: Object properties (altitude, size, eccentricity) don't
+   change between CDM updates. They're encoded once and injected as context
+   into the temporal processing. Like knowing the patient's age and history.
+
+3. CONTINUOUS TIME EMBEDDING: CDMs arrive at irregular intervals (not evenly
+   spaced). Instead of positional encoding (position 1, 2, 3...), we embed
+   the actual time_to_tca value. The model knows "this CDM was 3.2 days
+   before closest approach" vs "this one was 0.5 days before."
+
+4. TEMPORAL SELF-ATTENTION: The Transformer reads the full CDM sequence and
+   learns which updates were most informative. A sudden miss distance drop
+   at day -2 gets more attention than a stable reading at day -5.
+
+5. PREDICTION HEADS: The final hidden state (from the most recent CDM)
+   feeds into two prediction heads:
+   - Risk classifier: sigmoid probability of high-risk collision
+   - Miss distance regressor: predicted log(miss distance in km)
+
+6. PHYSICS LOSS: The training loss includes a penalty when the model predicts
+   a miss distance BELOW the Minimum Orbital Intersection Distance (MOID).
+   MOID is the closest the two orbits can geometrically get. Predicting
+   closer than MOID is physically impossible (without a maneuver), so we
+   penalize it. This is like penalizing a model for predicting negative
+   blood pressure -- constraining outputs to the physically possible range.
+"""
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import math
+
+
+class GatedResidualNetwork(nn.Module):
+    """
+    Gated skip connection with ELU activation and layer norm.
+
+    Think of this as a "smart residual block" -- it learns how much of the
+    transformed input to mix with the original. The gate (sigmoid) controls
+    this: gate=0 means pass through unchanged, gate=1 means fully transformed.
+    """
+
+    def __init__(self, d_model: int, d_hidden: int = None, dropout: float = 0.1):
+        super().__init__()
+        d_hidden = d_hidden or d_model
+        self.fc1 = nn.Linear(d_model, d_hidden)
+        self.fc2 = nn.Linear(d_hidden, d_model)
+        self.gate_fc = nn.Linear(d_hidden, d_model)
+        self.norm = nn.LayerNorm(d_model)
+        self.dropout = nn.Dropout(dropout)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        residual = x
+        h = F.elu(self.fc1(x))
+        h = self.dropout(h)
+        transform = self.fc2(h)
+        gate = torch.sigmoid(self.gate_fc(h))
+        return self.norm(residual + gate * transform)
+
+
+class VariableSelectionNetwork(nn.Module):
+    """
+    Learns which input features matter most via softmax attention.
+
+    For N input features, produces N attention weights that sum to 1.
+    Each feature is independently projected to d_model, then weighted
+    and summed. The weights are interpretable -- they tell you which
+    CDM columns the model found most predictive.
+    """
+
+    def __init__(self, n_features: int, d_model: int, dropout: float = 0.1):
+        super().__init__()
+        self.n_features = n_features
+        self.d_model = d_model
+
+        # Each feature gets its own linear projection: scalar -> d_model vector
+        self.feature_projections = nn.ModuleList([
+            nn.Linear(1, d_model) for _ in range(n_features)
+        ])
+
+        # Gating network: takes flattened projections -> feature weights
+        self.gate_network = nn.Sequential(
+            nn.Linear(n_features * d_model, n_features),
+            nn.Softmax(dim=-1),
+        )
+
+        self.grn = GatedResidualNetwork(d_model, dropout=dropout)
+
+    def forward(self, x: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        """
+        Args:
+            x: (..., n_features) — can be (B, F) for static or (B, S, F) for temporal
+
+        Returns:
+            output: (..., d_model) — weighted combination of projected features
+            weights: (..., n_features) — attention weights (sum to 1)
+        """
+        # Project each feature independently
+        # x[..., i:i+1] is the i-th feature, shape (..., 1)
+        projected = [proj(x[..., i:i+1]) for i, proj in enumerate(self.feature_projections)]
+        # projected[i] shape: (..., d_model)
+
+        # Stack for gating: (..., n_features, d_model)
+        stacked = torch.stack(projected, dim=-2)
+
+        # Flatten for gate computation: (..., n_features * d_model)
+        flat = stacked.reshape(*stacked.shape[:-2], -1)
+        weights = self.gate_network(flat)  # (..., n_features)
+
+        # Weighted sum: (..., d_model)
+        output = (stacked * weights.unsqueeze(-1)).sum(dim=-2)
+        output = self.grn(output)
+
+        return output, weights
+
+
+class PhysicsInformedTFT(nn.Module):
+    """
+    Physics-Informed Temporal Fusion Transformer for conjunction assessment.
+
+    Input flow:
+      temporal_features (B, S, F_t) → Variable Selection → time embedding → self-attention → attention pool → heads
+      static_features   (B, F_s)    → Variable Selection → context injection ↗
+
+    Output:
+      risk_logit: (B, 1) — raw logit for risk classification (apply sigmoid for probability)
+      miss_log:   (B, 1) — predicted log1p(miss_distance_km)
+      pc_log10:   (B, 1) — predicted log10(Pc) collision probability (when has_pc_head=True)
+      feature_weights: (B, S, F_t) — which temporal features mattered
+    """
+
+    def __init__(
+        self,
+        n_temporal_features: int,
+        n_static_features: int,
+        d_model: int = 128,
+        n_heads: int = 4,
+        n_layers: int = 2,
+        dropout: float = 0.15,
+        max_seq_len: int = 30,
+    ):
+        super().__init__()
+        self.d_model = d_model
+        self.max_seq_len = max_seq_len
+
+        # --- Variable Selection Networks ---
+        self.temporal_vsn = VariableSelectionNetwork(n_temporal_features, d_model, dropout)
+        self.static_vsn = VariableSelectionNetwork(n_static_features, d_model, dropout)
+
+        # --- Static context encoding ---
+        self.static_encoder = nn.Sequential(
+            nn.Linear(d_model, d_model),
+            nn.GELU(),
+            nn.Dropout(dropout),
+        )
+        # Static -> enrichment vector that's added to each temporal step
+        self.static_to_enrichment = nn.Linear(d_model, d_model)
+
+        # --- Continuous time embedding ---
+        # Instead of fixed positional encoding, we embed the actual time_to_tca
+        self.time_embedding = nn.Sequential(
+            nn.Linear(1, d_model // 2),
+            nn.GELU(),
+            nn.Linear(d_model // 2, d_model),
+        )
+
+        # --- Transformer encoder layers ---
+        encoder_layer = nn.TransformerEncoderLayer(
+            d_model=d_model,
+            nhead=n_heads,
+            dim_feedforward=d_model * 2,
+            dropout=dropout,
+            activation="gelu",
+            batch_first=True,
+            norm_first=True,
+        )
+        self.transformer_encoder = nn.TransformerEncoder(
+            encoder_layer, num_layers=n_layers
+        )
+
+        # --- Pre/post attention processing ---
+        self.pre_attn_grn = GatedResidualNetwork(d_model, dropout=dropout)
+        self.post_attn_grn = GatedResidualNetwork(d_model, dropout=dropout)
+
+        # --- Attention-weighted pooling ---
+        # Learns which time steps matter most instead of just taking the last one.
+        # Softmax attention over all real positions, with padding masked out.
+        self.pool_attention = nn.Sequential(
+            nn.Linear(d_model, d_model // 2),
+            nn.Tanh(),
+            nn.Linear(d_model // 2, 1),
+        )
+
+        # --- Prediction heads ---
+        self.risk_head = nn.Sequential(
+            nn.LayerNorm(d_model),
+            nn.Linear(d_model, 64),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(64, 1),
+        )
+
+        self.miss_head = nn.Sequential(
+            nn.LayerNorm(d_model),
+            nn.Linear(d_model, 64),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(64, 1),
+        )
+
+        # --- Collision probability head ---
+        # Predicts log10(Pc) directly instead of binary risk classification.
+        # Pc ranges from ~1e-20 to ~1e-1, so log10 scale maps to [-20, -1].
+        # The Kelvins `risk` column is already log10(Pc).
+        self.pc_head = nn.Sequential(
+            nn.LayerNorm(d_model),
+            nn.Linear(d_model, 64),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(64, 1),
+        )
+
+    def encode_sequence(
+        self,
+        temporal_features: torch.Tensor,  # (B, S, F_t)
+        static_features: torch.Tensor,    # (B, F_s)
+        time_to_tca: torch.Tensor,        # (B, S, 1)
+        mask: torch.Tensor,               # (B, S) — True for real, False for padding
+    ):
+        """Encode CDM sequence into per-timestep hidden states.
+
+        Returns:
+            hidden: (B, S, D) per-timestep representations after Transformer
+            temporal_weights: (B, S, F_t) variable selection attention weights
+        """
+        # 1. Variable selection -- learn which features matter
+        temporal_selected, temporal_weights = self.temporal_vsn(temporal_features)
+        # temporal_selected: (B, S, D), temporal_weights: (B, S, F_t)
+
+        static_selected, static_weights = self.static_vsn(static_features)
+        # static_selected: (B, D)
+
+        # 2. Static context -- compute enrichment vector
+        static_ctx = self.static_encoder(static_selected)  # (B, D)
+        enrichment = self.static_to_enrichment(static_ctx)  # (B, D)
+
+        # 3. Continuous time embedding
+        t_embed = self.time_embedding(time_to_tca)  # (B, S, D)
+
+        # 4. Combine: temporal + time + static context
+        x = temporal_selected + t_embed + enrichment.unsqueeze(1)
+
+        # 5. Pre-attention GRN
+        x = self.pre_attn_grn(x)
+
+        # 6. Transformer self-attention
+        # Convert mask: True=real -> need to invert for PyTorch's src_key_padding_mask
+        # PyTorch expects True=ignore, so we flip
+        padding_mask = ~mask  # (B, S), True = pad position to ignore
+        x = self.transformer_encoder(x, src_key_padding_mask=padding_mask)
+
+        # 7. Post-attention GRN
+        x = self.post_attn_grn(x)
+
+        return x, temporal_weights
+
+    def forward(
+        self,
+        temporal_features: torch.Tensor,  # (B, S, F_t)
+        static_features: torch.Tensor,    # (B, F_s)
+        time_to_tca: torch.Tensor,        # (B, S, 1)
+        mask: torch.Tensor,               # (B, S) — True for real, False for padding
+    ):
+        B, S, _ = temporal_features.shape
+
+        # Steps 1-7: encode sequence into per-timestep hidden states
+        x, temporal_weights = self.encode_sequence(
+            temporal_features, static_features, time_to_tca, mask
+        )
+
+        # 8. Attention-weighted pooling over all real positions
+        # Instead of just the last CDM, learn which time steps matter most
+        attn_scores = self.pool_attention(x).squeeze(-1)  # (B, S)
+        # Mask padding positions with -inf so they get zero attention
+        attn_scores = attn_scores.masked_fill(~mask, float("-inf"))
+        attn_weights = F.softmax(attn_scores, dim=-1)  # (B, S)
+        # Handle all-padding edge case (shouldn't happen but be safe)
+        attn_weights = attn_weights.nan_to_num(0.0)
+        x_pooled = (x * attn_weights.unsqueeze(-1)).sum(dim=1)  # (B, D)
+
+        # 9. Prediction heads
+        risk_logit = self.risk_head(x_pooled)    # (B, 1)
+        miss_log = self.miss_head(x_pooled)      # (B, 1)
+        pc_log10 = self.pc_head(x_pooled)        # (B, 1) — log10(Pc)
+
+        return risk_logit, miss_log, pc_log10, temporal_weights
+
+    def count_parameters(self) -> int:
+        return sum(p.numel() for p in self.parameters() if p.requires_grad)
+
+
+class SigmoidFocalLoss(nn.Module):
+    """
+    Focal Loss for binary classification (Lin et al., 2017).
+
+    Down-weights well-classified examples so the model focuses on hard cases.
+    FL(p_t) = -alpha_t * (1 - p_t)^gamma * log(p_t)
+
+    With gamma=0, this reduces to standard weighted BCE.
+    With gamma=2, easy examples (p_t > 0.9) get ~100x less weight.
+    """
+
+    def __init__(self, alpha: float = 0.75, gamma: float = 2.0, reduction: str = "mean"):
+        super().__init__()
+        self.alpha = alpha
+        self.gamma = gamma
+        self.reduction = reduction
+
+    def forward(self, logits: torch.Tensor, targets: torch.Tensor) -> torch.Tensor:
+        p = torch.sigmoid(logits)
+        # p_t = probability of the true class
+        p_t = targets * p + (1 - targets) * (1 - p)
+        # alpha_t = alpha for positive class, (1-alpha) for negative
+        alpha_t = targets * self.alpha + (1 - targets) * (1 - self.alpha)
+        # focal modulator: (1 - p_t)^gamma
+        focal_weight = (1 - p_t) ** self.gamma
+        # BCE per-element (numerically stable via log-sum-exp)
+        bce = F.binary_cross_entropy_with_logits(logits, targets, reduction="none")
+        loss = alpha_t * focal_weight * bce
+        if self.reduction == "none":
+            return loss
+        return loss.mean()
+
+
+class PhysicsInformedLoss(nn.Module):
+    """
+    Combined task loss + physics regularization.
+
+    Total loss = risk_weight * FocalLoss(risk) + miss_weight * MSE(miss_distance)
+                 + pc_weight * MSE(log10_Pc) + physics_weight * ReLU(MOID - predicted_miss)
+
+    The physics term: MOID (Minimum Orbital Intersection Distance) is the
+    geometric minimum distance between two orbits. The actual miss distance
+    at closest approach CANNOT be less than MOID (without a maneuver).
+    If the model predicts miss < MOID, we penalize it.
+
+    The Pc term: direct regression on log10(collision probability). The Kelvins
+    `risk` column is log10(Pc), giving us 162K labeled examples. This lets
+    the model output calibrated collision probabilities, not just binary risk.
+
+    For the Kelvins dataset, we approximate MOID from the orbital elements
+    in the CDM features. When MOID isn't available, the physics term is 0.
+    """
+
+    def __init__(
+        self,
+        risk_weight: float = 1.0,
+        miss_weight: float = 0.1,
+        pc_weight: float = 0.3,
+        physics_weight: float = 0.2,
+        pos_weight: float = 50.0,
+        use_focal: bool = False,
+        focal_alpha: float = 0.75,
+        focal_gamma: float = 2.0,
+    ):
+        super().__init__()
+        self.risk_weight = risk_weight
+        self.miss_weight = miss_weight
+        self.pc_weight = pc_weight
+        self.physics_weight = physics_weight
+        if use_focal:
+            self.risk_loss = SigmoidFocalLoss(alpha=focal_alpha, gamma=focal_gamma)
+        else:
+            self.risk_loss = nn.BCEWithLogitsLoss(
+                pos_weight=torch.tensor(pos_weight)
+            )
+        self.miss_loss = nn.MSELoss()
+
+    def forward(
+        self,
+        risk_logit: torch.Tensor,      # (B, 1)
+        miss_pred_log: torch.Tensor,    # (B, 1)
+        risk_target: torch.Tensor,      # (B,)
+        miss_target_log: torch.Tensor,  # (B,)
+        pc_pred_log10: torch.Tensor = None,  # (B, 1) predicted log10(Pc)
+        pc_target_log10: torch.Tensor = None,  # (B,) target log10(Pc)
+        moid_log: torch.Tensor = None,  # (B,) optional, log1p(MOID_km)
+        domain_weight: torch.Tensor = None,  # (B,) per-sample weight
+    ) -> tuple[torch.Tensor, dict]:
+
+        # Risk classification loss (BCE with class weighting)
+        if domain_weight is not None and not isinstance(self.risk_loss, SigmoidFocalLoss):
+            # Per-sample weighted BCE: compute element-wise then weight
+            bce_per_sample = F.binary_cross_entropy_with_logits(
+                risk_logit.squeeze(-1), risk_target,
+                pos_weight=self.risk_loss.pos_weight.to(risk_logit.device),
+                reduction="none",
+            )
+            L_risk = (bce_per_sample * domain_weight).mean()
+        else:
+            L_risk = self.risk_loss(risk_logit.squeeze(-1), risk_target)
+
+        # Miss distance regression loss — also domain-weighted
+        miss_residual = (miss_pred_log.squeeze(-1) - miss_target_log) ** 2
+        if domain_weight is not None:
+            L_miss = (miss_residual * domain_weight).mean()
+        else:
+            L_miss = miss_residual.mean()
+
+        # Collision probability regression loss
+        L_pc = torch.tensor(0.0, device=risk_logit.device)
+        if pc_pred_log10 is not None and pc_target_log10 is not None:
+            pc_residual = (pc_pred_log10.squeeze(-1) - pc_target_log10) ** 2
+            if domain_weight is not None:
+                L_pc = (pc_residual * domain_weight).mean()
+            else:
+                L_pc = pc_residual.mean()
+
+        # Physics constraint: predicted miss >= MOID
+        L_physics = torch.tensor(0.0, device=risk_logit.device)
+        if moid_log is not None:
+            # Violation = how much below MOID the prediction is
+            violation = F.relu(moid_log - miss_pred_log.squeeze(-1))
+            L_physics = violation.mean()
+
+        total = (self.risk_weight * L_risk
+                 + self.miss_weight * L_miss
+                 + self.pc_weight * L_pc
+                 + self.physics_weight * L_physics)
+
+        metrics = {
+            "loss": total.item(),
+            "risk_loss": L_risk.item(),
+            "miss_loss": L_miss.item(),
+            "pc_loss": L_pc.item(),
+            "physics_loss": L_physics.item(),
+        }
+
+        return total, metrics

src/model/pretrain.py

@@ -0,0 +1,164 @@
+# Generated by Claude Code -- 2026-02-10
+"""Self-supervised pre-training for the PI-TFT encoder.
+
+Masked Feature Reconstruction: mask 60% of CDM temporal features at random
+per timestep, train the Transformer encoder to reconstruct them. This forces
+the model to learn feature correlations, temporal dynamics, and
+static-temporal interactions from ALL CDM data (no labels needed).
+"""
+
+import torch
+import torch.nn as nn
+
+from src.model.deep import PhysicsInformedTFT
+
+
+class CDMMaskingStrategy(nn.Module):
+    """Randomly mask temporal features per timestep for reconstruction pre-training.
+
+    For each real timestep (respecting padding mask), replaces a fraction of the
+    temporal features with a learnable [MASK] token.
+    """
+
+    def __init__(self, n_temporal_features: int, mask_ratio: float = 0.6):
+        super().__init__()
+        self.n_temporal_features = n_temporal_features
+        self.mask_ratio = mask_ratio
+        # Learnable [MASK] token — one value per temporal feature
+        self.mask_token = nn.Parameter(torch.zeros(n_temporal_features))
+        nn.init.normal_(self.mask_token, std=0.02)
+
+    def forward(
+        self,
+        temporal: torch.Tensor,  # (B, S, F_t)
+        padding_mask: torch.Tensor,  # (B, S) True=real, False=padding
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        """Apply random feature masking.
+
+        Returns:
+            masked_temporal: (B, S, F_t) with masked positions replaced by mask_token
+            feature_mask: (B, S, F_t) bool — True where features were masked
+        """
+        B, S, F = temporal.shape
+
+        # Generate random mask: True = masked (to reconstruct)
+        feature_mask = torch.rand(B, S, F, device=temporal.device) < self.mask_ratio
+
+        # Only mask real timesteps (not padding)
+        feature_mask = feature_mask & padding_mask.unsqueeze(-1)
+
+        # Replace masked positions with learnable mask token
+        masked_temporal = temporal.clone()
+        masked_temporal[feature_mask] = self.mask_token.expand(B, S, -1)[feature_mask]
+
+        return masked_temporal, feature_mask
+
+
+class MaskedReconstructionHead(nn.Module):
+    """Lightweight 2-layer MLP decoder for feature reconstruction.
+
+    Intentionally small to force the encoder (not the decoder) to learn
+    rich representations.
+    """
+
+    def __init__(self, d_model: int, n_temporal_features: int, dropout: float = 0.1):
+        super().__init__()
+        self.decoder = nn.Sequential(
+            nn.LayerNorm(d_model),
+            nn.Linear(d_model, d_model),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(d_model, n_temporal_features),
+        )
+
+    def forward(self, hidden: torch.Tensor) -> torch.Tensor:
+        """Reconstruct temporal features from encoder hidden states.
+
+        Args:
+            hidden: (B, S, D) per-timestep encoder output
+
+        Returns:
+            reconstructed: (B, S, F_t) reconstructed temporal features
+        """
+        return self.decoder(hidden)
+
+
+class PretrainingWrapper(nn.Module):
+    """Wraps PI-TFT encoder with masking strategy and reconstruction head.
+
+    Forward pass: generate mask → apply mask token → encode_sequence() →
+    reconstruct → return reconstructed + masks.
+    """
+
+    def __init__(
+        self,
+        n_temporal_features: int,
+        n_static_features: int,
+        d_model: int = 128,
+        n_heads: int = 4,
+        n_layers: int = 2,
+        dropout: float = 0.15,
+        mask_ratio: float = 0.6,
+    ):
+        super().__init__()
+        self.encoder = PhysicsInformedTFT(
+            n_temporal_features=n_temporal_features,
+            n_static_features=n_static_features,
+            d_model=d_model,
+            n_heads=n_heads,
+            n_layers=n_layers,
+            dropout=dropout,
+        )
+        self.masking = CDMMaskingStrategy(n_temporal_features, mask_ratio)
+        self.reconstruction_head = MaskedReconstructionHead(
+            d_model, n_temporal_features, dropout
+        )
+
+    def forward(
+        self,
+        temporal: torch.Tensor,    # (B, S, F_t)
+        static: torch.Tensor,      # (B, F_s)
+        time_to_tca: torch.Tensor, # (B, S, 1)
+        mask: torch.Tensor,        # (B, S) True=real
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        """
+        Returns:
+            reconstructed: (B, S, F_t) reconstructed temporal features
+            feature_mask: (B, S, F_t) bool — True where features were masked
+            original: (B, S, F_t) original temporal features (for loss computation)
+        """
+        original = temporal.clone()
+
+        # Mask temporal features
+        masked_temporal, feature_mask = self.masking(temporal, mask)
+
+        # Encode masked sequence
+        hidden, _ = self.encoder.encode_sequence(
+            masked_temporal, static, time_to_tca, mask
+        )
+
+        # Reconstruct
+        reconstructed = self.reconstruction_head(hidden)
+
+        return reconstructed, feature_mask, original
+
+
+class PretrainingLoss(nn.Module):
+    """MSE loss computed only on masked positions."""
+
+    def forward(
+        self,
+        reconstructed: torch.Tensor,  # (B, S, F_t)
+        original: torch.Tensor,       # (B, S, F_t)
+        feature_mask: torch.Tensor,   # (B, S, F_t) bool
+    ) -> tuple[torch.Tensor, dict]:
+        # MSE on masked positions only
+        masked_diff = (reconstructed - original) ** 2
+        masked_diff = masked_diff[feature_mask]
+
+        if masked_diff.numel() == 0:
+            loss = torch.tensor(0.0, device=reconstructed.device, requires_grad=True)
+        else:
+            loss = masked_diff.mean()
+
+        return loss, {"reconstruction_loss": loss.item()}

src/model/triage.py

@@ -0,0 +1,50 @@
+# Generated by Claude Code -- 2026-02-13
+"""Urgency tier classifier for conjunction events."""
+
+from enum import Enum
+from dataclasses import dataclass
+
+
+class UrgencyTier(str, Enum):
+    LOW = "LOW"
+    MODERATE = "MODERATE"
+    HIGH = "HIGH"
+
+
+@dataclass
+class TriageResult:
+    tier: UrgencyTier
+    color: str
+    recommendation: str
+    risk_probability: float
+
+
+def classify_urgency(risk_prob: float) -> TriageResult:
+    """Classify conjunction urgency based on predicted risk probability.
+
+    Tiers:
+        LOW (risk <= 0.10): Monitor only
+        MODERATE (0.10 < risk <= 0.40): Assess maneuver options
+        HIGH (risk > 0.40): Immediate action required
+    """
+    if risk_prob <= 0.10:
+        return TriageResult(
+            tier=UrgencyTier.LOW,
+            color="#4fff8a",
+            recommendation="Monitor conjunction. No action required.",
+            risk_probability=risk_prob,
+        )
+    elif risk_prob <= 0.40:
+        return TriageResult(
+            tier=UrgencyTier.MODERATE,
+            color="#ffb84f",
+            recommendation="Assess maneuver options. Increased monitoring recommended.",
+            risk_probability=risk_prob,
+        )
+    else:
+        return TriageResult(
+            tier=UrgencyTier.HIGH,
+            color="#ff4f5a",
+            recommendation="Immediate action required. Initiate collision avoidance maneuver.",
+            risk_probability=risk_prob,
+        )