@kotro-labs/proxy-engine 0.3.0

package/README.md

@@ -0,0 +1,72 @@
+# @kotro-labs/proxy-engine
+
+<p align="center">
+  <img src="media/icon.png" alt="Kotro" width="72" height="72" />
+</p>
+
+npm distribution for the [Kotro Proxy Engine](https://github.com/kotro-labs/kotro-proxy-engine) — a local AI reverse proxy with streaming semantic cache, PII redaction, and context compression for OpenAI and Anthropic SDKs.
+
+## Features
+
+- **Zero-config startup** — precompiled binary with no dependencies
+- **Semantic SSE cache** — faster repeat prompts; `X-Kotro-Cache: HIT` on cache hits
+- **Enterprise failover** — dynamic routing on 429/503 upstream errors
+- **Operator dashboard** — local UI for observability (`http://127.0.0.1:9090/dashboard`)
+- **Isolated telemetry** — `/metrics` binds to loopback by default, separate from LLM traffic
+- **Context-aware cache keys** — prevents false cache hits in multi-turn agent loops
+
+## Install
+
+```bash
+npm install -g @kotro-labs/proxy-engine
+```
+
+## Quick start
+
+```bash
+# Point at your provider (default upstream is local mock on :9000)
+export KOTRO_UPSTREAM_URL=https://api.openai.com
+
+kotro-proxy
+```
+
+The proxy listens on `:8080` by default. Point your IDE or SDK at `http://localhost:8080/v1`.
+
+```bash
+curl -N http://127.0.0.1:8080/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -d '{"model":"gpt-4","stream":true,"messages":[{"role":"user","content":"hello"}]}'
+```
+
+Cache hits return the `X-Kotro-Cache: HIT` header.
+
+## Architecture
+
+```text
+AI client  →  localhost:8080/v1/*     (LLM proxy — may bind 0.0.0.0 in cluster mode)
+Operator   →  127.0.0.1:9090/dashboard  (telemetry — loopback only by default)
+```
+
+## Configuration
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `KOTRO_LISTEN_ADDR` | `:8080` | Proxy bind address |
+| `KOTRO_UPSTREAM_URL` | `http://127.0.0.1:9000` | Provider base URL |
+| `KOTRO_ENABLE_CACHE` | `true` | Semantic SSE cache |
+| `KOTRO_ENABLE_REDACTION` | `true` | PII guardrail |
+| `KOTRO_ENABLE_COMPRESSION` | `true` | Context block dedup |
+| `KOTRO_TRUST_UPSTREAM_GATEWAY` | `false` | Honor `X-Tenant-ID` only from trusted proxy CIDRs |
+
+Full documentation: [github.com/kotro-labs/kotro-proxy-engine](https://github.com/kotro-labs/kotro-proxy-engine)
+
+## Other install channels
+
+- **Homebrew:** `brew tap kotro-labs/tap && brew install kotro-proxy`
+- **VS Code / Cursor:** [Marketplace extension](https://marketplace.visualstudio.com/items?itemName=kotrolabs.kotro-proxy-engine)
+- **GitHub Releases:** [Download binaries](https://github.com/kotro-labs/kotro-proxy-engine/releases)
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+const { resolveBinaryPath } = require('../lib/binary-target');
+
+function main() {
+  const binRoot = path.join(__dirname, '..', 'bin');
+  const binary = resolveBinaryPath(binRoot);
+  const child = spawn(binary, process.argv.slice(2), {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  child.on('error', (err) => {
+    console.error(`kotro-proxy: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on('close', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+main();

package/lib/binary-target.js

@@ -0,0 +1,40 @@
+/**
+ * Platform resolver for the npm CLI package.
+ * Keep in sync with distributions/shared/binary-target.js
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const BINARY_BASENAMES = {
+  'darwin-arm64': 'kotro-proxy-aarch64-apple-darwin',
+  'darwin-x64': 'kotro-proxy-x86_64-apple-darwin',
+  'linux-x64': 'kotro-proxy-x86_64-unknown-linux-gnu',
+  'win32-x64': 'kotro-proxy-x86_64-pc-windows-msvc.exe',
+};
+
+function binaryBasename(platform, arch) {
+  if (platform === 'darwin') {
+    return arch === 'arm64' ? BINARY_BASENAMES['darwin-arm64'] : BINARY_BASENAMES['darwin-x64'];
+  }
+  if (platform === 'linux') {
+    return BINARY_BASENAMES['linux-x64'];
+  }
+  if (platform === 'win32') {
+    return BINARY_BASENAMES['win32-x64'];
+  }
+  throw new Error(`Unsupported platform: ${platform}/${arch}`);
+}
+
+function resolveBinaryPath(binRoot, platform = process.platform, arch = process.arch) {
+  const name = binaryBasename(platform, arch);
+  const candidate = path.join(binRoot, name);
+  if (!fs.existsSync(candidate)) {
+    throw new Error(
+      `Native binary not found at ${candidate}. Reinstall @kotrolabs/proxy-engine or build from source.`,
+    );
+  }
+  return candidate;
+}
+
+module.exports = { BINARY_BASENAMES, binaryBasename, resolveBinaryPath };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@kotro-labs/proxy-engine",
+  "version": "0.3.0",
+  "description": "High-performance semantic caching AI proxy gateway with native Rust runtime.",
+  "license": "MIT",
+  "author": "Ramesh Pandian",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kotro-labs/kotro-proxy-engine.git",
+    "directory": "distributions/npm-cli"
+  },
+  "bin": {
+    "kotro-proxy": "./bin/index.js"
+  },
+  "files": [
+    "README.md",
+    "media/icon.png",
+    "bin/index.js",
+    "lib/binary-target.js",
+    "bin/kotro-proxy-*"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "keywords": [
+    "ai",
+    "proxy",
+    "cache",
+    "rust",
+    "llm",
+    "openai",
+    "anthropic"
+  ]
+}