Spaces:
Configuration error
Configuration error
Niranjan-Murugarasu024
feat: TradeSense AI Chairman Edition production release ready for Hugging Face Spaces
0125724 | # TradeSense AI — Frontend API Contract Specification (M19.1 Frozen) | |
| **Version**: `1.9.0-ENTERPRISE` | |
| **Backend Status**: `FROZEN & AUTHORITATIVE` | |
| **OpenAPI Snapshot**: [`openapi/tradesense-openapi.json`](file:///d:/Stock_project/v7.5.1US%20us%20stocks%20only%20%28them%20switch,graph%20coming%20with%20homepage%29/openapi/tradesense-openapi.json) | |
| --- | |
| ## 1. Authentication & Session Management | |
| ### `POST /api/v1/auth/login` | |
| - **Purpose**: Authenticate user with PBKDF2 verification & account lockout guard. | |
| - **Parameters**: `username` (string), `password` (string), `tenant_id` (string, default: `default_tenant`). | |
| - **Response (200)**: | |
| ```json | |
| { | |
| "access_token": "eyJhbGciOi...", | |
| "token_type": "bearer", | |
| "tenant_id": "default_tenant", | |
| "username": "lead_quant", | |
| "expires_in_minutes": 60 | |
| } | |
| ``` | |
| - **Error Codes**: `401 Unauthorized` (bad password), `423 Locked` (5 consecutive failures). | |
| ### `POST /api/v1/auth/logout` | |
| - **Headers**: `Authorization: Bearer <token>` | |
| - **Response (200)**: `{"message": "Successfully logged out and revoked access token."}` | |
| --- | |
| ## 2. Research Plane Endpoints | |
| ### `POST /api/v1/research/runs` | |
| - **Headers**: `Authorization: Bearer <token>`, `Idempotency-Key: <uuid>` | |
| - **Query**: `experiment_id` (string), `strategy_id` (string) | |
| - **Body**: `ConfigurationSnapshot` | |
| - **Response (202)**: `{"run_id": "run_...", "status": "QUEUED", "workflow_state": "PRE_REGISTERED", "enqueued": true}` | |
| ### `GET /api/v1/research/runs` | |
| - **Query**: `experiment_id` (optional), `limit` (int, default 50), `offset` (int, default 0) | |
| - **Response (200)**: `{"total": 12, "tenant_id": "...", "runs": [...]}` | |
| ### `GET /api/v1/research/runs/{run_id}` | |
| - **Response (200)**: `ResearchRun` domain object with `configuration`, `provenance`, `status`, `workflow_state`, `metrics_summary`. | |
| ### `GET /api/v1/research/runs/{run_id}/evidence_package` | |
| - **Purpose**: Sealed Institutional Evidence Package export with SHA-256 root digest. | |
| - **Response (200)**: | |
| ```json | |
| { | |
| "evidence_package": { | |
| "package_schema_version": "1.9.0-INSTITUTIONAL-EVIDENCE", | |
| "metadata": { ... }, | |
| "specification": { ... }, | |
| "governance": { ... }, | |
| "audit_subchain": [ ... ], | |
| "family_1_control_reference": { ... } | |
| }, | |
| "cryptographic_verification": { | |
| "root_digest_sha256": "3a8f...", | |
| "algorithm": "SHA-256", | |
| "verified": true | |
| } | |
| } | |
| ``` | |
| --- | |
| ## 3. Control Plane & Governance Endpoints | |
| ### `GET /api/v1/governance/decisions` | |
| - **Response (200)**: `{"total": 5, "decisions": [...]}` (Includes Family 1 permanent benchmark). | |
| ### `POST /api/v1/governance/decisions/{decision_id}/reviews` | |
| - **Query**: `verdict` (`APPROVE` | `REJECT` | `REQUEST_CHANGES`), `comments` (string) | |
| - **Response (201)**: `ResearchDecision` with updated `peer_reviews` list. | |
| ### `GET /api/v1/governance/family_1_archive` | |
| - **Purpose**: Permanent Immutable Control Benchmark record. | |
| - **Response (200)**: | |
| ```json | |
| { | |
| "family_id": "family_1_5d_reversal", | |
| "classification": "EXPLAINED_FACTOR_PREMIUM", | |
| "operational_status": "NO_GENERALIZABLE_ALPHA", | |
| "workflow_state": "ARCHIVED", | |
| "evidence_summary": { | |
| "net_annualized_alpha_pct": -0.45, | |
| "newey_west_hac_t_stat": -0.04, | |
| "p_value": 0.9703 | |
| } | |
| } | |
| ``` | |
| ### `GET /api/v1/audit/events` | |
| - **Query**: `limit`, `offset`, `actor_id` | |
| - **Response (200)**: `{"total": 45, "events": [...]}` | |
| ### `GET /api/v1/audit/verify` | |
| - **Response (200)**: `{"ledger_cryptographically_verified": true, "tampering_detected": false}` | |
| --- | |
| ## 4. Multi-Tenant Organizations & Usage | |
| ### `GET /api/v1/organizations` / `POST /api/v1/organizations` | |
| ### `GET /api/v1/tenants/usage` | |
| - **Response (200)**: `{"period_date": "2026-09", "research_runs_count": 12, "total_cpu_seconds": 45.2, "storage_bytes": 2048576, "api_requests_count": 142}` | |
| --- | |
| ## 5. Health, Probes & Version | |
| - `GET /startup` -> `{"status": "READY", "initialized": true}` | |
| - `GET /health` -> `{"status": "UP"}` | |
| - `GET /ready` -> `{"status": "READY"}` | |
| - `GET /api/v1/version` -> `{"version": "1.9.0-ENTERPRISE", "family_1_status": "EXPLAINED_FACTOR_PREMIUM (CLOSED & IMMUTABLE)"}` | |