applied-cli 0.1.0__py3-none-any.whl

applied_cli/presets/demo.yaml

@@ -0,0 +1,170 @@
+# ============================================================================
+# Applied Demo Setup Template
+# ============================================================================
+#
+# AGENT INSTRUCTIONS
+# ------------------
+# You are filling in this template to set up a demo shop for a new brand.
+# Follow these steps IN ORDER before writing the spec:
+#
+#   1. BRAND CONTEXT
+#      Search "[BrandName] about" or read their homepage to understand what
+#      they sell, their tone, and key policies (warranty, subscription, etc.)
+#
+#   2. HELP CENTER URL
+#      Search "[BrandName] help center" or "[BrandName] FAQ" to find their
+#      support site. Common patterns: help.brand.com, support.brand.com,
+#      brand.com/pages/faq. Use the top-level support page URL below.
+#
+#   3. Q&A RESPONSES (aim for 4–5 total)
+#      Fetch 3–4 pages from the help center covering different topics
+#      (shipping/tracking, returns/exchanges, warranty, product FAQ).
+#      Extract real answers — do NOT fabricate content.
+#      If you cannot find real content for a topic, OMIT that Q&A entry
+#      entirely rather than leaving a placeholder.
+#      Keep answers under 100 words. Use natural customer phrasing for
+#      questions (e.g. "How do I track my order?" not "Order tracking").
+#
+#   4. AGENT NAME
+#      Pick a friendly, gender-neutral first name for the email agent
+#      (e.g. Alex, Jordan, Sam, Casey). Not a real employee name.
+#
+#   5. GREETING (chat)
+#      Write a warm opening message matching the brand's tone.
+#      IMPORTANT: {firstName} in answer text is a RUNTIME token — the
+#      backend substitutes the customer's actual first name at send time.
+#      Do NOT replace {firstName} with a real name. Leave it as-is.
+#      Do NOT include the shop name (e.g. avoid "Welcome to BrandName Demo").
+#      Use the brand name directly: "Welcome to [BrandName]."
+#
+#   6. LEAVE ESCALATION TRIGGERS AS-IS
+#      Do not change the escalation question text. These are exact-match
+#      phrases used to route conversations to a human agent.
+#
+#   7. SIMULATION DISTRIBUTION
+#      Fill in the simulation.distribution section at the bottom.
+#      If a classified CSV was provided, use the topic/intent frequencies
+#      from that data. Otherwise estimate based on the brand's support type:
+#        - E-commerce (physical goods): heavy warranty/returns/shipping
+#        - SaaS/subscription: heavy billing/cancellation/technical
+#        - Marketplace: heavy order issues/refunds/seller disputes
+#      Topic and intent names must match the taxonomy exactly.
+#      All percent values must sum to 100.
+#
+#   8. REMOVE ALL COMMENT LINES before running shop setup.
+#      YAML comments (#) are fine to keep — the CLI ignores them.
+#      But remove any unfilled placeholder entries (type: qa with "...")
+#      entirely.
+#
+# ============================================================================
+
+name: "[BrandName] Demo"
+
+brand:
+  description: >
+    [TODO: 2–3 sentences — what the brand does, what they sell, and any
+    key differentiators such as warranty programs, subscription model,
+    or notable product features.]
+  guardrail: >
+    [TODO: Tone and boundary instructions. Example: "Always be helpful
+    and concise. Never make commitments outside of established [BrandName]
+    policies. Escalate billing disputes and warranty edge-cases to a
+    human agent."]
+
+agents:
+  - modality: chat
+    name: "[BrandName] Chat"
+    description: >
+      [TODO: 1 sentence — AI support agent for [BrandName] customers via
+      live chat. What does it handle?]
+    auto_reply: true
+    responses:
+      - type: greeting
+        # {firstName} is a RUNTIME token — leave it exactly as {firstName}.
+        # The backend replaces it with the customer's first name at send time.
+        # Write a warm, brand-appropriate opening under 20 words.
+        answer: "Hey {firstName}! Welcome to [BrandName]. How can I help you today?"
+
+      # Add 4–5 Q&A pairs sourced from the brand's help center.
+      # Fetch real pages — do NOT fabricate answers.
+      # OMIT an entry entirely if you cannot find real content for it.
+      # Common topics: shipping/tracking, returns, warranty, product FAQ.
+      - type: qa
+        question: "[customer question — natural phrasing, e.g. How do I track my order?]"
+        answer: "[answer sourced from help center — under 100 words]"
+
+      # (copy the qa block above for each additional Q&A — aim for 4–5 total)
+
+      - type: escalation
+        question: "I want to speak to a human"
+      - type: escalation
+        question: "This is urgent"
+
+  - modality: email
+    name: "[BrandName] Email"
+    description: >
+      [TODO: 1 sentence — AI support agent for [BrandName] customers via
+      email. What does it handle?]
+    auto_reply: true
+    responses:
+      - type: greeting
+        # Keep short — the agent writes the full email body.
+        # {firstName} is a RUNTIME token — do NOT replace it.
+        answer: "Hi {firstName},"
+
+      - type: signature
+        # Replace [AgentName] with a friendly first name (e.g. Alex, Jordan).
+        # Use \\\n for a line break within the signature text.
+        answer: "Best,\n\n[AgentName]\\\n[BrandName] Customer Support Team"
+
+      # Same Q&A pairs as chat — copy them here.
+      # OMIT any entry where you don't have real content.
+      - type: qa
+        question: "[same question as chat]"
+        answer: "[same answer as chat]"
+
+      # (copy for each additional Q&A)
+
+      - type: escalation
+        question: "I want to speak to a human"
+
+# Optional: include if a historical conversations CSV is available.
+# Remove this section entirely if no CSV is provided.
+#
+# conversations_csv:
+#   file_path: "/path/to/classified_conversations.csv"
+#   process_labels: true
+#   agent_modality: email   # which agent receives the imported conversations
+#   column_map:             # rename CSV columns to match expected headers
+#     OriginalIdColumn: ID
+#     OriginalBodyColumn: BODY
+
+knowledge_base:
+  # Search "[BrandName] help center" to find this URL.
+  # Use the top-level support/FAQ page (e.g. help.brand.com).
+  url: "https://[help-center-url]"
+  title: "[BrandName] Help Center"
+
+# Simulation populates the analytics graphs with realistic conversation history.
+# Requires a superuser account — if you're not a superuser the step is skipped
+# gracefully. To skip intentionally, remove this section.
+#
+# AGENT INSTRUCTIONS for distribution:
+#   1. If a classified conversations CSV was provided and used above, use the
+#      topic/intent frequency breakdown from that data to set percent values.
+#   2. If no CSV is available, make a reasonable guess based on the brand's
+#      support patterns (e.g. e-commerce brands: heavy on shipping/returns/warranty).
+#   3. topic and intent names must exactly match what's in the taxonomy file.
+#      Run `applied-cli intents list` after setup to verify names.
+#   4. All percent values must sum to exactly 100.
+#
+simulation:
+  num_conversations: 500
+  date_from: "[YYYY-MM-DD, e.g. 90 days ago]"
+  date_to: "[YYYY-MM-DD, e.g. today]"
+  delete_previous: false
+  distribution:
+    - topic: "[TopicName]"
+      intent: "[IntentName]"
+      percent: [number]
+    # Add more entries — all percents must sum to 100

applied_cli/runtime.py

@@ -0,0 +1,53 @@
+import os
+from typing import Optional
+
+from applied_cli.auth_store import load_credentials
+from applied_cli.config import DEFAULT_BASE_URL, normalize_base_url
+from applied_cli.http import APIError
+
+
+def resolve_runtime(
+    *,
+    base_url: Optional[str],
+    shop_id: Optional[str],
+    api_token: Optional[str],
+) -> tuple[str, str, str]:
+    requested_profile = os.getenv("APPLIED_PROFILE")
+    creds = load_credentials(profile=requested_profile)
+    resolved_base_url = normalize_base_url(
+        base_url
+        or os.getenv("APPLIED_BASE_URL")
+        or os.getenv("APPLIED_ENDPOINT")
+        or (creds.base_url if creds else "")
+        or DEFAULT_BASE_URL
+    )
+    resolved_shop_id = shop_id or os.getenv("APPLIED_SHOP_ID") or (
+        creds.shop_id if creds else ""
+    )
+    resolved_token = api_token or os.getenv("APPLIED_API_TOKEN") or (
+        creds.api_token if creds else ""
+    )
+
+    if not resolved_base_url:
+        raise APIError(
+            "Missing base URL.",
+            code="MISSING_BASE_URL",
+            hint="Set via --base-url, APPLIED_BASE_URL, or run `applied-cli auth login`.",
+            retryable=False,
+        )
+    if not resolved_shop_id:
+        raise APIError(
+            "Missing shop ID.",
+            code="MISSING_SHOP_ID",
+            hint="Set via --shop-id, APPLIED_SHOP_ID, or run `applied-cli auth login`.",
+            retryable=False,
+        )
+    if not resolved_token:
+        raise APIError(
+            "Missing API token.",
+            code="MISSING_API_TOKEN",
+            hint="Set via --api-token, APPLIED_API_TOKEN, or run `applied-cli auth login`.",
+            retryable=False,
+        )
+
+    return resolved_base_url, resolved_shop_id, resolved_token

applied_cli/shop_spec.py

@@ -0,0 +1,398 @@
+"""
+Spec file loader and validator for `applied-cli shop setup`.
+
+Supports YAML and JSON formats.  Returns a fully-validated dict ready for the
+setup command to consume without further type-checking.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from applied_cli.commands._normalize import MODALITY_ALIASES, RESPONSE_TYPE_ALIASES
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+# Matches unfilled template placeholders in two styles:
+#   {BrandName}  — curly-brace, uppercase-first  (NOT {firstName} which is runtime)
+#   [BrandName]  — square-bracket, uppercase-first, NOT followed by ( (which would be a markdown link)
+#   [TODO: ...]  — square-bracket TODO marker
+_TEMPLATE_PLACEHOLDER_RE = re.compile(
+    r"\{[A-Z][^}]*\}"           # {BrandName} style
+    r"|"
+    r"\[[A-Z][^\]]*\](?!\()"    # [BrandName] style, not a markdown link [text](url)
+)
+
+def _err(path: str, message: str) -> None:
+    raise ValueError(f"spec.{path}: {message}")
+
+
+def _check_placeholder(value: str, *, path: str) -> None:
+    """Raise if value looks like an unfilled template placeholder."""
+    if value.strip() in {"...", "[fill in]", ""}:
+        _err(path, "contains an unfilled template placeholder — replace with real content")
+    match = _TEMPLATE_PLACEHOLDER_RE.search(value)
+    if match:
+        _err(
+            path,
+            f"contains unfilled template placeholder '{match.group()}' — replace with real content"
+            " ({firstName} is a runtime token and is allowed)",
+        )
+
+
+def _require_str(value: Any, *, path: str, allow_empty: bool = False) -> str:
+    if value is None:
+        _err(path, "is required")
+    if not isinstance(value, str):
+        _err(path, "must be a string")
+    s = value.strip()
+    if not allow_empty and not s:
+        _err(path, "cannot be empty")
+    return s
+
+
+def _optional_str(value: Any, *, path: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        _err(path, "must be a string")
+    return value.strip() or None
+
+
+def _optional_bool(value: Any, *, path: str, default: bool) -> bool:
+    if value is None:
+        return default
+    if not isinstance(value, bool):
+        _err(path, "must be true or false")
+    return value
+
+
+def _optional_int(value: Any, *, path: str, min_val: int | None = None) -> int | None:
+    if value is None:
+        return None
+    if not isinstance(value, int) or isinstance(value, bool):
+        _err(path, "must be an integer")
+    if min_val is not None and value < min_val:
+        _err(path, f"must be >= {min_val}")
+    return value
+
+
+def _normalize_modality(raw: Any, *, path: str) -> str:
+    s = _require_str(raw, path=path)
+    key = s.lower()
+    if key not in MODALITY_ALIASES:
+        _err(path, f"must be one of: {', '.join(sorted(MODALITY_ALIASES))}")
+    return MODALITY_ALIASES[key]
+
+
+# ---------------------------------------------------------------------------
+# Response validation
+# ---------------------------------------------------------------------------
+
+def _validate_response(raw: Any, *, path: str) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        _err(path, "must be an object")
+
+    raw_type = raw.get("type")
+    if not isinstance(raw_type, str):
+        _err(f"{path}.type", "is required")
+    type_key = raw_type.strip().lower()
+    if type_key not in RESPONSE_TYPE_ALIASES:
+        _err(f"{path}.type", f"must be one of: {', '.join(sorted(RESPONSE_TYPE_ALIASES))}")
+    response_type = RESPONSE_TYPE_ALIASES[type_key]
+
+    # greeting/signature use fixed question labels; escalation answers are trigger-only
+    if response_type == "greeting":
+        question = _optional_str(raw.get("question"), path=f"{path}.question") or "Greeting message"
+        answer = _require_str(raw.get("answer"), path=f"{path}.answer")
+        _check_placeholder(answer, path=f"{path}.answer")
+    elif response_type == "signature":
+        question = _optional_str(raw.get("question"), path=f"{path}.question") or "Message signature"
+        answer = _require_str(raw.get("answer"), path=f"{path}.answer")
+        _check_placeholder(answer, path=f"{path}.answer")
+    elif response_type == "escalate":
+        question = _require_str(raw.get("question"), path=f"{path}.question")
+        _check_placeholder(question, path=f"{path}.question")
+        answer = _optional_str(raw.get("answer"), path=f"{path}.answer") or ""
+    else:
+        question = _require_str(raw.get("question"), path=f"{path}.question")
+        _check_placeholder(question, path=f"{path}.question")
+        answer = _require_str(raw.get("answer"), path=f"{path}.answer")
+        _check_placeholder(answer, path=f"{path}.answer")
+
+    return {
+        "type": response_type,
+        "question": question,
+        "answer": answer,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Agent validation
+# ---------------------------------------------------------------------------
+
+def _validate_agent(raw: Any, *, path: str, brand_guardrail: str | None) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        _err(path, "must be an object")
+
+    modality = _normalize_modality(raw.get("modality"), path=f"{path}.modality")
+    name = _optional_str(raw.get("name"), path=f"{path}.name")
+    description = _optional_str(raw.get("description"), path=f"{path}.description")
+
+    # Guardrail: use agent-level if set, fall back to brand.guardrail
+    guardrail_raw = raw.get("guardrail")
+    if guardrail_raw is not None:
+        guardrail = _optional_str(guardrail_raw, path=f"{path}.guardrail")
+    else:
+        guardrail = brand_guardrail
+
+    auto_reply = _optional_bool(raw.get("auto_reply"), path=f"{path}.auto_reply", default=True)
+    escalation_mode = _optional_str(raw.get("escalation_mode"), path=f"{path}.escalation_mode")
+    response_delay = _optional_int(
+        raw.get("response_delay_in_seconds"),
+        path=f"{path}.response_delay_in_seconds",
+        min_val=0,
+    )
+
+    responses_raw = raw.get("responses") or []
+    if not isinstance(responses_raw, list):
+        _err(f"{path}.responses", "must be an array")
+    responses = [
+        _validate_response(r, path=f"{path}.responses[{i}]")
+        for i, r in enumerate(responses_raw)
+    ]
+
+    return {
+        "modality": modality,
+        "name": name,  # may be None — caller fills in default
+        "description": description,
+        "guardrail": guardrail,
+        "auto_reply": auto_reply,
+        "escalation_mode": escalation_mode,
+        "response_delay_in_seconds": response_delay,
+        "responses": responses,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Optional section validators
+# ---------------------------------------------------------------------------
+
+def _validate_conversations_csv(raw: Any, *, path: str) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        _err(path, "must be an object")
+
+    file_path = _optional_str(raw.get("file_path"), path=f"{path}.file_path")
+    url = _optional_str(raw.get("url"), path=f"{path}.url")
+    if not file_path and not url:
+        _err(path, "requires either file_path or url")
+    if file_path and url:
+        _err(path, "provide either file_path or url, not both")
+
+    process_labels = _optional_bool(
+        raw.get("process_labels"), path=f"{path}.process_labels", default=True
+    )
+    agent_modality_raw = raw.get("agent_modality")
+    agent_modality: str | None = None
+    if agent_modality_raw is not None:
+        agent_modality = _normalize_modality(agent_modality_raw, path=f"{path}.agent_modality")
+
+    # column_map: optional dict renaming CSV columns before upload.
+    # Keys are original column names (case-insensitive match), values are target names.
+    # Example: {"ConversationId": "ID", "conversation": "BODY"}
+    column_map_raw = raw.get("column_map")
+    column_map: dict[str, str] | None = None
+    if column_map_raw is not None:
+        if not isinstance(column_map_raw, dict):
+            _err(f"{path}.column_map", "must be an object mapping original to target column names")
+        column_map = {str(k): str(v) for k, v in column_map_raw.items()}
+
+    return {
+        "file_path": file_path,
+        "url": url,
+        "process_labels": process_labels,
+        "agent_modality": agent_modality,
+        "column_map": column_map,
+    }
+
+
+def _validate_taxonomy(raw: Any, *, path: str) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        _err(path, "must be an object")
+
+    file_path = _require_str(raw.get("file_path"), path=f"{path}.file_path")
+    if not Path(file_path).exists():
+        _err(f"{path}.file_path", f"file not found: {file_path}")
+
+    return {"file_path": file_path}
+
+
+def _validate_knowledge_base(raw: Any, *, path: str) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        _err(path, "must be an object")
+
+    url = _require_str(raw.get("url"), path=f"{path}.url")
+    title = _optional_str(raw.get("title"), path=f"{path}.title")
+
+    return {"url": url, "title": title}
+
+
+def _validate_simulation(raw: Any, *, path: str) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        _err(path, "must be an object")
+
+    num_conversations = _optional_int(
+        raw.get("num_conversations"), path=f"{path}.num_conversations", min_val=1
+    ) or 20
+    date_from = _require_str(raw.get("date_from"), path=f"{path}.date_from")
+    date_to = _require_str(raw.get("date_to"), path=f"{path}.date_to")
+    delete_previous = _optional_bool(
+        raw.get("delete_previous"), path=f"{path}.delete_previous", default=False
+    )
+
+    distribution_raw = raw.get("distribution")
+    if not isinstance(distribution_raw, list) or not distribution_raw:
+        _err(f"{path}.distribution", "is required and must be a non-empty array")
+    distribution: list[dict[str, Any]] = []
+    total_pct = 0
+    for i, item in enumerate(distribution_raw):
+        item_path = f"{path}.distribution[{i}]"
+        if not isinstance(item, dict):
+            _err(item_path, "must be an object")
+        topic = _require_str(item.get("topic"), path=f"{item_path}.topic")
+        intent = _require_str(item.get("intent"), path=f"{item_path}.intent")
+        pct_raw = item.get("percent")
+        if not isinstance(pct_raw, (int, float)) or isinstance(pct_raw, bool):
+            _err(f"{item_path}.percent", "must be a number")
+        pct = float(pct_raw)
+        if pct <= 0:
+            _err(f"{item_path}.percent", "must be > 0")
+        total_pct += pct
+        distribution.append({"topic": topic, "intent": intent, "percent": pct})
+
+    if abs(total_pct - 100.0) > 0.5:
+        _err(f"{path}.distribution", f"percent values must sum to 100 (got {total_pct})")
+
+    return {
+        "num_conversations": num_conversations,
+        "date_from": date_from,
+        "date_to": date_to,
+        "delete_previous": delete_previous,
+        "distribution": distribution,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Top-level loader
+# ---------------------------------------------------------------------------
+
+def load_and_validate_shop_spec(spec_path: str) -> dict[str, Any]:
+    """Load and validate a shop setup spec file (YAML or JSON).
+
+    Returns a fully-validated dict:
+    {
+        "name": str,
+        "brand": {"description": str|None, "guardrail": str|None},
+        "agents": [{"modality", "name", "description", "guardrail", "auto_reply",
+                    "escalation_mode", "response_delay_in_seconds", "responses"}, ...],
+        "conversations_csv": {...} | None,
+        "knowledge_base": {...} | None,
+        "simulation": {...} | None,
+    }
+    """
+    path = Path(spec_path)
+    try:
+        raw_text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"spec: cannot read file: {exc}") from exc
+
+    payload: Any
+    suffix = path.suffix.lower()
+    if suffix in {".yaml", ".yml"}:
+        try:
+            import yaml  # type: ignore[import-untyped]
+
+            payload = yaml.safe_load(raw_text)
+        except ImportError as exc:
+            raise ValueError(
+                "pyyaml is required to load YAML spec files. "
+                "Run: pip install pyyaml"
+            ) from exc
+        except Exception as exc:
+            raise ValueError(f"spec: invalid YAML — {exc}") from exc
+    else:
+        try:
+            payload = json.loads(raw_text)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"spec: invalid JSON — {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise ValueError("spec: root must be an object")
+
+    # --- name ---
+    name = _require_str(payload.get("name"), path="name")
+    _check_placeholder(name, path="name")
+
+    # --- brand (optional) ---
+    brand_raw = payload.get("brand")
+    brand_description: str | None = None
+    brand_guardrail: str | None = None
+    if brand_raw is not None:
+        if not isinstance(brand_raw, dict):
+            _err("brand", "must be an object")
+        brand_description = _optional_str(brand_raw.get("description"), path="brand.description")
+        if brand_description:
+            _check_placeholder(brand_description, path="brand.description")
+        brand_guardrail = _optional_str(brand_raw.get("guardrail"), path="brand.guardrail")
+        if brand_guardrail:
+            _check_placeholder(brand_guardrail, path="brand.guardrail")
+
+    # --- agents (required, min 1) ---
+    agents_raw = payload.get("agents")
+    if not isinstance(agents_raw, list) or not agents_raw:
+        _err("agents", "is required and must be a non-empty array")
+    agents: list[dict[str, Any]] = []
+    for i, agent_raw in enumerate(agents_raw):
+        validated = _validate_agent(
+            agent_raw,
+            path=f"agents[{i}]",
+            brand_guardrail=brand_guardrail,
+        )
+        # Fill in default name if not specified
+        if not validated["name"]:
+            modality_label = validated["modality"].replace("_", " ").title()
+            validated["name"] = f"{name} {modality_label}"
+        agents.append(validated)
+
+    # --- optional sections ---
+    conversations_csv: dict[str, Any] | None = None
+    if "conversations_csv" in payload and payload["conversations_csv"] is not None:
+        conversations_csv = _validate_conversations_csv(
+            payload["conversations_csv"], path="conversations_csv"
+        )
+
+    taxonomy: dict[str, Any] | None = None
+    if "taxonomy" in payload and payload["taxonomy"] is not None:
+        taxonomy = _validate_taxonomy(payload["taxonomy"], path="taxonomy")
+
+    knowledge_base: dict[str, Any] | None = None
+    if "knowledge_base" in payload and payload["knowledge_base"] is not None:
+        knowledge_base = _validate_knowledge_base(payload["knowledge_base"], path="knowledge_base")
+
+    simulation: dict[str, Any] | None = None
+    if "simulation" in payload and payload["simulation"] is not None:
+        simulation = _validate_simulation(payload["simulation"], path="simulation")
+
+    return {
+        "name": name,
+        "brand": {"description": brand_description, "guardrail": brand_guardrail},
+        "agents": agents,
+        "conversations_csv": conversations_csv,
+        "taxonomy": taxonomy,
+        "knowledge_base": knowledge_base,
+        "simulation": simulation,
+    }