@pewterzz/karp 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# karp
+
+A local-first CLI that recalls shell commands using a local LLM. Ask in plain English, get back the exact command — nothing else.
+
+```
+karp "how do I check disk usage"
+# df -h
+```
+
+No cloud. No subscriptions. Runs against any llama.cpp or Ollama server.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- A running llama.cpp or Ollama instance (local or on your network)
+
+---
+
+## Install
+
+```bash
+npm install -g karp
+```
+
+---
+
+## Setup
+
+Point karp at your LLM server:
+
+```bash
+karp config url http://localhost:8080/v1/chat/completions
+karp config model your-model-name.gguf
+```
+
+For Ollama, the URL is typically `http://localhost:11434/v1/chat/completions`.
+
+Config is stored at `~/.karp/config.json`.
+
+---
+
+## Usage
+
+### Ask a question
+
+```bash
+karp "how do I recursively copy a folder"
+# cp -r src/ dest/
+```
+
+The model returns only the command. If you include words like "explain" or "what does", it gives a one-sentence description instead.
+
+### Store a command
+
+```bash
+karp store "docker run -d -p 3000:8080 ghcr.io/open-webui/open-webui:main"
+```
+
+Stored commands are used as context when you ask questions. The more you store, the better karp gets at recalling your specific setup.
+
+### List stored commands
+
+```bash
+karp list
+# 1. docker run -d -p 3000:8080 ghcr.io/open-webui/open-webui:main
+# 2. df -h
+# ...
+```
+
+### Remove a stored command
+
+```bash
+karp remove 2
+```
+
+### Repeat the last answer
+
+```bash
+karp last
+```
+
+Prints the previous response instantly — no LLM call.
+
+### View or change config
+
+```bash
+karp config                        # show all config
+karp config url <url>              # set server URL
+karp config model <model>          # set model name
+karp config top_k <n>              # results sent to LLM (default: 10)
+karp config threshold <n>          # store size before BM25 kicks in (default: 15)
+```
+
+---
+
+## How it works
+
+Queries go to your local LLM with a strict system prompt that enforces command-only output. When your store grows past `threshold` entries, karp runs **BM25** over your saved commands to find the most relevant ones before sending them as context — keeping prompts short and responses accurate.
+
+All data lives in `~/.karp/`:
+
+| File | Purpose |
+|---|---|
+| `config.json` | Server URL, model, and tuning options |
+| `commands.md` | Your stored commands |
+| `.last` | Cache of the last response |
+
+---
+
+## License
+
+MIT

package/bin/karp.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const KARP_DIR = path.join(os.homedir(), ".karp");
+const STORE_PATH = path.join(KARP_DIR, "commands.md");
+const LAST_PATH = path.join(KARP_DIR, ".last");
+const CONFIG_PATH = path.join(KARP_DIR, "config.json");
+
+const DEFAULTS = {
+  url: "http://localhost:8080/v1/chat/completions",
+  model: "",
+  top_k: 10,
+  threshold: 15,
+};
+
+function loadConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) return { ...DEFAULTS };
+  try {
+    return { ...DEFAULTS, ...JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8")) };
+  } catch {
+    console.error("warning: config.json is invalid, using defaults");
+    return { ...DEFAULTS };
+  }
+}
+
+function saveConfig(cfg) {
+  fs.mkdirSync(KARP_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+const cfg = loadConfig();
+const LLAMA_URL = cfg.url;
+const MODEL = cfg.model;
+const RETRIEVE_THRESHOLD = cfg.threshold;
+const TOP_K = cfg.top_k;
+
+const SYSTEM_PROMPT =
+  "You are a command recall assistant. " +
+  "When the user asks about a command, return ONLY the exact command — nothing else. " +
+  "No explanation, no markdown, no code fences, no punctuation around it. " +
+  "If the user explicitly asks for an explanation (e.g. 'explain', 'what does', 'why'), " +
+  "give a single short sentence. " +
+  "If you cannot find a matching command, reply with: not found";
+
+// --- storage ---
+
+function loadStore() {
+  if (!fs.existsSync(STORE_PATH)) return [];
+  return fs.readFileSync(STORE_PATH, "utf8").split("\n").filter((l) => l.trim());
+}
+
+function saveStore(lines) {
+  fs.mkdirSync(KARP_DIR, { recursive: true });
+  fs.writeFileSync(STORE_PATH, lines.join("\n") + (lines.length ? "\n" : ""));
+}
+
+// --- BM25 retrieval ---
+
+function tokenize(text) {
+  return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+
+function bm25Rank(query, docs, k1 = 1.5, b = 0.75) {
+  const qTokens = new Set(tokenize(query));
+  if (!qTokens.size) return docs;
+
+  const tokenized = docs.map(tokenize);
+  const avgLen = tokenized.reduce((s, t) => s + t.length, 0) / tokenized.length;
+  const N = docs.length;
+
+  const df = {};
+  for (const tokens of tokenized)
+    for (const term of new Set(tokens)) df[term] = (df[term] ?? 0) + 1;
+
+  function score(tokens) {
+    const tf = {};
+    for (const t of tokens) tf[t] = (tf[t] ?? 0) + 1;
+    let s = 0;
+    for (const term of qTokens) {
+      if (!tf[term]) continue;
+      const idf = Math.log((N - (df[term] ?? 0) + 0.5) / ((df[term] ?? 0) + 0.5) + 1);
+      const tfNorm = (tf[term] * (k1 + 1)) / (tf[term] + k1 * (1 - b + (b * tokens.length) / avgLen));
+      s += idf * tfNorm;
+    }
+    return s;
+  }
+
+  return docs
+    .map((doc, i) => ({ doc, score: score(tokenized[i]) }))
+    .sort((a, b) => b.score - a.score)
+    .map(({ doc }) => doc);
+}
+
+function retrieve(query, stored) {
+  if (stored.length <= RETRIEVE_THRESHOLD) return stored;
+  return bm25Rank(query, stored).slice(0, TOP_K);
+}
+
+// --- LLM call ---
+
+async function ask(query) {
+  if (!LLAMA_URL || !MODEL) {
+    console.error('error: run `karp config url <url>` and `karp config model <model>` first');
+    process.exit(1);
+  }
+  const stored = loadStore();
+  let context = "";
+  if (stored.length) {
+    const relevant = retrieve(query, stored);
+    context =
+      "Stored commands the user has saved:\n" +
+      relevant.map((cmd, i) => `  ${i + 1}. ${cmd}`).join("\n") +
+      "\n\n";
+  }
+
+  const res = await fetch(LLAMA_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model: MODEL,
+      messages: [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: `${context}${query}` },
+      ],
+      max_tokens: 150,
+      temperature: 0.1,
+      stream: false,
+    }),
+  }).catch((e) => {
+    console.error(`error: cannot reach llama.cpp server — ${e.message}`);
+    process.exit(1);
+  });
+
+  const data = await res.json();
+  const result = data.choices[0].message.content.trim();
+  console.log(result);
+  fs.mkdirSync(KARP_DIR, { recursive: true });
+  fs.writeFileSync(LAST_PATH, result + "\n");
+}
+
+// --- commands ---
+
+function cmdStore(command) {
+  const lines = loadStore();
+  lines.push(command);
+  saveStore(lines);
+  console.log(`stored (${lines.length}): ${command}`);
+}
+
+function cmdList() {
+  const lines = loadStore();
+  if (!lines.length) { console.log("no commands stored yet"); return; }
+  lines.forEach((l, i) => console.log(`${i + 1}. ${l}`));
+}
+
+function cmdLast() {
+  if (!fs.existsSync(LAST_PATH)) {
+    console.error("no previous answer");
+    process.exit(1);
+  }
+  console.log(fs.readFileSync(LAST_PATH, "utf8").trim());
+}
+
+function cmdRemove(arg) {
+  const n = parseInt(arg, 10);
+  const lines = loadStore();
+  if (isNaN(n) || n < 1 || n > lines.length) {
+    console.error(`error: no entry ${arg} (have ${lines.length})`);
+    process.exit(1);
+  }
+  const [removed] = lines.splice(n - 1, 1);
+  saveStore(lines);
+  console.log(`removed: ${removed}`);
+}
+
+function cmdConfig(args) {
+  const current = loadConfig();
+  if (!args.length) {
+    console.log(JSON.stringify(current, null, 2));
+    return;
+  }
+  const [key, ...rest] = args;
+  const validKeys = Object.keys(DEFAULTS);
+  if (!validKeys.includes(key)) {
+    console.error(`unknown config key: ${key}\nvalid keys: ${validKeys.join(", ")}`);
+    process.exit(1);
+  }
+  if (!rest.length) {
+    console.log(`${key} = ${JSON.stringify(current[key])}`);
+    return;
+  }
+  const raw = rest.join(" ");
+  const value = key === "top_k" || key === "threshold" ? parseInt(raw, 10) : raw;
+  current[key] = value;
+  saveConfig(current);
+  console.log(`set ${key} = ${JSON.stringify(value)}`);
+}
+
+function usage() {
+  console.log(
+    "usage:\n" +
+    '  karp "query"              ask the model, returns exact command\n' +
+    "  karp last                 print the last answer again\n" +
+    '  karp store "command"      save a command to local memory\n' +
+    "  karp list                 show all stored commands\n" +
+    "  karp remove <n>           remove stored command by number\n" +
+    "  karp config               show current config\n" +
+    "  karp config <key> <val>   set a config value\n" +
+    "                            keys: url, model, top_k, threshold"
+  );
+}
+
+// --- main ---
+
+const args = process.argv.slice(2);
+if (!args.length) { usage(); process.exit(0); }
+
+const [cmd, ...rest] = args;
+if (cmd === "last") cmdLast();
+else if (cmd === "store") { if (!rest.length) { console.error('usage: karp store "command"'); process.exit(1); } cmdStore(rest.join(" ")); }
+else if (cmd === "list") cmdList();
+else if (cmd === "remove") { if (!rest.length) { console.error("usage: karp remove <n>"); process.exit(1); } cmdRemove(rest[0]); }
+else if (cmd === "config") cmdConfig(rest);
+else if (cmd === "-h" || cmd === "--help" || cmd === "help") usage();
+else await ask(args.join(" "));

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@pewterzz/karp",
+  "version": "1.0.0",
+  "description": "Local-first LLM CLI for instant command recall",
+  "type": "module",
+  "bin": {
+    "karp": "bin/karp.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "cli",
+    "llm",
+    "llama",
+    "ollama",
+    "command-recall",
+    "local-ai",
+    "productivity"
+  ],
+  "author": "pewterzz",
+  "license": "MIT",
+  "preferGlobal": true
+}