CAD-Documenter/docs/USAGE.md

# CAD-Documenter Usage Guide

## Quick Start

```bash
# Install
cd /path/to/CAD-Documenter
uv sync

# Set API key
export OPENAI_API_KEY="sk-your-key"

# Run
uv run cad-doc your_video.mp4
```

## Basic Commands

### Generate Documentation
```bash
cad-doc video.mp4
```

Creates `video_docs/` with:
- `documentation.md` - Main documentation
- `frames/` - Extracted keyframes

### With All Features
```bash
cad-doc video.mp4 --bom --atomizer-hints --pdf
```

Creates additional:
- `bom.csv` - Bill of Materials
- `atomizer_hints.json` - FEA setup hints
- `documentation.pdf` - PDF version

### Custom Output Directory
```bash
cad-doc video.mp4 --output ./my_docs/
```

## Recording Tips

For best results when recording your CAD walkthrough:

### Video
- Use 1080p or higher resolution
- 30 FPS is sufficient
- Record the CAD viewport directly (not your whole screen)
- Spin the model slowly and steadily
- Pause briefly when showing details

### Audio
- Use a decent microphone
- Speak clearly and at normal pace
- Name each component explicitly: "This is the main bracket..."
- Mention materials: "Made of 6061 aluminum"
- Describe functions: "This holds the motor in place"
- Note constraints: "Must fit within 200mm envelope"
- Call out features: "These fillets reduce stress concentration"

### Structure
1. Start with an overview (assembly name, purpose)
2. Go through major components
3. Show details and features
4. Discuss assembly relationships
5. Mention any constraints or requirements

## Configuration

### Create Config File
```bash
cad-doc --init-config
```

Creates `~/.cad-documenter.toml` with defaults.

### Config Options

```toml
[api]
provider = "openai"  # or "anthropic"
# api_key = "sk-..."  # Or use env var

[processing]
whisper_model = "base"  # tiny/base/small/medium/large
use_scene_detection = true
max_frames = 15

[output]
include_bom = true
include_atomizer_hints = true
```

### Environment Variables

```bash
export OPENAI_API_KEY="sk-..."      # For OpenAI
export ANTHROPIC_API_KEY="sk-..."   # For Anthropic
export CAD_DOC_PROVIDER="anthropic" # Override provider
export CAD_DOC_WHISPER_MODEL="medium" # Override Whisper model
```

## CLI Options

```
Usage: cad-doc [OPTIONS] VIDEO

Options:
  -o, --output PATH           Output directory
  --frames-only               Only extract frames, skip analysis
  --atomizer-hints            Generate Atomizer FEA hints
  --bom                       Generate Bill of Materials
  --pdf                       Generate PDF output
  --frame-interval FLOAT      Seconds between frames
  --whisper-model [tiny|base|small|medium|large]
                              Whisper model size
  --api-provider [openai|anthropic]
                              Vision API provider
  --config PATH               Config file path
  --init-config               Create default config file
  -v, --verbose               Verbose output
  --version                   Show version
  --help                      Show this message
```

## Python API

```python
from cad_documenter.pipeline import DocumentationPipeline

# Simple usage
pipeline = DocumentationPipeline(
    video_path="walkthrough.mp4",
    output_dir="./docs"
)

results = pipeline.run_full_pipeline(
    atomizer_hints=True,
    bom=True,
    pdf=True
)

print(f"Documentation: {results['documentation']}")
print(f"Components: {results['components']}")
```

### With Progress Callback

```python
def on_progress(progress):
    print(f"[{progress.stage.value}] {progress.message} ({progress.progress:.0%})")

pipeline = DocumentationPipeline(
    video_path="walkthrough.mp4",
    output_dir="./docs",
    progress_callback=on_progress
)

results = pipeline.run()
```

## Atomizer Integration

The `atomizer_hints.json` output is designed for use with Atomizer FEA optimization:

```json
{
  "assembly_name": "Motor Bracket Assembly",
  "optimization_hints": {
    "objectives": [
      {"name": "mass", "direction": "minimize"},
      {"name": "stiffness", "direction": "maximize"}
    ],
    "constraints": [
      {"type": "envelope", "value": "200mm"},
      {"type": "frequency", "value": ">100 Hz"}
    ],
    "parameters": ["thickness", "fillet_radius", "rib_count"]
  },
  "fea_hints": {
    "critical_regions": [
      {"feature": "fillet", "concern": "stress_concentration"}
    ],
    "study_suggestions": [
      "Modal analysis recommended - frequency/vibration mentioned"
    ]
  }
}
```

## Troubleshooting

### "No API key found"
Set your API key:
```bash
export OPENAI_API_KEY="sk-..."
```
Or add to config file.

### "No frames extracted"
- Check video file is valid
- Try different frame_interval
- Ensure ffmpeg is installed

### "No components detected"
- Ensure video clearly shows the model
- Speak component names clearly
- Try larger Whisper model: `--whisper-model medium`
- Check API key has sufficient credits

### "Transcription failed"
- Video may have no audio track
- Use `--frames-only` to skip transcription
- Check ffmpeg can extract audio: `ffmpeg -i video.mp4 -vn audio.wav`

### PDF generation fails
- Install pandoc: `apt install pandoc texlive-xetex`
- Or use Typst with Atomaste Report Standard