API reference
CadFlow exposes two complementary public styles. The session-oriented API uses Model and Shape for direct native geometry work. The declarative API records richer operations, semantics, products, and exchange artifacts for inspection and replay. Both are supported; choose the smallest surface that preserves the state your workflow needs.
Choose an entry point
| Need | Start with | Result |
|---|---|---|
| Build and inspect native geometry interactively | Model | Session-owned Shape values |
| Execute a known native batch | Graph | Ordered string results across the stable C ABI |
| Record and replay a structured design workflow | @model | ModelResult, Model JSON, and session JSON |
| Construct constrained 2D profiles | Sketch API | Immutable sketch state, solve diagnostics, and native profiles |
| Organize reusable products | Assembly API | Parts, occurrences, connectors, constraints, and reports |
| Inspect STEP/BREP evidence | Inspection API | Structured topology, measurements, comparisons, sections, and views |
| Compile portable render artifacts | Scene API | Validated Scene packages and GLB resources |
| Describe static thin geometry | Flexible API | Deterministic sampled panel meshes and exports |
| Describe reduced connection behavior | Physical API | Validated connection layers and response batches |
| Package distributed face contact | Simulation API | Solver-independent contact evidence and handoff packages |
Reference layers
This reference is intentionally split into three layers:
- Concept and contract pages explain ownership, units, mutation, error behavior, and recommended workflows.
- Domain catalogs list every public symbol in one subsystem.
- Generated symbol pages preserve the runtime signature, parameters, return annotation, aliases, fields, and public members for each symbol.
Use all API symbols when you know a name, or open a domain catalog when you know the subsystem.
Core runtime
| Page | Covers |
|---|---|
| Model | Session lifecycle, construction groups, preflight, and dynamic operations |
| Shape | Ownership, measurements, validation, meshing, and export |
| Sessions and frames | NativeSession, opaque handles, CoordinateFrame, and Workplane |
| Feedback and preview | Diagnostics, reports, preview buffers, and GLB conversion |
Modeling and execution
| Page | Covers |
|---|---|
| Creation and import | Primitives, profiles, curves, surfaces, and external geometry |
| Features and transforms | Extrude, revolve, sweep, booleans, local features, and copies |
| Topology, query, and exchange | Subshapes, selection, measurements, validation, STEP/STL/BREP |
| Native Graph | Node references, supported batches, execution, and result decoding |
| Recording and replay | @model, GraphSession, Model JSON, strict replay, and artifacts |
| Expressions, units, and tolerances | Symbolic values, dimensions, conversions, and tolerance analysis |
Contract conventions
Read API conventions before integrating CadFlow into a long-lived application. Read errors and diagnostics before building automated recovery or agent feedback.
Important defaults:
- Public imports come from
cadflowor the documented public submodules. Do not importcadflow._engine. - Coordinates and angles are ordinary Python numbers; a function accepting a unit-bearing value says so explicitly.
Shapevalues cannot crossModelsessions.- Product, sketch, physical, and simulation data are generally immutable or functionally updated; assign returned replacements.
- Paths may write artifacts. A successful call does not replace downstream file, schema, or geometry validation.
Completeness and version
The generated reference currently covers 518 unique public symbols, including 414 of 414 top-level exports and explicit exports from 28 public module surfaces. It is generated from CadFlow 0.1.0 and can be checked against the runtime with:
PYTHONPATH=../CadFlow/python python scripts/generate_api_reference.py --check
CadFlow is Alpha. Pin the package version, retain artifact metadata, and review compatibility and migration before upgrading.