@opencompress/opencompress 1.0.0

package/README.md

@@ -0,0 +1,112 @@
+# OpenCompress Plugin for OpenClaw
+
+Automatic 5-layer prompt compression for any LLM. Drop-in replacement for your current provider — same models, same API, 40-70% cheaper and faster.
+
+## How it works
+
+```
+Your Agent → OpenCompress (compress) → Your LLM provider (OpenRouter/OpenAI/Anthropic)
+```
+
+OpenCompress sits between OpenClaw and your existing LLM provider. It compresses prompts through a 5-layer pipeline (distilled model + dict aliasing + output shaping + adaptive rate + closed-loop control), then forwards to your provider using your own API key (BYOK).
+
+- **53%** average input token reduction
+- **62%** latency improvement
+- **96%** quality preservation (SQuALITY benchmark)
+
+## Install
+
+```bash
+openclaw plugins install /path/to/opencompress
+```
+
+Or from npm (coming soon):
+
+```bash
+openclaw plugins install @opencompress/opencompress
+```
+
+## Setup
+
+### 1. Get an OpenCompress API key
+
+1. Go to [opencompress.ai/dashboard](https://www.opencompress.ai/dashboard)
+2. Sign up and create a **BYOK key** — enter your existing OpenRouter or OpenAI API key
+3. Copy the `sk-occ-...` key
+
+### 2. Onboard in OpenClaw
+
+```bash
+openclaw onboard opencompress
+```
+
+The wizard will prompt for your API key and verify it.
+
+### 3. Use it
+
+Switch to the OpenCompress provider:
+
+```
+/model opencompress/gpt-4o-mini
+```
+
+All your requests now go through compression automatically. Model IDs are identical to OpenRouter/OpenAI — no config changes needed.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/compress-stats` | Show compression savings (calls, tokens saved, cost saved) |
+
+## Supported models (20)
+
+| Model | ID |
+|-------|-----|
+| GPT-4o | `gpt-4o` |
+| GPT-4o Mini | `gpt-4o-mini` |
+| GPT-4.1 | `gpt-4.1` |
+| GPT-4.1 Mini | `gpt-4.1-mini` |
+| GPT-4.1 Nano | `gpt-4.1-nano` |
+| O3 | `o3` |
+| O4 Mini | `o4-mini` |
+| Claude Sonnet 4.6 | `claude-sonnet-4-6` |
+| Claude Opus 4.6 | `claude-opus-4-6` |
+| Claude Haiku 4.5 | `claude-haiku-4-5-20251001` |
+| Gemini 2.5 Pro | `gemini-2.5-pro` |
+| Gemini 2.5 Flash | `gemini-2.5-flash` |
+| DeepSeek V3 | `deepseek/deepseek-chat-v3-0324` |
+| DeepSeek Reasoner | `deepseek/deepseek-reasoner` |
+| Llama 4 Maverick | `meta-llama/llama-4-maverick` |
+| Llama 4 Scout | `meta-llama/llama-4-scout` |
+| Qwen3 235B | `qwen/qwen3-235b-a22b` |
+| Qwen3 32B | `qwen/qwen3-32b` |
+| Mistral Large | `mistralai/mistral-large-2411` |
+| Gemini 2.5 Pro Preview | `google/gemini-2.5-pro-preview` |
+
+## Pricing
+
+OpenCompress charges **20% of what you save**. If compression saves you $1.00, you pay $0.20 — net saving $0.80.
+
+BYOK mode: you pay your LLM provider directly + the compression fee.
+
+## Configuration
+
+Plugin config options in `openclaw.plugin.json`:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `apiKey` | — | Your `sk-occ-...` API key (optional, set during onboard) |
+| `baseUrl` | `https://www.opencompress.ai/api` | Custom API endpoint |
+
+## Development
+
+```bash
+npm install
+npm run build      # Build with tsup
+npm run dev        # Watch mode
+npm run typecheck  # Type check
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * OpenClaw Plugin Types (locally defined)
+ *
+ * OpenClaw's plugin SDK uses duck typing — these match the shapes
+ * expected by registerProvider() and the plugin system.
+ * Defined locally to avoid depending on internal OpenClaw paths.
+ */
+type ModelApi = "openai-completions" | "openai-responses" | "anthropic-messages" | "google-generative-ai";
+type ModelDefinitionConfig = {
+    id: string;
+    name: string;
+    api?: ModelApi;
+    reasoning: boolean;
+    input: Array<"text" | "image">;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    headers?: Record<string, string>;
+};
+type ModelProviderConfig = {
+    baseUrl: string;
+    apiKey?: string;
+    api?: ModelApi;
+    headers?: Record<string, string>;
+    authHeader?: boolean;
+    models: ModelDefinitionConfig[];
+};
+type AuthProfileCredential = {
+    apiKey?: string;
+    type?: string;
+    [key: string]: unknown;
+};
+type ProviderAuthResult = {
+    profiles: Array<{
+        profileId: string;
+        credential: AuthProfileCredential;
+    }>;
+    configPatch?: Record<string, unknown>;
+    defaultModel?: string;
+    notes?: string[];
+};
+type WizardPrompter = {
+    text: (opts: {
+        message: string;
+        validate?: (value: string) => string | undefined;
+    }) => Promise<string | symbol>;
+    note: (message: string) => void;
+    progress: (message: string) => {
+        stop: (message?: string) => void;
+    };
+};
+type ProviderAuthContext = {
+    config: Record<string, unknown>;
+    agentDir?: string;
+    workspaceDir?: string;
+    prompter: WizardPrompter;
+    runtime: {
+        log: (message: string) => void;
+    };
+    isRemote: boolean;
+    openUrl: (url: string) => Promise<void>;
+};
+type ProviderAuthMethod = {
+    id: string;
+    label: string;
+    hint?: string;
+    kind: "oauth" | "api_key" | "token" | "device_code" | "custom";
+    run: (ctx: ProviderAuthContext) => Promise<ProviderAuthResult>;
+};
+type ProviderPlugin = {
+    id: string;
+    label: string;
+    docsPath?: string;
+    aliases?: string[];
+    envVars?: string[];
+    models?: ModelProviderConfig;
+    auth: ProviderAuthMethod[];
+    formatApiKey?: (cred: AuthProfileCredential) => string;
+};
+type PluginLogger = {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+type OpenClawPluginService = {
+    id: string;
+    start: () => void | Promise<void>;
+    stop?: () => void | Promise<void>;
+};
+type CommandHandler = {
+    name: string;
+    description: string;
+    acceptsArgs?: boolean;
+    requireAuth?: boolean;
+    handler: (ctx: {
+        args?: string;
+    }) => Promise<{
+        text: string;
+    }>;
+};
+type OpenClawPluginApi = {
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    source: string;
+    config: Record<string, unknown> & {
+        models?: {
+            providers?: Record<string, ModelProviderConfig>;
+        };
+        agents?: Record<string, unknown>;
+    };
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    registerProvider: (provider: ProviderPlugin) => void;
+    registerTool: (tool: unknown, opts?: unknown) => void;
+    registerHook: (events: string | string[], handler: unknown, opts?: unknown) => void;
+    registerHttpRoute: (params: {
+        path: string;
+        handler: unknown;
+    }) => void;
+    registerService: (service: OpenClawPluginService) => void;
+    registerCommand: (command: CommandHandler) => void;
+    resolvePath: (input: string) => string;
+    on: (hookName: string, handler: unknown, opts?: unknown) => void;
+};
+type OpenClawPluginDefinition = {
+    id?: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    register?: (api: OpenClawPluginApi) => void | Promise<void>;
+    activate?: (api: OpenClawPluginApi) => void | Promise<void>;
+};
+declare const plugin: OpenClawPluginDefinition;
+
+export { plugin as default };

package/dist/index.js

@@ -0,0 +1,244 @@
+// src/index.ts
+var VERSION = "1.0.0";
+var DEFAULT_BASE_URL = "https://www.opencompress.ai/api";
+function getApiKey(api) {
+  const auth = api.config.auth;
+  return auth?.profiles?.opencompress?.credentials?.["api-key"]?.apiKey;
+}
+var OPENCOMPRESS_MODELS = [
+  // OpenAI
+  { id: "gpt-4o", name: "GPT-4o (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128e3, maxTokens: 16384 },
+  { id: "gpt-4o-mini", name: "GPT-4o Mini (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128e3, maxTokens: 16384 },
+  { id: "gpt-4.1", name: "GPT-4.1 (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1047576, maxTokens: 32768 },
+  { id: "gpt-4.1-mini", name: "GPT-4.1 Mini (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1047576, maxTokens: 32768 },
+  { id: "gpt-4.1-nano", name: "GPT-4.1 Nano (Compressed)", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1047576, maxTokens: 32768 },
+  { id: "o3", name: "O3 (Compressed)", reasoning: true, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 2e5, maxTokens: 1e5 },
+  { id: "o4-mini", name: "O4 Mini (Compressed)", reasoning: true, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 2e5, maxTokens: 1e5 },
+  // Anthropic
+  { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6 (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 2e5, maxTokens: 128e3 },
+  { id: "claude-opus-4-6", name: "Claude Opus 4.6 (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 2e5, maxTokens: 128e3 },
+  { id: "claude-haiku-4-5-20251001", name: "Claude Haiku 4.5 (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 2e5, maxTokens: 128e3 },
+  // Google
+  { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro (Compressed)", reasoning: true, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1048576, maxTokens: 65536 },
+  { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1048576, maxTokens: 65536 },
+  { id: "google/gemini-2.5-pro-preview", name: "Gemini 2.5 Pro Preview (Compressed)", reasoning: true, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1048576, maxTokens: 65536 },
+  // DeepSeek
+  { id: "deepseek/deepseek-chat-v3-0324", name: "DeepSeek V3 (Compressed)", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 131072, maxTokens: 8192 },
+  { id: "deepseek/deepseek-reasoner", name: "DeepSeek Reasoner (Compressed)", reasoning: true, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 131072, maxTokens: 8192 },
+  // Meta
+  { id: "meta-llama/llama-4-maverick", name: "Llama 4 Maverick (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 1048576, maxTokens: 65536 },
+  { id: "meta-llama/llama-4-scout", name: "Llama 4 Scout (Compressed)", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 524288, maxTokens: 65536 },
+  // Qwen
+  { id: "qwen/qwen3-235b-a22b", name: "Qwen3 235B (Compressed)", reasoning: true, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 131072, maxTokens: 8192 },
+  { id: "qwen/qwen3-32b", name: "Qwen3 32B (Compressed)", reasoning: true, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 131072, maxTokens: 8192 },
+  // Mistral
+  { id: "mistralai/mistral-large-2411", name: "Mistral Large (Compressed)", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 131072, maxTokens: 8192 }
+];
+function buildProviderModels(baseUrl) {
+  return {
+    baseUrl: `${baseUrl}/v1`,
+    api: "openai-completions",
+    models: OPENCOMPRESS_MODELS
+  };
+}
+var opencompressProvider = {
+  id: "opencompress",
+  label: "OpenCompress",
+  docsPath: "https://docs.opencompress.ai",
+  aliases: ["oc", "compress"],
+  envVars: ["OPENCOMPRESS_API_KEY"],
+  models: buildProviderModels(DEFAULT_BASE_URL),
+  formatApiKey: (cred) => cred.apiKey || "",
+  auth: [
+    {
+      id: "api-key",
+      label: "OpenCompress",
+      hint: "One-click setup \u2014 no API key needed",
+      kind: "custom",
+      run: async (ctx) => {
+        ctx.prompter.note(
+          "OpenCompress compresses all LLM prompts automatically.\n53% fewer tokens, 62% faster, 96% quality preserved.\nWe'll create your account now \u2014 $1 free credit included."
+        );
+        const spinner = ctx.prompter.progress("Creating account...");
+        try {
+          const res = await fetch(`${DEFAULT_BASE_URL}/v1/provision`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: "{}"
+          });
+          if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: { message: "Unknown error" } }));
+            spinner.stop("Setup failed");
+            throw new Error(
+              `Provisioning failed: ${err.error?.message || res.statusText}`
+            );
+          }
+          const data = await res.json();
+          spinner.stop("Account created");
+          return {
+            profiles: [
+              {
+                profileId: "default",
+                credential: { apiKey: data.apiKey }
+              }
+            ],
+            defaultModel: "gpt-4o-mini",
+            notes: [
+              "OpenCompress is ready! All LLM calls are now compressed automatically.",
+              `Free credit: ${data.freeCredit}. Add more: POST /api/v1/topup or visit opencompress.ai/dashboard`
+            ]
+          };
+        } catch (err) {
+          spinner.stop("Setup failed");
+          throw err instanceof Error ? err : new Error(String(err));
+        }
+      }
+    }
+  ]
+};
+var plugin = {
+  id: "opencompress",
+  name: "OpenCompress",
+  description: "5-layer prompt compression \u2014 53% input reduction, 62% latency cut, 96% quality",
+  version: VERSION,
+  async register(api) {
+    const baseUrl = api.pluginConfig?.baseUrl || DEFAULT_BASE_URL;
+    if (baseUrl !== DEFAULT_BASE_URL) {
+      opencompressProvider.models = buildProviderModels(baseUrl);
+    }
+    api.registerProvider(opencompressProvider);
+    if (!api.config.models) {
+      api.config.models = { providers: {} };
+    }
+    if (!api.config.models.providers) {
+      api.config.models.providers = {};
+    }
+    api.config.models.providers.opencompress = buildProviderModels(baseUrl);
+    api.logger.info("OpenCompress provider registered (20 models, 5-layer compression)");
+    api.registerCommand({
+      name: "compress-stats",
+      description: "Show OpenCompress usage statistics and savings",
+      acceptsArgs: true,
+      requireAuth: false,
+      handler: async () => {
+        const apiKey = getApiKey(api);
+        if (!apiKey) {
+          return {
+            text: "No API key found. Run `openclaw onboard opencompress` to set up."
+          };
+        }
+        try {
+          const res = await fetch(`${baseUrl}/user/stats`, {
+            headers: { Authorization: `Bearer ${apiKey}` }
+          });
+          if (!res.ok) {
+            return { text: `Failed to fetch stats: HTTP ${res.status}` };
+          }
+          const stats = await res.json();
+          const calls = stats.totalCalls ?? 0;
+          const savings = stats.totalSavings?.toFixed(4) ?? "0.0000";
+          const rate = stats.avgCompressionRate ? `${(stats.avgCompressionRate * 100).toFixed(1)}%` : "N/A";
+          const origTokens = stats.totalOriginalTokens?.toLocaleString() ?? "N/A";
+          const compTokens = stats.totalCompressedTokens?.toLocaleString() ?? "N/A";
+          return {
+            text: [
+              "```",
+              "OpenCompress Stats",
+              "==================",
+              `API calls:          ${calls}`,
+              `Avg compression:    ${rate}`,
+              `Original tokens:    ${origTokens}`,
+              `Compressed tokens:  ${compTokens}`,
+              `Total savings:      $${savings}`,
+              "```",
+              "",
+              "Dashboard: https://www.opencompress.ai/dashboard"
+            ].join("\n")
+          };
+        } catch (err) {
+          return {
+            text: `Error fetching stats: ${err instanceof Error ? err.message : String(err)}`
+          };
+        }
+      }
+    });
+    api.logger.info("Registered /compress-stats command");
+    api.registerCommand({
+      name: "compress-byok",
+      description: "Connect your own LLM key (OpenAI/Anthropic/OpenRouter) to save more",
+      acceptsArgs: true,
+      requireAuth: false,
+      handler: async (ctx) => {
+        const apiKey = getApiKey(api);
+        if (!apiKey) {
+          return { text: "Not set up. Run `openclaw onboard opencompress` first." };
+        }
+        const upstreamKey = ctx.args?.trim();
+        if (!upstreamKey) {
+          const res2 = await fetch(`${baseUrl}/v1/topup`, {
+            headers: { Authorization: `Bearer ${apiKey}` }
+          });
+          const data2 = res2.ok ? await res2.json() : null;
+          return {
+            text: [
+              "**BYOK (Bring Your Own Key)**",
+              "",
+              "Connect your LLM provider key to pay them directly \u2014 we only charge the compression fee (20% of savings).",
+              "",
+              "**Usage:**",
+              "  `/compress-byok sk-proj-xxx`  \u2014 Connect OpenAI key",
+              "  `/compress-byok sk-ant-xxx`   \u2014 Connect Anthropic key",
+              "  `/compress-byok sk-or-xxx`    \u2014 Connect OpenRouter key",
+              "  `/compress-byok off`          \u2014 Switch back to router mode",
+              "",
+              data2 ? `**Balance:** $${data2.balance.toFixed(2)}` : ""
+            ].join("\n")
+          };
+        }
+        if (upstreamKey === "off" || upstreamKey === "disable" || upstreamKey === "router") {
+          const res2 = await fetch(`${baseUrl}/v1/byok`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${apiKey}` }
+          });
+          if (!res2.ok) {
+            return { text: `Failed to switch: HTTP ${res2.status}` };
+          }
+          return { text: "Switched back to **router mode**. We handle LLM routing via OpenRouter." };
+        }
+        if (upstreamKey.startsWith("sk-occ-")) {
+          return { text: "That's an OpenCompress key. Provide your LLM provider key (OpenAI, Anthropic, etc.)." };
+        }
+        if (upstreamKey.length < 10) {
+          return { text: "Key looks too short. Provide your full LLM API key." };
+        }
+        const res = await fetch(`${baseUrl}/v1/byok`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({ upstreamApiKey: upstreamKey })
+        });
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({ error: { message: "Unknown error" } }));
+          return { text: `Failed: ${err.error?.message || res.statusText}` };
+        }
+        const data = await res.json();
+        return {
+          text: [
+            `Switched to **BYOK mode** (${data.provider}).`,
+            "",
+            data.billing,
+            "",
+            "To switch back: `/compress-byok off`"
+          ].join("\n")
+        };
+      }
+    });
+    api.logger.info("Registered /compress-byok command");
+  }
+};
+var index_default = plugin;
+export {
+  index_default as default
+};

package/openclaw.plugin.json

@@ -0,0 +1,20 @@
+{
+  "id": "opencompress",
+  "name": "OpenCompress",
+  "description": "5-layer prompt compression — 53% input reduction, 62% latency cut, 96% quality. Save 40-70% on any LLM.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "OpenCompress API key (sk-occ-...)"
+      },
+      "baseUrl": {
+        "type": "string",
+        "default": "https://www.opencompress.ai/api",
+        "description": "OpenCompress API base URL"
+      }
+    },
+    "required": []
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@opencompress/opencompress",
+  "version": "1.0.0",
+  "description": "OpenCompress plugin for OpenClaw — automatic 5-layer prompt compression for any LLM",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "compression",
+    "llm",
+    "opencompress",
+    "prompt-compression",
+    "cost-optimization",
+    "byok"
+  ],
+  "author": "OpenCompress <hello@opencompress.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/claw-compactor/openclaw-plugin.git"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2025.1.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}