Repository navigation
Screener Contract
📄 Canonical source:
docs/SCREENER-CONTRACT.md
Status: Phase 2 — defined (schema + this doc). Ingestion and ranking are later phases. Related: #645 (this contract), #646 (suitability filter), #647 (attention-weight ranking), #648 (news/earnings ingestion), #649 (promote-to-protocol handoff).
SEES already has the right machinery — the dual-score model from #638 splits Opportunity (screening/ranking) from Signal (timing). A screener is not a new engine; it is a new input surface (catalysts) and a new output destination (watchlist → protocol).
- The screener emits attention.
- Directional conviction happens later, after handover, via the existing scoring.
Consequences enforced by the contract:
- No market data is required to create or filter a hit — a hit exists before any bars, quotes, or scores.
- No scores live on a hit or watchlist item — attention weight is computed later and is always per-source.
- Source-agnostic — news / earnings / social / email are pure adapters; the core shape below never changes.
Prisma model: ScreenerHit (table screener_hit).
| Field | Type | Notes |
|---|---|---|
id |
UUID | primary key |
ticker |
varchar(20) | unresolved ticker (raw symbol string) |
symbolId |
varchar(36) | null | resolved symbol FK — null until universe expansion |
source |
varchar(20) | enum: news | earnings | social | email
|
catalystType |
varchar(50) | free-form, e.g. earnings-beat, news-mention, social-surge
|
catalystStrength |
float (0–100) | source-provided strength |
sourceReliability |
float (0–100) | per-source static weight, denormalised at ingest |
rawPayloadRef |
varchar(500) | null | link/ref to the source payload for audit |
timestamp |
datetime | when the catalyst occurred |
createdAt |
datetime | when the hit was recorded |
A hit from any future source maps onto this shape with zero contract changes —
the source adapter fills source, catalystType, catalystStrength, and
sourceReliability; everything else is generic.
Prisma model: WatchlistItem (table watchlist_item). Distinct from the named
Watchlist list (which just holds symbols); a WatchlistItem is an individual
attention item that can belong to a list (watchlistId) or stand alone.
State machine:
new ──▶ watching ──▶ promoted ──▶ (done)
│ │
└──────────────────────┴──▶ expired (unused after N days — N TBD)
| Status | Meaning |
|---|---|
new |
surfaced by the screener, not yet reviewed |
watching |
accepted for monitoring |
promoted |
handed to a protocol's automation loop (promotedTo = protocol slug, promotedAt set) |
expired |
unused after N days (N TBD) |
Fields: ticker, symbolId?, status, source?, screenerHitId? (1:1 provenance
link), promotedTo?, promotedAt?, expiresAt?.
- Suitability filter — #646 (static metadata join, no scoring).
- Attention-weight ranking — #647 (Phase 3, computed not stored).
- News/earnings ingestion adapters — #648 (Phase 3).
- Promote-to-protocol handoff — #649 (Phase 3).
- Social / Discord / email adapters — Phase 5.
Tables are created idempotently at backend startup via PrismaService.bootstrapSchema()
(CREATE TABLE IF NOT EXISTS), matching the existing scheduled_job / ab_test pattern.
Trading Command Suite · Financial Disclaimer · Installing · FAQ
Source · AGPL-3.0 · Issues · Discussions Built by Ryan Bayne · FifeCIC
💚 Support this project → — free, complete, no premium edition, and no income.
🛑 Not financial advice. The app ships unconfigured and is not set up to make money for you. Test on a demo account before connecting anything real.
v0.162.0 · alpha · © 2026 Ryan Bayne / FifeCIC · AGPL-3.0 · generated from the repository — corrections belong in the repo, not this page.
🛑 Financial Disclaimer — read before connecting an account.
🌐 Website · Screenshots
💚 Support this project — the app is free, complete, and has no income.
Start here
Understand
- How it works
- Glossary
- Scoring architecture
- Risk controls
- How a bot becomes a trade
- Screener contract
- Trading constraints
- Readiness tiers
- Notice codes
Help