@ai.ntellect/core

Stop your AI agents from going off-rails in production.

LLMs generate. You control.

One LLM call $\rightarrow$ deterministic execution $\rightarrow$ no routing hallucinations.

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

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

User → LLM (intent) → Petri Net (routing) → GraphFlow (execution)

One decision. Then control.

Installation

pnpm add @ai.ntellect/core zod

Requirements: TypeScript 5.x+, Node.js 18+.

Table of Contents

• Core Thesis
• GraphFlow
• CortexFlow
• Agent
• Pipelines
• Persistence
• Planner & Compiler
• CLI
• GraphController

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.

GraphFlow — Typed Execution

A GraphFlow is a typed state machine where each node is a discrete unit of logic.

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",
    },
    {
      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:

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

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

| Component | Description | |--------|-------------| | PetriNet | Core Petri Net engine | | CortexFlowOrchestrator | Intent → routing → execution | | IntentClassifier | LLM-based intent classification | | HybridIntentClassifier | 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.

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 result = await agent.process("What is 25 + 7?");

Cognitive Loop Components

| Component | Description | |-----------|-------------| | Agent | Public API: orchestrates the cognitive loop | | GenericExecutor | Decision-making + action execution | | CognitiveHandler | Context-aware goal computation and next-state routing | | LLMFactory | Multi-provider LLM client (OpenAI, Groq, Ollama, etc.) | | PromptBuilder | Structured prompt construction | | Tools | Prebuilt agent utilities (file-system, shell, etc.) |

Built-in Agent Tools

import {
  createFileReaderTool,
  createFileWriterTool,
  createShellTool,
  createDirectoryListerTool,
  createAllAgentTools,
  createCalculatorTool,
} from "@ai.ntellect/core";

Pipelines

Declarative pipelines with triggers, typed stages, and human gates.

import { AgentPipeline } from "@ai.ntellect/core";
import { InMemoryPetriCheckpointAdapter } from "@ai.ntellect/core";

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();

Persistence — Memory & Checkpoints

The persistence/ barrel provides a unified interface for storage:

import {
  Memory,
  InMemoryCheckpointAdapter,
  InMemoryPetriCheckpointAdapter,
  RedisPetriCheckpointAdapter,
  PostgresPetriCheckpointAdapter,
} from "@ai.ntellect/core";

Memory

import { Memory } from "@ai.ntellect/core";
import { InMemoryAdapter } from "@ai.ntellect/core/modules/memory";

const memory = new Memory(new InMemoryAdapter());
await memory.init();
await memory.createMemory({ content: "Hello", roomId: "default" });
const results = await memory.getMemoryByIndex("Hello", { roomId: "default" });

Checkpoint Adapters

| Adapter | Use Case | |---------|----------| | InMemoryCheckpointAdapter | Testing / development | | InMemoryPetriCheckpointAdapter | PetriNet checkpoint testing | | RedisPetriCheckpointAdapter | Distributed / production | | PostgresPetriCheckpointAdapter | SQL-backed persistence | | Neo4jPetriCheckpointAdapter | Graph-backed persistence |

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.

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);

Planner & Compiler

For advanced workflows, the LLM generates a Zod-validated JSON plan that is compiled into a deterministic GraphFlow at runtime.

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);

await workflow.execute("start");

CLI (Interactive REPL)

pnpm cli -p groq -m llama-3.1-8b-instant
pnpm cli -p openai -m gpt-4o-mini
pnpm cli -p ollama -m llama3

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).

GraphController

Orchestrate multiple GraphFlows in parallel or sequence:

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");

License

MIT cense

MIT