@clypra/runtime 1.0.0

package/src/graph/__tests__/validator.test.ts

@@ -0,0 +1,381 @@
+/**
+ * Unit Tests - Graph Validator
+ */
+
+import { describe, it, expect } from "vitest";
+import { GraphValidator } from "../validator";
+import type { MediaProcessingGraph, GraphNode } from "../types";
+
+describe("GraphValidator", () => {
+  const createNode = (id: string, type: string, inputCount: number = 1): GraphNode => ({
+    id,
+    type,
+    version: 1,
+    params: {},
+    inputs:
+      inputCount > 0
+        ? {
+            in: { id: "in", name: "input", type: "Texture" },
+          }
+        : {},
+    outputs: {
+      out: { id: "out", name: "output", type: "Texture" },
+    },
+    capabilities: {
+      temporal: false,
+      stateful: false,
+      spatial: false,
+      geometry: false,
+      inputsCount: inputCount,
+    },
+    requirements: {
+      temporalRadius: 0,
+      preferredPrecision: "fp16",
+      multipass: false,
+      supportsHalfResolution: true,
+    },
+    lifecycle: "Created",
+  });
+
+  describe("validate", () => {
+    it("should validate a correct graph", () => {
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [createNode("node1", "source", 0), createNode("node2", "effect", 1)],
+        edges: [
+          {
+            fromNodeId: "node1",
+            fromPinId: "out",
+            toNodeId: "node2",
+            toPinId: "in",
+          },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it("should detect cycles", () => {
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [createNode("node1", "effect"), createNode("node2", "effect")],
+        edges: [
+          {
+            fromNodeId: "node1",
+            fromPinId: "out",
+            toNodeId: "node2",
+            toPinId: "in",
+          },
+          {
+            fromNodeId: "node2",
+            fromPinId: "out",
+            toNodeId: "node1",
+            toPinId: "in",
+          },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+      expect(result.errors.some((e) => e.type === "cycle")).toBe(true);
+    });
+
+    it("should detect missing source nodes", () => {
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [createNode("node2", "effect")],
+        edges: [
+          {
+            fromNodeId: "node1", // This node doesn't exist
+            fromPinId: "out",
+            toNodeId: "node2",
+            toPinId: "in",
+          },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.type === "invalid-node")).toBe(true);
+    });
+
+    it("should detect missing target nodes", () => {
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [createNode("node1", "source", 0)],
+        edges: [
+          {
+            fromNodeId: "node1",
+            fromPinId: "out",
+            toNodeId: "node2", // This node doesn't exist
+            toPinId: "in",
+          },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.type === "invalid-node")).toBe(true);
+    });
+
+    it("should detect missing output pins", () => {
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [createNode("node1", "source", 0), createNode("node2", "effect")],
+        edges: [
+          {
+            fromNodeId: "node1",
+            fromPinId: "nonexistent", // This pin doesn't exist
+            toNodeId: "node2",
+            toPinId: "in",
+          },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.type === "missing-connection")).toBe(true);
+    });
+
+    it("should detect missing input pins", () => {
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [createNode("node1", "source", 0), createNode("node2", "effect")],
+        edges: [
+          {
+            fromNodeId: "node1",
+            fromPinId: "out",
+            toNodeId: "node2",
+            toPinId: "nonexistent", // This pin doesn't exist
+          },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.type === "missing-connection")).toBe(true);
+    });
+
+    it("should detect type mismatches", () => {
+      const node1 = createNode("node1", "source", 0);
+      const node2 = createNode("node2", "effect");
+
+      // Change output type to Depth
+      node1.outputs.out.type = "Depth";
+      // Input expects Texture
+
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [node1, node2],
+        edges: [
+          {
+            fromNodeId: "node1",
+            fromPinId: "out",
+            toNodeId: "node2",
+            toPinId: "in",
+          },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.type === "type-mismatch")).toBe(true);
+    });
+
+    it("should accept valid empty graph", () => {
+      const graph: MediaProcessingGraph = {
+        id: "empty-graph",
+        nodes: [],
+        edges: [],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it("should handle graph with isolated nodes", () => {
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [
+          createNode("node1", "source", 0),
+          createNode("node2", "effect"),
+          createNode("node3", "source", 0), // Isolated
+        ],
+        edges: [
+          {
+            fromNodeId: "node1",
+            fromPinId: "out",
+            toNodeId: "node2",
+            toPinId: "in",
+          },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      // Graph structure is valid, but node3 has missing connection
+      // This may generate errors for unconnected inputs
+      expect(result).toBeDefined();
+    });
+
+    it("should generate warnings for multipass effects", () => {
+      const node = createNode("node1", "blur", 0);
+      node.requirements.multipass = true;
+
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [node],
+        edges: [],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.warnings).toBeDefined();
+      expect(result.warnings.some((w) => w.type === "performance")).toBe(true);
+    });
+
+    it("should generate warnings for high temporal radius", () => {
+      const node = createNode("node1", "temporal-effect", 0);
+      node.requirements.temporalRadius = 10;
+
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [node],
+        edges: [],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.warnings).toBeDefined();
+      expect(result.warnings.some((w) => w.type === "performance" && w.severity === "high")).toBe(true);
+    });
+
+    it("should generate warnings for stateful effects", () => {
+      const node = createNode("node1", "stateful-effect", 0);
+      node.capabilities.stateful = true;
+
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [node],
+        edges: [],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.warnings).toBeDefined();
+      expect(result.warnings.some((w) => w.type === "compatibility")).toBe(true);
+    });
+
+    it("should handle complex valid graph", () => {
+      const input1 = createNode("input1", "MediaInput", 0);
+      const input2 = createNode("input2", "MediaInput", 0);
+      const effect1 = createNode("effect1", "blur");
+      const effect2 = createNode("effect2", "brightness");
+
+      // Create blend node with 2 inputs
+      const blend: GraphNode = {
+        id: "blend",
+        type: "blend",
+        version: 1,
+        params: {},
+        inputs: {
+          in1: { id: "in1", name: "input1", type: "Texture" },
+          in2: { id: "in2", name: "input2", type: "Texture" },
+        },
+        outputs: {
+          out: { id: "out", name: "output", type: "Texture" },
+        },
+        capabilities: {
+          temporal: false,
+          stateful: false,
+          spatial: true,
+          geometry: false,
+          inputsCount: 2,
+        },
+        requirements: {
+          temporalRadius: 0,
+          preferredPrecision: "fp16",
+          multipass: false,
+          supportsHalfResolution: true,
+        },
+        lifecycle: "Created",
+      };
+
+      const output = createNode("output", "Output");
+
+      const graph: MediaProcessingGraph = {
+        id: "complex-graph",
+        nodes: [input1, input2, effect1, effect2, blend, output],
+        edges: [
+          { fromNodeId: "input1", fromPinId: "out", toNodeId: "effect1", toPinId: "in" },
+          { fromNodeId: "input2", fromPinId: "out", toNodeId: "effect2", toPinId: "in" },
+          { fromNodeId: "effect1", fromPinId: "out", toNodeId: "blend", toPinId: "in1" },
+          { fromNodeId: "effect2", fromPinId: "out", toNodeId: "blend", toPinId: "in2" },
+          { fromNodeId: "blend", fromPinId: "out", toNodeId: "output", toPinId: "in" },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+  });
+
+  describe("error reporting", () => {
+    it("should provide detailed error information", () => {
+      const graph: MediaProcessingGraph = {
+        id: "test-graph",
+        nodes: [createNode("node1", "effect"), createNode("node2", "effect")],
+        edges: [
+          {
+            fromNodeId: "node1",
+            fromPinId: "out",
+            toNodeId: "node2",
+            toPinId: "in",
+          },
+          {
+            fromNodeId: "node2",
+            fromPinId: "out",
+            toNodeId: "node1",
+            toPinId: "in",
+          },
+        ],
+      };
+
+      const validator = new GraphValidator();
+      const result = validator.validate(graph);
+
+      expect(result.errors.length).toBeGreaterThan(0);
+      const error = result.errors[0];
+      expect(error.type).toBeDefined();
+      expect(error.message).toBeDefined();
+      expect(typeof error.message).toBe("string");
+    });
+  });
+});

package/src/graph/builder.ts

@@ -0,0 +1,263 @@
+/**
+ * @clypra/runtime — Graph Builder
+ *
+ * Constructs media processing graphs from effect definitions.
+ * Used by all Labs to build execution graphs.
+ */
+
+import type { GraphNode, GraphEdge, MediaProcessingGraph, EffectCapabilities, EffectRequirements, GraphDataType } from "./types";
+import { GraphHelper } from "./types";
+
+export interface EffectDefinition {
+  id: string;
+  type: string;
+  parameters?: Record<string, any>;
+  inputs?: Array<{
+    id: string;
+    name: string;
+    type: GraphDataType;
+  }>;
+  outputs?: Array<{
+    id: string;
+    name: string;
+    type: GraphDataType;
+  }>;
+  capabilities?: Partial<EffectCapabilities>;
+  requirements?: Partial<EffectRequirements>;
+}
+
+export interface MediaInput {
+  id: string;
+  type: "video" | "image" | "feature-map";
+  source: string;
+}
+
+/**
+ * GraphBuilder - Constructs media processing graphs
+ */
+export class GraphBuilder {
+  private graphId: string;
+  private graph: MediaProcessingGraph;
+
+  constructor(graphId: string = "graph-" + Date.now()) {
+    this.graphId = graphId;
+    this.graph = GraphHelper.create(graphId);
+  }
+
+  /**
+   * Build graph from effect definition and inputs
+   */
+  build(effect: EffectDefinition, inputs: MediaInput[]): MediaProcessingGraph {
+    // Reset graph
+    this.graph = GraphHelper.create(this.graphId);
+
+    // Add input nodes
+    const inputNodes = this.createInputNodes(inputs);
+    for (const node of inputNodes) {
+      this.graph = GraphHelper.withNode(this.graph, node);
+    }
+
+    // Add effect node
+    const effectNode = this.createEffectNode(effect);
+    this.graph = GraphHelper.withNode(this.graph, effectNode);
+
+    // Connect inputs to effect
+    for (let i = 0; i < inputNodes.length; i++) {
+      const inputNode = inputNodes[i];
+      const inputPin = effect.inputs?.[i] || { id: "input", name: "Input", type: "Texture" };
+
+      this.graph = GraphHelper.withEdge(this.graph, inputNode.id, "output", effectNode.id, inputPin.id);
+    }
+
+    // Add output node
+    const outputNode = this.createOutputNode();
+    this.graph = GraphHelper.withNode(this.graph, outputNode);
+
+    // Connect effect to output
+    const outputPin = effect.outputs?.[0] || { id: "output", name: "Output", type: "Texture" };
+    this.graph = GraphHelper.withEdge(this.graph, effectNode.id, outputPin.id, outputNode.id, "input");
+
+    return this.graph;
+  }
+
+  /**
+   * Build graph from multiple effects (composition)
+   */
+  buildComposite(effects: EffectDefinition[], inputs: MediaInput[]): MediaProcessingGraph {
+    this.graph = GraphHelper.create(this.graphId);
+
+    // Add input nodes
+    const inputNodes = this.createInputNodes(inputs);
+    for (const node of inputNodes) {
+      this.graph = GraphHelper.withNode(this.graph, node);
+    }
+
+    // Chain effects
+    let previousNodes = inputNodes;
+    for (const effect of effects) {
+      const effectNode = this.createEffectNode(effect);
+      this.graph = GraphHelper.withNode(this.graph, effectNode);
+
+      // Connect previous nodes to this effect
+      for (let i = 0; i < previousNodes.length && i < (effect.inputs?.length || 1); i++) {
+        const inputPin = effect.inputs?.[i] || { id: "input", name: "Input", type: "Texture" };
+        this.graph = GraphHelper.withEdge(this.graph, previousNodes[i].id, "output", effectNode.id, inputPin.id);
+      }
+
+      previousNodes = [effectNode];
+    }
+
+    // Add output node
+    const outputNode = this.createOutputNode();
+    this.graph = GraphHelper.withNode(this.graph, outputNode);
+
+    // Connect last effect to output
+    if (previousNodes.length > 0) {
+      this.graph = GraphHelper.withEdge(this.graph, previousNodes[0].id, "output", outputNode.id, "input");
+    }
+
+    return this.graph;
+  }
+
+  /**
+   * Get the current graph
+   */
+  getGraph(): MediaProcessingGraph {
+    return this.graph;
+  }
+
+  /**
+   * Create input nodes from media inputs
+   */
+  private createInputNodes(inputs: MediaInput[]): GraphNode[] {
+    return inputs.map((input, index) => ({
+      id: `input-${index}`,
+      type: "MediaInput",
+      version: 0,
+      params: {
+        source: input.source,
+        mediaType: input.type,
+      },
+      inputs: {},
+      outputs: {
+        output: {
+          id: "output",
+          name: "Output",
+          type: "Texture",
+        },
+      },
+      capabilities: {
+        temporal: false,
+        stateful: false,
+        spatial: false,
+        geometry: false,
+        inputsCount: 0,
+      },
+      requirements: {
+        temporalRadius: 0,
+        preferredPrecision: "fp16",
+        multipass: false,
+        supportsHalfResolution: true,
+      },
+      lifecycle: "Created",
+    }));
+  }
+
+  /**
+   * Create effect node from definition
+   */
+  private createEffectNode(effect: EffectDefinition): GraphNode {
+    const inputs: Record<string, any> = {};
+    if (effect.inputs) {
+      for (const input of effect.inputs) {
+        inputs[input.id] = {
+          id: input.id,
+          name: input.name,
+          type: input.type,
+        };
+      }
+    } else {
+      // Default single input
+      inputs.input = {
+        id: "input",
+        name: "Input",
+        type: "Texture",
+      };
+    }
+
+    const outputs: Record<string, any> = {};
+    if (effect.outputs) {
+      for (const output of effect.outputs) {
+        outputs[output.id] = {
+          id: output.id,
+          name: output.name,
+          type: output.type,
+        };
+      }
+    } else {
+      // Default single output
+      outputs.output = {
+        id: "output",
+        name: "Output",
+        type: "Texture",
+      };
+    }
+
+    return {
+      id: effect.id,
+      type: effect.type,
+      version: 0,
+      params: effect.parameters || {},
+      inputs,
+      outputs,
+      capabilities: {
+        temporal: effect.capabilities?.temporal || false,
+        stateful: effect.capabilities?.stateful || false,
+        spatial: effect.capabilities?.spatial || true,
+        geometry: effect.capabilities?.geometry || false,
+        inputsCount: effect.inputs?.length || 1,
+      },
+      requirements: {
+        temporalRadius: effect.requirements?.temporalRadius || 0,
+        preferredPrecision: effect.requirements?.preferredPrecision || "fp16",
+        multipass: effect.requirements?.multipass || false,
+        supportsHalfResolution: effect.requirements?.supportsHalfResolution || true,
+      },
+      lifecycle: "Created",
+    };
+  }
+
+  /**
+   * Create output node
+   */
+  private createOutputNode(): GraphNode {
+    return {
+      id: "output",
+      type: "Output",
+      version: 0,
+      params: {},
+      inputs: {
+        input: {
+          id: "input",
+          name: "Input",
+          type: "Texture",
+        },
+      },
+      outputs: {},
+      capabilities: {
+        temporal: false,
+        stateful: false,
+        spatial: false,
+        geometry: false,
+        inputsCount: 1,
+      },
+      requirements: {
+        temporalRadius: 0,
+        preferredPrecision: "fp16",
+        multipass: false,
+        supportsHalfResolution: true,
+      },
+      lifecycle: "Created",
+    };
+  }
+}

package/src/graph/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Graph Builder - Media Processing Graph Construction
+ *
+ * This module handles the construction of media processing graphs from effect definitions.
+ * It is responsible for:
+ * - Building node trees from effect compositions
+ * - Validating graph structure
+ * - Resolving dependencies
+ * - Capability tracking
+ */
+
+export * from "./types";
+export * from "./builder";
+export * from "./validator";