Zoris Engine

Quantitative intelligence, risk prediction, and autonomous portfolio management engine for the Jamaica Stock Exchange.

Overview

The Zoris Engine is a distributed quantitative trading system that aggregates JSE market telemetry, calculates risk-weighted predictions using an XGBoost model augmented by a Kronos time-series foundation model, and autonomously manages a virtual portfolio with liquidity-gated execution.

The engine operates across three infrastructure nodes on GCP and DigitalOcean, delivering real-time market intelligence, autonomous trade execution with liquidity rails, and an institutional-grade dashboard.

Architecture

The Zoris Engine is composed of three primary nodes:

Telemetry Node (GCP)

The lightweight upstream scraper responsible for end-of-day data extraction. It connects to the Jamaica Stock Exchange at market-close intervals to extract price data, trade summaries, and fundamental metrics, then delivers payloads via secure transfer to the Compute Core.

Runtime: Python 3.10+
Key Modules: Price scraper, trade breadth scraper, fundamentals scraper
Delivery: Secure payload transfer to the Compute Core
Cron: 16:00 EST weekdays

Compute Core (DigitalOcean)

The primary brain. Runs a FastAPI server containing the risk prediction engine, sentiment analysis, news intelligence, autonomous trade executor (with liquidity rails), and the API gateway.

Runtime: Python 3.12 / Uvicorn ASGI
Key Modules: Brain (XGBoost + Kronos), Sentiment Engine, News Intelligence, Autonomous Executor, Morning Intel
Port: Internal service port
Cron: Pipeline at 16:15 EST weekdays; Morning Intel at 07:00 EST weekdays; Macro weekly Mondays 09:00 EST

Frontend Node (DigitalOcean)

The client-facing Next.js dashboard served via Nginx reverse proxy.

Runtime: Node.js 18+ / Next.js 14
Reverse Proxy: Nginx with cache-busting headers
Key Components: Dashboard, AI Portfolio view, Asset detail view, Theme context

Data Flow

â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”    secure     â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
â”‚  Telemetry Node â”‚   transfer    â”‚   Compute Core   â”‚
â”‚  (GCP Scraper)  â”‚ â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â–º  â”‚   (FastAPI)      â”‚
â”‚                 â”‚               â”‚   + Brain        â”‚
â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜               â”‚   + Executor     â”‚
                                  â””â”€â”€â”€â”€â”€â”€â”€â”€â”¬â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜
                                           â”‚
                                    REST/JSON â”‚
                                           â–¼
                                  â”Œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”
                                  â”‚  Frontend Node   â”‚
                                  â”‚  (Next.js)       â”‚
                                  â””â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”˜

Authentication

All API endpoints are protected by X-API-Key header authentication. The engine supports two classes of credentials:

Admin Key (zoris-admin-<hex>): Full access to all endpoints including key generation and portfolio history. Stored in server-side environment variables only. Never shared or committed to version control.
Client Keys (zoris-sk-<hex>): Issued per-client via the admin endpoint POST /api/keys/generate. Scoped by subscription tier (STANDARD, PRO, INSTITUTIONAL) with configurable access to macro datasets.

Key rotation is performed periodically. Compromised keys are invalidated immediately and replaced.

AI Prediction Pipeline

The engine uses a two-layer prediction system:

Layer 1: Kronos Foundation Model

A time-series foundation model (Kronos-small) that generates probability-of-upward-move estimates for each symbol based on 200-day lookback windows. These predictions are cached daily and serve as a feature input to the XGBoost model.

Layer 2: XGBoost Risk Model

A gradient-boosted decision tree model trained on 14 features including RSI, Bollinger Band metrics, momentum signals, sentiment scores, and Kronos probability estimates. The model produces:

Zoris Score (0-100): Conviction metric for each instrument
Action: LONG / HOLD / AVOID
Position Weight: Risk-adjusted allocation fraction
Ranking Tercile: TOP / MIDDLE / BOTTOM / ILLIQUID

Model Performance

Binary accuracy: 56.6% | 3-class: 51.3% | Movers: 56.6%
Walk-forward validated with no train/test leakage
Retrained every 5 days (warm-start)

Liquidity Rail

The autonomous executor enforces a 4-gate entry system to ensure all positions can be exited based on real market conditions:

Gate	Threshold	Purpose
ADV_20	>= 5,000 shares	Sufficient average daily volume (20-day)
Today's Volume	> 0	Stock actively trading
Bid-Ask Spread	<= 5%	Exit friction cap
Position Size	<= 15% of ADV_20	Exitable within ~7 trading days

Exit rail for existing positions:

TRAPPED (zero volume): flagged, excluded from liquid equity calculations
SLOW_EXIT (>5 days to exit): partial exit capped at 25% of daily volume
HIGH_SPREAD (>10% spread): exit proceeds discounted by spread percentage
Liquid Equity = total equity minus illiquid discounts; used for all new position sizing

API Reference

Market Intelligence

`GET /api/market/latest`

Returns the latest normalized market statistics for all tracked JSE instruments including price, AI predicted return, Zoris Score, and RSI.

`GET /api/market/history/{symbol}`

Returns chronological price, volume, and technical indicator history for a given JSE ticker. Supports all instruments on the JSE.

Portfolio Management

`GET /api/portfolio`

Returns all portfolio positions with current values.

`GET /api/portfolio/summary`

Returns aggregate portfolio metrics including total equity, cash balance, and position breakdown.

`GET /api/portfolio/trade`

Returns the trade history for the portfolio.

`POST /api/portfolio/trade`

Executes a manual trade (buy/sell) with quantity and price.

`POST /api/portfolio/upload-pdf`

Uploads a JSE Account Statement PDF to parse and sync portfolio positions.

`POST /api/portfolio/upload-research`

Uploads market research for intelligence analysis.

PDF Reports

`GET /api/quant-briefing.pdf`

Returns the Daily Quant Briefing report as a PDF document. Contains system performance metrics, JSE market sentiment, top AI signals ranked by Zoris Score, and AI portfolio summary.

`GET /api/compliance-report.pdf`

Returns the Compliance & Risk Disclosure report as a PDF document. Contains risk disclosures, model performance metrics, trade audit trail, regulatory notices, and document certification.

AI Performance

`GET /api/ai/performance`

Returns AI prediction accuracy metrics: binary accuracy, 3-class accuracy, movers accuracy, and average error.

Suggestions

`GET /api/suggestions`

Returns pending position suggestions generated by the morning intel engine.

`POST /api/suggestions/{id}/confirm`

Confirms and executes a pending suggestion.

`POST /api/suggestions/{id}/reject`

Rejects a pending suggestion.

Macro Intelligence (Pro/Institutional)

`GET /api/macro_insights`

Returns national speculation parameters from ABIS, STATIN, and PIOJ.

Administrative (Master Key Only)

`POST /api/keys/generate`

Mints a new B2B client API key for institutional access.

Database Architecture

The engine uses domain-segregated SQLite stores:

Database	Purpose	Key Fields
Portfolio DB (SQLite)	Position tracking, trade history, cash balance	`symbol`, `quantity`, `cost_basis`, `purchase_date`
AI Portfolio DB (SQLite)	Autonomous executor positions and history	`symbol`, `quantity`, `cost_basis`, `justification`
Client DB (SQLite)	API key authentication	`key_string`, `client_name`, `created_at`

All historical data is append-only. New entries are added with timestamps; existing records are never overwritten.

Pipeline Schedule

Time (EST)	Stage	Description
16:00	T0	Telemetry scrapes JSE end-of-day prices, trade summaries, fundamentals
16:15	T1	Main pipeline: News intelligence, sentiment, brain, LLM, executor
07:00	T2	Morning Intel: Pre-market trade suggestions
09:00 Mon	T3	Macro aggregator + model (weekly)

Pipeline Steps (16:15 EST)

Pre-flight: Verify GCP data arrived
Institutional Intelligence Cycle (news + PDF ingestion)
Sentiment Composite generation
Risk and Prediction calculation (XGBoost + Kronos)
LLM analysis and notification
Autonomous trade execution (with liquidity rails)

License

Was this page helpful?

Last updated today

Built with Documentation.AI