Skip to content

Maricusco Internal Documentation

This is internal team documentation for the Maricusco multi-agent trading system. It provides comprehensive guides for development, deployment, and system architecture for team members.

Overview

Maricusco is a multi-agent LLM-powered financial trading framework that orchestrates specialized AI agents to analyze market data, conduct research, and make informed trading decisions through collaborative debate and risk assessment.

The system employs a modular monolith architecture with clear separation of concerns, enabling scalable development and future microservices migration.

Documentation Structure

Development

  • Mock Mode - Cost-free development and testing without LLM API calls
  • Issues Management - Bidirectional synchronization between GitHub and Markdown for issue tracking

Quick Start

For installation and setup instructions, see the README.md in the repository.

Enable Mock Mode for Development:

export MARICUSCO_MOCK_MODE=true
maricusco

System Architecture

The framework is organized into distinct agent teams:

Analyst Team

  • Fundamentals Analyst: Evaluates company financials and performance metrics
  • Sentiment Analyst: Analyzes social media and public sentiment
  • News Analyst: Monitors global news and macroeconomic indicators
  • Technical Analyst: Utilizes technical indicators to detect trading patterns

Researcher Team

  • Bull Researcher: Advocates for bullish positions
  • Bear Researcher: Advocates for bearish positions
  • Research Manager: Facilitates debates and makes investment decisions

Risk Management Team

  • Aggressive Debator: Advocates for higher-risk strategies
  • Conservative Debator: Advocates for lower-risk approaches
  • Neutral Debator: Provides balanced risk assessment
  • Risk Manager: Evaluates and refines trading plans from risk perspectives

Trader Agent

Composes reports from analysts and researchers to make informed trading decisions.

Contributing to Documentation

This internal documentation is built with MkDocs and the Material theme. To contribute:

# Install documentation dependencies
uv pip install -e ".[docs]"

# Serve locally (runs on port 8002 to avoid conflict with ChromaDB)
cd docs
mkdocs serve

# Build static site
mkdocs build

Resources

Metrics Configuration

  • MARICUSCO_METRICS_ENABLED (default: false) — enable Prometheus metrics exposition.
  • MARICUSCO_METRICS_PATH (default: /metrics) — HTTP path for the metrics endpoint.
  • MARICUSCO_METRICS_PORT (default: 8000) — port used by the metrics endpoint.
  • MARICUSCO_METRICS_SAMPLING_RATE (default: 1.0) — sampling factor for high-volume operations.
  • MARICUSCO_METRICS_LABELS (optional) — comma-separated key=value pairs applied to exported metrics.

Prometheus Setup and Access

  • Service: prometheus in docker-compose.yml, pinned to prom/prometheus:v3.8.0.
  • Config: docker/prometheus/prometheus.yml (scrape interval 15s, path /metrics, target app:8000, alerting/rule placeholders).
  • Retention: --storage.tsdb.retention.time=15d (compose command).
  • UI: http://localhost:9090 (host-mapped Prometheus UI).
  • Enable app metrics: set MARICUSCO_METRICS_ENABLED=true; ensure the app serves /metrics on port 8000 inside the container.
  • Alerting rules: add YAML files under /etc/prometheus/rules/*.yml (create docker/prometheus/rules/ and mount if needed).