User Guide

Complete guide for using the Mecasty Hybrid AI CAD system effectively.

---

Table of Contents

1. Introduction
2. How the Hybrid AI System Works
3. Best Practices for Prompts
4. Examples: Good vs Bad Prompts
5. Troubleshooting Guide
6. Feature Flag Usage

---

Introduction

Mecasty converts your natural language descriptions into precise CAD models using a hybrid AI system that combines:

1. Fast Pattern Matching - Instant extraction for common shapes
2. Intelligent LLM - Deep understanding for complex designs
3. Smart Validation - Built-in checks for accuracy
4. User Feedback - Clarification when needed

This guide will help you get the best results from the system.

---

How the Hybrid AI System Works

The Four Tiers

The system uses a cascading approach to extract your design intent:

Your Prompt
    │
    ▼
┌─────────────────────────────────┐
│ Tier 1: Pattern Matcher         │  ← <5ms, handles 80% of prompts
│ (Fast regex-based matching)     │
└─────────────────────────────────┘
    │
    ├── High confidence? → ✅ Return result immediately
    │
    ▼ Low confidence
┌─────────────────────────────────┐
│ Tier 2: Structured LLM          │  ← ~500ms, for complex features
│ (Gemini with JSON schema)       │
└─────────────────────────────────┘
    │
    ├── High confidence? → ✅ Return result
    │
    ▼ Low confidence
┌─────────────────────────────────┐
│ Tier 3: Disambiguation          │  ← Ask you for clarification
│ (Generate helpful questions)    │
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ Tier 4: Legacy Fallback         │  ← Last resort, basic extraction
│ (Simple regex patterns)         │
└─────────────────────────────────┘

Why This Matters

---

Best Practices for Prompts

1. Be Specific with Dimensions

Why: The AI needs exact measurements to create precise geometry.

Good:

"Create a box 100mm wide, 200mm long, and 50mm tall"

Okay:

"Create a box 100x200x50mm"

Avoid:

"Create a big box"           ❌ No dimensions
"Create a box about 100mm"   ❌ Approximate

---

2. Specify Units

Why: While millimeters are the default, explicit units prevent ambiguity.

Good:

"A hole 10mm in diameter"
"A bracket 5 inches wide"

Okay:

"A 10mm hole"  ← Assumes mm (default)

Avoid:

"A hole 10"    ❌ Ambiguous: 10mm or 10 inches?
"A box 10x10" ❌ No units

Supported Units:

---

3. Reference Features Clearly

Why: Ambiguous references lead to incorrect placement.

Good:

"Add a hole on the top face of the base plate"
"Place fillets on all vertical edges"
"Center the hole on the front face"

Okay:

"Add a hole on top"

Avoid:

"Put it there"               ❌ No reference
"Add holes on the thing"     ❌ Vague
"Make it round in the area"  ❌ Unclear scope

---

4. Use Standard Terminology

Why: CAD has specific terms that the AI recognizes.

---

5. Describe One Feature at a Time (Complex Parts)

Why: Breaking complex parts into logical steps improves accuracy.

For Complex Parts:

Step 1: "Create a base plate 200x150x20mm"
Step 2: "Add four M8 mounting holes at the corners, 15mm from edges"
Step 3: "Create a central bore 50mm diameter through the plate"
Step 4: "Add 2mm fillets to all internal edges"

For Simple Parts:

"Create a mounting plate 150x100x10mm with four M6 holes at the corners, 10mm from each edge"

---

6. Include Tolerance When Critical

Why: Manufacturing needs precise tolerances.

Good:

"A shaft 25mm diameter with 0.05mm tolerance"
"Holes 10mm ±0.1mm"

Avoid:

"A shaft around 25mm"  ← No tolerance specified

---

7. Specify Thread Standards

Why: Thread pitch and diameter must match.

Good:

"An M8 threaded hole, 15mm deep"
"A 1/4-20 UNC threaded hole"
"M6 fine pitch thread"

Avoid:

"An 8mm thread"  ❌ Ambiguous: diameter or thread size?
"A 1/4 thread"   ❌ UNC or UNF?

Supported Standards:

• ISO Metric: M1.6 to M100 (coarse and fine)
• UNC: 1/4-20 to 1-8
• UNF: 1/4-28 to 1-12

---

Examples: Good vs Bad Prompts

Simple Geometric Shapes

Box / Rectangular Prism

Excellent:

"Create a box 100mm wide, 200mm long, and 50mm tall with rounded corners (2mm fillet)"

Good:

"Box 100x200x50mm"

Poor:

"A box"                    ❌ No dimensions
"Make a big box"            ❌ Subjective size
"Box about 100"             ❌ Incomplete units

---

Cylinder

Excellent:

"Create a cylinder 50mm diameter, 100mm height, with 2mm fillets on the top and bottom edges"

Good:

"Cylinder 50mm diameter, 100mm tall"

Poor:

"Round column"              ❌ No dimensions
"Tube 50mm"                 ❌ Height? Wall thickness?
"Circle thing 50"           ❌ Unprofessional

---

Holes

Simple Hole

Excellent:

"Add a 10mm diameter hole through the top face, centered"

Good:

"10mm hole on top"

Poor:

"Drill a hole"              ❌ No size or location
"Make it hollow"            ❌ Not a hole specification

Threaded Hole

Excellent:

"Add four M8 threaded holes, 20mm deep, arranged in a 100mm square pattern, 10mm from each edge"

Good:

"M8 threaded holes at corners"

Poor:

"Screw holes"               ❌ No size, count, or location
"8mm threads"               ❌ Thread or hole diameter?

Counterbore

Excellent:

"Add a counterbore for M6 socket head cap screw: 6.5mm through-hole, 11mm counterbore diameter, 6mm deep"

Good:

"M6 counterbore"

Poor:

"Flat bottom hole"          ❌ No specification
"Hole for bolt"             ❌ Which bolt?

---

Mounting Plates

Excellent:

"Create a mounting plate 150mm wide, 200mm long, 10mm thick. Add four M8 threaded holes at the corners, centered 15mm from each edge. Include 2mm fillets on all edges."

Good:

"Mounting plate 150x200x10mm, four M8 corner holes"

Poor:

"Mounting plate with holes" ❌ No dimensions or specifications
"Make me a bracket"         ❌ Too vague

---

Complex Assemblies

Excellent (Broken into logical parts):

Part 1: "Create a base plate 200mm square, 20mm thick"

Part 2: "Add four M12 mounting holes, one in each corner, 25mm from edges"

Part 3: "Create a center boss 80mm diameter, 30mm tall on the top surface"

Part 4: "Drill a 30mm bore through the boss and base plate, centered"

Part 5: "Add four M6 threaded holes around the boss in a 60mm bolt circle"

Part 6: "Shell the base plate to 3mm wall thickness, leaving the boss solid"

Part 7: "Apply 2mm fillets to all internal edges"

Good:

"Gearbox housing: 200x150x20mm base, four M8 mounting holes at corners,
 center bore 50mm diameter 30mm deep, two bearing seats 30mm diameter 10mm deep,
 shell to 3mm wall thickness, 2mm fillets on internal edges"

Poor:

"Make a gearbox thing"      ❌ No specifications
"Housing with holes"        ❌ Incomplete

---

Patterns and Arrays

Linear Pattern

Excellent:

"Create a linear pattern of 5 holes, spaced 25mm apart, along the length of the plate"

Good:

"Five holes in a row, 25mm spacing"

Poor:

"Several holes in a line"   ❌ How many? How spaced?

Circular Pattern

Excellent:

"Create a circular pattern of 6 holes, equally spaced, on a 100mm diameter bolt circle, centered on the part"

Good:

"Six holes in a circle, 100mm diameter"

Poor:

"Holes around the center"   ❌ How many? What diameter?

---

Gears

Excellent:

"Create a spur gear with 20 teeth, 50mm pitch diameter, 20-degree pressure angle, 10mm thick"

Good:

"Gear 20 teeth, 50mm diameter"

Poor:

"Make a gear"               ❌ No specifications
"Toothed wheel"             ❌ Non-standard term

---

Troubleshooting Guide

Common Issues and Solutions

"Low Confidence" Warning

Symptoms: System asks clarifying questions

Causes:

• Missing dimensions
• Ambiguous position descriptions
• Unusual feature combinations
• Unclear units

Solutions:

1. Add specific dimensions: 100mm instead of large
2. Specify positions: centered or 10mm from edge
3. Break complex parts into steps
4. Explicitly state units

---

"Invalid Geometry" Error

Symptoms: System cannot create the requested geometry

Causes:

• Impossible dimensions (negative values, zero)
• Conflicting constraints
• Self-intersecting features
• Features larger than parent body

Solutions:

1. Check all dimensions are positive and reasonable
2. Ensure features fit within the parent body
3. Verify hole diameters are smaller than the part
4. Check thread depths don't exceed material thickness

---

"Feature Not Recognized" Error

Symptoms: Unknown feature type

Causes:

• Non-standard terminology
• Very complex or custom features
• Typos in feature names

Solutions:

1. Use standard CAD terms (see terminology table above)
2. Break complex features into standard operations
3. Check for typos

---

Slow Response Times

Symptoms: Taking longer than expected

Causes:

• Complex prompts requiring LLM processing
• High system load
• Network latency to LLM API

Solutions:

1. Use simpler, more direct prompts
2. Break complex parts into multiple simple prompts
3. Avoid overly verbose descriptions
4. Check system status at /monitoring

---

"Rate Limited" Error

Symptoms: Too many requests error

Causes:

• Exceeded rate limit (100 req/min, 1000 req/hour)
• Burst of rapid requests

Solutions:

1. Wait 60 seconds before retrying
2. Batch operations when possible
3. Check rate limit headers in API responses
4. Consider implementing client-side rate limiting

---

Confidence Score Guide

---

When to Use Disambiguation

The system will ask questions when:

1. Dimensions are unclear

   • "What are the specific dimensions?"
   • "What units should be used?"

2. Position is ambiguous

   • "Where should the holes be positioned?"
   • "Which face should the feature be on?"

3. Thread specs are missing

   • "What is the thread specification?"
   • "How deep should the threads be?"

4. Material not specified

   • "What material should the part be made from?"

Best Practice: Answer disambiguation questions as specifically as possible.

---

Feature Flag Usage

Feature flags allow you to control system behavior.

Available Flags

---

When to Adjust Flags

Disable Regex (Pattern Matching)

Scenario: Always want LLM analysis, even for simple shapes

FEATURE_REGEX=false

Effect: All prompts go directly to LLM (slower, more expensive)

---

Disable Structured Extraction

Scenario: Emergency fallback to legacy system only

FEATURE_STRUCTURED=false

Effect: Bypass LLM entirely, use only pattern matching

---

Disable Disambiguation

Scenario: Automated system where user interaction isn't possible

FEATURE_DISAMBIGUATION=false

Effect: Returns best-effort result without asking questions

---

Disable Circuit Breaker

Scenario: Testing or development environment

FEATURE_CIRCUIT_BREAKER=false

Effect: No automatic failure protection (not recommended for production)

---

Setting Flags

Environment Variables

# .env.local
FEATURE_REGEX=true
FEATURE_STRUCTURED=true
FEATURE_DISAMBIGUATION=true
FEATURE_LEGACY=true
FEATURE_CIRCUIT_BREAKER=true
FEATURE_RETRY=true
MAX_EXTRACTION_TIME=45000

Runtime Configuration

import { extractWithHybrid } from "@/lib/gemini/hybridExtractor"

const result = await extractWithHybrid({
  userPrompt: "Create a box 100mm",
  generateFn: generateContent,
  config: {
    confidenceThreshold: 0.7,
    enablePatternMatch: true,
    enableStructured: true,
    enableDisambiguation: true,
    enableLegacyFallback: true
  }
})

---

Recommended Configurations

Maximum Speed

For fastest response (simpler results):

FEATURE_REGEX=true
FEATURE_STRUCTURED=false
FEATURE_DISAMBIGUATION=false

Maximum Accuracy

For highest precision (slower, more expensive):

FEATURE_REGEX=true
FEATURE_STRUCTURED=true
FEATURE_DISAMBIGUATION=true
CONFIDENCE_THRESHOLD=0.8

Maximum Reliability

For production stability:

FEATURE_REGEX=true
FEATURE_STRUCTURED=true
FEATURE_DISAMBIGUATION=true
FEATURE_LEGACY=true
FEATURE_CIRCUIT_BREAKER=true
FEATURE_RETRY=true

---

Quick Reference Card

Essential Keywords

Dimension Format

[Number][Unit] or [Number] [Unit]

Examples:
- 100mm
- 10 cm
- 4 inches
- 0.5"
- 1 ft

Thread Format

Metric: M8, M8x1, M8 fine
Unified: 1/4-20, 3/8-16 UNC, 1/2-20 UNF

Confidence Thresholds

High: ≥ 0.9 (proceed automatically)
Medium: 0.7 - 0.89 (review recommended)
Low: < 0.7 (clarification needed)

---

Getting Help

Resources

1. API Reference: See API_REFERENCE.md for complete API documentation
2. Architecture Guide: See ARCHITECTURE.md for system details
3. Monitoring Dashboard: Visit /monitoring for real-time metrics

Support

For technical support:

• Check the troubleshooting section above
• Review system status at /api/monitoring/health
• Check recent errors at /api/monitoring/errors

---

Last Updated: 2026-03-10