@kognitivedev/model-flow 0.2.29

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+
+$ tsc

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @kognitivedev/model-flow
+
+## 0.2.29
+
+### Patch Changes
+
+- release

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+export type JsonObject = Record<string, unknown>;
+export type ModelFlowTaskType = "classification" | "regression" | "ranking" | "extraction" | "generation";
+export type ModelFlowNodeType = "data_source" | "query" | "join" | "snapshot" | "schema_profile" | "target" | "data_quality" | "leakage_check" | "cleaning" | "feature_transform" | "text_features" | "embedding" | "train_test_split" | "model_candidate" | "ensemble" | "validation" | "slice_metrics" | "prediction_preview" | "publish_contract" | "inference_transform" | "deploy_preview";
+export interface ModelFlowObjective {
+    taskType: ModelFlowTaskType;
+    target?: string;
+    optimizationMetric?: string;
+}
+export interface ModelFlowNode {
+    id: string;
+    type: ModelFlowNodeType;
+    label?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    config?: JsonObject;
+}
+export interface ModelFlowEdge {
+    id?: string;
+    from: string;
+    to: string;
+    label?: string;
+    config?: JsonObject;
+}
+export interface ModelFlowDefinition {
+    version: 1;
+    inputSchema?: JsonObject;
+    outputSchema?: JsonObject;
+    objective: ModelFlowObjective;
+    nodes: ModelFlowNode[];
+    edges: ModelFlowEdge[];
+    metadata?: JsonObject;
+}
+export interface ModelFlowValidationIssue {
+    severity: "error" | "warning" | "info";
+    scope: "graph" | "node" | "edge";
+    nodeId?: string;
+    edgeId?: string;
+    code: string;
+    message: string;
+}
+export interface ModelFlowRunEvent {
+    eventType: string;
+    nodeId?: string | null;
+    nodeType?: string | null;
+    stepIndex?: number | null;
+    payload?: JsonObject | null;
+}
+export declare const MODEL_FLOW_NODE_TYPES: ModelFlowNodeType[];
+export declare function createEmptyModelFlowDefinition(): ModelFlowDefinition;
+export declare function normalizeModelFlowDefinition(definition: Partial<ModelFlowDefinition> | null | undefined): ModelFlowDefinition;
+export declare function validateModelFlowDefinition(definition: Partial<ModelFlowDefinition> | null | undefined): ModelFlowValidationIssue[];
+export declare function hasBlockingModelFlowIssues(issues: ModelFlowValidationIssue[]): boolean;

package/dist/index.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_FLOW_NODE_TYPES = void 0;
+exports.createEmptyModelFlowDefinition = createEmptyModelFlowDefinition;
+exports.normalizeModelFlowDefinition = normalizeModelFlowDefinition;
+exports.validateModelFlowDefinition = validateModelFlowDefinition;
+exports.hasBlockingModelFlowIssues = hasBlockingModelFlowIssues;
+exports.MODEL_FLOW_NODE_TYPES = [
+    "data_source",
+    "query",
+    "join",
+    "snapshot",
+    "schema_profile",
+    "target",
+    "data_quality",
+    "leakage_check",
+    "cleaning",
+    "feature_transform",
+    "text_features",
+    "embedding",
+    "train_test_split",
+    "model_candidate",
+    "ensemble",
+    "validation",
+    "slice_metrics",
+    "prediction_preview",
+    "publish_contract",
+    "inference_transform",
+    "deploy_preview",
+];
+const NODE_TYPE_SET = new Set(exports.MODEL_FLOW_NODE_TYPES);
+function createEmptyModelFlowDefinition() {
+    return {
+        version: 1,
+        inputSchema: { type: "object", properties: {}, required: [] },
+        outputSchema: { type: "object", properties: {}, required: [] },
+        objective: { taskType: "classification" },
+        nodes: [],
+        edges: [],
+    };
+}
+function normalizeModelFlowDefinition(definition) {
+    const fallback = createEmptyModelFlowDefinition();
+    const nodes = Array.isArray(definition === null || definition === void 0 ? void 0 : definition.nodes)
+        ? definition.nodes.filter(isModelFlowNode).map((node) => (Object.assign(Object.assign({}, node), { config: isRecord(node.config) ? node.config : {} })))
+        : [];
+    const edges = Array.isArray(definition === null || definition === void 0 ? void 0 : definition.edges)
+        ? definition.edges.filter(isModelFlowEdge)
+        : [];
+    const objective = isRecord(definition === null || definition === void 0 ? void 0 : definition.objective)
+        ? Object.assign(Object.assign({ taskType: isTaskType(definition.objective.taskType) ? definition.objective.taskType : fallback.objective.taskType }, (typeof definition.objective.target === "string" ? { target: definition.objective.target } : {})), (typeof definition.objective.optimizationMetric === "string" ? { optimizationMetric: definition.objective.optimizationMetric } : {})) : fallback.objective;
+    return Object.assign({ version: 1, inputSchema: isRecord(definition === null || definition === void 0 ? void 0 : definition.inputSchema) ? definition.inputSchema : fallback.inputSchema, outputSchema: isRecord(definition === null || definition === void 0 ? void 0 : definition.outputSchema) ? definition.outputSchema : fallback.outputSchema, objective,
+        nodes,
+        edges }, (isRecord(definition === null || definition === void 0 ? void 0 : definition.metadata) ? { metadata: definition.metadata } : {}));
+}
+function validateModelFlowDefinition(definition) {
+    var _a, _b;
+    const normalized = normalizeModelFlowDefinition(definition);
+    const issues = [];
+    const nodeIds = new Set();
+    const nodeTypes = new Set();
+    for (const node of normalized.nodes) {
+        if (nodeIds.has(node.id)) {
+            issues.push(nodeIssue("error", node.id, "duplicate_node_id", `Node id "${node.id}" is duplicated.`));
+        }
+        nodeIds.add(node.id);
+        nodeTypes.add(node.type);
+    }
+    for (const requiredType of ["data_source", "target", "model_candidate", "validation"]) {
+        if (!nodeTypes.has(requiredType)) {
+            issues.push(graphIssue("error", `missing_${requiredType}`, `Add a ${requiredType.replaceAll("_", " ")} node before publishing.`));
+        }
+    }
+    if (!((_a = normalized.objective) === null || _a === void 0 ? void 0 : _a.target)) {
+        const targetNode = normalized.nodes.find((node) => node.type === "target");
+        const targetColumn = typeof ((_b = targetNode === null || targetNode === void 0 ? void 0 : targetNode.config) === null || _b === void 0 ? void 0 : _b.targetColumn) === "string" ? targetNode.config.targetColumn : "";
+        if (!targetColumn) {
+            issues.push(graphIssue("error", "missing_target_column", "Choose the target column the model should predict."));
+        }
+    }
+    if (!nodeTypes.has("train_test_split")) {
+        issues.push(graphIssue("warning", "missing_holdout", "Add a train/test split so validation is not measured on training rows."));
+    }
+    if (!nodeTypes.has("publish_contract")) {
+        issues.push(graphIssue("info", "missing_publish_contract", "Add a publish contract node before exposing an inference API."));
+    }
+    for (const edge of normalized.edges) {
+        if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to)) {
+            issues.push({
+                severity: "error",
+                scope: "edge",
+                edgeId: edge.id,
+                code: "broken_edge",
+                message: `Edge ${edge.from} -> ${edge.to} references a missing node.`,
+            });
+        }
+    }
+    return issues;
+}
+function hasBlockingModelFlowIssues(issues) {
+    return issues.some((issue) => issue.severity === "error");
+}
+function isModelFlowNode(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.id === "string"
+        && typeof value.type === "string"
+        && NODE_TYPE_SET.has(value.type);
+}
+function isModelFlowEdge(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.from === "string" && typeof value.to === "string";
+}
+function isTaskType(value) {
+    return value === "classification"
+        || value === "regression"
+        || value === "ranking"
+        || value === "extraction"
+        || value === "generation";
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function graphIssue(severity, code, message) {
+    return { severity, scope: "graph", code, message };
+}
+function nodeIssue(severity, nodeId, code, message) {
+    return { severity, scope: "node", nodeId, code, message };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@kognitivedev/model-flow",
+  "version": "0.2.29",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w --noCheck",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "description": "Shared model-flow graph contracts and validation for Kognitive",
+  "keywords": [
+    "kognitive",
+    "model-flow",
+    "ml",
+    "ai"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kognitivedev/kognitive",
+    "directory": "packages/model-flow"
+  },
+  "homepage": "https://kognitive.dev"
+}

package/src/__tests__/model-flow.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import {
+    createEmptyModelFlowDefinition,
+    hasBlockingModelFlowIssues,
+    normalizeModelFlowDefinition,
+    validateModelFlowDefinition,
+} from "../index";
+
+describe("model-flow shared contract", () => {
+    it("normalizes unknown definitions to a safe graph shape", () => {
+        const definition = normalizeModelFlowDefinition({ nodes: [{ id: "x", type: "not_real" } as never] });
+
+        expect(definition.version).toBe(1);
+        expect(definition.nodes).toEqual([]);
+        expect(definition.edges).toEqual([]);
+    });
+
+    it("validates publish-blocking model graph requirements", () => {
+        const issues = validateModelFlowDefinition(createEmptyModelFlowDefinition());
+
+        expect(hasBlockingModelFlowIssues(issues)).toBe(true);
+        expect(issues.map((issue) => issue.code)).toContain("missing_data_source");
+        expect(issues.map((issue) => issue.code)).toContain("missing_model_candidate");
+    });
+
+    it("accepts a complete minimal graph", () => {
+        const issues = validateModelFlowDefinition({
+            version: 1,
+            objective: { taskType: "classification", target: "churn_30d", optimizationMetric: "f1" },
+            nodes: [
+                { id: "source", type: "data_source" },
+                { id: "target", type: "target", config: { targetColumn: "churn_30d" } },
+                { id: "split", type: "train_test_split" },
+                { id: "model", type: "model_candidate" },
+                { id: "validate", type: "validation" },
+                { id: "contract", type: "publish_contract" },
+            ],
+            edges: [
+                { from: "source", to: "target" },
+                { from: "target", to: "split" },
+                { from: "split", to: "model" },
+                { from: "model", to: "validate" },
+                { from: "validate", to: "contract" },
+            ],
+        });
+
+        expect(hasBlockingModelFlowIssues(issues)).toBe(false);
+    });
+});
+

package/src/index.ts

@@ -0,0 +1,235 @@
+export type JsonObject = Record<string, unknown>;
+
+export type ModelFlowTaskType =
+    | "classification"
+    | "regression"
+    | "ranking"
+    | "extraction"
+    | "generation";
+
+export type ModelFlowNodeType =
+    | "data_source"
+    | "query"
+    | "join"
+    | "snapshot"
+    | "schema_profile"
+    | "target"
+    | "data_quality"
+    | "leakage_check"
+    | "cleaning"
+    | "feature_transform"
+    | "text_features"
+    | "embedding"
+    | "train_test_split"
+    | "model_candidate"
+    | "ensemble"
+    | "validation"
+    | "slice_metrics"
+    | "prediction_preview"
+    | "publish_contract"
+    | "inference_transform"
+    | "deploy_preview";
+
+export interface ModelFlowObjective {
+    taskType: ModelFlowTaskType;
+    target?: string;
+    optimizationMetric?: string;
+}
+
+export interface ModelFlowNode {
+    id: string;
+    type: ModelFlowNodeType;
+    label?: string;
+    position?: { x: number; y: number };
+    config?: JsonObject;
+}
+
+export interface ModelFlowEdge {
+    id?: string;
+    from: string;
+    to: string;
+    label?: string;
+    config?: JsonObject;
+}
+
+export interface ModelFlowDefinition {
+    version: 1;
+    inputSchema?: JsonObject;
+    outputSchema?: JsonObject;
+    objective: ModelFlowObjective;
+    nodes: ModelFlowNode[];
+    edges: ModelFlowEdge[];
+    metadata?: JsonObject;
+}
+
+export interface ModelFlowValidationIssue {
+    severity: "error" | "warning" | "info";
+    scope: "graph" | "node" | "edge";
+    nodeId?: string;
+    edgeId?: string;
+    code: string;
+    message: string;
+}
+
+export interface ModelFlowRunEvent {
+    eventType: string;
+    nodeId?: string | null;
+    nodeType?: string | null;
+    stepIndex?: number | null;
+    payload?: JsonObject | null;
+}
+
+export const MODEL_FLOW_NODE_TYPES: ModelFlowNodeType[] = [
+    "data_source",
+    "query",
+    "join",
+    "snapshot",
+    "schema_profile",
+    "target",
+    "data_quality",
+    "leakage_check",
+    "cleaning",
+    "feature_transform",
+    "text_features",
+    "embedding",
+    "train_test_split",
+    "model_candidate",
+    "ensemble",
+    "validation",
+    "slice_metrics",
+    "prediction_preview",
+    "publish_contract",
+    "inference_transform",
+    "deploy_preview",
+];
+
+const NODE_TYPE_SET = new Set<string>(MODEL_FLOW_NODE_TYPES);
+
+export function createEmptyModelFlowDefinition(): ModelFlowDefinition {
+    return {
+        version: 1,
+        inputSchema: { type: "object", properties: {}, required: [] },
+        outputSchema: { type: "object", properties: {}, required: [] },
+        objective: { taskType: "classification" },
+        nodes: [],
+        edges: [],
+    };
+}
+
+export function normalizeModelFlowDefinition(definition: Partial<ModelFlowDefinition> | null | undefined): ModelFlowDefinition {
+    const fallback = createEmptyModelFlowDefinition();
+    const nodes = Array.isArray(definition?.nodes)
+        ? definition.nodes.filter(isModelFlowNode).map((node) => ({
+            ...node,
+            config: isRecord(node.config) ? node.config : {},
+        }))
+        : [];
+    const edges = Array.isArray(definition?.edges)
+        ? definition.edges.filter(isModelFlowEdge)
+        : [];
+    const objective = isRecord(definition?.objective)
+        ? {
+            taskType: isTaskType(definition.objective.taskType) ? definition.objective.taskType : fallback.objective.taskType,
+            ...(typeof definition.objective.target === "string" ? { target: definition.objective.target } : {}),
+            ...(typeof definition.objective.optimizationMetric === "string" ? { optimizationMetric: definition.objective.optimizationMetric } : {}),
+        }
+        : fallback.objective;
+
+    return {
+        version: 1,
+        inputSchema: isRecord(definition?.inputSchema) ? definition.inputSchema : fallback.inputSchema,
+        outputSchema: isRecord(definition?.outputSchema) ? definition.outputSchema : fallback.outputSchema,
+        objective,
+        nodes,
+        edges,
+        ...(isRecord(definition?.metadata) ? { metadata: definition.metadata } : {}),
+    };
+}
+
+export function validateModelFlowDefinition(definition: Partial<ModelFlowDefinition> | null | undefined): ModelFlowValidationIssue[] {
+    const normalized = normalizeModelFlowDefinition(definition);
+    const issues: ModelFlowValidationIssue[] = [];
+    const nodeIds = new Set<string>();
+    const nodeTypes = new Set<ModelFlowNodeType>();
+
+    for (const node of normalized.nodes) {
+        if (nodeIds.has(node.id)) {
+            issues.push(nodeIssue("error", node.id, "duplicate_node_id", `Node id "${node.id}" is duplicated.`));
+        }
+        nodeIds.add(node.id);
+        nodeTypes.add(node.type);
+    }
+
+    for (const requiredType of ["data_source", "target", "model_candidate", "validation"] as ModelFlowNodeType[]) {
+        if (!nodeTypes.has(requiredType)) {
+            issues.push(graphIssue("error", `missing_${requiredType}`, `Add a ${requiredType.replaceAll("_", " ")} node before publishing.`));
+        }
+    }
+
+    if (!normalized.objective?.target) {
+        const targetNode = normalized.nodes.find((node) => node.type === "target");
+        const targetColumn = typeof targetNode?.config?.targetColumn === "string" ? targetNode.config.targetColumn : "";
+        if (!targetColumn) {
+            issues.push(graphIssue("error", "missing_target_column", "Choose the target column the model should predict."));
+        }
+    }
+
+    if (!nodeTypes.has("train_test_split")) {
+        issues.push(graphIssue("warning", "missing_holdout", "Add a train/test split so validation is not measured on training rows."));
+    }
+
+    if (!nodeTypes.has("publish_contract")) {
+        issues.push(graphIssue("info", "missing_publish_contract", "Add a publish contract node before exposing an inference API."));
+    }
+
+    for (const edge of normalized.edges) {
+        if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to)) {
+            issues.push({
+                severity: "error",
+                scope: "edge",
+                edgeId: edge.id,
+                code: "broken_edge",
+                message: `Edge ${edge.from} -> ${edge.to} references a missing node.`,
+            });
+        }
+    }
+
+    return issues;
+}
+
+export function hasBlockingModelFlowIssues(issues: ModelFlowValidationIssue[]): boolean {
+    return issues.some((issue) => issue.severity === "error");
+}
+
+function isModelFlowNode(value: unknown): value is ModelFlowNode {
+    if (!isRecord(value)) return false;
+    return typeof value.id === "string"
+        && typeof value.type === "string"
+        && NODE_TYPE_SET.has(value.type);
+}
+
+function isModelFlowEdge(value: unknown): value is ModelFlowEdge {
+    if (!isRecord(value)) return false;
+    return typeof value.from === "string" && typeof value.to === "string";
+}
+
+function isTaskType(value: unknown): value is ModelFlowTaskType {
+    return value === "classification"
+        || value === "regression"
+        || value === "ranking"
+        || value === "extraction"
+        || value === "generation";
+}
+
+function isRecord(value: unknown): value is JsonObject {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function graphIssue(severity: ModelFlowValidationIssue["severity"], code: string, message: string): ModelFlowValidationIssue {
+    return { severity, scope: "graph", code, message };
+}
+
+function nodeIssue(severity: ModelFlowValidationIssue["severity"], nodeId: string, code: string, message: string): ModelFlowValidationIssue {
+    return { severity, scope: "node", nodeId, code, message };
+}
+

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "noEmit": false,
+    "incremental": false
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}
+