# Simetrix Platform Overview

```bash
# Hosted API base URL
API_BASE="https://api.simetrix.io"

# Basic connectivity check (Prometheus metrics)
curl "$API_BASE/metrics"
```

## Product Summary
- Simetrix is a decision stack for market forecasting, scenario simulation, and AI-driven execution.
- Components share a common data spine, provenance IDs, and health guardrails.
- Primary audience: institutional research, ops, and execution teams.

## Core Concepts
- Simetrix Data Spine: DuckDB-backed store for predictions, telemetry, and attestations.
- Provenance IDs: run_id, scenario_hash, model_version appear across services and artifacts.
- Guardrails: quotas, rate limits, and stale-feed detection protect outputs.

## Components and Interfaces

### Simetrix API
- Role: core FastAPI surface for forecasting, simulation, telemetry, auth, and Copilot tooling.
- Interfaces: /v2/forecast/*, /simulate/*, /analytics/*, /copilot/tools/*, /metrics, /public/attestations.
- Docs: https://api.simetrix.io/api-docs

### Market Twin
- Role: hierarchical forecasting engine for symbols and portfolios.
- Interfaces: /v1/infer/*, registry artifacts under data/registry/market_twin/*.
- Consumes scenario_hash for conditioned forecasts.

### Scenario Engine
- Role: deterministic scenario minting and quota enforcement.
- Interfaces: /scenario/run, /scenario/batch/run, /scenario/summary/*, /scenario/health.
- Emits scenario_hash used by Market Twin, MarketSimulator, and AI Trader.

### MarketSimulator
- Role: multi-agent replay and narrative lab with telemetry outputs.
- Interfaces: /dashboard, SSE/WS feeds, RunManifest artifacts under runs/.
- Publishes calibration evidence back to the data spine.

### Simetrix AI Trader
- Role: execution brain with adapters, risk engines, and dashboards.
- Interfaces: /v1/trader/*, /metrics, WS feeds, dashboards at /settings, /ops, /risk.

### Simetrix Frontend
- Role: React/Vite surface for /app, /portfolio, /scenario-studio, /market-simulator, /docs, /ops.
- Consumes Simetrix API and Market Twin outputs.

## Auth and Access
- Tokens: Bearer token in Authorization header (or X-API-Key/x-pt-key for some routes).
- Common scopes: forecast:read:v2, portfolio:read, scenario:run, scenario:condition, admin.

## Environments
- Local default API base: http://127.0.0.1:8900
- Hosted API base: https://api.simetrix.io

## Related Context Files
- API reference: https://simetrix.io/docs/contexts/api-ref.md
- Integration guides: https://simetrix.io/docs/contexts/guides.md
- Full reference: https://simetrix.io/docs/contexts/full-ref.md