Content
# Tool List
**Kaiwu SDK CLI & MCP Dual-Mode Tool** — Boson Quantum CIM Coherent Light Quantum Computer Python SDK Docker Packaging Tool, supporting Command Line (CLI), Python Library (import), and AI Agent (MCP) three calling methods.
> 📚 **Kaiwu SDK Official Documentation**: [https://kaiwu-sdk-docs.qboson.com/en/latest/index.html](https://kaiwu-sdk-docs.qboson.com/en/latest/index.html)
---
## Table of Contents
- [Architecture Overview](#architecture-overview)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [1. Obtain Credentials](#1-obtain-credentials)
- [2. Download SDK](#2-download-sdk)
- [3. Configure User Information](#3-configure-user-information)
- [4. Build Docker Image](#4-build-docker-image)
- [5. Generate License](#5-generate-license)
- [6. Run Scripts](#6-run-scripts)
- [CLI Usage Guide](#cli-usage-guide)
- [Python Library Usage Guide](#python-library-usage-guide)
- [MCP Server Usage Guide](#mcp-server-usage-guide)
- [Project Structure](#project-structure)
- [Frequently Asked Questions](#frequently-asked-questions)
---
## Architecture Overview
```
┌─────────────────────────────────────────────┐
│ Host Machine (Host) │
│ │
│ ┌──────────┐ ┌───────────────┐ │
│ │ CLI │ │ Python │ │ MCP Server │ │
│ │ (cli.py) │ │ Library │ │ (mcp_server) │ │
│ └────┬─────┘ │(import) │ └───────┬───────┘ │
│ │ └─────┬─────┘ │ │
│ └──────────────┼────────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ core.py │ Pure Business Logic Layer │
│ └──────┬──────┘ │
│ │ docker compose │
│ │ │
│ ┌────────────▼──────────────┐ │
│ │ user_script/ │ Script Directory (Persistent)│
│ │ ~/any/path/xxx.py │ Auto-Mount │
│ └───────────────────────────┘ │
│ │ │
└───────────────┼──────────────────────────────┘
│ volume mount
┌───────────────▼──────────────────────────────┐
│ Docker Container (kaiwu-sdk) │
│ │
│ • Python 3.10 │
│ • Kaiwu SDK v1.3.1 (Installed) │
│ • /user_script/ (Mapped from Host) │
│ • /mnt/script/ (External Script Auto-Mount) │
│ • named volume: kaiwu-license (Persistent) │
│ │
│ User Scripts Run in This Environment, Calling Kaiwu SDK │
│ Access Boson Quantum CIM Coherent Light Quantum Computer │
└──────────────────────────────────────────────┘
```
**Core Principle**: One Core Logic Layer (`core.py`), Three Thin Interface Layers (`cli.py` + Python import + `mcp_server.py`). CLI for Humans, Python Library for Program Calls, MCP for AI Agent, Sharing the Same Business Logic.
---
## Prerequisites
- **Docker** & **Docker Compose** (v2+)
- **Python 3.10** (Host Machine, Only for CLI/MCP Tool. Kaiwu SDK Only Supports 3.10)
- **Kaiwu SDK v1.3.1** (Current Compatible Version, `cp310` wheel)
- Boson Quantum Platform Account: [https://platform.qboson.com/](https://platform.qboson.com/)
---
## Quick Start
### 1. Obtain Credentials
Log in to [Boson Quantum Platform](https://platform.qboson.com/), obtain your **User ID (user_id)** and **SDK Authorization Code (sdk_code)**.
### 2. Download SDK
Visit **[SDK Download Page](https://platform.qboson.com/sdkDownload)**, download **Linux Version** of Kaiwu SDK (downloaded as `.zip` file, containing `.whl`).
Place the downloaded `.zip` (or extracted `.whl`) in the project `sdk/` directory:
```bash
# Method 1: Directly Place zip (Docker Builds Automatically Unzip)
cp ~/Downloads/kaiwu-*.zip ./sdk/
# Method 2: Extract and Place whl
unzip ~/Downloads/kaiwu-*.zip -d ./sdk/
```
Docker build will automatically process: `.zip` auto-unzip → find `.whl` → `pip install`.
### 3. Configure User Information
Edit `user_config.yaml`, fill in your credentials:
```yaml
user_id: "your_user_id_here"
sdk_code: "your_sdk_code_here"
```
### 4. Build Docker Image
```bash
# Use CLI Tool
python cli.py build
# Or Use docker compose
docker compose build --no-cache
```
### 5. Generate License
```bash
# Use Credentials in user_config.yaml
python cli.py license init
# Or Explicitly Specify Credentials
python cli.py license init --user-id "your_id" --sdk-code "your_code"
# Check License Status
python cli.py license check
```
> License persists through Docker named volume (`kaiwu-license`), `docker compose run --rm` won't lose.
### 6. Run Scripts
Write your Python scripts in **any location**, CLI will automatically mount them to Docker container for execution:
```bash
# Run Scripts in user_script/
python cli.py run example_tsp.py
# Run Scripts in Host Machine Any Location
python cli.py run /home/user/projects/my_tsp_solver.py
python cli.py run ~/Desktop/experiment.py
```
---
## CLI Usage Guide
### Command List
| Command | Description |
|------|------|
| `python cli.py build` | Build Kaiwu SDK Docker Image |
| `python cli.py license init` | Generate SDK License |
| `python cli.py license check` | Check License Status |
| `python cli.py run <script>` | Run Python Scripts (Support Host Machine Any Path) |
| `python cli.py solve --qubo '<json>'` | Directly Solve QUBO Matrix |
| `python cli.py solve --ising '<json>'` | Directly Solve Ising Matrix |
| `python cli.py solve --tsp '<distances>'` | **Automatically Compile TSP → QUBO → Solve** (via qubify) |
| `python cli.py solve --maxcut '<adjacency>'` | **Automatically Compile Max-Cut → QUBO → Solve** (via qubify) |
| `python cli.py solve --knapsack '<json>'` | **Automatically Compile Knapsack → QUBO → Solve** (via qubify) |
| `python cli.py solve --dsl '<json>'` | **Automatically Compile Custom Problem → QUBO → Solve** (via qubify) |
| `python cli.py compile --preset tsp --data '<json>'` | Compile Problem → QUBO Matrix (No Solve) |
| `python cli.py convert qubo-to-ising '<json>'` | QUBO Matrix → Ising Matrix |
| `python cli.py convert ising-to-qubo '<json>'` | Ising Matrix → QUBO Matrix |
| `python cli.py status` | View Container Status |
### Solver Parameters
`solve` command supports fine-grained solver parameter adjustment:
#### SA (Simulated Annealing) Parameters
| Parameter | Description | Default Value |
|------|------|--------|
| `--sa-temp` | Initial Temperature | 100 |
| `--sa-alpha` | Cooling Coefficient | 0.99 |
| `--sa-cutoff` | Cutoff Temperature | 0.001 |
| `--sa-iters` | Iterations per Temperature | 10 |
| `--sa-size` | Output Solution Count | 100 |
| `--sa-procs` | Parallel Processes (-1 for All Cores) | 1 |
#### CIM (Quantum Machine) Parameters
| Parameter | Description | Default Value |
|------|------|--------|
| `--cim-interval` | Polling Interval (Minutes) | 1 |
| `--cim-project` | Project Number | — |
| `--cim-task-mode` | Computing Mode (quota/sample) | quota |
| `--cim-samples` | Sampling Count (sample mode) | 10 |
### Example
```bash
# Build Image
python cli.py build
# Generate License (Using user_config.yaml)
python cli.py license init
# Run Custom Script (Any Path)
python cli.py run my_optimization.py
python cli.py run ~/projects/quantum/experiment.py
# Directly Solve QUBO (Automatically Convert to Ising + Precision Adjustment)
python cli.py solve --qubo '[[0.89, 0.22, 0.198], [0.22, 0.23, 0.197], [0.198, 0.197, 0.198]]'
# Use CIM Machine to Solve
python cli.py solve --ising '[[1, -1], [-1, 1]]' --cim --task-name "my-experiment"
# SA Solve with Parameters
python cli.py solve --qubo '[[1, 2], [0, 3]]' --sa-temp 1000 --sa-alpha 0.995 --sa-size 50
# Use CIM Sample Mode
python cli.py solve --qubo '[[1, 0], [0, 1]]' --cim --cim-task-mode sample --cim-samples 100
# Automatically Compile and Solve (via qubify)
python cli.py solve --tsp '[[0,10,15,20],[10,0,35,25],[15,35,0,30],[20,25,30,0]]'
python cli.py solve --maxcut '[[0,1,0],[1,0,1],[0,1,0]]'
python cli.py solve --knapsack '{"values":[60,100,120],"weights":[10,20,30],"capacity":50}'
# Compile Custom Problem (qubify DSL) and Solve
python cli.py solve --dsl '{"variables":{"x":("binary",(3,))},"objective":[{"coeff":1,"vars":[0,1]}],"constraints":[{"type":"one_hot","vars":[0,1,2]}]}'
# Only Compile No Solve (Output QUBO Matrix JSON)
python cli.py compile --preset maxcut --data '[[0,1,0],[1,0,1],[0,1,0]]'
# QUBO ↔ Ising Matrix Conversion
python cli.py convert qubo-to-ising '[[1, 2], [0, 3]]'
python cli.py convert ising-to-qubo '[[0, 1], [1, 0]]'
```
### Automatic Compilation and Solve (via qubify)
[kaiwu-cli-mcp](https://github.com/LehaoLin/kaiwu-cli-mcp) integrates **[qubify](https://github.com/LehaoLin/qubify)** — a constraint-to-QUBO compiler.
**This means you no longer need to manually derive QUBO matrices.** Just provide business data:
```
Your Business Data → qubify Compiler → QUBO Matrix → Kaiwu SDK → Solution
```
Supported preset problem types:
| Preset | Input | Example |
|--------|------|------|
| `tsp` | Distance Matrix `[[d00,d01,...], ...]` | Traveling Salesman Problem |
| `maxcut` | Adjacency Matrix `[[w00,w01,...], ...]` | Maximum Cut Problem |
| `knapsack` | `{"values":[], "weights":[], "capacity":N}` | 0/1 Knapsack Problem |
You can also use qubify DSL to describe arbitrary custom constraint problems:
```json
{
"variables": {"x": ("binary", (5,))},
"objective": [{"coeff": -1.0, "vars": [0]}],
"constraints": [
{"type": "one_hot", "vars": [0, 1, 2]},
{"type": "cardinality", "vars": [3, 4], "rhs": 1}
]
}
```
Compilation and solving are completed on the **host machine** (qubify doesn't need to be installed in Docker), only the final matrix is passed into Docker to call Kaiwu SDK.
### Solving Process
Internal processing flow of `solve --qubo` and `solve --ising`:
```
--qubo Input → QUBO→Ising Conversion (kw.conversion) → Precision Adjustment (kw.ising) → Optimizer Solve → Output
--ising Input → Precision Adjustment (kw.ising) → Optimizer Solve → Output
```
QUBO matrix is automatically converted to Ising format through `kw.conversion.qubo_matrix_to_ising_matrix()`,
and adjusted in precision through `kw.ising.adjust_ising_matrix_precision()` to ensure compatibility with CIM hardware.
### Writing User Scripts
Create `.py` files in **any location**, directly `import kaiwu as kw` to use the SDK.
- **Recommended Practice**: Place scripts in `user_script/` directory (this directory is mapped to container `/user_script/`, execution is fastest)
- **Flexible Practice**: Place scripts in host machine any path, CLI will automatically mount the script directory in read-only mode to container's `/mnt/script/`, then execute with Kaiwu SDK environment in container
Refer to [Kaiwu SDK Official Documentation - TSP Tutorial](https://kaiwu-sdk-docs.qboson.com/en/latest/index.html) to learn QUBO/Ising modeling methods.
```python
# user_script/my_solver.py
import numpy as np
import kaiwu as kw
# Define QUBO Matrix
matrix = np.array([[0.89, 0.22], [0.22, 0.23]])
# Adjust Precision
adjusted = kw.qubo.adjust_qubo_matrix_precision(matrix)
# Use Simulated Annealing to Solve
opt = kw.classical.SimulatedAnnealingOptimizer()
solution = opt.solve(adjusted)
print(f"Solution: {solution}")
```
---
## Python Library Usage Guide
`kaiwu-cli-mcp` supports being used as a Python library to import and use directly in code. Core module `core.py` returns structured dict, suitable for embedding into other programs.
### Installation
**Method 1: pip install (Recommended)**
```bash
# Install from Local Source Code (Editable Mode)
cd /path/to/kaiwu-cli-mcp
pip install -e .
```
# Tool List
## Import kaiwu_cli_mcp from any directory
python -c "import kaiwu_cli_mcp; print(kaiwu_cli_mcp.__doc__)"
```
You can also use the command-line interface directly after installation:
```bash
kaiwu-cli build
kaiwu-cli solve --qubo '[[1, 0], [0, 1]]'
```
**Method 2: Manually add path**
```bash
cp -r kaiwu-cli-mcp /your/project/vendor/
```
```python
import sys
sys.path.insert(0, "/your/project/vendor/kaiwu-cli-mcp")
from core import solve_qubo, compile_and_solve
```
### Usage Examples
```python
from core import build_image, init_license, check_license, run_script
from core import solve_qubo, solve_ising, compile_and_solve, compile_problem
from core import container_status, convert_qubo_to_ising, convert_ising_to_qubo
# Build Docker image
result = build_image()
print(result) # {"success": True, "message": "Docker image built successfully", ...}
# Generate license
result = init_license("your_user_id", "your_sdk_code")
# Directly solve QUBO matrix
result = solve_qubo('[[0.89, 0.22], [0.22, 0.23]]')
if result["success"]:
print(result["output"]) # Solution result
# Use CIM quantum computer
result = solve_ising(
'[[1, -1], [-1, 1]]',
use_cim=True,
task_name="my-experiment",
)
# Automatically compile and solve TSP
result = compile_and_solve(
preset="tsp",
data='[[0,10,15,20],[10,0,35,25],[15,35,0,30],[20,25,30,0]]',
)
# Automatically compile and solve Knapsack
result = compile_and_solve(
preset="knapsack",
data='{"values":[60,100,120],"weights":[10,20,30],"capacity":50}',
)
# Specify SA solver parameters
result = solve_qubo(
'[[1, 0], [0, 1]]',
sa_params={"initial_temperature": 1000, "alpha": 0.995, "size_limit": 50},
)
# Compile problem (no solution), output QUBO matrix
result = compile_problem(preset="maxcut", data='[[0,1,0],[1,0,1],[0,1,0]]')
if result["success"]:
print(result["qubo_matrix"]) # QUBO matrix in JSON format
print(result["var_map"]) # Variable mapping
# Matrix conversion
result = convert_qubo_to_ising('[[1, 2], [0, 3]]')
# result["output"] contains {"ising_matrix": ..., "bias": ...}
# Check container status
result = container_status()
```
### Function Return Value Convention
All functions return a unified dict structure:
```python
# Success
{"success": True, "message": "...", "output": "..."}
# Failure
{"success": False, "message": "...", "output": "..."}
```
### Docker Dependency Description
| Function | Requires Docker | Description |
|------|------------|------|
| `build_image` | Yes | Build Kaiwu SDK image |
| `init_license` | Yes | Execute Kaiwu SDK in container |
| `check_license` | Yes | Check license file in container |
| `run_script` | Yes | Execute user script in container |
| `solve_qubo` | Yes | Call Kaiwu SDK to solve in container |
| `solve_ising` | Yes | Call Kaiwu SDK to solve in container |
| `compile_and_solve` | Yes | Compile QUBO on host → solve in container |
| `compile_problem` | No | Pure Python, compile QUBO on host (requires `qubify`) |
| `convert_qubo_to_ising` | Yes | Convert in container with Kaiwu SDK |
| `convert_ising_to_qubo` | Yes | Convert in container with Kaiwu SDK |
| `container_status` | Yes | docker compose ps |
---
## MCP Server Usage Guide
MCP (Model Context Protocol) mode allows AI Agent to directly call Kaiwu SDK.
Supports MCP configuration for the following AI coding tools: **Hermes Agent**, **Claude Code**, **OpenAI Codex**, **OpenCode**.
### Start MCP Server
```bash
cd /root/kaiwu-cli-mcp
pip install -r requirements.txt # Install fastmcp dependencies
python mcp_server.py # Start MCP Server (stdio mode)
```
---
### MCP Configuration Methods for Each Tool
#### Hermes Agent
Edit `~/.hermes/config.yaml`:
```yaml
mcpServers:
kaiwu-sdk-tools:
command: python
args: ["/root/kaiwu-cli-mcp/mcp_server.py"]
```
#### Claude Code
**Method 1: CLI Command** (recommended)
```bash
claude mcp add --transport stdio kaiwu-sdk-tools -- python /root/kaiwu-cli-mcp/mcp_server.py
```
**Method 2: `.mcp.json` file** (project-level, git-trackable)
Create `.mcp.json` in project root:
```json
{
"mcpServers": {
"kaiwu-sdk-tools": {
"command": "python",
"args": ["/root/kaiwu-cli-mcp/mcp_server.py"]
}
}
}
```
- **Local scope** (only current project, gitignored): `claude mcp add --scope local ...`
- **Project scope** (team-shared): `claude mcp add --scope project ...`
- **User scope** (global for all projects, `~/.claude.json`): `claude mcp add --scope user ...`
Use `/mcp` in Claude Code TUI to view and manage all MCP servers.
#### OpenAI Codex
Edit `~/.codex/config.toml`:
```toml
[mcp_servers.kaiwu-sdk-tools]
command = "python"
args = ["/root/kaiwu-cli-mcp/mcp_server.py"]
```
> Refer to [Codex configuration documentation](https://github.com/openai/codex/blob/main/docs/config.md) for detailed configuration parameters.
#### OpenCode
Create `opencode.json` (or `opencode.jsonc` for comments) in project root:
```json
{
"mcp": {
"kaiwu-sdk-tools": {
"type": "local",
"command": ["python", "/root/kaiwu-cli-mcp/mcp_server.py"]
}
}
}
```
> Refer to [OpenCode configuration documentation](https://opencode.ai/docs/) for detailed configuration parameters.
Use `/mcps` in OpenCode TUI to manage MCP servers.
---
### Available MCP Tools
After configuration, AI Agent can automatically discover the following tools:
| Tool Name | Description |
|--------|------|
| `kaiwu_build_image` | Build Kaiwu SDK Docker image |
| `kaiwu_init_license` | Generate SDK License (specify user_id/sdk_code) |
| `kaiwu_check_license` | Check License status |
| `kaiwu_run_script` | Run Python script (support arbitrary host path, auto-mount to Docker) |
| `kaiwu_solve_qubo` | Solve QUBO matrix (auto-convert to Ising + precision adjustment) |
| `kaiwu_solve_ising` | Solve Ising matrix (auto-precision adjustment) |
| `kaiwu_solve_preset` | **Automatically compile + solve (tsp/maxcut/knapsack)** via qubify |
| `kaiwu_solve_dsl` | **Automatically compile + solve (custom DSL)** via qubify |
| `kaiwu_compile_problem` | Compile problem → QUBO matrix (no solution) via qubify |
| `kaiwu_convert_qubo_to_ising` | QUBO matrix → Ising matrix |
| `kaiwu_convert_ising_to_qubo` | Ising matrix → QUBO matrix |
| `kaiwu_container_status` | View Docker container status |
All solving tools support `sa_params` and `cim_params` parameters (JSON format) to adjust optimizer behavior.
---
## Project Structure
```
kaiwu-cli-mcp/
├── cli.py # CLI entry (argparse)
├── mcp_server.py # MCP Server entry (FastMCP)
├── core.py # Pure business logic layer (importable)
├── config.py # Shared configuration reading
├── converters.py # qubify converter encapsulation
├── __init__.py # Python package entry
├── pyproject.toml # Python package configuration
├── user_config.yaml # User credential configuration ★edit this file★
├── Dockerfile # Kaiwu SDK Docker environment
├── docker-compose.yml # Docker orchestration (map user_script/ + license persistence)
├── requirements.txt # Python dependencies
├── README.md # This file
├── sdk/ # Place Kaiwu SDK .whl/.zip files
│ └── .gitkeep
└── user_script/ # User script directory ★write scripts here★
└── example_tsp.py # TSP example script
```
---
## Frequently Asked Questions
### Q: Where to download SDK .whl?
Log in to [https://platform.qboson.com/](https://platform.qboson.com/), select Linux version on the download page. File name example: `kaiwu-1.3.1-cp310-cp310-linux_x86_64.whl`.
### Q: How to confirm License generation success?
```bash
python cli.py license check
```
License persists through Docker named volume, will not be lost due to container restart.
### Q: How to directly enter Docker container for debugging?
```bash
docker compose run --rm kaiwu bash
```
Enter and directly use `python3` for interactive Kaiwu SDK usage.
### Q: Which solvers are supported?
- **SimulatedAnnealingOptimizer** (`kw.classical`) — Classical simulated annealing, no internet required
- **CIMOptimizer** (`kw.cim`) — Coherent Ising Machine real machine, requires cloud platform quota
Adjust solver parameters with CLI options `--sa-*` and `--cim-*`.
### Q: Python version requirements?
Kaiwu SDK v1.3.1 only supports **Python 3.10** (no minor version distinction). Docker image uses `python:3.10-slim`.
### Q: How is License persistence implemented?
Through Docker Compose's named volume `kaiwu-license`, mounted to SDK's license directory in container. Even if `docker compose run --rm` removes the container, license files remain in named volume. To clear license, run `docker volume rm kaiwu-cli-mcp_kaiwu-license`.
---
## Reference Links
- [Kaiwu SDK Official Documentation](https://kaiwu-sdk-docs.qboson.com/zh/latest/index.html)
- [Qboson Quantum Platform](https://platform.qboson.com/)
- [Kaiwu SDK Module Manual](https://kaiwu-sdk-docs.qboson.com/zh/latest/source/modules/index.html) — kaiwu.cim / kaiwu.qubo / kaiwu.license / kaiwu.conversion etc.
- [Kaiwu SDK Installation Instructions](https://kaiwu-sdk-docs.qboson.com/zh/latest/source/getting_started/sdk_installation_instructions.html)
- [Kaiwu SDK QUBO Modeling Tutorial (TSP)](https://kaiwu-sdk-docs.qboson.com/zh/latest/source/getting_started/tutorial_tsp.html)
---
## License
This tool is an open-source project. Kaiwu SDK copyright belongs to [Beijing Qboson Quantum Technology Co., Ltd.](https://www.qboson.com/).
