@voidwire/llm-summarize 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rudy Ruiz
+
+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,89 @@
+# llm-summarize
+
+Fast LLM-powered text summarization for observability and logging.
+
+## Philosophy
+
+- **Config-driven** - No hardcoded defaults, specify exact provider/model
+- **Prismis pattern** - Secrets in .env, references in config.toml via `env:VAR_NAME`
+- **Fast and cheap** - Designed for high-volume summarization (haiku/gpt-4.1-mini)
+- **Composable** - JSON output pipes to jq and other tools
+
+## Installation
+
+```bash
+cd llmcli-tools
+./install.sh llm-summarize
+```
+
+## Configuration
+
+### Config file: `~/.config/llm/config.toml`
+
+```toml
+[llm]
+provider = "openai"
+model = "gpt-4.1-mini"
+api_key = "env:OPENAI_API_KEY"
+max_tokens = 50
+```
+
+### Secrets file: `~/.config/llm/.env`
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Usage
+
+```bash
+llm-summarize <text>
+llm-summarize --stdin
+echo "text" | llm-summarize --stdin
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--model <name>` | Override model from config |
+| `--max-tokens <n>` | Max output tokens |
+| `--stdin` | Read text from stdin |
+| `-h, --help` | Show help |
+
+## Output
+
+```json
+{
+  "summary": "User saved form data to PostgreSQL.",
+  "model": "gpt-4.1-mini",
+  "tokens_used": 12
+}
+```
+
+## Supported Providers
+
+| Provider | Models | API Key |
+|----------|--------|---------|
+| `anthropic` | claude-3-5-haiku-latest, claude-sonnet-4-20250514 | Required |
+| `openai` | gpt-4.1-mini, gpt-4o | Required |
+| `ollama` | llama3, mistral, gemma3, etc. | Not needed |
+
+### Ollama Configuration
+
+```toml
+[llm]
+provider = "ollama"
+model = "llama3"
+api_base = "http://localhost:11434/api/generate"  # optional, this is default
+max_tokens = 50
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | API error (rate limit, auth, network) |
+| 2 | Client error (missing args, invalid config) |

package/cli.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env bun
+/**
+ * llm-summarize CLI
+ *
+ * Philosophy:
+ * - Fast summaries for observability and logging
+ * - Multi-provider support (Anthropic, OpenAI, Ollama)
+ * - Deterministic JSON output for tooling integration
+ * - Config-driven - no hardcoded defaults
+ *
+ * Usage:
+ *   llm-summarize <text>
+ *   llm-summarize --stdin
+ *   echo "text" | llm-summarize --stdin
+ *
+ * Config: ~/.config/llm/config.toml
+ *   [llm]
+ *   provider = "anthropic"
+ *   model = "claude-3-5-haiku-latest"
+ *   api_key = "env:ANTHROPIC_API_KEY"
+ *   max_tokens = 50
+ *
+ * Secrets: ~/.config/llm/.env
+ *   ANTHROPIC_API_KEY=sk-ant-...
+ *
+ * Exit codes:
+ *   0 - Success
+ *   1 - API error (rate limit, auth, network)
+ *   2 - Client error (missing args, invalid config)
+ */
+
+import { summarize, loadConfig, type SummarizeOptions } from "./index";
+
+/**
+ * Read text from stdin
+ */
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of Bun.stdin.stream()) {
+    chunks.push(Buffer.from(chunk));
+  }
+
+  return Buffer.concat(chunks).toString("utf-8").trim();
+}
+
+/**
+ * Print usage
+ */
+function printUsage(): void {
+  console.error(`
+llm-summarize - Summarize text using LLM APIs
+
+Philosophy:
+  Fast, cheap summaries for observability events.
+  Config-driven - specify exact provider/model.
+  JSON output for tooling integration.
+
+Usage: llm-summarize [options] <text>
+       llm-summarize --stdin
+
+Options:
+  --model <name>        Override model from config
+  --max-tokens <n>      Max output tokens (default: from config or 50)
+  --stdin               Read text from stdin
+  -h, --help            Show this help
+
+Config file: ~/.config/llm/config.toml
+  [llm]
+  provider = "anthropic"
+  model = "claude-3-5-haiku-latest"
+  api_key = "env:ANTHROPIC_API_KEY"
+  max_tokens = 50
+
+Secrets file: ~/.config/llm/.env
+  ANTHROPIC_API_KEY=sk-ant-...
+  OPENAI_API_KEY=sk-...
+
+Environment overrides:
+  LLM_PROVIDER          Override provider
+  LLM_MODEL             Override model
+  LLM_API_KEY           Override API key
+
+Supported providers:
+  anthropic - Claude models (claude-3-5-haiku-latest, claude-sonnet-4-20250514)
+  openai    - GPT models (gpt-4.1-mini, gpt-4o)
+  ollama    - Local models (llama3, mistral, gemma3, etc.) - no API key needed
+
+Examples:
+  # Simple summarization
+  llm-summarize "User requested fix for post-password-reset login failure"
+
+  # With options
+  llm-summarize --max-tokens 30 "Long event description..."
+
+  # From stdin (for piping)
+  echo "Tool: Edit, File: auth.ts, Result: added JWT validation" | llm-summarize --stdin
+
+  # Pipe from another tool
+  cat event.json | jq -r '.description' | llm-summarize --stdin
+`);
+}
+
+interface ParsedArgs {
+  text: string;
+  options: SummarizeOptions;
+}
+
+/**
+ * Parse command-line arguments
+ */
+async function parseArgs(argv: string[]): Promise<ParsedArgs | null> {
+  const args = argv.slice(2);
+
+  // Handle help
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    return null;
+  }
+
+  let modelOverride: string | undefined;
+  let maxTokensOverride: number | undefined;
+  let useStdin = false;
+  let text = "";
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--model" && i + 1 < args.length) {
+      modelOverride = args[++i];
+    } else if (arg === "--max-tokens" && i + 1 < args.length) {
+      maxTokensOverride = parseInt(args[++i], 10);
+    } else if (arg === "--stdin") {
+      useStdin = true;
+    } else if (!arg.startsWith("-")) {
+      text = arg;
+    }
+  }
+
+  // Get text from stdin or argument
+  if (useStdin) {
+    text = await readStdin();
+  }
+
+  return {
+    text,
+    options: {
+      model: modelOverride,
+      maxTokens: maxTokensOverride,
+    },
+  };
+}
+
+/**
+ * Main entry point
+ */
+async function main(): Promise<void> {
+  const parsed = await parseArgs(process.argv);
+
+  if (!parsed) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!parsed.text) {
+    console.log(JSON.stringify({ error: "No text provided" }, null, 2));
+    console.error("Error: No text to summarize");
+    process.exit(2);
+  }
+
+  // Load config and summarize
+  const config = loadConfig();
+  const result = await summarize(parsed.text, config, parsed.options);
+
+  // Output JSON
+  console.log(JSON.stringify(result, null, 2));
+
+  // Diagnostic
+  if (result.summary) {
+    console.error(`✅ Summarized (${result.tokens_used || "?"} tokens)`);
+    process.exit(0);
+  } else {
+    console.error(`❌ ${result.error}`);
+    process.exit(1);
+  }
+}
+
+main();

package/index.ts

@@ -0,0 +1,399 @@
+/**
+ * llm-summarize - Library exports
+ *
+ * Fast LLM-powered text summarization for observability and logging.
+ * Pure functions, no process.exit, no stderr output.
+ *
+ * Usage:
+ *   import { summarize, loadConfig } from "llm-summarize";
+ *   const config = loadConfig();
+ *   const result = await summarize("text to summarize", config);
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface SummarizeResult {
+  summary?: string;
+  error?: string;
+  model?: string;
+  tokens_used?: number;
+}
+
+export interface LLMConfig {
+  provider: string | null;
+  model: string | null;
+  apiKey: string | null;
+  apiBase: string | null;
+  maxTokens: number;
+}
+
+export interface SummarizeOptions {
+  model?: string;
+  maxTokens?: number;
+}
+
+export type ProviderType = "anthropic" | "openai" | "ollama";
+
+// ============================================================================
+// Config Loading
+// ============================================================================
+
+/**
+ * Load environment variables from .env file
+ */
+function loadEnvFile(envPath: string): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  if (!existsSync(envPath)) {
+    return env;
+  }
+
+  try {
+    const content = readFileSync(envPath, "utf-8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+
+      const eqIdx = trimmed.indexOf("=");
+      if (eqIdx === -1) continue;
+
+      const key = trimmed.slice(0, eqIdx).trim();
+      let value = trimmed.slice(eqIdx + 1).trim();
+
+      // Remove quotes if present
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+
+      env[key] = value;
+    }
+  } catch {
+    // Ignore parse errors
+  }
+
+  return env;
+}
+
+/**
+ * Resolve env: references in config values
+ */
+function resolveEnvRef(
+  value: string,
+  envVars: Record<string, string>,
+): string | null {
+  if (value.startsWith("env:")) {
+    const varName = value.slice(4);
+    return envVars[varName] || process.env[varName] || null;
+  }
+  return value;
+}
+
+/**
+ * Load configuration from config.toml with env file support
+ * Config: ~/.config/llm/config.toml
+ * Secrets: ~/.config/llm/.env
+ */
+export function loadConfig(): LLMConfig {
+  const configDir = join(process.env.HOME!, ".config", "llm");
+  const configPath = join(configDir, "config.toml");
+  const envPath = join(configDir, ".env");
+
+  // Load .env file first
+  const envVars = loadEnvFile(envPath);
+
+  // No defaults - config required
+  const config: LLMConfig = {
+    provider: null,
+    model: null,
+    apiKey: null,
+    apiBase: null,
+    maxTokens: 50,
+  };
+
+  if (!existsSync(configPath)) {
+    return config;
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8");
+
+    // Parse [llm] section
+    const providerMatch = content.match(/^\s*provider\s*=\s*"([^"]+)"/m);
+    if (providerMatch) {
+      config.provider = providerMatch[1];
+    }
+
+    const modelMatch = content.match(/^\s*model\s*=\s*"([^"]+)"/m);
+    if (modelMatch) {
+      config.model = modelMatch[1];
+    }
+
+    const apiKeyMatch = content.match(/^\s*api_key\s*=\s*"([^"]+)"/m);
+    if (apiKeyMatch) {
+      config.apiKey = resolveEnvRef(apiKeyMatch[1], envVars);
+    }
+
+    const apiBaseMatch = content.match(/^\s*api_base\s*=\s*"([^"]+)"/m);
+    if (apiBaseMatch) {
+      config.apiBase = apiBaseMatch[1];
+    }
+
+    const maxTokensMatch = content.match(/^\s*max_tokens\s*=\s*(\d+)/m);
+    if (maxTokensMatch) {
+      config.maxTokens = parseInt(maxTokensMatch[1], 10);
+    }
+  } catch {
+    // Ignore parse errors
+  }
+
+  // Environment variables override config
+  if (process.env.LLM_PROVIDER) config.provider = process.env.LLM_PROVIDER;
+  if (process.env.LLM_MODEL) config.model = process.env.LLM_MODEL;
+  if (process.env.LLM_API_KEY) config.apiKey = process.env.LLM_API_KEY;
+
+  return config;
+}
+
+// ============================================================================
+// Provider Implementations
+// ============================================================================
+
+/**
+ * Call Anthropic API
+ */
+async function callAnthropic(
+  text: string,
+  model: string,
+  maxTokens: number,
+  apiKey: string,
+  apiBase?: string,
+): Promise<SummarizeResult> {
+  const endpoint = apiBase || "https://api.anthropic.com/v1/messages";
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: maxTokens,
+        temperature: 0.3,
+        messages: [
+          {
+            role: "user",
+            content: `What was accomplished or decided? One sentence, past tense, focus on actions and outcomes:\n\n${text}`,
+          },
+        ],
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      return {
+        error: `Anthropic API error: ${response.status} ${errorText}`,
+      };
+    }
+
+    const result = await response.json();
+    const content = result.content?.[0]?.text || "";
+
+    return {
+      summary: content.trim(),
+      model,
+      tokens_used: result.usage?.output_tokens,
+    };
+  } catch (error) {
+    return {
+      error: `Anthropic request failed: ${String(error)}`,
+    };
+  }
+}
+
+/**
+ * Call OpenAI API
+ */
+async function callOpenAI(
+  text: string,
+  model: string,
+  maxTokens: number,
+  apiKey: string,
+  apiBase?: string,
+): Promise<SummarizeResult> {
+  const endpoint = apiBase || "https://api.openai.com/v1/chat/completions";
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: maxTokens,
+        temperature: 0.3,
+        messages: [
+          {
+            role: "user",
+            content: `What was accomplished or decided? One sentence, past tense, focus on actions and outcomes:\n\n${text}`,
+          },
+        ],
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      return {
+        error: `OpenAI API error: ${response.status} ${errorText}`,
+      };
+    }
+
+    const result = await response.json();
+    const content = result.choices?.[0]?.message?.content || "";
+
+    return {
+      summary: content.trim(),
+      model,
+      tokens_used: result.usage?.completion_tokens,
+    };
+  } catch (error) {
+    return {
+      error: `OpenAI request failed: ${String(error)}`,
+    };
+  }
+}
+
+/**
+ * Call Ollama API
+ */
+async function callOllama(
+  text: string,
+  model: string,
+  maxTokens: number,
+  apiBase: string,
+): Promise<SummarizeResult> {
+  const endpoint = `${apiBase}/api/generate`;
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        prompt: `What was accomplished or decided? One sentence, past tense, focus on actions and outcomes:\n\n${text}`,
+        stream: false,
+        options: {
+          num_predict: maxTokens,
+          temperature: 0.3,
+        },
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      return {
+        error: `Ollama API error: ${response.status} ${errorText}`,
+      };
+    }
+
+    const result = await response.json();
+    const content = result.response || "";
+
+    return {
+      summary: content.trim(),
+      model,
+      tokens_used: result.eval_count,
+    };
+  } catch (error) {
+    return {
+      error: `Ollama request failed: ${String(error)}`,
+    };
+  }
+}
+
+// ============================================================================
+// Main API
+// ============================================================================
+
+/**
+ * Summarize text using configured LLM
+ *
+ * @param text - Text to summarize
+ * @param config - LLM configuration (from loadConfig())
+ * @param options - Optional overrides for model and maxTokens
+ * @returns SummarizeResult with summary or error
+ */
+export async function summarize(
+  text: string,
+  config: LLMConfig,
+  options?: SummarizeOptions,
+): Promise<SummarizeResult> {
+  const provider = config.provider;
+  const model = options?.model || config.model;
+  const maxTokens = options?.maxTokens || config.maxTokens;
+  const apiKey = config.apiKey;
+
+  // Validate config
+  if (!provider) {
+    return {
+      error: `No provider configured. Set provider in ~/.config/llm/config.toml`,
+    };
+  }
+
+  if (!model) {
+    return {
+      error: `No model configured. Set model in ~/.config/llm/config.toml`,
+    };
+  }
+
+  // API key required for cloud providers
+  if (!apiKey && provider !== "ollama") {
+    return {
+      error: `No API key configured. Set api_key = "env:VAR_NAME" in ~/.config/llm/config.toml`,
+    };
+  }
+
+  // Call appropriate provider
+  if (provider === "anthropic") {
+    return callAnthropic(
+      text,
+      model,
+      maxTokens,
+      apiKey!,
+      config.apiBase || undefined,
+    );
+  } else if (provider === "openai") {
+    return callOpenAI(
+      text,
+      model,
+      maxTokens,
+      apiKey!,
+      config.apiBase || undefined,
+    );
+  } else if (provider === "ollama") {
+    if (!config.apiBase) {
+      return {
+        error: `No api_base configured for ollama. Set api_base in ~/.config/llm/config.toml`,
+      };
+    }
+    return callOllama(text, model, maxTokens, config.apiBase);
+  } else {
+    return {
+      error: `Unknown provider: ${provider}. Supported: anthropic, openai, ollama`,
+    };
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@voidwire/llm-summarize",
+  "version": "2.0.0",
+  "description": "Fast LLM-powered text summarization for observability and logging",
+  "type": "module",
+  "main": "./index.ts",
+  "bin": {
+    "llm-summarize": "./cli.ts"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./cli": "./cli.ts"
+  },
+  "files": [
+    "index.ts",
+    "cli.ts",
+    "lib/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "keywords": [
+    "llm",
+    "summarize",
+    "anthropic",
+    "openai",
+    "cli",
+    "llcli"
+  ],
+  "author": "nickpending <nickpending@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nickpending/llmcli-tools.git",
+    "directory": "packages/llm-summarize"
+  },
+  "homepage": "https://github.com/nickpending/llmcli-tools/tree/main/packages/llm-summarize#readme",
+  "bugs": {
+    "url": "https://github.com/nickpending/llmcli-tools/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}