kvat 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# kvat - KVCache Auto-Tuner
+
+[![npm version](https://img.shields.io/npm/v/kvat.svg)](https://www.npmjs.com/package/kvat)
+[![PyPI](https://img.shields.io/pypi/v/kvat.svg)](https://pypi.org/project/kvat/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/Keyvanhardani/kvcache-autotune/blob/main/LICENSE)
+
+**Automatic KV-Cache Optimization for HuggingFace Transformers**
+
+Find the optimal cache strategy, attention backend, and configuration for your model and hardware.
+
+## Requirements
+
+- **Node.js** 14.0+
+- **Python** 3.9+
+- **PyTorch** 2.0+
+- **Transformers** 4.35+
+
+## Installation
+
+```bash
+npm install kvat
+```
+
+Then install the Python package:
+
+```bash
+pip install kvat[full]
+```
+
+## CLI Usage
+
+```bash
+# Optimize any HuggingFace model
+kvat tune meta-llama/Llama-3.2-1B --profile chat-agent
+
+# Quick test
+kvat tune gpt2 --profile ci-micro -v
+
+# Show system info
+kvat info
+```
+
+## JavaScript API
+
+```javascript
+const kvat = require('kvat');
+
+// Check if kvat is installed
+if (!kvat.isKvatInstalled()) {
+  await kvat.installKvat();  // Install Python package
+}
+
+// Run tuning
+const result = await kvat.tune('gpt2', {
+  profile: 'chat-agent',
+  outputDir: './results',
+  verbose: true
+});
+
+console.log('Results saved to:', result.outputDir);
+
+// Get system info
+const info = await kvat.info();
+console.log(info);
+
+// Run arbitrary command
+const { stdout, stderr, code } = await kvat.run(['profiles']);
+```
+
+## API Reference
+
+### `isKvatInstalled()`
+
+Check if the kvat Python package is installed.
+
+Returns: `boolean`
+
+### `installKvat(full = true)`
+
+Install the kvat Python package.
+
+- `full` (boolean): Install with full dependencies (default: true)
+
+Returns: `Promise<void>`
+
+### `tune(modelId, options)`
+
+Run kvat tune command.
+
+- `modelId` (string): HuggingFace model ID
+- `options.profile` (string): Profile name (default: 'chat-agent')
+- `options.device` (string): Device cuda/cpu/mps (default: 'cuda')
+- `options.outputDir` (string): Output directory (default: './kvat_results')
+- `options.verbose` (boolean): Verbose output (default: false)
+
+Returns: `Promise<{success: boolean, outputDir: string, stdout: string, stderr: string}>`
+
+### `info()`
+
+Get system information.
+
+Returns: `Promise<string>`
+
+### `run(args)`
+
+Run arbitrary kvat command.
+
+- `args` (string[]): Command arguments
+
+Returns: `Promise<{stdout: string, stderr: string, code: number}>`
+
+## Available Profiles
+
+| Profile | Context | Output | Focus |
+|---------|---------|--------|-------|
+| `chat-agent` | 2-8K | 64-256 | TTFT (latency) |
+| `rag` | 8-32K | 256-512 | Balanced |
+| `longform` | 4-8K | 1-2K | Throughput |
+| `ci-micro` | 512 | 32 | Quick testing |
+
+## Links
+
+- **GitHub**: https://github.com/Keyvanhardani/kvcache-autotune
+- **PyPI**: https://pypi.org/project/kvat/
+- **Documentation**: https://github.com/Keyvanhardani/kvcache-autotune#readme
+
+## License
+
+Apache 2.0
+
+---
+
+<p align="center">
+  <a href="https://keyvan.ai"><strong>Keyvan.ai</strong></a> | <a href="https://www.linkedin.com/in/keyvanhardani">LinkedIn</a>
+</p>
+<p align="center">
+  Made in Germany with dedication for the HuggingFace Community
+</p>

package/cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * KVCache Auto-Tuner CLI Wrapper
+ *
+ * This script forwards all arguments to the Python kvat CLI.
+ * Usage: kvat <command> [options]
+ */
+
+const { spawn } = require('child_process');
+const { getPythonCommand, isKvatInstalled } = require('./index');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Check if kvat is installed
+  if (!isKvatInstalled()) {
+    console.error('Error: kvat Python package is not installed.');
+    console.error('');
+    console.error('Please install it first:');
+    console.error('  pip install kvat[full]');
+    console.error('');
+    console.error('Or use the JavaScript API to install:');
+    console.error('  const kvat = require("kvat");');
+    console.error('  await kvat.installKvat();');
+    process.exit(1);
+  }
+
+  const python = getPythonCommand();
+
+  // Forward all arguments to Python kvat
+  const proc = spawn(python, ['-m', 'kvat', ...args], {
+    stdio: 'inherit'
+  });
+
+  proc.on('close', (code) => {
+    process.exit(code);
+  });
+
+  proc.on('error', (err) => {
+    console.error('Failed to start kvat:', err.message);
+    process.exit(1);
+  });
+}
+
+main();

package/index.js

@@ -0,0 +1,198 @@
+/**
+ * KVCache Auto-Tuner - JavaScript Wrapper
+ *
+ * This package provides a JavaScript wrapper for the kvat Python CLI.
+ * It requires Python 3.9+ and pip to be installed on the system.
+ */
+
+const { spawn, execSync } = require('child_process');
+const path = require('path');
+
+/**
+ * Check if Python and kvat are installed
+ * @returns {boolean} True if kvat is available
+ */
+function isKvatInstalled() {
+  try {
+    execSync('python -m kvat --version', { stdio: 'pipe' });
+    return true;
+  } catch {
+    try {
+      execSync('python3 -m kvat --version', { stdio: 'pipe' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Get the Python command to use
+ * @returns {string} 'python' or 'python3'
+ */
+function getPythonCommand() {
+  try {
+    execSync('python --version', { stdio: 'pipe' });
+    return 'python';
+  } catch {
+    return 'python3';
+  }
+}
+
+/**
+ * Install kvat Python package
+ * @param {boolean} full - Install with full dependencies
+ * @returns {Promise<void>}
+ */
+async function installKvat(full = true) {
+  const python = getPythonCommand();
+  const pkg = full ? 'kvat[full]' : 'kvat';
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(python, ['-m', 'pip', 'install', pkg], {
+      stdio: 'inherit'
+    });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Failed to install kvat (exit code ${code})`));
+      }
+    });
+  });
+}
+
+/**
+ * Run kvat tune command
+ * @param {string} modelId - HuggingFace model ID
+ * @param {Object} options - Tuning options
+ * @param {string} [options.profile='chat-agent'] - Profile name
+ * @param {string} [options.device='cuda'] - Device (cuda, cpu, mps)
+ * @param {string} [options.outputDir='./kvat_results'] - Output directory
+ * @param {boolean} [options.verbose=false] - Verbose output
+ * @returns {Promise<Object>} Tuning result
+ */
+async function tune(modelId, options = {}) {
+  const {
+    profile = 'chat-agent',
+    device = 'cuda',
+    outputDir = './kvat_results',
+    verbose = false
+  } = options;
+
+  const python = getPythonCommand();
+  const args = ['-m', 'kvat', 'tune', modelId, '--profile', profile, '-o', outputDir];
+
+  if (verbose) {
+    args.push('-v');
+  }
+
+  return new Promise((resolve, reject) => {
+    let stdout = '';
+    let stderr = '';
+
+    const proc = spawn(python, args, {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    proc.stdout.on('data', (data) => {
+      stdout += data.toString();
+      if (verbose) {
+        process.stdout.write(data);
+      }
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+      if (verbose) {
+        process.stderr.write(data);
+      }
+    });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve({
+          success: true,
+          outputDir,
+          stdout,
+          stderr
+        });
+      } else {
+        reject(new Error(`kvat tune failed (exit code ${code}): ${stderr}`));
+      }
+    });
+  });
+}
+
+/**
+ * Run kvat info command
+ * @returns {Promise<string>} System info
+ */
+async function info() {
+  const python = getPythonCommand();
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(python, ['-m', 'kvat', 'info'], {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve(stdout);
+      } else {
+        reject(new Error(`kvat info failed: ${stderr}`));
+      }
+    });
+  });
+}
+
+/**
+ * Run arbitrary kvat command
+ * @param {string[]} args - Command arguments
+ * @returns {Promise<{stdout: string, stderr: string, code: number}>}
+ */
+async function run(args) {
+  const python = getPythonCommand();
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(python, ['-m', 'kvat', ...args], {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on('close', (code) => {
+      resolve({ stdout, stderr, code });
+    });
+  });
+}
+
+module.exports = {
+  isKvatInstalled,
+  installKvat,
+  tune,
+  info,
+  run,
+  getPythonCommand
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "kvat",
+  "version": "0.1.0",
+  "description": "Automatic KV-Cache Optimization for HuggingFace Transformers - Find the optimal cache strategy, attention backend, and configuration for your model and hardware.",
+  "main": "index.js",
+  "bin": {
+    "kvat": "./cli.js"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "transformers",
+    "llm",
+    "kv-cache",
+    "optimization",
+    "inference",
+    "huggingface",
+    "deep-learning",
+    "machine-learning",
+    "pytorch",
+    "flash-attention",
+    "ai",
+    "ml"
+  ],
+  "author": "Keyvanhardani",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Keyvanhardani/kvcache-autotune.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Keyvanhardani/kvcache-autotune/issues"
+  },
+  "homepage": "https://github.com/Keyvanhardani/kvcache-autotune#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {},
+  "files": [
+    "index.js",
+    "cli.js",
+    "postinstall.js",
+    "README.md"
+  ]
+}

package/postinstall.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * KVCache Auto-Tuner - Post-install Script
+ *
+ * Checks for Python and provides installation instructions.
+ */
+
+const { execSync } = require('child_process');
+
+function checkPython() {
+  try {
+    const version = execSync('python --version', { stdio: 'pipe' }).toString().trim();
+    return { available: true, version, command: 'python' };
+  } catch {
+    try {
+      const version = execSync('python3 --version', { stdio: 'pipe' }).toString().trim();
+      return { available: true, version, command: 'python3' };
+    } catch {
+      return { available: false };
+    }
+  }
+}
+
+function checkKvat(pythonCmd) {
+  try {
+    execSync(`${pythonCmd} -m kvat --version`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function main() {
+  console.log('');
+  console.log('KVCache Auto-Tuner (kvat) - npm package installed');
+  console.log('='.repeat(50));
+  console.log('');
+
+  const python = checkPython();
+
+  if (!python.available) {
+    console.log('WARNING: Python is not installed or not in PATH.');
+    console.log('');
+    console.log('kvat requires Python 3.9+ to run. Please install Python first:');
+    console.log('  - Windows: https://www.python.org/downloads/');
+    console.log('  - macOS: brew install python3');
+    console.log('  - Linux: sudo apt install python3 python3-pip');
+    console.log('');
+    return;
+  }
+
+  console.log(`Python found: ${python.version}`);
+
+  const kvatInstalled = checkKvat(python.command);
+
+  if (kvatInstalled) {
+    console.log('kvat Python package: Installed');
+    console.log('');
+    console.log('You can now use kvat:');
+    console.log('  kvat tune gpt2 --profile ci-micro');
+    console.log('  kvat info');
+  } else {
+    console.log('kvat Python package: Not installed');
+    console.log('');
+    console.log('To install the Python package, run:');
+    console.log(`  ${python.command} -m pip install kvat[full]`);
+    console.log('');
+    console.log('Or use the JavaScript API:');
+    console.log('  const kvat = require("kvat");');
+    console.log('  await kvat.installKvat();');
+  }
+
+  console.log('');
+  console.log('Documentation: https://github.com/Keyvanhardani/kvcache-autotune');
+  console.log('');
+}
+
+main();