@hsuite/smart-engines-sdk 3.11.0 → 3.13.0

package/CHANGELOG.md

@@ -252,7 +252,7 @@ class MyService {
   ValidatorRules` section, two new rows in the "Available clients" table,
   and a pointer to the full developer guide.
 - Complete developer guide added at
-  `docs/developers/libs/rules-engine.md#smart-app-sdk-guide` — covers
+  `docs/internal/developers/libs/rules-engine.md#smart-app-sdk-guide` — covers
   authoring paths, composer reference tables, publish + entity-create
   end-to-end flow, `baas.rules.*` + `baas.entities.*` reference, and 7
   common pitfalls.

package/README.md

@@ -235,7 +235,7 @@ const sim = await baas.rules.simulate({ ruleRef, action: 'mint', context: { amou
 // sim.isValid === true | false (+ reason)
 ```
 
-Full reference: [Smart-App SDK Guide](../../docs/developers/libs/rules-engine.md#smart-app-sdk-guide)
+Full reference: [Smart-App SDK Guide](../../docs/internal/developers/libs/rules-engine.md#smart-app-sdk-guide)
 
 ---
 

package/dist/index.d.ts

@@ -3885,7 +3885,7 @@ export type AgentExecuteRequest = {
 	params: Record<string, unknown>;
 };
 export type AgentExecuteStepResult = {
-	kind: "onchain" | "offchain";
+	kind: "onchain" | "offchain" | "function";
 	status: string;
 	transactionBytes?: string;
 	ref?: string;
@@ -5396,6 +5396,62 @@ declare function xlmToStroops(xlm: string | number): string;
 declare function validateBitcoinAddress(address: string): boolean;
 declare function satoshisToBtc(satoshis: string | number): string;
 declare function btcToSatoshis(btc: string | number): string;
+export type ModelProvider = "anthropic" | "openai" | "gemini";
+export type ChatMessage = {
+	role: "system" | "user" | "assistant";
+	content: string;
+};
+export type InferArgs = {
+	system?: string;
+	messages: ChatMessage[];
+	maxTokens?: number;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+};
+export type InferResult = {
+	ok: boolean;
+	text?: string;
+	error?: string;
+	raw?: unknown;
+};
+export type IModelProvider = {
+	readonly provider: ModelProvider;
+	infer(args: InferArgs): Promise<InferResult>;
+};
+export declare function createAnthropicProvider(opts: {
+	apiKey: string;
+	model: string;
+}): IModelProvider;
+export declare function createOpenAiProvider(opts: {
+	apiKey: string;
+	model: string;
+}): IModelProvider;
+export declare function createGeminiProvider(opts: {
+	apiKey: string;
+	model: string;
+}): IModelProvider;
+export declare function createModelProvider(opts: {
+	provider: ModelProvider;
+	apiKey: string;
+	model: string;
+}): IModelProvider;
+export type InferJsonResult<T> = {
+	ok: boolean;
+	value?: T;
+	error?: string;
+	raw?: string;
+};
+export declare function inferJson<T = unknown>(opts: {
+	provider: ModelProvider;
+	apiKey: string;
+	model: string;
+	system?: string;
+	input: unknown;
+	maxTokens?: number;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	parse?: (raw: unknown) => T;
+}): Promise<InferJsonResult<T>>;
 export type StateRootResponse = {
 	appId: string;
 	stateRoot: string;
@@ -25558,6 +25614,9 @@ declare namespace subscription {
 declare namespace faucet {
 	export { FaucetChallenge, FaucetClient, FaucetDispenseRequest, FaucetDispenseResult, FaucetDispensed, FaucetRateLimited, FaucetStatusResponse, FaucetTrustlineRequired };
 }
+declare namespace ai {
+	export { ChatMessage, IModelProvider, InferArgs, InferJsonResult, InferResult, ModelProvider, createAnthropicProvider, createGeminiProvider, createModelProvider, createOpenAiProvider, inferJson };
+}
 declare namespace bridge {
 	export { BridgeChain, BridgeClaimRecord, BridgeClaimStatus, BridgeClient, BridgeConfig, BridgeDestinationConfig, BridgeDirection, BridgeGenesisBinding, BridgeMode, BridgeOperationConfig, BridgeRulesConfig, BridgeSourceConfig, BridgeStatus, BridgeSupply, BridgeTrustLevel, CreateBridgeRequest, CreateBridgeResponse, ListBridgesOptions, ListBridgesResponse, ListClaimsOptions, ListClaimsResponse, PortRequest, PortResult, ReturnRequest };
 }
@@ -25595,6 +25654,7 @@ declare namespace pqcVerify {
 export {
 	RetryConfig as ResilienceRetryConfig,
 	RetryConfig$1 as RetryConfig,
+	ai,
 	auth,
 	baas,
 	bridge,

package/dist/index.js

@@ -10375,6 +10375,358 @@ function btcToSatoshis(btc) {
   return (amount * 1e8).toFixed(0);
 }
 
+// src/ai/index.ts
+var ai_exports = {};
+__export(ai_exports, {
+  createAnthropicProvider: () => createAnthropicProvider,
+  createGeminiProvider: () => createGeminiProvider,
+  createModelProvider: () => createModelProvider,
+  createOpenAiProvider: () => createOpenAiProvider,
+  inferJson: () => inferJson
+});
+
+// src/ai/types.ts
+var DEFAULT_INFER_TIMEOUT_MS = 3e4;
+
+// src/ai/http.ts
+var InferTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`request timed out after ${timeoutMs}ms`);
+    this.name = "InferTimeoutError";
+  }
+};
+function isAbortError(err) {
+  if (err instanceof InferTimeoutError) {
+    return true;
+  }
+  return typeof err === "object" && err !== null && err.name === "AbortError";
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function fetchWithTimeout(url, init, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_INFER_TIMEOUT_MS;
+  const callerSignal = opts.signal;
+  const controller = new AbortController();
+  let timedOut = false;
+  let timer;
+  if (timeoutMs > 0) {
+    timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    if (typeof timer === "object" && typeof timer.unref === "function") {
+      timer.unref();
+    }
+  }
+  const onCallerAbort = () => controller.abort();
+  if (callerSignal) {
+    if (callerSignal.aborted) {
+      controller.abort();
+    } else {
+      callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+    }
+  }
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (timedOut) {
+      throw new InferTimeoutError(timeoutMs);
+    }
+    throw err;
+  } finally {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+    if (callerSignal) {
+      callerSignal.removeEventListener("abort", onCallerAbort);
+    }
+  }
+}
+
+// src/ai/anthropic.ts
+var ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
+var ANTHROPIC_VERSION = "2023-06-01";
+var DEFAULT_MAX_TOKENS = 1024;
+function createAnthropicProvider(opts) {
+  const { apiKey, model } = opts;
+  return {
+    provider: "anthropic",
+    async infer(args) {
+      const messages = args.messages.filter((m) => m.role === "user" || m.role === "assistant").map((m) => ({ role: m.role, content: m.content }));
+      const body = {
+        model,
+        max_tokens: args.maxTokens ?? DEFAULT_MAX_TOKENS,
+        messages
+      };
+      if (args.system) {
+        body.system = args.system;
+      }
+      let res;
+      try {
+        res = await fetchWithTimeout(
+          ANTHROPIC_URL,
+          {
+            method: "POST",
+            headers: {
+              "x-api-key": apiKey,
+              "anthropic-version": ANTHROPIC_VERSION,
+              "content-type": "application/json"
+            },
+            body: JSON.stringify(body)
+          },
+          { timeoutMs: args.timeoutMs, signal: args.signal }
+        );
+      } catch (err) {
+        if (isAbortError(err)) {
+          return { ok: false, error: errMsg(err) };
+        }
+        throw err;
+      }
+      if (!res.ok) {
+        throw new Error(`Anthropic request failed with status ${res.status}`);
+      }
+      const data = await res.json();
+      const text = Array.isArray(data.content) ? data.content.find((b) => typeof b.text === "string")?.text : void 0;
+      if (typeof text !== "string") {
+        return { ok: false, error: "Anthropic response contained no text block", raw: data };
+      }
+      return { ok: true, text, raw: data };
+    }
+  };
+}
+
+// src/ai/openai.ts
+var OPENAI_URL = "https://api.openai.com/v1/chat/completions";
+var DEFAULT_MAX_TOKENS2 = 1024;
+function createOpenAiProvider(opts) {
+  const { apiKey, model } = opts;
+  return {
+    provider: "openai",
+    async infer(args) {
+      const messages = [];
+      if (args.system) {
+        messages.push({ role: "system", content: args.system });
+      }
+      for (const m of args.messages) {
+        messages.push({ role: m.role, content: m.content });
+      }
+      let res;
+      try {
+        res = await fetchWithTimeout(
+          OPENAI_URL,
+          {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${apiKey}`,
+              "content-type": "application/json"
+            },
+            body: JSON.stringify({
+              model,
+              max_tokens: args.maxTokens ?? DEFAULT_MAX_TOKENS2,
+              messages
+            })
+          },
+          { timeoutMs: args.timeoutMs, signal: args.signal }
+        );
+      } catch (err) {
+        if (isAbortError(err)) {
+          return { ok: false, error: errMsg(err) };
+        }
+        throw err;
+      }
+      if (!res.ok) {
+        throw new Error(`OpenAI request failed with status ${res.status}`);
+      }
+      const data = await res.json();
+      const text = data.choices?.[0]?.message?.content;
+      if (typeof text !== "string") {
+        return { ok: false, error: "OpenAI response contained no message content", raw: data };
+      }
+      return { ok: true, text, raw: data };
+    }
+  };
+}
+
+// src/ai/gemini.ts
+var GEMINI_BASE = "https://generativelanguage.googleapis.com/v1beta/models";
+var DEFAULT_MAX_TOKENS3 = 1024;
+function createGeminiProvider(opts) {
+  const { apiKey, model } = opts;
+  return {
+    provider: "gemini",
+    async infer(args) {
+      const contents = args.messages.filter((m) => m.role === "user" || m.role === "assistant").map((m) => ({
+        role: m.role === "assistant" ? "model" : "user",
+        parts: [{ text: m.content }]
+      }));
+      const body = {
+        contents,
+        generationConfig: { maxOutputTokens: args.maxTokens ?? DEFAULT_MAX_TOKENS3 }
+      };
+      if (args.system) {
+        body.systemInstruction = { parts: [{ text: args.system }] };
+      }
+      const url = `${GEMINI_BASE}/${model}:generateContent`;
+      let res;
+      try {
+        res = await fetchWithTimeout(
+          url,
+          {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              "x-goog-api-key": apiKey
+            },
+            body: JSON.stringify(body)
+          },
+          { timeoutMs: args.timeoutMs, signal: args.signal }
+        );
+      } catch (err) {
+        if (isAbortError(err)) {
+          return { ok: false, error: errMsg(err) };
+        }
+        throw err;
+      }
+      if (!res.ok) {
+        throw new Error(`Gemini request failed with status ${res.status}`);
+      }
+      const data = await res.json();
+      const text = data.candidates?.[0]?.content?.parts?.[0]?.text;
+      if (typeof text !== "string") {
+        return { ok: false, error: "Gemini response contained no text part", raw: data };
+      }
+      return { ok: true, text, raw: data };
+    }
+  };
+}
+
+// src/ai/factory.ts
+function createModelProvider(opts) {
+  const { provider, apiKey, model } = opts;
+  switch (provider) {
+    case "anthropic":
+      return createAnthropicProvider({ apiKey, model });
+    case "openai":
+      return createOpenAiProvider({ apiKey, model });
+    case "gemini":
+      return createGeminiProvider({ apiKey, model });
+    default: {
+      const never = provider;
+      throw new Error(`Unsupported model provider: ${String(never)}`);
+    }
+  }
+}
+
+// src/ai/infer-json.ts
+var JSON_ONLY_INSTRUCTION = "Respond with ONLY a single JSON object, no prose.";
+var RETRY_INSTRUCTION = "Return valid JSON only.";
+function nextBalancedObject(raw, from) {
+  const start = raw.indexOf("{", from);
+  if (start === -1) {
+    return null;
+  }
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < raw.length; i++) {
+    const ch = raw[i];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+    } else if (ch === "{") {
+      depth++;
+    } else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        return [start, i];
+      }
+    }
+  }
+  return null;
+}
+function extractJson(raw) {
+  let from = 0;
+  let sawCandidate = false;
+  for (; ; ) {
+    const span = nextBalancedObject(raw, from);
+    if (!span) {
+      break;
+    }
+    sawCandidate = true;
+    const slice = raw.slice(span[0], span[1] + 1);
+    try {
+      return JSON.parse(slice);
+    } catch {
+      from = span[0] + 1;
+    }
+  }
+  throw new Error(
+    sawCandidate ? "no valid JSON object found in reply" : "no JSON object found in reply"
+  );
+}
+async function inferJson(opts) {
+  const { provider, apiKey, model, system, input, maxTokens, timeoutMs, signal, parse } = opts;
+  let client;
+  try {
+    client = createModelProvider({ provider, apiKey, model });
+  } catch (err) {
+    return { ok: false, error: errMsg(err) };
+  }
+  const systemPrompt = system ? `${system}
+
+${JSON_ONLY_INSTRUCTION}` : JSON_ONLY_INSTRUCTION;
+  const userContent = typeof input === "string" ? input : JSON.stringify(input);
+  const messages = [{ role: "user", content: userContent }];
+  const first = await runOnce(
+    client,
+    { system: systemPrompt, messages, maxTokens, timeoutMs, signal },
+    parse
+  );
+  if (first.ok) {
+    return first;
+  }
+  const retryMessages = [...messages];
+  if (typeof first.raw === "string") {
+    retryMessages.push({ role: "assistant", content: first.raw });
+  }
+  retryMessages.push({ role: "user", content: RETRY_INSTRUCTION });
+  const second = await runOnce(
+    client,
+    { system: systemPrompt, messages: retryMessages, maxTokens, timeoutMs, signal },
+    parse
+  );
+  return second;
+}
+async function runOnce(client, args, parse) {
+  let inferred;
+  try {
+    inferred = await client.infer(args);
+  } catch (err) {
+    return { ok: false, error: errMsg(err) };
+  }
+  if (!inferred.ok || typeof inferred.text !== "string") {
+    return { ok: false, error: inferred.error ?? "provider returned no text", raw: inferred.text };
+  }
+  const raw = inferred.text;
+  try {
+    const parsed = extractJson(raw);
+    const value = parse ? parse(parsed) : parsed;
+    return { ok: true, value, raw };
+  } catch (err) {
+    return { ok: false, error: errMsg(err), raw };
+  }
+}
+
 // src/baas/index.ts
 var baas_exports = {};
 __export(baas_exports, {
@@ -13501,6 +13853,7 @@ exports.ValidatorDiscoveryClient = ValidatorDiscoveryClient;
 exports.ValidatorMetadataSchema = ValidatorMetadataSchema;
 exports.ValidatorRulesSchema = ValidatorRulesSchema;
 exports.XrplTransactionsClient = XrplTransactionsClient;
+exports.ai = ai_exports;
 exports.appTopic = appTopic;
 exports.atom = atom;
 exports.auth = auth_exports;
@@ -13509,7 +13862,11 @@ exports.bridge = bridge_exports;
 exports.canonicalizeAttestation = canonicalizeAttestation;
 exports.chains = chains_exports;
 exports.computeAttestationHash = computeAttestationHash;
+exports.createAnthropicProvider = createAnthropicProvider;
+exports.createGeminiProvider = createGeminiProvider;
 exports.createHttpClient = createHttpClient;
+exports.createModelProvider = createModelProvider;
+exports.createOpenAiProvider = createOpenAiProvider;
 exports.createResilientFetchWithBreaker = createResilientFetchWithBreaker;
 exports.createXrplWeb3Signer = createXrplWeb3Signer;
 exports.dao = dao_exports;
@@ -13525,6 +13882,7 @@ exports.forAgent = forAgent;
 exports.forToken = forToken;
 exports.forTopic = forTopic;
 exports.governance = governance_exports;
+exports.inferJson = inferJson;
 exports.isKnownNetwork = isKnownNetwork;
 exports.isPersonhoodVerifierNotConfigured = isPersonhoodVerifierNotConfigured;
 exports.isRuleRejected = isRuleRejected;