API Reference

Generated from the cadling package source. Each symbol links to its definition on GitHub.

class CADItem(BaseModel)

Source: cadling/cadling/datamodel/base_models.py:200

Base class for all CAD items.

This is the foundational class for all geometric elements, similar to docling’s DocItem but adapted for CAD data.

CADItem hierarchy: CADItem (base) ├── STEPEntityItem (STEP geometric entities) ├── MeshItem (mesh data from STL, OBJ) ├── AssemblyItem (multi-part assemblies) └── AnnotationItem (dimensions, tolerances)

Attributes: item_type: Type identifier (e.g., “step_entity”, “mesh”). label: Human-readable label. text: Text representation of this item. bbox: 3D bounding box (optional). properties: Custom properties (volume, mass, etc.). parent: Parent item ID (for hierarchies). children: Child item IDs. prov: Provenance chain.

Methods

add_provenance

add_provenance(component_type: str, component_name: str)

Source: cadling/cadling/datamodel/base_models.py:240

Add provenance information.

Args: component_type: Type of component. component_name: Name of component.

class CADlingDocument(BaseModel)

Source: cadling/cadling/datamodel/base_models.py:363

Central data structure for CAD documents.

This is the equivalent of docling’s DoclingDocument but adapted for CAD files. It contains hierarchical items (entities, meshes, assemblies), CAD-specific metadata (topology, embeddings), semantic segments, and methods for export.

Attributes: name: Document name. format: CAD file format. origin: Source file metadata. hash: Document hash. items: Hierarchical list of CAD items. segments: List of semantic segments from segmentation models. segment_index: Fast lookup index for segments by ID. topology: Topology graph (entity references). embeddings: Neural embeddings from ll_stepnet (optional). bounding_box: Overall bounding box for the document. metadata: Format-specific metadata populated by backends. processing_history: History of processing steps.

Methods

add_item

add_item(item: CADItem)

Source: cadling/cadling/datamodel/base_models.py:429

Add a CAD item to the document.

Args: item: CADItem to add.

add_segment

add_segment(segment: Segment)

Source: cadling/cadling/datamodel/base_models.py:438

Add a semantic segment to the document.

Segments are identified by segmentation models and represent meaningful geometric regions (features, components, etc.).

Args: segment: Segment to add.

Example: segment = Segment( segment_id=“seg_hole_0”, segment_type=“feature”, properties={“manufacturing_feature”: “hole”} ) doc.add_segment(segment)

add_processing_step

add_processing_step(step_name: str, component: str, duration_ms: Optional[float] = None, status: ConversionStatus = ConversionStatus.SUCCESS)

Source: cadling/cadling/datamodel/base_models.py:462

Add a processing step to history.

Args: step_name: Name of the processing step. component: Component that executed this step. duration_ms: Duration in milliseconds. status: Status of this step.

export_to_json

export_to_json() -> Dict[str, Any]

Source: cadling/cadling/datamodel/base_models.py:486

Export document to JSON format.

Returns: Dictionary representation suitable for JSON serialization.

Example: json_data = doc.export_to_json() with open(“output.json”, “w”) as f: json.dump(json_data, f, indent=2)

export_to_markdown

export_to_markdown() -> str

Source: cadling/cadling/datamodel/base_models.py:540

Export document to Markdown format.

Returns: Markdown string representation.

Example: markdown = doc.export_to_markdown() with open(“output.md”, “w”) as f: f.write(markdown)

class ConversionResult(BaseModel)

Source: cadling/cadling/datamodel/base_models.py:641

Result of a CAD file conversion.

Similar to docling’s ConversionResult but adapted for CAD conversion.

Attributes: input: Input document descriptor. document: Converted CADlingDocument (if successful). status: Conversion status. errors: List of errors encountered.

Methods

add_error

add_error(component: str, error_message: str, item_id: Optional[str] = None)

Source: cadling/cadling/datamodel/base_models.py:660

Add an error to the result.

Args: component: Component where error occurred. error_message: Error message. item_id: ID of item that caused error.

class ConversionStatus(str, Enum)

Source: cadling/cadling/datamodel/base_models.py:60

Status of a conversion operation.

class DocumentConverter

Source: cadling/cadling/backend/document_converter.py:82

Main converter for CAD files.

This is the primary entry point for cadling, providing a unified interface for converting various CAD formats to CADlingDocument.

Similar to docling’s DocumentConverter but adapted for CAD files.

Attributes: allowed_formats: List of formats this converter will process. format_options: Format-specific configuration.

Example: # Basic usage converter = DocumentConverter() result = converter.convert(“part.step”)

# With format options
from cadling.backend.step.step_backend import STEPBackend
from cadling.pipeline.simple_pipeline import SimpleCADPipeline

converter = DocumentConverter(
    allowed_formats=[InputFormat.STEP],
    format_options={
        InputFormat.STEP: FormatOption(
            backend=STEPBackend,
            pipeline_cls=SimpleCADPipeline,
            backend_options=STEPBackendOptions(
                enable_ll_stepnet=True
            )
        )
    }
)

Methods

__init__

__init__(allowed_formats: Optional[List[InputFormat]] = None, format_options: Optional[Dict[InputFormat, FormatOption]] = None)

Source: cadling/cadling/backend/document_converter.py:117

Initialize document converter.

Args: allowed_formats: Formats to process (None = all formats). format_options: Format-specific configuration.

convert

convert(source: Union[Path, str, BytesIO], format: Optional[InputFormat] = None, pipeline_options: Optional[PipelineOptions] = None, allowed_root: Optional[Union[Path, str]] = None) -> ConversionResult

Source: cadling/cadling/backend/document_converter.py:141

Convert a CAD file to CADlingDocument.

Args: source: Path to file or byte stream. format: Format (auto-detected if not provided). pipeline_options: Pipeline options to override format-level defaults. allowed_root: If provided, restrict file access to this directory. Paths outside the root raise ValueError.

Returns: ConversionResult with status and document (or errors).

Raises: ValueError: If the resolved path falls outside allowed_root or the file does not exist.

Example: # From file path result = converter.convert(“part.step”)

# From Path object
result = converter.convert(Path("part.stl"))

# With explicit format
result = converter.convert("data.bin", format=InputFormat.STEP)

# Restrict to a directory
result = converter.convert("part.step", allowed_root="/data/cad")

class FormatOption(BaseModel)

Source: cadling/cadling/backend/document_converter.py:49

Configuration for a specific CAD format.

This defines the backend and pipeline to use for a format, similar to docling’s FormatOption.

Attributes: backend: Backend class for this format. pipeline_cls: Pipeline class to use. backend_options: Backend-specific options. pipeline_options: Pipeline-specific options.

Methods

set_optional_field_default

set_optional_field_default() -> Self

Source: cadling/cadling/backend/document_converter.py:69

Set default pipeline options if not provided.

class InputFormat(str, Enum)

Source: cadling/cadling/datamodel/base_models.py:43

Supported CAD file formats.

This enum defines all CAD formats that cadling can process, similar to docling’s InputFormat but for CAD files instead of documents.