447 lines
18 KiB
Python
447 lines
18 KiB
Python
"""Read-only PixelRAG application portfolio and integration inventory.
|
|
|
|
This module converts the product strategy for PixelRAG into machine-readable
|
|
lanes. It is intentionally no-write: it does not crawl, call models, read
|
|
secrets, or promote visual evidence into price truth.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from collections import Counter
|
|
from copy import deepcopy
|
|
from datetime import datetime, timezone
|
|
from typing import Any, Mapping
|
|
|
|
|
|
POLICY = "read_only_pixelrag_application_portfolio_v1"
|
|
|
|
SOURCE_BASIS = [
|
|
{
|
|
"id": "pixelrag_visual_rag_pattern",
|
|
"basis": "render_public_pages_as_screenshot_tiles_for_visual_retrieval_and_vlm_reading",
|
|
"url": "https://medium.com/open-intelligence/pixelrag-proves-that-the-biggest-bottleneck-in-web-rag-was-the-text-parser-all-along-d6ce53c78b02",
|
|
},
|
|
{
|
|
"id": "google_merchant_product_data",
|
|
"basis": "normalize_offer_evidence_around_product_title_price_availability_image_link_and_related_attributes",
|
|
"url": "https://support.google.com/merchants/answer/7052112",
|
|
},
|
|
{
|
|
"id": "google_product_structured_data",
|
|
"basis": "use_product_price_availability_reviews_shipping_and_visual_rich-result_fields_as_validation_targets",
|
|
"url": "https://developers.google.com/search/docs/appearance/structured-data/product",
|
|
},
|
|
{
|
|
"id": "baymard_product_list_ux",
|
|
"basis": "product_list_cards_need_scannable_visuals_and_key_attributes_for_comparison",
|
|
"url": "https://baymard.com/research/ecommerce-product-lists",
|
|
},
|
|
]
|
|
|
|
|
|
LANES: list[dict[str, Any]] = [
|
|
{
|
|
"id": "commerce.marketplace_visual_offer_cards",
|
|
"priority": "P0",
|
|
"status": "production_contract_ready",
|
|
"area": "commerce",
|
|
"title": "Multi-commerce public offer card visual evidence",
|
|
"integrates_with": [
|
|
"momo",
|
|
"pchome",
|
|
"shopee_tw",
|
|
"coupang_tw",
|
|
"yahoo_shopping_tw",
|
|
"etmall_tw",
|
|
"friday_tw",
|
|
"rakuten_tw",
|
|
],
|
|
"use_cases": [
|
|
"Rendered product cards",
|
|
"Promotion badges",
|
|
"Seller and delivery badges",
|
|
"Rating and sold-count signals",
|
|
"Parser-empty or parser-low-confidence fallback",
|
|
],
|
|
"current_capability": [
|
|
"visual_manifest_generation",
|
|
"visual_capture_receipts",
|
|
"rag_candidate_replay",
|
|
"ocr_vlm_replay_contract",
|
|
],
|
|
"next_machine_action": "run_ollama_first_vlm_replay_worker",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
{
|
|
"id": "commerce.product_feed_and_structured_data_gap_check",
|
|
"priority": "P0",
|
|
"status": "source_contract_design_ready",
|
|
"area": "commerce",
|
|
"title": "Product feed / structured data gap detection",
|
|
"integrates_with": [
|
|
"Google Merchant product data",
|
|
"Google Product structured data",
|
|
"brand sites",
|
|
"Shopify storefronts",
|
|
"marketplace offer pages",
|
|
],
|
|
"use_cases": [
|
|
"Compare visible product card fields against feed/structured-data fields",
|
|
"Detect missing image, price, availability, review, shipping, or product URL evidence",
|
|
"Build source contracts before platform data enters growth opportunities",
|
|
],
|
|
"current_capability": [
|
|
"source_readiness_contract",
|
|
"external_offer_evidence_contract",
|
|
"pixelrag_field_contract",
|
|
],
|
|
"next_machine_action": "build_pixelrag_source_contract_gap_readback",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
{
|
|
"id": "commerce.promotion_coupon_delivery_badge_extraction",
|
|
"priority": "P1",
|
|
"status": "contract_ready_worker_not_started",
|
|
"area": "commerce",
|
|
"title": "Promotion, coupon, discount, and delivery badge extraction",
|
|
"integrates_with": [
|
|
"Shopee promotion chips",
|
|
"Coupang delivery badges",
|
|
"MOMO campaign blocks",
|
|
"PChome campaign badges",
|
|
"Yahoo/ETMall coupon panels",
|
|
],
|
|
"use_cases": [
|
|
"Detect visible discounts that structured parsers miss",
|
|
"Separate base price from coupon/member/delivery incentives",
|
|
"Feed promotion evidence into no-write candidate receipts",
|
|
],
|
|
"current_capability": ["ocr_vlm_replay_contract"],
|
|
"next_machine_action": "run_ollama_first_vlm_replay_worker_then_promotion_gate",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
{
|
|
"id": "commerce.product_identity_visual_matching",
|
|
"priority": "P1",
|
|
"status": "requires_worker_and_identity_replay",
|
|
"area": "commerce",
|
|
"title": "Product identity visual matching",
|
|
"integrates_with": [
|
|
"product images",
|
|
"package size/spec text",
|
|
"brand/logo regions",
|
|
"variant cards",
|
|
"unit price evidence",
|
|
],
|
|
"use_cases": [
|
|
"Reduce false same-product matches",
|
|
"Use package/spec visual evidence before accepting competitor offer candidates",
|
|
"Keep unit basis evidence attached to each candidate",
|
|
],
|
|
"current_capability": ["field_contract", "identity_matcher_required_boundary"],
|
|
"next_machine_action": "build_visual_identity_matcher_replay_contract",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
{
|
|
"id": "commerce.availability_delivery_stock_signal",
|
|
"priority": "P1",
|
|
"status": "source_contract_design_ready",
|
|
"area": "commerce",
|
|
"title": "Availability, stock, delivery, and shipping signal evidence",
|
|
"integrates_with": [
|
|
"PChome stock hints",
|
|
"MOMO availability text",
|
|
"Coupang rocket delivery badge",
|
|
"Shopee shipping badge",
|
|
"merchant listing structured data",
|
|
],
|
|
"use_cases": [
|
|
"Avoid recommending unavailable or slow-delivery products for promotion",
|
|
"Detect delivery advantage as a sales-action signal",
|
|
"Flag missing availability in source contracts",
|
|
],
|
|
"current_capability": ["ocr_vlm_replay_contract", "source_readiness_contract"],
|
|
"next_machine_action": "build_availability_delivery_evidence_replay",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
{
|
|
"id": "commerce.platform_barrier_classifier",
|
|
"priority": "P0",
|
|
"status": "production_contract_ready",
|
|
"area": "governance",
|
|
"title": "Blocked page / captcha / login barrier classifier",
|
|
"integrates_with": [
|
|
"PixelRAG capture receipts",
|
|
"Shopee/Coupang probes",
|
|
"structured API fallback strategy",
|
|
"source contract status",
|
|
],
|
|
"use_cases": [
|
|
"Prevent AI from treating 403/captcha/login pages as product data",
|
|
"Route blocked pages to platform probe or structured API strategy",
|
|
"Keep anti-bot boundaries explicit",
|
|
],
|
|
"current_capability": ["visual_barrier_reason", "blocked_pages_are_not_product_data"],
|
|
"next_machine_action": "build_platform_probe_or_structured_api_strategy",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
{
|
|
"id": "rag.visual_evidence_to_internal_knowledge",
|
|
"priority": "P1",
|
|
"status": "contract_ready_worker_not_started",
|
|
"area": "rag",
|
|
"title": "Visual evidence to internal RAG learning candidates",
|
|
"integrates_with": [
|
|
"rag_service",
|
|
"learning_episode_candidate_preview",
|
|
"PromotionGate",
|
|
"embedding signature guard",
|
|
"pgvector metadata lane",
|
|
],
|
|
"use_cases": [
|
|
"Turn accepted visual receipts into replayable learning candidates",
|
|
"Attach screenshot/tile evidence to every extracted field",
|
|
"Only promote after OCR/VLM, identity replay, PromotionGate, and signature guard pass",
|
|
],
|
|
"current_capability": ["rag_candidate_replay", "ocr_vlm_replay_contract"],
|
|
"next_machine_action": "run_vlm_extraction_then_rag_candidate_promotion_preflight",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
{
|
|
"id": "rag.pgvector_visual_metadata",
|
|
"priority": "P2",
|
|
"status": "not_started",
|
|
"area": "rag",
|
|
"title": "pgvector-compatible visual evidence metadata",
|
|
"integrates_with": [
|
|
"pgvector",
|
|
"BGE-M3 text metadata",
|
|
"Qwen3-VL or approved local visual model",
|
|
"visual receipt file refs",
|
|
],
|
|
"use_cases": [
|
|
"Search visual evidence by platform, field, tile, and confidence",
|
|
"Avoid FAISS in production until ADR approves a separate store",
|
|
"Keep retrieval metadata in the same governance boundary as text RAG",
|
|
],
|
|
"current_capability": ["deferred_until_ollama_first_visual_embedding_benchmark"],
|
|
"next_machine_action": "run_ollama_first_visual_embedding_benchmark",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
{
|
|
"id": "ux.product_listing_quality_benchmark",
|
|
"priority": "P2",
|
|
"status": "source_contract_design_ready",
|
|
"area": "ux",
|
|
"title": "Product listing/card UX quality benchmark",
|
|
"integrates_with": [
|
|
"Baymard product list heuristics",
|
|
"PChome growth dashboard",
|
|
"AI surface visual QA",
|
|
"external marketplace screenshots",
|
|
],
|
|
"use_cases": [
|
|
"Benchmark whether our product cards show enough scannable evidence",
|
|
"Detect text-heavy or missing-attribute cards",
|
|
"Turn external marketplace patterns into product UX guardrails",
|
|
],
|
|
"current_capability": ["sitewide_visual_qa_readback", "pixelrag_visual_receipts"],
|
|
"next_machine_action": "build_product_card_visual_ux_benchmark_readback",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": False,
|
|
},
|
|
{
|
|
"id": "ops.visual_regression_for_public_pages",
|
|
"priority": "P2",
|
|
"status": "partially_integrated",
|
|
"area": "ops",
|
|
"title": "Public page visual regression and evidence capture",
|
|
"integrates_with": [
|
|
"sitewide visual QA",
|
|
"AI automation smoke",
|
|
"product landing pages",
|
|
"crawler diagnostics pages",
|
|
],
|
|
"use_cases": [
|
|
"Catch layout breaks that HTML tests do not see",
|
|
"Keep evidence screenshots attached to smoke history",
|
|
"Detect content overlap and text-heavy regressions",
|
|
],
|
|
"current_capability": ["sitewide_visual_qa_readback"],
|
|
"next_machine_action": "merge_pixelrag_tile_receipts_with_sitewide_visual_qa_artifacts",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": False,
|
|
},
|
|
{
|
|
"id": "marketing.ad_landing_and_creative_evidence",
|
|
"priority": "P3",
|
|
"status": "not_started",
|
|
"area": "marketing",
|
|
"title": "Ad landing page and creative evidence checks",
|
|
"integrates_with": [
|
|
"Google Shopping landing pages",
|
|
"Meta commerce public landing pages",
|
|
"public brand campaign pages",
|
|
"product feed destination URLs",
|
|
],
|
|
"use_cases": [
|
|
"Verify landing page visible price/image availability against feed contract",
|
|
"Detect promotional creative mismatch before campaign decisions",
|
|
"Keep evidence read-only and public-page-only",
|
|
],
|
|
"current_capability": ["manifest_contract_possible"],
|
|
"next_machine_action": "build_public_landing_visual_evidence_contract",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
{
|
|
"id": "forbidden.personalized_or_private_state",
|
|
"priority": "P0_guardrail",
|
|
"status": "forbidden",
|
|
"area": "governance",
|
|
"title": "Personalized, cart, checkout, account, or anti-bot bypass states",
|
|
"integrates_with": [],
|
|
"use_cases": [
|
|
"Explicitly reject login-only prices, carts, checkout pages, private coupons, sessions, and anti-bot bypass",
|
|
"Prevent hidden manual or credentialed scraping from entering the automation plan",
|
|
],
|
|
"current_capability": ["guardrail_only"],
|
|
"next_machine_action": "reject_and_route_to_official_api_or_manual_csv_contract",
|
|
"writes_database": False,
|
|
"promotion_required_before_price_truth": True,
|
|
},
|
|
]
|
|
|
|
|
|
def _selected_lanes(
|
|
*,
|
|
area: str | None = None,
|
|
priority: str | None = None,
|
|
include_forbidden: bool = False,
|
|
) -> list[dict[str, Any]]:
|
|
area_key = str(area or "").strip().lower()
|
|
priority_key = str(priority or "").strip().upper()
|
|
selected: list[dict[str, Any]] = []
|
|
for lane in LANES:
|
|
if not include_forbidden and lane["status"] == "forbidden":
|
|
continue
|
|
if area_key and lane["area"] != area_key:
|
|
continue
|
|
if priority_key and lane["priority"] != priority_key:
|
|
continue
|
|
selected.append(deepcopy(lane))
|
|
return selected
|
|
|
|
|
|
def _counts(lanes: list[Mapping[str, Any]], key: str) -> dict[str, int]:
|
|
return dict(sorted(Counter(str(item.get(key) or "unknown") for item in lanes).items()))
|
|
|
|
|
|
def _recommended_order(lanes: list[Mapping[str, Any]]) -> list[dict[str, Any]]:
|
|
order = {"P0": 0, "P0_guardrail": 1, "P1": 2, "P2": 3, "P3": 4}
|
|
actionable = [
|
|
item for item in lanes
|
|
if str(item.get("status")) not in {"forbidden"}
|
|
]
|
|
ranked = sorted(
|
|
actionable,
|
|
key=lambda item: (
|
|
order.get(str(item.get("priority")), 99),
|
|
str(item.get("status")),
|
|
str(item.get("id")),
|
|
),
|
|
)
|
|
return [
|
|
{
|
|
"rank": index + 1,
|
|
"id": item["id"],
|
|
"priority": item["priority"],
|
|
"status": item["status"],
|
|
"next_machine_action": item["next_machine_action"],
|
|
}
|
|
for index, item in enumerate(ranked[:8])
|
|
]
|
|
|
|
|
|
def build_pixelrag_application_portfolio(
|
|
*,
|
|
area: str | None = None,
|
|
priority: str | None = None,
|
|
include_forbidden: bool = False,
|
|
) -> dict[str, Any]:
|
|
"""Return the product-level PixelRAG integration portfolio."""
|
|
lanes = _selected_lanes(area=area, priority=priority, include_forbidden=include_forbidden)
|
|
ready_count = sum(
|
|
1 for item in lanes
|
|
if str(item.get("status")) in {"production_contract_ready", "source_contract_design_ready", "partially_integrated"}
|
|
)
|
|
blocked_or_forbidden_count = sum(
|
|
1 for item in lanes
|
|
if str(item.get("status")) in {"forbidden"}
|
|
)
|
|
worker_required_count = sum(
|
|
1 for item in lanes
|
|
if "worker" in str(item.get("status")) or "worker" in str(item.get("next_machine_action"))
|
|
)
|
|
|
|
return {
|
|
"success": True,
|
|
"policy": POLICY,
|
|
"generated_at": datetime.now(timezone.utc).isoformat(),
|
|
"status": "portfolio_ready",
|
|
"filters": {
|
|
"area": str(area or "").strip().lower() or None,
|
|
"priority": str(priority or "").strip().upper() or None,
|
|
"include_forbidden": include_forbidden,
|
|
},
|
|
"summary": {
|
|
"lane_count": len(lanes),
|
|
"ready_or_partially_integrated_count": ready_count,
|
|
"worker_required_count": worker_required_count,
|
|
"blocked_or_forbidden_count": blocked_or_forbidden_count,
|
|
"area_counts": _counts(lanes, "area"),
|
|
"priority_counts": _counts(lanes, "priority"),
|
|
"status_counts": _counts(lanes, "status"),
|
|
},
|
|
"source_basis": SOURCE_BASIS,
|
|
"lanes": lanes,
|
|
"recommended_order": _recommended_order(lanes),
|
|
"answer_to_owner": (
|
|
"PixelRAG should become the visual evidence layer for public product cards, "
|
|
"feed/structured-data gap detection, promotion/delivery badge extraction, "
|
|
"identity matching evidence, internal RAG candidate promotion, and product UX "
|
|
"benchmarking. It must stay no-write until OCR/VLM replay, identity replay, "
|
|
"PromotionGate, and source contracts pass."
|
|
),
|
|
"not_recommended": [
|
|
"Do not use PixelRAG for login-only prices, cart/checkout state, private coupons, sessions, or anti-bot bypass.",
|
|
"Do not write competitor_prices, competitor_price_history, ai_insights, or RAG truth directly from pixels.",
|
|
"Do not use hosted VLM/embedding APIs as the default path; use Ollama-first verification.",
|
|
"Do not put FAISS into production visual retrieval without a separate ADR; prefer pgvector-compatible metadata first.",
|
|
],
|
|
"controlled_apply": {
|
|
"network_call": False,
|
|
"db_write": False,
|
|
"secret_read": False,
|
|
"production_price_write": False,
|
|
"artifact_write": False,
|
|
"primary_human_gate_count": 0,
|
|
},
|
|
"next_machine_action": (
|
|
"run_ollama_first_vlm_replay_worker"
|
|
if worker_required_count
|
|
else "keep_pixelrag_application_portfolio_monitoring"
|
|
),
|
|
}
|
|
|
|
|
|
__all__ = ["POLICY", "build_pixelrag_application_portfolio"]
|