HyperFlow / docs /flagship /operations.md
Gaurav711's picture
Deploy 891f179
2b86c60 verified
|
Raw History Blame Contribute Delete
8.69 kB

HyperFlow-owned operations

The operations service manages deliveries owned by HyperFlow. It does not grant access to Swiggy's fleet, warehouse inventory, or private operational metrics. The canonical operations workflow requires user_input or simulation provenance for each persisted job. Site, replenishment, and dispatch calculations are explicitly labelled simulations.

Delivery and courier workflow

Provision separate operator and courier accounts. A courier must explicitly enroll by submitting owner_account_id; the referenced account must be a provisioned operator or admin. Enrollment authorizes one workspace and cannot silently change to another. The operator lists enrolled couriers before assigning work.

Create a delivery with:

{
  "label": "HyperFlow-owned parcel",
  "pickup": {"latitude": 12.9, "longitude": 77.6},
  "dropoff": {"latitude": 12.91, "longitude": 77.61},
  "load_units": 1,
  "source": "user_input"
}

Assignment requires courier_account_id, declared integer capacity_units, and speed_kmh. Capacity is a workload budget; it is not inferred fleet capacity. Active job loads may not exceed that budget. Changing capacity while jobs remain active is rejected. Owner-scoped database/file locks serialize competing assignments, and optimistic record versions reject stale writes. Assigning a courier enrolled in another workspace is forbidden.

The lifecycle is:

CREATED -> ASSIGNED -> PICKED_UP -> IN_TRANSIT -> DELIVERED
CREATED or ASSIGNED -> CANCELLED

Only operators may cancel. Couriers can inspect and update only their own assigned jobs. Assignment indexes reference authoritative owner-scoped jobs and do not grant access unless the actual assignment matches. A failed write that leaves an index behind therefore fails closed. Every status change retains its actor and time.

GPS updates require location_consent: true, position, timezone-qualified captured_at, and accuracy_meters. Observations older than five minutes, more than 30 seconds into the future, or older than the stored observation are rejected. GPS is accepted only for active jobs. Completion and cancellation clear the stored location. Domain events contain record references rather than location coordinates. ETA is a straight-line estimate using declared speed; accuracy remains unknown. A UI must obtain browser location permission before submitting GPS.

Dispatch comparison

dispatch_plan(jobs, couriers, strategy) accepts nearest_first or cost. Both receive identical inputs, nonnegative workload capacity, explicit speeds, and pickup/dropoff coordinates. The nearest-first baseline assigns jobs in input order to the nearest feasible courier. The MILP first maximizes assigned job count, then minimizes total independent-trip distance with that count held fixed. It uses SciPy's MILP solver. Non-optimal solver termination raises an error rather than claiming an optimum.

The account-scoped dispatch service accepts created delivery IDs and enrolled couriers. It persists the proposal and job versions without executing assignments. Capacity is not reserved by a proposal. Assignment validates current state again.

The model assumes separate trips from each courier's stated position, then pickup, then dropoff. It does not solve multi-stop routing, model traffic, estimate actual ETA accuracy, or establish real fuel/cost savings. Comparing total distances when assignment counts differ requires explicitly reporting those counts.

Reproduce the controlled study:

python3 scripts/eval_dispatch.py --seed 42 --cases 20
python3 scripts/eval_dispatch.py --seed 42 --cases 20 --output /tmp/hyperflow-dispatch.json

The script writes files only when --output is supplied. Results include source, seed, per-case input hashes, assignment counts, distance, runtime measurements, Python/SciPy versions, and host architecture. No credentials or user locations are used. The retained historical local report with the default 20 cases recorded (current reproduction is pending):

Strategy Assigned jobs Independent-trip distance
Nearest first 146 862.395670 km
Cost MILP 150 847.215198 km

These are reproducible simulation outputs, not measured operational improvements. Timings depend on local hardware and exclude initial SciPy imports.

Operational review

The review service applies versioned, explainable rules to supplied observations: three or more refund requests within the supplied 30-day aggregate, refund amount exceeding the supplied order total, and an explicitly identified duplicate receipt. Each matched rule records its observed value and threshold. The result is a review signal, not a fraud probability. No model precision or accuracy is invented.

Operators/admins record CONFIRMED_ISSUE, CLEARED, or NEEDS_INFORMATION with a reason. Decisions append to the audit history rather than deleting previous judgments. Public reviewer accounts remain read-only in their own partition. The service does not infer verified fraud labels from rule matches.

Explicit economic scenarios

Site sensitivity requires currency, daily_orders, average_order_minor, gross_margin_fraction, competition_loss_fraction, monthly_rent_minor, monthly_other_fixed_minor, per_order_cost_minor, and setup_cost_minor. days_per_month defaults to 30. Optional sensitivity entries provide a name and nonnegative demand/rent multipliers. Default demand multipliers are 0.8, 1, and 1.2.

Monthly contribution equals monthly orders after the assumed competition loss, multiplied by unit contribution, minus rent and other fixed costs. Outputs use integer minor currency units. Setup payback is absent when contribution is not positive. Scenario ranges are deterministic sensitivity, never confidence intervals.

Replenishment requires explicit stock_units, inbound_units, committed_units, daily_demand_units, lead_time_days, review_period_days, safety_stock_units, unit_cost_minor, fixed_order_cost_minor, and currency. Target stock is demand through lead time plus the review period, with explicit safety stock. Recommended order is the positive shortfall against stock plus inbound minus commitments. Estimated cost includes a fixed order charge only for a positive order quantity.

Missing inputs, invalid units/counts, and nonfinite numbers produce validation errors. Recommendations do not imply verified provider inventory or optimize unknown holding, shortage, or shelf-life costs.

Verification

python3 -m pytest tests/flagship_ops -q

Tests cover exhaustive small-case solver comparison, infeasibility, invalid numbers, role and workspace isolation, explicit enrollment, overcapacity, failed writes, GPS consent/freshness/privacy, lifecycle validation, evidence histories, sensitivity, and replenishment inputs. Integration tests use real migrated temporary SQLite files, provisioned accounts, separate Store instances, simultaneous assignment, and restart durability. PostgreSQL deployment requires the separate database integration suite; SQLite results do not establish PostgreSQL behavior.

Retained surface adapter audit

The canonical delivery/dispatch contract above is implemented in backend/flagship/operations.py. Newer surface adapters also exist in api.py and services for routing, weather, fraud and merchant scenarios. They require separate authentication, provenance and behavior verification; canonical service tests do not certify every mounted page.

Road-network responses are provider observations only when actually returned with source/time evidence. Geometric/tortuosity distance and weather speed multipliers are assumptions. A smoothed ETA is not a measured improvement in arrival accuracy. Compare identical inputs, disclose routing failures and label every fallback as an estimate.

Refund plausibility taxonomies and merchant SLA calculations are scenario/review rules. No authority to debit real merchant payouts, hold escrow or downrank Swiggy merchants is established by consumer MCP access. Show proposed/simulated consequences explicitly; do not claim executed financial enforcement. Real fraud precision/recall requires verified outcome labels and an appropriate held-out study.

Audit empty and unavailable states for invented stores, couriers, demand curves, coupon savings and revenue. Publish an operational metric only when its event type, account/time window, amount/unit and outcome can be traced to evidence. Benchmarks stay separate from operational measurements.