promptpilot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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

@@ -0,0 +1,283 @@
+# promptpilot
+
+`promptpilot` is a lightweight TypeScript npm package that sits between your app or CLI workflow and a target LLM. It rewrites prompts locally through Ollama when available, stores reusable session context, compresses older turns, and emits a Claude-friendly final prompt for shell pipelines or application code.
+
+It is designed for local-first workflows on machines like an 18 GB MacBook. By default, `promptpilot` inspects your local Ollama installation and auto-selects a small optimization model, preferring `qwen2.5:3b`, `phi3:mini`, and `llama3.2:3b` in that order. The package still lets you override the model manually when needed.
+
+## Why local Ollama
+
+- It keeps prompt optimization close to your workflow.
+- It reduces external API calls for prompt rewriting.
+- It lets you use a small, fast model for compression before sending the final prompt to a stronger remote model like Claude.
+- It automatically picks an installed local model that fits a low-memory workflow.
+
+## What it does
+
+- Accepts a raw prompt plus optional metadata.
+- Persists session context across turns.
+- Retrieves relevant prior context for the next prompt.
+- Summarizes older context when budgets get tight.
+- Preserves critical instructions and constraints.
+- Estimates token usage before and after optimization.
+- Outputs plain prompt text or structured JSON.
+- Works cleanly with Claude CLI shell pipelines.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+npm test
+ollama pull qwen2.5:3b
+promptpilot optimize "explain binary search simply" --plain
+promptpilot optimize "continue my study guide" --session dsa --save-context --plain | claude
+```
+
+After publishing, install from npm with:
+
+```bash
+npm install -g promptpilot
+```
+
+## Install and build
+
+```bash
+npm install
+npm run build
+```
+
+Install directly from a local tarball:
+
+```bash
+npm pack
+npm install -g ./promptpilot-0.1.0.tgz
+```
+
+## Library usage
+
+```ts
+import { createOptimizer, optimizePrompt } from "promptpilot";
+
+const optimizer = createOptimizer({
+  provider: "ollama",
+  host: "http://localhost:11434",
+  contextStore: "local"
+});
+
+const result = await optimizer.optimize({
+  prompt: "help me write a better follow up email for a startup internship",
+  task: "email",
+  tone: "professional but human",
+  targetModel: "claude",
+  sessionId: "internship-search"
+});
+
+console.log(result.optimizedPrompt);
+
+const oneOff = await optimizePrompt({
+  prompt: "continue working on my essay intro",
+  task: "essay",
+  sessionId: "essay1"
+});
+
+console.log(oneOff.finalPrompt);
+```
+
+## Claude CLI usage
+
+Plain shell output:
+
+```bash
+promptpilot optimize "help me explain binary search simply" --session study --plain
+```
+
+Piping into Claude CLI:
+
+```bash
+promptpilot optimize "help me explain binary search simply" --session study --plain | claude
+```
+
+Using stdin in a shell pipeline:
+
+```bash
+cat notes.txt | promptpilot optimize --task summarization --plain | claude
+```
+
+Saving context between calls:
+
+```bash
+promptpilot optimize "continue working on my essay intro" --session essay1 --task essay --save-context --plain
+```
+
+Debugging token usage:
+
+```bash
+promptpilot optimize "summarize these lecture notes" --session notes1 --json --debug
+```
+
+Clearing a session:
+
+```bash
+promptpilot optimize --session essay1 --clear-session
+```
+
+Node `child_process` example:
+
+```ts
+import { spawn } from "node:child_process";
+
+const prompt = spawn("promptpilot", [
+  "optimize",
+  "continue my study guide",
+  "--session",
+  "dsa",
+  "--plain"
+]);
+
+const claude = spawn("claude", [], { stdio: ["pipe", "inherit", "inherit"] });
+prompt.stdout.pipe(claude.stdin);
+```
+
+## Session context
+
+By default, if you pass a `sessionId`, `promptpilot` stores optimized turns in a local session store. The default store is JSON files under `~/.promptpilot/sessions`. A SQLite store is also available when `node:sqlite` or `better-sqlite3` is present.
+
+If you do not pass `ollamaModel` or `--model`, `promptpilot` asks Ollama which models are installed and picks the best small model for the job. For most workflows it prefers `qwen2.5:3b`, then `phi3:mini`, then `llama3.2:3b`. For code-heavy prompts it will prefer `qwen2.5-coder:3b` when that model is installed. If only oversized local models are available, it warns and falls back to deterministic heuristic optimization instead of silently using a heavy model.
+
+Each session stores:
+
+- User prompts
+- Optimized prompts
+- Final prompts
+- Extracted constraints
+- Context summaries
+- Timestamps
+- Optional tags
+
+Context retrieval prefers:
+
+- Pinned constraints
+- Task-aligned prior turns
+- Recent prompts
+- Named entities and recurring references
+- Stored summaries when budgets are tight
+
+## Token reduction
+
+`promptpilot` estimates token usage heuristically for:
+
+- The new prompt
+- Retrieved session context
+- The final composed prompt
+
+You can control the budgets with:
+
+- `maxInputTokens`
+- `maxContextTokens`
+- `maxTotalTokens`
+
+When context is too large, it ranks prior turns, preserves high-value constraints, summarizes older context, and drops lower-signal items.
+
+## CLI
+
+```bash
+promptpilot optimize "write me a better prompt for asking claude to summarize lecture notes"
+```
+
+Supported flags:
+
+- `--session <id>`
+- `--model <name>` to override auto-selection
+- `--mode <mode>`
+- `--task <task>`
+- `--tone <tone>`
+- `--preset <preset>`
+- `--target-model <name>`
+- `--output-format <text>`
+- `--max-length <n>`
+- `--tag <value>` repeatable
+- `--pin-constraint <text>` repeatable
+- `--store <local|sqlite>`
+- `--storage-dir <path>`
+- `--sqlite-path <path>`
+- `--plain`
+- `--json`
+- `--debug`
+- `--save-context`
+- `--no-context`
+- `--max-total-tokens <n>`
+- `--max-context-tokens <n>`
+- `--max-input-tokens <n>`
+- `--clear-session`
+- `--bypass-optimization`
+
+If no prompt argument is provided, `promptpilot optimize` will read the raw prompt from stdin.
+
+## Public API
+
+Main exports:
+
+- `createOptimizer`
+- `optimizePrompt`
+- `PromptOptimizer`
+- `OllamaClient`
+- `FileSessionStore`
+- `SQLiteSessionStore`
+
+Supported modes:
+
+- `clarity`
+- `concise`
+- `detailed`
+- `structured`
+- `persuasive`
+- `compress`
+- `claude_cli`
+
+Supported presets:
+
+- `code`
+- `email`
+- `essay`
+- `support`
+- `summarization`
+- `chat`
+
+## File structure
+
+```text
+src/
+  index.ts
+  types.ts
+  errors.ts
+  cli.ts
+  core/
+    optimizer.ts
+    ollamaClient.ts
+    systemPrompt.ts
+    contextManager.ts
+    tokenEstimator.ts
+    contextCompressor.ts
+  storage/
+    fileSessionStore.ts
+    sqliteSessionStore.ts
+  utils/
+    validation.ts
+    logger.ts
+    json.ts
+test/
+```
+
+## Safety and fallback behavior
+
+If Ollama is unavailable, `promptpilot` falls back to a deterministic local formatter that still preserves constraints and emits a Claude-compatible final prompt. Empty prompts are rejected, timeouts are supported, and hard token budget failures throw explicit errors.
+
+## Future improvements
+
+- Semantic retrieval for context
+- Better token counting by model
+- Prompt scoring
+- Local embeddings for relevance search
+- Response-aware context updates
+- Cache layer
+- Benchmark suite

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { createOptimizer } from './index.js';
+
+type CliWriter = {
+    write(message: string): void;
+};
+interface CliIO {
+    stdout: CliWriter;
+    stderr: CliWriter;
+    stdin?: NodeJS.ReadStream;
+}
+interface CliDependencies {
+    createOptimizer: typeof createOptimizer;
+    readStdin: (stdin?: NodeJS.ReadStream) => Promise<string>;
+}
+declare function runCli(argv: string[], io?: CliIO, dependencies?: CliDependencies): Promise<number>;
+
+export { runCli };