Enterprise architecture: deterministic risk engine, data forensics, production API, compliance ontology

[Copilot]

Adds the foundational infrastructure layers to transform Sentinel-Scope into a scalable compliance intelligence platform with deterministic scoring, forensic auditability, and a production API surface. All changes are additive — zero existing files modified, 98 existing tests unaffected.

Deterministic Risk Engine (risk_engine/)

8-factor weighted scoring (0–100) with transparent component breakdown. No black-box models.

from risk_engine import DeterministicRiskEngine

engine = DeterministicRiskEngine(model_version="1.0.0")
result = engine.score_project(
    violation_classes=["Class C", "Class B"],
    permit_age_days=400,
    inspection_failures=3, inspection_total=10,
    milestone_delay_days=45,
    complaint_count_90d=5,
    prior_stop_work_orders=1,
    building_type="residential", stories=15,
    contractor_violation_rate=0.3,
)
# result.risk_score=66, stop_work_probability_30d=0.54, fine_exposure_estimate=$35k
# result.features_snapshot contains all inputs for reproducibility
engine.explain(result)  # full component score breakdown

Data Forensics (data_forensics/)

• SHA-256 hashed ingestion archival for every external data pull
• reconstruct_state_at(project_id, datetime) — answers "what did we know at time T?"
• verify_integrity(snapshot_id) — tamper detection via hash recomputation
• replay_risk_score(snapshot_id, engine) — re-score with historical data

Production API (api/v1/)

• GET /projects/{id}/risk — deterministic risk assessment
• GET /projects/{id}/enforcement-forecast — 30/60-day stop-work probabilities, timeline, recommended actions
• GET /portfolio/{tenant_id}/risk-index — portfolio-level aggregation
• POST /webhooks/register — event subscription
• GET /health, GET /metrics (Prometheus-compatible)
• JWT auth (HMAC-SHA256), tenant isolation via X-Tenant-ID, token-bucket rate limiting
• RBAC: admin, project_manager, auditor, viewer

Compliance Ontology (ontology/)

Portable state machines and taxonomies — not hardcoded to NYC DOB:

• Violation states: 10-state FSM with validated transitions (REPORTED → ACKNOWLEDGED → CURE_PERIOD → …)
• Permit lifecycle: 8-stage lifecycle (APPLIED → APPROVED → ACTIVE → EXPIRED/REVOKED)
• Escalation graph: maps risk score ranges → enforcement categories
• Milestone taxonomy: 8 construction phases with fuzzy milestone matching

Supporting Infrastructure

• Enforcement engine (core/enforcement_engine.py): forecasts escalation level, enforcement actions, and remediation timeline from risk score
• Workers (workers/task_queue.py): in-process task queue with retry logic and dead-letter queue
• Visual pipeline (visual_pipeline/): async image job submission, SHA-256 dedup, status tracking
• Services (services/): DOB sync and generic ingestion coordinated through forensics layer
• Domain models (core/compliance_models.py): TenantContext, ProjectProfile, RiskAssessment, ComplianceSnapshot, AuditLogEntry (frozen/immutable where appropriate)
• Deployment: Dockerfile (3.12-slim, health check), K8s manifests (2 replicas, probes, resource limits), CI workflow (lint → test → build)

Tests

56 new tests across 7 files (154 total, all passing). Key coverage: risk engine determinism, forensics integrity verification, ontology state transitions, enforcement forecasting, worker retry/dead-letter, auth token lifecycle, rate limiting.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.