🚀 AI Senticor Engine

AI-Powered Market Sentiment & Volatility Intelligence Platform

A cutting-edge financial analysis tool that combines sentiment analysis from FinBERT AI with real-time market data to provide actionable insights for stock trading and portfolio management.

Keywords: sentiment analysis, stock market, AI trading, FinBERT, financial analysis, volatility analysis, RAG, vector database, LLM, market intelligence, technical analysis, stock screening, alpha detection, quantitative finance, machine learning, NLP, financial AI, trading signals, market sentiment

⚠️ DISCLAIMER This repository was developed with the assistance of AI tools and is intended for educational and research purposes only. The code, models, and recommendations provided herein should not be used in production environments or for actual trading decisions without thorough review, validation, and testing by qualified professionals. No warranty is provided regarding accuracy, reliability, or suitability for any particular purpose. Users assume all risks associated with the use of this software.

---

❓ Why This Project

Real-world demonstration of production-grade AI engineering applied to financial market intelligence:

• Bridge AI & Finance: Practical application of LLMs, RAG, vector databases, and NLP transformers in quantitative finance
• End-to-End Product Thinking: From data ingestion → AI analysis → interactive visualization → professional reporting
• Engineering Excellence: Showcasing async architecture, comprehensive testing (114 tests, 76% coverage), CI/CD, and modular design patterns

🚀 Project Highlights

Business Impact:

• Alpha Detection Engine: Auto-identifies high-sentiment, low-volatility opportunities with intelligent risk scoring
• Market Intelligence Map: Interactive quadrant visualization revealing strategic positioning across 4 zones: Alpha, Hype, Danger, Oversight.
• Professional PDF Reports: Client-ready analysis with market map visualization and actionable insights
• Competitive Analysis Agent: Autonomous peer-universe research with sector narrative, confidence scoring, and competitive PDF export

AI/ML Engineering:

• FinBERT Sentiment Analysis: Fine-tuned transformer model (ProsusAI) for financial news sentiment scoring
• RAG Sector Insights: ChromaDB vector search + LLM generation for sector-wide commentary
• Config-Driven Sector Control: Dedicated Sector News tab for Sector DB operations plus Config tab for editable ticker-sector mapping
• Multi-LLM Support: Provider abstraction layer with graceful fallback (OpenAI/Anthropic/HuggingFace FREE models)
• Multi-Agent Orchestration: Lightweight asyncio supervisor with specialized worker agents for autonomous sector research

Technical Architecture:

• 10x Faster with Async: Parallel processing across 50+ tickers using asyncio patterns
• Startup Performance Telemetry: Initial load now emits per-step timing logs (page config, session init, sidebar, tabs) visible in the Logs tab
• Testing Excellence: 114 unit tests with mocking, fixtures, edge cases (timeout, rate limits, malformed data)
• CI/CD Pipeline: GitHub Actions with automated lint, test, coverage, and security scanning using uv for 10-100x faster builds
• Security First: Automated security scanning with Bandit, Safety, pip-audit, and Trivy; SARIF results uploaded to GitHub Security
• Code Quality: Pre-commit hooks (Black, isort, flake8, mypy) ensuring consistent, production-ready code

---

�🖼️ Demo

Interactive UI Walkthrough - See the platform in action with real-time sentiment analysis, quadrant mapping, and intelligent insights. More screenshots (PNG) are available in docs/images/ for full-resolution stills and reference.

View Sample PDF Report - Professional market analysis report generated by the platform

The Senticor Market Map positions stocks in four strategic zones:

• 🟢 Alpha Zone: Positive sentiment + Low volatility
• 🔵 Hype Zone: Positive sentiment + High volatility
• 🔴 Danger Zone: Negative sentiment + High volatility
• ⚪ Oversight: Negative sentiment + Low volatility

---

📊 Technology Stack & Architecture

Tech Stack: Streamlit, FinBERT (Transformers), LangChain, ChromaDB, OpenBB Platform, Plotly, Pytest

Architecture: Modular layered design with separation between presentation, business logic, and utilities.

👉 For detailed system architecture, module breakdown, and data flows, see docs/ARCHITECTURE.md

👉 For the new Competitive Analysis Agent workflow and output schema, see docs/COMPETITIVE_ANALYSIS.md

👉 New to the project? Start with the comprehensive learning guide: docs/LEARNING_GUIDE.md

---

📱 Mobile Support

The Senticor Engine UI is fully responsive and optimized for mobile devices! Access your market intelligence on-the-go with:

• Auto-responsive layouts that stack on mobile (< 768px)
• Touch-friendly controls with minimum 44x44px touch targets
• Collapsible sidebar for maximum screen real estate
• Responsive charts that scale to fit any screen size
• Optimized typography with device-specific font sizes

📖 See full mobile features and testing guide: docs/MOBILE.md

Quick Mobile Access:

# Run Streamlit with network access
streamlit run src/app.py --server.address 0.0.0.0

# Then visit from your mobile device:
# http://<your-computer-ip>:8501

---

🛠️ Installation

Prerequisites

• Python 3.11 or higher
• pip package manager
• Virtual environment (recommended)

Quick Start

# Clone the repository
git clone https://github.com/yourusername/ai-senticor-engine.git
cd ai-senticor-engine

# Create virtual environment
python -m venv .venv

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

# Install dependencies
pip install -r requirements.txt

# Run the application
streamlit run src/app.py

� Privacy Configuration (Recommended)

To prevent Streamlit from sending usage statistics, create or edit the config file:

# Create the Streamlit config directory
mkdir -p ~/.streamlit  # On Windows: %USERPROFILE%\.streamlit

# Add the following to ~/.streamlit/config.toml
[browser]
gatherUsageStats = false

This disables telemetry and keeps your usage data private.

�🔑 API Key Configuration

Some data providers require API keys. OpenBB Platform uses a centralized credential system.

Environment Variables

# Create a .env file in the project root
OBB_FMP_API_KEY=your_fmp_key_here
OBB_POLYGON_API_KEY=your_polygon_key_here
OBB_BENZINGA_API_KEY=your_benzinga_key_here
OBB_ALPHA_VANTAGE_API_KEY=your_av_key_here

Provider-Specific Keys:

• FMP (Financial Modeling Prep): Get free key
• Polygon.io: Get free key
• Benzinga: Get key
• Alpha Vantage: Get free key
• Intrinio: Get key

Note: Yahoo Finance (yfinance) does not require an API key.

---

📖 Usage

Basic Workflow

1. Launch the App

   streamlit run src/app.py

2. Configure RAG Sector Analysis (Optional)

   • Enable/disable Sector News Analysis in the sidebar
   • Select LLM provider: HuggingFace (Free), OpenAI, or Anthropic
   • Choose model and temperature settings

3. Configure Ticker-Sector Mapping

   • Open the "⚙️ Config" tab
   • Edit the Ticker-Sector Mapping table (add/remove tickers or update sectors)
   • Click Save Mapping Changes
   • Sidebar tickers are read-only and automatically sourced from this mapping table

4. Run Analysis

   • Click "🚀 Run Engine" to fetch data and generate insights
   • Alpha flags automatically appear in sidebar

5. Explore Results

   • View the Market Map for overall positioning with sortable market summary
   • Check "🎯 Alpha Flags" in the sidebar for top opportunities
   • Use "Company Intelligence" tab for detailed stock analysis with risk-adjusted recommendations
   • Use "Competitive Analysis" tab for peer-universe intelligence, signal comparison, and confidence-scored narrative
   • Use the "📰 Sector News" tab for:
     • Sector DB controls (clear DB, load all sector news)
     • Lookback window selection from 1D to 1M (default 7D)
     • Browsing all persisted sector news with filtering
   • Use the "⚙️ Config" tab for persistent ticker-sector mapping management
   • Use the "📋 Logs" tab to inspect startup timing breakdown on first load (helps identify slow initialization steps)

Mapping Persistence

• Custom ticker-sector overrides are persisted locally at data/custom_sector_mapping.json
• Overrides are loaded automatically on app startup/rerun
• Reset in Config clears both session state and the JSON override file

6. Generate Report
   • Download PDF report for documentation or presentations
   • Download Competitive PDF report from the Competitive Analysis tab

---

📁 Project Structure

see docs/ARCHITECTURE.md

🔧 Configuration

All configuration is centralized in src/config.py for easy customization:

• LLM Providers: Configure OpenAI, Anthropic, or HuggingFace models
• Risk Thresholds: Adjust alpha detection sentiment/volatility thresholds
• Data Sources: Switch between yfinance, Polygon, FMP, and other providers
• Visualization: Customize chart heights, colors, and quadrant zones
• Analysis Parameters: Configure headline counts, trading days, temperature settings

For detailed RAG and sector news configuration, see docs/RAG_SECTOR_NEWS.md.

---

🚀 Deployment

Docker

# Dockerfile included in repository
docker build -t senticor-engine .
docker run -p 8501:8501 senticor-engine

---

Testing & CI ✅

Run tests locally:

python -m pytest -q

CI runs automatically at .github/workflows/ci.yml on push and PRs.

---

Contributing & Support 🤝

• See CONTRIBUTING.md for contribution guidelines and how to run tests.
• File issues or feature requests at the repo Issues page.
• For quick questions, open an issue and tag maintainers.

---

License 📜

MIT — see LICENSE for details.

---

🙏 Acknowledgments

• FinBERT: ProsusAI for the financial sentiment model
• OpenBB: For providing comprehensive financial data API
• Streamlit: For the amazing web framework

---

🔮 Roadmap

See docs/ROADMAP.md for the complete product roadmap.

Upcoming Highlights:

• 🤖 Competitive Analysis Agent v2.0 - Extend current shipped multi-agent pipeline with LangGraph memory, hypothesis generation/testing, and deeper pattern mining
• 📊 Backtesting Engine - Historical performance analysis with Sharpe ratio, max drawdown, and strategy validation
• 🔄 Real-time Streaming - WebSocket integration for live price updates and sentiment feeds
• 📈 Portfolio Optimizer - Modern Portfolio Theory (MPT) with efficient frontier calculation
• 🎯 ML Volatility Forecasting - LSTM/GARCH models for volatility prediction with uncertainty quantification
• 📧 Alert System - Configurable notifications via email/SMS/Slack for alpha opportunities
• 🔐 User Authentication - Multi-user support with portfolio tracking and personalized watchlists
• 📱 API Backend - REST/GraphQL API for programmatic access and third-party integrations

---

⭐ If you find this project useful, please consider giving it a star!