hermes-config/skills/self-hosting/shop-pro-quote/references/ai-features.md

AI Features — DeepSeek Integration

spq-v2 mirrors v1's AI integration exactly: all calls go to /deepseek/v1/chat/completions with deepseek-v4-flash.

Architecture

All AI functions live in src/lib/ai.ts and use a shared callDeepSeek() helper:

fetch('/deepseek/v1/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'deepseek-v4-flash',
    messages: [{role:'system', content}, {role:'user', content}],
    temperature: 0,
    thinking: { type: 'disabled' },
    max_tokens: 500,
  }),
})

The endpoint works through the Python proxy server (/deepseek/* is forwarded by nginx in production, not the Python proxy — the proxy only handles /pb/*; ensure nginx has the /deepseek location block).

Exported Functions

1. getPriorityAnalysis(services) — Generate Priorities

• Input: ServiceItem[] (name, recommendation)
• Output: PriorityResult[] (name, rank, priority_reason)
• Sends services to AI for safety-first ranking: CRITICAL_SAFETY > SAFETY_CONCERN > RECOMMENDED > MAINTENANCE > OPTIONAL
• Strips markdown code blocks from response before JSON parsing

2. aiWriteExplanation(params) — AI Write

• Input: ExplanationParams (serviceName, recommendation, technicianNotes?, vehicleInfo?, mileage?, maintenanceInterval?)
• Output: ExplanationResult (level, explanation) or null
• Generates professional customer-facing explanation
• Incorporates vehicle context, mileage, interval data
• Parses LEVEL: and EXPLANATION: tagged response format
• Level is one of: CRITICAL, RECOMMENDED, OPTIONAL, PREVENTIVE, MAINTENANCE

3. aiSuggestServices(vehicle, selectedServices, catalog) — AI Suggest

• Input: SuggestVehicle, string[], CatalogItem[]
• Output: SuggestResult[] (name, reason) or null
• Recommends services from catalog based on mileage + vehicle info
• Cross-references AI output against catalog names — only returns catalog matches
• Never invents services; only suggests from the provided catalog

4. Screenshot OCR + Extraction (in Appointments.tsx)

• Uses Tesseract.js (dynamic CDN import: cdn.jsdelivr.net/npm/tesseract.js@5)
• Canvas preprocessing: 2-3x upscale + mild contrast enhancement
• OCR text sent to /deepseek/v1/chat/completions with max_tokens: 2000 for structured JSON extraction
• Extracted appointments reviewed before batch import

Pitfalls

• Tesseract.js not in package.json — the screenshot import feature loads it dynamically from CDN. If offline or CDN blocked, the feature silently fails.
• Model must be deepseek-v4-flash — other models may not follow the strict JSON-only response format.
• AI functions return null on failure — UI must handle null gracefully (show toast, don't crash).
• temperature: 0 is intentional — structured extraction needs deterministic output.