AXON Architecture Overview

AXON is built on a three-phase pipeline that transforms cognitive intent into executable AI programs:

Source (.axon) → [Phase 1: Compiler] → AST/IR → [Phase 2: Backend] → Prompts → [Phase 3: Runtime] → Results

Architecture Principles

1. Separation of Concerns

Phase 1 (Compiler): Language-agnostic semantic understanding
Phase 2 (Backends): Model-specific prompt generation
Phase 3 (Runtime): Execution orchestration and validation

2. Cognitive-First Design

Every component speaks the language of intelligence:

No mechanical abstractions: No for loops, no if statements
Semantic nodes only: ReasonChain, ProbeDirective, WeaveNode
Epistemic type system: FactualClaim vs Opinion, not just String

3. Model Agnosticism

The IR (Intermediate Representation) has zero dependencies on any LLM provider:

# IR nodes are pure semantic structures
IRReason(
    about="contract_risks",
    depth=3,
    show_work=True,
    output_type="RiskAnalysis"
)

Backends translate this into Claude, GPT-4, Gemini, or local models.

The Three Phases

Phase 1: Compiler (axon/compiler/)

Transforms source text into a validated Intermediate Representation:

Lexer (lexer.py) — Tokenizes source into a stream of tokens
Parser (parser.py) — Builds a cognitive AST (Abstract Syntax Tree)
Type Checker (type_checker.py) — Validates epistemic type constraints
IR Generator (ir_generator.py) — Lowers AST to model-agnostic IR

Key Outputs: IRProgram with resolved flows, personas, anchors, and types.

Phase 2: Backends (axon/backends/)

Compiles IR into provider-specific prompt structures:

AnthropicBackend — Claude-optimized prompts with extended thinking
GeminiBackend — Google Gemini with system_instruction formatting
OpenAIBackend — (Stub) GPT-4 Chat Completions format
OllamaBackend — (Stub) Local model adaptations

Key Outputs: CompiledProgram with system prompts, user prompts, and tool declarations.

Phase 3: Runtime (axon/runtime/)

Orchestrates execution with validation, retry, and tracing:

Executor — Main orchestrator coordinating all components
SemanticValidator — Enforces epistemic type contracts
RetryEngine — Adaptive retry with failure context injection
Tracer — Records every semantic decision for observability
MemoryBackend — Persistent semantic storage layer

Key Outputs: ExecutionResult with step outputs, validation results, and full trace.

Data Flow

Key Design Patterns

Visitor Pattern (Compiler)

Both the Parser and IR Generator use explicit visitor registries:

_VISITOR_MAP: dict[type, str] = {
    ast.PersonaDefinition: "_visit_persona",
    ast.FlowDefinition: "_visit_flow",
    # ...
}

This enables clear dispatch logic without getattr magic.

Protocol-Based Abstraction (Runtime)

The ModelClient protocol decouples execution from LLM APIs:

class ModelClient(Protocol):
    async def call(
        self,
        system_prompt: str,
        user_prompt: str,
        **kwargs
    ) -> ModelResponse:
        ...

Any implementation (Anthropic, OpenAI, mock) can drive execution.

Continuation-Passing Style (Validation)

Anchor checking and validation use CPS for composable error handling:

def _check_anchors_cps(
    response: ModelResponse,
    on_success: Callable,
    on_failure: Callable
) -> Any:
    if violations:
        return on_failure(violations)
    return on_success()

Component Communication

Compiler → Backend

ir_program: IRProgram = ir_generator.generate(ast)
compiled: CompiledProgram = backend.compile_program(ir_program)

Backend → Runtime

executor = Executor(client=anthropic_client)
result: ExecutionResult = await executor.execute(compiled)

Runtime → Tracing

tracer.emit(TraceEventType.ANCHOR_CHECK, 
            step_name="extract",
            data={"anchor": "NoHallucination"})

File Organization

axon/
├── compiler/          # Phase 1: Language processing
│   ├── lexer.py       # Token stream generation
│   ├── parser.py      # AST construction
│   ├── ast_nodes.py   # Cognitive AST definitions
│   ├── type_checker.py # Epistemic type validation
│   ├── ir_generator.py # IR lowering
│   └── ir_nodes.py    # Model-agnostic IR
├── backends/          # Phase 2: Prompt compilation
│   ├── base_backend.py      # Abstract interface
│   ├── anthropic_backend.py # Claude implementation
│   ├── gemini_backend.py    # Gemini implementation
│   └── ...
└── runtime/           # Phase 3: Execution
    ├── executor.py           # Main orchestrator
    ├── semantic_validator.py # Type enforcement
    ├── retry_engine.py       # Adaptive retry
    ├── tracer.py             # Execution logging
    └── memory_backend.py     # Semantic storage

Next Steps

Compiler Deep Dive

Explore the lexer and parser implementation

Backend Architecture

Learn how prompts are generated

Runtime Execution

Understand the execution pipeline

Compiler

Backends

Runtime

​AXON Architecture Overview

​Architecture Principles

​1. Separation of Concerns

​2. Cognitive-First Design

​3. Model Agnosticism

​The Three Phases

​Phase 1: Compiler (axon/compiler/)

​Phase 2: Backends (axon/backends/)

​Phase 3: Runtime (axon/runtime/)

​Data Flow

​Key Design Patterns

​Visitor Pattern (Compiler)

​Protocol-Based Abstraction (Runtime)

​Continuation-Passing Style (Validation)

​Component Communication

​Compiler → Backend

​Backend → Runtime

​Runtime → Tracing

​File Organization

​Next Steps