|
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
8.19 kB
| # HyperFlow integration contract | |
| This is the wiring and boundary map, not a live-provider certification. Actual passing evidence is in [status](docs/flagship/status.md). API schemas exposed by `/docs` and current source remain authoritative for field details. | |
| ## Runtime and surfaces | |
| ```mermaid | |
| 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](https://mcp.swiggy.com/builders/docs/start/authenticate/) 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 | |
| 1. Parse/edit intent with `/api/v2/baskets/parse`; discover and plan with `/api/v2/provider/read`, `/provider/discover` and `/baskets/plan`. `/baskets/optimize` validates structured inputs. | |
| 2. Create `/api/v2/proposals`, inspect the exact version and amounts, then approve at `/api/v2/actions/{proposal_id}/approve` with its version. | |
| 3. Execute `/api/v2/actions/{action_id}/execute` using `Idempotency-Key`. Reusing a key with different content conflicts. Persist the attempt before external mutation. | |
| 4. Fetch current provider cart and compare approval binding. Changed data produces a revised proposal; no silent removal, substitution or quantity change. | |
| 5. Persist validated success/receipt, failure or uncertainty. Inspect `/api/v2/actions/{action_id}` and use `/reconcile` when appropriate. A lost order response is never a reason for blind placement retry. | |
| 6. Subscribe to `/api/v2/events`, retaining event IDs; reconnect with `Last-Event-ID` or `after`. 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](docs/flagship/operations.md). 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. | |