Kuroshio黑潮Kuroshio黑潮Kuroshio is an open-source quantamental portfolio engine: multi-factor screening, LLM agent research that is cheap enough to run daily, and rebalancing proposals governed by your own written investment policy. It ranks, argues, and proposes — it never places an order.
# zero-key path: yfinance data, pure-quant scoring $ pip install "kuroshio[yfinance]" $ kuroshio screen --market us --tickers NVDA,AMD,AVGO,MSFT,META,LLY,XOM,JPM,COST,NFLX
Stage-1 breakout gates, then cross-sectional percentile scoring across momentum, volume, relative strength and market-specific factors. Pure functions — no network, no DB.
A componentized TradingAgents pipeline runs analyst debate per holding. Facets are TTL-cached, so a daily run over a whole portfolio costs cents rather than dollars.
Your IPS — a markdown file with caps, hurdles and friction — decides. The allocator emits SWAP / TRIM / ALERT cards, each citing the exact clause that triggered it.
Everything below is the actual JSON output of kuroshio screen --json, captured
on the session shown and frozen into this page. Click a column to sort; toggle a flag to filter.
An example portfolio is checked against examples/ips-balanced.md. Holding weights
are illustrative; every score is the engine's real output for this session. The cards below are
verbatim ProposalCards — the engine's only output. It has no broker connection by design.
Weekly rebalances over the trailing year, 20-day forward returns, top-5 basket, scored only on data available at each rebalance date.
Core logic never imports a data vendor. Providers are plugins, screening and allocation are pure functions over plain dataclasses, and every edge (CLI, Discord) is an adapter at the boundary.