@cadenza.io/service 1.22.0 → 1.23.0

package/README.md

@@ -2,21 +2,28 @@
 
 ## Overview
 
-Cadenza is an innovative framework that extends traditional orchestration with event-driven choreography, providing "structured freedom" for building distributed, self-evolving systems. 
+Cadenza is an innovative framework that extends traditional orchestration with event-driven choreography, providing "structured freedom" for building distributed, self-evolving systems.
 
 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.
+This repository (@Cadenza.io/service) is an extension of the core package, providing the infrastructure for making the Cadenza model truly distributed. It makes use of the core meta-layer extension, and provides a set of tools for building distributed applications, abstracting complexities like networking and security.
+
+The service package provides everything in the core package plus the following:
+- **Service Extension**: A Service exposes the local graphs and signals to other Services in the system and enables them to interact with tasks and signals across other Services in the system via socket and/or REST.
+- **Database Service Extension**: A Database Service takes a schema and auto generates the necessary tasks and signals to interact with that database using the cadenza model. It exposes those tasks using by creating a Service.
+- **CadenzaDB compatibility**: A service can connect to the official CadenzaDB service and will automatically sync realtime data for introspection and visualization.
+
+There is no need to install the core package separately. Instead, install the service package, which includes everything in the core package plus the distributed extensions.
 
 ## Installation
 
-Install the core package via npm:
+Install the service package via npm:
 
 ```bash
 npm install @cadenza.io/service
@@ -24,93 +31,36 @@ npm install @cadenza.io/service
 
 ## Usage
 
-### Creating Tasks
-Tasks are the atomic units of work in Cadenza. They can be chained to form graphs.
+### Creating a service
+Creating a Service will create a REST server and a socket server. It will sync with the CadenzaDB service if available.
 
 ```typescript
 import Cadenza from '@cadenza.io/service';
 
-const task1 = Cadenza.createTask('task1', (context) => {
-  console.log(context.foo);
-  return { bar: 'baz' };
-}, 'First task');
-
-const task2 = Cadenza.createTask('task2', (context) => {
-  return {...context, qux: 'quux'};
-}, 'Second task');
-
-const task3 = Cadenza.createTask('task3', (context) => {
-  return {...context, cadenza: 'is awesome'};
-}, 'Third task');
-
-task1.then(
-  task2.then(
-    task3
-  ),
-);
-
-```
-
-### Creating Routines
-Routines are named entry points to graphs.
-
-```typescript
-const routine = Cadenza.createRoutine('myRoutine', [task1], 'Test routine');
-```
-
-### Running Graphs
-Use a Runner to execute routines or tasks.
-
-```typescript
-const runner = Cadenza.runner;
-await runner.run(routine, {foo: 'bar'});
+Cadenza.createCadenzaService('MyService'); // Name should start with an uppercase letter and contain no spaces.
 ```
 
-### Signals
-Signals provide event-driven coordination.
+### Working with distribution
+Distribution is easy with Cadenza. You can delegate the flow by using a DeputyTask, or subscribe to foreign signals by prefixing them with the service name.
 
 ```typescript
-task1.emits('my.signal');
-task2.doOn('my.other.signal');
+// Creates a proxy Task for the specified task or routine on the specified service. 
+// The local flow will await the result of the remote flow.
+Cadenza.createDeputyTask('Process context', 'ContextService');
 
-Cadenza.broker.emit('my.other.signal', {foo: 'bar'}); // This will trigger task2
+// This will subscribe to the signal on the remote service.
+localTask.doOn('ContextService.process.failed');
 ```
 
-### 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]).
 
-```typescript
-Cadenza.createTask('My task', (ctx) => {
-  console.log(ctx.foo);
-  return ctx;
-}).emits('meta.some.signal'); // Emits a on task execution
-
-Cadenza.createMetaTask('My meta task', (ctx) => {
-  console.log(ctx.__task.name);
-  return true;
-}).doOn('meta.some.signal');
+For full examples, see this repository or the test suite.
 
-Cadenza.broker.emit('meta.some.signal', {foo: 'bar'}); // Trigger from anywhere
-```
-
-For full examples, see the [docs folder](docs/examples.md) 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.
-- **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.
 
 ## Architecture Overview
-Cadenza's core is divided into:
-- **Definition Layer**: Task, Routine for static graphs.
-- **Execution Layer**: Node, Layer, Builder, Run for runtime.
-- **Signal Layer**: SignalBroker, SignalParticipant for coordination.
-- **Context Layer**: GraphContext for data flow.
-- **Registry Layer**: GraphRegistry for introspection.
-- **Factory**: Cadenza for creation and bootstrap.
+Cadenza's service package is divided into:
+
 
 ## Contributing
 Contributions are welcome! Please fork the repo, create a branch, and submit a PR. Follow the code style and add tests for new features.