feat(camera): add name hint for failed item recognition

[mcull]

Summary

Fixes #310 - Adds the ability to provide a name hint when camera item recognition fails, helping the AI identify difficult items like gas cans and radial saws.

Problem

Camera item recognition was failing on certain items (specifically mentioned: gas can, radial saw) with no way for users to provide additional context to help the AI. Users would just see "Could not identify the item. Please try again." and have to retake the photo or give up.

Solution

1. Enhanced Error UI with Hint Option

When recognition fails, the error screen now shows:

• The captured photo (so users can see what image is being analyzed)
• Two clear action buttons:
  • "Take New Photo" - Start over with a fresh capture
  • "Try Again with Hint" - Provide a name hint for the same photo

2. Name Hint Input Flow

Clicking "Try Again with Hint" reveals:

• Text input with label: "What is this item?"
• Helpful placeholder: "e.g., gas can, radial saw, ladder..."
• Explanation: "Give us a hint about what this item is, and we'll try again with this photo"
• Two action buttons:
  • "Cancel" - Go back to error screen
  • "Try with Hint" - Submit hint and re-analyze (disabled until user types something)
• Enter key also submits the hint
• Auto-focuses on input for quick typing

3. Backend: analyze-item API Enhancement

Updated /api/analyze-item to accept optional nameHint form parameter:

const nameHint = formData.get('nameHint') as string | null;

When hint is provided, it's passed to OpenAI:

USER HINT: The user indicated this might be a "{hint}". Use this hint to help identify the object in the image, but still verify it matches what you see.

Key points:

• AI uses hint as context, not gospel truth
• Still applies all safety restrictions (no bypassing prohibited items)
• Improves recognition accuracy for edge cases

4. Smart Retry Logic

New retryWithHint() function:

1. Reuses the already-captured photo (no new photo required)
2. Converts data URL back to blob
3. Creates draft item if not already created
4. Sends photo + hint to analysis API
5. Updates item with recognized name/description
6. Triggers watercolor generation on success
7. Shows improved error message if hint still doesn't work:
   • "Still could not identify the item with that hint. Please try a new photo or different hint."

Distinguishing Recognition Failures vs. Prohibited Items

The API already distinguishes between:

• Prohibited items: Returns prohibited: true with specific prohibitionReason
  • Example: "Sharp weapons and dangerous items are not permitted for safety reasons"
• Genuine recognition failures: Returns recognized: false without prohibited flag
  • Example: Low confidence, blurry image, unclear object

The hint feature only appears for genuine recognition failures, not for prohibited items. This ensures the hint can't be used to bypass safety restrictions.

User Flow Example

1. User takes photo of a gas can
2. AI recognition fails: "Could not identify the item"
3. User sees the photo + two buttons
4. User clicks "Try Again with Hint"
5. Input appears: "What is this item?"
6. User types "gas can"
7. User clicks "Try with Hint" (or presses Enter)
8. System re-analyzes with hint: "USER HINT: The user indicated this might be a 'gas can'"
9. ✅ Success! Item recognized as "Gas Can"
10. Watercolor generation proceeds normally

Technical Details

Files Changed

• src/app/api/analyze-item/route.ts - Accept and use nameHint parameter
• src/components/AddItemClient.tsx - Add hint UI and retry logic

State Management

• showHintInput: boolean - Toggle hint input visibility
• nameHint: string - Store user's hint text

Dependencies

• Added TextField to MUI imports
• No new external dependencies

Testing Checklist

Manual Testing Needed

• Take photo of gas can → recognition fails → provide hint "gas can" → verify success
• Take photo of radial saw → recognition fails → provide hint "radial saw" → verify success
• Verify hint doesn't bypass safety restrictions (test with prohibited item + innocent hint)
• Test "Take New Photo" button still works correctly
• Test "Cancel" button in hint input returns to error state
• Test Enter key submits hint
• Verify captured photo displays correctly in error state
• Test error message when hint still doesn't work

Edge Cases

• Empty hint (button should be disabled)
• Whitespace-only hint (button should be disabled)
• Very long hint text
• Multiple retries with different hints
• Network failure during hint retry

Screenshots

Before (Current)

Error screen with only "Try Again" button

After (This PR)

Error screen showing:

• Captured photo thumbnail
• "Take New Photo" button (outlined)
• "Try Again with Hint" button (contained, primary)

Hint input screen showing:

• "What is this item?" text field
• Placeholder examples
• "Cancel" and "Try with Hint" buttons

Related

• Closes Item Recognition Enhancement with Name Hint #310

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
stufflibrary	Ready	Preview	Comment	Sep 30, 2025 3:03am