@nexart/ai-execution 0.9.0 → 0.10.0

package/dist/langchain.d.cts

@@ -0,0 +1,185 @@
+import { c as CertifyDecisionParams, e as AttestOptions, b as CerAiExecutionBundle, h as AttestationReceipt } from './types-C5t12OK8.cjs';
+
+/**
+ * @nexart/ai-execution — LangChain Integration
+ *
+ * Provides a minimal helper surface for certifying the final input and
+ * final output of a LangChain run as a Certified Execution Record (CER).
+ *
+ * Two helpers:
+ *
+ *   createLangChainCer(input)
+ *     Always synchronous. Local CER creation only — no network required.
+ *     Returns LangChainCerResult.
+ *
+ *   certifyLangChainRun(input)
+ *     • Without nodeUrl/apiKey → identical to createLangChainCer (sync).
+ *     • With nodeUrl + apiKey  → sends the sealed bundle to a NexArt node
+ *       for attestation via the existing certifyAndAttestDecision() path.
+ *       Returns Promise<LangChainAttestedResult>.
+ *
+ * Both helpers produce bundles that are fully protocol-aligned and pass
+ * verifyCer() / verifyAiCerBundleDetailed(). No LangChain-specific schema.
+ */
+
+/**
+ * Injectable attestation function type.
+ * Defaults to the real certifyAndAttestDecision(); override in tests to avoid
+ * hitting the network. Follows the same injectable pattern as
+ * certifyAndAttestRun()'s attestStep option.
+ *
+ * @internal
+ */
+type AttestDecisionFn = (params: CertifyDecisionParams, options: AttestOptions) => Promise<{
+    bundle: CerAiExecutionBundle;
+    receipt: AttestationReceipt;
+}>;
+/**
+ * Normalized input for LangChain CER helpers.
+ *
+ * Accepts the practical final-run shape produced by LangChain chains,
+ * agents, and runnables without requiring any LangChain import.
+ */
+interface LangChainCertificationInput {
+    /** Optional run ID — a UUID is generated if omitted. */
+    executionId?: string;
+    /** AI provider name (e.g. "openai", "anthropic", "google"). */
+    provider: string;
+    /** Model name (e.g. "gpt-4o-mini", "claude-3-haiku-20240307"). */
+    model: string;
+    /** Model version string — null if unknown. */
+    modelVersion?: string | null;
+    /**
+     * Final run input. Accepts any shape produced by LangChain:
+     * { messages: [...] }, a plain string, HumanMessage array, etc.
+     * Arrays are wrapped as { items: [...] }.
+     */
+    input: unknown;
+    /**
+     * Final run output. Accepts any shape produced by LangChain:
+     * AIMessage, { text: "..." }, a plain string, etc.
+     * Arrays are wrapped as { items: [...] }.
+     */
+    output: unknown;
+    /**
+     * Optional metadata from the LangChain run. Recognized keys:
+     *   - prompt?:         string  — used as the CER prompt field
+     *   - appId?:          string  — included in the CER snapshot
+     *   - runId?:          string
+     *   - workflowId?:     string
+     *   - conversationId?: string
+     * All other keys are preserved in the CER bundle's meta.tags.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Optional override for the AI inference timestamp.
+     * Defaults to current time if omitted.
+     */
+    timestamp?: string;
+    /**
+     * Optional override for the CER bundle creation timestamp.
+     * Pin this to a fixed value to get a deterministic certificateHash.
+     * Defaults to current time if omitted.
+     */
+    createdAt?: string;
+    /**
+     * Optional model inference parameters.
+     * Fields not provided default to 0 / null (protocol-safe).
+     * These values are included in the certificateHash.
+     */
+    parameters?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number | null;
+        seed?: number | null;
+    };
+    /**
+     * NexArt node URL for attestation (e.g. "https://node.nexart.io").
+     * When set together with apiKey, certifyLangChainRun() will call the
+     * node to produce an AttestationReceipt alongside the local CER.
+     * Has no effect on createLangChainCer().
+     */
+    nodeUrl?: string;
+    /**
+     * NexArt API key for node attestation.
+     * Required when nodeUrl is set.
+     */
+    apiKey?: string;
+}
+/** Result returned by createLangChainCer() and certifyLangChainRun() in local mode. */
+interface LangChainCerResult {
+    /** The sealed CER bundle. Pass to verifyCer() to verify integrity. */
+    bundle: CerAiExecutionBundle;
+    /** SHA-256 certificate hash — the tamper-evident fingerprint of this record. */
+    certificateHash: string;
+    /** The executionId embedded in the CER snapshot. */
+    executionId: string;
+}
+/**
+ * Result returned by certifyLangChainRun() when nodeUrl + apiKey are provided.
+ * Extends LangChainCerResult with the receipt from the attestation node.
+ */
+interface LangChainAttestedResult extends LangChainCerResult {
+    /** The attestation receipt from the NexArt node. */
+    receipt: AttestationReceipt;
+    /** Always true — distinguishes an attested result from a local result. */
+    attested: true;
+}
+/**
+ * Create a CER bundle locally from a LangChain final run.
+ *
+ * Always synchronous — no network required. The resulting bundle is fully
+ * aligned with the CER Protocol and verifies via verifyCer() /
+ * verifyAiCerBundleDetailed().
+ *
+ * @example
+ * ```ts
+ * const { bundle, certificateHash } = createLangChainCer({
+ *   provider: 'openai',
+ *   model: 'gpt-4o-mini',
+ *   input: { messages: [{ role: 'user', content: 'What is 2+2?' }] },
+ *   output: { text: '4' },
+ *   createdAt: new Date().toISOString(),
+ * });
+ * ```
+ */
+declare function createLangChainCer(input: LangChainCertificationInput): LangChainCerResult;
+/**
+ * Attested mode: call the NexArt node to produce an AttestationReceipt
+ * alongside the local CER. Requires nodeUrl + apiKey on the input.
+ *
+ * @example
+ * ```ts
+ * const { bundle, certificateHash, receipt } = await certifyLangChainRun({
+ *   provider: 'openai',
+ *   model: 'gpt-4o-mini',
+ *   input: { messages: [...] },
+ *   output: { text: '...' },
+ *   nodeUrl: 'https://node.nexart.io',
+ *   apiKey: 'nxa_...',
+ * });
+ * ```
+ */
+declare function certifyLangChainRun(input: LangChainCertificationInput & {
+    nodeUrl: string;
+    apiKey: string;
+}, _options?: {
+    _attestFn?: AttestDecisionFn;
+}): Promise<LangChainAttestedResult>;
+/**
+ * Local mode: identical to createLangChainCer() — synchronous, no network.
+ *
+ * @example
+ * ```ts
+ * const { bundle, certificateHash } = certifyLangChainRun({
+ *   provider: 'openai',
+ *   model: 'gpt-4o-mini',
+ *   input: { messages: [...] },
+ *   output: { text: '...' },
+ *   createdAt: new Date().toISOString(),
+ * });
+ * ```
+ */
+declare function certifyLangChainRun(input: LangChainCertificationInput): LangChainCerResult;
+
+export { type AttestDecisionFn, type LangChainAttestedResult, type LangChainCerResult, type LangChainCertificationInput, certifyLangChainRun, createLangChainCer };

package/dist/langchain.d.ts

@@ -0,0 +1,185 @@
+import { c as CertifyDecisionParams, e as AttestOptions, b as CerAiExecutionBundle, h as AttestationReceipt } from './types-C5t12OK8.js';
+
+/**
+ * @nexart/ai-execution — LangChain Integration
+ *
+ * Provides a minimal helper surface for certifying the final input and
+ * final output of a LangChain run as a Certified Execution Record (CER).
+ *
+ * Two helpers:
+ *
+ *   createLangChainCer(input)
+ *     Always synchronous. Local CER creation only — no network required.
+ *     Returns LangChainCerResult.
+ *
+ *   certifyLangChainRun(input)
+ *     • Without nodeUrl/apiKey → identical to createLangChainCer (sync).
+ *     • With nodeUrl + apiKey  → sends the sealed bundle to a NexArt node
+ *       for attestation via the existing certifyAndAttestDecision() path.
+ *       Returns Promise<LangChainAttestedResult>.
+ *
+ * Both helpers produce bundles that are fully protocol-aligned and pass
+ * verifyCer() / verifyAiCerBundleDetailed(). No LangChain-specific schema.
+ */
+
+/**
+ * Injectable attestation function type.
+ * Defaults to the real certifyAndAttestDecision(); override in tests to avoid
+ * hitting the network. Follows the same injectable pattern as
+ * certifyAndAttestRun()'s attestStep option.
+ *
+ * @internal
+ */
+type AttestDecisionFn = (params: CertifyDecisionParams, options: AttestOptions) => Promise<{
+    bundle: CerAiExecutionBundle;
+    receipt: AttestationReceipt;
+}>;
+/**
+ * Normalized input for LangChain CER helpers.
+ *
+ * Accepts the practical final-run shape produced by LangChain chains,
+ * agents, and runnables without requiring any LangChain import.
+ */
+interface LangChainCertificationInput {
+    /** Optional run ID — a UUID is generated if omitted. */
+    executionId?: string;
+    /** AI provider name (e.g. "openai", "anthropic", "google"). */
+    provider: string;
+    /** Model name (e.g. "gpt-4o-mini", "claude-3-haiku-20240307"). */
+    model: string;
+    /** Model version string — null if unknown. */
+    modelVersion?: string | null;
+    /**
+     * Final run input. Accepts any shape produced by LangChain:
+     * { messages: [...] }, a plain string, HumanMessage array, etc.
+     * Arrays are wrapped as { items: [...] }.
+     */
+    input: unknown;
+    /**
+     * Final run output. Accepts any shape produced by LangChain:
+     * AIMessage, { text: "..." }, a plain string, etc.
+     * Arrays are wrapped as { items: [...] }.
+     */
+    output: unknown;
+    /**
+     * Optional metadata from the LangChain run. Recognized keys:
+     *   - prompt?:         string  — used as the CER prompt field
+     *   - appId?:          string  — included in the CER snapshot
+     *   - runId?:          string
+     *   - workflowId?:     string
+     *   - conversationId?: string
+     * All other keys are preserved in the CER bundle's meta.tags.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Optional override for the AI inference timestamp.
+     * Defaults to current time if omitted.
+     */
+    timestamp?: string;
+    /**
+     * Optional override for the CER bundle creation timestamp.
+     * Pin this to a fixed value to get a deterministic certificateHash.
+     * Defaults to current time if omitted.
+     */
+    createdAt?: string;
+    /**
+     * Optional model inference parameters.
+     * Fields not provided default to 0 / null (protocol-safe).
+     * These values are included in the certificateHash.
+     */
+    parameters?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number | null;
+        seed?: number | null;
+    };
+    /**
+     * NexArt node URL for attestation (e.g. "https://node.nexart.io").
+     * When set together with apiKey, certifyLangChainRun() will call the
+     * node to produce an AttestationReceipt alongside the local CER.
+     * Has no effect on createLangChainCer().
+     */
+    nodeUrl?: string;
+    /**
+     * NexArt API key for node attestation.
+     * Required when nodeUrl is set.
+     */
+    apiKey?: string;
+}
+/** Result returned by createLangChainCer() and certifyLangChainRun() in local mode. */
+interface LangChainCerResult {
+    /** The sealed CER bundle. Pass to verifyCer() to verify integrity. */
+    bundle: CerAiExecutionBundle;
+    /** SHA-256 certificate hash — the tamper-evident fingerprint of this record. */
+    certificateHash: string;
+    /** The executionId embedded in the CER snapshot. */
+    executionId: string;
+}
+/**
+ * Result returned by certifyLangChainRun() when nodeUrl + apiKey are provided.
+ * Extends LangChainCerResult with the receipt from the attestation node.
+ */
+interface LangChainAttestedResult extends LangChainCerResult {
+    /** The attestation receipt from the NexArt node. */
+    receipt: AttestationReceipt;
+    /** Always true — distinguishes an attested result from a local result. */
+    attested: true;
+}
+/**
+ * Create a CER bundle locally from a LangChain final run.
+ *
+ * Always synchronous — no network required. The resulting bundle is fully
+ * aligned with the CER Protocol and verifies via verifyCer() /
+ * verifyAiCerBundleDetailed().
+ *
+ * @example
+ * ```ts
+ * const { bundle, certificateHash } = createLangChainCer({
+ *   provider: 'openai',
+ *   model: 'gpt-4o-mini',
+ *   input: { messages: [{ role: 'user', content: 'What is 2+2?' }] },
+ *   output: { text: '4' },
+ *   createdAt: new Date().toISOString(),
+ * });
+ * ```
+ */
+declare function createLangChainCer(input: LangChainCertificationInput): LangChainCerResult;
+/**
+ * Attested mode: call the NexArt node to produce an AttestationReceipt
+ * alongside the local CER. Requires nodeUrl + apiKey on the input.
+ *
+ * @example
+ * ```ts
+ * const { bundle, certificateHash, receipt } = await certifyLangChainRun({
+ *   provider: 'openai',
+ *   model: 'gpt-4o-mini',
+ *   input: { messages: [...] },
+ *   output: { text: '...' },
+ *   nodeUrl: 'https://node.nexart.io',
+ *   apiKey: 'nxa_...',
+ * });
+ * ```
+ */
+declare function certifyLangChainRun(input: LangChainCertificationInput & {
+    nodeUrl: string;
+    apiKey: string;
+}, _options?: {
+    _attestFn?: AttestDecisionFn;
+}): Promise<LangChainAttestedResult>;
+/**
+ * Local mode: identical to createLangChainCer() — synchronous, no network.
+ *
+ * @example
+ * ```ts
+ * const { bundle, certificateHash } = certifyLangChainRun({
+ *   provider: 'openai',
+ *   model: 'gpt-4o-mini',
+ *   input: { messages: [...] },
+ *   output: { text: '...' },
+ *   createdAt: new Date().toISOString(),
+ * });
+ * ```
+ */
+declare function certifyLangChainRun(input: LangChainCertificationInput): LangChainCerResult;
+
+export { type AttestDecisionFn, type LangChainAttestedResult, type LangChainCerResult, type LangChainCertificationInput, certifyLangChainRun, createLangChainCer };