kyrodb

TypeScript SDK for KyroDB, the freshness-aware context runtime for AI systems.

The SDK is a typed, security-first HTTP client. It does not embed planner logic, perform vector search, bypass freshness checks, or synthesize proof evidence on the client side.

Install

npm install kyrodb

Quick Start

Use the managed runtime handoff from the KyroDB console:

1. Open Console -> Runtime -> Backend environment.
2. Click Create env command.
3. Run the generated one-time command from your backend project. It writes .env.kyrodb.
4. Load .env.kyrodb only in server-side code before calling KyroDBClient.fromEnv().

For local development, use your normal server env loader, such as dotenv, direnv, your process manager, or your deployment platform's secret store. Runtime bearer tokens must never be placed in browser JavaScript.

import { KyroDBClient, filters } from "kyrodb";
import { embedQuery } from "./your-app/embeddings.js";

const client = KyroDBClient.fromEnv();
const queryEmbedding = await embedQuery("How do refunds work?");

const packet = await client.retrieve({
  query_embedding: queryEmbedding,
  scope: {
    tenant_id: "default",
    namespace: "kb"
  },
  filters: filters.exact("category", "billing"),
  top_k: 3,
  freshness_mode: "balanced",
  include_content: true
});

console.log(packet.trace_id);

KyroDB does not create embeddings in the SDK. Use the same embedding model and dimension that populate your pgvector/Qdrant knowledge store; for example, a runtime configured with vector(1536) must receive a 1536-float query embedding.

Environment Loading

import { KyroDBClient } from "kyrodb";

const client = KyroDBClient.fromEnv();

fromEnv() reads:

• KYRODB_BASE_URL
• KYRODB_DATA_PLANE_TOKEN
• KYRODB_OBSERVABILITY_TOKEN
• KYRODB_SHADOW_SESSION_ID
• KYRODB_ALLOW_INSECURE_HTTP

Privilege Planes

Data-plane methods use dataPlaneToken:

• retrieve
• invalidate
• ingestChangeEvent
• upsertDocument
• deleteDocument
• recordFeedback

Calls that affect usage metering (retrieve, invalidate, upsertDocument, and deleteDocument) accept { idempotencyKey } as the second argument when your server wants deterministic retry identity. Change events use their required source_event_id field as the runtime idempotency key. Routes that do not advertise the Idempotency-Key runtime header accept only { signal } options so retry guarantees are not implied where the runtime will not honor them.

Observability and admin methods use observabilityToken:

• client.observability.getTrace
• client.observability.diagnoseTrace
• client.observability.contextProofReport
• client.admin.health
• client.admin.buildProofBundle
• client.admin.buildRootCauseReport
• client.admin.diffReplayRuns
• client.admin.runCounterfactualReplay
• client.admin.createShadowSession
• client.admin.exportReplayCapture

The SDK fails before network I/O if an observability/admin method is used without an observability token.

Shadow Sessions

Shadow sessions are isolated replay/serving sandboxes for design-partner candidate checks. Create one with an admin observability token, then pass the returned session_id as shadowSessionId or KYRODB_SHADOW_SESSION_ID.

The SDK sends the runtime header kyro-shadow-session-id only on routes that the gateway can serve from shadow-local state: retrieve, invalidation, change-event ingest, write-through mutation calls, feedback recording/lookup, trace lookup, and trace diagnosis. Admin artifact routes, including shadow-session creation, do not receive that header.

Security Defaults

• HTTPS is required outside loopback unless allowInsecureHttp is explicit.
• URL credentials, query strings, and fragments are rejected in baseUrl.
• Data-plane and observability tokens must be distinct unless explicitly allowed.
• Redirects are blocked.
• Request and response bodies are bounded.
• Error messages redact configured secrets and do not retain raw response bodies.
• JavaScript unsafe integer freshness generations are rejected on decode.
• Request validators reject non-finite numbers before JSON serialization.

Development

npm ci
npm run check

npm run check runs typecheck, lint, format check, tests, build, and release metadata validation against the pinned OpenAPI contract in contracts/.

Live runtime tests are opt-in and never run network calls unless explicitly enabled:

KYRODB_LIVE_TESTS=1 \
KYRODB_BASE_URL=https://runtime.example.com \
KYRODB_DATA_PLANE_TOKEN=... \
KYRODB_OBSERVABILITY_TOKEN=... \
KYRODB_TEST_QUERY_EMBEDDING="$REAL_QUERY_EMBEDDING_JSON" \
npm run test:live

Additional live gates:

• KYRODB_LIVE_EVENT_FEED_TESTS=1
• KYRODB_LIVE_WRITE_THROUGH_TESTS=1
• KYRODB_LIVE_REPLAY_TESTS=1

Gate variables accept either 1 or true.

The live gates default to tenant_id=default and namespace=kb; override with KYRODB_TEST_TENANT_ID and KYRODB_TEST_NAMESPACE when testing a different runtime principal scope. KYRODB_TEST_QUERY_EMBEDDING is required so release tests use a real embedding from the same model/dimension as the target connector, not a toy fixture.

The source-tree examples use the same production shape. Before running an example directly, provide:

export KYRODB_EXAMPLE_QUERY_EMBEDDING="$REAL_QUERY_EMBEDDING_JSON"
export KYRODB_EXAMPLE_TENANT_ID=default
export KYRODB_EXAMPLE_NAMESPACE=kb