@cephalization/phoenix-insight 0.1.0

package/src/progress.ts

@@ -0,0 +1,239 @@
+/**
+ * Progress indicators for Phoenix Insight CLI
+ */
+import ora, { type Ora } from "ora";
+
+/**
+ * Progress indicator for snapshot operations
+ */
+export class SnapshotProgress {
+  private spinner: Ora | null = null;
+  private enabled: boolean;
+  private currentPhase: string | null = null;
+  private totalSteps = 6;
+  private currentStep = 0;
+
+  constructor(enabled: boolean = true) {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Start the progress indicator
+   */
+  start(message: string = "Creating Phoenix data snapshot") {
+    if (!this.enabled) return;
+
+    this.currentStep = 0;
+    this.spinner = ora({
+      text: message,
+      spinner: "dots",
+      color: "blue",
+    }).start();
+  }
+
+  /**
+   * Update progress with a new phase
+   */
+  update(phase: string, detail?: string) {
+    if (!this.enabled || !this.spinner) return;
+
+    this.currentStep++;
+    this.currentPhase = phase;
+
+    const progress = Math.round((this.currentStep / this.totalSteps) * 100);
+    const progressBar = this.createProgressBar(progress);
+
+    const message = detail
+      ? `${progressBar} ${phase}: ${detail}`
+      : `${progressBar} ${phase}`;
+
+    this.spinner.text = message;
+  }
+
+  /**
+   * Complete a phase successfully
+   */
+  succeed(message?: string) {
+    if (!this.enabled || !this.spinner) return;
+
+    const finalMessage =
+      message || `✓ ${this.currentPhase || "Snapshot"} complete`;
+    this.spinner.succeed(finalMessage);
+    this.spinner = null;
+  }
+
+  /**
+   * Fail with an error
+   */
+  fail(message?: string) {
+    if (!this.enabled || !this.spinner) return;
+
+    const finalMessage =
+      message || `✗ ${this.currentPhase || "Snapshot"} failed`;
+    this.spinner.fail(finalMessage);
+    this.spinner = null;
+  }
+
+  /**
+   * Stop without success/fail status
+   */
+  stop() {
+    if (!this.enabled || !this.spinner) return;
+
+    this.spinner.stop();
+    this.spinner = null;
+  }
+
+  /**
+   * Create a progress bar string
+   */
+  private createProgressBar(percentage: number): string {
+    const width = 20;
+    const filled = Math.round((percentage / 100) * width);
+    const empty = width - filled;
+
+    const bar = "█".repeat(filled) + "░".repeat(empty);
+    return `[${bar}] ${percentage}%`;
+  }
+}
+
+/**
+ * Progress indicator for agent thinking
+ */
+export class AgentProgress {
+  private spinner: Ora | null = null;
+  private enabled: boolean;
+  private stepCount = 0;
+  private currentTool: string | null = null;
+
+  constructor(enabled: boolean = true) {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Start thinking indicator
+   */
+  startThinking() {
+    if (!this.enabled) return;
+
+    this.stepCount = 0;
+    this.currentTool = null;
+    this.spinner = ora({
+      text: "🤔 Analyzing...",
+      spinner: "dots",
+      color: "cyan",
+    }).start();
+  }
+
+  /**
+   * Update with current tool usage
+   */
+  updateTool(toolName: string, detail?: string) {
+    if (!this.enabled || !this.spinner) return;
+
+    this.stepCount++;
+    this.currentTool = toolName;
+
+    // Map tool names to more user-friendly descriptions
+    const friendlyNames: Record<string, string> = {
+      bash: "Running command",
+      px_fetch_more_spans: "Fetching additional spans",
+      px_fetch_more_trace: "Fetching trace details",
+    };
+
+    const displayName = friendlyNames[toolName] || toolName;
+    const message = detail
+      ? `🔧 ${displayName}: ${detail}`
+      : `🔧 ${displayName} (step ${this.stepCount})`;
+
+    this.spinner.text = message;
+  }
+
+  /**
+   * Update with tool result
+   */
+  updateToolResult(toolName: string, success: boolean = true) {
+    if (!this.enabled || !this.spinner) return;
+
+    const icon = success ? "✓" : "✗";
+    const status = success ? "completed" : "failed";
+
+    // More informative messages for each tool
+    const toolMessages: Record<string, string> = {
+      bash: "Command executed",
+      px_fetch_more_spans: "Additional spans fetched",
+      px_fetch_more_trace: "Trace details fetched",
+    };
+
+    const baseMessage = toolMessages[toolName] || `Tool ${toolName}`;
+    const message = `${icon} ${baseMessage} ${status}`;
+
+    // Brief flash of the result before moving on
+    this.spinner.text = message;
+  }
+
+  /**
+   * Show progress for a specific action
+   */
+  updateAction(action: string) {
+    if (!this.enabled || !this.spinner) return;
+
+    this.spinner.text = `🔍 ${action}...`;
+  }
+
+  /**
+   * Stop the thinking indicator
+   */
+  stop() {
+    if (!this.enabled || !this.spinner) return;
+
+    this.spinner.stop();
+    this.spinner = null;
+  }
+
+  /**
+   * Complete with a success message
+   */
+  succeed(message: string = "✨ Analysis complete") {
+    if (!this.enabled || !this.spinner) return;
+
+    this.spinner.succeed(message);
+    this.spinner = null;
+  }
+}
+
+/**
+ * Simple progress logger for when spinners aren't appropriate
+ */
+export class SimpleProgress {
+  private enabled: boolean;
+
+  constructor(enabled: boolean = true) {
+    this.enabled = enabled;
+  }
+
+  log(message: string) {
+    if (!this.enabled) return;
+    console.log(`[Phoenix Insight] ${message}`);
+  }
+
+  info(message: string) {
+    if (!this.enabled) return;
+    console.log(`ℹ️  ${message}`);
+  }
+
+  success(message: string) {
+    if (!this.enabled) return;
+    console.log(`✅ ${message}`);
+  }
+
+  warning(message: string) {
+    if (!this.enabled) return;
+    console.log(`⚠️  ${message}`);
+  }
+
+  error(message: string) {
+    if (!this.enabled) return;
+    console.log(`❌ ${message}`);
+  }
+}

package/src/prompts/index.ts

@@ -0,0 +1 @@
+export { INSIGHT_SYSTEM_PROMPT } from "./system.js";

package/src/prompts/system.ts

@@ -0,0 +1,31 @@
+/**
+ * System prompt for the Phoenix Insight AI agent
+ * This prompt teaches the agent about the filesystem layout and available commands
+ */
+
+export const INSIGHT_SYSTEM_PROMPT = `You are an expert at analyzing Phoenix observability data.
+
+**START by reading /phoenix/_context.md** - it contains a summary of what's available.
+
+You have access to a bash shell with Phoenix data organized as files:
+
+/phoenix/
+  _context.md                    - READ THIS FIRST: summary of available data
+  /projects/{name}/spans/        - Span data (JSONL format, may be sampled)
+  /datasets/                     - Datasets and examples
+  /experiments/                  - Experiment runs and results
+  /prompts/                      - Prompt templates and versions
+
+Use commands like:
+- cat, head, tail: Read file contents  
+- grep: Search for patterns
+- jq: Query and transform JSON/JSONL
+- ls, find: Navigate and discover data
+- sort, uniq, wc: Aggregate and count
+- awk: Complex text processing
+
+If you need MORE data than what's in the snapshot:
+- px-fetch-more spans --project <name> --limit 500
+- px-fetch-more trace --trace-id <id>
+
+This is a READ-ONLY snapshot. Start with _context.md, then explore to answer the question.`;

package/src/snapshot/client.ts

@@ -0,0 +1,129 @@
+import { createClient, type PhoenixClient } from "@arizeai/phoenix-client";
+
+export class PhoenixClientError extends Error {
+  public code:
+    | "NETWORK_ERROR"
+    | "AUTH_ERROR"
+    | "INVALID_RESPONSE"
+    | "UNKNOWN_ERROR";
+  public originalError?: unknown;
+
+  constructor(
+    message: string,
+    code: "NETWORK_ERROR" | "AUTH_ERROR" | "INVALID_RESPONSE" | "UNKNOWN_ERROR",
+    originalError?: unknown
+  ) {
+    super(message);
+    this.name = "PhoenixClientError";
+    this.code = code;
+    this.originalError = originalError;
+  }
+}
+
+export interface PhoenixClientConfig {
+  baseURL?: string;
+  apiKey?: string;
+}
+
+/**
+ * Creates a wrapped Phoenix client with error handling
+ */
+export function createPhoenixClient(
+  config: PhoenixClientConfig = {}
+): PhoenixClient {
+  const headers: Record<string, string> = {};
+
+  if (config.apiKey) {
+    headers["api_key"] = config.apiKey;
+  }
+
+  const clientOptions: Parameters<typeof createClient>[0] = {
+    options: {
+      baseUrl: config.baseURL,
+      headers: Object.keys(headers).length > 0 ? headers : undefined,
+    },
+  };
+
+  return createClient(clientOptions);
+}
+
+/**
+ * Wraps an async operation with standardized error handling
+ */
+export async function withErrorHandling<T>(
+  operation: () => Promise<T>,
+  context: string
+): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    // Network errors
+    if (error instanceof TypeError && error.message.includes("fetch")) {
+      throw new PhoenixClientError(
+        `Network error during ${context}: Unable to connect to Phoenix server`,
+        "NETWORK_ERROR",
+        error
+      );
+    }
+
+    // HTTP errors from the middleware
+    if (error instanceof Error && error.message.includes(": ")) {
+      const parts = error.message.split(": ", 2);
+      if (parts.length === 2 && parts[1]) {
+        const [url, statusInfo] = parts;
+        const statusParts = statusInfo.split(" ");
+        const statusCode = statusParts[0];
+        const statusText = statusParts.slice(1).join(" ");
+
+        if (statusCode === "401" || statusCode === "403") {
+          throw new PhoenixClientError(
+            `Authentication error during ${context}: ${statusText}`,
+            "AUTH_ERROR",
+            error
+          );
+        }
+
+        if (statusCode && statusCode.startsWith("4")) {
+          throw new PhoenixClientError(
+            `Client error during ${context}: ${statusCode} ${statusText}`,
+            "INVALID_RESPONSE",
+            error
+          );
+        }
+
+        if (statusCode && statusCode.startsWith("5")) {
+          throw new PhoenixClientError(
+            `Server error during ${context}: ${statusCode} ${statusText}`,
+            "NETWORK_ERROR",
+            error
+          );
+        }
+      }
+    }
+
+    // Unknown errors
+    throw new PhoenixClientError(
+      `Unexpected error during ${context}: ${error instanceof Error ? error.message : String(error)}`,
+      "UNKNOWN_ERROR",
+      error
+    );
+  }
+}
+
+/**
+ * Helper to safely extract data from API responses
+ */
+export function extractData<T>(response: { data?: T; error?: unknown }): T {
+  if (response.error) {
+    throw response.error;
+  }
+
+  if (!response.data) {
+    throw new PhoenixClientError(
+      "Invalid API response: missing data",
+      "INVALID_RESPONSE"
+    );
+  }
+
+  return response.data;
+}