Deploy Signal Generator app

Dockerfile

@@ -0,0 +1,40 @@
+# Base image
+FROM ubuntu:22.04
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    python3 \
+    python3-pip \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Ollama
+RUN curl -fsSL https://ollama.com/install.sh | sh
+
+# Copy necessary files
+COPY requirements.txt .
+COPY src/ src/
+COPY run_saturday_analysis.py .
+COPY entrypoint.sh .
+# Copy other possible dependencies if they are at root like setup.py or local modules
+# For now, assuming src/ structure covers most imports, but let's be safe
+COPY . .
+
+# Install Python dependencies
+RUN pip3 install --no-cache-dir -r requirements.txt
+
+# Create a non-root user (Hugging Face Spaces runs as user 1000)
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+# Expose the port
+EXPOSE 7860
+
+# Set entrypoint
+ENTRYPOINT ["./entrypoint.sh"]

README.md

@@ -7,4 +7,83 @@ sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Stock Alchemist Signal Generator
+
+A Dockerized FastAPI application that generates stock trading signals using Ollama (LLaMA 3.1) and performs scheduled fundamental analysis. Designed to run on Hugging Face Spaces.
+
+## Features
+
+- **Daily Signal Generation**: Prompts a local LLaMA 3.1 model to analyze stocks and generates trading signals.
+- **Weekly Analysis**: Runs a comprehensive fundamental analysis script every Saturday.
+- **Persistent Storage**: Stores results in a TiDB/MySQL database.
+- **Automated Scheduling**: Uses GitHub Actions to trigger daily and weekly tasks.
+
+## Setup Instructions
+
+### 1. Hugging Face Space Setup
+
+1. Create a new Space on [Hugging Face](https://huggingface.co/spaces).
+2. Select **Docker** as the SDK.
+3. Choose "Blank" or just point it to your repository.
+
+### 2. Environment Variables
+
+In your Hugging Face Space "Settings" -> "Variables and secrets", add the following **Secret** variables:
+
+- `API_SECRET`: A strong secret key to protect your endpoints.
+- `DB_HOST`: Your TiDB/MySQL host.
+- `DB_PORT`: Your TiDB/MySQL port (e.g., 4000 for TiDB, 3306 for MySQL).
+- `DB_USERNAME`: Database username.
+- `DB_PASSWORD`: Database password.
+- `DB_DATABASE`: Database name (e.g., `gotti`).
+- `DB_SSL_CA`: (Optional) Path to SSL CA certificate if needed (relative to repository root).
+
+### 3. GitHub Actions Setup
+
+To enable the scheduler:
+
+1. Go to your GitHub repository -> **Settings** -> **Secrets and variables** -> **Actions**.
+2. Add the following **Repository secrets**:
+   - `HF_SPACE_URL`: The URL of your Hugging Face Space (e.g., `https://username-space-name.hf.space`).
+   - `API_SECRET`: The same secret you set in Hugging Face.
+
+### 4. Database Initialization
+
+The application handles table creation automatically in `src/db/local_database.py`. Ensure your database user has `CREATE TABLE` permissions.
+
+## Local Development
+
+### Prerequisites
+
+- Docker
+- Python 3.10+
+- Ollama (running locally if testing outside Docker)
+
+### Running with Docker
+
+```bash
+# Build the image
+docker build -t stock-alchemist .
+
+# Run the container
+# Note: You need to pass env vars. For local testing, you might want to use --env-file
+docker run -p 7860:7860 \
+  -e API_SECRET=test_secret \
+  -e DB_HOST=host.docker.internal \
+  -e DB_USERNAME=root \
+  -e DB_PASSWORD=yourpassword \
+  stock-alchemist
+```
+
+### API Endpoints
+
+- `POST /generate-signal`: Trigger signal generation. Headers: `X-API-Secret: <your_secret>` (or `API_SECRET` in local dev). *Note: The code uses `API_SECRET` env var validation.*
+- `POST /saturday-analysis`: Trigger weekly analysis.
+- `GET /health`: Health check and system vitals.
+
+## Project Structure
+
+- `Dockerfile` & `entrypoint.sh`: System configuration.
+- `src/main.py`: FastAPI application entry point.
+- `src/db/`: Database interaction logic.
+- `.github/workflows/scheduler.yml`: Automated scheduler.

entrypoint.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# Start Ollama in the background
+ollama serve &
+
+# Wait for Ollama to be ready
+echo "Waiting for Ollama to start..."
+while ! curl -s http://localhost:11434/api/tags > /dev/null; do
+    sleep 1
+done
+echo "Ollama is ready!"
+
+# Pull the model if it doesn't exist
+# We use 'llama3.1' as requested.
+MODEL_NAME="llama3.1"
+if ! ollama list | grep -q "$MODEL_NAME"; then
+    echo "Pulling model $MODEL_NAME..."
+    ollama pull $MODEL_NAME
+else
+    echo "Model $MODEL_NAME already exists."
+fi
+
+# Start the FastAPI application
+# Using uvicorn on port 7860 (Hugging Face default)
+echo "Starting FastAPI app..."
+uvicorn src.main:app --host 0.0.0.0 --port 7860

requirements.txt

@@ -0,0 +1,21 @@
+transformers
+torch
+accelerate
+yfinance
+sqlalchemy
+selenium
+xata
+pandas
+numpy
+openpyxl
+mysql-connector-python
+google-generativeai
+beautifulsoup4
+requests
+python-dotenv
+alpaca-py
+schedule
+fastapi
+uvicorn
+pydantic
+openai

run_saturday_analysis.py

@@ -0,0 +1,86 @@
+"""
+Saturday Fundamental Analysis Runner
+Runs fundamental analysis for all tickers in available_tickers table
+"""
+
+import sys
+from pathlib import Path
+from datetime import datetime
+
+# Add src to path
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+from db.local_database import LocalDatabase, DatabaseEntry, DataType
+from fundamental_analysis.decision_maker import evaluate_stock
+
+def run_saturday_analysis():
+    """Run fundamental analysis for all available tickers"""
+    
+    print("=" * 60)
+    print("📊 SATURDAY FUNDAMENTAL ANALYSIS")
+    print("=" * 60)
+    print(f"Started at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+    
+    # Initialize database
+    db = LocalDatabase()
+    
+    # Get all available tickers
+    tickers = db.get_all_available_tickers()
+    total = len(tickers)
+    
+    if total == 0:
+        print("⚠️  No tickers found in available_tickers table")
+        print("Run: python src/db/populate_tickers.py alpaca")
+        return
+    
+    print(f"📋 Found {total} tickers to analyze\n")
+    
+    success_count = 0
+    error_count = 0
+    skipped_count = 0
+    
+    for i, ticker in enumerate(tickers, 1):
+        try:
+            print(f"[{i}/{total}] Analyzing {ticker}...", end=" ")
+            
+            # Run fundamental analysis
+            result = evaluate_stock(ticker, compare_to_sector=False)
+            
+            if result is None:
+                print("⚠️  Skipped (no data)")
+                skipped_count += 1
+                continue
+            
+            # Save to database
+            today = datetime.now().date().isoformat()
+            entry = DatabaseEntry(
+                date=today,
+                data_type=DataType.FUNDAMENTAL.value,
+                ticker=ticker,
+                data=result,
+                metadata={'saturday_batch': True}
+            )
+            
+            if db.save(entry, expiry_days=7):
+                print(f"✅ {result.get('recommendation', 'HOLD')}")
+                success_count += 1
+            else:
+                print("❌ Save failed")
+                error_count += 1
+                
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            error_count += 1
+    
+    print("\n" + "=" * 60)
+    print("📊 ANALYSIS COMPLETE")
+    print("=" * 60)
+    print(f"✅ Success: {success_count}")
+    print(f"⚠️  Skipped: {skipped_count}")
+    print(f"❌ Errors: {error_count}")
+    print(f"📊 Total: {total}")
+    print(f"\nCompleted at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("=" * 60)
+
+if __name__ == "__main__":
+    run_saturday_analysis()

src/calendar_scraper/adapters/__init__.py

@@ -0,0 +1,2 @@
+# FILE: /calendar-scraper/adapters/__init__.py
+# This file is intentionally left blank.

src/calendar_scraper/adapters/nasdaq.py

@@ -0,0 +1,637 @@
+import requests
+from datetime import datetime, date, timedelta
+import sys
+from pathlib import Path
+
+# Add src to path for database import
+sys.path.append(str(Path(__file__).parent.parent.parent))
+
+from calendar_scraper.models.earnings_calendar import EarningsEvent
+from calendar_scraper.models.economic_calendar import EconomicEvent
+from calendar_scraper.models.ipo_calendar import IPOEvent
+from calendar_scraper.models.stock_split_calendar import StockSplitEvent
+from calendar_scraper.models.dividend_calendar import DividendEvent
+from db.adapters import CalendarAdapter
+
+class NasdaqAdapter():
+    
+    def __init__(self):
+        self.base_earnings_url = "https://api.nasdaq.com/api/calendar/earnings"
+        self.base_ipo_url = "https://api.nasdaq.com/api/ipo/calendar"
+        self.base_splits_url = "https://api.nasdaq.com/api/calendar/splits"
+        self.base_economic_url = "https://api.nasdaq.com/api/calendar/economicevents"
+        self.base_dividends_url = "https://api.nasdaq.com/api/calendar/dividends"
+        
+        self.headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+            "Accept": "application/json, text/plain, */*",
+            "Referer": "https://www.nasdaq.com/market-activity/earnings",
+            "Origin": "https://www.nasdaq.com"
+        }
+        # Initialize database adapter
+        self.db_adapter = CalendarAdapter()
+    
+    def get_earning_events(self):
+        """Get earnings calendar data from NASDAQ API"""
+        try:
+            # Make request to NASDAQ API
+            response = requests.get(self.base_earnings_url, headers=self.headers)
+            response.raise_for_status()
+            
+            # Parse JSON response
+            data = response.json()
+            
+            # Verify response structure
+            if not data or 'data' not in data or 'rows' not in data['data']:
+                print("Invalid response format from NASDAQ API")
+                return []
+            
+            # Extract date from response
+            as_of_date_str = data['data'].get('asOf', '')
+            try:
+                as_of_date = datetime.strptime(as_of_date_str, '%a, %b %d, %Y').date()
+            except ValueError:
+                as_of_date = date.today()
+            
+            # Parse rows into earnings events
+            events = []
+            for row in data['data']['rows']:
+                try:
+                    event = self._parse_row_to_event(row, as_of_date)
+                    if event:
+                        events.append(event)
+                except Exception as e:
+                    print(f"Error parsing row {row['symbol'] if 'symbol' in row else 'unknown'}: {e}")
+            
+            print(f"Found {len(events)} earnings events from NASDAQ")
+            return events
+            
+        except requests.RequestException as e:
+            print(f"Error fetching data from NASDAQ API: {e}")
+            return []
+        except Exception as e:
+            print(f"Unexpected error: {e}")
+            return []
+    
+    def _parse_row_to_event(self, row, report_date):
+        """Convert a row from the NASDAQ API response to an EarningsEvent object"""
+        # Extract basic information
+        ticker = row.get('symbol', '')
+        company = row.get('name', '')
+        
+        # Skip if missing essential data
+        if not ticker or not company:
+            return None
+        
+        # Parse time of day
+        time_str = row.get('time', '').lower()
+        if 'after' in time_str or 'post' in time_str:
+            time_of_day = 'After Close'
+        elif 'pre' in time_str or 'before' in time_str:
+            time_of_day = 'Before Open'
+        elif 'not-supplied' in time_str:
+            time_of_day = 'Unknown'
+        else:
+            time_of_day = 'During Market'
+        
+        # Extract EPS information
+        eps_forecast = row.get('epsForecast', '')
+        last_year_eps = row.get('lastYearEPS', '')
+        
+        # Combine EPS data
+        eps_info = []
+        if eps_forecast:
+            eps_info.append(f"Forecast: {eps_forecast}")
+        if last_year_eps:
+            eps_info.append(f"Last Year: {last_year_eps}")
+        
+        eps = " | ".join(eps_info)
+        
+        # Clean market cap value - remove $ and commas
+        market_cap = row.get('marketCap', '')
+        if market_cap and isinstance(market_cap, str):
+            # Remove $ and commas, then convert to float
+            market_cap = market_cap.replace('$', '').replace(',', '')
+            if market_cap.strip():  # Check if it's not just whitespace
+                try:
+                    market_cap = float(market_cap)
+                except ValueError:
+                    market_cap = None
+        
+        # Create earnings event object
+        event = EarningsEvent(
+            date=report_date,
+            time=time_of_day,
+            company=company,
+            ticker=ticker,
+            eps=eps,
+            revenue="",
+            market_cap=market_cap
+        )
+        
+        try:
+            self.db_adapter.save_earnings_event(
+                date=report_date.strftime("%Y-%m-%d"),
+                ticker=ticker,
+                event_data={
+                    "company": company,
+                    "time": time_of_day,
+                    "eps": eps,
+                    "revenue": "",
+                    "market_cap": market_cap,
+                    "eps_forecast": eps_forecast,
+                    "last_year_eps": last_year_eps
+                }
+            )
+           # print(f"✅ Saved {ticker} earnings event to database for {report_date.strftime('%Y-%m-%d')}")
+        except Exception as e:
+            print(f"⚠️ Failed to save {ticker} to database: {e}")
+        
+        return event
+    
+    # ==================== IPO EVENTS ====================
+    
+    def get_ipo_events(self, date_str: str = None) -> list:
+        """
+        Get IPO calendar data from NASDAQ API
+        
+        Args:
+            date_str: Date in format YYYY-MM (e.g., "2025-11")
+        
+        Returns:
+            List of IPOEvent objects
+        """
+        if not date_str:
+            date_str = datetime.now().strftime("%Y-%m")
+        
+        try:
+            url = f"{self.base_ipo_url}?date={date_str}"
+            response = requests.get(url, headers=self.headers)
+            response.raise_for_status()
+            
+            data = response.json()
+            
+            if not data or 'data' not in data:
+                print("Invalid response format from NASDAQ IPO API")
+                return []
+            
+            events = []
+            
+            # Parse priced IPOs
+            if 'priced' in data['data'] and 'rows' in data['data']['priced']:
+                for row in data['data']['priced']['rows']:
+                    event = self._parse_ipo_row(row, 'priced')
+                    if event:
+                        events.append(event)
+            
+            # Parse upcoming IPOs (nested under upcomingTable)
+            if 'upcoming' in data['data'] and data['data']['upcoming']:
+                upcoming_data = data['data']['upcoming']
+                if 'upcomingTable' in upcoming_data and upcoming_data['upcomingTable']:
+                    upcoming_table = upcoming_data['upcomingTable']
+                    if 'rows' in upcoming_table and upcoming_table['rows']:
+                        for row in upcoming_table['rows']:
+                            event = self._parse_ipo_row(row, 'upcoming')
+                            if event:
+                                events.append(event)
+            
+            # Parse filed IPOs
+            if 'filed' in data['data'] and data['data']['filed']:
+                filed_data = data['data']['filed']
+                # Check if rows are directly under filed or nested
+                if 'rows' in filed_data and filed_data['rows']:
+                    for row in filed_data['rows']:
+                        event = self._parse_ipo_row(row, 'filed')
+                        if event:
+                            events.append(event)
+            
+            print(f"Found {len(events)} IPO events from NASDAQ")
+            return events
+            
+        except requests.RequestException as e:
+            print(f"Error fetching IPO data from NASDAQ API: {e}")
+            return []
+        except Exception as e:
+            print(f"Unexpected error in get_ipo_events: {e}")
+            return []
+    
+    def _parse_ipo_row(self, row, status):
+        """Parse IPO row data"""
+        try:
+            company = row.get('companyName', '')
+            ticker = row.get('proposedTickerSymbol', '')
+            exchange = row.get('proposedExchange', '')
+            
+            if not company or not ticker:
+                return None
+            
+            # Parse date
+            date_str = row.get('expectedPriceDate', '') or row.get('pricedDate', '')
+            if date_str:
+                try:
+                    event_date = datetime.strptime(date_str, '%m/%d/%Y').date()
+                except:
+                    event_date = datetime.now().date()
+            else:
+                event_date = datetime.now().date()
+            
+            # Get shares and clean if string (remove commas)
+            shares_raw = row.get('sharesOffered', '')
+            shares = 0
+            if shares_raw:
+                try:
+                    # Remove commas and convert to int
+                    shares = int(str(shares_raw).replace(',', ''))
+                except:
+                    shares = 0
+            
+            price_range = row.get('proposedSharePrice', '')
+            offer_amount = row.get('dollarValueOfSharesOffered', '')
+            deal_status = row.get('dealStatus', status)
+            
+            # Calculate market cap from offer amount or price range
+            market_cap = None
+            try:
+                # Try to get from offer amount first
+                if offer_amount:
+                    # Remove $, commas, and convert (e.g., "$1,014,999,994")
+                    offer_clean = str(offer_amount).replace('$', '').replace(',', '')
+                    market_cap = float(offer_clean)
+                elif shares and price_range:
+                    # Extract average price from range (e.g., "4.00-6.00")
+                    if '-' in str(price_range):
+                        prices = str(price_range).replace('$', '').split('-')
+                        avg_price = (float(prices[0].strip()) + float(prices[1].strip())) / 2
+                        market_cap = shares * avg_price
+                    elif price_range:
+                        # Single price
+                        price = float(str(price_range).replace('$', ''))
+                        market_cap = shares * price
+            except:
+                pass
+            
+            event = IPOEvent(
+                date=event_date,
+                company=company,
+                ticker=ticker,
+                exchange=exchange,
+                shares=str(shares) if shares else "",
+                price_range=str(price_range) if price_range else "",
+                market_cap=market_cap,
+                expected_to_trade=deal_status
+            )
+            
+            # Save to database
+            try:
+                from db.local_database import DatabaseEntry, DataType
+                entry = DatabaseEntry(
+                    date=event_date.strftime("%Y-%m-%d"),
+                    data_type=DataType.IPO.value,
+                    ticker=ticker,
+                    data={
+                        "event_type": "ipo",
+                        "status": deal_status,
+                        "company": company,
+                        "exchange": exchange,
+                        "shares": str(shares) if shares else "",
+                        "price_range": str(price_range) if price_range else "",
+                        "market_cap": market_cap,
+                        "offer_amount": offer_amount
+                    },
+                    metadata={
+                        "source": "calendar_scraper",
+                        "scraper": "nasdaq_ipo"
+                    }
+                )
+                self.db_adapter.db.save(entry, expiry_days=90)
+                # print(f"✅ Saved {ticker} IPO event to database")
+            except Exception as e:
+                print(f"⚠️ Failed to save {ticker} IPO to database: {e}")
+            
+            return event
+            
+        except Exception as e:
+            print(f"Error parsing IPO row: {e}")
+            return None
+    
+    # ==================== STOCK SPLIT EVENTS ====================
+    
+    def get_stock_split_events(self, date_str: str = None) -> list:
+        """
+        Get stock split calendar data from NASDAQ API
+        
+        Args:
+            date_str: Date in format YYYY-MM-DD (optional)
+        
+        Returns:
+            List of StockSplitEvent objects
+        """
+        try:
+            url = self.base_splits_url
+            if date_str:
+                url = f"{url}?date={date_str}"
+            
+            response = requests.get(url, headers=self.headers)
+            response.raise_for_status()
+            
+            data = response.json()
+            
+            if not data or 'data' not in data or 'rows' not in data['data']:
+                print("Invalid response format from NASDAQ Stock Split API")
+                return []
+            
+            events = []
+            for row in data['data']['rows']:
+                event = self._parse_stock_split_row(row)
+                if event:
+                    events.append(event)
+            
+            print(f"Found {len(events)} stock split events from NASDAQ")
+            return events
+            
+        except requests.RequestException as e:
+            print(f"Error fetching stock split data from NASDAQ API: {e}")
+            return []
+        except Exception as e:
+            print(f"Unexpected error in get_stock_split_events: {e}")
+            return []
+    
+    def _parse_stock_split_row(self, row):
+        """Parse stock split row data"""
+        try:
+            # API returns: symbol, name, ratio, executionDate
+            company = row.get('name', '')
+            ticker = row.get('symbol', '')
+            ratio = row.get('ratio', '')
+            
+            if not ticker or not ratio:
+                return None
+            
+            # Parse execution date (effective date)
+            ex_date_str = row.get('executionDate', '')
+            if ex_date_str:
+                try:
+                    ex_date = datetime.strptime(ex_date_str, '%m/%d/%Y').date()
+                except:
+                    ex_date = datetime.now().date()
+            else:
+                ex_date = datetime.now().date()
+            
+            event = StockSplitEvent(
+                date=ex_date,
+                company=company,
+                ticker=ticker,
+                ratio=ratio,
+                option_symbol="",
+                announcement_date=None,
+                ex_date=ex_date
+            )
+            
+            # Save to database
+            try:
+                from db.local_database import DatabaseEntry, DataType
+                entry = DatabaseEntry(
+                    date=ex_date.strftime("%Y-%m-%d"),
+                    data_type=DataType.STOCK_SPLIT.value,
+                    ticker=ticker,
+                    data={
+                        "event_type": "stock_split",
+                        "company": company,
+                        "ratio": ratio,
+                        "execution_date": ex_date.strftime("%Y-%m-%d")
+                    },
+                    metadata={
+                        "source": "calendar_scraper",
+                        "scraper": "nasdaq_splits"
+                    }
+                )
+                self.db_adapter.db.save(entry, expiry_days=90)
+                # print(f"✅ Saved {ticker} stock split event to database")
+            except Exception as e:
+                print(f"⚠️ Failed to save {ticker} stock split to database: {e}")
+            
+            return event
+            
+        except Exception as e:
+            print(f"Error parsing stock split row: {e}")
+            return None
+    
+    # ==================== ECONOMIC EVENTS ====================
+    
+    def get_economic_events(self, date_str: str = None, country_list:list[str]=['UNITED_STATES','United States']) -> list:
+        """
+        Get economic events calendar data from NASDAQ API
+        
+        Args:
+            date_str: Date in format YYYY-MM-DD (e.g., "2025-11-06")
+        
+        Returns:
+            List of EconomicEvent objects
+        """
+        if not date_str:
+            date_str = datetime.now().strftime("%Y-%m-%d")
+        
+        try:
+            url = f"{self.base_economic_url}?date={date_str}"
+            response = requests.get(url, headers=self.headers)
+            response.raise_for_status()
+            
+            data = response.json()
+            
+            if not data or 'data' not in data or 'rows' not in data['data']:
+                print("Invalid response format from NASDAQ Economic Events API")
+                return []
+            
+            events = []
+            for row in data['data']['rows']:
+                event = self._parse_economic_event_row(row, date_str, country_list)
+                if event:
+                    events.append(event)
+            
+            print(f"Found {len(events)} economic events from NASDAQ")
+            return events
+            
+        except requests.RequestException as e:
+            print(f"Error fetching economic events data from NASDAQ API: {e}")
+            return []
+        except Exception as e:
+            print(f"Unexpected error in get_economic_events: {e}")
+            return []
+    
+    def _parse_economic_event_row(self, row, date_str, country_list) :
+        """Parse economic event row data"""
+        try:
+            event_name = row.get('eventName', '')
+            country = row.get('country', 'US')
+            
+            if not event_name:
+                return None
+            if event_name.lower() in ['n/a', 'not available']:
+                return None
+            if country not in country_list:
+                return None
+            # Parse event date
+            try:
+                event_date = datetime.strptime(date_str, '%Y-%m-%d').date()
+            except:
+                event_date = datetime.now().date()
+            
+            time = row.get('time', '')
+            actual = row.get('actual', '')
+            consensus = row.get('consensus', '')
+            previous = row.get('previous', '')
+            
+            event = EconomicEvent(
+                date=event_date,
+                time=time,
+                country=country,
+                importance=row.get('importance', 0),
+                event=event_name,
+                actual=actual,
+                forecast=consensus,
+                previous=previous
+            )
+            
+            # Save to database
+            try:
+                self.db_adapter.save_economic_event(
+                    date=event_date.strftime("%Y-%m-%d"),
+                    event_data={
+                        "country": country,
+                        "time": time,
+                        "event": event_name,
+                        "actual": actual,
+                        "forecast": consensus,
+                        "previous": previous
+                    }
+                )
+                # print(f"✅ Saved {event_name} economic event to database")
+            except Exception as e:
+                print(f"⚠️ Failed to save {event_name} economic event to database: {e}")
+            
+            return event
+            
+        except Exception as e:
+            print(f"Error parsing economic event row: {e}")
+            return None
+    
+    # ==================== DIVIDEND EVENTS ====================
+    
+    def get_dividend_events(self, date_str: str = None) -> list:
+        """
+        Get dividend calendar data from NASDAQ API
+        
+        Args:
+            date_str: Date in format YYYY-MM-DD (e.g., "2025-11-06")
+        
+        Returns:
+            List of DividendEvent objects
+        """
+        if not date_str:
+            date_str = datetime.now().strftime("%Y-%m-%d")
+        
+        try:
+            url = f"{self.base_dividends_url}?date={date_str}"
+            response = requests.get(url, headers=self.headers)
+            response.raise_for_status()
+            
+            data = response.json()
+            
+            if not data or 'data' not in data or 'calendar' not in data['data']:
+                print("Invalid response format from NASDAQ Dividends API")
+                return []
+            
+            calendar_data = data['data']['calendar']
+            if 'rows' not in calendar_data:
+                print("No rows in calendar data")
+                return []
+            
+            events = []
+            for row in calendar_data['rows']:
+                event = self._parse_dividend_row(row, date_str)
+                if event:
+                    events.append(event)
+            
+            print(f"Found {len(events)} dividend events from NASDAQ")
+            return events
+            
+        except requests.RequestException as e:
+            print(f"Error fetching dividend data from NASDAQ API: {e}")
+            return []
+        except Exception as e:
+            print(f"Unexpected error in get_dividend_events: {e}")
+            return []
+    
+    def _parse_dividend_row(self, row, date_str):
+        """Parse dividend row data"""
+        try:
+            # API returns: companyName, symbol, dividend_Ex_Date, payment_Date, record_Date, 
+            # dividend_Rate, indicated_Annual_Dividend, announcement_Date
+            company = row.get('companyName', '')
+            ticker = row.get('symbol', '')
+            dividend_rate = row.get('dividend_Rate', 0)
+            
+            if not company or not ticker:
+                return None
+            
+            # Use ex-dividend date as the event date
+            ex_date_str = row.get('dividend_Ex_Date', '')
+            if ex_date_str:
+                try:
+                    event_date = datetime.strptime(ex_date_str, '%m/%d/%Y').date()
+                except:
+                    event_date = datetime.now().date()
+            else:
+                event_date = datetime.now().date()
+            
+            annual_dividend = row.get('indicated_Annual_Dividend', '')
+            ex_date = row.get('dividend_Ex_Date', '')
+            record_date = row.get('record_Date', '')
+            payment_date = row.get('payment_Date', '')
+            announcement_date = row.get('announcement_Date', '')
+            
+            event = DividendEvent(
+                date=event_date,
+                company=company,
+                ticker=ticker,
+                dividend_rate=str(dividend_rate),
+                annual_dividend=str(annual_dividend) if annual_dividend else "",
+                ex_date=ex_date,
+                record_date=record_date,
+                payment_date=payment_date,
+                announcement_date=announcement_date
+            )
+            
+            # Save to database
+            try:
+                from db.local_database import DatabaseEntry, DataType
+                entry = DatabaseEntry(
+                    date=event_date.strftime("%Y-%m-%d"),
+                    data_type=DataType.DIVIDENDS.value,
+                    ticker=ticker,
+                    data={
+                        "event_type": "dividend",
+                        "company": company,
+                        "dividend_rate": str(dividend_rate),
+                        "annual_dividend": str(annual_dividend) if annual_dividend else "",
+                        "ex_date": ex_date,
+                        "record_date": record_date,
+                        "payment_date": payment_date,
+                        "announcement_date": announcement_date
+                    },
+                    metadata={
+                        "source": "calendar_scraper",
+                        "scraper": "nasdaq_dividends"
+                    }
+                )
+                self.db_adapter.db.save(entry, expiry_days=90)
+                # print(f"✅ Saved {ticker} dividend event to database")
+            except Exception as e:
+                print(f"⚠️ Failed to save {ticker} dividend to database: {e}")
+            
+            return event
+            
+        except Exception as e:
+            print(f"Error parsing dividend row: {e}")
+            return None
+        

src/calendar_scraper/get_calendar_events.py

@@ -0,0 +1,152 @@
+from datetime import date
+import sys
+from pathlib import Path
+
+# Add src to path if needed
+sys.path.append(str(Path(__file__).parent.parent))
+
+from calendar_scraper.adapters.nasdaq import NasdaqAdapter
+from db.local_database import LocalDatabase, DatabaseEntry, DataType
+
+def get_events(_date:date):
+    adapter = NasdaqAdapter()
+    earnings = adapter.get_earning_events()
+    ipos = adapter.get_ipo_events(_date.strftime("%Y-%m"))
+    splits = adapter.get_stock_split_events(_date.strftime("%Y-%m-%d"))
+    economic = adapter.get_economic_events(_date.strftime("%Y-%m-%d"))
+    dividends = adapter.get_dividend_events(_date.strftime("%Y-%m-%d"))
+    return {
+        "earnings": earnings,
+        "ipos": ipos,
+        "splits": splits,
+        "economic": economic,
+        "dividends": dividends
+    }
+
+def _map_event_to_entry(event, event_type: str, _date: date) -> DatabaseEntry:
+    """Map a calendar event object to a DatabaseEntry"""
+    
+    if event_type == "earnings":
+        # EarningsEvent(date, time, company, ticker, eps, revenue, market_cap)
+        return DatabaseEntry(
+            date=_date.isoformat(),
+            data_type=DataType.EARNINGS.value,
+            ticker=event.ticker,
+            data={
+                'event_type': 'earnings',
+                'time': event.time,
+                'company': event.company,
+                'eps': event.eps,
+                'revenue': event.revenue,
+                'market_cap': event.market_cap,
+                'execution_date': event.date # Store the actual event date
+            },
+            metadata={'source': 'nasdaq_calendar'}
+        )
+    elif event_type == "ipos":
+        # IPOEvent(date, company, ticker, exchange, shares, price_range, market_cap, expected_to_trade)
+        return DatabaseEntry(
+            date=_date.isoformat(),
+            data_type=DataType.IPO.value,
+            ticker=event.ticker,
+            data={
+                'event_type': 'ipo',
+                'company': event.company,
+                'exchange': event.exchange,
+                'shares': event.shares,
+                'price_range': event.price_range,
+                'market_cap': event.market_cap,
+                'expected_to_trade': event.expected_to_trade,
+                'execution_date': str(event.date)
+            },
+            metadata={'source': 'nasdaq_calendar'}
+        )
+    elif event_type == "splits":
+        # StockSplitEvent(date, company, ticker, ratio, ...)
+        return DatabaseEntry(
+            date=_date.isoformat(),
+            data_type=DataType.STOCK_SPLIT.value,
+            ticker=event.ticker,
+            data={
+                'event_type': 'stock_split',
+                'company': event.company,
+                'ratio': event.ratio,
+                'execution_date': str(event.date)
+            },
+            metadata={'source': 'nasdaq_calendar'}
+        )
+    elif event_type == "economic":
+        # EconomicEvent(date, time, country, importance, event, actual, forecast, previous)
+        # Use country as ticker for economic events
+        ticker = event.country.upper().replace(' ', '_') if event.country else "GLOBAL"
+        return DatabaseEntry(
+            date=_date.isoformat(),
+            data_type=DataType.ECONOMIC_EVENTS.value,
+            ticker=ticker,
+            data={
+                'event_type': 'economic',
+                'time': event.time,
+                'importance': event.importance,
+                'event': event.event,
+                'actual': event.actual,
+                'forecast': event.forecast,
+                'previous': event.previous,
+                'execution_date': str(event.date)
+            },
+            metadata={'source': 'nasdaq_calendar'}
+        )
+    elif event_type == "dividends":
+        # DividendEvent(date, company, ticker, dividend_rate, ...)
+        return DatabaseEntry(
+            date=_date.isoformat(),
+            data_type=DataType.DIVIDENDS.value,
+            ticker=event.ticker,
+            data={
+                'event_type': 'dividend',
+                'company': event.company,
+                'dividend_rate': event.dividend_rate,
+                'execution_date': str(event.date)
+            },
+            metadata={'source': 'nasdaq_calendar'}
+        )
+    return None
+
+def save_events_to_db(events_dict: dict, _date: date):
+    """Save all fetched events to the database"""
+    db = LocalDatabase()
+    all_entries = []
+    
+    print(f"Processing events for database saving...")
+    
+    for event_type, events in events_dict.items():
+        if not events:
+            continue
+            
+        print(f"  - Processing {len(events)} {event_type} events...")
+        for event in events:
+            try:
+                entry = _map_event_to_entry(event, event_type, _date)
+                if entry:
+                    all_entries.append(entry)
+            except Exception as e:
+                print(f"Error mapping {event_type} event: {e}")
+    
+    if all_entries:
+        print(f"Saving {len(all_entries)} entries to database...")
+        saved_count = db.save_batch(all_entries, expiry_days=30)
+        print(f"Successfully saved {saved_count} events to database.")
+    else:
+        print("No events to save.")
+
+if __name__ == "__main__":
+    today = date.today()
+    print(f"Fetching events for {today}...")
+    events = get_events(today)
+    
+    print(f"Earnings Events: {len(events['earnings'])}")
+    print(f"IPO Events: {len(events['ipos'])}")
+    print(f"Stock Split Events: {len(events['splits'])}")
+    print(f"Economic Events: {len(events['economic'])}")
+    print(f"Dividend Events: {len(events['dividends'])}")
+    
+    save_events_to_db(events, today)

src/calendar_scraper/models/__init__.py

@@ -0,0 +1,3 @@
+# FILE: /calendar-scraper/calendar_scraper/models/__init__.py
+
+# This file is intentionally left blank.

src/calendar_scraper/models/dividend_calendar.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+from datetime import date
+from typing import Optional
+
+
+@dataclass
+class DividendEvent:
+    """Represents a dividend event"""
+    date: date
+    company: str
+    ticker: str
+    dividend_rate: str
+    annual_dividend: Optional[str] = ""
+    ex_date: Optional[str] = ""
+    record_date: Optional[str] = ""
+    payment_date: Optional[str] = ""
+    announcement_date: Optional[str] = ""

src/calendar_scraper/models/earnings_calendar.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+@dataclass
+class EarningsEvent:
+    def __init__(self, date,time,company, ticker, eps, revenue, market_cap):
+        self.date = date
+        self.time = time
+        self.company = company
+        self.ticker = ticker
+        self.eps = eps
+        self.revenue = revenue
+        self.market_cap = market_cap
+    
+    def __repr__(self):
+       return self.__print__()
+        
+    def __print__(self):
+        return f"EarningsEvent(date={self.date}, time={self.time}, company={self.company}, ticker={self.ticker}, eps={self.eps}, revenue={self.revenue}, market_cap={self.market_cap})"

src/calendar_scraper/models/economic_calendar.py

@@ -0,0 +1,20 @@
+
+from dataclasses import dataclass
+
+@dataclass
+class EconomicEvent:
+    def __init__(self, date,time,country,importance, event, actual, forecast, previous):
+        self.date = date
+        self.time = time
+        self.country = country
+        self.importance = importance
+        self.event = event
+        self.actual = actual
+        self.forecast = forecast
+        self.previous = previous
+    
+    def __repr__(self):
+       return self.__print__()
+        
+    def __print__(self):
+        return f"EconomicEvent(date={self.date}, time={self.time}, currency={self.country}, importance={self.importance}, event={self.event}, actual={self.actual}, forecast={self.forecast}, previous={self.previous})"    

src/calendar_scraper/models/ipo_calendar.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from datetime import date
+from typing import Optional
+
+
+@dataclass
+class IPOEvent:
+    """Represents an IPO event"""
+    date: date
+    company: str
+    ticker: str
+    exchange: str
+    shares: Optional[str] = ""
+    price_range: Optional[str] = ""
+    market_cap: Optional[float] = None
+    expected_to_trade: Optional[str] = ""

src/calendar_scraper/models/stock_split_calendar.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+from datetime import date as date_type
+from typing import Optional
+
+
+@dataclass
+class StockSplitEvent:
+    """Represents a stock split event"""
+    date: date_type
+    company: str
+    ticker: str
+    ratio: str
+    option_symbol: Optional[str] = ""
+    announcement_date: Optional[date_type] = None
+    ex_date: Optional[date_type] = None
+    record_date: Optional[date_type] = None
+    payable_date: Optional[date_type] = None

src/db/__init__.py

@@ -0,0 +1,45 @@
+"""
+Local Database System for Stock Alchemist
+
+A comprehensive database solution for storing and retrieving
+stock market data across multiple modules with JSON file storage
+and SQLite indexing.
+"""
+
+from .local_database import (
+    LocalDatabase,
+    DatabaseEntry,
+    DataType,
+    get_database
+)
+
+from .adapters import (
+    CalendarAdapter,
+    FundamentalAdapter,
+    NewsAdapter,
+    TechnicalAnalysisAdapter,
+    get_calendar_adapter,
+    get_fundamental_adapter,
+    get_news_adapter,
+    get_technical_adapter
+)
+
+__all__ = [
+    # Core database
+    'LocalDatabase',
+    'DatabaseEntry',
+    'DataType',
+    'get_database',
+    
+    # Adapters
+    'CalendarAdapter',
+    'FundamentalAdapter',
+    'NewsAdapter',
+    'TechnicalAnalysisAdapter',
+    'get_calendar_adapter',
+    'get_fundamental_adapter',
+    'get_news_adapter',
+    'get_technical_adapter',
+]
+
+__version__ = '1.0.0'

src/db/adapters.py

@@ -0,0 +1,622 @@
+"""
+Module-specific adapters for integrating the local database
+with calendar_scraper, fundamental_analysis, and news_scraper
+"""
+
+from datetime import datetime
+from typing import Dict, Any, List, Optional
+from pathlib import Path
+import sys
+
+# Add src to path if needed
+sys.path.append(str(Path(__file__).parent.parent))
+
+from db.local_database import LocalDatabase, DatabaseEntry, DataType
+
+
+class CalendarAdapter:
+    """
+    Adapter for calendar_scraper module
+    Handles earnings_events and economic_events
+    """
+    
+    def __init__(self, db: Optional[LocalDatabase] = None):
+        self.db = db or LocalDatabase()
+    
+### EARINGS ###
+
+    def save_earnings_event(self, date: str, ticker: str, event_data: Dict[str, Any],
+                           expiry_days: int = 30) -> bool:
+        """
+        Save earnings event to database
+        
+        Args:
+            date: Event date (YYYY-MM-DD)
+            ticker: Stock ticker
+            event_data: Event details (company, time, eps, revenue, market_cap)
+            expiry_days: Data expiry in days
+            
+        Returns:
+            True if successful
+        """
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.EARNINGS.value,
+            ticker=ticker.upper(),
+            data={
+                'event_type': 'earnings',
+                **event_data
+            },
+            metadata={
+                'source': 'calendar_scraper',
+                'scraper': 'earnings'
+            }
+        )
+        
+        return self.db.save(entry, expiry_days=expiry_days)
+
+    
+    def get_earnings_events(self, ticker: str, date_from: str = None,
+                           date_to: str = None) -> List[DatabaseEntry]:
+        """Get earnings events for ticker"""
+        entries = self.db.query(
+            ticker=ticker.upper(),
+            data_type=DataType.EARNINGS.value,
+            date_from=date_from,
+            date_to=date_to
+        )
+        
+        # Filter for earnings events only
+        return [e for e in entries if e.data.get('event_type') == 'earnings']
+    
+   ### ECONOMIC EVENTS ###
+ 
+    def save_economic_event(self, date: str, event_data: Dict[str, Any],
+                           expiry_days: int = 7) -> bool:
+        """
+        Save economic event to database
+        
+        Args:
+            date: Event date (YYYY-MM-DD)
+            event_data: Event details (country, importance, event, actual, forecast, previous)
+            expiry_days: Data expiry in days
+            
+        Returns:
+            True if successful
+        """
+        # Use country as ticker for economic events
+        ticker = event_data.get('country', 'GLOBAL').upper().replace(' ', '_')
+        
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.ECONOMIC_EVENTS.value,
+            ticker=ticker,
+            data={
+                'event_type': 'economic',
+                **event_data
+            },
+            metadata={
+                'source': 'calendar_scraper',
+                'scraper': 'economic'
+            }
+        )
+        
+        return self.db.save(entry, expiry_days=expiry_days)
+
+    
+    def get_economic_events(self, country: str = None, date_from: str = None,
+                           date_to: str = None) -> List[DatabaseEntry]:
+        """Get economic events"""
+        ticker = country.upper().replace(' ', '_') if country else None
+        
+        entries = self.db.query(
+            ticker=ticker,
+            data_type=DataType.ECONOMIC_EVENTS.value,
+            date_from=date_from,
+            date_to=date_to
+        )
+        
+        # Filter for economic events only
+        return [e for e in entries if e.data.get('event_type') == 'economic']
+
+
+    ### DIVIDENDS ###
+    def get_dividends_events(self, ticker: str, date_from: str = None,
+                           date_to: str = None) -> List[DatabaseEntry]:
+        """Get dividend events for ticker"""
+        entries = self.db.query(
+            ticker=ticker.upper(),
+            data_type=DataType.DIVIDENDS.value,
+            date_from=date_from,
+            date_to=date_to
+        )
+        
+        # Filter for earnings events only
+        return [e for e in entries if e.data.get('event_type') == 'dividend']
+
+    ### IPOs ###
+    def get_ipo_events(self, ticker: str, date_from: str = None,
+                            date_to: str = None) -> List[DatabaseEntry]:
+          """Get ipo events for ticker"""
+          entries = self.db.query(
+                ticker=ticker.upper(),
+                data_type=DataType.IPO.value,
+                date_from=date_from,
+                date_to=date_to
+          )
+          
+          # Filter for earnings events only
+          return [e for e in entries if e.data.get('event_type') == 'ipo']
+    
+    ## STOCK SPLITS ###
+    def get_stock_split_events(self, ticker: str, date_from: str = None,
+                            date_to: str = None) -> List[DatabaseEntry]:
+          """Get stock split events for ticker"""
+          entries = self.db.query(
+                ticker=ticker.upper(),
+                data_type=DataType.STOCK_SPLIT.value,
+                date_from=date_from,
+                date_to=date_to
+          )
+          
+          # Filter for earnings events only
+          return [e for e in entries if e.data.get('event_type') == 'stock_split']
+      
+
+class FundamentalAdapter:
+    """
+    Adapter for fundamental_analysis module
+    Handles financial metrics and investment decisions
+    """
+    
+    def __init__(self, db: Optional[LocalDatabase] = None):
+        self.db = db or LocalDatabase()
+    
+    def save_financial_metrics(self, date: str, ticker: str, metrics: Dict[str, Any],
+                              expiry_days: int = 1) -> bool:
+        """
+        Save financial metrics to database
+        
+        Args:
+            date: Analysis date (YYYY-MM-DD)
+            ticker: Stock ticker
+            metrics: Financial metrics from calculator.py
+            expiry_days: Data expiry in days (financial data changes daily)
+            
+        Returns:
+            True if successful
+        """
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.FUNDAMENTAL.value,
+            ticker=ticker.upper(),
+            data={
+                'analysis_type': 'metrics',
+                'metrics': metrics
+            },
+            metadata={
+                'source': 'fundamental_analysis',
+                'module': 'calculator'
+            }
+        )
+        
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def save_investment_decision(self, date: str, ticker: str, decision: Dict[str, Any],
+                                expiry_days: int = 1) -> bool:
+        """
+        Save investment decision to database
+        
+        Args:
+            date: Decision date (YYYY-MM-DD)
+            ticker: Stock ticker
+            decision: Investment decision from decision_maker.py
+            expiry_days: Data expiry in days
+            
+        Returns:
+            True if successful
+        """
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.FUNDAMENTAL.value,
+            ticker=ticker.upper(),
+            data={
+                'analysis_type': 'decision',
+                'recommendation': decision.get('recommendation'),
+                'score': decision.get('final_score'),
+                'confidence': decision.get('confidence'),
+                'reasoning': decision.get('reasoning'),
+                'key_metrics': decision.get('key_metrics'),
+                'category_scores': decision.get('category_scores')
+            },
+            metadata={
+                'source': 'fundamental_analysis',
+                'module': 'decision_maker'
+            }
+        )
+        
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def save_sector_analysis(self, date: str, sector: str, analysis: Dict[str, Any],
+                           expiry_days: int = 7) -> bool:
+        """
+        Save sector analysis to database
+        
+        Args:
+            date: Analysis date (YYYY-MM-DD)
+            sector: Sector name (e.g., "Technology")
+            analysis: Sector comparison data
+            expiry_days: Data expiry in days
+            
+        Returns:
+            True if successful
+        """
+        # Use sector name as ticker
+        ticker = f"SECTOR_{sector.upper().replace(' ', '_')}"
+        
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.FUNDAMENTAL.value,
+            ticker=ticker,
+            data={
+                'analysis_type': 'sector',
+                'sector': sector,
+                **analysis
+            },
+            metadata={
+                'source': 'fundamental_analysis',
+                'module': 'sector_analyzer'
+            }
+        )
+        
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def get_financial_metrics(self, ticker: str, date: str = None) -> Optional[DatabaseEntry]:
+        """Get latest financial metrics for ticker"""
+        if date:
+            return self.db.get(date, DataType.FUNDAMENTAL.value, ticker.upper())
+        
+        # Get most recent
+        entries = self.db.query(
+            ticker=ticker.upper(),
+            data_type=DataType.FUNDAMENTAL.value,
+            limit=1
+        )
+        
+        return entries[0] if entries else None
+    
+    def get_investment_decisions(self, ticker: str, date_from: str = None,
+                                date_to: str = None) -> List[DatabaseEntry]:
+        """Get investment decision history for ticker"""
+        entries = self.db.query(
+            ticker=ticker.upper(),
+            data_type=DataType.FUNDAMENTAL.value,
+            date_from=date_from,
+            date_to=date_to
+        )
+        
+        # Filter for decisions only
+        return [e for e in entries if e.data.get('analysis_type') == 'decision']
+
+
+class NewsAdapter:
+    """
+    Adapter for news_scraper module
+    Handles news articles and sentiment analysis
+    """
+    
+    def __init__(self, db: Optional[LocalDatabase] = None):
+        self.db = db or LocalDatabase()
+    
+    def save_news_article(self, date: str, ticker: str, article: Dict[str, Any],
+                         expiry_days: int = 30) -> bool:
+        """
+        Save news article to database
+        
+        Args:
+            date: Article date (YYYY-MM-DD)
+            ticker: Stock ticker
+            article: Article data (title, content, source, url, etc.)
+            expiry_days: Data expiry in days
+            
+        Returns:
+            True if successful
+        """
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.NEWS.value,
+            ticker=ticker.upper(),
+            data={
+                'content_type': 'article',
+                **article
+            },
+            metadata={
+                'source': 'news_scraper',
+                'scraper': article.get('source', 'unknown')
+            }
+        )
+        
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def save_sentiment_analysis(self, date: str, ticker: str, sentiment: Dict[str, Any],
+                               expiry_days: int = 7) -> bool:
+        """
+        Save sentiment analysis to database
+        
+        Args:
+            date: Analysis date (YYYY-MM-DD)
+            ticker: Stock ticker
+            sentiment: Sentiment analysis results
+            expiry_days: Data expiry in days
+            
+        Returns:
+            True if successful
+        """
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.NEWS.value,
+            ticker=ticker.upper(),
+            data={
+                'content_type': 'sentiment',
+                **sentiment
+            },
+            metadata={
+                'source': 'news_scraper',
+                'module': 'sentiment_analysis'
+            }
+        )
+        
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def get_news_articles(self, ticker: str, date_from: str = None,
+                         date_to: str = None) -> List[DatabaseEntry]:
+        """Get news articles for ticker"""
+        entries = self.db.query(
+            ticker=ticker.upper(),
+            data_type=DataType.NEWS.value,
+            date_from=date_from,
+            date_to=date_to
+        )
+        
+        # Filter for articles only
+        return [e for e in entries if e.data.get('content_type') == 'article']
+    
+    def get_sentiment_history(self, ticker: str, date_from: str = None,
+                             date_to: str = None) -> List[DatabaseEntry]:
+        """Get sentiment analysis history for ticker"""
+        entries = self.db.query(
+            ticker=ticker.upper(),
+            data_type=DataType.NEWS.value,
+            date_from=date_from,
+            date_to=date_to
+        )
+        
+        # Filter for sentiment only
+        return [e for e in entries if e.data.get('content_type') == 'sentiment']
+
+
+class TechnicalAnalysisAdapter:
+    """
+    Adapter for technical analysis data
+    Can be used for price data, indicators, signals
+    """
+    
+    def __init__(self, db: Optional[LocalDatabase] = None):
+        self.db = db or LocalDatabase()
+    
+    def save_technical_indicators(self, date: str, ticker: str, indicators: Dict[str, Any],
+                                 expiry_days: int = 1) -> bool:
+        """
+        Save technical indicators to database
+        
+        Args:
+            date: Analysis date (YYYY-MM-DD)
+            ticker: Stock ticker
+            indicators: Technical indicators (RSI, MACD, etc.)
+            expiry_days: Data expiry in days
+            
+        Returns:
+            True if successful
+        """
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.TECHNICAL_ANALYSIS.value,
+            ticker=ticker.upper(),
+            data={
+                'analysis_type': 'indicators',
+                **indicators
+            },
+            metadata={
+                'source': 'technical_analysis'
+            }
+        )
+        
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def save_trading_signal(self, date: str, ticker: str, signal: Dict[str, Any],
+                          expiry_days: int = 1) -> bool:
+        """
+        Save trading signal to database
+        
+        Args:
+            date: Signal date (YYYY-MM-DD)
+            ticker: Stock ticker
+            signal: Trading signal data
+            expiry_days: Data expiry in days
+            
+        Returns:
+            True if successful
+        """
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.TECHNICAL_ANALYSIS.value,
+            ticker=ticker.upper(),
+            data={
+                'analysis_type': 'signal',
+                **signal
+            },
+            metadata={
+                'source': 'technical_analysis'
+            }
+        )
+        
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def get_technical_indicators(self, ticker: str, date_from: str = None,
+                                date_to: str = None) -> List[DatabaseEntry]:
+        """Get technical indicators for ticker"""
+        entries = self.db.query(
+            ticker=ticker.upper(),
+            data_type=DataType.TECHNICAL_ANALYSIS.value,
+            date_from=date_from,
+            date_to=date_to
+        )
+        
+        # Filter for indicators only
+        return [e for e in entries if e.data.get('analysis_type') == 'indicators']
+    
+    def get_trading_signals(self, ticker: str, date_from: str = None,
+                           date_to: str = None) -> List[DatabaseEntry]:
+        """Get trading signals for ticker"""
+        entries = self.db.query(
+            ticker=ticker.upper(),
+            data_type=DataType.TECHNICAL_ANALYSIS.value,
+            date_from=date_from,
+            date_to=date_to
+        )
+        
+        # Filter for signals only
+        return [e for e in entries if e.data.get('analysis_type') == 'signal']
+
+
+# Additional methods for CalendarAdapter
+def _add_calendar_methods():
+    """Add missing methods to CalendarAdapter"""
+    
+    def save_ipo_event(self, date: str, ticker: str, event_data: Dict[str, Any],
+                      expiry_days: int = 90) -> bool:
+        """Save IPO event to database"""
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.IPO.value,
+            ticker=ticker.upper(),
+            data={
+                'event_type': 'ipo',
+                **event_data
+            },
+            metadata={
+                'source': 'calendar_scraper',
+                'scraper': 'ipo'
+            }
+        )
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def save_stock_split_event(self, date: str, ticker: str, event_data: Dict[str, Any],
+                               expiry_days: int = 90) -> bool:
+        """Save stock split event to database"""
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.STOCK_SPLIT.value,
+            ticker=ticker.upper(),
+            data={
+                'event_type': 'stock_split',
+                **event_data
+            },
+            metadata={
+                'source': 'calendar_scraper',
+                'scraper': 'stock_split'
+            }
+        )
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def save_dividend_event(self, date: str, ticker: str, event_data: Dict[str, Any],
+                           expiry_days: int = 90) -> bool:
+        """Save dividend event to database"""
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.DIVIDENDS.value,
+            ticker=ticker.upper(),
+            data={
+                'event_type': 'dividend',
+                **event_data
+            },
+            metadata={
+                'source': 'calendar_scraper',
+                'scraper': 'dividend'
+            }
+        )
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    # Add methods to CalendarAdapter class
+    CalendarAdapter.save_ipo_event = save_ipo_event
+    CalendarAdapter.save_stock_split_event = save_stock_split_event
+    CalendarAdapter.save_dividend_event = save_dividend_event
+
+_add_calendar_methods()
+
+
+# Additional method for FundamentalAdapter
+def _add_fundamental_methods():
+    """Add missing methods to FundamentalAdapter"""
+    
+    def save_fundamental_analysis(self, date: str, ticker: str, analysis_data: Dict[str, Any],
+                                  expiry_days: int = 30) -> bool:
+        """
+        Save complete fundamental analysis to database
+        Includes last_processed_datetime for tracking
+        """
+        entry = DatabaseEntry(
+            date=date,
+            data_type=DataType.FUNDAMENTAL.value,
+            ticker=ticker.upper(),
+            data={
+                'analysis_type': 'complete',
+                'last_processed_datetime': datetime.now().isoformat(),
+                **analysis_data
+            },
+            metadata={
+                'source': 'fundamental_analysis',
+                'module': 'complete_analysis'
+            }
+        )
+        return self.db.save(entry, expiry_days=expiry_days)
+    
+    def get_fundamental_analysis(self, ticker: str, date_from: str = None,
+                                date_to: str = None) -> List[DatabaseEntry]:
+        """Get fundamental analysis for ticker"""
+        entries = self.db.query(
+            ticker=ticker.upper(),
+            data_type=DataType.FUNDAMENTAL.value,
+            date_from=date_from,
+            date_to=date_to
+        )
+        
+        # Filter for complete analysis
+        return [e for e in entries if e.data.get('analysis_type') == 'complete']
+    
+    # Add methods to FundamentalAdapter class
+    FundamentalAdapter.save_fundamental_analysis = save_fundamental_analysis
+    FundamentalAdapter.get_fundamental_analysis = get_fundamental_analysis
+
+_add_fundamental_methods()
+
+
+# Convenience functions for quick access
+def get_calendar_adapter(db: Optional[LocalDatabase] = None) -> CalendarAdapter:
+    """Get calendar adapter instance"""
+    return CalendarAdapter(db)
+
+
+def get_fundamental_adapter(db: Optional[LocalDatabase] = None) -> FundamentalAdapter:
+    """Get fundamental analysis adapter instance"""
+    return FundamentalAdapter(db)
+
+
+def get_news_adapter(db: Optional[LocalDatabase] = None) -> NewsAdapter:
+    """Get news adapter instance"""
+    return NewsAdapter(db)
+
+
+def get_technical_adapter(db: Optional[LocalDatabase] = None) -> TechnicalAnalysisAdapter:
+    """Get technical analysis adapter instance"""
+    return TechnicalAnalysisAdapter(db)

src/db/db_util.py

@@ -0,0 +1,352 @@
+#!/usr/bin/env python3
+"""
+Database management utility for Stock Alchemist
+Similar to cache_util.py but for the local database system
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from datetime import datetime, timedelta
+import json
+
+# Add src to path
+sys.path.append(str(Path(__file__).parent.parent))
+
+from db.local_database import LocalDatabase, DataType
+
+
+def show_stats(db_dir: str):
+    """Show database statistics"""
+    db = LocalDatabase(db_dir=db_dir)
+    stats = db.get_stats()
+    
+    print("\n" + "="*60)
+    print("DATABASE STATISTICS")
+    print("="*60)
+    
+    print(f"\n📊 Overview:")
+    print(f"  Total Entries: {stats.get('total_entries', 0):,}")
+    print(f"  Total Size: {stats.get('total_size_mb', 0)} MB ({stats.get('total_size_bytes', 0):,} bytes)")
+    print(f"  Compression: {stats.get('compression', 'disabled')}")
+    print(f"  Expired Entries: {stats.get('expired_entries', 0)}")
+    
+    date_range = stats.get('date_range')
+    if date_range:
+        print(f"  Date Range: {date_range['from']} to {date_range['to']}")
+    
+    by_type = stats.get('by_type', {})
+    if by_type:
+        print(f"\n📁 By Data Type:")
+        for data_type, count in sorted(by_type.items()):
+            print(f"  {data_type:.<30} {count:>6,}")
+    
+    top_tickers = stats.get('top_tickers', {})
+    if top_tickers:
+        print(f"\n🏢 Top 10 Tickers:")
+        for ticker, count in list(top_tickers.items())[:10]:
+            print(f"  {ticker:.<20} {count:>6,}")
+    
+    print("\n" + "="*60 + "\n")
+
+
+def clean_expired(db_dir: str):
+    """Clean expired entries"""
+    db = LocalDatabase(db_dir=db_dir)
+    count = db.clean_expired()
+    print(f"✓ Cleaned {count} expired entries")
+
+
+def clear_all(db_dir: str, confirm: bool = False):
+    """Clear all database entries"""
+    if not confirm:
+        response = input("⚠️  This will delete ALL data. Are you sure? (yes/no): ")
+        if response.lower() != 'yes':
+            print("❌ Cancelled")
+            return
+    
+    db = LocalDatabase(db_dir=db_dir)
+    db.clear_all()
+
+
+def clear_by_type(db_dir: str, data_type: str):
+    """Clear entries of specific type"""
+    db = LocalDatabase(db_dir=db_dir)
+    
+    # Query all entries of this type
+    entries = db.query(data_type=data_type)
+    
+    if not entries:
+        print(f"No entries found for type: {data_type}")
+        return
+    
+    print(f"Found {len(entries)} entries of type '{data_type}'")
+    response = input("Delete these entries? (yes/no): ")
+    
+    if response.lower() != 'yes':
+        print("❌ Cancelled")
+        return
+    
+    # Delete each entry
+    deleted = 0
+    for entry in entries:
+        if db.delete(entry.date, entry.data_type, entry.ticker):
+            deleted += 1
+    
+    print(f"✓ Deleted {deleted} entries")
+
+
+def clear_by_ticker(db_dir: str, ticker: str):
+    """Clear entries for specific ticker"""
+    db = LocalDatabase(db_dir=db_dir)
+    
+    # Query all entries for this ticker
+    entries = db.query(ticker=ticker)
+    
+    if not entries:
+        print(f"No entries found for ticker: {ticker}")
+        return
+    
+    print(f"Found {len(entries)} entries for ticker '{ticker}'")
+    response = input("Delete these entries? (yes/no): ")
+    
+    if response.lower() != 'yes':
+        print("❌ Cancelled")
+        return
+    
+    # Delete each entry
+    deleted = 0
+    for entry in entries:
+        if db.delete(entry.date, entry.data_type, entry.ticker):
+            deleted += 1
+    
+    print(f"✓ Deleted {deleted} entries")
+
+
+def clear_older_than(db_dir: str, days: int):
+    """Clear entries older than specified days"""
+    db = LocalDatabase(db_dir=db_dir)
+    cutoff_date = (datetime.now() - timedelta(days=days)).date().isoformat()
+    
+    # Query old entries
+    entries = db.query(date_to=cutoff_date)
+    
+    if not entries:
+        print(f"No entries older than {days} days")
+        return
+    
+    print(f"Found {len(entries)} entries older than {days} days")
+    response = input("Delete these entries? (yes/no): ")
+    
+    if response.lower() != 'yes':
+        print("❌ Cancelled")
+        return
+    
+    # Delete each entry
+    deleted = 0
+    for entry in entries:
+        if db.delete(entry.date, entry.data_type, entry.ticker):
+            deleted += 1
+    
+    print(f"✓ Deleted {deleted} entries")
+
+
+def search(db_dir: str, date_from: str = None, date_to: str = None, 
+          data_type: str = None, ticker: str = None, limit: int = 10):
+    """Search database entries"""
+    db = LocalDatabase(db_dir=db_dir)
+    
+    entries = db.query(
+        date_from=date_from,
+        date_to=date_to,
+        data_type=data_type,
+        ticker=ticker,
+        limit=limit
+    )
+    
+    if not entries:
+        print("No entries found")
+        return
+    
+    print(f"\n📋 Found {len(entries)} entries:\n")
+    print(f"{'Date':<12} {'Type':<20} {'Ticker':<10} {'Created':<20}")
+    print("-" * 70)
+    
+    for entry in entries:
+        created = datetime.fromisoformat(entry.created_at).strftime("%Y-%m-%d %H:%M")
+        print(f"{entry.date:<12} {entry.data_type:<20} {entry.ticker:<10} {created:<20}")
+    
+    print()
+
+
+def export_data(db_dir: str, output_file: str, date_from: str = None, 
+               date_to: str = None, data_type: str = None, ticker: str = None):
+    """Export database entries to JSON file"""
+    db = LocalDatabase(db_dir=db_dir)
+    
+    entries = db.query(
+        date_from=date_from,
+        date_to=date_to,
+        data_type=data_type,
+        ticker=ticker
+    )
+    
+    if not entries:
+        print("No entries to export")
+        return
+    
+    # Convert to dict list
+    export_data = [entry.to_dict() for entry in entries]
+    
+    # Write to file
+    with open(output_file, 'w', encoding='utf-8') as f:
+        json.dump(export_data, f, indent=2, default=str)
+    
+    print(f"✓ Exported {len(entries)} entries to {output_file}")
+
+
+def import_data(db_dir: str, input_file: str, expiry_days: int = None):
+    """Import database entries from JSON file"""
+    db = LocalDatabase(db_dir=db_dir)
+    
+    with open(input_file, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+    
+    if not isinstance(data, list):
+        print("❌ Invalid format: expected list of entries")
+        return
+    
+    from db.local_database import DatabaseEntry
+    
+    entries = []
+    for item in data:
+        try:
+            entry = DatabaseEntry.from_dict(item)
+            entries.append(entry)
+        except Exception as e:
+            print(f"⚠️  Skipping invalid entry: {e}")
+    
+    if not entries:
+        print("No valid entries to import")
+        return
+    
+    print(f"Found {len(entries)} valid entries")
+    response = input("Import these entries? (yes/no): ")
+    
+    if response.lower() != 'yes':
+        print("❌ Cancelled")
+        return
+    
+    count = db.save_batch(entries, expiry_days=expiry_days)
+    print(f"✓ Imported {count} entries")
+
+
+def list_types():
+    """List available data types"""
+    print("\n📁 Available Data Types:\n")
+    for dt in DataType:
+        print(f"  - {dt.value}")
+    print()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Database management utility for Stock Alchemist",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Show statistics
+  python db_util.py --stats
+  
+  # Clean expired entries
+  python db_util.py --clean-expired
+  
+  # Search for entries
+  python db_util.py --search --ticker AAPL --limit 20
+  
+  # Clear entries by type
+  python db_util.py --clear-type financial_info
+  
+  # Clear entries older than 30 days
+  python db_util.py --clear-older-than 30
+  
+  # Export data
+  python db_util.py --export backup.json --date-from 2025-01-01
+  
+  # Import data
+  python db_util.py --import backup.json --expiry-days 30
+        """
+    )
+    
+    parser.add_argument("--db-dir", type=str, default="database",
+                       help="Database directory (default: database)")
+    
+    # Actions
+    parser.add_argument("--stats", action="store_true",
+                       help="Show database statistics")
+    parser.add_argument("--clean-expired", action="store_true",
+                       help="Clean expired entries")
+    parser.add_argument("--clear-all", action="store_true",
+                       help="Clear all entries (WARNING: destructive)")
+    parser.add_argument("--clear-type", type=str,
+                       help="Clear entries of specific type")
+    parser.add_argument("--clear-ticker", type=str,
+                       help="Clear entries for specific ticker")
+    parser.add_argument("--clear-older-than", type=int,
+                       help="Clear entries older than N days")
+    parser.add_argument("--search", action="store_true",
+                       help="Search database entries")
+    parser.add_argument("--export", type=str,
+                       help="Export entries to JSON file")
+    parser.add_argument("--import", type=str, dest="import_file",
+                       help="Import entries from JSON file")
+    parser.add_argument("--list-types", action="store_true",
+                       help="List available data types")
+    
+    # Query filters
+    parser.add_argument("--date-from", type=str,
+                       help="Start date (YYYY-MM-DD)")
+    parser.add_argument("--date-to", type=str,
+                       help="End date (YYYY-MM-DD)")
+    parser.add_argument("--data-type", type=str,
+                       help="Filter by data type")
+    parser.add_argument("--ticker", type=str,
+                       help="Filter by ticker")
+    parser.add_argument("--limit", type=int, default=10,
+                       help="Limit number of results (default: 10)")
+    parser.add_argument("--expiry-days", type=int,
+                       help="Set expiry days for imported data")
+    parser.add_argument("--yes", action="store_true",
+                       help="Skip confirmation prompts")
+    
+    args = parser.parse_args()
+    
+    # Execute actions
+    if args.stats:
+        show_stats(args.db_dir)
+    elif args.clean_expired:
+        clean_expired(args.db_dir)
+    elif args.clear_all:
+        clear_all(args.db_dir, confirm=args.yes)
+    elif args.clear_type:
+        clear_by_type(args.db_dir, args.clear_type)
+    elif args.clear_ticker:
+        clear_by_ticker(args.db_dir, args.clear_ticker)
+    elif args.clear_older_than:
+        clear_older_than(args.db_dir, args.clear_older_than)
+    elif args.search:
+        search(args.db_dir, args.date_from, args.date_to, 
+               args.data_type, args.ticker, args.limit)
+    elif args.export:
+        export_data(args.db_dir, args.export, args.date_from, 
+                   args.date_to, args.data_type, args.ticker)
+    elif args.import_file:
+        import_data(args.db_dir, args.import_file, args.expiry_days)
+    elif args.list_types:
+        list_types()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

src/db/examples.py

@@ -0,0 +1,453 @@
+"""
+Example usage of the Local Database system
+Demonstrates integration with all modules
+"""
+
+from datetime import datetime, timedelta
+from db.local_database import LocalDatabase, DatabaseEntry, DataType
+from db.adapters import (
+    CalendarAdapter, 
+    FundamentalAdapter, 
+    NewsAdapter, 
+    TechnicalAnalysisAdapter
+)
+
+
+def example_calendar_scraper():
+    """Example: Save and retrieve calendar events"""
+    print("\n" + "="*60)
+    print("EXAMPLE 1: Calendar Scraper Integration")
+    print("="*60)
+    
+    adapter = CalendarAdapter()
+    today = datetime.now().date().isoformat()
+    
+    # Save earnings event
+    print("\n📅 Saving earnings event for AAPL...")
+    earnings_data = {
+        'company': 'Apple Inc.',
+        'time': 'After Market Close',
+        'eps_forecast': 1.54,
+        'last_year_eps': 1.46,
+        'revenue': '89.5B',
+        'market_cap': '2.8T'
+    }
+    
+    success = adapter.save_earnings_event(
+        date=today,
+        ticker='AAPL',
+        event_data=earnings_data,
+        expiry_days=30
+    )
+    print(f"✓ Saved: {success}")
+    
+    # Save economic event
+    print("\n🌍 Saving economic event...")
+    economic_data = {
+        'country': 'United States',
+        'importance': 'high',
+        'event': 'Non-Farm Payrolls',
+        'actual': 199000,
+        'forecast': 180000,
+        'previous': 150000
+    }
+    
+    success = adapter.save_economic_event(
+        date=today,
+        event_data=economic_data,
+        expiry_days=7
+    )
+    print(f"✓ Saved: {success}")
+    
+    # Retrieve earnings events
+    print("\n📋 Retrieving AAPL earnings events...")
+    events = adapter.get_earnings_events('AAPL')
+    print(f"Found {len(events)} events")
+    
+    for event in events:
+        print(f"  Date: {event.date}, Company: {event.data.get('company')}")
+
+
+def example_fundamental_analysis():
+    """Example: Save and retrieve fundamental analysis"""
+    print("\n" + "="*60)
+    print("EXAMPLE 2: Fundamental Analysis Integration")
+    print("="*60)
+    
+    adapter = FundamentalAdapter()
+    today = datetime.now().date().isoformat()
+    
+    # Save financial metrics
+    print("\n📊 Saving financial metrics for GOOGL...")
+    metrics = {
+        'market_cap': 1850000000000,
+        'pe_ratio': 28.5,
+        'fcf_yield': 4.08,
+        'roic': 0.32,
+        'revenue_growth': 0.208,
+        'eps_growth': 0.25,
+        'net_margin': 0.23,
+        'roe': 0.28
+    }
+    
+    success = adapter.save_financial_metrics(
+        date=today,
+        ticker='GOOGL',
+        metrics=metrics,
+        expiry_days=1
+    )
+    print(f"✓ Saved: {success}")
+    
+    # Save investment decision
+    print("\n🎯 Saving investment decision for GOOGL...")
+    decision = {
+        'recommendation': 'BUY',
+        'final_score': 0.67,
+        'confidence': 1.0,
+        'reasoning': [
+            'Strong FCF yield of 4.08%',
+            'Excellent ROIC of 32%',
+            'High revenue growth of 20.8%'
+        ],
+        'key_metrics': {
+            'fcf_yield': 4.08,
+            'roic': 32.0,
+            'revenue_growth': 20.8
+        },
+        'category_scores': {
+            'fcf_yield': 0.85,
+            'roic': 0.90,
+            'growth': 0.80
+        }
+    }
+    
+    success = adapter.save_investment_decision(
+        date=today,
+        ticker='GOOGL',
+        decision=decision,
+        expiry_days=1
+    )
+    print(f"✓ Saved: {success}")
+    
+    # Retrieve latest metrics
+    print("\n📈 Retrieving latest metrics for GOOGL...")
+    entry = adapter.get_financial_metrics('GOOGL')
+    if entry:
+        print(f"  Date: {entry.date}")
+        # Check if this is a metrics entry or decision entry
+        if 'metrics' in entry.data:
+            metrics_data = entry.data['metrics']
+            print(f"  P/E Ratio: {metrics_data.get('pe_ratio')}")
+            print(f"  FCF Yield: {metrics_data.get('fcf_yield')}%")
+        elif entry.data.get('analysis_type') == 'decision':
+            print(f"  Recommendation: {entry.data.get('recommendation')}")
+            print(f"  Score: {entry.data.get('score')}")
+        else:
+            print(f"  Analysis Type: {entry.data.get('analysis_type', 'unknown')}")
+
+
+def example_news_scraper():
+    """Example: Save and retrieve news articles"""
+    print("\n" + "="*60)
+    print("EXAMPLE 3: News Scraper Integration")
+    print("="*60)
+    
+    adapter = NewsAdapter()
+    today = datetime.now().date().isoformat()
+    
+    # Save news article
+    print("\n📰 Saving news article for TSLA...")
+    article = {
+        'title': 'Tesla Announces Record Q4 Deliveries',
+        'content': 'Tesla reported record vehicle deliveries...',
+        'source': 'Bloomberg',
+        'url': 'https://example.com/article',
+        'author': 'John Doe'
+    }
+    
+    success = adapter.save_news_article(
+        date=today,
+        ticker='TSLA',
+        article=article,
+        expiry_days=30
+    )
+    print(f"✓ Saved: {success}")
+    
+    # Save sentiment analysis
+    print("\n😊 Saving sentiment analysis for TSLA...")
+    sentiment = {
+        'model': 'finbert-tone',
+        'sentiment': 'positive',
+        'score': 0.85,
+        'confidence': 0.92,
+        'breakdown': {
+            'positive': 0.85,
+            'neutral': 0.10,
+            'negative': 0.05
+        }
+    }
+    
+    success = adapter.save_sentiment_analysis(
+        date=today,
+        ticker='TSLA',
+        sentiment=sentiment,
+        expiry_days=7
+    )
+    print(f"✓ Saved: {success}")
+    
+    # Retrieve news articles
+    print("\n📋 Retrieving TSLA news articles...")
+    articles = adapter.get_news_articles('TSLA')
+    print(f"Found {len(articles)} articles")
+    
+    for article in articles:
+        print(f"  Title: {article.data.get('title')}")
+        print(f"  Source: {article.data.get('source')}")
+
+
+def example_technical_analysis():
+    """Example: Save and retrieve technical analysis"""
+    print("\n" + "="*60)
+    print("EXAMPLE 4: Technical Analysis Integration")
+    print("="*60)
+    
+    adapter = TechnicalAnalysisAdapter()
+    today = datetime.now().date().isoformat()
+    
+    # Save technical indicators
+    print("\n📉 Saving technical indicators for NVDA...")
+    indicators = {
+        'rsi': 65.5,
+        'macd': 12.3,
+        'macd_signal': 10.8,
+        'sma_50': 450.25,
+        'sma_200': 420.80,
+        'bollinger_upper': 480.00,
+        'bollinger_lower': 430.00,
+        'volume': 45000000
+    }
+    
+    success = adapter.save_technical_indicators(
+        date=today,
+        ticker='NVDA',
+        indicators=indicators,
+        expiry_days=1
+    )
+    print(f"✓ Saved: {success}")
+    
+    # Save trading signal
+    print("\n🚦 Saving trading signal for NVDA...")
+    signal = {
+        'signal_type': 'BUY',
+        'strength': 0.75,
+        'triggers': ['RSI oversold', 'MACD crossover'],
+        'entry_price': 455.00,
+        'stop_loss': 440.00,
+        'take_profit': 480.00
+    }
+    
+    success = adapter.save_trading_signal(
+        date=today,
+        ticker='NVDA',
+        signal=signal,
+        expiry_days=1
+    )
+    print(f"✓ Saved: {success}")
+    
+    # Retrieve technical indicators
+    print("\n📊 Retrieving NVDA technical indicators...")
+    indicators_list = adapter.get_technical_indicators('NVDA')
+    print(f"Found {len(indicators_list)} indicator sets")
+    
+    for ind in indicators_list:
+        print(f"  RSI: {ind.data.get('rsi')}")
+        print(f"  MACD: {ind.data.get('macd')}")
+
+
+def example_batch_operations():
+    """Example: Batch save operations"""
+    print("\n" + "="*60)
+    print("EXAMPLE 5: Batch Operations")
+    print("="*60)
+    
+    db = LocalDatabase()
+    today = datetime.now().date().isoformat()
+    
+    # Create multiple entries
+    print("\n💾 Batch saving multiple stock analyses...")
+    entries = []
+    
+    tickers = ['AAPL', 'GOOGL', 'MSFT', 'AMZN', 'NVDA']
+    
+    for ticker in tickers:
+        entry = DatabaseEntry(
+            date=today,
+            data_type=DataType.FINANCIAL_INFO.value,
+            ticker=ticker,
+            data={
+                'analysis_type': 'quick_scan',
+                'price': 100.0 + len(ticker),  # Dummy data
+                'volume': 1000000 * len(ticker)
+            },
+            metadata={'batch_id': 'scan_001'}
+        )
+        entries.append(entry)
+    
+    count = db.save_batch(entries, expiry_days=1)
+    print(f"✓ Saved {count}/{len(entries)} entries")
+
+
+def example_query_operations():
+    """Example: Advanced queries"""
+    print("\n" + "="*60)
+    print("EXAMPLE 6: Query Operations")
+    print("="*60)
+    
+    db = LocalDatabase()
+    
+    # Query by date range
+    print("\n🔍 Querying all financial data from last 7 days...")
+    date_from = (datetime.now() - timedelta(days=7)).date().isoformat()
+    
+    entries = db.query(
+        data_type=DataType.FINANCIAL_INFO.value,
+        date_from=date_from,
+        limit=10
+    )
+    
+    print(f"Found {len(entries)} entries:")
+    for entry in entries[:5]:  # Show first 5
+        print(f"  {entry.date} - {entry.ticker} - {entry.data.get('analysis_type', 'N/A')}")
+    
+    # Query specific ticker
+    print("\n🔍 Querying all data for AAPL...")
+    aapl_entries = db.query(ticker='AAPL', limit=5)
+    print(f"Found {len(aapl_entries)} AAPL entries")
+
+
+def example_database_stats():
+    """Example: Database statistics"""
+    print("\n" + "="*60)
+    print("EXAMPLE 7: Database Statistics")
+    print("="*60)
+    
+    db = LocalDatabase()
+    stats = db.get_stats()
+    
+    print(f"\n📊 Database Overview:")
+    print(f"  Total Entries: {stats.get('total_entries', 0):,}")
+    print(f"  Total Size: {stats.get('total_size_mb', 0)} MB")
+    print(f"  Expired Entries: {stats.get('expired_entries', 0)}")
+    
+    by_type = stats.get('by_type', {})
+    if by_type:
+        print(f"\n📁 By Data Type:")
+        for data_type, count in by_type.items():
+            print(f"  {data_type}: {count:,}")
+
+
+def example_integration_workflow():
+    """Example: Complete workflow combining all modules"""
+    print("\n" + "="*60)
+    print("EXAMPLE 8: Complete Integration Workflow")
+    print("="*60)
+    
+    ticker = 'AAPL'
+    today = datetime.now().date().isoformat()
+    
+    # 1. Check calendar for upcoming events
+    print(f"\n1️⃣ Checking calendar for {ticker}...")
+    calendar_adapter = CalendarAdapter()
+    earnings = calendar_adapter.get_earnings_events(ticker)
+    print(f"   Found {len(earnings)} upcoming earnings events")
+    
+    # 2. Save fundamental analysis
+    print(f"\n2️⃣ Saving fundamental analysis for {ticker}...")
+    fundamental_adapter = FundamentalAdapter()
+    
+    decision = {
+        'recommendation': 'HOLD',
+        'final_score': 0.31,
+        'confidence': 0.85,
+        'reasoning': ['Strong ROIC but low FCF yield'],
+        'key_metrics': {'roic': 73.8, 'fcf_yield': 2.36}
+    }
+    
+    fundamental_adapter.save_investment_decision(today, ticker, decision)
+    print("   ✓ Decision saved")
+    
+    # 3. Check news sentiment
+    print(f"\n3️⃣ Saving news sentiment for {ticker}...")
+    news_adapter = NewsAdapter()
+    
+    sentiment = {
+        'model': 'finbert-tone',
+        'sentiment': 'neutral',
+        'score': 0.55
+    }
+    
+    news_adapter.save_sentiment_analysis(today, ticker, sentiment)
+    print("   ✓ Sentiment saved")
+    
+    # 4. Save technical signal
+    print(f"\n4️⃣ Saving technical signal for {ticker}...")
+    technical_adapter = TechnicalAnalysisAdapter()
+    
+    signal = {
+        'signal_type': 'HOLD',
+        'strength': 0.60,
+        'triggers': ['Neutral RSI', 'No clear pattern']
+    }
+    
+    technical_adapter.save_trading_signal(today, ticker, signal)
+    print("   ✓ Signal saved")
+    
+    # 5. Comprehensive analysis
+    print(f"\n5️⃣ Retrieving comprehensive analysis for {ticker}...")
+    db = LocalDatabase()
+    all_data = db.query(ticker=ticker, date_from=today)
+    
+    print(f"\n📊 Complete {ticker} Analysis ({today}):")
+    print(f"   Total data points: {len(all_data)}")
+    
+    for entry in all_data:
+        data_type = entry.data_type
+        if data_type == 'financial_info':
+            rec = entry.data.get('recommendation', 'N/A')
+            print(f"   💰 Fundamental: {rec}")
+        elif data_type == 'news':
+            sent = entry.data.get('sentiment', 'N/A')
+            print(f"   📰 News Sentiment: {sent}")
+        elif data_type == 'technical_analysis':
+            sig = entry.data.get('signal_type', 'N/A')
+            print(f"   📉 Technical Signal: {sig}")
+
+
+def run_all_examples():
+    """Run all examples"""
+    print("\n" + "="*60)
+    print("LOCAL DATABASE SYSTEM - EXAMPLE USAGE")
+    print("="*60)
+    
+    try:
+        example_calendar_scraper()
+        example_fundamental_analysis()
+        example_news_scraper()
+        example_technical_analysis()
+        example_batch_operations()
+        example_query_operations()
+        example_database_stats()
+        example_integration_workflow()
+        
+        print("\n" + "="*60)
+        print("✓ All examples completed successfully!")
+        print("="*60 + "\n")
+        
+    except Exception as e:
+        print(f"\n❌ Error running examples: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    run_all_examples()

src/db/get_event_from_db.py

@@ -0,0 +1,49 @@
+from datetime import datetime, timedelta
+from db.local_database import LocalDatabase, DatabaseEntry, DataType
+from db.adapters import (
+    CalendarAdapter, 
+    FundamentalAdapter, 
+    NewsAdapter, 
+    TechnicalAnalysisAdapter
+)
+
+def get_events(type:str, date_str:str):
+    """Retrieve event data from the local database for a given type, ticker, and date"""
+    db = LocalDatabase()
+    entries = db.query(date_from=date_str, data_type=type)
+    for entry in entries:
+        if entry:
+            return entry.data ## RETURN FIRST MATCHING ENTRY ONLY
+        return None
+
+def get_event_ticker(type:str, ticker:str, date_str:str):
+    """Retrieve event data from the local database for a given type, ticker, and date"""
+    db = LocalDatabase()
+    entry = db.get(date_str=date_str, data_type=type,ticker=ticker)
+    if entry:
+        return entry.data
+    return None
+
+
+
+if __name__ == "__main__":
+    # Example usage
+    date_str = datetime.now().strftime("%Y-%m-%d")
+    ticker = "ABNB"
+    
+    event_types = [
+        DataType.DIVIDENDS.value,
+        DataType.STOCK_SPLIT.value,
+        DataType.IPO.value,
+        DataType.EARNINGS.value,
+        DataType.ECONOMIC_EVENTS.value,
+        DataType.FUNDAMENTAL.value,
+        DataType.NEWS.value,
+        DataType.TECHNICAL_ANALYSIS.value
+    ]
+    
+    for event_type in event_types:
+        print(event_type)
+        event_data = get_events(event_type, date_str)
+        print(f"Event Type: {event_type}, Date: {date_str}")
+        print(f"Data: {event_data}\n")

src/db/isrgrootx1.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

src/db/local_database.py

@@ -0,0 +1,1217 @@
+"""
+Advanced Local Database Manager for Stock Alchemist
+Stores data as JSON files organized by date, type, and ticker
+Uses MySQL for indexing and JSON files for data storage
+"""
+
+import json
+import mysql.connector
+from mysql.connector import Error
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+from dataclasses import dataclass, asdict, field
+from enum import Enum
+import hashlib
+import gzip
+import numpy as np
+
+
+class DataType(Enum):
+    """Supported data types - simplified naming"""
+    # Calendar events (no prefix needed)
+    EARNINGS = "earnings"
+    IPO = "ipo"
+    STOCK_SPLIT = "stock_split"
+    DIVIDENDS = "dividends"
+    ECONOMIC_EVENTS = "economic_events"
+    # Other data types
+    FUNDAMENTAL = "fundamental_analysis"
+    NEWS = "news"
+    TECHNICAL_ANALYSIS = "technical_analysis"
+
+
+@dataclass
+class DatabaseEntry:
+    """Base class for database entries"""
+    date: str  # ISO format YYYY-MM-DD
+    data_type: str  # DataType enum value
+    ticker: str
+    data: Dict[str, Any]
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    updated_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    expiry_date: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self):
+        """Convert to dictionary"""
+        return asdict(self)
+    
+    @classmethod
+    def from_dict(cls, data: Dict):
+        """Create from dictionary"""
+        return cls(**data)
+    
+    def generate_key(self):
+        """
+        Generate unique key for this entry
+        For calendar events, includes execution_date/ex_date to prevent duplicates
+        """
+        # For calendar events, include the actual event date to ensure uniqueness
+        if self.data_type in ['earnings', 'ipo', 'stock_split', 'dividends']:
+            event_date = (self.data.get('execution_date') or 
+                         self.data.get('ex_date') or 
+                         self.data.get('date') or 
+                         self.date)
+            key_string = f"{self.data_type}_{self.ticker}_{event_date}"
+        else:
+            key_string = f"{self.date}_{self.data_type}_{self.ticker}"
+        
+        return hashlib.md5(key_string.encode()).hexdigest()
+
+
+class LocalDatabase:
+    """
+    Advanced local database manager with MySQL index and JSON file storage
+    
+    Features:
+    - MySQL metadata index for fast queries
+    - JSON files for actual data storage
+    - Optional gzip compression for large data
+    - Automatic expiry and cleanup
+    - Date/Type/Ticker indexing
+    - Batch operations support
+    """
+    
+    def __init__(self, db_dir: str = "database", compress: bool = False):
+        """
+        Initialize database manager
+        
+        Args:
+            db_dir: Root directory for database storage
+            compress: Whether to compress JSON files with gzip
+        """
+        self.db_dir = Path(db_dir)
+        self.db_dir.mkdir(exist_ok=True)
+        
+        # Create subdirectories for organization
+        self.data_dir = self.db_dir / "data"
+        self.data_dir.mkdir(exist_ok=True)
+        
+        # Load environment variables
+        from dotenv import load_dotenv
+        import os
+        load_dotenv()
+        
+        # MySQL connection parameters from environment variables
+        self.mysql_config = {
+            'host': os.getenv('DB_HOST', 'localhost').strip(),
+            'user': os.getenv('DB_USERNAME', 'root').strip(),
+            'password': os.getenv('DB_PASSWORD', '').strip(),
+            'database': os.getenv('DB_DATABASE', 'gotti').strip(),
+            'port': int(os.getenv('DB_PORT', 3306))
+        }
+        
+        # SSL Configuration for TiDB
+        ssl_ca = os.getenv('DB_SSL_CA')
+        if ssl_ca:
+            # Resolve relative path if needed
+            if not os.path.isabs(ssl_ca):
+                # Assuming src/isrgrootx1.pem is relative to project root
+                # self.db_dir is usually project_root/database
+                # So project root is self.db_dir.parent
+                project_root = Path(__file__).parent.parent.parent
+                ssl_ca_path = project_root / ssl_ca
+                
+                if ssl_ca_path.exists():
+                    self.mysql_config['ssl_ca'] = str(ssl_ca_path)
+                    self.mysql_config['ssl_verify_cert'] = True
+                    self.mysql_config['ssl_verify_identity'] = True
+                else:
+                    print(f"⚠️  SSL CA file not found at {ssl_ca_path}")
+        
+        self.compress = compress
+        
+        self._init_database()
+    
+    def _create_connection(self):
+        """Create and return a MySQL database connection"""
+        try:
+            connection = mysql.connector.connect(**self.mysql_config)
+            return connection
+        except Error as e:
+            print(f"❌ Error connecting to MySQL: {e}")
+            return None
+    
+    def _get_table_name(self, data_type: str) -> str:
+        """Determine which table to use based on data_type"""
+        # Calendar events
+        if data_type in ['earnings', 'ipo', 'stock_split', 'dividends', 'economic_events']:
+            return 'calendar'
+        # News
+        elif data_type == 'news':
+            return 'news'
+        # Fundamental analysis
+        elif data_type == 'fundamental_analysis':
+            return 'fundamental_analysis'
+        else:
+            raise ValueError(f"Unknown data type: {data_type}")
+    
+    def _init_database(self):
+        """Initialize MySQL tables - three separate tables by data category"""
+        conn = self._create_connection()
+        if not conn:
+            raise Exception("Failed to connect to MySQL database")
+        
+        cursor = conn.cursor()
+        
+        try:
+            # Create calendar table
+            cursor.execute('''
+                CREATE TABLE IF NOT EXISTS calendar (
+                    entry_key VARCHAR(32) PRIMARY KEY,
+                    date DATE NOT NULL,
+                    event_type VARCHAR(50) NOT NULL,
+                    ticker VARCHAR(20) NOT NULL,
+                    data JSON NOT NULL,
+                    created_at DATETIME NOT NULL,
+                    updated_at DATETIME NOT NULL,
+                    expiry_date DATE,
+                    metadata JSON,
+                    execution_date DATE,
+                    INDEX idx_date (date),
+                    INDEX idx_event_type (event_type),
+                    INDEX idx_ticker (ticker),
+                    INDEX idx_date_event (date, event_type),
+                    INDEX idx_ticker_event (ticker, event_type)
+                ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+            ''')
+            
+            # Create news table
+            cursor.execute('''
+                CREATE TABLE IF NOT EXISTS news (
+                    entry_key VARCHAR(32) PRIMARY KEY,
+                    date DATE NOT NULL,
+                    ticker VARCHAR(20) NOT NULL,
+                    data JSON NOT NULL,
+                    created_at DATETIME NOT NULL,
+                    updated_at DATETIME NOT NULL,
+                    expiry_date DATE,
+                    metadata JSON,
+                    INDEX idx_date (date),
+                    INDEX idx_ticker (ticker),
+                    INDEX idx_date_ticker (date, ticker)
+                ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+            ''')
+            
+            # Create fundamental_analysis table
+            cursor.execute('''
+                CREATE TABLE IF NOT EXISTS fundamental_analysis (
+                    entry_key VARCHAR(32) PRIMARY KEY,
+                    date DATE NOT NULL,
+                    ticker VARCHAR(20) NOT NULL,
+                    data JSON NOT NULL,
+                    created_at DATETIME NOT NULL,
+                    updated_at DATETIME NOT NULL,
+                    expiry_date DATE,
+                    metadata JSON,
+                    INDEX idx_date (date),
+                    INDEX idx_ticker (ticker),
+                    INDEX idx_date_ticker (date, ticker)
+                ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+            ''')
+            
+            # Create available_tickers table - whitelist of allowed tickers
+            cursor.execute('''
+                CREATE TABLE IF NOT EXISTS available_tickers (
+                    ticker VARCHAR(20) PRIMARY KEY,
+                    name VARCHAR(255),
+                    exchange VARCHAR(50),
+                    sector VARCHAR(100),
+                    is_active BOOLEAN DEFAULT TRUE,
+                    added_at DATETIME NOT NULL,
+                    updated_at DATETIME NOT NULL,
+                    metadata JSON,
+                    INDEX idx_is_active (is_active),
+                    INDEX idx_exchange (exchange),
+                    INDEX idx_sector (sector)
+                ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+            ''')
+            
+            # Create signals table - tracks actionable ticker signals
+            cursor.execute('''
+                CREATE TABLE IF NOT EXISTS signals (
+                    signal_id VARCHAR(32) PRIMARY KEY,
+                    ticker VARCHAR(20) NOT NULL,
+                    signal_date DATE NOT NULL,
+                    signal_position VARCHAR(10) NOT NULL,
+                    calendar_event_keys JSON,
+                    news_keys JSON,
+                    fundamental_analysis_key VARCHAR(32),
+                    sentiment JSON,
+                    created_at DATETIME NOT NULL,
+                    updated_at DATETIME NOT NULL,
+                    metadata JSON,
+                    INDEX idx_ticker (ticker),
+                    INDEX idx_signal_date (signal_date),
+                    INDEX idx_ticker_date (ticker, signal_date),
+                    INDEX idx_created_at (created_at)
+                ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+            ''')
+            
+            # Add execution_date column to calendar table if it doesn't exist
+            try:
+                cursor.execute("ALTER TABLE calendar ADD COLUMN execution_date DATE AFTER date")
+                print("✅ Added execution_date column to calendar table")
+            except Error as e:
+                if e.errno != 1060:  # Error 1060 = Duplicate column name
+                    pass  # Column already exists, ignore
+            
+            # Add sentiment column to signals table if it doesn't exist
+            try:
+                cursor.execute("ALTER TABLE signals ADD COLUMN sentiment JSON AFTER fundamental_analysis_key")
+                print("✅ Added sentiment column to signals table")
+            except Error as e:
+                if e.errno != 1060:  # Error 1060 = Duplicate column name
+                    pass  # Column already exists, ignore
+
+            # Add signal_position column to signals table if it doesn't exist
+            try:
+                cursor.execute("ALTER TABLE signals ADD COLUMN signal_position VARCHAR(10) AFTER signal_date")
+                print("✅ Added signal_position column to signals table")
+            except Error as e:
+                if e.errno != 1060:  # Error 1060 = Duplicate column name
+                    pass  # Column already exists, ignore
+            
+            conn.commit()
+            print("✅ MySQL database tables initialized successfully (calendar, news, fundamental_analysis, available_tickers, signals)")
+        except Error as e:
+            print(f"❌ Error initializing database: {e}")
+            # Try without IF NOT EXISTS for MySQL versions that don't support it
+            try:
+                cursor.execute("SHOW COLUMNS FROM calendar LIKE 'execution_date'")
+                if cursor.fetchone() is None:
+                    cursor.execute("ALTER TABLE calendar ADD COLUMN execution_date DATE AFTER date")
+                    conn.commit()
+                    print("✅ Added execution_date column to calendar table")
+            except Exception as alter_error:
+                print(f"⚠️  Could not add execution_date column: {alter_error}")
+            
+            # Try adding sentiment column for older MySQL versions
+            try:
+                cursor.execute("SHOW COLUMNS FROM signals LIKE 'sentiment'")
+                if cursor.fetchone() is None:
+                    cursor.execute("ALTER TABLE signals ADD COLUMN sentiment JSON AFTER fundamental_analysis_key")
+                    conn.commit()
+                    print("✅ Added sentiment column to signals table")
+            except Exception as alter_error:
+                print(f"⚠️  Could not add sentiment column: {alter_error}")
+
+            # Try adding signal_position column for older MySQL versions
+            try:
+                cursor.execute("SHOW COLUMNS FROM signals LIKE 'signal_position'")
+                if cursor.fetchone() is None:
+                    cursor.execute("ALTER TABLE signals ADD COLUMN signal_position VARCHAR(10) AFTER signal_date")
+                    conn.commit()
+                    print("✅ Added signal_position column to signals table")
+            except Exception as alter_error:
+                print(f"⚠️  Could not add signal_position column: {alter_error}")
+        finally:
+            cursor.close()
+            conn.close()
+
+    def _generate_file_path(self, entry_key: str, data_type: str, date_str: str) -> Path:
+        """Generate organized file path for data storage"""
+        # Organize by type/year/month/
+        year_month = datetime.fromisoformat(date_str).strftime("%Y/%m")
+        type_dir = self.data_dir / data_type / year_month
+        type_dir.mkdir(parents=True, exist_ok=True)
+        
+        extension = ".json.gz" if self.compress else ".json"
+        return type_dir / f"{entry_key}{extension}"
+    
+    def _write_json(self, file_path: Path, data: Dict):
+        """Write JSON data with optional compression"""
+        json_str = json.dumps(data, indent=2, default=str)
+        
+        if self.compress:
+            with gzip.open(file_path, 'wt', encoding='utf-8') as f:
+                f.write(json_str)
+        else:
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(json_str)
+    
+    def _read_json(self, file_path: Path, compressed: bool) -> Dict:
+        """Read JSON data with optional decompression"""
+        if compressed:
+            with gzip.open(file_path, 'rt', encoding='utf-8') as f:
+                return json.load(f)
+        else:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+
+    def _clean_data_for_json(self, data: Any) -> Any:
+        """
+        Recursively clean data to ensure it's JSON serializable.
+        - Converts NaN/Infinity to None
+        - Converts numpy types to native python types
+        """
+        if isinstance(data, dict):
+            return {k: self._clean_data_for_json(v) for k, v in data.items()}
+        elif isinstance(data, list):
+            return [self._clean_data_for_json(v) for v in data]
+        elif isinstance(data, float):
+            if np.isnan(data) or np.isinf(data):
+                return None
+            return float(data)
+        elif isinstance(data, np.integer):
+            return int(data)
+        elif isinstance(data, np.floating):
+            if np.isnan(data) or np.isinf(data):
+                return None
+            return float(data)
+        elif isinstance(data, np.ndarray):
+            return self._clean_data_for_json(data.tolist())
+        return data
+
+    def add_ticker(self, ticker: str, name: str = None, exchange: str = None, 
+                   sector: str = None, metadata: Dict = None) -> bool:
+        """
+        Add a ticker to the available_tickers whitelist.
+        
+        Args:
+            ticker: Ticker symbol
+            name: Company name
+            exchange: Exchange name (e.g., 'NASDAQ', 'NYSE')
+            sector: Company sector
+            metadata: Additional metadata as JSON
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        conn = self._create_connection()
+        if not conn:
+            return False
+        
+        cursor = conn.cursor()
+        try:
+            now = datetime.now()
+            cursor.execute('''
+                INSERT INTO available_tickers 
+                (ticker, name, exchange, sector, is_active, added_at, updated_at, metadata)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+                ON DUPLICATE KEY UPDATE
+                name = VALUES(name),
+                exchange = VALUES(exchange),
+                sector = VALUES(sector),
+                is_active = VALUES(is_active),
+                updated_at = VALUES(updated_at),
+                metadata = VALUES(metadata)
+            ''', (
+                ticker.upper(),
+                name,
+                exchange,
+                sector,
+                True,
+                now,
+                now,
+                json.dumps(metadata) if metadata else None
+            ))
+            conn.commit()
+            return True
+        except Error as e:
+            print(f"❌ Error adding ticker {ticker}: {e}")
+            return False
+        finally:
+            cursor.close()
+            conn.close()
+    
+    def get_macroeconomic_indicators(self) -> Dict[str, Any]:
+        """
+        Retrieve macroeconomic indicators from the database.
+        
+        Returns:
+            Dictionary of macroeconomic indicators
+        """
+        conn = self._create_connection()
+        if not conn:
+            return {}
+        
+        cursor = conn.cursor()
+        try:
+            cursor.execute('''
+                SELECT data 
+                FROM macroeconomic_indicators 
+                ORDER BY date DESC 
+                LIMIT 1
+            ''')
+            row = cursor.fetchone()
+            if row:
+                return json.loads(row[0])
+            return {}
+        except Error as e:
+            print(f"❌ Error fetching macroeconomic indicators: {e}")
+            return {}
+        finally:
+            cursor.close()
+            conn.close()
+    
+    def remove_ticker(self, ticker: str) -> bool:
+        """
+        Deactivate a ticker (soft delete - sets is_active to False).
+        
+        Args:
+            ticker: Ticker symbol to deactivate
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        conn = self._create_connection()
+        if not conn:
+            return False
+        
+        cursor = conn.cursor()
+        try:
+            cursor.execute(
+                "UPDATE available_tickers SET is_active = FALSE, updated_at = %s WHERE ticker = %s",
+                (datetime.now(), ticker.upper())
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+        except Error as e:
+            print(f"❌ Error removing ticker {ticker}: {e}")
+            return False
+        finally:
+            cursor.close()
+            conn.close()
+    
+    def get_all_available_tickers(self) -> List[str]:
+        """
+        Get all active tickers from the whitelist.
+        
+        Returns:
+            List of ticker symbols
+        """
+        conn = self._create_connection()
+        if not conn:
+            return []
+        
+        cursor = conn.cursor()
+        try:
+            cursor.execute("SELECT ticker FROM available_tickers WHERE is_active = TRUE ORDER BY ticker")
+            return [row[0] for row in cursor.fetchall()]
+        except Error as e:
+            print(f"❌ Error fetching available tickers: {e}")
+            return []
+        finally:
+            cursor.close()
+            conn.close()
+    
+    def is_ticker_available(self, ticker: str) -> bool:
+        """
+        Check if ticker is in the available_tickers whitelist.
+        
+        Args:
+            ticker: Ticker symbol to check
+        Returns:
+            True if ticker is available and active, False otherwise
+        """
+        conn = self._create_connection()
+        if not conn:
+            return False
+        cursor = conn.cursor()
+        try:
+            cursor.execute(
+                "SELECT is_active FROM available_tickers WHERE ticker = %s",
+                (ticker.upper(),)
+            )
+            result = cursor.fetchone()
+            
+            if result and result[0]:  # Ticker exists and is_active = True
+                return True
+            return False
+        except Error as e:
+            print(f"❌ Error checking ticker availability for {ticker}: {e}")
+            return False
+        finally:
+            cursor.close()
+            conn.close()
+
+    def save(self, entry: DatabaseEntry, expiry_days: Optional[int] = None) -> bool:
+        """
+        Save entry to database. Updates existing entry if duplicate is found.
+        IMPORTANT: Checks if ticker is in available_tickers whitelist before saving.
+        
+        Args:
+            entry: DatabaseEntry to save
+            expiry_days: Optional expiry in days
+            
+        Returns:
+            True if successful, False if ticker not available or save fails
+        """
+        try:
+            # CRITICAL: Check if ticker is in the available_tickers whitelist
+            # Skip check for economic events as they use country names as tickers
+            if entry.data_type != DataType.ECONOMIC_EVENTS.value and not self.is_ticker_available(entry.ticker):
+                print(f"⚠️  Skipping {entry.data_type} for {entry.ticker} - ticker not in available_tickers whitelist")
+                return False
+            
+            entry_key = entry.generate_key()
+            
+            # Get the appropriate table name
+            table_name = self._get_table_name(entry.data_type)
+            
+            # Check if entry already exists
+            conn = self._create_connection()
+            if not conn:
+                return False
+            
+            cursor = conn.cursor()
+            
+            cursor.execute(f'SELECT created_at FROM {table_name} WHERE entry_key = %s', (entry_key,))
+            existing = cursor.fetchone()
+            
+            # Preserve original created_at if updating
+            if existing:
+                entry.created_at = str(existing[0])
+            
+            # Update the updated_at timestamp
+            entry.updated_at = datetime.now().isoformat()
+            
+            # Calculate expiry date if specified
+            if expiry_days:
+                expiry_date = (datetime.now() + timedelta(days=expiry_days)).date().isoformat()
+                entry.expiry_date = expiry_date
+            
+            # Store data directly as JSON in database
+            # Different INSERT statement based on table structure
+            if table_name == 'calendar':
+                # Calendar table has event_type column
+                cursor.execute('''
+                    INSERT INTO calendar 
+                    (entry_key, date, event_type, ticker, data, created_at, updated_at, 
+                     expiry_date, metadata)
+                    VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)
+                    ON DUPLICATE KEY UPDATE
+                        data = VALUES(data),
+                        updated_at = VALUES(updated_at),
+                        expiry_date = VALUES(expiry_date),
+                        metadata = VALUES(metadata)
+                ''', (
+                    entry_key,
+                    entry.date,
+                    entry.data_type,  # event_type (earnings, ipo, etc.)
+                    entry.ticker,
+                    json.dumps(self._clean_data_for_json(entry.data), default=str),
+                    entry.created_at,
+                    entry.updated_at,
+                    entry.expiry_date,
+                    json.dumps(entry.metadata)
+                ))
+            else:
+                # News and fundamental_analysis tables don't have event_type
+                cursor.execute(f'''
+                    INSERT INTO {table_name} 
+                    (entry_key, date, ticker, data, created_at, updated_at, 
+                     expiry_date, metadata)
+                    VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+                    ON DUPLICATE KEY UPDATE
+                        data = VALUES(data),
+                        updated_at = VALUES(updated_at),
+                        expiry_date = VALUES(expiry_date),
+                        metadata = VALUES(metadata)
+                ''', (
+                    entry_key,
+                    entry.date,
+                    entry.ticker,
+                    json.dumps(self._clean_data_for_json(entry.data), default=str),
+                    entry.created_at,
+                    entry.updated_at,
+                    entry.expiry_date,
+                    json.dumps(entry.metadata)
+                ))
+            
+            conn.commit()
+            return True
+            
+        except Exception as e:
+            print(f"Error saving entry {entry.ticker}: {e}")
+            return False
+        finally:
+            if 'cursor' in locals():
+                cursor.close()
+            if 'conn' in locals() and conn:
+                conn.close()
+    
+    def save_batch(self, entries: List[DatabaseEntry], expiry_days: Optional[int] = None) -> int:
+        """
+        Save multiple entries in batch. Updates existing entries if duplicates are found.
+        
+        Args:
+            entries: List of DatabaseEntry objects
+            expiry_days: Optional expiry in days
+            
+        Returns:
+            Number of successfully saved entries
+        """
+        success_count = 0
+        
+        conn = self._create_connection()
+        if not conn:
+            return 0
+        
+        cursor = conn.cursor()
+        
+        try:
+            for entry in entries:
+                try:
+                    # CRITICAL: Check if ticker is in the available_tickers whitelist
+                    # Skip check for economic events as they use country names as tickers
+                    if entry.data_type != DataType.ECONOMIC_EVENTS.value and not self.is_ticker_available(entry.ticker):
+                        print(f"⚠️  Skipping {entry.data_type} for {entry.ticker} - ticker not in available_tickers whitelist")
+                        continue
+
+                    entry_key = entry.generate_key()
+                    table_name = self._get_table_name(entry.data_type)
+                    
+                    # Check if entry already exists
+                    cursor.execute(f'SELECT created_at FROM {table_name} WHERE entry_key = %s', (entry_key,))
+                    existing = cursor.fetchone()
+                    
+                    # Preserve original created_at if updating
+                    if existing:
+                        entry.created_at = str(existing[0])
+                    
+                    # Update the updated_at timestamp
+                    entry.updated_at = datetime.now().isoformat()
+                    
+                    if expiry_days:
+                        expiry_date = (datetime.now() + timedelta(days=expiry_days)).date().isoformat()
+                        entry.expiry_date = expiry_date
+                    
+                    # Store data directly in database - different format for calendar
+                    if table_name == 'calendar':
+                        cursor.execute('''
+                            INSERT INTO calendar 
+                            (entry_key, date, event_type, ticker, data, created_at, updated_at, 
+                             expiry_date, metadata)
+                            VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)
+                            ON DUPLICATE KEY UPDATE
+                                data = VALUES(data),
+                                updated_at = VALUES(updated_at),
+                                expiry_date = VALUES(expiry_date),
+                                metadata = VALUES(metadata)
+                        ''', (
+                            entry_key,
+                            entry.date,
+                            entry.data_type,  # event_type
+                            entry.ticker,
+                            json.dumps(self._clean_data_for_json(entry.data), default=str),
+                            entry.created_at,
+                            entry.updated_at,
+                            entry.expiry_date,
+                            json.dumps(entry.metadata)
+                        ))
+                    else:
+                        cursor.execute(f'''
+                            INSERT INTO {table_name} 
+                            (entry_key, date, ticker, data, created_at, updated_at, 
+                             expiry_date, metadata)
+                            VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+                            ON DUPLICATE KEY UPDATE
+                                data = VALUES(data),
+                                updated_at = VALUES(updated_at),
+                                expiry_date = VALUES(expiry_date),
+                                metadata = VALUES(metadata)
+                        ''', (
+                            entry_key,
+                            entry.date,
+                            entry.ticker,
+                            json.dumps(self._clean_data_for_json(entry.data), default=str),
+                            entry.created_at,
+                            entry.updated_at,
+                            entry.expiry_date,
+                            json.dumps(entry.metadata)
+                        ))
+                    
+                    success_count += 1
+                    
+                except Exception as e:
+                    print(f"Error saving entry {entry.ticker}: {e}")
+                    continue
+            
+            conn.commit()
+            
+        finally:
+            cursor.close()
+            conn.close()
+        
+        return success_count
+
+    def save_signal(self, ticker: str, calendar_event_keys: List[str], news_keys: List[str], 
+                   fundamental_key: str, signal_position: str, sentiment: Dict = None) -> bool:
+        """Save a generated signal to the database"""
+        try:
+            conn = self._create_connection()
+            if not conn:
+                return False
+            cursor = conn.cursor()
+            
+            signal_date = datetime.now().date().isoformat()
+            signal_id = hashlib.md5(f"{ticker}_{signal_date}".encode()).hexdigest()
+            now = datetime.now()
+            
+            # Merge with existing sentiment if provided
+            final_sentiment = sentiment
+            if sentiment:
+                cursor.execute("SELECT sentiment FROM signals WHERE signal_id = %s", (signal_id,))
+                existing = cursor.fetchone()
+                if existing and existing[0]:
+                    existing_sentiment = json.loads(existing[0]) if isinstance(existing[0], str) else existing[0]
+                    if isinstance(existing_sentiment, dict):
+                        existing_sentiment.update(sentiment)
+                        final_sentiment = existing_sentiment
+            
+            cursor.execute('''
+                INSERT INTO signals 
+                (signal_id, ticker, signal_date, signal_position, calendar_event_keys, news_keys, 
+                 fundamental_analysis_key, sentiment, created_at, updated_at, metadata)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+                ON DUPLICATE KEY UPDATE
+                    signal_position = VALUES(signal_position),
+                    calendar_event_keys = VALUES(calendar_event_keys),
+                    news_keys = VALUES(news_keys),
+                    fundamental_analysis_key = VALUES(fundamental_analysis_key),
+                    sentiment = VALUES(sentiment),
+                    updated_at = VALUES(updated_at)
+            ''', (
+                signal_id,
+                ticker,
+                signal_date,
+                signal_position,
+                json.dumps(calendar_event_keys),
+                json.dumps(news_keys),
+                fundamental_key,
+                json.dumps(final_sentiment) if final_sentiment else None,
+                now,
+                now,
+                json.dumps({})
+            ))
+            
+            conn.commit()
+            return True
+        except Error as e:
+            print(f"❌ Error saving signal: {e}")
+            return False
+        finally:
+            if 'cursor' in locals():
+                cursor.close()
+            if 'conn' in locals():
+                conn.close()
+
+    def get_signal(self, ticker: str, date_str: str = None) -> Optional[Dict]:
+        """Get signal for a ticker on a specific date (defaults to today)"""
+        try:
+            if not date_str:
+                date_str = datetime.now().date().isoformat()
+                
+            conn = self._create_connection()
+            if not conn:
+                return None
+            cursor = conn.cursor(dictionary=True)
+            
+            cursor.execute('''
+                SELECT * FROM signals 
+                WHERE ticker = %s AND signal_date = %s
+            ''', (ticker, date_str))
+            
+            result = cursor.fetchone()
+            
+            if result:
+                # Parse JSON fields
+                for field in ['calendar_event_keys', 'news_keys', 'metadata', 'sentiment']:
+                    if result.get(field):
+                        if isinstance(result[field], str):
+                            result[field] = json.loads(result[field])
+                            
+            return result
+        except Error as e:
+            print(f"❌ Error getting signal: {e}")
+            return None
+        finally:
+            if 'cursor' in locals():
+                cursor.close()
+            if 'conn' in locals():
+                conn.close()
+    
+    def get(self, date_str: str, data_type: str, ticker: str) -> Optional[DatabaseEntry]:
+        """
+        Retrieve entry by date, type, and ticker
+        
+        Args:
+            date_str: Date in YYYY-MM-DD format
+            data_type: Data type (earnings, ipo, news, fundamental_analysis, etc.)
+            ticker: Stock ticker
+            
+        Returns:
+            DatabaseEntry if found, None otherwise
+        """
+        try:
+            # Generate key
+            key_string = f"{date_str}_{data_type}_{ticker}"
+            entry_key = hashlib.md5(key_string.encode()).hexdigest()
+            
+            # Get table name for this data type
+            table_name = self._get_table_name(data_type)
+            
+            conn = self._create_connection()
+            if not conn:
+                return None
+            cursor = conn.cursor()
+            
+            # Different SELECT based on table structure
+            if table_name == 'calendar':
+                cursor.execute('''
+                    SELECT date, event_type, ticker, data, created_at, updated_at, expiry_date, metadata
+                    FROM calendar 
+                    WHERE entry_key = %s
+                ''', (entry_key,))
+            else:
+                cursor.execute(f'''
+                    SELECT date, ticker, data, created_at, updated_at, expiry_date, metadata
+                    FROM {table_name} 
+                    WHERE entry_key = %s
+                ''', (entry_key,))
+            
+            result = cursor.fetchone()
+            cursor.close()
+            conn.close()
+            
+            if not result:
+                return None
+            
+            # Parse result based on table structure
+            if table_name == 'calendar':
+                date_val, event_type_val, ticker_val, data_json, created_at, updated_at, expiry_date, metadata_json = result
+                data_type_val = event_type_val  # event_type is the data_type
+            else:
+                date_val, ticker_val, data_json, created_at, updated_at, expiry_date, metadata_json = result
+                data_type_val = data_type  # Use the data_type parameter
+            
+            # Check if expired
+            if expiry_date:
+                if str(expiry_date) < datetime.now().date().isoformat():
+                    return None
+            
+            # Parse JSON data from database
+            data_dict = json.loads(data_json) if isinstance(data_json, str) else data_json
+            metadata_dict = json.loads(metadata_json) if isinstance(metadata_json, str) else (metadata_json or {})
+            
+            # Create DatabaseEntry
+            entry = DatabaseEntry(
+                date=str(date_val),
+                data_type=str(data_type_val),
+                ticker=str(ticker_val),
+                data=data_dict,
+                created_at=str(created_at),
+                updated_at=str(updated_at),
+                expiry_date=str(expiry_date) if expiry_date else None,
+                metadata=metadata_dict
+            )
+            return entry
+            
+        except Exception as e:
+            print(f"Error retrieving entry: {e}")
+            return None
+    
+    def query(self,
+              date_from: Optional[str] = None,
+              date_to: Optional[str] = None,
+              data_type: Optional[str] = None,
+              ticker: Optional[str] = None,
+              limit: Optional[int] = None,
+              include_expired: bool = False) -> List[DatabaseEntry]:
+        """
+        Query database with flexible filters across all tables
+        
+        Args:
+            date_from: Start date (inclusive)
+            date_to: End date (inclusive)
+            data_type: Filter by data type (e.g., 'earnings', 'news', 'fundamental_analysis')
+            ticker: Filter by ticker
+            limit: Max results
+            include_expired: Whether to include expired entries
+            
+        Returns:
+            List of DatabaseEntry objects
+        """
+        try:
+            conn = self._create_connection()
+            if not conn:
+                return []
+            
+            cursor = conn.cursor()
+            entries = []
+            
+            # Determine which tables to query
+            tables_to_query = []
+            if data_type:
+                # Query specific table based on data_type
+                table_name = self._get_table_name(data_type)
+                tables_to_query.append((table_name, data_type))
+            else:
+                # Query all tables
+                tables_to_query = [
+                    ('calendar', None),  # Will get all calendar events
+                    ('news', 'news'),
+                    ('fundamental_analysis', 'fundamental_analysis')
+                ]
+            
+            # Query each table
+            for table_name, specific_type in tables_to_query:
+                params = []
+                
+                if table_name == 'calendar':
+                    # Calendar has event_type column
+                    query = "SELECT date, event_type, ticker, data, created_at, updated_at, expiry_date, metadata FROM calendar WHERE 1=1"
+                    
+                    if specific_type:  # Specific calendar event type
+                        query += " AND event_type = %s"
+                        params.append(specific_type)
+                else:
+                    # News and fundamental_analysis don't have event_type
+                    query = f"SELECT date, ticker, data, created_at, updated_at, expiry_date, metadata FROM {table_name} WHERE 1=1"
+                
+                if date_from:
+                    query += " AND date >= %s"
+                    params.append(date_from)
+                
+                if date_to:
+                    query += " AND date <= %s"
+                    params.append(date_to)
+                
+                if ticker:
+                    query += " AND ticker = %s"
+                    params.append(ticker)
+                
+                if not include_expired:
+                    query += " AND (expiry_date IS NULL OR expiry_date >= %s)"
+                    params.append(datetime.now().date().isoformat())
+                
+                query += " ORDER BY date DESC, created_at DESC"
+                
+                if limit and len(tables_to_query) == 1:
+                    # Only apply limit if querying a single table
+                    query += f" LIMIT {limit}"
+                
+                cursor.execute(query, tuple(params))
+                results = cursor.fetchall()
+                
+                # Parse results based on table structure
+                for row in results:
+                    try:
+                        if table_name == 'calendar':
+                            date_val, event_type_val, ticker_val, data_json, created_at, updated_at, expiry_date, metadata_json = row
+                            data_type_val = event_type_val
+                        else:
+                            date_val, ticker_val, data_json, created_at, updated_at, expiry_date, metadata_json = row
+                            data_type_val = specific_type
+                        
+                        # Parse JSON data
+                        data_dict = json.loads(data_json) if isinstance(data_json, str) else data_json
+                        metadata_dict = json.loads(metadata_json) if isinstance(metadata_json, str) else (metadata_json or {})
+                        
+                        entry = DatabaseEntry(
+                            date=str(date_val),
+                            data_type=str(data_type_val),
+                            ticker=str(ticker_val),
+                            data=data_dict,
+                            created_at=str(created_at),
+                            updated_at=str(updated_at),
+                            expiry_date=str(expiry_date) if expiry_date else None,
+                            metadata=metadata_dict
+                        )
+                        entries.append(entry)
+                    except Exception as e:
+                        print(f"Error loading entry from {table_name}: {e}")
+                        continue
+            
+            cursor.close()
+            conn.close()
+            
+            # Sort all entries by date and apply limit if needed
+            entries.sort(key=lambda x: (x.date, x.created_at), reverse=True)
+            if limit:
+                entries = entries[:limit]
+            
+            return entries
+            
+        except Exception as e:
+            print(f"Error querying database: {e}")
+            return []
+    
+    def delete(self, date_str: str, data_type: str, ticker: str) -> bool:
+        """Delete entry by date, type, and ticker"""
+        try:
+            # Generate key
+            key_string = f"{date_str}_{data_type}_{ticker}"
+            entry_key = hashlib.md5(key_string.encode()).hexdigest()
+            
+            table_name = self._get_table_name(data_type)
+            
+            conn = self._create_connection()
+            if not conn:
+                return False
+            cursor = conn.cursor()
+            
+            cursor.execute(f'DELETE FROM {table_name} WHERE entry_key = %s', (entry_key,))
+            conn.commit()
+            
+            conn.close()
+            return True
+            
+        except Exception as e:
+            print(f"Error deleting entry: {e}")
+            return False
+    
+    def clean_expired(self) -> int:
+        """Remove expired entries"""
+        try:
+            conn = self._create_connection()
+            if not conn:
+                return 0
+            cursor = conn.cursor()
+            
+            total_cleaned = 0
+            
+            for table_name in ['calendar', 'news', 'fundamental_analysis']:
+                cursor.execute(f'''
+                    DELETE FROM {table_name} 
+                    WHERE expiry_date IS NOT NULL AND expiry_date < %s
+                ''', (datetime.now().date().isoformat(),))
+                total_cleaned += cursor.rowcount
+            
+            conn.commit()
+            conn.close()
+            
+            print(f"✓ Cleaned {total_cleaned} expired entries")
+            return total_cleaned
+            
+        except Exception as e:
+            print(f"Error cleaning expired entries: {e}")
+            return 0
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get database statistics across all tables"""
+        try:
+            conn = self._create_connection()
+            if not conn:
+                return {}
+            cursor = conn.cursor()
+            
+            # Initialize counters
+            total_entries = 0
+            by_type = {}
+            all_tickers = {}
+            total_size = 0
+            expired_count = 0
+            min_date = None
+            max_date = None
+            
+            # Query each table
+            for table_name in ['calendar', 'news', 'fundamental_analysis']:
+                # Count entries
+                cursor.execute(f'SELECT COUNT(*) FROM {table_name}')
+                table_count = cursor.fetchone()[0]
+                total_entries += table_count
+                
+                if table_name == 'calendar':
+                    # Get counts by event_type
+                    cursor.execute('SELECT event_type, COUNT(*) FROM calendar GROUP BY event_type')
+                    for event_type, count in cursor.fetchall():
+                        by_type[event_type] = count
+                else:
+                    # For news and fundamental_analysis, use table name as type
+                    by_type[table_name] = table_count
+                
+                # Get ticker counts
+                cursor.execute(f'SELECT ticker, COUNT(*) FROM {table_name} GROUP BY ticker')
+                for ticker, count in cursor.fetchall():
+                    all_tickers[ticker] = all_tickers.get(ticker, 0) + count
+                
+                # Get data size
+                cursor.execute(f'SELECT SUM(LENGTH(data)) FROM {table_name}')
+                table_size = cursor.fetchone()[0] or 0
+                total_size += table_size
+                
+                # Count expired entries
+                cursor.execute(f'''
+                    SELECT COUNT(*) FROM {table_name} 
+                    WHERE expiry_date IS NOT NULL AND expiry_date < %s
+                ''', (datetime.now().date().isoformat(),))
+                expired_count += cursor.fetchone()[0]
+                
+                # Get date range
+                cursor.execute(f'SELECT MIN(date), MAX(date) FROM {table_name}')
+                table_date_range = cursor.fetchone()
+                if table_date_range[0]:
+                    if min_date is None or table_date_range[0] < min_date:
+                        min_date = table_date_range[0]
+                    if max_date is None or table_date_range[1] > max_date:
+                        max_date = table_date_range[1]
+            
+            # Get top 10 tickers
+            top_tickers = dict(sorted(all_tickers.items(), key=lambda x: x[1], reverse=True)[:10])
+            
+            conn.close()
+            
+            stats = {
+                'total_entries': total_entries,
+                'by_type': by_type,
+                'top_tickers': top_tickers,
+                'total_size_bytes': total_size,
+                'total_size_mb': round(total_size / (1024 * 1024), 2),
+                'expired_entries': expired_count,
+                'date_range': {'from': str(min_date), 'to': str(max_date)} if min_date else None,
+                'compression': 'enabled' if self.compress else 'disabled'
+            }
+            
+            return stats
+            
+        except Exception as e:
+            print(f"Error getting stats: {e}")
+            return {}
+    
+    def clear_all(self) -> bool:
+        """Clear all data (use with caution!)"""
+        try:
+            conn = self._create_connection()
+            if not conn:
+                return False
+            cursor = conn.cursor()
+            
+            # Truncate all tables
+            for table_name in ['calendar', 'news', 'fundamental_analysis', 'signals']:
+                cursor.execute(f'TRUNCATE TABLE {table_name}')
+            
+            conn.commit()
+            conn.close()
+            
+            print("✓ All data cleared")
+            return True
+            
+        except Exception as e:
+            print(f"Error clearing data: {e}")
+            return False
+
+
+# Global database instance
+db_instance = None
+
+
+def get_database(db_dir: str = "database", compress: bool = False) -> LocalDatabase:
+    """Get or create database instance"""
+    global db_instance
+    if db_instance is None or db_instance.db_dir != Path(db_dir):
+        db_instance = LocalDatabase(db_dir=db_dir, compress=compress)
+    return db_instance

src/db/migrate_local_to_tidb.py

@@ -0,0 +1,132 @@
+import mysql.connector
+from mysql.connector import Error
+import os
+from dotenv import load_dotenv
+from pathlib import Path
+import sys
+
+# Add src to path to import if needed, though we'll use raw connections
+sys.path.append(str(Path(__file__).parent.parent.parent))
+
+def create_source_connection():
+    """Connect to local MySQL database"""
+    try:
+        config = {
+            'host': 'localhost',
+            'user': 'root',
+            'password': '1234',
+            'database': 'gotti'
+        }
+        conn = mysql.connector.connect(**config)
+        print("✅ Connected to source (local) database")
+        return conn
+    except Error as e:
+        print(f"❌ Error connecting to source database: {e}")
+        return None
+
+def create_dest_connection():
+    """Connect to destination TiDB database"""
+    try:
+        load_dotenv(override=True)
+        
+        config = {
+            'host': os.getenv('DB_HOST'),
+            'user': os.getenv('DB_USERNAME'),
+            'password': os.getenv('DB_PASSWORD'),
+            'database': os.getenv('DB_DATABASE'),
+            'port': int(os.getenv('DB_PORT', 4000))
+        }
+        
+        ssl_ca = os.getenv('DB_SSL_CA')
+        if ssl_ca:
+            project_root = Path(__file__).parent.parent.parent
+            ssl_ca_path = project_root / ssl_ca
+            if ssl_ca_path.exists():
+                config['ssl_ca'] = str(ssl_ca_path)
+                config['ssl_verify_cert'] = True
+                config['ssl_verify_identity'] = True
+        
+        conn = mysql.connector.connect(**config)
+        print("✅ Connected to destination (TiDB) database")
+        return conn
+    except Error as e:
+        print(f"❌ Error connecting to destination database: {e}")
+        return None
+
+def migrate_table(source_conn, dest_conn, table_name):
+    """Migrate a single table from source to destination"""
+    print(f"\nMigrating table: {table_name}...")
+    
+    try:
+        source_cursor = source_conn.cursor(dictionary=True)
+        dest_cursor = dest_conn.cursor()
+        
+        # Check if table exists in source
+        try:
+            source_cursor.execute(f"SELECT * FROM {table_name}")
+            rows = source_cursor.fetchall()
+        except Error as e:
+            print(f"⚠️  Skipping {table_name}: {e}")
+            return
+
+        if not rows:
+            print(f"ℹ️  Table {table_name} is empty.")
+            return
+
+        print(f"Found {len(rows)} rows in {table_name}.")
+        
+        # Get column names
+        columns = list(rows[0].keys())
+        placeholders = ', '.join(['%s'] * len(columns))
+        columns_str = ', '.join(columns)
+        
+        insert_query = f"""
+            INSERT INTO {table_name} ({columns_str}) 
+            VALUES ({placeholders})
+            ON DUPLICATE KEY UPDATE 
+            {', '.join([f"{col}=VALUES({col})" for col in columns])}
+        """
+        
+        # Batch insert
+        batch_size = 100
+        for i in range(0, len(rows), batch_size):
+            batch = rows[i:i+batch_size]
+            values = [tuple(row[col] for col in columns) for row in batch]
+            try:
+                dest_cursor.executemany(insert_query, values)
+                dest_conn.commit()
+                print(f"  Migrated {min(i+batch_size, len(rows))}/{len(rows)} rows...")
+            except Error as e:
+                print(f"❌ Error inserting batch: {e}")
+        
+        print(f"✅ Successfully migrated {table_name}")
+        
+    except Error as e:
+        print(f"❌ Error migrating {table_name}: {e}")
+    finally:
+        if 'source_cursor' in locals():
+            source_cursor.close()
+        if 'dest_cursor' in locals():
+            dest_cursor.close()
+
+def main():
+    print("🚀 Starting migration from Local MySQL to TiDB Cloud...")
+    
+    source_conn = create_source_connection()
+    dest_conn = create_dest_connection()
+    
+    if not source_conn or not dest_conn:
+        print("❌ Could not establish both connections. Aborting.")
+        return
+    
+    tables = ['available_tickers', 'calendar', 'news', 'fundamental_analysis', 'signals']
+    
+    for table in tables:
+        migrate_table(source_conn, dest_conn, table)
+    
+    source_conn.close()
+    dest_conn.close()
+    print("\n✨ Migration completed!")
+
+if __name__ == "__main__":
+    main()

src/db/verify_migration.py

@@ -0,0 +1,22 @@
+import sys
+from pathlib import Path
+sys.path.append(str(Path(__file__).parent.parent.parent))
+from src.db.local_database import LocalDatabase
+
+def verify():
+    print("🔍 Verifying data access via LocalDatabase (TiDB)...")
+    db = LocalDatabase()
+    
+    stats = db.get_stats()
+    print("\nDatabase Statistics:")
+    print(f"Total Entries: {stats.get('total_entries')}")
+    print(f"By Type: {stats.get('by_type')}")
+    print(f"Top Tickers: {stats.get('top_tickers')}")
+    
+    if stats.get('total_entries', 0) > 0:
+        print("\n✅ Verification Successful: Data is accessible!")
+    else:
+        print("\n❌ Verification Failed: No data found.")
+
+if __name__ == "__main__":
+    verify()

src/fundamental_analysis/calculator.py

@@ -0,0 +1,610 @@
+"""
+Stock Metrics Calculator
+Combines all individual metric functions and fetches data from yfinance
+Returns comprehensive DataFrame with all calculated metrics
+"""
+
+import yfinance as yf
+import pandas as pd
+import numpy as np
+from typing import Dict, List, Optional, Tuple
+from datetime import datetime
+import warnings
+warnings.filterwarnings('ignore')
+
+# Import all metric calculation functions
+from fundamental_analysis.metrics import *
+
+
+class StockMetricsCalculator:
+    """Calculate comprehensive metrics for a single stock"""
+    
+    def __init__(self, ticker: str):
+        """
+        Initialize calculator for a ticker
+        
+        Args:
+            ticker: Stock ticker symbol (e.g., 'AAPL')
+        """
+        self.ticker = ticker.upper()
+        self.stock = yf.Ticker(self.ticker)
+        self.data_fetched = False
+        self.missing_metrics = []
+        
+        # Raw data containers
+        self.info = {}
+        self.financials = {}
+        self.balance_sheet = {}
+        self.cashflow = {}
+        self.quarterly_financials = {}
+        self.quarterly_balance = {}
+        self.quarterly_cashflow = {}
+        
+    def fetch_data(self) -> bool:
+        """
+        Fetch all available data from yfinance
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            # Get company info
+            self.info = self.stock.info
+            
+            # Get financial statements
+            self.financials = self.stock.financials
+            self.balance_sheet = self.stock.balance_sheet
+            self.cashflow = self.stock.cashflow
+            
+            # Get quarterly statements
+            self.quarterly_financials = self.stock.quarterly_financials
+            self.quarterly_balance = self.stock.quarterly_balance_sheet
+            self.quarterly_cashflow = self.stock.quarterly_cashflow
+            
+            self.data_fetched = True
+            print(f"✓ Data fetched successfully for {self.ticker}")
+            return True
+            
+        except Exception as e:
+            print(f"✗ Error fetching data for {self.ticker}: {str(e)}")
+            return False
+    
+    def _get_from_statement(self, statement: pd.DataFrame, key: str, period: int = 0) -> Optional[float]:
+        """
+        Safely get value from financial statement
+        
+        Args:
+            statement: DataFrame from yfinance
+            key: Row name to extract
+            period: Column index (0 = most recent)
+        
+        Returns:
+            Value or None if not found
+        """
+        try:
+            if statement.empty:
+                return None
+            if key in statement.index:
+                values = statement.loc[key]
+                if not values.empty and period < len(values):
+                    val = values.iloc[period]
+                    return float(val) if pd.notna(val) else None
+            return None
+        except:
+            return None
+    
+    def _calculate_ttm(self, quarterly_statement: pd.DataFrame, key: str) -> Optional[float]:
+        """Calculate TTM (Trailing Twelve Months) from quarterly data"""
+        try:
+            if quarterly_statement.empty or key not in quarterly_statement.index:
+                return None
+            values = quarterly_statement.loc[key].iloc[:4]  # Last 4 quarters
+            values = values.replace({"-": None})
+            values = values.dropna()
+            if len(values) == 4 and values.notna().all():
+                return float(values.sum())
+            return None
+        except:
+            return None
+    
+    def calculate_all_metrics(self) -> pd.DataFrame:
+        """
+        Calculate all available metrics
+        
+        Returns:
+            DataFrame with metric names, values, formulas, and status
+        """
+        if not self.data_fetched:
+            self.fetch_data()
+        
+        metrics_data = []
+        
+        # ============================================================================
+        # EXTRACT RAW DATA
+        # ============================================================================
+        
+        print("\nExtracting raw financial data...")
+        
+        # Price and shares
+        price = self.info.get('currentPrice') or self.info.get('regularMarketPrice')
+        diluted_shares = self.info.get('sharesOutstanding')
+        
+        # Income statement (use TTM when available)
+        revenue = self._calculate_ttm(self.quarterly_financials, 'Total Revenue') or \
+                  self._get_from_statement(self.financials, 'Total Revenue')
+        revenue_prior = self._get_from_statement(self.financials, 'Total Revenue', 1)
+        
+        cogs = self._calculate_ttm(self.quarterly_financials, 'Cost Of Revenue') or \
+               self._get_from_statement(self.financials, 'Cost Of Revenue')
+        
+        gross_profit = self._calculate_ttm(self.quarterly_financials, 'Gross Profit') or \
+                       self._get_from_statement(self.financials, 'Gross Profit')
+        
+        ebit = self._calculate_ttm(self.quarterly_financials, 'EBIT') or \
+               self._get_from_statement(self.financials, 'EBIT')
+        
+        ebitda = self.info.get('ebitda') or \
+                 self._calculate_ttm(self.quarterly_financials, 'EBITDA') or \
+                 self._get_from_statement(self.financials, 'EBITDA')
+        
+        net_income = self._calculate_ttm(self.quarterly_financials, 'Net Income') or \
+                     self._get_from_statement(self.financials, 'Net Income')
+        net_income_prior = self._get_from_statement(self.financials, 'Net Income', 1)
+        
+        interest_expense = abs(self._calculate_ttm(self.quarterly_financials, 'Interest Expense') or \
+                              self._get_from_statement(self.financials, 'Interest Expense') or 0)
+        
+        # EPS
+        eps_ttm = self.info.get('trailingEps')
+        eps_forward = self.info.get('forwardEps')
+        eps_prior = self.info.get('trailingEps')  # Would need historical data for accurate prior
+        
+        # Balance sheet
+        total_assets = self._get_from_statement(self.balance_sheet, 'Total Assets')
+        current_assets = self._get_from_statement(self.balance_sheet, 'Current Assets')
+        current_liabilities = self._get_from_statement(self.balance_sheet, 'Current Liabilities')
+        
+        total_debt = self.info.get('totalDebt') or \
+                    (self._get_from_statement(self.balance_sheet, 'Long Term Debt') or 0) + \
+                    (self._get_from_statement(self.balance_sheet, 'Short Term Debt') or 0)
+        
+        cash = self._get_from_statement(self.balance_sheet, 'Cash And Cash Equivalents') or 0
+        cash_and_st_investments = self._get_from_statement(self.balance_sheet, 'Cash Cash Equivalents And Short Term Investments') or cash
+        
+        total_equity = self._get_from_statement(self.balance_sheet, 'Total Equity Gross Minority Interest') or \
+                      self._get_from_statement(self.balance_sheet, 'Stockholders Equity')
+        total_equity_prior = self._get_from_statement(self.balance_sheet, 'Stockholders Equity', 1)
+        
+        receivables = self._get_from_statement(self.balance_sheet, 'Receivables') or 0
+        inventory = self._get_from_statement(self.balance_sheet, 'Inventory') or 0
+        
+        book_value_per_share = self.info.get('bookValue')
+        
+        # Cash flow
+        cfo = self._calculate_ttm(self.quarterly_cashflow, 'Operating Cash Flow') or \
+              self._get_from_statement(self.cashflow, 'Operating Cash Flow')
+        
+        capex = abs(self._calculate_ttm(self.quarterly_cashflow, 'Capital Expenditure') or \
+                   self._get_from_statement(self.cashflow, 'Capital Expenditure') or 0)
+        
+        dividends_paid = abs(self._get_from_statement(self.cashflow, 'Cash Dividends Paid') or 0)
+        stock_repurchased = abs(self._get_from_statement(self.cashflow, 'Repurchase Of Capital Stock') or 0)
+        
+        # Tax rate
+        tax_rate = self.info.get('effectiveTaxRate') or 0.21  # Default to 21% if not available
+        
+        # Growth rates
+        earnings_growth = self.info.get('earningsGrowth') or 0
+        revenue_growth_rate = self.info.get('revenueGrowth') or 0
+        
+        # ============================================================================
+        # CALCULATE DERIVED VALUES
+        # ============================================================================
+        
+        # Market cap and EV
+        market_cap = calculate_market_cap(price, diluted_shares) if (price and diluted_shares) else self.info.get('marketCap')
+        enterprise_value = calculate_enterprise_value(market_cap, total_debt, cash) if market_cap else self.info.get('enterpriseValue')
+        
+        # Free cash flow
+        free_cash_flow = calculate_free_cash_flow(cfo, capex) if cfo else None
+        
+        # Averages for ratio calculations
+        avg_equity = calculate_average(total_equity, total_equity_prior) if (total_equity and total_equity_prior) else total_equity
+        
+        # Invested capital
+        invested_capital = calculate_invested_capital(total_equity, total_debt, cash) if (total_equity and total_debt) else None
+        
+        # ============================================================================
+        # CALCULATE ALL METRICS
+        # ============================================================================
+        
+        print("Calculating metrics...")
+        
+        # --- 1. VALUATION METRICS ---
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'Market Capitalization',
+            'Value': market_cap,
+            'Formula': 'Price × Diluted Shares',
+            'Status': 'Available' if market_cap else 'Missing'
+        })
+        
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'Enterprise Value (EV)',
+            'Value': enterprise_value,
+            'Formula': 'Market Cap + Total Debt - Cash',
+            'Status': 'Available' if enterprise_value else 'Missing'
+        })
+        
+        pe_ratio = calculate_pe_ratio(price, eps_ttm)
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'P/E Ratio (TTM)',
+            'Value': pe_ratio,
+            'Formula': 'Price / EPS',
+            'Status': 'Available' if pe_ratio else 'Missing',
+            'Threshold': '< sector median = undervalued'
+        })
+        
+        pe_forward = calculate_pe_ratio(price, eps_forward)
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'P/E Ratio (Forward)',
+            'Value': pe_forward,
+            'Formula': 'Price / Forward EPS',
+            'Status': 'Available' if pe_forward else 'Missing',
+            'Threshold': 'Use for valuation comparisons'
+        })
+        
+        peg_ratio = calculate_peg_ratio(pe_forward or pe_ratio, earnings_growth)
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'PEG Ratio',
+            'Value': peg_ratio,
+            'Formula': 'P/E / (EPS Growth % × 100)',
+            'Status': 'Available' if peg_ratio else 'Missing',
+            'Threshold': '< 0.8 = BUY, 0.8-1.2 = HOLD, > 1.5 = SELL'
+        })
+        
+        ev_ebitda = calculate_ev_ebitda(enterprise_value, ebitda)
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'EV/EBITDA',
+            'Value': ev_ebitda,
+            'Formula': 'Enterprise Value / EBITDA',
+            'Status': 'Available' if ev_ebitda else 'Missing',
+            'Threshold': 'Compare to sector median'
+        })
+        
+        price_to_fcf = calculate_price_to_fcf(market_cap, free_cash_flow)
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'Price / FCF',
+            'Value': price_to_fcf,
+            'Formula': 'Market Cap / Free Cash Flow',
+            'Status': 'Available' if price_to_fcf else 'Missing'
+        })
+        
+        fcf_yield_eq = calculate_fcf_yield_equity(free_cash_flow, market_cap)
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'FCF Yield (Equity) %',
+            'Value': fcf_yield_eq,
+            'Formula': '(FCF / Market Cap) × 100',
+            'Status': 'Available' if fcf_yield_eq else 'Missing',
+            'Threshold': '> 6% = BUY, 4-6% = HOLD, < 3% = SELL',
+            'Priority': 'HIGHEST'
+        })
+        
+        fcf_yield_ev = calculate_fcf_yield_enterprise(free_cash_flow, enterprise_value)
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'FCF Yield (Enterprise) %',
+            'Value': fcf_yield_ev,
+            'Formula': '(FCF / EV) × 100',
+            'Status': 'Available' if fcf_yield_ev else 'Missing',
+            'Threshold': '> 6% = BUY (preferred metric)',
+            'Priority': 'HIGHEST'
+        })
+        
+        pb_ratio = calculate_price_to_book(price, book_value_per_share)
+        metrics_data.append({
+            'Category': 'Valuation',
+            'Metric': 'Price / Book',
+            'Value': pb_ratio,
+            'Formula': 'Price / Book Value per Share',
+            'Status': 'Available' if pb_ratio else 'Missing'
+        })
+        
+        # --- 2. PROFITABILITY & MARGINS ---
+        gross_margin = calculate_gross_margin(revenue, cogs)
+        metrics_data.append({
+            'Category': 'Profitability',
+            'Metric': 'Gross Margin %',
+            'Value': gross_margin,
+            'Formula': '((Revenue - COGS) / Revenue) × 100',
+            'Status': 'Available' if gross_margin else 'Missing',
+            'Threshold': '> 40% good, > 60% excellent'
+        })
+        
+        ebitda_margin = calculate_ebitda_margin(ebitda, revenue)
+        metrics_data.append({
+            'Category': 'Profitability',
+            'Metric': 'EBITDA Margin %',
+            'Value': ebitda_margin,
+            'Formula': '(EBITDA / Revenue) × 100',
+            'Status': 'Available' if ebitda_margin else 'Missing',
+            'Threshold': '> 20% excellent'
+        })
+        
+        ebit_margin = calculate_ebit_margin(ebit, revenue)
+        metrics_data.append({
+            'Category': 'Profitability',
+            'Metric': 'EBIT Margin %',
+            'Value': ebit_margin,
+            'Formula': '(EBIT / Revenue) × 100',
+            'Status': 'Available' if ebit_margin else 'Missing'
+        })
+        
+        net_margin = calculate_net_margin(net_income, revenue)
+        metrics_data.append({
+            'Category': 'Profitability',
+            'Metric': 'Net Margin %',
+            'Value': net_margin,
+            'Formula': '(Net Income / Revenue) × 100',
+            'Status': 'Available' if net_margin else 'Missing',
+            'Threshold': '> 10% good'
+        })
+        
+        # --- 3. CASH FLOW METRICS ---
+        metrics_data.append({
+            'Category': 'Cash Flow',
+            'Metric': 'Free Cash Flow',
+            'Value': free_cash_flow,
+            'Formula': 'CFO - CapEx',
+            'Status': 'Available' if free_cash_flow else 'Missing',
+            'Threshold': 'Must be positive',
+            'Priority': 'CRITICAL'
+        })
+        
+        fcf_per_share = calculate_fcf_per_share(free_cash_flow, diluted_shares)
+        metrics_data.append({
+            'Category': 'Cash Flow',
+            'Metric': 'FCF per Share',
+            'Value': fcf_per_share,
+            'Formula': 'FCF / Diluted Shares',
+            'Status': 'Available' if fcf_per_share else 'Missing'
+        })
+        
+        cash_conversion = calculate_cash_conversion(cfo, net_income)
+        metrics_data.append({
+            'Category': 'Cash Flow',
+            'Metric': 'Cash Conversion Ratio',
+            'Value': cash_conversion,
+            'Formula': 'CFO / Net Income',
+            'Status': 'Available' if cash_conversion else 'Missing',
+            'Threshold': '> 1.0 = quality earnings, < 1.0 RED FLAG',
+            'Priority': 'HIGH'
+        })
+        
+        # --- 4. LIQUIDITY & SOLVENCY ---
+        current_ratio = calculate_current_ratio(current_assets, current_liabilities)
+        metrics_data.append({
+            'Category': 'Liquidity',
+            'Metric': 'Current Ratio',
+            'Value': current_ratio,
+            'Formula': 'Current Assets / Current Liabilities',
+            'Status': 'Available' if current_ratio else 'Missing',
+            'Threshold': '> 1.5 good'
+        })
+        
+        quick_ratio = calculate_quick_ratio(cash, 0, receivables, current_liabilities)
+        metrics_data.append({
+            'Category': 'Liquidity',
+            'Metric': 'Quick Ratio',
+            'Value': quick_ratio,
+            'Formula': '(Cash + Receivables) / Current Liabilities',
+            'Status': 'Available' if quick_ratio else 'Missing'
+        })
+        
+        net_debt_ebitda = calculate_net_debt_to_ebitda(total_debt, cash, ebitda)
+        metrics_data.append({
+            'Category': 'Solvency',
+            'Metric': 'Net Debt / EBITDA',
+            'Value': net_debt_ebitda,
+            'Formula': '(Total Debt - Cash) / EBITDA',
+            'Status': 'Available' if net_debt_ebitda else 'Missing',
+            'Threshold': '< 1 = Low risk, 1-3 = Moderate, > 3 = High risk',
+            'Priority': 'HIGH'
+        })
+        
+        interest_cov = calculate_interest_coverage(ebit, interest_expense)
+        metrics_data.append({
+            'Category': 'Solvency',
+            'Metric': 'Interest Coverage',
+            'Value': interest_cov,
+            'Formula': 'EBIT / Interest Expense',
+            'Status': 'Available' if interest_cov else 'Missing',
+            'Threshold': '> 3x safe, < 2x risky'
+        })
+        
+        debt_to_equity = calculate_debt_to_equity(total_debt, total_equity)
+        metrics_data.append({
+            'Category': 'Solvency',
+            'Metric': 'Debt / Equity',
+            'Value': debt_to_equity,
+            'Formula': 'Total Debt / Total Equity',
+            'Status': 'Available' if debt_to_equity else 'Missing'
+        })
+        
+        # --- 5. RETURNS & EFFICIENCY ---
+        roe = calculate_roe(net_income, avg_equity)
+        metrics_data.append({
+            'Category': 'Returns',
+            'Metric': 'Return on Equity (ROE) %',
+            'Value': roe,
+            'Formula': '(Net Income / Avg Equity) × 100',
+            'Status': 'Available' if roe else 'Missing',
+            'Threshold': '> 15% good, > 20% excellent',
+            'Priority': 'VERY HIGH'
+        })
+        
+        roa = calculate_roa(net_income, total_assets)
+        metrics_data.append({
+            'Category': 'Returns',
+            'Metric': 'Return on Assets (ROA) %',
+            'Value': roa,
+            'Formula': '(Net Income / Total Assets) × 100',
+            'Status': 'Available' if roa else 'Missing'
+        })
+        
+        roic = calculate_roic(ebit, tax_rate, invested_capital)
+        metrics_data.append({
+            'Category': 'Returns',
+            'Metric': 'Return on Invested Capital (ROIC) %',
+            'Value': roic,
+            'Formula': '(EBIT × (1 - Tax Rate) / Invested Capital) × 100',
+            'Status': 'Available' if roic else 'Missing',
+            'Threshold': '> 10% good, > 15% excellent',
+            'Priority': 'VERY HIGH - Best quality indicator'
+        })
+        
+        # --- 6. GROWTH METRICS ---
+        rev_growth = calculate_revenue_growth(revenue, revenue_prior)
+        metrics_data.append({
+            'Category': 'Growth',
+            'Metric': 'Revenue Growth (YoY) %',
+            'Value': rev_growth or (revenue_growth_rate * 100),
+            'Formula': '((Current Rev - Prior Rev) / Prior Rev) × 100',
+            'Status': 'Available' if (rev_growth or revenue_growth_rate) else 'Missing',
+            'Threshold': '> 10% good, > 20% excellent'
+        })
+        
+        eps_growth_calc = calculate_eps_growth(eps_ttm, eps_prior)
+        metrics_data.append({
+            'Category': 'Growth',
+            'Metric': 'EPS Growth (YoY) %',
+            'Value': eps_growth_calc or (earnings_growth * 100),
+            'Formula': '((Current EPS - Prior EPS) / Prior EPS) × 100',
+            'Status': 'Available' if (eps_growth_calc or earnings_growth) else 'Missing',
+            'Priority': 'HIGH'
+        })
+        
+        # --- 7. CAPITAL ALLOCATION ---
+        payout_ratio = calculate_payout_ratio(dividends_paid, net_income)
+        metrics_data.append({
+            'Category': 'Capital Allocation',
+            'Metric': 'Payout Ratio %',
+            'Value': payout_ratio,
+            'Formula': '(Dividends / Net Income) × 100',
+            'Status': 'Available' if payout_ratio else 'Missing',
+            'Threshold': '< 60% sustainable'
+        })
+        
+        buyback_yield = calculate_buyback_yield(stock_repurchased, market_cap)
+        metrics_data.append({
+            'Category': 'Capital Allocation',
+            'Metric': 'Buyback Yield %',
+            'Value': buyback_yield,
+            'Formula': '(Buyback Cash / Market Cap) × 100',
+            'Status': 'Available' if buyback_yield else 'Missing'
+        })
+        
+        total_payout = calculate_total_payout_ratio(dividends_paid, stock_repurchased, net_income)
+        metrics_data.append({
+            'Category': 'Capital Allocation',
+            'Metric': 'Total Payout Ratio %',
+            'Value': total_payout,
+            'Formula': '((Dividends + Buybacks) / Net Income) × 100',
+            'Status': 'Available' if total_payout else 'Missing'
+        })
+        
+        # Create DataFrame
+        df = pd.DataFrame(metrics_data)
+        
+        # Track missing metrics
+        self.missing_metrics = df[df['Status'] == 'Missing']['Metric'].tolist()
+        
+        print(f"\n✓ Calculated {len(df)} metrics")
+        print(f"✓ Available: {len(df[df['Status'] == 'Available'])}")
+        print(f"✗ Missing: {len(self.missing_metrics)}")
+        
+        return df
+    
+    def get_summary_statistics(self, df: pd.DataFrame) -> Dict:
+        """Generate summary statistics about the metrics"""
+        total = len(df)
+        available = len(df[df['Status'] == 'Available'])
+        missing = total - available
+        
+        return {
+            'ticker': self.ticker,
+            'total_metrics': total,
+            'available_metrics': available,
+            'missing_metrics': missing,
+            'coverage_percentage': (available / total) * 100 if total > 0 else 0,
+            'missing_metric_list': self.missing_metrics
+        }
+
+
+def calculate_metrics_for_ticker(ticker: str) -> Tuple[pd.DataFrame, Dict]:
+    """
+    Main function to calculate all metrics for a ticker
+    
+    Args:
+        ticker: Stock ticker symbol
+    
+    Returns:
+        Tuple of (metrics_dataframe, summary_statistics)
+    """
+    calculator = StockMetricsCalculator(ticker)
+    
+    if not calculator.fetch_data():
+        return pd.DataFrame(), {}
+        
+    
+    metrics_df = calculator.calculate_all_metrics()
+    summary = calculator.get_summary_statistics(metrics_df)
+    
+    return metrics_df, summary
+
+
+if __name__ == "__main__":
+    # Test with a sample ticker
+    test_ticker = "AAPL"
+    print(f"Testing with {test_ticker}...")
+    print("=" * 80)
+    
+    metrics_df, summary = calculate_metrics_for_ticker(test_ticker)
+    
+    if not metrics_df.empty:
+        print("\n" + "=" * 80)
+        print("SUMMARY STATISTICS")
+        print("=" * 80)
+        for key, value in summary.items():
+            if key != 'missing_metric_list':
+                print(f"{key}: {value}")
+        
+        print("\n" + "=" * 80)
+        print("SAMPLE METRICS (First 10)")
+        print("=" * 80)
+        print(metrics_df[['Category', 'Metric', 'Value', 'Status']].head(10).to_string(index=False))
+        
+        print("\n" + "=" * 80)
+        print("HIGH PRIORITY METRICS")
+        print("=" * 80)
+        priority_metrics = metrics_df[metrics_df['Priority'].notna()][['Metric', 'Value', 'Threshold', 'Priority']]
+        print(priority_metrics.to_string(index=False))
+        
+        if summary['missing_metrics'] > 0:
+            print("\n" + "=" * 80)
+            print("MISSING METRICS")
+            print("=" * 80)
+            for metric in summary['missing_metric_list']:
+                print(f"  - {metric}")
+        
+        # Save to CSV
+        output_file = f"{test_ticker}_metrics.csv"
+        metrics_df.to_csv(output_file, index=False)
+        print(f"\n✓ Metrics saved to {output_file}")

src/fundamental_analysis/data_fetcher.py

@@ -0,0 +1,336 @@
+"""
+Enhanced financial data fetcher using yfinance.
+Collects company data, sector data, and peer comparison data.
+"""
+
+import yfinance as yf
+import pandas as pd
+import numpy as np
+from typing import Dict, List, Optional, Tuple
+from datetime import datetime
+import warnings
+warnings.filterwarnings('ignore')
+
+
+class FinancialDataFetcher:
+    """Comprehensive data fetcher for fundamental analysis"""
+    
+    def __init__(self, ticker: str):
+        """
+        Initialize fetcher for a ticker
+        
+        Args:
+            ticker: Stock ticker symbol
+        """
+        self.ticker = ticker.upper()
+        self.stock = yf.Ticker(self.ticker)
+        self.info = None
+        self.sector = None
+        self.industry = None
+        
+    def fetch_company_info(self) -> Dict:
+        """Fetch basic company information"""
+        try:
+            self.info = self.stock.info
+            self.sector = self.info.get('sector', 'Unknown')
+            self.industry = self.info.get('industry', 'Unknown')
+            
+            return {
+                'ticker': self.ticker,
+                'company_name': self.info.get('longName', self.ticker),
+                'sector': self.sector,
+                'industry': self.industry,
+                'market_cap': self.info.get('marketCap', 0),
+                'country': self.info.get('country', 'Unknown'),
+                'website': self.info.get('website', ''),
+                'business_summary': self.info.get('longBusinessSummary', '')
+            }
+        except Exception as e:
+            print(f"Error fetching company info: {e}")
+            return {}
+    
+    def fetch_financial_statements(self) -> Dict[str, pd.DataFrame]:
+        """Fetch all financial statements (annual)"""
+        try:
+            return {
+                'income_statement': self.stock.income_stmt,
+                'balance_sheet': self.stock.balance_sheet,
+                'cash_flow': self.stock.cashflow,
+                'quarterly_income': self.stock.quarterly_income_stmt,
+                'quarterly_balance': self.stock.quarterly_balance_sheet,
+                'quarterly_cashflow': self.stock.quarterly_cashflow
+            }
+        except Exception as e:
+            print(f"Error fetching financial statements: {e}")
+            return {}
+    
+    def fetch_key_metrics(self) -> Dict:
+        """Fetch key financial metrics and ratios"""
+        try:
+            info = self.info if self.info else self.stock.info
+            
+            return {
+                # Price metrics
+                'current_price': info.get('currentPrice', info.get('regularMarketPrice', 0)),
+                'previous_close': info.get('previousClose', 0),
+                '52_week_high': info.get('fiftyTwoWeekHigh', 0),
+                '52_week_low': info.get('fiftyTwoWeekLow', 0),
+                
+                # Valuation metrics
+                'market_cap': info.get('marketCap', 0),
+                'enterprise_value': info.get('enterpriseValue', 0),
+                'trailing_pe': info.get('trailingPE'),
+                'forward_pe': info.get('forwardPE'),
+                'peg_ratio': info.get('pegRatio'),
+                'price_to_book': info.get('priceToBook'),
+                'price_to_sales': info.get('priceToSalesTrailing12Months'),
+                'ev_to_revenue': info.get('enterpriseToRevenue'),
+                'ev_to_ebitda': info.get('enterpriseToEbitda'),
+                
+                # Profitability metrics
+                'profit_margin': info.get('profitMargins'),
+                'operating_margin': info.get('operatingMargins'),
+                'gross_margin': info.get('grossMargins'),
+                'ebitda_margin': self._calculate_ebitda_margin(info),
+                
+                # Returns
+                'return_on_assets': info.get('returnOnAssets'),
+                'return_on_equity': info.get('returnOnEquity'),
+                
+                # Growth
+                'revenue_growth': info.get('revenueGrowth'),
+                'earnings_growth': info.get('earningsGrowth'),
+                
+                # Financial health
+                'total_cash': info.get('totalCash', 0),
+                'total_debt': info.get('totalDebt', 0),
+                'debt_to_equity': info.get('debtToEquity'),
+                'current_ratio': info.get('currentRatio'),
+                'quick_ratio': info.get('quickRatio'),
+                
+                # Cash flow
+                'operating_cash_flow': info.get('operatingCashflow', 0),
+                'free_cash_flow': info.get('freeCashflow', 0),
+                
+                # Per share
+                'book_value_per_share': info.get('bookValue'),
+                'revenue_per_share': info.get('revenuePerShare'),
+                'eps_trailing': info.get('trailingEps'),
+                'eps_forward': info.get('forwardEps'),
+                
+                # Shares
+                'shares_outstanding': info.get('sharesOutstanding', 0),
+                
+                # Other
+                'beta': info.get('beta'),
+                'dividend_yield': info.get('dividendYield'),
+            }
+        except Exception as e:
+            print(f"Error fetching key metrics: {e}")
+            return {}
+    
+    def _calculate_ebitda_margin(self, info: Dict) -> Optional[float]:
+        """Calculate EBITDA margin if available"""
+        try:
+            ebitda = info.get('ebitda')
+            revenue = info.get('totalRevenue')
+            if ebitda and revenue and revenue > 0:
+                return ebitda / revenue
+        except:
+            pass
+        return None
+    
+    def fetch_peer_tickers(self, max_peers: int = 10) -> List[str]:
+        """
+        Fetch peer company tickers in the same sector/industry
+        
+        Args:
+            max_peers: Maximum number of peers to return
+            
+        Returns:
+            List of peer ticker symbols
+        """
+        try:
+            if not self.sector or self.sector == 'Unknown':
+                self.fetch_company_info()
+            
+            # Try to get recommendations which sometimes include peers
+            recommendations = self.stock.recommendations
+            peers = set()
+            
+            # Fallback: Use a simple sector-based approach
+            # In production, you'd use a proper database or API for peer identification
+            # For now, we'll return an empty list and let users provide peers manually
+            
+            return []
+            
+        except Exception as e:
+            print(f"Error fetching peer tickers: {e}")
+            return []
+    
+    def fetch_peer_data(self, peer_tickers: List[str]) -> Dict[str, Dict]:
+        """
+        Fetch key metrics for peer companies
+        
+        Args:
+            peer_tickers: List of peer ticker symbols
+            
+        Returns:
+            Dictionary mapping ticker to metrics
+        """
+        peer_data = {}
+        
+        for ticker in peer_tickers:
+            try:
+                print(f"Fetching data for peer: {ticker}")
+                peer_stock = yf.Ticker(ticker)
+                peer_info = peer_stock.info
+                
+                peer_data[ticker] = {
+                    'company_name': peer_info.get('longName', ticker),
+                    'market_cap': peer_info.get('marketCap', 0),
+                    'trailing_pe': peer_info.get('trailingPE'),
+                    'forward_pe': peer_info.get('forwardPE'),
+                    'peg_ratio': peer_info.get('pegRatio'),
+                    'price_to_book': peer_info.get('priceToBook'),
+                    'profit_margin': peer_info.get('profitMargins'),
+                    'operating_margin': peer_info.get('operatingMargins'),
+                    'gross_margin': peer_info.get('grossMargins'),
+                    'return_on_equity': peer_info.get('returnOnEquity'),
+                    'return_on_assets': peer_info.get('returnOnAssets'),
+                    'revenue_growth': peer_info.get('revenueGrowth'),
+                    'earnings_growth': peer_info.get('earningsGrowth'),
+                    'debt_to_equity': peer_info.get('debtToEquity'),
+                    'current_ratio': peer_info.get('currentRatio'),
+                    'free_cash_flow': peer_info.get('freeCashflow', 0),
+                    'beta': peer_info.get('beta'),
+                }
+            except Exception as e:
+                print(f"Error fetching data for {ticker}: {e}")
+                continue
+        
+        return peer_data
+    
+    def calculate_sector_metrics(self, peer_data: Dict[str, Dict]) -> Dict:
+        """
+        Calculate sector-wide metrics from peer data
+        
+        Args:
+            peer_data: Dictionary of peer metrics
+            
+        Returns:
+            Dictionary of sector averages/medians
+        """
+        if not peer_data:
+            return {}
+        
+        # Collect all metrics
+        metrics = {
+            'trailing_pe': [],
+            'forward_pe': [],
+            'peg_ratio': [],
+            'price_to_book': [],
+            'profit_margin': [],
+            'operating_margin': [],
+            'gross_margin': [],
+            'return_on_equity': [],
+            'return_on_assets': [],
+            'revenue_growth': [],
+            'earnings_growth': [],
+            'debt_to_equity': [],
+            'current_ratio': [],
+            'beta': []
+        }
+        
+        # Aggregate peer metrics
+        for ticker, data in peer_data.items():
+            for key in metrics.keys():
+                value = data.get(key)
+                if value is not None and not (isinstance(value, float) and np.isnan(value)):
+                    metrics[key].append(value)
+        
+        # Calculate sector statistics
+        sector_metrics = {}
+        for key, values in metrics.items():
+            if values:
+                sector_metrics[f'{key}_median'] = float(np.median(values))
+                sector_metrics[f'{key}_mean'] = float(np.mean(values))
+                sector_metrics[f'{key}_min'] = float(np.min(values))
+                sector_metrics[f'{key}_max'] = float(np.max(values))
+                sector_metrics[f'{key}_count'] = len(values)
+        
+        return sector_metrics
+    
+    def fetch_all_data(self, peer_tickers: Optional[List[str]] = None) -> Dict:
+        """
+        Fetch all data for comprehensive analysis
+        
+        Args:
+            peer_tickers: Optional list of peer tickers for comparison
+            
+        Returns:
+            Complete dataset
+        """
+        print(f"\n{'='*60}")
+        print(f"Fetching data for {self.ticker}...")
+        print(f"{'='*60}\n")
+        
+        # Company data
+        company_info = self.fetch_company_info()
+        print(f"✓ Company: {company_info.get('company_name', self.ticker)}")
+        print(f"✓ Sector: {company_info.get('sector', 'Unknown')}")
+        print(f"✓ Industry: {company_info.get('industry', 'Unknown')}\n")
+        
+        # Financial statements
+        print("Fetching financial statements...")
+        statements = self.fetch_financial_statements()
+        
+        # Key metrics
+        print("Fetching key metrics...")
+        metrics = self.fetch_key_metrics()
+        
+        # Peer data
+        peer_data = {}
+        sector_metrics = {}
+        
+        if peer_tickers:
+            print(f"\nFetching peer data for {len(peer_tickers)} companies...")
+            peer_data = self.fetch_peer_data(peer_tickers)
+            print(f"✓ Successfully fetched data for {len(peer_data)} peers")
+            
+            if peer_data:
+                print("Calculating sector metrics...")
+                sector_metrics = self.calculate_sector_metrics(peer_data)
+                print(f"✓ Sector metrics calculated\n")
+        
+        return {
+            'ticker': self.ticker,
+            'fetch_date': datetime.now().isoformat(),
+            'company_info': company_info,
+            'financial_statements': statements,
+            'metrics': metrics,
+            'peer_data': peer_data,
+            'sector_metrics': sector_metrics
+        }
+
+
+if __name__ == "__main__":
+    # Example usage
+    ticker = input("Enter ticker symbol: ").upper()
+    
+    fetcher = FinancialDataFetcher(ticker)
+    
+    # Ask for peer tickers
+    peers_input = input("Enter peer tickers (comma-separated, or press Enter to skip): ").strip()
+    peer_tickers = [p.strip().upper() for p in peers_input.split(',')] if peers_input else None
+    
+    data = fetcher.fetch_all_data(peer_tickers)
+    
+    print(f"\n{'='*60}")
+    print("DATA COLLECTION COMPLETE")
+    print(f"{'='*60}")
+    print(f"Company: {data['company_info'].get('company_name')}")
+    print(f"Metrics collected: {len([k for k, v in data['metrics'].items() if v is not None])}")
+    if data['peer_data']:
+        print(f"Peers analyzed: {len(data['peer_data'])}")
+        print(f"Sector metrics: {len(data['sector_metrics'])}")

src/fundamental_analysis/decision_engine.py

@@ -0,0 +1,542 @@
+"""
+Investment decision engine.
+Combines all analyses to generate BUY/SELL/HOLD recommendations.
+"""
+
+import numpy as np
+from typing import Dict, List, Tuple
+from datetime import datetime
+
+
+class InvestmentDecisionEngine:
+    """Generates investment recommendations based on comprehensive analysis"""
+    
+    def __init__(self, 
+                 financial_data: Dict,
+                 fundamental_analysis: Dict,
+                 sector_analysis: Dict,
+                 valuation_analysis: Dict):
+        """
+        Initialize decision engine
+        
+        Args:
+            financial_data: Raw financial data
+            fundamental_analysis: Results from FinancialAnalyzer
+            sector_analysis: Results from SectorAnalyzer
+            valuation_analysis: Results from ValuationEngine
+        """
+        self.ticker = financial_data.get('ticker')
+        self.company_info = financial_data.get('company_info', {})
+        self.current_price = financial_data.get('metrics', {}).get('current_price', 0)
+        
+        self.fundamental = fundamental_analysis
+        self.sector = sector_analysis
+        self.valuation = valuation_analysis
+        
+        self.score_weights = {
+            'fundamental': 0.35,
+            'sector': 0.25,
+            'valuation': 0.40
+        }
+    
+    def score_fundamentals(self) -> Dict:
+        """
+        Score company fundamentals (0-100)
+        
+        Returns:
+            Fundamental scores and assessment
+        """
+        scores = {}
+        
+        # Growth score (0-25)
+        growth = self.fundamental.get('growth_analysis', {})
+        growth_quality = growth.get('growth_quality', 'Insufficient Data')
+        growth_scores = {
+            'Strong': 25, 'Good': 18, 'Moderate': 12, 
+            'Weak': 5, 'Insufficient Data': 10
+        }
+        scores['growth'] = growth_scores.get(growth_quality, 10)
+        
+        # Margin score (0-25)
+        margins = self.fundamental.get('margin_analysis', {})
+        margin_quality = margins.get('margin_quality', 'Insufficient Data')
+        margin_scores = {
+            'Excellent': 25, 'Good': 18, 'Moderate': 12,
+            'Weak': 5, 'Insufficient Data': 10
+        }
+        scores['margins'] = margin_scores.get(margin_quality, 10)
+        
+        # Returns score (0-25)
+        returns = self.fundamental.get('returns_analysis', {})
+        returns_quality = returns.get('returns_quality', 'Insufficient Data')
+        returns_scores = {
+            'Excellent': 25, 'Good': 18, 'Moderate': 12,
+            'Weak': 5, 'Insufficient Data': 10
+        }
+        scores['returns'] = returns_scores.get(returns_quality, 10)
+        
+        # Cash flow score (0-25)
+        cash_flow = self.fundamental.get('cash_flow_analysis', {})
+        cf_quality = cash_flow.get('cash_flow_quality', 'Insufficient Data')
+        cf_scores = {
+            'Excellent': 25, 'Good': 18, 'Moderate': 12,
+            'Weak': 5, 'Negative': 0, 'Insufficient Data': 10
+        }
+        scores['cash_flow'] = cf_scores.get(cf_quality, 10)
+        
+        total_score = sum(scores.values())
+        
+        return {
+            'scores': scores,
+            'total': total_score,
+            'max': 100,
+            'percentage': total_score,
+            'grade': self._get_grade(total_score),
+            'assessment': self._assess_fundamentals(total_score)
+        }
+    
+    def score_sector_position(self) -> Dict:
+        """
+        Score company's position within sector (0-100)
+        
+        Returns:
+            Sector position scores and assessment
+        """
+        scores = {}
+        
+        # Sector sentiment (0-30)
+        sentiment = self.sector.get('sector_sentiment', {})
+        overall_sentiment = sentiment.get('overall_sentiment', 'Neutral')
+        
+        if 'Positive' in overall_sentiment or 'tailwinds' in overall_sentiment:
+            scores['sector_sentiment'] = 30
+        elif 'Negative' in overall_sentiment or 'headwinds' in overall_sentiment:
+            scores['sector_sentiment'] = 10
+        else:
+            scores['sector_sentiment'] = 20
+        
+        # Competitive position (0-35)
+        ranking = self.sector.get('sector_ranking', {})
+        overall_position = ranking.get('overall_position', 'Unknown')
+        
+        position_scores = {
+            'Top 20%': 35, 'Top 40%': 25, 'Middle': 18,
+            'Bottom 40%': 10, 'Bottom 20%': 5, 'Unknown': 18
+        }
+        scores['competitive_position'] = position_scores.get(overall_position, 18)
+        
+        # Relative profitability (0-20)
+        profitability_comp = self.sector.get('profitability_comparison', {})
+        prof_vs_sector = profitability_comp.get('profitability_vs_sector', 'Unknown')
+        
+        prof_scores = {
+            'Top Performer': 20, 'Above Average': 15, 
+            'Below Average': 8, 'Bottom Performer': 3, 'Unknown': 10
+        }
+        scores['relative_profitability'] = prof_scores.get(prof_vs_sector, 10)
+        
+        # Relative growth (0-15)
+        growth_comp = self.sector.get('growth_comparison', {})
+        growth_vs_sector = growth_comp.get('growth_vs_sector', 'Unknown')
+        
+        growth_scores = {
+            'Fast Grower': 15, 'Above Average Growth': 11,
+            'Below Average Growth': 6, 'Lagging Sector': 2, 'Unknown': 8
+        }
+        scores['relative_growth'] = growth_scores.get(growth_vs_sector, 8)
+        
+        total_score = sum(scores.values())
+        
+        return {
+            'scores': scores,
+            'total': total_score,
+            'max': 100,
+            'percentage': total_score,
+            'grade': self._get_grade(total_score),
+            'assessment': self._assess_sector_position(total_score, overall_sentiment)
+        }
+    
+    def score_valuation(self) -> Dict:
+        """
+        Score valuation attractiveness (0-100)
+        
+        Returns:
+            Valuation scores and assessment
+        """
+        scores = {}
+        
+        # DCF valuation (0-40)
+        dcf = self.valuation.get('dcf_valuation', {})
+        dcf_upside = dcf.get('upside_percent', 0)
+        
+        if 'error' not in dcf:
+            if dcf_upside > 30:
+                scores['dcf'] = 40
+            elif dcf_upside > 15:
+                scores['dcf'] = 30
+            elif dcf_upside > 0:
+                scores['dcf'] = 20
+            elif dcf_upside > -15:
+                scores['dcf'] = 10
+            else:
+                scores['dcf'] = 0
+        else:
+            scores['dcf'] = 20  # Neutral if DCF not applicable
+        
+        # Relative valuation (0-40)
+        relative = self.valuation.get('relative_valuation', {})
+        avg_upside = relative.get('average_upside', 0)
+        
+        if avg_upside != 0:
+            if avg_upside > 25:
+                scores['relative'] = 40
+            elif avg_upside > 10:
+                scores['relative'] = 30
+            elif avg_upside > 0:
+                scores['relative'] = 20
+            elif avg_upside > -15:
+                scores['relative'] = 10
+            else:
+                scores['relative'] = 0
+        else:
+            scores['relative'] = 20  # Neutral if not available
+        
+        # Margin of safety (0-20)
+        mos = self.valuation.get('margin_of_safety', {})
+        dcf_mos = mos.get('dcf_margin_of_safety', {})
+        mos_percent = dcf_mos.get('margin_percent', 0)
+        
+        if mos_percent > 30:
+            scores['margin_of_safety'] = 20
+        elif mos_percent > 20:
+            scores['margin_of_safety'] = 15
+        elif mos_percent > 10:
+            scores['margin_of_safety'] = 10
+        elif mos_percent > 0:
+            scores['margin_of_safety'] = 5
+        else:
+            scores['margin_of_safety'] = 0
+        
+        total_score = sum(scores.values())
+        
+        return {
+            'scores': scores,
+            'total': total_score,
+            'max': 100,
+            'percentage': total_score,
+            'grade': self._get_grade(total_score),
+            'assessment': self._assess_valuation(total_score)
+        }
+    
+    def calculate_overall_score(self) -> Dict:
+        """
+        Calculate weighted overall investment score
+        
+        Returns:
+            Overall score and breakdown
+        """
+        fundamental_score = self.score_fundamentals()
+        sector_score = self.score_sector_position()
+        valuation_score = self.score_valuation()
+        
+        # Calculate weighted score
+        weighted_score = (
+            fundamental_score['percentage'] * self.score_weights['fundamental'] +
+            sector_score['percentage'] * self.score_weights['sector'] +
+            valuation_score['percentage'] * self.score_weights['valuation']
+        )
+        
+        return {
+            'overall_score': weighted_score,
+            'max_score': 100,
+            'grade': self._get_grade(weighted_score),
+            'breakdown': {
+                'fundamental': {
+                    'score': fundamental_score['percentage'],
+                    'weight': self.score_weights['fundamental'],
+                    'weighted_score': fundamental_score['percentage'] * self.score_weights['fundamental'],
+                    'details': fundamental_score
+                },
+                'sector': {
+                    'score': sector_score['percentage'],
+                    'weight': self.score_weights['sector'],
+                    'weighted_score': sector_score['percentage'] * self.score_weights['sector'],
+                    'details': sector_score
+                },
+                'valuation': {
+                    'score': valuation_score['percentage'],
+                    'weight': self.score_weights['valuation'],
+                    'weighted_score': valuation_score['percentage'] * self.score_weights['valuation'],
+                    'details': valuation_score
+                }
+            }
+        }
+    
+    def generate_recommendation(self) -> str:
+        """
+        Generate BUY/SELL/HOLD recommendation
+        
+        Returns:
+            Investment recommendation
+        """
+        overall = self.calculate_overall_score()
+        score = overall['overall_score']
+        
+        # Base recommendation on score
+        if score >= 70:
+            base_rec = "STRONG BUY"
+        elif score >= 60:
+            base_rec = "BUY"
+        elif score >= 50:
+            base_rec = "HOLD"
+        elif score >= 40:
+            base_rec = "SELL"
+        else:
+            base_rec = "STRONG SELL"
+        
+        # Adjust based on specific red flags
+        red_flags = self.identify_red_flags()
+        
+        if red_flags['critical_issues']:
+            if base_rec in ["STRONG BUY", "BUY"]:
+                base_rec = "HOLD"
+            elif base_rec == "HOLD":
+                base_rec = "SELL"
+        
+        return base_rec
+    
+    def identify_red_flags(self) -> Dict:
+        """
+        Identify critical red flags
+        
+        Returns:
+            Red flags and warnings
+        """
+        red_flags = {
+            'critical_issues': [],
+            'warnings': [],
+            'positive_signs': []
+        }
+        
+        # Check cash flow
+        cf_analysis = self.fundamental.get('cash_flow_analysis', {})
+        if cf_analysis.get('free_cash_flow', 0) < 0:
+            red_flags['critical_issues'].append("Negative free cash flow")
+        
+        # Check earnings
+        growth = self.fundamental.get('growth_analysis', {})
+        if growth.get('net_income_growth_yoy', 0) < -0.10:
+            red_flags['warnings'].append("Declining earnings (>10% drop)")
+        
+        # Check margins
+        margins = self.fundamental.get('margin_analysis', {})
+        if margins.get('operating_margin_trend', 0) < -0.02:
+            red_flags['warnings'].append("Contracting operating margins")
+        
+        # Check debt
+        health = self.fundamental.get('financial_health', {})
+        interest_coverage = health.get('interest_coverage')
+        if interest_coverage and interest_coverage < 2:
+            red_flags['critical_issues'].append("Low interest coverage (<2x)")
+        
+        # Check valuation
+        valuation_score = self.score_valuation()
+        if valuation_score['percentage'] < 25:
+            red_flags['warnings'].append("Expensive valuation")
+        
+        # Check sector
+        sector_sentiment = self.sector.get('sector_sentiment', {})
+        if 'Negative' in sector_sentiment.get('overall_sentiment', ''):
+            red_flags['warnings'].append("Sector facing headwinds")
+        
+        # Positive signs
+        if cf_analysis.get('fcf_positive_trend', False):
+            red_flags['positive_signs'].append("Growing free cash flow")
+        
+        if margins.get('operating_leverage', False):
+            red_flags['positive_signs'].append("Expanding operating margins")
+        
+        returns = self.fundamental.get('returns_analysis', {})
+        if returns.get('roic', 0) > 0.15:
+            red_flags['positive_signs'].append("Strong return on invested capital (>15%)")
+        
+        return red_flags
+    
+    def generate_confidence_score(self) -> Dict:
+        """
+        Generate confidence level in recommendation
+        
+        Returns:
+            Confidence metrics
+        """
+        confidence_factors = []
+        
+        # Data quality
+        fundamental = self.score_fundamentals()
+        if fundamental['grade'] != 'F':
+            confidence_factors.append(0.3)
+        
+        # Sector data available
+        if self.sector.get('peer_count', 0) > 0:
+            confidence_factors.append(0.25)
+        
+        # Valuation methods available
+        valuation = self.valuation.get('relative_valuation', {})
+        methods_available = sum([
+            'pe_valuation' in valuation,
+            'peg_valuation' in valuation,
+            'pb_valuation' in valuation
+        ])
+        confidence_factors.append(methods_available * 0.15)
+        
+        # Score consistency
+        overall = self.calculate_overall_score()
+        breakdown = overall['breakdown']
+        scores = [
+            breakdown['fundamental']['score'],
+            breakdown['sector']['score'],
+            breakdown['valuation']['score']
+        ]
+        std_dev = np.std(scores)
+        if std_dev < 15:  # Scores are consistent
+            confidence_factors.append(0.15)
+        
+        confidence = sum(confidence_factors)
+        
+        return {
+            'confidence_score': min(confidence, 1.0),
+            'confidence_level': self._get_confidence_level(confidence),
+            'factors': confidence_factors
+        }
+    
+    def _get_grade(self, score: float) -> str:
+        """Convert score to letter grade"""
+        if score >= 90:
+            return 'A+'
+        elif score >= 80:
+            return 'A'
+        elif score >= 70:
+            return 'B'
+        elif score >= 60:
+            return 'C'
+        elif score >= 50:
+            return 'D'
+        else:
+            return 'F'
+    
+    def _get_confidence_level(self, confidence: float) -> str:
+        """Convert confidence score to level"""
+        if confidence >= 0.8:
+            return "Very High"
+        elif confidence >= 0.6:
+            return "High"
+        elif confidence >= 0.4:
+            return "Moderate"
+        else:
+            return "Low"
+    
+    def _assess_fundamentals(self, score: float) -> str:
+        """Assess fundamental strength"""
+        if score >= 80:
+            return "Excellent fundamentals - Strong business"
+        elif score >= 60:
+            return "Good fundamentals - Solid business"
+        elif score >= 40:
+            return "Moderate fundamentals - Average business"
+        else:
+            return "Weak fundamentals - Concerning business"
+    
+    def _assess_sector_position(self, score: float, sentiment: str) -> str:
+        """Assess sector position"""
+        if score >= 70:
+            return f"Leading position in sector ({sentiment})"
+        elif score >= 50:
+            return f"Average position in sector ({sentiment})"
+        else:
+            return f"Weak position in sector ({sentiment})"
+    
+    def _assess_valuation(self, score: float) -> str:
+        """Assess valuation"""
+        if score >= 70:
+            return "Attractive valuation - Undervalued"
+        elif score >= 50:
+            return "Fair valuation - Reasonably priced"
+        elif score >= 30:
+            return "Full valuation - Fairly valued to slightly expensive"
+        else:
+            return "Expensive valuation - Overvalued"
+    
+    def generate_investment_thesis(self) -> str:
+        """
+        Generate investment thesis narrative
+        
+        Returns:
+            Investment thesis text
+        """
+        recommendation = self.generate_recommendation()
+        overall = self.calculate_overall_score()
+        red_flags = self.identify_red_flags()
+        
+        thesis = []
+        
+        # Opening
+        thesis.append(f"**{recommendation}** - Overall Score: {overall['overall_score']:.1f}/100 ({overall['grade']})")
+        thesis.append("")
+        
+        # Fundamental assessment
+        fund_score = overall['breakdown']['fundamental']['details']
+        thesis.append(f"**Fundamentals ({fund_score['percentage']:.0f}/100):** {fund_score['assessment']}")
+        
+        # Sector position
+        sector_score = overall['breakdown']['sector']['details']
+        thesis.append(f"**Sector Position ({sector_score['percentage']:.0f}/100):** {sector_score['assessment']}")
+        
+        # Valuation
+        val_score = overall['breakdown']['valuation']['details']
+        thesis.append(f"**Valuation ({val_score['percentage']:.0f}/100):** {val_score['assessment']}")
+        thesis.append("")
+        
+        # Key positives
+        if red_flags['positive_signs']:
+            thesis.append("**Key Strengths:**")
+            for sign in red_flags['positive_signs']:
+                thesis.append(f"  ✓ {sign}")
+            thesis.append("")
+        
+        # Key concerns
+        if red_flags['critical_issues'] or red_flags['warnings']:
+            thesis.append("**Key Concerns:**")
+            for issue in red_flags['critical_issues']:
+                thesis.append(f"  ⚠ {issue}")
+            for warning in red_flags['warnings']:
+                thesis.append(f"  • {warning}")
+            thesis.append("")
+        
+        # Confidence
+        confidence = self.generate_confidence_score()
+        thesis.append(f"**Confidence Level:** {confidence['confidence_level']} ({confidence['confidence_score']*100:.0f}%)")
+        
+        return "\n".join(thesis)
+    
+    def generate_decision_report(self) -> Dict:
+        """
+        Generate comprehensive investment decision report
+        
+        Returns:
+            Complete decision analysis
+        """
+        return {
+            'ticker': self.ticker,
+            'company_name': self.company_info.get('company_name', self.ticker),
+            'current_price': self.current_price,
+            'analysis_date': datetime.now().isoformat(),
+            'recommendation': self.generate_recommendation(),
+            'overall_score': self.calculate_overall_score(),
+            'confidence': self.generate_confidence_score(),
+            'red_flags': self.identify_red_flags(),
+            'investment_thesis': self.generate_investment_thesis()
+        }
+
+
+if __name__ == "__main__":
+    print("This module is meant to be imported and used with results from other analyzers")

src/fundamental_analysis/decision_maker.py

@@ -0,0 +1,620 @@
+"""
+Investment Decision Maker
+Main entry point: Input ticker → Output BUY/SELL/HOLD recommendation
+Uses composite scoring based on institutional methodology
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, Tuple, Optional, List
+from fundamental_analysis.calculator import calculate_metrics_for_ticker
+from fundamental_analysis.sector_analyzer import SectorAnalyzer
+import yfinance as yf
+import warnings
+warnings.filterwarnings('ignore')
+
+
+class InvestmentDecision:
+    """Make BUY/SELL/HOLD decisions based on comprehensive analysis"""
+    
+    # Scoring weights based on institutional methodology
+    WEIGHTS = {
+        'fcf_yield': 0.25,      # 25% - HIGHEST priority
+        'roic': 0.25,           # 25% - Quality indicator
+        'growth': 0.15,         # 15% - Growth metrics
+        'valuation': 0.15,      # 15% - Valuation ratios
+        'leverage': 0.10,       # 10% - Financial health
+        'capital_allocation': 0.10  # 10% - Capital management
+    }
+    
+    # Decision thresholds
+    THRESHOLDS = {
+        'buy': 0.35,      # Score >= 0.35 → BUY
+        'sell': -0.10     # Score < -0.10 → SELL
+    }
+    
+    def __init__(self, ticker: str, compare_to_sector: bool = True):
+        """
+        Initialize decision maker
+        
+        Args:
+            ticker: Stock ticker symbol
+            compare_to_sector: Whether to compare against sector peers
+        """
+        self.ticker = ticker.upper()
+        self.compare_to_sector = compare_to_sector
+        self.metrics_df = pd.DataFrame()
+        self.metrics_dict = {}
+        self.sector_comparison = pd.DataFrame()
+        self.sector_percentiles = {}
+        self.scores = {}
+        self.final_score = 0.0
+        self.recommendation = "HOLD"
+        self.confidence = 0.0
+        self.reasoning = []
+        
+    def analyze(self) -> Dict:
+        """
+        Perform complete analysis and generate recommendation
+        
+        Returns:
+            Dictionary with recommendation and detailed analysis
+        """
+        print(f"\n{'='*80}")
+        print(f"INVESTMENT ANALYSIS: {self.ticker}")
+        print(f"{'='*80}\n")
+        
+        # Step 1: Calculate all metrics
+        print("Step 1: Calculating financial metrics...")
+        self.metrics_df, summary = calculate_metrics_for_ticker(self.ticker)
+        
+        if self.metrics_df.empty:
+            return self._error_result("Failed to fetch data")
+        
+        # Convert metrics to dictionary for easier access
+        self._build_metrics_dict()
+        
+        # Step 2: Get sector comparison
+        if self.compare_to_sector:
+            print("\nStep 2: Comparing to sector peers...")
+            self._compare_to_sector()
+        else:
+            print("\nStep 2: Skipping sector comparison")
+        
+        # Step 3: Score each category
+        print("\nStep 3: Scoring investment criteria...")
+        self._score_all_categories()
+        
+        # Step 4: Calculate final score and recommendation
+        print("\nStep 4: Generating recommendation...")
+        self._calculate_final_score()
+        self._determine_recommendation()
+        
+        # Step 5: Build reasoning
+        self._build_reasoning()
+        
+        # Return complete analysis
+        return self._build_result()
+    
+    def _build_metrics_dict(self):
+        """Convert metrics DataFrame to dictionary for easier access"""
+        for _, row in self.metrics_df.iterrows():
+            if row['Status'] == 'Available':
+                metric_name = row['Metric'].replace(' ', '_').replace('/', '_').replace('(', '').replace(')', '').replace('%', 'pct')
+                self.metrics_dict[metric_name] = row['Value']
+    
+    def _get_metric(self, metric_name: str) -> Optional[float]:
+        """Safely get metric value"""
+        row = self.metrics_df[self.metrics_df['Metric'] == metric_name]
+        if not row.empty and row.iloc[0]['Status'] == 'Available':
+            return row.iloc[0]['Value']
+        return None
+    
+    def _compare_to_sector(self):
+        """Compare stock to sector peers"""
+        try:
+            # Get company info to determine sector
+            stock = yf.Ticker(self.ticker)
+            info = stock.info
+            sector = info.get('sector', 'Unknown')
+            
+            if sector == 'Unknown':
+                print("  ⚠ Could not determine sector, skipping comparison")
+                return
+            
+            print(f"  Sector: {sector}")
+            
+            # Map yfinance sectors to our predefined sectors
+            sector_mapping = {
+                'Technology': 'Technology',
+                'Financial Services': 'Financial',
+                'Healthcare': 'Healthcare',
+                'Consumer Cyclical': 'Consumer',
+                'Consumer Defensive': 'Consumer',
+                'Industrials': 'Industrial',
+                'Energy': 'Energy',
+                'Basic Materials': 'Materials',
+                'Real Estate': 'Real Estate',
+                'Communication Services': 'Communication'
+            }
+            
+            mapped_sector = sector_mapping.get(sector)
+            if not mapped_sector:
+                print(f"  ⚠ Sector '{sector}' not in predefined list")
+                return
+            
+            # Analyze sector with a subset of stocks (to avoid long wait)
+            analyzer = SectorAnalyzer(mapped_sector)
+            tickers = analyzer.get_sector_tickers()
+            
+            # Limit to 10 stocks for faster analysis
+            if len(tickers) > 10:
+                tickers = tickers[:10]
+                print(f"  Analyzing {len(tickers)} peer stocks (limited sample)...")
+            
+            comparison_df = analyzer.calculate_sector_metrics(tickers)
+            
+            if not comparison_df.empty and self.ticker in comparison_df.index:
+                self.sector_comparison = analyzer.compare_stock_to_peers(self.ticker, comparison_df)
+                self.sector_percentiles = comparison_df.rank(pct=True).loc[self.ticker].to_dict()
+                print(f"  ✓ Sector comparison complete")
+            else:
+                print(f"  ⚠ Could not compare to sector")
+                
+        except Exception as e:
+            print(f"  ⚠ Sector comparison error: {str(e)}")
+    
+    def _score_all_categories(self):
+        """Score each investment category"""
+        self.scores['fcf_yield'] = self._score_fcf_yield()
+        self.scores['roic'] = self._score_roic()
+        self.scores['growth'] = self._score_growth()
+        self.scores['valuation'] = self._score_valuation()
+        self.scores['leverage'] = self._score_leverage()
+        self.scores['capital_allocation'] = self._score_capital_allocation()
+        
+        # Print scores
+        for category, score in self.scores.items():
+            print(f"  {category.replace('_', ' ').title()}: {score:+.2f}")
+    
+    def _score_fcf_yield(self) -> float:
+        """
+        Score FCF Yield (HIGHEST PRIORITY - 25% weight)
+        Threshold: >6% = BUY, 4-6% = HOLD, <3% = SELL
+        """
+        fcf_yield = self._get_metric('FCF Yield (Enterprise) %')
+        
+        if fcf_yield is None:
+            return 0.0
+        
+        # Scoring rules
+        if fcf_yield >= 6.0:
+            score = 1.0  # Strong buy signal
+        elif fcf_yield >= 4.0:
+            score = 0.5  # Hold
+        elif fcf_yield >= 3.0:
+            score = 0.0  # Neutral
+        else:
+            score = -1.0  # Sell signal
+        
+        # Adjust based on sector percentile if available
+        if 'FCF_Yield_%' in self.sector_percentiles:
+            percentile = self.sector_percentiles['FCF_Yield_%']
+            if percentile > 0.75:
+                score += 0.3  # Top quartile bonus
+            elif percentile < 0.25:
+                score -= 0.3  # Bottom quartile penalty
+        
+        return np.clip(score, -1.0, 1.0)
+    
+    def _score_roic(self) -> float:
+        """
+        Score ROIC (VERY HIGH PRIORITY - 25% weight)
+        Threshold: >15% = excellent, >10% = good, <10% = concern
+        """
+        roic = self._get_metric('Return on Invested Capital (ROIC) %')
+        
+        if roic is None:
+            return 0.0
+        
+        # Scoring rules
+        if roic >= 20.0:
+            score = 1.0  # Exceptional
+        elif roic >= 15.0:
+            score = 0.7  # Excellent
+        elif roic >= 10.0:
+            score = 0.3  # Good
+        elif roic >= 5.0:
+            score = -0.3  # Mediocre
+        else:
+            score = -1.0  # Poor
+        
+        # Adjust based on sector percentile
+        if 'ROIC_%' in self.sector_percentiles:
+            percentile = self.sector_percentiles['ROIC_%']
+            if percentile > 0.75:
+                score += 0.2
+            elif percentile < 0.25:
+                score -= 0.2
+        
+        return np.clip(score, -1.0, 1.0)
+    
+    def _score_growth(self) -> float:
+        """
+        Score Growth Metrics (15% weight)
+        Revenue growth, EPS growth
+        """
+        rev_growth = self._get_metric('Revenue Growth (YoY) %')
+        eps_growth = self._get_metric('EPS Growth (YoY) %')
+        
+        if rev_growth is None and eps_growth is None:
+            return 0.0
+        
+        scores = []
+        
+        # Revenue growth scoring
+        if rev_growth is not None:
+            if rev_growth >= 20.0:
+                scores.append(1.0)
+            elif rev_growth >= 10.0:
+                scores.append(0.5)
+            elif rev_growth >= 5.0:
+                scores.append(0.2)
+            elif rev_growth >= 0.0:
+                scores.append(-0.2)
+            else:
+                scores.append(-1.0)  # Declining revenue
+        
+        # EPS growth scoring
+        if eps_growth is not None:
+            if eps_growth >= 20.0:
+                scores.append(1.0)
+            elif eps_growth >= 10.0:
+                scores.append(0.5)
+            elif eps_growth >= 5.0:
+                scores.append(0.2)
+            elif eps_growth >= 0.0:
+                scores.append(-0.2)
+            else:
+                scores.append(-1.0)
+        
+        return np.clip(np.mean(scores) if scores else 0.0, -1.0, 1.0)
+    
+    def _score_valuation(self) -> float:
+        """
+        Score Valuation Metrics (15% weight)
+        P/E, PEG, EV/EBITDA relative to sector
+        """
+        pe_ratio = self._get_metric('P/E Ratio (TTM)')
+        peg_ratio = self._get_metric('PEG Ratio')
+        ev_ebitda = self._get_metric('EV/EBITDA')
+        
+        scores = []
+        
+        # PEG ratio scoring (most important valuation metric)
+        if peg_ratio is not None:
+            if peg_ratio < 0.8:
+                scores.append(1.0)  # Undervalued
+            elif peg_ratio < 1.2:
+                scores.append(0.3)  # Fair value
+            elif peg_ratio < 1.5:
+                scores.append(-0.3)  # Slightly expensive
+            else:
+                scores.append(-1.0)  # Overvalued
+        
+        # P/E relative to sector
+        if 'PE_Ratio' in self.sector_percentiles:
+            percentile = self.sector_percentiles['PE_Ratio']
+            # Lower P/E is better (reverse percentile)
+            if percentile < 0.33:
+                scores.append(0.7)  # Cheap relative to sector
+            elif percentile < 0.67:
+                scores.append(0.0)  # Fair
+            else:
+                scores.append(-0.7)  # Expensive
+        
+        # EV/EBITDA relative to sector
+        if 'EV_EBITDA' in self.sector_percentiles:
+            percentile = self.sector_percentiles['EV_EBITDA']
+            # Lower is better
+            if percentile < 0.33:
+                scores.append(0.5)
+            elif percentile > 0.67:
+                scores.append(-0.5)
+        
+        return np.clip(np.mean(scores) if scores else 0.0, -1.0, 1.0)
+    
+    def _score_leverage(self) -> float:
+        """
+        Score Leverage/Financial Health (10% weight)
+        Net Debt/EBITDA, Interest Coverage
+        """
+        net_debt_ebitda = self._get_metric('Net Debt / EBITDA')
+        current_ratio = self._get_metric('Current Ratio')
+        cash_conversion = self._get_metric('Cash Conversion Ratio')
+        
+        scores = []
+        
+        # Net Debt/EBITDA scoring
+        if net_debt_ebitda is not None:
+            if net_debt_ebitda < 1.0:
+                scores.append(1.0)  # Very low leverage
+            elif net_debt_ebitda < 2.0:
+                scores.append(0.5)  # Moderate
+            elif net_debt_ebitda < 3.0:
+                scores.append(0.0)  # Acceptable
+            elif net_debt_ebitda < 4.0:
+                scores.append(-0.5)  # High
+            else:
+                scores.append(-1.0)  # Very high risk
+        
+        # Current ratio
+        if current_ratio is not None:
+            if current_ratio >= 2.0:
+                scores.append(0.5)
+            elif current_ratio >= 1.5:
+                scores.append(0.2)
+            elif current_ratio >= 1.0:
+                scores.append(-0.2)
+            else:
+                scores.append(-0.5)
+        
+        # Cash conversion (quality of earnings)
+        if cash_conversion is not None:
+            if cash_conversion >= 1.2:
+                scores.append(0.5)
+            elif cash_conversion >= 1.0:
+                scores.append(0.2)
+            elif cash_conversion >= 0.8:
+                scores.append(-0.2)
+            else:
+                scores.append(-0.5)  # Red flag
+        
+        return np.clip(np.mean(scores) if scores else 0.0, -1.0, 1.0)
+    
+    def _score_capital_allocation(self) -> float:
+        """
+        Score Capital Allocation (10% weight)
+        Dividends, buybacks, total payout ratio
+        """
+        payout_ratio = self._get_metric('Payout Ratio %')
+        total_payout = self._get_metric('Total Payout Ratio %')
+        roe = self._get_metric('Return on Equity (ROE) %')
+        
+        scores = []
+        
+        # Payout ratio - should be sustainable
+        if payout_ratio is not None:
+            if payout_ratio < 40.0:
+                scores.append(0.5)  # Low, room to grow
+            elif payout_ratio < 60.0:
+                scores.append(0.3)  # Sustainable
+            elif payout_ratio < 80.0:
+                scores.append(-0.2)  # High
+            else:
+                scores.append(-0.5)  # Potentially unsustainable
+        
+        # Total payout (dividends + buybacks)
+        if total_payout is not None and roe is not None:
+            # Good capital allocation returns cash to shareholders while maintaining high ROE
+            if roe > 15.0 and total_payout > 50.0:
+                scores.append(0.5)  # Strong returns + returning cash
+            elif roe > 15.0:
+                scores.append(0.3)  # Strong returns, could return more
+            elif total_payout > 50.0:
+                scores.append(-0.3)  # Returning cash but weak returns
+        
+        return np.clip(np.mean(scores) if scores else 0.0, -1.0, 1.0)
+    
+    def _calculate_final_score(self):
+        """Calculate weighted final score"""
+        self.final_score = sum(
+            self.scores.get(category, 0.0) * weight 
+            for category, weight in self.WEIGHTS.items()
+        )
+        
+        # Calculate confidence based on data availability and sector comparison
+        data_completeness = len([s for s in self.scores.values() if s != 0.0]) / len(self.scores)
+        sector_bonus = 0.15 if not self.sector_comparison.empty else 0.0
+        self.confidence = min(data_completeness + sector_bonus, 1.0)
+    
+    def _determine_recommendation(self):
+        """Determine BUY/SELL/HOLD based on final score"""
+        if self.final_score >= self.THRESHOLDS['buy']:
+            self.recommendation = "BUY"
+        elif self.final_score < self.THRESHOLDS['sell']:
+            self.recommendation = "SELL"
+        else:
+            self.recommendation = "HOLD"
+    
+    def _build_reasoning(self):
+        """Build human-readable reasoning for the recommendation"""
+        self.reasoning = []
+        
+        # Overall assessment
+        if self.final_score >= 0.5:
+            self.reasoning.append("✓ Strong overall fundamentals")
+        elif self.final_score >= 0.2:
+            self.reasoning.append("✓ Positive fundamentals")
+        elif self.final_score >= -0.2:
+            self.reasoning.append("• Mixed fundamentals")
+        else:
+            self.reasoning.append("✗ Weak fundamentals")
+        
+        # FCF Yield
+        fcf_yield = self._get_metric('FCF Yield (Enterprise) %')
+        if fcf_yield:
+            if fcf_yield >= 6.0:
+                self.reasoning.append(f"✓ Excellent FCF yield: {fcf_yield:.2f}%")
+            elif fcf_yield < 3.0:
+                self.reasoning.append(f"✗ Low FCF yield: {fcf_yield:.2f}%")
+        
+        # ROIC
+        roic = self._get_metric('Return on Invested Capital (ROIC) %')
+        if roic:
+            if roic >= 15.0:
+                self.reasoning.append(f"✓ Strong ROIC: {roic:.2f}%")
+            elif roic < 10.0:
+                self.reasoning.append(f"✗ Weak ROIC: {roic:.2f}%")
+        
+        # Growth
+        rev_growth = self._get_metric('Revenue Growth (YoY) %')
+        if rev_growth:
+            if rev_growth >= 15.0:
+                self.reasoning.append(f"✓ Strong revenue growth: {rev_growth:.2f}%")
+            elif rev_growth < 0:
+                self.reasoning.append(f"✗ Declining revenue: {rev_growth:.2f}%")
+        
+        # Valuation
+        peg_ratio = self._get_metric('PEG Ratio')
+        if peg_ratio:
+            if peg_ratio < 0.8:
+                self.reasoning.append(f"✓ Undervalued (PEG: {peg_ratio:.2f})")
+            elif peg_ratio > 1.5:
+                self.reasoning.append(f"✗ Overvalued (PEG: {peg_ratio:.2f})")
+        
+        # Leverage
+        net_debt_ebitda = self._get_metric('Net Debt / EBITDA')
+        if net_debt_ebitda is not None:
+            if net_debt_ebitda < 1.0:
+                self.reasoning.append(f"✓ Low leverage: {net_debt_ebitda:.2f}x")
+            elif net_debt_ebitda > 3.0:
+                self.reasoning.append(f"✗ High leverage: {net_debt_ebitda:.2f}x")
+        
+        # Sector comparison
+        if 'ROIC_%' in self.sector_percentiles:
+            roic_pct = self.sector_percentiles['ROIC_%']
+            if roic_pct > 0.75:
+                self.reasoning.append(f"✓ Top quartile ROIC vs peers (P{int(roic_pct*100)})")
+            elif roic_pct < 0.25:
+                self.reasoning.append(f"✗ Bottom quartile ROIC vs peers (P{int(roic_pct*100)})")
+    
+    def _build_result(self) -> Dict:
+        """Build final result dictionary"""
+        return {
+            'ticker': self.ticker,
+            'recommendation': self.recommendation,
+            'final_score': self.final_score,
+            'confidence': self.confidence,
+            'category_scores': self.scores,
+            'reasoning': self.reasoning,
+            'key_metrics': {
+                'FCF_Yield_%': self._get_metric('FCF Yield (Enterprise) %'),
+                'ROIC_%': self._get_metric('Return on Invested Capital (ROIC) %'),
+                'ROE_%': self._get_metric('Return on Equity (ROE) %'),
+                'Revenue_Growth_%': self._get_metric('Revenue Growth (YoY) %'),
+                'PEG_Ratio': self._get_metric('PEG Ratio'),
+                'Net_Debt_EBITDA': self._get_metric('Net Debt / EBITDA'),
+            },
+            'sector_percentiles': self.sector_percentiles if self.sector_percentiles else None
+        }
+    
+    def _error_result(self, error_message: str) -> Dict:
+        """Return error result"""
+        return {
+            'ticker': self.ticker,
+            'recommendation': 'ERROR',
+            'error': error_message,
+            'final_score': 0.0,
+            'confidence': 0.0
+        }
+    
+    def print_analysis(self, result: Dict):
+        """Print formatted analysis report"""
+        print(f"\n{'='*80}")
+        print(f"INVESTMENT RECOMMENDATION: {result['ticker']}")
+        print(f"{'='*80}")
+        
+        if result['recommendation'] == 'ERROR':
+            print(f"\n✗ ERROR: {result.get('error', 'Unknown error')}")
+            return
+        
+        # Recommendation with color coding
+        rec = result['recommendation']
+        if rec == 'BUY':
+            print(f"\n🟢 RECOMMENDATION: {rec} (Score: {result['final_score']:+.2f})")
+        elif rec == 'SELL':
+            print(f"\n🔴 RECOMMENDATION: {rec} (Score: {result['final_score']:+.2f})")
+        else:
+            print(f"\n🟡 RECOMMENDATION: {rec} (Score: {result['final_score']:+.2f})")
+        
+        print(f"Confidence: {result['confidence']:.0%}")
+        
+        # Category scores
+        print(f"\n{'-'*80}")
+        print("CATEGORY SCORES (weighted)")
+        print(f"{'-'*80}")
+        for category, score in result['category_scores'].items():
+            weight = self.WEIGHTS[category]
+            weighted_score = score * weight
+            bar_length = int(abs(score) * 20)
+            bar = '█' * bar_length
+            print(f"{category.replace('_', ' ').title():25} {score:+.2f} ({weight:.0%}) → {weighted_score:+.3f}  {bar}")
+        
+        # Key metrics
+        print(f"\n{'-'*80}")
+        print("KEY METRICS")
+        print(f"{'-'*80}")
+        for metric, value in result['key_metrics'].items():
+            if value is not None:
+                print(f"{metric:30} {value:>12.2f}")
+        
+        # Reasoning
+        print(f"\n{'-'*80}")
+        print("INVESTMENT RATIONALE")
+        print(f"{'-'*80}")
+        for reason in result['reasoning']:
+            print(f"  {reason}")
+        
+        print(f"\n{'='*80}\n")
+
+
+def evaluate_stock(ticker: str, compare_to_sector: bool = True) -> Dict:
+    """
+    Main function to evaluate a stock and get recommendation
+    
+    Args:
+        ticker: Stock ticker symbol
+        compare_to_sector: Whether to compare to sector peers
+    
+    Returns:
+        Dictionary with recommendation and analysis
+    """
+    decision = InvestmentDecision(ticker, compare_to_sector)
+    result = decision.analyze()
+    decision.print_analysis(result)
+    return result
+
+
+if __name__ == "__main__":
+    # Test with sample tickers
+    test_tickers = ['AAPL', 'GOOGL', 'MSFT']
+    
+    print("INVESTMENT DECISION MAKER TEST")
+    print("=" * 80)
+    
+    results = []
+    for ticker in test_tickers:
+        result = evaluate_stock(ticker, compare_to_sector=False)  # Disable sector for speed
+        results.append(result)
+        
+    # Summary comparison
+    print("\n" + "=" * 80)
+    print("SUMMARY COMPARISON")
+    print("=" * 80)
+    
+    summary_df = pd.DataFrame([{
+        'Ticker': r['ticker'],
+        'Recommendation': r['recommendation'],
+        'Score': r['final_score'],
+        'Confidence': r['confidence'],
+        'FCF Yield %': r['key_metrics']['FCF_Yield_%'],
+        'ROIC %': r['key_metrics']['ROIC_%'],
+        'PEG': r['key_metrics']['PEG_Ratio']
+    } for r in results])
+    
+    print(summary_df.to_string(index=False))
+    
+    # Save results
+    summary_df.to_csv('investment_recommendations.csv', index=False)
+    print(f"\n✓ Results saved to investment_recommendations.csv")

src/fundamental_analysis/financial_analyzer.py

@@ -0,0 +1,382 @@
+"""
+Financial analysis engine for fundamental metrics.
+Calculates growth, margins, returns, and cash flow metrics.
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, Optional, Tuple, List
+from datetime import datetime
+
+
+class FinancialAnalyzer:
+    """Analyzes financial statements and calculates key metrics"""
+    
+    def __init__(self, financial_data: Dict):
+        """
+        Initialize analyzer with fetched financial data
+        
+        Args:
+            financial_data: Complete dataset from FinancialDataFetcher
+        """
+        self.data = financial_data
+        self.ticker = financial_data.get('ticker')
+        self.metrics = financial_data.get('metrics', {})
+        self.statements = financial_data.get('financial_statements', {})
+        self.company_info = financial_data.get('company_info', {})
+        
+    def analyze_growth(self) -> Dict:
+        """
+        Analyze revenue and earnings growth trends
+        
+        Returns:
+            Dictionary with growth metrics
+        """
+        results = {
+            'revenue_growth_ttm': self.metrics.get('revenue_growth'),
+            'earnings_growth_ttm': self.metrics.get('earnings_growth'),
+        }
+        
+        # Calculate historical growth from income statement
+        try:
+            income_stmt = self.statements.get('income_statement')
+            if income_stmt is not None and not income_stmt.empty:
+                
+                # Revenue growth (most recent vs 1 year ago)
+                if 'Total Revenue' in income_stmt.index:
+                    revenues = income_stmt.loc['Total Revenue'].values
+                    if len(revenues) >= 2:
+                        results['revenue_growth_yoy'] = ((revenues[0] - revenues[1]) / abs(revenues[1])) if revenues[1] != 0 else None
+                        
+                        # 3-year CAGR if available
+                        if len(revenues) >= 3:
+                            years = min(len(revenues) - 1, 3)
+                            cagr = (revenues[0] / revenues[years]) ** (1/years) - 1 if revenues[years] != 0 else None
+                            results['revenue_cagr_3y'] = cagr
+                
+                # Net income growth
+                if 'Net Income' in income_stmt.index:
+                    net_incomes = income_stmt.loc['Net Income'].values
+                    if len(net_incomes) >= 2:
+                        # Handle negative values
+                        if net_incomes[1] != 0:
+                            results['net_income_growth_yoy'] = ((net_incomes[0] - net_incomes[1]) / abs(net_incomes[1]))
+        except Exception as e:
+            print(f"Error calculating historical growth: {e}")
+        
+        # Growth assessment
+        revenue_growth = results.get('revenue_growth_yoy') or results.get('revenue_growth_ttm')
+        earnings_growth = results.get('net_income_growth_yoy') or results.get('earnings_growth_ttm')
+        
+        results['growth_quality'] = self._assess_growth_quality(revenue_growth, earnings_growth)
+        
+        return results
+    
+    def analyze_margins(self) -> Dict:
+        """
+        Analyze profitability margins and trends
+        
+        Returns:
+            Dictionary with margin metrics
+        """
+        results = {
+            'gross_margin': self.metrics.get('gross_margin'),
+            'operating_margin': self.metrics.get('operating_margin'),
+            'profit_margin': self.metrics.get('profit_margin'),
+            'ebitda_margin': self.metrics.get('ebitda_margin'),
+        }
+        
+        # Calculate margin trends from income statement
+        try:
+            income_stmt = self.statements.get('income_statement')
+            if income_stmt is not None and not income_stmt.empty:
+                
+                # Calculate margins for multiple periods
+                if 'Total Revenue' in income_stmt.index:
+                    revenues = income_stmt.loc['Total Revenue'].values
+                    
+                    # Gross margin trend
+                    if 'Gross Profit' in income_stmt.index and len(revenues) >= 2:
+                        gross_profits = income_stmt.loc['Gross Profit'].values
+                        margins = [gp / rev if rev != 0 else None for gp, rev in zip(gross_profits, revenues)]
+                        margins = [m for m in margins if m is not None]
+                        
+                        if len(margins) >= 2:
+                            results['gross_margin_current'] = margins[0]
+                            results['gross_margin_trend'] = margins[0] - margins[1]
+                            results['gross_margin_stable'] = abs(margins[0] - margins[1]) < 0.02  # Within 2%
+                    
+                    # Operating margin trend
+                    if 'Operating Income' in income_stmt.index and len(revenues) >= 2:
+                        op_incomes = income_stmt.loc['Operating Income'].values
+                        margins = [oi / rev if rev != 0 else None for oi, rev in zip(op_incomes, revenues)]
+                        margins = [m for m in margins if m is not None]
+                        
+                        if len(margins) >= 2:
+                            results['operating_margin_current'] = margins[0]
+                            results['operating_margin_trend'] = margins[0] - margins[1]
+                            results['operating_leverage'] = margins[0] > margins[1]  # Expanding margins
+                    
+                    # Net margin trend
+                    if 'Net Income' in income_stmt.index and len(revenues) >= 2:
+                        net_incomes = income_stmt.loc['Net Income'].values
+                        margins = [ni / rev if rev != 0 else None for ni, rev in zip(net_incomes, revenues)]
+                        margins = [m for m in margins if m is not None]
+                        
+                        if len(margins) >= 2:
+                            results['net_margin_current'] = margins[0]
+                            results['net_margin_trend'] = margins[0] - margins[1]
+        
+        except Exception as e:
+            print(f"Error calculating margin trends: {e}")
+        
+        # Margin assessment
+        results['margin_quality'] = self._assess_margin_quality(results)
+        
+        return results
+    
+    def analyze_returns(self) -> Dict:
+        """
+        Analyze return on capital metrics
+        
+        Returns:
+            Dictionary with return metrics
+        """
+        results = {
+            'roe': self.metrics.get('return_on_equity'),
+            'roa': self.metrics.get('return_on_assets'),
+        }
+        
+        # Calculate ROIC (Return on Invested Capital)
+        try:
+            income_stmt = self.statements.get('income_statement')
+            balance_sheet = self.statements.get('balance_sheet')
+            
+            if income_stmt is not None and balance_sheet is not None:
+                if not income_stmt.empty and not balance_sheet.empty:
+                    
+                    # NOPAT = Net Operating Profit After Tax
+                    if 'Operating Income' in income_stmt.index and 'Tax Provision' in income_stmt.index:
+                        op_income = income_stmt.loc['Operating Income'].iloc[0]
+                        total_revenue = income_stmt.loc['Total Revenue'].iloc[0] if 'Total Revenue' in income_stmt.index else 1
+                        tax_provision = income_stmt.loc['Tax Provision'].iloc[0]
+                        
+                        # Estimate tax rate
+                        pretax_income = income_stmt.loc['Pretax Income'].iloc[0] if 'Pretax Income' in income_stmt.index else op_income
+                        tax_rate = abs(tax_provision / pretax_income) if pretax_income != 0 else 0.21
+                        
+                        nopat = op_income * (1 - tax_rate)
+                        
+                        # Invested Capital = Total Debt + Total Equity - Cash
+                        total_debt = self.metrics.get('total_debt', 0)
+                        total_assets = balance_sheet.loc['Total Assets'].iloc[0] if 'Total Assets' in balance_sheet.index else 0
+                        total_liabilities = balance_sheet.loc['Total Liabilities Net Minority Interest'].iloc[0] if 'Total Liabilities Net Minority Interest' in balance_sheet.index else 0
+                        equity = total_assets - total_liabilities
+                        cash = self.metrics.get('total_cash', 0)
+                        
+                        invested_capital = total_debt + equity - cash
+                        
+                        if invested_capital > 0:
+                            results['roic'] = nopat / invested_capital
+        
+        except Exception as e:
+            print(f"Error calculating ROIC: {e}")
+        
+        # Returns assessment
+        results['returns_quality'] = self._assess_returns_quality(results)
+        
+        return results
+    
+    def analyze_cash_flow(self) -> Dict:
+        """
+        Analyze cash flow metrics
+        
+        Returns:
+            Dictionary with cash flow metrics
+        """
+        results = {
+            'operating_cash_flow': self.metrics.get('operating_cash_flow', 0),
+            'free_cash_flow': self.metrics.get('free_cash_flow', 0),
+        }
+        
+        # Calculate FCF margin and conversion
+        try:
+            income_stmt = self.statements.get('income_statement')
+            cashflow_stmt = self.statements.get('cash_flow')
+            
+            if income_stmt is not None and not income_stmt.empty:
+                revenue = income_stmt.loc['Total Revenue'].iloc[0] if 'Total Revenue' in income_stmt.index else 0
+                net_income = income_stmt.loc['Net Income'].iloc[0] if 'Net Income' in income_stmt.index else 0
+                
+                if revenue > 0:
+                    results['fcf_margin'] = results['free_cash_flow'] / revenue
+                    results['ocf_margin'] = results['operating_cash_flow'] / revenue
+                
+                if net_income != 0:
+                    results['fcf_conversion'] = results['free_cash_flow'] / net_income
+            
+            # Cash flow trend
+            if cashflow_stmt is not None and not cashflow_stmt.empty:
+                if 'Free Cash Flow' in cashflow_stmt.index:
+                    fcf_values = cashflow_stmt.loc['Free Cash Flow'].values
+                    if len(fcf_values) >= 2:
+                        results['fcf_growth'] = ((fcf_values[0] - fcf_values[1]) / abs(fcf_values[1])) if fcf_values[1] != 0 else None
+                        results['fcf_positive_trend'] = fcf_values[0] > fcf_values[1]
+        
+        except Exception as e:
+            print(f"Error calculating cash flow metrics: {e}")
+        
+        # Cash flow assessment
+        results['cash_flow_quality'] = self._assess_cash_flow_quality(results)
+        
+        return results
+    
+    def analyze_financial_health(self) -> Dict:
+        """
+        Analyze financial health and leverage
+        
+        Returns:
+            Dictionary with financial health metrics
+        """
+        results = {
+            'total_cash': self.metrics.get('total_cash', 0),
+            'total_debt': self.metrics.get('total_debt', 0),
+            'debt_to_equity': self.metrics.get('debt_to_equity'),
+            'current_ratio': self.metrics.get('current_ratio'),
+            'quick_ratio': self.metrics.get('quick_ratio'),
+        }
+        
+        # Calculate net debt
+        results['net_debt'] = results['total_debt'] - results['total_cash']
+        
+        # Calculate interest coverage
+        try:
+            income_stmt = self.statements.get('income_statement')
+            if income_stmt is not None and not income_stmt.empty:
+                if 'Operating Income' in income_stmt.index and 'Interest Expense' in income_stmt.index:
+                    op_income = income_stmt.loc['Operating Income'].iloc[0]
+                    interest = abs(income_stmt.loc['Interest Expense'].iloc[0])
+                    
+                    if interest > 0:
+                        results['interest_coverage'] = op_income / interest
+        
+        except Exception as e:
+            print(f"Error calculating interest coverage: {e}")
+        
+        # Health assessment
+        results['financial_health_quality'] = self._assess_financial_health(results)
+        
+        return results
+    
+    def _assess_growth_quality(self, revenue_growth: Optional[float], earnings_growth: Optional[float]) -> str:
+        """Assess growth quality"""
+        if revenue_growth is None or earnings_growth is None:
+            return "Insufficient Data"
+        
+        if revenue_growth > 0.15 and earnings_growth > 0.15:
+            return "Strong"
+        elif revenue_growth > 0.08 and earnings_growth > 0.08:
+            return "Good"
+        elif revenue_growth > 0 and earnings_growth > 0:
+            return "Moderate"
+        else:
+            return "Weak"
+    
+    def _assess_margin_quality(self, margins: Dict) -> str:
+        """Assess margin quality"""
+        operating_margin = margins.get('operating_margin_current') or margins.get('operating_margin')
+        margin_trend = margins.get('operating_margin_trend')
+        
+        if operating_margin is None:
+            return "Insufficient Data"
+        
+        if operating_margin > 0.20 and (margin_trend is None or margin_trend >= 0):
+            return "Excellent"
+        elif operating_margin > 0.10 and (margin_trend is None or margin_trend >= 0):
+            return "Good"
+        elif operating_margin > 0.05:
+            return "Moderate"
+        else:
+            return "Weak"
+    
+    def _assess_returns_quality(self, returns: Dict) -> str:
+        """Assess returns quality"""
+        roe = returns.get('roe')
+        roic = returns.get('roic')
+        
+        primary_return = roic if roic is not None else roe
+        
+        if primary_return is None:
+            return "Insufficient Data"
+        
+        if primary_return > 0.20:
+            return "Excellent"
+        elif primary_return > 0.15:
+            return "Good"
+        elif primary_return > 0.10:
+            return "Moderate"
+        else:
+            return "Weak"
+    
+    def _assess_cash_flow_quality(self, cash_flow: Dict) -> str:
+        """Assess cash flow quality"""
+        fcf = cash_flow.get('free_cash_flow', 0)
+        fcf_conversion = cash_flow.get('fcf_conversion')
+        
+        if fcf <= 0:
+            return "Negative"
+        
+        if fcf_conversion and fcf_conversion > 1.0:
+            return "Excellent"
+        elif fcf_conversion and fcf_conversion > 0.8:
+            return "Good"
+        elif fcf > 0:
+            return "Moderate"
+        else:
+            return "Weak"
+    
+    def _assess_financial_health(self, health: Dict) -> str:
+        """Assess financial health"""
+        net_debt = health.get('net_debt', 0)
+        current_ratio = health.get('current_ratio')
+        interest_coverage = health.get('interest_coverage')
+        
+        # Net cash position is excellent
+        if net_debt < 0:
+            return "Excellent"
+        
+        # Check liquidity and debt coverage
+        healthy_liquidity = current_ratio and current_ratio > 1.5
+        healthy_coverage = interest_coverage and interest_coverage > 3
+        
+        if healthy_liquidity and healthy_coverage:
+            return "Good"
+        elif (current_ratio and current_ratio > 1.0) or (interest_coverage and interest_coverage > 1.5):
+            return "Moderate"
+        else:
+            return "Weak"
+    
+    def generate_summary(self) -> Dict:
+        """
+        Generate comprehensive analysis summary
+        
+        Returns:
+            Complete analysis results
+        """
+        return {
+            'ticker': self.ticker,
+            'company_name': self.company_info.get('company_name', self.ticker),
+            'sector': self.company_info.get('sector', 'Unknown'),
+            'industry': self.company_info.get('industry', 'Unknown'),
+            'analysis_date': datetime.now().isoformat(),
+            'growth_analysis': self.analyze_growth(),
+            'margin_analysis': self.analyze_margins(),
+            'returns_analysis': self.analyze_returns(),
+            'cash_flow_analysis': self.analyze_cash_flow(),
+            'financial_health': self.analyze_financial_health()
+        }
+
+
+if __name__ == "__main__":
+    # Test with sample data
+    print("This module is meant to be imported and used with data from data_fetcher.py")

src/fundamental_analysis/main.py

@@ -0,0 +1,32 @@
+"""
+Main Entry Point for Stock Analysis
+Simple interface to analyze stocks and get BUY/SELL/HOLD recommendations
+"""
+
+from fundamental_analysis.decision_maker import evaluate_stock
+import sys
+
+
+def main():
+    """Main function for stock analysis"""
+    # Get ticker from command line or user input
+    if len(sys.argv) > 1:
+        ticker = sys.argv[1].upper()
+    else:
+        ticker = input("\nEnter stock ticker (e.g., AAPL, GOOGL, MSFT): ").strip().upper()
+    if not ticker:
+        print("Error: No ticker provided")
+        return
+    # Ask about sector comparison
+    if len(sys.argv) > 2 and sys.argv[2].lower() in ['--no-sector', '-n']:
+        compare_sector = False
+    else:
+        use_sector = input("\nCompare to sector peers? (Y/n): ").strip().lower()
+        compare_sector = use_sector != 'n'
+    # Analyze the stock
+    result = evaluate_stock(ticker, compare_to_sector=compare_sector)
+    return result
+
+
+if __name__ == "__main__":
+    main()

src/fundamental_analysis/metrics.py

@@ -0,0 +1,616 @@
+"""
+Individual metric calculation functions.
+Each function is self-contained and follows formulas from stock_evaluation_formulas_and_process.md
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, Optional, Tuple
+
+
+# ============================================================================
+# 1. BUILDING BLOCKS & DATA EXTRACTION
+# ============================================================================
+
+def get_diluted_shares(info: Dict, financials: Dict) -> Optional[float]:
+    """Get diluted shares outstanding"""
+    return info.get('sharesOutstanding') or financials.get('shares_outstanding')
+
+
+def get_eps_ttm(info: Dict) -> Optional[float]:
+    """Earnings Per Share - Trailing Twelve Months"""
+    return info.get('trailingEps')
+
+
+def get_eps_forward(info: Dict) -> Optional[float]:
+    """Earnings Per Share - Forward (Next 12 months)"""
+    return info.get('forwardEps')
+
+
+def get_book_value_per_share(info: Dict) -> Optional[float]:
+    """Book Value Per Share"""
+    return info.get('bookValue')
+
+
+# ============================================================================
+# 2. VALUATION METRICS
+# ============================================================================
+
+def calculate_market_cap(price: float, diluted_shares: float) -> Optional[float]:
+    """
+    Market Capitalization
+    Formula: MktCap = Share Price × Diluted Shares
+    """
+    if type(price) in [int, float] and type(diluted_shares) in [int, float]:
+        return price * diluted_shares
+    return None
+
+
+def calculate_enterprise_value(market_cap: float, total_debt: float, 
+                               cash: float, minority_interest: float = 0,
+                               preferred_stock: float = 0) -> Optional[float]:
+    """
+    Enterprise Value
+    Formula: EV = MktCap + Total Debt + Minority Interest + Preferred Stock − Cash
+    
+    Explanation: Total value of firm's operating assets available to all capital providers
+    """
+    if type(market_cap) in [int, float] and type(total_debt) in [int, float] and \
+       type(cash) in [int, float] and type(minority_interest) in [int, float] and \
+       type(preferred_stock) in [int, float]:
+        return market_cap + total_debt + minority_interest + preferred_stock - cash
+    return None
+
+
+def calculate_pe_ratio(price: float, eps: float) -> Optional[float]:
+    """
+    Price-to-Earnings Ratio
+    Formula: P/E = Share Price / EPS
+    
+    Explanation: How many dollars investors pay per dollar of earnings
+    """
+    if type(price) in [int, float] and type(eps) in [int, float]:
+        if eps and eps > 0:
+            return price / eps
+    return None
+
+
+def calculate_peg_ratio(pe_ratio: float, eps_growth_rate: float) -> Optional[float]:
+    """
+    PEG Ratio (Price/Earnings-to-Growth)
+    Formula: PEG = P/E / (Expected EPS annual growth rate in %)
+    
+    Explanation: Normalizes PE by growth. PEG ≈ 1 implies valuation equals growth
+    Threshold: PEG < 1 suggests value, PEG > 1.5 suggests expensive
+    """
+    if type(pe_ratio) in [int, float] and type(eps_growth_rate) in [int, float]:
+        if pe_ratio and eps_growth_rate and eps_growth_rate > 0:
+            return pe_ratio / (eps_growth_rate * 100)
+    return None
+
+
+def calculate_ev_ebitda(enterprise_value: float, ebitda: float) -> Optional[float]:
+    """
+    EV/EBITDA Multiple
+    Formula: EV/EBITDA = Enterprise Value / EBITDA
+    
+    Explanation: Capital-structure neutral valuation, useful for comparing 
+    companies with different leverage
+    """
+    if type(enterprise_value) in [int, float] and type(ebitda) in [int, float]:
+        if ebitda and ebitda > 0:
+            return enterprise_value / ebitda
+    return None
+
+
+def calculate_price_to_fcf(market_cap: float, free_cash_flow: float) -> Optional[float]:
+    """
+    Price to Free Cash Flow
+    Formula: P/FCF = Market Cap / Free Cash Flow
+    
+    Explanation: How many dollars investors pay per dollar of free cash flow
+    """
+    if type(market_cap) in [int, float] and type(free_cash_flow) in [int, float]:
+        if free_cash_flow and free_cash_flow > 0:
+            return market_cap / free_cash_flow
+    return None
+
+
+def calculate_fcf_yield_equity(free_cash_flow: float, market_cap: float) -> Optional[float]:
+    """
+    Free Cash Flow Yield (Equity basis)
+    Formula: FCF yield = Free Cash Flow / Market Cap
+    
+    Explanation: Cash return on equity investment
+    Threshold: > 6% = attractive, < 3% = expensive
+    Priority: HIGHEST - measures actual cash generation
+    """
+    if type(free_cash_flow) in [int, float] and type(market_cap) in [int, float]:
+        if market_cap and market_cap > 0:
+            return (free_cash_flow / market_cap) * 100  # Return as percentage
+    return None
+
+
+def calculate_fcf_yield_enterprise(free_cash_flow: float, enterprise_value: float) -> Optional[float]:
+    """
+    Free Cash Flow Yield (Enterprise basis)
+    Formula: FCF yield = Free Cash Flow / EV
+    
+    Explanation: Cash return on enterprise value (preferred for comparing 
+    leveraged vs unleveraged firms)
+    Threshold: > 6% = Buy candidate, 4-6% = Hold, < 3% = Unattractive
+    """
+    if type(free_cash_flow) in [int, float] and type(enterprise_value) in [int, float]:
+        if enterprise_value and enterprise_value > 0:
+            return (free_cash_flow / enterprise_value) * 100  # Return as percentage
+    return None
+
+
+def calculate_price_to_book(price: float, book_value_per_share: float) -> Optional[float]:
+    """
+    Price-to-Book Ratio
+    Formula: P/B = Price / Book Value per Share
+    
+    Explanation: Valuation relative to net asset value
+    """
+    if type(price) in [int, float] and type(book_value_per_share) in [int, float]:
+        if book_value_per_share and book_value_per_share > 0:
+            return price / book_value_per_share
+    return None
+
+
+# ============================================================================
+# 3. PROFITABILITY & MARGIN METRICS
+# ============================================================================
+
+def calculate_gross_margin(revenue: float, cogs: float) -> Optional[float]:
+    """
+    Gross Margin
+    Formula: Gross margin = (Revenue − COGS) / Revenue
+    
+    Explanation: Unit economics - whether price > cost. Rising gross margins 
+    imply pricing power or scale
+    """
+    if type(revenue) in [int, float] and type(cogs) in [int, float]:
+        if revenue and revenue > 0:
+            return ((revenue - cogs) / revenue) * 100
+    return None
+
+
+def calculate_ebitda_margin(ebitda: float, revenue: float) -> Optional[float]:
+    """
+    EBITDA Margin
+    Formula: EBITDA margin = EBITDA / Revenue
+    
+    Explanation: Operational cash profitability before capital structure and non-cash charges
+    """
+    if type(ebitda) in [int, float] and type(revenue) in [int, float]:
+        if revenue and revenue > 0:
+            return (ebitda / revenue) * 100
+    return None
+
+
+def calculate_ebit_margin(ebit: float, revenue: float) -> Optional[float]:
+    """
+    EBIT (Operating) Margin
+    Formula: EBIT margin = EBIT / Revenue
+    
+    Explanation: Includes depreciation/amortization; useful for capital-intensive businesses
+    """
+    if type(ebit) in [int, float] and type(revenue) in [int, float]:
+        if revenue and revenue > 0:
+            return (ebit / revenue) * 100
+    return None
+
+
+def calculate_net_margin(net_income: float, revenue: float) -> Optional[float]:
+    """
+    Net Margin
+    Formula: Net margin = Net Income / Revenue
+    
+    Explanation: True bottom-line profitability after interest and tax
+    """
+    if type(net_income) in [int, float] and type(revenue) in [int, float]:
+        if revenue and revenue > 0:
+            return (net_income / revenue) * 100
+    return None
+
+
+# ============================================================================
+# 4. CASH FLOW METRICS
+# ============================================================================
+
+def calculate_free_cash_flow(cash_from_operations: float, capex: float) -> Optional[float]:
+    """
+    Free Cash Flow
+    Formula: FCF = Cash from Operations − Capital Expenditures
+    
+    Explanation: Actual cash business generates after reinvestment. 
+    This is the ULTIMATE value driver.
+    """
+    if type(cash_from_operations) in [int, float] and type(capex) in [int, float]:
+        return cash_from_operations - abs(capex)  # CapEx is usually negative
+    return None
+
+
+def calculate_fcf_per_share(free_cash_flow: float, diluted_shares: float) -> Optional[float]:
+    """
+    Free Cash Flow per Share
+    Formula: FCF per share = Free Cash Flow / Diluted Shares
+    
+    Explanation: Per-share cash generation, adjusted for dilution
+    """
+    if type(free_cash_flow) in [int, float] and type(diluted_shares) in [int, float]:
+        if diluted_shares and diluted_shares > 0:
+            return free_cash_flow / diluted_shares
+    return None
+
+
+def calculate_cash_conversion(cfo: float, net_income: float) -> Optional[float]:
+    """
+    Cash Conversion Ratio
+    Formula: Cash Conversion = CFO / Net Income
+    
+    Explanation: Measures quality of earnings. Should be > 1.0
+    RED FLAG if consistently < 1.0 (profits not converting to cash)
+    """
+    if type(cfo) in [int, float] and type(net_income) in [int, float]:
+        if net_income and net_income != 0:
+            return cfo / net_income
+    return None
+
+
+# ============================================================================
+# 5. LIQUIDITY & SOLVENCY METRICS
+# ============================================================================
+
+def calculate_current_ratio(current_assets: float, current_liabilities: float) -> Optional[float]:
+    """
+    Current Ratio
+    Formula: Current ratio = Current Assets / Current Liabilities
+    
+    Explanation: Basic short-term liquidity. > 1 is typical
+    """
+    if type(current_assets) in [int, float] and type(current_liabilities) in [int, float]:
+        if current_liabilities and current_liabilities > 0:
+            return current_assets / current_liabilities
+    return None
+
+
+def calculate_quick_ratio(cash: float, marketable_securities: float, 
+                          receivables: float, current_liabilities: float) -> Optional[float]:
+    """
+    Quick Ratio (Acid Test)
+    Formula: Quick ratio = (Cash + Marketable Securities + Receivables) / Current Liabilities
+    
+    Explanation: Stricter liquidity measure excluding inventory
+    """
+    if type(cash) in [int, float] and type(marketable_securities) in [int, float] and \
+    type(receivables) in [int, float] and type(current_liabilities) in [int, float]:
+        if current_liabilities and current_liabilities > 0:
+            return (cash + marketable_securities + receivables) / current_liabilities
+    return None
+
+
+def calculate_net_debt_to_ebitda(total_debt: float, cash: float, ebitda: float) -> Optional[float]:
+    """
+    Net Debt to EBITDA
+    Formula: Net debt / EBITDA = (Total Debt − Cash) / EBITDA
+    
+    Explanation: Years of EBITDA required to pay net debt
+    Thresholds:
+    - < 1.0: Low risk
+    - 1-3: Moderate
+    - > 3: High risk (alert if > 4-5)
+    """
+    if type(total_debt) in [int, float] and type(cash) in [int, float] and type(ebitda) in [int, float]:
+        if ebitda and ebitda > 0:
+            net_debt = total_debt - cash
+            return net_debt / ebitda
+    return None
+
+
+def calculate_interest_coverage(ebit: float, interest_expense: float) -> Optional[float]:
+    """
+    Interest Coverage Ratio
+    Formula: Interest coverage = EBIT / Interest Expense
+    
+    Explanation: Ability to pay interest from operating earnings
+    Threshold: > 3x is safe, < 2x is risky
+    """
+    if type(ebit) in [int, float] and type(interest_expense) in [int, float]:
+        if interest_expense and interest_expense > 0:
+            return ebit / interest_expense
+    return None
+
+
+def calculate_debt_to_equity(total_debt: float, total_equity: float) -> Optional[float]:
+    """
+    Debt-to-Equity Ratio
+    Formula: Debt-to-Equity = Total Debt / Total Equity
+    
+    Explanation: Capital structure leverage
+    """
+    if type(total_debt) in [int, float] and type(total_equity) in [int, float]:
+        if total_equity and total_equity > 0:
+            return total_debt / total_equity
+    return None
+
+
+# ============================================================================
+# 6. RETURN & EFFICIENCY METRICS
+# ============================================================================
+
+def calculate_roe(net_income: float, avg_shareholders_equity: float) -> Optional[float]:
+    """
+    Return on Equity
+    Formula: ROE = Net Income / Average Shareholders' Equity
+    
+    Explanation: Returns delivered to equity holders
+    Threshold: > 15% is good, > 20% is excellent
+    Priority: HIGH - quality indicator
+    """
+    if type(net_income) in [int, float] and type(avg_shareholders_equity) in [int, float]:
+        if avg_shareholders_equity and avg_shareholders_equity > 0:
+            return (net_income / avg_shareholders_equity) * 100
+    return None
+
+
+def calculate_roa(net_income: float, total_assets: float) -> Optional[float]:
+    """
+    Return on Assets
+    Formula: ROA = Net Income / Total Assets
+    
+    Explanation: Asset utilization efficiency
+    """
+    if type(net_income) in [int, float] and type(total_assets) in [int, float]:
+        if total_assets and total_assets > 0:
+            return (net_income / total_assets) * 100
+    return None
+
+
+def calculate_roic(ebit: float, tax_rate: float, invested_capital: float) -> Optional[float]:
+    """
+    Return on Invested Capital
+    Formula: 
+        NOPAT = EBIT × (1 − Tax Rate)
+        ROIC = NOPAT / Invested Capital
+    Where: Invested Capital = Total Equity + Total Debt - Cash
+    
+    Explanation: Operating return on all capital (equity + debt)
+    Thresholds:
+    - > 10%: Good
+    - > 15%: Excellent (high-quality business)
+    - Trending up: High-return projects
+    Priority: VERY HIGH - best measure of capital efficiency
+    """
+    if type(ebit) in [int, float] and type(tax_rate) in [int, float] and type(invested_capital) in [int, float]:
+        if invested_capital and invested_capital > 0:
+            nopat = ebit * (1 - tax_rate)
+            return (nopat / invested_capital) * 100
+    return None
+
+
+def calculate_invested_capital(total_equity: float, total_debt: float, cash: float) -> Optional[float]:
+    """
+    Invested Capital
+    Formula: Invested Capital = Total Equity + Total Debt - Cash
+    
+    Explanation: Total capital deployed in operations
+    """
+    if type(total_equity) in [int, float] and type(total_debt) in [int, float] and type(cash) in [int, float]:
+        return total_equity + total_debt - cash
+    return None
+
+
+# ============================================================================
+# 7. GROWTH METRICS
+# ============================================================================
+
+def calculate_revenue_growth(current_revenue: float, prior_revenue: float) -> Optional[float]:
+    """
+    Revenue Growth Rate (YoY)
+    Formula: Revenue Growth = (Current Revenue - Prior Revenue) / Prior Revenue
+    
+    Explanation: Top-line growth momentum
+    """
+    if type(current_revenue) in [int, float] and type(prior_revenue) in [int, float]:
+        if prior_revenue and prior_revenue > 0:
+            return ((current_revenue - prior_revenue) / prior_revenue) * 100
+    return None
+
+
+def calculate_eps_growth(current_eps: float, prior_eps: float) -> Optional[float]:
+    """
+    EPS Growth Rate (YoY)
+    Formula: EPS Growth = (Current EPS - Prior EPS) / Prior EPS
+    
+    Explanation: Bottom-line growth momentum
+    """
+    if type(current_eps) in [int, float] and type(prior_eps) in [int, float]:
+        if prior_eps and prior_eps > 0:
+            return ((current_eps - prior_eps) / prior_eps) * 100
+    return None
+
+
+def calculate_cagr(ending_value: float, beginning_value: float, years: int) -> Optional[float]:
+    """
+    Compound Annual Growth Rate
+    Formula: CAGR = (Ending Value / Beginning Value)^(1/years) - 1
+    
+    Explanation: Smoothed annual growth rate over period
+    """
+    if type(ending_value) in [int, float] and type(beginning_value) in [int, float] and type(years) in [int, float]:
+        if beginning_value and beginning_value > 0 and years > 0:
+            return (((ending_value / beginning_value) ** (1 / years)) - 1) * 100
+    return None
+
+
+def calculate_sustainable_growth(roe: float, payout_ratio: float) -> Optional[float]:
+    """
+    Sustainable EPS Growth
+    Formula: Sustainable Growth = ROE × (1 - Payout Ratio)
+    Or: Sustainable Growth = ROE × Reinvestment Rate
+    
+    Explanation: Theoretical growth rate based on returns and reinvestment
+    """
+    if type(roe) in [int, float] and type(payout_ratio) in [int, float]:
+        reinvestment_rate = 1 - payout_ratio
+        return roe * reinvestment_rate
+    return None
+
+
+# ============================================================================
+# 8. CAPITAL ALLOCATION METRICS
+# ============================================================================
+
+def calculate_payout_ratio(dividends: float, net_income: float) -> Optional[float]:
+    """
+    Payout Ratio
+    Formula: Payout Ratio = Dividends / Net Income
+    
+    Explanation: Proportion of earnings paid as dividends
+    """
+    if type(dividends) in [int, float] and type(net_income) in [int, float]:
+        if net_income and net_income > 0:
+            return (dividends / net_income) * 100
+    return None
+
+
+def calculate_buyback_yield(buyback_cash: float, market_cap: float) -> Optional[float]:
+    """
+    Buyback Yield
+    Formula: Buyback Yield = Cash spent on repurchases / Market Cap
+    
+    Explanation: Return to shareholders via buybacks
+    """
+    if type(buyback_cash) in [int, float] and type(market_cap) in [int, float]:
+        if market_cap and market_cap > 0:
+            return (buyback_cash / market_cap) * 100
+    return None
+
+
+def calculate_dilution_rate(current_shares: float, prior_shares: float) -> Optional[float]:
+    """
+    Dilution Rate
+    Formula: Dilution = (Current Shares - Prior Shares) / Prior Shares
+    
+    Explanation: Share count increase (dilution) or decrease (buybacks)
+    Negative value = buybacks, Positive value = dilution
+    """
+    if type(current_shares) in [int, float] and type(prior_shares) in [int, float]:
+        if prior_shares and prior_shares > 0:
+            return ((current_shares - prior_shares) / prior_shares) * 100
+    return None
+
+
+def calculate_total_payout_ratio(dividends: float, buybacks: float, net_income: float) -> Optional[float]:
+    """
+    Total Payout Ratio (including buybacks)
+    Formula: Total Payout = (Dividends + Buybacks) / Net Income
+    
+    Explanation: Total cash returned to shareholders
+    """
+    if type(dividends) in [int, float] and type(buybacks) in [int, float] and type(net_income) in [int, float]:
+        if net_income and net_income > 0:
+            return ((dividends + buybacks) / net_income) * 100
+    return None
+
+
+# ============================================================================
+# 9. EFFICIENCY METRICS
+# ============================================================================
+
+def calculate_asset_turnover(revenue: float, total_assets: float) -> Optional[float]:
+    """
+    Asset Turnover
+    Formula: Asset Turnover = Revenue / Total Assets
+    
+    Explanation: How efficiently assets generate revenue
+    """
+    if type(revenue) in [int, float] and type(total_assets) in [int, float]:
+        if total_assets and total_assets > 0:
+            return revenue / total_assets
+    return None
+
+
+def calculate_inventory_turnover(cogs: float, avg_inventory: float) -> Optional[float]:
+    """
+    Inventory Turnover
+    Formula: Inventory Turnover = COGS / Average Inventory
+    
+    Explanation: How quickly inventory is sold
+    """
+    if type(cogs) in [int, float] and type(avg_inventory) in [int, float]:
+        if avg_inventory and avg_inventory > 0:
+            return cogs / avg_inventory
+    return None
+
+
+def calculate_receivables_turnover(revenue: float, avg_receivables: float) -> Optional[float]:
+    """
+    Receivables Turnover
+    Formula: Receivables Turnover = Revenue / Average Receivables
+    
+    Explanation: How quickly receivables are collected
+    """
+    if type(revenue) in [int, float] and type(avg_receivables) in [int, float]:
+        if avg_receivables and avg_receivables > 0:
+            return revenue / avg_receivables
+    return None
+
+
+# ============================================================================
+# 10. WORKING CAPITAL METRICS
+# ============================================================================
+
+def calculate_working_capital(current_assets: float, current_liabilities: float) -> Optional[float]:
+    """
+    Working Capital
+    Formula: Working Capital = Current Assets - Current Liabilities
+    
+    Explanation: Short-term operational liquidity
+    """
+    if type(current_assets) in [int, float] and type(current_liabilities) in [int, float]:
+        return current_assets - current_liabilities
+    return None
+
+
+def calculate_working_capital_ratio(working_capital: float, revenue: float) -> Optional[float]:
+    """
+    Working Capital to Revenue
+    Formula: WC Ratio = Working Capital / Revenue
+    
+    Explanation: Capital tied up in operations
+    """
+    if type(working_capital) in [int, float] and type(revenue) in [int, float]:
+        if revenue and revenue > 0:
+            return (working_capital / revenue) * 100
+    return None
+
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+def safe_divide(numerator: float, denominator: float, 
+                default: Optional[float] = None) -> Optional[float]:
+    """Safely divide two numbers, returning default if denominator is 0"""
+    if type(numerator) in [int, float] and type(denominator) in [int, float]:
+        if denominator and denominator != 0:
+            return numerator / denominator
+    return default
+
+
+def calculate_average(value1: float, value2: float) -> Optional[float]:
+    """Calculate average of two values"""
+    if type(value1) in [int, float] and type(value2) in [int, float]:
+        return (value1 + value2) / 2
+    return None
+
+
+def annualize_quarterly(quarterly_value: float) -> Optional[float]:
+    """Convert quarterly value to annual (TTM)"""
+    if type(quarterly_value) in [int, float]:
+        return quarterly_value * 4
+    return None

src/fundamental_analysis/sector_analyzer.py

@@ -0,0 +1,415 @@
+"""
+Sector Analyzer
+Get all important stocks for a sector and perform peer comparison analysis
+"""
+
+import yfinance as yf
+import pandas as pd
+import numpy as np
+from typing import List, Dict, Optional, Tuple
+from fundamental_analysis.calculator import calculate_metrics_for_ticker
+import warnings
+warnings.filterwarnings('ignore')
+
+
+# Predefined sector/industry stock lists
+# These can be expanded or replaced with dynamic fetching from financial APIs
+SECTOR_STOCKS = {
+    'Technology': {
+        'Mega Cap': ['AAPL', 'MSFT', 'GOOGL', 'META', 'NVDA', 'TSLA', 'AVGO', 'ORCL', 'ADBE', 'CRM'],
+        'Large Cap': ['AMD', 'INTC', 'QCOM', 'TXN', 'AMAT', 'ADI', 'LRCX', 'KLAC', 'SNPS', 'CDNS'],
+        'Mid Cap': ['SNOW', 'CRWD', 'NET', 'DDOG', 'ZS', 'OKTA', 'MDB', 'TEAM', 'WDAY', 'PANW']
+    },
+    'Financial': {
+        'Banks': ['JPM', 'BAC', 'WFC', 'C', 'GS', 'MS', 'USB', 'PNC', 'TFC', 'SCHW'],
+        'Insurance': ['BRK-B', 'UNH', 'PGR', 'MET', 'PRU', 'AIG', 'ALL', 'TRV', 'AXP', 'CB'],
+        'Asset Management': ['BLK', 'BX', 'KKR', 'APO', 'TROW', 'IVZ', 'BEN', 'AMG']
+    },
+    'Healthcare': {
+        'Pharma': ['JNJ', 'PFE', 'ABBV', 'MRK', 'LLY', 'TMO', 'ABT', 'BMY', 'AMGN', 'GILD'],
+        'Biotech': ['VRTX', 'REGN', 'BIIB', 'ILMN', 'MRNA', 'BNTX', 'ALNY', 'SGEN', 'INCY', 'EXAS'],
+        'Medical Devices': ['MDT', 'DHR', 'SYK', 'BSX', 'EW', 'ZBH', 'BAX', 'IDXX', 'ALGN', 'HOLX']
+    },
+    'Consumer': {
+        'Retail': ['AMZN', 'WMT', 'HD', 'LOW', 'TGT', 'COST', 'TJX', 'ROST', 'DG', 'DLTR'],
+        'Consumer Goods': ['PG', 'KO', 'PEP', 'PM', 'MDLZ', 'CL', 'EL', 'KMB', 'GIS', 'K'],
+        'Restaurants': ['MCD', 'SBUX', 'CMG', 'YUM', 'QSR', 'DPZ', 'DRI', 'TXRH', 'WING', 'SHAK']
+    },
+    'Industrial': {
+        'Aerospace': ['BA', 'RTX', 'LMT', 'NOC', 'GD', 'HON', 'GE', 'TDG', 'HWM', 'LDOS'],
+        'Manufacturing': ['CAT', 'DE', 'ETN', 'EMR', 'ITW', 'ROK', 'PH', 'IR', 'AME', 'XYL'],
+        'Transportation': ['UPS', 'FDX', 'UNP', 'NSC', 'CSX', 'DAL', 'UAL', 'AAL', 'LUV', 'JBHT']
+    },
+    'Energy': {
+        'Oil & Gas': ['XOM', 'CVX', 'COP', 'EOG', 'SLB', 'MPC', 'PSX', 'VLO', 'OXY', 'HES'],
+        'Utilities': ['NEE', 'DUK', 'SO', 'D', 'AEP', 'EXC', 'SRE', 'XEL', 'WEC', 'ES']
+    },
+    'Materials': ['LIN', 'APD', 'SHW', 'ECL', 'NEM', 'FCX', 'NUE', 'VMC', 'MLM', 'DOW'],
+    'Real Estate': ['PLD', 'AMT', 'CCI', 'EQIX', 'PSA', 'DLR', 'WELL', 'AVB', 'EQR', 'VICI'],
+    'Communication': ['GOOGL', 'META', 'NFLX', 'DIS', 'CMCSA', 'T', 'VZ', 'TMUS', 'CHTR', 'PARA']
+}
+
+
+class SectorAnalyzer:
+    """Analyze stocks within a sector for peer comparison"""
+    
+    def __init__(self, sector: str, subsector: Optional[str] = None):
+        """
+        Initialize sector analyzer
+        
+        Args:
+            sector: Main sector name (e.g., 'Technology', 'Healthcare')
+            subsector: Optional subsector/industry (e.g., 'Banks', 'Pharma')
+        """
+        self.sector = sector
+        self.subsector = subsector
+        self.tickers = []
+        self.metrics_data = {}
+        
+    def get_sector_tickers(self) -> List[str]:
+        """
+        Get list of tickers for the sector/subsector
+        
+        Returns:
+            List of ticker symbols
+        """
+        if self.sector not in SECTOR_STOCKS:
+            print(f"Warning: Sector '{self.sector}' not found in predefined list")
+            print(f"Available sectors: {list(SECTOR_STOCKS.keys())}")
+            return []
+        
+        sector_data = SECTOR_STOCKS[self.sector]
+        
+        # If sector has subsectors (nested dict)
+        if isinstance(sector_data, dict) and any(isinstance(v, list) for v in sector_data.values()):
+            if self.subsector:
+                if self.subsector in sector_data:
+                    self.tickers = sector_data[self.subsector]
+                else:
+                    print(f"Warning: Subsector '{self.subsector}' not found")
+                    print(f"Available subsectors: {list(sector_data.keys())}")
+                    return []
+            else:
+                # Flatten all subsectors
+                self.tickers = [ticker for subsector_list in sector_data.values() 
+                               for ticker in subsector_list]
+        else:
+            # Direct list of tickers
+            self.tickers = sector_data
+        
+        print(f"Found {len(self.tickers)} tickers for {self.sector}" + 
+              (f" > {self.subsector}" if self.subsector else ""))
+        
+        return self.tickers
+    
+    def calculate_sector_metrics(self, tickers: Optional[List[str]] = None) -> pd.DataFrame:
+        """
+        Calculate metrics for all stocks in the sector
+        
+        Args:
+            tickers: Optional custom list of tickers (uses sector tickers if None)
+        
+        Returns:
+            DataFrame with all stocks and their key metrics
+        """
+        if tickers is None:
+            tickers = self.tickers if self.tickers else self.get_sector_tickers()
+        
+        if not tickers:
+            print("No tickers to analyze")
+            return pd.DataFrame()
+        
+        print(f"\nCalculating metrics for {len(tickers)} stocks...")
+        print("=" * 80)
+        
+        results = []
+        failed_tickers = []
+        
+        for i, ticker in enumerate(tickers, 1):
+            print(f"\n[{i}/{len(tickers)}] Processing {ticker}...")
+            
+            try:
+                metrics_df, summary = calculate_metrics_for_ticker(ticker)
+                
+                if metrics_df.empty:
+                    print(f"✗ Failed to get data for {ticker}")
+                    failed_tickers.append(ticker)
+                    continue
+                
+                # Extract key metrics for comparison
+                key_metrics = self._extract_key_metrics(ticker, metrics_df)
+                results.append(key_metrics)
+                
+                # Store full metrics for later reference
+                self.metrics_data[ticker] = metrics_df
+                
+            except Exception as e:
+                print(f"✗ Error processing {ticker}: {str(e)}")
+                failed_tickers.append(ticker)
+                continue
+        
+        if not results:
+            print("\n✗ No data collected for any tickers")
+            return pd.DataFrame()
+        
+        # Create comparison DataFrame
+        comparison_df = pd.DataFrame(results)
+        comparison_df = comparison_df.set_index('Ticker')
+        
+        print("\n" + "=" * 80)
+        print(f"✓ Successfully processed {len(results)}/{len(tickers)} stocks")
+        if failed_tickers:
+            print(f"✗ Failed: {', '.join(failed_tickers)}")
+        
+        return comparison_df
+    
+    def _extract_key_metrics(self, ticker: str, metrics_df: pd.DataFrame) -> Dict:
+        """Extract key metrics for peer comparison"""
+        
+        def get_metric_value(metric_name: str) -> Optional[float]:
+            """Helper to safely extract metric value"""
+            row = metrics_df[metrics_df['Metric'] == metric_name]
+            if not row.empty and row.iloc[0]['Status'] == 'Available':
+                return row.iloc[0]['Value']
+            return None
+        
+        key_metrics = {
+            'Ticker': ticker,
+            
+            # Valuation
+            'Market_Cap': get_metric_value('Market Capitalization'),
+            'PE_Ratio': get_metric_value('P/E Ratio (TTM)'),
+            'PEG_Ratio': get_metric_value('PEG Ratio'),
+            'EV_EBITDA': get_metric_value('EV/EBITDA'),
+            'Price_FCF': get_metric_value('Price / FCF'),
+            'FCF_Yield_%': get_metric_value('FCF Yield (Enterprise) %'),
+            'Price_Book': get_metric_value('Price / Book'),
+            
+            # Profitability
+            'Gross_Margin_%': get_metric_value('Gross Margin %'),
+            'EBITDA_Margin_%': get_metric_value('EBITDA Margin %'),
+            'Net_Margin_%': get_metric_value('Net Margin %'),
+            
+            # Cash Flow
+            'Free_Cash_Flow': get_metric_value('Free Cash Flow'),
+            'Cash_Conversion': get_metric_value('Cash Conversion Ratio'),
+            
+            # Leverage
+            'Net_Debt_EBITDA': get_metric_value('Net Debt / EBITDA'),
+            'Debt_Equity': get_metric_value('Debt / Equity'),
+            'Current_Ratio': get_metric_value('Current Ratio'),
+            
+            # Returns
+            'ROE_%': get_metric_value('Return on Equity (ROE) %'),
+            'ROA_%': get_metric_value('Return on Assets (ROA) %'),
+            'ROIC_%': get_metric_value('Return on Invested Capital (ROIC) %'),
+            
+            # Growth
+            'Revenue_Growth_%': get_metric_value('Revenue Growth (YoY) %'),
+            'EPS_Growth_%': get_metric_value('EPS Growth (YoY) %'),
+            
+            # Capital Allocation
+            'Payout_Ratio_%': get_metric_value('Payout Ratio %'),
+            'Total_Payout_%': get_metric_value('Total Payout Ratio %'),
+        }
+        
+        return key_metrics
+    
+    def get_peer_statistics(self, comparison_df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Calculate sector statistics (median, mean, percentiles)
+        
+        Args:
+            comparison_df: DataFrame from calculate_sector_metrics
+        
+        Returns:
+            DataFrame with sector statistics
+        """
+        if comparison_df.empty:
+            return pd.DataFrame()
+        
+        stats_df = pd.DataFrame({
+            'Median': comparison_df.median(),
+            'Mean': comparison_df.mean(),
+            'Std_Dev': comparison_df.std(),
+            'Min': comparison_df.min(),
+            'Q1': comparison_df.quantile(0.25),
+            'Q3': comparison_df.quantile(0.75),
+            'Max': comparison_df.max(),
+            'Count': comparison_df.count()
+        })
+        
+        return stats_df
+    
+    def compare_stock_to_peers(self, ticker: str, comparison_df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Compare a specific stock to sector peers
+        
+        Args:
+            ticker: Stock to compare
+            comparison_df: Sector comparison data
+        
+        Returns:
+            DataFrame showing stock vs sector statistics
+        """
+        if ticker not in comparison_df.index:
+            print(f"Ticker {ticker} not found in comparison data")
+            return pd.DataFrame()
+        
+        stock_data = comparison_df.loc[ticker]
+        sector_stats = self.get_peer_statistics(comparison_df)
+        
+        comparison = pd.DataFrame({
+            'Stock_Value': stock_data,
+            'Sector_Median': sector_stats['Median'],
+            'Sector_Mean': sector_stats['Mean'],
+            'Percentile_Rank': comparison_df.rank(pct=True).loc[ticker] * 100,
+            'vs_Median': ((stock_data - sector_stats['Median']) / sector_stats['Median'] * 100)
+        })
+        
+        return comparison
+    
+    def rank_stocks(self, comparison_df: pd.DataFrame, 
+                    metrics: Optional[List[str]] = None) -> pd.DataFrame:
+        """
+        Rank stocks based on key metrics
+        
+        Args:
+            comparison_df: Sector comparison data
+            metrics: List of metrics to rank by (None = use default key metrics)
+        
+        Returns:
+            DataFrame with rankings
+        """
+        if comparison_df.empty:
+            return pd.DataFrame()
+        
+        # Default key metrics for ranking (higher is better for most)
+        if metrics is None:
+            metrics = [
+                'FCF_Yield_%',      # Higher is better
+                'ROIC_%',           # Higher is better
+                'ROE_%',            # Higher is better
+                'Revenue_Growth_%', # Higher is better
+                'EPS_Growth_%',     # Higher is better
+            ]
+            
+            # Reverse ranking for these (lower is better)
+            reverse_metrics = [
+                'PE_Ratio',
+                'PEG_Ratio',
+                'EV_EBITDA',
+                'Net_Debt_EBITDA',
+                'Debt_Equity'
+            ]
+        
+        # Calculate composite score
+        scores = pd.DataFrame(index=comparison_df.index)
+        
+        for metric in metrics:
+            if metric in comparison_df.columns:
+                # Normalize and rank (higher is better)
+                scores[f'{metric}_rank'] = comparison_df[metric].rank(pct=True, na_option='keep')
+        
+        # Calculate average rank across all metrics
+        scores['Composite_Score'] = scores.mean(axis=1)
+        scores['Rank'] = scores['Composite_Score'].rank(ascending=False, method='min')
+        
+        # Add key metrics for context
+        result = scores[['Composite_Score', 'Rank']].copy()
+        for metric in metrics:
+            if metric in comparison_df.columns:
+                result[metric] = comparison_df[metric]
+        
+        return result.sort_values('Rank')
+
+
+def analyze_sector(sector: str, subsector: Optional[str] = None, 
+                   custom_tickers: Optional[List[str]] = None) -> Tuple[pd.DataFrame, pd.DataFrame, SectorAnalyzer]:
+    """
+    Main function to analyze a sector
+    
+    Args:
+        sector: Sector name
+        subsector: Optional subsector name
+        custom_tickers: Optional custom list of tickers
+    
+    Returns:
+        Tuple of (comparison_df, sector_stats, analyzer_object)
+    """
+    analyzer = SectorAnalyzer(sector, subsector)
+    
+    if custom_tickers:
+        comparison_df = analyzer.calculate_sector_metrics(custom_tickers)
+    else:
+        analyzer.get_sector_tickers()
+        comparison_df = analyzer.calculate_sector_metrics()
+    
+    sector_stats = analyzer.get_peer_statistics(comparison_df)
+    
+    return comparison_df, sector_stats, analyzer
+
+
+def list_available_sectors() -> None:
+    """Print all available sectors and subsectors"""
+    print("\nAVAILABLE SECTORS:")
+    print("=" * 80)
+    
+    for sector, data in SECTOR_STOCKS.items():
+        if isinstance(data, dict) and any(isinstance(v, list) for v in data.values()):
+            print(f"\n{sector}:")
+            for subsector, tickers in data.items():
+                print(f"  - {subsector} ({len(tickers)} stocks)")
+        else:
+            print(f"\n{sector}: {len(data)} stocks")
+
+
+if __name__ == "__main__":
+    # Test with a sample sector
+    print("SECTOR ANALYZER TEST")
+    print("=" * 80)
+    
+    # Show available sectors
+    list_available_sectors()
+    
+    # Test with a small subset of Technology stocks
+    print("\n\nTesting with Technology > Mega Cap (first 3 stocks)...")
+    print("=" * 80)
+    
+    test_tickers = ['AAPL', 'MSFT', 'GOOGL']
+    comparison_df, sector_stats, analyzer = analyze_sector('Technology', custom_tickers=test_tickers)
+    
+    if not comparison_df.empty:
+        print("\n" + "=" * 80)
+        print("COMPARISON DATA")
+        print("=" * 80)
+        
+        # Show key valuation metrics
+        valuation_cols = ['Market_Cap', 'PE_Ratio', 'PEG_Ratio', 'FCF_Yield_%', 'ROIC_%']
+        print("\nValuation Metrics:")
+        print(comparison_df[valuation_cols].to_string())
+        
+        # Show sector statistics
+        print("\n" + "=" * 80)
+        print("SECTOR STATISTICS")
+        print("=" * 80)
+        print(sector_stats.loc[valuation_cols].to_string())
+        
+        # Rank stocks
+        print("\n" + "=" * 80)
+        print("STOCK RANKINGS")
+        print("=" * 80)
+        rankings = analyzer.rank_stocks(comparison_df)
+        print(rankings.to_string())
+        
+        # Compare AAPL to peers
+        print("\n" + "=" * 80)
+        print("AAPL vs PEERS")
+        print("=" * 80)
+        aapl_comparison = analyzer.compare_stock_to_peers('AAPL', comparison_df)
+        print(aapl_comparison.loc[valuation_cols].to_string())
+        
+        # Save results
+        comparison_df.to_csv('sector_comparison.csv')
+        sector_stats.to_csv('sector_statistics.csv')
+        print("\n✓ Results saved to sector_comparison.csv and sector_statistics.csv")

src/fundamental_analysis/test_analyzer.py

@@ -0,0 +1,44 @@
+"""
+Quick test script for the fundamental analyzer
+"""
+
+import sys
+from fundamental_analysis.main import analyze_stock
+
+def test_basic_analysis():
+    """Test basic analysis with a well-known ticker"""
+    print("=" * 80)
+    print("Testing Fundamental Analyzer with AAPL")
+    print("=" * 80)
+    print()
+    
+    try:
+        # Test with Apple, comparing against major tech peers
+        peer_tickers = ["MSFT", "GOOGL", "META"]
+        
+        print("Running analysis for AAPL with peers: MSFT, GOOGL, META")
+        print("-" * 80)
+        print()
+        
+        analyze_stock("AAPL", peer_tickers)
+        
+        print()
+        print("=" * 80)
+        print("✓ Test completed successfully!")
+        print("=" * 80)
+        
+    except Exception as e:
+        print()
+        print("=" * 80)
+        print(f"✗ Test failed with error: {type(e).__name__}")
+        print(f"Error message: {str(e)}")
+        print("=" * 80)
+        import traceback
+        traceback.print_exc()
+        return False
+    
+    return True
+
+if __name__ == "__main__":
+    success = test_basic_analysis()
+    sys.exit(0 if success else 1)

src/fundamental_analysis/valuation_engine.py

@@ -0,0 +1,330 @@
+"""
+Valuation engine for stock analysis.
+Implements DCF, comparable multiples, and scenario analysis.
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, List, Optional, Tuple
+
+
+class ValuationEngine:
+    """Performs stock valuation using multiple methodologies"""
+    
+    def __init__(self, financial_data: Dict, analysis_results: Dict):
+        """
+        Initialize valuation engine
+        
+        Args:
+            financial_data: Complete dataset from FinancialDataFetcher
+            analysis_results: Results from FinancialAnalyzer
+        """
+        self.ticker = financial_data.get('ticker')
+        self.metrics = financial_data.get('metrics', {})
+        self.statements = financial_data.get('financial_statements', {})
+        self.sector_metrics = financial_data.get('sector_metrics', {})
+        self.analysis = analysis_results
+        
+    def calculate_intrinsic_value_dcf(self, 
+                                      growth_rate: float = 0.10,
+                                      terminal_growth: float = 0.02,
+                                      discount_rate: float = 0.10,
+                                      years: int = 5) -> Dict:
+        """
+        Calculate intrinsic value using DCF method
+        
+        Args:
+            growth_rate: Expected FCF growth rate
+            terminal_growth: Perpetual growth rate
+            discount_rate: WACC / required return
+            years: Forecast period
+            
+        Returns:
+            DCF valuation results
+        """
+        results = {
+            'method': 'DCF',
+            'assumptions': {
+                'growth_rate': growth_rate,
+                'terminal_growth': terminal_growth,
+                'discount_rate': discount_rate,
+                'forecast_years': years
+            }
+        }
+        
+        try:
+            # Get current FCF
+            current_fcf = self.metrics.get('free_cash_flow', 0)
+            
+            if current_fcf <= 0:
+                results['error'] = 'Negative or zero FCF - DCF not applicable'
+                return results
+            
+            # Project FCF
+            projected_fcf = []
+            pv_fcf = []
+            
+            for year in range(1, years + 1):
+                fcf = current_fcf * ((1 + growth_rate) ** year)
+                pv = fcf / ((1 + discount_rate) ** year)
+                projected_fcf.append(fcf)
+                pv_fcf.append(pv)
+            
+            # Terminal value
+            terminal_fcf = projected_fcf[-1] * (1 + terminal_growth)
+            terminal_value = terminal_fcf / (discount_rate - terminal_growth)
+            pv_terminal = terminal_value / ((1 + discount_rate) ** years)
+            
+            # Enterprise value
+            enterprise_value = sum(pv_fcf) + pv_terminal
+            
+            # Equity value
+            net_debt = self.metrics.get('total_debt', 0) - self.metrics.get('total_cash', 0)
+            equity_value = enterprise_value - net_debt
+            
+            # Per share value
+            shares_outstanding = self.metrics.get('shares_outstanding', 1)
+            fair_value_per_share = equity_value / shares_outstanding if shares_outstanding > 0 else 0
+            
+            current_price = self.metrics.get('current_price', 0)
+            upside = ((fair_value_per_share - current_price) / current_price) * 100 if current_price > 0 else 0
+            
+            results.update({
+                'current_fcf': current_fcf,
+                'pv_cash_flows': sum(pv_fcf),
+                'pv_terminal_value': pv_terminal,
+                'enterprise_value': enterprise_value,
+                'equity_value': equity_value,
+                'fair_value_per_share': fair_value_per_share,
+                'current_price': current_price,
+                'upside_percent': upside,
+                'recommendation': 'BUY' if upside > 15 else 'HOLD' if upside > -10 else 'SELL'
+            })
+            
+        except Exception as e:
+            results['error'] = f'DCF calculation error: {str(e)}'
+        
+        return results
+    
+    def calculate_relative_valuation(self) -> Dict:
+        """
+        Calculate valuation using comparable multiples
+        
+        Returns:
+            Relative valuation results
+        """
+        results = {
+            'method': 'Comparable Multiples'
+        }
+        
+        current_price = self.metrics.get('current_price', 0)
+        
+        # P/E based valuation
+        if self.metrics.get('trailing_pe') and self.metrics.get('eps_trailing'):
+            sector_pe = self.sector_metrics.get('trailing_pe_median')
+            
+            if sector_pe:
+                eps = self.metrics.get('eps_trailing')
+                fair_value_pe = eps * sector_pe
+                pe_upside = ((fair_value_pe - current_price) / current_price) * 100 if current_price > 0 else 0
+                
+                results['pe_valuation'] = {
+                    'company_pe': self.metrics.get('trailing_pe'),
+                    'sector_pe_median': sector_pe,
+                    'eps': eps,
+                    'fair_value': fair_value_pe,
+                    'current_price': current_price,
+                    'upside_percent': pe_upside
+                }
+        
+        # PEG based valuation
+        if self.metrics.get('peg_ratio') and self.metrics.get('eps_forward'):
+            sector_peg = self.sector_metrics.get('peg_ratio_median')
+            earnings_growth = self.analysis.get('growth_analysis', {}).get('earnings_growth_ttm', 0)
+            
+            if sector_peg and earnings_growth:
+                eps_forward = self.metrics.get('eps_forward')
+                fair_pe = sector_peg * (earnings_growth * 100)
+                fair_value_peg = eps_forward * fair_pe
+                peg_upside = ((fair_value_peg - current_price) / current_price) * 100 if current_price > 0 else 0
+                
+                results['peg_valuation'] = {
+                    'company_peg': self.metrics.get('peg_ratio'),
+                    'sector_peg_median': sector_peg,
+                    'earnings_growth': earnings_growth,
+                    'fair_pe': fair_pe,
+                    'fair_value': fair_value_peg,
+                    'current_price': current_price,
+                    'upside_percent': peg_upside
+                }
+        
+        # P/B based valuation
+        if self.metrics.get('price_to_book') and self.metrics.get('book_value_per_share'):
+            sector_pb = self.sector_metrics.get('price_to_book_median')
+            
+            if sector_pb:
+                book_value = self.metrics.get('book_value_per_share')
+                fair_value_pb = book_value * sector_pb
+                pb_upside = ((fair_value_pb - current_price) / current_price) * 100 if current_price > 0 else 0
+                
+                results['pb_valuation'] = {
+                    'company_pb': self.metrics.get('price_to_book'),
+                    'sector_pb_median': sector_pb,
+                    'book_value_per_share': book_value,
+                    'fair_value': fair_value_pb,
+                    'current_price': current_price,
+                    'upside_percent': pb_upside
+                }
+        
+        # Calculate average upside from available methods
+        upsides = []
+        if 'pe_valuation' in results:
+            upsides.append(results['pe_valuation']['upside_percent'])
+        if 'peg_valuation' in results:
+            upsides.append(results['peg_valuation']['upside_percent'])
+        if 'pb_valuation' in results:
+            upsides.append(results['pb_valuation']['upside_percent'])
+        
+        if upsides:
+            avg_upside = sum(upsides) / len(upsides)
+            results['average_upside'] = avg_upside
+            results['recommendation'] = 'BUY' if avg_upside > 15 else 'HOLD' if avg_upside > -10 else 'SELL'
+        
+        return results
+    
+    def scenario_analysis(self) -> Dict:
+        """
+        Perform bull/base/bear scenario valuation
+        
+        Returns:
+            Scenario analysis results
+        """
+        # Base case: use historical/current growth rates
+        base_growth = self.analysis.get('growth_analysis', {}).get('revenue_growth_ttm', 0.08)
+        base_growth = max(0.05, min(base_growth, 0.20))  # Cap between 5% and 20%
+        
+        scenarios = {}
+        
+        # Bear case: 20% lower growth, higher risk (lower valuation)
+        bear_growth = base_growth * 0.8
+        scenarios['bear'] = self.calculate_intrinsic_value_dcf(
+            growth_rate=bear_growth,
+            discount_rate=0.12  # Higher discount rate = higher risk = lower valuation
+        )
+        
+        # Base case
+        scenarios['base'] = self.calculate_intrinsic_value_dcf(
+            growth_rate=base_growth,
+            discount_rate=0.10
+        )
+        
+        # Bull case: 20% higher growth, lower risk (higher valuation)
+        bull_growth = base_growth * 1.2
+        scenarios['bull'] = self.calculate_intrinsic_value_dcf(
+            growth_rate=bull_growth,
+            discount_rate=0.08  # Lower discount rate = lower risk = higher valuation
+        )
+        
+        # Summary
+        results = {
+            'scenarios': scenarios,
+            'current_price': self.metrics.get('current_price', 0)
+        }
+        
+        # Calculate price ranges
+        bear_price = scenarios['bear'].get('fair_value_per_share', 0)
+        base_price = scenarios['base'].get('fair_value_per_share', 0)
+        bull_price = scenarios['bull'].get('fair_value_per_share', 0)
+        
+        results['price_range'] = {
+            'bear': bear_price,
+            'base': base_price,
+            'bull': bull_price,
+            'range': bull_price - bear_price
+        }
+        
+        # Risk/reward assessment
+        current_price = results['current_price']
+        if current_price > 0:
+            downside = ((bear_price - current_price) / current_price) * 100
+            upside = ((bull_price - current_price) / current_price) * 100
+            
+            results['risk_reward'] = {
+                'downside_percent': downside,
+                'upside_percent': upside,
+                'risk_reward_ratio': abs(upside / downside) if downside != 0 else 0,
+                'assessment': 'Favorable' if upside > abs(downside) else 'Unfavorable'
+            }
+        
+        return results
+    
+    def calculate_margin_of_safety(self) -> Dict:
+        """
+        Calculate margin of safety
+        
+        Returns:
+            Margin of safety metrics
+        """
+        results = {}
+        
+        current_price = self.metrics.get('current_price', 0)
+        if current_price <= 0:
+            return {'error': 'Invalid current price'}
+        
+        # Based on DCF
+        dcf_result = self.calculate_intrinsic_value_dcf()
+        if 'fair_value_per_share' in dcf_result:
+            intrinsic_value = dcf_result['fair_value_per_share']
+            margin = ((intrinsic_value - current_price) / intrinsic_value) * 100 if intrinsic_value > 0 else 0
+            
+            results['dcf_margin_of_safety'] = {
+                'intrinsic_value': intrinsic_value,
+                'current_price': current_price,
+                'margin_percent': margin,
+                'assessment': self._assess_margin_of_safety(margin)
+            }
+        
+        # Based on book value
+        book_value = self.metrics.get('book_value_per_share', 0)
+        if book_value > 0:
+            margin = ((book_value - current_price) / book_value) * 100
+            results['book_value_margin'] = {
+                'book_value': book_value,
+                'current_price': current_price,
+                'margin_percent': margin
+            }
+        
+        return results
+    
+    def _assess_margin_of_safety(self, margin: float) -> str:
+        """Assess margin of safety"""
+        if margin >= 30:
+            return "Excellent - Strong margin of safety"
+        elif margin >= 20:
+            return "Good - Adequate margin of safety"
+        elif margin >= 10:
+            return "Fair - Minimal margin of safety"
+        elif margin >= 0:
+            return "Weak - Little to no margin of safety"
+        else:
+            return "Overvalued - Negative margin of safety"
+    
+    def generate_valuation_report(self) -> Dict:
+        """
+        Generate comprehensive valuation report
+        
+        Returns:
+            Complete valuation analysis
+        """
+        return {
+            'ticker': self.ticker,
+            'current_price': self.metrics.get('current_price', 0),
+            'dcf_valuation': self.calculate_intrinsic_value_dcf(),
+            'relative_valuation': self.calculate_relative_valuation(),
+            'scenario_analysis': self.scenario_analysis(),
+            'margin_of_safety': self.calculate_margin_of_safety()
+        }
+
+
+if __name__ == "__main__":
+    print("This module is meant to be imported and used with data from data_fetcher.py and financial_analyzer.py")

src/main.py

@@ -0,0 +1,205 @@
+import os
+import sys
+import threading
+import json
+import logging
+from typing import Optional, Dict, Any
+from fastapi import FastAPI, HTTPException, Header, BackgroundTasks, Depends
+from pydantic import BaseModel
+from datetime import datetime
+
+# Add src to path
+sys.path.append(os.path.join(os.path.dirname(__file__), ".."))
+
+from src.db.local_database import LocalDatabase, DatabaseEntry, DataType
+from run_saturday_analysis import run_saturday_analysis
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="Stock Alchemist Signal Generator")
+
+# --- Models ---
+class SignalRequest(BaseModel):
+    ticker: Optional[str] = None
+    prompt_override: Optional[str] = None
+
+class SignalResponse(BaseModel):
+    status: str
+    message: str
+    signal_id: Optional[str] = None
+
+# --- Dependencies ---
+def verify_api_secret(x_api_secret: str = Header(...)):
+    """Verify the API secret header"""
+    expected_secret = os.getenv("API_SECRET")
+    if not expected_secret:
+        # If no secret is set in env, we might want to fail safe or allow default for dev
+        # For production security, better to fail if not configured.
+        logger.warning("API_SECRET environment variable not set! Security disabled.")
+        return # Allow if env var missing (or raise error based on preference)
+        # raise HTTPException(status_code=500, detail="Server misconfiguration: API_SECRET not set")
+    
+    if x_api_secret != expected_secret:
+        raise HTTPException(status_code=403, detail="Invalid API Secret")
+
+# --- Services ---
+
+def generate_signal_logic(ticker: str, prompt_override: Optional[str] = None):
+    """
+    Core logic to generate a signal using Ollama and save to DB.
+    """
+    import requests
+    
+    logger.info(f"Generating signal for {ticker}...")
+    
+    # 1. Construct Prompt
+    # Need to get some data about the ticker to give to the LLM? 
+    # For now, we'll assume the prompt asks the LLM to use its internal knowledge or just generate a generic signal based on the ticker name.
+    # In a real scenario, we'd fetch news/price data here and feed it.
+    
+    # Let's try to fetch some basic info from DB if available?
+    db = LocalDatabase()
+    
+    # Construct prompt
+    prompt = prompt_override or f"Analyze the stock {ticker} and provide a trading signal (BUY/SELL/HOLD) with confidence score and reasoning. Format response as JSON."
+    
+    try:
+        # 2. Call Ollama
+        # Using the local Ollama instance
+        ollama_url = "http://localhost:11434/api/generate"
+        payload = {
+            "model": "llama3.1",
+            "prompt": prompt,
+            "stream": False,
+            "format": "json" # Llama 3 supports json mode often
+        }
+        
+        response = requests.post(ollama_url, json=payload, timeout=120)
+        response.raise_for_status()
+        result = response.json()
+        llm_output = result.get('response', '')
+        
+        logger.info(f"Ollama response for {ticker}: {llm_output[:100]}...")
+        
+        # 3. Parse and Save to DB
+        # We'll save the raw LLM output as a signal entry
+        
+        # Try to parse JSON from LLM if possible, otherwise wrap it
+        try:
+            signal_data = json.loads(llm_output)
+        except json.JSONDecodeError:
+            signal_data = {"raw_output": llm_output}
+            
+        # Extract signal position if possible
+        position = signal_data.get('signal', signal_data.get('recommendation', 'HOLD')).upper()
+        if position not in ['BUY', 'SELL', 'HOLD']:
+            position = 'HOLD' # Default
+            
+        # Save using LocalDatabase
+        # We need to use save_signal or save generic entry?
+        # save_signal requires specific keys. Let's use save generic entry or try save_signal if we have the keys.
+        # simpler to just update the 'signals' table logic in LocalDatabase or use db.save() with DataType.CUSTOM?
+        # The user's signals table has specific columns. 
+        # local_database.py -> save_signal(self, ticker, calendar_event_keys, news_keys, fundamental_key, signal_position, sentiment)
+        
+        # We'll provide empty lists for keys for now as we didn't link specific events
+        is_saved = db.save_signal(
+            ticker=ticker,
+            calendar_event_keys=[],
+            news_keys=[],
+            fundamental_key="generated_by_ollama",
+            signal_position=position,
+            sentiment=signal_data
+        )
+        
+        if is_saved:
+            logger.info(f"Signal saved for {ticker}")
+        else:
+            logger.error(f"Failed to save signal for {ticker}")
+            
+    except Exception as e:
+        logger.error(f"Error generating signal for {ticker}: {e}")
+
+# --- Endpoints ---
+
+@app.post("/generate-signal", response_model=SignalResponse, dependencies=[Depends(verify_api_secret)])
+async def generate_signal(request: SignalRequest, background_tasks: BackgroundTasks):
+    """
+    Trigger signal generation. 
+    If ticker is provided, generates for that ticker.
+    If not, could pick a random one or all? Let's require ticker for now or pick first available.
+    """
+    target_ticker = request.ticker
+    
+    if not target_ticker:
+        # Pick a ticker from DB?
+        try:
+            db = LocalDatabase()
+            tickers = db.get_all_available_tickers()
+            if tickers:
+                target_ticker = tickers[0] # Just pick the first one for the demo/daily run
+            else:
+                raise HTTPException(status_code=404, detail="No tickers available in database")
+        except Exception as e:
+             raise HTTPException(status_code=500, detail=f"Database error: {e}")
+    
+    # Run in background to avoid timeout
+    background_tasks.add_task(generate_signal_logic, target_ticker, request.prompt_override)
+    
+    return SignalResponse(
+        status="accepted", 
+        message=f"Signal generation started for {target_ticker}"
+    )
+
+@app.post("/saturday-analysis", dependencies=[Depends(verify_api_secret)])
+async def trigger_saturday_analysis(background_tasks: BackgroundTasks):
+    """
+    Trigger the saturday analysis script.
+    """
+    background_tasks.add_task(run_saturday_analysis)
+    return {"status": "accepted", "message": "Saturday analysis started"}
+
+@app.get("/health")
+async def health_check():
+    """
+    Simple health check.
+    Also logs vitals as requested.
+    """
+    # Verify DB connection
+    db_status = "unknown"
+    try:
+        db = LocalDatabase()
+        if db._create_connection():
+            db_status = "connected"
+        else:
+            db_status = "disconnected"
+    except Exception as e:
+        db_status = f"error: {e}"
+    
+    # Check Ollama
+    ollama_status = "unknown"
+    try:
+        import requests
+        resp = requests.get("http://localhost:11434/api/tags", timeout=5)
+        if resp.status_code == 200:
+            ollama_status = "running"
+        else:
+            ollama_status = f"error: {resp.status_code}"
+    except Exception:
+        ollama_status = "down"
+
+    vitals = {
+        "status": "ok", 
+        "time": datetime.now().isoformat(),
+        "database": db_status,
+        "ollama": ollama_status
+    }
+    
+    logger.info(f"Health Check: {vitals}")
+    return vitals
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

src/news_processing_performance.csv

@@ -0,0 +1,37 @@
+timestamp,ticker,headline,handler1_duration_sec,handler2_duration_sec,handler3_duration_sec,handler4_duration_sec,handler5_duration_sec,marketaux_processing_times_sec
+2025-12-02 15:22:14,XYZ,"Block Processed 124M Transactions Over Black Friday-Cyber Monday Period, 49.8M Unique Consumers Engaged With Square, Afterpay And Cash App Card",0.0671,0.6457,34.8712,1.2196,0.1178,[]
+2025-12-02 15:23:27,MDB,"Scotiabank Maintains Sector Perform on MongoDB, Raises Price Target to $415",0.3386,0.7927,18.3751,30.3256,0.0818,"['29.8627', '20.6539', '25.1773']"
+2025-12-02 15:23:49,GENI,Genius Sports Announces Deal With FanDuel Sports Network To Launch Intelligent Content Platform Across NBA And WNBA,0.0910,0.6553,19.7569,0.3972,0.0897,[]
+2025-12-02 15:26:40,MSFT,Why Satya Nadella Spends Weekends Studying Startups— And What It Reveals About Microsoft's AI Fears,0.0723,1.1099,17.3942,28.3587,0.1097,"['22.4378', '27.8175', '17.4317']"
+2025-12-02 15:27:03,CRDO,"Barclays Maintains Overweight on Credo Technology Group, Raises Price Target to $220",0.0537,0.6266,17.4651,0.5390,0.0806,[]
+2025-12-02 15:27:48,BA,"Boeing Shares Higher Amid Presentation At UBS Global Industrials and Transportation
+Conference",0.0705,0.6446,17.0340,18.8040,0.1045,['18.3200']
+2025-12-02 15:29:12,BA,"Boeing CFO Says Boeing Sees 2026 Deliveries Up For 737, 787 Vs 2025; 737 Max 10 Seen Certified In Late 2026; Boeing Sees $2B Free Cash Outflow For 2025, Sees DoJ Penalty To Flip Into 2026",0.0979,0.6760,22.3228,17.7965,0.0923,['17.2851']
+2025-12-02 15:29:33,LI,"Barclays Maintains Equal-Weight on Li Auto, Lowers Price Target to $18",0.0506,0.8701,17.2470,0.4168,0.0962,[]
+2025-12-02 15:59:17,FIVE,"Guggenheim Maintains Buy on Five Below, Raises Price Target to $185",0.0560,1.2611,38.0789,1.0606,0.2354,[]
+2025-12-02 16:03:34,ABT,Top 2 Health Care Stocks You May Want To Dump This Month,0.0619,2.3249,17.1654,18.4556,0.3189,['18.0078']
+2025-12-02 16:05:20,EXPI,"eXp World's eXp Realty Unit Expands Operations In Romania, Netherlands",0.0838,0.6778,22.5123,0.5070,0.0741,[]
+2025-12-02 16:05:46,AMD,"HPE Announces AMD Helios AI Rack Scale Solution, With Scale-Up Networking Built With Broadcom",0.0647,1.8995,21.8066,0.4986,0.3523,[]
+2025-12-02 16:06:36,EXFY,Expensify Announces Improved Expense Integration With Uber For Business,0.0696,1.5454,24.0861,0.4225,0.1837,[]
+2025-12-02 16:07:23,AMTM,"Cantor Fitzgerald Maintains Overweight on Amentum Holdings, Raises Price Target to $40",0.0703,0.6492,20.7363,0.4494,0.0900,[]
+2025-12-02 16:07:46,ANNX,"Clear Street Initiates Coverage On Annexon with Buy Rating, Announces Price Target of $17",0.0608,0.6555,19.4098,0.4228,0.0930,[]
+2025-12-02 16:08:35,WMT,"Walmart Highlights Opening Of 2nd Owned, Operated Milk Processing Facility In Georgia",0.0728,0.9513,22.1578,24.2291,0.0815,"['23.7437', '18.1360']"
+2025-12-02 16:08:59,GEHC,GE HealthCare Unveils Advanced Image Technologies In Partnership With Nvidia,0.0691,1.4951,19.3745,0.4110,0.2545,[]
+2025-12-02 16:09:53,AMZN,"Atlassian Announces Public Listing Of Jira, Confluence, Jira Service Management On Amazon Web Services Marketplace",0.0593,1.0465,18.7451,30.7071,0.1686,"['25.3135', '30.2298', '20.0358']"
+2025-12-02 16:10:16,CART,Instacart And The Home Depot Canada Launch Nationwide Partnership To Offer Same-Day Delivery Ahead Of The Holiday Season,0.0729,1.5587,19.9771,0.4319,0.1495,[]
+2025-12-02 16:11:11,JANX,"Clear Street Maintains Buy on Janux Therapeutics, Lowers Price Target to $32",0.0754,0.7339,22.9644,30.7776,0.1054,['30.2398']
+2025-12-02 16:12:40,BA,"Boeing shares are trading higher after the company reportedly said that it expects a year-over-year increase in its FY26 deliveries of its 737, 787 models and that the DoJ penalty will flip into 2026. The company will complete its Spirit acquisition this year.",0.1395,0.9766,63.2482,20.9684,0.0784,['20.4570']
+2025-12-02 16:13:22,SHOP,Shopify shares are trading higher after the company announced its merchants achieved $14.6 billion in sales over the Black Friday-Cyber Monday weekend. This represented a 27% year-over-year increase.,0.1278,0.7203,19.9788,0.4339,0.0795,[]
+2025-12-02 16:13:43,VOO,Americans Feel Bleak Despite Strong Economy — Here's Why,0.0610,0.6459,18.8759,0.4239,0.0866,[]
+2025-12-02 16:18:39,MDB,"Wells Fargo Maintains Overweight on MongoDB, Raises Price Target to $450",0.1581,1.5171,17.3543,16.9989,0.0814,['0.0']
+2025-12-02 16:18:59,DRVN,FEP To Acquire IMO Cars Wash From Driven Brands; Terms Not Disclosed,0.0471,0.6079,16.6443,0.7564,0.0646,[]
+2025-12-02 16:20:28,ASPI,"ASP Isotopes Founder Paul Mann To Return As CEO On January 19, 2026, After Health-Related Leave; Interim CEO Robert Ainscow To Resume COO-Only Role",0.0739,0.6738,19.5016,64.9769,0.0901,['0.0']
+2025-12-02 16:22:48,EIX,"UBS Maintains Buy on Edison Intl, Raises Price Target to $70",0.0610,1.1330,21.5212,22.7984,0.1066,['0.0']
+2025-12-02 16:24:43,JAMF,Jamf Partners With UberEther To Pursue FedRAMP High And DoD IL5 Authorization,0.1184,0.6767,28.2747,84.8554,0.1146,['0.0']
+2025-12-02 16:25:41,TXG,"Morgan Stanley Downgrades 10x Genomics to Equal-Weight, Raises Price Target to $20",0.0753,1.1334,23.7296,29.5197,0.0881,['0.0']
+2025-12-02 16:26:40,MDB,"UBS Maintains Neutral on MongoDB, Raises Price Target to $440",0.0642,0.6210,19.2360,28.2389,0.1334,['0.0']
+2025-12-02 16:38:19,MDB,"Canaccord Genuity Maintains Buy on MongoDB, Raises Price Target to $455",0.0653,1.3490,41.2146,19.6604,0.1831,['0.0']
+2025-12-02 16:40:40,ALB,Applied Materials To Rally Around 12%? Here Are 10 Top Analyst Forecasts For Tuesday,0.3986,6.8471,17.3188,115.0094,1.0037,['0.0']
+2025-12-02 16:51:44,AAPL,"Loop Capital Maintains Buy on Apple, Raises Price Target to $325",0.0763,1.4723,39.4810,20.8113,0.3246,['0.0']
+2025-12-02 16:54:34,ABTC,Nasdaq Surges 200 Points; United Natural Foods Posts Upbeat Earnings,0.0543,2.5619,19.3508,120.4805,0.8688,['0.0']
+2025-12-02 16:57:45,MSFT,"Speaking At UBS Global Technology And AI Conference, Nvidia CFO Says "Still Haven't Completed A Definitive Agreement" With OpenAI; Says $500B In Bookings For Blackwell And Rubin AI Chips Through 2026 Does Not Include "Any Of The Work That We're Doing Right Now, On The Next Part Of The Agreement With OpenAI"",0.1744,1.6818,57.4261,19.6906,0.3012,['0.0']

src/news_scraper/adapters/__init__.py

@@ -0,0 +1,2 @@
+# FILE: /stock-news-scraper/stock-news-scraper/src/adapters/__init__.py
+# This file is intentionally left blank.

src/news_scraper/adapters/alpaca_ws.py

@@ -0,0 +1,195 @@
+import os
+import threading
+import websocket
+import json
+import time
+import logging
+from news_scraper.models.news import News
+from news_scraper.helpers.news_db_logger import NewsDBLogger
+
+logger = logging.getLogger(__name__)
+
+class AlpacaNewsFeedAdapter:
+    """
+    Singleton class for Alpaca WebSocket API adapter.
+    This class connects to the Alpaca WebSocket API to receive real-time news updates.
+    """
+    _instance = None
+    _lock = threading.Lock()
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super(AlpacaNewsFeedAdapter, cls).__new__(cls)
+                    cls._instance.__initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        if self.__initialized:
+            return
+        self.__initialized = True
+        # Initialize the Alpaca WebSocket API connection
+        apca_key = "PKFF63XPNPCWWZXYXRK223NE2P"
+        apca_secret = "HqJE1b2jHuTvZzGGHW2jRHBajcmBw18PNJzUcNXLhfZ5"
+        self.websocket_url = "wss://stream.data.alpaca.markets/v1beta1/news"
+        self.headers = {
+            "APCA-API-KEY-ID": apca_key,
+            "APCA-API-SECRET-KEY": apca_secret,
+        }
+        self.ws = None
+        self.ws_thread = None
+        self.authenticated = False
+        self.connected = False
+        self.callbacks = []
+        self.db_logger = NewsDBLogger()
+        self.connect()
+
+    def connect(self):
+        """
+        Connect to the Alpaca WebSocket API.
+        """
+        self.ws = websocket.WebSocketApp(
+            self.websocket_url,
+            on_open=self.on_open,
+            on_message=self.on_message,
+            on_error=self.on_error,
+            on_close=self.on_close,
+            header=self.headers
+        )
+        # Run the WebSocket in a separate thread
+        self.ws_thread = threading.Thread(target=self.ws.run_forever)
+        self.ws_thread.daemon = True
+        self.ws_thread.start()
+    
+    def on_open(self, ws):
+        """
+        Handle WebSocket open event.
+        """
+        print("WebSocket connection established")
+        
+    def subscribe_to_news(self):
+        """
+        Subscribe to all news updates.
+        """
+        subscription_msg = {
+            "action": "subscribe",
+            "news": ["*"]
+        }
+        self.ws.send(json.dumps(subscription_msg))
+        #print("Sent subscription request for news")
+
+    def on_message(self, ws, message):
+        """
+        Handle incoming messages from the WebSocket.
+        """
+        print(f"[DEBUG] Raw message: {message}")
+        data = json.loads(message)
+
+        # Handle different message types
+        if isinstance(data, list) and len(data) > 0:
+            msg_type = data[0].get("T", "")
+            
+            # Handle connection success
+            if msg_type == "success" and data[0].get("msg") == "connected":
+                self.connected = True
+                #print("Successfully connected to Alpaca News WebSocket")
+                
+            # Handle authentication success
+            elif msg_type == "success" and data[0].get("msg") == "authenticated":
+                self.authenticated = True
+                #print("Successfully authenticated with Alpaca News WebSocket")
+                # Subscribe to news after authentication
+                self.subscribe_to_news()
+                
+            # Handle subscription confirmation
+            elif msg_type == "subscription":
+                print("[ALPACA] Successfully subscribed to news channels:", data[0].get("news", []))
+                
+            # Handle actual news updates
+            elif data[0].get("T") == "n":
+                # Process news data using the News class
+                news_item = News(
+                    id=data[0].get("id"),
+                    headline=data[0].get("headline"),
+                    summary=data[0].get("summary"),
+                    author=data[0].get("author"),
+                    created_at=data[0].get("created_at"),
+                    updated_at=data[0].get("updated_at"),
+                    url=data[0].get("url"),
+                    content=data[0].get("content"),
+                    symbols=data[0].get("symbols", []),
+                    source=data[0].get("source")
+                )
+                symbols_str = ', '.join(news_item.symbols) if news_item.symbols else ''
+                headline_preview = news_item.headline[:50] if news_item.headline else "No headline"
+                logger.info(f"[ALPACA] Received news | '{news_item.headline}' ({symbols_str})")
+                
+                # Log to database (without sentiment for now) - REMOVED to avoid duplicate logging
+                # self.db_logger.log_news_with_sentiment(news_item)
+                # logger.info(f"[ALPACA] Logged to DB | {headline_preview}...")
+                
+                # Call registered callbacks only when we have a news item
+                for callback in self.callbacks:
+                    callback(news_item)
+
+    def on_error(self, ws, error):
+        """
+        Handle errors from the WebSocket.
+        """
+        print(f"Error: {error}")
+
+    def on_close(self, ws, close_status_code, close_msg):
+        """
+        Handle WebSocket closure.
+        """
+        print(f"WebSocket closed: {close_status_code} - {close_msg}")
+        self.connected = False
+        self.authenticated = False
+        
+        # Attempt to reconnect after a delay
+        print("Attempting to reconnect in 5 seconds...")
+        time.sleep(5)
+        self.connect()
+    
+    def register_callback(self, callback):
+        """
+        Register a callback function to be called when news is received.
+        The callback function should accept a news item dictionary as its parameter.
+        """
+        if callable(callback):
+            self.callbacks.append(callback)
+            return True
+        return False
+    
+    def close(self):
+        """
+        Close the WebSocket connection.
+        """
+        if self.ws:
+            self.ws.close()
+            self.ws = None
+
+if __name__ == "__main__":
+    # Example usage with a callback function
+    def print_news(news_item):
+        print(f"[PROCESSOR] [QUEUE] News item | {news_item.headline}")
+
+    # Create the adapter
+    alpaca_adapter = AlpacaNewsFeedAdapter()
+    alpaca_adapter.register_callback(print_news)
+    
+    # Keep the main thread alive to receive messages
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("Exiting...")
+        alpaca_adapter.close()
+
+
+
+
+
+
+

src/news_scraper/adapters/base_adapter.py

@@ -0,0 +1,10 @@
+class BaseAdapter:
+
+    def fetch_articles(self):
+        raise NotImplementedError("Subclasses must implement this method.")
+
+    def parse_article(self, raw_data):
+        raise NotImplementedError("Subclasses must implement this method.")
+    
+    def analyze_article(self, article):
+        raise NotImplementedError("Subclasses must implement this method.")

src/news_scraper/adapters/bloomberg_adapter.py

@@ -0,0 +1,19 @@
+from news_scraper.adapters.base_adapter import BaseAdapter
+from news_scraper.models.article import Article
+
+class BloombergAdapter(BaseAdapter):
+    
+    def __init__(self):
+        super().__init__()
+
+    def fetch_articles(self):
+        # Implementation for fetching articles from Bloomberg
+        pass
+
+    def parse_article(self, raw_article):
+        # Implementation for parsing a raw article from Bloomberg
+        pass
+
+    def save_to_database(self, article: Article):
+        # Implementation for saving the article to the database
+        pass

src/news_scraper/adapters/motley_fool_adapter.py

@@ -0,0 +1,19 @@
+from .base_adapter import BaseAdapter
+from news_scraper.models.article import Article
+
+class MotleyFoolAdapter(BaseAdapter):
+    
+    def __init__(self):
+        super().__init__()
+
+    def fetch_articles(self):
+        # Implementation for fetching articles from Bloomberg
+        pass
+
+    def parse_article(self, raw_article):
+        # Implementation for parsing a raw article from Bloomberg
+        pass
+
+    def save_to_database(self, article: Article):
+        # Implementation for saving the article to the database
+        pass

src/news_scraper/adapters/yahoo_finance_adapter.py

@@ -0,0 +1,44 @@
+from datetime import datetime
+from .base_adapter import BaseAdapter
+from news_scraper.models.article import Article
+import yfinance as yf 
+from news_scraper.services.sentiment_analysis_gemini import analyze_sentiment
+from news_scraper.helpers.news_db_logger import NewsDBLogger
+
+class YahooFinanceAdapter(BaseAdapter):
+    def __init__(self):
+        super().__init__()
+        self.db_logger = NewsDBLogger()
+
+    def fetch_articles(self):
+        # Logic to scrape articles from Yahoo Finance
+        return(yf.Search('AAPL',news_count=1).news)
+    
+    def parse_article(self, raw_article):
+        # Logic to parse a raw article into an Article object
+        publish_time = datetime.fromtimestamp(raw_article['providerPublishTime'])
+        article= Article(url=raw_article['link'], title=raw_article['title'],description=None, score=None, ticker=raw_article['relatedTickers'],time=publish_time)
+        print(article.__repr__())
+        return article
+
+    def analyze_article(self, article):
+        # Use Gemini sentiment analysis on the article
+        sentiment_result = analyze_sentiment(url=article.url)
+        
+        # Log the article and its sentiment to database
+        self.db_logger.log_news_with_sentiment(article, sentiment_result)
+        
+        # Continue with the original analysis
+        return super().analyze_article(article)
+
+"""
+Format of the raw article object returned by Yahoo Finance API:
+[{'uuid': '637daa50-f230-3ddd-a251-1b9840c38c10',
+'title': 'Apple Inc. (AAPL): Alibaba Partnership to Bring AI to iPhones in China',
+'publisher': 'Insider Monkey',
+'link': 'https://finance.yahoo.com/news/apple-inc-aapl-alibaba-partnership-044613466.html',
+'providerPublishTime': 1739421973,
+'type': 'STORY',
+'thumbnail': {'resolutions': [{'url': 'https://s.yimg.com/uu/api/res/1.2/fTPNobtT0bdcSxj2xXAamw--~B/aD04MTY7dz0xNDU2O2FwcGlkPXl0YWNoeW9u/https://media.zenfs.com/en/insidermonkey.com/bd47dc2e86b4a3086f845d200d9daf1f', 'width': 1456, 'height': 816, 'tag': 'original'}, {'url': 'https://s.yimg.com/uu/api/res/1.2/nIyTyNRglKMNfFFMGli.7A--~B/Zmk9ZmlsbDtoPTE0MDtweW9mZj0wO3c9MTQwO2FwcGlkPXl0YWNoeW9u/https://media.zenfs.com/en/insidermonkey.com/bd47dc2e86b4a3086f845d200d9daf1f', 'width': 140, 'height': 140, 'tag': '140x140'}]},
+'relatedTickers': ['AAPL']}]
+"""

src/news_scraper/helpers/news_db_logger.py

@@ -0,0 +1,248 @@
+"""
+Database Logger for News Items
+Replaces ExcelLogger - logs news with sentiment directly to MySQL news table
+"""
+
+import sys
+import logging
+import threading
+from pathlib import Path
+from datetime import datetime
+from typing import Optional, List, Tuple
+
+# Add src to path for imports
+sys.path.append(str(Path(__file__).parent.parent.parent))
+
+from db.local_database import LocalDatabase, DatabaseEntry, DataType
+
+logger = logging.getLogger(__name__)
+
+
+class NewsDBLogger:
+    """
+    Logs news items with sentiment analysis directly to the MySQL news table.
+    Replaces the old ExcelLogger functionality.
+    """
+    _instance = None
+    _lock = threading.Lock()
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super(NewsDBLogger, cls).__new__(cls)
+                    cls._instance.initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        """Initialize the database logger."""
+        if self.initialized:
+            return
+        self.initialized = True
+        self.db = LocalDatabase()
+        logger.info("✅ NewsDBLogger initialized with MySQL backend")
+    
+    def log_news_with_sentiment(self, news_item, pre_sentiment=None, sentiment=None, rating=None, processing_time=None):
+        """
+        Log a news item and its sentiment analysis to the database.
+        
+        Args:
+            news_item: The news item object containing news details
+            pre_sentiment (str, optional): Pre-processed sentiment analysis text
+            sentiment (str, optional): Processed sentiment analysis text
+            rating (str or float, optional): Sentiment score/rating
+            processing_time (float, optional): Time taken to process this news item in seconds
+        """
+        try:
+            # Extract symbols/ticker
+            ticker = "GENERAL"  # Default ticker
+            symbols_str = ""
+            
+            if hasattr(news_item, 'symbols') and news_item.symbols:
+                symbols_list = news_item.symbols if isinstance(news_item.symbols, list) else [news_item.symbols]
+                symbols_str = ', '.join(symbols_list)
+                ticker = symbols_list[0] if symbols_list else "GENERAL"
+            elif isinstance(news_item, dict) and 'symbols' in news_item:
+                symbols_list = news_item['symbols'] if isinstance(news_item['symbols'], list) else [news_item['symbols']]
+                symbols_str = ', '.join(symbols_list)
+                ticker = symbols_list[0] if symbols_list else "GENERAL"
+            
+            # Get date
+            news_date = datetime.now().strftime("%Y-%m-%d")
+            if hasattr(news_item, 'created_at'):
+                try:
+                    news_date = str(news_item.created_at).split('T')[0]
+                except:
+                    pass
+            elif isinstance(news_item, dict) and 'created_at' in news_item:
+                try:
+                    news_date = str(news_item['created_at']).split('T')[0]
+                except:
+                    pass
+            
+            # Build the data payload matching Excel format
+            data = {
+                'Timestamp': datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                'NewsID': getattr(news_item, 'id', None) if hasattr(news_item, 'id') else (news_item.get('id') if isinstance(news_item, dict) else None),
+                'Headline': getattr(news_item, 'headline', None) if hasattr(news_item, 'headline') else (news_item.get('headline') if isinstance(news_item, dict) else None),
+                'URL': getattr(news_item, 'url', None) if hasattr(news_item, 'url') else (news_item.get('url') if isinstance(news_item, dict) else None),
+                'Source': getattr(news_item, 'source', None) if hasattr(news_item, 'source') else (news_item.get('source') if isinstance(news_item, dict) else None),
+                'Symbols': symbols_str,
+                'PreSentimentScore': pre_sentiment,
+                'SentimentScore': rating,
+                'SentimentAnalysis': sentiment,
+                'TimeToProcess': processing_time
+            }
+            
+            # Create database entry
+            entry = DatabaseEntry(
+                date=news_date,
+                data_type=DataType.NEWS.value,  # "news"
+                ticker=ticker,
+                data=data,
+                metadata={
+                    'logged_at': datetime.now().isoformat(),
+                    'has_sentiment': sentiment is not None,
+                    'processing_time': processing_time
+                }
+            )
+            
+            # Save to database
+            success = self.db.save(entry, expiry_days=90)  # Keep news for 90 days
+            
+            if success:
+                headline = data.get('Headline', 'Unknown headline')
+                logger.info(f"✅ Logged to DB | {headline[:60]}...")
+            else:
+                logger.error(f"❌ Failed to log news to database")
+                
+            return success
+            
+        except Exception as e:
+            logger.error(f"❌ Error logging news: {str(e)}")
+            import traceback
+            traceback.print_exc()
+            return False
+    
+    def log_batch(self, news_items_with_sentiment_and_times: List[Tuple]):
+        """
+        Log multiple news items with sentiment in batch.
+        
+        Args:
+            news_items_with_sentiment_and_times: List of tuples (news_item, sentiment_data, processing_time)
+                                               processing_time can be None if unavailable
+        """
+        try:
+            entries = []
+            
+            for item_data in news_items_with_sentiment_and_times:
+                # Unpack the tuple - handle both 2-element and 3-element tuples
+                if len(item_data) == 2:
+                    news_item, sentiment_data = item_data
+                    processing_time = None
+                elif len(item_data) == 3:
+                    news_item, sentiment_data, processing_time = item_data
+                else:
+                    print(f"⚠️  Invalid item data format: {item_data}")
+                    continue
+                
+                # Extract sentiment details
+                pre_sentiment = sentiment_data.get('pre_sentiment') if isinstance(sentiment_data, dict) else None
+                sentiment = sentiment_data.get('sentiment') if isinstance(sentiment_data, dict) else None
+                rating = sentiment_data.get('rating') if isinstance(sentiment_data, dict) else None
+                
+                # Extract symbols/ticker
+                ticker = "GENERAL"
+                symbols_str = ""
+                
+                if hasattr(news_item, 'symbols') and news_item.symbols:
+                    symbols_list = news_item.symbols if isinstance(news_item.symbols, list) else [news_item.symbols]
+                    symbols_str = ', '.join(symbols_list)
+                    ticker = symbols_list[0] if symbols_list else "GENERAL"
+                elif isinstance(news_item, dict) and 'symbols' in news_item:
+                    symbols_list = news_item['symbols'] if isinstance(news_item['symbols'], list) else [news_item['symbols']]
+                    symbols_str = ', '.join(symbols_list)
+                    ticker = symbols_list[0] if symbols_list else "GENERAL"
+                
+                # Get date
+                news_date = datetime.now().strftime("%Y-%m-%d")
+                if hasattr(news_item, 'created_at'):
+                    try:
+                        news_date = str(news_item.created_at).split('T')[0]
+                    except:
+                        pass
+                elif isinstance(news_item, dict) and 'created_at' in news_item:
+                    try:
+                        news_date = str(news_item['created_at']).split('T')[0]
+                    except:
+                        pass
+                
+                # Build data payload
+                data = {
+                    'Timestamp': datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                    'NewsID': getattr(news_item, 'id', None) if hasattr(news_item, 'id') else (news_item.get('id') if isinstance(news_item, dict) else None),
+                    'Headline': getattr(news_item, 'headline', None) if hasattr(news_item, 'headline') else (news_item.get('headline') if isinstance(news_item, dict) else None),
+                    'URL': getattr(news_item, 'url', None) if hasattr(news_item, 'url') else (news_item.get('url') if isinstance(news_item, dict) else None),
+                    'Source': getattr(news_item, 'source', None) if hasattr(news_item, 'source') else (news_item.get('source') if isinstance(news_item, dict) else None),
+                    'Symbols': symbols_str,
+                    'PreSentimentScore': pre_sentiment,
+                    'SentimentScore': rating,
+                    'SentimentAnalysis': sentiment,
+                    'TimeToProcess': processing_time
+                }
+                
+                # Create database entry
+                entry = DatabaseEntry(
+                    date=news_date,
+                    data_type=DataType.NEWS.value,
+                    ticker=ticker,
+                    data=data,
+                    metadata={
+                        'logged_at': datetime.now().isoformat(),
+                        'has_sentiment': sentiment is not None,
+                        'processing_time': processing_time
+                    }
+                )
+                
+                entries.append(entry)
+            
+            # Batch save to database
+            if entries:
+                saved_count = self.db.save_batch(entries, expiry_days=90)
+                logger.info(f"✅ Batch logged {saved_count}/{len(entries)} news items")
+                return saved_count
+            else:
+                logger.warning("⚠️  No valid entries to log")
+                return 0
+                
+        except Exception as e:
+            logger.error(f"❌ Error batch logging: {str(e)}")
+            import traceback
+            traceback.print_exc()
+            return 0
+
+
+# Example usage
+if __name__ == "__main__":
+    logger = NewsDBLogger()
+    
+    # Test with a mock news item
+    class MockNews:
+        def __init__(self):
+            self.id = "test123"
+            self.headline = "Test Headline"
+            self.url = "https://example.com"
+            self.source = "TestSource"
+            self.symbols = ["AAPL", "MSFT"]
+            self.created_at = "2025-01-15T10:30:00Z"
+    
+    mock_news = MockNews()
+    logger.log_news_with_sentiment(
+        mock_news,
+        pre_sentiment="POSITIVE",
+        sentiment="The news is very positive",
+        rating=0.85,
+        processing_time=1.5
+    )
+    
+    print("\n✅ Test completed - check database for entry")

src/news_scraper/helpers/performance_logger.py

@@ -0,0 +1,63 @@
+import csv
+import os
+import logging
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+class PerformanceLogger:
+    def __init__(self, filename="news_processing_performance.csv"):
+        self.filename = filename
+        self._initialize_csv()
+
+    def _initialize_csv(self):
+        """Initialize the CSV file with headers if it doesn't exist."""
+        if not os.path.exists(self.filename):
+            try:
+                with open(self.filename, mode='w', newline='', encoding='utf-8') as file:
+                    writer = csv.writer(file)
+                    headers = [
+                        "timestamp",
+                        "ticker",
+                        "headline",
+                        "handler1_duration_sec",
+                        "handler2_duration_sec",
+                        "handler3_duration_sec",
+                        "handler4_duration_sec",
+                        "handler5_duration_sec",
+                        "marketaux_processing_times_sec"
+                    ]
+                    writer.writerow(headers)
+                logger.info(f"[PERFORMANCE] Initialized log file: {self.filename}")
+            except Exception as e:
+                logger.error(f"[PERFORMANCE] Failed to initialize log file: {e}")
+
+    def log_metrics(self, metrics: dict):
+        """
+        Log a dictionary of metrics to the CSV file.
+        
+        Args:
+            metrics (dict): Dictionary containing metric values.
+        """
+        try:
+            with open(self.filename, mode='a', newline='', encoding='utf-8') as file:
+                writer = csv.writer(file)
+                
+                # Extract values with defaults
+                row = [
+                    datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
+                    metrics.get('ticker', 'N/A'),
+                    metrics.get('headline', 'N/A'),
+                    f"{metrics.get('handler1_duration', 0):.4f}",
+                    f"{metrics.get('handler2_duration', 0):.4f}",
+                    f"{metrics.get('handler3_duration', 0):.4f}",
+                    f"{metrics.get('handler4_duration', 0):.4f}",
+                    f"{metrics.get('handler5_duration', 0):.4f}",
+                    str(metrics.get('marketaux_processing_times', []))
+                ]
+                
+                writer.writerow(row)
+                logger.info(f"[PERFORMANCE] Logged metrics for {metrics.get('ticker', 'N/A')}")
+                
+        except Exception as e:
+            logger.error(f"[PERFORMANCE] Failed to log metrics: {e}")

src/news_scraper/helpers/timer.py

@@ -0,0 +1,138 @@
+import time
+import logging
+from datetime import datetime
+import statistics
+import os
+
+class Timer:
+    """
+    Helper class to track and log the time it takes to process news items.
+    Measures time from when an item is added to the queue until it's processed.
+    """
+    def __init__(self, log_file_path=None):
+        self.start_times = {}  # Map of news_id -> start timestamp
+        self.processing_times = []  # Store recent processing times for stats
+        self.max_history = 100  # Maximum number of processing times to store
+        self.log_file_path = log_file_path or "news_processing_times.log"
+        self.logger = self._setup_logger()
+        self.log_to_file = False  # Flag to control logging to file
+        
+    def _setup_logger(self):
+        """Set up a dedicated logger for timing statistics"""
+        logger = logging.getLogger('news_processing_timer')
+        if not logger.handlers:
+            logger.setLevel(logging.INFO)
+            
+            # Create log directory if it doesn't exist
+            log_dir = os.path.dirname(self.log_file_path)
+            if log_dir and not os.path.exists(log_dir):
+                os.makedirs(log_dir)
+            
+            # if self.log_to_file:
+            #     # Set up file handler for logging to a file
+            #     file_handler = logging.FileHandler(self.log_file_path)
+            #     file_handler.setFormatter(logging.Formatter(
+            #         '%(asctime)s - %(levelname)s - %(message)s'
+            #     ))
+            #     logger.addHandler(file_handler)
+
+            # Console handler for immediate visibility
+            console_handler = logging.StreamHandler()
+            console_handler.setFormatter(logging.Formatter(
+                '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+            ))
+            logger.addHandler(console_handler)
+        
+        return logger
+    
+    def start_timing(self, news_item):
+        """Start timing for a news item when it enters the queue"""
+        # Get a unique ID for the news item - prefer id attribute if available
+        news_id = getattr(news_item, 'id', str(id(news_item)))
+        
+        # Store the start time
+        self.start_times[news_id] = time.time()
+        
+        # Log the event at debug level
+        item_title = getattr(news_item, 'headline', 
+                   getattr(news_item, 'title', f"ID: {news_id}"))
+        self.logger.debug(f"Started timing for news item: {item_title}")
+        
+        return news_id
+    
+    def stop_timing(self, news_item):
+        """Stop timing for a news item and log the processing time"""
+        end_time = time.time()
+        
+        # Get a unique ID for the news item
+        news_id = getattr(news_item, 'id', str(id(news_item)))
+        
+        if news_id in self.start_times:
+            start_time = self.start_times[news_id]
+            process_time = end_time - start_time
+            
+            # Get title for better logging
+            item_title = getattr(news_item, 'headline', 
+                      getattr(news_item, 'title', f"ID: {news_id}"))
+            
+            # Get symbols/ticker if available
+            symbols = getattr(news_item, 'symbols', 
+                    getattr(news_item, 'ticker', ''))
+            symbols_str = ', '.join(symbols) if isinstance(symbols, list) else str(symbols)
+            
+            # Log the processing time
+            self.logger.info(f"Processing time: {process_time:.4f}s - {item_title} - Symbols: {symbols_str}")
+            
+            # Store for statistics
+            self.processing_times.append(process_time)
+            if len(self.processing_times) > self.max_history:
+                self.processing_times.pop(0)  # Remove oldest
+                
+            # Remove the entry from the start times dictionary
+            del self.start_times[news_id]
+            
+            return process_time
+        else:
+            self.logger.warning(f"No start time found for news item: {item_title}")
+            return None
+    
+    def get_queue_stats(self):
+        """Get statistics about items currently in the queue"""
+        current_time = time.time()
+        waiting_times = []
+        
+        for news_id, start_time in self.start_times.items():
+            waiting_time = current_time - start_time
+            waiting_times.append(waiting_time)
+        
+        stats = {
+            'queue_size': len(waiting_times),
+            'avg_wait_time': sum(waiting_times) / len(waiting_times) if waiting_times else 0,
+            'max_wait_time': max(waiting_times) if waiting_times else 0,
+            'min_wait_time': min(waiting_times) if waiting_times else 0
+        }
+        
+        self.logger.info(f"Queue stats: {stats['queue_size']} items, avg wait: {stats['avg_wait_time']:.2f}s, max wait: {stats['max_wait_time']:.2f}s")
+        return stats
+    
+    def get_processing_stats(self):
+        """Get statistics about recent processing times"""
+        if not self.processing_times:
+            return {
+                'count': 0,
+                'avg': 0,
+                'max': 0,
+                'min': 0,
+                'median': 0
+            }
+            
+        stats = {
+            'count': len(self.processing_times),
+            'avg': sum(self.processing_times) / len(self.processing_times),
+            'max': max(self.processing_times),
+            'min': min(self.processing_times),
+            'median': statistics.median(self.processing_times) if len(self.processing_times) > 0 else 0
+        }
+        
+        self.logger.info(f"Processing stats: {stats['count']} items, avg: {stats['avg']:.4f}s, median: {stats['median']:.4f}s, min: {stats['min']:.4f}s, max: {stats['max']:.4f}s")
+        return stats

src/news_scraper/interfaces/__init__.py

@@ -0,0 +1,2 @@
+# FILE: /stock-news-scraper/stock-news-scraper/src/interfaces/__init__.py
+# This file is intentionally left blank.

src/news_scraper/main.py

@@ -0,0 +1,69 @@
+import time
+import logging
+from news_scraper.services.news_processor import NewsProcessor
+from news_scraper.adapters.alpaca_ws import AlpacaNewsFeedAdapter
+from news_scraper.helpers.timer import Timer
+
+def main():
+    # Configure logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(levelname)s - %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    
+    # Initialize the timer
+    timer = Timer("logs/news_processing_times.log")
+    
+    # Initialize the news processor
+    news_processor = NewsProcessor()
+    
+    # Register an async callback for news processing
+    async def news_callback(news_item):
+        # Stop timing when the news item is processed
+        timer.stop_timing(news_item)
+        print(f"[PROCESSOR] [FUNC] Processing | {news_item.headline if hasattr(news_item, 'headline') else ''}")
+    
+    news_processor.register_callback(news_callback)
+    
+    # Start processing news items
+    news_processor.start_processing()
+    
+    # Initialize AlpacaNewsFeedAdapter
+    def print_news(news_item):
+        # Start timing when the news item enters the queue
+        timer.start_timing(news_item)
+        print(f"[PROCESSOR] [QUEUE] News item | {news_item.headline}")
+        news_processor.add_news(news_item)
+
+    # Create the Alpaca adapter and register callback
+    alpaca_adapter = AlpacaNewsFeedAdapter()
+    alpaca_adapter.register_callback(print_news)
+    
+    # Initialize CalendarProcessor
+    from news_scraper.services.calendar_processor import CalendarProcessor
+    calendar_processor = CalendarProcessor()
+    last_run_date = None
+    
+    # Keep the main thread alive to receive messages
+    try:
+        while True:
+            # Run Calendar Processor daily
+            from datetime import date
+            current_date = date.today()
+            if last_run_date != current_date:
+                calendar_processor.run_daily_scan()
+                last_run_date = current_date
+
+            # Periodically log queue statistics
+            if time.time() % 120 < 1:  # Roughly every two minutes
+                timer.get_queue_stats()
+                timer.get_processing_stats()
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("Exiting...")
+        alpaca_adapter.close()
+        news_processor.stop_processing()
+
+if __name__ == "__main__":
+    main()

src/news_scraper/models/__init__.py

@@ -0,0 +1,3 @@
+# FILE: /stock-news-scraper/stock-news-scraper/src/models/__init__.py
+
+# This file is intentionally left blank.

src/news_scraper/models/article.py

@@ -0,0 +1,14 @@
+class Article:
+    def __init__(self, url: str, title: str, description: str, score: float, ticker: str,time:str):
+        self.url = url
+        self.title = title
+        self.description = description
+        self.score = score
+        self.ticker = ticker
+        self.time=time
+
+    def __repr__(self):
+       return self.__print__()
+    
+    def __print__(self):    
+        return f"Article(title={self.title}, url={self.url}, score={self.score}, ticker={self.ticker}, time={self.time})"