Metadata-Version: 2.4
Name: LangSC
Version: 1.0.1
Summary: Language Structure Computation - GPF, BCC, and JSS unified package
Author: endongxun
Author-email: xunendong@gmail.com
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pywin32; platform_system == "Windows"
Requires-Dist: wordcloud
Requires-Dist: requests
Requires-Dist: chardet
Dynamic: license-file

# LangSC 使用手册

LangSC（Language Structure Computation）是一个统一的 Python 包，集成了自然语言结构分析、语料库查询和 JSON 结构检索三大功能。

包含三个独立的核心类：

| 类 | 功能 | 底层库 |
|---|------|--------|
| **GPF** | 基于网格的自然语言结构分析框架 | `gpflib.dll` |
| **BCC** | BCC 语料库查询与索引 | `bcclib.dll` |
| **JSS** | JSON 结构检索 | `jsslib.dll` |

三个类相互独立，按需导入，不会加载多余的动态库。

---

## 1. 安装

```bash
pip install LangSC
```

依赖：`pywin32`（仅 Windows）、`wordcloud`、`requests`、`chardet`

支持平台：Windows、Linux、macOS
Python 版本：>= 3.6

---

## 2. GPF 类 — 自然语言结构分析

### 2.1 初始化

```python
from LangSC import GPF

gpf = GPF("./data")
```

- `dataPath`：数据目录路径，包含 Table 和 FSA 文件
- 构造函数自动检测 `IdxLog_GPF.txt`，若数据未索引则自动索引到 `dataPathIdx/`

### 2.2 NLP 分析

```python
# 分词
result = gpf.Segment("自然语言处理是人工智能的重要方向")

# 词性标注
result = gpf.POS("自然语言处理是人工智能的重要方向")

# 统一解析接口
result = gpf.Parse("自然语言处理", Structure="Segment")  # 分词
result = gpf.Parse("自然语言处理", Structure="POS")       # 词性标注
result = gpf.Parse("自然语言处理", Structure="Tree")      # 句法树（需服务）
```

`Parse` 参数：
| 参数 | 说明 |
|------|------|
| `Structure` | `"Segment"` / `"POS"` / `"Tree"` / `"Chunk"` 等 |
| `Web` | 是否通过 Web 服务解析 |
| `Table` | 指定用户词表名 |

### 2.3 文本与网格操作

```python
gpf.SetText("今天天气很好")       # 设置文本
gpf.SetGridText("今天天气很好")   # 同上，先初始化再设置

text = gpf.GetText()              # 获取全文
text = gpf.GetText(0, 3)          # 获取范围文本
text = gpf.GetGridText()          # 同 GetText

grid = gpf.GetGrid()              # 获取网格结构（JSON）
grid = gpf.GetStructure()         # 同 GetGrid
```

### 2.4 Unit（语言单元）操作

```python
unitNo = gpf.AddUnit("天气")              # 添加 Unit
unitNo = gpf.AddUnit("天气", colNo=3)     # 指定列号

gpf.AddUnitKV(unitNo, "POS", "n")         # 添加属性

word = gpf.GetWord(unitNo)                 # 获取 Unit 文本
kvs  = gpf.GetUnitKV(unitNo)              # 获取全部属性
val  = gpf.GetUnitKV(unitNo, "POS")       # 获取指定属性
val  = gpf.GetUnitKVs(unitNo, "Word")     # 同 GetUnitKV

units = gpf.GetUnit("POS=n")              # 按条件查找 Unit
units = gpf.GetUnits("POS=n")             # 同上
unit  = gpf.GetUnit(0)                    # 按 FSA 路径号获取
unit  = gpf.GetFSAUnit(0)                 # 同上

ret = gpf.IsUnit(unitNo, "POS=n")         # 判断 Unit 属性
```

### 2.5 Relation（关系）操作

```python
gpf.AddRelation(unitNo1, unitNo2, "SBJ")              # 添加关系
gpf.AddRelationKV(unitNo1, unitNo2, "SBJ", "key", "val")  # 添加关系属性

rels = gpf.GetRelation()                               # 获取全部关系
rels = gpf.GetRelations("Role=SBJ")                    # 按条件查找

kvs = gpf.GetRelationKV(unitNo1, unitNo2, "SBJ")      # 获取关系属性
kvs = gpf.GetRelationKVs(unitNo1, unitNo2, "SBJ", "key")

ret = gpf.IsRelation(unitNo1, unitNo2, "SBJ")         # 判断关系
```

### 2.6 Grid KV（网格属性）

```python
gpf.AddGridKV("key", "val")       # 添加网格属性
gpf.AddTextKV("key", "val")       # 同上

kvs = gpf.GetGridKV()             # 获取全部网格属性
kvs = gpf.GetGridKV("key")        # 获取指定属性
kvs = gpf.GetGridKVs("key")       # 同上
kvs = gpf.GetTextKV("key")        # 同上
```

### 2.7 Table（数据表）操作

```python
gpf.SetTable("tableName")                    # 设置当前数据表
gpf.CallTable("tableName")                   # 加载并设置数据表

tables = gpf.GetTable()                       # 获取全部表名
items  = gpf.GetTableItem("tableName")        # 获取表项列表
items  = gpf.GetTableItems("tableName", "kv") # 按条件获取表项
items  = gpf.GetItem("tableName")             # 同 GetTableItem

kvs = gpf.GetTableItemKV("tableName", "item")          # 获取表项属性
kvs = gpf.GetTableItemKVs("tableName", "item", "key")  # 获取指定属性
kvs = gpf.GetItemKV("tableName", "item", "key")        # 同上

ret = gpf.IsTable("tableName", "item", "kv")  # 判断表项属性

suffix = gpf.GetSuffix("tableName", "text")   # 后缀匹配
prefix = gpf.GetPrefix("tableName", "text")   # 前缀匹配
```

### 2.8 FSA（有限状态自动机）

```python
gpf.CallFSA("fsaName", Param1="val1")  # 执行 FSA
gpf.RunFSA("fsaName")                  # 同 CallFSA

val = gpf.GetFSAParam("key")           # 获取 FSA 参数
val = gpf.GetParam("key")              # 同上

pathNo = gpf.GetFSANode("tag")         # 获取 FSA 节点
pathNo = gpf.GetNode(0)                # 按整数标签获取
```

### 2.9 索引

```python
gpf.IndexTable("table_file.txt")   # 索引 Table 文件
gpf.IndexFSA("fsa_file.txt")      # 索引 FSA 文件
```

### 2.10 Service / Dot 可视化

```python
result = gpf.CallService("text", "ServiceName")  # 调用服务
img    = gpf.Dot2Img(dot_string, "name")          # Dot 转图片

gpf.DotFile("input.dot", "output.png")            # Dot 文件转图片
gpf.DotBuff(dot_string, "output.png")             # Dot 字符串转图片文件
```

### 2.11 结构添加

```python
gpf.AddStructure(json_str)   # 添加结构（自动识别类型）
gpf.AddGrid(json_str)        # 同上
gpf.AddGridJS(json_str)      # 同上

gpf.AddSeq(json_str)         # 添加序列结构
gpf.AddTree(json_str)        # 添加树结构
gpf.AddGraph(json_str)       # 添加图结构
```

### 2.12 可视化输出

```python
gpf.Show()                                  # 显示当前网格
gpf.Show(Json=json_str)                     # 显示 JSON 结构
gpf.Show(Output="output.png")               # 指定输出文件
gpf.Show(Relation=True)                     # 显示关系
gpf.Show(Unit=unitNo)                       # 显示单个 Unit

gpf.ShowStructure(json_str, "output.png")   # 显示结构
gpf.ShowGrid("output.png")                  # 显示网格
gpf.ShowRelation("output.png")              # 显示关系图
gpf.ShowUnit(unitNo, "output.png")          # 显示 Unit 详情

# 返回 Dot 脚本（不生成文件）
dot = gpf.ShowTree(json_str)
dot = gpf.ShowSeq(json_str)
dot = gpf.ShowGraph(json_str)
gpf.ShowCloud(json_str, "output.png")       # 词云
```

### 2.13 其他

```python
log = gpf.GetLog()                          # 获取日志
unitNo = gpf.Reduce(From=0, To=5, Head=0)  # 归约操作
gpf.GPFPersons()                            # 致谢
```

---

## 3. BCC 类 — 语料库查询

### 3.1 初始化

```python
from LangSC import BCC

bcc = BCC("./corpus")
```

- `dataPath`：语料数据目录
- 构造函数自动检测 `IdxLog_BCC.txt`，若数据未索引则自动索引到 `dataPathIdx/`

### 3.2 语料查询

```python
# 频率查询（默认）
result = bcc.RunBCC("学习")

# 指定查询模式
result = bcc.RunBCC("学习", Command="Freq")
result = bcc.RunBCC("学习", Command="Freq", Number=200)
result = bcc.RunBCC("学习", Command="Context", WinSize=20, Number=100)
result = bcc.RunBCC("学习", Command="Count")

# 直接调用
result = bcc.CallBCC("学习{}Freq(100,$Q,0)")
```

`RunBCC` 参数：
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `Command` | `"Freq"` / `"Context"` / `"Count"` | `"Freq"` |
| `Number` | 返回条数 | `100` |
| `Target` | 目标字段 | `"$Q"` |
| `WinSize` | 上下文窗口大小 | `20` |
| `PageNo` | 分页页码 | `0` |
| `Print` | 输出格式，`"Lua"` 为 Lua 格式 | `""` |
| `ContextNum` | 上下文条数 | `0` |

### 3.3 KV 操作

```python
bcc.AddBCCKV("Key", "Val")    # 添加键值
result = bcc.GetBCCKV("Key")  # 获取键值
result = bcc.GetBCCKVs()      # 获取全部键值
bcc.ClearBCCKV()               # 清空键值
```

### 3.4 语料索引

```python
# 索引目录
bcc.IndexBCC("/path/to/corpus_dir")

# 索引文件列表
bcc.IndexBCC("/path/to/filelist.txt")

# 索引文件列表（Python list）
bcc.IndexBCC(["file1.txt", "file2.txt"])

# 指定索引结构
bcc.IndexBCC("/path/to/corpus", Structure="Segment")
```

---

## 4. JSS 类 — JSON 结构检索

### 4.1 初始化

```python
from LangSC import JSS

jss = JSS("./table")
```

- `dataPath`：数据目录路径
- 构造函数自动检测 `IdxLog_JSS.txt`：
  - **存在** → 已是索引目录，直接加载全部子目录中的表
  - **不存在** → 视为原始 JSON 数据目录，自动索引后加载

### 4.2 数据目录结构

原始数据目录（以 `./table` 为例）：

```
./table/
├── ci.jsonl              # 原始数据（JSONL 格式）
├── cfg_ci.txt            # ci 的配置文件（可选，缺失时自动生成）
├── audio.jsonl
├── cfg_audio.txt
└── hunxiao.json          # 也支持 .json 格式
```

**cfg 文件命名规则**：`cfg_<数据文件名>.txt`

索引后自动生成：

```
./tableIdx/
├── IdxLog_JSS.txt        # 索引日志
├── ci/                   # ci 表的索引
├── audio/                # audio 表的索引
└── hunxiao/              # hunxiao 表的索引
```

### 4.3 cfg 配置文件格式

以 `cfg_ci.txt` 为例：

```json
{
    "table_name": "ci",
    "record_format": "jsonl",
    "content": {
        "id": "id",
        "ci": "ci",
        "pos": "pos",
        "pinyin": "pinyin",
        "shiyi": "shiyi",
        "freq": "freq"
    },
    "index": {
        "number": ["id"],
        "kv": ["ci"],
        "affix": [],
        "bm25": []
    }
}
```

| 字段 | 说明 |
|------|------|
| `table_name` | 表名 |
| `record_format` | `"jsonl"`（每行一条 JSON）或 `"json"`（JSON 数组） |
| `content` | 字段映射，数组类型字段加 `[]` 后缀，如 `"tags[]": "tags[]"` |
| `index.number` | 数值索引字段（支持范围查询） |
| `index.kv` | 键值索引字段（支持精确匹配） |
| `index.affix` | 词缀索引字段 |
| `index.bm25` | 全文检索字段 |

**自动生成规则**（当 cfg 文件缺失时）：
- 读取数据文件首条记录推断 schema
- `content`：全部字段直接映射，数组字段加 `[]`
- `index.number`：`id` 字段（如为整数）
- `index.kv`：全部字符串类型字段
- `index.affix` / `index.bm25`：留空

### 4.4 查询

```python
# 查询（单表时无需指定 table）
results = jss.RunJSS("SELECT TOP 10 id, ci FROM ci WHERE pinyin = 'ai4';")

# 多表时通过 table 参数指定
results = jss.RunJSS("SELECT * FROM audio WHERE tags = 'a';", table="audio")
results = jss.RunJSS("SELECT * FROM ci WHERE pos = 'n';", table="ci")
```

SQL 语法支持：`SELECT`、`FROM`、`WHERE`、`TOP`、`AND`、`OR`，字段条件支持 `=`、`>`、`<` 等。

### 4.5 终止

```python
jss.Terminate()  # 释放全部表的句柄
```

---

## 5. 完整示例

### 5.1 GPF 分词 + 词性标注

```python
from LangSC import GPF

gpf = GPF("./data")

# 分词
seg = gpf.Parse("自然语言处理是人工智能的重要方向", Structure="Segment")
print(seg)  # ["自然", "语言", "处理", "是", ...]

# 词性标注
pos = gpf.Parse("自然语言处理是人工智能的重要方向", Structure="POS")
print(pos)  # ["自然/b", "语言/n", "处理/v", ...]
```

### 5.2 GPF 网格操作

```python
from LangSC import GPF

gpf = GPF("./data")
gpf.SetText("我喜欢北京")

u1 = gpf.AddUnit("我")
u2 = gpf.AddUnit("喜欢")
u3 = gpf.AddUnit("北京")

gpf.AddUnitKV(u1, "POS", "r")
gpf.AddUnitKV(u2, "POS", "v")
gpf.AddUnitKV(u3, "POS", "ns")

gpf.AddRelation(u2, u1, "SBJ")
gpf.AddRelation(u2, u3, "OBJ")

grid = gpf.GetGrid()
gpf.Show(Output="result.png", Relation=True)
```

### 5.3 BCC 语料查询

```python
from LangSC import BCC

bcc = BCC("./corpus")

# 词频统计
freq = bcc.RunBCC("学习", Command="Freq", Number=50)
print(freq)

# 上下文检索
ctx = bcc.RunBCC("学习", Command="Context", WinSize=30, Number=20)
print(ctx)
```

### 5.4 JSS 数据检索

```python
from LangSC import JSS

# 自动索引 + 加载（首次会自动建索引，之后直接加载）
jss = JSS("./table")

# 查询
results = jss.RunJSS("SELECT TOP 5 id, ci, pinyin FROM ci WHERE ci = '爱';")
for row in results:
    print(row)

# 清理
jss.Terminate()
```

---

## 6. 平台与文件说明

| 平台 | GPF 库 | BCC 库 | JSS 库 |
|------|--------|--------|--------|
| Windows | `gpflib.dll` | `bcclib.dll` | `jsslib.dll` |
| Linux | `libgpflib.so` | `libbcclib.so` | `libjsslib.so` |
| macOS | `libgpflib.dylib` | `libbcclib.dylib` | `libjsslib.dylib` |

包内附带的数据文件：

| 文件 | 用途 |
|------|------|
| `GPFconfig.txt` | GPF 配置 |
| `BCCconfig.txt` | BCC 配置 |
| `Parser.lua` | BCC Lua 解析脚本 |
| `Segment.dat` | CRF 分词模型 |
| `idxPOS.dat` | 词性标注数据 |
| `base.lex` | JSS 分词词典 |

---

## 7. 参考

说明文档及使用示例：http://gpf.blcu.edu.cn

> 荀恩东. 自然语言结构计算——GPF结构分析框架 [M]. 北京: 人民邮电出版社. 2022
