hoops_ai.ml.CADSearch

class hoops_ai.ml.CADSearch(shape_model=None, text_model=None)

Bases: object

Provides similarity search over CAD datasets using pre-computed embeddings.

Supports: - Indexing embeddings from EmbeddingBatch objects - Shape-based retrieval (query by CAD file) - Text-based retrieval (query by description) (FUTURE WORK) - Saving/loading of vector indices - Metadata filtering

Example

# Create embedding batch from arrays batch = EmbeddingBatch.from_arrays(embeddings, model=”my_model”, ids=part_ids)

# Index and search searcher = CADSearch(shape_model=model) searcher.index_shape(batch) results = searcher.search_by_shape(“query.step”)

Parameters:

  • shape_model (Optional[ShapeEmbeddingsModel])

  • text_model (Optional[TextEmbeddingsModel])

close()

Close the search instance and release resources.

Return type:

None

index_shape(embedding_batch, vector_store=None)

Index shape embeddings from an EmbeddingBatch into a vector store.

Parameters:

  • embedding_batch (EmbeddingBatch) – Pre-constructed EmbeddingBatch with embeddings and optional IDs

  • vector_store (VectorStore | None) – Custom vector store (if None, creates FAISS store)

Raises:

ValueError – If embedding batch is invalid

Return type:

None

index_text(embedding_batch, vector_store=None)

(FUTURE WORK) Index text embeddings from an EmbeddingBatch into a vector store.

Parameters:

  • embedding_batch (EmbeddingBatch) – Pre-constructed EmbeddingBatch with text embeddings and optional IDs

  • vector_store (VectorStore | None) – Custom vector store (if None, creates FAISS store)

Raises:

ValueError – If embedding batch is invalid

Return type:

None

load_shape_index(path, vector_store_cls=None)

Load a previously saved shape vector index from disk.

This allows you to skip re-computing shape embeddings and directly use a pre-built index for queries.

Parameters:

  • path (str) – File path to load index from (e.g., “parts_index.faiss”)

  • vector_store_cls (type | None) – Vector store class to use for loading. If None, defaults to FaissVectorStore.

Return type:

None

Example

# Load pre-built index searcher = CADSearch(shape_model=model) searcher.load_shape_index(“parts_index.faiss”)

# Query immediately without indexing results = searcher.search_by_shape(“query.step”, top_k=10)

load_text_index(path, vector_store_cls=None)

(FUTURE WORK) Load a previously saved text vector index from disk.

This allows you to skip re-computing text embeddings and directly use a pre-built index for queries.

Parameters:

  • path (str) – File path to load index from (e.g., “text_index.faiss”)

  • vector_store_cls (type | None) – Vector store class to use for loading. If None, defaults to FaissVectorStore.

Return type:

None

Example

# Load pre-built index searcher = CADSearch(text_model=model) searcher.load_text_index(“text_index.faiss”)

# Query immediately without indexing results = searcher.search_by_text(“steel bracket”, top_k=10)

save_shape_index(path)

Save the shape vector index to disk for later reuse.

This allows you to persist computed shape embeddings and avoid re-indexing when restarting scripts or machines.

Parameters:

path (str) – File path to save index (e.g., “parts_index.faiss”)

Raises:

ValueError – If shape index hasn’t been built yet

Return type:

None

Example

# Build and save index searcher.index_shape(embedding_batch) searcher.save_shape_index(“parts_index.faiss”)

# Later, load instead of re-indexing searcher.load_shape_index(“parts_index.faiss”)

save_text_index(path)

(FUTURE WORK) Save the text vector index to disk for later reuse.

This allows you to persist computed text embeddings and avoid re-indexing when restarting scripts or machines.

Parameters:

path (str) – File path to save index (e.g., “text_index.faiss”)

Raises:

ValueError – If text index hasn’t been built yet

Return type:

None

Example

# Build and save index searcher.index_text(embedding_batch) searcher.save_text_index(“text_index.faiss”)

# Later, load instead of re-indexing searcher.load_text_index(“text_index.faiss”)

search_by_embedding(query_embedding, search_space='shape', top_k=10, filters=None, include_metadata=True)

Search using a pre-computed embedding.

Parameters:

  • query_embedding (Embedding) – Pre-computed embedding

  • search_space (str) – Which index to search (“shape” or “text”)

  • top_k (int) – Number of results to return

  • filters (Dict[str, Any] | None) – Optional metadata filters

  • include_metadata (bool) – Whether to include metadata in results

Returns:

List of VectorHit objects sorted by similarity

Return type:

List[VectorHit]

search_by_shape(cad_path, top_k=10, filters=None, include_metadata=True)

Search for similar parts by providing a CAD file.

Parameters:

  • cad_path (str) – Path to query CAD file

  • top_k (int) – Number of results to return

  • filters (Dict[str, Any] | None) – Optional metadata filters

  • include_metadata (bool) – Whether to include metadata in results

Returns:

List of VectorHit objects sorted by similarity

Return type:

List[VectorHit]

search_by_text(query_text, top_k=10, filters=None, include_metadata=True)

(FUTURE WORK) Search for parts by text description.

Parameters:

  • query_text (str) – Text query

  • top_k (int) – Number of results to return

  • filters (Dict[str, Any] | None) – Optional metadata filters

  • include_metadata (bool) – Whether to include metadata in results

Returns:

List of VectorHit objects sorted by similarity

Return type:

List[VectorHit]