Apppublic

FabrizHas/bee-sentinel-x

sourceHugging Faceupdated 4mo agoView on Hugging Face

0likes

App README

🐝 BEE SENTINEL-X

An autonomous, multi-layered decision and paper-trading agent designed for the Kraken xStocks ecosystem. By combining deterministic technical indicators with real-time, AI-driven financial sentiment analysis, Bee Sentinel-X bridges the gap between raw quantitative metrics and macro market catalysts.

The system features an integrated reasoning-to-execution loop powered by Gemini 2.5 Flash and uses the official Kraken CLI binary wrapper for secure, simulated order execution.

🔒 Enterprise-Grade Safety Guard: This architecture is strictly restricted to paper-trading operations. The TRADING_MODE is hardcoded to enforce paper constraints, preventing unauthorized live capital deployment.

🏗️ System Architecture

The project follows a modular, layer-segregated architecture to guarantee strict governance, observability, and decoupled data ingestion.

mermaid

flowchart LR
  A[Scheduler / Dashboard] --> B[Market Data]
  A --> C[RSS Headlines]
  B --> D[Technical Indicators]
  C --> E[Gemini Decision Engine]
  D --> E
  E --> F[Risk Manager]
  F -->|approved| G[Kraken CLI Paper Executor]
  F -->|blocked| H[Audit Log]
  G --> H
  H --> I[Gradio Dashboard]

⚙️ Key Engineering Features

Dual-Channel Ingestion

Synthesizes historical technical asset data alongside unstructured market news catalysts.

Deterministic Risk Gates

A hardcoded validation layer (Confidence Threshold, RSI boundaries, and Asset Custody guards) that overrides AI logic if risk parameters are breached.

Immutability & Auditability

Append-only JSONL event logs capture full execution context, model rationales, and runtime metrics for compliance reviews.

Cloud Native

Fully containerized using a non-root Docker configuration designed for seamless integration with Hugging Face Spaces.

🛠️ Core Capabilities

Watchlist Orchestration

Out-of-the-box support for micro/macro xStocks pairs:

—AAPLx/USD
—TSLAx/USD
—NVDAx/USD
—SPYx/USD
—QQQx/USD

Live Market Fetching

Native streaming of price action through the Kraken CLI binary, utilizing a robust yfinance fallback pipeline for underlying tracking tickers.

Zero-Dependency Sentiment Extraction

High-performance extraction of daily financial articles via Yahoo Finance RSS feeds without restrictive API key limitations.

Structured Generative Intelligence

Implements advanced prompt engineering with strict JSON schemas to guarantee programmatic BUY, SELL, or HOLD agent responses.

Observability Dashboard

Comprehensive user interface engineered in Gradio, exposing cycle-level state diagnostics and historic signal parameters.

💻 Local Installation & Setup

Prerequisites

—Python >= 3.11
—Git

Installation Steps

1. Clone the Repository

bash

git clone https://huggingface.co/spaces/FabrizHas/bee-sentinel-x
cd bee-sentinel-x

2. Create and Activate Virtual Environment

bash

python -m venv .venv

On Windows

powershell

.\.venv\Scripts\Activate.ps1

On macOS/Linux

bash

source .venv/bin/activate

3. Install Dependencies

bash

pip install -e ".[dev]"

4. Configure Environment Variables

Create a .env file from the sample template:

bash

cp .env.example .env

Then open .env and configure your credentials such as:

—GEMINI_API_KEY

⚙️ Environment Parameters

The framework is governed through the following environment variables:

env

GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.5-flash
TRADING_MODE=paper
WATCHLIST=AAPLx/USD,TSLAx/USD,NVDAx/USD,SPYx/USD,QQQx/USD
INITIAL_BALANCE=10000
CONFIDENCE_THRESHOLD=0.80
MAX_POSITION_USD=500
POLL_INTERVAL_SECONDS=300
DATA_DIR=/data

🚀 Command Line Interface (CLI)

Bee Sentinel-X exposes automated CLI commands for management and operations.

System Diagnostic Doctor

Runs internal pathing, credential, and volume sanity checks.

bash

bee-sentinel doctor

Single Cycle Execution

Triggers a manual ingestion, reasoning, and execution cycle.

bash

bee-sentinel run-once

Autonomous Cron Loop

Runs the agent continuously as a background worker according to polling intervals.

bash

bee-sentinel run-loop

Launch UI Command Center

Serves the interactive Gradio dashboard interface.

bash

bee-sentinel dashboard --host 0.0.0.0 --port 7860

📊 Production Observability & Auditing

The system maintains real-time telemetry across three specialized append-only audit files.

`decisions.jsonl`

Stores:

—Market technical inputs
—Sentiment catalysts
—Model confidence
—Risk validation outputs

`trades.jsonl`

Captures:

—Execution commands dispatched to the Kraken CLI wrapper
—System execution feedback

`cycles.jsonl`

Contains:

—Pipeline health statistics
—Runtime intervals
—Operational exceptions

🧪 Quality Assurance & Testing

The package includes a comprehensive test suite focused on:

—Quantitative indicators
—Risk gate containment
—Environment validation

Run tests with:

bash

pytest