@nexart/ai-execution 0.9.0 → 0.10.0

package/README.md

@@ -1,4 +1,4 @@
-# @nexart/ai-execution v0.8.0
+# @nexart/ai-execution v0.10.0
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
@@ -7,7 +7,7 @@ Tamper-evident records and Certified Execution Records (CER) for AI operations.
 | Component | Version |
 |---|---|
 | Service | — |
-| SDK | 0.8.0 |
+| SDK | 0.10.0 |
 | Protocol | 1.2.0 |
 
 ## Why Not Just Store Logs?
@@ -672,6 +672,168 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 | `runAnthropicExecution` | `@nexart/ai-execution/providers/anthropic` |
 | `wrapProvider` | `@nexart/ai-execution/providers/wrap` |
 
+## LangChain Integration
+
+`@nexart/ai-execution` v0.10.0 includes a minimal LangChain helper surface. Certify the final input and output of any LangChain chain, agent, or runnable as a tamper-evident CER — no LangChain package dependency required.
+
+`certifyLangChainRun` operates in two modes depending on whether `nodeUrl` and `apiKey` are supplied:
+
+| Mode | How to call | Returns |
+|---|---|---|
+| **Local** (default) | No `nodeUrl` / `apiKey` | `LangChainCerResult` (sync) |
+| **Node-attested** | `nodeUrl` + `apiKey` on input | `Promise<LangChainAttestedResult>` |
+
+### Mode 1 — Local CER creation (synchronous, no network)
+
+`createLangChainCer` is always local. `certifyLangChainRun` without `nodeUrl`/`apiKey` is identical.
+
+```ts
+import { createLangChainCer, certifyLangChainRun } from '@nexart/ai-execution';
+// or: import { ... } from '@nexart/ai-execution/langchain';
+
+// Using createLangChainCer — always explicit about local-only behaviour
+const { bundle, certificateHash, executionId } = createLangChainCer({
+  executionId: 'run-001',           // optional — UUID generated if omitted
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  input: { messages: [{ role: 'user', content: 'What is the capital of France?' }] },
+  output: { text: 'Paris.' },
+  metadata: { appId: 'my-app', projectId: 'docs-bot' },
+  parameters: { temperature: 0, maxTokens: 200, topP: null, seed: null },
+  createdAt: new Date().toISOString(),  // pin for deterministic hash
+});
+
+console.log(certificateHash); // sha256:...
+
+// certifyLangChainRun without nodeUrl/apiKey: identical, sync
+const { bundle: b2 } = certifyLangChainRun({
+  provider: 'openai', model: 'gpt-4o-mini',
+  input: { messages: [{ role: 'user', content: 'Summarise this.' }] },
+  output: { text: 'Summary...' },
+});
+```
+
+### Mode 2 — Node-attested certification (async)
+
+Add `nodeUrl` and `apiKey` to the same input to route through the existing `certifyAndAttestDecision()` path. The function returns a `Promise<LangChainAttestedResult>` with the `receipt` from the NexArt node.
+
+```ts
+import { certifyLangChainRun } from '@nexart/ai-execution';
+
+const result = await certifyLangChainRun({
+  executionId: 'run-001',
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  input: { messages: [{ role: 'user', content: 'What is the capital of France?' }] },
+  output: { text: 'Paris.' },
+  metadata: { appId: 'my-app', projectId: 'docs-bot' },
+  createdAt: new Date().toISOString(),
+  nodeUrl: 'https://node.nexart.io',   // ← triggers attested mode
+  apiKey: process.env.NEXART_API_KEY!, // ← required with nodeUrl
+});
+
+console.log(result.certificateHash);   // sha256:... (same semantics as local)
+console.log(result.attested);          // true
+console.log(result.receipt);
+// {
+//   attestationId:   "nxa_attest_...",
+//   certificateHash: "sha256:...",
+//   nodeRuntimeHash: "sha256:...",
+//   protocolVersion: "1.2.0"
+// }
+```
+
+`result.bundle` passes `verifyCer()` identically to local mode — the `certificateHash` covers only the CER content, not the receipt fields.
+
+### Three helpers
+
+| Helper | Returns | Network |
+|---|---|---|
+| `createLangChainCer(input)` | `LangChainCerResult` (sync) | Never |
+| `certifyLangChainRun(input)` without `nodeUrl`/`apiKey` | `LangChainCerResult` (sync) | Never |
+| `certifyLangChainRun({ ...input, nodeUrl, apiKey })` | `Promise<LangChainAttestedResult>` | Yes — NexArt node |
+
+### Result types
+
+```ts
+interface LangChainCerResult {
+  bundle:          CerAiExecutionBundle;
+  certificateHash: string;
+  executionId:     string;
+}
+
+interface LangChainAttestedResult extends LangChainCerResult {
+  receipt:  AttestationReceipt;
+  attested: true;
+}
+```
+
+### Input normalization
+
+| Input shape | Stored in CER as |
+|---|---|
+| `string` | `string` (pass-through) |
+| Plain object `{}` | `Record<string, unknown>` (pass-through) |
+| Array `[]` | `{ items: [...] }` |
+| Anything else | `String(value)` |
+
+### Prompt extraction
+
+Resolved in this order: `metadata.prompt` → `input.messages[0].content` → `input.prompt` → `input.text` → `"[LangChain run]"`.
+
+### Metadata mapping
+
+| Metadata key | Mapped to |
+|---|---|
+| `appId` | `snapshot.appId` |
+| `runId` | `snapshot.runId` |
+| `workflowId` | `snapshot.workflowId` |
+| `conversationId` | `snapshot.conversationId` |
+| `prompt` | Used as the CER `prompt` field |
+| All other keys | `bundle.meta.tags` (as `"key:value"` strings) |
+
+### Verification
+
+Bundles from all three helpers are fully protocol-aligned:
+
+```ts
+import { verifyCer, verifyAiCerBundleDetailed } from '@nexart/ai-execution';
+
+const basic    = verifyCer(bundle);
+// { ok: true, code: 'OK' }
+
+const detailed = verifyAiCerBundleDetailed(bundle);
+// { status: 'VERIFIED', checks: { bundleIntegrity: 'PASS', nodeSignature: 'SKIPPED' }, ... }
+```
+
+### Testing the attested path without a network
+
+Use the injectable `_attestFn` test option (same pattern as `certifyAndAttestRun`'s `attestStep`):
+
+```ts
+import type { AttestDecisionFn } from '@nexart/ai-execution';
+
+const mockAttest: AttestDecisionFn = async (params, _opts) => {
+  const { certifyDecision } = await import('@nexart/ai-execution');
+  const bundle = certifyDecision(params);
+  return { bundle, receipt: { attestationId: 'mock-123', certificateHash: bundle.certificateHash,
+    nodeRuntimeHash: 'sha256:' + 'beef'.repeat(16), protocolVersion: '1.2.0' } };
+};
+
+const result = await certifyLangChainRun(
+  { ...input, nodeUrl: 'https://node.nexart.io', apiKey: 'nxa_test' },
+  { _attestFn: mockAttest },
+);
+```
+
+### V3 roadmap (not yet implemented)
+
+- `BaseCallbackHandler` integration for automatic mid-chain CER capture at `onLLMEnd`
+- LangSmith trace correlation via `metadata.runId` → `snapshot.conversationId`
+- Separate `@nexart/langchain` package once the callback surface is proven in production
+
+---
+
 ## Version History
 
 | Version | Description |
@@ -685,7 +847,9 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 | v0.5.0 | Ed25519 signed receipt verification: `verifyNodeReceiptSignature`, `verifyBundleAttestation`, `fetchNodeKeys`, `selectNodeKey`; new attestation `CerVerifyCode` entries; `SPEC.md`; `NodeKeysDocument`, `SignedAttestationReceipt`, `NodeReceiptVerifyResult` types |
 | v0.6.0 | Frictionless integration: `certifyDecisionFromProviderCall` (OpenAI/Anthropic/Gemini/Mistral/Bedrock drop-in); `sanitizeForStorage` + `sanitizeForStamp` redaction helpers; `createClient(defaults)` factory; regression fixture suite; all backward-compatible, no hash changes |
 | v0.7.0 | AIEF alignment: `verifyAief()` (AIEF §9.1 adapter); `verifyRunSummary()` chain verifier; `makeToolEvent()` + `hashToolOutput()` + `snapshot.toolCalls` (AIEF-06); `BundleDeclaration` block (`stabilitySchemeId`, `protectedSetId`, `protectedFields`) excluded from `certificateHash`; `redactBeforeSeal()` pre-seal verifiable redaction; `validateProfile()` (flexible/AIEF_L2/L3/L4); 5 new `CerVerifyCode` entries; backward-compatible, no hash changes |
-| **v0.8.0** | Helper APIs: `exportVerifiableRedacted()` (post-seal re-seal with redacted snapshot + provenance metadata); `certifyAndAttestRun()` (one-call multi-step certify + optional per-step attestation with injectable mock); test determinism fix (no time-dependent first-run failures); all v0.1–v0.7 bundles verify identically, no hashing or canonicalization changes |
+| v0.8.0 | Helper APIs: `exportVerifiableRedacted()` (post-seal re-seal with redacted snapshot + provenance metadata); `certifyAndAttestRun()` (one-call multi-step certify + optional per-step attestation with injectable mock); test determinism fix; all v0.1–v0.7 bundles verify identically |
+| v0.9.0 | CER Protocol types: `CerVerificationResult`, `ReasonCode`, `CheckStatus`; `verifyAiCerBundleDetailed()`; `CertifyDecisionParams.createdAt` wired through; determinism bug fix |
+| **v0.10.0** | LangChain integration: `createLangChainCer()` (sync/local); `certifyLangChainRun()` dual-mode — local (sync) or node-attested (`Promise<LangChainAttestedResult>` when `nodeUrl`+`apiKey` supplied); `LangChainAttestedResult`, `AttestDecisionFn`; injectable `_attestFn` for test mocking; `@nexart/ai-execution/langchain` subpath; 47 tests (was 34); all prior bundles verify identically |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing

package/dist/index.cjs

@@ -41,9 +41,11 @@ __export(src_exports, {
   certifyAndAttestRun: () => certifyAndAttestRun,
   certifyDecision: () => certifyDecision,
   certifyDecisionFromProviderCall: () => certifyDecisionFromProviderCall,
+  certifyLangChainRun: () => certifyLangChainRun,
   computeInputHash: () => computeInputHash,
   computeOutputHash: () => computeOutputHash,
   createClient: () => createClient,
+  createLangChainCer: () => createLangChainCer,
   createSnapshot: () => createSnapshot,
   exportCer: () => exportCer,
   exportVerifiableRedacted: () => exportVerifiableRedacted,
@@ -2622,6 +2624,99 @@ function verifyAiCerBundleDetailed(bundle) {
     verifier
   };
 }
+
+// src/langchain.ts
+var crypto6 = __toESM(require("crypto"), 1);
+function normalizeCerValue(value) {
+  if (typeof value === "string") return value;
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  if (Array.isArray(value)) return { items: value };
+  return String(value);
+}
+function extractPrompt(input, metadata) {
+  if (typeof metadata?.prompt === "string" && metadata.prompt.length > 0) {
+    return metadata.prompt;
+  }
+  if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+    const obj = input;
+    if (Array.isArray(obj.messages) && obj.messages.length > 0) {
+      const first = obj.messages[0];
+      if (typeof first?.content === "string" && first.content.length > 0) {
+        return first.content;
+      }
+    }
+    if (typeof obj.prompt === "string" && obj.prompt.length > 0) return obj.prompt;
+    if (typeof obj.text === "string" && obj.text.length > 0) return obj.text;
+  }
+  if (typeof input === "string" && input.length > 0) return input;
+  return "[LangChain run]";
+}
+function buildMeta(metadata) {
+  if (!metadata || Object.keys(metadata).length === 0) return void 0;
+  const reserved = /* @__PURE__ */ new Set(["prompt", "appId", "runId", "workflowId", "conversationId"]);
+  const extraTags = [];
+  for (const [k, v] of Object.entries(metadata)) {
+    if (!reserved.has(k)) {
+      extraTags.push(typeof v === "string" ? `${k}:${v}` : `${k}:${JSON.stringify(v)}`);
+    }
+  }
+  return extraTags.length > 0 ? { tags: extraTags } : void 0;
+}
+function resolveParameters(params) {
+  return {
+    temperature: params?.temperature ?? 0,
+    maxTokens: params?.maxTokens ?? 0,
+    topP: params?.topP ?? null,
+    seed: params?.seed ?? null
+  };
+}
+function buildCertifyParams(input, executionId) {
+  return {
+    executionId,
+    timestamp: input.timestamp,
+    createdAt: input.createdAt,
+    provider: input.provider,
+    model: input.model,
+    modelVersion: input.modelVersion ?? null,
+    prompt: extractPrompt(input.input, input.metadata),
+    input: normalizeCerValue(input.input),
+    output: normalizeCerValue(input.output),
+    parameters: resolveParameters(input.parameters),
+    appId: typeof input.metadata?.appId === "string" ? input.metadata.appId : null,
+    runId: typeof input.metadata?.runId === "string" ? input.metadata.runId : void 0,
+    workflowId: typeof input.metadata?.workflowId === "string" ? input.metadata.workflowId : void 0,
+    conversationId: typeof input.metadata?.conversationId === "string" ? input.metadata.conversationId : void 0,
+    meta: buildMeta(input.metadata)
+  };
+}
+function createLangChainCer(input) {
+  const executionId = input.executionId ?? crypto6.randomUUID();
+  const bundle = certifyDecision(buildCertifyParams(input, executionId));
+  return {
+    bundle,
+    certificateHash: bundle.certificateHash,
+    executionId: bundle.snapshot.executionId
+  };
+}
+function certifyLangChainRun(input, _options) {
+  if (input.nodeUrl && input.apiKey) {
+    const executionId = input.executionId ?? crypto6.randomUUID();
+    const certifyParams = buildCertifyParams({ ...input, executionId }, executionId);
+    const attestFn = _options?._attestFn ?? certifyAndAttestDecision;
+    return attestFn(certifyParams, { nodeUrl: input.nodeUrl, apiKey: input.apiKey }).then(
+      ({ bundle, receipt }) => ({
+        bundle,
+        receipt,
+        certificateHash: bundle.certificateHash,
+        executionId: bundle.snapshot.executionId,
+        attested: true
+      })
+    );
+  }
+  return createLangChainCer(input);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CerAttestationError,
@@ -2635,9 +2730,11 @@ function verifyAiCerBundleDetailed(bundle) {
   certifyAndAttestRun,
   certifyDecision,
   certifyDecisionFromProviderCall,
+  certifyLangChainRun,
   computeInputHash,
   computeOutputHash,
   createClient,
+  createLangChainCer,
   createSnapshot,
   exportCer,
   exportVerifiableRedacted,