Sec Filing Analyzer README

StockHuntr — SEC Filing Analyzer

Chat with SEC filings. Get cited answers and risk scores — free.

StockHuntr is a free AI tool for reading and analyzing SEC filings. Ask about any 10-K, 10-Q, or 8-K in plain English and get clear, cited answers straight from the filing, plus AI risk and concern scoring across 800+ US companies (all S&P 500 constituents). Everything is grounded in primary-source SEC EDGAR data. It also generates 30-day alpha signals as a secondary feature.

It competes with paid AI research tools (Fintool, AlphaSense) and free raw EDGAR — cited AI answers and risk scoring on primary-source filings, at no cost. Research and educational only; not investment advice.

Live at: stockhuntr.net

Features

Chat With Filings (Ask the Market)

• Cited answers — Ask questions in plain English about any 10-K, 10-Q, or 8-K and get answers grounded in the actual filing, with accession numbers and EDGAR links cited
• Grounded Q&A blocks — Company and filing pages carry server-rendered "key questions" derived from real analysis data, with FAQPage structured data (lib/qa-builders.ts)
• Natural-language querying — Screen and query the filing corpus at /query

AI-Powered Filing Analysis

• AI Risk & Concern Scoring — 0–10 concern score (LOW → CRITICAL) with factor breakdown; detects data breaches, litigation, executive departures, restatements, covenant breaches, and more
• Risk Factor Analysis — Claude AI analyzes risk factor changes between filings, identifying new risks, removed risks, and severity shifts
• Sentiment Analysis — Management tone detection from MD&A sections (-1 to +1 scale)
• Executive Summaries — Investor-focused bullet points generated from filing content
• 8-K Event Classification — Automated categorization of current event filings

30-Day Alpha Prediction (Alpha Model v2 — secondary feature)

• Stepwise+Ridge regression predicting 30-day market-relative alpha (stock return minus S&P 500)
• 13 features across 44 Mixture-of-Experts (MoE) models — global + 11 sector experts + 4 cap-tier experts + 29 sector×cap-tier combined experts
• 4,009 training samples from 500+ companies (10x expansion from v1's 340 samples)
• Historical price snapshots at filing date (99% coverage) — eliminates stale-price bias from prior model
• Macro regime features — S&P 500 30-day trend and VIX level at filing date for bull/bear market adjustment
• EPS surprise — strongest new feature (actual vs. consensus EPS), winsorized to [-50%, +50%]
• Backtested accuracy: 53.5% directional (74.7% high-confidence), Sharpe ratio ~1.97 (90-day strict walk-forward CV)
• Paper Trading — Automated virtual portfolio validates live performance (30-day hold period)
• See MODEL.md for full model documentation

Content & Discovery (server-rendered for SEO / AI crawlers)

• /learn — Explainer library: plain-language answers about SEC forms and items (10-K vs 10-Q, 8-K items, going concern, EPS surprises, XBRL, Form 4)
• /sectors & /sectors/[slug] — Sector insight pages with aggregate stats (filings analyzed, avg concern, model accuracy) computed from the corpus
• /news & /news/[slug] — Daily AI-written news/insights section: a small, significance-gated set (≤4/day, never one-per-filing) of original articles analyzing the most significant recent filings. Each is Claude-written from stored analysis with a strict no-arithmetic/grounded prompt, carries NewsArticle JSON-LD, a visible AI-disclosure line, E-E-A-T provenance (primary-source EDGAR link + methodology), a dynamic OG image, and internal links to the filing/company/sector. Google-News-surfaced via /news-sitemap.xml (48h window, <news:news> tags); auto-syndicated to owned Medium/X/LinkedIn accounts (credential-gated). Not investment advice.
• /pulse — Recurring "SEC Filing Pulse" report: sector concern heat, most significant filings, strongest 30-day signals (ISR-refreshed, Article JSON-LD)
• RSS feed (/feed.xml) — RSS 2.0 of the most recent AI-analyzed filings (autodiscovery <link> site-wide); consumed by feed readers + news aggregators
• /compare & /compare/[slug] — Comparison landing pages (e.g. Fintool vs StockHuntr, AlphaSense alternatives, Bloomberg Terminal alternatives)
• MCP server (/api/mcp, docs at /mcp) — Remote Model Context Protocol server (Streamable HTTP) with 7 read-only tools: filings, filing analysis, company snapshot, company search, fundamentals screening, top signals, and model track record — for MCP clients (Claude, ChatGPT, agents). Published to the official MCP Registry as io.github.kyliemckinleydemo/sec-filing-analyzer. Discovery manifest at /.well-known/mcp.json. See

Data Pipeline (Automated Cron Jobs)

• SEC Filing Ingestion — Fetches new 10-K, 10-Q, 8-K filings via RSS (3x daily), matched to companies by CIK (not ticker) for reliability, with daily-index catch-up
• AI Analysis — Automated analyze-filings cron keeps recent filings analyzed in bounded, cost-guarded batches
• News Generation — generate-news cron (daily 12:00 UTC) writes the day's ≤4 significant-filing articles via Claude (significance-gated, idempotent, cost-capped); syndicate-news cron (12:30 UTC) cross-posts new articles to owned Medium/X/LinkedIn accounts (credential-gated no-op until keys are set)
• Prediction Backfill — backfill-predictions cron persists 30-day alpha predictions so Top Signals / Track Record / MCP stay populated
• Ticker Audit — Weekly ticker-audit cron surfaces ticker-universe drift (delistings, duplicates, missing companies)
• Stock Price Updates — Real-time prices from Yahoo Finance (batch rotation 6x daily)
• Analyst Data — Consensus ratings, target prices, upgrades/downgrades
• Macro Indicators — S&P 500, VIX, Treasury yields, sector ETFs
• Paper Trading — Automated position closure after 30-day hold period
• Supervisor — Health monitoring with auto-recovery and email alerts, including analysis-coverage and stock-price-freshness data checks

User Features

• Watchlist Alerts — Email notifications for high-concern filings, price moves, analyst activity
• Company Search — Search 800+ companies by ticker
• Filing History — Browse 10-K, 10-Q, 8-K with infinite scroll
• Paper Trading Dashboard — Track virtual portfolio performance
• Magic Link Auth — Passwordless email authentication

Tech Stack

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL database
• Anthropic API key (get one here)

Installation

git clone https://github.com/kyliemckinleydemo/sec-filing-analyzer.git
cd sec-filing-analyzer
npm install

Environment Variables

Create .env.local:

# Required
DATABASE_URL="postgresql://user:password@localhost:5432/sec_analyzer"
ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

# Cron job authentication
CRON_SECRET="your-cron-secret"

# Email alerts (Resend)
RESEND_API_KEY="re_your-key-here"
ALERT_EMAIL="you@example.com"

# Auth
JWT_SECRET="your-jwt-secret"
MAGIC_LINK_SECRET="your-magic-link-secret"

Database Setup

npx prisma generate
npx prisma db push

Run

npm run dev        # Development server at localhost:3000
npm test           # Run all 244 Vitest tests
npm run test:e2e   # Run Playwright E2E tests (108)

Project Structure

sec-filing-analyzer/
├── app/                              # Next.js App Router
│   ├── api/
│   │   ├── analyze/[accession]/      # AI filing analysis
│   │   ├── predict/[accession]/      # Price prediction
│   │   ├── filings/latest/           # Latest filings feed
│   │   ├── mcp/                      # Remote MCP server (Streamable HTTP)
│   │   ├── cron/                     # Automated cron jobs
│   │   │   ├── daily-filings-rss/    # SEC RSS ingestion (CIK-matched) + IndexNow
│   │   │   ├── analyze-filings/      # Automated AI analysis (bounded batches)
│   │   │   ├── backfill-predictions/ # Persist 30-day predictions
│   │   │   ├── ticker-audit/         # Weekly ticker-universe drift audit
│   │   │   ├── update-analyst-data/  # Analyst consensus
│   │   │   ├── update-stock-prices/  # Full price refresh
│   │   │   ├── update-stock-prices-batch/  # Batch rotation
│   │   │   ├── update-macro-indicators/    # Macro data
│   │   │   ├── watchlist-alerts/     # User email alerts
│   │   │   ├── watchlist-alerts-scheduler/ # Alert routing
│   │   │   ├── paper-trading-close-positions/ # Position mgmt
│   │   │   └── supervisor/           # Health monitoring
│   │   ├── auth/                     # Magic link auth
│   │   ├── paper-trading/            # Trade execution
│   │   ├── watchlist/                # Watchlist CRUD
│   │   └── chat/                     # AI chat
│   ├── components/                   # Shared components
│   │   ├── Navigation.tsx            # Sticky site header/nav
│   │   ├── Footer.tsx                # Site-wide footer
│   │   └── QASection.tsx             # Grounded Q&A block (FAQPage JSON-LD)
│   ├── learn/                        # Explainer library (+ [slug])
│   ├── sectors/                      # Sector insight pages (+ [sector])
│   ├── pulse/                        # SEC Filing Pulse report
│   ├── compare/                      # Comparison landing pages (+ [slug])
│   ├── latest-filings/               # Filing feed page
│   ├── filing/[accession]/           # Filing detail page
│   ├── company/[ticker]/             # Company page
│   ├── paper-trading/                # Portfolio dashboard
│   ├── watchlist/                    # Watchlist page
│   ├── sitemap.ts                    # Dynamic sitemap.xml
│   ├── robots.ts                     # robots.txt (allows AI crawlers)
│   ├── layout.tsx                    # Root layout: nav, JSON-LD, Clarity
│   └── page.tsx                      # Homepage (SSR initial data)
├── lib/                              # Core business logic
│   ├── alpha-model.ts                # Alpha prediction model
│   ├── qa-builders.ts                # Grounded Q&A pair builders
│   ├── filings-server.ts            # Server-side latest-filings query
│   ├── sector-insights.ts            # Sector aggregate stats
│   ├── pulse.ts                      # Pulse report computation
│   ├── indexnow.ts                   # IndexNow URL submission
│   ├── paper-trading.ts              # PaperTradingEngine class
│   ├── supervisor.ts                 # Cron health monitoring
│   ├── claude-client.ts              # Anthropic API client
│   ├── sec-rss-client.ts             # SEC RSS feed client (CIK matching)
│   ├── macro-indicators.ts           # Macro data fetching
│   ├── auth.ts                       # JWT + magic link auth
│   ├── rate-limit.ts                 # API rate limiting
│   └── prisma.ts                     # Prisma client singleton
├── public/
│   └── llms.txt                      # LLM/AI-crawler site summary
├── scripts/
│   └── export-dataset.ts             # Open dataset export (CSV/JSONL)
├── __tests__/                        # Test suite (244 Vitest + 108 E2E)
│   ├── unit/                         # Pure logic tests
│   ├── integration/                  # API route + service tests
│   │   ├── api/cron/                 # All cron job tests
│   │   └── lib/                      # Service layer tests
│   ├── e2e/                          # Playwright browser tests
│   ├── fixtures/                     # Shared test data
│   └── mocks/                        # Prisma + module mocks
├── prisma/
│   └── schema.prisma                 # Database schema
├── scripts/                          # Data pipeline scripts
└── vercel.json                       # Cron schedules + config

Cron Jobs

The system runs automated jobs via Vercel Cron (see vercel.json):

All cron endpoints require Authorization: Bearer <CRON_SECRET> or vercel-cron user-agent. The analyze-filings job only spends on the Anthropic API when ANALYSIS_ENABLED=true (dry-run otherwise).

See CRON-JOBS-README.md for detailed documentation.

Testing

npm test                    # All 244 Vitest tests
npm run test:unit           # Unit tests only
npm run test:integration    # Integration tests only
npm run test:coverage       # With coverage report
npm run test:e2e            # Playwright E2E (108 tests)
npm run test:count          # Count tests across suites (static)

Test Coverage

See TEST-PLAN.md for detailed test architecture.

API Endpoints

Public

Analysis (requires auth)

Cron (requires CRON_SECRET)

Environment Variables

Deployment

Deployed via Vercel CLI (not GitHub auto-deploy):

npm run deploy              # Production deploy with --force
npm run deploy:preview      # Preview deployment

This runs vercel --prod --force and sets the stockhuntr.net alias.

Database Sync

After schema changes, sync production DB:

vercel env pull .env.prod
DATABASE_URL=$(grep DATABASE_URL .env.prod | cut -d= -f2-) npx prisma db push
rm .env.prod

See DEPLOYMENT.md for the full deployment guide.

Documentation

Disclaimer

This tool is for educational and research purposes only. Do not use this as financial advice. Always consult with a qualified financial advisor before making investment decisions. Past performance does not guarantee future results.

Built with Next.js, TypeScript, Claude AI, and Vitest