simplecadapi 2.0.0b2

A simplified OCP-native CAD modeling 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

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

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

Build a local wheel/sdist first if you want to install from local artifacts:

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

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

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

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/operation_graph_json_spec.md
• 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:

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/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.