"""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"]