Daniel Bedeleanu
b90085cce5
- AI Prompt: Detailed categorization to distinguish spare parts from consumables - Search: Web scraping (requests + BeautifulSoup) to extract Google results, no API key - Trigger: Automatic background search after AI extraction if category matches whitelist - UX: Block until search completes, user reviews and edits all fields before save - Mapping: Extract product type/specs/manufacturer/description to Notes field - Retry on failure, user can skip if needed
9.3 KiB
Phase 4.1: AI Prompt Enhancement — Spare Parts Deep Identification - Discussion Log
Audit trail only. Do not use as input to planning, research, or execution agents. Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
Date: 2026-04-22 Phase: 4.1-ai-spare-parts-deep-id Areas discussed: AI Prompt Strategy, Search API Selection, Search Trigger & Confirmation, Data Extraction & Item Mapping
AI Prompt Strategy
Classification Approach
| Option | Description | Selected |
|---|---|---|
| Yes, explicit classification | AI returns spare_part_detected field. Backend auto-searches if true. Cleaner, deterministic behavior. | |
| No, infer from category | Use the extracted category to infer if it's likely a spare part (e.g., 'RAM', 'SSD' → search). Less explicit, fewer prompt changes. | ✓ |
| Hybrid approach | AI provides a classification + confidence score. Backend uses both to decide whether to search. |
User's choice: No, infer from category
Rationale: Keeps the AI extraction unchanged; the backend maintains a whitelist of spare-part categories that trigger search. Simpler to implement and maintain.
Prompt Detail Level
| Option | Description | Selected |
|---|---|---|
| Basic list in prompt | Add simple guidance: 'Spare parts: RAM, SSD, NVME, PCIe cards, etc. Consumables: cords, connectors, small hardware. Extract category accordingly.' | |
| Detailed categorization | Provide extensive examples and decision logic: 'If it's a component that plugs into or connects to another device (not just cabling), classify as spare part.' | ✓ |
| You decide | Claude picks the right level of detail based on testing during planning phase. |
User's choice: Detailed categorization
Rationale: Field users need reliable distinction. Detailed prompt with decision logic (plugs/connects vs just cables) reduces false positives on consumables.
Search API Selection
Internet Search Service
| Option | Description | Selected |
|---|---|---|
| Google Custom Search (official API) | Reliable, well-documented, ~100 free queries/day + paid tiers. Requires API key + setup. | |
| Bing Search API | Fast, cheaper than Google ($0-7/month for 1M queries), fewer free tier limits. Less common in Python examples. | |
| DuckDuckGo or free Python libs | Zero cost, no auth, easier to start. Less reliable (may get blocked, unstable parsing). Good for MVP, risky for production. | |
| Deferred decision | Research both during planning phase, decide based on cost/complexity/reliability trade-offs. |
User's choice: Modified to avoid API keys
User's note: "Google Custom Search needs an api key? If yes, I don't need this. We cannot use free Google search? The items will not be 1000s in short time, will be tens in an hour maximum rate."
Follow-up decision: User prioritizes zero API key overhead. Volume is low (tens/hour). Recommend web scraping instead of official API.
Search Implementation Method
| Option | Description | Selected |
|---|---|---|
| Web scraping (requests + BeautifulSoup) | No API key needed, zero cost, works for low volume (tens/hour). Risk: Google may block scraper IPs. Mitigate with rate limiting + delays. | ✓ |
| DuckDuckGo instant answer API | Free, no key, returns structured 'instant answers' for simple queries (specs, product info). Limited but sufficient for parts lookup. | |
| Python library (googlesearch-py) | Open-source, zero cost, handles Google scraping internally. Less reliable than official API but good for MVP. |
User's choice: Yes, web scraping
Rationale: Zero API key overhead, suitable for low-volume field use, can implement rate limiting to avoid blocking.
Search Trigger & Confirmation
When Search Should Occur
| Option | Description | Selected |
|---|---|---|
| Automatic in background | After AI extraction, if category is in spare-part whitelist and Part Number exists, search automatically. Results appear in UI shortly after. | ✓ |
| User-initiated button | Show 'Search for specs' button in the onboarding UI. User clicks to trigger search. More control, less friction-free. | |
| Auto-search + optional repeat | Search auto-triggers by default. User can click 'Refresh search' to get fresh results if needed. |
User's choice: Automatic in background
Rationale: Frictionless for field users. Reduces decision fatigue; specs appear automatically if available.
UI Behavior During Search
| Option | Description | Selected |
|---|---|---|
| Non-blocking (populate later) | Show item form immediately. Specs from search fill in after they arrive. User can save without waiting for search. | |
| Optional block (wait or skip) | Show loading state. Button to 'Save anyway' or 'Wait for specs'. User chooses based on impatience. | |
| Quick timeout (3-5 sec) | Wait max 3-5 seconds for search results. If no results arrive, continue without them. Prevents user frustration from slow internet. |
User's choice (modified): "User will wait for all fields to be populated, and if not ok, will edit not ok fields and after that will save the new item in inventory."
Rationale: Review-and-edit-before-save model. User blocks until search completes, reviews all pre-populated fields, edits as needed, then saves.
Implication: Requires a reasonable timeout before showing "no results" error; details to be determined during planning.
Failure Handling
| Option | Description | Selected |
|---|---|---|
| Show error, let user retry | Display 'Search failed. [Retry] or [Skip]'. User can retry or proceed without specs. | ✓ |
| Pre-fill with manual entry | Search fails → show empty spec fields. User manually enters details they know. No retry. | |
| Reasonable timeout (15 sec) then skip | Wait 15 seconds max. If no results, show 'No specs found online. [Edit manually]' and continue. |
User's choice: Show error, let user retry
Rationale: User has control. Can retry if network is temporarily unavailable; can skip if they don't want to wait.
Data Extraction & Item Mapping
Fields to Extract from Search Results
| Option | Description | Selected |
|---|---|---|
| Product type/category | What the part is (RAM, SSD, etc.). Refines the AI-extracted category if needed. | ✓ |
| Specifications (speed, capacity, voltage) | Technical details that matter for inventory (DDR4 32GB, 3.0TB SSD, etc.). | ✓ |
| Manufacturer/model | Brand and model name if found. Helps distinguish between variants. | ✓ |
| Price estimate | Approx cost if available. Useful for valuation, but may be outdated or region-specific. |
User's choice: Product type, Specifications, Manufacturer/model, plus "details/description of that item too"
Rationale: Comprehensive data about each part. Price optional; description/details more useful than price for inventory accuracy.
Item Field Mapping
| Option | Description | Selected |
|---|---|---|
| Enrich 'Item Type' field | Item Type becomes detailed: 'RAM DDR4 32GB 3000MHz' (combining specs + type). Category stays as selected. | |
| Use 'Notes' for detailed specs | Item Type is simpler (e.g., 'RAM'). Notes field gets the detailed specs and description from search. | ✓ |
| Both fields | Item Type is searchable summary ('RAM DDR4'). Notes gets full detailed specs/description/manufacturer. |
User's choice: Use 'Notes' for detailed specs
Rationale: Keeps Item Type concise and searchable. Notes field captures all detailed information without cluttering the type field.
Category Refinement from Search
| Option | Description | Selected |
|---|---|---|
| Pre-populate, user can edit | Search results suggest a refined category/type. User can accept or change it before saving. | ✓ |
| Trust AI extraction | Keep the AI's original category/type. Search results fill in Notes only. No second-guessing the AI. | |
| Suggest if high confidence | If search results clearly indicate a different category (e.g., search says 'SSD' but AI said 'Storage'), suggest it. Otherwise keep AI extraction. |
User's choice: Pre-populate, user can edit
Rationale: Search often clarifies or refines the category. User can accept the refined value or revert to AI extraction if search is incorrect.
Claude's Discretion
Areas where user deferred to Claude for implementation decisions:
- Specific spare-parts category whitelist (to be built from field feedback)
- Search timeout duration (suggested: 15-30 seconds before showing error)
- BeautifulSoup parsing logic and CSS selectors for Google results
- Rate limiting strategy (delays, retries, backoff)
- Fallback behavior if internet is unavailable
Deferred Ideas
- Price Estimation — Extract approximate cost from search results for asset valuation. Noted for Phase 5 (nice-to-have).
- Search Result Caching — Cache results for repeated part numbers to reduce searches. Noted for Phase 5 (optimization, not MVP).
- Multi-Language Search — Support multiple languages. Noted for Phase 6+ (localization).
- Local Part Database — Build local cache of known parts. Noted for Phase 6+ (infrastructure heavy).