Upload 25 files

Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.11-slim
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+EXPOSE 7860
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,11 @@
+---
+title: Space Risk Intelligence API
+emoji: 🚀
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Space Risk Intelligence API

app/analytics.py

@@ -0,0 +1,46 @@
+from collections import defaultdict
+from app.repository import list_high_risk_pairs, latest_runs
+
+def shell_analytics(db, limit: int = 10):
+    rows = list_high_risk_pairs(db, limit=500)
+    buckets = defaultdict(lambda: {"shell_key": "", "pair_count": 0, "avg_final_score": 0.0, "max_final_score": 0.0, "high_or_critical": 0})
+    for r in rows:
+        key = r.shell_key or "unknown"
+        b = buckets[key]
+        b["shell_key"] = key
+        b["pair_count"] += 1
+        b["avg_final_score"] += r.final_score
+        b["max_final_score"] = max(b["max_final_score"], r.final_score)
+        if r.risk_label in ("high", "critical"):
+            b["high_or_critical"] += 1
+    out = []
+    for b in buckets.values():
+        b["avg_final_score"] = b["avg_final_score"] / max(1, b["pair_count"])
+        out.append(b)
+    out.sort(key=lambda x: x["avg_final_score"], reverse=True)
+    return out[:limit]
+
+def diagnostics_summary(db):
+    rows = list_high_risk_pairs(db, limit=500)
+    runs = latest_runs(db, limit=10)
+    labels = {"low": 0, "medium": 0, "high": 0, "critical": 0}
+    if not rows:
+        return {
+            "pair_count": 0,
+            "avg_final_score": 0.0,
+            "max_final_score": 0.0,
+            "high_plus_critical": 0,
+            "label_distribution": labels,
+            "recent_runs": len(runs),
+        }
+    scores = [r.final_score for r in rows]
+    for r in rows:
+        labels[r.risk_label] = labels.get(r.risk_label, 0) + 1
+    return {
+        "pair_count": len(rows),
+        "avg_final_score": sum(scores) / len(scores),
+        "max_final_score": max(scores),
+        "high_plus_critical": labels["high"] + labels["critical"],
+        "label_distribution": labels,
+        "recent_runs": len(runs),
+    }

app/config.py

@@ -0,0 +1,14 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+    APP_NAME: str = "Space Risk Intelligence API"
+    APP_ENV: str = "dev"
+    DATABASE_URL: str = "sqlite:///./space_risk.db"
+    CELESTRAK_URL: str = "https://celestrak.org/NORAD/elements/gp.php?GROUP=active&FORMAT=json"
+    ALLOWED_ORIGINS: str = "http://localhost:5173,http://localhost:3000"
+    TOP_K_ALERTS: int = 25
+    MAX_OBJECTS_PER_RUN: int = 600
+    MAX_CANDIDATE_PAIRS: int = 2500
+
+settings = Settings()

app/database.py

@@ -0,0 +1,17 @@
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, sessionmaker
+from app.config import settings
+
+connect_args = {"check_same_thread": False} if settings.DATABASE_URL.startswith("sqlite") else {}
+engine = create_engine(settings.DATABASE_URL, connect_args=connect_args)
+SessionLocal = sessionmaker(bind=engine, autocommit=False, autoflush=False)
+
+class Base(DeclarativeBase):
+    pass
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

app/explanations.py

@@ -0,0 +1,43 @@
+def build_top_factors(features, anomaly_score, final_score):
+    factors = []
+    if features.get("close_approach_proxy", 0) > 0.5:
+        factors.append("small orbital separation proxy")
+    if features.get("same_shell", 0) >= 1:
+        factors.append("same orbital shell")
+    if features.get("graph_local_density", 0) > 0.2:
+        factors.append("dense interaction neighborhood")
+    if features.get("recurrence_count", 0) >= 3:
+        factors.append("repeated appearance across scoring windows")
+    if features.get("trend_delta_score", 0) > 0.1:
+        factors.append("risk trend increasing over time")
+    if anomaly_score > 0.6:
+        factors.append("unusual conjunction pattern")
+    if final_score > 0.9:
+        factors.append("high blended system score")
+    return factors[:5] or ["general risk elevation from orbital similarity"]
+
+def analyst_summary(features, top_factors, final_score):
+    text = "This pair is prioritized because " + ", ".join(top_factors[:3]) + "." if top_factors else "This pair is prioritized because multiple similarity signals are elevated."
+    if features.get("recurrence_count", 0) >= 3:
+        text += " The pair has appeared repeatedly in recent scoring windows."
+    if features.get("graph_local_density", 0) > 0.2:
+        text += " The surrounding interaction neighborhood is congested."
+    if final_score > 0.9:
+        text += " This pair should be reviewed first."
+    return text
+
+def structured_explanation(features, top_factors, final_score, action):
+    return {
+        "why_risky": top_factors[:3],
+        "what_changed": "Risk increased recently." if features.get("trend_delta_score", 0) > 0.1 else "No major recent change detected.",
+        "context": "Pair sits in a dense local interaction neighborhood." if features.get("graph_local_density", 0) > 0.2 else "Pair context is not highly congested.",
+        "recommended_action": action,
+        "final_score": final_score,
+    }
+
+def recommended_action(label):
+    return {
+        "critical": "immediate analyst review",
+        "high": "prioritize analyst review",
+        "medium": "monitor and rescore on next cycle",
+    }.get(label, "low priority monitoring")

app/feature_engineering.py

@@ -0,0 +1,88 @@
+from app.utils import safe_float, safe_int
+
+FEATURE_COLUMNS = [
+    "delta_mean_motion","delta_inclination","delta_eccentricity","delta_raan","delta_bstar",
+    "launch_year_gap","same_object_type","same_shell","shell_density_proxy","close_approach_proxy",
+    "persistence_proxy","recurrence_count","trend_delta_score","score_volatility_proxy",
+    "graph_degree_sum","graph_common_neighbors","graph_jaccard","graph_local_density",
+]
+
+FEATURE_LABELS = {
+    "delta_mean_motion": "Mean motion difference",
+    "delta_inclination": "Inclination difference",
+    "delta_eccentricity": "Eccentricity difference",
+    "delta_raan": "RAAN difference",
+    "delta_bstar": "BSTAR difference",
+    "launch_year_gap": "Launch year gap",
+    "same_object_type": "Same object type",
+    "same_shell": "Same orbital shell",
+    "shell_density_proxy": "Shell density proxy",
+    "close_approach_proxy": "Close approach proxy",
+    "persistence_proxy": "Persistence proxy",
+    "recurrence_count": "Recurrence count",
+    "trend_delta_score": "Trend delta",
+    "score_volatility_proxy": "Score volatility",
+    "graph_degree_sum": "Graph degree sum",
+    "graph_common_neighbors": "Common neighbors",
+    "graph_jaccard": "Graph jaccard",
+    "graph_local_density": "Graph local density",
+}
+
+def normalize_object(raw):
+    name = raw.get("OBJECT_NAME") or raw.get("object_name") or "UNKNOWN"
+    norad = raw.get("NORAD_CAT_ID") or raw.get("norad_cat_id")
+    intl = raw.get("OBJECT_ID") or raw.get("object_id") or ""
+    launch_year = int(intl[:4]) if len(intl) >= 4 and intl[:4].isdigit() else None
+    return {
+        "object_id": str(norad or name),
+        "norad_cat_id": safe_int(norad, 0) or None,
+        "object_name": name,
+        "object_type": raw.get("OBJECT_TYPE") or raw.get("object_type"),
+        "mean_motion": safe_float(raw.get("MEAN_MOTION") or raw.get("mean_motion")),
+        "inclination": safe_float(raw.get("INCLINATION") or raw.get("inclination")),
+        "eccentricity": safe_float(raw.get("ECCENTRICITY") or raw.get("eccentricity")),
+        "raan": safe_float(raw.get("RA_OF_ASC_NODE") or raw.get("raan")),
+        "bstar": safe_float(raw.get("BSTAR") or raw.get("bstar")),
+        "launch_year": launch_year,
+    }
+
+def orbital_shell_key(obj):
+    mm = safe_float(obj.get("mean_motion"))
+    inc = safe_float(obj.get("inclination"))
+    ecc = safe_float(obj.get("eccentricity"))
+    return f"mm:{int(mm)}|inc:{int(inc//5)*5}|ecc:{int(ecc*1000)//10}"
+
+def base_pair_features(a, b):
+    mm1, mm2 = safe_float(a.get("mean_motion")), safe_float(b.get("mean_motion"))
+    inc1, inc2 = safe_float(a.get("inclination")), safe_float(b.get("inclination"))
+    ecc1, ecc2 = safe_float(a.get("eccentricity")), safe_float(b.get("eccentricity"))
+    raan1, raan2 = safe_float(a.get("raan")), safe_float(b.get("raan"))
+    b1, b2 = safe_float(a.get("bstar")), safe_float(b.get("bstar"))
+    ly1, ly2 = safe_int(a.get("launch_year")), safe_int(b.get("launch_year"))
+    same_type = 1 if (a.get("object_type") or "") == (b.get("object_type") or "") else 0
+    same_shell = 1 if orbital_shell_key(a) == orbital_shell_key(b) else 0
+    delta_mm = abs(mm1 - mm2)
+    delta_inc = abs(inc1 - inc2)
+    delta_ecc = abs(ecc1 - ecc2)
+    delta_raan = abs(raan1 - raan2)
+    delta_bstar = abs(b1 - b2)
+    launch_gap = abs(ly1 - ly2) if ly1 and ly2 else 25
+    shell_density_proxy = max(0.0, 10.0 - delta_mm) + max(0.0, 8.0 - delta_inc / 2.0)
+    close_approach_proxy = 1.0 / (1.0 + delta_mm + delta_inc / 10.0 + delta_ecc * 50.0 + delta_raan / 60.0)
+    persistence_proxy = 1.0 if same_shell else 0.25
+    return {
+        "delta_mean_motion": delta_mm,
+        "delta_inclination": delta_inc,
+        "delta_eccentricity": delta_ecc,
+        "delta_raan": delta_raan,
+        "delta_bstar": delta_bstar,
+        "launch_year_gap": float(launch_gap),
+        "same_object_type": float(same_type),
+        "same_shell": float(same_shell),
+        "shell_density_proxy": float(shell_density_proxy),
+        "close_approach_proxy": float(close_approach_proxy),
+        "persistence_proxy": float(persistence_proxy),
+    }
+
+def combine_features(a, b, trend, graph):
+    return {**base_pair_features(a, b), **trend, **graph}

app/graph_features.py

@@ -0,0 +1,26 @@
+import networkx as nx
+
+def build_graph(candidate_pairs):
+    g = nx.Graph()
+    for a, b in candidate_pairs:
+        g.add_edge(a, b)
+    return g
+
+def pair_graph_features(g, a, b):
+    degree_sum = float(g.degree(a) + g.degree(b))
+    common = len(list(nx.common_neighbors(g, a, b))) if a in g and b in g else 0
+    na = set(g.neighbors(a)) if a in g else set()
+    nb = set(g.neighbors(b)) if b in g else set()
+    union = len(na | nb)
+    inter = len(na & nb)
+    jaccard = float(inter / union) if union else 0.0
+    nodes = set([a, b]) | na | nb
+    sub = g.subgraph(nodes)
+    possible = max(1, len(nodes) * (len(nodes) - 1) / 2)
+    density = float(sub.number_of_edges() / possible)
+    return {
+        "graph_degree_sum": degree_sum,
+        "graph_common_neighbors": float(common),
+        "graph_jaccard": jaccard,
+        "graph_local_density": density,
+    }

app/main.py

@@ -0,0 +1,27 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from app.config import settings
+from app.database import Base, engine
+from app.routers.health import router as health_router
+from app.routers.objects import router as objects_router
+from app.routers.pairs import router as pairs_router
+from app.routers.admin import router as admin_router
+from app.routers.analytics import router as analytics_router
+from app.scripts.bootstrap_demo import bootstrap_if_needed
+
+Base.metadata.create_all(bind=engine)
+bootstrap_if_needed()
+
+app = FastAPI(title=settings.APP_NAME, docs_url="/docs", redoc_url="/redoc", openapi_url="/openapi.json")
+origins = [x.strip() for x in settings.ALLOWED_ORIGINS.split(",") if x.strip()]
+app.add_middleware(CORSMiddleware, allow_origins=origins, allow_credentials=True, allow_methods=["*"], allow_headers=["*"])
+
+@app.get("/")
+def root():
+    return {"status": "ok", "message": "Space Risk Intelligence API is running", "docs": "/docs", "health": "/health"}
+
+app.include_router(health_router)
+app.include_router(objects_router)
+app.include_router(pairs_router)
+app.include_router(admin_router)
+app.include_router(analytics_router)

app/ml.py

@@ -0,0 +1,46 @@
+import json
+from pathlib import Path
+import joblib
+import numpy as np
+from sklearn.ensemble import IsolationForest
+from xgboost import XGBClassifier
+from app.feature_engineering import FEATURE_COLUMNS, FEATURE_LABELS
+
+BASE_DIR = Path(__file__).resolve().parents[1]
+MODEL_DIR = BASE_DIR / "models"
+MODEL_DIR.mkdir(exist_ok=True)
+BASELINE_PATH = MODEL_DIR / "baseline_model.joblib"
+ANOMALY_PATH = MODEL_DIR / "anomaly_model.joblib"
+FEATURE_COLUMNS_PATH = MODEL_DIR / "feature_columns.json"
+
+def train_models(X, y):
+    clf = XGBClassifier(
+        n_estimators=140, max_depth=5, learning_rate=0.06,
+        subsample=0.9, colsample_bytree=0.9, eval_metric="logloss",
+        random_state=42
+    )
+    clf.fit(X, y)
+    anomaly = IsolationForest(n_estimators=180, contamination=0.08, random_state=42)
+    anomaly.fit(X)
+    joblib.dump(clf, BASELINE_PATH)
+    joblib.dump(anomaly, ANOMALY_PATH)
+    FEATURE_COLUMNS_PATH.write_text(json.dumps(FEATURE_COLUMNS), encoding="utf-8")
+    return str(BASELINE_PATH)
+
+def predict_local(feature_vector):
+    clf = joblib.load(BASELINE_PATH)
+    anomaly = joblib.load(ANOMALY_PATH)
+    x = np.array([feature_vector])
+    risk = float(clf.predict_proba(x)[0][1])
+    raw = float(anomaly.decision_function(x)[0])
+    anomaly_score = float(max(0.0, min(1.0, 1.0 - ((raw + 0.5) / 1.0))))
+    final = 0.72 * risk + 0.18 * anomaly_score + 0.10 * min(1.0, feature_vector[10] if len(feature_vector) > 10 else 0.0)
+    return risk, anomaly_score, float(max(0.0, min(1.0, final)))
+
+def feature_importance():
+    clf = joblib.load(BASELINE_PATH)
+    vals = clf.feature_importances_.tolist()
+    out = []
+    for name, value in sorted(zip(FEATURE_COLUMNS, vals), key=lambda x: x[1], reverse=True):
+        out.append({"feature": name, "label": FEATURE_LABELS.get(name, name), "importance": float(value)})
+    return out

app/models.py

@@ -0,0 +1,55 @@
+from datetime import datetime
+from sqlalchemy import String, Float, Integer, DateTime, Text, Boolean
+from sqlalchemy.orm import Mapped, mapped_column
+from app.database import Base
+
+class SpaceObject(Base):
+    __tablename__ = "space_objects"
+    object_id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    norad_cat_id: Mapped[int | None] = mapped_column(Integer, index=True, nullable=True)
+    object_name: Mapped[str] = mapped_column(String(255), index=True)
+    object_type: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    mean_motion: Mapped[float | None] = mapped_column(Float, nullable=True)
+    inclination: Mapped[float | None] = mapped_column(Float, nullable=True)
+    eccentricity: Mapped[float | None] = mapped_column(Float, nullable=True)
+    raan: Mapped[float | None] = mapped_column(Float, nullable=True)
+    bstar: Mapped[float | None] = mapped_column(Float, nullable=True)
+    launch_year: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    inserted_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+class PairScore(Base):
+    __tablename__ = "pair_scores"
+    pair_id: Mapped[str] = mapped_column(String(128), primary_key=True)
+    primary_object_id: Mapped[str] = mapped_column(String(64), index=True)
+    secondary_object_id: Mapped[str] = mapped_column(String(64), index=True)
+    latest_run_id: Mapped[str] = mapped_column(String(64), index=True)
+    risk_score: Mapped[float] = mapped_column(Float, index=True)
+    anomaly_score: Mapped[float] = mapped_column(Float, index=True)
+    final_score: Mapped[float] = mapped_column(Float, index=True)
+    risk_label: Mapped[str] = mapped_column(String(32), index=True)
+    recurrence_count: Mapped[int] = mapped_column(Integer, default=1)
+    trend_delta_24h: Mapped[float | None] = mapped_column(Float, nullable=True)
+    shell_key: Mapped[str | None] = mapped_column(String(128), index=True, nullable=True)
+    top_factors_json: Mapped[str] = mapped_column(Text)
+    feature_payload_json: Mapped[str] = mapped_column(Text)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+class PairScoreHistory(Base):
+    __tablename__ = "pair_score_history"
+    history_id: Mapped[str] = mapped_column(String(128), primary_key=True)
+    pair_id: Mapped[str] = mapped_column(String(128), index=True)
+    run_id: Mapped[str] = mapped_column(String(64), index=True)
+    risk_score: Mapped[float] = mapped_column(Float)
+    anomaly_score: Mapped[float] = mapped_column(Float)
+    final_score: Mapped[float] = mapped_column(Float)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+class ScoringRun(Base):
+    __tablename__ = "scoring_runs"
+    run_id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    source: Mapped[str] = mapped_column(String(64))
+    object_count: Mapped[int] = mapped_column(Integer, default=0)
+    candidate_pair_count: Mapped[int] = mapped_column(Integer, default=0)
+    scored_pair_count: Mapped[int] = mapped_column(Integer, default=0)
+    completed: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)

app/repository.py

@@ -0,0 +1,56 @@
+from sqlalchemy.orm import Session
+from sqlalchemy import select, desc, or_
+from app.models import SpaceObject, PairScore, PairScoreHistory, ScoringRun
+
+def upsert_space_object(db: Session, payload):
+    obj = db.get(SpaceObject, payload["object_id"])
+    if obj:
+        for k, v in payload.items():
+            setattr(obj, k, v)
+        db.add(obj)
+    else:
+        db.add(SpaceObject(**payload))
+
+def list_objects(db: Session, limit=100):
+    return db.scalars(select(SpaceObject).limit(limit)).all()
+
+def get_object(db: Session, object_id):
+    return db.get(SpaceObject, object_id)
+
+def save_pair_score(db: Session, payload):
+    row = db.get(PairScore, payload["pair_id"])
+    if row:
+        for k, v in payload.items():
+            setattr(row, k, v)
+        db.add(row)
+    else:
+        db.add(PairScore(**payload))
+
+def insert_pair_history(db: Session, payload):
+    db.add(PairScoreHistory(**payload))
+
+def list_high_risk_pairs(db: Session, limit=50):
+    return db.scalars(select(PairScore).order_by(desc(PairScore.final_score)).limit(limit)).all()
+
+def get_pair(db: Session, pair_id):
+    return db.get(PairScore, pair_id)
+
+def get_pair_history(db: Session, pair_id, limit=20):
+    return db.scalars(select(PairScoreHistory).where(PairScoreHistory.pair_id == pair_id).order_by(desc(PairScoreHistory.created_at)).limit(limit)).all()
+
+def create_run(db: Session, payload):
+    db.add(ScoringRun(**payload))
+
+def latest_runs(db: Session, limit=10):
+    return db.scalars(select(ScoringRun).order_by(desc(ScoringRun.created_at)).limit(limit)).all()
+
+def get_run(db: Session, run_id):
+    return db.get(ScoringRun, run_id)
+
+def object_pairs(db: Session, object_id: str, limit=25):
+    stmt = select(PairScore).where(or_(PairScore.primary_object_id == object_id, PairScore.secondary_object_id == object_id)).order_by(desc(PairScore.final_score)).limit(limit)
+    return db.scalars(stmt).all()
+
+def pairs_in_same_shell(db: Session, shell_key: str, exclude_pair_id: str, limit=20):
+    stmt = select(PairScore).where(PairScore.shell_key == shell_key, PairScore.pair_id != exclude_pair_id).order_by(desc(PairScore.final_score)).limit(limit)
+    return db.scalars(stmt).all()

app/routers/admin.py

@@ -0,0 +1,53 @@
+import json
+from fastapi import APIRouter, Depends
+from app.database import get_db
+from app.feature_engineering import normalize_object
+from app.ingestion import fetch_celestrak_json
+from app.repository import list_high_risk_pairs, latest_runs, get_run
+from app.services import scoring_cycle, demo_objects
+from app.scripts.train_baseline import run_training
+
+router = APIRouter(prefix="/api/v1", tags=["admin"])
+
+@router.post("/ingest/celestrak")
+def ingest_celestrak(db=Depends(get_db)):
+    return {"status": "ok", **scoring_cycle(db, [normalize_object(x) for x in fetch_celestrak_json()], source="celestrak")}
+
+@router.post("/score/demo-cycle")
+def score_demo_cycle(db=Depends(get_db)):
+    return {"status": "ok", **scoring_cycle(db, demo_objects(db), source="demo")}
+
+@router.post("/train/baseline")
+def train_baseline():
+    model_path, rows, metrics = run_training()
+    return {"status": "ok", "model_path": model_path, "rows_used": rows, "metrics": metrics}
+
+@router.get("/alerts/live")
+def alerts_live(limit: int = 25, db=Depends(get_db)):
+    rows = list_high_risk_pairs(db, limit)
+    return [{"pair_id": r.pair_id, "final_score": r.final_score, "risk_label": r.risk_label, "top_factors": json.loads(r.top_factors_json)} for r in rows]
+
+@router.get("/runs")
+def runs(db=Depends(get_db)):
+    return [{"run_id": r.run_id, "source": r.source, "object_count": r.object_count, "candidate_pair_count": r.candidate_pair_count, "scored_pair_count": r.scored_pair_count, "completed": r.completed, "created_at": r.created_at} for r in latest_runs(db, 10)]
+
+@router.get("/runs/{run_id}")
+def run_detail(run_id: str, db=Depends(get_db)):
+    r = get_run(db, run_id)
+    if not r:
+        return {"detail": "Run not found"}
+    rows = [x for x in list_high_risk_pairs(db, 200) if x.latest_run_id == run_id]
+    labels = {"low": 0, "medium": 0, "high": 0, "critical": 0}
+    for x in rows:
+        labels[x.risk_label] = labels.get(x.risk_label, 0) + 1
+    return {
+        "run_id": r.run_id,
+        "source": r.source,
+        "object_count": r.object_count,
+        "candidate_pair_count": r.candidate_pair_count,
+        "scored_pair_count": r.scored_pair_count,
+        "completed": r.completed,
+        "created_at": r.created_at,
+        "label_distribution": labels,
+        "top_pairs": [{"pair_id": x.pair_id, "final_score": x.final_score, "risk_label": x.risk_label} for x in sorted(rows, key=lambda z: z.final_score, reverse=True)[:20]],
+    }

app/routers/analytics.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter, Depends
+from app.database import get_db
+from app.analytics import shell_analytics, diagnostics_summary
+from app.ml import feature_importance
+
+router = APIRouter(prefix="/api/v1", tags=["analytics"])
+
+@router.get("/analytics/shells")
+def get_shell_analytics(limit: int = 10, db=Depends(get_db)):
+    return shell_analytics(db, limit)
+
+@router.get("/diagnostics/summary")
+def get_diagnostics_summary(db=Depends(get_db)):
+    return diagnostics_summary(db)
+
+@router.get("/model/feature-importance")
+def get_feature_importance():
+    return feature_importance()

app/routers/health.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+from app.config import settings
+
+router = APIRouter()
+
+@router.get("/health")
+def health():
+    return {"status": "ok", "app": settings.APP_NAME}

app/routers/objects.py

@@ -0,0 +1,22 @@
+import json
+from fastapi import APIRouter, Depends, HTTPException
+from app.database import get_db
+from app.repository import list_objects, get_object, object_pairs
+
+router = APIRouter(prefix="/api/v1/objects", tags=["objects"])
+
+@router.get("")
+def get_objects(limit: int = 100, db=Depends(get_db)):
+    return list_objects(db, limit)
+
+@router.get("/{object_id}")
+def get_object_detail(object_id: str, db=Depends(get_db)):
+    obj = get_object(db, object_id)
+    if not obj:
+        raise HTTPException(status_code=404, detail="Object not found")
+    return obj
+
+@router.get("/{object_id}/pairs")
+def get_object_related_pairs(object_id: str, limit: int = 25, db=Depends(get_db)):
+    rows = object_pairs(db, object_id, limit)
+    return [{"pair_id": r.pair_id, "final_score": r.final_score, "risk_label": r.risk_label, "top_factors": json.loads(r.top_factors_json)} for r in rows]

app/routers/pairs.py

@@ -0,0 +1,63 @@
+import json
+from fastapi import APIRouter, Depends, HTTPException
+from app.database import get_db
+from app.feature_engineering import normalize_object
+from app.services import score_pair
+from app.repository import list_high_risk_pairs, get_pair, get_pair_history, pairs_in_same_shell, object_pairs
+
+router = APIRouter(prefix="/api/v1", tags=["pairs"])
+
+@router.post("/score/pair")
+def score_pair_route(payload: dict, db=Depends(get_db)):
+    return score_pair(db, normalize_object(payload["primary"]), normalize_object(payload["secondary"]))
+
+@router.get("/pairs/high-risk")
+def high_risk(limit: int = 50, db=Depends(get_db)):
+    rows = list_high_risk_pairs(db, limit)
+    return [{"pair_id": r.pair_id, "risk_score": r.risk_score, "anomaly_score": r.anomaly_score, "final_score": r.final_score, "risk_label": r.risk_label, "recurrence_count": r.recurrence_count, "trend_delta_24h": r.trend_delta_24h, "shell_key": r.shell_key, "top_factors": json.loads(r.top_factors_json)} for r in rows]
+
+@router.get("/pairs/{pair_id}")
+def pair_detail(pair_id: str, db=Depends(get_db)):
+    row = get_pair(db, pair_id)
+    if not row:
+        raise HTTPException(status_code=404, detail="Pair not found")
+    payload = json.loads(row.feature_payload_json)
+    return {
+        "pair_id": row.pair_id,
+        "primary_object_id": row.primary_object_id,
+        "secondary_object_id": row.secondary_object_id,
+        "risk_score": row.risk_score,
+        "anomaly_score": row.anomaly_score,
+        "final_score": row.final_score,
+        "risk_label": row.risk_label,
+        "recurrence_count": row.recurrence_count,
+        "trend_delta_24h": row.trend_delta_24h,
+        "shell_key": row.shell_key,
+        "top_factors": json.loads(row.top_factors_json),
+        "features": payload,
+        "analyst_summary": payload.get("analyst_summary", ""),
+        "structured_explanation": payload.get("structured_explanation", {}),
+    }
+
+@router.get("/pairs/{pair_id}/history")
+def pair_history(pair_id: str, limit: int = 20, db=Depends(get_db)):
+    rows = get_pair_history(db, pair_id, limit)
+    return [{"history_id": r.history_id, "run_id": r.run_id, "risk_score": r.risk_score, "anomaly_score": r.anomaly_score, "final_score": r.final_score, "created_at": r.created_at} for r in rows]
+
+@router.get("/pairs/{pair_id}/neighbors")
+def pair_neighbors(pair_id: str, limit: int = 20, db=Depends(get_db)):
+    row = get_pair(db, pair_id)
+    if not row:
+        raise HTTPException(status_code=404, detail="Pair not found")
+    shell_rows = pairs_in_same_shell(db, row.shell_key or "unknown", row.pair_id, limit)
+    object_related = object_pairs(db, row.primary_object_id, limit) + object_pairs(db, row.secondary_object_id, limit)
+    seen = {pair_id}
+    related = []
+    for r in shell_rows + object_related:
+        if r.pair_id in seen:
+            continue
+        seen.add(r.pair_id)
+        related.append({"pair_id": r.pair_id, "final_score": r.final_score, "risk_label": r.risk_label, "top_factors": json.loads(r.top_factors_json)})
+        if len(related) >= limit:
+            break
+    return related

app/scripts/bootstrap_demo.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+from app.database import Base, engine, SessionLocal
+from app.repository import list_objects, latest_runs
+from app.scripts.seed_synthetic import main as seed_main
+from app.scripts.train_baseline import run_training
+from app.services import scoring_cycle, demo_objects
+
+def bootstrap_if_needed():
+    Base.metadata.create_all(bind=engine)
+    model_path = Path(__file__).resolve().parents[2] / "models" / "baseline_model.joblib"
+    db = SessionLocal()
+    try:
+        has_objects = bool(list_objects(db, 5))
+    finally:
+        db.close()
+    if not has_objects:
+        seed_main()
+    if not model_path.exists():
+        run_training()
+    db = SessionLocal()
+    try:
+        if not latest_runs(db, 1):
+            scoring_cycle(db, demo_objects(db), source="bootstrap-demo")
+    finally:
+        db.close()
+
+if __name__ == "__main__":
+    bootstrap_if_needed()

app/scripts/seed_synthetic.py

@@ -0,0 +1,36 @@
+import random
+from app.database import Base, engine, SessionLocal
+from app.repository import upsert_space_object
+
+def synthetic_objects(n=300):
+    items = []
+    for i in range(n):
+        shell = random.choice([(15.2, 53), (14.9, 98), (13.8, 74), (2.0, 0), (12.5, 55)])
+        mm, inc = shell
+        items.append({
+            "object_id": f"OBJ-{i+1}",
+            "norad_cat_id": 10000 + i,
+            "object_name": f"SIM_OBJECT_{i+1}",
+            "object_type": random.choice(["PAYLOAD", "DEBRIS", "ROCKET BODY"]),
+            "mean_motion": round(random.gauss(mm, 0.12), 5),
+            "inclination": round(random.gauss(inc, 1.4), 5),
+            "eccentricity": round(abs(random.gauss(0.001, 0.002)), 6),
+            "raan": round(random.uniform(0, 360), 4),
+            "bstar": round(random.uniform(0.00001, 0.005), 8),
+            "launch_year": random.randint(1998, 2025),
+        })
+    return items
+
+def main():
+    Base.metadata.create_all(bind=engine)
+    db = SessionLocal()
+    try:
+        for item in synthetic_objects():
+            upsert_space_object(db, item)
+        db.commit()
+        print("Synthetic objects loaded.")
+    finally:
+        db.close()
+
+if __name__ == "__main__":
+    main()

app/scripts/train_baseline.py

@@ -0,0 +1,35 @@
+import json, random
+import numpy as np
+import pandas as pd
+from sklearn.metrics import roc_auc_score
+from app.database import SessionLocal
+from app.repository import list_objects
+from app.feature_engineering import FEATURE_COLUMNS, combine_features
+from app.graph_features import build_graph, pair_graph_features
+from app.ml import train_models
+
+def run_training():
+    db = SessionLocal()
+    try:
+        objs = list_objects(db, 5000)
+        objects = [{"object_id": o.object_id, "object_type": o.object_type, "mean_motion": o.mean_motion, "inclination": o.inclination, "eccentricity": o.eccentricity, "raan": o.raan, "bstar": o.bstar, "launch_year": o.launch_year} for o in objs]
+    finally:
+        db.close()
+    pairs = [tuple(random.sample(objects, 2)) for _ in range(4000)]
+    g = build_graph([(a["object_id"], b["object_id"]) for a, b in pairs[:1000]])
+    rows, raw_scores = [], []
+    for a, b in pairs:
+        trend = {"recurrence_count": float(random.choice([0,1,2,3,4])), "trend_delta_score": float(random.uniform(-0.1, 0.3)), "score_volatility_proxy": float(random.uniform(0, 0.2))}
+        f = combine_features(a, b, trend, pair_graph_features(g, a["object_id"], b["object_id"]))
+        score = 0.30*f["close_approach_proxy"] + 0.16*f["same_shell"] + 0.10*min(1.0,f["shell_density_proxy"]/12.0) + 0.10*min(1.0,f["graph_local_density"]*2.0) + 0.09*min(1.0,f["graph_jaccard"]) + 0.10*min(1.0,f["recurrence_count"]/5.0) + 0.08*max(0.0,f["trend_delta_score"]) + np.random.normal(0,0.05)
+        y = 1 if score > 0.48 else 0
+        rows.append({**f, "label": y})
+        raw_scores.append(score)
+    df = pd.DataFrame(rows)
+    path = train_models(df[FEATURE_COLUMNS].values, df["label"].values)
+    auc = float(roc_auc_score(df["label"].values, np.array(raw_scores)))
+    return path, len(df), {"pseudo_auc": round(auc, 4), "rows": int(len(df))}
+
+if __name__ == "__main__":
+    p, r, m = run_training()
+    print(json.dumps({"model_path": p, "rows": r, "metrics": m}, indent=2))

app/services.py

@@ -0,0 +1,109 @@
+from itertools import combinations
+from app.config import settings
+from app.feature_engineering import normalize_object, combine_features, orbital_shell_key, FEATURE_COLUMNS
+from app.graph_features import build_graph, pair_graph_features
+from app.repository import upsert_space_object, save_pair_score, insert_pair_history, create_run, get_pair_history, list_objects
+from app.ml import predict_local
+from app.utils import new_id, dumps
+from app.explanations import build_top_factors, analyst_summary, structured_explanation, recommended_action
+
+def demo_objects(db, limit=200):
+    rows = list_objects(db, limit=limit)
+    return [{"object_id": r.object_id, "object_name": r.object_name, "object_type": r.object_type, "mean_motion": r.mean_motion, "inclination": r.inclination, "eccentricity": r.eccentricity, "raan": r.raan, "bstar": r.bstar, "launch_year": r.launch_year} for r in rows]
+
+def generate_candidate_pairs(objects):
+    grouped = {}
+    for obj in objects:
+        key = orbital_shell_key(obj)
+        grouped.setdefault(key, []).append(obj)
+    candidates = []
+    for group in grouped.values():
+        if len(group) < 2:
+            continue
+        for a, b in combinations(group[:120], 2):
+            candidates.append((a, b))
+            if len(candidates) >= settings.MAX_CANDIDATE_PAIRS:
+                return candidates
+    return candidates
+
+def _trend_features(db, pair_id):
+    hist = get_pair_history(db, pair_id, limit=10)
+    if len(hist) < 2:
+        return {"recurrence_count": float(len(hist)), "trend_delta_score": 0.0, "score_volatility_proxy": 0.0}
+    scores = [h.final_score for h in hist]
+    avg = sum(scores) / len(scores)
+    vol = sum(abs(x - avg) for x in scores) / len(scores)
+    return {"recurrence_count": float(len(hist)), "trend_delta_score": float(scores[0] - scores[-1]), "score_volatility_proxy": float(vol)}
+
+def score_pair(db, a, b, graph_feats=None):
+    pair_id = f"{a['object_id']}__{b['object_id']}"
+    trend = _trend_features(db, pair_id)
+    graph = graph_feats or {"graph_degree_sum": 0.0, "graph_common_neighbors": 0.0, "graph_jaccard": 0.0, "graph_local_density": 0.0}
+    features = combine_features(a, b, trend, graph)
+    vector = [float(features.get(c, 0.0)) for c in FEATURE_COLUMNS]
+    risk, anomaly, final = predict_local(vector)
+    label = "critical" if final >= 0.9 else "high" if final >= 0.75 else "medium" if final >= 0.45 else "low"
+    top = build_top_factors(features, anomaly, final)
+    action = recommended_action(label)
+    summary = analyst_summary(features, top, final)
+    structured = structured_explanation(features, top, final, action)
+    return {
+        "pair_id": pair_id,
+        "risk_score": risk,
+        "anomaly_score": anomaly,
+        "final_score": final,
+        "risk_label": label,
+        "top_factors": top,
+        "analyst_summary": summary,
+        "structured_explanation": structured,
+        "recommended_action": action,
+        "features": features,
+    }
+
+def scoring_cycle(db, objects, source="demo"):
+    run_id = new_id("run")
+    create_run(db, {"run_id": run_id, "source": source, "object_count": len(objects), "candidate_pair_count": 0, "scored_pair_count": 0, "completed": False})
+    for obj in objects:
+        upsert_space_object(db, obj)
+    db.commit()
+    candidates = generate_candidate_pairs(objects)
+    graph = build_graph([(a["object_id"], b["object_id"]) for a, b in candidates])
+    count = 0
+    for a, b in candidates:
+        graph_feats = pair_graph_features(graph, a["object_id"], b["object_id"])
+        result = score_pair(db, a, b, graph_feats)
+        hist = get_pair_history(db, result["pair_id"], limit=20)
+        recurrence = len(hist) + 1
+        trend_delta = result["final_score"] - hist[-1].final_score if hist else 0.0
+        save_pair_score(db, {
+            "pair_id": result["pair_id"],
+            "primary_object_id": a["object_id"],
+            "secondary_object_id": b["object_id"],
+            "latest_run_id": run_id,
+            "risk_score": result["risk_score"],
+            "anomaly_score": result["anomaly_score"],
+            "final_score": result["final_score"],
+            "risk_label": result["risk_label"],
+            "recurrence_count": recurrence,
+            "trend_delta_24h": trend_delta,
+            "shell_key": orbital_shell_key(a),
+            "top_factors_json": dumps(result["top_factors"]),
+            "feature_payload_json": dumps(result["features"] | {"analyst_summary": result["analyst_summary"], "structured_explanation": result["structured_explanation"]}),
+        })
+        insert_pair_history(db, {
+            "history_id": new_id("hist"),
+            "pair_id": result["pair_id"],
+            "run_id": run_id,
+            "risk_score": result["risk_score"],
+            "anomaly_score": result["anomaly_score"],
+            "final_score": result["final_score"],
+        })
+        count += 1
+    from app.models import ScoringRun
+    run = db.get(ScoringRun, run_id)
+    run.candidate_pair_count = len(candidates)
+    run.scored_pair_count = count
+    run.completed = True
+    db.add(run)
+    db.commit()
+    return {"run_id": run_id, "object_count": len(objects), "candidate_pair_count": len(candidates), "scored_pair_count": count}

app/utils.py

@@ -0,0 +1,19 @@
+import json, uuid
+
+def safe_float(v, d=0.0):
+    try:
+        return d if v in (None, "") else float(v)
+    except Exception:
+        return d
+
+def safe_int(v, d=0):
+    try:
+        return d if v in (None, "") else int(v)
+    except Exception:
+        return d
+
+def dumps(x):
+    return json.dumps(x, default=str)
+
+def new_id(prefix):
+    return f"{prefix}_{uuid.uuid4().hex[:16]}"

requirements.txt

@@ -0,0 +1,12 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+pydantic-settings==2.5.2
+sqlalchemy==2.0.35
+requests==2.32.3
+numpy==2.1.2
+pandas==2.2.3
+scikit-learn==1.5.2
+xgboost==2.1.1
+joblib==1.4.2
+networkx==3.3
+python-multipart==0.0.9