Metadata-Version: 2.4
Name: gsa-engine
Version: 0.1.1
Summary: GSA Architectural Design Compiler — AML-to-3D pipeline
License-Expression: MIT
Project-URL: repository, http://39.105.188.122:3000/Lab/GSA
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: lark>=1.1
Requires-Dist: pydantic>=2.0
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.20
Requires-Dist: pyyaml>=6.0
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: compas>=2.0
Requires-Dist: shapely>=2.0
Requires-Dist: networkx>=3.0
Requires-Dist: python-multipart>=0.0.6
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"

# GSA Engine

[![Release](http://39.105.188.122:3000/Lab/GSA/releases/tag/v0.1.0)](http://39.105.188.122:3000/Lab/GSA/releases/tag/v0.1.0)
![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

**GSA (Generative Space Architecture)** — 面向建筑设计的声明式编译引擎。

解析 **AML**（Architecture Markup Language），经过语义分析、空间布局求解、风格注入、行为编排、合规审计等管道，生成可交付的三维建筑模型。

---

## 安装

**私有仓库** — 包托管在实验室 Gitea 实例，非 PyPI 公开包。

```bash
# 从私有仓库直接安装
pip install http://39.105.188.122:3000/Lab/GSA/releases/download/v0.1.0/gsa_engine-0.1.0-py3-none-any.whl

# 或在项目目录下本地构建安装
pip install -e .
```

### 依赖

核心依赖在安装时自动解析：

| 包 | 用途 |
|---|---|
| `lark` | AML/DSL 语法解析 |
| `pydantic` | 数据模型与验证 |
| `fastapi` + `uvicorn` | API 服务 |
| `compas` + `shapely` | 三维几何拓扑 |
| `numpy` + `scipy` | 数值优化与求解 |
| `networkx` | 邻接图分析 |

---

## 快速入门

### 解析 AML 并检测语法错误

```python
from backend.archdsl.parser_aml import parse_aml

# 合法 AML — 返回 Project 对象
project, issues = parse_aml("""
  <project id="DEMO">
    <level id="L1" elevation="0.0m" height="3.0m">
      <space id="SP-01" type="office" area="25sqm" ceiling-height="2.8m"/>
    </level>
  </project>
""")
assert project is not None
print(f"解析成功: {project.id}, {len(project.levels)} 层")

# 非法 AML — 返回结构化错误
project, issues = parse_aml('<project><level id="L1" elev')
assert project is None
for i in issues:
    print(f"[{i['code']}] 第{i['line']}行: {i['message']}")
```

### 错误信息结构

解析失败时每条 `issue` 包含：

| 字段 | 说明 | 示例 |
|---|---|---|
| `code` | 错误编码 | `PARSE-DSL-001` |
| `category` | 错误类别 | `data_semantic` |
| `phase` | 检测阶段 | `parse` |
| `severity` | 严重级别 | `fatal` / `error` / `warning` / `info` |
| `title` | 简短标题 | `AML Syntax Error` |
| `message` | 详细描述 | 包含上下文语法的提示 |
| `line` | 行号 | `10` |
| `column` | 列号 | `5` |

错误编码体系覆盖所有管道阶段：
- `PARSE-DSL-*` — 语法解析错误
- `LINT-DSL-*` — 语义完整性检查
- `AUDIT-REG-*` — 合规审计
- `AUDIT-SPC-*` — 空间验证
- `AUDIT-GEO-*` — 几何验证
- `AUDIT-MEP-*` — 设备管道检查
- `AUDIT-CST-*` — 施工性检查

### 启动 API 服务

```bash
# 方式一：CLI 命令
gsa-api

# 方式二：模块方式
python -m backend

# 方式三：uvicorn 直接启动
uvicorn backend.main:app --reload --port 8000
```

### 完整管道

```python
from backend.logic.pipeline import DesignPipeline

pipeline = DesignPipeline()
project, layout, issues = pipeline.process(aml_text)
```

管道 9 步骤：
1. **Parse AML** → Project 模型 + 语法错误
2. **Semantic Lint** → 完整性评分
3. **SemanticAnalyzer** → COMPAS VolMesh 三维拓扑
4. **LayoutSolver** → 4 个子求解器（边界/洞口/结构/竖井）
5. **BSSApplier** → 样式属性注入
6. **BehaviorEngine** → 6 种 ArchOps 操作
7. **AuditEngine** → 合规审计
8. **DesignOptimizer** → 自动修复（最多 5 轮）
9. **Quality Gate** → 通过/警告/阻断 裁决

---

## 项目结构

```
backend/
├── main.py                # FastAPI 入口，7 个端点
├── archdsl/               # DSL 解析层
│   ├── grammar_aml.lark   # AML 文法
│   ├── grammar_bss.lark   # BSS 文法
│   ├── parser_aml.py      # AML 解析器
│   ├── parser_bss.py      # BSS 解析器
│   ├── bss_applier.py     # 风格注入
│   ├── source_editor.py   # AML 源码编辑
│   └── schemas/context.py # Pydantic 数据模型
├── kernel/                # 核心求解
│   ├── solver.py          # 布局求解主调度
│   ├── solvers/           # 4 个子求解器
│   ├── compas_bridge.py   # COMPAS VolMesh 转换
│   ├── property_cascade.py# 属性级联系统
│   └── grid_synthesizer.py# 网格自动综合
├── logic/                 # 逻辑层
│   ├── pipeline.py        # 9 步管道编排
│   ├── semantics/         # 语义分析（重构版）
│   ├── audit.py           # 合规审计引擎
│   ├── lint.py            # 语义完整性检查
│   ├── quality_gate.py    # 质量门禁
│   ├── optimizer.py       # 自动修复优化
│   └── behavior/          # 行为引擎
├── errors/                # 错误系统
│   ├── registry.py        # 23 个错误编码注册
│   ├── aggregator.py      # 去重/分组/路由
│   └── issue.py           # AuditIssue 模型
└── export/
    └── ifc_exporter.py    # IFC 导出
```

---

## 开发

```bash
# 安装全部开发依赖
pip install -r requirements.txt

# 运行测试
python3 -m pytest tests/ -v

# 构建包
python3 -m build --wheel
```

---

## 许可

MIT License

Copyright (c) 2025 ringoarch
