SENTINEL: Transcendent Market Intelligence

SENTINEL is an institutional-grade financial market intelligence platform combining deep learning price forecasting, natural language processing for sentiment analysis, Bayesian belief networks, and epistemic uncertainty filters.

Instead of operating as a traditional automated execution bot, SENTINEL acts as a cognitive market analysis organism. It integrates technical price regression with NLP sentiment analysis, multi-timeframe regime detection, and safety governance—including an Epistemic Humility Protocol and Silence Intelligence that suppresses predictions when market ambiguity exceeds quantifiable confidence thresholds.

Architecture Overview

The system operates across a 6-tier intelligence pipeline orchestrated by the Fusion Engine:

┌─────────────────────────────────────────────────────────────────┐
│               WEB DASHBOARD (Next.js 16 + React 19)              │
│       Framer Motion · Tailwind CSS · Holographic Fallback       │
└────────────────────────────────┬────────────────────────────────┘
                                 │ HTTP (REST)
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                FASTAPI NEURAL CORTEX (main.py)                  │
│                     Port 8000 · CORS Enabled                    │
└────────────────────────────────┬────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                    TIER 4-6: COGNITIVE GOVERNANCE               │
│  • Transcendent Intelligence (Epistemic awareness, daily budget) │
│  • Omega Intelligence (Silence protocol & ambiguity suppression)│
│  • Elite Governance (Hard risk filters & decision audit)        │
└────────────────────────────────┬────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                 TIER 1-3: FUSION & INFERENCE ENGINE             │
│  • Bayesian Belief Networks (Prior/Posterior Regime Odds)       │
│  • Decision Quality (Drawdown-aware confidence estimation)      │
│  • Fusion Aggregation: 0.6 × LSTM + 0.4 × Sentiment             │
└──────────────────┬──────────────────────────────┬───────────────┘
                   │                              │
                   ▼                              ▼
      ┌─────────────────────────┐   ┌───────────────────────────┐
      │   LSTM TREND PREDICTOR  │   │     FINBERT SENTIMENT     │
      │ • PyTorch 2-layer LSTM  │   │ • Hugging Face FinBERT    │
      │ • 60-day rolling window │   │ • TextBlob / VADER fallback│
      └────────────┬────────────┘   └─────────────┬─────────────┘
                   │                              │
                   └──────────────┬───────────────┘
                                  ▼
                   ┌─────────────────────────────┐
                   │       DATA INGESTION        │
                   │ • Yahoo Finance (yfinance)  │
                   │ • Alpha Vantage Connector   │
                   └─────────────────────────────┘

The 6 Intelligence Tiers

Tier	Name	Core Functionality	Primary Components
Tier 1	Core Analytic	Price trend regression & short-term trajectory	PyTorch 2-layer LSTM (`lstm_model.py`), `yfinance` data loader (`stock_data.py`)
Tier 2	Contextual	Multi-timeframe trend alignment & sentiment	FinBERT NLP model (`sentiment_engine.py`), Reddit/news ingestors (`fetch_social.py`)
Tier 3	Decision Quality	Capital preservation and confidence weighting	Drawdown-aware penalty model (`decision_quality.py`), Bayesian belief network (`bayesian_belief.py`)
Tier 4	Elite Governance	Institutional rules, bounds, and audit checks	Hard risk constitution (`elite_governance.py`), guardrails (`advanced_guardrails.py`)
Tier 5	Omega Sentience	Silence protocol & ambiguity discrimination	Silence Intelligence (`omega_intelligence.py`), uncertainty tools (`uncertainty_tools.py`)
Tier 6	Transcendent	Epistemic awareness, cognitive budgeting, ethics	Daily insight budgeting (`transcendent_state.json`), moral restraint (`transcendent_intelligence.py`)

Implemented Features

Sequential Deep Learning Forecasts: 2-layer PyTorch LSTM model trained on 60-day rolling OHLCV windows to estimate expected price trajectories.
Financial NLP Sentiment: Sentiment classification using Hugging Face Transformers (ProsusAI/finbert) with automatic fallback to VADER and TextBlob when GPU/model weights are unavailable.
Bayesian Belief Networks: Dynamic probability distributions evaluating likelihood across Bullish, Neutral, and Bearish regimes.
Epistemic Humility & Silence Protocol: Automatically silences buy/sell signals when epistemic ambiguity (unknown unknowns) exceeds risk thresholds, preventing over-trading during regime shifts.
Daily Insight Budgeting: Limits cognitive inferences to preserve high conviction hypotheses and reduce noise amplification.
Hybrid Deployment Support: Fully decoupled web dashboard (Next.js) and computation core (FastAPI), with built-in client-side holographic mock telemetry for offline demonstration.
Multi-Asset Telemetry: Pre-configured analysis targets for BTC-USD, AAPL, TSLA, MSFT, ^NSEI, and ^NSEBANK.
Offline CLI Inference: Standalone command-line inference tool (cli_predict.py) for rapid local queries without launching the UI.

Tech Stack

Backend & AI Engine

Language: Python 3.10+ (tested on Python 3.12)
Deep Learning: PyTorch (torch), Scikit-learn
NLP: Hugging Face Transformers (transformers), VADER (vaderSentiment), TextBlob
API Framework: FastAPI, Uvicorn, Pydantic
Statistical Modeling: SciPy, NumPy, Pandas
Data Providers: Yahoo Finance (yfinance), Alpha Vantage (alpha_conn.py), PRAW (Reddit API)

Frontend Dashboard

Framework: Next.js 16.1 (App Router, Turbopack)
Library: React 19.2
Language: TypeScript 5
Styling: Tailwind CSS v4
Animation & Visuals: Framer Motion 12, Lucide React, Recharts 3

Repository Structure

.
├── backend/                        # Python AI & API Engine
│   ├── modules/                    # Core Intelligence Modules
│   │   ├── advanced_analysis.py    # Multi-factor market analytics
│   │   ├── advanced_guardrails.py  # Runtime boundaries & execution constraints
│   │   ├── alpha_conn.py           # Alpha Vantage integration connector
│   │   ├── backtest_tracker.py     # Prediction history logger
│   │   ├── bayesian_belief.py      # Bayesian belief network & regime odds
│   │   ├── database.py             # SQLite persistence utility
│   │   ├── decision_quality.py     # Confidence decay and drawdown scoring
│   │   ├── elite_governance.py     # Hard risk constitution & compliance
│   │   ├── fusion.py               # Central ensemble fusion engine
│   │   ├── lstm_model.py           # PyTorch 2-layer LSTM sequential model
│   │   ├── omega_intelligence.py   # Silence protocol & ambiguity filter
│   │   ├── sentiment_engine.py     # FinBERT and lexical sentiment analyzer
│   │   ├── stock_data.py           # Market data ingestion (yfinance)
│   │   ├── transcendent_intelligence.py # Epistemic budget & ethics engine
│   │   └── uncertainty_tools.py    # Entropy & epistemic bounds tools
│   ├── data/                       # State and data ingestion scripts
│   │   ├── fetch_prices.py         # Standalone price fetch utility
│   │   ├── fetch_social.py         # Standalone Reddit/social scraper
│   │   └── transcendent_state.json # Daily cognitive budget state store
│   ├── .env.example                # Template for external API credentials
│   ├── cli_predict.py              # CLI entry point for predictions
│   ├── list_models.py              # Model directory / inspection script
│   ├── main.py                     # FastAPI server entry point
│   ├── requirements.txt            # Complete Python dependencies
│   ├── requirements_lite.txt       # Lightweight dependencies (no PyTorch/Transformers)
│   └── test_system.py              # System self-verification test script
├── data/                           # Reference test fixtures & backtest data
│   ├── backtest_history.json       # Historical prediction log
│   └── raw/                        # Sample reference CSVs (BTC-USD OHLCV & sentiment)
├── frontend/                       # Next.js Web Dashboard
│   ├── app/
│   │   ├── actions.ts              # Server action connecting UI to FastAPI / mock
│   │   ├── globals.css             # Tailwind CSS imports & theme definitions
│   │   ├── layout.tsx              # Root HTML layout with Geist font
│   │   └── page.tsx                # Dashboard interface with real-time telemetry
│   ├── lib/
│   │   ├── mockData.ts             # Holographic telemetry mock payload
│   │   └── utils.ts                # Class merging (clsx + tailwind-merge)
│   ├── public/                     # Static assets (favicon.png)
│   ├── eslint.config.mjs           # ESLint 9 configuration
│   ├── next.config.ts              # Next.js configuration
│   ├── package.json                # Frontend package dependencies & scripts
│   ├── postcss.config.mjs          # PostCSS configuration
│   └── tsconfig.json               # TypeScript configuration
├── .gitignore                      # Git exclusion rules
├── LICENSE                         # MIT License
├── PRODUCTION_DEPLOYMENT.md        # Cloud deployment guide (Render + Vercel)
├── README.md                       # Repository documentation
├── SYSTEM_GUIDE.md                 # Detailed architectural walkthrough
└── TRANSCENDENT_VISION.md          # Theoretical paper on the 6-tier architecture

Prerequisites

Node.js: 18.18+ or 20+ (verified with Node.js 26)
npm: 9+ (verified with npm 11)
Python: 3.10+ (tested with Python 3.12)
Git

Installation & Setup

1. Clone Repository

git clone https://github.com/nfsprogramming/Sentinel-Intelligence.git
cd Sentinel-Intelligence

2. Frontend Setup

cd frontend
npm install
npm run dev

The web dashboard is now accessible at http://localhost:3000. By default, if the backend server is offline, the frontend operates in Holographic Demo Mode, displaying verified sample telemetry.

3. Backend Setup (Optional for Full Local AI Execution)

Open a separate terminal window:

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# Install dependencies (for complete deep learning & NLP pipeline):
pip install -r requirements.txt

# Or for lightweight testing without PyTorch / Transformers:
# pip install -r requirements_lite.txt

# Configure environment variables (optional):
cp .env.example .env

To run the FastAPI server:

python main.py

The API starts at http://127.0.0.1:8000.

Usage

Web Interface

Launch both the backend (python main.py) and frontend (npm run dev).
Open http://localhost:3000.
Select an asset (BTC-USD, AAPL, TSLA, MSFT, ^NSEI, ^NSEBANK) or click Run Market Analysis.
Review the 6-tier telemetry:
- Regime Classification: Current market phase and volatility state.
- Bayesian Distribution: Bullish, Neutral, and Bearish posterior probabilities.
- Silence Status: Indicates whether the Omega tier has approved or suppressed signal output.
- Cognitive Budget: Inferences consumed vs. daily quota.

Command Line Interface

To run predictions directly from the terminal without the web server:

cd backend
python cli_predict.py --ticker BTC-USD

Testing & Validation

Frontend Verification

cd frontend
npm run lint    # ESLint check (passes with 0 errors)
npm run build   # Next.js production build verification

Backend Verification

With the Python environment active:

cd backend
python test_system.py

Limitations

Proprietary Bounds: As noted in institutional filings, high-frequency execution drivers and proprietary alpha weights for real-money execution are decoupled from this public repository.
First-Run Weight Download: Initial execution of test_system.py or main.py requires downloading the FinBERT model weights (~440 MB) from Hugging Face.
API Rate Limits: Yahoo Finance and Reddit APIs impose rate limits during high-frequency querying. For continuous production streaming, dedicated API keys should be populated in backend/.env.

Contributing

Fork the repository.
Create a feature branch (git checkout -b feature/improvement).
Ensure all tests and linting pass (npm run lint and npm run build in frontend/).
Commit your changes (git commit -m "Add feature").
Push to the branch (git push origin feature/improvement).
Open a Pull Request.

Navigation Menu

Repository navigation

README.md

README.md

SENTINEL: Transcendent Market Intelligence

Architecture Overview

The 6 Intelligence Tiers

Implemented Features

Tech Stack

Backend & AI Engine

Frontend Dashboard

Repository Structure

Prerequisites

Installation & Setup

1. Clone Repository

2. Frontend Setup

3. Backend Setup (Optional for Full Local AI Execution)

Usage

Web Interface

Command Line Interface

Testing & Validation

Frontend Verification

Backend Verification

Limitations

Contributing

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

SENTINEL: Transcendent Market Intelligence

Architecture Overview

The 6 Intelligence Tiers

Implemented Features

Tech Stack

Backend & AI Engine

Frontend Dashboard

Repository Structure

Prerequisites

Installation & Setup

1. Clone Repository

2. Frontend Setup

3. Backend Setup (Optional for Full Local AI Execution)

Usage

Web Interface

Command Line Interface

Testing & Validation

Frontend Verification

Backend Verification

Limitations

Contributing

License