Skip to main content

Contributing

CadFlow combines a public Python frontend, a C++17 runtime, generated cross-language contracts, and a large compatibility suite. Contributions should preserve the narrow public boundary and include evidence proportional to the behavior changed.

Repository map​

CadFlow/
├── python/cadflow/          Public frontend and domain facades
├── python/cadflow/_engine/  Bundled complete Python feature layer
├── native/                  C++ session, kernel, I/O, runtime, and physics
├── scene-contract/          Cross-language Scene schemas and validators
├── skills/                  Agent-oriented workflows and API references
├── examples/                Parts, assemblies, flexible models, and reconstructions
├── docs/                    Architecture, guides, and generated API docs
├── agent_dsl/               Optional experimental command wrapper
└── tests/                   Native, packaging, compatibility, and workflow tests

Development setup​

Follow Installation, then install test dependencies:

python -m pip install -e ".[test]" --no-build-isolation

For native backend work:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j2

Use a parallelism level appropriate for the available memory; OCCT-heavy builds can be resource intensive.

Run tests​

python -m pytest -q

During development, run the narrowest relevant file first, then the full suite before submitting:

python -m pytest -q tests/test_native_backend.py
python -m pytest -q tests/compat_suite/test_compat_public_api_surface.py
python -m pytest -q

Package changes should also build a wheel:

python -m pip wheel . --no-deps -w dist

Respect ownership boundaries​

  • Public integrations use import cadflow as cad and public domain modules.
  • Python frontend code must not expose OCC objects or private C++ handles.
  • c_api.cpp remains the stable ABI entry point.
  • Geometry-intensive algorithms belong in the native kernel.
  • Constraints, policy, schemas, diagnostics, and metadata may remain in Python.
  • Compatibility behavior should have characterization tests before migration.

Add or change a public operation​

Cover the complete vertical slice where applicable:

  1. C++ kernel implementation and validation.
  2. Stable C ABI entry point.
  3. Python native binding.
  4. Model facade and, when suitable, Graph support.
  5. Ownership and invalid-input tests.
  6. OCCT equivalence or round-trip evidence.
  7. User guide and generated API updates.

Pull request checklist​

  • The change solves one clearly stated problem.
  • Public behavior and limitations are documented.
  • New code uses the established ownership boundary.
  • Tests cover success, invalid input, and relevant compatibility behavior.
  • Generated files are updated only when their sources changed.
  • CAD examples validate geometry and verify non-empty outputs.
  • No application code depends on cadflow._engine or direct OCP objects.
  • License and OpenCascade notice requirements remain intact.

Use the GitHub issue tracker to discuss defects and proposed behavior before a large implementation.