@qvac/sdk 0.4.1 → 0.6.0

package/README.md

@@ -1,14 +1,25 @@
-[![QVAC logo](https://tether-2.gitbook.io/qvac-by-tether-or-reference/y2AsIh94H9DJ1pIBCNj9/~gitbook/image?url=https%3A%2F%2F4184520186-files.gitbook.io%2F~%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Forganizations%252Fnu0sKQdYg5T0N88iY6ZN%252Fsites%252Fsite_Fu2B8%252Flogo%252Fto5sbpix5Uz6MFPzPwY1%252FVector.png%3Falt%3Dmedia%26token%3D27902e06-6941-413c-a199-1e2780444d1a&width=260&dpr=2&quality=100&sign=8040ed76&sv=2)](https://tether-2.gitbook.io/qvac-by-tether-or-reference/y2AsIh94H9DJ1pIBCNj9)
+[![QVAC logo](docs/logo.avif)](https://qvac.tether.dev)
 
 ---
 
-**QVAC** is an open-source, cross-platform system for building local-first, peer-to-peer **AI applications**. QVAC runs on [**Bare**](https://bare.pears.com) by [Holepunch](https://holepunch.to), a lightweight, cross-platform JavaScript runtime.
+**QVAC** is an open-source, cross-platform **ecosystem** for local-first, peer-to-peer **AI**. QVAC runs on [**Bare**](https://bare.pears.com) by [Holepunch](https://holepunch.to), a lightweight, cross-platform JavaScript runtime.
 
 # QVAC SDK
 
-**QVAC SDK** is the canonical entry point to QVAC. Written in TypeScript, it provides all QVAC capabilities through a unified interface while also abstracting away the complexity of running your application in a JS environment other than Bare.
+**QVAC SDK** is the canonical entry point to develop AI applications with QVAC.
 
-For the comprehensive reference, [see official QVAC documentation](https://tether-2.gitbook.io/qvac-by-tether-or-reference/y2AsIh94H9DJ1pIBCNj9).
+> _Part of **QVAC** ecosystem_
+> <br>
+> <sup>
+> <a href="https://qvac.tether.dev" >Home</a> &nbsp;•&nbsp;
+> <a href="https://qvac.tether.dev/docs" >Docs</a> &nbsp;•&nbsp;
+> <a href="https://qvacbytether.featurebase.app" >Support</a> &nbsp;•&nbsp;
+> <a href="https://discord.com/invite/tetherdev" >Discord</a>
+> </sup>
+
+Written in TypeScript, it provides all QVAC capabilities through a unified interface while also abstracting away the complexity of running your application in a JS environment other than Bare.
+
+For the comprehensive reference, [see official QVAC documentation](https://qvac.tether.dev/docs).
 
 ## Requirements
 
@@ -16,65 +27,29 @@ Supported JS environments: Bare, Node.js, Expo and Bun.
 
 ## Installation
 
-### Steps
-
-1. [Authenticate to Tether’s GitHub packages](#step-1-authenticate-to-tethers-github-packages)
-2. [Install package and dependencies](#step-2-install-package-and-dependencies)
-
-### Step 1: authenticate to Tether’s GitHub packages
-
-1. [Create a GitHub personal access token (classic) with scope `read:packages`](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic).
-
-2. Add the token to your environment variables. For example, on macOS/Linux:
-
-```bash
-export NPM_TOKEN=<token_generated_in_previous_step>
-```
-
-3. In the root of your project, create file `.npmrc` with the following content:
-
-```ini
-@qvac:registry=https://registry.npmjs.org
-//registry.npmjs.org/:_authToken=${NPM_TOKEN}
-```
-
-_Alternatively, you can create the `.npmrc` file in your home directory, for user-level (global) configuration._
-
-4. Confirm authentication to Tether’s GitHub packages:
-
 ```bash
-npm whoami --registry=https://npm.pkg.github.com
+npm install @qvac/sdk
 ```
 
-It should return your GitHub username.
+### Linux
 
-### Step 2: Install package and dependencies
-
-1. Install in your project using the package manager of your choice:
+OS peer dependency:
 
 ```bash
-npm i @qvac/sdk
+apt install vulkan-sdk
 ```
 
-> [!TIP]  
-> If you can't get the package via Tether's private GitHub package registry, see section [Build from source](#build-from-source).
-
-#### On Linux
-
-> [!IMPORTANT]  
-> If you're on Linux ensure that the Vulkan SDK is installed (e.g. `apt install vulkan-sdk` on Ubuntu)
-
-#### On Expo
+### Expo
 
-1. Install the peer dependencies for Expo/React Native support:
+1. Peer dependencies:
 
 ```bash
 npm i expo-file-system react-native-bare-kit
 ```
 
-2. If you are on Android, bump your `minSdkVersion` to 29. You can do so by adding `ext { minSdkVersion=29 }` to your `android/build.gradle` or by using `expo-build-properties`.
+2. On Android, bump `minSdkVersion` to 29, by adding `ext { minSdkVersion=29 }` to `android/build.gradle` or using `expo-build-properties`.
 
-3. Add the QVAC Expo plugin to your `app.json`:
+3. Add the QVAC Expo plugin to `app.json`:
 
 ```js
 export default {
@@ -101,78 +76,81 @@ npx expo run:android --device
 > [!IMPORTANT]  
 > Due to limitations with `llamacpp`, QVAC currently does not run on emulators. You **must** use a physical device.
 
-## Quickstart
-
-You can run the self-contained example below:
+## Usage
 
 ```js
-import { loadModel, completion, unloadModel } from "@qvac/sdk";
-
-// Load model into memory
-const modelId = await loadModel(
-  "pear://afa79ee07c0a138bb9f11bfaee771fb1bdfca8c82d961cff0474e49827bd1de3/Llama-3.2-1B-Instruct-Q4_0.gguf",
-  {
+import {
+  completion,
+  LLAMA_3_2_1B_INST_Q4_0,
+  loadModel,
+  downloadAsset,
+  unloadModel,
+  VERBOSITY,
+} from "@qvac/sdk";
+try {
+  // First just cache the model
+  await downloadAsset({
+    assetSrc: LLAMA_3_2_1B_INST_Q4_0,
+    onProgress: (progress) => {
+      console.log(progress);
+    },
+  });
+  // Then load it in memory from cache
+  const modelId = await loadModel({
+    modelSrc: LLAMA_3_2_1B_INST_Q4_0,
     modelType: "llm",
-  },
-);
-
-// Use the loaded model
-const response = completion({
-  modelId,
-  history: [{ role: "user", content: "What is the capital of France?" }],
-  stream: false,
-});
-const text = await response.text;
-console.log(text);
-
-// Enable KV cache for faster subsequent completions
-const cachedResponse = completion({
-  modelId,
-  history: [
-    { role: "user", content: "What is the capital of France?" },
-    { role: "assistant", content: "The capital of France is Paris." },
-    { role: "user", content: "What about Germany?" },
-  ],
-  stream: true,
-  kvCache: true, // enables caching for faster inference
-});
-
-// You can use the loaded model multiple times
-
-// Unload model to free up system resources
-await unloadModel({ modelId });
-process.exit();
+    modelConfig: {
+      device: "gpu",
+      ctx_size: 2048,
+      verbosity: VERBOSITY.ERROR,
+    },
+  });
+  const history = [
+    {
+      role: "user",
+      content: "Explain quantum computing in one sentence, use lots of emojis",
+    },
+  ];
+  const result = completion({ modelId, history, stream: true });
+  for await (const token of result.tokenStream) {
+    process.stdout.write(token);
+  }
+  const stats = await result.stats;
+  console.log("\n📊 Performance Stats:", stats);
+  // Change `clearStorage: true` to delete cached model files
+  await unloadModel({ modelId, clearStorage: false });
+} catch (error) {
+  console.error("❌ Error:", error);
+  process.exit(1);
+}
 ```
 
-**For more on how to use QVAC SDK, see [SDK at QVAC documentation](https://tether-2.gitbook.io/qvac-by-tether-or-reference/y2AsIh94H9DJ1pIBCNj9/sdk)**.
-
-## Build from source
-
-Use the [Bun](https://bun.sh/) package manager:
-
-```bash
-bun i
-```
+## Functionalities
 
-```bash
-bun run build  # or `watch` for hotreload
-```
+### AI tasks
 
-```bash
-bun run build:pack
-```
+- Completion: LLM inference via [`llama.cpp`](https://github.com/ggml-org/llama.cpp).
+- Transcription: speech-to-text (ASR) via [`whisper.cpp`](https://github.com/ggml-org/whisper.cpp).
+- Text embeddings: via `llama.cpp`, for RAG.
+- Translation: between different languages.
+- Text-to-Speech: TTS via ONNX.
+- Multimodal: via [`llama.cpp`] — i.e., process and understand multiple types of media within the same conversation context.
+- RAG: retrieval-augmented generation with progress streaming, cancellation, and workspace management.
+- Delegated inference: perform peer-to-peer edge inference via Holepunch stack.
 
-This outputs a tarball under `dist/qvac-sdk-{version}.tgz` that you can install in your project, e.g.:
+### Utilities
 
-```bash
-npm i path/to/qvac-sdk-0.3.0.tgz
-```
+- Configuration: customize SDK behavior via config files (`qvac.config.json`, `.js`, or `.ts`).
+- Logging: visibility into what's happening inside your models during loading, inference, and other operations.
+- Download Lifecycle: pause and resume model downloads.
+- Blind Relays: establish peer connections through NAT/firewalls by routing traffic through relay nodes.
+- Sharded models: download a model that is sharded into multiple parts.
 
 ## Examples
 
-In the `./examples` subdirectory, you will find scripts demonstrating SDK usage. To try any of them:
+In the `./examples` subdirectory, you will find scripts demonstrating how to use all SDK functionalities. To try any of them:
 
-1. Follow the steps in section [Build from source](#build-from-source).
+1. Build the SDK from source (see [Build](#build) section).
 2. Run using Bare, Node.js, or Bun as the runtime:
 
 ```bash
@@ -186,139 +164,326 @@ node dist/examples/path/to/example.js
 bun run examples/path/to/example.ts
 ```
 
-## Logging
+### Completion
+
+- `llama.cpp` with local files: [`examples/llamacpp-filesystem.ts`](examples/llamacpp-filesystem.ts)
+- `llama.cpp` with Hyperdrive: [`examples/llamacpp-hyperdrive.ts`](examples/llamacpp-hyperdrive.ts)
+- `llama.cpp` with HTTP: [`examples/llamacpp-http.ts`](examples/llamacpp-http.ts)
+- `llama.cpp` with tools/function calls: [`examples/llamacpp-native-tools.ts`](examples/llamacpp-native-tools.ts)
+- `llama.cpp` with multimodal inference: [`examples/llamacpp-multimodal.ts`](examples/llamacpp-multimodal.ts)
+- `llama.cpp` with KV cache: [`examples/kv-cache-example.ts`](examples/kv-cache-example.ts)
 
-QVAC SDK includes built-in log propagation that streams model logs from the worker process to your client application in real-time. This gives you visibility into what's happening inside your models during loading, inference, and other operations.
+### Transcription
 
-### Usage
+- `whisper.cpp` transcription: [`examples/whispercpp-filesystem.ts`](examples/whispercpp-filesystem.ts)
+- Microphone recording: [`examples/whispercpp-microphone-record.ts`](examples/whispercpp-microphone-record.ts)
 
-Simply pass a logger when loading your model:
+### Embeddings
 
-```js
-import { getLogger, loadModel, completion, unloadModel } from "@qvac/sdk";
-
-// Create a logger for your application
-const logger = getLogger("my-app", {
-  level: "debug", // Set log level
-  transports: [
-    // Optional: add custom log handlers
-    (level, namespace, message) => {
-      console.log(`[${level.toUpperCase()}] ${namespace}: ${message}`);
-    },
-  ],
-});
+- Single and batch embeddings: [`examples/embed-hyperdrive.ts`](examples/embed-hyperdrive.ts)
 
-// Load model with logging - RPC stream starts automatically
-const modelId = await loadModel(
-  "pear://afa79ee07c0a138bb9f11bfaee771fb1bdfca8c82d961cff0474e49827bd1de3/Llama-3.2-1B-Instruct-Q4_0.gguf",
-  {
-    modelType: "llm",
-    logger, // Enable log streaming
-  },
-);
+**RAG with HyperDB** (cross-platform):
 
-// Now you'll see model logs in your console as operations happen
-for await (const token of completion({
-  modelId,
-  history: [{ role: "user", content: "Hello!" }],
-}).tokenStream) {
-  process.stdout.write(token);
-}
+- Ingest (full pipeline): [`examples/rag/rag-hyperdb/ingest.ts`](examples/rag/rag-hyperdb/ingest.ts)
+- Segregated pipeline: [`examples/rag/rag-hyperdb/pipeline.ts`](examples/rag/rag-hyperdb/pipeline.ts) _(Segregated flow: chunk → embed → save)_
+- Workspaces: [`examples/rag/rag-hyperdb/workspaces.ts`](examples/rag/rag-hyperdb/workspaces.ts) _(Workspace lifecycle: list, close, delete)_
+- Cancellation: [`examples/rag/rag-hyperdb/cancellation.ts`](examples/rag/rag-hyperdb/cancellation.ts) _(progress + cancel)_
 
-await unloadModel({ modelId }); // Logging stream closes automatically
-```
+**RAG with other backends** (desktop only):
 
-### What You'll See
+- LanceDB: [`examples/rag/rag-lancedb.ts`](examples/rag/rag-lancedb.ts)
+- ChromaDB: [`examples/rag/rag-chromadb.ts`](examples/rag/rag-chromadb.ts) _(requires ChromaDB server)_
+- SQLite-Vector: [`examples/rag/rag-sqlite.ts`](examples/rag/rag-sqlite.ts) _(SQLite-Vector WASM)_
 
-When logging is enabled, you'll see real-time logs from the underlying model libraries:
+### Translation
 
-```
-[DEBUG] llamacpp:llm: Loading model weights...
-[INFO] llamacpp:llm: Model loaded successfully, vocab_size=32000
-[DEBUG] llamacpp:llm: Starting inference...
-[DEBUG] llamacpp:llm: Inference completed, tokens=12
-```
+- Marian OPUS translation: [`examples/translation/translation-opus.ts`](examples/translation/translation-opus.ts)
+- Indic language translation: [`examples/translation/translation-indic.ts`](examples/translation/translation-indic.ts)
+- LLM-based translation: [`examples/translation/translation-llm.ts`](examples/translation/translation-llm.ts)
 
-This works for all model types (LLM, Whisper, NMT, Embeddings) and provides valuable insight into model performance and behavior.
+### Text-to-Speech
 
-### Completion
+- TTS with [eSpeak](https://github.com/espeak-ng/espeak-ng): [`examples/text-to-speech.ts`](examples/text-to-speech.ts)
 
-- `llama.cpp` with local files: [`examples/llamacpp-filesystem.ts`](examples/llamacpp-filesystem.ts)
-- `llama.cpp` with Hyperdrive: [`examples/llamacpp-hyperdrive.ts`](examples/llamacpp-hyperdrive.ts)
-- `llama.cpp` with HTTP: [`examples/llamacpp-http.ts`](examples/llamacpp-http.ts)
-- `llama.cpp` with file logging: [`examples/llamacpp-file-logging.ts`](examples/llamacpp-file-logging.ts)
-- `llama.cpp` with tools/function calls: [`examples/llamacpp-tools.ts`](examples/llamacpp-tools.ts)
-- `llama.cpp` with tools and routing: [`examples/llamacpp-tools-routing.ts`](examples/llamacpp-tools-routing.ts)
-- `llama.cpp` with multimodal inference: [`examples/llamacpp-multimodal.ts`](examples/llamacpp-multimodal.ts)
-- `llama.cpp` with KV cache: [`examples/kv-cache-example.ts`](examples/kv-cache-example.ts)
+### Multimodel
 
-### Transcription
+- Load multiple models simultaneously: [`examples/multi-model-demo.ts`](examples/multi-model-demo.ts)
 
-- `whisper.cpp` transcription: [`examples/whispercpp-transcription.ts`](examples/whispercpp-transcription.ts)
-- Microphone recording: [`examples/microphone-record-transcription.ts`](examples/microphone-record-transcription.ts)
+### Delegated inference
 
-### Embeddings
+- Provider: [`examples/delegated-inference/provider.ts`](examples/delegated-inference/provider.ts)
+- Consumer: [`examples/delegated-inference/consumer.ts`](examples/delegated-inference/consumer.ts)
 
-- Embedding with Hyperdrive: [`examples/embed-hyperdrive.ts`](examples/embed-hyperdrive.ts)
-- RAG example with HyperDB: [`examples/rag-hyperdb.ts`](examples/rag-hyperdb.ts)
-- RAG with workspaces: [`examples/rag-hyperdb-workspaces.ts`](examples/rag-hyperdb-workspaces.ts) _(Demonstrates workspace isolation and chunking)_
-- RAG example with LanceDB (desktop only): [`examples/rag-lancedb.ts`](examples/rag-lancedb.ts)
-- RAG example with ChromaDB (desktop only): [`examples/rag-chromadb.ts`](examples/rag-chromadb.ts) _(Note: Requires ChromaDB server running)_
-- RAG example with SQLite-Vector (desktop only): [`examples/rag-sqlite.ts`](examples/rag-sqlite.ts) _(Note: Uses SQLite-Vector WASM)_
+> [!TIP]
+> Set `QVAC_HYPERSWARM_SEED` env var to ensure that the provider uses the same keypair (i.e., public key doesn't change on every run).
 
-### Translation
+> [!NOTE]
+> Consumer does not handle reconnection yet.
 
-- Marian OPUS translation: [`examples/translation-opus.ts`](examples/translation-opus.ts)
-- Indic language translation: [`examples/translation-indic.ts`](examples/translation-indic.ts)
-- LLM-based translation: [`examples/translation-llm.ts`](examples/translation-llm.ts)
+### Logging
 
-### Text to Speech
+Stream real-time logs from the SDK server and native addons:
 
-- Text to Speech: [`examples/text-to-speech.ts`](examples/text-to-speech.ts)
+```ts
+import { loggingStream, SDK_LOG_ID } from "@qvac/sdk";
 
-**Note**: To run the text-to-speech example, espeak data is required which can be obtained from [here](https://github.com/espeak-ng/espeak-ng).
+// SDK server logs (general operations)
+for await (const log of loggingStream({ id: SDK_LOG_ID })) {
+  console.log(`[${log.level}] ${log.namespace}: ${log.message}`);
+}
 
-### Multimodel
+// Addon logs per model (llamacpp, whispercpp, etc.)
+for await (const log of loggingStream({ id: modelId })) {
+  console.log(`[${log.level}] ${log.namespace}: ${log.message}`);
+}
+```
 
-- Load multiple models simultaneously: [`examples/multi-model-demo.ts`](examples/multi-model-demo.ts)
+- Log streaming: [`examples/logging-streaming.ts`](examples/logging-streaming.ts)
+- Log with custom file transport: [`examples/logging-file-transport.ts`](examples/logging-file-transport.ts)
 
-### Delegated inference
+### Configuration
 
-- Provider example: [`examples/delegated-inference/provider.ts`](examples/delegated-inference/provider.ts)
-- Consumer example: [`examples/delegated-inference/consumer.ts`](examples/delegated-inference/consumer.ts)
+Customize SDK behavior using a config file. The SDK auto-discovers `qvac.config.{json,js,ts}` in your project root, or you can specify a path via `QVAC_CONFIG_PATH` environment variable.
 
-**Note**: Set the `QVAC_HYPERSWARM_SEED` env var to ensure that the provider's uses the same keypair (i.e. the public key doesn't change on every run).
-**Note**: ⚠️ Consumer does not handle reconnection yet.
+**Supported formats:**
 
-### Download Lifecycle
+- `qvac.config.json` - JSON format
+- `qvac.config.js` - JavaScript with `export default`
+- `qvac.config.ts` - TypeScript with `export default`
 
-- Pause and resume download: [`examples/download-with-cancel.ts`](examples/download-with-cancel.ts)
+**Available options:**
 
-### Sharded Models
+| Option                    | Type       | Default          | Description                                         |
+| ------------------------- | ---------- | ---------------- | --------------------------------------------------- |
+| `cacheDirectory`          | `string`   | `~/.qvac/models` | Where models and assets are stored                  |
+| `swarmRelays`             | `string[]` | `[]`             | Hyperswarm relay public keys for P2P                |
+| `loggerLevel`             | `string`   | `"info"`         | Log level: `"error"`, `"warn"`, `"info"`, `"debug"` |
+| `loggerConsoleOutput`     | `boolean`  | `true`           | Enable/disable console output                       |
+| `httpDownloadConcurrency` | `number`   | `3`              | Max concurrent HTTP downloads for sharded models    |
+| `httpConnectionTimeoutMs` | `number`   | `10000`          | HTTP connection timeout in milliseconds             |
+
+- Config usage example: [`examples/default-config-usage.ts`](examples/default-config-usage.ts)
 
-- Load sharded models from Hyperdrive: [`examples/llamacpp-sharded.ts`](examples/llamacpp-sharded.ts)
-- Load models from local filesystem: [`examples/llamacpp-filesystem.ts`](examples/llamacpp-filesystem.ts)
+### Download Lifecycle
 
-**Note**: Sharded models automatically download all parts sequentially with detailed progress tracking per shard. For local sharded models, pass the path to the first shard file (e.g., `model-00001-of-00005.gguf`), and remaining shards will be loaded automatically.
+- Pause and resume download: [`examples/download-with-cancel.ts`](examples/download-with-cancel.ts)
 
 ### Blind Relays
 
 Blind relays help establish peer connections through NAT/firewalls by routing traffic through relay nodes.
 
 - Model downloads via Hyperdrive: [`examples/download-with-blind-relays.ts`](./examples/download-with-blind-relays.ts)
-- Delegated inference: You can reuse the same pattern for delegated inference by calling `setConfig({ swarmRelays: [...relayPublicKeys] })` before starting your provider/consumer.
+- Delegated inference: You can reuse the same pattern for delegated inference by adding `swarmRelays` to your config file before starting your provider/consumer.
+
+> [!NOTE]
+> The examples use mock relay keys. For real deployments, you **must** use your own relay servers or trusted public relays.
+
+### Sharded Models
+
+Sharded models are split into multiple files following the pattern: `<name>-00001-of-0000X.<ext>`. The SDK automatically downloads and loads all parts with detailed progress tracking.
+
+**Supported formats:**
+
+- Archives (`.tar`, `.tar.gz`, `.tgz`): HTTP or local with automatic extraction
+- HTTP sharded URL: pass the download URL of any shard and the SDK will fetch the remaining shards
+- Hyperdrive: use any sharded Hyperdrive model source
+- Local shards: pass the path to any shard file. _(Note: All shards must be in the same directory)_
+
+See: [`examples/llamacpp-sharded.ts`](examples/llamacpp-sharded.ts)
+
+## Basic flow
+
+```mermaid
+sequenceDiagram
+    participant User as User
+    participant SDK as QVAC SDK
+    participant RPC as RPC Client (singleton)
+    participant Worker as Bare Worker (singleton)
+
+    User->>SDK: Call loadModel("llama-3", options)
+    SDK->>RPC: Create runtime-specific RPC client
+    RPC->>Worker: Spawn worker (if needed) and send loadModel request
+    Worker->>Worker: Download and load model into memory
+    Worker->>RPC: Return success response
+    RPC->>SDK: Model loaded successfully
+    SDK->>User: loadModel() resolves with modelId
+```
 
 **Note**: The example uses mock relay keys. In real deployments, you **must** use your own relay servers or trusted public relays.
 
-## Known issues
+### Hot Config Reload
+
+Hot config reload allows you to update model configurations on-the-fly without unloading the model. Pass `modelId` (instead of `modelSrc`) to `loadModel` with the `modelType` and new `modelConfig` to apply changes instantly.
+
+- Config reload using whisper: [`examples/config-reload.ts`](examples/config-reload.ts)
+
+**Note**: Config reload is currently supported for Whisper models. All config parameters except `contextParams` (GPU settings, flash attention) can be hot reloaded. `contextParams` are load-time only and require full model reload. More model types coming soon.
+
+## Contributing
+
+### Commit Message and PR Title Format
+
+This repository enforces structured commit messages and PR titles to maintain consistency and generate changelogs automatically.
+
+#### Format
+
+**Commit messages:**
+
+```
+prefix[tags]?: subject
+```
+
+**PR titles:**
+
+```
+TICKET prefix[tags]: subject
+```
+
+#### Allowed Prefixes
+
+- `feat` - New features or capabilities
+- `fix` - Bug fixes
+- `doc` - Documentation changes
+- `test` - Test additions or modifications
+- `mod` - Model-related changes
+- `chore` - Maintenance tasks
+- `infra` - CI/CD, tooling, infrastructure
+
+#### Allowed Tags
+
+Tags are optional:
+
+- `[api]` - API changes (non-breaking)
+- `[bc]` - Breaking changes (including breaking API changes)
+
+#### Examples
+
+**Valid commit messages:**
+
+```bash
+feat: add RAG support for LanceDB
+fix[api]: fix completion stream error handling
+doc: update installation instructions
+feat[bc]: redesign loadModel signature
+chore: update dependencies
+```
+
+**Valid PR titles:**
+
+```bash
+QVAC-123 feat: add RAG support for LanceDB
+QVAC-456 fix[api]: fix completion stream error handling
+QVAC-789 doc: update installation instructions
+QVAC-101 feat[bc]: redesign loadModel signature
+```
+
+#### Code Examples Requirements
+
+When creating PRs with specific tags, you must include code examples in the PR description:
+
+**`[bc]` tag requirements:**
+
+Must include BEFORE/AFTER code examples showing the migration path:
+
+````markdown
+## BC Changes
+
+**BEFORE:**
+
+```typescript
+const model = await loadModel("model-path");
+```
+
+**AFTER:**
+
+```typescript
+const modelId = await loadModel("model-path", { modelType: "llm" });
+```
+````
+
+Or using inline comments:
+
+````markdown
+```typescript
+// old
+const model = await loadModel("model-path");
+
+// new
+const modelId = await loadModel("model-path", { modelType: "llm" });
+```
+````
+
+**`[api]` tag requirements (non-breaking):**
+
+Must include at least one fenced code block showing the new API usage:
+
+````markdown
+## New API
+
+```typescript
+// New completion API with streaming support
+for await (const token of completion({
+  modelId,
+  history: [{ role: "user", content: "Hello!" }],
+}).tokenStream) {
+  process.stdout.write(token);
+}
+```
+````
+
+#### Validation
+
+- **Commit messages** are validated automatically via Husky commit-msg hook
+- **PR titles and descriptions** are validated via GitHub Actions on PR creation/update
+- Invalid commits or PRs will be rejected with helpful error messages
+- **Auto-skipped commits:** The following Git-generated commits bypass validation:
+  - Merge commits (e.g., `Merge pull request #123`)
+  - Version bumps (e.g., `1.0.0`, `v1.0.0`)
+  - Revert commits (e.g., `Revert "feat: add feature"`)
+  - Squash commits (e.g., `squash! fix: bug fix`)
+
+#### Generating Changelogs
+
+Once your PRs are merged into `dev`, you can generate a changelog:
+
+```bash
+npm run changelog:generate
+```
+
+This will:
+
+1. Compare versions between `dev` and `main` branches
+2. Collect all merged PRs
+3. Parse and classify each PR by prefix
+4. Generate `changelog/<version>/CHANGELOG.md`
+5. Generate `changelog/<version>/breaking.md` for BC changes (with code examples)
+6. Generate `changelog/<version>/api.md` for API changes (with code examples)
+
+**Note:** Requires a GitHub token (`GITHUB_TOKEN` or `GH_TOKEN` environment variable) to fetch PR metadata.
+
+## Build
+
+Use the [Bun](https://bun.sh/) package manager:
+
+```bash
+bun i
+```
+
+```bash
+bun run build  # or `watch` for hotreload
+```
+
+```bash
+bun run build:pack
+```
+
+This outputs a tarball under `dist/qvac-sdk-{version}.tgz` that you can install in your project, e.g.:
+
+```bash
+npm i path/to/qvac-sdk-0.3.0.tgz
+```
 
-- **One off scripts don't terminate / hang**
-  - Add a `process.exit()` call at the end, we're working on it.
+## More Resources
 
-- **I'm building my Expo app on iOS but I don't see logs from QVAC**
-  - `npx expo start`
-  - Open the `ios` folder in Xcode
-  - Start the app with the play ▶️ button
-  - View -> Debug area -> Activate console
-  - You should see the system logs on the right pane
-  - ⚠️ This only works when starting the app from Xcode
+- [Comprehensive documentation of this SDK](https://qvac.tether.dev/docs/sdk)
+- [Package at NPM](https://www.npmjs.com/package/@qvac/sdk)