@topce/pizx 0.4.0 → 0.5.0

package/README.md

@@ -2,6 +2,8 @@
 
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/topce?style=social&logo=github)](https://github.com/sponsors/topce)
 
+![pizx — zx fork with native Pi AI integration](github-social-banner.png)
+
 > **zx fork with native Pi AI integration** — 15 template tags for shell scripting, AI text generation, coding agents, agentic patterns, communication, and orchestration topologies.
 
 ## Quick Start
@@ -46,7 +48,7 @@ npm install @topce/pizx
 
 **Prerequisites:**
 - Node.js >= 22.19.0
-- [Pi AI](https://github.com/earendil-works/pi-ai) installed and configured (`pi auth login`)
+- [Pi AI](https://github.com/earendil-works/pi) installed and configured (`pi auth login`)
 - Shell commands from [zx](https://github.com/google/zx) (`$`, `cd`, `echo`, `fetch`, etc.)
 
 ## Writing Scripts
@@ -66,16 +68,25 @@ echo(intro)
 ```js
 import { $, π, Π, Ρ, Φ, Σ } from '@topce/pizx'
 
+// Greek letters work everywhere...
 const output = await $`ls src/ | grep '.ts'`
 console.log(output.stdout)
 
 const review = await π`review this code for issues:\n${output.stdout}`
 console.log(review.text)
 
-// Use the coding agent to fix issues
-await Π`fix the TypeScript errors in src/`
+// ...and so do English word aliases:
+import { pi, Pi, ralph, fleet, subagent } from '@topce/pizx'
+
+const answer = await pi`explain async/await`
+await Pi`fix the TypeScript errors in src/`
+await fleet`review all files in src/`
 ```
 
+> **English word aliases**: Every Greek letter tag has an English alternative.
+> `pi` (alias for `π`), `Pi` (alias for `Π`), `fleet` (alias for `Φ`), `ralph` (alias for `Ρ`),
+> `pipeline` (alias for `Λ`), etc. — use whichever style you prefer. See [full mapping](#english-aliases) below.
+
 ### CLI Quick Queries
 
 ```bash
@@ -126,6 +137,24 @@ Each tag has detailed documentation in [`docs/`](docs/):
 | `Χ` | Chi | Analyze traces → extract patterns | [docs/chi.md](docs/chi.md) |
 | `Τ` | Tau | Define schema → write → refine → consolidate | [docs/tau.md](docs/tau.md) |
 
+### English Aliases
+
+Every Greek letter tag has an equivalent English word. They're interchangeable — use whichever style you prefer.
+
+| Greek | English | Greek | English |
+|-------|---------|-------|---------|
+| `π` | `pi` | `Π` | `Pi` |
+| `Ρ` | `ralph` | `Φ` | `fleet` |
+| `Σ` | `subagent` | `Δ` | `debate` |
+| `Λ` | `pipeline` | `Ψ` | `critique` |
+| `Ω` | `orchestrator` | `Ν` | `team` |
+| `Θ` | `thread` | `Μ` | `memory` |
+| `Β` | `broadcast` | `Α` | `adaptive` |
+| `Γ` | `graph` | `Χ` | `learn` |
+| `Τ` | `store` | | |
+
+See [`english-examples/`](english-examples/) for runnable examples using all English aliases.
+
 ## Architecture
 
 See [docs/decisions/](docs/decisions/) for Architecture Decision Records covering the key design choices:
@@ -395,3 +424,10 @@ See [`examples/`](examples/) for runnable examples of every pattern and feature:
 ## License
 
 MIT
+
+## Credits
+
+Built on the shoulders of two outstanding tools:
+
+- [**zx**](https://github.com/google/zx) by [Anton Medvedev](https://github.com/antonmedv) — the original shell scripting tool for Node.js that popularized template-tag ergonomics for command execution. pizx preserves every zx API (`$`, `cd`, `echo`, `fetch`, `chalk`, etc.) unchanged.
+- [**Pi**](https://github.com/earendil-works/pi) by Mario Zechner / Earendil Works — the unified LLM API and coding agent harness that powers all `π`, `Π`, and pattern tags through `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent`.

package/dist/cli.js

@@ -367,7 +367,8 @@ ${skillContext}` : skillContext;
       reasoning: opts.thinkingLevel ?? "medium",
       thinkingBudgets: opts.thinkingBudgets,
       timeoutMs: opts.timeoutMs,
-      maxRetries: opts.maxRetries
+      maxRetries: opts.maxRetries,
+      apiKey: opts.apiKey
     }
   );
   const durationMs = Date.now() - t0;
@@ -904,9 +905,9 @@ var defaults4 = {
   rounds: 1
 };
 var CritiqueRound = class {
-  constructor(content, critique, round) {
+  constructor(content, critique2, round) {
     this.content = content;
-    this.critique = critique;
+    this.critique = critique2;
     this.round = round;
   }
   content;
@@ -970,12 +971,12 @@ Revise the content based on the critique.`,
     }
     if (!opts.quiet) process.stderr.write(`  \u2192 Critiquing (round ${r + 1})...
 `);
-    const critique = await ask(currentContent, {
+    const critique2 = await ask(currentContent, {
       ...opts,
       model: plannerModel,
       system: mergeSystem(opts.system, CRITIQUE_SYSTEM)
     });
-    critiqueRounds.push(new CritiqueRound(currentContent, critique, r));
+    critiqueRounds.push(new CritiqueRound(currentContent, critique2, r));
   }
   const t1 = Date.now();
   const finalContent = currentContent;
@@ -2461,21 +2462,21 @@ ${prompt}`, {
   }
   return { keys, roles: roles.slice(0, agentCount), assignments };
 }
-function formatStore(store) {
-  const entries = Object.entries(store).filter(([, v]) => v);
+function formatStore(store2) {
+  const entries = Object.entries(store2).filter(([, v]) => v);
   if (entries.length === 0) return "(empty \u2014 you are the first contributor)";
   return entries.map(([k, v]) => `[${k}]: ${v}`).join("\n\n");
 }
-function mergeEntry(store, key, content) {
-  if (store[key]) {
-    store[key] += `
+function mergeEntry(store2, key, content) {
+  if (store2[key]) {
+    store2[key] += `
 
 ${content}`;
   } else {
-    store[key] = content;
+    store2[key] = content;
   }
 }
-async function executeRound(roles, assignments, store, round, opts) {
+async function executeRound(roles, assignments, store2, round, opts) {
   const workerModel = opts.workerModel ?? opts.model;
   const isWrite = round === 1;
   const operation = isWrite ? "write" : "update";
@@ -2483,7 +2484,7 @@ async function executeRound(roles, assignments, store, round, opts) {
     roles.map(async (role) => {
       const assignedKeys = assignments.get(role) ?? ["General"];
       const keysStr = assignedKeys.join(", ");
-      const storeText = formatStore(store);
+      const storeText = formatStore(store2);
       const systemPrompt = isWrite ? WRITE_SYSTEM(role, keysStr).replace("{store}", storeText) : UPDATE_SYSTEM(role, keysStr).replace("{store}", storeText);
       const task = isWrite ? `Write your initial findings to your assigned keys: ${keysStr}` : `Review the shared context and update your entries for keys: ${keysStr}`;
       const response = await ask(task, {
@@ -2495,7 +2496,7 @@ async function executeRound(roles, assignments, store, round, opts) {
     })
   );
   const entries = [];
-  const newStore = { ...store };
+  const newStore = { ...store2 };
   for (const r of roundResults) {
     if (r.status !== "fulfilled") continue;
     const { role, response } = r.value;
@@ -2518,8 +2519,8 @@ async function executeRound(roles, assignments, store, round, opts) {
   }
   return { entries, store: newStore };
 }
-async function consolidateStore(task, store, opts) {
-  const storeText = formatStore(store);
+async function consolidateStore(task, store2, opts) {
+  const storeText = formatStore(store2);
   return ask(
     `Original task: ${task}
 
@@ -2560,7 +2561,7 @@ async function execute14(pieces, args, opts) {
     }
   }
   const allEntries = [];
-  let store = {};
+  let store2 = {};
   for (let round = 1; round <= totalRounds; round++) {
     const label = round === 1 ? "Writing" : "Updating";
     if (!opts.quiet) process.stderr.write(`  \u2192 Round ${round}/${totalRounds}: ${label}...
@@ -2568,15 +2569,15 @@ async function execute14(pieces, args, opts) {
     const { entries, store: updatedStore } = await executeRound(
       roles,
       assignments,
-      store,
+      store2,
       round,
       opts
     );
     allEntries.push(...entries);
-    store = updatedStore;
+    store2 = updatedStore;
   }
   if (!opts.quiet) process.stderr.write("  \u2192 Consolidating store...\n");
-  const synthesis = await consolidateStore(task, store, { ...opts, plannerModel });
+  const synthesis = await consolidateStore(task, store2, { ...opts, plannerModel });
   if (!opts.quiet && opts.qualityCheck) process.stderr.write("  \u2192 Quality review...\n");
   const qualityReview = await runQualityReview(task, synthesis, opts);
   const t1 = Date.now();
@@ -2587,7 +2588,7 @@ async function execute14(pieces, args, opts) {
     `Entries: ${allEntries.length}`,
     `Synthesis: ${synthesis}`
   ].join("\n\n");
-  return new TauOutput(summary, allEntries, store, synthesis, t0, t1, qualityReview);
+  return new TauOutput(summary, allEntries, store2, synthesis, t0, t1, qualityReview);
 }
 var \u03A4 = createPatternTag(defaults14, execute14);
 
@@ -2628,10 +2629,10 @@ The conversation so far:
 Respond as your role. Be specific, build on or challenge what others have said.
 Keep your response under 200 words.`;
 var SYNTHESIS_SYSTEM6 = `You are a neutral facilitator. Synthesize the multi-agent conversation thread into a clear, actionable conclusion. Weigh the evidence, resolve conflicts, and present the best path forward.`;
-function buildThreadPrompt(role, thread) {
+function buildThreadPrompt(role, thread2) {
   return THREAD_PROMPT.replace("{role}", role).replace(
     "{thread}",
-    thread || "(This is the first message in the thread.)"
+    thread2 || "(This is the first message in the thread.)"
   );
 }
 async function execute15(pieces, args, opts) {
@@ -2649,17 +2650,17 @@ async function execute15(pieces, args, opts) {
 `);
   }
   const messages = [];
-  let thread = `Topic: ${topic}
+  let thread2 = `Topic: ${topic}
 `;
   for (let turn = 1; turn <= maxTurns; turn++) {
     if (!opts.quiet) process.stderr.write(`  \u2192 Turn ${turn}/${maxTurns}
 `);
     for (let a = 0; a < roles.length; a++) {
       const role = roles[a] ?? `Agent ${a + 1}`;
-      const prompt = buildThreadPrompt(role, thread);
+      const prompt = buildThreadPrompt(role, thread2);
       const response = await ask(prompt, { ...opts, model: workerModel });
       messages.push(new ThreadMessage(role, turn, response));
-      thread += `
+      thread2 += `
 [${role}] (Turn ${turn}): ${response}
 `;
     }
@@ -2669,7 +2670,7 @@ async function execute15(pieces, args, opts) {
     `Topic: ${topic}
 
 Conversation thread:
-${thread}
+${thread2}
 
 Synthesize a clear, actionable conclusion.`,
     {
@@ -2689,6 +2690,23 @@ Synthesize a clear, actionable conclusion.`,
 }
 var \u0398 = createPatternTag(defaults15, execute15);
 
+// src/patterns/index.ts
+var ralph = \u03A1;
+var fleet = \u03A6;
+var subagent = \u03A3;
+var debate = \u0394;
+var pipeline = \u039B;
+var critique = \u03A8;
+var orchestrator = \u03A9;
+var thread = \u0398;
+var memory = \u039C;
+var broadcast = \u0392;
+var adaptive = \u0391;
+var graph = \u0393;
+var team = \u039D;
+var learn = \u03A7;
+var store = \u03A4;
+
 // src/pi.ts
 import {
   streamSimple
@@ -2776,7 +2794,8 @@ function makeOpts(opts) {
     reasoning: opts.thinkingLevel,
     thinkingBudgets: opts.thinkingBudgets,
     timeoutMs: opts.timeoutMs,
-    maxRetries: opts.maxRetries
+    maxRetries: opts.maxRetries,
+    apiKey: opts.apiKey
   };
 }
 async function run(pieces, args, opts) {
@@ -3147,6 +3166,23 @@ async function runScriptMode(scriptPath) {
   g.\u0392 = \u0392;
   g.\u0391 = \u0391;
   g.\u0393 = \u0393;
+  g.pi = \u03C0;
+  g.Pi = \u03A0;
+  g.ralph = ralph;
+  g.fleet = fleet;
+  g.subagent = subagent;
+  g.debate = debate;
+  g.pipeline = pipeline;
+  g.critique = critique;
+  g.orchestrator = orchestrator;
+  g.thread = thread;
+  g.memory = memory;
+  g.broadcast = broadcast;
+  g.adaptive = adaptive;
+  g.graph = graph;
+  g.team = team;
+  g.learn = learn;
+  g.store = store;
   const { createRequire: createRequire2 } = await import("node:module");
   const __filename = absPath;
   const __dirname = path.dirname(absPath);