Celes Renata
a72f336ad1
Multi-stage evidence-grounded inference architecture replacing the monolithic 9B model extraction pipeline. CPU-first specialist services handle routine extraction while the 9B vLLM model is preserved for semantic adjudication of ambiguous cases. Key components: - Capability-aware inference gateway (OpenAI-compatible + Ollama) - Endpoint registry with DB migrations and REST API - Sentence-aware document segmenter (property tests) - Deterministic financial parsing with offset integrity - Symbol resolution with ambiguity detection - Specialist service (GLiNER2, dynamic batching, K8s deployment) - Company-specific sentiment (FinBERT, calibration) - Retrieval-based novelty and duplicate detection - Confidence calibration pipeline - Deterministic routing engine (property tests) - 9B adjudication layer with VRAM gating - Stock-specific impact model (features, labels, baseline, trained) - Pipeline orchestrator (state machine, queues, leases, feature flags) - Bounded parallelism (async workers, semaphore, load shedding) - Observability (tracing, metrics, alerts) - Compatibility adapter (v3→v2 golden mapping tests) - Shadow/canary promotion framework - Active learning and fine-tuning pipeline Test results: 1,161 tests pass, ruff lint clean. All 282 spec tasks completed.
145 lines
11 KiB
Markdown
145 lines
11 KiB
Markdown
# Stonks Oracle — What It Is and What It Does
|
|
|
|
## The One-Liner
|
|
|
|
Stonks Oracle is an autonomous market intelligence system that reads the news so you don't have to, forms a view on 50 publicly traded companies, and paper-trades that view — then grades its own homework.
|
|
|
|
---
|
|
|
|
## The Problem It Solves
|
|
|
|
Markets are noisy. Every day, hundreds of news articles, SEC filings, earnings transcripts, and geopolitical headlines hit the wire. A human analyst covering even a dozen names struggles to weigh all of it in real time. Most retail and even some institutional desks end up reacting to headlines rather than synthesizing the full picture.
|
|
|
|
Stonks Oracle replaces that manual synthesis with an always-on pipeline:
|
|
|
|
1. **It reads everything.** News articles, 10-K/10-Q filings, earnings calls, press releases, and macro/geopolitical headlines — ingested automatically on a schedule.
|
|
2. **It extracts structured intelligence.** A local AI model reads each document and pulls out: which companies are mentioned, the sentiment (bullish / bearish / neutral), the catalyst type (earnings, product launch, regulatory action, M&A, etc.), impact horizon (same-day through 90 days), key facts, and material risks.
|
|
3. **It forms a view.** Those individual extractions are aggregated into rolling trend summaries per company, refreshed continuously. The system flags contradictions (e.g., one filing is bullish but a news article is bearish) and tracks confidence based on evidence depth.
|
|
4. **It decides whether to trade.** When confidence is high enough, contradiction is low, and evidence is fresh, it issues a buy or sell recommendation — with a full written thesis explaining why.
|
|
5. **It executes paper trades.** An autonomous trading engine places orders through Alpaca's paper-trading system. Position sizing, stop-losses, take-profits, sector concentration limits, and circuit breakers are all built in.
|
|
6. **It measures itself.** Every prediction is frozen at the moment it's made, then checked against actual price movements days and weeks later. The system tracks its own win rate, calibration, and whether it's beating SPY.
|
|
|
|
---
|
|
|
|
## The Universe
|
|
|
|
50 companies across 10 sectors:
|
|
|
|
| Sector | Examples |
|
|
|--------|----------|
|
|
| Technology | AAPL, MSFT, NVDA, GOOGL, META |
|
|
| Consumer Cyclical | AMZN, TSLA, NKE, SBUX |
|
|
| Financial Services | JPM, GS, V, MA |
|
|
| Healthcare | JNJ, UNH, PFE, LLY |
|
|
| Energy | XOM, CVX, COP |
|
|
| Communication Services | NFLX, DIS, T |
|
|
| Industrials | CAT, BA, UPS |
|
|
| Consumer Defensive | PG, KO, WMT |
|
|
| Real Estate | AMT, PLD |
|
|
| Utilities | NEE, DUK |
|
|
|
|
46 competitor relationships are defined (direct rivals, same-sector peers, overlapping products, supply chain adjacencies) so the system can propagate signals — e.g., if a semiconductor shortage hits one chipmaker, the system assesses exposure for its competitors and supply chain partners.
|
|
|
|
---
|
|
|
|
## The Three Signal Layers
|
|
|
|
Think of these as three analysts sitting at the same desk, each watching a different feed:
|
|
|
|
### Layer 1 — Company-Specific Intelligence
|
|
|
|
The bread and butter. Every news article and filing about a specific company gets scored for sentiment, impact magnitude, and time horizon. These signals are weighted by recency (yesterday's earnings matter more than last month's), source credibility, and novelty (the fifth article repeating the same news adds less information than the first).
|
|
|
|
Trend summaries roll up across five windows: intraday, 1 day, 7 days, 30 days, and 90 days — giving both a "what's happening right now" and a "what's the longer arc" view.
|
|
|
|
### Layer 2 — Macro & Geopolitical
|
|
|
|
Global events (trade wars, rate decisions, geopolitical crises, commodity shocks) are classified by impact type and severity. Each company has an exposure profile — geographic revenue mix, supply chain regions, commodity dependencies — that maps macro events down to company-level impact scores.
|
|
|
|
A tariff announcement on Chinese imports doesn't affect all 50 companies equally. Apple with its Chinese manufacturing exposure gets a higher impact score than Procter & Gamble with largely domestic supply chains.
|
|
|
|
### Layer 3 — Competitive & Historical Patterns
|
|
|
|
The system mines its own history: when this type of catalyst (say, an earnings beat) happened to this company in the past, what happened to the stock? What happened to its competitors? If NVIDIA reports a blowout quarter, does AMD tend to sell off or rally in sympathy?
|
|
|
|
This layer also tracks major corporate actions (M&A, restructurings, leadership changes) and propagates their implications across the competitive web.
|
|
|
|
**Safety rule:** The system never trades on macro or competitive signals alone. If there's no company-specific evidence supporting the thesis, the recommendation is downgraded to informational only.
|
|
|
|
---
|
|
|
|
## How a Trade Happens
|
|
|
|
Here's the chain from "news article published" to "paper order placed":
|
|
|
|
1. **Ingestion** — The article is fetched, deduplicated, and stored.
|
|
2. **Parsing** — Raw HTML is cleaned, boilerplate is stripped, quality is scored.
|
|
3. **Extraction** — The AI model reads the cleaned text and produces structured JSON: tickers mentioned, sentiment, catalysts, key facts, risks.
|
|
4. **Aggregation** — The new extraction is merged into rolling trend summaries for each mentioned company. Confidence, contradiction, and evidence depth are recalculated.
|
|
5. **Recommendation** — If the trend passes quality filters (enough evidence, high enough confidence, low enough contradiction, not stale), a BUY or SELL recommendation is generated with a written thesis.
|
|
6. **Risk checks** — The trading engine asks: Is the circuit breaker tripped? Is the market open? Do I already have too many positions? Is this sector already overweight? Are earnings in the next 48 hours?
|
|
7. **Position sizing** — Dollar amount is computed from confidence, portfolio heat, and the current risk tier (conservative / moderate / aggressive — auto-adjusted based on trailing performance).
|
|
8. **Execution** — The order goes to Alpaca's paper-trading API. Stop-loss and take-profit levels are set automatically based on the stock's recent volatility.
|
|
9. **Monitoring** — Open positions are tracked with trailing stops. If a position declines past its stop, it's closed. If it hits the take-profit target, it's closed.
|
|
10. **Scoring** — Days later, the prediction is evaluated against the actual price move. Did the call go the right way? Did the confidence track reality?
|
|
|
|
---
|
|
|
|
## Risk Management (Built In, Not Bolted On)
|
|
|
|
- **Circuit breakers** — If daily losses exceed a threshold or a single position loses too much, all trading halts automatically.
|
|
- **Position caps** — No single position can consume more than a set percentage of the portfolio.
|
|
- **Sector concentration limits** — The system won't pile into one sector even if all signals are bullish.
|
|
- **Correlation awareness** — New positions are rejected if they'd push portfolio correlation too high.
|
|
- **Earnings blackout** — Position sizes are reduced or skipped entirely within 48 hours of an earnings announcement.
|
|
- **Reserve pool** — Profits are partially siphoned into an emergency liquidity reserve.
|
|
- **Risk tier auto-adjustment** — The system evaluates its own Sharpe ratio, drawdown, and win rate daily and shifts between conservative, moderate, and aggressive modes.
|
|
|
|
---
|
|
|
|
## Self-Grading: The Validation Loop
|
|
|
|
Most trading systems tell you their view. Few systematically check whether that view was right.
|
|
|
|
Stonks Oracle captures every prediction as an immutable snapshot — the thesis, the confidence, the price at the time, the evidence cited. Then it waits. After the prediction's time horizon elapses (1 day, 7 days, 30 days), it compares the predicted direction against the actual price movement and computes:
|
|
|
|
- **Win rate** — What fraction of directional calls were correct?
|
|
- **Calibration** — When the system says "70% confident bullish," does the stock actually go up ~70% of the time? (If it only goes up 50% of the time, the system is overconfident.)
|
|
- **Information coefficient** — Does the system's score have any linear correlation with actual returns?
|
|
- **Excess return vs. SPY** — Is it adding alpha, or would you be better off in an index fund?
|
|
- **Source attribution** — Which news sources and signal types actually contribute to correct predictions? Which are noise?
|
|
|
|
If model quality drops below defined thresholds, a safety gate prevents the system from upgrading recommendations from "informational" to "paper eligible" — it forces itself to the sidelines until accuracy recovers.
|
|
|
|
---
|
|
|
|
## The Dashboard
|
|
|
|
A web-based interface lets you see everything the system sees:
|
|
|
|
- **Home** — Portfolio value, daily P&L, risk tier, active alerts.
|
|
- **Companies** — The tracked universe with current trend summaries and signal strength.
|
|
- **Documents** — Every ingested article and filing, with the AI's structured extraction visible.
|
|
- **Trends** — Per-company trend charts across all time windows, with evidence chains you can click through.
|
|
- **Recommendations** — Active and historical recommendations with full theses and risk classifications.
|
|
- **Trading** — The engine's status: open positions, reserve pool, circuit breaker state, portfolio heat map.
|
|
- **Orders & Positions** — Full trade blotter with execution details.
|
|
- **Macro Events** — Global event timeline showing what the system is tracking at the geopolitical level.
|
|
- **Reports** — AI-generated daily and weekly performance summaries.
|
|
- **Model Performance** — Calibration curves, win rate trends, source reliability scores.
|
|
- **SQL Explorer** — Ad-hoc queries against the full analytical data warehouse, with a chart builder.
|
|
|
|
---
|
|
|
|
## What It Is Not
|
|
|
|
- **Not a live trading system (yet).** All trades are paper trades through Alpaca's sandbox. The architecture supports live execution, but safety gates and validation must demonstrate consistent edge before real money is at risk.
|
|
- **Not a black box.** Every recommendation includes a full thesis, every trade has a decision trace, every prediction links back to the specific evidence that drove it.
|
|
- **Not a prediction guarantee.** Markets are hard. The system's value is in disciplined synthesis, consistent process, and honest self-measurement — not in claiming to always be right.
|
|
|
|
---
|
|
|
|
## Where It's Headed
|
|
|
|
Active development is upgrading the signal math from rule-based heuristics to probabilistic Bayesian inference — running both approaches in parallel, comparing their verdicts, and using the disagreements as training signals for continuous improvement. The goal is a system that not only reads the market but learns from its own track record which types of evidence, in which market regimes, actually predict future price moves.
|