@qvac/sdk

QVAC SDK

QVAC SDK is the canonical entry point to develop AI applications with QVAC.

Part of QVAC ecosystem
^{Home  •  Docs  •  Support  •  Discord}

QVAC SDK is the main entry point for developing applications with QVAC. It is type-safe and exposes all QVAC capabilities through a unified interface. It runs on Node.js, Bare runtime, and Expo.

See https://docs.qvac.tether.io/sdk/getting-started for the comprehensive QVAC documentation.

For AI/LLM tools, use https://docs.qvac.tether.io/llms-full.txt as the consolidated plaintext documentation export.

Assembling a custom worker on Bare? See @qvac/bare-sdk — the same SDK surface with no built-in plugin addons, designed for consumers wiring their own worker entry (Pear apps, bare-expo apps, direct Bare scripts).

Supported environments and installation

See https://docs.qvac.tether.io/sdk/getting-started/installation

Quickstart

• Create the examples workspace:

mkdir qvac-examples
cd qvac-examples
npm init -y && npm pkg set type=module

• Install the SDK:

npm install @qvac/sdk

• Create the quickstart script:

import { loadModel, LLAMA_3_2_1B_INST_Q4_0, completion, unloadModel } from "@qvac/sdk";
try {
    // Load a model into memory
    const modelId = await loadModel({
        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
        modelType: "llm",
        onProgress: (progress) => {
            console.log(progress);
        },
    });
    // You can use the loaded model multiple times
    const history = [
        {
            role: "user",
            content: "Explain quantum computing in one sentence",
        },
    ];
    const result = completion({ modelId, history, stream: true });
    for await (const token of result.tokenStream) {
        process.stdout.write(token);
    }
    // Unload model to free up system resources
    await unloadModel({ modelId });
}
catch (error) {
    console.error("❌ Error:", error);
    process.exit(1);
}

• Run the quickstart script:

node quickstart.js

Examples

In the ./examples subdirectory, you will find scripts demonstrating how to use all SDK functionalities. To try any of them:

• Build the SDK from source (see Build section).
• Run using Bare, Node.js, or Bun as the runtime:

# With Bare
bun run bare:example dist/examples/path/to/example.js

# With Node
node dist/examples/path/to/example.js

# With bun, straight from source
bun run examples/path/to/example.ts

Build

Use the Bun package manager:

bun i

bun run build  # or `watch` for hotreload

bun run build:pack

This outputs a tarball under dist/sdk-{version}.tgz that you can install in your project, e.g.:

npm i path/to/sdk-0.3.0.tgz

Testing

The SDK test suite is organized into three buckets by runtime:

Bucket	Runtime	Location	Command
Unit	Bun / Node	test/unit/	bun run test:unit
Server (Bare)	Bare	test/bare/	bun run test:bare
Client (consumer)	Node / RN	e2e/	See e2e/README.md

See TESTING.md for the full decision tree on where new tests should land.

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:

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:

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:

## BC Changes

**BEFORE:**

```typescript
const model = await loadModel("model-path");
```

**AFTER:**

```typescript
const modelId = await loadModel("model-path", { modelType: "llm" });
```

Or using inline comments:

```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:

## 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:

npm run changelog:generate

This will:

• Compare versions between dev and main branches
• Collect all merged PRs
• Parse and classify each PR by prefix
• Generate changelog/<version>/CHANGELOG.md
• Generate changelog/<version>/breaking.md for BC changes (with code examples)
• Generate changelog/<version>/api.md for API changes (with code examples)