simplecadapi 2.0.0__tar.gz → 2.0.0b2__tar.gz

simplecadapi-2.0.0b2/.gitignore

@@ -0,0 +1,27 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.env
+
+output/
+
+# Sandbox artifacts
+sandbox/
+
+# Generated skills archives
+skills/*.tar.gz
+
+.DS_Store
+
+# CAD/export artifacts
+*.step
+*.stl
+examples.py

{simplecadapi-2.0.0 → simplecadapi-2.0.0b2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: simplecadapi
-Version: 2.0.0
-Summary: A simplified CAD modeling Python API based on CADQuery
+Version: 2.0.0b2
+Summary: A simplified OCP-native CAD modeling Python API
 Project-URL: Homepage, https://github.com/NiJingzhe/SimpleCADAPI
 Project-URL: Repository, https://github.com/NiJingzhe/SimpleCADAPI
 Project-URL: Documentation, https://github.com/NiJingzhe/SimpleCADAPI#readme
@@ -348,7 +348,7 @@ License:                     GNU GENERAL PUBLIC LICENSE
         library.  If this is what you want to do, use the GNU Lesser General
         Public License instead of this License.
 License-File: LICENSE
-Keywords: 3d,cad,cadquery,design,modeling
+Keywords: 3d,cad,design,modeling,ocp,opencascade
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Manufacturing
@@ -361,7 +361,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.10
-Requires-Dist: cadquery>=2.5.2
+Requires-Dist: cadquery-ocp>=7.8.1
 Requires-Dist: numpy>=1.21.0
 Requires-Dist: rich>=14.0.0
 Provides-Extra: dev
@@ -371,93 +371,218 @@ Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Provides-Extra: editor
-Requires-Dist: cq-editor>=0.5.0; extra == 'editor'
 Description-Content-Type: text/markdown
 
-# CAD建模形式化Python API设计与实现
+# SimpleCADAPI
 
----
+SimpleCADAPI is an OCP-native imperative CAD modeling Python package. It keeps the 1.x-style functional API while adding v2 graph recording, expression parameters, and replayable model JSON workflows.
 
-## 简介
+## README Scope
 
-本项目旨在使用CadQuery的occ impl.shapes中提供的方法，编写一套命令式的Python API，以简化通过代码进行CAD建模的过程。API设计遵循开放封闭原则，核心类型封闭，所有的操作和扩展都通过新建函数实现。
-同时兼容Numpy库，允许用户在几何体上进行高效的数学运算和变换。
+This README only covers package-level capabilities, installation methods, publishing/packaging workflows, and Skills usage instructions.
+Experimental scripts and temporary modeling examples are not included as formal documentation.
 
-## 详细文档
+## Package Installation (Python Package Managers)
 
-![Document](./docs/)
+Current package name: `simplecadapi` (see `pyproject.toml` for the version).
 
-## 基础类型
+### Method A: Install from package repository with pip
 
-### 图元类型
+```bash
+pip install simplecadapi
+```
 
-图元类型和OCP的TopoDS_Shape类型一一对应，主要包括以下几种：
+Optional development dependencies:
 
-- `Solid`: 实体类型，表示封闭的三维几何体。
-- `Face`: 面类型，表示单个表面。
-- `Edge`: 边类型，表示曲线边界。
-- `Vertex`: 顶点类型，表示几何体的点。
-- `Wire`: 线类型，表示边的集合。
+```bash
+pip install "simplecadapi[dev]"
+```
 
-### 坐标系类型
+### Method B: Install with uv
 
-坐标系类型用于定义三维空间中的位置和方向，我们对于世界坐标系的定义是：一个右手坐标系，原点在(0, 0, 0)，默认X轴向前，Y轴向右，Z轴向上。坐标系类型包括：
+Install in the current virtual environment:
 
-- `SimpleWorkplane`: 工作平面类型，表示一个二维平面，本质上统计一个原点和一个法向量和一个X轴方向向量。作为一个上下文变量，可以通过with语法包裹操作，那么这些操作就会在这个工作平面下进行。允许嵌套定义Workplane，那么嵌套定义的平面将在上一个平面的基础上进行变换。
+```bash
+uv pip install simplecadapi
+```
 
-## API命名风格
+Add as a project dependency in `pyproject.toml`:
 
-- 所有函数名使用小写字母和下划线分隔（snake_case），要求使用动词开头，表示操作或行为，同时需要包含API的返回类型(因为同名API可能会重载为返回不同类型的对象，但我们想要避免这一点)，例如：`make_circle_rwire`, `make_circle_redge`, `make_circle_rface`, `extrude_rsolid`等
-- 类名使用驼峰命名法（CamelCase）
-- 函数和类的文档字符串使用Google风格，包含参数、返回值和异常说明
-- 所有函数和类都应有类型注解，确保代码的可读性和可维护性
-- 所有函数和类都应有详细的文档字符串，描述其功能、参数、返回值和异常
-- 所有函数和类都应有示例代码，便于用户理解和使用
-- 所有的代码实现都要有严格且详细的try catch和异常抛出，异常抛出的内容中要求明确指出错误原因，以及用户应当如何在调用层做出怎样的改进可能可以避免这个问题。
+```bash
+uv add simplecadapi
+```
 
-## 扩展原则
+### Method C: Install from local build artifacts
 
-开放封闭原则，核心类型封闭，所有的操作和扩展都通过新建函数实现。我们可以通过利用现有的函数和操作来组合出新的高级操作并封装为函数来实现功能的扩展。
+Build a local wheel/sdist first if you want to install from local artifacts:
 
-## 自动化工具 (Auto Tools)
+```bash
+uv build
+```
 
-项目包含一套自动化工具，用于支持API的自进化开发流程：
+## Quick Verification of Installation
 
-### 主要CLI工具
+```python
+import simplecadapi as scad
 
-#### 1. `auto_docs_gen.py` - 动态文档生成
-- **功能**: 自动从`operations.py`和`evolve.py`中提取所有API函数
-- **特点**:
-  - 解析函数签名、文档字符串、参数说明、返回值、异常信息
-  - 自动清理已删除API对应的过期文档
-  - 支持多源文件与多输出目录参数（`--source`、`--output-dir`）
-- **输出**: 生成格式统一的Markdown文档到`docs/api/`目录（默认）
-- **使用**: `auto-docs-gen [--source <path>] [--output-dir <dir>] [--no-clean]`
+box = scad.make_box_rsolid(10.0, 20.0, 30.0)
+scad.export_stl(box, "example_box.stl")
+scad.export_step(box, "example_box.step")
+```
 
-#### 2. `make_export.py` - 动态修改__init__.py
-- **功能**: 自动更新`__init__.py`文件中的导入和导出
-- **特点**: 
-  - 自动检测新增的API函数
-  - 按功能分类组织导入语句
-  - 生成友好的别名映射
-  - 支持预览模式(`--dry-run`)和强制模式(`--force`)
-- **使用**: `python make_export.py [--dry-run] [--force]`
+## How to Package SDK Skills
 
-#### 3. `evolution.py` - 代码自进化
-- **功能**: 从指定脚本中自动抽取新的建模函数并添加到`evolve.py`
-- **特点**: 
-  - 提取函数完整实现代码
-  - 自动处理导入语句
-  - 支持代码自进化开发流程
-- **使用**: `python evolution.py <script_path>`
+This project provides the `skill-pack` CLI for generating lightweight SDK reference skills: **No built-in SDK source code**, focused on API and architecture descriptions.
 
-### 自进化开发流程
+### 1) Packaging Command
 
-这套工具支持以下自进化开发流程：
+Execute in the repository root directory:
 
-1. **开发新API**: 在`operations.py`或`evolve.py`中添加新函数
-2. **自动导出**: 运行`make_export.py`更新`__init__.py`
-3. **生成文档**: 运行`auto_docs_gen.py`生成API文档
-4. **持续进化**: 重复上述流程实现API的持续进化
+```bash
+uv run skill-pack --refresh-docs --archive --skill-name simplecadapi
+```
 
-所有工具都支持错误处理和详细的日志输出，确保开发流程的稳定性和可追踪性。
+Common parameters:
+
+- `--output-root <dir>`: Output directory (default `./skills`)
+- `--package-name <pkg>`: Runtime installation package name (default reads from `project.name`)
+- `--package-version <ver>`: Runtime installation version (default reads from `project.version`)
+- `--no-clean`: Do not clean existing output directory
+- `--archive`: Additionally generate `<skill-name>.tar.gz`
+
+### 2) Packaging Result Structure
+
+After packaging, you will get a directory similar to:
+
+- `skills/simplecadapi/SKILL.md`
+- `skills/simplecadapi/references/`
+- `skills/simplecadapi/references/docs/api/`
+- `skills/simplecadapi/references/docs/core/`
+
+### 3) Read the SDK skill
+
+```bash
+cd skills/simplecadapi
+```
+
+Key entry points:
+
+- `skills/simplecadapi/SKILL.md`
+- `skills/simplecadapi/references/SDK_OVERVIEW.md`
+- `skills/simplecadapi/references/SDK_SURFACES.md`
+- `skills/simplecadapi/references/V2_MODELING_WORKFLOWS.md`
+- `skills/simplecadapi/references/SDK_PACKAGE_SUMMARY.md`
+- `skills/simplecadapi/references/docs/api/README.md`
+- `skills/simplecadapi/references/docs/core/README.md`
+
+### 4) Preferred v2 replay workflow
+
+```python
+from simplecadapi import GraphSession, export_model_json, replay_model_json
+
+with GraphSession() as session:
+    ...
+
+model_json = export_model_json(session)
+rebuilt = replay_model_json(model_json)
+print(len(rebuilt))
+```
+
+## Serialization and Replay Docs
+
+For detailed operation-by-operation JSON formats and replay behavior, see:
+
+- [`docs/core/serialization/README.md`](docs/core/serialization/README.md)
+- [`docs/core/operation_graph_json_spec.md`](docs/core/operation_graph_json_spec.md)
+- [`examples/07_serialization_operation_tree.py`](examples/07_serialization_operation_tree.py)
+
+## Auto Tools
+
+The project includes 4 main CLIs:
+
+- `auto-docs-gen`: Generate `docs/api/` documentation from the public API source surface
+- `make-export`: Update imports/exports in `src/simplecadapi/__init__.py`
+- `evolve`: Extract functions from scripts for repository-managed evolve modules
+- `skill-pack`: Package thin SDK skill (documentation only)
+
+Examples:
+
+```bash
+uv run make-export --dry-run
+uv run auto-docs-gen
+uv run evolve path/to/your_case.py
+uv run skill-pack --refresh-docs --archive
+```
+
+## RAGFlow Documentation Sync
+
+`scripts/sync_ragflow_docs.py` is used to incrementally sync Markdown files under `docs/` to the specified RAGFlow dataset, chunked by H2 headings; the document's `chunk_method` is set to `manual`.
+
+Prepare the environment:
+
+```bash
+.venv/bin/python -m pip install ragflow-sdk
+```
+
+It is recommended to use `.env` (already added to `.gitignore`):
+
+```bash
+RAGFLOW_API_KEY=your_key_here
+RAGFLOW_BASE_URL=http://localhost
+RAGFLOW_DATASET_NAME=SimpleCADAPI
+```
+
+Run the sync:
+
+```bash
+set -a && source .env && set +a
+.venv/bin/python scripts/sync_ragflow_docs.py --create-dataset
+```
+
+Common parameters:
+
+- `--dataset-id` / `RAGFLOW_DATASET_ID`: Directly specify the dataset ID (avoid name conflicts)
+- `--delete-removed`: Delete documents that have been removed locally
+- `--dry-run`: Only preview changes without executing writes
+- `--progress-interval N`: Print progress every N documents
+
+## Development and Testing
+
+Local development installation (editable):
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+Run unit tests:
+
+```bash
+uv run python -m unittest test/test_all_features.py
+```
+
+Run examples:
+
+```bash
+uv run python examples/01_basic_modeling.py
+uv run python examples/02_graph_replay.py
+uv run python examples/03_expressions.py
+uv run python examples/05_loft_sweep_revolve.py
+uv run python examples/06_parametric_gear_model.py
+uv run python examples/07_serialization_operation_tree.py
+```
+
+## Core Design Constraints (Brief)
+
+- API functions uniformly use `snake_case` and reflect return types in function names (e.g., `*_rsolid`, `*_rwire`).
+- Core types are OCP-native wrappers and are kept as stable as possible; functionality is extended by adding new functions (Open-Closed Principle).
+- Support `SimpleWorkplane` context for local coordinate modeling.
+- Export interfaces support single entities, multiple entities, and nested list inputs.
+
+## Documentation Entry Points
+
+- API documentation: `docs/api/`
+- Core documentation: `docs/core/`
+
+## License
+
+MIT, see `LICENSE`.

simplecadapi-2.0.0b2/README.md

@@ -0,0 +1,213 @@
+# SimpleCADAPI
+
+SimpleCADAPI is an OCP-native imperative CAD modeling Python package. It keeps the 1.x-style functional API while adding v2 graph recording, expression parameters, and replayable model JSON workflows.
+
+## README Scope
+
+This README only covers package-level capabilities, installation methods, publishing/packaging workflows, and Skills usage instructions.
+Experimental scripts and temporary modeling examples are not included as formal documentation.
+
+## Package Installation (Python Package Managers)
+
+Current package name: `simplecadapi` (see `pyproject.toml` for the version).
+
+### Method A: Install from package repository with pip
+
+```bash
+pip install simplecadapi
+```
+
+Optional development dependencies:
+
+```bash
+pip install "simplecadapi[dev]"
+```
+
+### Method B: Install with uv
+
+Install in the current virtual environment:
+
+```bash
+uv pip install simplecadapi
+```
+
+Add as a project dependency in `pyproject.toml`:
+
+```bash
+uv add simplecadapi
+```
+
+### Method C: Install from local build artifacts
+
+Build a local wheel/sdist first if you want to install from local artifacts:
+
+```bash
+uv build
+```
+
+## Quick Verification of Installation
+
+```python
+import simplecadapi as scad
+
+box = scad.make_box_rsolid(10.0, 20.0, 30.0)
+scad.export_stl(box, "example_box.stl")
+scad.export_step(box, "example_box.step")
+```
+
+## How to Package SDK Skills
+
+This project provides the `skill-pack` CLI for generating lightweight SDK reference skills: **No built-in SDK source code**, focused on API and architecture descriptions.
+
+### 1) Packaging Command
+
+Execute in the repository root directory:
+
+```bash
+uv run skill-pack --refresh-docs --archive --skill-name simplecadapi
+```
+
+Common parameters:
+
+- `--output-root <dir>`: Output directory (default `./skills`)
+- `--package-name <pkg>`: Runtime installation package name (default reads from `project.name`)
+- `--package-version <ver>`: Runtime installation version (default reads from `project.version`)
+- `--no-clean`: Do not clean existing output directory
+- `--archive`: Additionally generate `<skill-name>.tar.gz`
+
+### 2) Packaging Result Structure
+
+After packaging, you will get a directory similar to:
+
+- `skills/simplecadapi/SKILL.md`
+- `skills/simplecadapi/references/`
+- `skills/simplecadapi/references/docs/api/`
+- `skills/simplecadapi/references/docs/core/`
+
+### 3) Read the SDK skill
+
+```bash
+cd skills/simplecadapi
+```
+
+Key entry points:
+
+- `skills/simplecadapi/SKILL.md`
+- `skills/simplecadapi/references/SDK_OVERVIEW.md`
+- `skills/simplecadapi/references/SDK_SURFACES.md`
+- `skills/simplecadapi/references/V2_MODELING_WORKFLOWS.md`
+- `skills/simplecadapi/references/SDK_PACKAGE_SUMMARY.md`
+- `skills/simplecadapi/references/docs/api/README.md`
+- `skills/simplecadapi/references/docs/core/README.md`
+
+### 4) Preferred v2 replay workflow
+
+```python
+from simplecadapi import GraphSession, export_model_json, replay_model_json
+
+with GraphSession() as session:
+    ...
+
+model_json = export_model_json(session)
+rebuilt = replay_model_json(model_json)
+print(len(rebuilt))
+```
+
+## Serialization and Replay Docs
+
+For detailed operation-by-operation JSON formats and replay behavior, see:
+
+- [`docs/core/serialization/README.md`](docs/core/serialization/README.md)
+- [`docs/core/operation_graph_json_spec.md`](docs/core/operation_graph_json_spec.md)
+- [`examples/07_serialization_operation_tree.py`](examples/07_serialization_operation_tree.py)
+
+## Auto Tools
+
+The project includes 4 main CLIs:
+
+- `auto-docs-gen`: Generate `docs/api/` documentation from the public API source surface
+- `make-export`: Update imports/exports in `src/simplecadapi/__init__.py`
+- `evolve`: Extract functions from scripts for repository-managed evolve modules
+- `skill-pack`: Package thin SDK skill (documentation only)
+
+Examples:
+
+```bash
+uv run make-export --dry-run
+uv run auto-docs-gen
+uv run evolve path/to/your_case.py
+uv run skill-pack --refresh-docs --archive
+```
+
+## RAGFlow Documentation Sync
+
+`scripts/sync_ragflow_docs.py` is used to incrementally sync Markdown files under `docs/` to the specified RAGFlow dataset, chunked by H2 headings; the document's `chunk_method` is set to `manual`.
+
+Prepare the environment:
+
+```bash
+.venv/bin/python -m pip install ragflow-sdk
+```
+
+It is recommended to use `.env` (already added to `.gitignore`):
+
+```bash
+RAGFLOW_API_KEY=your_key_here
+RAGFLOW_BASE_URL=http://localhost
+RAGFLOW_DATASET_NAME=SimpleCADAPI
+```
+
+Run the sync:
+
+```bash
+set -a && source .env && set +a
+.venv/bin/python scripts/sync_ragflow_docs.py --create-dataset
+```
+
+Common parameters:
+
+- `--dataset-id` / `RAGFLOW_DATASET_ID`: Directly specify the dataset ID (avoid name conflicts)
+- `--delete-removed`: Delete documents that have been removed locally
+- `--dry-run`: Only preview changes without executing writes
+- `--progress-interval N`: Print progress every N documents
+
+## Development and Testing
+
+Local development installation (editable):
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+Run unit tests:
+
+```bash
+uv run python -m unittest test/test_all_features.py
+```
+
+Run examples:
+
+```bash
+uv run python examples/01_basic_modeling.py
+uv run python examples/02_graph_replay.py
+uv run python examples/03_expressions.py
+uv run python examples/05_loft_sweep_revolve.py
+uv run python examples/06_parametric_gear_model.py
+uv run python examples/07_serialization_operation_tree.py
+```
+
+## Core Design Constraints (Brief)
+
+- API functions uniformly use `snake_case` and reflect return types in function names (e.g., `*_rsolid`, `*_rwire`).
+- Core types are OCP-native wrappers and are kept as stable as possible; functionality is extended by adding new functions (Open-Closed Principle).
+- Support `SimpleWorkplane` context for local coordinate modeling.
+- Export interfaces support single entities, multiple entities, and nested list inputs.
+
+## Documentation Entry Points
+
+- API documentation: `docs/api/`
+- Core documentation: `docs/core/`
+
+## License
+
+MIT, see `LICENSE`.

simplecadapi-2.0.0b2/docs/api/Const.md

@@ -0,0 +1,17 @@
+# Const
+
+## Class Definition
+
+```python
+class Const
+```
+
+*Source: expr.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import Const`
+
+## Description
+
+Immutable constant node used in the v2 expression graph.

simplecadapi-2.0.0b2/docs/api/Expr.md

@@ -0,0 +1,17 @@
+# Expr
+
+## Class Definition
+
+```python
+class Expr
+```
+
+*Source: expr.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import Expr`
+
+## Description
+
+Derived scalar expression node built from one or more operands.

simplecadapi-2.0.0b2/docs/api/ExpressionGraph.md

@@ -0,0 +1,17 @@
+# ExpressionGraph
+
+## Class Definition
+
+```python
+class ExpressionGraph()
+```
+
+*Source: expr.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ExpressionGraph`
+
+## Description
+
+A lightweight registry of expression DAG nodes.

simplecadapi-2.0.0b2/docs/api/GraphSession.md

@@ -0,0 +1,31 @@
+# GraphSession
+
+## Class Definition
+
+```python
+class GraphSession(graph_id: Optional[str] = None)
+```
+
+*Source: graph.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import GraphSession`
+
+## Description
+
+Context manager that records CAD operations into a DAG.
+
+with GraphSession() as session:
+n1 = record_operation(
+"make_line_redge", {"start": (0, 0, 0), "end": (1, 0, 0)}
+)
+n2 = record_operation(
+"make_line_redge", {"start": (1, 0, 0), "end": (1, 1, 0)}
+)
+record_operation(
+"make_wire_from_edges_rwire", {"edge_count": 2}, inputs=[n1, n2]
+)
+
+# Access the graph after the session
+print(session.graph.topological_order())