@cephalization/phoenix-insight 0.4.0 → 1.0.2

package/src/snapshot/prompts.ts

@@ -1,267 +0,0 @@
-import type { PhoenixClient } from "@arizeai/phoenix-client";
-import type { ExecutionMode } from "../modes/types.js";
-import { withErrorHandling, extractData } from "./client.js";
-
-interface FetchPromptsOptions {
-  limit?: number;
-}
-
-/**
- * Converts an array to JSONL format
- */
-function toJSONL(items: unknown[]): string {
-  if (items.length === 0) {
-    return "";
-  }
-  return items.map((item) => JSON.stringify(item)).join("\n");
-}
-
-/**
- * Converts a prompt template to markdown format
- */
-function templateToMarkdown(template: any, templateFormat: string): string {
-  // Handle string template
-  if (templateFormat === "STRING") {
-    if (typeof template === "string") {
-      return template;
-    }
-    // It might be wrapped in an object with type
-    if (template?.template && typeof template.template === "string") {
-      return template.template;
-    }
-    return JSON.stringify(template, null, 2);
-  }
-
-  // Handle chat template
-  const messages = template?.messages || [];
-  const lines: string[] = ["# Chat Template", ""];
-
-  for (const message of messages) {
-    lines.push(`## ${message.role}`);
-    lines.push("");
-
-    if (typeof message.content === "string") {
-      lines.push(message.content);
-    } else if (Array.isArray(message.content)) {
-      // Handle multi-part content
-      for (const part of message.content) {
-        if (part.type === "text" && part.text) {
-          lines.push(part.text);
-        } else {
-          // For non-text parts, show as JSON
-          lines.push("```json");
-          lines.push(JSON.stringify(part, null, 2));
-          lines.push("```");
-        }
-      }
-    } else {
-      // If content is not string or array, show as JSON
-      lines.push("```json");
-      lines.push(JSON.stringify(message.content, null, 2));
-      lines.push("```");
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-/**
- * Creates a markdown representation of a prompt version
- */
-function createVersionMarkdown(version: any): string {
-  const lines: string[] = [];
-
-  // Add metadata header
-  lines.push("---");
-  lines.push(`id: ${version.id}`);
-  if (version.model_name) lines.push(`model_name: ${version.model_name}`);
-  if (version.model_provider)
-    lines.push(`model_provider: ${version.model_provider}`);
-  if (version.template_format)
-    lines.push(`template_format: ${version.template_format}`);
-  if (version.description) lines.push(`description: ${version.description}`);
-  lines.push("---");
-  lines.push("");
-
-  // Add template content
-  if (version.template) {
-    lines.push(
-      templateToMarkdown(version.template, version.template_format || "STRING")
-    );
-    lines.push("");
-  }
-
-  // Add invocation parameters if present
-  if (version.invocation_parameters) {
-    lines.push("## Invocation Parameters");
-    lines.push("");
-    lines.push("```json");
-    lines.push(JSON.stringify(version.invocation_parameters, null, 2));
-    lines.push("```");
-    lines.push("");
-  }
-
-  // Add tools if present
-  if (version.tools) {
-    lines.push("## Tools");
-    lines.push("");
-    lines.push("```json");
-    lines.push(JSON.stringify(version.tools, null, 2));
-    lines.push("```");
-    lines.push("");
-  }
-
-  // Add response format if present
-  if (version.response_format) {
-    lines.push("## Response Format");
-    lines.push("");
-    lines.push("```json");
-    lines.push(JSON.stringify(version.response_format, null, 2));
-    lines.push("```");
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-/**
- * Fetches all prompts and their versions from Phoenix
- */
-export async function fetchPrompts(
-  client: PhoenixClient,
-  mode: ExecutionMode,
-  options: FetchPromptsOptions = {}
-): Promise<void> {
-  const { limit = 100 } = options;
-
-  // Fetch all prompts with pagination
-  const prompts: any[] = [];
-  let cursor: string | null = null;
-
-  while (prompts.length < limit) {
-    const query: Record<string, unknown> = {
-      limit: Math.min(limit - prompts.length, 100),
-    };
-    if (cursor) {
-      query.cursor = cursor;
-    }
-
-    const response = await withErrorHandling(
-      () => client.GET("/v1/prompts", { params: { query } }),
-      "fetching prompts"
-    );
-
-    const data = extractData(response);
-    prompts.push(...data.data);
-    cursor = data.next_cursor;
-
-    // Stop if no more data
-    if (!cursor || data.data.length === 0) {
-      break;
-    }
-  }
-
-  // Write prompts index
-  await mode.writeFile("/phoenix/prompts/index.jsonl", toJSONL(prompts));
-
-  // Fetch versions for each prompt
-  for (const prompt of prompts) {
-    const safePromptName = prompt.name.replace(/[^a-zA-Z0-9-_]/g, "_");
-
-    // Write prompt metadata
-    await mode.writeFile(
-      `/phoenix/prompts/${safePromptName}/metadata.json`,
-      JSON.stringify(
-        {
-          id: prompt.id,
-          name: prompt.name,
-          description: prompt.description || null,
-          metadata: prompt.metadata || {},
-          source_prompt_id: prompt.source_prompt_id || null,
-          snapshot_timestamp: new Date().toISOString(),
-        },
-        null,
-        2
-      )
-    );
-
-    // Fetch all versions for this prompt
-    const versions: any[] = [];
-    let versionCursor: string | null = null;
-
-    while (true) {
-      const versionQuery: Record<string, unknown> = {
-        limit: 100,
-      };
-      if (versionCursor) {
-        versionQuery.cursor = versionCursor;
-      }
-
-      const versionsResponse = await withErrorHandling(
-        () =>
-          client.GET("/v1/prompts/{prompt_identifier}/versions", {
-            params: {
-              path: { prompt_identifier: prompt.id },
-              query: versionQuery,
-            },
-          }),
-        `fetching versions for prompt ${prompt.name}`
-      );
-
-      const versionsData = extractData(versionsResponse);
-      versions.push(...versionsData.data);
-      versionCursor = versionsData.next_cursor;
-
-      // Stop if no more data
-      if (!versionCursor || versionsData.data.length === 0) {
-        break;
-      }
-    }
-
-    // Write versions index as JSONL
-    await mode.writeFile(
-      `/phoenix/prompts/${safePromptName}/versions/index.jsonl`,
-      toJSONL(versions)
-    );
-
-    // Write each version as markdown
-    for (const version of versions) {
-      const versionId = version.id.replace(/[^a-zA-Z0-9-_]/g, "_");
-      const markdownContent = createVersionMarkdown(version);
-
-      await mode.writeFile(
-        `/phoenix/prompts/${safePromptName}/versions/${versionId}.md`,
-        markdownContent
-      );
-    }
-
-    // Fetch and save the latest version separately for convenience
-    try {
-      const latestResponse = await withErrorHandling(
-        () =>
-          client.GET("/v1/prompts/{prompt_identifier}/latest", {
-            params: {
-              path: { prompt_identifier: prompt.id },
-            },
-          }),
-        `fetching latest version for prompt ${prompt.name}`
-      );
-
-      const latestData = extractData(latestResponse);
-      if (latestData.data) {
-        const latestMarkdownContent = createVersionMarkdown(latestData.data);
-
-        await mode.writeFile(
-          `/phoenix/prompts/${safePromptName}/latest.md`,
-          latestMarkdownContent
-        );
-      }
-    } catch (error) {
-      // If there's no latest version, that's okay - just skip it
-      console.warn(
-        `No latest version available for prompt ${prompt.name}: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-  }
-}

package/src/snapshot/spans.ts

@@ -1,163 +0,0 @@
-import type { PhoenixClient } from "@arizeai/phoenix-client";
-import type { ExecutionMode } from "../modes/types.js";
-import { withErrorHandling } from "./client.js";
-
-export interface SnapshotSpansOptions {
-  /** Inclusive lower bound time for filtering spans */
-  startTime?: Date | string | null;
-  /** Exclusive upper bound time for filtering spans */
-  endTime?: Date | string | null;
-  /** Maximum number of spans to fetch per project (default: 1000) */
-  spansPerProject?: number;
-  /** Enable debug logging (default: uses DEBUG env var) */
-  debug?: boolean;
-}
-
-/**
- * Debug logger that respects the debug flag or DEBUG environment variable
- */
-function createDebugLogger(debug?: boolean) {
-  const isDebugEnabled = debug ?? !!process.env.DEBUG;
-  return {
-    log: (message: string) => {
-      if (isDebugEnabled) {
-        console.log(`[snapshotSpans] ${message}`);
-      }
-    },
-  };
-}
-
-interface SpanData {
-  id: string;
-  name: string;
-  context: {
-    trace_id: string;
-    span_id: string;
-  };
-  span_kind: string;
-  parent_id: string | null;
-  start_time: string;
-  end_time: string;
-  status_code: string;
-  status_message: string;
-  attributes: Record<string, unknown>;
-  events: Array<unknown>;
-}
-
-interface ProjectMetadata {
-  name: string;
-}
-
-/**
- * Fetches spans for all projects and writes them to the snapshot
- *
- * @param client - Phoenix client instance
- * @param mode - Execution mode for file operations
- * @param options - Options for filtering and limiting spans
- */
-export async function snapshotSpans(
-  client: PhoenixClient,
-  mode: ExecutionMode,
-  options: SnapshotSpansOptions = {}
-): Promise<void> {
-  const { startTime, endTime, spansPerProject = 1000, debug } = options;
-  const logger = createDebugLogger(debug);
-
-  // Read projects index to get project names
-  // Use relative path so it works with the cwd set by the execution mode
-  logger.log("Reading projects index from projects/index.jsonl");
-  const projectsIndexContent = await mode.exec("cat projects/index.jsonl");
-  if (!projectsIndexContent.stdout) {
-    // No projects, nothing to do
-    logger.log("No projects found in index, skipping span fetch");
-    return;
-  }
-
-  const projectNames = projectsIndexContent.stdout
-    .trim()
-    .split("\n")
-    .filter((line) => line.length > 0)
-    .map((line) => {
-      const project = JSON.parse(line) as ProjectMetadata;
-      return project.name;
-    });
-
-  logger.log(`Found ${projectNames.length} project(s): ${projectNames.join(", ")}`);
-
-  // Fetch spans for each project
-  for (const projectName of projectNames) {
-    await withErrorHandling(async () => {
-      logger.log(`Starting span fetch for project: ${projectName}`);
-      const spans: SpanData[] = [];
-      let cursor: string | null = null;
-      let totalFetched = 0;
-
-      // Paginate through spans until we reach the limit or no more data
-      while (totalFetched < spansPerProject) {
-        const query: Record<string, any> = {
-          limit: Math.min(100, spansPerProject - totalFetched), // Fetch in chunks of 100
-        };
-
-        if (cursor) {
-          query.cursor = cursor;
-        }
-
-        if (startTime) {
-          query.start_time =
-            startTime instanceof Date ? startTime.toISOString() : startTime;
-        }
-
-        if (endTime) {
-          query.end_time =
-            endTime instanceof Date ? endTime.toISOString() : endTime;
-        }
-
-        const response = await client.GET(
-          "/v1/projects/{project_identifier}/spans",
-          {
-            params: {
-              path: {
-                project_identifier: projectName,
-              },
-              query,
-            },
-          }
-        );
-
-        if (response.error) throw response.error;
-
-        const data = response.data?.data ?? [];
-        spans.push(...(data as SpanData[]));
-        totalFetched += data.length;
-
-        cursor = response.data?.next_cursor ?? null;
-
-        // Stop if there's no more data
-        if (!cursor || data.length === 0) {
-          break;
-        }
-      }
-
-      logger.log(`Completed span fetch for project ${projectName}: ${spans.length} span(s) fetched`);
-
-      // Write spans to JSONL file
-      const spansFilePath = `/phoenix/projects/${projectName}/spans/index.jsonl`;
-      logger.log(`Writing spans to ${spansFilePath}`);
-      const jsonlContent = spans.map((span) => JSON.stringify(span)).join("\n");
-      await mode.writeFile(spansFilePath, jsonlContent);
-
-      // Write metadata about the spans snapshot
-      const metadataFilePath = `/phoenix/projects/${projectName}/spans/metadata.json`;
-      logger.log(`Writing metadata to ${metadataFilePath}`);
-      const metadata = {
-        project: projectName,
-        spanCount: spans.length,
-        startTime: startTime || null,
-        endTime: endTime || null,
-        snapshotTime: new Date().toISOString(),
-      };
-
-      await mode.writeFile(metadataFilePath, JSON.stringify(metadata, null, 2));
-    }, `fetching spans for project ${projectName}`);
-  }
-}

package/src/snapshot/utils.ts

@@ -1,140 +0,0 @@
-/**
- * Snapshot discovery utilities
- *
- * Functions for listing and finding snapshots in the local filesystem.
- */
-
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import * as os from "node:os";
-
-/**
- * Information about a single snapshot
- */
-export interface SnapshotInfo {
-  /** Absolute path to the snapshot directory (the 'phoenix' subdirectory) */
-  path: string;
-  /** Timestamp when the snapshot was created (from directory name) */
-  timestamp: Date;
-  /** Unique identifier for the snapshot (directory name) */
-  id: string;
-}
-
-/**
- * Get the base snapshots directory path
- */
-export function getSnapshotsDir(): string {
-  return path.join(os.homedir(), ".phoenix-insight", "snapshots");
-}
-
-/**
- * Parse a snapshot directory name to extract timestamp
- *
- * Directory names are in format: `<timestamp>-<random>` where timestamp is Date.now()
- * Example: "1704067200000-abc123" -> Date(2024-01-01T00:00:00.000Z)
- *
- * @param dirName - The directory name to parse
- * @returns The parsed timestamp as Date, or null if invalid
- */
-function parseSnapshotDirName(dirName: string): Date | null {
-  // Format: <timestamp>-<random>
-  const match = dirName.match(/^(\d+)-[\w]+$/);
-  if (!match || !match[1]) {
-    return null;
-  }
-
-  const timestamp = parseInt(match[1], 10);
-  if (isNaN(timestamp) || timestamp <= 0) {
-    return null;
-  }
-
-  const date = new Date(timestamp);
-  // Validate the date is reasonable (between year 2000 and year 3000)
-  // Use UTC year to avoid timezone issues
-  const year = date.getUTCFullYear();
-  if (year < 2000 || year > 3000) {
-    return null;
-  }
-
-  return date;
-}
-
-/**
- * List all available snapshots
- *
- * Scans the snapshots directory and returns information about each valid snapshot.
- * Results are sorted by timestamp descending (most recent first).
- *
- * @returns Array of snapshot info objects, sorted by timestamp descending
- */
-export async function listSnapshots(): Promise<SnapshotInfo[]> {
-  const snapshotsDir = getSnapshotsDir();
-
-  // Check if snapshots directory exists
-  try {
-    await fs.access(snapshotsDir);
-  } catch {
-    // Directory doesn't exist - return empty array
-    return [];
-  }
-
-  // Read directory contents
-  let entries: string[];
-  try {
-    entries = await fs.readdir(snapshotsDir);
-  } catch {
-    // Cannot read directory - return empty array
-    return [];
-  }
-
-  // Filter and parse valid snapshot directories
-  const snapshots: SnapshotInfo[] = [];
-
-  for (const entry of entries) {
-    const timestamp = parseSnapshotDirName(entry);
-    if (!timestamp) {
-      // Invalid directory name format - skip
-      continue;
-    }
-
-    const snapshotPath = path.join(snapshotsDir, entry, "phoenix");
-
-    // Verify the phoenix subdirectory exists
-    try {
-      const stat = await fs.stat(snapshotPath);
-      if (!stat.isDirectory()) {
-        continue;
-      }
-    } catch {
-      // Phoenix subdirectory doesn't exist or can't be accessed - skip
-      continue;
-    }
-
-    snapshots.push({
-      path: snapshotPath,
-      timestamp,
-      id: entry,
-    });
-  }
-
-  // Sort by timestamp descending (most recent first)
-  snapshots.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
-
-  return snapshots;
-}
-
-/**
- * Get the latest (most recent) snapshot
- *
- * @returns The most recent snapshot info, or null if no snapshots exist
- */
-export async function getLatestSnapshot(): Promise<SnapshotInfo | null> {
-  const snapshots = await listSnapshots();
-
-  if (snapshots.length === 0) {
-    return null;
-  }
-
-  // First element is the most recent due to descending sort
-  return snapshots[0] ?? null;
-}