@cephalization/phoenix-insight 0.1.0 → 0.3.0

package/src/snapshot/context.ts

@@ -39,6 +39,131 @@ interface PromptInfo {
   updatedAt?: string;
 }
 
+// =============================================================================
+// Static Section Templates
+// =============================================================================
+
+/**
+ * Quick Start section for external agents - appears at the top for discoverability
+ */
+const QUICK_START_SECTION = `## Quick Start for External Agents
+
+This is a **read-only snapshot** of Phoenix observability data. You cannot modify this data.
+
+### Key Files to Start With
+
+| File | Description |
+|------|-------------|
+| \`/phoenix/projects/index.jsonl\` | List of all projects with traces |
+| \`/phoenix/datasets/index.jsonl\` | List of all datasets |
+| \`/phoenix/experiments/index.jsonl\` | List of all experiments |
+| \`/phoenix/prompts/index.jsonl\` | List of all prompts |
+
+### How to Parse Each File Format
+
+**JSONL files** (\`.jsonl\`): One JSON object per line
+\`\`\`bash
+# Read all lines as a JSON array
+cat /phoenix/projects/index.jsonl | jq -s '.'
+
+# Process each line individually
+while read -r line; do echo "$line" | jq '.name'; done < /phoenix/projects/index.jsonl
+
+# Get first N items
+head -n 5 /phoenix/projects/index.jsonl | jq -s '.'
+\`\`\`
+
+**JSON files** (\`.json\`): Standard JSON format
+\`\`\`bash
+# Read and pretty-print
+cat /phoenix/projects/my-project/metadata.json | jq '.'
+
+# Extract specific field
+cat /phoenix/projects/my-project/metadata.json | jq '.name'
+\`\`\`
+
+**Markdown files** (\`.md\`): Plain text prompt templates
+\`\`\`bash
+# Read prompt template
+cat /phoenix/prompts/my-prompt/versions/v1.md
+\`\`\`
+
+### Common Operations
+
+\`\`\`bash
+# List all project names
+cat /phoenix/projects/index.jsonl | jq -r '.name'
+
+# Count spans in a project
+wc -l < /phoenix/projects/my-project/spans/index.jsonl
+
+# Find spans with errors
+cat /phoenix/projects/my-project/spans/index.jsonl | jq 'select(.status_code == "ERROR")'
+
+# Get dataset examples
+cat /phoenix/datasets/my-dataset/examples.jsonl | jq -s '.' | head -n 100
+
+# Search across all files
+grep -r "error" /phoenix/
+\`\`\``;
+
+/**
+ * Directory Structure section showing the snapshot layout
+ */
+const DIRECTORY_STRUCTURE_SECTION = `## Directory Structure
+
+\`\`\`
+/phoenix/
+  _context.md                    # This file - start here!
+  /projects/
+    index.jsonl                  # List of all projects
+    /{project_name}/
+      metadata.json              # Project details
+      /spans/
+        index.jsonl              # Span data (may be sampled)
+        metadata.json            # Span snapshot metadata
+  /datasets/
+    index.jsonl                  # List of all datasets
+    /{dataset_name}/
+      metadata.json              # Dataset details
+      examples.jsonl             # Dataset examples
+  /experiments/
+    index.jsonl                  # List of all experiments
+    /{experiment_id}/
+      metadata.json              # Experiment details
+      runs.jsonl                 # Experiment runs
+  /prompts/
+    index.jsonl                  # List of all prompts
+    /{prompt_name}/
+      metadata.json              # Prompt details
+      /versions/
+        index.jsonl              # Version list
+        /{version_id}.md         # Version template
+  /_meta/
+    snapshot.json                # Snapshot metadata
+\`\`\``;
+
+/**
+ * What You Can Do section describing available operations
+ */
+const WHAT_YOU_CAN_DO_SECTION = `## What You Can Do
+
+- **Explore**: ls, cat, grep, find, jq, awk, sed
+- **Fetch more data**: \`px-fetch-more spans --project <name> --limit 500\`
+- **Fetch specific trace**: \`px-fetch-more trace --trace-id <id>\``;
+
+/**
+ * Data Freshness section with refresh instructions
+ */
+const DATA_FRESHNESS_SECTION = `## Data Freshness
+
+This is a **read-only snapshot**. Data may have changed since capture.
+Run with \`--refresh\` to get latest data.`;
+
+// =============================================================================
+// Main Context Generation
+// =============================================================================
+
 /**
  * Generates a _context.md summary file for the Phoenix snapshot
  * This provides human and agent-readable context about what data is available
@@ -47,17 +172,54 @@ export async function generateContext(
   mode: ExecutionMode,
   metadata: ContextMetadata
 ): Promise<void> {
-  const lines: string[] = [];
-
-  // Header
-  lines.push("# Phoenix Snapshot Context");
-  lines.push("");
-
   // Collect stats from the snapshot
   const stats = await collectSnapshotStats(mode);
 
-  // What's Here section
+  // Build the dynamic "What's Here" section
+  const whatsHereSection = buildWhatsHereSection(stats, metadata);
+
+  // Build the dynamic "Recent Activity" section (may be empty)
+  const recentActivitySection = buildRecentActivitySection(stats);
+
+  // Compose the full context document
+  const content = [
+    "# Phoenix Snapshot Context",
+    "",
+    QUICK_START_SECTION,
+    "",
+    whatsHereSection,
+    recentActivitySection,
+    DIRECTORY_STRUCTURE_SECTION,
+    "",
+    WHAT_YOU_CAN_DO_SECTION,
+    "",
+    DATA_FRESHNESS_SECTION,
+  ].join("\n");
+
+  // Write the context file
+  await mode.writeFile("/phoenix/_context.md", content);
+}
+
+// =============================================================================
+// Dynamic Section Builders
+// =============================================================================
+
+/**
+ * Builds the "What's Here" section with project/dataset/experiment/prompt summaries
+ */
+function buildWhatsHereSection(
+  stats: {
+    projects: ProjectStats[];
+    datasets: DatasetInfo[];
+    experiments: ExperimentInfo[];
+    prompts: PromptInfo[];
+  },
+  metadata: ContextMetadata
+): string {
+  const lines: string[] = [];
+
   lines.push("## What's Here");
+  lines.push("");
 
   // Projects summary
   if (stats.projects.length > 0) {
@@ -115,81 +277,40 @@ export async function generateContext(
   );
   lines.push("");
 
-  // Recent Activity section (if we have recent data)
-  const recentActivity = getRecentActivity(stats);
-  if (recentActivity.length > 0) {
-    lines.push("## Recent Activity");
-    for (const activity of recentActivity) {
-      lines.push(`- ${activity}`);
-    }
-    lines.push("");
-  }
+  return lines.join("\n");
+}
 
-  // What You Can Do section
-  lines.push("## What You Can Do");
-  lines.push("- **Explore**: ls, cat, grep, find, jq, awk, sed");
-  lines.push(
-    "- **Fetch more data**: `px-fetch-more spans --project <name> --limit 500`"
-  );
-  lines.push(
-    "- **Fetch specific trace**: `px-fetch-more trace --trace-id <id>`"
-  );
-  lines.push("");
+/**
+ * Builds the "Recent Activity" section if there are recent updates
+ * Returns an empty string if no recent activity
+ */
+function buildRecentActivitySection(stats: {
+  projects: ProjectStats[];
+  datasets: DatasetInfo[];
+  experiments: ExperimentInfo[];
+  prompts: PromptInfo[];
+}): string {
+  const activities = getRecentActivity(stats);
 
-  // Data Freshness section
-  lines.push("## Data Freshness");
-  lines.push(
-    "This is a **read-only snapshot**. Data may have changed since capture."
-  );
-  lines.push("Run with `--refresh` to get latest data.");
-  lines.push("");
+  if (activities.length === 0) {
+    return "";
+  }
 
-  // File Formats section
-  lines.push("## File Formats");
-  lines.push(
-    "- `.jsonl` files: One JSON object per line, use `jq -s` to parse as array"
-  );
-  lines.push("- `.json` files: Standard JSON");
-  lines.push("- `.md` files: Markdown (prompt templates)");
+  const lines: string[] = [];
+  lines.push("## Recent Activity");
+  lines.push("");
+  for (const activity of activities) {
+    lines.push(`- ${activity}`);
+  }
   lines.push("");
 
-  // Directory Structure section
-  lines.push("## Directory Structure");
-  lines.push("```");
-  lines.push("/phoenix/");
-  lines.push("  _context.md                    # This file");
-  lines.push("  /projects/");
-  lines.push("    index.jsonl                  # List of all projects");
-  lines.push("    /{project_name}/");
-  lines.push("      metadata.json              # Project details");
-  lines.push("      /spans/");
-  lines.push("        index.jsonl              # Span data (may be sampled)");
-  lines.push("        metadata.json            # Span snapshot metadata");
-  lines.push("  /datasets/");
-  lines.push("    index.jsonl                  # List of all datasets");
-  lines.push("    /{dataset_name}/");
-  lines.push("      metadata.json              # Dataset details");
-  lines.push("      examples.jsonl             # Dataset examples");
-  lines.push("  /experiments/");
-  lines.push("    index.jsonl                  # List of all experiments");
-  lines.push("    /{experiment_id}/");
-  lines.push("      metadata.json              # Experiment details");
-  lines.push("      runs.jsonl                 # Experiment runs");
-  lines.push("  /prompts/");
-  lines.push("    index.jsonl                  # List of all prompts");
-  lines.push("    /{prompt_name}/");
-  lines.push("      metadata.json              # Prompt details");
-  lines.push("      /versions/");
-  lines.push("        index.jsonl              # Version list");
-  lines.push("        /{version_id}.md         # Version template");
-  lines.push("  /_meta/");
-  lines.push("    snapshot.json                # Snapshot metadata");
-  lines.push("```");
-
-  // Write the context file
-  await mode.writeFile("/phoenix/_context.md", lines.join("\n"));
+  return lines.join("\n");
 }
 
+// =============================================================================
+// Data Collection
+// =============================================================================
+
 /**
  * Collects statistics from the snapshot filesystem
  */
@@ -358,6 +479,10 @@ async function collectSnapshotStats(mode: ExecutionMode): Promise<{
   return result;
 }
 
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
 /**
  * Determines the status of an experiment based on its run counts
  */

package/src/snapshot/utils.ts

@@ -0,0 +1,140 @@
+/**
+ * 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;
+}