TradeAssist: Gemini SEC Filing Analyzer

A modern, highly modular PyQt6 application that maps stock tickers to SEC CIK records, downloads specific SEC EDGAR filings (like 10-Ks, 10-Qs, and 8-Ks), parses their clean text, and feeds them into Google's Gemini models (using the new google-genai SDK) using custom or preconfigured prompt instructions to receive clean, structured JSON or plain text data.

This workspace separates the core Gemini/SEC analysis backend logic completely from the PyQt GUI layer, enabling you to easily import the core analytical engine (GeminiSecAnalyzer) directly into your trading bot or automated pipelines without dragging in any GUI dependencies.

Project Directory Structure

TradeAssist/
├── app/                       # Main application package
│   ├── __init__.py            # Package entry point
│   ├── config.py              # Central configurations (API keys, logging, SEC headers)
│   │
│   ├── backend/               # Shared Python backend services (NO PyQt dependencies)
│   │   ├── __init__.py
│   │   ├── data_models.py     # Pydantic schemas for Gemini structured JSON outputs
│   │   ├── sec_client.py      # SEC EDGAR client (CIK mapping, listing & downloading filings)
│   │   ├── gemini_client.py   # Google GenAI wrapper with exponential rate-limit retries
│   │   └── ...                 # Shared clients and data models
│   │
│   ├── features/              # Feature-owned tabs and private logic
│   │   └── fundamental/
│   │       ├── backend/analyzer.py
│   │       └── gui/            # Fundamental tab and its widgets
│   │
│   ├── gui/                   # Application-wide PyQt6 UI infrastructure
│   │   ├── __init__.py
│   │   ├── main_window.py     # Main window orchestrating components & worker threads
│   │   ├── worker.py          # Asynchronous QThread workers (keeps GUI responsive)
│   │   └── components/        # Reusable GUI widgets
│   │       ├── __init__.py
│   │       ├── filing_panel.py # Search, list, select filings; toggle bot scan mode
│   │       ├── prompt_panel.py # Model configuration (temperature, schema, custom/preset prompts)
│   │       └── results_panel.py # Dynamic HTML renderer for structured/text results
│   │
│   └── main.py                # Graphical App entry point (QApplication)
│
├── tests/                     # Tests kept separate from application code
├── requirements.txt           # Python library dependencies
└── README.md                  # This documentation file

Features

1. Two Core Analysis Modes:
   • Specific Filing Analysis: Select a specific filing (e.g. 10-K, 10-Q, 8-K), choose/input a prompt, and extract targeted details (Risk factors, Balance sheets, Dilution signs).
   • Comprehensive Bot Scan: Check the box to run a multi-variable scan across news headlines, RSS filing metadata, share counts, and financial statements directly—mirroring your original bot scanning logic.
2. Strict Structured JSON Responses: Uses Pydantic schemas (under data_models.py) coupled with Gemini's response_schema mode to guarantee output structure for bot pipelines.
3. Decoupled Backend Engine: Built cleanly using the official new google-genai SDK, ready to be dropped into any script.
4. Asynchronous Multi-threading: SEC scraping and Gemini inference runs in native PyQt background threads to ensure the UI remains fully responsive.
5. Modern styling: Uses the polished Fusion desktop palette and rich-HTML color-coded results cards for analysis ratings.

Setup & Running

1. Install Dependencies

Ensure you have a Python 3.11+ environment active, then install the required libraries:

pip install -r requirements.txt

2. Set Your API Keys

Ensure your Gemini API key is configured in your environment:

# Windows PowerShell
$env:GEMINI_API_KEY="your-gemini-api-key-here"

# Windows Command Prompt
set GEMINI_API_KEY=your-gemini-api-key-here

3. Run the GUI App

Launch the main dashboard:

python -m app.main

Drop-in Integration: Plugging Into Your Trading Bot

Because the backend logic is completely decoupled from the PyQt GUI library, you can import and run the exact same analysis programmatically inside your automated trading bot in just a few lines of code!

Here is a simple example showing how to plug it in:

import os
from app.features.fundamental.backend.analyzer import GeminiSecAnalyzer
from app.backend.data_models import StockAnalysis

# 1. Initialize analyzer (it picks up GEMINI_API_KEY from environment)
analyzer = GeminiSecAnalyzer()

# 2. Run the comprehensive bot scan on a ticker (returns strict StockAnalysis pydantic model)
result: StockAnalysis = analyzer.analyze_ticker_comprehensive("TSLA")

# 3. Read the structured scores and trigger bot decisions!
print(f"News Score: {result.news_score}/10")
print(f"SEC Filing Score: {result.SEC_score}/10")
print(f"Dilution Risk: {result.dilution_score}/10")
print(f"Cash Burn Risk: {result.cash_burn_score}/10")

if result.dilution_score > 7 or result.cash_burn_score > 8:
    print("⚠️ WARNING: High risk detected! Aborting stock purchasing pipeline.")
else:
    print("✅ Target meets bot risk tolerance standards. Proceeding to market evaluation.")