flowsight/docs/AGENT-SPECS.md

Agent specs

Contract: analyze(ticker_or_scope, snapshots) -> AgentResult(values[], score, citations[]). Agents never fetch live; they read snapshots. Fixtures in tests/fixtures/ prove each.

A1 — Smart Money Tracker

• Reads: broker-summary/top, broker-activity/top, foreign-flow.
• Steps: (1) top buyers/sellers per ticker; (2) per-broker accumulation ranks; (3) foreign inflow 90d trend; (4) correlate broker net direction vs foreign direction; (5) classify phase: accumulation / distribution / neutral / conflict.
• Output: score −100..+100, phase, top-3 players with net Rp, direction-agreement flag.
• Fixture: BBCA 5d — 3 domestic brokers net-buy Rp 1.2T + foreign inflow → score > +60.

A2 — Broker Intel

• Reads: brokers/ registry cache, broker-activity per code, brokers/top daily.
• Steps: (1) classify each active broker by origin/cohort; (2) behavior class per broker (accumulating/distributing/neutral from top/ ranks); (3) sector exposure shift week-over-week; (4) emit rotation signal on sign flip with evidence rows.
• Output: behavior map, rotation signal (from→to + net Rp delta).
• Fixture: Financials net −Rp 800M → Consumer +Rp 1.1B flip detected (sector_flow_idx.json).

A3 — News Sentiment (Adaptive RAG)

• Reads: news (incremental), filings, suspensions.
• Steps: (1) fetch candidate articles; (2) LLM confidence check — confident → answer from context, uncertain (rare ticker) → force retrieval + ground; (3) per-article sentiment + confidence; (4) aggregate trend improving/deteriorating/stable; (5) insider summary from filings.
• Output: score −1..+1, trend, key events (≤5, cited), insider line.
• Offline path: when no news/filings/suspensions snapshots exist, the agent falls back to the derived news_items table (NewsSince) instead of failing.
• Fixture: ticker with 2 bullish + 1 neutral + 1 director buy → positive trend cited.

A4 — Fundamental

• Reads: company/report (sections=overview,valuation,financials,dividend), financials/quarterly (n≤8), get-segments.
• Steps: (1) P/E, P/B vs subsector median (subsector/report statistics); (2) revenue/earnings 8Q trend; (3) ROE trajectory, debt/equity, payout ratio; (4) grade A–F from weighted rubric (profitability 35, growth 25, leverage 20, payout 20).
• Output: score 0–100, grade, vs-peers table, red flags.
• Fixture: BBCA — premium P/E vs banks median, declining ROE flagged.

A5 — Technical

• Reads: daily (≤90d), most-traded, top-changes, free-float.
• Steps: (1) volume vs 20d avg multiples; (2) momentum positioning from movers; (3) relative volume vs market; (4) liquidity grade from free-float %.
• Output: momentum signal (strong/up/flat/down), anomaly flag with dates, liquidity grade.
• Fixture: 3.2× volume spike flagged with date + mover rank cited.

A6 — Event Catalyst

• Reads: corporate-actions, quarterly-dates, listing-performance.
• Steps: (1) upcoming dividends/splits/AGM with dates; (2) next earnings estimate; (3) IPO-window context for recent listings; (4) score opportunity 0–100 (yield × certainty − earnings-risk).
• Output: catalyst calendar rows (event, date, H−N, score).
• Fixture: ex-div in 23d with yield + payout flag rendered.

A7 — Master Synthesizer

• Reads: A1–A6 outputs + risk profile + accuracy-ledger weights.
• Steps: (1) weight signals (conservative→fundamental-heavy, aggressive→ technical+broker-heavy); (2) agreement bonus when ≥3 agents align, conflict flag when fundamentals oppose flows; (3) conviction 1–5 from weighted score spread; (4) position size via capped Kelly (max 10% single name); (5) thesis ≤5 sentences, each claim cited.
• Output: BUY/HOLD/AVOID, conviction, size %, thesis, conflict flags.
• Fixture: good fundamental + broker selling → HOLD-or-lower with conflict cited.