amaprice 1.0.11 → 1.0.12

package/README.md

@@ -183,6 +183,9 @@ Environment variables used by the npm package:
 | `VISION_PROVIDER` | auto | `src/extractors/vision.js` | Optional force value: `openrouter` or `openai` |
 | `OPENROUTER_HTTP_REFERER` | none | `src/extractors/vision.js` | Optional OpenRouter attribution header |
 | `OPENROUTER_TITLE` | none | `src/extractors/vision.js` | Optional OpenRouter attribution header |
+| `VISION_GUARDRAIL_ENABLED` | `1` | `src/extractors/pipeline.js` | Reject suspicious vision outputs before DB writes |
+| `VISION_GUARDRAIL_MIN_CONFIDENCE` | `0.92` | `src/extractors/pipeline.js` | Minimum confidence required for vision price acceptance |
+| `VISION_GUARDRAIL_MAX_REL_DELTA` | `0.5` | `src/extractors/pipeline.js` | Max relative delta vs last known price before rejecting vision price |
 | `OPENAI_API_KEY` | none | `src/extractors/vision.js` | Legacy fallback if `OPENROUTER_API_KEY` is unset |
 
 For production background workers, prefer the Supabase **service role key**.
@@ -202,6 +205,9 @@ Steps:
    - `VISION_FALLBACK_ENABLED=1`
    - `OPENROUTER_API_KEY=<your-openrouter-key>`
    - `VISION_MODEL=google/gemini-3-flash-preview`
+   - `VISION_GUARDRAIL_ENABLED=1`
+   - `VISION_GUARDRAIL_MIN_CONFIDENCE=0.92`
+   - `VISION_GUARDRAIL_MAX_REL_DELTA=0.5`
 4. Ensure builder is Dockerfile (root `Dockerfile`).
 5. Deploy.
 6. Confirm logs show `[worker] processed=...`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amaprice",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "CLI tool to scrape and track Amazon product prices",
   "main": "src/scraper.js",
   "type": "commonjs",

package/src/extractors/pipeline.js

@@ -106,14 +106,81 @@ function normalizeScraperResult(result, method) {
   };
 }
 
+function toFiniteNumber(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : null;
+}
+
+function readFloatEnv(name, fallback, { min = null, max = null } = {}) {
+  const raw = process.env[name];
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  if (min != null && parsed < min) return min;
+  if (max != null && parsed > max) return max;
+  return parsed;
+}
+
+function isVisionGuardrailEnabled() {
+  return process.env.VISION_GUARDRAIL_ENABLED !== '0';
+}
+
+function getVisionMinConfidence() {
+  return readFloatEnv('VISION_GUARDRAIL_MIN_CONFIDENCE', 0.92, { min: 0, max: 1 });
+}
+
+function getVisionMaxRelativeDelta() {
+  return readFloatEnv('VISION_GUARDRAIL_MAX_REL_DELTA', 0.5, { min: 0, max: 10 });
+}
+
+function evaluateVisionGuardrails(result, {
+  baselinePrice = null,
+  enabled = isVisionGuardrailEnabled(),
+  minConfidence = getVisionMinConfidence(),
+  maxRelativeDelta = getVisionMaxRelativeDelta(),
+} = {}) {
+  if (!enabled) {
+    return { accepted: true, reason: null };
+  }
+
+  if (!result || result.method !== 'vision' || !result.price) {
+    return { accepted: true, reason: null };
+  }
+
+  const confidence = toFiniteNumber(result.confidence) || 0;
+  if (confidence < minConfidence) {
+    return {
+      accepted: false,
+      reason: `low_confidence:${confidence.toFixed(3)}<${Number(minConfidence).toFixed(3)}`,
+    };
+  }
+
+  const extracted = toFiniteNumber(result.price?.numeric);
+  const baseline = toFiniteNumber(baselinePrice);
+  if (extracted == null || baseline == null || baseline <= 0) {
+    return { accepted: true, reason: null };
+  }
+
+  const relativeDelta = Math.abs(extracted - baseline) / baseline;
+  if (relativeDelta > maxRelativeDelta) {
+    return {
+      accepted: false,
+      reason: `relative_delta:${relativeDelta.toFixed(3)}>${Number(maxRelativeDelta).toFixed(3)}`,
+    };
+  }
+
+  return { accepted: true, reason: null };
+}
+
 async function runCollectionPipeline({
   url,
   domain = null,
   allowVision = true,
   allowRailwayDomFallback = true,
+  baselinePrice = null,
 }) {
   const effectiveDomain = domain || extractDomain(url);
   const fallbackCurrency = fallbackCurrencyForDomain(effectiveDomain);
+  let rejectedVisionResult = null;
 
   const htmlJsonResult = normalizeScraperResult(
     await runHtmlJsonExtraction(url, { fallbackCurrency }),
@@ -139,9 +206,30 @@ async function runCollectionPipeline({
         finalUrl: shot.finalUrl,
       }, 'vision');
 
-      if (normalizedVision.price || normalizedVision.blockedSignal) {
+      if (normalizedVision.blockedSignal) {
         return normalizedVision;
       }
+
+      if (normalizedVision.price) {
+        const guardrail = evaluateVisionGuardrails(normalizedVision, { baselinePrice });
+        if (guardrail.accepted) {
+          return normalizedVision;
+        }
+
+        rejectedVisionResult = {
+          ...normalizedVision,
+          status: 'no_price',
+          price: null,
+          blockedSignal: false,
+          blockedReason: null,
+          debug: {
+            ...(normalizedVision.debug || {}),
+            guardrail: 'rejected',
+            guardrailReason: guardrail.reason,
+            baselinePrice: toFiniteNumber(baselinePrice),
+          },
+        };
+      }
     } catch (err) {
       // Continue to DOM fallback.
     }
@@ -152,7 +240,7 @@ async function runCollectionPipeline({
     return normalizeScraperResult(domResult, 'railway_dom');
   }
 
-  return htmlJsonResult;
+  return rejectedVisionResult || htmlJsonResult;
 }
 
 module.exports = {
@@ -163,4 +251,7 @@ module.exports = {
 module.exports.__test = {
   fallbackCurrencyForDomain,
   normalizeScraperResult,
+  evaluateVisionGuardrails,
+  getVisionMinConfidence,
+  getVisionMaxRelativeDelta,
 };

package/src/extractors/vision.js

@@ -185,6 +185,19 @@ function isVisionEnabled() {
   return process.env.VISION_FALLBACK_ENABLED === '1';
 }
 
+function buildVisionPrompt() {
+  return [
+    'You extract the final payable price from an Amazon product-detail screenshot.',
+    'Respond with JSON only using exactly keys: price, currency, confidence, is_blocked, reason, raw_text.',
+    'price must be a decimal number (dot separator), or null when uncertain.',
+    'Only use the main buy-box product price for the shown product.',
+    'Ignore list/strike prices, "from" ranges, installment/monthly values, coupons, shipping, used/new offers, bundle prices, and sponsored/related product prices.',
+    'If the page is captcha/challenge/login/cookie-wall and price is not clearly visible, set is_blocked=true and price=null.',
+    'If multiple plausible prices exist, set price=null.',
+    'confidence must be a number between 0 and 1.',
+  ].join(' ');
+}
+
 async function requestOpenRouter({ apiKey, model, prompt, base64 }) {
   const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
     method: 'POST',
@@ -291,12 +304,7 @@ async function extractPriceFromScreenshotBuffer(imageBuffer, {
     };
   }
 
-  const prompt = [
-    'Extract the currently visible final product price from this e-commerce screenshot.',
-    'Respond with JSON only and keys: price, currency, confidence, is_blocked, reason, raw_text.',
-    'Use decimal number for price (example: 79.99).',
-    'If price is not clearly visible, set price=null and confidence<=0.5.',
-  ].join(' ');
+  const prompt = buildVisionPrompt();
 
   const transport = selected.name === 'openrouter'
     ? await requestOpenRouter({
@@ -352,6 +360,7 @@ module.exports = {
 };
 
 module.exports.__test = {
+  buildVisionPrompt,
   extractJsonBlock,
   extractOutputText,
   getProvider,

package/src/orchestrator/runner.js

@@ -94,6 +94,7 @@ async function processClaimedJob(job, {
       domain: job.domain,
       allowVision,
       allowRailwayDomFallback,
+      baselinePrice: job.last_price,
     });
 
     if (!result.price) {