czsc

The czsc CLI is a unified command-line interface built with typer designed for both human and LLM use. It exposes capabilities for signal directories, Chan-theory analysis, strategy backtesting, research, visualization, and performance benchmarking.

Key Design Principles:

• Command Structure: Organized into sub-command groups (e.g., signals, data, plot).
• LLM-Friendly: Commands support a --json flag for machine-readable output. Unlike global callbacks, this flag is implemented per-command to ensure better compatibility with LLM prompting (e.g., czsc signals list --json).
• Separation of Concerns: CLI modules follow a pattern of Parse arguments $\rightarrow$ Call czsc.* public API $\rightarrow$ Render via _io.py. They do not contain business or algorithmic logic.
• Entry Point: Registered via pyproject.toml as czsc = "czsc.cli:app".

The czsc-trader crate provides a multi-strategy trading engine for Chan Lun (缠论) analysis, signal compilation, and parameter optimization. Its core components include:

• engine_v2: An event-driven v2 execution engine.
• signals: Compiles signal strings into SignalConfig (works with czsc-signals).
• trader: Provides the CzscTrader and CzscSignals state machines.
• optimize: Performs grid search for position strategy parameters.

Note on Backtesting: czsc-trader is responsible for generating signals and position weight sequences. It does not perform the backtesting itself; weighted backtesting is handled by the external wbt crate.

The czsc-utils crate provides tools for K-line synthesis and trading calendar management:

• BarGenerator: A multi-period K-line synthesizer.
• freq_data: Tools for frequency period and time alignment calculations.
• is_trading_time: Logic to judge trading periods for Chinese A-share and futures markets.

czsc-signal-macros is an internal procedural macro crate used by the czsc framework.

Important: Most users should not depend on this crate directly. If you want to use the czsc quantitative analysis framework, you should add the facade crate instead:

cargo add czsc

This crate is only intended for direct use if you are building your own Rust project and want to integrate the czsc-style inventory signal registration system. It provides compile-time signature validation and automatic registration for signal functions used by czsc-signals.

czsc is part of a larger ecosystem for technical analysis, backtesting, and weight management.

• wbt (Weight Back Test): A hard dependency. It provides the WeightBacktest engine and performance reporting. czsc top-level imports like from czsc import WeightBacktest are actually forwarded from this package.
• wmr (Weight Manager): A downstream companion (not a hard dependency) used for persisting and managing strategy weights in production or research environments using DuckDB or ClickHouse.
• talib-rs: An optional dependency used only during unit testing to verify numerical parity between czsc's native TA operators and TA-Lib.

The czsc-core crate provides the fundamental implementations for Chanlun (CZSC) technical analysis, including:

• Core Types: Fractals (FX), Strokes (BI), Centers (ZS), and the CZSC analyzer.
• Basic Algorithms: K-line inclusion handling (remove_include) and stroke identification (check_bi).

To ensure candidates are not rejected as invalid clones, you must perform one of the following two types of legitimate optimization operations:

1. Entry Optimization (入场优化): Modify the signals_all, signals_any, or signals_not fields within an event in the opens list. You must replace them with a different, real, and fully classified signal to filter false breakouts or capture earlier entry points.
2. Exit Optimization (出场优化): Add a new event to the exits list using a real long-direction signal to enable earlier profit-taking and reduce drawdowns.

Note: Simply changing interval, timeout, stop_loss, or T0 is considered an invalid clone and will be rejected.

To install the precompiled version of czsc, use pip. For development environments, uv is recommended. Note that Python version must be ≥ 3.10.

Using pip:

pip install czsc -U

Using uv:

uv pip install czsc

The data_source parameter supports three modes for providing market data:

1. mock: Uses czsc.mock.generate_symbol_kines to generate deterministic market data. Ideal for testing the pipeline.
2. tushare: Fetches real market data via czsc.connectors.ts_connector.get_raw_bars. Requires a TUSHARE_TOKEN to be set in your environment or a .env file in the repository root.
3. feather: Reads standard market data from user-provided feather/ipc files. The files must contain the following columns: dt, symbol, open, close, high, low, vol, amount.

To run with Tushare and an LLM, ensure your .env contains:

TUSHARE_TOKEN=...
ANTHROPIC_BASE_URL=...
ANTHROPIC_API_KEY=...
ANTHROPIC_MODEL=...

If you are a Python user, do not use the Rust facade. Instead, install the CPython extension which is built using maturin. This provides a Python-native interface to the same core logic.

pip install czsc

You can add czsc-signals as a dependency in your Cargo.toml.

Note: Most users should prefer the facade crate czsc (cargo add czsc) which re-exports these signals under the czsc::signals namespace. Only use czsc-signals directly if you want to integrate the signal function library into your own framework without using the czsc-trader state machine.

[dependencies]
czsc-signals = "1.0"

To add czsc-trader as a direct dependency in your Rust project, add it to your Cargo.toml file.

[dependencies]
czsc-trader = "1.0"