@ekairos/dataset 1.22.40-beta.development.0 → 1.22.40

package/dist/materializeDataset.tool.js

@@ -1,86 +1,92 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.materializeDatasetToolInputSchema = void 0;
-exports.createMaterializeDatasetTool = createMaterializeDatasetTool;
-const ai_1 = require("ai");
-const zod_1 = require("zod");
-const dataset_1 = require("./dataset");
-const fileSourceSchema = zod_1.z.object({
-    kind: zod_1.z.literal("file"),
-    fileId: zod_1.z.string(),
-    description: zod_1.z.string().optional(),
+import { tool } from "ai";
+import { z } from "zod";
+import { dataset } from "./dataset.js";
+const fileResourceSchema = z.object({
+    kind: z.literal("file"),
+    fileId: z.string(),
+    description: z.string().optional(),
 });
-const textSourceSchema = zod_1.z.object({
-    kind: zod_1.z.literal("text"),
-    text: zod_1.z.string(),
-    mimeType: zod_1.z.string().optional(),
-    name: zod_1.z.string().optional(),
-    description: zod_1.z.string().optional(),
+const textResourceSchema = z.object({
+    kind: z.literal("text"),
+    text: z.string(),
+    mimeType: z.string().optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
 });
-const datasetSourceSchema = zod_1.z.object({
-    kind: zod_1.z.literal("dataset"),
-    datasetId: zod_1.z.string(),
-    description: zod_1.z.string().optional(),
+const datasetResourceSchema = z.object({
+    kind: z.literal("dataset"),
+    datasetId: z.string(),
+    description: z.string().optional(),
 });
-const querySourceSchema = zod_1.z.object({
-    kind: zod_1.z.literal("query"),
-    query: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
-    title: zod_1.z.string().optional(),
-    explanation: zod_1.z.string().optional(),
+const queryResourceSchema = z.object({
+    kind: z.literal("query"),
+    query: z.record(z.string(), z.any()),
+    title: z.string().optional(),
+    explanation: z.string().optional(),
 });
-const datasetSchemaSchema = zod_1.z.object({
-    title: zod_1.z.string().optional(),
-    description: zod_1.z.string().optional(),
-    schema: zod_1.z.any(),
+const contextInputSchema = z.union([
+    z.object({ id: z.string() }),
+    z.object({ key: z.string() }),
+]);
+const datasetSchemaSchema = z.object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+    schema: z.any(),
 });
-const materializeDatasetToolInputSchema = zod_1.z.object({
-    datasetId: zod_1.z.string().optional(),
-    sandboxId: zod_1.z.string().optional(),
-    title: zod_1.z.string().optional(),
-    sources: zod_1.z
-        .array(zod_1.z.discriminatedUnion("kind", [
-        fileSourceSchema,
-        textSourceSchema,
-        datasetSourceSchema,
-        querySourceSchema,
-    ]))
-        .min(1),
-    instructions: zod_1.z.string().optional(),
-    mode: zod_1.z.enum(["auto", "schema"]).optional(),
-    output: zod_1.z.enum(["rows", "object"]).optional(),
+const materializeDatasetToolInputSchema = z.object({
+    datasetId: z.string().optional(),
+    sandboxId: z.string().optional(),
+    title: z.string().optional(),
+    context: contextInputSchema.optional(),
+    files: z.array(fileResourceSchema.omit({ kind: true })).optional(),
+    texts: z.array(textResourceSchema.omit({ kind: true })).optional(),
+    datasets: z.array(datasetResourceSchema.omit({ kind: true })).optional(),
+    queries: z.array(queryResourceSchema.omit({ kind: true })).optional(),
+    instructions: z.string().optional(),
+    mode: z.enum(["auto", "schema"]).optional(),
+    output: z.enum(["rows", "object"]).optional(),
     schema: datasetSchemaSchema.optional(),
-    first: zod_1.z.boolean().optional(),
+    first: z.boolean().optional(),
 });
-exports.materializeDatasetToolInputSchema = materializeDatasetToolInputSchema;
-function createMaterializeDatasetTool(params) {
-    return (0, ai_1.tool)({
-        description: "Materialize a dataset from declarative sources. Returns only the target datasetId. Query sources use the preconfigured runtime domain.",
+export function createMaterializeDatasetTool(params) {
+    return tool({
+        description: "Materialize a dataset from declarative resources. Returns only the target datasetId. Query resources use the preconfigured runtime domain.",
         inputSchema: materializeDatasetToolInputSchema,
         execute: async (input) => {
-            let builder = (0, dataset_1.dataset)(params.runtime);
+            let builder = dataset(params.runtime);
             if (input.title?.trim()) {
                 builder = builder.title(input.title);
             }
             if (input.sandboxId?.trim()) {
                 builder = builder.sandbox({ sandboxId: input.sandboxId });
             }
-            for (const source of input.sources) {
-                if (source.kind === "file") {
-                    builder = builder.fromFile(source);
-                    continue;
-                }
-                if (source.kind === "text") {
-                    builder = builder.fromText(source);
-                    continue;
-                }
-                if (source.kind === "dataset") {
-                    builder = builder.fromDataset(source);
-                    continue;
-                }
+            const materialCount = (input.files?.length ?? 0) +
+                (input.texts?.length ?? 0) +
+                (input.datasets?.length ?? 0) +
+                (input.queries?.length ?? 0);
+            if (input.context && materialCount > 0) {
+                throw new Error("dataset_context_resource_is_exclusive");
+            }
+            if (!input.context && materialCount === 0) {
+                throw new Error("dataset_context_or_material_required");
+            }
+            if (input.context) {
+                builder = builder.fromContext(input.context);
+            }
+            for (const resource of input.files ?? []) {
+                builder = builder.fromFile(resource);
+            }
+            for (const resource of input.texts ?? []) {
+                builder = builder.fromText(resource);
+            }
+            for (const resource of input.datasets ?? []) {
+                builder = builder.fromDataset(resource);
+            }
+            for (const resource of input.queries ?? []) {
                 builder = builder.fromQuery(params.queryDomain, {
-                    query: source.query,
-                    title: source.title,
-                    explanation: source.explanation,
+                    query: resource.query,
+                    title: resource.title,
+                    explanation: resource.explanation,
                 });
             }
             if (input.output === "object") {
@@ -109,4 +115,4 @@ function createMaterializeDatasetTool(params) {
         },
     });
 }
-//# sourceMappingURL=materializeDataset.tool.js.map
+export { materializeDatasetToolInputSchema };

package/dist/notation.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Formal notation for datasets — the dataset stated intensionally.
+ *
+ * A dataset has TWO CO-EQUAL FACES at the same level:
+ * - its formal DEFINITION (this notation: the proposition that defines the
+ *   set, in LaTeX), and
+ * - its MATERIALIZATION (the rows + the code that produces them).
+ * The notation is not a comment about the data; it IS the dataset, written
+ * as a logical statement. The materialization is the same set written
+ * extensionally. Neither is subordinate to the other.
+ *
+ * The SAME notation plays two roles across the lifecycle: it is the PLAN
+ * (status "plan": stated first, the materialization is built to realize it)
+ * and, once finalized, the RESULT (status "result": it describes exactly
+ * what was produced). It is iterated in between — every revision keeps the
+ * prior version in `history`, so the discovery trail stays visible.
+ *
+ * The definition is a logical proposition, possibly DERIVED (a syllogism),
+ * so it is NOT, in general, mechanically verifiable: a predicate may be
+ * semantic ("x es una frase divertida") and the set is still well-formed.
+ * We TRUST the formality and the produced dataset — there is no verdict.
+ *
+ * SOME predicates happen to be arithmetic (a row count, a field type, a
+ * preserved total). For those, and only those, we attach OPTIONAL evidence
+ * computed over the rows. It is advisory: a contradiction is a hint, never
+ * a claim that the dataset is invalid. Predicates with no arithmetic form
+ * are "asserted" — trusted. Nothing here blocks or changes a build; the
+ * notation rides on dataset_datasets.notation.
+ */
+export type DatasetNotationSymbolKind = "set" | "variable" | "function" | "constant" | "predicate";
+export type DatasetNotationSymbol = {
+    /** plain identifier, e.g. "D", "w", "Orders" */
+    name: string;
+    /** LaTeX for the symbol, e.g. "\\mathcal{D}" (defaults to the name) */
+    latex?: string;
+    kind: DatasetNotationSymbolKind;
+    description: string;
+};
+export type NotationCmpOp = "=" | "!=" | "<" | "<=" | ">" | ">=";
+/**
+ * OPTIONAL arithmetic evidence for the subset of predicates that happen to
+ * be mechanical (counts, types, ranges, totals). Evaluated over the rows;
+ * field access supports dot-paths into nested records ("company.taxId").
+ * Leaf checks are dataset-level propositions; and/or/not/implies compose
+ * them propositionally. A predicate WITHOUT a check is a formal/semantic
+ * claim we trust — that is the normal case, not an exception.
+ */
+export type NotationCheck = {
+    kind: "row_count";
+    op: NotationCmpOp;
+    value: number;
+} | {
+    kind: "field_type";
+    field: string;
+    type: "number" | "integer" | "string" | "boolean";
+    allowNull?: boolean;
+} | {
+    kind: "field_range";
+    field: string;
+    min?: number;
+    max?: number;
+} | {
+    kind: "field_in";
+    field: string;
+    values: Array<string | number | boolean>;
+} | {
+    kind: "field_nonnull";
+    field: string;
+} | {
+    kind: "field_matches";
+    field: string;
+    pattern: string;
+} | {
+    kind: "unique";
+    fields: string[];
+} | {
+    kind: "aggregate";
+    fn: "sum" | "count" | "min" | "max" | "avg";
+    /** omit for fn = "count" */
+    field?: string;
+    op: NotationCmpOp;
+    value: number;
+    /** absolute tolerance for float comparison (default 1e-9) */
+    tolerance?: number;
+} | {
+    kind: "and";
+    checks: NotationCheck[];
+} | {
+    kind: "or";
+    checks: NotationCheck[];
+} | {
+    kind: "not";
+    check: NotationCheck;
+} | {
+    kind: "implies";
+    if: NotationCheck;
+    then: NotationCheck;
+};
+export type DatasetNotationPredicate = {
+    /** stable id within the notation, e.g. "p1", "rowCount" */
+    id: string;
+    description: string;
+    /** the claim in LaTeX, e.g. "\\forall r \\in D:\\; r.amount > 0" */
+    latex: string;
+    /**
+     * OPTIONAL arithmetic form. Absent (the common case) = a formal/semantic
+     * claim we trust without mechanical checking.
+     */
+    check?: NotationCheck;
+};
+/**
+ * Advisory evidence for one predicate. Never a verdict on the dataset:
+ * - "asserted"     formal/semantic claim, trusted, no mechanical check
+ * - "supported"    arithmetic evidence agrees with the stated claim
+ * - "contradicted" arithmetic evidence disagrees — a hint, not a failure
+ */
+export type DatasetNotationCheckResult = {
+    predicateId: string;
+    status: "asserted" | "supported" | "contradicted";
+    detail?: string;
+};
+export type DatasetNotationRevision = {
+    version: number;
+    latex: string;
+    /** why this revision happened — the discovery that triggered it */
+    reason: string;
+    at: number;
+};
+/**
+ * The role the notation currently plays — the two ends of its life:
+ * - "plan":   stated before/while building; the materialization realizes it
+ * - "result": finalized; it describes the dataset that was produced
+ * There is intentionally NO "verified"/"violated" verdict — validity is
+ * trusted, not proven. Iteration is tracked by `version`/`history`; advisory
+ * arithmetic evidence lives in `checks`, separate from this role.
+ */
+export type DatasetNotationStatus = "plan" | "result";
+export type DatasetNotation = {
+    version: number;
+    status: DatasetNotationStatus;
+    /** the main definition: the dataset as a set, in LaTeX */
+    latex: string;
+    symbols: DatasetNotationSymbol[];
+    predicates: DatasetNotationPredicate[];
+    /** advisory per-predicate evidence (asserted/supported/contradicted) */
+    checks?: DatasetNotationCheckResult[];
+    /** when the advisory evidence was last computed */
+    evidenceAt?: number;
+    history: DatasetNotationRevision[];
+};
+export type NotationRevisionInput = {
+    latex: string;
+    symbols?: DatasetNotationSymbol[];
+    predicates?: DatasetNotationPredicate[];
+    reason: string;
+    /** "final" marks the notation as describing the produced dataset */
+    final?: boolean;
+};
+/**
+ * Iterate the notation: every revision bumps the version and appends to
+ * history, so the discovery trail (sets/variables found along the way)
+ * stays visible.
+ */
+export declare function reviseDatasetNotation(previous: DatasetNotation | null | undefined, input: NotationRevisionInput): DatasetNotation;
+/** escape an identifier for use inside \text{} */
+export declare function latexIdentifier(name: string): string;
+type JsonSchemaLike = {
+    title?: string;
+    schema?: Record<string, any>;
+    properties?: Record<string, any>;
+};
+/**
+ * A query-backed dataset has a complete deterministic description: the
+ * dataset is the image of a known query over a known domain. No model is
+ * involved, so here the formal definition and its predicates derive
+ * mechanically from the query, the inferred schema and the row count — and
+ * those predicates DO carry arithmetic evidence (the special case where the
+ * formal claims happen to be fully mechanical).
+ */
+export declare function inferQueryNotation(params: {
+    entityNames: string[];
+    rowCount: number;
+    schema?: JsonSchemaLike | null;
+    explanation?: string;
+}): DatasetNotation;
+type CheckOutcome = {
+    ok: boolean;
+    detail: string;
+};
+export declare function evaluateNotationCheck(rows: any[], check: NotationCheck): CheckOutcome;
+/**
+ * Annotate a notation with ADVISORY arithmetic evidence over the produced
+ * rows. Never throws, never blocks, and never changes the notation's
+ * lifecycle status — the dataset's validity is trusted, not proven here.
+ *
+ * Each predicate is reported as:
+ * - "asserted"     no arithmetic form (formal/semantic claim, trusted)
+ * - "supported"    arithmetic evidence agrees
+ * - "contradicted" arithmetic evidence disagrees (a hint to look, not a
+ *                  verdict that the dataset is wrong)
+ * A check that can't be evaluated stays "asserted" — we don't downgrade a
+ * trusted claim because of a malformed mechanical form.
+ */
+export declare function annotateNotationEvidence(notation: DatasetNotation, rows: any[]): DatasetNotation;
+export {};