IAF Architecture Map

This document serves as the operations navigation guide for external LLMs (Claude Code, GPT Agent, etc.) taking over IAF. It answers not "what functions are in each file," but "which files can be touched, which should be left alone, and which areas to modify when touching them."

Core principle: Do not touch infrastructure unless absolutely necessary. 99% of requirements can be fulfilled by adjusting Adjustable components.

v0.4 changes: Integrated full external LLM takeover plan. Added MANIFEST.json, validate.py, call_log.jsonl, tool hot-reload, Tube retry/data-passing, auto_commit.sh and other component descriptions. Maintains independent agent engine copy design (possibility management) without introducing engine inheritance.

0. External LLM Takeover Entry Point

When an external LLM first takes over an IAF instance, read these three files in order to begin work:

0.1 MANIFEST.json (System Map)

Auto-generated by generate_manifest.py scanning directories, also auto-refreshed when chat_server.py starts.

{
  "framework": "IAF",
  "version": "0.1.0",
  "generated_at": "2026-04-01T14:30:00Z",

  "structure": {
    "agents_dir": "agents/",
    "template_dir": "template/",
    "dispatch_dir": "dispatch/",
    "tube_dir": "tube/",
    "global_config": "config.json",
    "tube_config": "tube/tubes.json",
    "tube_log": "tube/tube_log.jsonl",
    "pages_dir": "pages/"
  },

  "agents": {
    "charlie": {
      "config": "agents/charlie/agent_config.json",
      "soul": "agents/charlie/SOUL.md",
      "tools": ["file_tools.py", "shell_tools.py", "dispatch_tools.py", "tube_tools.py"],
      "history": "agents/charlie/history.jsonl",
      "call_log": "agents/charlie/call_log.jsonl",
      "model": "google/gemini-3-flash-preview"
    }
  },

  "dispatches": {
    "roundtable": {
      "config": "dispatch/roundtable/dispatch_config.json",
      "agents": ["charlie", "mcmillan"],
      "ui": "dispatch/roundtable/roundtable.html"
    }
  },

  "tubes": {
    "morning_news": {
      "enabled": true,
      "triggers": ["cron:0 3 * * *", "manual"],
      "steps": ["agent:charlie"]
    }
  },

  "conventions": {
    "tool_file_pattern": "*_tools.py",
    "tool_export_variable": "TOOLS",
    "context_strategy_dir": "context/",
    "skill_dir": "skills/"
  }
}

External LLM manual refresh: python3 generate_manifest.py

0.2 PLAYBOOK.md (Operations Manual)

Plain-text operations manual covering complete steps for all common operations. See standalone file.

0.3 validate.py (Validation Script)

External LLM calls via Bash after modifying files to confirm changes are valid.

python3 validate.py agent charlie          # Validate single agent
python3 validate.py tool agents/charlie/tools/http_tools.py  # Validate tool file
python3 validate.py tube                   # Validate tubes.json
python3 validate.py all                    # Global validation

Output format: Success → OK, Failure → FAIL: N error(s) + line-by-line error descriptions. Plain text, no colours.

0.4 auto_commit.sh (Safety Snapshot)

External LLM calls before performing batch modifications:

bash auto_commit.sh "Pre-modification snapshot: adding http tools to charlie"

Rollback: git revert HEAD or git checkout -- {file}

1. Global Classification

All files in the framework fall into two categories:

2. Infrastructure Inventory (Do Not Touch)

2.1 Shared Layer lib/

2.2 Web Service Layer

2.3 Agent Engine template/

Note: template/ is the copy source. When creating a new Agent: cp -r template/ agents/xxx/, after which files in agents/xxx/ become Adjustable. Do not modify template/ itself.

direct_llm.py five-layer message assembly model:

Layer 1: context_files content → concatenated as system prompt
Layer 2: skills trigger matching → injected as user+assistant dialogue pairs when matched
Layer 3: history.jsonl → loaded in chat mode only, skipped in batch mode
Layer 4: current user message
Layer 5: trim → ensures total stays within max_context - 8000

direct_llm.py path resolution rules (shared by context_files and skill_file):

direct_llm.py structured logging (call_log.jsonl):

Each call_agent() invocation records the following events in agents/xxx/call_log.jsonl:

External LLM viewing: tail -20 agents/xxx/call_log.jsonl or grep "tool_error" agents/xxx/call_log.jsonl

2.4 Dispatch Strategy Infrastructure

Within each dispatch strategy folder, the following files are Infrastructure:

dispatch_base.py key interfaces:

get_llm_caller(project_root) → call_llm_fn or None
load_global_config(project_root) → dict
resolve_llm_endpoint(provider, global_config) → (url, key)
load_agent_tools(agent_id, project_root) → (tool_definitions, tool_functions)
call_with_tool_loop(messages, url, key, model, call_llm_fn, tool_definitions, tool_functions, max_tool_loops) → (content, tool_history)
write_agent_memory(agent_id, tool_history) → None
write_staging_history(project_root, session_id) → None
clear_staging() → None
set_status(session_id, round_num, agent_id, agent_name, status) → None
clear_status() → None
get_status() → dict

2.5 Tube Layer Infrastructure

2.5.1 Core Engine

Runtime mechanism key points:

• Polls tubes.json every 15 seconds (hot-loaded, config changes don't require restart)
• Each triggered tube executes in an independent thread, multiple tubes can run in parallel
• running_tubes dictionary prevents duplicate triggering of the same tube
• Steps default to serial: next step runs only if previous exits with code 0; non-0 follows on_fail config (stop or continue)
• Supports step-level retry (retry.max + retry.delay_sec)
• Inter-step data passes via staging files ($PREV_OUTPUT placeholder)
• type=tube steps execute inline recursively (depth limit 5 levels)
• Other type steps build commands via targets/ modules, executed as subprocesses

2.5.2 Pluggable Trigger Sources triggers/

Each .py file is a trigger source type with unified interface:

def check(config: dict, state: dict) -> bool

state fields (provided by tube_runner):

User extension: Drop a .py file in triggers/, implement check() interface. Zero code changes.

2.5.3 Pluggable Drive Targets targets/

Each .py file is a drive target type with unified interface:

def build_command(step: dict, project_root: str) -> list[str]

User extension: Drop a .py file in targets/, implement build_command() interface. Zero code changes. Exception: type=tube steps don't go through targets/ modules; they're handled inline recursively by tube_runner.

2.5.4 Tube API Endpoints

2.5.5 tube_log.jsonl Event Types

2.6 Framework-Level Utility Tools

These three files are Infrastructure, but external LLMs only call them, never modify them.

3. Adjustable Components Inventory (AI Operation Targets)

3.1 Agent Adjustable Components

Within each agents/xxx/ folder:

Engine code (core/direct_llm.py, core/tool_executor.py) is semi-infrastructure: not modified by default after copying from template. Only modify when the user needs this Agent to be fundamentally different from others at the engine level — this is the core promise of "possibility management."

Engine modification protocol: Each agent has an independent engine copy. When modifying engine logic: 1) Modify one agent's copy and test. 2) After confirmation, diff against other agents' same-named files. 3) Sync individually to agents that need the same modification (not all agents need syncing — some may have special logic). 4) After syncing, run python3 validate.py all

3.2 Dispatch Adjustable Components

Within each dispatch/xxx/ folder:

Key design: Dispatch does not call Agent's call_agent. It directly calls lib/llm_client.call_llm(), assembling context itself via context_injector. The Agent folder serves Dispatch only as a data source (SOUL.md, rules, config), not as an executor.

3.3 Tube Adjustable Components

3.4 UI Adjustable Components

4. AI Operations Decision Tree

Received requirement
  │
  ├─ Need a new Agent?
  │   → bash auto_commit.sh "snapshot before adding agent"
  │   → cp -r template/ agents/xxx/
  │   → Edit SOUL.md
  │   → Edit agent_config.json (set context_files, skills, model)
  │   → Don't touch engine code
  │   → python3 validate.py agent xxx
  │   → python3 generate_manifest.py
  │
  ├─ Need to change Agent's loaded files?
  │   → Edit agent_config.json's context_files array
  │   → Add path = add file, remove path = remove file
  │   → Don't touch direct_llm.py
  │
  ├─ Need to add tools to Agent?
  │   → Reference template/tools/TOOL_CONTRACT.md for format
  │   → Drop *_tools.py file in agents/xxx/tools/
  │   → Hot-reload auto-discovery, no code changes
  │   → python3 validate.py tool agents/xxx/tools/new_tools.py
  │
  ├─ Need Agent to execute shell commands?
  │   → cp template/tools/shell_tools.py agents/xxx/tools/
  │
  ├─ Need Agent to trigger Tubes?
  │   → cp template/tools/tube_tools.py agents/xxx/tools/
  │
  ├─ Need Agent to initiate multi-Agent collaboration?
  │   → cp template/tools/dispatch_tools.py agents/xxx/tools/
  │
  ├─ Need to add skills to Agent?
  │   → Drop .md file in agents/xxx/skills/
  │   → Method A: Add trigger rule in agent_config.json skills array (exact match)
  │   → Method B: Add entry in skill_router.md (semantic trigger, needs file_tools)
  │   → Method C: Add directly to context_files (full injection, always loaded)
  │
  ├─ Need a new Dispatch strategy?
  │   → cp -r dispatch/roundtable/ dispatch/xxx/
  │   → Edit dispatch.py ORCHESTRATION LOGIC section
  │   → Edit dispatch_config.json, rules/
  │   → Don't touch dispatch_base.py, session_manager.py, context_injector.py
  │
  ├─ Need to adjust signal topology?
  │   → Edit tube/tubes.json
  │   → Don't touch tube_runner.py, triggers/, targets/
  │   → python3 validate.py tube
  │
  ├─ Need a new Tube trigger source type?
  │   → Drop .py file in tube/triggers/, implement check(config, state) → bool
  │   → Use filename as type in tubes.json
  │   → Don't touch tube_runner.py
  │
  ├─ Need a new Tube drive target type?
  │   → Drop .py file in tube/targets/, implement build_command(step, project_root) → list
  │   → Use filename as type in steps of tubes.json
  │   → Don't touch tube_runner.py
  │
  ├─ Need to manually trigger a Tube?
  │   → curl -X POST http://127.0.0.1:5000/api/tube/trigger \
  │       -H "Content-Type: application/json" \
  │       -d '{"tube_id": "xxx"}'
  │   → or: touch tube/manual_triggers/xxx
  │   → or: Agent triggers via tube_tools.py
  │
  ├─ Need to check system runtime status?
  │   → Agent chat history: tail agents/xxx/history.jsonl
  │   → Agent run log: tail agents/xxx/call_log.jsonl
  │   → Tube execution log: tail tube/tube_log.jsonl
  │   → Tube step output: Read tube/staging/{tube_id}_{timestamp}/
  │   → Error troubleshooting: grep "error\|failed" tube/tube_log.jsonl
  │   → Global validation: python3 validate.py all
  │
  ├─ Need to modify Agent engine logic?
  │   → bash auto_commit.sh "snapshot before engine modification"
  │   → Modify one agent's core/ copy first and test
  │   → diff against other agents' same-named files
  │   → Sync individually (note: not all agents need syncing)
  │   → python3 validate.py all
  │
  ├─ Need a new UI page?
  │   → Drop .html file in pages/
  │   → Auto-discovered by yellow pages
  │
  ├─ Need to rollback changes?
  │   → git diff → see what changed
  │   → git log --oneline -10 → see snapshot history
  │   → git checkout -- {file} → restore single file
  │   → git revert HEAD → rollback most recent commit
  │
  └─ None of the above?
      → May need to touch Infrastructure
      → First confirm: can this really not be achieved via Adjustable components?
      → If confirmed, read the corresponding Infrastructure source code, understand, then modify
      → After modification: python3 validate.py all to verify no other modules affected

5. Agent Capability Three-Layer Model Quick Reference

6. File Change Impact Scope Quick Reference

7. Hot-Reload Mechanism Quick Reference

8. Dangerous Operations Checklist (Always Git Commit Before Modifying)

Before operation: bash auto_commit.sh "description"
After operation: python3 validate.py all

9. External LLM Full Takeover Acceptance Scenario

1. Read MANIFEST.json
   → Understand what agents, tubes, dispatches the system has

2. Read PLAYBOOK.md
   → Know how to operate

3. Bash: bash auto_commit.sh "pre-modification snapshot"
   → Safety backup

4. Bash: cp -r template/ agents/monitor/
   → Create new agent

5. Write agents/monitor/SOUL.md
   → Write "You are a website monitoring agent, check site status when called..."

6. Edit agents/monitor/agent_config.json
   → Set display_name, model

7. Read template/tools/TOOL_CONTRACT.md
   → Understand tool file format

8. Write agents/monitor/tools/http_tools.py
   → Write HTTP check tool conforming to contract

9. Bash: python3 validate.py agent monitor
   → Output "OK"

10. Edit tube/tubes.json
    → Add a tube triggering monitor agent every 10 minutes

11. Bash: python3 validate.py tube
    → Output "OK"

12. Bash: python3 generate_manifest.py
    → Update MANIFEST.json

13. Bash: bash auto_commit.sh "Added monitor agent and scheduled check tube"
    → Save modifications

14. After 10 minutes:
    Read tube/tube_log.jsonl → Confirm tube triggered
    Read agents/monitor/call_log.jsonl → Confirm agent ran

15. If issues:
    Bash: git diff → See what changed
    Bash: git revert HEAD → Rollback