v0.1.0 · Implementing arXiv:2505.24831v2

Crypto portfolios,
built on consensus.

A production-grade Python framework for cryptocurrency portfolio construction. Consensus Louvain clustering, Ledoit-Wolf shrinkage, and Sharpe-ascent optimisation — packaged for quant teams who ship.

Install with pip View on GitHub Star

Python 3.10 · 3.11 · 3.12 Stateless FastAPI surface Docker-ready

    
zsh — cps@quant
 prod  

              ❯ 
              pip install crypto-portfolio-system
            
          Successfully installed crypto-portfolio-system-0.1.0
          
              ❯ 
              crypto-portfolio --source yfinance \
            
              --symbols BTC-USD,ETH-USD,SOL-USD,ADA-USD \
          
              --period 6mo --consensus-runs 20
          
          ▸ Ingested 1,834 price points across 4 symbols
          
          ▸ Fitted ARIMA(2,1,2) · horizon 7d
          
          ▸ Building rolling correlation networks · 60d window
          
          ▸ Running consensus Louvain (20 runs, τ=0.5)
          
            ✓ 5 stable communities · Jaccard 0.81
          
          ▸ Ledoit-Wolf shrinkage · λ=0.42
          
          ▸ Sharpe ascent · cap=0.35 · ceil=1.20
          
            ✓ weights {
          
                  BTC: 0.34,  ETH: 0.28,  SOL: 0.21,  ADA: 0.17 }
          
          ✔ Run 4abf12c8 complete → outputs/
          
            trades.csv · summary.csv · log_returns.csv · events.jsonl

Sharpe (annualised)

live

1.84 net of costs

Stable communities

consensus

12 across 80 assets

Pipeline runtime

~3.2s per rebalance

Ingest 0.4s

Louvain consensus 1.1s

Sharpe ascent 1.7s

4 .

Forecasting methods

4 .

Data sources

20 .

Consensus runs

6 .

Risk controls

5 .

Output artefacts

3 .

Python versions

Built on the shoulders of

NumPy

pandas

PyTorch

NetworkX

statsmodels

arch

FastAPI

Uvicorn

yfinance

ccxt

pytest

ruff

mypy

Docker

NumPy

pandas

PyTorch

NetworkX

statsmodels

arch

FastAPI

Uvicorn

yfinance

ccxt

pytest

ruff

mypy

Docker

Pipeline

From price data to risk-aware portfolios.

A single, opinionated pipeline. Each stage is observable, deterministic, and independently testable.

01

Ingest

Wide price frames via synthetic, CSV, yfinance, or live ccxt polling.

CSV yfinance ccxt synthetic
02

Clean & log-returns

Calendar alignment, missing-value handling, and log-returns computation.

pandas NumPy
03

Forecast

Naive, ARIMA, GARCH (AIC), and shared multi-asset LSTM with governance drift detection.

ARIMA GARCH LSTM
04

Correlation networks

Rolling correlation matrices → graph edges with NetworkX.

NetworkX
05

Consensus Louvain

Stable clusters extracted across N runs with majority co-occurrence threshold τ.

Louvain consensus
06

Sharpe ascent

Ledoit-Wolf shrinkage, per-asset caps, vol ceiling, transaction & slippage.

Ledoit-Wolf constraints
07

Artefacts

Persistent, idempotent artefacts: trades, summary, log-returns, events, metrics.

trades.csv events.jsonl

Features

Everything a quant pipeline needs.
Nothing it doesn't.

Designed for serious work — observable, testable, and built on the research literature.

Multi-method forecasting

Naive, ARIMA, GARCH with AIC-selected orders, and a shared multi-asset LSTM — swappable per run with a single flag.

Consensus Louvain

Stable community detection across N independent Louvain runs, with co-occurrence threshold and Jaccard stability metrics.

Sharpe-ratio optimisation

Ledoit-Wolf covariance shrinkage, per-asset caps, asset-count and volatility ceilings — all in one objective.

Risk & execution modelling

Transaction costs and slippage applied to net returns; per-rebalance turnover surfaced in every artefact.

Governance & drift

Forecast drift detection and MSE tracking over time. Pipeline emits events, metrics, and structured logs.

Pluggable & layered

Hexagonal architecture. Domain is pure Python; infrastructure is swappable. Ships CLI, REST, Docker, and ccxt poller.

Interfaces

One framework.
Four ways to use it.

CLI for scripting, Python API for notebooks and services, REST for stateless backends, and a live poller for real-time research.

Shell-first workflow.

Two scripts. One for batch runs, one for live ingestion. Flags map 1:1 to PipelineConfig — no surprises.

config-as-flags idempotent runs jsonl events

zsh


                      $ pip install crypto-portfolio-system
                    
                      
                    
                      $ crypto-portfolio \
                    
                          --source yfinance \
                    
                          --symbols BTC-USD,ETH-USD,SOL-USD,ADA-USD \
                    
                          --period 6mo \
                    
                          --forecast-method arima \
                    
                          --consensus-runs 20 \
                    
                          --weight-cap 0.35 \
                    
                          --max-volatility-annual 1.20 \
                    
                          --output-dir outputs --run-dir runs

Composable from code.

Every dependency is injected. The pipeline, forecaster, store, logger, and governance are all pluggable.

config-as-flags idempotent runs jsonl events

python · run_pipeline.py


                      from cps import (
                    
                          PipelineConfig, run_pipeline,
                    
                          ForecastService, StructuredLogger,
                    
                          MetricsRegistry, ForecastGovernance,
                    
                          FileArtifactStore,
                    
                      )
                    
                      
                    
                      config = PipelineConfig(
                    
                          forecast_method="arima", random_seed=42
                    
                      )
                    
                      artifacts = run_pipeline(
                    
                          prices, config,
                    
                          artifact_store=FileArtifactStore("outputs"),
                    
                          logger=StructuredLogger("cps", "outputs/events.jsonl"),
                    
                          metrics_registry=MetricsRegistry(),
                    
                          governance=ForecastGovernance(),
                    
                          forecast_service=ForecastService(),
                    
                      )

Stateless HTTP surface.

Submit a run with a config and CSV body, then read back trades, metrics, summary, and log-returns.

config-as-flags idempotent runs jsonl events

http · /api/v1/runs


                      # Submit a run
                    
                      curl -X POST http://localhost:8000/api/v1/runs 
                    
                        -H 'Content-Type: application/json' \
                    
                        -d '{
                    
                          "config": {"forecast_method": "arima"},
                    
                          "prices_csv_content": "date,btc,eth\n..."
                    
                        }'
                    
                      
                    
                      # Read artefacts back
                    
                      curl http://localhost:8000/api/v1/runs/{run_id}/summary
                    
                      curl http://localhost:8000/api/v1/runs/{run_id}/trades
                    
                      curl http://localhost:8000/api/v1/runs/{run_id}/metrics

Poll any ccxt exchange.

Long-running poller writes long-form OHLCV. Pivot to wide and feed straight into the pipeline.

config-as-flags idempotent runs jsonl events

zsh · cps-realtime


                      $ pip install -e ".[realtime]"
                    
                      
                    
                      $ cps-realtime \
                    
                          --exchange binance \
                    
                          --symbols BTC/USDT,ETH/USDT,SOL/USDT \
                    
                          --output-csv prices.csv \
                    
                          --timeframe 1m \
                    
                          --interval-seconds 60 \
                    
                          --max-iterations 0

Adopt

Install in seconds. No accounts.

MIT licensed. Pay nothing. Add capabilities as you need them.

Core

The default install. Naive + ARIMA forecasting, FileArtifactStore, structured logging.

$ pip install crypto-portfolio-system

Naive & ARIMA forecasting
Consensus Louvain clustering
Sharpe-ascent with constraints
Structured JSONL logging
Metrics registry

PyPI

Studio

Recommended

Everything in Core, plus GARCH volatility and a multi-asset LSTM forecaster.

$ pip install crypto-portfolio-system[forecast-lstm,forecast-garch]

Everything in Core
GARCH with AIC order selection
Multi-asset shared LSTM
Forecast drift governance
MSE telemetry on runs

Install Studio

Live

Studio + live ccxt polling, yfinance ingest, and the FastAPI REST surface.

$ pip install crypto-portfolio-system[all]

Everything in Studio
Live ccxt poller
yfinance multi-asset ingestor
Stateless FastAPI surface
Docker-ready image

Install Live

All tiers ship under the MIT license. No telemetry. No accounts.

Questions

Answers,
without the fluff.

If something's missing, open an issue on GitHub. Or read the full README.

How is this different from off-the-shelf backtesters?

CPS is a research-to-production pipeline, not a UI. Every stage (forecasting, Louvain consensus, optimisation, risk) is a first-class object you can compose, swap, or replace — without writing UI glue.
Does it ship with live trading?

No. CPS produces deterministic, idempotent artefacts — trades, summary, log-returns. Live trading is intentionally out of scope. The ccxt poller feeds the same wide price frame the pipeline expects.
Why consensus Louvain instead of one Louvain pass?

Louvain is stochastic. Running it N times and extracting co-occurring communities gives you a stability signal you can measure. The τ threshold controls how strict 'stable' is.
Which Python versions are supported?

Python 3.10, 3.11, and 3.12 — tested on every push. NumPy ≥1.24, pandas ≥2.0, NetworkX ≥3.1, statsmodels ≥0.14.
Can I run this in Docker?

Yes. A multi-stage Dockerfile is in the repo — small runtime image with optional extras pulled in via build args.
Is there a web dashboard?

Not yet — it's a known roadmap item awaiting sponsorship. CPS is CLI + REST first; visualisation belongs to whoever consumes the artefacts.

Ready when you are

Build portfolios the research-grade way.

Install CPS, point it at any source — CSV, yfinance, or live ccxt — and ship a deterministic, risk-aware crypto portfolio.

Install with pip Read the source

MIT license · v0.1.0 · Tested on 3.10 / 3.11 / 3.12

Crypto portfolios, built on consensus.

From price data to risk-aware portfolios.

Everything a quant pipeline needs.Nothing it doesn't.

Multi-method forecasting

Consensus Louvain

Sharpe-ratio optimisation

Risk & execution modelling

Governance & drift

Pluggable & layered

One framework.Four ways to use it.

Shell-first workflow.

Composable from code.

Stateless HTTP surface.

Poll any ccxt exchange.

Install in seconds. No accounts.

Core

Studio

Live

Answers,without the fluff.

Build portfolios the research-grade way.

Crypto portfolios,
built on consensus.

Everything a quant pipeline needs.
Nothing it doesn't.

One framework.
Four ways to use it.

Answers,
without the fluff.