Database & Storage

The system utilizes a hybrid storage architecture to manage structured trading data, unstructured research knowledge, and historical performance reports. It relies on SQLAlchemy for relational data, Vector Stores (ChromaDB) for RAG-based analysis, and JSON for local backtesting logs.

Relational Database (SQLAlchemy)

The core application data is managed via SQLAlchemy, supporting persistence for backtest results and live trade history. This allows the Dashboard to retrieve historical performance and agent reasoning.

Core Models

• Backtest: Stores the parameters and aggregate results of a backtesting run, including initial capital, final value, and performance metrics (Sharpe Ratio, Max Drawdown).
• Trade / BacktestTrade: Records individual executions. Each record includes the asset, action (BUY/SELL), price, quantity, and critically, the agent reasoning and confidence level at the time of the trade.

Database Session Management

To interact with the database in a custom script or backend extension, use SessionLocal:

from database import SessionLocal, Trade

# Create a new session
session = SessionLocal()

# Query latest trades
recent_trades = session.query(Trade).order_by(Trade.timestamp.desc()).limit(10).all()

for trade in recent_trades:
    print(f"{trade.timestamp}: {trade.action} @ {trade.price}")

session.close()

Knowledge Vector Store (RAG)

Unstructured data—such as research papers, technical analysis guides, and market philosophy—is stored in a Vector Database. This enables agents to perform Retrieval-Augmented Generation (RAG) to ground their decisions in academic and historical context.

Knowledge Domains

The system partitions knowledge into specialized domains to ensure agents retrieve relevant context:

• technical: Technical analysis patterns and indicator definitions.
• sentiment: Market psychology and social sentiment theory.
• fundamental: Network health and valuation models.
• risk: Position sizing and portfolio management strategies.
• papers: Academic PDFs and research summaries.

Indexing New Knowledge

To add new documents to the agent's knowledge base, place .md or .txt files in the knowledge/ folder and run the indexer:

from agents.rag.indexer import KnowledgeIndexer

indexer = KnowledgeIndexer()
# Indexes files into domain-specific vector stores
stats = indexer.index_all() 
print(f"Indexed {stats['technical']} chunks for Technical Analysis.")

Backtest Report Storage

When a backtest is executed, the system generates a detailed JSON report in the logs/ directory. These files serve as a portable record of the strategy's performance before they are persisted to the relational database.

Report Structure

Reports include:

1. Metadata: Start/End dates, initial capital.
2. Trade Log: A list of every entry and exit with associated PnL.
3. Equity Curve: A timestamped series of portfolio values vs. Benchmark (BTC).

Viewing Reports via CLI

You can inspect the most recent backtest results using the provided utility script:

# Displays the trade log and P/L for the latest backtest
python view_trades.py

API Data Access

The Dashboard Backend provides structured endpoints to query this data for the frontend.

| Endpoint | Description | | :--- | :--- | | GET /api/backtests | Returns a list of all stored backtest summaries. | | GET /api/backtests/{id} | Returns detailed metrics, equity curves, and trade history for a specific run. | | WS /ws | A WebSocket connection for receiving real-time trade updates. |

Example: Trade Schema

All trades (both live and backtested) follow a consistent Pydantic schema for the API:

{
  "id": 101,
  "timestamp": "2023-10-27T14:30:00",
  "asset": "BTC",
  "action": "BUY",
  "price": 45000.0,
  "reasoning": "RSI shows oversold conditions while fundamental network growth remains strong.",
  "confidence": 85
}