kavach-ai 0.1.0

package/README.md

@@ -0,0 +1,168 @@
+# Kavach
+
+Your agents, your data, your machine.
+
+```bash
+npm install -g kavach-ai
+kavach install model    # free local model, ~1.5GB
+kavach open             # studio at http://localhost:5181
+```
+
+The package is `kavach-ai`; the command it installs is `kavach`. (`kavach` on
+npm belongs to an unrelated project.)
+
+The binary ships inside a small per-platform package that npm selects
+automatically, so there is no download step and nothing to fetch outside the
+registry — it installs cleanly behind a corporate proxy.
+
+No account needed for the free tier. The model runs on your CPU, works offline,
+and costs nothing — forever.
+
+## What runs where
+
+Kavach is a **hosted control plane** with a **local data plane**. The split is
+the point of the product:
+
+| | Where it lives |
+|---|---|
+| Chat sessions and messages | your machine |
+| Knowledge base — files, chunks, embeddings | your machine |
+| Agents you write, and their prompts | your machine |
+| Automations and workflow definitions | your machine |
+| Run history, traces, outputs | your machine |
+| Your model API keys | your machine, encrypted at rest |
+| Login, entitlement, billing | Kavach |
+| Licensed marketplace templates | Kavach |
+
+Your documents are chunked, embedded, and searched locally. They are never
+uploaded. Kavach could not produce them under subpoena, because Kavach never
+had them. The client is never issued a credential that can read Kavach's
+database — the control-plane API has no endpoint that returns tenant content,
+so a stolen token grants access to nothing.
+
+## Cost tiers
+
+The composer's toggle picks how a turn is served:
+
+- **free** — the bundled local model. Zero cost, works with the network
+  unplugged, needs no login.
+- **auto** — scores the task, then routes to the cheapest connected model that
+  can handle it. The default.
+- **paid** — always the strongest model you have connected.
+
+`auto` explains itself: hover the model chip to see which model answered and
+why.
+
+## Commands
+
+```
+kavach open              start the daemon and open the studio
+kavach serve             start the daemon without opening a browser
+kavach install model     download the local model that fits this machine
+kavach install whisper   add local speech-to-text (~148MB)
+kavach install router    add the routing model used by `auto` (~500MB)
+kavach install engine    the inference engine only, without a model
+kavach model list        show the models this machine can run
+kavach model use <id>    switch local models
+kavach doctor            check the install and report anything wrong
+kavach status            show entitlement and configuration
+kavach login             link this install to a Kavach account
+```
+
+## Local models
+
+`kavach install model` probes the machine and picks:
+
+| ID | Model | Download | Needs |
+|---|---|---|---|
+| `qwen3.5-2b` | Qwen3.5-2B, Opus-distilled | 1.5GB | 3GB free RAM, 2 cores |
+| `qwen3.5-4b` | Qwen3.5-4B v2, Opus-distilled | 2.6GB | 6GB free RAM, 4 cores |
+
+Selection is deliberately conservative and judged on *available* memory, not
+installed: a machine with 16GB installed and 1GB free will OOM exactly like a
+2GB machine. If the machine later has room for a better model, `kavach doctor`
+says so.
+
+These are small models. They are good at chat, summarisation, and extraction,
+and they will visibly struggle with long tool-calling agent runs. That is what
+`auto` is for.
+
+## How `auto` decides
+
+By default `auto` scores a request with a built-in heuristic: deterministic,
+offline, no download, no added latency.
+
+An optional routing model (Qwen3.5-0.8B plus the `acrouter` LoRA) scores more
+accurately. It is **not** a download — upstream publishes the adapter as
+safetensors against a safetensors base, and llama.cpp needs GGUF for both, so
+building it is a one-time local conversion. `kavach install router` prints the
+exact commands.
+
+Routing never fails closed: if the model is absent, cold, or slow, `auto`
+falls back to the heuristic. Failing to decide which model answers would mean
+not answering at all.
+
+## Speech to text
+
+`kavach install whisper` adds whisper.cpp. Prebuilt engines are not published
+for every platform; where none exists the command says so and prints the two
+commands that build it, rather than reporting success and leaving you with a
+microphone button that fails.
+
+Dictated audio is transcribed on your machine and never leaves it — a voice
+note is exactly the kind of content this architecture exists to keep local. The
+transcriber starts on first use, so installs that never touch the microphone
+pay nothing for it.
+
+## Trial and billing
+
+The trial is **7 days**, and the clock lives on Kavach's servers keyed to your
+installation — reinstalling or deleting `~/.kavach` does not restart it.
+
+When a trial or subscription lapses, Kavach becomes **read-only**:
+
+- everything you created is still there and still readable
+- writes are refused, and scheduled agents stop running
+- nothing is deleted, and billing keeps working so you can resume
+
+**Your local model and local data are never gated.** A personal install has no
+login, no entitlement and no network requirement; `kavach chat` works forever,
+lapsed subscription or not. Read-only applies only to a deployment running in
+org mode, where Kavach is serving a team.
+
+## Automations
+
+Scheduled automations in personal mode **run only while this machine is
+awake**. A missed schedule fires once on wake, marked as a catch-up, rather
+than replaying every slot that was missed while the laptop was closed.
+
+For schedules that must be reliable, deploy the same binary on always-on
+infrastructure you own (a VM, your Docker host, your cluster) and point the
+team's browsers at it. Same product, same data ownership, plus shared knowledge
+bases, shared agents, and cron that actually fires.
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `KAVACH_HOME` | Install root. Default `~/.kavach` |
+| `KAVACH_LLAMA_SERVER` | Use your own llama.cpp build (e.g. compiled for your GPU) |
+| `KAVACH_WHISPER_SERVER` | Use your own whisper.cpp build |
+| `KAVACH_LLAMA_RELEASE_BASE` | Mirror for llama.cpp engine downloads |
+| `KAVACH_WHISPER_RELEASE_BASE` | Mirror for whisper.cpp engine downloads |
+| `KAVACH_BINARY` | Run a specific binary, e.g. one you built yourself |
+| `KAVACH_LOG` | Log filter, e.g. `kavach_client=debug` |
+
+## Uninstalling
+
+```bash
+npm uninstall -g kavach-ai
+rm -rf ~/.kavach
+```
+
+Everything Kavach stored is under that one directory, which is also all you
+need to back up.
+
+## Licence
+
+MIT.

package/bin/kavach.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Launcher. Hands every argument to the native daemon.
+ *
+ * The wrapper stays as thin as possible: no argument parsing, no config
+ * reading, no business logic. Anything implemented here would have to be
+ * implemented a second time for people who run the binary directly, and the
+ * two copies would drift.
+ */
+
+const { spawn } = require('child_process');
+
+const { binaryPath, developmentBinary, detect } = require('../scripts/platform');
+
+function resolve() {
+  let info;
+  try {
+    info = detect();
+  } catch (error) {
+    // Unsupported platform — detect() already explains what to do.
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  const installed = binaryPath();
+  if (installed) return installed;
+
+  // Working on the daemon itself: a locally-built binary beats reinstalling.
+  const local = developmentBinary();
+  if (local) return local;
+
+  console.error(
+    `kavach: the binary for ${info.key} is not installed.\n\n` +
+      `It ships in ${info.package}, an optional dependency of this package.\n` +
+      `Installers skip optional dependencies when given --no-optional or\n` +
+      `--omit=optional, and some CI caches drop them.\n\n` +
+      `  Fix:    npm install -g kavach-ai --include=optional\n` +
+      `  Build:  cargo build --release -p kavach-client\n`
+  );
+  process.exit(1);
+}
+
+function main() {
+  const child = spawn(resolve(), process.argv.slice(2), { stdio: 'inherit' });
+
+  // Forward termination so Ctrl-C in the terminal stops the daemon rather
+  // than orphaning it holding the port and gigabytes of model memory.
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => child.kill(signal));
+  }
+
+  child.on('exit', (code, signal) => {
+    // Reproduce signal death as the conventional 128+n so shell scripts and
+    // supervisors see what actually happened.
+    process.exit(signal ? 128 + signalNumber(signal) : code ?? 0);
+  });
+
+  child.on('error', (error) => {
+    console.error(`kavach: could not start the daemon — ${error.message}`);
+    process.exit(1);
+  });
+}
+
+function signalNumber(signal) {
+  return { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 }[signal] ?? 0;
+}
+
+main();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "kavach-ai",
+  "version": "0.1.0",
+  "description": "Kavach — your agents, your data, your machine. Runs a local AI model and studio on your own hardware.",
+  "keywords": [
+    "ai",
+    "agents",
+    "local-first",
+    "llm",
+    "privacy",
+    "knowledge-base"
+  ],
+  "license": "MIT",
+  "homepage": "https://bluehawks.ai/kavach",
+  "bin": {
+    "kavach": "bin/kavach.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/platform.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test \"scripts/*.test.js\"",
+    "build:platforms": "node scripts/build-platform-packages.js",
+    "prepublishOnly": "node scripts/no-publish.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@kavach-ai/cli-darwin-arm64": "0.1.0",
+    "@kavach-ai/cli-darwin-x64": "0.1.0",
+    "@kavach-ai/cli-linux-x64": "0.1.0",
+    "@kavach-ai/cli-linux-arm64": "0.1.0"
+  }
+}

package/scripts/platform.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * Locating the native binary.
+ *
+ * ## Why the binary ships inside npm packages rather than being downloaded
+ *
+ * The obvious design is a postinstall that fetches a release asset from
+ * GitHub. It cannot work here: the source repository is private, and a private
+ * repo's release assets are not anonymously downloadable, so every install
+ * would 404. Publishing the binaries to a second public repo would mean
+ * running release infrastructure whose only job is to be public.
+ *
+ * So the binaries are published as per-platform npm packages —
+ * `@kavach-ai/cli-linux-x64` and friends — and this package lists them as
+ * `optionalDependencies`. npm reads each one's `os`/`cpu` fields and installs
+ * only the one that matches, skipping the rest. This is what esbuild, swc and
+ * turbo do, and it buys three things beyond solving the private-repo problem:
+ * no network call outside the registry (so it works behind a corporate proxy
+ * that allows npm and nothing else), no checksum logic to get wrong, and an
+ * install that either fully succeeds or fully fails.
+ *
+ * Only compiled binaries are published. No source of any kind is in the
+ * tarballs — see `files` in package.json and the platform-package generator.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Platform package per `${process.platform}-${process.arch}`.
+ *
+ * Kept as a literal map rather than built by string concatenation so that
+ * `require.resolve` sees a static name and bundlers do not have to guess.
+ */
+const PACKAGES = {
+  'darwin-arm64': '@kavach-ai/cli-darwin-arm64',
+  'darwin-x64': '@kavach-ai/cli-darwin-x64',
+  'linux-x64': '@kavach-ai/cli-linux-x64',
+  'linux-arm64': '@kavach-ai/cli-linux-arm64',
+};
+
+/** Rust target triples, used by the release build and the generator. */
+const TARGETS = {
+  'darwin-arm64': 'aarch64-apple-darwin',
+  'darwin-x64': 'x86_64-apple-darwin',
+  'linux-x64': 'x86_64-unknown-linux-gnu',
+  'linux-arm64': 'aarch64-unknown-linux-gnu',
+};
+
+// Windows (`win32-x64` / `x86_64-pc-windows-msvc`) is deliberately absent as of
+// 0.1.0. It is not unsupported in principle — the `.exe` handling below and in
+// the platform-package generator is intact and the Rust target builds — there
+// was simply no Windows machine available to build and smoke-test on when this
+// released, and shipping a Windows binary nobody has ever run is worse than
+// shipping none: `detect` below tells those users to build from source, whereas
+// a listed-but-missing package installs cleanly and then cannot find its
+// binary. Restore both entries above once a Windows build is verified.
+
+/**
+ * Resolve the platform package for the current machine.
+ *
+ * @throws {Error} naming the supported set, on an unsupported platform
+ */
+function detect(platform = process.platform, arch = process.arch) {
+  const key = `${platform}-${arch}`;
+  const pkg = PACKAGES[key];
+
+  if (!pkg) {
+    // "Unsupported platform" with no further detail is the message that
+    // generates support tickets. Name what is supported and the way out.
+    throw new Error(
+      `Kavach has no prebuilt binary for ${key}.\n` +
+        `Supported: ${Object.keys(PACKAGES).join(', ')}.\n` +
+        `You can build from source: cargo build --release -p kavach-client`
+    );
+  }
+
+  return {
+    key,
+    package: pkg,
+    target: TARGETS[key],
+    binaryName: platform === 'win32' ? 'kavach.exe' : 'kavach',
+  };
+}
+
+/**
+ * Absolute path to the installed binary, or `null` when the platform package
+ * is not present.
+ *
+ * `null` rather than a throw: a missing optional dependency is a recoverable
+ * install problem with a known fix, and the caller prints that fix.
+ */
+function binaryPath(platform = process.platform, arch = process.arch) {
+  const { package: pkg, binaryName } = detect(platform, arch);
+
+  try {
+    // Resolve the package's own manifest rather than a path inside it — that
+    // works regardless of how the installer laid the tree out (hoisted,
+    // nested, pnpm's symlinked store).
+    const manifest = require.resolve(`${pkg}/package.json`, { paths: [__dirname] });
+    const candidate = path.join(path.dirname(manifest), 'bin', binaryName);
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Where a locally-built binary lives, for developers working on the daemon. */
+function developmentBinary() {
+  const override = process.env.KAVACH_BINARY;
+  if (override) return fs.existsSync(override) ? override : null;
+
+  const { binaryName } = detect();
+  for (const profile of ['dist', 'release', 'debug']) {
+    const candidate = path.resolve(__dirname, '..', '..', '..', 'target', profile, binaryName);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+module.exports = { PACKAGES, TARGETS, detect, binaryPath, developmentBinary };