TradeAssist 0.6.7__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,4 @@
+# TradeAssist Gemini-SEC Analyzer Package
+from app.config import VERSION
+
+__version__ = VERSION

app/backend/__init__.py

@@ -0,0 +1,2 @@
+# Backend logic for TradeAssist Gemini-SEC Analyzer
+# Keeping this package 100% pure Python/Pydantic/Gemini-SDK, free of PyQt6 GUI dependencies.

app/backend/analyzer.py

@@ -0,0 +1,324 @@
+import yfinance as yf
+from typing import Type, Optional, Union
+from pydantic import BaseModel
+from app.backend.sec_client import SECClient
+from app.backend.gemini_client import GeminiClient
+from app.backend.data_models import StockAnalysis, CustomAnalysisResult
+from app.config import get_logger
+from app.settings_manager import SettingsManager
+from datetime import datetime, timedelta
+import time
+
+logger = get_logger("analyzer")
+
+class GeminiSecAnalyzer:
+    """
+    Coordinating Engine that integrates SECClient and GeminiClient.
+    Provides decoupled analytical routines suitable for both the PyQt GUI
+    and integration into an automated trading bot.
+    """
+    def __init__(self, gemini_api_key: Optional[str] = None):
+        self.sec_client = SECClient()
+        self.gemini_client = GeminiClient(api_key=gemini_api_key)
+
+    def gather_recent_news(
+        self,
+        ticker_symbol: str,
+        days_back: int = 7,
+        limit: int = 10
+    ) -> str:
+        """
+        Gathers recent news for a ticker symbol using Finnhub (if API key is available)
+        or falls back to yfinance news feed.
+        Applies date filtering and article limits.
+        """
+        from app.config import FINNHUB_API_KEY
+
+        news_headlines = []
+        used_source = "None"
+
+        # 1. Try Finnhub News
+        if FINNHUB_API_KEY:
+            try:
+                import finnhub
+                logger.info(f"Attempting to fetch news from Finnhub for {ticker_symbol}")
+                finnhub_client = finnhub.Client(api_key=FINNHUB_API_KEY)
+                
+                to_date = datetime.now()
+                from_date = to_date - timedelta(days=days_back)
+                
+                from_str = from_date.strftime("%Y-%m-%d")
+                to_str = to_date.strftime("%Y-%m-%d")
+                
+                raw_news = finnhub_client.company_news(ticker_symbol.upper(), _from=from_str, to=to_str)
+                if raw_news:
+                    # Sort by datetime descending
+                    raw_news = sorted(raw_news, key=lambda x: x.get('datetime', 0), reverse=True)
+                    raw_news = raw_news[:limit]
+                    for article in raw_news:
+                        headline = article.get('headline', '').strip()
+                        source = article.get('source', 'Finnhub')
+                        summary = article.get('summary', '').strip()
+                        if headline:
+                            news_item = f"[{source}] {headline}"
+                            if summary:
+                                if len(summary) > 200:
+                                    summary = summary[:200] + "..."
+                                news_item += f"\n   Summary: {summary}"
+                            news_headlines.append(news_item)
+                    used_source = "Finnhub"
+            except Exception as e:
+                logger.error(f"Error fetching Finnhub news for {ticker_symbol}, falling back to yfinance: {e}")
+
+        # 2. Fallback to yfinance if Finnhub failed or wasn't configured
+        if not news_headlines:
+            try:
+                logger.info(f"Fetching news from yfinance for {ticker_symbol}")
+                ticker = yf.Ticker(ticker_symbol)
+                yf_news = ticker.news
+                if yf_news:
+                    now_ts = time.time()
+                    from_ts = now_ts - (days_back * 86400)
+                    
+                    filtered_yf_news = []
+                    for article in yf_news:
+                        content = article.get('content', {})
+                        pub_time_val = article.get('providerPublishTime', content.get('pubDate', 0))
+                        
+                        ts = 0
+                        if isinstance(pub_time_val, (int, float)):
+                            ts = pub_time_val
+                        elif isinstance(pub_time_val, str):
+                            try:
+                                ts = datetime.fromisoformat(pub_time_val.replace('Z', '+00:00')).timestamp()
+                            except Exception:
+                                pass
+                        
+                        if ts == 0 or ts >= from_ts:
+                            filtered_yf_news.append(article)
+
+                    # Limit count
+                    filtered_yf_news = filtered_yf_news[:limit]
+
+                    for article in filtered_yf_news:
+                        content = article.get('content', {})
+                        headline = content.get('title', article.get('title', '')).strip()
+                        publisher = content.get('publisher', article.get('publisher', 'YF'))
+                        summary = content.get('summary', article.get('summary', '')).strip()
+                        if not headline:
+                            headline = article.get('title', '').strip()
+                        if headline:
+                            news_item = f"[{publisher}] {headline}"
+                            if summary:
+                                if len(summary) > 200:
+                                    summary = summary[:200] + "..."
+                                news_item += f"\n   Summary: {summary}"
+                            news_headlines.append(news_item)
+                    used_source = "yfinance"
+            except Exception as e:
+                logger.error(f"Error fetching yfinance news fallback for {ticker_symbol}: {e}")
+
+        formatted_news = "\n\n".join(news_headlines) if news_headlines else "No recent news found."
+        logger.info(f"Gathered {len(news_headlines)} news items using {used_source}")
+        return formatted_news
+
+    def analyze_ticker_comprehensive(
+        self,
+        ticker_symbol: str,
+        model: str = "gemini-3.8-flash",
+        days_back: Optional[int] = None,
+        limit: Optional[int] = None
+    ) -> StockAnalysis:
+        """
+        Gathers general news, recent filings RSS summary, historical share count,
+        and financial statements for a ticker, and feeds them into the standard
+        comprehensive StockAnalysis model. Highly suitable for periodic bot scanning.
+        """
+        logger.info(f"Starting comprehensive analyzer for {ticker_symbol}")
+        ticker = yf.Ticker(ticker_symbol)
+
+        # Load settings for news limits if not passed explicitly
+        settings = SettingsManager.load_settings()
+        if days_back is None:
+            days_back = settings.get("news_scan_days", 7)
+        if limit is None:
+            limit = settings.get("news_limit", 10)
+
+        # 1. Gather recent news (Using customizable Finnhub/yfinance news feed)
+        formatted_news = self.gather_recent_news(ticker_symbol, days_back=days_back, limit=limit)
+
+        # 2. Gather SEC filings list (using RSS / metadata endpoint)
+        recent_filings_list = self.sec_client.get_recent_filings(ticker_symbol, count=10)
+        formatted_filings = []
+        for f in recent_filings_list:
+            formatted_filings.append(
+                f"- [Filed: {f['filing_date']}] Form {f['form']} | {f['description']} | Link: {f['url']}"
+            )
+        sec_filings_summary = "\n".join(formatted_filings) if formatted_filings else "No recent filings found."
+
+        # 3. Gather Fundamentals (Dilution & Cash Burn)
+        try:
+            shares_df = ticker.get_shares_full(start="2024-01-01")
+            shares_data = shares_df.tail(10).to_string() if shares_df is not None else "No share history available."
+        except Exception:
+            shares_data = "No share history available."
+
+        try:
+            balance_sheet = ticker.balance_sheet.to_string()
+            financials = ticker.financials.to_string()
+        except Exception:
+            balance_sheet = "Financial statement data unavailable."
+            financials = "Income statement data unavailable."
+
+        # 4. Build prompt
+        prompt = f"""
+        Analyze the following financial and news data for the ticker '{ticker_symbol.upper()}'.
+
+        1. RECENT NEWS HEADLINES:
+        {formatted_news}
+
+        1b. RECENT SEC FILINGS (LAST SEVERAL WEEKS):
+        {sec_filings_summary}
+
+        2. HISTORICAL SHARE COUNT DATA (Look for increasing share count indicating dilution):
+        {shares_data}
+
+        3. BALANCE SHEET & FINANCIAL DATA (Look for Cash & Cash Equivalents vs Net Income/Operating Expenses to evaluate cash burn):
+        {balance_sheet[:4000]} 
+        {financials[:4000]}
+        """
+
+        # 5. Call structured generation
+        result = self.gemini_client.generate_structured_analysis(
+            prompt=prompt,
+            response_schema=StockAnalysis,
+            model=model,
+            temperature=0.0
+        )
+        return result
+
+    def analyze_specific_filings(
+        self,
+        ticker_symbol: str,
+        filings: list,
+        custom_prompt: str,
+        response_schema: Optional[Type[BaseModel]] = None,
+        model: str = "gemini-3.8-flash",
+        temperature: float = 0.1,
+        max_chars: int = 150000,
+        include_news: Optional[bool] = None,
+        days_back: Optional[int] = None,
+        limit: Optional[int] = None
+    ) -> Union[BaseModel, str]:
+        """
+        Downloads multiple specific filings, extracts their text content, 
+        concatenates them with distinct structural separators and metadata,
+        and sends the combined text to Gemini along with a custom analytical prompt.
+        Supports structured JSON output (if response_schema is provided) or plaintext markdown.
+        Optionally includes recent news feed context for the ticker.
+        """
+        logger.info(f"Analyzing {len(filings)} filings for {ticker_symbol}")
+
+        # Load default settings if not passed explicitly
+        settings = SettingsManager.load_settings()
+        if include_news is None:
+            include_news = settings.get("include_news_custom", False)
+        if days_back is None:
+            days_back = settings.get("news_scan_days", 7)
+        if limit is None:
+            limit = settings.get("news_limit", 10)
+
+        news_context = ""
+        if include_news:
+            logger.info(f"Fetching news context to couple with custom prompt for {ticker_symbol}")
+            news_data = self.gather_recent_news(ticker_symbol, days_back=days_back, limit=limit)
+            news_context = f"""
+=== RECENT NEWS ({days_back} days, limit {limit}) ===
+{news_data}
+==================================================
+"""
+        
+        combined_texts = []
+        for idx, filing in enumerate(filings, start=1):
+            url = filing["url"]
+            form = filing["form"]
+            date = filing["filing_date"]
+            desc = filing.get("description", "[No Description]")
+            
+            # Fetch text of the specific filing using specified max_chars limit
+            filing_text = self.sec_client.fetch_filing_text(url, max_chars=max_chars)
+            if not filing_text:
+                logger.warning(f"Could not retrieve text for filing Form {form} from {url}")
+                continue
+                
+            combined_texts.append(f"""
+=== FILING DOCUMENT {idx} OF {len(filings)} ===
+Form Type: {form}
+Filing Date: {date}
+Description: {desc}
+SEC Document URL: {url}
+
+--- START OF FILING TEXT ---
+{filing_text}
+--- END OF FILING TEXT ---
+""")
+
+        if not combined_texts:
+            raise ValueError("Could not retrieve or parse filing text from any of the selected filings.")
+
+        # Build the combined prompt
+        full_prompt = f"""
+You are an expert financial analyst. Please execute the custom instruction below on the provided SEC filing document(s) and recent news for ticker '{ticker_symbol.upper()}'.
+
+{news_context}
+
+CUSTOM ANALYSIS INSTRUCTION:
+{custom_prompt}
+
+SEC FILING DOCUMENTS PROVIDED:
+{"".join(combined_texts)}
+"""
+
+        # Request Gemini analysis (either structured or unstructured)
+        if response_schema:
+            return self.gemini_client.generate_structured_analysis(
+                prompt=full_prompt,
+                response_schema=response_schema,
+                model=model,
+                temperature=temperature
+            )
+        else:
+            return self.gemini_client.generate_text_analysis(
+                prompt=full_prompt,
+                model=model,
+                temperature=temperature
+            )
+
+    def analyze_specific_filing(
+        self,
+        ticker_symbol: str,
+        filing_url: str,
+        custom_prompt: str,
+        response_schema: Optional[Type[BaseModel]] = None,
+        model: str = "gemini-3.8-flash",
+        temperature: float = 0.1
+    ) -> Union[BaseModel, str]:
+        """
+        Downloads a specific filing (10-K, 10-Q, 8-K), extracts its text content, 
+        and sends it to Gemini along with a custom analytical prompt.
+        Supports structured JSON output (if response_schema is provided) or plaintext markdown.
+        """
+        # Backward compatibility wrapper
+        filings = [{
+            "url": filing_url,
+            "form": "Unknown",
+            "filing_date": "Unknown"
+        }]
+        return self.analyze_specific_filings(
+            ticker_symbol=ticker_symbol,
+            filings=filings,
+            custom_prompt=custom_prompt,
+            response_schema=response_schema,
+            model=model,
+            temperature=temperature
+        )

app/backend/data_models.py

@@ -0,0 +1,24 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Any, Optional
+
+class StockAnalysis(BaseModel):
+    news_score: int = Field(description="Score from 0 to 10")
+    news_explanation: str = Field(description="Explanation")
+    headline_count_fed: int = Field(description="Count")
+    SEC_score: int = Field(description="Score from 0 to 10")
+    SEC_explanation: str = Field(description="Explanation")
+    dilution_score: int = Field(description="Score")
+    dilution_explanation: str = Field(description="Explanation")
+    cash_burn_score: int = Field(description="Score")
+    cash_burn_explanation: str = Field(description="Explanation")
+
+class KeyValueMetric(BaseModel):
+    key: str = Field(description="The name of the metric")
+    value: str = Field(description="The value")
+    context: str = Field(description="Context")
+
+class CustomAnalysisResult(BaseModel):
+    executive_summary: str = Field(description="Overview")
+    sentiment_score: int = Field(description="Sentiment 0-10")
+    key_insights: List[str] = Field(description="Bullet points")
+    metrics_table: List[KeyValueMetric] = Field(description="Structured key-values")

app/backend/gemini_client.py

@@ -0,0 +1,176 @@
+from google import genai
+from google.genai import types
+from google.genai.errors import APIError
+import time
+from typing import Type, Optional, Union
+from pydantic import BaseModel
+from app.config import GEMINI_API_KEY, get_logger
+
+logger = get_logger("gemini_client")
+
+class TextAnalysisResult(str):
+    """
+    Subclass of str that holds metadata about token usage and model.
+    """
+    def __new__(cls, content, *args, **kwargs):
+        return super().__new__(cls, content)
+    
+    def __init__(self, content, model="", prompt_tokens=0, candidates_tokens=0, total_tokens=0):
+        super().__init__()
+        self.model = model
+        self.prompt_tokens = prompt_tokens
+        self.candidates_tokens = candidates_tokens
+        self.total_tokens = total_tokens
+
+class GeminiClient:
+    """
+    Pure Python Gemini API Client wrapper.
+    Responsible for initializing the Google GenAI SDK, formatting contents,
+    and handling rate limits/service unavailability with exponential backoff.
+    """
+    def __init__(self, api_key: Optional[str] = None):
+        key = api_key or GEMINI_API_KEY
+        self.client = None
+        if not key:
+            logger.warning("No Gemini API key supplied. Ensure GEMINI_API_KEY is in your environment.")
+        else:
+            # Initialize client
+            self.client = genai.Client(api_key=key)
+
+    def generate_structured_analysis(
+        self,
+        prompt: str,
+        response_schema: Type[BaseModel],
+        model: str = "gemini-3.8-flash",
+        temperature: float = 0.0,
+        max_retries: int = 5,
+        initial_delay: float = 3.0
+    ) -> BaseModel:
+        """
+        Sends a prompt to Gemini requesting a structured output conforming to response_schema.
+        Implements exponential backoff to handle 429 (Rate Limits) and 503 (Overloaded) errors.
+        """
+        if not self.client:
+            raise ValueError(
+                "Gemini API Key is not set! Please go to File -> Settings & API Keys... "
+                "to configure your Gemini API Key before running analyses."
+            )
+
+        for attempt in range(max_retries):
+            try:
+                logger.info(f"Sending prompt to Gemini using model {model} (Attempt {attempt+1}/{max_retries})")
+                
+                response = self.client.models.generate_content(
+                    model=model,
+                    contents=prompt,
+                    config=types.GenerateContentConfig(
+                        response_mime_type="application/json",
+                        response_schema=response_schema,
+                        temperature=temperature
+                    )
+                )
+                
+                # Use Pydantic to validate and parse the JSON string returned by Gemini
+                parsed_response = response_schema.model_validate_json(response.text)
+                
+                # Get usage metadata or estimate
+                usage = getattr(response, 'usage_metadata', None)
+                prompt_tokens = getattr(usage, 'prompt_token_count', 0) if usage else 0
+                candidates_tokens = getattr(usage, 'candidates_token_count', 0) if usage else 0
+                total_tokens = getattr(usage, 'total_token_count', 0) if usage else 0
+                
+                if not prompt_tokens:
+                    prompt_tokens = int(len(prompt) / 4)
+                if not candidates_tokens:
+                    candidates_tokens = int(len(response.text) / 4)
+                if not total_tokens:
+                    total_tokens = prompt_tokens + candidates_tokens
+                
+                # Attach metadata safely
+                object.__setattr__(parsed_response, 'model', model)
+                object.__setattr__(parsed_response, 'prompt_tokens', prompt_tokens)
+                object.__setattr__(parsed_response, 'candidates_tokens', candidates_tokens)
+                object.__setattr__(parsed_response, 'total_tokens', total_tokens)
+                
+                return parsed_response
+
+            except APIError as e:
+                if e.code in [429, 503] and attempt < max_retries - 1:
+                    delay = initial_delay * (2 ** attempt)
+                    logger.warning(f"Gemini API returned error {e.code} ({e.message}). Retrying in {delay}s...")
+                    time.sleep(delay)
+                else:
+                    logger.error(f"Gemini API non-retryable error: {e}")
+                    raise e
+            except Exception as e:
+                logger.error(f"Unexpected error in Gemini generation: {e}")
+                raise e
+
+        raise Exception(f"Gemini API generation failed after {max_retries} attempts.")
+
+    def generate_text_analysis(
+        self,
+        prompt: str,
+        model: str = "gemini-3.8-flash",
+        temperature: float = 0.2,
+        max_retries: int = 5,
+        initial_delay: float = 3.0
+    ) -> str:
+        """
+        Sends a prompt to Gemini requesting a standard unstructured Markdown or text response.
+        Useful for general, open-ended research prompts.
+        """
+        if not self.client:
+            raise ValueError(
+                "Gemini API Key is not set! Please go to File -> Settings & API Keys... "
+                "to configure your Gemini API Key before running analyses."
+            )
+
+        for attempt in range(max_retries):
+            try:
+                logger.info(f"Sending text prompt to Gemini using model {model} (Attempt {attempt+1}/{max_retries})")
+                
+                response = self.client.models.generate_content(
+                    model=model,
+                    contents=prompt,
+                    config=types.GenerateContentConfig(
+                        temperature=temperature
+                    )
+                )
+                
+                response_text = response.text
+                
+                # Get usage metadata or estimate
+                usage = getattr(response, 'usage_metadata', None)
+                prompt_tokens = getattr(usage, 'prompt_token_count', 0) if usage else 0
+                candidates_tokens = getattr(usage, 'candidates_token_count', 0) if usage else 0
+                total_tokens = getattr(usage, 'total_token_count', 0) if usage else 0
+                
+                if not prompt_tokens:
+                    prompt_tokens = int(len(prompt) / 4)
+                if not candidates_tokens:
+                    candidates_tokens = int(len(response_text) / 4)
+                if not total_tokens:
+                    total_tokens = prompt_tokens + candidates_tokens
+                
+                return TextAnalysisResult(
+                    response_text,
+                    model=model,
+                    prompt_tokens=prompt_tokens,
+                    candidates_tokens=candidates_tokens,
+                    total_tokens=total_tokens
+                )
+
+            except APIError as e:
+                if e.code in [429, 503] and attempt < max_retries - 1:
+                    delay = initial_delay * (2 ** attempt)
+                    logger.warning(f"Gemini API returned error {e.code} ({e.message}). Retrying in {delay}s...")
+                    time.sleep(delay)
+                else:
+                    logger.error(f"Gemini API non-retryable error: {e}")
+                    raise e
+            except Exception as e:
+                logger.error(f"Unexpected error in Gemini generation: {e}")
+                raise e
+
+        raise Exception(f"Gemini API generation failed after {max_retries} attempts.")

app/backend/sec_client.py

@@ -0,0 +1,126 @@
+import warnings
+import requests
+from bs4 import BeautifulSoup, XMLParsedAsHTMLWarning
+from app.config import SEC_HEADERS, get_logger
+
+# Suppress BS4 XML-parsed-as-HTML warning for SEC XML-format filings
+warnings.filterwarnings("ignore", category=XMLParsedAsHTMLWarning)
+
+logger = get_logger("sec_client")
+
+class SECClient:
+    """
+    Pure Python SEC EDGAR Client.
+    Handles mapping tickers to CIKs, listing recent company filings,
+    and fetching/parsing the text content of specific filing documents.
+    """
+    def __init__(self):
+        self.headers = SEC_HEADERS
+
+    def get_cik(self, ticker: str) -> str:
+        """
+        Maps a stock ticker (e.g. 'AAPL') to its zero-padded 10-digit CIK.
+        """
+        ticker_clean = ticker.strip().upper()
+        url = "https://www.sec.gov/files/company_tickers.json"
+        try:
+            response = requests.get(url, headers=self.headers, timeout=10)
+            if response.status_code != 200:
+                logger.error(f"Failed to fetch SEC mapping list. Status: {response.status_code}")
+                return None
+            
+            data = response.json()
+            for entry in data.values():
+                if entry.get('ticker') == ticker_clean:
+                    return str(entry.get('cik_str')).zfill(10)
+            
+            logger.warning(f"Ticker '{ticker_clean}' not found in SEC company_tickers.json")
+            return None
+        except Exception as e:
+            logger.error(f"Error mapping CIK for {ticker_clean}: {e}")
+            return None
+
+    def get_recent_filings(self, ticker: str, count: int = 20) -> list:
+        """
+        Fetches the recent filings list for a given ticker from the SEC Submissions API.
+        Returns a list of structured dictionaries containing filing metadata.
+        """
+        cik = self.get_cik(ticker)
+        if not cik:
+            return []
+
+        url = f"https://data.sec.gov/submissions/CIK{cik}.json"
+        try:
+            response = requests.get(url, headers=self.headers, timeout=10)
+            if response.status_code != 200:
+                logger.error(f"SEC Submissions API returned status {response.status_code} for CIK {cik}")
+                return []
+
+            data = response.json()
+            filings_raw = data.get('filings', {}).get('recent', {})
+            if not filings_raw:
+                return []
+
+            # Structure the lists into individual records
+            filings = []
+            num_filings = len(filings_raw.get('accessionNumber', []))
+            
+            for i in range(min(num_filings, count)):
+                acc_num = filings_raw['accessionNumber'][i]
+                acc_num_no_dashes = acc_num.replace("-", "")
+                primary_doc = filings_raw['primaryDocument'][i]
+                
+                # Construct standard EDGAR URL for the filing document
+                doc_url = f"https://www.sec.gov/Archives/edgar/data/{int(cik)}/{acc_num_no_dashes}/{primary_doc}"
+                
+                filings.append({
+                    "ticker": ticker.upper(),
+                    "cik": cik,
+                    "accession_number": acc_num,
+                    "filing_date": filings_raw['filingDate'][i],
+                    "form": filings_raw['form'][i],
+                    "size": filings_raw['size'][i],
+                    "primary_doc": primary_doc,
+                    "description": filings_raw['primaryDocDescription'][i],
+                    "url": doc_url
+                })
+            
+            return filings
+        except Exception as e:
+            logger.error(f"Error fetching filings for {ticker}: {e}")
+            return []
+
+    def fetch_filing_text(self, url: str, max_chars: int = 150000) -> str:
+        """
+        Downloads an SEC filing HTML/TXT document and extracts cleaned plaintext.
+        Strips HTML tags, inline styling, and limits length to avoid excessive tokens.
+        """
+        try:
+            logger.info(f"Downloading filing from {url}")
+            response = requests.get(url, headers=self.headers, timeout=15)
+            if response.status_code != 200:
+                logger.error(f"Failed to fetch filing document. Status: {response.status_code}")
+                return ""
+
+            # Use BeautifulSoup to parse HTML and extract text
+            soup = BeautifulSoup(response.text, "lxml")
+            
+            # Remove script and style elements
+            for element in soup(["script", "style"]):
+                element.decompose()
+
+            # Get text and clean up whitespace
+            text = soup.get_text(separator="\n")
+            lines = [line.strip() for line in text.splitlines()]
+            chunks = [phrase for phrase in lines if phrase]
+            clean_text = "\n".join(chunks)
+
+            # Limit length to prevent extreme context window consumption
+            if len(clean_text) > max_chars:
+                logger.info(f"Filing text truncated from {len(clean_text)} to {max_chars} chars.")
+                return clean_text[:max_chars] + "\n\n...[TRUNCATED FOR LENGTH]..."
+            
+            return clean_text
+        except Exception as e:
+            logger.error(f"Error fetching/parsing filing text from {url}: {e}")
+            return ""