pocket-agent 0.1.0 → 0.1.1

package/README.md

@@ -1,140 +1,142 @@
-# pocket-agent
-
-**Plan-driven agent orchestration for Node.** You plug in a planner, executor, and evaluator (e.g. backed by any LLM); the framework runs the loop-plan → steps → evaluate → retry or replan-so you don’t re-implement it.
-
-**Author:** sam_thewise
-
----
-
-### In a nutshell
-
-- **Goal in → plan → steps → evaluate → done.** You give a goal; we get a machine-readable plan, run steps in dependency order, evaluate completion, and retry or replan as needed.
-- **You bring:** planner, executor, evaluator (and optional tools). **We bring:** scheduling, lifecycle events, retries, and structured outputs.
-- **Pocket** = small, drop-in. **Agent** = orchestration that turns your LLM into a plan-first workflow.
-
----
-
-### What this does (plain terms)
-
-You give a **goal** (e.g. “Summarize this contract” or “How does this codebase work?”). The library turns that into a **plan**: a ordered list of **steps**, each with a clear objective and inputs/outputs. It runs the steps one by one (or in order when steps depend on each other), uses your **model** (LLM) and optional **tools** to do the work, then asks an **evaluator** whether each step is actually done. If not, it retries or replans; when everything’s done, you get a single result with all the step outputs. You don’t wire the loop yourself-you plug in *how* to plan, *how* to run a step, and *how* to judge completion; the **runner** does the rest.
-
-**Terms you’ll see:**
-
-| Term | Meaning |
-|------|--------|
-| **Runner** | The thing you create with `createAgentRunner` or `createQuickAgent`. It runs the full loop: create plan → run steps → evaluate → retry/replan → return result. |
-| **Plan** | A list of **steps** (each has an id, objective, inputs, outputs, dependencies). The runner executes steps in an order that respects dependencies. |
-| **Planner** | Your code (or a built-in) that, given a goal and context, produces a **plan**. “What steps do we need to achieve this goal?” |
-| **Executor** | Your code (or a built-in) that runs *one* step. It gets the step definition, resolved inputs, and optional **model** and **tools**; it returns the step’s output (or error). “Do this step.” |
-| **Evaluator** | Your code (or a built-in LLM evaluator) that, given a step and its attempt result, says whether the step is **complete**, should **retry**, **replan**, or **failed**. “Is this step actually done?” |
-| **Tools** | Optional functions the executor can call during a step (e.g. read a file, call an API). The plan says which steps are allowed to use which tools. |
-| **Model** | The LLM (OpenAI, Anthropic, Gemini, Ollama, etc.) used by the executor (and often the evaluator). You pass it via a **provider** + API key or a custom adapter. |
-| **Provider** | Shortcut name for a model backend: `"openai"`, `"anthropic"`, `"gemini"`, `"ollama"`, `"lmstudio"`. Setting `provider` lets the library create the model adapter and a default evaluator from env. |
-
-Once these mean something, the rest of the doc (quick start, fluent plan, default evaluators, contracts) should fall into place.
-
----
-
-## Features
-
-- **Explicit plans** - Machine-readable step list before execution
-- **Dependency-ordered execution** - Steps run when their dependencies are satisfied
-- **Lifecycle events** - `run.started`, `plan.created`, `step.started`, `step.completed`, `run.completed`, etc.
-- **Bounded retries** - Evaluator-driven completion with configurable retry policy
-- **Structured outputs** - Per-step and final run outputs
-
-## Install
-
-```bash
-npm install pocket-agent
-```
-
-## Examples (quick start)
-
-### 1. Super quick start (one call)
-
-Set your API key in the environment, then create and run in two lines. Uses a single-step plan and the LLM to answer; no planner or executor code to write.
-
-```ts
-import { createQuickAgent } from "pocket-agent";
-
-const runner = createQuickAgent({ provider: "openai" });
-const run = await runner.run({ goal: "What is 2+2? Explain in one sentence." });
-
-console.log(run.outputs?.answer);
-```
-
-Supported `provider`: `"openai"` | `"anthropic"` | `"gemini"` | `"ollama"` | `"lmstudio"`. Each reads from env (e.g. `OPENAI_API_KEY`, `OPENAI_MODEL`). Optional `modelConfig` and `systemPrompt`. No tools in this mode; for tools and multi-step plans, see the docs below.
-
-### 2. Goal-only with LLM-generated steps
-
-Give a goal and let the LLM invent the plan (the list of steps). Use `createGoalDrivenAgent` with `useLLMPlanner: true`:
-
-```ts
-import { createGoalDrivenAgent } from "pocket-agent";
-
-const runner = createGoalDrivenAgent({
-  provider: "openai",
-  useLLMPlanner: true,
-  llmPlannerOptions: { maxSteps: 5, planHint: "Use 2–4 clear steps." },
-});
-
-const run = await runner.run({
-  goal: "Explain what an API is in three short steps: definition, why it matters, one example.",
-});
-
-console.log(run.plan.steps);  // steps were generated by the LLM
-console.log(run.outputs);
-```
-
-### 3. Custom planner and executor
-
-When you want your own plan or execution logic, use `createAgentRunner` with a planner, executor, and evaluator (or `provider` for a default evaluator):
-
-```ts
-import { createAgentRunner } from "pocket-agent";
-
-const runner = createAgentRunner({
-  provider: "openai",
-  planner,   // your Planner or use createFixedPlanPlanner(steps)
-  executor,  // your StepExecutor or use createDefaultExecutor({ model })
-  tools: {}, // optional
-});
-
-const run = await runner.run({
-  goal: "Find the latest contract, extract payment terms, and summarize risks.",
-  context: { customerId: "abc123" },
-});
-```
-
-For fluent step definitions and a minimal planner/executor/evaluator, see the docs below.
-
----
-
-## Documentation
-
-More guides live under **`docs/`** (links work on GitHub):
-
-| Doc | Description |
-|-----|-------------|
-| [Fluent plan and defaults](docs/fluent-plan-and-defaults.md) | Build plans with `step()` + `createFixedPlanPlanner` and run with `createDefaultExecutor`. |
-| [Custom planner and executor](docs/custom-planner-executor.md) | Minimal planner, executor, and evaluator (full code). |
-| [Default evaluators and providers](docs/default-evaluators-and-providers.md) | Provider table, `provider` in `createAgentRunner`, adapters. |
-| [Contracts](docs/contracts.md) | Planner, StepExecutor, StepEvaluator, Tools. |
-| [Events](docs/events.md) | Event-driven usage with `runner.start()`. |
-| [API key and local models](docs/api-key-and-local-models.md) | Cloud (OpenAI), Ollama, LM Studio, tools, project planner. |
-| [Examples](docs/examples.md) | All runnable scripts (`npm run example:*`). |
-
-## Scripts
-
-- `npm run build` - compile TypeScript to `dist/`
-- `npm test` - run tests
-- `npm run test:watch` - run tests in watch mode
-- `npm run example:quick-start` - quick-start example
-- `npm run example:fluent-plan` - fluent plan example
-- `npm run example:goal-driven-llm` - goal-only with LLM-generated steps
-- `npm run example:minimal` - minimal planner/executor/evaluator (no API key)
-- `npm run example:openai` - full run with tools (OpenAI or local)
-- `npm run example:planner` - project structure from a description
-
-See [docs/examples.md](docs/examples.md) for the full list and what each script does.
+# pocket-agent
+
+**[→ GitHub](https://github.com/sam-thewise/pocket-agent)**
+
+**Plan-driven agent orchestration for Node.** You plug in a planner, executor, and evaluator (e.g. backed by any LLM); the framework runs the loop-plan → steps → evaluate → retry or replan-so you don’t re-implement it.
+
+**Author:** sam_thewise
+
+---
+
+### In a nutshell
+
+- **Goal in → plan → steps → evaluate → done.** You give a goal; we get a machine-readable plan, run steps in dependency order, evaluate completion, and retry or replan as needed.
+- **You bring:** planner, executor, evaluator (and optional tools). **We bring:** scheduling, lifecycle events, retries, and structured outputs.
+- **Pocket** = small, drop-in. **Agent** = orchestration that turns your LLM into a plan-first workflow.
+
+---
+
+### What this does (plain terms)
+
+You give a **goal** (e.g. “Summarize this contract” or “How does this codebase work?”). The library turns that into a **plan**: a ordered list of **steps**, each with a clear objective and inputs/outputs. It runs the steps one by one (or in order when steps depend on each other), uses your **model** (LLM) and optional **tools** to do the work, then asks an **evaluator** whether each step is actually done. If not, it retries or replans; when everything’s done, you get a single result with all the step outputs. You don’t wire the loop yourself-you plug in *how* to plan, *how* to run a step, and *how* to judge completion; the **runner** does the rest.
+
+**Terms you’ll see:**
+
+| Term | Meaning |
+|------|--------|
+| **Runner** | The thing you create with `createAgentRunner` or `createQuickAgent`. It runs the full loop: create plan → run steps → evaluate → retry/replan → return result. |
+| **Plan** | A list of **steps** (each has an id, objective, inputs, outputs, dependencies). The runner executes steps in an order that respects dependencies. |
+| **Planner** | Your code (or a built-in) that, given a goal and context, produces a **plan**. “What steps do we need to achieve this goal?” |
+| **Executor** | Your code (or a built-in) that runs *one* step. It gets the step definition, resolved inputs, and optional **model** and **tools**; it returns the step’s output (or error). “Do this step.” |
+| **Evaluator** | Your code (or a built-in LLM evaluator) that, given a step and its attempt result, says whether the step is **complete**, should **retry**, **replan**, or **failed**. “Is this step actually done?” |
+| **Tools** | Optional functions the executor can call during a step (e.g. read a file, call an API). The plan says which steps are allowed to use which tools. |
+| **Model** | The LLM (OpenAI, Anthropic, Gemini, Ollama, etc.) used by the executor (and often the evaluator). You pass it via a **provider** + API key or a custom adapter. |
+| **Provider** | Shortcut name for a model backend: `"openai"`, `"anthropic"`, `"gemini"`, `"ollama"`, `"lmstudio"`. Setting `provider` lets the library create the model adapter and a default evaluator from env. |
+
+Once these mean something, the rest of the doc (quick start, fluent plan, default evaluators, contracts) should fall into place.
+
+---
+
+## Features
+
+- **Explicit plans** - Machine-readable step list before execution
+- **Dependency-ordered execution** - Steps run when their dependencies are satisfied
+- **Lifecycle events** - `run.started`, `plan.created`, `step.started`, `step.completed`, `run.completed`, etc.
+- **Bounded retries** - Evaluator-driven completion with configurable retry policy
+- **Structured outputs** - Per-step and final run outputs
+
+## Install
+
+```bash
+npm install pocket-agent
+```
+
+## Examples (quick start)
+
+### 1. Super quick start (one call)
+
+Set your API key in the environment, then create and run in two lines. Uses a single-step plan and the LLM to answer; no planner or executor code to write.
+
+```ts
+import { createQuickAgent } from "pocket-agent";
+
+const runner = createQuickAgent({ provider: "openai" });
+const run = await runner.run({ goal: "What is 2+2? Explain in one sentence." });
+
+console.log(run.outputs?.answer);
+```
+
+Supported `provider`: `"openai"` | `"anthropic"` | `"gemini"` | `"ollama"` | `"lmstudio"`. Each reads from env (e.g. `OPENAI_API_KEY`, `OPENAI_MODEL`). Optional `modelConfig` and `systemPrompt`. No tools in this mode; for tools and multi-step plans, see the docs below.
+
+### 2. Goal-only with LLM-generated steps
+
+Give a goal and let the LLM invent the plan (the list of steps). Use `createGoalDrivenAgent` with `useLLMPlanner: true`:
+
+```ts
+import { createGoalDrivenAgent } from "pocket-agent";
+
+const runner = createGoalDrivenAgent({
+  provider: "openai",
+  useLLMPlanner: true,
+  llmPlannerOptions: { maxSteps: 5, planHint: "Use 2–4 clear steps." },
+});
+
+const run = await runner.run({
+  goal: "Explain what an API is in three short steps: definition, why it matters, one example.",
+});
+
+console.log(run.plan.steps);  // steps were generated by the LLM
+console.log(run.outputs);
+```
+
+### 3. Custom planner and executor
+
+When you want your own plan or execution logic, use `createAgentRunner` with a planner, executor, and evaluator (or `provider` for a default evaluator):
+
+```ts
+import { createAgentRunner } from "pocket-agent";
+
+const runner = createAgentRunner({
+  provider: "openai",
+  planner,   // your Planner or use createFixedPlanPlanner(steps)
+  executor,  // your StepExecutor or use createDefaultExecutor({ model })
+  tools: {}, // optional
+});
+
+const run = await runner.run({
+  goal: "Find the latest contract, extract payment terms, and summarize risks.",
+  context: { customerId: "abc123" },
+});
+```
+
+For fluent step definitions and a minimal planner/executor/evaluator, see the docs below.
+
+---
+
+## Documentation
+
+More guides (absolute links so they work on npm and GitHub):
+
+| Doc | Description |
+|-----|-------------|
+| [Fluent plan and defaults](https://github.com/sam-thewise/pocket-agent/blob/master/docs/fluent-plan-and-defaults.md) | Build plans with `step()` + `createFixedPlanPlanner` and run with `createDefaultExecutor`. |
+| [Custom planner and executor](https://github.com/sam-thewise/pocket-agent/blob/master/docs/custom-planner-executor.md) | Minimal planner, executor, and evaluator (full code). |
+| [Default evaluators and providers](https://github.com/sam-thewise/pocket-agent/blob/master/docs/default-evaluators-and-providers.md) | Provider table, `provider` in `createAgentRunner`, adapters. |
+| [Contracts](https://github.com/sam-thewise/pocket-agent/blob/master/docs/contracts.md) | Planner, StepExecutor, StepEvaluator, Tools. |
+| [Events](https://github.com/sam-thewise/pocket-agent/blob/master/docs/events.md) | Event-driven usage with `runner.start()`. |
+| [API key and local models](https://github.com/sam-thewise/pocket-agent/blob/master/docs/api-key-and-local-models.md) | Cloud (OpenAI), Ollama, LM Studio, tools, project planner. |
+| [Examples](https://github.com/sam-thewise/pocket-agent/blob/master/docs/examples.md) | All runnable scripts (`npm run example:*`). |
+
+## Scripts
+
+- `npm run build` - compile TypeScript to `dist/`
+- `npm test` - run tests
+- `npm run test:watch` - run tests in watch mode
+- `npm run example:quick-start` - quick-start example
+- `npm run example:fluent-plan` - fluent plan example
+- `npm run example:goal-driven-llm` - goal-only with LLM-generated steps
+- `npm run example:minimal` - minimal planner/executor/evaluator (no API key)
+- `npm run example:openai` - full run with tools (OpenAI or local)
+- `npm run example:planner` - project structure from a description
+
+See [Examples](https://github.com/sam-thewise/pocket-agent/blob/master/docs/examples.md) for the full list and what each script does.

package/dist/adapters/createLLMEvaluator.js

@@ -27,34 +27,34 @@ function buildPrompt(input, options) {
         ? `\nPrior attempts: ${priorAttempts.length}. Last had status: ${priorAttempts[priorAttempts.length - 1]?.status}.`
         : "";
     const jsonInstruction = options.useJsonBlock
-        ? `Respond with a single JSON object in a fenced code block (\\\`\\\`\\\`json ... \\\`\\\`\\\`). The JSON must have:
-- "verdict": one of "complete", "retry", "needs_replan", "failed"
-- "reasons": array of short strings explaining your decision
-- "missingCriteria" (optional): array of criteria not yet satisfied
-- "confidence" (optional): number 0-1
+        ? `Respond with a single JSON object in a fenced code block (\\\`\\\`\\\`json ... \\\`\\\`\\\`). The JSON must have:
+- "verdict": one of "complete", "retry", "needs_replan", "failed"
+- "reasons": array of short strings explaining your decision
+- "missingCriteria" (optional): array of criteria not yet satisfied
+- "confidence" (optional): number 0-1
 - "suggestedAction" (optional): string for retry/replan`
-        : `Respond with exactly:
-VERDICT: complete|retry|needs_replan|failed
-REASONS: one or more short lines
+        : `Respond with exactly:
+VERDICT: complete|retry|needs_replan|failed
+REASONS: one or more short lines
 Optional lines: MISSING_CRITERIA: ... CONFIDENCE: 0-1 SUGGESTED_ACTION: ...`;
-    return `You are evaluating whether a step in a plan-driven agent run is complete.
-
-Step:
-- id: ${step.id}
-- name: ${step.name ?? step.id}
-- objective: ${step.objective}
-- expected outputs: ${(step.outputs ?? []).join(", ")}
-
-Completion criteria (all should be satisfied for "complete"):
-- ${criteria || "(none specified)"}
-
-Attempt result:
-- status: ${attemptResult.status}
-- structuredOutput: ${structuredStr}
-- rawOutput (excerpt): ${rawTruncated}${priorSummary}
-
-Is this step complete, should we retry, replan, or mark failed?
-
+    return `You are evaluating whether a step in a plan-driven agent run is complete.
+
+Step:
+- id: ${step.id}
+- name: ${step.name ?? step.id}
+- objective: ${step.objective}
+- expected outputs: ${(step.outputs ?? []).join(", ")}
+
+Completion criteria (all should be satisfied for "complete"):
+- ${criteria || "(none specified)"}
+
+Attempt result:
+- status: ${attemptResult.status}
+- structuredOutput: ${structuredStr}
+- rawOutput (excerpt): ${rawTruncated}${priorSummary}
+
+Is this step complete, should we retry, replan, or mark failed?
+
 ${jsonInstruction}`;
 }
 function parseResponse(content, stepId, attempt, useJsonBlock) {

package/dist/defaults/llmPlanner.js

@@ -59,33 +59,33 @@ function buildPlanPrompt(input, options) {
         ? `Available tools (use only if needed): ${input.availableTools.map((t) => t.name).join(", ")}.`
         : "No tools are available; use only reasoning/transform steps.";
     const constraintStr = constraints.length > 0 ? `Constraints: ${constraints.join("; ")}` : "";
-    return `You are a planning assistant. Given a goal and context, output a plan as a single JSON object.
-
-Goal: ${goal}
-
-Context (key-value): ${JSON.stringify(context)}
-
-${constraintStr ? constraintStr + "\n\n" : ""}${toolList}
-
-${hint}
-
-Respond with ONLY a JSON object in this exact shape (no markdown, no explanation):
-\`\`\`json
-{
-  "steps": [
-    {
-      "id": "unique_snake_case_id",
-      "name": "Human-readable step name",
-      "objective": "What this step must do",
-      "outputs": ["output_key"],
-      "dependencies": [],
-      "inputsFromContext": ["goal"],
-      "inputsFromStep": []
-    }
-  ]
-}
-\`\`\`
-
+    return `You are a planning assistant. Given a goal and context, output a plan as a single JSON object.
+
+Goal: ${goal}
+
+Context (key-value): ${JSON.stringify(context)}
+
+${constraintStr ? constraintStr + "\n\n" : ""}${toolList}
+
+${hint}
+
+Respond with ONLY a JSON object in this exact shape (no markdown, no explanation):
+\`\`\`json
+{
+  "steps": [
+    {
+      "id": "unique_snake_case_id",
+      "name": "Human-readable step name",
+      "objective": "What this step must do",
+      "outputs": ["output_key"],
+      "dependencies": [],
+      "inputsFromContext": ["goal"],
+      "inputsFromStep": []
+    }
+  ]
+}
+\`\`\`
+
 Rules: Step ids must be unique. Later steps can list earlier step ids in "dependencies" and reference their outputs in "inputsFromStep" as { "stepId": "id", "key": "output_key" }. Use "inputsFromContext" for keys from the run context (e.g. "goal"). Output only the JSON block.`;
 }
 /**

package/package.json

@@ -1,50 +1,54 @@
-{
-  "name": "pocket-agent",
-  "version": "0.1.0",
-  "description": "Reusable Node.js framework for plan-driven agent execution",
-  "author": "sam_thewise",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "url": "https://github.com/sam-thewise/pocket-agent",
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "example": "tsx examples/run-example.ts",
-    "example:openai": "tsx examples/run-with-openai.ts",
-    "example:planner": "tsx examples/run-project-planner.ts",
-    "example:quick-start": "tsx examples/run-quick-start.ts",
-    "example:fluent-plan": "tsx examples/run-fluent-plan.ts",
-    "example:goal-driven-llm": "tsx examples/run-goal-driven-llm.ts",
-    "example:minimal": "tsx examples/run-minimal.ts",
-    "lint": "eslint src --ext .ts"
-  },
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "optionalDependencies": {
-    "@anthropic-ai/sdk": "^0.30.0",
-    "@google/genai": "^1.0.0",
-    "openai": "^4.52.0"
-  },
-  "devDependencies": {
-    "@anthropic-ai/sdk": "^0.30.0",
-    "@google/genai": "^1.0.0",
-    "@types/node": "^20.10.0",
-    "openai": "^4.52.0",
-    "typescript": "^5.3.0",
-    "tsx": "^4.7.0",
-    "vitest": "^1.2.0"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "pocket-agent",
+  "version": "0.1.1",
+  "description": "Reusable Node.js framework for plan-driven agent execution",
+  "author": "sam_thewise",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sam-thewise/pocket-agent"
+  },
+  "homepage": "https://github.com/sam-thewise/pocket-agent#readme",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "example": "tsx examples/run-example.ts",
+    "example:openai": "tsx examples/run-with-openai.ts",
+    "example:planner": "tsx examples/run-project-planner.ts",
+    "example:quick-start": "tsx examples/run-quick-start.ts",
+    "example:fluent-plan": "tsx examples/run-fluent-plan.ts",
+    "example:goal-driven-llm": "tsx examples/run-goal-driven-llm.ts",
+    "example:minimal": "tsx examples/run-minimal.ts",
+    "lint": "eslint src --ext .ts"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "@google/genai": "^1.0.0",
+    "openai": "^4.52.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "@google/genai": "^1.0.0",
+    "@types/node": "^20.10.0",
+    "openai": "^4.52.0",
+    "typescript": "^5.3.0",
+    "tsx": "^4.7.0",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}