transactional-ai 0.2.3 → 0.2.4

package/README.md

@@ -7,69 +7,33 @@ Implement the Saga Pattern with persistent rollback and state recovery for Long-
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/Grafikui/Transactional-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/Grafikui/Transactional-ai/actions/workflows/ci.yml)
 
-## Why This Is Called Transactional AI
-
-This library does **not** wrap an LLM and does **not** claim that “AI” is making decisions inside the engine.
-
-The term **Transactional AI** describes the *problem domain*, not the implementation.
-
-Modern AI systems, agents, and LLM-driven workflows introduce the worst possible failure conditions:
-- Long-running, multi-step execution
-- External side effects (payments, emails, file writes, API calls)
-- Retries, timeouts, and partial completion
-- Process crashes and restarts
-- Non-deterministic outputs that cannot simply be re-run
-
-Naive async code is unsafe in this environment.
-
-`transactional-ai` provides a **transactional execution layer** for these AI-adjacent workflows:
-- Deterministic step execution
-- Durable state persistence
-- Automatic compensation (rollback)
-- Safe retries and resumability after failure
-
-In short:
-> **AI is the workload. Transactional guarantees are the missing infrastructure.**
-
-That is what this library provides.
-
-
 **[Live Demo](https://grafikui.github.io/Transactional-ai/)** | [Documentation](#quick-start) | [Examples](#advanced-usage)
 
-## Why This Is Called Transactional AI
-
-This library does **not** wrap an LLM and does **not** claim that “AI” is making decisions inside the engine.
-
-The term **Transactional AI** describes the *problem domain*, not the implementation.
-
-Modern AI systems, agents, and LLM-driven workflows introduce the worst possible failure conditions:
-- Long-running, multi-step execution
-- External side effects (payments, emails, file writes, API calls)
-- Retries, timeouts, and partial completion
-- Process crashes and restarts
-- Non-deterministic outputs that cannot simply be re-run
-
-Naive async code is unsafe in this environment.
+---
 
-`transactional-ai` provides a **transactional execution layer** for these AI-adjacent workflows:
-- Deterministic step execution
-- Durable state persistence
-- Automatic compensation (rollback)
-- Safe retries and resumability after failure
+## 🧠 Why "Transactional AI"?
 
-In short:
-> **AI is the workload. Transactional guarantees are the missing infrastructure.**
+> **Clarification:** This library does **not** wrap an LLM. It does **not** claim that "AI" is making decisions inside the engine.
 
-That is what this library provides.
+The term *Transactional AI* describes the **problem domain**, not the implementation.
 
+Modern AI systems, agents, and LLM-driven workflows introduce the worst possible failure conditions:
+* **Long-running execution:** Processes that take minutes, not milliseconds.
+* **External side effects:** Payments, emails, file writes, API calls.
+* **Instability:** Retries, timeouts, partial completions, and hallucinations.
+* **Non-determinism:** Outputs that cannot simply be re-run blindly.
 
-This does three critical things:
+**Naive async code is unsafe in this environment.**
 
-Explicitly says what it is not
+`transactional-ai` provides the **transactional execution layer** for these workflows:
+* ✅ **Deterministic** step execution
+* ✅ **Durable** state persistence
+* ✅ **Automatic** compensation (rollback)
+* ✅ **Safe** retries and resumability after failure
 
-Reframes “AI” as the risk surface
+**In short:** AI is the workload. Transactional guarantees are the missing infrastructure.
 
-Justifies the name without defensiveness
+---
 
 ## Interactive Demo
 
@@ -95,17 +59,17 @@ npm run demo
 npm run showcase -- --all
 ```
 
----
-
 ## Why use this?
 
-AI Agents are flaky. Steps fail, APIs time out, and hallucinations happen.
-`transactional-ai` gives you:
+AI Agents are flaky. Steps fail, APIs time out, and hallucinations happen. transactional-ai gives you:
+
+- Automatic Rollbacks: If step 3 fails, steps 2 and 1 are compensated (undone) automatically.
+
+- Concurrency Safety: Distributed locking prevents race conditions when scaling workers.
 
-1.  **Automatic Rollbacks**: If step 3 fails, steps 2 and 1 are compensated (undone) automatically.
-2.  **Concurrency Safety**: Distributed locking prevents race conditions when scaling workers.
-3.  **Persistence**: Transactions survive process crashes using Redis, Postgres, or File storage.
-4.  **Resilience**: Built-in retry policies for flaky LLM APIs.
+- Persistence: Transactions survive process crashes using Redis, Postgres, or File storage.
+
+- Resilience: Built-in retry policies for flaky LLM APIs.
 
 ## Installation
 
@@ -113,11 +77,9 @@ AI Agents are flaky. Steps fail, APIs time out, and hallucinations happen.
 npm install transactional-ai
 ```
 
----
-
 ## Quick Start
 
-### 1. The "Litmus Test" (Basic Usage)
+1. The "Litmus Test" (Basic Usage)
 
 Define a transaction where every action has a compensating rollback action.
 
@@ -155,7 +117,7 @@ agent
 await agent.run({ initialData: "foo" });
 ```
 
-### Adding Persistence (Redis)
+## Adding Persistence (Redis)
 
 To survive process crashes, simply provide a storage adapter.
 
@@ -180,11 +142,11 @@ await agent.run();
 
 ## Enterprise Features (v0.2.0)
 
-### 1. Distributed Locking (Redis)
+### Distributed Locking (Redis)
 
 Prevent race conditions when running multiple agent workers on the same Transaction ID.
 
-```typeScript
+```typescript
 import { Transaction, RedisStorage, RedisLock } from 'transactional-ai';
 
 const connection = 'redis://localhost:6379';
@@ -200,30 +162,29 @@ const agent = new Transaction('tx-unique-id', storage, {
 await agent.run();
 ```
 
-### 2. Postgres Storage (SQL)
+### Postgres Storage (SQL)
 
 Use Postgres for strict ACID compliance and auditability.
 
 Prerequisite: Run schema.sql in your database.
 
-```typeScript
+```typescript
 import { Transaction, PostgresStorage } from 'transactional-ai';
 
 const storage = new PostgresStorage('postgresql://user:pass@localhost:5432/mydb');
 const agent = new Transaction('tx-id', storage);
 ```
 
-#### Setting Up Postgres
-
+## Setting Up Postgres
 Before using PostgresStorage, create the required table in your database:
 
-**Option 1: Run the provided schema**
-```bash
+Option 1: Run the provided schema
+``` bash
 # From project root
 psql -U your_user -d your_database -f schema.sql
 ```
 
-**Option 2: Copy-paste this SQL**
+## Option 2: Copy-paste this SQL
 ```sql
 CREATE TABLE IF NOT EXISTS transactions (
   id VARCHAR(255) PRIMARY KEY,
@@ -236,13 +197,13 @@ CREATE TABLE IF NOT EXISTS transactions (
 CREATE INDEX IF NOT EXISTS idx_transactions_status ON transactions(status);
 ```
 
-**Important:** The table must exist before running your first transaction. It will NOT be auto-created.
+* **Important**: The table must exist before running your first transaction. It will NOT be auto-created.
 
-### 3. Retry Policies
+### Retry Policies
 
 Handle flaky APIs (e.g., OpenAI 500 errors) automatically without failing the transaction.
 
-```typeScript
+```typescript
 agent.step({
   name: 'generate-text',
   execute: async () => await openai.createCompletion(...),
@@ -254,7 +215,7 @@ agent.step({
 });
 ```
 
-### 4. Step Timeouts (NEW in v0.2.1)
+### 4. Step Timeouts
 
 Prevent steps from hanging indefinitely with configurable timeouts.
 
@@ -266,10 +227,8 @@ await tx.step('call-external-api', {
 });
 ```
 
-### 5. Observability Hooks (NEW in v0.2.1)
-
+### Observability Hooks
 Integrate with your logging, metrics, and alerting systems using event hooks.
-
 ```typescript
 import { Transaction, TransactionEvents } from 'transactional-ai';
 
@@ -290,14 +249,25 @@ const events: TransactionEvents = {
 const tx = new Transaction('workflow-123', storage, { events });
 ```
 
-**Available events:**
-- `onTransactionStart`, `onTransactionComplete`, `onTransactionFailed`
-- `onStepStart`, `onStepComplete`, `onStepFailed`, `onStepRetry`, `onStepSkipped`, `onStepTimeout`
-- `onCompensationStart`, `onCompensationComplete`, `onCompensationFailed`
+## Available Events
 
-**See full example:** `npm run example:observability`
+| Event Name                  | Description                                      |
+|------------------------------|------------------------------------------------|
+| onTransactionStart           | Triggered when a transaction begins           |
+| onTransactionComplete        | Triggered when a transaction completes        |
+| onTransactionFailed          | Triggered when a transaction fails            |
+| onStepStart                  | Triggered when an individual step starts      |
+| onStepComplete               | Triggered when an individual step completes   |
+| onStepFailed                 | Triggered when an individual step fails       |
+| onStepRetry                  | Triggered when a step is retried              |
+| onStepSkipped                | Triggered when a step is skipped              |
+| onStepTimeout                | Triggered when a step exceeds its timeout    |
+| onCompensationStart          | Triggered when compensation (rollback) begins |
+| onCompensationComplete       | Triggered when compensation completes         |
+| onCompensationFailed         | Triggered when compensation fails             |
 
----
+
+**See full example:** `npm run example:observability`
 
 ## CLI Inspector
 
@@ -314,7 +284,7 @@ npx tai-inspect workflow-id-555
 
 Output:
 
-```
+```bash 
 🔍 Inspecting: workflow-id-555
      Source: RedisStorage
 
@@ -326,11 +296,9 @@ Output:
      └── (comp) create-f..| ✅ completed
 ```
 
----
-
 ## Advanced Usage
 
-### Audit Mode (Governance)
+**Audit Mode (Governance)**
 
 By default, logs are cleared upon success to save storage space. To keep a permanent audit trail for compliance (e.g., "Why did the agent do this?"), enable Audit Mode:
 
@@ -340,7 +308,7 @@ const agent = new Transaction("id", storage, {
 });
 ```
 
-### Manual Rollbacks
+## Manual Rollbacks
 
 The library handles rollbacks automatically on error. You can trigger them manually by throwing an error inside any step:
 
@@ -362,7 +330,7 @@ agent.step({
 });
 ```
 
-### Testing Utilities (NEW in v0.2.1)
+## Testing Utilities
 
 Write fast, isolated tests for your transaction workflows with built-in testing utilities.
 
@@ -400,37 +368,36 @@ describe('My Workflow', () => {
 });
 ```
 
-**Testing utilities:**
-- `MemoryStorage` - Fast in-memory storage for tests
-- `MockLock` - Simulated distributed lock
-- `createEventSpy()` - Track event emissions
+## Testing utilities:
 
----
+- MemoryStorage - Fast in-memory storage for tests
 
-## Roadmap
+- MockLock - Simulated distributed lock
 
-[x] Core Saga Engine (Execute/Compensate)
+- createEventSpy() - Track event emissions
 
-[x] Persistence Adapters (File, Redis)
+## Roadmap
 
-[x] Resumability (Skip completed steps)
+- [x] Core Saga Engine (Execute/Compensate)
 
-[x] CLI Inspector (tai-inspect)
+- [x] Persistence Adapters (File, Redis)
 
-[x] Concurrent Transaction Locking
+- [x] Resumability (Skip completed steps)
 
-[x] Postgres/SQL Storage Adapter
+- [x] CLI Inspector (tai-inspect)
 
-[x] Step Retry Policies
+- [x] Concurrent Transaction Locking
 
-[x] Step Timeouts (v0.2.1)
+- [x] Postgres/SQL Storage Adapter
 
-[x] Observability Event Hooks (v0.2.1)
+- [x] Step Retry Policies
 
-[x] Testing Utilities (v0.2.1)
+- [x] Step Timeouts (v0.2.1)
 
----
+- [x] Observability Event Hooks (v0.2.1)
+
+- [x] Testing Utilities (v0.2.1)
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transactional-ai",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "A reliability protocol for AI Agents. Saga pattern with persistent rollback.",
   "main": "dist/index.js",
   "bin": {