pi-eda 0.2.0 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Shivam V Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -13,10 +13,16 @@ The [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) package, for
 custom-agent support and the `/skill:pi-subagents` dispatch pattern the skills
 reference.
 
+For plot review, use Pi interactively in a terminal with inline-image support.
+Leave Pi's default `terminal.showImages` setting enabled so `show` can render
+figures to the user without adding their pixels to model context.
+
 ## Install
 
+Install dependencies & this package:
+
 ```bash
-pi install git:github.com/shivam-v-verma/pi-eda
+pi install npm:pi-subagents
 pi install npm:pi-eda
 ```
 

package/extensions/eda-workflow-tracker.ts

@@ -18,6 +18,7 @@
 
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import type {
   ExtensionAPI,
   ExtensionContext,
@@ -35,9 +36,14 @@ import {
   handleStatus,
   handleClear,
   formatWidgetText,
+  resolveGraphPath,
   reconstructFromBranch,
 } from "./lib/eda-workflow-tracker-core.js";
 
+const bundledGraphPath = fileURLToPath(
+  new URL("../skills/exploring-data/workflow.graph.json", import.meta.url),
+);
+
 const WorkflowTrackerParams = Type.Object({
   action: Type.Union(
     [
@@ -51,7 +57,7 @@ const WorkflowTrackerParams = Type.Object({
   graphPath: Type.Optional(
     Type.String({
       description:
-        "Path to a workflow.graph.json ({ start, edges }) (for init)",
+        "Path to a workflow.graph.json ({ start, edges }); defaults to the bundled EDA graph (for init)",
     }),
   ),
   to: Type.Optional(
@@ -134,17 +140,12 @@ export default function (pi: ExtensionAPI) {
 
       switch (params.action) {
         case "init": {
-          if (!params.graphPath) {
-            result = {
-              graphPath,
-              current,
-              next: [],
-              error: "graphPath required for init",
-            };
-            break;
-          }
+          const selectedGraphPath = resolveGraphPath(
+            params.graphPath,
+            bundledGraphPath,
+          );
           try {
-            const parsed = await loadGraphFile(ctx.cwd, params.graphPath);
+            const parsed = await loadGraphFile(ctx.cwd, selectedGraphPath);
             if (!isValidGraph(parsed)) {
               throw new Error("expected { start: string, edges: object }");
             }
@@ -154,11 +155,11 @@ export default function (pi: ExtensionAPI) {
               graphPath,
               current,
               next: [],
-              error: `failed to load graph at "${params.graphPath}": ${(err as Error).message}`,
+              error: `failed to load graph at "${selectedGraphPath}": ${(err as Error).message}`,
             };
             break;
           }
-          result = handleInit(graph, params.graphPath);
+          result = handleInit(graph, selectedGraphPath);
           graphPath = result.graphPath;
           current = result.current;
           updateWidget(ctx);
@@ -196,6 +197,10 @@ export default function (pi: ExtensionAPI) {
         }
         case "status": {
           result = handleStatus(graph, current, graphPath);
+          if (!graph && current) {
+            result.error =
+              "graph not loaded -- current state was reconstructed but the graph file is unavailable; call init to reload";
+          }
           break;
         }
         case "clear": {

package/extensions/lib/eda-workflow-tracker-core.ts

@@ -11,15 +11,38 @@ export interface WorkflowGraph {
   edges: Record<string, string[]>;
 }
 
-/** True if `value` has the { start: string, edges: object } shape a WorkflowGraph requires. */
+/** True if `value` has a known start node and string-array edges. */
 export function isValidGraph(value: unknown): value is WorkflowGraph {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value as Record<string, unknown>;
-  return (
-    typeof candidate.start === "string" &&
-    typeof candidate.edges === "object" &&
-    candidate.edges !== null
-  );
+  if (
+    typeof candidate.start !== "string" ||
+    typeof candidate.edges !== "object" ||
+    candidate.edges === null ||
+    Array.isArray(candidate.edges)
+  ) {
+    return false;
+  }
+
+  const edges = candidate.edges as Record<string, unknown>;
+  if (
+    !Object.values(edges).every(
+      (targets) =>
+        Array.isArray(targets) &&
+        targets.every((target) => typeof target === "string"),
+    )
+  ) {
+    return false;
+  }
+
+  return allNodes(edges as Record<string, string[]>).has(candidate.start);
+}
+
+export function resolveGraphPath(
+  graphPath: string | undefined,
+  bundledGraphPath: string,
+): string {
+  return graphPath ?? bundledGraphPath;
 }
 
 export interface WorkflowTrackerDetails {

package/extensions/lib/show-core.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure logic for the `show` extension, split out for unit testing without
+ * needing a live ExtensionAPI/TUI (same pattern as eda-workflow-tracker-core.ts).
+ */
+
+import { extname, resolve } from "node:path";
+
+const MEDIA_TYPES: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+};
+
+export function resolveMediaType(path: string): string | undefined {
+  return MEDIA_TYPES[extname(path).toLowerCase()];
+}
+
+export function resolveImagePath(rawPath: string, cwd: string): string {
+  const path = rawPath.startsWith("@") ? rawPath.slice(1) : rawPath;
+  return resolve(cwd, path);
+}

package/extensions/show.ts

@@ -9,19 +9,10 @@
  */
 
 import { readFile, stat } from "node:fs/promises";
-import { extname, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Image, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-
-const MEDIA_TYPES: Record<string, string> = {
-	".png": "image/png",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".gif": "image/gif",
-	".webp": "image/webp",
-	".bmp": "image/bmp",
-};
+import { resolveImagePath, resolveMediaType } from "./lib/show-core.js";
 
 interface ShowDetails {
 	path: string;
@@ -48,12 +39,9 @@ export default function (pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const rawPath = params.path.startsWith("@")
-				? params.path.slice(1)
-				: params.path;
-			const absolutePath = resolve(ctx.cwd, rawPath);
+			const absolutePath = resolveImagePath(params.path, ctx.cwd);
 
-			const mediaType = MEDIA_TYPES[extname(absolutePath).toLowerCase()];
+			const mediaType = resolveMediaType(absolutePath);
 			if (!mediaType) {
 				return {
 					content: [
@@ -107,7 +95,7 @@ export default function (pi: ExtensionAPI) {
 			}
 			return new Image(details.base64, details.mediaType, theme, {
 				maxWidthCells: 80,
-				maxHeightCells: 24,
+				maxHeightCells: 36,
 			});
 		},
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-eda",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Pi tooling for interactive exploratory data analysis.",
   "license": "MIT",
   "author": "Shivam V Verma",
@@ -16,6 +16,7 @@
   ],
   "files": [
     "README.md",
+    "LICENSE",
     "agents",
     "eda.mplstyle.example",
     "extensions",

package/skills/exploring-data/SKILL.md

@@ -25,9 +25,8 @@ what the figure shows, not a conclusion dressed as a finding.
 
 If using this skill, you **must** first:
 
-- Run `init` on `eda-workflow-tracker` with `graphPath:
-  "skills/exploring-data/workflow.graph.json"` for guidance on what stage you
-  should be working on.
+- Run `init` on `eda-workflow-tracker` for guidance on what stage you should be
+  working on.
 - Read `workflow.md` for instructions for each stage.
 
 **Always call `advance` on the `eda-workflow-tracker` when done with a

package/skills/exploring-data/directory-structure.md

@@ -7,8 +7,10 @@ wanted).
 
 ```text
 eda/
+  .gitignore                  # containing `outputs/`
   index.md                    # landing pad for readers -- what's been done,
                                # links to each report below
+  outputs/                    # gitignored data/caches, can be shared across analyses
   customer_churn.md           # a report -- lives directly under eda/
   customer_churn/             # paired folder, same stem as the report file
     scripts/
@@ -35,6 +37,9 @@ eda/
 - Shared code (data loading, plotting helpers, constants) goes in an
   unnumbered `common_<topic>.py` and gets imported from there instead --
   never import one numbered script from another.
+- `eda/outputs/` is a top-level, shared cache. Any script can read from or
+  write to it. No substructure required inside it. Scripts that produce
+  data caches should check-or-recompute so it can be repopulated if needed.
 
 ## Common Mistakes
 

package/skills/exploring-data/plotting.md

@@ -10,8 +10,9 @@ per-type rule that hasn't been stated.
 
 - Generate figures with matplotlib, saved as PNG, following the conventions
   below.
-- Apply the user's `eda.mplstyle` at the top of the script
-  (`plt.style.use("eda")`) and respect user defaults.
+- If `~/.config/matplotlib/stylelib/eda.mplstyle` exists, apply it at the top
+  of the script (`plt.style.use("eda")`) and respect user defaults. Otherwise
+  skip `plt.style.use` and fall back to Defaults below.
 - Visually inspect every figure with the `read` tool before treating it as a
   result -- never make hypotheses from a figure you haven't looked at.
 - `read` is for your own inspection. When you're ready to show the figure to
@@ -30,10 +31,8 @@ per-type rule that hasn't been stated.
 If the user has not set up `eda.mplstyle` or has not offered opinions
 on plot style, use these defaults:
 
-- Colors: `eda.mplstyle` (see the repo-root `eda.mplstyle.example`) defaults to
-  `lightsteelblue` for one color and `Blues`
-  for a colormap -- pick something else only if needed to convey a point, e.g.
-  categorical comparison.
+- Colors: `lightsteelblue` for one color and `Blues` for a colormap -- pick
+  something else only if needed to convey a point, e.g. categorical comparison.
 - Gridlines: none. Spines / ticks: matplotlib defaults -- don't add or strip
   either.
 - Titles: Be brief -- words must earn their space. Detailed descriptions belong

package/skills/exploring-data/workflow.graph.json

@@ -5,13 +5,11 @@
     "Peek at the data": ["Propose/ask a question"],
     "Propose/ask a question": ["Build script/plot"],
     "Build script/plot": ["Light or heavy?"],
-    "Light or heavy?": ["Reread script", "Dispatch script-checker"],
-    "Reread script": ["Build script/plot", "Run now, this session"],
+    "Light or heavy?": ["Reread and run script", "Dispatch script-checker"],
+    "Reread and run script": ["Build script/plot", "Summarize the answer"],
     "Dispatch script-checker": ["Build script/plot", "Dispatch job-runner"],
-    "Run now, this session": ["Summarize the answer"],
     "Dispatch job-runner": ["Summarize the answer"],
-    "Summarize the answer": ["Continue analysis or lock in?"],
-    "Continue analysis or lock in?": [
+    "Summarize the answer": [
       "Propose/ask a question",
       "/skill:finishing-exploratory-data-analysis"
     ]

package/skills/exploring-data/workflow.md

@@ -7,7 +7,7 @@ exactly that stage of work; and then call `advance` before starting the next
 stage. Call `status` whenever you need to know where you are instead of holding
 it in your head.
 
-At the end of every turn, ask yourself if you have accomplished the exit 
+At the end of every turn, ask yourself if you have accomplished the exit
 condition to `advance` to the next stage.
 
 - If yes, `advance` should **always** be your first tool call.
@@ -28,10 +28,10 @@ condition to `advance` to the next stage.
 - Expect the scope to narrow or shift as the data yields a story during
   this analysis. This step is purely for you to ground yourself.
 - You should **never** be running code at this stage. If the user has
-  already offered specific questions/approaches, you must confirm your
-  understanding and then `advance`.
+  already offered a specific question/approach, it establishes the scope but
+  you must confirm a report name before advancing.
 - `advance` condition: the user has confirmed the scope of the analysis and has
-  given a report name; or the user has already requested a specific question.
+  given a report name.
 
 ### `Peek at the data`
 
@@ -94,9 +94,9 @@ We want to increase iteration speed and not waste user time.
   treating as heavy."
 - `advance` condition: you understand the computational cost of the script.
 
-### `Reread script`
+### `Reread and run script`
 
-Light path: Reread the script as a sanity check.
+Light path: reread the script as a sanity check, then run it in this session.
 
 - Does it match the user's stated intent/framing, does each nontrivial
   transform do what it should?
@@ -105,13 +105,10 @@ Light path: Reread the script as a sanity check.
 - This is a deliberately lower bar than the heavy path. A subtle mistake here
   can also be caught downstream in `/skill:finishing-exploratory-data-analysis`.
   We just want to sanity check here.
-- `advance` condition: you have reread the script and haven't found issues.
-
-### `Run now, this session`
-
-Light path continuation: run the smoke-tested script/plot in this session.
-
-- `advance` condition: you have run the script successfully on the data.
+- Once the reread finds no issues, run the smoke-tested script/plot in this
+  session.
+- `advance` condition: you have reread the script, found no issues, and run
+  it successfully on the data.
 
 ### `Dispatch script-checker`
 
@@ -149,14 +146,10 @@ Heavy path continuation: launch the `job-runner` only once the
 - `show` the figure(s) to the user, then summarize briefly with bullets.
 - Core principle: the user decides the interpretation. Continue interrogating
   the user until it makes sense to you and is consistent with the dataset.
-- `advance` condition: you understand the user's interpretation of the figure.
-
-### `Continue analysis or lock in?`
-
-- Ask the user whether to continue with another question or lock in the
-  analysis; keep interrogating until they pick one. "Next question" loops back
-  to `Propose/ask a question`, "finish analysis" exits to the finishing skill.
-- `advance` condition: the user has decided to continue the session or finish it.
+- Once the user makes a clear interpretation, ask whether to continue with another
+  question or lock in the analysis. Keep interrogating until they pick one.
+- `advance` condition: you understand the user's interpretation of the
+  figure, and the user has decided to continue the session or finish it.
 
 ### `/skill:finishing-exploratory-data-analysis`
 
@@ -178,7 +171,7 @@ Figure/analysis seems meaningful, ready to write up or commit.
 | Silently skipping the smoke test on a "just read cache and plot" script | Only skip for zero-computation cached-read-and-plot, and state that justification explicitly |
 | Trusting a sanity check that only ran on an easy/symmetric case | Pick a case that could actually have failed, especially for matching/ordering/canonicalization logic |
 | Checking that a smoke test ran fast/clean without looking at what it produced | Glance at the actual output values -- a clean run on garbage isn't a pass |
-| Running a light-path script without rereading it first because it's "just quick" | Reread against the stated intent/framing before running -- speed doesn't waive the check, it just changes who does it |
+| Running a light-path script without rereading it first because it's "just quick" | Reread against the stated intent/framing before running -- speed doesn't waive the check, it just changes who does it. Both happen in the same `Reread and run script` stage, but the reread must come first |
 | Launching a heavy scale-up "while the `script-checker` runs in the background" instead of waiting for it | Confirm the `script-checker` came back clean before launching -- don't launch and plan to fold feedback in later |
 | Letting 2+ small edits pile up on a heavy-path script since the last `script-checker` dispatch because none felt big enough alone | Dispatch again once 2+ edits have landed |
 | Treating a mid-work `script-checker` pass as covering the finishing skill's lock-in checkpoint | Different gate, different artifact -- a pending or completed `script-checker` pass never substitutes for it |