distil-llm 1.25.0

package/README.md

@@ -0,0 +1,62 @@
+# distil-llm
+
+**Compress your AI agent's context — and prove its decisions don't change.**
+
+[distil](https://github.com/dshakes/distil) is a cache-aware, **reversible**
+context-compression layer for LLM agents. Unlike every other compressor, it
+certifies — per request — that the agent's *next action* is unchanged
+(decision-equivalence), with calibrated, honest savings numbers.
+
+This npm package is the JS/TS bridge: a thin CLI shim + proxy helpers. The
+compression runs in the distil proxy; your SDK just points its `baseURL` at it.
+
+## Use it (no pip required)
+
+```sh
+# route your agent through distil — resolves uv/pipx/pip automatically
+npx distil-llm wrap -- claude
+
+# or start the proxy and point any SDK at it
+npx distil-llm proxy            # http://127.0.0.1:8788
+```
+
+`npx distil-llm` bridges to the distil CLI via `uvx`/`pipx` (install
+[uv](https://docs.astral.sh/uv/) once and it just works) — or `pip install
+distil-llm` for a permanent install.
+
+## Point your SDK at the proxy
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { distilBaseURL } from "distil-llm";
+
+const client = new Anthropic({ baseURL: distilBaseURL() });
+```
+
+```ts
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { distilBaseURL } from "distil-llm";
+
+const anthropic = createAnthropic({ baseURL: distilBaseURL() });
+```
+
+```ts
+import OpenAI from "openai";
+import { distilOpenAIBaseURL } from "distil-llm";
+
+const openai = new OpenAI({ baseURL: distilOpenAIBaseURL() }); // adds /v1
+```
+
+`distilBaseURL()` honors `DISTIL_BASE_URL` / `DISTIL_PORT` (defaults
+`http://127.0.0.1:8788`).
+
+## Why distil
+
+- **Reversible** — Tier-0 lossless + Tier-1 digests the model can expand back on
+  demand. Nothing is silently lost.
+- **Proven, per request** — a live decision-equivalence shadow gate, not just
+  offline benchmarks.
+- **Honest** — savings are calibrated to your billed usage; the community board
+  publishes real, auditable numbers.
+
+Full docs: <https://dshakes.github.io/distil/> · License: Apache-2.0

package/bin/distil.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// `npx distil-llm <args>` — thin bridge to the distil CLI (Python), so JS/TS
+// developers get distil without touching pip. All args pass straight through.
+//
+//   npx distil-llm wrap -- claude          # route your agent through distil
+//   npx distil-llm proxy                   # start the proxy for any SDK baseURL
+//   npx distil-llm stats                   # your genuine savings
+
+"use strict";
+
+const { spawn } = require("node:child_process");
+const { resolveRunner, NO_RUNNER_HELP } = require("../lib/runner.js");
+
+const runner = resolveRunner();
+if (!runner) {
+  process.stderr.write(NO_RUNNER_HELP + "\n");
+  process.exit(127);
+}
+
+const args = runner.prefixArgs.concat(process.argv.slice(2));
+const child = spawn(runner.cmd, args, { stdio: "inherit" });
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code == null ? 1 : code);
+});
+child.on("error", (err) => {
+  process.stderr.write(`distil: failed to launch ${runner.cmd}: ${err.message}\n`);
+  process.exit(127);
+});

package/index.d.ts

@@ -0,0 +1,15 @@
+export interface DistilURLOptions {
+  /** Proxy host. Default "127.0.0.1". */
+  host?: string;
+  /** Proxy port. Default 8788 (or DISTIL_PORT). */
+  port?: number;
+}
+
+/** Base URL of a local distil proxy (honors DISTIL_BASE_URL). */
+export function distilBaseURL(opts?: DistilURLOptions): string;
+
+/** distil proxy base URL with the OpenAI `/v1` segment appended. */
+export function distilOpenAIBaseURL(opts?: DistilURLOptions): string;
+
+export const DEFAULT_PORT: number;
+export const DEFAULT_HOST: string;

package/index.js

@@ -0,0 +1,38 @@
+// distil-llm — TS/JS helpers for routing any SDK through the distil proxy.
+//
+// distil compresses at the network layer: start the proxy once
+// (`npx distil-llm proxy`, default http://127.0.0.1:8788) and point your SDK's
+// baseURL at it — no code changes to your calls, cache-aware reversible
+// compression, per-request decision-equivalence proof.
+//
+//   import Anthropic from "@anthropic-ai/sdk";
+//   import { distilBaseURL } from "distil-llm";
+//   const client = new Anthropic({ baseURL: distilBaseURL() });
+//
+//   import { createAnthropic } from "@ai-sdk/anthropic";
+//   const anthropic = createAnthropic({ baseURL: distilBaseURL() });
+//
+// Zero dependencies. The proxy itself is the integration; these are just the
+// tiny glue so you don't hardcode the URL.
+
+"use strict";
+
+const DEFAULT_PORT = 8788;
+const DEFAULT_HOST = "127.0.0.1";
+
+/** Base URL of a local distil proxy. Reads DISTIL_BASE_URL if set, else builds
+ *  http://<host>:<port> (defaults 127.0.0.1:8788). */
+function distilBaseURL(opts) {
+  opts = opts || {};
+  if (process.env.DISTIL_BASE_URL) return process.env.DISTIL_BASE_URL;
+  const host = opts.host || DEFAULT_HOST;
+  const port = opts.port || Number(process.env.DISTIL_PORT) || DEFAULT_PORT;
+  return `http://${host}:${port}`;
+}
+
+/** OpenAI-style clients expect the base URL to include the API version segment. */
+function distilOpenAIBaseURL(opts) {
+  return distilBaseURL(opts).replace(/\/+$/, "") + "/v1";
+}
+
+module.exports = { distilBaseURL, distilOpenAIBaseURL, DEFAULT_PORT, DEFAULT_HOST };

package/lib/runner.js

@@ -0,0 +1,41 @@
+// Resolve how to run the (Python) distil CLI from Node, in preference order:
+//   1. an already-installed `distil` on PATH (pipx/pip install)
+//   2. `uvx --from distil-llm distil` (ephemeral, no install — the happy path)
+//   3. `pipx run --spec distil-llm distil`
+//   4. `python3 -m distil` (if the package is importable)
+// Pure Node, zero dependencies. Exported for testing.
+
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+
+function has(cmd) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  return spawnSync(probe, [cmd], { stdio: "ignore" }).status === 0;
+}
+
+/** Return {cmd, prefixArgs} for invoking distil, or null if no runner exists. */
+function resolveRunner(env) {
+  env = env || process.env;
+  if (env.DISTIL_NPM_RUNNER) {
+    // escape hatch for tests / custom setups: "cmd arg1 arg2"
+    const parts = env.DISTIL_NPM_RUNNER.split(" ").filter(Boolean);
+    return { cmd: parts[0], prefixArgs: parts.slice(1) };
+  }
+  if (has("distil")) return { cmd: "distil", prefixArgs: [] };
+  if (has("uvx")) return { cmd: "uvx", prefixArgs: ["--from", "distil-llm", "distil"] };
+  if (has("pipx")) return { cmd: "pipx", prefixArgs: ["run", "--spec", "distil-llm", "distil"] };
+  return null;
+}
+
+const NO_RUNNER_HELP = [
+  "distil-llm (npm) bridges to the distil CLI, which runs on Python.",
+  "No runner found. Install one of:",
+  "  • uv     → https://docs.astral.sh/uv/   (then `npx distil-llm …` just works via uvx)",
+  "  • pipx   → pipx install distil-llm",
+  "  • pip    → pip install distil-llm",
+  "",
+  "Then, e.g.:  npx distil-llm wrap -- claude",
+].join("\n");
+
+module.exports = { resolveRunner, has, NO_RUNNER_HELP };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "distil-llm",
+  "version": "1.25.0",
+  "description": "Compress your AI agent's context and prove its decisions don't change — cache-aware, reversible, certified. JS/TS bridge to the distil CLI + proxy helpers.",
+  "keywords": [
+    "llm",
+    "ai-agent",
+    "context-compression",
+    "prompt-compression",
+    "token-savings",
+    "anthropic",
+    "openai",
+    "proxy",
+    "claude",
+    "mcp"
+  ],
+  "homepage": "https://dshakes.github.io/distil/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dshakes/distil.git",
+    "directory": "packaging/npm"
+  },
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "distil": "bin/distil.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  }
+}