feat(ai): 建立 PixelRAG application portfolio
This commit is contained in:
ogt
446
services/pixelrag_application_portfolio_service.py
Normal file
446
services/pixelrag_application_portfolio_service.py
Normal file
@@ -0,0 +1,446 @@
|
||||
"""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"]
|
||||
Reference in New Issue
Block a user