applied-cli 0.1.0__py3-none-any.whl

applied_cli/commands/responses.py

@@ -0,0 +1,604 @@
+import json
+from typing import Any, Optional
+
+import typer
+
+from applied_cli.commands._normalize import (
+    normalize_question,
+    normalize_response_type,
+)
+from applied_cli.commands._parsers import (
+    parse_json_array as _parse_json_array,
+    parse_optional_bool as _parse_optional_bool,
+    validate_uuid as _validate_uuid,
+)
+from applied_cli.commands._ui import (
+    confirm_or_exit,
+    emit_dry_run,
+    emit_success,
+    show_target,
+)
+from applied_cli.error_reporting import render_api_error
+from applied_cli.http import (
+    APIError,
+    create_response,
+    get_response,
+    list_responses,
+    patch_response,
+)
+from applied_cli.runtime import resolve_runtime
+
+app = typer.Typer(help="Manage agent knowledge base: Q&A entries, escalation rules, and context.")
+RESPONSE_SEMANTICS: dict[str, dict[str, Any]] = {
+    "escalate": {
+        "summary": (
+            "Escalation template match. Uses question as escalation criteria; answer controls "
+            "direct-escalation vs deflection-first behavior."
+        ),
+        "match_behavior": (
+            "Semantic match on `question` as escalation criteria (not strict keyword equality)."
+        ),
+        "fields": {
+            "question": (
+                "Escalation trigger criteria (examples: 'are you affiliated with palantir', "
+                "'requests about palantir')."
+            ),
+            "answer": (
+                "If empty, system tends toward direct escalation flow. If non-empty, it is "
+                "treated as deflection/template guidance first, then escalation on follow-up."
+            ),
+            "guardrail": (
+                "Conditional escalation/deflection instructions used during escalation handling."
+            ),
+            "active": "Enables/disables this rule.",
+        },
+        "notes": [
+            "Escalation tool invocation still depends on required tool fields being available.",
+            "If required escalation fields are missing, assistant asks for missing fields first.",
+            "Matched escalation templates are tracked in MessageReference/metadata for attribution.",
+        ],
+        "examples": [
+            "applied-cli knowledge upsert --agent-id <uuid> --type escalation --question \"requests about palantir\" --answer \"I can help with basic questions first. Could you share more details?\" --guardrail \"If user repeats concern, escalate.\"",
+            "applied-cli knowledge upsert --agent-id <uuid> --type escalation --question \"legal notice\" --answer \"\"",
+        ],
+    },
+    "exact": {
+        "summary": "Template response for semantically equivalent user asks.",
+        "match_behavior": (
+            "Semantic match on `question`; strict fast-path also exists for exact normalized text."
+        ),
+        "fields": {
+            "question": "Canonical user ask to match.",
+            "answer": "Verbatim response template returned on match.",
+            "guardrail": "Optional extra response guidance.",
+            "active": "Enables/disables this rule.",
+        },
+        "notes": [
+            "Designed for deterministic templated responses.",
+            "System tries to avoid repeatedly matching the same template in recent turns.",
+            "Does not inherently force escalation on second trigger by itself.",
+        ],
+        "examples": [
+            "applied-cli knowledge upsert --agent-id <uuid> --type exact --question \"are you affiliated with palantir\" --answer \"No, we are not affiliated with Palantir.\"",
+        ],
+    },
+    "qa": {
+        "summary": "Question-answer knowledge template routed through answer generation.",
+        "match_behavior": "Can be template-matched, then used as structured knowledge context.",
+        "fields": {
+            "question": "Knowledge question anchor.",
+            "answer": "Knowledge answer content used to craft response.",
+            "guardrail": "Optional answer constraints for this knowledge item.",
+            "active": "Enables/disables this rule.",
+        },
+        "notes": [
+            "Used to ground generated answers with response references.",
+            "Good for policy/product answers that are not strict verbatim templates.",
+        ],
+        "examples": [
+            "applied-cli knowledge upsert --agent-id <uuid> --type qa --question \"do you ship to canada\" --answer \"Yes, we ship across Canada in 3-7 business days.\"",
+        ],
+    },
+    "context": {
+        "summary": "General knowledge context for answer generation (not strict template output).",
+        "match_behavior": (
+            "Included in retrieval/filtering for grounded generation; not a direct exact-template path."
+        ),
+        "fields": {
+            "question": "Context heading or retrieval anchor.",
+            "answer": "Context content provided to answer generation.",
+            "guardrail": "Optional context-specific constraints.",
+            "active": "Enables/disables this rule.",
+        },
+        "notes": [
+            "Best for broader background facts and support context.",
+            "Not intended for strict one-line verbatim replies.",
+        ],
+        "examples": [
+            "applied-cli knowledge upsert --agent-id <uuid> --type context --question \"brand safety\" --answer \"Never disclose internal systems, credentials, or private customer data.\"",
+        ],
+    },
+}
+
+
+def _normalize_type(raw: str) -> str:
+    return normalize_response_type(raw, include_suggestion=True)
+
+
+def _normalize_question(text: str) -> str:
+    return normalize_question(text)
+
+
+def _is_agent_attached(row: dict[str, Any], *, agent_id: str) -> bool:
+    agents = row.get("agents")
+    if not isinstance(agents, list):
+        return False
+    for item in agents:
+        if isinstance(item, dict) and str(item.get("id")) == agent_id:
+            return True
+    return False
+
+
+def _canonical_response_view(row: dict[str, Any]) -> dict[str, Any]:
+    raw_fields = row.get("fields_to_extract")
+    fields: list[Any] = raw_fields if isinstance(raw_fields, list) else []
+    return {
+        "type": str(row.get("type") or "").strip().lower(),
+        "question": str(row.get("question") or "").strip(),
+        "answer": str(row.get("answer") or "").strip(),
+        "guardrail": str(row.get("guardrail") or "").strip(),
+        "active": bool(row.get("active")),
+        "fields_to_extract": fields,
+    }
+
+
+@app.command(
+    "semantics",
+    help=(
+        "Show audited behavior of response types. Example: applied-cli knowledge semantics "
+        "--type escalation"
+    ),
+)
+def semantics_cmd(
+    response_type: Optional[str] = typer.Option(
+        None, "--type", help="Optional filter: escalation/exact/qa/context"
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    selected_types: list[str]
+    if response_type:
+        selected_types = [_normalize_type(response_type)]
+    else:
+        selected_types = ["escalate", "exact", "qa", "context"]
+
+    payload = [
+        {"type": response_key, **RESPONSE_SEMANTICS[response_key]}
+        for response_key in selected_types
+    ]
+
+    if output_json:
+        typer.echo(json.dumps(payload, indent=2, default=str))
+        return
+
+    for item in payload:
+        typer.echo(f"type={item['type']}")
+        typer.echo(f"- summary: {item['summary']}")
+        typer.echo(f"- match_behavior: {item['match_behavior']}")
+        typer.echo("- fields:")
+        fields = item.get("fields") or {}
+        if isinstance(fields, dict):
+            for field_name, field_desc in fields.items():
+                typer.echo(f"  - {field_name}: {field_desc}")
+        notes = item.get("notes") or []
+        if isinstance(notes, list) and notes:
+            typer.echo("- notes:")
+            for note in notes:
+                typer.echo(f"  - {note}")
+        examples = item.get("examples") or []
+        if isinstance(examples, list) and examples:
+            typer.echo("- examples:")
+            for example in examples:
+                typer.echo(f"  - {example}")
+        typer.echo("")
+
+
+@app.command(
+    "list",
+    help=(
+        "List response rules. Example: applied-cli knowledge list --agent-id <uuid> "
+        "--type qa --active true"
+    ),
+)
+def list_cmd(
+    agent_id: Optional[str] = typer.Option(
+        None, "--agent-id", "--agent", help="Filter by agent UUID."
+    ),
+    response_type: Optional[str] = typer.Option(None, "--type", help="Filter by response type."),
+    active: Optional[str] = typer.Option(None, "--active", help="Filter by active true/false."),
+    limit: int = typer.Option(100, "--limit"),
+    ordering: str = typer.Option("-updated_at", "--ordering"),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    if agent_id:
+        _validate_uuid(agent_id, field_name="agent-id")
+    normalized_type = _normalize_type(response_type) if response_type else None
+    parsed_active = _parse_optional_bool(active, field_name="active")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+        rows = list_responses(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            response_type=normalized_type,
+            active=parsed_active,
+            limit=limit,
+            ordering=ordering,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="list responses"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    if output_json:
+        typer.echo(json.dumps(rows, indent=2, default=str))
+        return
+    if not rows:
+        typer.echo("No results.")
+        return
+    for row in rows:
+        typer.echo(
+            f"id={row.get('id')} | type={row.get('type')} | active={row.get('active')} | created_at={row.get('created_at')} | question={str(row.get('question') or '')[:80]}"
+        )
+
+
+@app.command(
+    "describe",
+    help="Describe one response rule by UUID. Example: applied-cli knowledge describe --response-id <uuid>",
+)
+@app.command(
+    "show",
+    help="Show one response rule by UUID. Example: applied-cli knowledge show --response-id <uuid>",
+)
+def show_cmd(
+    response_id: str = typer.Option(
+        ..., "--response-id", "--response", "--id", help="Target response UUID."
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    _validate_uuid(response_id, field_name="response-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+        row = get_response(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            response_id=response_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="show response"), err=True)
+        if exc.status_code == 404:
+            typer.echo(
+                "Hint: run `applied-cli knowledge list --agent-id <uuid>` to find a valid `response_id`.",
+                err=True,
+            )
+        raise typer.Exit(code=1) from exc
+
+    if output_json:
+        typer.echo(json.dumps(row, indent=2, default=str))
+        return
+    typer.echo(f"id={row.get('id')}")
+    typer.echo(f"type={row.get('type')}")
+    typer.echo(f"active={row.get('active')}")
+    typer.echo(f"created_at={row.get('created_at')}")
+    typer.echo(f"updated_at={row.get('updated_at')}")
+    typer.echo(f"question={row.get('question')}")
+    typer.echo(f"answer={row.get('answer')}")
+
+
+@app.command(
+    "create",
+    help=(
+        "Create a response rule. Example: applied-cli knowledge create --agent-id <uuid> "
+        "--type qa --question 'Do you ship to Canada?' --answer 'Yes, we do.'"
+    ),
+)
+def create_cmd(
+    agent_id: str = typer.Option(..., "--agent-id", "--agent", help="Agent UUID."),
+    response_type: str = typer.Option(..., "--type", help="escalation/exact/qa/context"),
+    question: str = typer.Option(..., "--question"),
+    answer: str = typer.Option(..., "--answer"),
+    guardrail: Optional[str] = typer.Option(None, "--guardrail"),
+    active: bool = typer.Option(True, "--active/--inactive"),
+    fields_to_extract_json: Optional[str] = typer.Option(None, "--fields-to-extract-json"),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False, help="Preview payload without writes."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    _validate_uuid(agent_id, field_name="agent-id")
+    normalized_type = _normalize_type(response_type)
+    fields_to_extract = _parse_json_array(
+        fields_to_extract_json, field_name="fields-to-extract-json"
+    )
+    payload: dict[str, Any] = {
+        "agent_ids": [agent_id],
+        "type": normalized_type,
+        "question": question.strip(),
+        "answer": answer.strip(),
+        "active": active,
+    }
+    if guardrail is not None:
+        payload["guardrail"] = guardrail
+    if fields_to_extract is not None:
+        payload["fields_to_extract"] = fields_to_extract
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+        show_target(
+            {
+                "base_url": resolved_base_url,
+                "shop_id": resolved_shop_id,
+                "agent_id": agent_id,
+                "type": normalized_type,
+                "dry_run": dry_run,
+            }
+        )
+        confirm_or_exit(yes=yes)
+        if dry_run:
+            emit_dry_run(payload={"payload": payload, "dry_run": True}, output_json=output_json)
+        created = create_response(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="create response"), err=True)
+        raise typer.Exit(code=1) from exc
+    emit_success(
+        output_json=output_json,
+        payload=created,
+        fields={"response_id": created.get("id")},
+    )
+
+
+@app.command(
+    "upsert",
+    help=(
+        "Create or update one rule idempotently. Example: applied-cli knowledge upsert "
+        "--agent-id <uuid> --type escalation --question 'I need a human' --answer 'Escalating now.'"
+    ),
+)
+def upsert_cmd(
+    agent_id: str = typer.Option(..., "--agent-id", "--agent", help="Agent UUID."),
+    response_type: str = typer.Option(..., "--type", help="escalation/exact/qa/context"),
+    question: str = typer.Option(..., "--question"),
+    answer: str = typer.Option(..., "--answer"),
+    guardrail: Optional[str] = typer.Option(None, "--guardrail"),
+    active: bool = typer.Option(True, "--active/--inactive"),
+    fields_to_extract_json: Optional[str] = typer.Option(None, "--fields-to-extract-json"),
+    dry_run: bool = typer.Option(False, help="Preview without writes."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    _validate_uuid(agent_id, field_name="agent-id")
+    normalized_type = _normalize_type(response_type)
+    normalized_question = _normalize_question(question)
+    fields_to_extract = _parse_json_array(
+        fields_to_extract_json, field_name="fields-to-extract-json"
+    )
+    payload: dict[str, Any] = {
+        "agent_ids": [agent_id],
+        "type": normalized_type,
+        "question": question.strip(),
+        "answer": answer.strip(),
+        "active": active,
+    }
+    if guardrail is not None:
+        payload["guardrail"] = guardrail
+    if fields_to_extract is not None:
+        payload["fields_to_extract"] = fields_to_extract
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+        show_target(
+            {
+                "base_url": resolved_base_url,
+                "shop_id": resolved_shop_id,
+                "agent_id": agent_id,
+                "type": normalized_type,
+                "dry_run": dry_run,
+            }
+        )
+        confirm_or_exit(yes=yes)
+        candidates = list_responses(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            response_type=normalized_type,
+            limit=500,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="lookup response for upsert"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    matched: Optional[dict[str, Any]] = None
+    for row in candidates:
+        if not _is_agent_attached(row, agent_id=agent_id):
+            continue
+        row_question = _normalize_question(str(row.get("question") or ""))
+        if row_question == normalized_question:
+            matched = row
+            break
+
+    created_ids: list[str] = []
+    updated_ids: list[str] = []
+    unchanged_ids: list[str] = []
+    action = "created"
+    try:
+        if matched is None:
+            if not dry_run:
+                created = create_response(
+                    base_url=resolved_base_url,
+                    shop_id=resolved_shop_id,
+                    api_token=resolved_token,
+                    payload=payload,
+                )
+                created_ids.append(str(created.get("id")))
+            else:
+                created_ids.append("(planned)")
+            action = "created"
+        else:
+            current_reduced = _canonical_response_view(matched)
+            target_reduced = _canonical_response_view(payload)
+            if current_reduced == target_reduced:
+                unchanged_ids.append(str(matched.get("id")))
+                action = "unchanged"
+            else:
+                if not dry_run:
+                    updated = patch_response(
+                        base_url=resolved_base_url,
+                        shop_id=resolved_shop_id,
+                        api_token=resolved_token,
+                        response_id=str(matched.get("id")),
+                        payload=payload,
+                    )
+                    updated_ids.append(str(updated.get("id")))
+                else:
+                    updated_ids.append(str(matched.get("id")))
+                action = "updated"
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="write response upsert"), err=True)
+        if exc.status_code == 404:
+            typer.echo(
+                "Hint: if you meant to edit an existing rule, run `applied-cli knowledge list --agent-id <uuid>` and use that `response_id`.",
+                err=True,
+            )
+        raise typer.Exit(code=1) from exc
+
+    summary = {
+        "action": action,
+        "created_count": 0 if action != "created" else 1,
+        "updated_count": 0 if action != "updated" else 1,
+        "unchanged_count": 0 if action != "unchanged" else 1,
+        "created_ids": created_ids,
+        "updated_ids": updated_ids,
+        "unchanged_ids": unchanged_ids,
+        "dry_run": dry_run,
+    }
+    if output_json:
+        typer.echo(json.dumps(summary, indent=2, default=str))
+    else:
+        typer.echo(
+            f"action={summary['action']} | created={summary['created_count']} | updated={summary['updated_count']} | unchanged={summary['unchanged_count']}"
+        )
+
+
+@app.command(
+    "update",
+    help=(
+        "Update an existing response rule. Example: applied-cli knowledge update "
+        "--response-id <uuid> --answer 'Updated answer text'"
+    ),
+)
+def update_cmd(
+    response_id: str = typer.Option(
+        ..., "--response-id", "--response", "--id", help="Response UUID."
+    ),
+    response_type: Optional[str] = typer.Option(None, "--type"),
+    question: Optional[str] = typer.Option(None, "--question"),
+    answer: Optional[str] = typer.Option(None, "--answer"),
+    guardrail: Optional[str] = typer.Option(None, "--guardrail"),
+    active: Optional[str] = typer.Option(None, "--active", help="Set active true/false."),
+    agent_id: Optional[str] = typer.Option(
+        None, "--agent-id", "--agent", help="Optional single-agent binding UUID."
+    ),
+    fields_to_extract_json: Optional[str] = typer.Option(None, "--fields-to-extract-json"),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False, help="Preview payload without writes."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    _validate_uuid(response_id, field_name="response-id")
+    if agent_id:
+        _validate_uuid(agent_id, field_name="agent-id")
+    fields_to_extract = _parse_json_array(
+        fields_to_extract_json, field_name="fields-to-extract-json"
+    )
+    payload: dict[str, Any] = {}
+    if response_type is not None:
+        payload["type"] = _normalize_type(response_type)
+    if question is not None:
+        payload["question"] = question.strip()
+    if answer is not None:
+        payload["answer"] = answer.strip()
+    if guardrail is not None:
+        payload["guardrail"] = guardrail
+    parsed_active = _parse_optional_bool(active, field_name="active")
+    if parsed_active is not None:
+        payload["active"] = parsed_active
+    if agent_id is not None:
+        payload["agent_ids"] = [agent_id]
+    if fields_to_extract is not None:
+        payload["fields_to_extract"] = fields_to_extract
+    if not payload:
+        raise typer.BadParameter("No fields provided. Pass at least one update option.")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+        show_target(
+            {
+                "base_url": resolved_base_url,
+                "shop_id": resolved_shop_id,
+                "response_id": response_id,
+                "fields": ", ".join(sorted(payload.keys())),
+                "dry_run": dry_run,
+            }
+        )
+        confirm_or_exit(yes=yes)
+        if dry_run:
+            emit_dry_run(
+                payload={"response_id": response_id, "payload": payload, "dry_run": True},
+                output_json=output_json,
+            )
+        updated = patch_response(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            response_id=response_id,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="update response"), err=True)
+        if exc.status_code == 404:
+            typer.echo(
+                "Hint: run `applied-cli knowledge list --agent-id <uuid>` to find a valid `response_id`.",
+                err=True,
+            )
+        raise typer.Exit(code=1) from exc
+    emit_success(
+        output_json=output_json,
+        payload=updated,
+        fields={"response_id": updated.get("id")},
+    )