#!/usr/bin/env python3 """HyperFlow 3.0 Operational & Forward Deployed Engineering (FDE) Management CLI. Provides unified on-site administration and operational diagnostics: - doctor: On-site local dependency diagnostic health check covering store schema, vault key encoding/length, reviewer workspace isolation, worker heartbeats, and provider reachability. - trace: Forensic timeline trace reconstructing the immutable causal event chain for any order, cart, or action. - metrics: Inspect dual-run counterfactual operational metrics and aggregate cost/km savings. - zone-policy: Runtime configuration and inspection of dark store zone policies (tortuosity, SLA, batching). - migrate, worker-health, generate-vault-key, provision: Core identity and schema operations. """ from __future__ import annotations import argparse import base64 import getpass import json import os import secrets import sys import time from typing import Optional, Sequence from backend.fde.doctor import run_doctor, format_doctor_report from backend.fde.trace import run_trace, format_trace_report from backend.fde.metrics import CounterfactualMetricsLogger from backend.fde.zone_policy import ZonePolicyManager, ZonePolicy try: from dotenv import load_dotenv load_dotenv() except ImportError: pass def main(argv: Optional[Sequence[str]] = None) -> None: parser = argparse.ArgumentParser( description="HyperFlow 3.0 Operational & Forward Deployed Engineering (FDE) CLI" ) sub = parser.add_subparsers(dest="command", required=True) # Core Store & Identity subcommands sub.add_parser("migrate", help="Run database schema migrations to version 1") sub.add_parser("worker-health", help="Check background worker heartbeat freshness") sub.add_parser("generate-vault-key", help="Generate 256-bit base64 AES master key") p = sub.add_parser("provision", help="Provision a local account") p.add_argument("username", help="Username for the new account") p.add_argument("--role", choices=["admin", "operator", "user", "courier", "reviewer"], default="user") p.add_argument("--password", help="Account password (12+ characters)") # FDE Tool 1: doctor doc_p = sub.add_parser("doctor", help="Forward Deployed Engineer on-site system diagnostic") doc_p.add_argument("--json", action="store_true", help="Output JSON diagnostic report") doc_p.add_argument("--providers", action="store_true", help="Opt in to public docs HTTP and Redis TCP probes") doc_p.add_argument("--no-providers", action="store_true", help="Keep network probes disabled (default)") # FDE Tool 2: trace tr_p = sub.add_parser("trace", help="Forensic causal timeline trace for a record, order, or event") tr_p.add_argument("record_id", help="Record ID, Order ID, Cart ID, or Action ID to trace") tr_p.add_argument("--json", action="store_true", help="Output JSON timeline") # FDE Tool 3: metrics met_p = sub.add_parser("metrics", help="Inspect dual-run counterfactual operational metrics") met_p.add_argument("--summary", action="store_true", help="Display aggregate savings and efficiency metrics") met_p.add_argument("--limit", type=int, default=10, help="Number of recent runs to display") met_p.add_argument("--type", choices=["basket", "routing"], default=None, help="Filter by counterfactual type") met_p.add_argument("--json", action="store_true", help="Output raw JSON metric records") # FDE Tool 4: zone-policy zp_p = sub.add_parser("zone-policy", help="Dark store zone policy runtime configuration") zp_p.add_argument("--list", action="store_true", help="List all configured zone policies") zp_p.add_argument("--get", metavar="ZONE_ID", help="Inspect a specific zone policy") zp_p.add_argument("--set", metavar="ZONE_ID", help="Target zone ID to update or create") zp_p.add_argument("--name", help="Human-readable zone name") zp_p.add_argument("--tau", type=float, help="Urban tortuosity factor in [1.2, 1.6]") zp_p.add_argument("--min-sla", type=float, help="Minimum SLA delivery window in minutes") zp_p.add_argument("--max-sla", type=float, help="Maximum SLA delivery window in minutes") zp_p.add_argument("--min-batch", type=int, help="Minimum batch size [1..5]") zp_p.add_argument("--max-batch", type=int, help="Maximum batch size [1..5]") zp_p.add_argument("--json", action="store_true", help="Output as JSON") args = parser.parse_args(argv) # 1. Key generation (no DB required) if args.command == "generate-vault-key": key = base64.b64encode(secrets.token_bytes(32)).decode() print(f"VAULT_SECRET_KEY={key}") return # Attempt to initialize Store store = None try: from backend.flagship.store import Store store = Store() except Exception as exc: if args.command == "doctor": rep = { "overall": "FAIL", "database": {"status": "FAIL", "error_type": type(exc).__name__}, "schema": {"status": "FAIL", "reason": "Database unavailable"}, "vault": {"status": "FAIL", "reason": "Database unavailable"}, "worker": {"status": "FAIL", "reason": "Database unavailable"}, "providers": {"status": "FAIL", "reason": "Database unavailable"}, } if getattr(args, "json", False): print(json.dumps(rep, indent=2)) else: print(format_doctor_report(rep)) sys.exit(1) raise SystemExit("Database initialization failed; connection details are redacted") from None # Subcommand Execution if args.command == "doctor": rep = run_doctor(store, check_providers=getattr(args, "providers", False) and not getattr(args, "no_providers", False)) if getattr(args, "json", False): print(json.dumps(rep, indent=2)) else: print(format_doctor_report(rep)) if rep.get("overall") == "FAIL": sys.exit(1) elif args.command == "trace": res = run_trace(store, args.record_id) if getattr(args, "json", False): print(json.dumps(res, indent=2)) else: print(format_trace_report(res)) elif args.command == "metrics": logger = CounterfactualMetricsLogger(store=store) if getattr(args, "summary", False) or not (getattr(args, "json", False) or getattr(args, "limit", None)): summary = logger.get_summary() if getattr(args, "json", False): print(json.dumps(summary, indent=2)) else: print("=" * 70) print("HYPERFLOW COUNTERFACTUAL OPERATIONAL METRICS SUMMARY") print("=" * 70) print(f"Total Evaluated Runs: {summary['total_runs']} (Basket: {summary['basket_runs']}, Routing: {summary['routing_runs']})") print(f"Total Cost Savings: INR {summary['total_cost_savings_inr']:,.2f} (Avg: {summary['avg_cost_savings_pct']}%)") print(f"Total Road Distance Saved: {summary['total_distance_savings_km']:.3f} km (Avg: {summary['avg_distance_savings_pct']}%)") print(f"Average ETA Improvement: {summary['avg_eta_improvement_minutes']} minutes") print(f"Overfill Mitigation Rate: {summary['avg_overfill_mitigation_rate'] * 100:.1f}%") print(f"Out-of-Stock Mitigation Rate: {summary['avg_oos_mitigation_rate'] * 100:.1f}%") print(f"Courier Batching Efficiency: {summary['avg_batch_efficiency']} orders/courier") print("=" * 70) else: recent = logger.get_recent(limit=args.limit, metric_type=args.type) if getattr(args, "json", False): print(json.dumps(recent, indent=2)) else: print("=" * 70) print(f"RECENT COUNTERFACTUAL EVENTS (Last {len(recent)})") print("=" * 70) for idx, ev in enumerate(recent, 1): if ev.get("type") == "basket": print(f"[{idx:02d}] {ev['timestamp']} | BASKET | Saved: INR {ev.get('cost_savings_inr', 0):.2f} ({ev.get('cost_savings_pct', 0):.1f}%) | OOS Mitigated: {ev.get('stockout_events_prevented', 0)}") else: print(f"[{idx:02d}] {ev['timestamp']} | ROUTING | Saved: {ev.get('distance_savings_km', 0):.2f}km ({ev.get('distance_savings_pct', 0):.1f}%) | ETA Imp: {ev.get('eta_improvement_minutes', 0):.1f}m") print("=" * 70) elif args.command == "zone-policy": manager = ZonePolicyManager(store=store) target_set = getattr(args, "set", None) target_get = getattr(args, "get", None) if target_set: updates = {} if args.name is not None: updates["name"] = args.name if args.tau is not None: updates["tortuosity_factor"] = args.tau if args.min_sla is not None: updates["min_sla_minutes"] = args.min_sla if args.max_sla is not None: updates["max_sla_minutes"] = args.max_sla if args.min_batch is not None: updates["min_batch_size"] = args.min_batch if args.max_batch is not None: updates["max_batch_size"] = args.max_batch updated = manager.update_policy(target_set, updates, persist=True) if getattr(args, "json", False): print(json.dumps(updated.to_dict(), indent=2)) else: print(f"Updated zone policy '{target_set}':") print(json.dumps(updated.to_dict(), indent=2)) elif target_get: pol = manager.get_policy(target_get) if getattr(args, "json", False): print(json.dumps(pol.to_dict(), indent=2)) else: print(f"Zone Policy '{target_get}':") print(json.dumps(pol.to_dict(), indent=2)) else: all_policies = manager.list_policies() if getattr(args, "json", False): print(json.dumps(all_policies, indent=2)) else: print("=" * 70) print("CONFIGURED DARK STORE ZONE POLICIES") print("=" * 70) for zid, p in all_policies.items(): print(f"Zone ID: {zid:<12} | Name: {p.get('name')} | tau: {p.get('tortuosity_factor')}") print(f" SLA Window: [{p.get('min_sla_minutes')} - {p.get('max_sla_minutes')}] min | Batch Limits: [{p.get('min_batch_size')} - {p.get('max_batch_size')}] orders") print("=" * 70) elif args.command == "migrate": store.migrate() print("HyperFlow schema version 1 ready") elif args.command == "worker-health": from backend.fde.doctor import check_worker_heartbeats report = check_worker_heartbeats(store) if report["status"] != "PASS": raise SystemExit(report["reason"]) print("Worker heartbeat is fresh") elif args.command == "provision": from backend.flagship.identity import Identity password = args.password or getpass.getpass("Password (12+ characters): ") print(json.dumps(Identity(store).provision(args.username, password, args.role))) if __name__ == "__main__": main(sys.argv[1:])