Agentic Tooling

The agentic tooling layer provides the bridge between LLM-based reasoning and the data-driven reality of financial markets. These tools enable agents to fetch real-time news, query historical knowledge bases, perform precise mathematical calculations for risk management, and generate structured analysis reports.

Data Connectors

NewsAPIConnector

The NewsAPIConnector provides agents with access to real-time market sentiment data. It features a dual-source strategy, prioritizing free, high-quality RSS feeds before falling back to the NewsAPI service.

Usage Example:

from data_connectors.newsapi_connector import NewsAPIConnector

connector = NewsAPIConnector(api_key="your_newsapi_key")
news = connector.get_bitcoin_news(limit=10)

for article in news:
    print(f"Source: {article['source']} | Title: {article['title']}")

Interface Details:

get_bitcoin_news(language="en", limit=20): Returns a list of dictionaries containing title, description, url, published_at, and source.
Fallback Logic: Automatically attempts to fetch from CoinTelegraph and CoinDesk RSS feeds before using Google News RSS or the NewsAPI REST endpoint.

Knowledge Retrieval (RAG)

To ground agent decisions in established trading theory and research papers, the system utilizes a Retrieval-Augmented Generation (RAG) pipeline.

KnowledgeIndexer

The KnowledgeIndexer processes raw documents into a vector database, organized by domain (Technical, Sentiment, Fundamental, Risk).

Usage Example:

from agents.rag.indexer import KnowledgeIndexer

indexer = KnowledgeIndexer(knowledge_dir="./knowledge")
stats = indexer.index_all()

print(f"Indexed {stats['technical']} chunks for the Technical Agent.")

Key Features:

Domain Segregation: Documents are indexed into specific namespaces (e.g., technical_analysis, risk_management) so agents only retrieve relevant context.
Format Support: Optimized for .md and .txt files.
Smart Chunking: Splits content by Markdown headers and paragraphs to preserve semantic context.

Structured Output Schemas

Agents communicate their findings using Pydantic models. This ensures the Trading Orchestrator can parse recommendations programmatically for execution or backtesting.

AgentRecommendation Base Class

Every agent response inherits from AgentRecommendation, enforcing a standardized schema.

Specialized Metadata

Specialized agents provide additional metadata relevant to their domain:

TechnicalAnalysis: Includes rsi_signal, macd_signal, and support_level.
SentimentAnalysis: Includes fear_greed_interpretation and news_sentiment.
RiskAnalysis: Includes stop_loss_level and take_profit_level (calculated via math tools).

Math & Calculation Tools

The Risk Agent utilizes internal math utilities to provide exact price levels for trade execution. These tools prevent LLM "hallucination" of prices by performing deterministic calculations.

Available Calculation Tools:

calculate_atr_stop_loss: Computes stop-loss levels based on Average True Range (ATR) volatility.
calculate_take_profit: Determines target exit points based on risk-reward ratios.
position_sizing: Calculates the optimal percentage of capital to allocate based on current portfolio volatility.

Visualization & Reporting

Trade Log Viewer

The view_trades.py utility provides a CLI interface for inspecting the decisions made by the agents during a backtest session.

# View the most recent backtest trade log
python view_trades.py

Dashboard Backend

For real-time monitoring, the system provides a FastAPI-based dashboard backend that exposes:

Backtest Metrics: Sharpe Ratio, Alpha vs. Hold, and Max Drawdown.
Equity Curves: Time-series data of portfolio value.
Agent Reasoning: The full JSON "thought process" of each agent for every trade executed.