IAF v1.0 — Four-Layer Architecture Complete

What changed since v0.9

v0.9 shipped the Agent Layer and UI Layer. Dispatch and Scheduler were architecture-only. v1.0 completes the entire four-layer stack:

• Dispatch Layer — Multi-agent collaboration is live. The Roundtable strategy ships as the first complete implementation.
• Tube Layer — The signal topology layer (previously called "Scheduler") has been redesigned from a simple cron trigger into a full declarative wiring system with pluggable triggers and targets.
• Agent Toolset — Four tool files now available: file_tools, shell_tools, tube_tools, dispatch_tools. Agents can trigger tubes, initiate collaboration, and execute shell commands.
• CLI Entry Points — Standardised run_agent.py and run_dispatch.py for subprocess execution.
• Tube Dashboard — Real-time monitoring panel with manual trigger buttons, execution logs, and per-tube status.
• context_files — Agent identity system upgraded from single SOUL.md to configurable multi-file loading.

Four-Layer Architecture

The framework now 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.

Agent Layer

The core of IAF: the Fundamental Loop. Each agent is a self-contained runtime (~267 lines of engine code):

• LLM Communication — Message assembly, API calls via OpenRouter, structured response handling
• Tool Executor — Auto-discovery registry, whitelist-based execution, tool call loop
• Context Management — Sliding-window trimming strategy, chat history persistence
• Identity & Knowledge — Configurable context_files loads any .md files as system prompt
• Skills — Trigger-based dynamic injection of task instructions

Five-Layer Message Assembly

Agent Toolset

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

Dispatch Layer

The Dispatch Layer implements multi-agent collaboration. It calls lib/llm_client.call_llm() directly — it does not go through the Agent engine. Agent folders are treated as "asset libraries + model config", not as executors.

Dispatch Folder Structure

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.

Tube Layer

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.

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, and so the system behaves completely differently.

Tube Anatomy

tubes.json Example

[
  {
    "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" }
    ]
  }
]

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

UI Layer

A browser-based interface following the yellow-pages architecture. Every HTML page is fully self-contained. Zero coupling between pages. No unified SPA shell, no shared router.

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

AI Operability

IAF is not just "an AI framework for humans" — it is an AI framework that AI can also operate. A top-tier AI agent taking over a framework must pass four gates:

Four Orthogonal Extension Dimensions

Status Summary

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

Tech Stack

Get the Code

# 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

# Start the server
python3 chat_server.py

# Open http://localhost:5000

Links

• GitHub — intelligenism-agent-framework
• Full Architecture Docs — IAF Architecture Overview
• v0.9 Release Notes — IAF v0.9 — First Public Release
• Website — intelligenism.club
• Theory — intelligenism.org