promptic-sdk 0.2.0__py3-none-any.whl

promptic_sdk/__init__.py

@@ -0,0 +1,97 @@
+"""Promptic Python SDK."""
+
+from promptic_sdk.client import AsyncPrompticClient, PrompticAPIError, PrompticClient
+from promptic_sdk.models import (
+    AgentEvaluation,
+    AgentEvaluationList,
+    AgentEvaluationStatus,
+    Component,
+    ComponentCreated,
+    ComponentList,
+    Dataset,
+    DatasetItem,
+    DatasetList,
+    DatasetWithItems,
+    DeployedPrompt,
+    Deployment,
+    DeploymentCreated,
+    Evaluator,
+    EvaluatorList,
+    EvaluatorType,
+    Experiment,
+    ExperimentList,
+    ExperimentStarted,
+    ExperimentStatus,
+    Hyperparameters,
+    Insight,
+    InsightResult,
+    InsightResultMeta,
+    Iteration,
+    IterationList,
+    IterationScore,
+    IterationWithScores,
+    ModelProvider,
+    Observation,
+    ObservationList,
+    OptimizerType,
+    Span,
+    SpanEvent,
+    TaskType,
+    Trace,
+    TraceList,
+    TraceListItem,
+    TracingStats,
+    Workspace,
+)
+from promptic_sdk.tracing import ai_component, dataset, init
+
+__version__ = "0.2.0"
+__all__ = [
+    "AsyncPrompticClient",
+    "PrompticClient",
+    "PrompticAPIError",
+    "ai_component",
+    "dataset",
+    "init",
+    # Models
+    "AgentEvaluation",
+    "AgentEvaluationList",
+    "AgentEvaluationStatus",
+    "Component",
+    "ComponentCreated",
+    "ComponentList",
+    "Dataset",
+    "DatasetItem",
+    "DatasetList",
+    "DatasetWithItems",
+    "DeployedPrompt",
+    "Deployment",
+    "DeploymentCreated",
+    "Evaluator",
+    "EvaluatorList",
+    "EvaluatorType",
+    "Experiment",
+    "ExperimentList",
+    "ExperimentStarted",
+    "ExperimentStatus",
+    "Hyperparameters",
+    "Insight",
+    "InsightResult",
+    "InsightResultMeta",
+    "Iteration",
+    "IterationList",
+    "IterationScore",
+    "IterationWithScores",
+    "ModelProvider",
+    "Observation",
+    "ObservationList",
+    "OptimizerType",
+    "Span",
+    "SpanEvent",
+    "TaskType",
+    "Trace",
+    "TraceList",
+    "TraceListItem",
+    "TracingStats",
+    "Workspace",
+]

promptic_sdk/cli/__init__.py

@@ -0,0 +1,28 @@
+"""Promptic CLI package."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from promptic_sdk.cli.config import load_config
+from promptic_sdk.client import PrompticClient
+
+_err_console = Console(stderr=True)
+
+
+def get_client() -> PrompticClient:
+    """Create an authenticated client from CLI config."""
+    config = load_config()
+    if not config:
+        _err_console.print(
+            "No configuration found. Run 'promptic login' or 'promptic configure'.",
+            style="red",
+        )
+        raise typer.Exit(1)
+    return PrompticClient(
+        api_key=config.api_key,
+        access_token=config.access_token,
+        workspace_id=config.workspace_id,
+        endpoint=config.endpoint,
+    )

promptic_sdk/cli/commands/annotations.py

@@ -0,0 +1,126 @@
+"""Annotations commands — create, list, and delete."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from promptic_sdk.cli import get_client
+from promptic_sdk.models import Annotation
+
+annotations_app = typer.Typer(help="Manage trace annotations.")
+console = Console()
+err_console = Console(stderr=True)
+
+
+@annotations_app.command("create")
+def create_annotation(
+    component_id: str = typer.Option(..., "--component", help="AI Component ID."),
+    run_id: str = typer.Option(..., "--run", help="Run ID."),
+    trace_db_id: str = typer.Option(..., "--trace", help="Trace DB ID."),
+    rating: Annotated[
+        str | None,
+        typer.Option(help="Rating (positive/negative)."),
+    ] = None,
+    comment: Annotated[str | None, typer.Option(help="Comment text.")] = None,
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Create or update an annotation for a trace in a run."""
+    with get_client() as client:
+        result = client.upsert_annotation(
+            component_id,
+            run_id,
+            trace_db_id,
+            rating=rating,
+            comment=comment,
+        )
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    console.print(f"[green]Annotation saved:[/green] {result['id']}")
+    if result.get("rating"):
+        console.print(f"  Rating: {result['rating']}")
+    if result.get("comment"):
+        console.print(f"  Comment: {result['comment']}")
+
+
+def _print_annotations_table(annotations: list[Annotation], title: str) -> None:
+    """Shared helper to print an annotations table."""
+    if not annotations:
+        console.print("No annotations found.", style="dim")
+        return
+
+    table = Table(title=title)
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Trace ID")
+    table.add_column("Rating")
+    table.add_column("Comment", max_width=40)
+    table.add_column("Created")
+
+    for ann in annotations:
+        table.add_row(
+            ann["id"],
+            ann["traceDbId"],
+            ann.get("rating") or "-",
+            (ann.get("comment") or "-")[:80],
+            ann["createdAt"],
+        )
+
+    console.print(table)
+
+
+@annotations_app.command("list")
+def list_annotations(
+    component_id: str = typer.Option(..., "--component", help="AI Component ID."),
+    run_id: Annotated[
+        str | None,
+        typer.Option("--run", help="Run ID (includes all annotations from the dataset)."),
+    ] = None,
+    dataset_id: Annotated[
+        str | None,
+        typer.Option("--dataset", help="Dataset ID (all annotations across runs)."),
+    ] = None,
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """List annotations for a run or dataset.
+
+    When using --run, returns all annotations across all runs of the same dataset.
+    When using --dataset, returns all annotations for traces in any run of that dataset.
+    """
+    if not run_id and not dataset_id:
+        err_console.print("[red]Provide --run or --dataset.[/red]")
+        raise typer.Exit(1)
+
+    with get_client() as client:
+        if dataset_id:
+            result = client.list_dataset_annotations(component_id, dataset_id)
+        else:
+            result = client.list_annotations(component_id, run_id)  # type: ignore[arg-type]
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    annotations = result["data"]
+    _print_annotations_table(annotations, f"Annotations ({len(annotations)})")
+
+
+@annotations_app.command("delete")
+def delete_annotation(
+    annotation_id: str = typer.Argument(help="Annotation ID."),
+    component_id: str = typer.Option(..., "--component", help="AI Component ID."),
+    run_id: str = typer.Option(..., "--run", help="Run ID."),
+) -> None:
+    """Delete an annotation."""
+    with get_client() as client:
+        client.delete_annotation(component_id, run_id, annotation_id)
+    console.print("[green]Annotation deleted.[/green]")

promptic_sdk/cli/commands/components.py

@@ -0,0 +1,106 @@
+"""AI component commands."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from promptic_sdk.cli import get_client
+
+components_app = typer.Typer(help="Manage AI components.")
+console = Console()
+
+
+@components_app.command("list")
+def list_components(
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """List all AI components in the workspace."""
+    with get_client() as client:
+        result = client.list_components()
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    items = result["data"]
+    if not items:
+        console.print("No components found.", style="dim")
+        return
+
+    table = Table(title=f"AI Components ({len(items)})")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Name")
+    table.add_column("Description")
+    table.add_column("Created")
+
+    for c in items:
+        table.add_row(
+            c["id"],
+            c["name"],
+            c["description"] or "-",
+            c["createdAt"],
+        )
+
+    console.print(table)
+
+
+@components_app.command("create")
+def create_component(
+    name: str = typer.Argument(help="Component name."),
+    description: str | None = typer.Option(
+        None, "--description", "-d", help="Optional description."
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Create a new AI component."""
+    with get_client() as client:
+        result = client.create_component(name, description=description)
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    console.print(f"[green]Component created:[/green] {result['id']}")
+
+
+@components_app.command("get")
+def get_component(
+    component_id: str = typer.Argument(help="Component ID."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Get details of an AI component."""
+    with get_client() as client:
+        result = client.get_component(component_id)
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    console.print(f"\n[bold]Component:[/bold] {result['name']}")
+    console.print(f"  ID:          {result['id']}")
+    if result["description"]:
+        console.print(f"  Description: {result['description']}")
+    console.print(f"  Created:     {result['createdAt']}")
+
+
+@components_app.command("delete")
+def delete_component(
+    component_id: str = typer.Argument(help="Component ID."),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation."),
+) -> None:
+    """Delete an AI component."""
+    if not force:
+        typer.confirm(f"Delete component {component_id}?", abort=True)
+
+    with get_client() as client:
+        client.delete_component(component_id)
+
+    console.print("[green]Component deleted.[/green]")

promptic_sdk/cli/commands/configure.py

@@ -0,0 +1,25 @@
+"""Configure command — save API key and endpoint."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from promptic_sdk.cli.config import get_config_path, save_config
+
+console = Console()
+
+
+def configure(
+    api_key: str = typer.Option(
+        ..., prompt="Promptic API key", help="Your Promptic API key (pk_...)."
+    ),
+    endpoint: str = typer.Option(
+        "https://promptic.eu",
+        prompt="Promptic endpoint",
+        help="Promptic platform URL.",
+    ),
+) -> None:
+    """Save Promptic API key and endpoint to ~/.promptic/config.toml."""
+    save_config(api_key, endpoint)
+    console.print(f"Configuration saved to {get_config_path()}", style="green")

promptic_sdk/cli/commands/datasets.py

@@ -0,0 +1,134 @@
+"""Datasets commands — create, list, and get."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from promptic_sdk.cli import get_client
+
+datasets_app = typer.Typer(help="Manage agent datasets.")
+console = Console()
+err_console = Console(stderr=True)
+
+
+@datasets_app.command("create")
+def create_dataset(
+    component_id: str = typer.Option(..., "--component", help="AI Component ID."),
+    name: str = typer.Option(..., "--name", help="Dataset name."),
+    description: Annotated[str | None, typer.Option(help="Dataset description.")] = None,
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Create a new dataset from traces."""
+    with get_client() as client:
+        # First create the dataset
+        result = client.create_dataset(
+            component_id,
+            name,
+            description=description,
+        )
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    console.print(f"[green]Dataset created:[/green] {result['name']}")
+    console.print(f"  ID: {result['id']}")
+    console.print(f"  Items: {result['itemCount']}")
+    console.print()
+    console.print(
+        "[dim]Tip: Add traces via SDK with "
+        "promptic_sdk.ai_component('...', dataset='...')"
+        " or use the API.[/dim]"
+    )
+
+
+@datasets_app.command("list")
+def list_datasets(
+    component_id: str = typer.Option(..., "--component", help="AI Component ID."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """List datasets for an AI component."""
+    with get_client() as client:
+        result = client.list_datasets(component_id)
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    datasets = result["data"]
+    if not datasets:
+        console.print("No datasets found.", style="dim")
+        return
+
+    table = Table(title=f"Datasets ({len(datasets)})")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Name")
+    table.add_column("Items", justify="right")
+    table.add_column("Created")
+
+    for ds in datasets:
+        table.add_row(
+            ds["id"],
+            ds["name"],
+            str(ds["itemCount"]),
+            ds["createdAt"],
+        )
+
+    console.print(table)
+
+
+@datasets_app.command("get")
+def get_dataset(
+    dataset_id: str = typer.Argument(help="Dataset ID."),
+    component_id: str = typer.Option(..., "--component", help="AI Component ID."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Get a dataset with its items."""
+    with get_client() as client:
+        result = client.get_dataset(component_id, dataset_id)
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    console.print(f"\n[bold]Dataset:[/bold] {result['name']}")
+    console.print(f"[bold]ID:[/bold] {result['id']}")
+    console.print(f"[bold]Items:[/bold] {result['itemCount']}")
+    if result.get("description"):
+        console.print(f"[bold]Description:[/bold] {result['description']}")
+
+    items = result.get("items", [])
+    if items:
+        console.print(f"\n[bold]Items ({len(items)}):[/bold]")
+        item_table = Table()
+        item_table.add_column("Trace ID", style="cyan")
+        item_table.add_column("Input", max_width=40)
+        item_table.add_column("Output", max_width=40)
+
+        for item in items:
+            item_table.add_row(
+                item["traceDbId"],
+                (item["input"] or "-")[:80],
+                (item["output"] or "-")[:80],
+            )
+        console.print(item_table)
+
+
+@datasets_app.command("delete")
+def delete_dataset(
+    dataset_id: str = typer.Argument(help="Dataset ID."),
+    component_id: str = typer.Option(..., "--component", help="AI Component ID."),
+) -> None:
+    """Delete a dataset."""
+    with get_client() as client:
+        client.delete_dataset(component_id, dataset_id)
+    console.print("[green]Dataset deleted.[/green]")

promptic_sdk/cli/commands/deployments.py

@@ -0,0 +1,103 @@
+"""Deployment commands."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+
+from promptic_sdk.cli import get_client
+
+deployments_app = typer.Typer(help="Manage deployments.")
+console = Console()
+
+
+@deployments_app.command("status")
+def deployment_status(
+    component_id: str = typer.Argument(help="Component ID."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show current deployment for a component."""
+    with get_client() as client:
+        result = client.get_deployment(component_id)
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    if not result:
+        console.print("No deployment active.", style="dim")
+        return
+
+    exp = result["experiment"]
+    console.print("\n[bold]Active Deployment[/bold]")
+    console.print(f"  Component:   {result['aiComponentId']}")
+    console.print(f"  Experiment:  {result['experimentId']}")
+    console.print(f"  Exp. Name:   {exp['name'] or '-'}")
+    console.print(f"  Model:       {exp['targetModel']}")
+    console.print(f"  Status:      {exp['experimentStatus']}")
+
+
+@deployments_app.command("deploy")
+def deploy(
+    component_id: str = typer.Argument(help="Component ID."),
+    experiment_id: str = typer.Argument(help="Experiment ID to deploy."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Deploy an experiment to a component."""
+    with get_client() as client:
+        result = client.deploy(component_id, experiment_id)
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    console.print(
+        f"[green]Deployed[/green] experiment {result['experimentId']} "
+        f"to component {result['aiComponentId']}"
+    )
+
+
+@deployments_app.command("prompt")
+def deployment_prompt(
+    component_id: str = typer.Argument(help="Component ID."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show the deployed prompt for a component."""
+    with get_client() as client:
+        result = client.get_deployed_prompt(component_id)
+
+    if output_json:
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+    if not result:
+        console.print("No deployment active.", style="dim")
+        return
+
+    console.print(f"\n[bold]{result['componentName'] or '-'}[/bold]")
+    console.print(f"  Model:       {result['model']}")
+    console.print(f"  Score:       {result['score']}")
+    console.print(f"  Experiment:  {result['experimentId']}")
+    console.print("\n[bold]Prompt:[/bold]\n")
+    console.print(result["prompt"])
+
+
+@deployments_app.command("undeploy")
+def undeploy(
+    component_id: str = typer.Argument(help="Component ID."),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation."),
+) -> None:
+    """Remove deployment from a component."""
+    if not force:
+        typer.confirm(f"Undeploy from component {component_id}?", abort=True)
+
+    with get_client() as client:
+        client.undeploy(component_id)
+
+    console.print("[green]Deployment removed.[/green]")