Download INTEGRATION.md from Gaurav711/HyperFlow: direct link, hf CLI and curl.
- Browser
- Download file 8.19 kB
-
https://huggingface.co/spaces/Gaurav711/HyperFlow/resolve/main/INTEGRATION.md
- Command line
-
hf download hf://spaces/Gaurav711/HyperFlow/INTEGRATION.md
-
curl -L -o INTEGRATION.md https://huggingface.co/spaces/Gaurav711/HyperFlow/resolve/main/INTEGRATION.md
HyperFlow integration contract
This is the wiring and boundary map, not a live-provider certification. Actual passing evidence is in status. API schemas exposed by /docs and current source remain authoritative for field details.
Runtime and surfaces
flowchart TD
UI[React / Vite workspace] -->|Bearer session / api/v2| API[FastAPI]
API --> DB[(PostgreSQL authoritative state)]
Worker[Durable worker] --> DB
Worker -. optional notification .-> Redis[Redis]
API -->|account credential / explicit live mode| MCP[Swiggy MCP]
API -->|explicit replay mode| Sim[Isolated simulations]
API -->|authenticated SSE cursor| UI
Entrypoint: backend/api/main.py calls the flagship app factory. frontend/src/App.jsx currently maps public routes to the persisted, source-labelled FlagshipPages implementations: agent, store, BasketOps, delivery/courier, intelligence, guard, site scenarios, analytics, replay and case study. Earlier prototype page files remain in source. /dev/* aliases also exist; testing only aliases does not replace exercising user-facing routes.
The app also mounts public geo metadata with descriptive capability boundaries. Account-owned operations require authentication. Direct compatibility checkout returns 409 and directs users through reviewed proposals; compatibility weather/forecast/health endpoints return labelled UNAVAILABLE empty states. Legacy catch-all routes generally return 410, with explicitly declared exceptions such as health/retraining. Do not infer universal provider coverage from a v2 prefix.
The worker processes persisted training jobs and outbox notifications. /health checks the API; /ready checks schema/database and worker freshness. Redis loss must not erase jobs or SSE history.
Authentication and provider credentials
HyperFlow login is distinct from Swiggy authorization. Ordinary registration receives a server-assigned user role; administrator/operator/courier roles are provisioned. Public reviewer accounts are isolated simulations with no live-provider or paid-model authority.
Opaque sessions are stored server-side; the frontend retains its session token in browser storage and sends Authorization: Bearer …. Reload validation must not confuse an offline network error with proven session expiry. Clear account-scoped UI state when switching accounts.
Real credentials are encrypted with account-bound authenticated encryption and a persistent VAULT_SECRET_KEY. Store/refresh/disconnect operations never return token plaintext. Provider failures must not downgrade a live request to simulation.
Required Phase 1 contract:
| Operation | Meaning |
|---|---|
POST /api/v2/provider/credentials |
Store this account's supplied access token and optional refresh/expiry metadata; storage does not establish validity |
GET /api/v2/provider/credentials |
Return configured, verification_status, verified_at, expiry_known, and nullable expires_at; never fabricate expiry |
DELETE /api/v2/provider/credentials |
Disconnect this account; invalidate its verification evidence |
POST /api/v2/provider/verify with { "provider": "im" } |
Read-only authenticated discovery; return status without exposing addresses or tokens |
POST /api/v2/provider/refresh |
Refresh current credentials safely; rotating replacements cannot overwrite a concurrent user replacement |
| Swiggy authorize-url/callback | Registered client ID, exact configured redirect, expiring single-use state and PKCE; reject mismatch/replay |
The verification addition and revised fields are present in current source; passing verification still requires current test evidence. Verification must bind to the current credential version; an old successful response cannot verify a replacement token. Outage/rate-limit failures do not prove credential revocation.
Current Swiggy authentication documentation describes refresh support. Read actual response expiry and rotating refresh token values; unknown manual-token expiry stays unknown. Do not fabricate a refresh token from an access token. Verify provider names, schemas, error codes and limits against current official documentation before modifying integrations.
Commerce sequence and contracts
- Parse/edit intent with
/api/v2/baskets/parse; discover and plan with/api/v2/provider/read,/provider/discoverand/baskets/plan./baskets/optimizevalidates structured inputs. - Create
/api/v2/proposals, inspect the exact version and amounts, then approve at/api/v2/actions/{proposal_id}/approvewith its version. - Execute
/api/v2/actions/{action_id}/executeusingIdempotency-Key. Reusing a key with different content conflicts. Persist the attempt before external mutation. - Fetch current provider cart and compare approval binding. Changed data produces a revised proposal; no silent removal, substitution or quantity change.
- Persist validated success/receipt, failure or uncertainty. Inspect
/api/v2/actions/{action_id}and use/reconcilewhen appropriate. A lost order response is never a reason for blind placement retry. - Subscribe to
/api/v2/events, retaining event IDs; reconnect withLast-Event-IDorafter. Scope history and authorization to the account, revalidate sessions and deduplicate events in consumers.
States include PROPOSED, APPROVED, EXECUTING, SUCCEEDED, FAILED, UNKNOWN and SUPERSEDED; only validated evidence permits success. Provider payment-pending evidence must remain pending. Purchases and bookings are outside the current ₹0 verification campaign.
Jobs, models and operations
Training submission returns 202 and a durable job. The implemented lifecycle includes EVALUATED before explicit administrator promotion; queued/running/insufficient/rejected/failed states remain distinct. Worker restart resumes persisted work with bounded attempts. /api/v2/models identifies serving state; promotion and rollback require administrator authority. Candidate manifests carry immutable dataset, schema, configuration and artifact identities.
Delivery enrollment, assignment, telemetry, transitions, reviews and economic inputs use /api/v2/operations/*; read operations assumptions. Provider tracking grants no authority over provider couriers. Synthetic weather, coupon, health or demand values must never appear as live observations.
Verification matrix
| Boundary | Required evidence | Current restriction |
|---|---|---|
| API ↔ database | Isolated migration, restart, account isolation and concurrency tests | SQLite results do not establish PostgreSQL semantics |
| API ↔ provider | Schema fixtures plus separately captured live read receipts | Live discovery pending supplied token; no live transaction certification |
| Browser ↔ API | Actual mounted-route tests, reload/account switch, offline and SSE recovery | Historical browser reports need current reproduction |
| Worker ↔ model registry | Failed write/promotion, exact artifact, rollback, concurrent serving | Historical study results do not certify current serving |
| Operations ↔ user workflow | Assignment/review tests and volunteer tasks | No customer-scale fleet or merchant evidence |
Durable model turns and serving qualification
Authenticated /api/v2/agent/turns and /api/v2/agent/turns/{record_id} expose only the account's persisted turn records. A stable turn ID binds the payload: completed retries return the saved response; payload changes conflict; incomplete/failed turns require inspection and an explicit new attempt. Checkpoints do not implement automatic continuation of a partially executed model loop.
Model budgets count physical outbound requests, including failed requests. Global campaign and account limits apply. Both model-enable and free-quota-confirmation flags are required. Deadlines are cooperative; provider calls already in flight can exceed the turn deadline. ML studies do not become serving candidates without both explicit quality thresholds and exact-artifact verification.