HyperFlow / manage.py
Gaurav711's picture
Deploy 891f179
2b86c60 verified
Raw History Blame Contribute Delete
11.5 kB
#!/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 <id>
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:])