Skip to content

Setup

Installation

For complete installation instructions, see the README.md in the repository.

Quick Start:

# Install uv (required)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Clone and setup
git clone https://github.com/Maricusco/multi-agent-trading.git
cd multi-agent-trading

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv sync --locked --dev

# Verify installation
maricusco --help

Key Points: - All dependencies are managed via uv and locked in uv.lock - Use uv sync --locked to install from the lockfile (ensures reproducibility) - Pre-commit hook versions are automatically synced from uv.lock via sync-with-uv hook - For development, use uv sync --locked --dev to include dev dependencies - Single source of truth: pyproject.toml → uv.lock → .pre-commit-config.yaml (auto-synced)

Metrics Configuration

  • Enable exposition: MARICUSCO_METRICS_ENABLED=true (default: false).
  • Endpoint: MARICUSCO_METRICS_PATH (default /metrics).
  • Port: MARICUSCO_METRICS_PORT (default 8000).
  • Sampling: MARICUSCO_METRICS_SAMPLING_RATE (default 1.0).
  • Constant labels: MARICUSCO_METRICS_LABELS (comma key=value).

Health Check Configuration

  • Enable/disable: MARICUSCO_HEALTHCHECK_ENABLED (default: true).
  • Endpoint path: MARICUSCO_HEALTHCHECK_PATH (default /health).
  • Required dependencies: defaults database, redis; optional dependencies via MARICUSCO_HEALTHCHECK_OPTIONAL_DEPENDENCIES (comma-separated).
  • Vendor checks: toggle with MARICUSCO_HEALTHCHECK_VENDORS_ENABLED (default: false).
  • Timeouts: MARICUSCO_HEALTHCHECK_TIMEOUT_DEFAULT with per-dependency overrides (..._DATABASE, ..._REDIS, ..._VENDORS), typically 1–2s.
  • Cache: MARICUSCO_HEALTHCHECK_CACHE_TTL_SECONDS (default 0 = no cache).

Prometheus Server Setup

  • Service: prometheus in docker-compose.yml (prom/prometheus:v3.8.0).
  • Config: docker/prometheus/prometheus.yml (/metrics, target app:8000, 15s scrape, rule file placeholders).
  • Retention: --storage.tsdb.retention.time=15d.
  • Start Prometheus only: 
    docker-compose up -d prometheus
  • UI: http://localhost:9090.

Metrics Endpoint

  • Implemented via FastAPI router in maricusco/api/metrics.py.
  • Exposes /metrics; returns 503 when metrics disabled, 500 on internal render errors.
  • Ensure application container serves port 8000 internally for Prometheus scraping.

PromQL Quick Examples

  • Error rate (5m): rate(maricusco_api_errors_total[5m])
  • 95th percentile request latency: histogram_quantile(0.95, rate(maricusco_request_duration_seconds_bucket[5m]))
  • Active agents: maricusco_active_agents