backend/README.md

MLStocks Backend

The AI-driven backbone of the MLStocks intelligence platform, orchestrating multi-agent analysis and automated model building.

🚀 Key Features

• Agentic Analyst: A multi-agent team (Market, Sentiment, Strategy, Risk) powered by AutoGen and Google Gemini for real-time options analysis.
• NEXUS Model Builders:
  • NEXUS Quadrant: Classic ML pipeline (Scikit-Learn, XGBoost).
  • NEXUS Neural: Deep Learning engine (PyTorch, LSTMs, Transformers).
• Hugging Face Hub Integration: Automated publishing of trained models with dynamic README/Model Card generation.
• Data Engine: Real-time market data synchronization and technical indicator calculation via Yahoo Finance and ta.

🛠️ Technology Stack

• Framework: FastAPI (Python 3.10+)
• LLM Orchestration: AutoGen (Microsoft)
• AI Models: Google Gemini 2.0/1.5 Flash
• Database: SQLite with SQLAlchemy (Asynchronous)
• ML Frameworks: Scikit-Learn, PyTorch, XGBoost

📦 Setup & Installation

1. Environment Setup:

   python -m venv .venv
   source .venv/bin/activate  # Linux/WSL
   pip install -e .
   

2. Configuration: Create a .env file in the backend/ directory:

   GOOGLE_API_KEY=your_gemini_key
   HF_TOKEN=your_huggingface_token
   SECRET_KEY=your_jwt_secret
   

🏃 Running the Server

python main.py

The API documentation will be available at http://localhost:8000/docs.

📂 Structure

• app/api/: FastAPI route definitions.
• app/agentic_analyst/: Multi-agent team logic and tool definitions.
• app/model_builder/: ML training and publishing orchestration.
• app/core/: Configuration, authentication, and model factory.
• app/models/: Database schema and Pydantic models.