@cephalization/phoenix-insight 0.1.0

package/src/commands/index.ts

@@ -0,0 +1,8 @@
+export {
+  fetchMoreSpans,
+  type FetchMoreSpansOptions,
+} from "./px-fetch-more-spans.js";
+export {
+  fetchMoreTrace,
+  type FetchMoreTraceOptions,
+} from "./px-fetch-more-trace.js";

package/src/commands/px-fetch-more-spans.ts

@@ -0,0 +1,174 @@
+import type { PhoenixClient } from "@arizeai/phoenix-client";
+import type { ExecutionMode } from "../modes/types.js";
+import { withErrorHandling } from "../snapshot/client.js";
+
+export interface FetchMoreSpansOptions {
+  /** Project name to fetch spans for */
+  project: string;
+  /** Number of additional spans to fetch */
+  limit: number;
+  /** Inclusive lower bound time for filtering spans */
+  startTime?: Date | string | null;
+  /** Exclusive upper bound time for filtering spans */
+  endTime?: Date | string | null;
+}
+
+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 SpansMetadata {
+  project: string;
+  spanCount: number;
+  startTime: string | null;
+  endTime: string | null;
+  snapshotTime: string;
+  lastCursor?: string | null;
+}
+
+/**
+ * Fetches additional spans for a specific project on-demand
+ *
+ * @param client - Phoenix client instance
+ * @param mode - Execution mode for file operations
+ * @param options - Options for fetching spans
+ */
+export async function fetchMoreSpans(
+  client: PhoenixClient,
+  mode: ExecutionMode,
+  options: FetchMoreSpansOptions
+): Promise<void> {
+  const { project, limit, startTime, endTime } = options;
+
+  await withErrorHandling(async () => {
+    // Try to read existing metadata to get the last cursor
+    let existingMetadata: SpansMetadata | null = null;
+    let existingSpans: SpanData[] = [];
+
+    try {
+      const metadataResult = await mode.exec(
+        `cat /phoenix/projects/${project}/spans/metadata.json`
+      );
+      if (metadataResult.exitCode === 0 && metadataResult.stdout) {
+        existingMetadata = JSON.parse(metadataResult.stdout);
+      }
+    } catch (error) {
+      // Metadata doesn't exist, that's okay
+    }
+
+    // Try to read existing spans
+    try {
+      const spansResult = await mode.exec(
+        `cat /phoenix/projects/${project}/spans/index.jsonl`
+      );
+      if (spansResult.exitCode === 0 && spansResult.stdout) {
+        existingSpans = spansResult.stdout
+          .trim()
+          .split("\n")
+          .filter((line) => line.length > 0)
+          .map((line) => JSON.parse(line) as SpanData);
+      }
+    } catch (error) {
+      // Spans file doesn't exist, that's okay
+    }
+
+    // Fetch new spans
+    const newSpans: SpanData[] = [];
+    let cursor: string | null = existingMetadata?.lastCursor ?? null;
+    let totalFetched = 0;
+
+    while (totalFetched < limit) {
+      const query: Record<string, any> = {
+        limit: Math.min(100, limit - 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: project,
+            },
+            query,
+          },
+        }
+      );
+
+      if (response.error) throw response.error;
+
+      const data = response.data?.data ?? [];
+      newSpans.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;
+      }
+    }
+
+    // Combine existing and new spans
+    const allSpans = [...existingSpans, ...newSpans];
+
+    // Write updated spans to JSONL file
+    const jsonlContent = allSpans
+      .map((span) => JSON.stringify(span))
+      .join("\n");
+    await mode.writeFile(
+      `/phoenix/projects/${project}/spans/index.jsonl`,
+      jsonlContent
+    );
+
+    // Update metadata
+    const metadata: SpansMetadata = {
+      project,
+      spanCount: allSpans.length,
+      startTime:
+        startTime instanceof Date
+          ? startTime.toISOString()
+          : (startTime ?? null),
+      endTime:
+        endTime instanceof Date ? endTime.toISOString() : (endTime ?? null),
+      snapshotTime: new Date().toISOString(),
+      lastCursor: cursor,
+    };
+
+    await mode.writeFile(
+      `/phoenix/projects/${project}/spans/metadata.json`,
+      JSON.stringify(metadata, null, 2)
+    );
+
+    console.log(
+      `Fetched ${newSpans.length} additional spans for project "${project}"`
+    );
+    console.log(`Total spans for project: ${allSpans.length}`);
+  }, `fetching more spans for project ${project}`);
+}

package/src/commands/px-fetch-more-trace.ts

@@ -0,0 +1,183 @@
+import type { PhoenixClient } from "@arizeai/phoenix-client";
+import type { ExecutionMode } from "../modes/types.js";
+import { withErrorHandling } from "../snapshot/client.js";
+
+export interface FetchMoreTraceOptions {
+  /** Trace ID to fetch all spans for */
+  traceId: string;
+  /** Project name to search in */
+  project: string;
+}
+
+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>;
+}
+
+/**
+ * Fetches all spans for a specific trace ID
+ *
+ * @param client - Phoenix client instance
+ * @param mode - Execution mode for file operations
+ * @param options - Options for fetching trace
+ */
+export async function fetchMoreTrace(
+  client: PhoenixClient,
+  mode: ExecutionMode,
+  options: FetchMoreTraceOptions
+): Promise<void> {
+  const { traceId, project } = options;
+
+  await withErrorHandling(async () => {
+    // First, check if the project exists in our snapshot
+    const projectsResult = await mode.exec("cat /phoenix/projects/index.jsonl");
+    if (projectsResult.exitCode !== 0 || !projectsResult.stdout) {
+      console.error("No projects found in snapshot. Run a snapshot first.");
+      return;
+    }
+
+    const projectNames = projectsResult.stdout
+      .trim()
+      .split("\n")
+      .filter((line) => line.length > 0)
+      .map((line) => JSON.parse(line).name);
+
+    if (!projectNames.includes(project)) {
+      console.error(
+        `Project "${project}" not found. Available projects: ${projectNames.join(
+          ", "
+        )}`
+      );
+      return;
+    }
+
+    // Fetch all spans that belong to this trace
+    const traceSpans: SpanData[] = [];
+    let cursor: string | null = null;
+    let totalFetched = 0;
+
+    console.log(`Fetching trace ${traceId} from project "${project}"...`);
+
+    // We need to fetch spans in batches and filter by trace_id
+    // Since the API doesn't support direct trace_id filtering
+    while (true) {
+      const query: Record<string, any> = {
+        limit: 100, // Fetch in chunks
+      };
+
+      if (cursor) {
+        query.cursor = cursor;
+      }
+
+      const response = await client.GET(
+        "/v1/projects/{project_identifier}/spans",
+        {
+          params: {
+            path: {
+              project_identifier: project,
+            },
+            query,
+          },
+        }
+      );
+
+      if (response.error) throw response.error;
+
+      const data = response.data?.data ?? [];
+      totalFetched += data.length;
+
+      // Filter spans that belong to our trace
+      const matchingSpans = (data as SpanData[]).filter(
+        (span) => span.context.trace_id === traceId
+      );
+      traceSpans.push(...matchingSpans);
+
+      cursor = response.data?.next_cursor ?? null;
+
+      // Stop if we found spans for the trace or no more data
+      if (traceSpans.length > 0 || !cursor || data.length === 0) {
+        // If we found some spans, continue until we have all spans from the trace
+        // This is because trace spans might be spread across multiple pages
+        if (traceSpans.length > 0 && cursor && data.length > 0) {
+          console.log(
+            `Found ${traceSpans.length} spans so far, continuing search...`
+          );
+          continue;
+        }
+        break;
+      }
+
+      // Show progress for large datasets
+      if (totalFetched % 1000 === 0) {
+        console.log(`Searched ${totalFetched} spans so far...`);
+      }
+    }
+
+    if (traceSpans.length === 0) {
+      console.log(
+        `No spans found for trace ${traceId} in project "${project}"`
+      );
+      console.log(
+        `Searched through ${totalFetched} spans. The trace might not exist or might be in a different project.`
+      );
+      return;
+    }
+
+    // Sort spans by start_time to show them in order
+    traceSpans.sort(
+      (a, b) =>
+        new Date(a.start_time).getTime() - new Date(b.start_time).getTime()
+    );
+
+    // Write trace spans to a dedicated file
+    const jsonlContent = traceSpans
+      .map((span) => JSON.stringify(span))
+      .join("\n");
+
+    const traceDir = `/phoenix/traces/${traceId}`;
+    await mode.writeFile(`${traceDir}/spans.jsonl`, jsonlContent);
+
+    // Create trace metadata
+    const rootSpan = traceSpans.find((span) => !span.parent_id);
+    const firstSpan = traceSpans[0];
+    const lastSpan = traceSpans[traceSpans.length - 1];
+    const metadata = {
+      traceId,
+      project,
+      spanCount: traceSpans.length,
+      rootSpan: rootSpan ? { id: rootSpan.id, name: rootSpan.name } : null,
+      startTime: firstSpan?.start_time || null,
+      endTime: lastSpan?.end_time || null,
+      duration:
+        firstSpan && lastSpan
+          ? new Date(lastSpan.end_time).getTime() -
+            new Date(firstSpan.start_time).getTime()
+          : 0,
+      snapshotTime: new Date().toISOString(),
+    };
+
+    await mode.writeFile(
+      `${traceDir}/metadata.json`,
+      JSON.stringify(metadata, null, 2)
+    );
+
+    console.log(`\nSuccessfully fetched trace ${traceId}:`);
+    console.log(`- Project: ${project}`);
+    console.log(`- Spans: ${traceSpans.length}`);
+    console.log(`- Root span: ${rootSpan?.name || "Unknown"}`);
+    console.log(`- Duration: ${(metadata.duration / 1000).toFixed(2)} seconds`);
+    console.log(`\nTrace data saved to: ${traceDir}/`);
+  }, `fetching trace ${traceId}`);
+}

package/src/config/index.ts

@@ -0,0 +1,225 @@
+/**
+ * Config singleton module for Phoenix Insight CLI
+ *
+ * Provides centralized configuration management with priority-based merging:
+ * 1. Config file (lowest priority)
+ * 2. Environment variables
+ * 3. CLI arguments (highest priority)
+ */
+
+import { configSchema, type Config, getDefaultConfig } from "./schema.js";
+import {
+  getConfigPath,
+  loadConfigFile,
+  validateConfig,
+  createDefaultConfig,
+  setCliConfigPath,
+} from "./loader.js";
+
+// Re-export Config type for convenience
+export type { Config } from "./schema.js";
+
+/**
+ * Module-level storage for the initialized config singleton
+ */
+let configInstance: Config | null = null;
+
+/**
+ * CLI arguments that can override config values
+ */
+export interface CliArgs {
+  /** Custom config file path */
+  config?: string;
+  /** Phoenix server base URL */
+  baseUrl?: string;
+  /** Phoenix API key */
+  apiKey?: string;
+  /** Maximum spans to fetch per project */
+  limit?: number;
+  /** Enable streaming responses */
+  stream?: boolean;
+  /** Execution mode: sandbox or local */
+  local?: boolean;
+  /** Force refresh of snapshot data */
+  refresh?: boolean;
+  /** Enable tracing */
+  trace?: boolean;
+}
+
+/**
+ * Environment variable mappings to config keys
+ */
+const ENV_VAR_MAPPINGS: Record<string, keyof Config> = {
+  PHOENIX_BASE_URL: "baseUrl",
+  PHOENIX_API_KEY: "apiKey",
+  PHOENIX_INSIGHT_LIMIT: "limit",
+  PHOENIX_INSIGHT_STREAM: "stream",
+  PHOENIX_INSIGHT_MODE: "mode",
+  PHOENIX_INSIGHT_REFRESH: "refresh",
+  PHOENIX_INSIGHT_TRACE: "trace",
+};
+
+/**
+ * Parse environment variable value to appropriate type
+ */
+function parseEnvValue(
+  key: keyof Config,
+  value: string
+): string | number | boolean | undefined {
+  switch (key) {
+    case "baseUrl":
+    case "apiKey":
+      return value;
+    case "limit":
+      const num = parseInt(value, 10);
+      return isNaN(num) ? undefined : num;
+    case "stream":
+    case "refresh":
+    case "trace":
+      return value.toLowerCase() === "true" || value === "1";
+    case "mode":
+      if (value === "sandbox" || value === "local") {
+        return value;
+      }
+      return undefined;
+    default:
+      return value;
+  }
+}
+
+/**
+ * Get config values from environment variables
+ */
+function getEnvConfig(): Partial<Config> {
+  const envConfig: Partial<Config> = {};
+
+  for (const [envVar, configKey] of Object.entries(ENV_VAR_MAPPINGS)) {
+    const value = process.env[envVar];
+    if (value !== undefined) {
+      const parsed = parseEnvValue(configKey, value);
+      if (parsed !== undefined) {
+        (envConfig as any)[configKey] = parsed;
+      }
+    }
+  }
+
+  return envConfig;
+}
+
+/**
+ * Convert CLI args to config format
+ */
+function cliArgsToConfig(cliArgs: CliArgs): Partial<Config> {
+  const config: Partial<Config> = {};
+
+  if (cliArgs.baseUrl !== undefined) {
+    config.baseUrl = cliArgs.baseUrl;
+  }
+  if (cliArgs.apiKey !== undefined) {
+    config.apiKey = cliArgs.apiKey;
+  }
+  if (cliArgs.limit !== undefined) {
+    config.limit = cliArgs.limit;
+  }
+  if (cliArgs.stream !== undefined) {
+    config.stream = cliArgs.stream;
+  }
+  if (cliArgs.local !== undefined) {
+    // CLI uses --local flag, config uses mode
+    config.mode = cliArgs.local ? "local" : "sandbox";
+  }
+  if (cliArgs.refresh !== undefined) {
+    config.refresh = cliArgs.refresh;
+  }
+  if (cliArgs.trace !== undefined) {
+    config.trace = cliArgs.trace;
+  }
+
+  return config;
+}
+
+/**
+ * Initialize the configuration singleton
+ *
+ * Merges configuration from multiple sources with the following priority:
+ * 1. Config file (lowest priority)
+ * 2. Environment variables
+ * 3. CLI arguments (highest priority)
+ *
+ * @param cliArgs - CLI arguments from Commander
+ * @returns The initialized configuration
+ */
+export async function initializeConfig(cliArgs: CliArgs = {}): Promise<Config> {
+  // Set CLI config path if provided (for getConfigPath to use)
+  if (cliArgs.config) {
+    setCliConfigPath(cliArgs.config);
+  }
+
+  // Get config file path
+  const { path: configPath, isDefault } = getConfigPath();
+
+  // Try to create default config if it doesn't exist (only for default path)
+  if (isDefault) {
+    await createDefaultConfig(configPath, isDefault);
+  }
+
+  // Load config file
+  const fileConfig = await loadConfigFile(configPath);
+
+  // Validate file config (returns defaults if null/invalid)
+  const validatedFileConfig = validateConfig(fileConfig);
+
+  // Get environment config
+  const envConfig = getEnvConfig();
+
+  // Get CLI config
+  const cliConfig = cliArgsToConfig(cliArgs);
+
+  // Merge configs: file < env < cli
+  const mergedConfig = {
+    ...validatedFileConfig,
+    ...envConfig,
+    ...cliConfig,
+  };
+
+  // Final validation with Zod
+  const result = configSchema.safeParse(mergedConfig);
+
+  if (result.success) {
+    configInstance = result.data;
+  } else {
+    // Log validation issues as warnings
+    result.error.issues.forEach((issue) => {
+      console.warn(
+        `Warning: Config validation error at '${issue.path.join(".")}': ${issue.message}`
+      );
+    });
+    // Fall back to defaults
+    configInstance = getDefaultConfig();
+  }
+
+  return configInstance;
+}
+
+/**
+ * Get the initialized configuration
+ *
+ * @throws Error if config has not been initialized via initializeConfig()
+ * @returns The configuration object
+ */
+export function getConfig(): Config {
+  if (configInstance === null) {
+    throw new Error(
+      "Config not initialized. Call initializeConfig() first before using getConfig()."
+    );
+  }
+  return configInstance;
+}
+
+/**
+ * Reset the config singleton (useful for testing)
+ */
+export function resetConfig(): void {
+  configInstance = null;
+  setCliConfigPath(undefined);
+}