Developer Onboarding Guide¶

Welcome to the Maricusco development team. This guide will help you set up your development environment and understand the project workflow.

Prerequisites¶

Quick Setup Available

The quick-start script can automatically install required prerequisites. Manual installation is optional.

Required Prerequisites¶

Tool	Description	Installation
make	Build automation tool (to run `make quickstart`)	Pre-installed on macOS/Linux; Windows users may need to install separately
Git	Version control and repository cloning	Auto-installed via Homebrew (macOS) or apt/dnf (Linux) if missing
Python 3.12.12	Python runtime (exact version required)	Auto-installed via Homebrew (macOS) or apt/dnf (Linux) if missing
uv 0.9.13	Package manager (exact version required, newer versions accepted)	Auto-installed via official installer if missing

Optional Prerequisites¶

Tool	Description	Minimum Version
Docker	Container runtime for local services	20.10.0 (for BuildKit features)
Docker Compose	Service orchestration for PostgreSQL, Redis, ChromaDB, Prometheus, Grafana	Included with Docker

Initial Setup¶

1. Clone the Repository¶

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

# Checkout the dev branch (main development branch)
git checkout dev

2. Quick-Start Script (Recommended)¶

Recommended Approach

The quick-start script automatically installs prerequisites and sets up the development environment in one command.

Run the quick-start script:

make quickstart

What the script does:

Prerequisites Check - Verifies Python, uv, Git, Docker, Docker Compose
Version Detection - Automatically reads required versions from Dockerfile and CI/CD config
Version Verification - Checks installed versions match project requirements exactly
Interactive Updates - Prompts to update Python, uv, or Docker if versions don't match requirements
Auto-Installation - Installs missing required prerequisites (Python, uv, Git) with your permission
Optional Installation - Offers to install Docker and Docker Compose (optional but recommended)
Environment Setup - Creates virtual environment using exact Python version
Dependencies - Installs base and development dependencies
Configuration - Creates .env file from template
Git Hooks - Installs pre-commit hooks
Validation - Validates the complete setup
Interactive Setup - Optionally configures API keys and mock mode interactively

Version Requirements

The script automatically reads required versions from the project's Dockerfile and CI/CD configuration, ensuring it always uses the correct versions even when they're updated.

Version Matching: - Python: Requires exact version match (e.g., 3.12.12). The script will prompt to update if a different version is installed. - uv: Requires exact version match (e.g., 0.9.13), but newer versions are accepted as they're backward compatible. - Docker: Requires minimum version 20.10.0 (for BuildKit features). The script will prompt to update if an older version is installed.

If installed versions don't match requirements, the script will interactively prompt you to update them.

Platform Support:

Platform	Installation Method
macOS	Homebrew
Linux	apt/dnf (requires sudo)
Windows	Manual installation instructions provided

3. Manual Setup (Alternative)¶

Manual Setup

If you prefer to set up the environment manually, follow these steps:

Step-by-step manual setup:

# Ensure you have the exact Python version (3.12.12)
python3.12 --version  # Should show Python 3.12.12

# Create virtual environment
uv venv --python python3.12

# Activate virtual environment
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate  # Windows

# Install dependencies
uv sync --locked --extra dev

# Create .env file
cp .env.example .env

# Install pre-commit hooks
uv run pre-commit install

# Validate setup
make validate-setup

Version Requirements

When setting up manually, ensure you have: - Python 3.12.12 (exact version) - uv 0.9.13 (exact version, or newer) - Docker 20.10.0+ (if using Docker services)

4. Configure Environment Variables¶

Interactive Configuration

The quick-start script can configure API keys interactively. Alternatively, edit .env manually.

Edit .env file:

# Required for real LLM usage
OPENAI_API_KEY=your_openai_key_here

# Optional but recommended
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here
GOOGLE_API_KEY=your_google_key_here

# Development (enable mock mode to avoid API costs)
MARICUSCO_MOCK_MODE=true

Security Warning

Never commit API keys to version control. The .env file is gitignored.

5. Verify Installation¶

Verify your setup is working correctly:

# Activate virtual environment and verify CLI
source .venv/bin/activate && maricusco --help

# Validate development environment
make validate-setup

# Run tests in mock mode
MARICUSCO_MOCK_MODE=true make test

Development Workflow¶

Branch Strategy¶

The project follows a Git Flow-inspired branching strategy:

Branch Type	Purpose	Protection
`main`	Production-ready code	Protected
`dev`	Main development branch (default)	Default branch
`feature/*`	Feature development	-
`bugfix/*`	Bug fixes	-
`hotfix/*`	Urgent production fixes	-

Creating a Feature Branch¶

# Ensure dev branch is up to date
git checkout dev
git pull origin dev

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push to remote
git push origin feature/your-feature-name

Commit Message Convention¶

Follow the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Commit Types:

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation changes
`style`	Code style changes (formatting, no logic change)
`refactor`	Code refactoring
`test`	Adding or updating tests
`chore`	Maintenance tasks (dependencies, build, etc.)
`perf`	Performance improvements
`ci`	CI/CD changes

Examples:

# Feature
git commit -m "feat(agents): add parallel execution for analysts"

# Bug fix
git commit -m "fix(data): handle missing API key gracefully"

# Documentation
git commit -m "docs: update architecture diagram"

# Chore
git commit -m "chore(deps): update langchain to 1.1.3"

Pre-commit Hooks¶

Automatic Code Quality

Pre-commit hooks run automatically before each commit to enforce code quality.

Tools included:

Tool	Purpose
ruff	Linting and formatting
pyright	Type checking
bandit	Security scanning
detect-secrets	Secret detection
pip-audit	Dependency vulnerability scanning

Commands:

# Install hooks (done automatically by make quickstart)
uv run pre-commit install

# Run hooks manually on all files
uv run pre-commit run --all-files

# Skip hooks (use sparingly, only when necessary)
git commit --no-verify -m "commit message"

Running Tests¶

Mock Mode Recommended

Use mock mode for fast, cost-free testing during development.

Test commands:

# Run all tests in mock mode (fast, no API costs)
MARICUSCO_MOCK_MODE=true make test

# Run specific test file
MARICUSCO_MOCK_MODE=true make test TEST_ARGS='-k test_technical_analyst'

# Run tests with coverage
MARICUSCO_MOCK_MODE=true make test-coverage

# View coverage report
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

Code Quality Checks¶

The project provides Makefile targets for all common development tasks. Use make help to see all available commands.

Using Makefile Commands¶

# View all available commands
make help

# Run all code quality checks
make quality

# Run individual checks
make lint          # Run ruff linter (check only)
make format        # Auto-format code with ruff
make format-check  # Check formatting without fixing
make type-check    # Run pyright type checker
make security      # Run security scanners (bandit, pip-audit)

Manual Commands (Alternative)¶

If you prefer running tools directly:

# Run linter
uv run ruff check .

# Auto-fix linting issues
uv run ruff check --fix .

# Run formatter
uv run ruff format .

# Run type checker
npx pyright maricusco/ cli/

# Run security scanner
uv run bandit -r maricusco/ cli/ -ll

# Run all checks (as CI does)
uv run pre-commit run --all-files

Makefile Commands Reference¶

The project includes a comprehensive Makefile with targets for all common development tasks. All commands use uv for dependency management and respect the virtual environment.

Development Setup¶

make quickstart         # Interactive quick-start script (installs prerequisites, sets up environment, configures API keys)
make validate-setup     # Validate development environment setup
make validate-app        # Run comprehensive application validation (Docker, environment, imports, etc.)
make clean-venv         # Remove virtual environment

Code Quality¶

make lint               # Run ruff linter (check only, no fixes)
make format             # Auto-format code with ruff
make format-check       # Check code formatting without fixing
make type-check         # Run pyright type checker
make security           # Run security scanners (bandit, pip-audit)
make quality            # Run all code quality checks (lint, format-check, type-check, security)
make pre-commit-run     # Run pre-commit hooks on all files

Testing¶

make test               # Run pytest (set TEST_ARGS='-k pattern' to filter)
make test TEST_ARGS='-k test_technical_analyst'  # Run specific tests
make test-coverage      # Run pytest with coverage reports (HTML and XML)

Docker Commands¶

make up                 # Start all services in detached mode
make down               # Stop all services
make docker-ps          # List running Docker containers
make logs               # View logs from all services (follow mode)
make docker-build       # Build Docker image
make docker-rebuild     # Rebuild Docker image without cache
make reset CONFIRM=true # Stop all services and remove volumes (WARNING: deletes data)

Documentation¶

# Build documentation
cd docs && uv run mkdocs build

# Serve documentation locally (http://127.0.0.1:8002)
cd docs && uv run mkdocs serve

# Clean build artifacts
rm -rf docs/site/

Dependency Management¶

make lock-sync          # Update uv.lock to sync with pyproject.toml
make check-lock-sync    # Check if uv.lock is in sync with pyproject.toml

Package/Build¶

make build              # Build the package
make install-editable   # Install package in editable mode

Cleanup¶

make clean-cache        # Clean Python cache files (__pycache__, .pyc)
make clean-coverage     # Clean coverage reports and data
make clean              # Clean all build artifacts (cache, coverage)

CI Validation¶

make ci-check           # Run all CI checks locally (lock sync, quality, tests)

Issue Synchronization¶

make sync-issues-from-github  # Sync issues from GitHub to markdown file
make sync-issues-to-github    # Sync issues from markdown file to GitHub
make sync-issues-check         # Check if markdown file is in sync with GitHub
make sync-issues-dry-run       # Preview changes that would be synced to GitHub

Dependency Management¶

The project uses uv for dependency management with a lockfile (uv.lock) for reproducible builds.

Adding Dependencies¶

# Add a new dependency
# 1. Edit pyproject.toml and add the package with version
# 2. Update lockfile
make lock-sync

# 3. Commit both files
git add pyproject.toml uv.lock
git commit -m "chore(deps): add new-package==1.0.0"

Updating Dependencies¶

# Update all dependencies
uv lock --upgrade

# Update specific package
uv lock --upgrade-package langchain

# Verify lockfile is in sync
make check-lock-sync

# Commit updated lockfile
git add uv.lock
git commit -m "chore(deps): update dependencies"

Lockfile Requirement

Always commit uv.lock with dependency changes. The lockfile ensures reproducible builds across environments.

Managing Dependabot PRs¶

Zero Manual Effort

Dependabot automatically creates PRs for dependency updates every Sunday. The system uses GitHub's native auto-merge for zero manual effort.

Fully Automatic Process:

Dependabot creates PRs weekly (Sunday 9am)
CI automatically runs and updates uv.lock if needed
Patch/minor updates enable auto-merge instantly
PRs merge automatically when CI passes (no waiting, no polling)
Major updates get labeled requires-review for manual review

What You Need to Do:

Nothing for ~90% of updates (patch/minor automatically merge)
Review PRs with requires-review label (major updates, ~1-2/month)
View on GitHub: https://github.com/your-org/multi-agent-trading/pulls?q=is:pr+is:open+label:requires-review
Click "Merge pull request" button after reviewing

That's it. No scripts, no commands, no manual tracking needed.

Mock Mode Development¶

Cost-Free Development

Use mock mode to develop without API costs.

Enable mock mode:

# Enable mock mode globally
export MARICUSCO_MOCK_MODE=true

# Run CLI in mock mode
maricusco

# Run tests in mock mode
MARICUSCO_MOCK_MODE=true make test

# Simulate agent execution delays (for testing parallel execution)
export MARICUSCO_MOCK_AGENT_DELAYS_MS="technical:800,sentiment:400,news:200,fundamentals:600"
maricusco

See Mock Mode documentation for complete details.

Working with Issues¶

The project uses GitHub Issues with bidirectional synchronization to Markdown files.

Viewing Issues¶

# View issues in markdown format
cat docs/content/github_issues.md

# Or view on GitHub
gh issue list

Syncing Issues¶

# Sync issues from GitHub to markdown
export GITHUB_TOKEN=$(gh auth token)
make sync-issues-from-github

# Check sync status
make sync-issues-check

# Sync changes from markdown to GitHub
make sync-issues-to-github

See Issues Management documentation for complete workflow.

Project Structure¶

multi-agent-trading/
├── cli/                    # Command-line interface
│   ├── main.py            # CLI entry point
│   ├── models.py          # CLI data models
│   └── utils.py           # CLI utilities
│
├── maricusco/             # Main application package
│   ├── agents/            # AI agents
│   │   ├── analysts/      # Technical, fundamentals, sentiment, news
│   │   ├── researchers/   # Bull, bear researchers
│   │   ├── managers/      # Research, risk managers
│   │   ├── trader/        # Trading agent
│   │   └── risk_mgmt/     # Risk debate agents
│   │
│   ├── orchestration/     # Workflow orchestration (LangGraph)
│   │   ├── trading_graph.py      # Main workflow graph
│   │   ├── conditional_logic.py  # Routing logic
│   │   ├── synchronization.py    # Parallel execution sync
│   │   └── propagation.py        # Workflow execution
│   │
│   ├── data/              # Market data layer
│   │   ├── interface.py   # Unified data interface
│   │   ├── cache.py       # Redis caching
│   │   ├── memory.py      # ChromaDB vector memory
│   │   ├── llm_factory.py # LLM instance creation
│   │   ├── vendors/       # Data source implementations
│   │   ├── tools/         # LangChain tool wrappers
│   │   └── utils/         # Data processing utilities
│   │
│   ├── api/               # FastAPI endpoints
│   │   ├── app.py         # FastAPI application
│   │   ├── health.py      # Health check endpoint
│   │   └── metrics.py     # Metrics endpoint
│   │
│   ├── config/            # Configuration
│   │   └── settings.py    # Default configuration
│   │
│   ├── models/            # Shared domain models
│   │   └── agent_states.py # Agent state schemas
│   │
│   ├── utils/             # Shared utilities
│   │   ├── logging.py     # Structured logging
│   │   ├── metrics.py     # Prometheus metrics
│   │   ├── mock_llm.py    # Mock LLM for testing
│   │   └── mock_memory.py # Mock memory for testing
│   │
│   ├── services/          # Business logic services (future)
│   └── database/          # Database layer (future)
│
├── tests/                 # Test suite
│   ├── api/              # API tests
│   ├── integration/      # Integration tests
│   ├── orchestration/    # Orchestration tests
│   ├── performance/      # Performance tests
│   └── utils/            # Test utilities
│
├── docs/                  # Documentation (MkDocs)
│   ├── content/          # Markdown documentation
│   └── mkdocs.yml        # MkDocs configuration
│
├── docker/                # Docker configuration
│   ├── entrypoint.sh     # Container entrypoint
│   ├── healthcheck.sh    # Health check script
│   ├── grafana/          # Grafana provisioning
│   ├── prometheus/       # Prometheus configuration
│   └── postgres/         # PostgreSQL initialization
│
├── scripts/               # Utility scripts
│   ├── sync_issues.py          # GitHub issues synchronization
│   ├── cleanup_artifacts.py    # Cleanup temporary files
│   ├── generate_test_metrics.py # Generate test metrics
│   └── validate_app.py         # Application validation
│
├── .github/               # GitHub configuration
│   ├── workflows/        # CI/CD workflows
│   └── actions/          # Reusable actions
│
├── pyproject.toml         # Project metadata and dependencies
├── uv.lock               # Dependency lockfile
├── Dockerfile            # Container image definition
├── docker-compose.yml    # Local services orchestration
├── Makefile              # Development automation
└── README.md             # Project overview

Common Development Tasks¶

Running the CLI¶

# Activate virtual environment
source .venv/bin/activate

# Run CLI in mock mode (no API costs)
MARICUSCO_MOCK_MODE=true maricusco

# Run CLI with real APIs
maricusco

# Run CLI with specific ticker and date
maricusco --ticker AAPL --date 2024-12-01

Viewing Logs¶

# Application logs (if file logging enabled)
tail -f maricusco/logs/maricusco.log

# Docker service logs
docker-compose logs -f app
docker-compose logs -f postgres
docker-compose logs -f redis

Accessing Monitoring¶

# Prometheus UI
open http://localhost:9090

# Grafana UI
open http://localhost:3000
# Default credentials: admin / admin

Debugging¶

# Run with debug logging
export MARICUSCO_LOG_LEVEL=DEBUG
maricusco

# Use Python debugger
python -m pdb -m cli.main

# Use ipdb for better debugging
uv pip install ipdb
# Add breakpoint in code: import ipdb; ipdb.set_trace()

Cleaning Up¶

# Remove virtual environment
make clean-venv

# Stop Docker services
make down

# Remove Docker volumes (WARNING: deletes data)
make reset CONFIRM=true

# Clean Python cache files
make clean-cache

# Clean all build artifacts
make clean

CI/CD Pipeline¶

The project uses GitHub Actions for continuous integration and deployment.

Pipeline Stages¶

Stage	Description
Check Lock	Verify `uv.lock` is in sync with `pyproject.toml`
Lint	Run ruff linter and formatter
Type Check	Run pyright type checker
Security	Run bandit and pip-audit security scanners
Detect Secrets	Scan for committed secrets
Pre-commit	Run pre-commit hooks
Test	Run pytest test suite with coverage
Docker Build	Build and scan Docker image
Merge Validation	Validate PR merge conditions
Notification	Send Slack notification (if configured)

Viewing CI Results¶

# View workflow runs
gh run list

# View specific run
gh run view <run-id>

# View logs for failed job
gh run view <run-id> --log-failed

Fixing CI Failures¶

Using Makefile (recommended):

# Run all CI checks locally
make ci-check

# Run individual checks
make check-lock-sync    # Verify lock file sync
make quality            # Run all quality checks
make test               # Run tests

# Auto-fix formatting issues
make format

Manual commands:

# Run the same checks locally
uv run pre-commit run --all-files

# Fix linting issues
uv run ruff check --fix .
uv run ruff format .

# Fix type errors
npx pyright maricusco/ cli/

# Run tests
MARICUSCO_MOCK_MODE=true make test

Documentation¶

Building Documentation Locally¶

# Install documentation dependencies
uv sync --locked --extra docs

# Serve documentation locally (port 8002)
cd docs
uv run mkdocs serve

# Open in browser
open http://127.0.0.1:8002

To build static documentation:

cd docs
uv run mkdocs build
# Output will be in docs/site/

Updating Documentation¶

# Edit markdown files in docs/content/
vim docs/content/architecture.md

# Preview changes
cd docs && uv run mkdocs serve

# Commit changes
git add docs/content/architecture.md
git commit -m "docs: update architecture documentation"

Documentation Structure¶

index.md: Home page and overview
developer_onboarding.md: This guide (includes setup instructions)
architecture.md: System architecture
mock-mode.md: Mock mode documentation
monitoring_metrics.md: Observability
docker_setup.md: Docker configuration
issues_management.md: Issue tracking workflow
cicd.md: CI/CD pipeline documentation
cli_usage.md: CLI usage and commands

Getting Help¶

Internal Resources¶

Documentation: https://maricusco.pages.dev
GitHub Issues: https://github.com/Maricusco/multi-agent-trading/issues
Slack: https://teammaricusco.slack.com

Team Contacts¶

shakedmanes (Developer): Development, features, code, code reviews
of1r (DevOps Engineer): Infrastructure, monitoring, deployment
ziv426 (Developer): Development, features, code

Common Issues¶

Issue	Solution
Virtual environment	`make clean-venv && make venv && make install-dev`
Dependency sync	`make lock-sync`
Docker services	`make down && docker-compose down -v && make up`
API keys	`env \\| grep API_KEY` or use `MARICUSCO_MOCK_MODE=true`

Best Practices¶

Code Quality¶

Write clear, self-documenting code
Add docstrings to all public functions and classes
Follow PEP 8 style guidelines (enforced by ruff)
Use type hints for function parameters and return values
Keep functions small and focused (single responsibility)
Avoid deep nesting (max 3-4 levels)

Testing¶

Write tests for all new features
Aim for >80% code coverage
Use mock mode for fast, cost-free testing
Test edge cases and error conditions
Use descriptive test names: test_<what>_<condition>_<expected>

Git Workflow¶

Commit frequently with meaningful messages
Keep commits atomic (one logical change per commit)
Review your own changes before pushing
Rebase feature branches on dev regularly
Squash commits before merging (if requested)

Documentation¶

Update documentation when changing behavior
Add code comments for non-obvious logic
Keep README and docs in sync with code
Use diagrams for complex workflows

Security¶

Never commit API keys or secrets
Use environment variables for sensitive data
Review dependencies for vulnerabilities regularly
Follow principle of least privilege

Next Steps¶

Now that your environment is set up:

Explore the codebase: Start with maricusco/orchestration/trading_graph.py
Run a test analysis: MARICUSCO_MOCK_MODE=true maricusco
Read the architecture docs: System Overview
Learn about mock mode: Mock Mode Guide
Understand CI/CD: CI/CD Pipeline
Pick an issue: Find a good first issue on GitHub
Ask questions: Reach out on Slack if you need help

Welcome to the Team

You're all set! Start exploring and contributing to the project.