┌─────────────────────────────────────────────────────────────────────────────┐
│                   FINANCIAL RESEARCH ASSISTANT ARCHITECTURE                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ DATA SOURCES                                                        │   │
│  │   SEC EDGAR ──► Earnings Transcripts ──► Financial News ──► Market  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                       │
│                                    ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ DOCUMENT PROCESSING                                                 │   │
│  │   Filing Parser ───────► Table Extraction ───────► Segmentation     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                       │
│                                    ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ FINANCIAL ANALYSIS                                                  │   │
│  │   Financial NER ────┬────► Metric Extraction                        │   │
│  │                     └────► Sentiment Analysis                       │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                       │
│                                    ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ AI INTELLIGENCE                                                     │   │
│  │   Embeddings ──────────► RAG Pipeline ──────────► Comparative       │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                       │
│                                    ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ RESEARCH OUTPUT                                                     │   │
│  │           ┌─────────────┬──────────────┬─────────────┐              │   │
│  │           ▼             ▼              ▼             ▼              │   │
│  │       Summary      Risk Alerts    Due Diligence   Research Q&A      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

financial-research/
├── src/
│   ├── __init__.py
│   ├── config.py                 # Configuration
│   ├── ingestion/
│   │   ├── __init__.py
│   │   ├── sec_client.py         # SEC EDGAR API
│   │   ├── filing_parser.py      # 10-K/10-Q parsing
│   │   └── earnings_parser.py    # Earnings call transcripts
│   ├── extraction/
│   │   ├── __init__.py
│   │   ├── financial_ner.py      # Financial entity recognition
│   │   ├── metrics_extractor.py  # Financial metrics
│   │   └── table_extractor.py    # Financial tables
│   ├── analysis/
│   │   ├── __init__.py
│   │   ├── sentiment.py          # Financial sentiment
│   │   ├── risk_analyzer.py      # Risk factor analysis
│   │   └── comparator.py         # Peer comparison
│   ├── retrieval/
│   │   ├── __init__.py
│   │   └── vector_store.py       # Pinecone integration
│   ├── generation/
│   │   ├── __init__.py
│   │   └── rag_pipeline.py       # RAG for Q&A
│   └── api/
│       ├── __init__.py
│       └── main.py               # FastAPI application
├── tests/
├── docker-compose.yml
└── requirements.txt

# src/config.py
from pydantic_settings import BaseSettings
from typing import List

class Settings(BaseSettings):
    # API Keys
    openai_api_key: str
    sec_user_agent: str = "CompanyName research@company.com"

    # Models
    embedding_model: str = "text-embedding-3-large"
    llm_model: str = "gpt-4o"

    # Vector Store (Pinecone)
    pinecone_api_key: str
    pinecone_environment: str = "us-west1-gcp"
    pinecone_index: str = "financial-research"

    # SEC EDGAR settings
    sec_base_url: str = "https://www.sec.gov"
    edgar_full_text_url: str = "https://efts.sec.gov/LATEST/search-index"

    # Financial analysis settings
    sentiment_threshold: float = 0.3
    risk_keywords: List[str] = [
        "material weakness", "going concern", "litigation",
        "regulatory", "investigation", "restatement"
    ]

    class Config:
        env_file = ".env"

settings = Settings()

# src/ingestion/sec_client.py
from typing import List, Dict, Any, Optional
from dataclasses import dataclass
import aiohttp
import asyncio
from datetime import datetime
import re

from ..config import settings

@dataclass
class SECFiling:
    cik: str
    company_name: str
    ticker: str
    form_type: str  # 10-K, 10-Q, 8-K, etc.
    filed_date: str
    accession_number: str
    document_url: str
    primary_document: str

class SECClient:
    """Client for SEC EDGAR API."""

    def __init__(self):
        self.headers = {
            "User-Agent": settings.sec_user_agent,
            "Accept-Encoding": "gzip, deflate"
        }

    async def search_filings(
        self,
        ticker: str = None,
        cik: str = None,
        form_types: List[str] = None,
        date_from: str = None,
        date_to: str = None,
        max_results: int = 100
    ) -> List[SECFiling]:
        """Search for SEC filings."""
        # Build query
        query_parts = []

        if ticker:
            query_parts.append(f'ticker:"{ticker}"')
        if cik:
            query_parts.append(f'cik:"{cik}"')
        if form_types:
            forms = " OR ".join([f'formType:"{ft}"' for ft in form_types])
            query_parts.append(f"({forms})")

        query = " AND ".join(query_parts) if query_parts else "*"

        params = {
            "q": query,
            "dateRange": "custom",
            "startdt": date_from or "2020-01-01",
            "enddt": date_to or datetime.now().strftime("%Y-%m-%d"),
            "forms": ",".join(form_types) if form_types else "",
            "from": 0,
            "size": max_results
        }

        async with aiohttp.ClientSession(headers=self.headers) as session:
            async with session.get(
                f"{settings.edgar_full_text_url}",
                params=params
            ) as response:
                if response.status == 200:
                    data = await response.json()
                    return self._parse_search_results(data)
                return []

    async def fetch_filing_content(self, filing: SECFiling) -> str:
        """Fetch the actual filing document content."""
        async with aiohttp.ClientSession(headers=self.headers) as session:
            async with session.get(filing.document_url) as response:
                if response.status == 200:
                    return await response.text()
                return ""

    async def get_company_filings(
        self,
        ticker: str,
        form_types: List[str] = ["10-K", "10-Q", "8-K"]
    ) -> List[SECFiling]:
        """Get all filings for a company."""
        return await self.search_filings(
            ticker=ticker,
            form_types=form_types,
            max_results=50
        )

    def _parse_search_results(self, data: Dict[str, Any]) -> List[SECFiling]:
        """Parse SEC search API results."""
        filings = []
        hits = data.get("hits", {}).get("hits", [])

        for hit in hits:
            source = hit.get("_source", {})
            filings.append(SECFiling(
                cik=source.get("ciks", [""])[0],
                company_name=source.get("display_names", [""])[0],
                ticker=source.get("tickers", [""])[0] if source.get("tickers") else "",
                form_type=source.get("form", ""),
                filed_date=source.get("file_date", ""),
                accession_number=source.get("adsh", ""),
                document_url=self._build_document_url(source),
                primary_document=source.get("primary_doc", "")
            ))

        return filings

    def _build_document_url(self, source: Dict[str, Any]) -> str:
        """Build URL to filing document."""
        cik = source.get("ciks", [""])[0].lstrip("0")
        accession = source.get("adsh", "").replace("-", "")
        primary_doc = source.get("primary_doc", "")

        return f"{settings.sec_base_url}/Archives/edgar/data/{cik}/{accession}/{primary_doc}"

┌─────────────────────────────────────────────────────────────┐
│ SEC EDGAR DOCUMENT HIERARCHY                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Company (CIK: 0000320193) → Apple Inc.                     │
│  │                                                          │
│  └─► Filings                                                │
│      ├─► 10-K (Annual Report)                               │
│      │   ├─► Accession: 0000320193-24-000069                │
│      │   └─► Documents:                                     │
│      │       ├─► aapl-20240928.htm (primary)                │
│      │       ├─► Financial_Report.xlsx                      │
│      │       └─► Exhibits (agreements, etc.)                │
│      │                                                      │
│      ├─► 10-Q (Quarterly Report)                            │
│      └─► 8-K (Material Events)                              │
│                                                             │
│  URL Pattern:                                               │
│  /Archives/edgar/data/{CIK}/{accession}/{document}          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# src/ingestion/filing_parser.py
from typing import List, Dict, Any, Optional
from dataclasses import dataclass
import re
from bs4 import BeautifulSoup

@dataclass
class FilingSection:
    section_name: str
    section_number: str
    content: str
    tables: List[Dict[str, Any]]

@dataclass
class ParsedFiling:
    form_type: str
    company_name: str
    fiscal_year: str
    filed_date: str
    sections: List[FilingSection]
    risk_factors: str
    mda: str  # Management Discussion & Analysis
    financial_statements: Dict[str, Any]

class FilingParser:
    """Parse SEC filings (10-K, 10-Q)."""

    # Standard 10-K sections
    SECTION_PATTERNS = {
        "business": r"item\s*1[.\s]+business",
        "risk_factors": r"item\s*1a[.\s]+risk\s*factors",
        "properties": r"item\s*2[.\s]+properties",
        "legal_proceedings": r"item\s*3[.\s]+legal\s*proceedings",
        "mda": r"item\s*7[.\s]+management.{0,30}discussion",
        "financial_statements": r"item\s*8[.\s]+financial\s*statements",
    }

    def parse(self, html_content: str, form_type: str) -> ParsedFiling:
        """Parse a filing document."""
        soup = BeautifulSoup(html_content, 'html.parser')

        # Remove scripts and styles
        for tag in soup(['script', 'style']):
            tag.decompose()

        text = soup.get_text(separator='\n')

        # Extract sections
        sections = self._extract_sections(text)

        # Extract company info
        company_info = self._extract_company_info(text)

        # Extract financial tables
        financial_statements = self._extract_financial_tables(soup)

        return ParsedFiling(
            form_type=form_type,
            company_name=company_info.get("company_name", ""),
            fiscal_year=company_info.get("fiscal_year", ""),
            filed_date=company_info.get("filed_date", ""),
            sections=sections,
            risk_factors=self._get_section_content(sections, "risk_factors"),
            mda=self._get_section_content(sections, "mda"),
            financial_statements=financial_statements
        )

    def _extract_sections(self, text: str) -> List[FilingSection]:
        """Extract standard sections from filing."""
        sections = []
        text_lower = text.lower()

        for section_name, pattern in self.SECTION_PATTERNS.items():
            match = re.search(pattern, text_lower, re.IGNORECASE)
            if match:
                start = match.start()

                # Find end (next section or end of document)
                end = len(text)
                for other_name, other_pattern in self.SECTION_PATTERNS.items():
                    if other_name != section_name:
                        other_match = re.search(other_pattern, text_lower[start+100:], re.IGNORECASE)
                        if other_match:
                            potential_end = start + 100 + other_match.start()
                            if potential_end < end:
                                end = potential_end

                content = text[start:end].strip()

                sections.append(FilingSection(
                    section_name=section_name,
                    section_number=self._get_section_number(section_name),
                    content=content[:50000],  # Limit size
                    tables=[]
                ))

        return sections

    def _extract_company_info(self, text: str) -> Dict[str, str]:
        """Extract company information from filing."""
        info = {}

        # Company name pattern
        company_match = re.search(
            r"(?:company|registrant)[:\s]+([A-Z][A-Za-z\s,\.]+(?:Inc|Corp|LLC|Ltd)\.?)",
            text[:5000]
        )
        if company_match:
            info["company_name"] = company_match.group(1).strip()

        # Fiscal year
        year_match = re.search(r"fiscal\s+year\s+(?:ended?|ending)\s+(\w+\s+\d{1,2},?\s+\d{4})", text[:10000], re.IGNORECASE)
        if year_match:
            info["fiscal_year"] = year_match.group(1)

        return info

    def _extract_financial_tables(self, soup: BeautifulSoup) -> Dict[str, Any]:
        """Extract financial statement tables."""
        tables = {}

        # Find tables with financial data
        for table in soup.find_all('table'):
            table_text = table.get_text().lower()

            # Identify table type
            if "balance sheet" in table_text or "assets" in table_text:
                tables["balance_sheet"] = self._parse_table(table)
            elif "income" in table_text or "revenue" in table_text:
                tables["income_statement"] = self._parse_table(table)
            elif "cash flow" in table_text:
                tables["cash_flow"] = self._parse_table(table)

        return tables

    def _parse_table(self, table) -> List[List[str]]:
        """Parse HTML table to list of lists."""
        rows = []
        for tr in table.find_all('tr'):
            cells = []
            for td in tr.find_all(['td', 'th']):
                cells.append(td.get_text(strip=True))
            if cells:
                rows.append(cells)
        return rows

    def _get_section_number(self, section_name: str) -> str:
        """Get standard section number."""
        numbers = {
            "business": "1",
            "risk_factors": "1A",
            "properties": "2",
            "legal_proceedings": "3",
            "mda": "7",
            "financial_statements": "8"
        }
        return numbers.get(section_name, "")

    def _get_section_content(self, sections: List[FilingSection], name: str) -> str:
        """Get content of specific section."""
        for section in sections:
            if section.section_name == name:
                return section.content
        return ""

┌─────────────────────────────────────────────────────────────┐
│ 10-K STANDARD SECTIONS                                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Item 1:   Business Description ← Company overview          │
│  Item 1A:  Risk Factors ← Critical for risk analysis        │
│  Item 2:   Properties                                       │
│  Item 3:   Legal Proceedings ← Litigation risk              │
│  Item 7:   MD&A (Management Discussion) ← Key insights      │
│  Item 8:   Financial Statements ← Numbers                   │
│                                                             │
│  MOST VALUABLE FOR RAG:                                     │
│  • Item 1A (Risk Factors) - Forward-looking concerns        │
│  • Item 7 (MD&A) - Management's narrative on performance    │
│  • Item 8 (Financials) - Structured data for metrics        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# src/extraction/metrics_extractor.py
from typing import List, Dict, Any, Optional
from dataclasses import dataclass
import re
from openai import OpenAI

from ..config import settings

@dataclass
class FinancialMetric:
    metric_name: str
    value: float
    unit: str  # USD, %, etc.
    period: str
    yoy_change: Optional[float] = None
    context: str = ""

class MetricsExtractor:
    """Extract financial metrics from SEC filings."""

    def __init__(self):
        self.client = OpenAI(api_key=settings.openai_api_key)

        # Regex patterns for common metrics
        self.patterns = {
            "revenue": r"(?:total\s+)?(?:net\s+)?revenue[s]?\s*(?:of|was|were|:)?\s*\$?([\d,]+(?:\.\d+)?)\s*(million|billion|M|B)?",
            "net_income": r"net\s+income\s*(?:of|was|:)?\s*\$?([\d,]+(?:\.\d+)?)\s*(million|billion|M|B)?",
            "eps": r"(?:diluted\s+)?(?:earnings|EPS)\s+per\s+share\s*(?:of|was|:)?\s*\$?([\d,]+(?:\.\d+)?)",
            "gross_margin": r"gross\s+(?:profit\s+)?margin\s*(?:of|was|:)?\s*([\d,]+(?:\.\d+)?)\s*%?",
            "operating_margin": r"operating\s+(?:income\s+)?margin\s*(?:of|was|:)?\s*([\d,]+(?:\.\d+)?)\s*%?"
        }

    def extract_from_text(self, text: str) -> List[FinancialMetric]:
        """Extract metrics using regex patterns."""
        metrics = []

        for metric_name, pattern in self.patterns.items():
            matches = re.finditer(pattern, text, re.IGNORECASE)
            for match in matches:
                value_str = match.group(1).replace(",", "")
                value = float(value_str)

                # Handle unit multiplier
                unit = "USD"
                if len(match.groups()) > 1 and match.group(2):
                    multiplier_text = match.group(2).lower()
                    if multiplier_text in ["billion", "b"]:
                        value *= 1_000_000_000
                    elif multiplier_text in ["million", "m"]:
                        value *= 1_000_000

                if "margin" in metric_name:
                    unit = "%"

                # Get surrounding context
                start = max(0, match.start() - 100)
                end = min(len(text), match.end() + 100)
                context = text[start:end]

                metrics.append(FinancialMetric(
                    metric_name=metric_name,
                    value=value,
                    unit=unit,
                    period=self._extract_period(context),
                    context=context
                ))

        return metrics

    def extract_with_llm(self, text: str) -> List[FinancialMetric]:
        """Extract metrics using LLM for complex cases."""
        prompt = f"""Extract all financial metrics from this text.

Text:
{text[:8000]}

For each metric found, provide:
1. metric_name: revenue, net_income, eps, gross_margin, operating_margin, etc.
2. value: numeric value
3. unit: USD, %, etc.
4. period: fiscal quarter/year

Return as JSON array:
[
    {{
        "metric_name": "revenue",
        "value": 1500000000,
        "unit": "USD",
        "period": "Q4 2024",
        "yoy_change": 15.5
    }}
]"""

        response = self.client.chat.completions.create(
            model=settings.llm_model,
            messages=[
                {"role": "system", "content": "You are a financial data extraction expert."},
                {"role": "user", "content": prompt}
            ],
            response_format={"type": "json_object"},
            temperature=0
        )

        import json
        try:
            data = json.loads(response.choices[0].message.content)
            return [
                FinancialMetric(
                    metric_name=m["metric_name"],
                    value=m["value"],
                    unit=m["unit"],
                    period=m.get("period", ""),
                    yoy_change=m.get("yoy_change")
                )
                for m in data.get("metrics", data) if isinstance(data, list) else data.get("metrics", [])
            ]
        except (json.JSONDecodeError, KeyError):
            return []

    def _extract_period(self, context: str) -> str:
        """Extract fiscal period from context."""
        patterns = [
            r"(Q[1-4]\s*\d{4})",
            r"(fiscal\s+(?:year|quarter)\s+\d{4})",
            r"((?:first|second|third|fourth)\s+quarter\s+\d{4})",
            r"(\d{4}\s+annual)"
        ]

        for pattern in patterns:
            match = re.search(pattern, context, re.IGNORECASE)
            if match:
                return match.group(1)

        return ""

┌─────────────────────────────────────────────────────────────┐
│ DUAL EXTRACTION STRATEGY                                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  REGEX (Fast, Free):                                        │
│  ─────────────────                                          │
│  • "Total revenue of $394.3 billion" → ✓ Captured           │
│  • "Net income was $97B" → ✓ Captured                       │
│  • Standard patterns, 90%+ of cases                         │
│                                                             │
│  LLM (Accurate, Costly):                                    │
│  ───────────────────────                                    │
│  • "Revenue grew 8% to reach $394.3B" → Complex context     │
│  • "Excluding one-time items, adjusted EPS was..." → Needs  │
│    reasoning to identify which number matters               │
│                                                             │
│  STRATEGY:                                                  │
│  1. Run regex first (free, instant)                         │
│  2. Use LLM for complex sections or validation              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# src/analysis/sentiment.py
from typing import List, Dict, Any, Tuple
from dataclasses import dataclass
from enum import Enum
from transformers import pipeline, AutoTokenizer, AutoModelForSequenceClassification

class SentimentLabel(Enum):
    POSITIVE = "positive"
    NEGATIVE = "negative"
    NEUTRAL = "neutral"

@dataclass
class SentimentResult:
    text: str
    label: SentimentLabel
    score: float
    topic: str = ""

class FinancialSentiment:
    """Financial-specific sentiment analysis."""

    def __init__(self):
        # Use FinBERT for financial sentiment
        model_name = "ProsusAI/finbert"
        self.tokenizer = AutoTokenizer.from_pretrained(model_name)
        self.model = AutoModelForSequenceClassification.from_pretrained(model_name)
        self.pipeline = pipeline(
            "sentiment-analysis",
            model=self.model,
            tokenizer=self.tokenizer
        )

        # Financial sentiment keywords
        self.positive_keywords = [
            "growth", "exceeded", "strong", "record", "improved",
            "increased", "profitable", "momentum", "beat", "outperformed"
        ]
        self.negative_keywords = [
            "declined", "missed", "weak", "challenging", "decreased",
            "loss", "concern", "risk", "uncertainty", "impairment"
        ]

    def analyze(self, text: str) -> SentimentResult:
        """Analyze sentiment of financial text."""
        # Truncate for model
        truncated = text[:512]

        result = self.pipeline(truncated)[0]

        label_map = {
            "positive": SentimentLabel.POSITIVE,
            "negative": SentimentLabel.NEGATIVE,
            "neutral": SentimentLabel.NEUTRAL
        }

        return SentimentResult(
            text=text[:200],
            label=label_map.get(result["label"].lower(), SentimentLabel.NEUTRAL),
            score=result["score"]
        )

    def analyze_earnings_call(
        self,
        transcript: str
    ) -> Dict[str, Any]:
        """Analyze sentiment throughout earnings call."""
        # Split into sections
        sections = self._split_transcript(transcript)

        results = {
            "overall_sentiment": None,
            "management_sentiment": [],
            "qa_sentiment": [],
            "key_topics": [],
            "sentiment_shifts": []
        }

        # Analyze each section
        for section in sections:
            sentiment = self.analyze(section["content"])

            if section["type"] == "prepared_remarks":
                results["management_sentiment"].append({
                    "speaker": section.get("speaker", "Management"),
                    "sentiment": sentiment.label.value,
                    "score": sentiment.score
                })
            elif section["type"] == "qa":
                results["qa_sentiment"].append({
                    "question": section.get("question", ""),
                    "sentiment": sentiment.label.value,
                    "score": sentiment.score
                })

        # Calculate overall sentiment
        all_scores = [s["score"] for s in results["management_sentiment"]]
        if all_scores:
            avg_score = sum(all_scores) / len(all_scores)
            results["overall_sentiment"] = {
                "score": avg_score,
                "label": self._score_to_label(avg_score)
            }

        return results

    def _split_transcript(self, transcript: str) -> List[Dict[str, Any]]:
        """Split earnings call transcript into sections."""
        import re

        sections = []

        # Split by speaker
        speaker_pattern = r"([A-Z][a-z]+\s+[A-Z][a-z]+(?:\s+[A-Z][a-z]+)?)\s*[-–:]\s*"
        parts = re.split(speaker_pattern, transcript)

        for i in range(1, len(parts), 2):
            if i + 1 < len(parts):
                speaker = parts[i]
                content = parts[i + 1]

                section_type = "qa" if "?" in content[:500] else "prepared_remarks"

                sections.append({
                    "speaker": speaker,
                    "content": content,
                    "type": section_type
                })

        return sections

    def _score_to_label(self, score: float) -> str:
        """Convert score to sentiment label."""
        if score > 0.6:
            return "positive"
        elif score < 0.4:
            return "negative"
        return "neutral"

# src/generation/rag_pipeline.py
from typing import List, Dict, Any, Optional
from dataclasses import dataclass
from openai import OpenAI
from pinecone import Pinecone

from ..config import settings

@dataclass
class ResearchAnswer:
    answer: str
    confidence: float
    sources: List[Dict[str, Any]]
    key_metrics: List[Dict[str, Any]]
    risks_identified: List[str]

class FinancialRAG:
    """RAG pipeline for financial research Q&A."""

    def __init__(self):
        self.openai = OpenAI(api_key=settings.openai_api_key)
        self.pinecone = Pinecone(api_key=settings.pinecone_api_key)
        self.index = self.pinecone.Index(settings.pinecone_index)

    def index_filing(
        self,
        filing_id: str,
        company: str,
        form_type: str,
        sections: List[Dict[str, Any]]
    ):
        """Index a filing's sections."""
        vectors = []

        for section in sections:
            # Generate embedding
            embedding = self._embed(section["content"][:8000])

            vectors.append({
                "id": f"{filing_id}_{section['name']}",
                "values": embedding,
                "metadata": {
                    "filing_id": filing_id,
                    "company": company,
                    "form_type": form_type,
                    "section": section["name"],
                    "content": section["content"][:4000]  # Truncate for metadata
                }
            })

        # Upsert in batches
        for i in range(0, len(vectors), 100):
            self.index.upsert(vectors=vectors[i:i+100])

    def query(
        self,
        question: str,
        companies: List[str] = None,
        form_types: List[str] = None,
        top_k: int = 10
    ) -> ResearchAnswer:
        """Answer a financial research question."""
        # Generate query embedding
        query_embedding = self._embed(question)

        # Build filter
        filter_dict = {}
        if companies:
            filter_dict["company"] = {"$in": companies}
        if form_types:
            filter_dict["form_type"] = {"$in": form_types}

        # Search
        results = self.index.query(
            vector=query_embedding,
            top_k=top_k,
            include_metadata=True,
            filter=filter_dict if filter_dict else None
        )

        if not results.matches:
            return ResearchAnswer(
                answer="No relevant information found.",
                confidence=0.0,
                sources=[],
                key_metrics=[],
                risks_identified=[]
            )

        # Prepare context
        context = self._prepare_context(results.matches)

        # Generate answer
        answer = self._generate_answer(question, context)

        return ResearchAnswer(
            answer=answer["response"],
            confidence=answer["confidence"],
            sources=[
                {
                    "company": m.metadata["company"],
                    "form_type": m.metadata["form_type"],
                    "section": m.metadata["section"],
                    "score": m.score
                }
                for m in results.matches[:5]
            ],
            key_metrics=answer.get("metrics", []),
            risks_identified=answer.get("risks", [])
        )

    def _embed(self, text: str) -> List[float]:
        """Generate embedding."""
        response = self.openai.embeddings.create(
            model=settings.embedding_model,
            input=text
        )
        return response.data[0].embedding

    def _prepare_context(self, matches) -> str:
        """Prepare context from search results."""
        parts = []
        for i, match in enumerate(matches[:5]):
            meta = match.metadata
            parts.append(f"""
[Source {i+1}] {meta['company']} - {meta['form_type']} ({meta['section']})
{meta['content']}
""")
        return "\n".join(parts)

    def _generate_answer(self, question: str, context: str) -> Dict[str, Any]:
        """Generate research answer."""
        prompt = f"""You are a financial analyst. Answer the question using ONLY the provided SEC filings.

SEC Filing Excerpts:
{context}

Question: {question}

Instructions:
1. Base your answer ONLY on the provided filings
2. Cite sources using [Source N] format
3. Extract relevant financial metrics
4. Highlight any risk factors mentioned
5. Be precise and quantitative where possible

Return JSON:
{{
    "response": "Your detailed answer with citations",
    "confidence": 0.0-1.0,
    "metrics": [{{"name": "revenue", "value": 1000000, "period": "2024"}}],
    "risks": ["risk 1", "risk 2"]
}}"""

        response = self.openai.chat.completions.create(
            model=settings.llm_model,
            messages=[
                {"role": "system", "content": "You are a financial research analyst."},
                {"role": "user", "content": prompt}
            ],
            response_format={"type": "json_object"},
            temperature=0.1
        )

        import json
        return json.loads(response.choices[0].message.content)

┌─────────────────────────────────────────────────────────────┐
│ FINANCIAL RAG REQUIREMENTS                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  METADATA FILTERING (Critical for finance):                 │
│  ───────────────────────────────────────                    │
│  • filter: {company: "AAPL"} → Only Apple's filings         │
│  • filter: {form_type: "10-K"} → Only annual reports        │
│  • filter: {company: {$in: ["AAPL", "MSFT", "GOOGL"]}}      │
│    → Peer comparison across competitors                     │
│                                                             │
│  TYPICAL QUERIES:                                           │
│  ────────────────                                           │
│  • "What are Apple's main risks?" → filter: company=AAPL    │
│  • "Compare cloud revenue growth" → filter: form_type=10-K  │
│  • "Recent material events" → filter: form_type=8-K         │
│                                                             │
│  WHY THIS MATTERS:                                          │
│  ─────────────────                                          │
│  Without filtering, "Apple's revenue" might return          │
│  Microsoft's filing about competing with Apple              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# src/api/main.py
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from typing import List, Dict, Any, Optional

from ..config import settings
from ..ingestion.sec_client import SECClient
from ..ingestion.filing_parser import FilingParser
from ..extraction.metrics_extractor import MetricsExtractor
from ..analysis.sentiment import FinancialSentiment
from ..generation.rag_pipeline import FinancialRAG

app = FastAPI(
    title="Financial Research Assistant",
    description="AI-powered SEC filing analysis and research",
    version="1.0.0"
)

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"]
)

# Initialize components
sec_client = SECClient()
filing_parser = FilingParser()
metrics_extractor = MetricsExtractor()
sentiment_analyzer = FinancialSentiment()
rag = FinancialRAG()


class AnalyzeRequest(BaseModel):
    ticker: str
    form_types: List[str] = ["10-K", "10-Q"]
    max_filings: int = 5

class QuestionRequest(BaseModel):
    question: str
    companies: Optional[List[str]] = None
    form_types: Optional[List[str]] = None


@app.post("/api/company/analyze")
async def analyze_company(request: AnalyzeRequest):
    """Analyze a company's SEC filings."""
    # Fetch filings
    filings = await sec_client.get_company_filings(
        ticker=request.ticker,
        form_types=request.form_types
    )

    results = []
    for filing in filings[:request.max_filings]:
        # Fetch and parse content
        content = await sec_client.fetch_filing_content(filing)
        parsed = filing_parser.parse(content, filing.form_type)

        # Extract metrics
        metrics = metrics_extractor.extract_from_text(parsed.mda)

        # Analyze risk factors sentiment
        risk_sentiment = sentiment_analyzer.analyze(parsed.risk_factors[:2000])

        # Index for RAG
        rag.index_filing(
            filing_id=filing.accession_number,
            company=request.ticker,
            form_type=filing.form_type,
            sections=[
                {"name": s.section_name, "content": s.content}
                for s in parsed.sections
            ]
        )

        results.append({
            "form_type": filing.form_type,
            "filed_date": filing.filed_date,
            "metrics": [
                {"name": m.metric_name, "value": m.value, "unit": m.unit}
                for m in metrics[:10]
            ],
            "risk_sentiment": risk_sentiment.label.value,
            "sections_found": len(parsed.sections)
        })

    return {
        "ticker": request.ticker,
        "filings_analyzed": len(results),
        "results": results
    }


@app.post("/api/research/question")
async def answer_question(request: QuestionRequest):
    """Answer a financial research question."""
    answer = rag.query(
        question=request.question,
        companies=request.companies,
        form_types=request.form_types
    )

    return {
        "question": request.question,
        "answer": answer.answer,
        "confidence": answer.confidence,
        "sources": answer.sources,
        "key_metrics": answer.key_metrics,
        "risks": answer.risks_identified
    }


@app.get("/api/health")
async def health_check():
    return {"status": "healthy"}

# docker-compose.yml
version: '3.8'

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - PINECONE_API_KEY=${PINECONE_API_KEY}
      - SEC_USER_AGENT=${SEC_USER_AGENT}

# requirements.txt
fastapi==0.109.0
uvicorn==0.27.0
pydantic==2.5.3
pydantic-settings==2.1.0
openai==1.10.0
pinecone-client==3.0.0
transformers==4.37.0
beautifulsoup4==4.12.3
aiohttp==3.9.1

import requests

# Analyze a company
response = requests.post(
    "http://localhost:8000/api/company/analyze",
    json={
        "ticker": "AAPL",
        "form_types": ["10-K", "10-Q"],
        "max_filings": 3
    }
)
analysis = response.json()
print(f"Analyzed {analysis['filings_analyzed']} filings")

# Ask a research question
response = requests.post(
    "http://localhost:8000/api/research/question",
    json={
        "question": "What are Apple's main revenue drivers and growth outlook?",
        "companies": ["AAPL"]
    }
)
answer = response.json()
print(f"Answer: {answer['answer']}")