# Phase 4.1: AI Prompt Enhancement — Spare Parts Deep Identification - Context

**Gathered:** 2026-04-22
**Status:** Ready for planning

<domain>
## Phase Boundary

Enhance AI extraction pipeline to automatically identify spare parts (vs consumables) and search the internet for detailed specifications. When a Part Number is detected on an identified spare part, extract product type, specifications, manufacturer, and description from search results, pre-populate Item fields for user review, and allow editing before save.

**In scope:**
- Update AI prompt to distinguish spare parts (RAM, SSD, NVME, PCIe, disk, etc.) from consumables (cords, connectors, small hardware)
- Implement web-based internet search for part specifications (no API key required)
- Extract specs, manufacturer, product type, and descriptions from search results
- Pre-populate Item Category/Type/Notes fields with search results for user review
- Implement retry logic and error handling for search failures
- Validate with field users from Phase 4 deployments

**Out of scope:**
- Caching of search results (can be deferred)
- Price estimation from search (optional enhancement)
- Multi-language support for search results
- Local database of part specifications (MVP uses web search only)

</domain>

<decisions>
## Implementation Decisions

### AI Prompt Enhancement
- **D-01:** No explicit spare-part classification field. Infer from extracted category using a backend whitelist of known spare-part categories.
- **D-02:** Use detailed categorization logic in the AI prompt: "If a component plugs into or connects to another device (not just cabling), classify as spare part." Provide comprehensive examples (RAM, SSD, NVME, PCIe cards, disks, memory modules, processors, etc.) vs consumables (cords, connectors, adhesives, small fasteners).

### Internet Search Integration
- **D-03:** Use web scraping with Python `requests` + `BeautifulSoup` to extract Google search results. No API key required, suitable for low volume (tens of items per hour maximum).
- **D-04:** Implement rate limiting with delays and User-Agent headers to avoid IP blocking by Google. Details to be determined during planning (suggested: 1-2 second delay between requests, rotating User-Agent).

### Search Trigger & User Flow
- **D-05:** Automatic background search: After AI extraction, if extracted category matches the spare-parts whitelist AND Part Number is present, trigger internet search automatically.
- **D-06:** Block onboarding UI until search completes. Show loading state during search.
- **D-07:** On search failure: Display error message with "[Retry]" and "[Skip]" buttons. User can retry or proceed without specs.
- **D-08:** User reviews all search-populated fields before final save. User can edit any incorrect/incomplete data in the form.

### Data Extraction & Item Mapping
- **D-09:** Extract from search results: product type/category, specifications (capacity, speed, voltage, etc.), manufacturer/model name, and detailed description.
- **D-10:** Store extracted data:
  - **Category/Item Type:** Pre-populate with refined values from search. User can edit before saving.
  - **Notes field:** Store detailed specs, manufacturer, description, and any other details from search.
- **D-11:** Item Type field remains searchable/concise (e.g., "RAM DDR4" not full spec). Detailed specs go in Notes.

### Claude's Discretion
- Specific spare-parts category whitelist (which categories trigger search — to be built from field feedback and product categorization)
- Search timeout duration (recommended: 15-30 seconds max before showing "no results" error)
- BeautifulSoup parsing logic and CSS selectors for Google search results (site-specific and may need tuning)
- Retry logic details (number of retries, backoff strategy)
- Fallback behavior if internet is unavailable (graceful degradation — show empty spec fields for user to fill)

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Core Architecture & Data Models
- `PROJECT_ARCHITECTURE.md` — Item model fields (Category, Type, Notes), AI integration (Gemini 2.0 Flash, Claude 3.5 Sonnet), multi-AI provider pattern
- `PROJECT.md` — Multi-AI provider flexibility requirement, offline-first constraint, UI fidelity standards (no UPPERCASE, no BOLD fonts)
- `.planning/REQUIREMENTS.md` — Mobile UX, field user validation requirements

### AI & Prompt Design
- `backend/ai/gemini_extractor.py` — Current Gemini prompt structure and extraction pattern
- `backend/ai/claude_extractor.py` — Current Claude fallback pattern and prompt structure

### Frontend Integration (Onboarding Flow)
- `frontend/components/AIOnboarding.tsx` — Current item extraction and confirmation flow; where search results will be integrated

### UI/UX Standards
- `dev_docs/` — Premium fidelity standards (Tailwind, Lucide, no UPPERCASE, no BOLD)

No external specification documents — requirements fully captured in decisions above.

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- **AI Extractor Pattern:** `backend/ai/gemini_extractor.py` and `claude_extractor.py` provide the extraction interface. Search integration can follow the same async pattern.
- **AIOnboarding Component:** `frontend/components/AIOnboarding.tsx` already manages item confirmation flow. Search results will integrate into the review-and-edit phase before save.
- **ConfigManager:** `backend/config_manager.py` handles runtime configuration. Can be extended for search preferences (rate limits, timeout).
- **Admin Dashboard:** `frontend/components/AdminDashboard.tsx` has patterns for secure field masking; future enhancement for Google Search settings.

### Established Patterns
- **Multi-AI Provider:** Backend already switches between Gemini and Claude. Search integration is independent but should use the same provider-agnostic pattern if extending AI for parsing search results.
- **Offline-First:** Sync uses UUID idempotency. Search is online-only; gracefully skip if network unavailable.
- **Error Handling:** Admin dashboard shows error states. Onboarding should follow similar patterns for search failures.

### Integration Points
- **AI Extraction:** Search triggers after AI extraction completes (in `AIOnboarding.tsx`)
- **Item Save:** Search results pre-populate Item fields; user edits then saves as normal
- **Backend:** `/items/` POST endpoint receives search-enriched Item data

</code_context>

<specifics>
## Specific Ideas

- **Field User Validation (Phase 4):** Deploy with field teams running Phase 4 to gather feedback on search accuracy and relevance. Use their corrections to refine the spare-parts whitelist and prompt.
- **Spare-Parts Whitelist:** Build from common warehouse components: RAM, SSD, NVME, PCIe cards, CPU, power supplies, network cards, storage controllers, motherboards. Will refine based on field feedback.
- **Web Scraping Resilience:** Include user-agent rotation and request delays to avoid Google blocks. Consider fallback to a second search engine (e.g., Bing) if Google scraping fails.

</specifics>

<deferred>
## Deferred Ideas

- **Price Estimation:** Extract approximate cost from search results for asset valuation. Deferred to Phase 5 (nice-to-have, adds complexity).
- **Search Result Caching:** Cache search results for repeated part numbers to reduce API calls. Deferred to Phase 5 (optimization, not MVP).
- **Multi-Language Search:** Support searching in multiple languages based on user locale. Deferred to Phase 6+ (localization out of scope for v2).
- **Local Part Database:** Build local cache of known parts to avoid repeated searches. Deferred to Phase 6+ (requires significant infrastructure).

None — discussion stayed within phase scope.

</deferred>

---

*Phase: 4.1-ai-spare-parts-deep-id*
*Context gathered: 2026-04-22*