Upload 26 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,17 @@
+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,12 @@
+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,11 @@
+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,19 @@
+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,28 @@
+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,12 @@
+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/ingestion.py

@@ -0,0 +1,7 @@
+import requests
+from app.config import settings
+def fetch_celestrak_json():
+    r=requests.get(settings.CELESTRAK_URL, timeout=60)
+    r.raise_for_status()
+    body=r.json()
+    return body[: settings.MAX_OBJECTS_PER_RUN] if isinstance(body, list) else []

app/main.py

@@ -0,0 +1,17 @@
+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,19 @@
+import json
+from pathlib import Path
+import joblib, 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,51 @@
+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,30 @@
+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,28 @@
+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,11 @@
+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,5 @@
+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,16 @@
+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,35 @@
+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,18 @@
+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,16 @@
+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,23 @@
+import json, random
+import numpy as np, 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,43 @@
+from itertools import combinations
+from app.config import settings
+from app.feature_engineering import 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: grouped.setdefault(orbital_shell_key(obj), []).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:
+        result=score_pair(db,a,b,pair_graph_features(graph,a["object_id"],b["object_id"])); 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,9 @@
+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