@ai.ntellect/core 1.0.0 → 1.1.0

package/README.md

@@ -1,193 +1,462 @@
-# @ai.ntellect/workflow
+# @ai.ntellect/core
 
-The **@ai.ntellect/workflow** package is a robust framework for managing and executing workflows, supporting dynamic decision-making, conditional paths, event-driven execution, and state persistence.
+**Stop your AI agents from going off-rails in production.**
 
-## Features
+*LLMs generate. You control.*
 
-- **Dynamic Workflow Execution:** Manage workflows with complex branching and parallel paths.
-- **Conditional Logic:** Execute nodes based on real-time conditions.
-- **Event-Driven Execution:** Trigger actions dynamically using events.
-- **State Management:** Handle shared and persistent states.
-- **Visualization:** Generate workflow diagrams using Mermaid syntax.
+One LLM call $\rightarrow$ deterministic execution $\rightarrow$ no routing hallucinations.
 
-## Installation
+---
+
+## Why
+
+LLMs are great at generating text.  
+**They are bad at controlling systems.**
+
+Most frameworks let the LLM decide everything:
+- which tool to call
+- in what order
+- with what context
+
+$\rightarrow$ This breaks as complexity grows.
+
+**This framework does the opposite:**
+- LLM decides **intent (once)**
+- Your system handles **execution (deterministically)**
+
+No drift. No hidden loops. No surprises.
+
+**This is not an agent framework. It's a control layer for LLM systems.**
+
+---
+
+### The Contrast
+
+**Most frameworks:**
+`User` $\rightarrow$ `LLM` $\rightarrow$ `LLM` $\rightarrow$ `LLM` $\rightarrow$ `Tool` $\rightarrow$ `LLM` (Probabilistic Chaos)
+
+**This framework:**
+`User` $\rightarrow$ `LLM` $\rightarrow$ `System` $\rightarrow$ `Done` (Deterministic Control)
+
+---
+
+## Why this works
 
-Install the package via npm:
+We replaced probabilistic guessing with explicit definitions. Routing is **defined**, not **learned**.
+
+- **No prompt drift**: Your agent won't change its behavior because of a minor prompt tweak.
+- **No hidden loops**: Execution paths are explicit and finite.
+- **No probabilistic branching**: If the intent is X, the path is ALWAYS Y.
+
+Just state + transitions.
+
+---
+
+## Quick Reference
 
-```bash
-npm install @ai.ntellect/workflow
 ```
+User → LLM (intent) → Petri Net (routing) → GraphFlow (execution)
+```
+
+One decision. Then control.
 
-Import the `Workflow` class:
+---
 
-```javascript
-import { Workflow } from "@ai.ntellect/workflow";
+## Installation
+
+```sh
+pnpm add @ai.ntellect/core zod
 ```
 
-## Creating a content pipeline workflow
+**Requirements**: TypeScript 5.x+, Node.js 18+.
 
-Here is an example of creating a workflow to manage a content pipeline:
+---
 
-```javascript
-import { Workflow } from "@ai.ntellect/workflow";
+## Table of Contents
 
-const contentPipelineDefinition = {
-  name: "ContentPipeline",
-  entryNode: "fetchContent",
-  nodes: {
-    fetchContent: {
-      name: "fetchContent",
-      description: "Fetch content from external APIs",
-      execute: async (state) => {
-        console.log("Fetching content...");
-        state.content = ["Article1", "Article2"];
-        return state;
-      },
-      next: ["processContent"],
-    },
-    processContent: {
-      name: "processContent",
-      description: "Process and analyze content",
-      execute: async (state) => {
-        console.log("Processing content:", state.content);
-        state.processedContent = state.content.map((c) => c.toUpperCase());
-        return state;
-      },
-      next: ["publishContent"],
+- [Core Thesis](#core-thesis)
+- [Source Structure](#source-structure)
+- [GraphFlow — Typed Execution](#graphflow--typed-execution)
+- [CortexFlow — Intent Routing](#cortexflow--intent-routing)
+- [Agent — Cognitive Loop](#agent--cognitive-loop)
+- [AgentPipeline — Declarative Pipelines](#agentpipeline--declarative-pipelines)
+- [Persistence — Memory & Checkpoints](#persistence--memory--checkpoints)
+- [Planner & Compiler](#planner--compiler)
+- [CLI (Interactive REPL)](#cli-interactive-repl)
+- [Testing & Build](#testing--build)
+
+---
+
+## Core Thesis
+
+The framework architecture is the **Classifier-Controller Split**:
+
+| Layer | Role | Technology | Correctness |
+|-------|------|-----------|-------------|
+| **Intent** | Classify user input | LLM | Probabilistic (confidence threshold) |
+| **Routing** | Choose execution path | Petri Net | Deterministic (verified) |
+| **Execution** | Run business logic | GraphFlow | Typed (Zod validated) |
+
+This split means the LLM is called exactly **once per turn** for intent classification. All subsequent routing and execution is handled by verified, typed code.
+
+---
+
+## Source Structure
+
+```
+@ai.ntellect/core
+├── execution/         # GraphFlow engine (typed nodes, events, checkpoints, planner, compiler)
+├── routing/           # PetriNet, CortexFlowOrchestrator, IntentClassifier
+├── agent/             # Agent, GenericExecutor, handlers, tools
+├── persistence/       # Barrel: Memory + checkpoint adapters
+├── pipeline/          # AgentPipeline (trigger → stages → gate)
+├── modules/           # Plugins: agenda, cli, embedding, memory, nlp
+├── interfaces/        # Contract interfaces
+├── types/             # Zod schemas
+└── index.ts           # Barrel: all public API exports
+```
+
+### Path Aliases
+
+- `@ai.ntellect/core` — root barrel (all major exports)
+- `@ai.ntellect/core/execution/...` — deep imports for GraphFlow internals
+- `@ai.ntellect/core/routing/...` — deep imports for PetriNet / CortexFlow
+- `@ai.ntellect/core/agent/...` — deep imports for Agent module
+- `@ai.ntellect/core/pipeline/...` — deep imports for AgentPipeline
+
+---
+
+## GraphFlow — Typed Execution
+
+A `GraphFlow` is a **typed state machine** where each node is a discrete unit of logic.
+
+```typescript
+import { z } from "zod";
+import { GraphFlow } from "@ai.ntellect/core";
+
+const schema = z.object({ count: z.number().default(0) });
+
+const workflow = new GraphFlow({
+  name: "counter",
+  schema,
+  context: { count: 0 },
+  nodes: [
+    {
+      name: "increment",
+      execute: async (ctx) => { ctx.count++; },
+      next: "double",
     },
-    publishContent: {
-      name: "publishContent",
-      description: "Publish processed content",
-      execute: async (state) => {
-        console.log("Publishing content:", state.processedContent);
-        state.published = true;
-        return state;
-      },
+    {
+      name: "double",
+      execute: async (ctx) => { ctx.count *= 2; },
     },
+  ],
+});
+
+await workflow.execute("increment");
+console.log(workflow.context.count); // 2
+```
+
+### Node Types
+
+| Type | Description |
+|------|-------------|
+| **Sequential** | `next: "nodeName"` or `next: (ctx) => condition ? "a" : "b"` |
+| **Parallel** | `parallel: { enabled: true, joinNode: "merge" }` — fork-join model |
+| **Send API** | Dynamic fan-out: create N parallel branches at runtime |
+| **Event-Driven** | `when: "event.name"` — pause and wait for external event |
+
+### Checkpoints
+
+Save/resume workflow state with time-travel debugging and human-in-the-loop breakpoints:
+
+```typescript
+import { InMemoryCheckpointAdapter } from "@ai.ntellect/core";
+
+const adapter = new InMemoryCheckpointAdapter();
+const cpId = await workflow.executeWithCheckpoint("start", adapter, {
+  breakpoints: ["approve_payment"],
+});
+
+// Later, resume with optional state modification:
+await workflow.resumeFromCheckpoint(cpId, adapter, {
+  contextModifications: { status: "approved" },
+});
+```
+
+---
+
+## CortexFlow — Intent Routing
+
+CortexFlow wraps intent classification + Petri Net routing. The LLM identifies intent once; the Petri Net handles all control flow deterministically.
+
+### Basic Usage
+
+```typescript
+import { CortexFlowOrchestrator, IntentClassifier } from "@ai.ntellect/core/routing/orchestrator";
+import { ToolRegistry } from "@ai.ntellect/core";
+import { GraphFlow } from "@ai.ntellect/core";
+
+const llmFn = async (prompt: string) => { /* your LLM call */ };
+const registry = new ToolRegistry();
+const orchestrator = new CortexFlowOrchestrator("mail_assistant", registry);
+
+const classifier = new IntentClassifier(llmFn, {
+  intents: ["FETCH_MAILS", "SUMMARIZE", "UNKNOWN"],
+  confidenceThreshold: 0.7,
+});
+orchestrator.setIntentClassifier(IntentClassifier.toFn(classifier), classifier);
+orchestrator.setLLMCall(llmFn);
+
+// Build Petri Net
+const net = orchestrator.petri;
+net.addPlace({ id: "idle", type: "initial", tokens: [{ id: "start", data: {}, createdAt: 0 }] });
+net.addPlace({ id: "done", type: "final", tokens: [] });
+net.addTransition({
+  id: "process_mails",
+  from: ["idle"],
+  to: "done",
+  action: { type: "graphflow", name: "mail_fetch" },
+});
+
+registry.register({ name: "mail_fetch", description: "...", graph: new GraphFlow({...}), startNode: "fetch" });
+
+const sessionId = orchestrator.startSession();
+const result = await orchestrator.orchestrate("Summarise my last 5 emails", sessionId);
+```
+
+### Key Components
+
+| Export | Source | Description |
+|--------|--------|-------------|
+| `PetriNet` | `@ai.ntellect/core` | Core Petri Net engine |
+| `CortexFlowOrchestrator` | `@ai.ntellect/core/routing` | Intent → routing → execution |
+| `IntentClassifier` | `@ai.ntellect/core/routing` | LLM-based intent classification |
+| `HybridIntentClassifier` | `@ai.ntellect/core/routing` | Keyword + LLM fallback |
+
+### Advanced Features
+
+- **Hybrid Fallback**: Delegate to conversational LLM on low confidence
+- **Multi-Intent**: Execute multiple intents sequentially
+- **Formal Verification**: Deadlock detection via incidence matrices
+- **Persistence**: Redis/PostgreSQL checkpoint adapters
+
+---
+
+## Agent — Cognitive Loop
+
+The `Agent` class wraps a cognitive loop (think → execute → reply) on top of GraphFlow, with LLM-driven tool selection.
+
+```typescript
+import { Agent, createCalculatorTool } from "@ai.ntellect/core";
+
+const agent = new Agent({
+  role: "Math Assistant",
+  tools: [createCalculatorTool()],
+  llmConfig: {
+    provider: "groq",
+    model: "llama-3.1-8b-instant",
+    apiKey: process.env.GROQ_API_KEY,
   },
-};
+});
 
-const workflow = new Workflow(contentPipelineDefinition);
+const result = await agent.process("What is 25 + 7?");
 ```
 
-## Executing the workflow
+### Cognitive Loop Components
+
+| Component | Location | Description |
+|-----------|----------|-------------|
+| `Agent` | `agent/agent.ts` | Public API: orchestrates the cognitive loop |
+| `GenericExecutor` | `agent/generic-executor.ts` | Decision-making + action execution |
+| `DynamicGoalHandler` | `agent/handlers/` | Context-aware goal computation |
+| `DynamicNextHandler` | `agent/handlers/` | Next-state routing |
+| `LLMFactory` | `agent/llm-factory.ts` | Multi-provider LLM client |
+| `PromptBuilder` | `agent/prompt-builder.ts` | Structured prompt construction |
+| Tools (`file-system`, etc.) | `agent/tools/` | Prebuilt agent tools |
+
+### Built-in Agent Tools
+
+```typescript
+import {
+  createFileReaderTool,
+  createFileWriterTool,
+  createShellTool,
+  createDirectoryListerTool,
+  createAllAgentTools,
+  createCalculatorTool,
+} from "@ai.ntellect/core";
+```
+
+---
+
+## AgentPipeline — Declarative Pipelines
+
+Declarative pipelines with triggers, typed stages, and human gates.
 
-Run the content pipeline workflow with an initial state:
+```typescript
+import { AgentPipeline } from "@ai.ntellect/core";
+import { InMemoryPetriCheckpointAdapter } from "@ai.ntellect/core";
 
-```javascript
-const initialState = {};
-await workflow.execute(initialState, "fetchContent");
+const pipeline = new AgentPipeline({
+  name: "price-monitor",
+  stages: [
+    {
+      id: "fetch",
+      run: async (ctx) => ({ data: await fetchData() }),
+      retry: { max: 3, delayMs: 1000 },
+    },
+    {
+      id: "process",
+      run: async (ctx) => ({ result: processData(ctx.data) }),
+    },
+  ],
+  trigger: { type: "cron", expression: "*/5 * * * *" },
+  gate: "human",
+  checkpointAdapter: new InMemoryPetriCheckpointAdapter(),
+});
+
+await pipeline.start();
 ```
 
-Example output:
+---
 
-```text
-Fetching content...
-Processing content: [ 'Article1', 'Article2' ]
-Publishing content: [ 'ARTICLE1', 'ARTICLE2' ]
+## Persistence — Memory & Checkpoints
+
+The `persistence/` barrel provides a unified interface for storage:
+
+```typescript
+import {
+  Memory,
+  InMemoryCheckpointAdapter,
+  InMemoryPetriCheckpointAdapter,
+  RedisPetriCheckpointAdapter,
+  PostgresPetriCheckpointAdapter,
+} from "@ai.ntellect/core";
 ```
 
-## Visualizing the workflow
+### Memory
 
-Generate a visual representation of the content pipeline workflow:
+```typescript
+import { Memory } from "@ai.ntellect/core";
+import { InMemoryAdapter } from "@ai.ntellect/core/modules/memory";
 
-```javascript
-workflow.visualize("Content Pipeline Workflow");
+const memory = new Memory(new InMemoryAdapter());
+await memory.init();
+await memory.createMemory({ content: "Hello", roomId: "default" });
+const results = await memory.getMemoryByIndex("Hello", { roomId: "default" });
 ```
 
-Output example:
+### Checkpoint Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `InMemoryCheckpointAdapter` | Testing / development |
+| `InMemoryPetriCheckpointAdapter` | PetriNet checkpoint testing |
+| `RedisPetriCheckpointAdapter` | Distributed / production |
+| `PostgresPetriCheckpointAdapter` | SQL-backed persistence |
+| `Neo4jPetriCheckpointAdapter` | Graph-backed persistence |
 
-```mermaid
-workflow TD
-  fetchContent[Fetch Content]
-  processContent[Process Content]
-  publishContent[Publish Content]
-  fetchContent --> processContent
-  processContent --> publishContent
+### Graph Observability & Persistence (Neo4j)
+
+Because the framework relies on explicit routing (Petri Nets) and state machines (GraphFlow), **Neo4j** is supported as a first-class citizen. It allows you to visually audit execution traces, map long-term memory relations, and persist agent entity resolutions without polluting your business logic.
+
+```typescript
+import { 
+  createDriver,
+  Neo4jMemoryAdapter, 
+  Neo4jExecutionTracer, 
+  Neo4jEntityStore 
+} from "@ai.ntellect/core/persistence";
+
+const { driver } = await createDriver({ url: "bolt://localhost:7687", username: "neo4j", password: "password" });
+
+// 1. Graph Memory (Semantic & Relational)
+const memoryAdapter = new Neo4jMemoryAdapter(driver);
+await memoryAdapter.addRelation({ fromId: "mem-1", toId: "mem-2", type: "RELATES_TO", roomId: "user-1" });
+
+// 2. Visual Execution Tracing (Zero-invasion event listener)
+const tracer = Neo4jExecutionTracer.attach(workflow, driver, "exec-123");
+// Visually query in Neo4j Browser: MATCH path=(e:Execution)-[:HAS_RUN]->(n:NodeRun) RETURN path
+
+// 3. Persistent Entity Resolution
+const entityStore = new Neo4jEntityStore(driver);
+await entityStore.recordResolution("ent-1", "find user intent", 0.95);
 ```
 
-## Advanced features
+---
 
-### Event-driven execution
+## Planner & Compiler
 
-Add event-driven nodes to the workflow:
+For advanced workflows, the LLM generates a Zod-validated JSON plan that is compiled into a deterministic GraphFlow at runtime.
 
-```javascript
-workflow.addNode(
-  {
-    name: "eventDrivenNode",
-    description: "Node triggered by a custom event",
-    execute: async (state) => {
-      console.log("Custom event processed.");
-      return state;
-    },
-  },
-  { events: ["customEvent"] }
-);
+```typescript
+import { Planner, Compiler } from "@ai.ntellect/core";
+
+const planner = new Planner(llmFn);
+const plan = await planner.createPlan("Send 0.5 ETH to Alice after checking balance");
+
+const compiler = new Compiler();
+const workflow = compiler.compile(plan);
 
-workflow.emit("customEvent", { state: { exampleKey: "exampleValue" } });
+await workflow.execute("start");
 ```
 
-Example output:
+---
 
-```text
-Custom event processed.
+## CLI (Interactive REPL)
+
+```sh
+pnpm cli -p groq -m llama-3.1-8b-instant
+pnpm cli -p openai -m gpt-4o-mini
+pnpm cli -p ollama -m llama3
 ```
 
-### Parallel execution
+**Slash commands**: `/status`, `/history`, `/list`, `/resume [cpId]`, `/approve`, `/reject`, `/modify k=v`, `/clear`, `/help`.
+
+The CLI automatically loads API keys from `.env` (`GROQ_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`).
+
+---
 
-Execute multiple nodes concurrently:
+## GraphController
 
-```javascript
-await workflow.executeParallel(
-  { data: "Parallel Execution" },
-  ["nodeA", "nodeB"],
-  2
-);
+Orchestrate multiple GraphFlows in parallel or sequence:
+
+```typescript
+import { GraphController } from "@ai.ntellect/core";
+
+const controller = new GraphController();
+controller.add("workflow_a", graphA);
+controller.add("workflow_b", graphB);
+
+await controller.parallel("workflow_a", "workflow_b");
+await controller.sequential("workflow_a", "workflow_b");
 ```
 
-### Conditional logic
+---
 
-Add conditional nodes to control the workflow path:
+## Testing & Build
 
-```javascript
-workflow.addNode(
-  {
-    name: "conditionalNode",
-    description: "Node executed conditionally",
-    execute: async (state) => {
-      console.log("Condition met, executing node...");
-      return state;
-    },
-  },
-  {
-    condition: (state) => state.content && state.content.length > 0,
-    next: ["publishContent"],
-  }
-);
-```
-
-### Sub-workflows
-
-Embed sub-workflows for modularity:
-
-```javascript
-const subWorkflowDefinition = {
-  name: "SubWorkflow",
-  nodes: {
-    subNode: {
-      name: "subNode",
-      execute: async (state) => {
-        console.log("Executing sub-workflow.");
-        return state;
-      },
-    },
-  },
-};
+```sh
+pnpm run build                  # tsc → dist/
+pnpm test                       # Mocha via ts-node (5s timeout)
+pnpm run test:all               # Full suite (test/**/*.test.ts)
+pnpm test --grep "suite name"   # Focused suite
+pnpm run test:watch             # Watch mode
+```
+
+**Real LLM tests**: `pnpm test --grep "CortexFlow Real LLM"` (requires Ollama `llama3:latest` on `localhost:11434`).
+
+**Examples**:
 
-workflow.addSubWorkflow(
-  new Workflow(subWorkflowDefinition),
-  "subNode",
-  "processContent"
-);
+```sh
+pnpm run example:hello
+pnpm run example:agent
+pnpm run example:onchain
 ```
+
+---
+
+## License
+
+MIT