Intelligenism Agent Framework

Why IAF Exists

IAF is not just another multi-agent framework. It is the first practical implementation of Intelligenism — a theoretical framework on how intelligence emerges in organisations, whether human, artificial, or hybrid.

The AI industry has no shortage of agent frameworks (CrewAI, AutoGen, LangGraph, Google ADK, and many more). They all solve the same problem: "how to make multiple agents collaborate on tasks." But they all share the same blind spot: they hardcode a specific collaboration paradigm into the framework itself, then call it "flexible" because you can configure parameters within that paradigm.

IAF starts from a different premise — an epistemological one.

From single neurons to complex neural networks, intelligence exhibits a bottom-up construction pattern. Regardless of whether we look at complex intelligent systems or individual neurons, their boundaries are clear, and individuals maintain a high degree of independence from one another. This means the complexity and intelligence potential of a neural network comes from the connections between individuals, not from making the individuals internally more complex. Therefore, maintaining the independence of individuals or small units, and expressing complexity outside the individual, is the essence of connectionism. — Thinking, Conception and Construction of Intelligenism

This principle directly shapes IAF's architecture: every agent is a complete, independent unit. Complexity lives in the connections between agents (the Dispatch and Tube layers), not inside any single agent's code.

Possibility Management vs Certainty Management

Intelligenism begins with an epistemological judgment: humans cannot assert that any theory is absolute truth. Since we cannot assert absolute truth, the way to evaluate a theory should shift toward "fitness" — whether the theory can effectively guide action and produce positive value in a given scenario. — Thinking, Conception and Construction of Intelligenism

2026 is a period of profound transformation in AI. The only thing we can be certain of is that we are in the middle of a revolution — everything else is uncertain. This creates a critical risk: if we bet resources on a framework built on certainty-based assumptions, when that assumption is falsified, all accumulated advantages collapse.

Most multi-agent frameworks practice certainty management. Their developers assume they know which collaboration paradigm works best, so they deeply integrate that paradigm into the framework's core. CrewAI's identity is role-playing sequential execution. AutoGen's identity is multi-round dialogue with consensus convergence. If you could swap these out, these frameworks would lose their reason to exist.

IAF practices possibility management. It assumes that more multi-agent collaboration modes will emerge in the future, and therefore refuses to assert from a position of absolute truth that any one mode is necessarily better.

What this means in practice:

• Certainty management — One shared engine serves all agents. Users are free within the range of parameters the framework designer foresaw. "We're flexible — you can configure many parameters."
• Possibility management — Each agent owns a complete copy of the entire engine. Users can modify any line of code, making any agent fundamentally different from any other — without risking impact on other agents. "You own the full code — you can change anything."

Core Concepts

Fundamental Loop

The Fundamental Loop is a complete, self-contained agent runtime. Every agent has its own independent copy containing:

• LLM Communication Engine — Message assembly, API calls via OpenRouter, structured response handling
• Tool Executor — Auto-discovers and registers tools, executes LLM-requested tool calls
• Context Manager — History management, sliding-window trimming strategy
• Tool Library — Pluggable tool modules (file I/O, shell, tube trigger, dispatch collaboration)
• Identity & Knowledge — Configurable context_files loads any .md files as system prompt
• Skills — Task instructions dynamically injected based on trigger rules

Current implementation: ~267 lines of Python for the engine core, plus shared infrastructure. The engine uses a five-layer message assembly model:

Agent Capability Model

Available Tool Files

Drop a tool file into agents/xxx/tools/ — auto-discovered, zero code changes.

Additive Complexity

Shared-engine frameworks have multiplicative complexity: 3 agents × 2 trimming strategies × 4 tool sets = 24 combinations, each with potential interaction bugs. Adding one agent multiplies the complexity by a coefficient.

IAF has additive complexity: each agent's Fundamental Loop is always ~267 lines. Adding a 4th agent means one more 267-line copy. Each copy evolves independently, affecting nothing else.

True Parallel Execution

Because each Fundamental Loop runs as an independent process:

• No GIL limitation — Each agent is a separate Python process
• No shared memory — No locks, no race conditions, no state pollution
• Natural rate limit distribution — Different agents can call different LLM providers
• Fault isolation — One agent crashes, others keep running

Four-Layer Architecture

The framework consists of four fully independent layers. Units within each layer are also isolated from each other. The four layers communicate through Flask APIs and the filesystem — no layer invades another.

Plus cross-cutting infrastructure:

• chat_server.py — Router + Tube Runner bootstrap (no business logic)
• tube_routes.py — Tube Layer Flask Blueprint
• dispatch_routes.py — Dispatch Layer Flask Blueprint

Layer 1: Agent Layer

The bottom execution unit. Each agent owns a complete Fundamental Loop copy (engine, tools, context, identity, skills). Agents don't know Dispatch or Tube exist. Two run modes: chat (with history, for user interaction) and batch (clean context, for scheduled tasks).

Layer 2: Dispatch Layer

Multi-agent collaboration orchestration. Each collaboration strategy is an independent folder containing its own orchestration logic, context injector, config, and optional UI page. Dispatch treats agents as data sources (reads their context_files, skills, model config) but calls lib/llm_client.call_llm() directly — zero coupling with agent engines.

Three-layer context isolation:

Agents are unaware they participated in a Dispatch. Dispatch never touches an agent's history.jsonl. Isolation is an architectural guarantee.

Layer 3: Tube Layer

The signal topology layer — the wiring between building blocks. When a condition is met, trigger a target to execute. Same three agents plus two dispatches — different Tube configurations produce entirely different system behaviour: serial pipelines, parallel fan-out, feedback loops. The blocks haven't changed; the wiring has. See the Tube in Detail section below.

Layer 4: UI Layer

Yellow-pages index + independent HTML pages. Each page is self-contained, communicates with the backend through APIs. No SPA, no shared UI engine — adding a page means dropping an HTML file into a directory.

Mapping to Intelligenism Theory

Dispatch in Detail

Dispatch Folder Structure

Context Injector

Each Dispatch strategy has a context_injector.py that selectively reads from agent folders based on dispatch_config.json:

{
  "agents": {
    "default": {
      "display_name": "Strategist",
      "provider": "from_agent",
      "model": "from_agent",
      "context_files": [
        "agents/default/SOUL.md",
        "dispatch/roundtable/rules/default.md",
        "dispatch/roundtable/staging/session_history.md"
      ]
    }
  },
  "turn_order": ["default", "agent2"]
}

provider and model set to "from_agent" reads from the agent's own agent_config.json. Or you can override directly — the same agent can use different models in different collaboration strategies.

Data Flow

dispatch.py
 ├── reads dispatch_config.json (which agents, what to read from each)
 ├── context_injector.py (selectively reads from agent folders per config)
 │   ├── agents/xxx/SOUL.md ← read or not, config decides
 │   ├── agents/xxx/skills/x.md ← which ones, config decides
 │   └── agents/xxx/agent_config.json ← get model/provider
 ├── assembles Dispatch's own context (session history, task instructions)
 └── calls lib/llm_client.call_llm() directly

Tube in Detail

Tube is the framework's third dimension — the signal topology layer. It describes signal pathways between building blocks: when a condition is met, trigger a target to execute.

Existing multi-agent frameworks share a common problem: the pipes between building blocks are cast in place.

Tube Anatomy

tubes.json — Single Source of Topology Truth

[
  {
    "id": "doc_analysis_pipeline",
    "enabled": true,
    "triggers": [
      { "type": "cron", "config": { "expr": "30 9 * * *" } },
      { "type": "manual" }
    ],
    "steps": [
      { "type": "agent", "id": "doc_processor", "mode": "batch",
        "payload": { "prompt": "Process and analyse documents" } },
      { "type": "dispatch", "id": "roundtable",
        "payload": { "message": "Brainstorm based on analysis results" } },
      { "type": "tube", "id": "send_report" }
    ]
  }
]

Trigger Sources

Drive Targets

Execution Model

• Subprocess isolation — tube_runner only spawns subprocesses, never imports business code
• Serial steps — Next step runs only if previous exits with code 0
• Parallel tubes — Different tubes execute in independent threads, non-blocking
• Duplicate prevention — running_tubes dictionary prevents re-firing the same tube
• Hot reload — tubes.json is re-read every polling cycle, no restart needed
• Fire-and-forget — Triggering does not block the main loop

Tube API Endpoints

The Tube Dashboard (pages/tube-dashboard.html) provides real-time monitoring: tube list with live status, manual trigger buttons, expandable config details and step payloads, scrolling execution logs, and per-tube log clearing. Auto-polls every 10 seconds.

File System as Communication Protocol

Agents communicate through the file system — output files, monitor status files, log files, flag files. Not through shared memory or function calls.

• Simple implementation — No message queues, no RPC frameworks, no shared memory management
• Naturally debuggable — Intermediate files can be viewed with any text editor
• Future-proof for distribution — Replace file directory with NFS/S3/HTTP API, and agents can run on different servers

AI Operability

IAF is not just "an AI framework for humans" — it is an AI framework that AI can also operate. The design features — minimal codebase, filesystem communication, JSON declarative config, process isolation — make the framework fully controllable by both carbon-based and silicon-based intelligence.

A top-tier AI agent taking over a framework must pass four gates: understand, modify, deploy, monitor. IAF is clear on every gate:

Directory Structure

intelligenism-agent-framework/
├── config.json                     # Global config (provider connections)
├── lib/                            # Shared infrastructure
│   ├── llm_client.py               # HTTP LLM calls + retry + error classification
│   └── token_utils.py              # Token estimation
├── template/                       # Fundamental Loop template (copy to create agents)
│   ├── core/
│   │   ├── direct_llm.py           # Engine core (~267 lines)
│   │   └── tool_executor.py        # Tool auto-discovery registry
│   ├── tools/
│   │   └── file_tools.py           # Default tool set
│   ├── context/
│   │   └── sliding_window.py       # Default trimming strategy
│   ├── skills/                     # Empty directory (populate per agent)
│   ├── SOUL.md                     # Identity template
│   └── agent_config.json           # Agent config template
├── agents/                         # Agent instance directory
│   └── default/                    # (same structure as template/)
├── dispatch/                       # Collaboration strategy library
│   └── roundtable/                 # Roundtable discussion strategy
│       ├── dispatch.py             # Orchestration logic
│       ├── dispatch_base.py        # Infrastructure (tool loop, LLM parsing)
│       ├── context_injector.py     # Context assembly
│       ├── session_manager.py      # Session management
│       ├── dispatch_config.json    # Participating agents + file read rules
│       ├── context/                # Dispatch-specific trimming
│       ├── rules/                  # Agent role definitions
│       ├── sessions/               # Collaboration records
│       ├── staging/                # Runtime temporary files
│       └── roundtable.html         # Dedicated UI page
├── tube/                           # Signal topology layer
│   ├── tube_runner.py              # Main loop engine
│   ├── triggers/                   # Pluggable trigger sources
│   │   ├── cron.py                 # Cron scheduling
│   │   └── manual.py              # Manual / API trigger
│   ├── targets/                    # Pluggable drive targets
│   │   ├── agent.py                # Drive agent
│   │   └── dispatch.py             # Drive dispatch
│   ├── run_agent.py                # Agent CLI entry
│   ├── run_dispatch.py             # Dispatch CLI entry
│   ├── tubes.json                  # Single source of topology truth
│   ├── tube_log.jsonl              # Execution log
│   └── manual_triggers/            # Flag file directory
├── chat_server.py                  # Web server / router + Tube Runner
├── dispatch_routes.py              # Dispatch Flask Blueprint
├── tube_routes.py                  # Tube Flask Blueprint
├── index.html                      # Yellow pages (feature index)
├── chat.html                       # Basic chat interface
├── pages/                          # User-created pages
│   └── tube-dashboard.html         # Tube monitoring panel
└── tests/
    └── test_template.py

Four Orthogonal Extension Dimensions

The framework's four extension dimensions are fully orthogonal — a change in any one dimension does not affect the other three.

Folder = Product

The core difference from traditional SaaS products: what users get is not a black-box service, but a fully disassemblable, learnable, and modifiable blueprint.

Key Design Principles

• Stateless API — LLMs don't remember previous conversations. Full context is re-sent every call.
• LLM decides, code executes — LLMs return structured JSON tool requests, not executable code.
• Auto-discovery pattern — Tools, trimming strategies, agents, pages, trigger sources, drive targets — all discovered by scanning directories.
• Layered isolation — Each layer only knows its adjacent layer. Four layers + three-layer context isolation.
• Process isolation — Each agent, each Tube step runs in an independent process.
• Filesystem communication — Agents communicate via files. Naturally debuggable, future-distributable.
• Possibility management — Copy full code instead of parameterised configuration.
• Folder as product — Agents, Dispatches, HTML pages are independently distributable product units.
• Additive complexity — Adding agents, collaboration modes, tubes, pages — all additive.
• Declarative topology — tubes.json is the single source of signal topology truth.
• AI operable — Both carbon-based and silicon-based intelligence can fully control the framework.
• Dual-side pluggable — Tube input side (triggers/) and output side (targets/) are both extend-by-dropping-files.

Comparison with Existing Frameworks

Tech Stack

The entire framework depends only on Python + HTML. No Node.js, no npm, no frontend build tools.

pip install flask requests croniter

That's it.

Current Status: v1.0

• ✅ Agent Layer (Fundamental Loop) — complete and functional
• ✅ Dispatch Layer (Roundtable strategy) — complete and functional
• ✅ Tube Layer (Signal Topology) — complete and functional
• ✅ UI Layer (Yellow Pages + Chat + Tube Dashboard) — complete and functional
• ✅ Shared Infrastructure (llm_client + token_utils) — complete
• ✅ Agent Toolset (file / shell / tube / dispatch) — complete
• ✅ CLI Entry Points — standardised
• ✅ Architecture Validation Tests — complete

Getting Started

# Clone the repo
git clone https://github.com/IntelligenismCommercialDevelopment-LLC/intelligenism-agent-framework.git
cd intelligenism-agent-framework

# Set up virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install flask requests croniter

# Configure your LLM provider in config.json

# Create your first agent
cp -r template/ agents/my_agent/

# Edit agents/my_agent/SOUL.md to define your agent's identity

# Start the server
python3 chat_server.py

# Open http://localhost:5000

The Bigger Picture

IAF is one component of a larger knowledge production system rooted in Intelligenism theory:

Each layer is independently developed and independently valuable. Together, they form a complete pipeline from raw information to structured, retrievable, actionable knowledge.

Links

• GitHub — intelligenism-agent-framework
• v1.0 Release Notes — IAF v1.0 — Four-Layer Architecture Complete
• v0.9 Release Notes — IAF v0.9 — First Public Release
• Website — intelligenism.club
• Theory — intelligenism.org