@cadenza.io/core 3.8.0 → 3.9.1

package/README.md

@@ -7,12 +7,12 @@ Cadenza is an innovative framework that extends traditional orchestration with e
 The core package (@Cadenza.io/core) includes the foundational primitives for defining and executing graphs of tasks, managing contexts, handling signals, and bootstrapping executions. It's designed to be language-agnostic in model, with this TypeScript implementation serving as the reference.
 
 Cadenza's design philosophy emphasizes:
-- **Structured Freedom**: Explicit graphs for dependencies (orchestration) combined with signals for loose coupling (choreography).
-- **Meta-Layer Extension**: A self-reflective layer for monitoring, optimization, and auto-generation, enabling AI-driven self-development. Essentially extending the core, using the core.
+- **Decentralized Adaptive Orchestration (DAO)**: Explicit graphs for dependencies (orchestration) combined with signals for loose coupling (choreography). This combination allows for flexible and dynamic workflows, while still maintaining the benefits of traditional orchestration.
+- **Meta-Layer Extension**: A self-reflective layer for monitoring, optimization, and auto-generation, enabling AI-driven self-development. Essentially used for extending the core features by using the core features.
 - **Introspectability**: Exportable graphs, traceable executions, and metadata separation for transparency and debugging.
-- **Modularity**: Lightweight core with extensions (e.g., distribution, UI integration) as separate packages.
+- **Modularity**: Lightweight core with extensions (e.g., distribution, UI integration) as separate packages using the meta layer.
 
-The core is suitable for local dynamic workflows using tasks and signals. But thanks to the meta layer, it also serves as the foundation for the distributed, agentic AI applications, and more, abstracting complexities like networking and security in extensions.
+The core is suitable for local dynamic workflows using tasks and signals. But thanks to the meta layer, it also serves as the foundation for distributed applications, and more, abstracting complexities like networking and security in extensions.
 
 ## Installation
 
@@ -25,88 +25,125 @@ npm install @cadenza.io/core
 ## Usage
 
 ### Creating Tasks
-Tasks are the atomic units of work in Cadenza. They can be chained to form graphs.
+Tasks are the atomic units of work in Cadenza. They can be chained to form complex graphs.
 
 ```typescript
 import Cadenza from '@cadenza.io/core';
 
-const task1 = Cadenza.createTask('task1', (context) => {
-  console.log(context.foo);
-  return { bar: 'baz' };
-}, 'First task');
+// Create functions for tasks
+function validateContext(context) {
+  if (!context.foo) {
+    throw new Error('Missing foo');
+  }
+  return true;
+}
+
+function processContext(context) {
+  return { bar: context.foo + '-bar' };
+}
 
-const task2 = Cadenza.createTask('task2', (context) => {
-  return {...context, qux: 'quux'};
-}, 'Second task');
+function logContext(context) {
+  console.log(context);
+}
+
+// Wrap functions into tasks
+const validateTask = Cadenza.createTask(
+  'Validate context',
+  validateContext
+);
 
-const task3 = Cadenza.createTask('task3', (context) => {
-  return {...context, cadenza: 'is awesome'};
-}, 'Third task');
+const processTask = Cadenza.createTask(
+  'Process context',
+  processContext,
+);
 
-task1.then(
-  task2.then(
-    task3
-  ),
+const logTask = Cadenza.createTask(
+  'Log context',
+  logContext,
 );
 
+// Chain tasks together
+validateTask.then(processTask).then(logTask);
+
+// Equivalent to:
+const validated = validateContext(context);
+if (validated) {
+  const validatedContext = context;
+  const processedContext = processContext(validatedContext);
+  logContext(processedContext);
+}
 ```
 
 ### Creating Routines
 Routines are named entry points to graphs.
 
 ```typescript
-const routine = Cadenza.createRoutine('myRoutine', [task1], 'Test routine');
+const processContextRoutine = Cadenza.createRoutine(
+  'Process context', 
+  [validateTask], 
+  'Processes a context by first validating it, processing the string and logging it.',
+);
 ```
 
 ### Running Graphs
 Use a Runner to execute routines or tasks.
 
 ```typescript
-const runner = Cadenza.runner;
-await runner.run(routine, {foo: 'bar'});
+Cadenza.run(processContextRoutine);
 ```
 
 ### Signals
-Signals provide event-driven coordination.
+Signals provide event-driven coordination. The signal syntax is `domain.event`.
 
 ```typescript
-task1.emits('my.signal');
-task2.doOn('my.other.signal');
-
-Cadenza.broker.emit('my.other.signal', {foo: 'bar'}); // This will trigger task2
+processContextRoutine.doOn('main.recived_context'); // Subscribe to a signal
+processTask.doOn('main.context_updated'); // Works on tasks and routines
+logTask.emits('process.done'); // Emits after successfull task execution
+
+Cadenza.emit('main.recived_context', {foo: 'foo'}); // Emit from anywhere with a context
+Cadenza.emit('main.context_updated', {foo: 'foo-bar'}); // This will trigger the processTask and subsequently logTask. Essentially, skipping the validationTask.
+
+// Emit a signal from within a task
+Candenza.createTask('Update context', (ctx, emit) => {
+  if (ctx.bar === 'foo-bar') {
+    ctx.foo = 'foo-baz';
+    emit('main.context_updated', ctx); 
+  }
+});
 ```
 
 ### Using the Meta Layer
 
-The meta layer serves as a tool for extending the core features. It follows the same rules and primitives as the user layer but runs on a separate meta runner. It consists of MetaTasks, MetaRoutines and meta signals. To trigger a meta flow you need to emit a meta signal (meta.[domain].[action]).
+The meta layer serves as a tool for extending the core features. It follows the same rules and primitives as the user layer but runs on a separate meta runner. It consists of MetaTasks, MetaRoutines and meta signals. To trigger a meta flow you need to emit a meta signal (meta.domain.event).
 
 ```typescript
 Cadenza.createTask('My task', (ctx) => {
   console.log(ctx.foo);
   return ctx;
-}).emits('meta.some.signal'); // Emits a on task execution
+}).emits('meta.some.event');
 
 Cadenza.createMetaTask('My meta task', (ctx) => {
   console.log(ctx.__task.name);
   return true;
-}).doOn('meta.some.signal');
+})
+  .doOn('meta.some.event')
+  .emits('meta.some.other_event');
 
-Cadenza.broker.emit('meta.some.signal', {foo: 'bar'}); // Trigger from anywhere
+Cadenza.emit('meta.some.event', {foo: 'bar'}); // Emit from anywhere
 ```
 
-For full examples, see the [docs folder](docs/examples.md) or the test suite.
+For full examples, see the cadenza-service package (https://github.com/cadenzaio/cadenza-service) or the test suite.
 
 ## Features
-- **Graph-Based Orchestration**: Define tasks and routines with chaining for dependencies, failovers, and layering.
-- **Event-Driven Choreography**: Signals for loose coupling, with meta-signals for self-management.
+- **Graph-Based Orchestration**: Define tasks and routines with chaining for dependencies and layering.
+- **Event-Driven Choreography**: Signals for loose coupling with meta-signals for self-management.
 - **Context Management**: Immutable contexts with metadata separation and schema validation.
-- **Execution Engine**: Sync/async strategies, throttling, debouncing, and unique merging.
-- **Bootstrapping**: Lazy initialization with seed tasks for registry and signal handling.
+- **Execution Engine**: Sync/async strategies, throttling, debouncing, fan-in/fan-out merging, dynamic task creation/chaining/deletion.
 
 ## Architecture Overview
 Cadenza's core is divided into:
 - **Definition Layer**: Task, Routine for static graphs.
-- **Execution Layer**: Node, Layer, Builder, Run for runtime.
+- **Execution Layer**: Node, Layer, Builder, Runner for runtime.
 - **Signal Layer**: SignalBroker, SignalParticipant for coordination.
 - **Context Layer**: GraphContext for data flow.
 - **Registry Layer**: GraphRegistry for introspection.

package/dist/index.d.mts

@@ -441,11 +441,15 @@ declare class Task extends SignalEmitter implements Graph {
      * @param context - The GraphContext to validate and execute.
      * @param emit
      * @param progressCallback - Callback for progress updates.
+     * @param nodeData
      * @returns TaskResult from the taskFunction or error object on validation failure.
      * @edge If validateInputContext is true, validates context; on failure, emits 'meta.task.validationFailed' with detailed errors.
      * @edge If validateOutputContext is true, validates output; on failure, emits 'meta.task.outputValidationFailed' with detailed errors.
      */
-    execute(context: GraphContext, emit: (signal: string, context: AnyObject) => void, progressCallback: (progress: number) => void): TaskResult;
+    execute(context: GraphContext, emit: (signal: string, context: AnyObject) => void, progressCallback: (progress: number) => void, nodeData: {
+        nodeId: string;
+        routineExecId: string;
+    }): TaskResult;
     doAfter(...tasks: Task[]): this;
     then(...tasks: Task[]): this;
     decouple(task: Task): void;
@@ -779,7 +783,10 @@ declare class EphemeralTask extends Task {
     readonly condition: (context: any) => boolean;
     readonly isEphemeral: boolean;
     constructor(name: string, task: TaskFunction, description?: string, once?: boolean, condition?: (context: any) => boolean, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, isSubMeta?: boolean, isHidden?: boolean, getTagCallback?: ThrottleTagGetter | undefined, inputSchema?: SchemaDefinition | undefined, validateInputContext?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputContext?: boolean, retryCount?: number, retryDelay?: number, retryDelayMax?: number, retryDelayFactor?: number);
-    execute(context: any, emit: (signal: string, context: AnyObject) => void, progressCallback: (progress: number) => void): TaskResult;
+    execute(context: any, emit: (signal: string, context: AnyObject) => void, progressCallback: (progress: number) => void, nodeData: {
+        nodeId: string;
+        routineExecId: string;
+    }): TaskResult;
 }
 
 declare class GraphAsyncRun extends GraphRunStrategy {
@@ -832,8 +839,8 @@ declare class Cadenza {
      * @throws Error if invalid.
      */
     static validateName(name: string): void;
-    static runTask(task: Task, context: AnyObject): void;
-    static runRoutine(routine: GraphRoutine, context: AnyObject): void;
+    static run(task: Task | GraphRoutine, context: AnyObject): void;
+    static emit(event: string, data?: AnyObject): void;
     /**
      * Creates a standard Task and registers it in the GraphRegistry.
      * @param name Unique identifier for the task.

package/dist/index.d.ts

@@ -441,11 +441,15 @@ declare class Task extends SignalEmitter implements Graph {
      * @param context - The GraphContext to validate and execute.
      * @param emit
      * @param progressCallback - Callback for progress updates.
+     * @param nodeData
      * @returns TaskResult from the taskFunction or error object on validation failure.
      * @edge If validateInputContext is true, validates context; on failure, emits 'meta.task.validationFailed' with detailed errors.
      * @edge If validateOutputContext is true, validates output; on failure, emits 'meta.task.outputValidationFailed' with detailed errors.
      */
-    execute(context: GraphContext, emit: (signal: string, context: AnyObject) => void, progressCallback: (progress: number) => void): TaskResult;
+    execute(context: GraphContext, emit: (signal: string, context: AnyObject) => void, progressCallback: (progress: number) => void, nodeData: {
+        nodeId: string;
+        routineExecId: string;
+    }): TaskResult;
     doAfter(...tasks: Task[]): this;
     then(...tasks: Task[]): this;
     decouple(task: Task): void;
@@ -779,7 +783,10 @@ declare class EphemeralTask extends Task {
     readonly condition: (context: any) => boolean;
     readonly isEphemeral: boolean;
     constructor(name: string, task: TaskFunction, description?: string, once?: boolean, condition?: (context: any) => boolean, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, isSubMeta?: boolean, isHidden?: boolean, getTagCallback?: ThrottleTagGetter | undefined, inputSchema?: SchemaDefinition | undefined, validateInputContext?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputContext?: boolean, retryCount?: number, retryDelay?: number, retryDelayMax?: number, retryDelayFactor?: number);
-    execute(context: any, emit: (signal: string, context: AnyObject) => void, progressCallback: (progress: number) => void): TaskResult;
+    execute(context: any, emit: (signal: string, context: AnyObject) => void, progressCallback: (progress: number) => void, nodeData: {
+        nodeId: string;
+        routineExecId: string;
+    }): TaskResult;
 }
 
 declare class GraphAsyncRun extends GraphRunStrategy {
@@ -832,8 +839,8 @@ declare class Cadenza {
      * @throws Error if invalid.
      */
     static validateName(name: string): void;
-    static runTask(task: Task, context: AnyObject): void;
-    static runRoutine(routine: GraphRoutine, context: AnyObject): void;
+    static run(task: Task | GraphRoutine, context: AnyObject): void;
+    static emit(event: string, data?: AnyObject): void;
     /**
      * Creates a standard Task and registers it in the GraphRegistry.
      * @param name Unique identifier for the task.

package/dist/index.js

@@ -256,10 +256,25 @@ var SignalBroker = class _SignalBroker {
   }
   executeListener(signal, context) {
     const obs = this.signalObservers.get(signal);
+    if (!obs || obs.tasks.size === 0) {
+      return false;
+    }
     const isMeta = signal.startsWith("meta");
-    const runner = isMeta ? this.metaRunner : this.runner;
-    if (obs && obs.tasks.size && runner) {
-      obs.fn(runner, Array.from(obs.tasks), context);
+    if (!isMeta) {
+      const tasks = [];
+      const metaTasks = [];
+      obs.tasks.forEach(
+        (task) => task.isMeta ? metaTasks.push(task) : tasks.push(task)
+      );
+      if (tasks.length && this.runner) {
+        obs.fn(this.runner, tasks, context);
+      }
+      if (metaTasks.length && this.metaRunner) {
+        obs.fn(this.metaRunner, metaTasks, context);
+      }
+      return true;
+    } else if (this.metaRunner) {
+      obs.fn(this.metaRunner, Array.from(obs.tasks), context);
       return true;
     }
     return false;
@@ -838,6 +853,23 @@ var GraphNode = class _GraphNode extends SignalEmitter {
           }
         });
       });
+      if (context.__previousTaskExecutionId) {
+        this.emitMetricsWithMetadata(
+          "meta.node.detected_previous_task_execution",
+          {
+            data: {
+              taskExecutionId: this.id,
+              previousTaskExecutionId: context.__previousTaskExecutionId
+            },
+            filter: {
+              taskName: this.task.name,
+              taskVersion: this.task.version
+            },
+            ...context
+          }
+        );
+        context.__previousTaskExecutionId = null;
+      }
       if (context.__signalEmission?.consumed === false && (!this.isMeta() || this.debug)) {
         this.emitMetricsWithMetadata("meta.node.consumed_signal", {
           data: {
@@ -983,7 +1015,8 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       const result = this.task.execute(
         this.context,
         this.emitWithMetadata.bind(this),
-        this.onProgress.bind(this)
+        this.onProgress.bind(this),
+        { nodeId: this.id, routineExecId: this.routineExecId }
       );
       if (result?.errored || result?.failed) {
         return this.retry(result);
@@ -1839,11 +1872,12 @@ var Task = class extends SignalEmitter {
    * @param context - The GraphContext to validate and execute.
    * @param emit
    * @param progressCallback - Callback for progress updates.
+   * @param nodeData
    * @returns TaskResult from the taskFunction or error object on validation failure.
    * @edge If validateInputContext is true, validates context; on failure, emits 'meta.task.validationFailed' with detailed errors.
    * @edge If validateOutputContext is true, validates output; on failure, emits 'meta.task.outputValidationFailed' with detailed errors.
    */
-  execute(context, emit, progressCallback) {
+  execute(context, emit, progressCallback, nodeData) {
     return this.taskFunction(
       this.isMeta ? context.getClonedFullContext() : context.getClonedContext(),
       emit,
@@ -2661,8 +2695,8 @@ var EphemeralTask = class extends Task {
     this.once = once;
     this.condition = condition;
   }
-  execute(context, emit, progressCallback) {
-    const result = super.execute(context, emit, progressCallback);
+  execute(context, emit, progressCallback, nodeData) {
+    const result = super.execute(context, emit, progressCallback, nodeData);
     if (this.once || this.condition(result)) {
       this.destroy();
     }
@@ -3240,11 +3274,11 @@ var Cadenza = class {
       throw new Error("Task or Routine name must be a non-empty string.");
     }
   }
-  static runTask(task, context) {
-    this.runner.run(task, context);
+  static run(task, context) {
+    this.runner?.run(task, context);
   }
-  static runRoutine(routine, context) {
-    this.runner.run(routine, context);
+  static emit(event, data = {}) {
+    this.broker?.emit(event, data);
   }
   /**
    * Creates a standard Task and registers it in the GraphRegistry.