Download manage.py from Gaurav711/HyperFlow: direct link, hf CLI and curl.
- Browser
- Download file 11.5 kB
-
https://huggingface.co/spaces/Gaurav711/HyperFlow/resolve/main/manage.py
- Command line
-
hf download hf://spaces/Gaurav711/HyperFlow/manage.py
-
curl -L -o manage.py https://huggingface.co/spaces/Gaurav711/HyperFlow/resolve/main/manage.py
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:]) | |