shopping-cli 3.0.0__py3-none-any.whl

shopping_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Standalone shopping-cli consultation runtime."""
+
+VERSION = "3.0.0"

shopping_cli/agents/__init__.py

@@ -0,0 +1 @@
+"""Buyer and merchant agent helpers."""

shopping_cli/agents/agent_cli.py

@@ -0,0 +1,31 @@
+"""Console entry point for running a resident merchant agent."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from shopping_cli.agents import merchant_agent, merchant_daemon
+from shopping_cli.cli_common import emit
+from shopping_cli.config import DEFAULT_DB_PATH
+from shopping_cli.db.session import db_session
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="Run a resident shopping-cli merchant agent.")
+    parser.add_argument("--db", default=str(DEFAULT_DB_PATH), help="SQLite database path")
+    parser.add_argument("--merchant", required=True)
+    parser.add_argument("--once", action="store_true")
+    parser.add_argument("--interval", type=float, default=3.0)
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+    if not args.once:
+        merchant_daemon.run_forever(args.db, args.merchant, interval=args.interval)
+        return
+    with db_session(args.db) as conn:
+        result = merchant_agent.process_once(conn, args.merchant)
+    emit(result, args.format)
+
+
+if __name__ == "__main__":
+    main()

shopping_cli/agents/buyer_cli.py

@@ -0,0 +1,163 @@
+"""Deterministic buyer-side consultation helpers."""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import Any
+
+from shopping_cli.core.catalog import product_summary, search_products
+from shopping_cli.core.conversations import append_message, conversation_summary, ensure_conversation
+from shopping_cli.core.errors import NotFoundError, ValidationError
+from shopping_cli.core.risk import infer_intent
+
+MVP_WARNINGS = [
+    "MVP records consultation only; no order is created.",
+    "No stock is reserved by shopping-cli.",
+    "Payment, refund, escrow, and delivery-success handling are outside this version.",
+]
+
+
+def status_guidance(conversation: dict[str, Any]) -> dict[str, Any]:
+    status = str(conversation.get("status") or "")
+    if status == "waiting_merchant":
+        return {
+            "pending": True,
+            "next_action": "Wait for merchant agent response.",
+            "status_hint": "merchant_agent_pending",
+        }
+    if status == "human_required":
+        return {
+            "pending": True,
+            "next_action": "Wait for merchant human review.",
+            "status_hint": "merchant_human_pending",
+        }
+    if status == "waiting_buyer":
+        return {
+            "pending": False,
+            "next_action": "Review the merchant reply and continue the consultation if needed.",
+            "status_hint": "buyer_turn",
+        }
+    if status == "closed":
+        return {
+            "pending": False,
+            "next_action": "Conversation is closed.",
+            "status_hint": "closed",
+        }
+    return {
+        "pending": False,
+        "next_action": "Continue the consultation without creating orders or payments.",
+        "status_hint": "open",
+    }
+
+
+def status_warnings(conversation: dict[str, Any]) -> list[str]:
+    status = str(conversation.get("status") or "")
+    if status == "waiting_merchant":
+        return ["Merchant agent response is pending; keep the conversation open."]
+    if status == "human_required":
+        return ["Merchant human review is required before any commitment."]
+    return []
+
+
+def ask(
+    conn: sqlite3.Connection,
+    buyer_id: str,
+    text: str,
+    city: str = "",
+    area: str = "",
+    limit: int = 3,
+    source_id: str = "buyer-cli",
+    host: str = "",
+    session_id: str = "",
+    reuse_open: bool = True,
+) -> dict[str, Any]:
+    buyer_id = str(buyer_id or "").strip()
+    if not buyer_id:
+        raise ValidationError("buyer id is required")
+    candidates = search_products(conn, query=text, city=city, area=area, limit=limit)
+    if not candidates:
+        return {
+            "ok": True,
+            "buyer_id": buyer_id,
+            "candidates": [],
+            "conversation": None,
+            "warnings": ["No matching merchant or product found.", *MVP_WARNINGS],
+            "missing_facts": ["merchant", "product"],
+        }
+    selected = candidates[0]
+    conversation = ensure_conversation(conn, buyer_id, selected["merchant_id"], selected["sku"], reuse_open=reuse_open)
+    message = append_message(
+        conn,
+        conversation["id"],
+        "buyer",
+        infer_intent(text),
+        text,
+        structured_payload={
+            "city": city,
+            "area": area,
+            "selected_sku": selected["sku"],
+            "source_id": source_id or "buyer-cli",
+            "host": host or "",
+            "session_id": session_id or "",
+        },
+    )
+    summary = conversation_summary(conn, conversation["id"])
+    return {
+        "ok": True,
+        "buyer_id": buyer_id,
+        "candidates": candidates,
+        "selected": selected,
+        "conversation": summary,
+        "message": message,
+        "warnings": [*MVP_WARNINGS, *status_warnings(summary)],
+        **status_guidance(summary),
+    }
+
+
+def summarize(conn: sqlite3.Connection, conversation_id: str) -> dict[str, Any]:
+    conversation = conversation_summary(conn, conversation_id)
+    option = conversation.get("product")
+    if option is None and conversation.get("sku"):
+        try:
+            option = product_summary(conn, conversation["sku"])
+        except NotFoundError:
+            option = None
+    missing_facts: list[str] = []
+    warnings = list(MVP_WARNINGS)
+    if option is None:
+        missing_facts.append("product")
+    else:
+        if not option["merchant"].get("contact"):
+            missing_facts.append("merchant contact")
+        if not option["delivery"].get("service_area"):
+            missing_facts.append("delivery rule")
+        if option["stock"] <= 0:
+            warnings.append("Product is out of stock.")
+    warnings.extend(status_warnings(conversation))
+    for flag in conversation["flags"]:
+        warnings.append(f"Human review flag: {flag['reason']}")
+    guidance = status_guidance(conversation)
+    return {
+        "ok": True,
+        "conversation": conversation,
+        "option": option,
+        "missing_facts": missing_facts,
+        "warnings": warnings,
+        **guidance,
+        "no_order_created": True,
+        "no_stock_reserved": True,
+    }
+
+
+def record_intent(conn: sqlite3.Connection, conversation_id: str, intent: str, text: str) -> dict[str, Any]:
+    if intent not in {"purchase_intent", "quote_request"}:
+        raise ValidationError("--intent must be purchase_intent or quote_request")
+    message = append_message(conn, conversation_id, "buyer", intent, text, structured_payload={"source_id": "buyer-cli"})
+    conversation = conversation_summary(conn, conversation_id)
+    return {
+        "ok": True,
+        "message": message,
+        "conversation": conversation,
+        "warnings": [*MVP_WARNINGS, *status_warnings(conversation)],
+        **status_guidance(conversation),
+    }

shopping_cli/agents/merchant_agent.py

@@ -0,0 +1,263 @@
+"""Resident deterministic merchant agent."""
+
+from __future__ import annotations
+
+import os
+import re
+import sqlite3
+from typing import Any, cast
+
+from shopping_cli import VERSION
+from shopping_cli.agents.buyer_cli import MVP_WARNINGS
+from shopping_cli.agents.tools import MerchantAgentTools, SQLiteMerchantAgentTools, record_heartbeat
+from shopping_cli.core.errors import NotFoundError
+from shopping_cli.core.harness import MAX_STALE_TTL_SECONDS, message_idempotency_key
+from shopping_cli.core.risk import human_review_reason
+from shopping_cli.core.limits import safe_non_negative_float as _safe_non_negative_float, safe_non_negative_int as _safe_non_negative_int
+
+
+def _positive_message_id(value: Any) -> int:
+    if isinstance(value, bool):
+        raise ValueError("buyer message id must be a positive integer")
+    try:
+        message_id = int(value)
+    except (OverflowError, TypeError, ValueError) as exc:
+        raise ValueError("buyer message id must be a positive integer") from exc
+    if message_id <= 0:
+        raise ValueError("buyer message id must be a positive integer")
+    return message_id
+
+
+def _claim_ttl_seconds_from_env() -> int:
+    try:
+        seconds = int(os.environ.get("SHOPPING_AGENT_CLAIM_TTL_SECONDS") or "300")
+    except (OverflowError, TypeError, ValueError):
+        return 300
+    return seconds if 0 < seconds <= MAX_STALE_TTL_SECONDS else 300
+
+
+def heartbeat(
+    conn: sqlite3.Connection,
+    merchant_id: str,
+    status: str = "online",
+    capabilities: list[str] | None = None,
+    pid: int = 0,
+    version: str = VERSION,
+    last_error: str = "",
+    checked_count: int = 0,
+    replied_count: int = 0,
+) -> dict[str, Any]:
+    return record_heartbeat(
+        conn,
+        merchant_id,
+        status=status,
+        capabilities=capabilities,
+        pid=pid,
+        version=version,
+        last_error=last_error,
+        checked_count=checked_count,
+        replied_count=replied_count,
+    )
+
+
+def latest_buyer_message(conversation: dict[str, Any]) -> dict[str, Any] | None:
+    for message in reversed(conversation.get("messages", [])):
+        if message["sender"] == "buyer":
+            return message
+    return None
+
+
+def has_agent_reply_after(conversation: dict[str, Any], buyer_message_id: int) -> bool:
+    for message in conversation.get("messages", []):
+        try:
+            message_id = _positive_message_id(message.get("id"))
+        except ValueError:
+            continue
+        if message_id <= buyer_message_id:
+            continue
+        if message["sender"] in {"merchant_agent", "merchant"}:
+            return True
+    return False
+
+
+def _automation_boundaries(product: dict[str, Any]) -> str:
+    merchant_value = product.get("merchant")
+    merchant = cast(dict[str, Any], merchant_value) if isinstance(merchant_value, dict) else {}
+    return str(merchant.get("automation_boundaries") or product.get("automation_boundaries") or "").strip()
+
+
+def _authorized_bargain_amount(product: dict[str, Any]) -> str:
+    boundaries = _automation_boundaries(product)
+    if not boundaries:
+        return ""
+    lower = boundaries.lower()
+    if not any(term in lower or term in boundaries for term in ("discount", "lowest", "final price", "砍价", "优惠", "实付", "成交")):
+        return ""
+    title = str(product.get("title") or "").strip()
+    sku = str(product.get("sku") or "").strip()
+    segments: list[str] = []
+    for marker in (title, sku):
+        if marker and marker in boundaries:
+            start = boundaries.find(marker)
+            segments.append(boundaries[start : start + 140])
+    if "两款均适用" in boundaries or "all products" in lower:
+        segments.append(boundaries)
+    patterns = [
+        r"(?:实付|最低可成交价|最低价|成交价)[^\d]{0,16}(\d+(?:\.\d+)?)\s*(?:元|cny|CNY)?",
+        r"(?:lowest price|final price)[^\d]{0,16}(\d+(?:\.\d+)?)\s*(?:cny|CNY|元)?",
+        r"(\d+(?:\.\d+)?)\s*(?:元|cny|CNY)[^\n。；;]{0,16}(?:成交|可成交)",
+    ]
+    for segment in segments:
+        for pattern in patterns:
+            match = re.search(pattern, segment, flags=re.IGNORECASE)
+            if match:
+                return match.group(1)
+    return ""
+
+
+def generate_reply(
+    tools: MerchantAgentTools,
+    conversation: dict[str, Any],
+    buyer_message: dict[str, Any],
+) -> tuple[str, bool, str]:
+    product = None
+    if conversation.get("sku"):
+        try:
+            product = tools.product_summary(conversation["sku"])
+        except (NotFoundError, SystemExit):
+            product = None
+    reason = human_review_reason(buyer_message["text"], product_found=product is not None)
+    if not reason and buyer_message.get("intent") in {"negotiate", "quote_request"}:
+        reason = "bargaining"
+    disclaimer = " ".join(MVP_WARNINGS)
+    if product is None:
+        return f"I need a merchant human to confirm which product this consultation refers to. {disclaimer}", True, reason
+    delivery = product["delivery"]
+    price = _safe_non_negative_float(product.get("price"))
+    stock = _safe_non_negative_int(product.get("stock"))
+    if not reason and stock <= 2:
+        reason = "low_stock"
+    if not reason and buyer_message["intent"] == "ask_delivery" and not delivery.get("service_area"):
+        reason = "unclear_delivery"
+    delivery_text = "delivery rule is missing"
+    if delivery.get("service_area"):
+        delivery_text = (
+            f"delivery area {delivery['service_area']}, ETA {_safe_non_negative_int(delivery.get('eta_minutes'))} minutes, "
+            f"fee {_safe_non_negative_float(delivery.get('fee')):.2f} {delivery['currency']}"
+        )
+    if reason == "bargaining":
+        # 议价底价是隐私——negotiation 路径以 _leaks_private_threshold 守护，
+        # resident 若直接报价（_authorized_bargain_amount）会把授权底价写进
+        # 公开会话。一致处理：议价请求一律路由人工审查，不自动报价。
+        return (
+            f"{product['title']} needs merchant human review for price negotiation. "
+            f"Catalog price {price:.2f} {product['currency']}, stock {stock}; {delivery_text}. {disclaimer}",
+            True,
+            "bargaining",
+        )
+    if reason:
+        return (
+            f"{product['title']} is listed at {price:.2f} {product['currency']} with "
+            f"{stock} in stock. This request needs merchant human review because: {reason}. {disclaimer}",
+            True,
+            reason,
+        )
+    return (
+        f"{product['title']} has stock {stock} and current price "
+        f"{price:.2f} {product['currency']}; {delivery_text}. {disclaimer}",
+        False,
+        "",
+    )
+
+
+def process_once_with_tools(tools: MerchantAgentTools, merchant_id: str) -> dict[str, Any]:
+    agent = tools.heartbeat(merchant_id)
+    abandoned: list[dict[str, Any]] = []
+    if hasattr(tools, "abandon_stale_messages"):
+        abandoned = tools.abandon_stale_messages(agent["id"], stale_after_seconds=_claim_ttl_seconds_from_env())
+    conversations = tools.waiting_merchant_conversations(merchant_id)
+    replied: list[dict[str, Any]] = []
+    failed: list[dict[str, Any]] = []
+    for conversation in conversations:
+        buyer_message = latest_buyer_message(conversation)
+        if buyer_message is None:
+            continue
+        # Negotiation-protocol 消息由 kiwi merchant 运行时经 negotiation API
+        # 驱动——resident 抢 claim 会打断买家的谈判回合（协商方 claim 失败），
+        # 且 generate_reply 曾把授权底价写进公开会话。协商消息一律跳过。
+        if (buyer_message.get("structured_payload") or {}).get("protocol_version"):
+            continue
+        try:
+            buyer_message_id = _positive_message_id(buyer_message.get("id"))
+        except ValueError as exc:
+            error = f"{type(exc).__name__}: {exc}"
+            tools.heartbeat(
+                merchant_id,
+                status="online",
+                last_error=error,
+                checked_count=len(conversations),
+                replied_count=len(replied),
+            )
+            failed.append({"conversation_id": conversation["id"], "message_id": 0, "error": error})
+            continue
+        if has_agent_reply_after(conversation, buyer_message_id):
+            continue
+        idempotency_key = message_idempotency_key(agent["id"], buyer_message_id)
+        claim = tools.claim_message(agent["id"], conversation["id"], buyer_message_id, idempotency_key)
+        if not claim.get("claimed"):
+            continue
+        try:
+            reply, needs_human, reason = generate_reply(tools, conversation, buyer_message)
+            status = "human_required" if needs_human else "waiting_buyer"
+            message = tools.append_message(
+                conversation["id"],
+                "merchant_agent",
+                buyer_message["intent"],
+                reply,
+                structured_payload={
+                    "human_required": needs_human,
+                    "reason": reason,
+                    "source_id": agent["id"],
+                    "processed_message_id": buyer_message_id,
+                    "idempotency_key": idempotency_key,
+                },
+                status=status,
+            )
+            tools.complete_message(agent["id"], buyer_message_id)
+            flags = []
+            if needs_human:
+                flags.append(tools.add_flag(conversation["id"], reason or "human_required", sku=conversation.get("sku", "")))
+                tools.heartbeat(merchant_id, status="human_required")
+            replied.append(
+                {
+                    "conversation_id": conversation["id"],
+                    "message_id": message["id"],
+                    "human_required": needs_human,
+                    "reason": reason,
+                    "flags": flags,
+                }
+            )
+        except Exception as exc:  # pragma: no cover - exercised through fake tools
+            error = f"{type(exc).__name__}: {exc}"
+            tools.fail_message(agent["id"], buyer_message_id, error)
+            tools.heartbeat(
+                merchant_id,
+                status="online",
+                last_error=error,
+                checked_count=len(conversations),
+                replied_count=len(replied),
+            )
+            failed.append({"conversation_id": conversation["id"], "message_id": buyer_message_id, "error": error})
+    return {
+        "ok": True,
+        "merchant_id": merchant_id,
+        "agent": agent,
+        "checked": len(conversations),
+        "replied": replied,
+        "failed": failed,
+        "abandoned": abandoned,
+    }
+
+
+def process_once(conn: sqlite3.Connection, merchant_id: str) -> dict[str, Any]:
+    return process_once_with_tools(SQLiteMerchantAgentTools(conn), merchant_id)