applied-cli 0.1.0__py3-none-any.whl

applied_cli/commands/simulate.py

@@ -0,0 +1,330 @@
+import json
+from typing import Any, Optional
+
+import typer
+
+from applied_cli.commands._parsers import parse_json_dict, validate_uuid
+from applied_cli.error_reporting import render_api_error
+from applied_cli.http import APIError, simulate_agent_conversation
+from applied_cli.runtime import resolve_runtime
+
+app = typer.Typer(
+    help="Generate simulated conversations (including backdated timestamps)."
+)
+
+
+@app.command(
+    "run",
+    help=(
+        "Simulate conversations for an agent with sensible defaults. Example: "
+        "applied-cli simulate run --agent-id <uuid> --count 10 "
+        "--created-at-from 2026-01-26T00:00:00Z --created-at-to 2026-02-26T23:59:59Z "
+        "--is-test false --conversation-type web_chat"
+    ),
+)
+@app.command(
+    "conversations",
+    hidden=True,
+    help="Alias for `simulate run`.",
+)
+def conversations_cmd(
+    agent_id: str = typer.Option(
+        ...,
+        "--agent-id",
+        "--agent",
+        "--id",
+        help="Target agent UUID.",
+    ),
+    count: int = typer.Option(
+        1,
+        "--count",
+        help="Number of conversations to simulate.",
+    ),
+    max_turns: int = typer.Option(
+        6,
+        "--max-turns",
+        help="Maximum turns per simulated conversation (1-10).",
+    ),
+    agent_subtype: Optional[str] = typer.Option(
+        None,
+        "--agent-subtype",
+        help="Optional agent subtype forwarded to simulate endpoint.",
+    ),
+    conversation_type: Optional[str] = typer.Option(
+        None,
+        "--conversation-type",
+        help="Optional conversation type (e.g. web_chat, email, sms).",
+    ),
+    direction: Optional[str] = typer.Option(
+        None,
+        "--direction",
+        help="Optional direction (e.g. inbound, outbound).",
+    ),
+    is_test: bool = typer.Option(
+        True,
+        "--is-test/--no-is-test",
+        help="Mark simulated conversations as test data.",
+    ),
+    is_historical: bool = typer.Option(
+        True,
+        "--is-historical/--no-is-historical",
+        help="Mark simulated conversations as historical.",
+    ),
+    remote_platform: Optional[str] = typer.Option(
+        None,
+        "--remote-platform",
+        help="Optional remote platform tag (for example: instagram).",
+    ),
+    created_at: Optional[str] = typer.Option(
+        None,
+        "--created-at",
+        help="Explicit timestamp (ISO-8601) for each simulation run.",
+    ),
+    created_at_from: Optional[str] = typer.Option(
+        None,
+        "--created-at-from",
+        help="Start timestamp (ISO-8601) for random timestamp simulation.",
+    ),
+    created_at_to: Optional[str] = typer.Option(
+        None,
+        "--created-at-to",
+        help="End timestamp (ISO-8601) for random timestamp simulation.",
+    ),
+    created_at_distribution: str = typer.Option(
+        "daily_peaks",
+        "--created-at-distribution",
+        help="Timestamp distribution: flat, daily_peaks, weekly_peaks.",
+    ),
+    label_id: Optional[str] = typer.Option(
+        None,
+        "--label-id",
+        help="Optional topic UUID.",
+    ),
+    sublabel_id: Optional[str] = typer.Option(
+        None,
+        "--sublabel-id",
+        help="Optional intent UUID.",
+    ),
+    metadata_json: Optional[str] = typer.Option(
+        None,
+        "--metadata-json",
+        help='Optional conversation metadata JSON object. Example: \'{"source":"cli"}\'',
+    ),
+    simulate_experiments: bool = typer.Option(
+        False,
+        "--simulate-experiments/--no-simulate-experiments",
+        help="Enable experiment traffic simulation fields.",
+    ),
+    experiment_id: Optional[str] = typer.Option(
+        None,
+        "--experiment-id",
+        help="Optional experiment UUID when simulating experiments.",
+    ),
+    traffic_rule_id: Optional[str] = typer.Option(
+        None,
+        "--traffic-rule-id",
+        help="Optional traffic rule UUID when simulating experiments.",
+    ),
+    populate_workforce_actions: bool = typer.Option(
+        False,
+        "--populate-workforce-actions/--no-populate-workforce-actions",
+        help="Emit workforce-style actions/metrics in simulation.",
+    ),
+    assigned_user_id: Optional[str] = typer.Option(
+        None,
+        "--assigned-user-id",
+        help="Optional assignee UUID for workforce simulation.",
+    ),
+    user_model: Optional[str] = typer.Option(
+        None,
+        "--user-model",
+        help="Optional simulated user model (for example: openai:gpt-5-nano).",
+    ),
+    user_temperature: Optional[float] = typer.Option(
+        None,
+        "--user-temperature",
+        help="Optional simulated user temperature (0.0-2.0).",
+    ),
+    seed: Optional[int] = typer.Option(
+        None,
+        "--seed",
+        help="Optional deterministic seed for user LLM timestamp sampling.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    continue_on_error: bool = typer.Option(
+        False,
+        "--continue-on-error/--no-continue-on-error",
+        help="Continue remaining simulations even if one fails.",
+    ),
+    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."),
+) -> None:
+    validate_uuid(agent_id, field_name="agent-id")
+    if experiment_id:
+        validate_uuid(experiment_id, field_name="experiment-id")
+    if traffic_rule_id:
+        validate_uuid(traffic_rule_id, field_name="traffic-rule-id")
+    if assigned_user_id:
+        validate_uuid(assigned_user_id, field_name="assigned-user-id")
+    if label_id:
+        validate_uuid(label_id, field_name="label-id")
+    if sublabel_id:
+        validate_uuid(sublabel_id, field_name="sublabel-id")
+    metadata = parse_json_dict(metadata_json, field_name="metadata-json")
+    if count < 1:
+        raise typer.BadParameter("count must be >= 1.")
+    if not (1 <= max_turns <= 10):
+        raise typer.BadParameter("max-turns must be between 1 and 10.")
+    if user_temperature is not None and not (0.0 <= user_temperature <= 2.0):
+        raise typer.BadParameter("user-temperature must be between 0.0 and 2.0.")
+    if conversation_type and conversation_type not in {"web_chat", "email", "sms", "phone_call"}:
+        raise typer.BadParameter(
+            "conversation-type must be one of: web_chat, email, sms, phone_call."
+        )
+    if direction and direction not in {"inbound", "outbound"}:
+        raise typer.BadParameter("direction must be one of: inbound, outbound.")
+    if bool(created_at_from) != bool(created_at_to):
+        raise typer.BadParameter(
+            "Provide both --created-at-from and --created-at-to, or neither."
+        )
+    if created_at and (created_at_from or created_at_to):
+        raise typer.BadParameter(
+            "Use either --created-at OR --created-at-from/--created-at-to."
+        )
+    if created_at_distribution not in {"flat", "daily_peaks", "weekly_peaks"}:
+        raise typer.BadParameter(
+            "created-at-distribution must be one of: flat, daily_peaks, weekly_peaks."
+        )
+
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="resolve runtime for simulation"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    successes: list[dict[str, Any]] = []
+    failures: list[dict[str, Any]] = []
+    for idx in range(count):
+        payload: dict[str, Any] = {
+            "max_turns": max_turns,
+            "is_test": is_test,
+            "is_historical": is_historical,
+            "created_at_distribution": created_at_distribution,
+            "simulate_experiments": simulate_experiments,
+            "populate_workforce_actions": populate_workforce_actions,
+        }
+        if agent_subtype:
+            payload["agent_subtype"] = agent_subtype
+        if conversation_type:
+            payload["conversation_type"] = conversation_type
+        if direction:
+            payload["direction"] = direction
+        if remote_platform:
+            payload["remote_platform"] = remote_platform
+        if created_at:
+            payload["created_at"] = created_at
+        if created_at_from and created_at_to:
+            payload["created_at_from"] = created_at_from
+            payload["created_at_to"] = created_at_to
+        if label_id:
+            payload["label_id"] = label_id
+        if sublabel_id:
+            payload["sublabel_id"] = sublabel_id
+        if metadata is not None:
+            payload["metadata"] = metadata
+        if experiment_id:
+            payload["experiment_id"] = experiment_id
+        if traffic_rule_id:
+            payload["traffic_rule_id"] = traffic_rule_id
+        if assigned_user_id:
+            payload["assigned_user_id"] = assigned_user_id
+        if seed is not None or user_model is not None or user_temperature is not None:
+            payload["user_llm"] = {}
+            if seed is not None:
+                payload["user_llm"]["seed"] = seed + idx
+            if user_model is not None:
+                payload["user_llm"]["model"] = user_model
+            if user_temperature is not None:
+                payload["user_llm"]["temperature"] = user_temperature
+
+        try:
+            result = simulate_agent_conversation(
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                agent_id=agent_id,
+                payload=payload,
+            )
+            successes.append(result)
+        except APIError as exc:
+            failure = {
+                "attempt": idx + 1,
+                "error": render_api_error(exc, action="simulate conversation"),
+            }
+            failures.append(failure)
+            if not continue_on_error:
+                if output_json:
+                    typer.echo(
+                        json.dumps(
+                            {
+                                "result": "failed",
+                                "success_count": len(successes),
+                                "failure_count": len(failures),
+                                "failures": failures,
+                            },
+                            indent=2,
+                        )
+                    )
+                else:
+                    typer.echo(failure["error"], err=True)
+                raise typer.Exit(code=1) from exc
+
+    summary = {
+        "result": "success" if not failures else "partial_success",
+        "agent_id": agent_id,
+        "count_requested": count,
+        "success_count": len(successes),
+        "failure_count": len(failures),
+        "is_test": is_test,
+        "is_historical": is_historical,
+        "simulate_experiments": simulate_experiments,
+        "populate_workforce_actions": populate_workforce_actions,
+        "created_at": created_at,
+        "created_at_from": created_at_from,
+        "created_at_to": created_at_to,
+        "created_at_distribution": created_at_distribution,
+        "simulations": successes if output_json else None,
+        "failures": failures if failures else None,
+    }
+
+    if output_json:
+        typer.echo(json.dumps(summary, indent=2, default=str))
+        return
+    conversation_ids = [
+        str(row.get("conversation_id"))
+        for row in successes
+        if isinstance(row, dict) and row.get("conversation_id")
+    ]
+    preview_ids = ",".join(conversation_ids[:5]) if conversation_ids else ""
+
+    typer.echo(
+        "result="
+        + summary["result"]
+        + " | "
+        + " | ".join(
+            [
+                f"agent_id={agent_id}",
+                f"requested={count}",
+                f"success={len(successes)}",
+                f"failed={len(failures)}",
+                f"is_test={is_test}",
+                f"is_historical={is_historical}",
+                f"conversation_ids={preview_ids}" if preview_ids else "conversation_ids=(none)",
+            ]
+        )
+    )

applied_cli/commands/spec.py

@@ -0,0 +1,238 @@
+import json
+import uuid
+from typing import Any, Optional
+
+import httpx
+import typer
+
+from applied_cli.commands.chat import (
+    _create_conversation,
+    _stream_v1_completion,
+    _verify_agent_scope,
+)
+from applied_cli.commands.rate import conversation as rate_conversation_command
+from applied_cli.error_reporting import render_api_error
+from applied_cli.http import APIError
+from applied_cli.spec_workflow import (
+    apply_agent_settings_from_spec,
+    create_agent_from_spec,
+    load_and_validate_spec,
+    upsert_spec_responses,
+)
+from applied_cli.runtime import resolve_runtime
+
+app = typer.Typer(help="Run spec-driven bootstrap/test/rate workflow.")
+
+
+def _run_test_case(
+    *,
+    client: httpx.Client,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str,
+    test_case: dict[str, Any],
+) -> dict[str, Any]:
+    channel = str(test_case["channel"])
+    conversation_id = _create_conversation(
+        client,
+        base_url=base_url,
+        agent_id=agent_id,
+        channel=channel,
+    )
+    transcript_results: list[dict[str, Any]] = []
+    for turn in test_case["turns"]:
+        transcript = [
+            {
+                "id": str(uuid.uuid4()),
+                "role": "user",
+                "content": turn,
+                "text": turn,
+                "format": "TEXT",
+                "entity": {"type": "user"},
+            }
+        ]
+        payload: dict[str, object] = {
+            "conversation_id": conversation_id,
+            "context": "EVALUATE",
+            "transcript": transcript,
+            "metadata": {
+                "source": "applied-cli-spec",
+                "isTest": True,
+                "channel": channel,
+                "test_name": test_case["name"],
+            },
+            "draft": False,
+        }
+        assistant_text = _stream_v1_completion(
+            client,
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+            agent_id=agent_id,
+            payload=payload,
+        )
+        transcript_results.append(
+            {"user": turn, "assistant": assistant_text, "assistant_chars": len(assistant_text)}
+        )
+    return {
+        "name": test_case["name"],
+        "channel": channel,
+        "conversation_id": conversation_id,
+        "turns": transcript_results,
+    }
+
+
+@app.command("run")
+def run(
+    spec: str = typer.Option(..., "--spec", help="Path to spec JSON."),
+    agent_id: Optional[str] = typer.Option(
+        None, "--agent-id", help="Reuse existing agent id instead of creating one."
+    ),
+    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="Validate and print plan 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:
+    if agent_id:
+        try:
+            uuid.UUID(agent_id)
+        except ValueError as exc:
+            raise typer.BadParameter("agent-id must be a valid UUID.") from exc
+    try:
+        validated_spec = load_and_validate_spec(spec)
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+    except ValueError as exc:
+        typer.echo(f"Spec validation failed: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="resolve runtime for spec run"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    typer.echo("Plan:")
+    typer.echo(f"- base_url: {resolved_base_url}")
+    typer.echo(f"- shop_id: {resolved_shop_id}")
+    typer.echo(f"- tests: {len(validated_spec['tests'])}")
+    typer.echo(f"- responses: {len(validated_spec['responses'])}")
+    typer.echo(f"- dry_run: {dry_run}")
+    if not yes and not typer.confirm("Continue?"):
+        raise typer.Exit(code=1)
+
+    working_agent_id = agent_id
+    try:
+        if working_agent_id:
+            apply_agent_settings_from_spec(
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                agent_id=working_agent_id,
+                spec=validated_spec,
+                dry_run=dry_run,
+            )
+            upsert_spec_responses(
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                agent_id=working_agent_id,
+                responses=validated_spec["responses"],
+                dry_run=dry_run,
+            )
+        else:
+            created = create_agent_from_spec(
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                spec=validated_spec,
+                dry_run=dry_run,
+            )
+            working_agent_id = str(created.get("id"))
+            upsert_spec_responses(
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                agent_id=working_agent_id,
+                responses=validated_spec["responses"],
+                dry_run=dry_run,
+            )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="bootstrap spec run"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    report: dict[str, Any] = {
+        "agent_id": working_agent_id,
+        "benchmark_name": validated_spec["benchmark_name"],
+        "tests": [],
+        "dry_run": dry_run,
+    }
+    if dry_run:
+        if output_json:
+            typer.echo(json.dumps(report, indent=2))
+        else:
+            typer.echo("Dry run complete. No tests executed.")
+        raise typer.Exit(code=0)
+
+    if not working_agent_id or working_agent_id == "dry-run":
+        typer.echo("Unable to resolve agent id for execution.", err=True)
+        raise typer.Exit(code=1)
+
+    with httpx.Client() as client:
+        try:
+            _verify_agent_scope(
+                client,
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                agent_id=working_agent_id,
+            )
+            for test_case in validated_spec["tests"]:
+                typer.echo(f"\nRunning test: {test_case['name']}")
+                result = _run_test_case(
+                    client=client,
+                    base_url=resolved_base_url,
+                    shop_id=resolved_shop_id,
+                    api_token=resolved_token,
+                    agent_id=working_agent_id,
+                    test_case=test_case,
+                )
+                report["tests"].append(result)
+        except APIError as exc:
+            typer.echo(render_api_error(exc, action="run spec tests"), err=True)
+            raise typer.Exit(code=1) from exc
+
+    for test_result, test_case in zip(report["tests"], validated_spec["tests"]):
+        try:
+            rate_conversation_command(
+                conversation_id=test_result["conversation_id"],
+                agent_id=working_agent_id,
+                benchmark_name=validated_spec["benchmark_name"],
+                auto=bool(test_case.get("auto_rate", True)),
+                include_references=bool(test_case.get("include_references", True)),
+                pass_status=test_case.get("pass_status"),
+                csat_score=test_case.get("csat_score"),
+                feedback=test_case.get("feedback"),
+                reference_score=test_case.get("reference_score"),
+                reference_notes=test_case.get("reference_notes"),
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                dry_run=False,
+                yes=True,
+            )
+        except Exception as exc:
+            typer.echo(
+                f"Rating failed for conversation {test_result['conversation_id']}: {exc}",
+                err=True,
+            )
+
+    if output_json:
+        typer.echo(json.dumps(report, indent=2, default=str))
+    else:
+        typer.echo("\nSpec run complete:")
+        typer.echo(f"- agent_id: {working_agent_id}")
+        typer.echo(f"- tests_executed: {len(report['tests'])}")

applied_cli/config.py

@@ -0,0 +1,50 @@
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+
+@dataclass
+class Credentials:
+    base_url: str
+    shop_id: str
+    api_token: str
+
+
+DEFAULT_BASE_URL = "https://api.appliedlabs.ai"
+ENDPOINT_ALIASES = {
+    "prod": "https://api.appliedlabs.ai",
+    "production": "https://api.appliedlabs.ai",
+    "api.appliedlabs.ai": "https://api.appliedlabs.ai",
+    "dev": "https://api.appliedlabs.dev",
+    "development": "https://api.appliedlabs.dev",
+    "api.appliedlabs.dev": "https://api.appliedlabs.dev",
+    "local": "http://localhost:8000",
+    "localhost": "http://localhost:8000",
+    "127.0.0.1": "http://127.0.0.1:8000",
+}
+
+
+def normalize_base_url(value: str) -> str:
+    raw = value.strip()
+    if not raw:
+        return ""
+    alias = ENDPOINT_ALIASES.get(raw.lower())
+    if alias:
+        return alias
+
+    with_scheme = raw
+    if not with_scheme.startswith(("http://", "https://")):
+        if with_scheme.startswith(("localhost", "127.0.0.1")):
+            with_scheme = f"http://{with_scheme}"
+        else:
+            with_scheme = f"https://{with_scheme}"
+
+    parsed = urlsplit(with_scheme)
+    if parsed.scheme and parsed.netloc:
+        return f"{parsed.scheme}://{parsed.netloc}".rstrip("/")
+    return with_scheme.rstrip("/")
+
+
+def mask_token(token: str) -> str:
+    if len(token) <= 10:
+        return token[:2] + "..." if len(token) > 2 else "***"
+    return f"{token[:4]}...{token[-4:]}"

applied_cli/error_reporting.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+from applied_cli.http import APIError
+
+
+def _extract_request_id(detail: Any) -> str | None:
+    if not isinstance(detail, dict):
+        return None
+    if isinstance(detail.get("request_id"), str):
+        return detail["request_id"]
+    error_payload = detail.get("error")
+    if isinstance(error_payload, dict) and isinstance(
+        error_payload.get("request_id"), str
+    ):
+        return error_payload["request_id"]
+    return None
+
+
+def render_api_error(exc: APIError, *, action: str) -> str:
+    lines: list[str] = []
+    lines.append(f"Error during {action}.")
+    if exc.code:
+        lines.append(f"- code: {exc.code}")
+    if exc.status_code is not None:
+        lines.append(f"- http_status: {exc.status_code}")
+    if exc.method and exc.url:
+        lines.append(f"- request: {exc.method} {exc.url}")
+    lines.append(f"- message: {exc}")
+    if exc.hint:
+        lines.append(f"- fix: {exc.hint}")
+    request_id = _extract_request_id(exc.detail)
+    if request_id:
+        lines.append(f"- request_id: {request_id}")
+    if exc.suggestions:
+        lines.append("- next_steps:")
+        for step in exc.suggestions:
+            lines.append(f"  - {step}")
+    return "\n".join(lines)