Developer Guide

K9-AIF is an architecture-first framework. Before writing code, you design components using ABB contracts, then implement SBBs that extend them. This page covers what you need to know before you start, and how to set up your environment.

Prerequisites

K9-AIF is designed for developers with practical software engineering experience. You do not need to be an AI researcher, but you should be comfortable with the following.

Language and Runtime

• Python 3.11 — required. K9-AIF uses Python 3.11 features and is tested against this version.
• Familiarity with virtual environments (venv), pip, and package management.
• Object-oriented programming — classes, inheritance, abstract base classes.

AI and Agent Concepts

• LLMs — you should understand what a large language model is, how to prompt it, and what an inference call returns. K9-AIF uses Ollama locally by default.
• Agents — you should understand what an AI agent is: a component that receives input, reasons about it (usually via an LLM), and returns a structured output.
• Multi-agent systems — helpful but not required. K9-AIF introduces this through its Router → Orchestrator → Squad → Agent hierarchy.

Architecture and Design

• Familiarity with design patterns — Factory, Strategy, Template Method, Observer. K9-AIF applies these structurally.
• Understanding of separation of concerns — each layer in K9-AIF knows only what is below it, never above.
• YAML configuration — agents and squads are defined in YAML; no hardcoded behavior.

Infrastructure

• SQL basics — K9-AIF persists routing decisions to SQLite (default) or PostgreSQL. You don't need to write SQL, but you should understand schemas and connections.
• Kafka / messaging (optional for production) — the EOC reference example uses Kafka for event routing. Not required to get started.
• Docker / Podman (optional) — the EOC example runs in containers. The framework itself runs without containers.

Environment Setup

1. Clone the Repository

git clone https://github.com/k9aif/k9-aif-framework.git
cd k9-aif-framework

2. Create a Virtual Environment

python3.11 -m venv .venv
source .venv/bin/activate       # Mac / Linux
.venv\Scripts\activate          # Windows

3. Install Dependencies

pip install -r requirements.txt

4. Install the CLI

pip install k9aif

Verify the install:

k9aif verify
k9aif --version

5. Ollama (Local LLM)

K9-AIF uses Ollama as the default LLM provider. Install Ollama and pull a model:

ollama pull llama3.2
ollama pull granite3-dense:2b

The framework config points to Ollama at localhost:11434 by default.

Run the Framework Tests

Confirm everything is wired correctly — no LLM or database needed:

pytest k9_aif_abb/tests/test_framework.py -v
pytest k9_aif_abb/tests/test_intelligent_model_router.py -v

VS Code + Claude Code

K9-AIF is designed to be developed with VS Code and the Claude Code extension. The repository ships with pre-configured context files and hooks that make Claude Code framework-aware.

What's Included

• CLAUDE.md — full architecture reference loaded automatically into every Claude Code session in this project.
• SKILLS.md — 11 step-by-step recipes for the most common tasks: adding agents, squads, routers, validation loops, adapters, and tests.
• Hooks — five post-edit hooks that run automatically on every file save: Python syntax check, YAML validation, ABB test suite, governance check, and docstring check.
• k9aif Plugin — a Claude Code plugin in k9aif-plugin/ that exposes framework skills as slash commands.

Plugin Slash Commands

Load the plugin in a terminal session:

claude --plugin-dir ./k9aif-plugin

Available commands:

• /k9aif:add-agent <AgentName> <AppName> — scaffolds agent YAML, Python class, and test stub
• /k9aif:add-squad <SquadName> <AppName> <Agent1,Agent2> — creates squad YAML with flow steps
• /k9aif:add-validation-loop <AgentName> <AppName> — converts agent to iterative K9ValidationLoopAgent
• /k9aif:add-router <RouterName> <AppName> — scaffolds a custom BaseModelRouter
• /k9aif:add-adapter <ConcernName> <ProviderName> — scaffolds a provider adapter
• /k9aif:inspect <examples/AppName> — inspects SBBs for architectural violations, warnings, and recommendations

Key Concepts Before You Code

ABB vs SBB

Architecture Building Blocks (ABB) live in k9_aif_abb/. They are abstract contracts — interfaces, lifecycle hooks, governance points. You never modify them.

Solution Building Blocks (SBB) live in examples/<AppName>/ or k9_projects/<AppName>/. These are your implementations — agents, squads, orchestrators, routers — that extend the ABBs with domain logic.

The Execution Hierarchy

Event → Router → Orchestrator → Squad → Agents → LLM

Each layer knows only what is below it. Agents do not know about squads. Squads do not know about orchestrators. This decoupling is enforced by convention and validated by /k9aif:inspect.

The Three Rules Every Agent Must Follow

• Always call the LLM via llm_invoke() — never call OllamaLLM directly.
• Always wrap llm_invoke() in a try/except RuntimeError and return a [WARN] dict on failure.
• Never reference squads, orchestrators, or routing in agent code or YAML.

Next Steps

• Full Developer Guide — all 21 sections including patterns, governance, messaging, and testing
• EOC Reference Example — the canonical K9-AIF application: insurance operations with Kafka, PostgreSQL, and Neo4j
• Python API Docs — full pydoc reference for every ABB class
• Architecture Graph — live Neo4j graph of all K9-AIF components and relationships