@tryvira/sdk 0.1.25 → 0.1.27

package/README.md

@@ -1,94 +1,150 @@
 # @tryvira/sdk
 
-MIT-licensed client library. The Vira service, application, and backend remain
-proprietary and are governed separately.
-
-Typed JavaScript/TypeScript client for Vira's scoped control and runtime APIs.
+The official JavaScript and TypeScript client for Vira. Use it to connect an AI
+application, record observations, author governed behavior, evaluate changes, release
+approved behavior, and resolve it at runtime.
 
 ## Install
 
 ```bash
-npm install @tryvira/sdk
+npm install @tryvira/sdk@0.1.26
 ```
 
-The client sends requests to Vira; it does not execute tools locally or create a second
-authority/telemetry store. Use a customer API key for hosted deployments and a local
-development key only with the local stack.
+Configure the organization, project, and environment for every request. Keep the API
+key server-side.
+
+```bash
+export VIRA_CONTROL_URL="https://api.tryvira.xyz"
+export VIRA_API_KEY="<your-vira-api-key>"
+export VIRA_ORGANIZATION_ID="<organization-id>"
+export VIRA_PROJECT_ID="<project-id>"
+export VIRA_ENVIRONMENT_ID="<environment-id>"
+```
 
 ## Connect and record an observation
 
 ```ts
-import { ViraClient } from '@tryvira/sdk';
+import { randomUUID } from "node:crypto";
+import { ViraClient } from "@tryvira/sdk";
+
+const scope = {
+  organizationId: process.env.VIRA_ORGANIZATION_ID!,
+  projectId: process.env.VIRA_PROJECT_ID!,
+  environmentId: process.env.VIRA_ENVIRONMENT_ID!,
+};
 
 const vira = new ViraClient({
-  baseUrl: process.env.VIRA_CONTROL_URL ?? 'http://127.0.0.1:4185',
+  baseUrl: process.env.VIRA_CONTROL_URL!,
   apiKey: process.env.VIRA_API_KEY,
 });
 
 const connected = await vira.connectOnce({
-  name: 'my-agent', systemType: 'custom-agent',
-  organizationId: 'org', projectId: 'project', environmentId: 'local',
-  adapterType: 'custom-node', adapterVersion: '1',
+  ...scope,
+  name: "support-agent",
+  systemType: "custom-agent",
+  adapterType: "custom-node",
+  adapterVersion: "1.0.0",
+  idempotencyKey: "connect:support-agent:1",
 });
 
-const systemId = String(connected?.body.system?.id);
-const connectionId = String(connected?.body.connection?.id);
 await vira.observe({
-  eventId: `event-${Date.now()}`,
-  eventType: 'model.response',
-  aiSystemId: systemId,
-  connectionId,
-  payload: { message: 'A model response was produced.' },
-}, { idempotencyKey: `event-${Date.now()}` });
+  eventId: randomUUID(),
+  eventType: "model.response",
+  aiSystemId: String(connected.body.system.id),
+  connectionId: String(connected.body.connection.id),
+  payload: { task: "billing question", outcome: "completed" },
+}, { idempotencyKey: `observation:${randomUUID()}` });
 ```
 
-## Semantic and runtime resolution
+`connectOnce` is idempotent when the same identity and idempotency key are retried.
+Observations are evidence for authoring and evaluation; they do not grant runtime
+authority.
+
+## Resolve behavior at runtime
 
-Semantic resolution finds an eligible governed target. Runtime resolution is the effectful
-boundary and therefore requires a released behavior point, scope and idempotency key.
+Semantic resolution helps select a candidate. Runtime resolution is the enforcing
+boundary and checks scope, policy, release state, and the requested behavior identity.
 
 ```ts
 const semantic = await vira.resolveSemantic({
-  input: 'answer a customer billing question',
-  profile: { domain: 'support' },
+  input: "Answer a customer billing question",
+  profile: { domain: "support" },
 });
 
 const runtime = await vira.resolveRuntime({
-  behaviorPoint: 'support.answer',
-  executionBoundary: { organizationId: 'org', projectId: 'project', environmentId: 'local' },
-  idempotencyKey: 'runtime-request-001',
+  behaviorPoint: "support.answer_billing",
+  executionBoundary: scope,
+  idempotencyKey: "runtime:billing:request-001",
 });
+
+if (runtime.body.decision !== "ALLOW") {
+  throw new Error(`Vira denied runtime resolution: ${runtime.body.reason ?? "unknown"}`);
+}
 ```
 
-Do not treat a semantic result as authorization. The server remains the authority and may
-abstain, deny or require a released revision.
+Do not treat a semantic match, a score, or a strategy activation as a release. The
+server may deny or abstain when no eligible immutable revision exists.
 
-## Packs and Strategy executions
+## Create and release a Pack
 
-The normal pack lifecycle is import → install → evaluate → approve → release. Strategy
-execution starts only from an immutable, released artifact and can be continued with
-state/references when it reaches `WAITING_USER` or `WAITING_HOST`.
+Use a Pack when a Task, Behavior Point, Program, Strategy, signals, and evaluation
+material should move together. A Pack is a candidate until it has been evaluated,
+approved, and released.
 
 ```ts
-const packs = await vira.listPacks();
 const imported = await vira.importPack({
-  manifest: { id: 'example.pack', name: 'Example', version: '1.0.0' },
-  objects: {},
-  idempotencyKey: 'pack-import-001',
+  manifest: { id: "support.billing", name: "Billing support behavior", version: "1.0.0" },
+  objects: {
+    semanticTasks: [{
+      taskKey: "support.answer_billing",
+      description: "Answer billing questions using available account evidence",
+      examples: ["Why was I charged twice?"],
+    }],
+    behaviorPoints: [{
+      key: "support.answer_billing",
+      taskKey: "support.answer_billing",
+      requirement: "Be accurate, cite evidence, and ask for missing account context",
+    }],
+  },
+  idempotencyKey: "pack:import:support.billing:1.0.0",
 });
-console.log(packs?.body, imported?.body);
 
-const continued = await vira.continueStrategyExecution('execution-id', {
-  authorityDigest: 'digest-from-the-execution',
-  state: { answer: 'approved' },
-  references: { userInput: { answer: 'approved' } },
+const packId = String(imported.body.pack.id);
+await vira.installPack(packId, { variables: {} });
+const evaluation = await vira.evaluatePack(packId, {
+  candidateExecutionRequired: true,
+  rubric: {
+    taskCorrectness: 1,
+    behaviorCompliance: 1,
+    groundedness: 1,
+    safetyAuthority: 1,
+    usefulSpecificity: 1,
+  },
+  idempotencyKey: "pack:evaluate:support.billing:1.0.0",
 });
-
-// Pack evaluation consumes a persisted, server-verified evaluation. The SDK
-// never accepts a client-provided passed/score as release evidence.
-await vira.evaluatePack('pack-id', { evaluationId: 'evaluation-id' });
+if (evaluation.body.passed !== true) throw new Error("Candidate evaluation failed");
+await vira.approvePack(packId);
+await vira.releasePack(packId);
 ```
 
+Never submit a client-created `passed`, `score`, or receipt as release evidence. Vira
+binds evaluation to the materialized Pack digest and immutable release identity. Use
+`previewPackUpgrade` before changing an installed Pack so conflicts and preserved
+overrides are visible first.
+
+## Errors and retries
+
+- Send an idempotency key with mutations.
+- Treat `401`/`403` as credential or scope errors; do not retry blindly.
+- Treat a runtime deny or abstain as a governed decision, not permission to bypass Vira.
+- Persist request IDs and receipts with application logs for support and audit.
+
 ## Documentation
 
-See the public Vira documentation at https://github.com/hrpering/tryvira.
+- [Developer guide](https://github.com/hrpering/tryvira/blob/main/docs/developer-guide.md)
+- [Pack authoring](https://github.com/hrpering/tryvira/blob/main/docs/packs.md)
+- [Runtime and release](https://github.com/hrpering/tryvira/blob/main/docs/runtime.md)
+- [API reference](https://github.com/hrpering/tryvira/blob/main/docs/reference/api.md)
+
+The client library is MIT licensed. The hosted Vira service and backend are governed
+separately.

package/dist/index.js

@@ -653,7 +653,12 @@ var ViraClient = class {
   }
   createTeachAnalysis(evidenceIds, options = {}) {
     if (!Array.isArray(evidenceIds) || evidenceIds.length < 1) throw new Error("SDK_TEACH_ANALYSIS_EVIDENCE_REQUIRED");
-    return this.request({ method: "POST", path: "/v1/teach/analyses", body: { evidenceIds: [...evidenceIds] } }, { idempotencyKey: options.idempotencyKey ?? `sdk:teach:analysis:${evidenceIds.join(",")}` });
+    const body = { evidenceIds: [...evidenceIds] };
+    if (options.analysisId) body.analysisId = options.analysisId;
+    if (options.controlPointId) body.controlPointId = options.controlPointId;
+    if (options.summary) body.summary = options.summary;
+    const requestKey = JSON.stringify([evidenceIds, options.analysisId ?? "", options.controlPointId ?? "", options.summary ?? ""]);
+    return this.request({ method: "POST", path: "/v1/teach/analyses", body }, { idempotencyKey: options.idempotencyKey ?? `sdk:teach:analysis:${requestKey}` });
   }
   getTeachAnalysis(analysisId) {
     required(analysisId, "SDK_TEACH_ANALYSIS_ID_REQUIRED");

package/dist/js-client.d.ts

@@ -382,6 +382,9 @@ export declare class ViraClient {
     }): Promise<ViraResponse<ClientBody> | null>;
     createTeachAnalysis(evidenceIds: readonly string[], options?: {
         idempotencyKey?: string;
+        analysisId?: string;
+        controlPointId?: string;
+        summary?: string;
     }): Promise<ViraResponse<ClientBody> | null>;
     getTeachAnalysis(analysisId: string): Promise<ViraResponse<ClientBody> | null>;
     createTeachProposal(input: ClientBody, options?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryvira/sdk",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Typed Vira SDK for connect-once, observation and governed runtime execution.",
   "keywords": ["vira", "ai-governance", "ai-runtime", "semantic-routing"],
   "engines": {"node": ">=20"},