HartOMat/plan.md

Plan: Rich Product Metadata Extraction from STEP Files

Context

The AI chat agent was asked "What is the biggest product from my order?" and couldn't answer because dimensional data wasn't available in tool results. While cad_files.mesh_attributes already stores bounding box dimensions, much more metadata is extractable from STEP files via OCC that would make the AI agent and the product library significantly more useful.

Currently extracted: part names, bounding box (xyz), sharp edges, smooth angle Available but not extracted: per-part volume, surface area, assembly hierarchy, instance counts, embedded colors, triangle counts, geometric complexity

Goal: Expand the STEP metadata extraction to compute richer product characteristics and store them in a structured cad_metadata JSONB field, accessible to the AI agent, product search, and frontend.

Affected Files

File	Change
backend/app/services/step_processor.py	Expand extract_step_metadata() with volume, surface area, hierarchy, complexity
backend/app/domains/products/models.py	Add cad_metadata JSONB column to Product
backend/alembic/versions/XXX_add_cad_metadata.py	Migration
backend/app/domains/pipeline/tasks/extract_metadata.py	Populate cad_metadata after STEP processing
backend/app/domains/products/schemas.py	Expose cad_metadata in ProductOut
backend/app/services/chat_service.py	Include metadata in search_products and system prompt
frontend/src/pages/ProductDetail.tsx	Display rich metadata (volume, part count, complexity)

Tasks (in order)

[ ] Task 1: Expand STEP metadata extraction

• File: backend/app/services/step_processor.py
• What: Expand extract_step_metadata() to compute additional properties after the existing bbox/edge extraction. Add a new function extract_rich_metadata(doc, shape_tool) that returns:

  {
      "part_count": 42,                    # Number of leaf parts
      "assembly_depth": 3,                 # Max nesting depth
      "total_volume_cm3": 1250.4,          # Sum of all part volumes (cm³)
      "total_surface_area_cm2": 3400.2,    # Sum of all surface areas (cm²)
      "total_triangle_count": 45000,       # After tessellation
      "total_vertex_count": 23000,         # After tessellation
      "largest_part": {                    # Part with largest volume
          "name": "OuterRing",
          "volume_cm3": 450.2,
      },
      "smallest_dimension_mm": 0.5,        # Smallest bbox dimension across all parts
      "instance_count": 36,                # Total instances (parts may repeat)
      "unique_part_count": 12,             # Distinct shapes
      "complexity_score": "high",          # low/medium/high based on triangle count
  }
  

  Use OCC:
  • GProp_GProps + BRepGProp.VolumeProperties() for volume
  • BRepGProp.SurfaceProperties() for surface area
  • Poly_Triangulation for triangle/vertex counts (after tessellation)
  • Assembly tree walk (already done in _collect_part_key_map) for hierarchy depth + instance count
• Acceptance gate: extract_rich_metadata() returns all fields for a test STEP file
• Dependencies: None

[ ] Task 2: Add cad_metadata column to Product model

• File: backend/app/domains/products/models.py
• What: Add cad_metadata: Mapped[dict | None] = mapped_column(JSONB, nullable=True, default=None) to the Product model. This stores the rich metadata at the product level (not cad_file) because products are the user-facing entity.
• Migration: alembic revision --autogenerate -m "add cad_metadata to products"
• Also: Add to ProductOut schema in backend/app/domains/products/schemas.py
• Acceptance gate: Column exists, schema includes it
• Dependencies: None

[ ] Task 3: Populate cad_metadata during STEP processing

• File: backend/app/domains/pipeline/tasks/extract_metadata.py
• What: After process_step_file extracts objects and queues thumbnail, call extract_rich_metadata() and store the result on the Product's cad_metadata field. Also store it on cad_files.mesh_attributes (merge with existing data).
• Also: Add a "reextract metadata" admin action that re-runs this for all existing products
• Acceptance gate: After STEP processing, product.cad_metadata is populated with volume, part_count, etc.
• Dependencies: Tasks 1, 2

[ ] Task 4: Expose metadata in AI agent tools

• File: backend/app/services/chat_service.py
• What:
  1. Update _tool_search_products() to include cad_metadata fields (part_count, total_volume_cm3, complexity_score) in results
  2. Update query_database tool description to mention products.cad_metadata JSONB field
  3. Update system prompt to mention available metadata
• Acceptance gate: AI agent can answer "What is the biggest product?" using volume data
• Dependencies: Task 3

[ ] Task 5: Display rich metadata on ProductDetail page

• File: frontend/src/pages/ProductDetail.tsx
• What: Add a "CAD Metadata" section on the product detail page showing:
  • Part count + unique parts + instances
  • Total volume (cm³) + surface area (cm²)
  • Largest part name + volume
  • Complexity score badge (low/medium/high)
  • Triangle/vertex count
  • Assembly depth
• Acceptance gate: Metadata displayed on product page; empty gracefully when not available
• Dependencies: Task 2

[ ] Task 6: Batch re-extract metadata for existing products

• File: backend/app/api/routers/admin.py
• What: Add a "Re-extract Rich Metadata" button in System Tools that queues a Celery task to re-process all completed STEP files and populate cad_metadata for all products.
• Acceptance gate: Button triggers batch job; existing products get metadata populated
• Dependencies: Tasks 1, 3

Migration Check

Yes — one new JSONB column on products table.

Order Recommendation

1. Task 1 (extraction logic) + Task 2 (model + migration) — parallel
2. Task 3 (wire up in pipeline)
3. Task 4 (AI agent) + Task 5 (frontend) — parallel
4. Task 6 (batch re-extract)

Risks / Open Questions

1. Volume calculation accuracy: OCC BRepGProp computes exact B-rep volume, not mesh-based. This is accurate but can be slow for very complex shapes. Cap at 5s per file.

2. Performance: Rich metadata extraction adds ~100-500ms per STEP file. This is acceptable since STEP processing already takes 1-5s.

3. Existing products: ~45 products with STEP files need backfill. Task 6 handles this.

4. Triangle count varies: Depends on tessellation settings (deflection angles). Store the count at the current tessellation quality for reference, with a note that it's approximate.