Feat/add comprehensive fields (#14)

bearmug · claude · web-flow · commit 69877f3e0b04 · 2025-10-26T20:14:10.000+01:00
* feat: Add comprehensive fundamental fields for advanced screening Add 19 new fields from TradingView API including enterprise value metrics, additional margin ratios, return metrics, and balance sheet data. New fields: - Margins: gross_margin_ttm, operating_margin_ttm, pre_tax_margin_ttm - Returns: return_on_assets, return_on_assets_fq, return_on_invested_capital_fq - Balance sheet: total_assets, total_debt, current_ratio - Valuation: enterprise_value_current, enterprise_value_to_ebit_ttm, enterprise_value_ebitda_ttm, price_earnings_growth_ttm, ebitda - Operating: research_and_dev_ratio_ttm, sell_gen_admin_exp_other_ratio_ttm Expands EXTENDED_COLUMNS from 17 to 31 fields for comprehensive analysis. Enables ~85% coverage of Swedish Investment Playbook requirements. Addresses user request for EV, EV/EBIT, EV/EBITDA, PEG metrics. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Improve filter validation with helpful error messages Add comprehensive validation for filter objects to provide clearer error messages when filters are malformed: - Detect when filters are arrays instead of objects - Check for missing required properties (field, operator, value) - List valid operators in error messages - Show index of problematic filter for easier debugging Replaces unhelpful "Unknown operator: undefined" with specific guidance like "Invalid filter at index 0: expected object with {field, operator, value}, got object". Applies validation to all three screening methods: stocks, forex, crypto. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: Update documentation for comprehensive fields and column optimization Update README to reflect recent additions: - Field count: 50+ → 75+ fields - Add comprehensive valuation metrics feature (EV, EV/EBIT, PEG, etc.) - Add performance optimization feature (minimal 7 vs extended 35 columns) - Document quality_growth_screener returns 35 extended columns - Expand Common Fields section with 4 new subsections: - Valuation & Enterprise Value (EV, EV/EBIT, EV/EBITDA, PEG, EBITDA) - Margins & Profitability (gross, operating, pre-tax, FCF margins) - Returns & Efficiency (ROA, ROIC, R&D ratio, SG&A ratio) - Balance Sheet (total assets, total debt, current ratio) - Add columns parameter to screen_stocks documentation Ensures documentation accurately reflects all 19 new comprehensive fields and the column optimization feature. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/README.md b/README.md
@@ -35,9 +35,10 @@
 ## Features
 
 - 🔍 **Screen stocks, forex, and crypto** with advanced filters
-- 📊 **50+ fundamental, technical, and performance fields** with TTM/FQ/FY variants
+- 📊 **75+ fundamental, technical, and performance fields** with TTM/FQ/FY variants
 - 🎯 **6 preset strategies** (quality, value, dividend, momentum, growth, comprehensive)
-- ⚡ **Configurable caching and rate limiting**
+- ⚡ **Performance optimized** - minimal (7 fields) vs extended (35 fields) column sets
+- 💰 **Comprehensive valuation metrics** - EV, EV/EBIT, EV/EBITDA, PEG, margins, ROIC
 - 🔧 **Works with Claude Desktop and Claude Code**
 - 🏦 **Exchange filtering** (NASDAQ, NYSE, CBOE) and primary listing support
 
@@ -174,6 +175,7 @@ Screen stocks based on filters.
 - `sort_by` - Field to sort by (default: `"market_cap_basic"`)
 - `sort_order` - `"asc"` or `"desc"` (default: `"desc"`)
 - `limit` - Number of results (1-200, default: 20)
+- `columns` - Optional array of columns to return (default: minimal 7 fields for performance)
 
 **Operators:**
 - `greater`, `less`, `greater_or_equal`, `less_or_equal`
@@ -272,6 +274,8 @@ High-growth companies with strong profitability and margins.
 
 Comprehensive quality and growth screen combining fundamental strength, growth momentum, financial stability, and technical uptrend. Primary listings only on major US exchanges.
 
+**Returns 35 extended columns** including enterprise value metrics, margins (gross, operating, pre-tax), returns (ROA, ROIC), balance sheet data, and R&D ratios for deep fundamental analysis.
+
 **16-Filter Criteria:**
 
 **Price & Size:**
@@ -306,7 +310,7 @@ Comprehensive quality and growth screen combining fundamental strength, growth m
 
 ## Common Fields
 
-### Fundamental
+### Fundamental - Core Metrics
 - `return_on_equity` - ROE (%)
 - `price_earnings_ttm` - P/E Ratio
 - `price_book_fq` - P/B Ratio
@@ -315,6 +319,30 @@ Comprehensive quality and growth screen combining fundamental strength, growth m
 - `market_cap_basic` - Market Capitalization
 - `dividend_yield_recent` - Dividend Yield (%)
 
+### Fundamental - Valuation & Enterprise Value
+- `enterprise_value_current` - Enterprise Value (Market Cap + Debt - Cash)
+- `enterprise_value_to_ebit_ttm` - EV/EBIT Ratio
+- `enterprise_value_ebitda_ttm` - EV/EBITDA Ratio
+- `price_earnings_growth_ttm` - PEG Ratio (P/E to Growth)
+- `ebitda` - Earnings Before Interest, Taxes, Depreciation & Amortization
+
+### Fundamental - Margins & Profitability
+- `gross_margin_ttm` - Gross Margin (%)
+- `operating_margin_ttm` - Operating Margin (%)
+- `pre_tax_margin_ttm` - Pre-Tax Margin (%)
+- `free_cash_flow_margin_ttm` - FCF Margin (%)
+
+### Fundamental - Returns & Efficiency
+- `return_on_assets` / `return_on_assets_fq` - ROA (%)
+- `return_on_invested_capital_fq` - ROIC (%)
+- `research_and_dev_ratio_ttm` - R&D as % of Revenue
+- `sell_gen_admin_exp_other_ratio_ttm` - SG&A as % of Revenue
+
+### Fundamental - Balance Sheet
+- `total_assets` - Total Company Assets
+- `total_debt` - Total Company Debt
+- `current_ratio` - Current Assets / Current Liabilities
+
 ### Technical
 - `RSI` - Relative Strength Index (14)
 - `SMA50` - 50-day Simple Moving Average
diff --git a/src/tools/fields.ts b/src/tools/fields.ts
@@ -98,6 +98,125 @@ const STOCK_FIELDS: FieldMetadata[] = [
     type: "percent",
     description: "Operating income as percentage of revenue",
   },
+  {
+    name: "operating_margin_ttm",
+    label: "Operating Margin (TTM)",
+    category: "fundamental",
+    type: "percent",
+    description: "Operating income as percentage of revenue (trailing twelve months)",
+  },
+  {
+    name: "gross_margin",
+    label: "Gross Margin",
+    category: "fundamental",
+    type: "percent",
+    description: "Gross profit as percentage of revenue",
+  },
+  {
+    name: "gross_margin_ttm",
+    label: "Gross Margin (TTM)",
+    category: "fundamental",
+    type: "percent",
+    description: "Gross profit as percentage of revenue (trailing twelve months)",
+  },
+  {
+    name: "pre_tax_margin_ttm",
+    label: "Pre-Tax Margin (TTM)",
+    category: "fundamental",
+    type: "percent",
+    description: "Pre-tax profit as percentage of revenue (trailing twelve months)",
+  },
+  {
+    name: "return_on_assets",
+    label: "Return on Assets",
+    category: "fundamental",
+    type: "percent",
+    description: "Net income relative to total assets",
+  },
+  {
+    name: "return_on_assets_fq",
+    label: "Return on Assets (FQ)",
+    category: "fundamental",
+    type: "percent",
+    description: "Net income relative to total assets (fiscal quarter)",
+  },
+  {
+    name: "return_on_invested_capital_fq",
+    label: "Return on Invested Capital (FQ)",
+    category: "fundamental",
+    type: "percent",
+    description: "Return on total invested capital (fiscal quarter)",
+  },
+  {
+    name: "research_and_dev_ratio_ttm",
+    label: "R&D Ratio (TTM)",
+    category: "fundamental",
+    type: "percent",
+    description: "Research and development expenses as percentage of revenue (trailing twelve months)",
+  },
+  {
+    name: "sell_gen_admin_exp_other_ratio_ttm",
+    label: "SG&A Ratio (TTM)",
+    category: "fundamental",
+    type: "percent",
+    description: "Selling, general and administrative expenses as percentage of revenue (trailing twelve months)",
+  },
+  {
+    name: "total_assets",
+    label: "Total Assets",
+    category: "fundamental",
+    type: "currency",
+    description: "Total company assets",
+  },
+  {
+    name: "total_debt",
+    label: "Total Debt",
+    category: "fundamental",
+    type: "currency",
+    description: "Total company debt",
+  },
+  {
+    name: "current_ratio",
+    label: "Current Ratio",
+    category: "fundamental",
+    type: "number",
+    description: "Current assets divided by current liabilities (liquidity measure)",
+  },
+  {
+    name: "enterprise_value_current",
+    label: "Enterprise Value",
+    category: "fundamental",
+    type: "currency",
+    description: "Market cap plus debt minus cash",
+  },
+  {
+    name: "enterprise_value_to_ebit_ttm",
+    label: "EV/EBIT (TTM)",
+    category: "fundamental",
+    type: "number",
+    description: "Enterprise value to EBIT ratio (trailing twelve months)",
+  },
+  {
+    name: "enterprise_value_ebitda_ttm",
+    label: "EV/EBITDA (TTM)",
+    category: "fundamental",
+    type: "number",
+    description: "Enterprise value to EBITDA ratio (trailing twelve months)",
+  },
+  {
+    name: "price_earnings_growth_ttm",
+    label: "PEG Ratio (TTM)",
+    category: "fundamental",
+    type: "number",
+    description: "Price/earnings to growth ratio (trailing twelve months)",
+  },
+  {
+    name: "ebitda",
+    label: "EBITDA",
+    category: "fundamental",
+    type: "currency",
+    description: "Earnings before interest, taxes, depreciation and amortization",
+  },
   {
     name: "dividend_yield_recent",
     label: "Dividend Yield",
diff --git a/src/tools/screen.ts b/src/tools/screen.ts
@@ -42,16 +42,42 @@ const DEFAULT_COLUMNS = [
 // Extended columns for comprehensive analysis
 export const EXTENDED_COLUMNS = [
   ...DEFAULT_COLUMNS,
+  // Cash flow & margins
   "free_cash_flow_ttm",
   "free_cash_flow_margin_ttm",
+  "gross_margin",
+  "gross_margin_ttm",
+  "operating_margin_ttm",
+  "pre_tax_margin_ttm",
+  // Returns & efficiency
+  "return_on_assets",
+  "return_on_assets_fq",
+  "return_on_invested_capital_fq",
+  // Balance sheet
+  "total_assets",
+  "total_debt",
+  "current_ratio",
+  // Valuation
+  "enterprise_value_current",
+  "enterprise_value_to_ebit_ttm",
+  "enterprise_value_ebitda_ttm",
+  "price_earnings_growth_ttm",
+  "ebitda",
+  // Operating metrics
+  "research_and_dev_ratio_ttm",
+  "sell_gen_admin_exp_other_ratio_ttm",
+  // Earnings & growth
   "earnings_release_next_trading_date_fq",
-  "fundamental_currency_code",
+  "earnings_per_share_diluted_yoy_growth_ttm",
+  // Dividends
   "dividends_yield_current",
   "dividend_payout_ratio_ttm",
+  // Risk & classification
+  "beta_1_year",
   "beta_5_year",
   "sector",
   "industry",
-  "earnings_per_share_diluted_yoy_growth_ttm",
+  "fundamental_currency_code",
 ];
 
 export class ScreenTool {
@@ -86,10 +112,19 @@ export class ScreenTool {
     }
 
     // Convert filters to TradingView format
-    const tvFilters: Filter[] = filters.map((f) => {
+    const tvFilters: Filter[] = filters.map((f, index) => {
+      // Validate filter structure
+      if (!f || typeof f !== 'object' || Array.isArray(f)) {
+        throw new Error(`Invalid filter at index ${index}: expected object with {field, operator, value}, got ${typeof f}`);
+      }
+
+      if (!f.field || !f.operator || f.value === undefined) {
+        throw new Error(`Invalid filter at index ${index}: missing required properties (field: ${f.field}, operator: ${f.operator}, value: ${f.value})`);
+      }
+
       const operation = OPERATOR_MAP[f.operator];
       if (!operation) {
-        throw new Error(`Unknown operator: ${f.operator}`);
+        throw new Error(`Unknown operator: ${f.operator}. Valid operators: ${Object.keys(OPERATOR_MAP).join(', ')}`);
       }
 
       return {
@@ -160,10 +195,19 @@ export class ScreenTool {
     const cached = this.cache.get(cacheKey);
     if (cached) return cached;
 
-    const tvFilters: Filter[] = filters.map((f) => {
+    const tvFilters: Filter[] = filters.map((f, index) => {
+      // Validate filter structure
+      if (!f || typeof f !== 'object' || Array.isArray(f)) {
+        throw new Error(`Invalid filter at index ${index}: expected object with {field, operator, value}, got ${typeof f}`);
+      }
+
+      if (!f.field || !f.operator || f.value === undefined) {
+        throw new Error(`Invalid filter at index ${index}: missing required properties (field: ${f.field}, operator: ${f.operator}, value: ${f.value})`);
+      }
+
       const operation = OPERATOR_MAP[f.operator];
       if (!operation) {
-        throw new Error(`Unknown operator: ${f.operator}`);
+        throw new Error(`Unknown operator: ${f.operator}. Valid operators: ${Object.keys(OPERATOR_MAP).join(', ')}`);
       }
 
       return {
@@ -214,10 +258,19 @@ export class ScreenTool {
     const cached = this.cache.get(cacheKey);
     if (cached) return cached;
 
-    const tvFilters: Filter[] = filters.map((f) => {
+    const tvFilters: Filter[] = filters.map((f, index) => {
+      // Validate filter structure
+      if (!f || typeof f !== 'object' || Array.isArray(f)) {
+        throw new Error(`Invalid filter at index ${index}: expected object with {field, operator, value}, got ${typeof f}`);
+      }
+
+      if (!f.field || !f.operator || f.value === undefined) {
+        throw new Error(`Invalid filter at index ${index}: missing required properties (field: ${f.field}, operator: ${f.operator}, value: ${f.value})`);
+      }
+
       const operation = OPERATOR_MAP[f.operator];
       if (!operation) {
-        throw new Error(`Unknown operator: ${f.operator}`);
+        throw new Error(`Unknown operator: ${f.operator}. Valid operators: ${Object.keys(OPERATOR_MAP).join(', ')}`);
       }
 
       return {
