kousuan 0.1.3
A Python package for providing mental arithmetic calculation skills
License: MIT
Requires Python: >=3.7
Keywords: math, mental-arithmetic, calculation, education, kousuan

# Kousuan Skill

一个提供口算计算技巧的Python包，帮助提高心算能力和数学计算技巧。

## 功能特性

- 基础四则运算
- 快速加法技巧
- 快速乘法技巧
- 数字分解
- 百分比计算
- 乘法表生成
- 心算技巧集合

## 安装

```bash
pip install kousuan
```

## 使用方法

### 命令行工具

```bash
# 默认 SDK 计算
kousuan "15+17"
kousuan "81-6/3"  

## 使用AI
kousuan ask "二的五次方"
```

### Python API

```python
from kousuan.core import resolve, update_configuration

## 直接计算，可提供参考答案
results = resolve('13*17', answer=221)

## 使用AI回答(需要配置LLM, optimize=True)
update_configuration({'llm_model': 'gpt-4o-2024-11-20', 'base_url': 'xxx', 'api_key': 'xxx'})

## 求解特殊题，SDK无法直接回答的问题, 开启optimize自动使用AI回答作为兜底
response = resolve('(5+@)x5=2025', optimize=True)

## 回答开放式问题
response = resolve('西瓜每千克3.5元，香蕉每千克4.5元，都买了2千克，问一共多少钱？')
```

## 返回格式说明

| 字段名        | 类型        | 说明                                                         | 示例值                                  |
|---------------|-------------|--------------------------------------------------------------|-----------------------------------------|
| expression    | string      | 输入的口算表达式                                             | "81-6x3"                                |
| success       | boolean     | 运算是否成功（true为成功，false为失败）                       | true                                    |
| result        | string      | 运算最终结果                                                 | "63"                                    |
| name          | string      | 运算类型名称                                                 | "标准混合运算"                          |
| description   | string      | 运算类型的说明                                               | "按运算优先级处理无括号混合运算"        |
| formula       | string      | 完整运算公式（含过程与结果）                                 | "混合运算: 81-6*3 = 63"                 |
| steps         | array       | 运算步骤数组，包含每一步的详细信息                           | 见下方steps子字段示例                   |
| step_count    | number      | 运算步骤总数                                                 | 5                                       |

#### steps数组子字段说明
| 子字段名      | 类型        | 说明                                                         | 示例值                                  |
|---------------|-------------|--------------------------------------------------------------|-----------------------------------------|
| description   | string      | 该步骤的描述文字                                             | "先算乘法"                              |
| operation     | string      | 该步骤执行的操作类型                                         | "先算乘法"                              |
| result        | string      | 该步骤的运算结果或状态                                       | "-18"                                   |
| formula       | string      | 该步骤的具体运算公式                                         | "-6.0 × 3.0 = -18"                      |


## 心算技巧

本包包含多种心算技巧，包括：

- **乘以11的技巧**：两位数乘以11时，将两个数字相加，结果放在中间
- **乘以5的技巧**：乘以10再除以2
- **乘以9的技巧**：乘以10再减去原数
- **以5结尾的数字平方**：将前一位数字乘以(前一位数字+1)，后面加上25
- **百分比计算**：计算10%时，将小数点左移一位

## 开发

### 安装开发依赖

```bash
pip install -e .[dev]
```

### 运行测试

```bash
pytest
```

### 代码格式化

```bash
black kousuan/
flake8 kousuan/
```

## 许可证

MIT License

## 作者

liandong