@cadenza.io/core 3.9.0 → 3.9.2

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

@@ -839,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

@@ -839,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

@@ -853,7 +853,7 @@ var GraphNode = class _GraphNode extends SignalEmitter {
           }
         });
       });
-      if (context.__previousTaskExecutionId) {
+      if (!this.silent && context.__previousTaskExecutionId) {
         this.emitMetricsWithMetadata(
           "meta.node.detected_previous_task_execution",
           {
@@ -3274,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.