Add output format documentation to metrics schema

Documents the JSON output structure for:
- Aggregated response from fetch_all_research_data
- Individual MCP outputs (fundamentals, valuation, volatility, macro, news, sentiment)
- Streamed partial_metrics format

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.obsidian/workspace.json

@@ -13,12 +13,12 @@
             "state": {
               "type": "markdown",
               "state": {
-                "file": "docs/mcp_raw_visa.md",
+                "file": "docs/metrics_schema_human_readable.md",
                 "mode": "source",
                 "source": false
               },
               "icon": "lucide-file",
-              "title": "mcp_raw_visa"
+              "title": "metrics_schema_human_readable"
             }
           }
         ]
@@ -185,11 +185,12 @@
   },
   "active": "369b0d31e1527f56",
   "lastOpenFiles": [
+    "docs/mcp_test_report_KO.md",
+    "docs/metrics_schema_human_readable.md",
+    "docs/mcp_raw_visa.md",
     "app.py.tmp.1610.1768146282892",
     "mcp-servers/volatility-basket/server.py.tmp.1610.1768144883587",
     "__pycache__/mcp_client.cpython-311.pyc.140529827342128",
-    "docs/mcp_test_report_KO.md",
-    "docs/metrics_schema_human_readable.md",
     "docs/metrics_schema_emitted.md",
     "docs/schema_normalization.md",
     "mcp_client.py.tmp.1610.1768140230378",
@@ -199,8 +200,6 @@
     "mcp_client.py.tmp.1610.1768140165633",
     "mcp_client.py.tmp.1610.1768140149514",
     "mcp_client.py.tmp.1610.1768140127411",
-    "mcp_client.py.tmp.1610.1768140120176",
-    "docs/mcp_raw_visa.md",
     "docs/alphavantage_data_schema.md",
     "docs/mcp_data_sources.md",
     "docs/mcp_normalized_schemas.md",

docs/metrics_schema_human_readable.md

@@ -178,3 +178,227 @@ Standardized output schema for financial data across ALL industries (banks, cons
 | `mcp-servers/volatility-basket/server.py`                  | Both        | get_all_sources_volatility()        |
 | `mcp-servers/macro-basket/server.py`                       | Both        | get_all_sources_macro()             |
 | `tests/test_mcp_e2e.py`                                    | Test        | E2E validation with expected counts |
+
+---
+
+## Output Format
+
+### Aggregated Response (from `fetch_all_research_data`)
+
+```json
+{
+  "ticker": "AAPL",
+  "company_name": "Apple Inc.",
+  "sources_available": ["fundamentals", "valuation", "volatility", "macro", "news", "sentiment"],
+  "sources_failed": [],
+  "metrics": {
+    "fundamentals": { ... },
+    "valuation": { ... },
+    "volatility": { ... },
+    "macro": { ... },
+    "news": { ... },
+    "sentiment": { ... }
+  },
+  "multi_source": {
+    "fundamentals_all": { ... },
+    "valuation_all": { ... },
+    "macro_all": { ... },
+    "volatility_all": { ... }
+  },
+  "conflict_resolution": { ... },
+  "aggregated_swot": { ... },
+  "completeness": {
+    "completeness_pct": 85.0,
+    "metrics_found": 17,
+    "metrics_total": 20,
+    "missing": { ... }
+  },
+  "generated_at": "2025-01-11T21:00:00"
+}
+```
+
+---
+
+### Fundamentals Output
+
+```json
+{
+  "sec_edgar": {
+    "source": "SEC EDGAR XBRL",
+    "data": {
+      "revenue": {"value": 383285000000, "end_date": "2024-09-28", "fiscal_year": 2024, "form": "10-K"},
+      "net_income": {"value": 93736000000, "end_date": "2024-09-28", "fiscal_year": 2024, "form": "10-K"},
+      "net_margin_pct": {"value": 24.45, "end_date": "2024-09-28", "fiscal_year": 2024, "form": "10-K"},
+      "total_assets": {"value": 364980000000},
+      "total_liabilities": {"value": 308030000000},
+      "stockholders_equity": {"value": 56950000000}
+    }
+  },
+  "yahoo_finance": {
+    "source": "Yahoo Finance",
+    "data": {
+      "operating_margin_pct": 30.74,
+      "total_debt": 106629000000,
+      "operating_cash_flow": 118254000000,
+      "free_cash_flow": 111443000000
+    }
+  }
+}
+```
+
+---
+
+### Valuation Output
+
+```json
+{
+  "yahoo_finance": {
+    "source": "Yahoo Finance",
+    "data": {
+      "current_price": 229.87,
+      "market_cap": 3480000000000,
+      "enterprise_value": 3580000000000,
+      "trailing_pe": 37.12,
+      "forward_pe": 31.45,
+      "ps_ratio": 9.08,
+      "pb_ratio": 61.11,
+      "trailing_peg": 2.89,
+      "forward_peg": 2.15,
+      "earnings_growth": 0.1047,
+      "revenue_growth": 0.0204
+    }
+  },
+  "alpha_vantage": {
+    "source": "Alpha Vantage",
+    "data": { ... }
+  }
+}
+```
+
+---
+
+### Volatility Output
+
+```json
+{
+  "yahoo_finance": {
+    "source": "Yahoo Finance",
+    "data": {
+      "beta": {"value": 1.24},
+      "historical_volatility": {"value": 22.5},
+      "implied_volatility": {"value": null}
+    }
+  },
+  "market_volatility_context": {
+    "vix": {"value": 15.45, "date": "2025-01-10"},
+    "vxn": {"value": 18.32, "date": "2025-01-10"}
+  }
+}
+```
+
+---
+
+### Macro Output
+
+```json
+{
+  "bea_bls": {
+    "source": "BEA/BLS",
+    "data": {
+      "gdp_growth": {"value": 4.30, "date": "2024-09-01"},
+      "cpi_inflation": {"value": 2.74, "date": "2024-12-01"},
+      "unemployment": {"value": 4.40, "date": "2024-12-01"}
+    }
+  },
+  "fred": {
+    "source": "FRED",
+    "data": {
+      "interest_rate": {"value": 3.72, "date": "2025-01-09"}
+    }
+  }
+}
+```
+
+---
+
+### News Output
+
+```json
+{
+  "group": "content_analysis",
+  "ticker": "AAPL",
+  "items": [
+    {
+      "title": "Apple Reports Record Q4 Earnings",
+      "content": "Apple Inc. reported...",
+      "url": "https://...",
+      "datetime": "2025-01-10",
+      "source": "Tavily"
+    }
+  ],
+  "item_count": 10,
+  "sources_used": ["Tavily", "NYT", "NewsAPI"],
+  "source": "news-basket",
+  "as_of": "2025-01-11"
+}
+```
+
+---
+
+### Sentiment Output
+
+```json
+{
+  "group": "content_analysis",
+  "ticker": "AAPL",
+  "items": [
+    {
+      "title": "AAPL to the moon!",
+      "content": "Just loaded up on more shares...",
+      "url": "https://reddit.com/r/wallstreetbets/...",
+      "datetime": "2025-01-10",
+      "source": "Reddit",
+      "subreddit": "r/wallstreetbets"
+    },
+    {
+      "title": "Apple Announces New Product Line",
+      "content": "Apple Inc. unveiled...",
+      "url": "https://finnhub.io/...",
+      "datetime": "2025-01-09",
+      "source": "Finnhub",
+      "subreddit": null
+    }
+  ],
+  "item_count": 15,
+  "sources_used": ["Finnhub", "Reddit"],
+  "source": "sentiment-basket",
+  "as_of": "2025-01-11"
+}
+```
+
+---
+
+### Streamed Metrics (partial_metrics)
+
+During task execution, metrics are streamed as:
+
+```json
+{
+  "source": "fundamentals",
+  "metric": "revenue",
+  "value": 383285000000,
+  "timestamp": "2025-01-11T21:00:01",
+  "end_date": "2024-09-28",
+  "fiscal_year": 2024,
+  "form": "10-K"
+}
+```
+
+| Source | Metrics Streamed |
+|--------|------------------|
+| fundamentals | `revenue`, `net_margin` |
+| valuation | `P/E`, `P/B`, `P/S`, `EV/EBITDA` |
+| volatility | `VIX`, `beta`, `hist_vol` |
+| macro | `GDP_growth`, `interest_rate`, `inflation`, `unemployment` |
+| news | `items_found` (count) |
+| sentiment | `items_found` (count) |