Financial Deep Research

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
*.egg-info/
.eggs/
*.egg

# Virtual environments
venv/
ENV/
env/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Research outputs (generated during runtime)
/research_output/
*.pdf
*.html

# Temporary files
*.tmp
*.temp
*.log

# Financial Deep Research Skill - Requirements
# All dependencies are Python standard library - no external packages needed

# The following are included with Python 3.8+:
# - argparse (CLI argument parsing)
# - re (regex for validation)
# - pathlib (file path handling)
# - dataclasses (data structures)
# - typing (type hints)
# - datetime (date handling)
# - urllib (HTTP requests for citation verification)
# - json (JSON parsing)
# - hashlib (citation ID generation)

# No pip install required!

#!/usr/bin/env python3
"""
Financial Citation Management System
Tracks sources, generates citations, and maintains bibliography with tier tracking
"""

from dataclasses import dataclass, field
from typing import List, Dict, Optional
from datetime import datetime
from urllib.parse import urlparse
import hashlib


@dataclass
class FinancialCitation:
    """Represents a single financial citation"""
    id: str
    title: str
    url: str
    tier: int  # 1-4 (1 = highest credibility)
    authors: Optional[List[str]] = None
    publication_date: Optional[str] = None
    retrieved_date: str = field(default_factory=lambda: datetime.now().strftime('%Y-%m-%d'))
    source_type: str = "web"  # sec_filing, data_provider, financial_news, general
    filing_type: Optional[str] = None  # 10-K, 10-Q, 8-K, etc.
    ticker: Optional[str] = None
    doi: Optional[str] = None
    citation_count: int = 0

    def to_markdown(self, index: int) -> str:
        """Generate markdown format citation"""
        tier_label = f"[Tier {self.tier}]" if self.tier else ""
        filing = f" ({self.filing_type})" if self.filing_type else ""
        ticker = f" [{self.ticker}]" if self.ticker else ""

        return f"[{index}]{ticker}{filing} [{self.title}]({self.url}) {tier_label} (Retrieved: {self.retrieved_date})"

    def to_inline(self, index: int) -> str:
        """Generate inline citation [index]"""
        return f"[{index}]"

    def to_bibliography_entry(self, index: int) -> str:
        """Generate full bibliography entry"""
        author_str = ""
        if self.authors:
            if len(self.authors) == 1:
                author_str = f"{self.authors[0]}."
            elif len(self.authors) == 2:
                author_str = f"{self.authors[0]} & {self.authors[1]}."
            else:
                author_str = f"{self.authors[0]} et al."

        date_str = f"({self.publication_date})" if self.publication_date else "(n.d.)"
        filing = f" {self.filing_type}." if self.filing_type else ""

        return f"[{index}] {author_str} {date_str}.{filing} \"{self.title}\". {self.url} (Retrieved: {self.retrieved_date})"


class FinancialCitationManager:
    """Manages financial citations and bibliography with tier organization"""

    # Domain to tier mapping
    TIER_MAPPING = {
        # Tier 1: Regulatory/Primary
        'sec.gov': 1, 'edgar.sec.gov': 1, 'federalreserve.gov': 1,
        'treasury.gov': 1, 'fdic.gov': 1, 'finra.org': 1,

        # Tier 2: Data Providers
        'bloomberg.com': 2, 'reuters.com': 2, 'spglobal.com': 2,
        'moodys.com': 2, 'fitchratings.com': 2, 'factset.com': 2,
        'morningstar.com': 2, 'pitchbook.com': 2,

        # Tier 3: Financial News
        'wsj.com': 3, 'ft.com': 3, 'barrons.com': 3,
        'cnbc.com': 3, 'marketwatch.com': 3,

        # Tier 4: General
        'seekingalpha.com': 4, 'finance.yahoo.com': 4,
    }

    def __init__(self):
        self.citations: Dict[str, FinancialCitation] = {}
        self.citation_order: List[str] = []

    def add_source(
        self,
        url: str,
        title: str,
        authors: Optional[List[str]] = None,
        publication_date: Optional[str] = None,
        source_type: str = "web",
        filing_type: Optional[str] = None,
        ticker: Optional[str] = None,
        doi: Optional[str] = None,
        tier: Optional[int] = None
    ) -> str:
        """Add a financial source and return its citation ID"""
        citation_id = hashlib.md5(url.encode()).hexdigest()[:8]

        if citation_id not in self.citations:
            # Auto-detect tier if not provided
            if tier is None:
                tier = self._detect_tier(url, source_type, filing_type)

            citation = FinancialCitation(
                id=citation_id,
                title=title,
                url=url,
                tier=tier,
                authors=authors,
                publication_date=publication_date,
                source_type=source_type,
                filing_type=filing_type,
                ticker=ticker,
                doi=doi
            )
            self.citations[citation_id] = citation
            self.citation_order.append(citation_id)

        self.citations[citation_id].citation_count += 1
        return citation_id

    def _detect_tier(self, url: str, source_type: str, filing_type: Optional[str]) -> int:
        """Auto-detect source tier based on URL and type"""
        # SEC filings are always Tier 1
        if filing_type or 'sec.gov' in url.lower():
            return 1

        # Company IR sites are Tier 1
        if any(pattern in url.lower() for pattern in ['ir.', 'investor.', 'investors.']):
            return 1

        # Check domain mapping
        parsed = urlparse(url)
        domain = parsed.netloc.lower().replace('www.', '')

        for domain_pattern, tier in self.TIER_MAPPING.items():
            if domain_pattern in domain:
                return tier

        # Default to Tier 4
        return 4

    def get_citation_number(self, citation_id: str) -> Optional[int]:
        """Get the citation number for a given ID"""
        try:
            return self.citation_order.index(citation_id) + 1
        except ValueError:
            return None

    def get_inline_citation(self, citation_id: str) -> str:
        """Get inline citation marker [n]"""
        num = self.get_citation_number(citation_id)
        return f"[{num}]" if num else "[?]"

    def generate_bibliography(self, organize_by_tier: bool = True) -> str:
        """Generate full bibliography, optionally organized by tier"""
        if not organize_by_tier:
            lines = ["## Bibliography\n"]
            for i, citation_id in enumerate(self.citation_order, 1):
                citation = self.citations[citation_id]
                lines.append(citation.to_bibliography_entry(i))
            return "\n\n".join(lines)

        # Organize by tier
        lines = ["## Bibliography\n"]

        tier_names = {
            1: "### Tier 1 Sources (Regulatory/Primary)",
            2: "### Tier 2 Sources (Data Providers)",
            3: "### Tier 3 Sources (Financial News/Research)",
            4: "### Tier 4 Sources (General Business)"
        }

        # Group by tier
        tier_citations = {1: [], 2: [], 3: [], 4: []}
        for i, citation_id in enumerate(self.citation_order, 1):
            citation = self.citations[citation_id]
            tier_citations[citation.tier].append((i, citation))

        # Generate by tier
        for tier in [1, 2, 3, 4]:
            if tier_citations[tier]:
                lines.append(f"\n{tier_names[tier]}\n")
                for i, citation in tier_citations[tier]:
                    lines.append(citation.to_bibliography_entry(i))

        return "\n".join(lines)

    def get_statistics(self) -> Dict[str, any]:
        """Get citation statistics"""
        tier_counts = {1: 0, 2: 0, 3: 0, 4: 0}
        for citation in self.citations.values():
            tier_counts[citation.tier] += 1

        return {
            'total_sources': len(self.citations),
            'total_citations': sum(c.citation_count for c in self.citations.values()),
            'tier_breakdown': tier_counts,
            'tier1_percentage': (tier_counts[1] / len(self.citations) * 100) if self.citations else 0,
            'filing_types': self._count_filing_types(),
            'most_cited': self._get_most_cited(5)
        }

    def _count_filing_types(self) -> Dict[str, int]:
        """Count SEC filing types"""
        counts = {}
        for citation in self.citations.values():
            if citation.filing_type:
                counts[citation.filing_type] = counts.get(citation.filing_type, 0) + 1
        return counts

    def _get_most_cited(self, n: int = 5) -> List[tuple]:
        """Get most cited sources"""
        sorted_citations = sorted(
            self.citations.items(),
            key=lambda x: x[1].citation_count,
            reverse=True
        )
        return [(self.get_citation_number(cid), c.title, c.citation_count)
                for cid, c in sorted_citations[:n]]


# Example usage
if __name__ == '__main__':
    manager = FinancialCitationManager()

    # Add SEC filing
    id1 = manager.add_source(
        url="https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193",
        title="Apple Inc. Form 10-K Annual Report",
        publication_date="2024",
        source_type="sec_filing",
        filing_type="10-K",
        ticker="AAPL"
    )

    # Add data provider
    id2 = manager.add_source(
        url="https://www.bloomberg.com/quote/AAPL:US",
        title="Apple Inc Stock Price",
        source_type="data_provider"
    )

    # Add financial news
    id3 = manager.add_source(
        url="https://www.wsj.com/articles/apple-earnings-2024",
        title="Apple Reports Q4 Earnings",
        publication_date="2024-10-31",
        source_type="financial_news"
    )

    print(f"Citation 1: {manager.get_inline_citation(id1)}")
    print(f"Citation 2: {manager.get_inline_citation(id2)}")
    print(f"\nBibliography:\n{manager.generate_bibliography()}")
    print(f"\nStatistics:\n{manager.get_statistics()}")

#!/usr/bin/env python3
"""
Markdown to HTML converter for financial research reports
Properly converts markdown sections to HTML while preserving structure and formatting
"""

import re
from typing import Tuple
from pathlib import Path


def convert_markdown_to_html(markdown_text: str) -> Tuple[str, str]:
    """
    Convert markdown to HTML in two parts: content and bibliography

    Args:
        markdown_text: Full markdown report text

    Returns:
        Tuple of (content_html, bibliography_html)
    """
    # Split content and bibliography
    parts = markdown_text.split('## Bibliography')
    content_md = parts[0]
    bibliography_md = parts[1] if len(parts) > 1 else ""

    # Convert content (everything except bibliography)
    content_html = _convert_content_section(content_md)

    # Convert bibliography separately
    bibliography_html = _convert_bibliography_section(bibliography_md)

    return content_html, bibliography_html


def _convert_content_section(markdown: str) -> str:
    """Convert main content sections to HTML"""
    html = markdown

    # Remove title and front matter
    lines = html.split('\n')
    processed_lines = []
    skip_until_first_section = True

    for line in lines:
        if skip_until_first_section:
            if line.startswith('## ') and not line.startswith('### '):
                skip_until_first_section = False
                processed_lines.append(line)
            continue
        processed_lines.append(line)

    html = '\n'.join(processed_lines)

    # Convert headers
    html = re.sub(
        r'^## (.+)$',
        r'<div class="section"><h2 class="section-title">\1</h2>',
        html,
        flags=re.MULTILINE
    )

    html = re.sub(
        r'^### (.+)$',
        r'<h3 class="subsection-title">\1</h3>',
        html,
        flags=re.MULTILINE
    )

    html = re.sub(
        r'^#### (.+)$',
        r'<h4 class="subsubsection-title">\1</h4>',
        html,
        flags=re.MULTILINE
    )

    # Convert **bold** text
    html = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', html)

    # Convert *italic* text
    html = re.sub(r'\*(.+?)\*', r'<em>\1</em>', html)

    # Convert inline code
    html = re.sub(r'`(.+?)`', r'<code>\1</code>', html)

    # Convert lists
    html = _convert_lists(html)

    # Convert tables
    html = _convert_tables(html)

    # Convert paragraphs
    html = _convert_paragraphs(html)

    # Close sections
    html = _close_sections(html)

    # Wrap executive summary
    html = html.replace(
        '<h2 class="section-title">Executive Summary</h2>',
        '<div class="executive-summary"><h2 class="section-title">Executive Summary</h2>'
    )
    if '<div class="executive-summary">' in html:
        html = html.replace(
            '</h2>\n<div class="section">',
            '</h2></div>\n<div class="section">',
            1
        )

    return html


def _convert_bibliography_section(markdown: str) -> str:
    """Convert bibliography section to HTML with tier organization"""
    if not markdown.strip():
        return ""

    html = markdown

    # Convert tier headers
    html = re.sub(
        r'^### (Tier \d.+)$',
        r'<div class="bib-tier"><div class="bib-tier-title">\1</div>',
        html,
        flags=re.MULTILINE
    )

    # Convert citation entries
    html = re.sub(
        r'\[(\d+)\]\s*(.+?)\s*(https?://[^\s\)]+)',
        r'<div class="bib-entry"><span class="bib-number">[\1]</span> \2 <a href="\3" target="_blank">\3</a></div>',
        html
    )

    # Convert bold
    html = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', html)

    html = f'<div class="bibliography-content">{html}</div>'

    return html


def _convert_lists(html: str) -> str:
    """Convert markdown lists to HTML lists"""
    lines = html.split('\n')
    result = []
    in_list = False
    list_type = None

    for line in lines:
        stripped = line.strip()

        if stripped.startswith('- ') or stripped.startswith('* '):
            if not in_list:
                result.append('<ul>')
                in_list = True
                list_type = 'ul'
            content = stripped[2:]
            result.append(f'<li>{content}</li>')

        elif re.match(r'^\d+\.\s', stripped):
            if not in_list:
                result.append('<ol>')
                in_list = True
                list_type = 'ol'
            content = re.sub(r'^\d+\.\s', '', stripped)
            result.append(f'<li>{content}</li>')

        else:
            if in_list:
                result.append(f'</{list_type}>')
                in_list = False
                list_type = None
            result.append(line)

    if in_list:
        result.append(f'</{list_type}>')

    return '\n'.join(result)


def _convert_tables(html: str) -> str:
    """Convert markdown tables to HTML tables"""
    lines = html.split('\n')
    result = []
    in_table = False
    is_header = False

    for line in lines:
        if '|' in line and line.strip().startswith('|'):
            if not in_table:
                result.append('<table class="data-table">')
                in_table = True
                is_header = True
                cells = [cell.strip() for cell in line.split('|')[1:-1]]
                result.append('<thead><tr>')
                for cell in cells:
                    result.append(f'<th>{cell}</th>')
                result.append('</tr></thead>')
                result.append('<tbody>')
            elif '---' in line:
                continue
            else:
                cells = [cell.strip() for cell in line.split('|')[1:-1]]
                result.append('<tr>')
                for cell in cells:
                    # Add numeric class for numbers
                    css_class = 'numeric' if re.match(r'^[\$\d\.\,\%\+\-]+$', cell.replace('B', '').replace('M', '').replace('K', '')) else ''
                    # Add positive/negative class for changes
                    if cell.startswith('+'):
                        css_class += ' positive'
                    elif cell.startswith('-') and '%' in cell:
                        css_class += ' negative'
                    result.append(f'<td class="{css_class.strip()}">{cell}</td>')
                result.append('</tr>')
        else:
            if in_table:
                result.append('</tbody></table>')
                in_table = False
            result.append(line)

    if in_table:
        result.append('</tbody></table>')

    return '\n'.join(result)


def _convert_paragraphs(html: str) -> str:
    """Wrap non-HTML lines in paragraph tags"""
    lines = html.split('\n')
    result = []
    in_paragraph = False

    for line in lines:
        stripped = line.strip()

        if not stripped:
            if in_paragraph:
                result.append('</p>')
                in_paragraph = False
            result.append(line)
            continue

        if (stripped.startswith('<') and stripped.endswith('>')) or \
           stripped.startswith('</') or \
           '<h' in stripped or '<div' in stripped or '<ul' in stripped or \
           '<ol' in stripped or '<li' in stripped or '<table' in stripped:
            if in_paragraph:
                result.append('</p>')
                in_paragraph = False
            result.append(line)
            continue

        if not in_paragraph:
            result.append('<p>' + line)
            in_paragraph = True
        else:
            result.append(line)

    if in_paragraph:
        result.append('</p>')

    return '\n'.join(result)


def _close_sections(html: str) -> str:
    """Close all open section divs"""
    lines = html.split('\n')
    result = []
    section_open = False

    for line in lines:
        if '<div class="section">' in line:
            if section_open:
                result.append('</div>')
            section_open = True
        result.append(line)

    if section_open:
        result.append('</div>')

    return '\n'.join(result)


def main():
    """Test the converter"""
    import sys

    if len(sys.argv) < 2:
        print("Usage: python md_to_html.py <markdown_file>")
        sys.exit(1)

    md_file = Path(sys.argv[1])
    if not md_file.exists():
        print(f"Error: File {md_file} not found")
        sys.exit(1)

    markdown_text = md_file.read_text()
    content_html, bib_html = convert_markdown_to_html(markdown_text)

    print("=== CONTENT HTML ===")
    print(content_html[:1500])
    print("\n=== BIBLIOGRAPHY HTML ===")
    print(bib_html[:500])


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Financial Research Engine
Core orchestration for financial deep research pipeline

Note: This is a placeholder for the research engine. The actual orchestration
is handled by Claude Code when the skill is invoked. This module provides
utility functions that can be called from the command line for testing.
"""

import argparse
import sys
from pathlib import Path
from datetime import datetime


def main():
    """Entry point for financial research engine"""
    parser = argparse.ArgumentParser(
        description="Financial Deep Research Engine",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Financial Research Modes:
  quick      - Market snapshot, 2-5 min, 10+ sources
  standard   - Most analysis, 5-10 min, 15-30 sources (default)
  deep       - Investment decisions, 10-20 min, 25-50 sources
  ultradeep  - M&A due diligence, 20-45 min, 30-100+ sources

Examples:
  python research_engine.py --query "Analyze Apple investment thesis" --mode standard
  python research_engine.py --query "NVDA vs AMD competitive analysis" --mode deep
  python research_engine.py --query "Fintech sector due diligence" --mode ultradeep

Note: This engine is typically invoked through Claude Code's skill system.
Direct CLI usage is for testing and debugging.
        """
    )

    parser.add_argument(
        '--query', '-q',
        type=str,
        required=True,
        help='Financial research query'
    )

    parser.add_argument(
        '--mode', '-m',
        type=str,
        choices=['quick', 'standard', 'deep', 'ultradeep'],
        default='standard',
        help='Research mode (default: standard)'
    )

    parser.add_argument(
        '--output', '-o',
        type=str,
        default=None,
        help='Output directory (default: /code/research_output/)'
    )

    args = parser.parse_args()

    print(f"\n{'='*60}")
    print(f"FINANCIAL DEEP RESEARCH ENGINE")
    print(f"{'='*60}\n")

    print(f"Query: {args.query}")
    print(f"Mode: {args.mode}")
    print(f"Output: {args.output or '/code/research_output/'}")
    print()

    # Mode configuration
    mode_config = {
        'quick': {
            'phases': [1, 3, 8],
            'min_sources': 10,
            'target_time': '2-5 min',
            'description': 'Market snapshot'
        },
        'standard': {
            'phases': [1, 2, 3, 4, 4.5, 5, 8],
            'min_sources': 15,
            'target_time': '5-10 min',
            'description': 'Standard analysis'
        },
        'deep': {
            'phases': [1, 2, 3, 4, 4.5, 5, 6, 7, 8],
            'min_sources': 25,
            'target_time': '10-20 min',
            'description': 'Investment decision'
        },
        'ultradeep': {
            'phases': [1, 2, 3, 4, 4.5, 5, 6, 7, 8],
            'min_sources': 30,
            'target_time': '20-45 min',
            'description': 'M&A due diligence'
        }
    }

    config = mode_config[args.mode]

    print(f"Configuration:")
    print(f"  Phases: {config['phases']}")
    print(f"  Min Sources: {config['min_sources']}")
    print(f"  Target Time: {config['target_time']}")
    print(f"  Description: {config['description']}")
    print()

    print("Note: Full research execution requires Claude Code skill invocation.")
    print("This CLI provides configuration preview and testing utilities.")
    print()

    # Generate output directory name
    timestamp = datetime.now().strftime('%Y%m%d')
    topic_slug = args.query[:30].replace(' ', '_').replace('/', '_')
    output_dir = f"/code/{topic_slug}_Financial_Research_{timestamp}/"

    print(f"Recommended output directory: {output_dir}")
    print()

    return 0


if __name__ == '__main__':
    sys.exit(main())

#!/usr/bin/env python3
"""
Financial Source Credibility Evaluator
Assesses source quality, credibility, and potential biases for financial research
"""

from dataclasses import dataclass
from typing import List, Dict, Optional
from urllib.parse import urlparse
from datetime import datetime, timedelta
import re


@dataclass
class CredibilityScore:
    """Represents financial source credibility assessment"""
    overall_score: float  # 0-100
    domain_authority: float  # 0-100
    recency: float  # 0-100
    expertise: float  # 0-100
    bias_score: float  # 0-100 (higher = more neutral)
    tier: int  # 1-4 (1 = highest credibility)
    factors: Dict[str, str]
    recommendation: str  # "high_trust", "moderate_trust", "low_trust", "verify"


class FinancialSourceEvaluator:
    """Evaluates financial source credibility and quality with tiered system"""

    # Tier 1: Primary/Regulatory Sources (Highest Credibility)
    TIER_1_DOMAINS = {
        # SEC & Regulatory
        'sec.gov', 'edgar.sec.gov', 'investor.gov',
        'federalreserve.gov', 'treasury.gov', 'fdic.gov',
        'occ.gov', 'finra.org', 'cftc.gov', 'bis.org',

        # Company IR (pattern-based, checked separately)
        # ir.*, investor.*, investors.*

        # Stock Exchanges
        'nyse.com', 'nasdaq.com', 'ice.com', 'cmegroup.com',

        # International Regulators
        'fca.org.uk', 'esma.europa.eu', 'bafin.de',
    }

    # Tier 2: Financial Data Providers (High Credibility)
    TIER_2_DOMAINS = {
        # Major Data Providers
        'bloomberg.com', 'reuters.com', 'refinitiv.com',
        'spglobal.com', 'capitaliq.com', 'moodys.com',
        'fitchratings.com', 'factset.com', 'morningstar.com',
        'pitchbook.com', 'preqin.com', 'dealogic.com',

        # Research Providers
        'mckinsey.com', 'bcg.com', 'bain.com', 'deloitte.com',
        'pwc.com', 'ey.com', 'kpmg.com',
    }

    # Tier 3: Financial News & Research (Moderate-High Credibility)
    TIER_3_DOMAINS = {
        # Established Financial News
        'wsj.com', 'ft.com', 'barrons.com', 'economist.com',
        'marketwatch.com', 'investopedia.com', 'thestreet.com',

        # Business News
        'cnbc.com', 'fortune.com', 'businessinsider.com',
        'forbes.com', 'bloomberg.com',  # News articles

        # Industry Publications
        'americanbanker.com', 'institutionalinvestor.com',
        'privateequityinternational.com', 'pensions-investments.com',
    }

    # Tier 4: General Business Sources (Moderate Credibility)
    TIER_4_DOMAINS = {
        # General Finance
        'finance.yahoo.com', 'google.com/finance',
        'seekingalpha.com', 'fool.com', 'zacks.com',
        'tipranks.com', 'gurufocus.com',

        # General News
        'nytimes.com', 'washingtonpost.com', 'bbc.com',
        'cnn.com', 'theguardian.com',

        # Tech/Business Blogs
        'medium.com', 'substack.com', 'linkedin.com',
    }

    # Low credibility indicators
    LOW_CREDIBILITY_INDICATORS = [
        'blogspot.com', 'wordpress.com', 'wix.com',
        'reddit.com', 'twitter.com', 'facebook.com',
        'stocktwits.com', 'wallstreetbets',
    ]

    def __init__(self):
        pass

    def evaluate_source(
        self,
        url: str,
        title: str,
        content: Optional[str] = None,
        publication_date: Optional[str] = None,
        author: Optional[str] = None
    ) -> CredibilityScore:
        """Evaluate financial source credibility"""

        domain = self._extract_domain(url)

        # Determine tier first
        tier = self._determine_tier(domain, url)

        # Calculate component scores
        domain_score = self._evaluate_domain_authority(domain, tier)
        recency_score = self._evaluate_recency(publication_date)
        expertise_score = self._evaluate_expertise(domain, title, author, tier)
        bias_score = self._evaluate_bias(domain, title, content, tier)

        # Calculate overall score (weighted average)
        overall = (
            domain_score * 0.40 +  # Higher weight for domain in financial
            recency_score * 0.20 +
            expertise_score * 0.25 +
            bias_score * 0.15
        )

        # Determine factors
        factors = self._identify_factors(
            domain, tier, domain_score, recency_score, expertise_score, bias_score
        )

        # Generate recommendation
        recommendation = self._generate_recommendation(overall, tier)

        return CredibilityScore(
            overall_score=round(overall, 2),
            domain_authority=round(domain_score, 2),
            recency=round(recency_score, 2),
            expertise=round(expertise_score, 2),
            bias_score=round(bias_score, 2),
            tier=tier,
            factors=factors,
            recommendation=recommendation
        )

    def _extract_domain(self, url: str) -> str:
        """Extract domain from URL"""
        parsed = urlparse(url)
        domain = parsed.netloc.lower()
        # Remove www prefix
        domain = domain.replace('www.', '')
        return domain

    def _determine_tier(self, domain: str, url: str) -> int:
        """Determine source tier (1-4)"""

        # Check Tier 1
        if domain in self.TIER_1_DOMAINS:
            return 1
        # Check for company IR sites (Tier 1)
        if any(pattern in domain for pattern in ['ir.', 'investor.', 'investors.']):
            return 1
        # SEC EDGAR links
        if 'sec.gov' in url:
            return 1

        # Check Tier 2
        if domain in self.TIER_2_DOMAINS:
            return 2

        # Check Tier 3
        if domain in self.TIER_3_DOMAINS:
            return 3

        # Check Tier 4
        if domain in self.TIER_4_DOMAINS:
            return 4

        # Check low credibility
        if any(indicator in domain for indicator in self.LOW_CREDIBILITY_INDICATORS):
            return 4  # Lowest tier

        # Unknown domain - default to tier 4
        return 4

    def _evaluate_domain_authority(self, domain: str, tier: int) -> float:
        """Evaluate domain authority based on tier (0-100)"""
        tier_scores = {
            1: 95.0,  # Regulatory/Primary
            2: 82.0,  # Data Providers
            3: 68.0,  # Financial News
            4: 50.0,  # General Business
        }

        base_score = tier_scores.get(tier, 50.0)

        # Bonus for specific high-authority domains
        if 'sec.gov' in domain:
            base_score = 100.0
        elif 'federalreserve.gov' in domain:
            base_score = 98.0
        elif domain in ['bloomberg.com', 'reuters.com']:
            base_score = 88.0

        # Penalty for low credibility indicators
        if any(indicator in domain for indicator in self.LOW_CREDIBILITY_INDICATORS):
            base_score = min(base_score, 35.0)

        return base_score

    def _evaluate_recency(self, publication_date: Optional[str]) -> float:
        """Evaluate information recency (0-100)"""
        if not publication_date:
            return 50.0  # Unknown date

        try:
            pub_date = datetime.fromisoformat(publication_date.replace('Z', '+00:00'))
            age = datetime.now() - pub_date

            # Financial data has stricter recency requirements
            if age < timedelta(days=30):  # < 1 month
                return 100.0
            elif age < timedelta(days=90):  # < 3 months
                return 90.0
            elif age < timedelta(days=180):  # < 6 months
                return 75.0
            elif age < timedelta(days=365):  # < 1 year
                return 60.0
            elif age < timedelta(days=730):  # < 2 years
                return 45.0
            else:
                return 30.0

        except Exception:
            return 50.0

    def _evaluate_expertise(
        self,
        domain: str,
        title: str,
        author: Optional[str],
        tier: int
    ) -> float:
        """Evaluate source expertise (0-100)"""
        base_score = 50.0

        # Tier-based expertise
        tier_expertise = {1: 40, 2: 30, 3: 20, 4: 10}
        base_score += tier_expertise.get(tier, 0)

        # SEC filings are authoritative
        if 'sec.gov' in domain or '10-K' in title or '10-Q' in title:
            base_score += 20

        # Earnings/financial content
        if any(term in title.lower() for term in ['earnings', 'quarterly', 'annual report', 'financial results']):
            base_score += 10

        # Analyst/research content
        if any(term in title.lower() for term in ['analysis', 'research', 'rating', 'estimate']):
            base_score += 5

        # Author credentials
        if author:
            if any(title in author.lower() for title in ['cfa', 'cpa', 'phd', 'analyst', 'economist']):
                base_score += 10

        return min(base_score, 100.0)

    def _evaluate_bias(
        self,
        domain: str,
        title: str,
        content: Optional[str],
        tier: int
    ) -> float:
        """Evaluate potential bias (0-100, higher = more neutral)"""
        base_score = 70.0

        # Tier-based bias (regulatory sources are most neutral)
        tier_bias = {1: 20, 2: 10, 3: 0, 4: -10}
        base_score += tier_bias.get(tier, 0)

        # Check for sensationalism in title
        sensational_indicators = [
            '!', 'shocking', 'crash', 'explode', 'moon', 'rocket',
            'guaranteed', 'secret', 'you won\'t believe', 'millionaire'
        ]
        title_lower = title.lower()
        if any(indicator in title_lower for indicator in sensational_indicators):
            base_score -= 25

        # Promotional content indicators
        promotional = ['buy now', 'limited time', 'act fast', 'don\'t miss']
        if any(promo in title_lower for promo in promotional):
            base_score -= 30

        # Seeking Alpha, retail sources may have bias
        if 'seekingalpha' in domain or 'fool.com' in domain:
            base_score -= 10

        # Check for balance in content
        if content:
            balanced_indicators = ['however', 'risk', 'downside', 'bear case', 'concerns']
            if any(indicator in content.lower() for indicator in balanced_indicators):
                base_score += 10

        return min(max(base_score, 0), 100.0)

    def _identify_factors(
        self,
        domain: str,
        tier: int,
        domain_score: float,
        recency_score: float,
        expertise_score: float,
        bias_score: float
    ) -> Dict[str, str]:
        """Identify key credibility factors"""
        factors = {}

        # Tier factor
        tier_names = {
            1: "Tier 1: Primary/Regulatory source",
            2: "Tier 2: Financial data provider",
            3: "Tier 3: Financial news/research",
            4: "Tier 4: General business source"
        }
        factors['tier'] = tier_names.get(tier, "Unknown tier")

        if domain_score >= 90:
            factors['domain'] = "Highest authority financial source"
        elif domain_score >= 75:
            factors['domain'] = "High authority financial source"
        elif domain_score <= 45:
            factors['domain'] = "Low authority - verify with primary sources"

        if recency_score >= 90:
            factors['recency'] = "Very recent financial data"
        elif recency_score <= 50:
            factors['recency'] = "Dated information - verify currency"

        if expertise_score >= 80:
            factors['expertise'] = "Expert financial source"
        elif expertise_score <= 50:
            factors['expertise'] = "Limited financial expertise"

        if bias_score >= 80:
            factors['bias'] = "Objective/neutral perspective"
        elif bias_score <= 50:
            factors['bias'] = "Potential bias detected"

        return factors

    def _generate_recommendation(self, overall_score: float, tier: int) -> str:
        """Generate trust recommendation"""
        # Tier 1 sources get higher trust
        if tier == 1 and overall_score >= 70:
            return "high_trust"
        elif tier == 1:
            return "moderate_trust"

        # Other tiers
        if overall_score >= 80:
            return "high_trust"
        elif overall_score >= 65:
            return "moderate_trust"
        elif overall_score >= 50:
            return "low_trust"
        else:
            return "verify"


# Example usage
if __name__ == '__main__':
    evaluator = FinancialSourceEvaluator()

    # Test sources
    test_sources = [
        {
            'url': 'https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193',
            'title': 'Apple Inc. 10-K Annual Report 2024',
            'publication_date': '2024-11-01'
        },
        {
            'url': 'https://www.bloomberg.com/news/articles/2024-10-30/apple-earnings',
            'title': 'Apple Reports Record Q4 Revenue',
            'publication_date': '2024-10-30'
        },
        {
            'url': 'https://seekingalpha.com/article/apple-buy-now',
            'title': 'Apple: BUY NOW Before It Explodes!',
            'publication_date': '2024-10-15'
        },
        {
            'url': 'https://ir.apple.com/investor-relations',
            'title': 'Apple Investor Relations - Q4 2024 Earnings Call',
            'publication_date': '2024-10-31'
        }
    ]

    for source in test_sources:
        score = evaluator.evaluate_source(**source)
        print(f"\nSource: {source['title'][:50]}...")
        print(f"URL: {source['url'][:60]}...")
        print(f"Tier: {score.tier}")
        print(f"Overall Score: {score.overall_score}/100")
        print(f"Recommendation: {score.recommendation}")
        print(f"Factors: {score.factors}")

#!/usr/bin/env python3
"""
Financial Report Validation Script
Ensures financial research reports meet quality standards before delivery
"""

import argparse
import re
import sys
from pathlib import Path
from typing import List, Tuple, Dict


class FinancialReportValidator:
    """Validates financial research report quality"""

    def __init__(self, report_path: Path):
        self.report_path = report_path
        self.content = self._read_report()
        self.errors: List[str] = []
        self.warnings: List[str] = []

    def _read_report(self) -> str:
        """Read report file"""
        try:
            with open(self.report_path, 'r', encoding='utf-8') as f:
                return f.read()
        except Exception as e:
            print(f"ERROR: Cannot read report: {e}")
            sys.exit(1)

    def validate(self) -> bool:
        """Run all validation checks"""
        print(f"\n{'='*60}")
        print(f"VALIDATING FINANCIAL REPORT: {self.report_path.name}")
        print(f"{'='*60}\n")

        checks = [
            ("Executive Summary", self._check_executive_summary),
            ("Required Sections", self._check_required_sections),
            ("Financial Sections", self._check_financial_sections),
            ("Citations", self._check_citations),
            ("Bibliography", self._check_bibliography),
            ("Placeholder Text", self._check_placeholders),
            ("Content Truncation", self._check_content_truncation),
            ("Word Count", self._check_word_count),
            ("Source Count", self._check_source_count),
            ("Financial Data", self._check_financial_data),
            ("Broken Links", self._check_broken_references),
        ]

        for check_name, check_func in checks:
            print(f"Checking: {check_name}...", end=" ")
            passed = check_func()
            if passed:
                print("PASS")
            else:
                print("FAIL")

        self._print_summary()

        return len(self.errors) == 0

    def _check_executive_summary(self) -> bool:
        """Check executive summary exists and is under 250 words"""
        pattern = r'## Executive Summary(.*?)(?=##|\Z)'
        match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)

        if not match:
            self.errors.append("Missing 'Executive Summary' section")
            return False

        summary = match.group(1).strip()
        word_count = len(summary.split())

        if word_count > 300:
            self.warnings.append(f"Executive summary too long: {word_count} words (should be <=250)")

        if word_count < 50:
            self.warnings.append(f"Executive summary too short: {word_count} words (should be >=50)")

        # Check for investment thesis
        if 'thesis' not in summary.lower() and 'recommendation' not in summary.lower():
            self.warnings.append("Executive summary missing clear investment thesis/recommendation")

        return True

    def _check_required_sections(self) -> bool:
        """Check all required sections are present"""
        required = [
            "Executive Summary",
            "Overview",  # Company/Topic Overview
            "Financial Analysis",
            "Valuation",
            "Competitive",  # Competitive Position
            "Risk",  # Risk Factors
            "Recommendation",
            "Bibliography",
            "Methodology"
        ]

        missing = []
        for section in required:
            if not re.search(rf'##.*{section}', self.content, re.IGNORECASE):
                missing.append(section)

        if missing:
            self.errors.append(f"Missing required sections: {', '.join(missing)}")
            return False

        return True

    def _check_financial_sections(self) -> bool:
        """Check financial-specific sections"""
        recommended = [
            "Revenue",
            "Margin",
            "Cash Flow",
            "Balance Sheet",
            "Bull Case",
            "Bear Case"
        ]

        missing_recommended = []
        for section in recommended:
            if section.lower() not in self.content.lower():
                missing_recommended.append(section)

        if len(missing_recommended) > 3:
            self.warnings.append(f"Missing recommended financial content: {', '.join(missing_recommended)}")

        return True

    def _check_citations(self) -> bool:
        """Check citation format and presence"""
        citations = re.findall(r'\[(\d+)\]', self.content)

        if not citations:
            self.errors.append("No citations found in report")
            return False

        unique_citations = set(citations)

        if len(unique_citations) < 10:
            self.warnings.append(f"Only {len(unique_citations)} unique sources cited (recommended: >=10)")

        # Check for consecutive citation numbers
        citation_nums = sorted([int(c) for c in unique_citations])
        if citation_nums:
            max_citation = max(citation_nums)
            expected = set(range(1, max_citation + 1))
            missing = expected - set(citation_nums)

            if missing:
                self.warnings.append(f"Non-consecutive citation numbers, missing: {sorted(missing)}")

        return True

    def _check_bibliography(self) -> bool:
        """Check bibliography exists, matches citations, and has no truncation placeholders"""
        pattern = r'## Bibliography(.*?)(?=##|\Z)'
        match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)

        if not match:
            self.errors.append("Missing 'Bibliography' section")
            return False

        bib_section = match.group(1)

        # Check for truncation placeholders
        truncation_patterns = [
            (r'\[\d+-\d+\]', 'Citation range (e.g., [8-75])'),
            (r'Additional.*citations', 'Phrase "Additional citations"'),
            (r'would be included', 'Phrase "would be included"'),
            (r'\[\.\.\.continue', 'Pattern "[...continue"'),
            (r'\[Continue with', 'Pattern "[Continue with"'),
            (r'etc\.(?!\w)', 'Standalone "etc."'),
        ]

        for pattern_re, description in truncation_patterns:
            if re.search(pattern_re, bib_section, re.IGNORECASE):
                self.errors.append(f"CRITICAL: Bibliography contains truncation placeholder: {description}")
                return False

        # Count bibliography entries
        bib_entries = re.findall(r'^\[(\d+)\]', bib_section, re.MULTILINE)

        if not bib_entries:
            self.errors.append("Bibliography has no entries")
            return False

        # Check for tier organization (recommended for financial)
        if 'Tier 1' not in bib_section and 'tier 1' not in bib_section.lower():
            self.warnings.append("Bibliography not organized by source tier (recommended for financial reports)")

        # Find citations in text
        text_citations = set(re.findall(r'\[(\d+)\]', self.content))
        bib_citations = set(bib_entries)

        # Check all citations have bibliography entries
        missing_in_bib = text_citations - bib_citations
        if missing_in_bib:
            self.errors.append(f"Citations missing from bibliography: {sorted(missing_in_bib)}")
            return False

        return True

    def _check_placeholders(self) -> bool:
        """Check for placeholder text that shouldn't be in final report"""
        placeholders = [
            'TBD', 'TODO', 'FIXME', 'XXX',
            '[citation needed]', '[needs citation]',
            '[placeholder]', '[TODO]', '[TBD]',
            '$X.XB', 'XX.X%', '[N]'  # Template placeholders
        ]

        found_placeholders = []
        for placeholder in placeholders:
            if placeholder in self.content:
                found_placeholders.append(placeholder)

        if found_placeholders:
            self.errors.append(f"Found placeholder text: {', '.join(found_placeholders)}")
            return False

        return True

    def _check_content_truncation(self) -> bool:
        """Check for content truncation patterns"""
        truncation_patterns = [
            (r'Content continues', 'Phrase "Content continues"'),
            (r'Due to length', 'Phrase "Due to length"'),
            (r'would continue', 'Phrase "would continue"'),
            (r'\[Sections \d+-\d+', 'Pattern "[Sections X-Y"'),
            (r'Additional sections', 'Phrase "Additional sections"'),
        ]

        for pattern_re, description in truncation_patterns:
            if re.search(pattern_re, self.content, re.IGNORECASE):
                self.errors.append(f"CRITICAL: Content truncation detected: {description}")
                return False

        return True

    def _check_word_count(self) -> bool:
        """Check overall report length"""
        word_count = len(self.content.split())

        if word_count < 1000:
            self.warnings.append(f"Report is very short: {word_count} words (financial reports should be 2000+)")

        print(f"  (Word count: {word_count})")
        return True

    def _check_source_count(self) -> bool:
        """Check minimum source count"""
        pattern = r'## Bibliography(.*?)(?=##|\Z)'
        match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)

        if not match:
            return True  # Already caught in bibliography check

        bib_section = match.group(1)
        bib_entries = re.findall(r'^\[(\d+)\]', bib_section, re.MULTILINE)

        source_count = len(set(bib_entries))

        if source_count < 10:
            self.warnings.append(f"Only {source_count} sources (recommended: >=10 for financial reports)")

        # Check for Tier 1 sources (regulatory/primary)
        tier1_indicators = ['sec.gov', 'SEC', '10-K', '10-Q', 'EDGAR', 'investor relations', 'IR']
        tier1_count = sum(1 for indicator in tier1_indicators if indicator in bib_section)

        if tier1_count < 2:
            self.warnings.append("Limited Tier 1 (regulatory/primary) sources - consider adding SEC filings")

        return True

    def _check_financial_data(self) -> bool:
        """Check for presence of key financial data"""
        required_metrics = [
            (r'\$[\d,.]+[BMK]', 'Dollar amounts'),
            (r'\d+\.?\d*%', 'Percentages'),
            (r'FY\d{4}|Q[1-4]\s*\d{4}', 'Fiscal periods'),
        ]

        for pattern, description in required_metrics:
            if not re.search(pattern, self.content):
                self.warnings.append(f"Missing financial data: {description}")

        # Check for financial tables
        if '|' not in self.content:
            self.warnings.append("No data tables found (recommended for financial reports)")

        return True

    def _check_broken_references(self) -> bool:
        """Check for broken internal references"""
        internal_links = re.findall(r'\[.*?\]\((\.\/.*?)\)', self.content)

        broken = []
        for link in internal_links:
            link_path = link.split('#')[0]
            full_path = self.report_path.parent / link_path

            if not full_path.exists():
                broken.append(link)

        if broken:
            self.errors.append(f"Broken internal links: {', '.join(broken)}")
            return False

        return True

    def _print_summary(self):
        """Print validation summary"""
        print(f"\n{'='*60}")
        print(f"VALIDATION SUMMARY")
        print(f"{'='*60}\n")

        if self.errors:
            print(f"ERRORS ({len(self.errors)}):")
            for error in self.errors:
                print(f"   - {error}")
            print()

        if self.warnings:
            print(f"WARNINGS ({len(self.warnings)}):")
            for warning in self.warnings:
                print(f"   - {warning}")
            print()

        if not self.errors and not self.warnings:
            print("ALL CHECKS PASSED - Report meets financial quality standards!\n")
        elif not self.errors:
            print("VALIDATION PASSED (with warnings)\n")
        else:
            print("VALIDATION FAILED - Please fix errors before delivery\n")


def main():
    parser = argparse.ArgumentParser(
        description="Validate financial research report quality",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python validate_report.py --report report.md
  python validate_report.py -r ~/research/financial_report_20251104.md
        """
    )

    parser.add_argument(
        '--report', '-r',
        type=str,
        required=True,
        help='Path to financial research report markdown file'
    )

    args = parser.parse_args()

    report_path = Path(args.report)

    if not report_path.exists():
        print(f"ERROR: Report file not found: {report_path}")
        sys.exit(1)

    validator = FinancialReportValidator(report_path)
    passed = validator.validate()

    sys.exit(0 if passed else 1)


if __name__ == '__main__':
    main()