Karkinos

Local-first quantitative research and investing platform for China markets.

Investing is a chronic condition. Here is your scalpel.

Documentation · Architecture · Releases · 简体中文

Karkinos connects point-in-time market data, reproducible research, portfolio construction, risk, simulation, accounting, and attribution in one local-first workflow.

Market data → point-in-time research → portfolio decisions → evaluation → continuous feedback.

Capabilities

• Point-in-time data — research inputs reflect information available at the modeled decision time.
• Research — backtesting, transaction-cost modeling, parameter exploration, out-of-sample evaluation, and robustness analysis.
• Portfolio & risk — published forecasts become portfolio targets, explicit risk decisions, and rebalance plans before execution.
• Simulation & evaluation — backtest, paper, and shadow workflows connect research expectations with later outcomes.
• Accounting & attribution — cash, positions, fees, returns, reconciliation, and outcome attribution remain explicit.
• China-market semantics — trading calendars, suspensions, price limits, lot rules, fees, and taxes are first-class concerns.
• AI-assisted research — optional AI can accelerate research iteration while deterministic code owns quantitative and financial results.
• Application — FastAPI backend, React / TypeScript interface, and a local-first runtime.

Using Karkinos

Method	Best for	Requirements
Source runtime	Current source checkout or any locally available branch	Python 3.12+, Node.js 24.x, uv, Git, POSIX shell
Docker Compose	Isolated Web + API runtime	Docker / Docker Compose
Python / pip from source	Manual Python/API integration	Python 3.12+; Node.js 24.x for the Web UI
Native release	Verified packaged runtime	Currently macOS arm64 / x86_64

Source runtime

Start the stable main branch (the default):

git clone https://github.com/imReese/Karkinos.git
cd Karkinos
./scripts/start_server.sh

Stable main serves the built Web UI and API at http://127.0.0.1:8000.

Start the current dev working tree:

git clone --branch dev https://github.com/imReese/Karkinos.git
cd Karkinos
uv sync --locked --extra server --extra dev
npm ci --prefix web
./scripts/start_server.sh dev

Development serves the Web UI with Vite HMR at http://127.0.0.1:5173 and the API with backend reload at http://127.0.0.1:8000.

Development state is isolated under ~/.karkinos/development/:

config/config.json   # created with safe defaults on first start
config/.env          # optional development credentials
data/                # development databases
logs/                # development logs

The launcher never copies existing account data or reads the repository's config.json or .env. Existing development databases use the application's normal migrations; a failed migration blocks startup. Set KARKINOS_DEV_HOME for another development directory.

Stop the managed runtime:

./scripts/stop_server.sh

Branch selection, refresh, and single-runtime rules: scripts/README.md.

Docker Compose

git clone --branch main --depth 1 https://github.com/imReese/Karkinos.git
cd Karkinos
cp config.example.json config.json
cp .env.example .env
docker compose up --build -d

Open http://127.0.0.1:8000.

Docker Compose keeps its database in the karkinos-data Docker volume and mounts config.json read-only into the container. Edit .env for optional TuShare, AI, or notification credentials before starting the service.

Python / pip from source

Karkinos is installable as a Python package from this repository. The PyPI project named karkinos is unrelated to this repository, so do not use pip install karkinos.

python -m pip install ".[server]"

For the Web UI:

npm ci --prefix web
npm --prefix web run build

Then create local configuration and start from the repository root:

cp config.example.json config.json
cp .env.example .env
python -m server

Open http://127.0.0.1:8000. The default writable data directory is data/store.

Native releases

Stable releases publish verified native archives and container images. Native archives are currently built for macOS arm64 and macOS x86_64. See Releases for available artifacts.

The standalone bootstrap_installer.sh asset is for the managed release/update handoff flow, not a generic cross-platform package manager. Linux and Windows users should currently prefer Docker or a source-based runtime.

Configuration

The default market-data policy is free_cn_research_v1. Verified daily research data prefers independent free sources (BaoStock + Tencent via AKShare), can fall back to other independent free observations when a provider is unavailable, and fails closed on real cross-source conflicts. TuShare and TDX are optional enhancement sources rather than requirements for the default data flywheel. AI providers, notifications, fees, server settings, paths, and environment-variable precedence are documented in the configuration guide.

Development

Changes integrate on dev. Start the source runtime with ./scripts/start_server.sh dev after installing the locked dependencies above. For contribution workflow, tests, migration rules, and engineering constraints, see CONTRIBUTING.md and docs/ENGINEERING.md.

Resources

Product — Goal · Architecture · Plan Engineering — Engineering · Guides · Contributing Project — Releases · Security · MIT License

---

_{Python · FastAPI · SQLite · React · TypeScript · Vite · Docker
Karkinos is research and investing software, not investment advice or a guarantee of returns.}