MAAIS

MAAIS is a local, auditable multi-agent research and paper-trading platform for USDT perpetual markets.

Current status: The platform implementation is complete, but it is not yet ready for the seven-day paper experiment until a fresh exact-commit 24-hour soak and immutable readiness verdict pass. The paper broker, authoritative event ledger, live orchestrator, Mission Control dashboard, reporting, backup/restore, and process drills are implemented. No live-money execution is in scope.

Safety boundary

The supported runtime modes are exactly:

• replay — deterministic historical/research execution;
• paper_live — public live market data with the local paper broker;
• testnet_smoke — authenticated Binance Demo/Testnet protocol checks only.

There is no live-money mode. Public market-data connectors do not require API credentials. Authenticated exchange operations are restricted to Binance Demo Futures and are never used to calculate official paper P&L.

Paper-model boundary

The official first paper candidate uses 1x leverage and a frozen maintenance-margin approximation equal to 0.5% of gross notional. It does not estimate a liquidation price and does not reproduce Binance maintenance-margin tiers or liquidation behavior. Mission Control and every immutable daily/final report display this limitation. The first week can test operations, decision traceability, data integrity, and the local execution/accounting model; it cannot establish live-exchange parity or durable profitability.

Local setup

Requirements: Python 3.12, uv, Docker Desktop with Compose, PostgreSQL client tools, Node 22/npm, tmux, jq, curl, at least 20 GiB free host disk, and a local Chromium-compatible browser installed through the pinned Playwright CLI.

cp .env.template .env
uv sync --dev
export MAAIS_DOCKER_CONTEXT=desktop-linux  # use `docker context show` to choose yours
docker --context "${MAAIS_DOCKER_CONTEXT}" compose up -d --wait postgres
uv run alembic upgrade head
uv run maais database-identity

If more than one local container engine is installed, keep MAAIS_DOCKER_CONTEXT explicit. Timed-run startup compares the Compose PostgreSQL system_identifier with the database reached by the application and fails closed if they are different.

MAAIS needs access to the local Docker engine, not Docker Hub credentials or a Docker credential-helper keychain entry. The Compose image is public. Do not approve an unexpected credential request for this paper workflow.

Verification

uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pip-audit
uv run detect-secrets scan --baseline .secrets.baseline --exclude-files '(^uv\.lock$|^\.superpowers/)'
uv run pytest -q

Paper-week operator workflow

The operational CLI now includes ledger verification, immutable daily reports, analysis-ready CSV/Parquet exports, a hash-verified seven-day final aggregator, validated backups, suffix-constrained restore drills, an immutable exact-commit qualification bundle, and candidate preflight. The daily close is concurrency-locked and safely resumes its unique verified bundle after an interrupted state update. The timed run remains blocked until that bundle, the process fault drills, and the separate 24-hour soak pass.

Disposable process drills and the 24-hour soak have separate purpose-bound launchers. Each process drill also completes a real daily report, backup, and health cycle with the Docker command disabled; in-run status and daily-close checks compare the configured PostgreSQL system identifier directly with the frozen start identity. The soak verdict rejects evidence from a drill run, any restart inside the soak, a process-drill bundle from a different commit, incomplete reason/explanation metadata for any decision, or malformed/error output in any of the four supervised-service logs. The seven-day launcher then requires that hash-verified verdict explicitly and rejects a failed, stale, incomplete, tampered, or different-commit bundle.

• Local setup
• Normal operations
• Incident response
• Recovery and restore
• Seven-day protocol

Design and delivery

• Current architecture
• Mission Control API
• Database schema
• Paper-trading and observability design
• Master delivery plan
• Phase 0 safety plan

Historical batch documents describe implemented components, not current system readiness. A seven-day test starts only after all preflight gates in the design have fresh evidence.