ovrule-lab 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# Ovrule SDK
+
+TypeScript client for Ovrule case-file classification, guardrails, and receipt verification.
+
+## Install
+
+```bash
+npm install ovrule
+```
+
+## 1. Simple classify
+
+```ts
+import { classify } from "ovrule";
+
+const receipt = await classify("Support agent wants to refund $5,000 without manager approval.");
+
+console.log(receipt.decision);
+console.log(receipt.summary);
+```
+
+## 2. `guard()` around an agent tool call
+
+```ts
+import { guard } from "ovrule";
+
+const result = await guard({
+  scenario: "Finance agent wants to wire $18,000 to a new vendor after bank details changed.",
+  policyPack: "finance",
+});
+
+if (!result.allowed) {
+  console.error(result.decision, result.suggestedFixes);
+  throw new Error("Tool call blocked by Ovrule.");
+}
+
+await issueWireTransfer();
+```
+
+## 3. LangChain middleware integration
+
+```ts
+import { OvruleClient } from "ovrule";
+
+const ovrule = new OvruleClient({ baseUrl: "https://your-ovrule-deployment.vercel.app" });
+
+export async function beforeToolInvoke(input: string) {
+  const guard = await ovrule.guard({
+    scenario: input,
+    policyPack: "general",
+  });
+
+  if (!guard.allowed) {
+    return {
+      blocked: true,
+      receipt: guard.receipt,
+      fixes: guard.suggestedFixes,
+    };
+  }
+
+  return { blocked: false };
+}
+```
+
+## API
+
+- `classify(action, options?)`
+- `guard(action, options?)`
+- `verify(receipt, signature)`

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+export type Decision = "ADMISSIBLE" | "AMBIGUOUS" | "REFUSED";
+export type Verdict = "PASS" | "WARN" | "FAIL";
+export type PolicyPackId = "general" | "customer_support" | "healthcare" | "finance";
+export type RuleName = "SAFETY" | "AUTHORIZATION" | "CAUSAL VALIDITY" | "REVERSIBILITY" | "IMPACT SCOPE" | "CONSENT";
+export type RuleTraceItem = {
+    rule: RuleName;
+    verdict: Verdict;
+    reason: string;
+};
+export type AffectedParty = {
+    label: string;
+    type: "user" | "customer" | "employee" | "third_party" | "public" | "system" | "other";
+    impact: "low" | "medium" | "high";
+};
+export type EvidenceItem = {
+    label: string;
+    kind: "user_statement" | "policy" | "system_state" | "transaction_data" | "external_signal" | "other";
+    summary: string;
+};
+export type MissingInformationItem = {
+    field: string;
+    whyItMatters: string;
+    couldFlip: "PASS" | "WARN" | "FAIL" | "decision";
+};
+export type HistoryEvent = {
+    id: string;
+    receiptId: string;
+    eventType: "created" | "contested" | "overridden" | "revised" | "annotated";
+    actorType: "system" | "human_reviewer" | "user";
+    actorLabel?: string;
+    note?: string;
+    payload: Record<string, unknown>;
+    createdAt: string;
+};
+export type FixSuggestion = {
+    edit: string;
+    flips: string[];
+    rewrittenAction: string;
+};
+export type CaseFileReceipt = {
+    scenario: string;
+    decision: Decision;
+    proposedAction: string;
+    claimedGoal: string;
+    affectedParties: AffectedParty[];
+    authorityBasis: string;
+    evidenceUsed: EvidenceItem[];
+    evidenceMissing: EvidenceItem[];
+    severity: "low" | "medium" | "high";
+    riskScore: number;
+    summary: string;
+    whyOkay: string[];
+    whyFail: string[];
+    missingInformation: MissingInformationItem[];
+    ruleTrace: RuleTraceItem[];
+    receiptId: string;
+    hash: string;
+    timestamp: string;
+    receiptMetadata: {
+        receiptId: string;
+        hash: string;
+        timestamp: string;
+    };
+    history: HistoryEvent[];
+    challengeHistory: HistoryEvent[];
+    policyPack?: PolicyPackId;
+    suggestedFixes?: FixSuggestion[];
+    signature?: string;
+};
+export type ProposedAction = {
+    scenario: string;
+    claimedGoal?: string;
+    affectedParties?: string[];
+    authorityBasis?: string;
+    policyPack?: PolicyPackId;
+};
+export type GuardResult = {
+    allowed: boolean;
+    decision: Decision;
+    suggestedFixes: FixSuggestion[];
+    receipt: CaseFileReceipt;
+};
+export type OvruleClientOptions = {
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+};
+type RequestOptions = {
+    signal?: AbortSignal;
+    policyPack?: PolicyPackId;
+};
+export declare class OvruleClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: OvruleClientOptions);
+    classify(action: string | ProposedAction, options?: RequestOptions): Promise<CaseFileReceipt>;
+    guard(action: string | ProposedAction, options?: RequestOptions): Promise<GuardResult>;
+    verify(receipt: CaseFileReceipt, signature: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+}
+export declare function classify(action: string | ProposedAction, options?: RequestOptions & OvruleClientOptions): Promise<CaseFileReceipt>;
+export declare function guard(action: string | ProposedAction, options?: RequestOptions & OvruleClientOptions): Promise<GuardResult>;
+export declare function verify(receipt: CaseFileReceipt, signature: string, options?: {
+    signal?: AbortSignal;
+} & OvruleClientOptions): Promise<boolean>;
+export {};

package/dist/index.js

@@ -0,0 +1,132 @@
+function normalizeAction(action, options) {
+    if (typeof action === "string") {
+        return {
+            scenario: action,
+            policyPack: options?.policyPack,
+        };
+    }
+    return {
+        ...action,
+        policyPack: action.policyPack ?? options?.policyPack,
+    };
+}
+async function readJson(response) {
+    const data = (await response.json());
+    if (!response.ok) {
+        throw new Error(data.error ?? `Ovrule request failed with status ${response.status}.`);
+    }
+    return data;
+}
+export class OvruleClient {
+    baseUrl;
+    fetchImpl;
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl?.replace(/\/$/, "") ?? "";
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error("No fetch implementation available. Pass one in OvruleClient options.");
+        }
+    }
+    async classify(action, options = {}) {
+        const payload = normalizeAction(action, options);
+        const response = await this.fetchImpl(`${this.baseUrl}/api/classify`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+            },
+            body: JSON.stringify({
+                scenario: payload.scenario,
+                policyPack: payload.policyPack,
+            }),
+            signal: options.signal,
+        });
+        if (!response.ok) {
+            const errorBody = await response.json().catch(() => null);
+            const message = errorBody && typeof errorBody === "object" && "error" in errorBody && typeof errorBody.error === "string"
+                ? errorBody.error
+                : `Ovrule classify failed with status ${response.status}.`;
+            throw new Error(message);
+        }
+        const reader = response.body?.getReader();
+        if (!reader) {
+            throw new Error("Ovrule classify did not return a readable response stream.");
+        }
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let finalReceipt = null;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            const blocks = buffer.split("\n\n");
+            buffer = blocks.pop() ?? "";
+            for (const block of blocks) {
+                const lines = block.split("\n");
+                const eventName = lines.find((line) => line.startsWith("event:"))?.slice(6).trim();
+                const data = lines
+                    .filter((line) => line.startsWith("data:"))
+                    .map((line) => line.slice(5).trim())
+                    .join("\n");
+                if (!eventName || !data) {
+                    continue;
+                }
+                const parsed = JSON.parse(data);
+                if (parsed.type === "analysis.completed") {
+                    finalReceipt = parsed.receipt;
+                }
+                if (parsed.type === "session.error") {
+                    throw new Error(parsed.message);
+                }
+            }
+        }
+        if (!finalReceipt) {
+            throw new Error("Ovrule classify stream finished without a final receipt.");
+        }
+        return finalReceipt;
+    }
+    async guard(action, options = {}) {
+        const receipt = await this.classify(action, options);
+        const allowed = receipt.decision === "ADMISSIBLE";
+        const suggestedFixes = receipt.suggestedFixes ?? [];
+        return {
+            allowed,
+            decision: receipt.decision,
+            suggestedFixes,
+            receipt,
+        };
+    }
+    async verify(receipt, signature, options = {}) {
+        const response = await this.fetchImpl(`${this.baseUrl}/api/verify`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ receipt, signature }),
+            signal: options.signal,
+        });
+        const data = await readJson(response);
+        return data.valid;
+    }
+}
+const defaultClient = new OvruleClient();
+export async function classify(action, options) {
+    if (options?.baseUrl || options?.fetch) {
+        return new OvruleClient(options).classify(action, options);
+    }
+    return defaultClient.classify(action, options);
+}
+export async function guard(action, options) {
+    if (options?.baseUrl || options?.fetch) {
+        return new OvruleClient(options).guard(action, options);
+    }
+    return defaultClient.guard(action, options);
+}
+export async function verify(receipt, signature, options) {
+    if (options?.baseUrl || options?.fetch) {
+        return new OvruleClient(options).verify(receipt, signature, options);
+    }
+    return defaultClient.verify(receipt, signature, options);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "ovrule-lab",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Ovrule case-file classification, guardrails, and receipt verification.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "ovrule",
+    "ai-governance",
+    "ai-audit",
+    "agent-safety",
+    "receipt-verification",
+    "typescript-sdk"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  }
+}