langfuse-agent-cli 0.3.0__py3-none-any.whl

langfuse_cli/client.py

@@ -0,0 +1,196 @@
+"""REST API client for Langfuse."""
+from __future__ import annotations
+
+from typing import Any, Dict, Iterator, List, Optional
+from urllib.parse import quote
+
+import requests
+from requests.auth import HTTPBasicAuth
+
+from langfuse_cli import __version__
+from langfuse_cli.config import ProfileConfig
+
+
+class LangfuseAPIError(Exception):
+    def __init__(self, message: str, status_code: Optional[int] = None, response_body: Optional[str] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class LangfuseClient:
+    """Client for Langfuse Public REST API v2."""
+
+    def __init__(self, profile: ProfileConfig, timeout: float = 15.0):
+        self.profile = profile
+        self.host = profile.host.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({
+            "User-Agent": f"langfuse-agent-cli/{__version__}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        })
+        if profile.public_key and profile.secret_key:
+            self.session.auth = HTTPBasicAuth(profile.public_key, profile.secret_key)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.host}{path}"
+        try:
+            resp = self.session.request(
+                method=method,
+                url=url,
+                params=params,
+                json=data if data else None,
+                timeout=self.timeout,
+                allow_redirects=method == "GET",  # requests would replay a redirected POST as a GET
+            )
+        except requests.exceptions.ConnectionError as e:
+            raise LangfuseAPIError(f"Connection failed to {self.host}: {e}") from e
+        except requests.exceptions.Timeout as e:
+            raise LangfuseAPIError(f"Request timed out connecting to {self.host} ({self.timeout}s)") from e
+        except requests.exceptions.RequestException as e:  # e.g. a host without http(s)://
+            raise LangfuseAPIError(f"Request to {url} failed: {e}") from e
+
+        if resp.is_redirect:  # only writes get here; a 3xx also counts as resp.ok
+            location = resp.headers.get("Location")
+            raise LangfuseAPIError(f"{method} {path} was redirected to {location}; set the host to the final URL",
+                                   status_code=resp.status_code)
+        if not resp.ok:
+            try:
+                message = resp.json().get("message")
+            except (ValueError, AttributeError):
+                message = None
+            if message:
+                error_msg = f"HTTP {resp.status_code}: {message}"
+            elif "html" in resp.headers.get("Content-Type", ""):
+                error_msg = f"HTTP {resp.status_code} on {path}"  # framework error pages carry no detail
+            else:
+                error_msg = f"HTTP {resp.status_code} on {path}: {resp.text[:200]}"
+            raise LangfuseAPIError(error_msg, status_code=resp.status_code, response_body=resp.text)
+
+        try:
+            return resp.json()  # every endpoint lf calls answers 2xx with a JSON body
+        except ValueError as e:
+            kind = resp.headers.get("Content-Type") or "no content type"
+            raise LangfuseAPIError(f"HTTP {resp.status_code} on {path} is not JSON ({kind}); is a login page or proxy "
+                                   "answering instead of Langfuse?", status_code=resp.status_code,
+                                   response_body=resp.text) from e
+
+    # 1. System Health
+    def health(self) -> Dict[str, Any]:
+        return self._request("GET", "/api/public/health")
+
+    def get_project(self) -> Dict[str, Any]:
+        """Project the API key belongs to; a cheap check that the keys are valid."""
+        return self._request("GET", "/api/public/projects")
+
+    # 2. Prompts API
+    def list_prompts(
+        self,
+        page: int = 1,
+        limit: int = 50,
+        tag: Optional[str] = None,
+        name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params: Dict[str, Any] = {"page": page, "limit": limit}
+        if tag:
+            params["tag"] = tag
+        if name:
+            params["name"] = name
+        return self._request("GET", "/api/public/v2/prompts", params=params)
+
+    def get_prompt(
+        self,
+        name: str,
+        version: Optional[int] = None,
+        label: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params: Dict[str, Any] = {}
+        if version is not None:
+            params["version"] = version
+        if label:
+            params["label"] = label
+        # Prompt names may contain "/" (folders); the API expects them encoded as one path segment.
+        return self._request("GET", f"/api/public/v2/prompts/{quote(name, safe='')}", params=params)
+
+    def create_prompt(
+        self,
+        name: str,
+        prompt_content: Any,
+        prompt_type: str = "text",
+        config: Optional[Dict[str, Any]] = None,
+        labels: Optional[List[str]] = None,
+        tags: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "name": name,
+            "type": prompt_type,
+            "prompt": prompt_content,
+        }
+        if config:
+            body["config"] = config
+        if labels:
+            body["labels"] = labels
+        if tags:
+            body["tags"] = tags
+        return self._request("POST", "/api/public/v2/prompts", data=body)
+
+    # 3. Observations API v2: the v4 read path for traces, sessions and errors
+    def list_observations(self, **params: Any) -> Dict[str, Any]:
+        query = {k: str(v).lower() if isinstance(v, bool) else v for k, v in params.items() if v is not None}
+        return self._request("GET", "/api/public/v2/observations", params=query)
+
+    def iter_observations(self, params: Dict[str, Any], max_items: Optional[int] = None) -> Iterator[Dict[str, Any]]:
+        """Yield observations across cursor pages, stopping after max_items when given."""
+        remaining = max_items
+        cursor = None
+        while remaining is None or remaining > 0:
+            page = self.list_observations(
+                **params, limit=1000 if remaining is None else min(1000, remaining), cursor=cursor
+            )
+            data = page.get("data", [])
+            if remaining is not None:
+                data = data[:remaining]
+                remaining -= len(data)
+            yield from data
+            cursor = (page.get("meta") or {}).get("cursor")
+            if not cursor:
+                return
+
+    # 4. Datasets API
+    def list_datasets(self, page: int = 1, limit: int = 50) -> Dict[str, Any]:
+        return self._request("GET", "/api/public/v2/datasets", params={"page": page, "limit": limit})
+
+    def get_dataset(self, name: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/public/v2/datasets/{quote(name, safe='')}")
+
+    def list_dataset_items(self, dataset_name: str, page: int = 1, limit: int = 50) -> Dict[str, Any]:
+        params = {"datasetName": dataset_name, "page": page, "limit": limit}
+        return self._request("GET", "/api/public/dataset-items", params=params)
+
+    # 5. Scores API
+    def create_score(
+        self,
+        trace_id: str,
+        name: str,
+        value: float,
+        comment: Optional[str] = None,
+        observation_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "traceId": trace_id,
+            "name": name,
+            "value": value,
+        }
+        if comment:
+            body["comment"] = comment
+        if observation_id:
+            body["observationId"] = observation_id
+        return self._request("POST", "/api/public/scores", data=body)

langfuse_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Commands package for Langfuse CLI."""

langfuse_cli/commands/auth.py

@@ -0,0 +1,93 @@
+"""Authentication and profile management commands."""
+from __future__ import annotations
+
+import argparse
+import getpass
+import sys
+from typing import Optional
+
+from langfuse_cli.client import LangfuseAPIError, LangfuseClient
+from langfuse_cli.config import ConfigManager, resolve_from_args
+
+
+def login(cfg: ConfigManager, profile_name: str, host: str, public_key: Optional[str], secret_key: Optional[str],
+          set_default: bool) -> int:
+    """Prompt for missing keys, save the profile, then verify the keys against the server."""
+    if not public_key:
+        public_key = input("Enter Langfuse Public Key (pk-lf-...): ").strip()
+    if not secret_key:
+        secret_key = getpass.getpass("Enter Langfuse Secret Key (sk-lf-...): ").strip()
+    if not public_key or not secret_key:  # an empty answer must never replace saved keys
+        print("✗ Both keys are needed; nothing was saved.", file=sys.stderr)
+        return 1
+
+    cfg.save_profile(
+        name=profile_name,
+        host=host,
+        public_key=public_key,
+        secret_key=secret_key,
+        set_default=set_default,
+    )
+    print(f"✓ Profile '{profile_name}' saved successfully ({host}).")
+
+    client = LangfuseClient(cfg.resolve_profile(name=profile_name))
+    try:
+        projects = client.get_project().get("data") or []
+    except LangfuseAPIError as e:
+        print(f"⚠ Profile saved, but the keys could not be verified: {e}", file=sys.stderr)
+        return 1
+    print(f"✓ Keys verified for project: {', '.join(p.get('name', '?') for p in projects) or '(none)'}")
+    return 0
+
+
+def handle_auth(args: argparse.Namespace) -> int:
+    cfg = ConfigManager()
+    subaction = getattr(args, "auth_action", None)
+
+    if subaction == "login":
+        return login(cfg, args.profile_name or "default", args.host or "https://cloud.langfuse.com",
+                     args.public_key, args.secret_key, args.default)
+
+    elif subaction == "switch":
+        target = args.target_profile
+        profiles = cfg.list_profiles()
+        if target not in profiles:
+            print(f"Error: Profile '{target}' not found. Available profiles: {list(profiles.keys())}", file=sys.stderr)
+            return 1
+        cfg.set_current_profile(target)
+        print(f"✓ Active profile switched to '{target}'.")
+        return 0
+
+    elif subaction == "list":
+        current = cfg.get_current_profile_name()
+        profiles = cfg.list_profiles()
+        if not profiles:
+            print("No profiles configured yet. Run 'lf auth login' to add one.")
+            return 0
+        print("Configured Profiles:")
+        for name, p in profiles.items():
+            active_marker = "* " if name == current else "  "
+            print(f"{active_marker}{name}:")
+            print(f"    Host: {p.host}")
+            print(f"    Public Key: {p.masked_public_key()}")
+            print(f"    Secret Key: {p.masked_secret_key()}")
+        return 0
+
+    # Default: status
+    prof = resolve_from_args(args)
+    print(f"Source: {prof.source}" + (f" ({prof.name})" if prof.source == "profile" else ""))
+    print(f"Host: {prof.host}")
+    print(f"Public Key: {prof.masked_public_key()}")
+    print(f"Secret Key: {prof.masked_secret_key()}")
+
+    if not prof.is_complete():
+        print("⚠ Incomplete credentials. Configure with 'lf auth login'.")
+        return 1
+
+    try:
+        projects = LangfuseClient(prof).get_project().get("data") or []
+    except LangfuseAPIError as e:
+        print(f"✗ {e}")
+        return 1
+    print(f"✓ Keys valid for project: {', '.join(p.get('name', '?') for p in projects) or '(none)'}")
+    return 0

langfuse_cli/commands/dataset.py

@@ -0,0 +1,37 @@
+"""Dataset commands for Langfuse."""
+from __future__ import annotations
+
+import argparse
+
+from langfuse_cli.client import LangfuseClient
+from langfuse_cli.config import resolve_from_args
+from langfuse_cli.formatters.agent import print_json
+
+
+def handle_dataset(args: argparse.Namespace) -> int:
+    client = LangfuseClient(resolve_from_args(args))
+
+    if args.dataset_action == "list":
+        datasets = client.list_datasets().get("data", [])
+        if args.output == "json":
+            print_json(args, datasets)
+        elif not datasets:
+            print("No datasets found.")
+        else:
+            print(f"Datasets ({len(datasets)}):")
+            for d in datasets:
+                print(f"  - {d.get('name')}: {d.get('description') or '(no description)'}")
+        return 0
+
+    # get: the v2 API serves a dataset and its items separately; show the first page of items
+    dataset = client.get_dataset(args.name)
+    dataset["items"] = client.list_dataset_items(args.name).get("data", [])
+    if args.output == "json":
+        print_json(args, dataset)
+    else:
+        print(f"Dataset: {dataset.get('name')}")
+        print(f"Description: {dataset.get('description')}")
+        print(f"Items: {len(dataset['items'])} (first page)")
+        for i, item in enumerate(dataset["items"][:5], 1):
+            print(f"  Item {i}: input={item.get('input')} expected={item.get('expectedOutput')}")
+    return 0

langfuse_cli/commands/doctor.py

@@ -0,0 +1,90 @@
+"""Diagnostic command for Langfuse CLI, auth, and skills."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from langfuse_cli import __version__
+from langfuse_cli.client import LangfuseAPIError, LangfuseClient
+from langfuse_cli.config import ConfigManager, resolve_from_args
+
+SKILL_NAME = "langfuse-agent-cli"
+# The skill as of this CLI's release tag, so an installed skill never documents flags the CLI lacks
+SKILL_SOURCE = f"https://github.com/tns15june/langfuse-agent-cli/tree/v{__version__}/skills/{SKILL_NAME}"
+KNOWN_SKILL_TARGETS = [
+    ("Claude Code", Path.home() / ".claude" / "skills"),
+    ("Antigravity", Path.home() / ".gemini" / "config" / "skills"),
+    ("Universal Agents", Path.home() / ".agents" / "skills"),
+    ("Cursor", Path.home() / ".cursor" / "skills"),
+    ("OpenCode", Path.home() / ".config" / "opencode" / "skills"),
+]
+# `npx skills add` installs into the current project unless given -g
+PROJECT_SKILL_DIRS = [Path(".claude") / "skills", Path(".agents") / "skills"]
+
+
+def _check_server(client: LangfuseClient) -> bool:
+    try:
+        health = client.health()
+        print(f"  ✓ Connectivity: OK (server version {health.get('version', 'unknown')})")
+        projects = client.get_project().get("data") or []
+        print(f"  ✓ API Authorization: Valid (project: {', '.join(p.get('name', '?') for p in projects)})")
+    except LangfuseAPIError as e:
+        hint = {401: " (verify public/secret keys)", 403: " (check project access)"}.get(e.status_code or 0, "")
+        print(f"  ✗ {e}{hint}")
+        return False
+    try:
+        client.list_observations(limit=1, fields="core")
+        print("  ✓ Observations API v2: available")
+    except LangfuseAPIError as e:
+        if e.status_code == 404:
+            print("  ✗ This server has no /api/public/v2/observations; trace commands need Langfuse v4")
+        else:
+            print(f"  ✗ Observations API v2: {e}")
+        return False
+    return True
+
+
+def handle_doctor(args: argparse.Namespace) -> int:
+    cfg = ConfigManager()
+    prof = resolve_from_args(args)
+
+    print("\nLangfuse Agent CLI System Diagnostics")
+    print("=" * 45)
+
+    print("\n1. Build & Runtime")
+    print(f"  CLI Version: {__version__}")
+    print(f"  Python Version: {sys.version.split()[0]}")
+    print(f"  Config File: {cfg.config_path} ({'exists' if cfg.config_path.exists() else 'not created yet'})")
+
+    print("\n2. Resolved Authentication")
+    print(f"  Source: {prof.source}" + (f" ({prof.name})" if prof.source == "profile" else ""))
+    print(f"  Host Endpoint: {prof.host}")
+    print(f"  Public Key: {prof.masked_public_key()}")
+    print(f"  Secret Key: {prof.masked_secret_key()}")
+    if not prof.is_complete():
+        print("  ✗ Incomplete credentials. Run 'lf auth login' or set LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY.")
+        auth_ok = False
+    else:
+        auth_ok = _check_server(LangfuseClient(prof))
+
+    print("\n3. Agent Skill")
+    skills_found = 0
+    project_targets = [(f"Project {d.parent}", Path.cwd() / d) for d in PROJECT_SKILL_DIRS]
+    for name, target_dir in KNOWN_SKILL_TARGETS + project_targets:
+        skill_path = target_dir / SKILL_NAME
+        if skill_path.exists():
+            skills_found += 1
+            print(f"  ✓ {name:<18} Installed at {skill_path}")
+        else:
+            print(f"  – {name:<18} Not found in {target_dir}")
+
+    print("\nSummary:")
+    if not auth_ok:
+        print("  ⚠ Fix the authentication or server problem above.")
+        return 1
+    if skills_found:
+        print("  ✓ All checks passed.")
+    else:
+        print(f"  ℹ Skill not installed. Run 'lf setup', or: npx skills@1 add {SKILL_SOURCE} -g")
+    return 0

langfuse_cli/commands/help_map.py

@@ -0,0 +1,167 @@
+"""Progressive disclosure and machine-readable command schemas for AI agents."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Dict
+
+# One entry per leaf command of the parser; tests/test_help.py fails on a missing or extra command
+# and on a catalog option the parser does not have.
+COMMAND_CATALOG: Dict[str, Dict[str, Any]] = {
+    "auth login": {
+        "desc": "Save a connection profile and verify its keys",
+        "write": True,
+        "opts": ["--profile-name <name>", "--host <url>", "--public-key <pk>", "--secret-key <sk>", "--default"],
+        "rules": [
+            "Prompts for missing keys (the secret is read hidden); ask the user to run it.",
+            "Stores ~/.config/langfuse/profiles.json with mode 0600.",
+        ],
+    },
+    "auth switch": {
+        "desc": "Make a saved profile the current one",
+        "write": True,
+        "opts": ["<profile>"],
+        "rules": [],
+    },
+    "auth list": {
+        "desc": "List saved profiles with masked keys",
+        "write": False,
+        "opts": [],
+        "rules": ["Never prints full secret keys."],
+    },
+    "auth status": {
+        "desc": "Show where credentials come from and check the keys",
+        "write": False,
+        "opts": ["--profile <name>", "--env-file <path>"],
+        "rules": [],
+    },
+    "doctor": {
+        "desc": "Check credentials, server version, the v2 observations API and the agent skill",
+        "write": False,
+        "opts": ["--profile <name>", "--env-file <path>"],
+        "rules": ["Exit code 1 means an authentication or server problem."],
+    },
+    "setup": {
+        "desc": "Log in, install the agent skill and run doctor",
+        "write": True,
+        "opts": ["--yes", "--host <url>"],
+        "rules": [
+            "Asks for the host and keys when a saved profile is missing or rejected, and before installing the "
+            "skill, unless --yes is given or stdin is not a terminal; agents run it with --yes.",
+            "Installs the skill version that matches the CLI; run it again after upgrading.",
+            "Exit code 1 means an authentication or server problem, or that the skill was not installed.",
+        ],
+    },
+    "prompt list": {
+        "desc": "List prompts with their versions, labels and tags",
+        "write": False,
+        "opts": ["--tag <tag>", "--limit <n>", "--output <json|text>", "--compact"],
+        "rules": [],
+    },
+    "prompt get": {
+        "desc": "Fetch a prompt, optionally filling its {{variables}}",
+        "write": False,
+        "opts": ["<name>", "--version <n>", "--label <label>", "--vars '<json>'", "--output <json|text>"],
+        "rules": [
+            "Without --version or --label the server returns the 'production' label.",
+            "Folder names like 'support/greeter' work as-is.",
+        ],
+    },
+    "prompt push": {
+        "desc": "Create a new prompt version",
+        "write": True,
+        "opts": ["<name>", "--text '<prompt>'", "--file <path>", "--type <text|chat>", "--labels <a,b>",
+                 "--tags <a,b>"],
+        "rules": ["Read the current version with 'prompt get' first and tell the user what will change."],
+    },
+    "trace list": {
+        "desc": "List traces newest first; --status error lists failing traces with their errors",
+        "write": False,
+        "opts": ["--status <all|error>", "--session-id <id>", "--user-id <id>", "--from-ts <iso>", "--to-ts <iso>",
+                 "--limit <n>", "--compact", "--agent-fields <paths>", "--output-summary"],
+        "rules": ["--limit counts traces, also with --status error."],
+    },
+    "trace get": {
+        "desc": "All observations of one trace; --timeline renders them as a tree",
+        "write": False,
+        "opts": ["<trace_id>", "--timeline", "--io", "--compact", "--agent-fields <paths>", "--output-summary"],
+        "rules": [
+            "Inputs and outputs are left out unless --io is given; they are often large.",
+            "Metadata, prompt links and trace tags are not fetched.",
+        ],
+    },
+    "trace session": {
+        "desc": "Traces of one session, oldest first (the newest 1000)",
+        "write": False,
+        "opts": ["<session_id>", "--compact", "--agent-fields <paths>", "--output-summary"],
+        "rules": [],
+    },
+    "dataset list": {
+        "desc": "List datasets",
+        "write": False,
+        "opts": ["--output <json|text>"],
+        "rules": [],
+    },
+    "dataset get": {
+        "desc": "A dataset with the first page of its items",
+        "write": False,
+        "opts": ["<name>", "--compact", "--output-summary"],
+        "rules": [],
+    },
+    "score create": {
+        "desc": "Record a numeric score on a trace or one of its observations",
+        "write": True,
+        "opts": ["--trace-id <id>", "--name <name>", "--value <number>", "--comment <text>", "--observation-id <id>"],
+        "rules": [],
+    },
+    "help-map": {
+        "desc": "This command map (* marks commands that write)",
+        "write": False,
+        "opts": [],
+        "rules": [],
+    },
+    "help": {
+        "desc": "Describe one command as JSON: options and rules",
+        "write": False,
+        "opts": ["<command...>"],
+        "rules": ["Give the exact command, e.g. lf help \"trace get\"."],
+    },
+}
+
+
+def handle_help_map(args: argparse.Namespace) -> int:
+    print("Langfuse Agent CLI Command Map (* indicates state mutation):")
+    for cmd, info in sorted(COMMAND_CATALOG.items()):
+        write_flag = "* " if info["write"] else "  "
+        print(f"{write_flag}lf {cmd:<18} — {info['desc']}")
+    return 0
+
+
+def handle_help_describe(args: argparse.Namespace) -> int:
+    words = list(args.target_command)
+    if words[:1] == ["describe"]:  # accept the `help describe "<cmd>"` spelling too
+        words = words[1:]
+    query = " ".join(words).strip()
+    info = COMMAND_CATALOG.get(query)
+    if info is None:
+        suggestions = [cmd for cmd in COMMAND_CATALOG if query and query in cmd]
+        hint = f" Did you mean: {', '.join(suggestions)}?" if suggestions else ""
+        print(f"Unknown command: '{query}'.{hint} Run 'lf help-map' to view all commands.", file=sys.stderr)
+        return 1
+
+    payload = {"cmd": f"lf {query}", "desc": info["desc"], "write": info["write"], "opts": info["opts"],
+               "rules": info["rules"]}
+    if args.output == "json":
+        print(json.dumps(payload, indent=2))
+    else:
+        print(f"Command: lf {query}")
+        print(f"Description: {info['desc']} (Mutation: {info['write']})")
+        print("Options:")
+        for opt in info["opts"]:
+            print(f"  {opt}")
+        if info["rules"]:
+            print("Rules:")
+            for r in info["rules"]:
+                print(f"  • {r}")
+    return 0