cadSet/CADDesigner-Code/workspace/skills/simplecad-self-evolve/references/PROJECT_README.md

SimpleCADAPI

SimpleCADAPI is an imperative CAD modeling Python package based on CADQuery. Its goal is to encapsulate common modeling operations into a clear, composable, testable functional API, and to support distributing "documentation + scripts + runtime installation" workflows via Skills.

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, version: 2.0.8 (see pyproject.toml).

Method A: Install from package repository with pip

pip install simplecadapi

Optional development dependencies:

pip install "simplecadapi[dev]"

Method B: Install with uv

Install in the current virtual environment:

uv pip install simplecadapi

Add as a project dependency in pyproject.toml:

uv add simplecadapi

Method C: Install from local build artifacts

The repository already contains example build artifacts (dist/):

pip install dist/simplecadapi-2.0.8-py3-none-any.whl

If you need to rebuild:

uv build

Quick Verification of Installation

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 and Use Skills

This project provides the skill-pack CLI for generating lightweight skill packages (thin mode): No built-in SDK source code, runtime installs simplecadapi from the package repository.

1) Packaging Command

Execute in the repository root directory:

uv run skill-pack --refresh-docs --archive --skill-name simplecad-self-evolve

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/simplecad-self-evolve/SKILL.md
• skills/simplecad-self-evolve/scripts/
• skills/simplecad-self-evolve/references/
• skills/simplecad-self-evolve/cases/simplecad_self_evolve_cases/

3) Install and Verify Runtime in the Skill Directory

cd skills/simplecad-self-evolve
PYTHON_BIN=.venv/bin/python scripts/install.sh
PYTHON_BIN=.venv/bin/python scripts/with_skill.sh --check

4) Run Your Program with the Wrapper Script

PYTHON_BIN=.venv/bin/python scripts/with_skill.sh -- .venv/bin/python your_script.py

5) Activate skill-local Case Module Path

eval "$(scripts/with_skill.sh --print-env)"

After activation, you can directly import:

from simplecad_self_evolve_cases.evolve import make_involute_spur_gear_rsolid

6) Add New Functions to the Skill-local evolve Module

scripts/add_new_case.sh path/to/new_case.py

7) Jupyter and Structure Validation

scripts/jupyter_with_skill.sh lab
scripts/validate_skill.sh

Auto Tools

The project includes 4 main CLIs:

• auto-docs-gen: Generate docs/api/ documentation from API source code
• make-export: Update imports/exports in src/simplecadapi/__init__.py
• evolve: Extract functions from scripts and append to the evolve module
• skill-pack: Package thin skill (documentation + scripts + cases)

Examples:

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:

.venv/bin/python -m pip install ragflow-sdk

It is recommended to use .env (already added to .gitignore):

RAGFLOW_API_KEY=your_key_here
RAGFLOW_BASE_URL=http://localhost
RAGFLOW_DATASET_NAME=SimpleCADAPI

Run the sync:

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):

uv pip install -e ".[dev]"

Run unit tests:

uv run python -m unittest test/test_all_features.py

Run examples:

uv run python examples.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 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.