@riskmodels/mcp 1.0.1

package/data/schema-paths.json

@@ -0,0 +1,16 @@
+[
+  "/schemas/ticker-returns-v2.json",
+  "/schemas/macro-factors-series-v1.json",
+  "/schemas/factor-correlation-v1.json",
+  "/schemas/factor-correlation-request-v1.json",
+  "/schemas/l3-decomposition-v1.json",
+  "/schemas/tickers-list-v1.json",
+  "/schemas/error-v1.json",
+  "/schemas/health-v1.json",
+  "/schemas/telemetry-v1.json",
+  "/schemas/estimate-v1.json",
+  "/schemas/decompose-v1.json",
+  "/schemas/risk-metadata-v1.json",
+  "/schemas/portfolio-risk-snapshot-v1.json",
+  "/schemas/portfolio-risk-index-v1.json"
+]

package/data/schemas/error-v1.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Error Response",
+  "type": "object",
+  "required": [
+    "error"
+  ],
+  "properties": {
+    "error": {
+      "type": "string",
+      "description": "Error message"
+    },
+    "error_code": {
+      "type": "string",
+      "description": "Machine-readable error code"
+    },
+    "message": {
+      "type": "string",
+      "description": "Detailed error message"
+    },
+    "details": {
+      "type": "object",
+      "description": "Additional error details (dev only)"
+    },
+    "_agent": {
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": [
+            "retry",
+            "top_up",
+            "upgrade",
+            "contact_support"
+          ]
+        },
+        "retry_after_seconds": {
+          "type": "integer"
+        },
+        "top_up_url": {
+          "type": "string"
+        },
+        "upgrade_url": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/data/schemas/estimate-v1.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Cost Estimate Response",
+  "type": "object",
+  "required": [
+    "estimated_cost_usd",
+    "capability",
+    "pricing_model",
+    "note"
+  ],
+  "properties": {
+    "estimated_cost_usd": {
+      "type": "number",
+      "description": "Predicted cost in USD"
+    },
+    "estimated_tokens": {
+      "type": "integer",
+      "description": "Equivalent token count at $0.00002/token"
+    },
+    "estimated_rows": {
+      "type": "integer",
+      "description": "Estimated row count for time-series endpoints"
+    },
+    "estimated_bytes": {
+      "type": "integer",
+      "description": "Estimated response size in bytes"
+    },
+    "capability": {
+      "type": "string",
+      "description": "Capability ID (e.g. ticker-returns, batch-analysis)"
+    },
+    "pricing_model": {
+      "type": "string",
+      "enum": ["per_request", "per_position", "per_token", "subscription"]
+    },
+    "unit_cost_usd": {
+      "type": "number",
+      "description": "Per-request or per-position unit cost"
+    },
+    "min_charge": {
+      "type": "number",
+      "description": "Minimum charge for batch endpoints"
+    },
+    "note": {
+      "type": "string",
+      "description": "Disclaimer about actual cost variance"
+    }
+  }
+}

package/data/schemas/factor-correlation-request-v1.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://riskmodels.app/schemas/factor-correlation-request-v1.json",
+  "title": "FactorCorrelationRequest",
+  "description": "JSON body for POST /api/correlation. Matches OpenAPI components.schemas.FactorCorrelationRequest and FactorCorrelationRequestSchema in lib/api/schemas.ts. Use integer types for window_days; the API may coerce numeric strings at runtime.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ticker"],
+  "properties": {
+    "ticker": {
+      "description": "Single US equity ticker, or batch: 1–50 tickers (200 response returns a results array).",
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 12
+        },
+        {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 50,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 12
+          }
+        }
+      ]
+    },
+    "factors": {
+      "type": "array",
+      "description": "Macro factor keys (lowercase canonical: bitcoin, gold, oil, dxy, vix, ust10y2y). Server normalizes aliases (e.g. btc → bitcoin). Omit to use all six.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "return_type": {
+      "type": "string",
+      "enum": ["gross", "l1", "l2", "l3_residual"],
+      "default": "l3_residual"
+    },
+    "window_days": {
+      "type": "integer",
+      "minimum": 20,
+      "maximum": 2000,
+      "default": 252
+    },
+    "method": {
+      "type": "string",
+      "enum": ["pearson", "spearman"],
+      "default": "pearson"
+    }
+  }
+}

package/data/schemas/factor-correlation-v1.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://riskmodels.app/schemas/factor-correlation-v1.json",
+  "title": "FactorCorrelationResponse",
+  "description": "Successful single-ticker 200 body for POST /api/correlation (and GET /api/metrics/{ticker}/correlation). Batch POST responses wrap per-ticker items in results (see OpenAPI). POST request body: factor-correlation-request-v1.json.",
+  "type": "object",
+  "required": ["ticker", "return_type", "window_days", "method", "correlations", "overlap_days", "warnings"],
+  "properties": {
+    "ticker": { "type": "string" },
+    "return_type": {
+      "type": "string",
+      "enum": ["gross", "l1", "l2", "l3_residual"]
+    },
+    "window_days": { "type": "integer", "minimum": 20, "maximum": 2000 },
+    "method": { "type": "string", "enum": ["pearson", "spearman"] },
+    "correlations": {
+      "type": "object",
+      "additionalProperties": { "type": ["number", "null"] }
+    },
+    "overlap_days": { "type": "integer" },
+    "warnings": { "type": "array", "items": { "type": "string" } },
+    "_metadata": { "type": "object" },
+    "_agent": {
+      "type": "object",
+      "properties": {
+        "latency_ms": { "type": "integer" },
+        "request_id": { "type": "string" }
+      }
+    }
+  }
+}

package/data/schemas/health-v1.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Health Status Response",
+  "type": "object",
+  "required": ["status", "timestamp", "version"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["healthy", "degraded", "down"]
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "version": {
+      "type": "string"
+    },
+    "services": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["healthy", "degraded", "down"]
+          },
+          "latency_ms": {
+            "type": "integer"
+          },
+          "last_update": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["available", "degraded", "unavailable"]
+          },
+          "avg_latency_ms_24h": {
+            "type": "integer"
+          },
+          "success_rate_24h": {
+            "type": "number"
+          },
+          "current_load": {
+            "type": "number"
+          }
+        }
+      }
+    },
+    "macro_factors": {
+      "type": "object",
+      "description": "Macro factors data health for correlation and GET /macro-factors series",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["healthy", "stale", "unavailable"]
+        },
+        "latest_teos": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "row_count_last_7d": {
+          "type": "integer"
+        },
+        "newest_teo": {
+          "type": ["string", "null"]
+        },
+        "oldest_teo": {
+          "type": ["string", "null"]
+        },
+        "stale": {
+          "type": "boolean"
+        }
+      }
+    }
+  }
+}

package/data/schemas/l3-decomposition-v1.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "L3 Risk Decomposition Response",
+  "description": "Daily EOD hierarchical orthogonal decomposition of a ticker's returns into market, sector, subsector, and residual components. Returns time-aligned parallel arrays (dates[i] pairs with every other array's [i]). Historical data streams from GCP zarr.",
+  "type": "object",
+  "required": [
+    "ticker",
+    "market_factor_etf",
+    "universe",
+    "dates",
+    "l3_market_hr",
+    "l3_sector_hr",
+    "l3_subsector_hr",
+    "l3_market_er",
+    "l3_sector_er",
+    "l3_subsector_er",
+    "l3_residual_er"
+  ],
+  "properties": {
+    "ticker": {
+      "type": "string",
+      "description": "Uppercased ticker symbol the decomposition was computed for (e.g. NVDA)."
+    },
+    "market_factor_etf": {
+      "type": "string",
+      "description": "ETF used as the market factor at Level 1. Defaults to SPY."
+    },
+    "universe": {
+      "type": "string",
+      "description": "Risk universe label (e.g. erm3_us_equity). Documents which peer set drove sector/subsector ETF selection."
+    },
+    "data_source": {
+      "type": "string",
+      "description": "Provenance tag for the underlying data bars. Typical values: 'zarr' (historical), 'supabase_latest' (latest snapshot)."
+    },
+    "dates": {
+      "type": "array",
+      "description": "Trading-day dates, one per observation, in ascending order. Aligned index-by-index with the other arrays in this response.",
+      "items": {
+        "type": "string",
+        "format": "date",
+        "description": "Trading day in YYYY-MM-DD format (US markets)."
+      }
+    },
+    "l3_market_hr": {
+      "type": "array",
+      "description": "Per-day hedge ratio vs. the Level 1 market factor ETF (units of market ETF per unit of ticker) after all three levels of orthogonalization.",
+      "items": { "type": ["number", "null"] }
+    },
+    "l3_sector_hr": {
+      "type": "array",
+      "description": "Per-day hedge ratio vs. the sector ETF after removing market beta (Level 2 residual regressed on sector). Negative values are valid after orthogonalization.",
+      "items": { "type": ["number", "null"] }
+    },
+    "l3_subsector_hr": {
+      "type": "array",
+      "description": "Per-day hedge ratio vs. the subsector ETF after removing both market and sector beta (Level 3 residual regressed on subsector). Negative values are valid after orthogonalization.",
+      "items": { "type": ["number", "null"] }
+    },
+    "l3_market_er": {
+      "type": "array",
+      "description": "Per-day fraction of total variance explained by the market factor (0–1). Summing (l3_market_er + l3_sector_er + l3_subsector_er + l3_residual_er) at any index yields ~1.0.",
+      "items": { "type": ["number", "null"] }
+    },
+    "l3_sector_er": {
+      "type": "array",
+      "description": "Per-day fraction of variance explained by the sector factor after removing market. Sums with the other *_er arrays to ~1.0.",
+      "items": { "type": ["number", "null"] }
+    },
+    "l3_subsector_er": {
+      "type": "array",
+      "description": "Per-day fraction of variance explained by the subsector factor after removing market and sector. Sums with the other *_er arrays to ~1.0.",
+      "items": { "type": ["number", "null"] }
+    },
+    "l3_residual_er": {
+      "type": "array",
+      "description": "Per-day fraction of variance that is idiosyncratic (stock-specific). Cannot be hedged by the L1/L2/L3 ETFs — this is the 'true alpha' contribution. Sums with the other *_er arrays to ~1.0.",
+      "items": { "type": ["number", "null"] }
+    },
+    "_metadata": {
+      "type": "object",
+      "description": "Provenance and freshness metadata attached by the API.",
+      "properties": {
+        "data_as_of": {
+          "type": "string",
+          "format": "date",
+          "description": "Latest trading day in the response (YYYY-MM-DD). Also emitted as the X-Data-As-Of response header."
+        },
+        "data_source": {
+          "type": "string",
+          "description": "Source of the time series (e.g. 'zarr')."
+        },
+        "range": {
+          "type": "array",
+          "description": "Inclusive [start_date, end_date] covered by the returned series.",
+          "items": { "type": "string", "format": "date" },
+          "minItems": 2,
+          "maxItems": 2
+        },
+        "billing_code": {
+          "type": "string",
+          "description": "Internal billing SKU recorded for this request."
+        }
+      }
+    },
+    "_agent": {
+      "type": "object",
+      "description": "Per-call agent envelope: cost, latency, and request correlation for telemetry.",
+      "properties": {
+        "cost_usd": {
+          "type": "number",
+          "description": "USD cost billed for this request against the key's daily spend budget."
+        },
+        "latency_ms": {
+          "type": "integer",
+          "description": "Server-side data fetch latency in milliseconds."
+        },
+        "request_id": {
+          "type": "string",
+          "description": "Unique request identifier for log correlation and support tickets."
+        }
+      }
+    }
+  }
+}

package/data/schemas/macro-factors-series-v1.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://riskmodels.app/schemas/macro-factors-series-v1.json",
+  "title": "MacroFactorsSeriesResponse",
+  "description": "Successful 200 body for GET /api/macro-factors (daily macro factor returns, long format).",
+  "type": "object",
+  "required": ["factors_requested", "start", "end", "row_count", "series", "warnings"],
+  "properties": {
+    "factors_requested": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "start": { "type": "string", "format": "date" },
+    "end": { "type": "string", "format": "date" },
+    "row_count": { "type": "integer", "minimum": 0 },
+    "series": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["factor_key", "teo"],
+        "properties": {
+          "factor_key": { "type": "string" },
+          "teo": { "type": "string", "format": "date" },
+          "return_gross": { "type": ["number", "null"] },
+          "metadata": { "type": "object", "additionalProperties": true }
+        },
+        "additionalProperties": true
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "_metadata": { "type": "object", "additionalProperties": true },
+    "_agent": {
+      "type": "object",
+      "properties": {
+        "latency_ms": { "type": "integer" },
+        "request_id": { "type": "string" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/data/schemas/portfolio-risk-index-v1.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PortfolioRiskIndex",
+  "description": "JSON response for POST /api/portfolio/risk-index. Returns L3 variance decomposition for a weighted portfolio.",
+  "type": "object",
+  "required": ["portfolio_risk_index"],
+  "properties": {
+    "portfolio_risk_index": {
+      "type": "object",
+      "required": ["variance_decomposition", "portfolio_volatility_23d", "position_count"],
+      "properties": {
+        "variance_decomposition": {
+          "type": "object",
+          "required": ["market", "sector", "subsector", "residual"],
+          "properties": {
+            "market": { "type": "number" },
+            "sector": { "type": "number" },
+            "subsector": { "type": "number" },
+            "residual": { "type": "number" }
+          }
+        },
+        "portfolio_volatility_23d": {
+          "type": ["number", "null"]
+        },
+        "position_count": {
+          "type": "integer"
+        }
+      }
+    },
+    "time_series": {
+      "type": "array",
+      "description": "Only present when timeSeries=true",
+      "items": {
+        "type": "object",
+        "properties": {
+          "date": { "type": "string", "format": "date" },
+          "market": { "type": "number" },
+          "sector": { "type": "number" },
+          "subsector": { "type": "number" },
+          "residual": { "type": "number" }
+        }
+      }
+    },
+    "cost_usd": { "type": "number" },
+    "positions_resolved": { "type": "integer" },
+    "positions_errored": { "type": "integer" }
+  }
+}

package/data/schemas/portfolio-risk-snapshot-v1.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PortfolioRiskSnapshot",
+  "description": "JSON response for POST /api/portfolio/risk-snapshot (format=json). When format=pdf, the response is binary application/pdf.",
+  "type": "object",
+  "required": ["title", "as_of", "portfolio_risk_index", "per_ticker", "_metadata"],
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Report title (user-supplied or auto-generated)"
+    },
+    "as_of": {
+      "type": "string",
+      "format": "date",
+      "description": "Report label date (YYYY-MM-DD)"
+    },
+    "portfolio_risk_index": {
+      "type": "object",
+      "required": ["variance_decomposition", "portfolio_volatility_23d", "position_count"],
+      "properties": {
+        "variance_decomposition": {
+          "type": "object",
+          "required": ["market", "sector", "subsector", "residual", "systematic"],
+          "properties": {
+            "market": { "type": "number", "description": "Fraction of portfolio variance from market factor" },
+            "sector": { "type": "number", "description": "Fraction from sector factors" },
+            "subsector": { "type": "number", "description": "Fraction from subsector factors" },
+            "residual": { "type": "number", "description": "Fraction from idiosyncratic / stock-specific risk" },
+            "systematic": { "type": "number", "description": "market + sector + subsector" }
+          }
+        },
+        "portfolio_volatility_23d": {
+          "type": ["number", "null"],
+          "description": "23-day weighted annualized portfolio volatility"
+        },
+        "position_count": {
+          "type": "integer",
+          "description": "Number of resolved positions"
+        },
+        "diversification": {
+          "type": "object",
+          "description": "Optional correlation-adjusted diversification metrics. Present only when include_diversification=true on the request.",
+          "properties": {
+            "window_days": { "type": "integer", "description": "Rolling window used to estimate ETF correlations (trading days)." },
+            "method": { "type": "string", "description": "Correlation method used (e.g. 'pearson')." },
+            "naive_pws": {
+              "type": "object",
+              "description": "Position-weighted sum of per-ticker ERs, ignoring cross-position correlations (upper bound on systematic risk).",
+              "properties": {
+                "market_er": { "type": "number", "description": "Position-weighted sum of market ER." },
+                "sector_er": { "type": "number", "description": "Position-weighted sum of sector ER." },
+                "subsector_er": { "type": "number", "description": "Position-weighted sum of subsector ER." },
+                "residual_er": { "type": "number", "description": "Position-weighted sum of residual ER." },
+                "total": { "type": "number", "description": "Sum of the four layers; naive upper bound for portfolio risk share." }
+              }
+            },
+            "correlation_adjusted": {
+              "type": "object",
+              "description": "Same layers as naive_pws, adjusted for the correlation matrix of the sector/subsector ETFs (actual variance contribution).",
+              "properties": {
+                "market_er": { "type": "number", "description": "Correlation-adjusted market ER." },
+                "sector_er": { "type": "number", "description": "Correlation-adjusted sector ER (reflects cross-sector correlations)." },
+                "subsector_er": { "type": "number", "description": "Correlation-adjusted subsector ER (reflects cross-subsector correlations)." },
+                "residual_er": { "type": "number", "description": "Residual ER after correlation adjustment." },
+                "total": { "type": "number", "description": "Sum of the adjusted layers." }
+              }
+            },
+            "diversification_credit": {
+              "type": "object",
+              "description": "Per-layer 'credit' from correlation adjustment: naive_pws[layer] − correlation_adjusted[layer]. Higher = more diversification benefit.",
+              "properties": {
+                "market": { "type": "number", "description": "Diversification credit at the market layer." },
+                "sector": { "type": "number", "description": "Diversification credit at the sector layer." },
+                "subsector": { "type": "number", "description": "Diversification credit at the subsector layer." },
+                "residual": { "type": "number", "description": "Diversification credit at the residual (idiosyncratic) layer." },
+                "total": { "type": "number", "description": "Sum of per-layer diversification credits." }
+              }
+            },
+            "layers": {
+              "type": "array",
+              "description": "Per-layer detail aligned with the decomposition hierarchy. Useful for ranking which layer is carrying the most (and least-diversified) risk.",
+              "items": {
+                "type": "object",
+                "required": ["layer", "naive_er", "adjusted_er", "adjustment_er"],
+                "properties": {
+                  "layer": { "type": "string", "enum": ["market", "sector", "subsector", "residual"], "description": "Which layer of the decomposition this row describes." },
+                  "naive_er": { "type": "number", "description": "Position-weighted sum of ER at this layer (no correlation adjustment)." },
+                  "adjusted_er": { "type": "number", "description": "Correlation-adjusted ER at this layer." },
+                  "adjustment_er": { "type": "number", "description": "naive_er − adjusted_er. Positive means diversification reduced risk at this layer." },
+                  "multiplier": { "type": ["number", "null"], "description": "Ratio adjusted_er / naive_er (null if naive_er is 0)." },
+                  "unique_etfs": { "type": "integer", "description": "Count of distinct sector/subsector ETFs contributing to this layer for the portfolio." }
+                }
+              }
+            },
+            "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal warnings about data coverage or assumption violations." },
+            "_explanation": { "type": "string", "description": "Plain-English summary suitable for showing to an end user." }
+          }
+        }
+      }
+    },
+    "per_ticker": {
+      "type": "array",
+      "description": "One row per position, in the order supplied in the request. Null values indicate the metric was unavailable for that ticker on the snapshot date.",
+      "items": {
+        "type": "object",
+        "required": ["ticker", "weight"],
+        "properties": {
+          "ticker": { "type": "string", "description": "Uppercased ticker symbol." },
+          "weight": { "type": "number", "description": "Supplied portfolio weight (not necessarily normalized to 1)." },
+          "l3_mkt_er": { "type": ["number", "null"], "description": "Fraction of this position's variance explained by the market factor (0–1)." },
+          "l3_sec_er": { "type": ["number", "null"], "description": "Fraction explained by the sector factor after removing market (0–1)." },
+          "l3_sub_er": { "type": ["number", "null"], "description": "Fraction explained by the subsector factor after removing market and sector (0–1)." },
+          "l3_res_er": { "type": ["number", "null"], "description": "Fraction of idiosyncratic / stock-specific variance. Cannot be ETF-hedged." },
+          "l3_mkt_hr": { "type": ["number", "null"], "description": "Hedge ratio vs. market factor ETF (SPY by default)." },
+          "l3_sec_hr": { "type": ["number", "null"], "description": "Hedge ratio vs. sector ETF after orthogonalizing against market. Negative values are valid." },
+          "l3_sub_hr": { "type": ["number", "null"], "description": "Hedge ratio vs. subsector ETF after orthogonalizing against market and sector. Negative values are valid." },
+          "vol_23d": { "type": ["number", "null"], "description": "23-day annualized volatility." },
+          "price_close": { "type": ["number", "null"], "description": "Latest close price in USD." }
+        }
+      }
+    },
+    "_metadata": {
+      "type": "object",
+      "description": "Response provenance and billing metadata. Also surfaced as response headers (X-Data-As-Of, X-Cost-Usd).",
+      "required": ["generated_at", "lineage", "billing_code"],
+      "properties": {
+        "generated_at": { "type": "string", "format": "date-time", "description": "Server-side timestamp when this snapshot was computed (ISO 8601)." },
+        "lineage": { "type": "string", "description": "Lineage identifier linking this response to the risk engine version and data cut." },
+        "billing_code": { "type": "string", "description": "Internal billing SKU recorded for this request." },
+        "data_as_of": { "type": "string", "format": "date", "description": "Trading day the underlying metrics correspond to (YYYY-MM-DD)." }
+      }
+    }
+  }
+}