TEAM_GUIDE.md

PrimoGreedy v7.0 — Team Guide

What Is PrimoGreedy?

PrimoGreedy is an AI-powered micro-cap stock discovery agent. It systematically hunts for undervalued companies with market caps between $10M and $300M, priced under $30/share, across four markets: USA, UK, Canada, and Australia. It uses Benjamin Graham's value investing math combined with real-time data from multiple APIs, then delivers structured investment memos to the team via email.

The system runs automatically every day at 6:00 AM UTC via a GitHub Actions cron job, and also has an interactive web UI (Chainlit) for on-demand analysis.

---

How It Works — The Pipeline

Every stock goes through a 4-step pipeline built with LangGraph:

SCOUT  ──>  GATEKEEPER  ──>  ANALYST  ──>  EMAIL

Step 1: Scout (Discovery)

The Scout uses a two-pronged approach to find candidates:

1. yFinance Screener — Directly queries Yahoo Finance for stocks matching our market cap and price criteria. Uses a seed pool of known micro-cap tickers per region, updated over time.
2. Brave Search Trending — Searches the web for currently-trending micro-cap discussions (Reddit, financial blogs, news). Extracts ticker symbols from the results and merges them into the screener pool.

Both feeds are merged, then run through a quantitative scoring system (0–100 points) that ranks candidates on:

Criterion	Points
Profitability (EPS > 0)	20
Graham Number undervaluation	25
Price-to-Book < 1.0	15
Free Cash Flow positive	15
Low Debt (Net Debt/EBITDA)	10
Current Ratio > 1.5	10
Cash runway (if unprofitable)	5

Only the highest-scoring candidate gets sent to the expensive LLM analyst step. Up to 4 backups are queued in case the top pick fails the Gatekeeper.

Step 2: Gatekeeper (Validation)

Hard filters that reject stocks automatically:

• Price > $30/share
• Market cap outside $10M–$300M
• Financial health fails sector-specific checks:
  • Banks: Price/Book must be near or under 1.0
  • Tech/Healthcare: Must have at least 6 months of cash runway (zombie filter)
  • Industrials/Default: Net Debt/EBITDA must be under 3.5x

If rejected, the pipeline loops back to Scout to try the next candidate. After 4 failed attempts per region, a failure report is sent instead.

Step 3: Analyst (AI Investment Memo)

For stocks that pass the Gatekeeper, the AI writes a structured investment memo using two valuation frameworks:

• Graham Classic — For profitable companies: sqrt(22.5 × EPS × BookValue) to calculate intrinsic value and margin of safety.
• Deep Value Asset Play — For unprofitable companies (miners, biotech, turnarounds): evaluates Price vs Book Value as the safety net.

The memo is structured in 4 sections:

1. Quantitative Base — Price vs calculated intrinsic value, margin of safety math
2. Lynch Pitch — What insiders are doing + the one catalyst that could move the stock
3. Munger Invert — How you could lose money, what metric proves the bear case
4. Final Verdict — STRONG BUY / BUY / WATCH / AVOID with a one-sentence bottom line

Data sources fed into the prompt:

• yFinance (price, EPS, book value, EBITDA, sector)
• Finnhub (insider sentiment, company news, 52W high/low, beta, ROE)
• Insider Feed (6-month insider buying/selling via MSPR score)
• Brave Search (recent news and catalysts)

Step 4: Email

The memo (or failure report) is sent to all team members via Resend. Each team member uses their own API key for reliability.

---

How to Use the Web UI (Chainlit)

The Chainlit app runs on Hugging Face Spaces. Commands:

Command	What It Does
AUTO	Runs the full screener + Brave scan and returns a hot list
NVDA	Analyses a single ticker through the full pipeline
NVDA, AMD, TSLA	Analyses multiple tickers
@DeItaone	Scouts the web for stocks mentioned by a social media personality
PORTFOLIO	Shows the paper portfolio with live P&L for all past calls
BACKTEST	Runs a Backtrader backtest on the paper portfolio vs Buy & Hold
What is the Graham Number?	Chat mode — ask the AI broker anything

---

Architecture Overview

src/
├── core/              # Shared modules used by everything
│   ├── logger.py      # Structured logging
│   ├── search.py      # Single Brave Search implementation
│   ├── ticker_utils.py # Ticker extraction, suffix resolution, price normalization
│   ├── memory.py      # Seen-tickers ledger (30-day TTL)
│   └── state.py       # Shared LangGraph state schema
│
├── discovery/          # Stock discovery and ranking
│   ├── screener.py    # yFinance micro-cap screener + Brave trending merge
│   ├── scoring.py     # Quantitative 0-100 scoring system
│   └── insider_feed.py # SEC Form 4 + Finnhub insider sentiment feeds
│
├── backtesting/        # Backtrader integration
│   ├── engine.py      # Cerebro setup and run helpers
│   ├── strategies.py  # PrimoAgent and Buy & Hold strategies
│   ├── portfolio_bridge.py # Converts paper portfolio into backtest signals
│   ├── data.py        # Data loading for backtests
│   ├── plotting.py    # Chart generation
│   └── reporting.py   # Markdown report generation
│
├── whale_hunter.py    # Daily cron pipeline (Scout→Gatekeeper→Analyst→Email)
├── agent.py           # Interactive Chainlit pipeline (adds Chat, Chart, manual lookup)
├── llm.py             # LLM connection with 6-model fallback chain
├── finance_tools.py   # Graham Number, health checks, Finnhub tools
├── portfolio_tracker.py # Paper portfolio ledger
├── email_utils.py     # Thread-safe email dispatch via Resend
├── scanner.py         # Trending stock scanner
├── social_scout.py    # Social media handle scouting
├── niche_hunter.py    # Standalone Brave-only global hunter
└── global_router.py   # Market config (suffixes, gov filing links)

app.py                 # Chainlit web UI entry point
backtest.py            # Interactive backtesting CLI
main.py                # Workflow-based analysis CLI

---

API Keys Required

Key	Service	Used For
OPENROUTER_API_KEY	OpenRouter	LLM access (free tier)
BRAVE_API_KEY	Brave Search	Web search for trending stocks and news
FINNHUB_API_KEY	Finnhub	Insider sentiment, company news, fundamentals
RESEND_API_KEY_*	Resend	Email delivery (one per team member)
EMAIL_*	—	Team member email addresses

All keys are stored as GitHub Secrets for the cron job and in .env for local development.

---

LLM Model Fallback

The system uses free models via OpenRouter. If one model is rate-limited (429 error), it automatically tries the next:

1. nvidia/nemotron-3-nano-30b-a3b (primary — fast, reliable)
2. stepfun/step-3.5-flash
3. arcee-ai/trinity-large-preview
4. google/gemma-3-27b-it
5. meta-llama/llama-3.3-70b-instruct
6. mistralai/mistral-small-3.1-24b-instruct

---

Daily Cron Schedule

The GitHub Actions workflow (.github/workflows/hunter.yml) runs at 06:00 UTC daily:

1. Hunts all 4 regions: USA, UK, Canada, Australia
2. Sends email reports for each region (success or failure)
3. Commits the updated seen_tickers.json memory ledger to the repo
4. 60-minute timeout

To trigger manually: go to Actions > Global Hunter Cron > Run workflow on GitHub.

---

Paper Portfolio

Every BUY / STRONG BUY / WATCH call is recorded in paper_portfolio.json with the entry price and date. Use PORTFOLIO in the UI to see live P&L, or BACKTEST to compare against a Buy & Hold baseline using Backtrader.

---

Key Concepts

• Graham Number: sqrt(22.5 × EPS × Book Value) — the maximum price a defensive investor should pay. If the current price is below this, there's a margin of safety.
• Margin of Safety: (Graham Value - Price) / Graham Value — the bigger this %, the more undervalued.
• MSPR (Monthly Share Purchase Ratio): Finnhub's insider sentiment metric. Positive = insiders buying, negative = insiders selling.
• Zombie Filter: Rejects tech/healthcare companies burning cash with less than 6 months of runway.
• Seen Tickers Memory: A JSON ledger that prevents re-analysing the same stock within 30 days.