@thyn-ai/sqai-ai-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,794 @@
+// src/toolkit.ts
+import { SQAI, SqaiError as SqaiError2 } from "@thyn-ai/sqai";
+
+// src/tools.ts
+import { tool } from "ai";
+import {
+  ContractIndex,
+  SqaiError,
+  currentPlatformKey,
+  invocationHash,
+  isReadOnlyEligible,
+  lookupCapability
+} from "@thyn-ai/sqai";
+
+// src/schemas.ts
+import { z } from "zod";
+var filterConditionSchema = z.object({
+  column: z.string().optional().describe("Exact column name to filter on."),
+  op: z.enum(["eq", "in", "gt", "gte", "lt", "lte", "is_null", "is_not_null"]),
+  value: z.union([z.string(), z.number(), z.boolean()]).optional(),
+  values: z.array(z.union([z.string(), z.number(), z.boolean()])).optional().describe("Values for the 'in' operator.")
+});
+var filterSpecSchema = z.object({
+  time_filter: z.string().optional().describe("Named time window, e.g. 'last_30_days'."),
+  conditions: z.array(filterConditionSchema).optional()
+});
+var querySpecSchema = z.object({
+  metric: z.string().describe("The measure to compute, e.g. 'revenue'. Use exact field names from listSources."),
+  aggregation: z.enum(["sum", "avg", "count", "min", "max"]).optional(),
+  group_by: z.string().optional().describe("Column to group results by."),
+  filter: filterSpecSchema.optional(),
+  limit: z.number().int().positive().optional().describe("Maximum rows to return."),
+  order: z.enum(["asc", "desc"]).optional(),
+  source: z.string().optional().describe("Source name to query (maps to source_name). Omit to let the planner pick.")
+});
+var taggedScalarSchema = z.object({
+  type: z.enum(["decimal", "bigint"]),
+  value: z.string()
+});
+var algentaWireValueSchema = z.lazy(
+  () => z.union([
+    z.null(),
+    z.boolean(),
+    z.number(),
+    z.string(),
+    z.array(algentaWireValueSchema),
+    taggedScalarSchema,
+    z.record(z.string(), algentaWireValueSchema)
+  ])
+);
+var singleBindingSchema = z.object({
+  parameter: z.union([z.string(), z.number()]).describe("Target parameter, by name or positional index."),
+  source: z.string().describe("Connected source name to pull the column from."),
+  field: z.string().describe("Column to extract."),
+  filter: filterSpecSchema.optional()
+});
+var alignedBindingSchema = z.object({
+  parameters: z.array(z.union([z.string(), z.number()])).describe("Target parameters, one per field, row-aligned."),
+  source: z.string(),
+  fields: z.array(z.string()).describe("Columns to extract, one per parameter."),
+  filter: filterSpecSchema.optional(),
+  alignment: z.literal("rowwise"),
+  nullPolicy: z.enum(["pairwise", "preserve"]).optional()
+});
+var computationBindingSchema = z.union([singleBindingSchema, alignedBindingSchema]);
+var computationSpecSchema = z.object({
+  module: z.string().describe("Capability module, e.g. 'stats'. Discover via listSources."),
+  function: z.string().describe("Function inside the module, e.g. 'median'."),
+  args: z.array(algentaWireValueSchema).default([]).describe("Positional arguments."),
+  kwargs: z.record(z.string(), algentaWireValueSchema).optional().describe("Named arguments."),
+  bindings: z.array(computationBindingSchema).optional().describe("Pull columns from connected sources instead of pasting data inline."),
+  seed: z.union([z.number(), z.string()]).optional().describe("Required for simulation modules; makes runs replayable")
+});
+var queryDataInputSchema = z.discriminatedUnion("kind", [
+  z.object({
+    version: z.literal("1"),
+    kind: z.literal("query"),
+    spec: querySpecSchema
+  }),
+  z.object({
+    version: z.literal("1"),
+    kind: z.literal("computation"),
+    spec: computationSpecSchema
+  })
+]);
+var explainQueryInputSchema = queryDataInputSchema;
+var listSourcesInputSchema = z.object({
+  capabilitySearch: z.string().optional().describe("Search the computation capability catalog; returns matching modules."),
+  module: z.string().optional().describe("List a module's functions with exact signatures.")
+});
+var cellSchema = z.union([z.number(), z.string(), z.boolean(), z.null()]);
+var candidateSchema = z.looseObject({
+  source: z.string().optional(),
+  column: z.string().optional(),
+  role: z.string().optional(),
+  confidence: z.number().optional()
+});
+var errorOutputSchema = z.object({
+  status: z.literal("error"),
+  code: z.string(),
+  message: z.string(),
+  retryable: z.boolean(),
+  request_id: z.string().nullable(),
+  nearest_matches: z.array(z.string()).optional()
+});
+var clarificationOutputSchema = z.object({
+  status: z.literal("needs_clarification"),
+  question: z.string(),
+  candidates: z.array(candidateSchema),
+  explanation: z.array(z.string())
+});
+var rejectedOutputSchema = z.object({
+  status: z.literal("rejected"),
+  rejection_reason: z.string(),
+  candidates: z.array(candidateSchema),
+  explanation: z.array(z.string())
+});
+var queryOkOutputSchema = z.object({
+  status: z.literal("ok"),
+  kind: z.literal("query"),
+  data: z.object({
+    columns: z.array(z.string()),
+    rows: z.array(z.array(cellSchema))
+  }),
+  total_rows: z.number(),
+  returned_rows: z.number(),
+  truncated: z.boolean(),
+  result_id: z.string().optional(),
+  plan_hash: z.string().nullable(),
+  schema_revision: z.string().nullable(),
+  source_name: z.string().nullable(),
+  intent_signature: z.string().nullable(),
+  deterministic_scope: z.string().nullable(),
+  decision_path: z.string().nullable(),
+  validated: z.boolean().nullable(),
+  request_id: z.string().nullable(),
+  explanation: z.array(z.string())
+});
+var determinismEnvelopeSchema = z.object({
+  runtime_bundle_version: z.string(),
+  runtime_bundle_sha256: z.string(),
+  platform: z.string(),
+  architecture: z.string(),
+  kernel_build: z.string(),
+  precision_mode: z.string(),
+  thread_count: z.number(),
+  seed: z.union([z.number(), z.string()]).optional(),
+  input_hash: z.string()
+});
+var bindingProvenanceSchema = z.object({
+  source_name: z.string(),
+  fields: z.array(z.string()),
+  schema_revision: z.string().nullable(),
+  row_count: z.number(),
+  input_hash: z.string()
+});
+var computationOkOutputSchema = z.object({
+  status: z.literal("ok"),
+  kind: z.literal("computation"),
+  value: algentaWireValueSchema,
+  value_type: z.string(),
+  preview: algentaWireValueSchema.optional(),
+  element_count: z.number().optional(),
+  truncated: z.boolean(),
+  result_id: z.string().optional(),
+  invocation_hash: z.string(),
+  computation_hash: z.string(),
+  contract_hash: z.string(),
+  determinism: determinismEnvelopeSchema,
+  provenance: z.object({ bindings: z.array(bindingProvenanceSchema) }).optional(),
+  latency_ms: z.number(),
+  request_id: z.string()
+});
+var queryDataOutputSchema = z.union([
+  queryOkOutputSchema,
+  computationOkOutputSchema,
+  clarificationOutputSchema,
+  rejectedOutputSchema,
+  errorOutputSchema
+]);
+var sourceListOutputSchema = z.object({
+  sources: z.array(
+    z.object({
+      name: z.string(),
+      fields: z.array(
+        z.object({
+          name: z.string(),
+          type: z.string(),
+          ops: z.array(z.string())
+        })
+      ),
+      row_count: z.number().nullable(),
+      schema_revision: z.string().nullable()
+    })
+  )
+});
+var moduleListOutputSchema = z.object({
+  modules: z.array(
+    z.object({
+      name: z.string(),
+      category: z.string(),
+      deterministic: z.boolean(),
+      function_count: z.number(),
+      sample_functions: z.array(z.string())
+    })
+  )
+});
+var functionListOutputSchema = z.object({
+  functions: z.array(
+    z.object({
+      name: z.string(),
+      signature: z.string(),
+      params: z.array(
+        z.object({
+          name: z.string(),
+          type: z.string(),
+          required: z.boolean()
+        })
+      ),
+      returns: z.string(),
+      deterministic: z.boolean(),
+      seed_required: z.boolean()
+    })
+  )
+});
+var listSourcesOutputSchema = z.union([
+  sourceListOutputSchema,
+  moduleListOutputSchema,
+  functionListOutputSchema,
+  errorOutputSchema
+]);
+var explainQueryOkQueryOutputSchema = z.object({
+  status: z.literal("ok"),
+  kind: z.literal("query"),
+  resolved_plan: z.record(z.string(), z.unknown()),
+  plan: z.array(z.string()),
+  plan_hash: z.string().nullable(),
+  confidence: z.number(),
+  validated: z.boolean()
+});
+var explainQueryOkComputationOutputSchema = z.object({
+  status: z.literal("ok"),
+  kind: z.literal("computation"),
+  matched_signature: z.string(),
+  invocation_hash: z.string(),
+  seed_required: z.boolean()
+});
+var explainQueryOutputSchema = z.union([
+  explainQueryOkQueryOutputSchema,
+  explainQueryOkComputationOutputSchema,
+  clarificationOutputSchema,
+  rejectedOutputSchema,
+  errorOutputSchema
+]);
+
+// src/truncate.ts
+function toCell(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "number" || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+function shapeQueryResult(result, options) {
+  if (!Array.isArray(result)) {
+    return {
+      data: { columns: ["value"], rows: [[toCell(result)]] },
+      total_rows: 1,
+      returned_rows: 1,
+      truncated: false
+    };
+  }
+  const totalRows = result.length;
+  if (totalRows === 0) {
+    return { data: { columns: [], rows: [] }, total_rows: 0, returned_rows: 0, truncated: false };
+  }
+  const first = result[0];
+  let columns;
+  let toRow;
+  if (first !== null && typeof first === "object" && !Array.isArray(first)) {
+    columns = Object.keys(first);
+    toRow = (row) => columns.map((column) => toCell(row[column]));
+  } else {
+    columns = ["value"];
+    toRow = (row) => [toCell(row)];
+  }
+  let keep = Math.min(totalRows, Math.max(0, Math.floor(options.maxRowsToModel)));
+  const cellsPerRow = Math.max(1, columns.length);
+  if (keep * cellsPerRow > options.maxCellsToModel) {
+    keep = Math.max(0, Math.floor(options.maxCellsToModel / cellsPerRow));
+  }
+  return {
+    data: { columns, rows: result.slice(0, keep).map(toRow) },
+    total_rows: totalRows,
+    returned_rows: keep,
+    truncated: keep < totalRows
+  };
+}
+function byteLength(value) {
+  return Buffer.byteLength(JSON.stringify(value ?? null), "utf-8");
+}
+function shapeComputationValue(value, options) {
+  if (value === null || typeof value !== "object") {
+    return { value, truncated: false };
+  }
+  if (Array.isArray(value)) {
+    const elementCount = value.length;
+    let preview = value.slice(0, Math.min(elementCount, Math.max(0, options.maxElementsToModel)));
+    while (preview.length > 0 && byteLength(preview) > options.maxBytesToModel) {
+      preview = preview.slice(0, Math.floor(preview.length / 2));
+    }
+    return {
+      value: null,
+      preview,
+      element_count: elementCount,
+      truncated: preview.length < elementCount
+    };
+  }
+  if (byteLength(value) <= options.maxBytesToModel) {
+    return { value, truncated: false };
+  }
+  return { value: null, truncated: true };
+}
+function storeWithinCap(value, maxOutputBytes, store) {
+  if (byteLength(value) > maxOutputBytes) {
+    return void 0;
+  }
+  return store(value);
+}
+
+// src/tools.ts
+var DEFAULT_OPTIONS = {
+  defaultLimit: 100,
+  maxExecutionRows: 1e3,
+  maxRowsToModel: 25,
+  maxCellsToModel: 250,
+  maxElementsToModel: 500,
+  maxBytesToModel: 32e3,
+  maxOutputBytes: 1e7
+};
+function toErrorOutput(error) {
+  if (error instanceof SqaiError) {
+    const nearest = error.details["nearest_matches"];
+    const nearestMatches = Array.isArray(nearest) && nearest.every((item) => typeof item === "string") ? nearest : void 0;
+    return {
+      status: "error",
+      code: error.code,
+      message: error.message,
+      retryable: error.retryable,
+      request_id: error.requestId,
+      ...nearestMatches ? { nearest_matches: nearestMatches } : {}
+    };
+  }
+  return {
+    status: "error",
+    code: "internal_error",
+    message: error instanceof Error ? error.message : String(error),
+    retryable: false,
+    request_id: null
+  };
+}
+async function readyError(toolkit) {
+  try {
+    await toolkit.ensureReady();
+    return null;
+  } catch (error) {
+    return error instanceof SqaiError ? error : new SqaiError(
+      "source_connection_failed",
+      `Connecting the configured sources failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function passthroughCandidates(resolution) {
+  return (resolution.candidates ?? []).map((candidate) => ({ ...candidate }));
+}
+function clarificationOutput(resolution) {
+  const candidates = resolution.candidates ?? [];
+  const names = candidates.slice(0, 5).map((candidate) => `${candidate.source}.${candidate.column}`);
+  const lead = resolution.explanation?.[0] ?? "The request is ambiguous.";
+  const question = names.length > 0 ? `${lead} Did you mean ${names.join(" or ")}?` : lead;
+  return {
+    status: "needs_clarification",
+    question,
+    candidates: passthroughCandidates(resolution),
+    explanation: resolution.explanation ?? []
+  };
+}
+function rejectedOutput(resolution) {
+  return {
+    status: "rejected",
+    rejection_reason: resolution.rejection_reason ?? "rejected",
+    candidates: passthroughCandidates(resolution),
+    explanation: resolution.explanation ?? []
+  };
+}
+function renderSignature(entry) {
+  const params = entry.signature.params;
+  const rendered = params.map((param) => `${param.name}${param.required === false ? "?" : ""}: ${param.type}`).join(", ");
+  return `${entry.name}(${rendered}) -> ${entry.signature.returns}`;
+}
+function splitCapabilityName(name) {
+  const separator = name.lastIndexOf(".");
+  return { module: name.slice(0, separator), functionName: name.slice(separator + 1) };
+}
+function toQuerySpec(spec, options) {
+  const sourceName = spec.source ?? options.source;
+  return {
+    metric: spec.metric,
+    ...spec.aggregation ? { aggregation: spec.aggregation } : {},
+    ...spec.group_by ? { group_by: spec.group_by } : {},
+    ...spec.filter ? { filter: spec.filter } : {},
+    limit: Math.min(spec.limit ?? options.defaultLimit, options.maxExecutionRows),
+    ...spec.order ? { order: spec.order } : {},
+    ...sourceName ? { source_name: sourceName } : {}
+  };
+}
+function toComputationSpec(spec) {
+  return {
+    module: spec.module,
+    function: spec.function,
+    args: spec.args ?? [],
+    ...spec.kwargs ? { kwargs: spec.kwargs } : {},
+    ...spec.bindings ? { bindings: spec.bindings } : {},
+    ...spec.seed !== void 0 ? { seed: spec.seed } : {}
+  };
+}
+var NUMBER_OPS = [
+  "sum",
+  "avg",
+  "count",
+  "min",
+  "max",
+  "eq",
+  "in",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "is_null",
+  "is_not_null"
+];
+var FILTER_ONLY_OPS = ["eq", "in", "is_null", "is_not_null"];
+function opsForFieldType(type) {
+  if (type === "number") {
+    return [...NUMBER_OPS];
+  }
+  return [...FILTER_ONLY_OPS];
+}
+function describeSources(sources) {
+  return sources.map((source) => {
+    const typedFields = source.typed_fields.length > 0 ? source.typed_fields : source.fields.map((name) => ({ name, type: "unknown" }));
+    return {
+      name: source.name,
+      fields: typedFields.map((field) => ({
+        name: field.name,
+        type: field.type,
+        ops: opsForFieldType(field.type)
+      })),
+      row_count: source.row_count,
+      schema_revision: source.schema_revision
+    };
+  });
+}
+function searchModules(client, query) {
+  const matches = client.searchCapabilities(query, 100);
+  const byModule = /* @__PURE__ */ new Map();
+  for (const match of matches) {
+    const { module, functionName } = splitCapabilityName(match.entry.name);
+    let aggregate = byModule.get(module);
+    if (!aggregate) {
+      if (byModule.size >= 10) {
+        continue;
+      }
+      aggregate = {
+        name: module,
+        category: match.entry.category,
+        deterministic: true,
+        function_count: 0,
+        sample_functions: []
+      };
+      byModule.set(module, aggregate);
+    }
+    aggregate.function_count += 1;
+    if (aggregate.sample_functions.length < 5) {
+      aggregate.sample_functions.push(functionName);
+    }
+  }
+  return [...byModule.values()];
+}
+function moduleFunctions(client, index, moduleName) {
+  const prefix = `${moduleName}.`;
+  const entries = client.capabilities().capabilities.filter(
+    (entry) => entry.ai_sdk && isReadOnlyEligible(entry) && entry.name.startsWith(prefix)
+  );
+  if (entries.length === 0) {
+    throw new SqaiError("unsupported_operation", `Unknown capability module '${moduleName}'.`, {
+      details: { module: moduleName, nearest_matches: index().nearest(moduleName) }
+    });
+  }
+  return entries.map((entry) => ({
+    name: entry.name,
+    signature: renderSignature(entry),
+    params: entry.signature.params.map(
+      (param) => ({ name: param.name, type: param.type, required: param.required ?? true })
+    ),
+    returns: entry.signature.returns,
+    deterministic: entry.deterministic,
+    seed_required: entry.seed_required ?? false
+  }));
+}
+function createSqaiTools(toolkit, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const client = toolkit.client;
+  let cachedIndex = null;
+  const contractIndex = () => {
+    if (!cachedIndex) {
+      cachedIndex = new ContractIndex(client.capabilities());
+    }
+    return cachedIndex;
+  };
+  const listSources = tool({
+    description: "Discover what SQAI can touch. No arguments: list connected data sources with exact field names, types, and allowed operations \u2014 call this before queryData so specs use exact names. With capabilitySearch: search the deterministic computation catalog and get matching modules. With module: list that module's functions with exact signatures.",
+    inputSchema: listSourcesInputSchema,
+    outputSchema: listSourcesOutputSchema,
+    execute: async (input) => {
+      const notReady = await readyError(toolkit);
+      if (notReady) {
+        return toErrorOutput(notReady);
+      }
+      try {
+        if (input?.capabilitySearch) {
+          return { modules: searchModules(client, input.capabilitySearch) };
+        }
+        if (input?.module) {
+          return { functions: moduleFunctions(client, contractIndex, input.module) };
+        }
+        return { sources: describeSources(client.listSources()) };
+      } catch (error) {
+        return toErrorOutput(error);
+      }
+    }
+  });
+  const queryData = tool({
+    description: "Execute one deterministic, read-only SQAI request. Use kind 'query' for tabular questions (aggregations, grouping, filtering) over connected sources \u2014 call listSources first for exact field names. Use kind 'computation' for math (statistics, financial, vector/matrix, simulation) over arrays: never paste large data into args \u2014 use bindings to pull columns from connected sources. Simulation modules require a seed. Large results are truncated for context; the full result stays retrievable via result_id.",
+    inputSchema: queryDataInputSchema,
+    outputSchema: queryDataOutputSchema,
+    execute: async (input) => {
+      const notReady = await readyError(toolkit);
+      if (notReady) {
+        return toErrorOutput(notReady);
+      }
+      try {
+        if (input.kind === "query") {
+          return await runQuery(input.spec);
+        }
+        return await runComputation(input.spec);
+      } catch (error) {
+        return toErrorOutput(error);
+      }
+    }
+  });
+  const explainQuery = tool({
+    description: "Dry-run a queryData request without executing it. kind 'query': resolve and verify the plan (resolved_plan, plan steps, plan_hash, confidence, validated). kind 'computation': check the capability exists and get its exact signature, a preview invocation_hash, and whether a seed is required. Use this to debug clarifications and rejections before running queryData.",
+    inputSchema: explainQueryInputSchema,
+    outputSchema: explainQueryOutputSchema,
+    execute: async (input) => {
+      const notReady = await readyError(toolkit);
+      if (notReady) {
+        return toErrorOutput(notReady);
+      }
+      try {
+        if (input.kind === "query") {
+          return await explainQueryPlan(input.spec);
+        }
+        return explainComputation(input.spec);
+      } catch (error) {
+        return toErrorOutput(error);
+      }
+    }
+  });
+  async function runQuery(spec) {
+    const querySpec = toQuerySpec(spec, opts);
+    const outcome = await client.ask(querySpec);
+    if (outcome.status === "needs_clarification") {
+      return clarificationOutput(outcome.resolution);
+    }
+    if (outcome.status === "rejected") {
+      return rejectedOutput(outcome.resolution);
+    }
+    const { data, resolution } = outcome;
+    const shaped = shapeQueryResult(data.result, opts);
+    const sourceName = data.resolved_source || resolution.resolved_source || null;
+    const resultId = storeWithinCap(
+      data.result,
+      opts.maxOutputBytes,
+      (value) => client.storeResult(value, sourceName ? [sourceName] : [])
+    );
+    return {
+      status: "ok",
+      kind: "query",
+      data: shaped.data,
+      total_rows: shaped.total_rows,
+      returned_rows: shaped.returned_rows,
+      truncated: shaped.truncated,
+      ...resultId ? { result_id: resultId } : {},
+      plan_hash: data.plan_hash ?? resolution.plan_hash ?? null,
+      schema_revision: data.schema_revision ?? resolution.schema_revision ?? null,
+      source_name: sourceName,
+      intent_signature: resolution.intent_signature ?? null,
+      deterministic_scope: data.deterministic_scope ?? resolution.deterministic_scope ?? null,
+      decision_path: data.decision_path ?? resolution.decision_path ?? null,
+      validated: data.validated ?? resolution.validated ?? null,
+      request_id: data.request_id ?? resolution.request_id ?? null,
+      explanation: data.explanation ?? resolution.explanation ?? []
+    };
+  }
+  async function runComputation(spec) {
+    const result = await client.compute(toComputationSpec(spec));
+    const shaped = shapeComputationValue(result.value, opts);
+    const sourceIds = result.provenance?.bindings.map((binding) => binding.source_name) ?? [];
+    const resultId = storeWithinCap(
+      result.value,
+      opts.maxOutputBytes,
+      (value) => client.storeResult(value, sourceIds)
+    );
+    return {
+      status: "ok",
+      kind: "computation",
+      value: shaped.value,
+      value_type: result.value_type,
+      ...shaped.preview !== void 0 ? { preview: shaped.preview } : {},
+      ...shaped.element_count !== void 0 ? { element_count: shaped.element_count } : {},
+      truncated: shaped.truncated,
+      ...resultId ? { result_id: resultId } : {},
+      invocation_hash: result.invocation_hash,
+      computation_hash: result.computation_hash,
+      contract_hash: result.contract_hash,
+      determinism: result.determinism,
+      ...result.provenance ? { provenance: result.provenance } : {},
+      latency_ms: result.latency_ms,
+      request_id: result.request_id
+    };
+  }
+  async function explainQueryPlan(spec) {
+    const resolution = await client.resolve(toQuerySpec(spec, opts));
+    if (resolution.clarification_required) {
+      return clarificationOutput(resolution);
+    }
+    if (resolution.rejection_reason || !resolution.resolved_plan) {
+      return rejectedOutput(resolution);
+    }
+    const verification = await client.verify(resolution);
+    return {
+      status: "ok",
+      kind: "query",
+      resolved_plan: resolution.resolved_plan,
+      plan: resolution.plan ?? [],
+      plan_hash: resolution.plan_hash ?? null,
+      confidence: resolution.confidence,
+      validated: verification.valid === true
+    };
+  }
+  function explainComputation(spec) {
+    const index = contractIndex();
+    const entry = lookupCapability(index, spec.module, spec.function);
+    const bindings = spec.bindings ?? [];
+    const descriptors = bindings.flatMap(
+      (binding) => "parameters" in binding ? binding.parameters.map((parameter, position) => ({
+        parameter,
+        source_name: binding.source,
+        fields: [binding.fields[position] ?? ""],
+        input_hash: ""
+      })) : [
+        {
+          parameter: binding.parameter,
+          source_name: binding.source,
+          fields: [binding.field],
+          input_hash: ""
+        }
+      ]
+    );
+    const previewHash = invocationHash({
+      module: spec.module,
+      function: spec.function,
+      args: spec.args ?? [],
+      kwargs: spec.kwargs ?? {},
+      resolved_bindings: descriptors,
+      seed: spec.seed ?? null,
+      contract_hash: index.contract.capability_contract_hash,
+      execution_scope: `${currentPlatformKey()}:${client.mode}`
+    });
+    return {
+      status: "ok",
+      kind: "computation",
+      matched_signature: renderSignature(entry),
+      invocation_hash: previewHash,
+      seed_required: entry.seed_required ?? false
+    };
+  }
+  return { listSources, queryData, explainQuery };
+}
+
+// src/toolkit.ts
+var SQAIToolkit = class {
+  client;
+  sourceInputs;
+  readyPromise = null;
+  readyError = null;
+  constructor(config = {}) {
+    const { sources, ...clientConfig } = config;
+    this.client = new SQAI(clientConfig);
+    this.sourceInputs = sources ?? [];
+  }
+  /** Connected sources; connecting starts on first access. */
+  get ready() {
+    return this.ensureReady();
+  }
+  /** The stored connection failure, when `ready` rejected. */
+  get connectionError() {
+    return this.readyError;
+  }
+  ensureReady() {
+    if (!this.readyPromise) {
+      this.readyPromise = this.connectAll();
+      this.readyPromise.catch((error) => {
+        this.readyError = error instanceof SqaiError2 ? error : new SqaiError2(
+          "source_connection_failed",
+          `Connecting the configured sources failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      });
+    }
+    return this.readyPromise;
+  }
+  async connect(source, options = {}) {
+    return this.client.connect(source, options);
+  }
+  tools(options = {}) {
+    return createSqaiTools(this, options);
+  }
+  async connectAll() {
+    for (const input of this.sourceInputs) {
+      if (typeof input === "string" || Array.isArray(input)) {
+        await this.client.connect(input);
+      } else {
+        await this.client.connect(input.data, input.name ? { name: input.name } : {});
+      }
+    }
+    return this.client.listSources();
+  }
+};
+function createSQAI(config = {}) {
+  return new SQAIToolkit(config);
+}
+
+// src/index.ts
+import { SQAI as SQAI2, SqaiError as SqaiError3 } from "@thyn-ai/sqai";
+export {
+  SQAI2 as SQAI,
+  SQAIToolkit,
+  SqaiError3 as SqaiError,
+  algentaWireValueSchema,
+  bindingProvenanceSchema,
+  candidateSchema,
+  clarificationOutputSchema,
+  computationBindingSchema,
+  computationOkOutputSchema,
+  computationSpecSchema,
+  createSQAI,
+  createSqaiTools,
+  determinismEnvelopeSchema,
+  errorOutputSchema,
+  explainQueryInputSchema,
+  explainQueryOkComputationOutputSchema,
+  explainQueryOkQueryOutputSchema,
+  explainQueryOutputSchema,
+  filterConditionSchema,
+  filterSpecSchema,
+  functionListOutputSchema,
+  listSourcesInputSchema,
+  listSourcesOutputSchema,
+  moduleListOutputSchema,
+  queryDataInputSchema,
+  queryDataOutputSchema,
+  queryOkOutputSchema,
+  querySpecSchema,
+  rejectedOutputSchema,
+  shapeComputationValue,
+  shapeQueryResult,
+  sourceListOutputSchema,
+  storeWithinCap
+};
+//# sourceMappingURL=index.js.map