How rayensebei/bvmt-market-surveillance works
BVMT Market Surveillance screens stored Tunisian market observations for unusual price or volume activity, enriches flags with news and review context, and presents a human-review queue through a read-only Flask API and React Terminal. Separate evaluation tooling measures detector results against sourced events and baselines. The README documents the overall pipeline and product capabilities; sampled source supports selected API, detector, and UI relationships, while unsampled implementation details are not inferred.
Main entry points: App.tsx Terminal navigation · evaluate.py Event evaluation · bvmt_data Stored market and news CSVs · app.py Read-only Flask API
Components 29
Data collection
- BVMT observations
- ilboursa news
- Market scraper
src/scraping/scrape_ilboursa.py - News scraper
src/scraping/scrape_news.py - Stored market and news CSVs
bvmt_data
Screening and review
- Rolling anomaly detector
src/detection/anomaly_detector.py - Decay detector
src/detection/decay_detector.py - Candidate detectors
src/detection/candidates_v2.py - News and event cross-reference
src/detection/crossref_legal_events.py - Flag classification
src/validation/classify_anomalies.py - Watchlist refinement
src/validation/refine_watchlist.py - Optional AI triage
src/triage/ai_triage_free.py - Groq service
Evaluation
- Event evaluation
src/evaluation/evaluate.py - Baselines and sensitivity
src/evaluation/baselines.py - Phase 2 comparison
src/evaluation/phase2.py - Evaluation report
src/evaluation/report.py
Analyst Terminal
- Read-only Flask API
app.py - Presentation aggregates
src/dashboard.py - Terminal navigation
frontend/src/App.tsx - API client
frontend/src/lib/api.ts - Overview and market map
frontend/src/pages/OverviewPage.tsx - Anomaly feed
frontend/src/pages/FeedPage.tsx - Stock detail
frontend/src/pages/StockPage.tsx - News view
frontend/src/pages/NewsPage.tsx - Watchlist view
frontend/src/pages/WatchlistPage.tsx - Pipeline view
frontend/src/pages/PipelinePage.tsx - Evaluation view
frontend/src/pages/EvaluationPage.tsx
Other components
- Human analyst
Connections 29
- BVMT observations → Market scraper: provides data
README.md - ilboursa news → News scraper: provides news
README.md - Market scraper → Stored market and news CSVs: updates files
src/scraping/scrape_ilboursa.py - News scraper → Stored market and news CSVs: stores news
README.md - Stored market and news CSVs → Rolling anomaly detector: feeds observations
README.md - Rolling anomaly detector → News and event cross-reference: flags for context
README.md - Decay detector → Watchlist refinement: adds decay flags
README.md - News and event cross-reference → Flag classification: provides context
README.md - Flag classification → Watchlist refinement: refines queue
README.md - Watchlist refinement → Optional AI triage: offers draft triage
README.md - Optional AI triage → Groq service: requests opinion
README.md - Stored market and news CSVs → Event evaluation: supplies evaluation data
README.md - Event evaluation → Baselines and sensitivity: compared with
src/evaluation/full_universe.py - Event evaluation → Phase 2 comparison: evaluates candidates
src/evaluation/phase2.py - Event evaluation → Evaluation report: feeds results
src/evaluation/report.py - Stored market and news CSVs → Read-only Flask API: serves stored files
README.md - Read-only Flask API → Presentation aggregates: builds read views
app.py - Presentation aggregates → Read-only Flask API: returns aggregates
app.py - Human analyst → Terminal navigation: uses Terminal
README.md - Terminal navigation → API client: requests data
frontend/src/App.tsx - API client → Read-only Flask API: fetches API
frontend/src/lib/api.ts - Terminal navigation → Overview and market map: routes views
frontend/src/App.tsx - Terminal navigation → Anomaly feed: routes views
frontend/src/App.tsx - Terminal navigation → Stock detail: routes views
frontend/src/App.tsx - Terminal navigation → News view: routes views
frontend/src/App.tsx - Terminal navigation → Watchlist view: routes views
frontend/src/App.tsx - Terminal navigation → Pipeline view: routes views
frontend/src/App.tsx - Terminal navigation → Evaluation view: routes views
frontend/src/App.tsx - Event evaluation → Evaluation view: exposes results
README.md