Add automated event hunter & trading research assistant

[Copilot]

Greenfield implementation of a structured trading research tool that scans stocks, options, crypto, and prediction markets for asymmetric event-driven opportunities across five parallel workflows.

Architecture

• models.py — Domain dataclasses: MergerArbCandidate, OptionsFlowAlert, AcquisitionBaitCandidate, ActivistPosition, TradeIdea, Basket, DailyScanResult
• data_sources.py — Seven ABCs (StockDataSource, OptionsDataSource, NewsDataSource, FilingsDataSource, CryptoDataSource, PredictionMarketSource, FlowDataSource) with full mock implementations; swap in live adapters without touching workflow code
• workflows/ — One module per workflow:
  • merger_arb.py — classifies announced deals as Pure arb / Speculative arb / Pass; surfaces prediction-market proxies
  • options_flow.py — flags vol/OI ≥ 3× 30-day avg; cross-checks news; generates thesis + invalidation
  • acquisition_bait.py — scores small/mid-cap stocks and crypto on FCF yield, EV/EBITDA, leverage, insider ownership
  • activist_tracker.py — parses 13F/SC 13D stubs and on-chain whale accumulation; annotates cross-workflow overlaps
  • portfolio.py — assembles a Conservative (arb + activist + equity bait) and Aggressive (options + spec arb + crypto + prediction markets) basket, each summing to 100%
• scanner.py — Orchestrates all five workflows; exposes daily_scan(), deep_dive(ticker), build_basket()
• output.py — Rich-based terminal renderer with colour-coded tables and structured sections
• main.py — CLI entry point

Usage

pip install -e .

stock-hunter daily-scan          # full pass of all 5 workflows
stock-hunter deep-dive ACME      # single-ticker focus
stock-hunter build-basket        # Conservative + Aggressive baskets only

Extending with live data

from stock_hunter.data_sources import StockDataSource, build_mock_data_sources
from stock_hunter.scanner import Scanner

class MyLiveStockData(StockDataSource):
    def get_price(self, symbol): ...
    def get_fundamentals(self, symbol): ...
    def screen(self, **criteria): ...

ds = build_mock_data_sources()
ds.stocks = MyLiveStockData()   # swap one adapter; rest stay as mocks
scanner = Scanner(ds)
result = scanner.daily_scan()

Original prompt

You are my AUTOMATED EVENT HUNTER and TRADING RESEARCH ASSISTANT.

High‑level goal:
Continuously scan stocks, options, crypto, and prediction markets (e.g., Polymarket)
to surface asymmetric opportunities, especially:

• Merger & acquisition / go‑private deals (merger arbitrage)
• Unusual options activity
• Potential acquisition targets (“acquisition bait”)
• Positions linked to activist investor 13F filings
• Diversified baskets of uncorrelated trades rather than single YOLO bets

You NEVER place trades yourself. You generate structured, step‑by‑step research
outputs and trade ideas that I can review and execute manually.

---

DATA SOURCES & ACCESS (assume tools exist)

Assume you can call tools or APIs with natural‑language commands like:

• STOCK_DATA(symbol, fields, timeframe)
• OPTIONS_DATA(symbol, expiry, strike_range)
• NEWS_SEARCH(query, timeframe)
• FILINGS_SEARCH(ticker or fund, form_type)
• CRYPTO_DATA(symbol, exchange, timeframe)
• PREDICTION_MARKETS(query, timeframe) # e.g. Polymarket order books, prices, volume
• FLOW_DATA(query) # large block trades, dark pool prints, etc.

If some data is not available, say so explicitly and suggest the closest proxy.

---

CORE WORKFLOWS (run these in parallel)

1. MERGER ARBITRAGE SCREEN (STOCKS & CRYPTO EQUIVALENTS)

• Scan daily for:
  • Announced cash mergers, LBOs, go‑privates, takeovers.
  • Large one‑day jumps (≥ 20%) on confirmed M&A news.
• For each candidate, output:
  • Ticker, price BEFORE announcement, price AFTER announcement.
  • Deal terms (cash/stock, offer price, expected close date, key conditions).
  • “Spread” between current price and offer price (in %).
  • Main risks: regulatory, financing, shareholder vote, geopolitical, etc.
• Classify each as:
  • “Pure arb” (late‑stage, small spread, lower risk),
  • “Speculative arb” (rumors, hostile bids, large spread),
  • “Pass” (spread too small vs. risk).
• For crypto/prediction markets:
  • Look for tokens or markets directly tied to the merger narrative
    (e.g., acquisition tokens, bankruptcy claims, event‑driven markets).
  • Summarize whether there is a cleaner play via prediction markets
    instead of the stock itself.

2. UNUSUAL OPTIONS VOLUME & FLOW

• Scan options chains for:
  • Volume or open interest ≥ 3x the 30‑day average.
  • Large, concentrated trades in near‑dated out‑of‑the‑money calls or puts.
• For each flagged symbol:
  • Show stock price, implied volatility change, and key strikes/expiries hit.
  • Distinguish between:
    • Directional bets (e.g., big OTM call sweep),
    • Hedging (e.g., large downside puts with existing long stock trend),
    • Complex spreads (e.g., call spreads, straddles).
  • Cross‑check news (NEWS_SEARCH) for catalysts:
    earnings, FDA decisions, court rulings, M&A rumors, macro headlines.
• Convert into 1–2 possible trade structures (stock, options, prediction
  market contracts, or crypto proxies), always stating:
  • Thesis, time horizon, entry level, invalidation level, key risks.

3. ACQUISITION BAIT SCREENER

• Universe: small and mid‑cap stocks plus mid‑cap crypto projects and L1/L2s.
• Look for profiles consistent with takeover targets:
  • Positive free cash flow, moderate growth, but compressed valuation
    vs peers in same sector.
  • Clean balance sheet (low net debt / EBITDA).
  • High institutional or insider ownership.
  • Strategic fit for larger acquirers (overlapping products or clear synergies).
• For each candidate, output:
  • “Why this could be a target” in 3–5 bullet points.
  • 3–5 likely acquirers and the strategic angle for each.
  • Any open strategic review, activist pressure, or prior deal rumors.
• For crypto:
  • Identify teams / protocols with strong cash flow (fees, MEV, revenue)
    but low FDV or low attention.
  • Flag ecosystems where acquisition/merger of teams, clients,
    or IP is plausible (wallets, infra, analytics).

4. ACTIVIST 13F & LARGE‑HOLDER TRACKER

• Monitor 13F filings and similar disclosures from well‑known activists,
  smart hedge funds, and crypto whales.
• For each new or increased position:
  • Summarize the activist’s history and typical playbook.
  • Show position size, % of company, and any public letters/campaigns.
  • Highlight overlaps with:
    • Merger arb opportunities,
    • Acquisition bait screen list,
    • Unusual options or prediction market activity.
• For on‑chain/crypto:
  • Track notable wallets and funds accumulating positions.
  • Identify overlap between large on‑chain buys and narrative catalysts.

5. DIVERSIFICATION & PORTFOLIO CONSTRUCTION

• When proposing ideas, always:
  • Limit concentration: no single idea > X% of a hypothetical trade basket.
  • Balance across:
    • Stocks (value, growth, event‑driven),
    • Options (defined‑risk plays),
    • Crypto (higher risk, smaller size),
    • Prediction markets (bin...