# NLC

**Repository Path**: yokay/nlc

## Basic Information

- **Project Name**: NLC
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NLC Compiler

**自然语言编译器** — 以自然语言为中间表示的模型驱动编译系统，面向 RP2040 嵌入式平台。

> **设计不变量**：模型负责"快和理解"，确定性工具负责"合法和正确"。

NLC Compiler 把传统编译器的"前端解析器 → 计算图 IR → 后端代码生成"三段式结构，重新定义为"大模型前端 → 自由自然语言 IR → 专用小模型后端"的变换流水线。程序员用自然语言提示词描述意图，编译器将其扩展为自由自然语言中间表示（NLC IR），人可以在 NLC IR 层面阅读、调试、迭代需求；随后后端小模型直接阅读自然语言 IR，理解意图后编译为 RP2040 可执行的汇编 / UF2 二进制。从提示词到机器码的每一跳变换都必须签发可机器校验的**规格满足证书**，不通过则回退重生成。

完整设计文档见 [nlc-compiler-design.md](./nlc-compiler-design.md)（含 9 章正文 + 10 张架构图）。

---

## 状态

v0.1 — Draft。流水线已端到端打通（含 Mock LLM 适配器，无需 GPU 即可跑通），确定性后端 + 规格验证器 + 证书签发已落地，模型层（前端 / 规格提取 / 后端 + RAG + 策略 + 反馈重试）已实现并通过 142 条测试（其中 `test_model.py` 92 条）。SMT 求解器（Z3）与符号执行（KLEE）的外部集成、模型量化 / vLLM 部署为后续工作。

---

## 目录结构

```
nlc/
├── ir.py                  # NLC IR — 自由自然语言中间表示
├── spec.py                # 形式化规格 (I/O 契约 / 时序 / 不变量 / 行为规约)
├── compiler.py            # compile() + compile_with_model() + ModelCompileResult
├── errors.py              # NLCError / CompileError / CertificateError
├── cli.py                 # 命令行入口 (compile / verify / disasm / keygen
│                          #   + model-compile / extract-spec / expand-ir)
├── backend/               # 确定性后端 (第 04 章 + 第 06 章)
│   ├── asm.py             #   ARMv6-M Thumb-2 编码器
│   ├── emitter.py         #   ASM 发射器
│   ├── legality.py        #   合法性检查 (指令集 / 寄存器 / 寻址模式)
│   ├── rp2040.py          #   RP2040 平台适配
│   └── uf2.py             #   UF2 二进制生成
├── verifier/              # 验证与证书体系 (第 05 章)
│   ├── certificate.py     #   证书签发 + ed25519 签名
│   ├── simulator.py       #   指令级模拟器
│   └── spec_verifier.py   #   规格满足验证 (Level 1 形式化 / Level 2 测试)
└── model/                 # 模型层 (第 08-09 章)
    ├── llm_adapter.py     #   LLMAdapter 抽象 + Mock + API + make_adapter 工厂
    ├── frontend.py        #   FrontendLLM: 短提示词 → 完整 NL IR
    ├── spec_extractor.py  #   SpecExtractor: NL IR → 形式化 Spec
    ├── backend_model.py   #   BackendModel: RAG + 策略 + 反馈重试 + parse_asm_text
    ├── strategy.py        #   4 策略 (busy_wait/timer_irq/pwm_hardware/pio_state_machine)
    ├── prompt.py          #   prompt 模板 + make_feedback (反馈重试演进)
    ├── rag.py             #   Retriever: 3 子库 (pico_sdk/datasheet/pio) + TF-IDF cosine
    └── training.py        #   PretrainPair / FinetunePair / DPOPreference + filter_verified

scripts/
└── train_backend_model.py # 三阶段训练 (Stage1 预训练 / Stage2 微调 / Stage3 DPO)

tests/                     # 142 条测试 (全量通过)
├── test_asm_encoder.py
├── test_certificate.py
├── test_compiler.py
├── test_legality.py
├── test_model.py          # 92 条 — 模型层
├── test_simulator.py
├── test_uf2.py
├── test_verifier.py
└── fixtures/              # breathing_led.nl.txt + breathing_led.spec.json

data/train/                # 训练数据样本 (pretrain / finetune / dpo .jsonl)
nlc-compiler-design.md     # 完整设计文档
nlc-compiler-design.html   # 设计文档 HTML 版
```

---

## 安装

依赖 Python 3.9+，目前仅依赖标准库（TF-IDF RAG / 模拟器 / 证书签名均为纯 Python 实现，无外部依赖）。

```bash
git clone https://gitee.com/yokay/nlc.git
cd nlc
python -m pytest tests/        # 验证安装：应输出 142 passed
```

可选：连接真实 LLM 时设置环境变量（`APILLMAdapter` 读取）：

```bash
set NLC_LLM_BASE_URL=https://api.openai.com/v1
set NLC_LLM_API_KEY=sk-...
set NLC_LLM_MODEL=gpt-4o-mini
```

---

## 使用

### 1. 确定性流水线（无模型，手工写 NL IR + Spec）

```bash
# 编译：NL IR + Spec → ASM → UF2 + 证书
python -m nlc.cli compile tests/fixtures/breathing_led.nl.txt \
    tests/fixtures/breathing_led.spec.json \
    --kind breathing_led --level 1 -o build/breathing_led.uf2

# 验证：用公钥复检既有产物三元组
python -m nlc.cli verify tests/fixtures/breathing_led.nl.txt \
    tests/fixtures/breathing_led.spec.json build/breathing_led.asm.bin \
    build/breathing_led.cert.json --pubkey pub.bin

# 反汇编：打印确定性 ASM 列表
python -m nlc.cli disasm tests/fixtures/breathing_led.spec.json --kind breathing_led

# 密钥：生成 ed25519 签名密钥对
python -m nlc.cli keygen key.bin --pubkey pub.bin
```

### 2. 模型驱动流水线（第 08-09 章）

```bash
# expand-ir: 短提示词 → 完整自然语言 IR (FrontendLLM)
python -m nlc.cli expand-ir "让 GP25 的 LED 每 500 毫秒闪烁一次" -o led_blink.nl.txt

# extract-spec: NL IR → 形式化规格 (SpecExtractor)
python -m nlc.cli extract-spec led_blink.nl.txt -o led_blink.spec.json

# model-compile: NL IR → ASM → UF2 + 证书 (BackendModel, 含 RAG + 策略 + 反馈重试)
python -m nlc.cli model-compile led_blink.nl.txt -o led_blink.uf2 \
    --adapter mock                    # mock 用于离线 / CI；省略则用 API 适配器
```

未指定 `--adapter mock` 且未配置 LLM 环境变量时，CLI 会给出明确提示而非崩溃。

### 3. 后端模型训练（第 09 章）

```bash
# 三阶段训练脚本（需 GPU + Qwen-Code-7B 基座）
# Stage1 预训练 (C→ASM) / Stage2 微调 (NL→ASM, spec-verified) / Stage3 DPO (策略选择)
python scripts/train_backend_model.py --stage all \
    --data-source E:\github\pico-examples \
    --workspace F:\NLC
```

脚本内嵌详细 loss 诊断日志（7 个关键节点 + spike / NaN / grad explosion 预警）。训练数据通过 `nlc.model.training.filter_verified` 质量门——未通过规格验证的样本不进入训练集。

---

## 设计要点

| 维度 | 选择 | 理由 |
| --- | --- | --- |
| IR 介质 | 自由自然语言（无文法、无 AST） | 零认知负担；小模型的理解能力正是其存在理由 |
| 验证方式 | 规格提取 → 规格满足验证（两跳） | 兼容自由自然语言；人确认规格，机器验证 ASM |
| 后端架构 | 小模型 + 合法性检查 + 规格验证（三重） | 模型负责快和理解，确定性工具负责合法和正确 |
| 失败回退 | 四级（重新生成 → 重新提取规格 → 降级验证 → 终止） | 系统永不输出未通过验证的代码 |
| 目标平台 | RP2040 (Cortex-M0+, 264KB SRAM, PIO) | 平台特化的小模型蒸馏 |
| 模型基座 | Qwen-Code-7B + LoRA 微调 | 中英双语覆盖；LoRA 训练参数量 0.1-1% |
| 训练数据 | 三阶段（C→ASM 预训练 / NL→ASM 微调 / DPO 策略选择） | 数据源 pico-examples；规格验证过滤保证教师不教错 |

---

## 测试

```bash
python -m pytest tests/ -v
```

142 条测试覆盖：ASM 编码器、合法性检查、UF2 生成、证书签发与验证、规格验证器、模拟器、编译流水线、模型层（前端 / 规格提取 / 后端 / RAG / 策略 / 反馈重试 / 训练数据）。`MockLLMAdapter` 使模型驱动流水线可在 CI 中无 GPU 端到端跑通。

---

## 许可

本仓库源码按 MIT 许可发布；设计文档（`nlc-compiler-design.md` / `.html`）按 CC-BY 4.0 许可。