axon-lang 0.12.0

A programming language for AI cognition — compiles to prompts, not machine code.

AXON v0.12.0
A programming language whose primitives are cognitive primitives of AI.

persona · intent · flow · reason · anchor · refine · memory · tool · probe · weave · validate · context
know · believe · speculate · doubt · par · hibernate
dataspace · ingest · focus · associate · aggregate · explore
deliberate · consensus · forge · agent

---

What is AXON?

AXON is a compiled language that targets LLMs instead of CPUs. It has a formal EBNF grammar, a lexer, parser, AST, intermediate representation, multiple compiler backends (Anthropic, OpenAI, Gemini, Ollama), and a runtime with semantic type checking, retry engines, and execution tracing.

It is not a Python library, a LangChain wrapper, or a YAML DSL.

persona LegalExpert {
    domain: ["contract law", "IP", "corporate"]
    tone: precise
    confidence_threshold: 0.85
    refuse_if: [speculation, unverifiable_claim]
}

anchor NoHallucination {
    require: source_citation
    confidence_floor: 0.75
    unknown_response: "Insufficient information"
}

flow AnalyzeContract(doc: Document) -> StructuredReport {
    step Extract {
        probe doc for [parties, obligations, dates, penalties]
        output: EntityMap
    }
    step Assess {
        reason {
            chain_of_thought: enabled
            given: Extract.output
            ask: "Are there ambiguous or risky clauses?"
            depth: 3
        }
        output: RiskAnalysis
    }
    step Check {
        validate Assess.output against: ContractSchema
        if confidence < 0.8 -> refine(max_attempts: 2)
        output: ValidatedAnalysis
    }
    step Report {
        weave [Extract.output, Check.output]
        format: StructuredReport
        include: [summary, risks, recommendations]
    }
}

---

Paradigm Shifts

AXON v0.7 introduces three compiler-level paradigm shifts that elevate the language from prompt compilation to a Cognitive Operating System.

I. Formal Model — Epistemic Constraint Calculus

Each program P in AXON operates over a typed epistemic lattice (T, ≤) where the compiler enforces semantic constraints at compile time. The paradigm shifts extend this with three new formal mechanisms:

Epistemic Scoping Function. Given an epistemic mode m ∈ {know, believe, speculate, doubt}, the compiler applies a constraint function C(m) that maps to a tuple of LLM parameters and auto-injected anchors:

C : Mode → (τ, p, A)
where
  τ ∈ [0,1]    — temperature override
  p ∈ [0,1]    — nucleus sampling (top_p)
  A ⊆ Anchors  — auto-injected constraint set

C(know)      = (0.1, 0.3, {RequiresCitation, NoHallucination})
C(believe)   = (0.3, 0.5, {NoHallucination})
C(speculate) = (0.9, 0.95, ∅)
C(doubt)     = (0.2, 0.4, {RequiresCitation, SyllogismChecker})

This is calculated at compile time — the IR carries the resolved constraint set, so the executor applies them as zero-cost runtime overrides.

Parallel DAG Scheduling. A par block B = {b₁, ..., bₙ} where n ≥ 2 is verified at compile time to have no data dependencies between branches:

∀ bᵢ, bⱼ ∈ B, i ≠ j : deps(bᵢ) ∩ outputs(bⱼ) = ∅

At runtime, branches execute via asyncio.gather, achieving O(max(tᵢ)) latency instead of O(Σtᵢ) for sequential chains.

CPS Continuation Points. A hibernate node generates a deterministic continuation ID via SHA-256(flow_name ∥ event_name ∥ source_position). The executor serializes the full ExecutionState (call stack, step results, context variables) and halts. On resume(continuation_id), the state is deserialized and execution continues from the exact IR node — implementing Continuation-Passing Style at the language level.

II. Design Philosophy — Programming Epistemic States

Traditional LLM frameworks treat every model call identically — the same temperature, the same constraints, the same trust level. This is the equivalent of asking a human to treat brainstorming and sworn testimony with the same cognitive rigor.

AXON rejects this flat model. Epistemic Directives make the confidence state of the AI a first-class construct in the language:

know {
    flow ExtractFacts(doc: Document) -> CitedFact {
        step Verify { ask: "Extract only verifiable facts" output: CitedFact }
    }
}

speculate {
    flow Brainstorm(topic: String) -> Opinion {
        step Imagine { ask: "What could be possible?" output: Opinion }
    }
}

The compiler does not merely label these blocks — it structurally transforms them. A know block injects citation anchors and drops temperature to 0.1, making hallucination a compile-time constraint violation. A speculate block removes all constraints and raises temperature to 0.9, liberating the model.

Parallel Cognitive Dispatch mirrors how human organizations work: delegate independent analyses to specialists concurrently, then synthesize.

Dynamic State Yielding transforms agents from expensive while True loops into event-driven processes that can sleep for days, weeks, or months — then resume with full context. The language handles the serialization; the developer writes hibernate until "event_name" and moves on.

III. Real-World Use Cases

Use Case 1: Legal Document Analysis Pipeline

A law firm needs to analyze contracts with maximum factual rigor, while also exploring creative legal strategies. AXON separates these cognitive modes at the language level:

know {
    flow ExtractClauses(contract: Document) -> ClauseMap {
        step Parse { probe contract for [parties, obligations, penalties] output: ClauseMap }
    }
}

flow AnalyzeRisk(contract: Document) -> StructuredReport {
    par {
        step Financial { ask: "Analyze financial exposure" output: RiskScore }
        step Regulatory { ask: "Check regulatory compliance" output: ComplianceReport }
        step Precedent { ask: "Find relevant case law" output: CaseList }
    }
    weave [Financial, Regulatory, Precedent] into Report { format: StructuredReport }
}

speculate {
    flow ExploreStrategies(report: StructuredReport) -> Opinion {
        step Creative { ask: "What unconventional strategies could mitigate these risks?" output: Opinion }
    }
}

• know guarantees citation-backed extraction (temperature 0.1)
• par runs 3 analyses concurrently, reducing latency by ~3x
• speculate explicitly relaxes constraints for creative strategy exploration

Use Case 2: Multi-Agent Research & Intelligence System

A BI platform deploys autonomous research agents that run for weeks, hibernating between data collection phases:

flow MarketIntelligence(sector: String) -> Report {
    know {
        flow GatherData(sector: String) -> DataSet {
            step Collect { ask: "Gather verified market data" output: DataSet }
        }
    }

    par {
        step Trends { ask: "Identify emerging trends" output: TrendAnalysis }
        step Competitors { ask: "Map competitor landscape" output: CompetitorMap }
    }

    hibernate until "quarterly_data_available"

    doubt {
        flow ValidateFindings(data: DataSet) -> ValidatedReport {
            step CrossCheck { ask: "Challenge every assumption with evidence" output: ValidatedReport }
        }
    }

    weave [Trends, Competitors] into Final { format: Report }
}

• Agent hibernates after initial analysis, costing $0 while waiting
• Resumes automatically when quarterly data arrives (webhook/cron)
• doubt mode forces adversarial validation with syllogism checking

Use Case 3: Autonomous Customer Support with Escalation

A SaaS platform handles support tickets with different confidence requirements and automatic escalation via hibernate:

persona SupportAgent {
    domain: ["product knowledge", "troubleshooting"]
    tone: empathetic
    confidence_threshold: 0.8
}

flow HandleTicket(ticket: String) -> Resolution {
    know {
        flow DiagnoseIssue(ticket: String) -> Diagnosis {
            step Classify { ask: "Classify the issue type and severity" output: Diagnosis }
        }
    }

    believe {
        flow SuggestSolution(diagnosis: Diagnosis) -> Solution {
            step Solve { ask: "Propose a solution based on known patterns" output: Solution }
        }
    }

    if confidence < 0.7 -> hibernate until "human_review_complete"

    step Respond { ask: "Draft customer response" output: Resolution }
}

• know classifies with strict accuracy (no guessing on severity)
• believe suggests solutions with moderate confidence
• Low confidence triggers hibernate — agent sleeps until a human reviews
• Zero compute cost during human review; resumes with full context

IV. Directed Creative Synthesis — the forge Primitive

AXON v0.10 introduces a sixth paradigm shift: mathematical formalization of the creative process inside LLMs.

The industry suffers from a structural limitation: LLMs can interpolate, but they struggle to create. forge addresses this by implementing a compiler-level Poincaré pipeline — the same 4-phase process mathematicians and scientists use when producing genuinely novel work.

Poincaré-Hadamard Creative Pipeline. A forge block orchestrates four sequential phases, each mapped to a distinct LLM configuration:

forge(seed, mode, novelty, depth, branches) → result

Phase 1: PREPARATION   — Expand the seed via context probing
Phase 2: INCUBATION    — Speculative exploration (depth iterations)
Phase 3: ILLUMINATION  — Best-of-N consensus crystallization
Phase 4: VERIFICATION  — Adversarial doubt + anchor validation

Boden Creativity Taxonomy. The mode parameter maps Margaret Boden's three creativity types to concrete LLM parameter overrides at compile time:

B : Mode → (τ, freedom, rule_flexibility)

B(combinatory)      = (0.9,  0.8, 0.3)   — novel recombination of known ideas
B(exploratory)      = (0.7,  0.6, 0.5)   — structured navigation of possibility spaces
B(transformational) = (1.2,  1.0, 0.9)   — rule-breaking synthesis, new paradigms

Novelty Operator K(x|K). The novelty parameter (0.0–1.0) controls the Kolmogorov-inspired tradeoff between utility and surprise. It blends into the effective temperature used during incubation:

τ_eff = τ_base × (0.5 + 0.5 × novelty)

novelty = 0.0 → τ_eff = 0.5 × τ_base  (conservative, high utility)
novelty = 1.0 → τ_eff = 1.0 × τ_base  (maximum divergence, high surprise)

Usage example — Directed Creative Synthesis:

anchor GoldenRatio {
    require: aesthetic_harmony
    confidence_floor: 0.70
}

flow CreateVisualConcept(brief: String) -> Visual {
    forge Artwork(seed: "aurora borealis over ancient ruins") -> Visual {
        mode:        transformational
        novelty:     0.85
        constraints: GoldenRatio
        depth:       4
        branches:    7
    }
}

run CreateVisualConcept("Create a visual concept for a film poster")

What the compiler does:

1. Preparation — expands "aurora borealis over ancient ruins" into a rich conceptual foundation via context probing
2. Incubation — runs 4 iterations of speculative exploration at τ_eff = 1.2 × 0.925 = 1.11, pushing beyond obvious associations
3. Illumination — launches 7 parallel branches, each crystallizing the incubated ideas, then selects the most coherent output (Best-of-N)
4. Verification — applies adversarial doubt against the GoldenRatio anchor, validating that the result is genuinely novel (K(x|K) > 0) and aesthetically balanced

This is not a prompt template. The forge primitive compiles to structured IR metadata that the runtime executes as an orchestrated pipeline — the same precision AXON applies to every other cognitive primitive.

V. Autonomous Goal-Seeking — the agent Primitive

AXON v0.12 introduces a seventh paradigm shift: compiler-verified autonomous agents grounded in the Belief-Desire-Intention (BDI) architecture, epistemic logic, and coinductive semantics.

Every existing LLM framework implements agents as Python classes with ad-hoc while-loops, hidden state machines, and zero formal guarantees. LangChain's AgentExecutor is a runtime artifact — it cannot be statically analyzed, type- checked, or budget-bounded at compile time. AXON's agent primitive makes autonomous goal-seeking a first-class compiled construct with mathematical semantics.

BDI Coinductive Semantics. An agent declaration compiles to a coinductive BDI system — a state machine whose behavior is defined by an infinite observation/transition pair over the epistemic lattice:

Agent ≅ ν X. (S × (Action → X))

where
  S        = Beliefs × Goals × Plans    — cognitive state
  Action   = Observe | Deliberate | Act | Reflect
  ν        = greatest fixpoint (coinduction — runs indefinitely)

The ν (nu) operator is the key: unlike inductive data (finite trees), a coinductive agent is a potentially infinite stream of state transitions, terminating only when the goal is achieved or a budget is exhausted. This formalization is not decorative — it determines the compiler's verification strategy and the executor's loop semantics.

Epistemic Lattice Convergence. At each BDI cycle, the agent's epistemic state is projected onto the same lattice (T, ≤) used by epistemic directives. The deliberation phase produces a state σ ∈ {know, believe, speculate, doubt} and a boolean goal_achieved. The convergence criterion is:

Converge(σ, g) = g = true ∧ σ ≥ believe

Diverge(σ, i, n) = σ = doubt ∧ Δσ = 0 ∧ i ≥ n
  where
    Δσ       = σᵢ - σᵢ₋₁   — epistemic progress between cycles
    i        = current iteration
    n        = stuck_window  — consecutive stagnation threshold

When Converge fires, the agent terminates successfully. When Diverge fires, the on_stuck recovery policy activates — escalate raises AgentStuckError, forge triggers creative re-seeding via the Poincaré pipeline, retry resets and re-attempts.

Budget Composition. Budget constraints compose from the IR into the runtime as a 4-tuple verified at compile time:

B(agent) = (max_iter, max_tokens, max_time, max_cost)

Terminate when: ∃ b ∈ B(agent) : consumed(b) ≥ limit(b)

The compiler rejects agents with unbounded budgets (max_iterations = 0 without an explicit on_stuck policy), preventing runaway execution by construction.

Strategy Dispatch. The strategy parameter selects the BDI loop variant at compile time. Each strategy maps to a specific deliberation/action sequence:

Λ : Strategy → CycleShape

Λ(react)            = Deliberate → Act → Observe
Λ(reflexion)        = Deliberate → Act → Observe → Reflect
Λ(plan_and_execute) = Plan → (Act → Observe)* → Verify
Λ(custom)           = user-defined step sequence

Usage example — Autonomous Research Agent:

persona ResearchAnalyst {
    domain: ["market research", "competitive analysis"]
    tone: analytical
    confidence_threshold: 0.85
}

tool WebSearch {
    provider: serper
    timeout: 10s
}

tool DataAnalyzer {
    provider: internal
    timeout: 30s
}

agent MarketResearcher {
    goal: "Produce a comprehensive competitive analysis report
           with verified data from at least 5 sources"
    tools: [WebSearch, DataAnalyzer]
    strategy: react
    max_iterations: 15
    max_tokens: 50000
    max_cost: 2.50
    on_stuck: forge
    return: CompetitiveReport
}

flow CompetitiveIntelligence(sector: String) -> CompetitiveReport {
    step Research {
        MarketResearcher(sector)
        output: CompetitiveReport
    }
}

run CompetitiveIntelligence("electric vehicles")
    with ResearchAnalyst

What the compiler does:

1. IR Generation — the agent block compiles to an IRAgent node containing goal, tools, budget (15 iter / 50k tokens / $2.50), strategy (react), and recovery policy (forge). The IRAgent is embedded as a step inside IRFlow, preserving compositional semantics.
2. Backend Compilation — the backend (Anthropic, Gemini) generates a CompiledStep with step_name: "agent:MarketResearcher" and full agent metadata in its metadata["agent"] dictionary. The system prompt includes persona traits, tool availability, and epistemic constraints.
3. Runtime Execution — the executor detects agent: prefix and dispatches to the BDI loop. Each cycle: deliberate (epistemic assessment via JSON), act (execute step or invoke tool), observe (update beliefs). The loop respects the budget 4-tuple and applies on_stuck when Diverge fires.
4. Trace Events — every BDI cycle emits STEP_START, MODEL_CALL, and STEP_END trace events, giving full observability into the agent's reasoning trajectory.

Why this matters: The agent is not a Python class that wraps while True. It is a compiled cognitive primitive — the compiler verifies its budget boundedness, the type checker validates its return type, the backend generates strategy-specific prompts, and the runtime executes a formally-defined BDI loop with epistemic convergence criteria. This is the difference between duct-taping an LLM into a loop and engineering an autonomous system with mathematical guarantees.

Agent Use Case 1: Autonomous Legal Research Agent

A law firm deploys an agent that autonomously researches case law until it finds sufficient precedent — or exhausts its budget and escalates to a human attorney:

agent CaseLawResearcher {
    goal: "Find 3+ relevant precedents for the contract dispute
           with verified court citations"
    tools: [WebSearch, PDFExtractor]
    strategy: reflexion
    max_iterations: 20
    max_cost: 5.00
    on_stuck: escalate
    return: CaseLawReport
}

• reflexion strategy adds self-critique after each cycle — the agent evaluates whether its found precedents are truly relevant, not just keyword matches
• on_stuck: escalate means if the agent doubts its findings after 20 cycles, it raises AgentStuckError with full context, so the human reviews exactly where the agent got stuck
• Budget cap of $5.00 prevents runaway API costs — the compiler guarantees termination

Agent Use Case 2: Multi-Agent Data Pipeline

A BI platform chains two agents: one gathers data, the other analyzes it. Both execute within the same compiled flow:

agent DataGatherer {
    goal: "Collect quarterly revenue data from public filings"
    tools: [WebSearch, FileReader]
    strategy: react
    max_iterations: 10
    on_stuck: retry
    return: DataSet
}

agent TrendAnalyzer {
    goal: "Identify year-over-year growth patterns and anomalies"
    tools: [Calculator, DataAnalyzer]
    strategy: plan_and_execute
    max_iterations: 8
    on_stuck: forge
    return: TrendReport
}

flow QuarterlyIntelligence(sector: String) -> TrendReport {
    step Gather { DataGatherer(sector) output: DataSet }
    step Analyze { TrendAnalyzer(Gather.output) output: TrendReport }
}

• Two agents, two strategies: react for data gathering (fast, tool-heavy), plan_and_execute for analysis (structured, plan-then-verify)
• Each agent has independent budget tracking — if DataGatherer costs $0.50, TrendAnalyzer still has its full budget
• If TrendAnalyzer gets stuck, forge triggers creative re-seeding via the Poincaré pipeline, generating novel analytical angles

Agent Use Case 3: Customer Onboarding Agent with Dynamic Recovery

A SaaS platform uses an agent to guide new customers through a personalized onboarding flow, adapting when it gets stuck:

persona OnboardingSpecialist {
    domain: ["product knowledge", "user experience"]
    tone: warm
    confidence_threshold: 0.80
}

agent OnboardingGuide {
    goal: "Complete the customer's onboarding checklist with
           personalized recommendations for their industry"
    tools: [APICall, Calculator]
    strategy: custom
    max_iterations: 12
    max_tokens: 30000
    on_stuck: forge
    return: OnboardingReport

    step Greet { ask: "Welcome the user and assess their goals" }
    step Configure { ask: "Recommend workspace configuration" }
    step Train { ask: "Generate personalized tutorial sequence" }
}

• custom strategy: the agent follows a user-defined step sequence (Greet → Configure → Train), not a generic loop
• on_stuck: forge — if the agent can't personalize recommendations (e.g., unknown industry), it triggers creative synthesis to propose novel onboarding paths instead of failing
• The return: OnboardingReport type is validated by the semantic type checker — the agent must produce a structurally valid report, not just free text

---

Architecture

.axon source → Lexer → Tokens → Parser → AST
                                           │
                              Type Checker (semantic validation)
                                           │
                              IR Generator → AXON IR (JSON-serializable)
                                           │
                              Backend (Anthropic │ OpenAI │ Gemini │ Ollama)
                                           │
                              Runtime (Executor + Validators + Tracer)
                                           │
                              Typed Output (validated, traced result)

28 Cognitive Primitives

Primitive	Keyword	What it represents
Persona	persona	Cognitive identity of the model
Context	context	Working memory / session config
Intent	intent	Atomic semantic instruction
Flow	flow	Composable pipeline of cognitive steps
Reason	reason	Explicit chain-of-thought
Anchor	anchor	Hard constraint (never violable)
Validate	validate	Semantic validation gate
Refine	refine	Adaptive retry with failure context
Memory	memory	Persistent semantic storage
Tool	tool	External invocable capability
Probe	probe	Directed information extraction
Weave	weave	Semantic synthesis of multiple outputs
Know	know	Epistemic scope — maximum factual rigor
Believe	believe	Epistemic scope — moderate confidence
Speculate	speculate	Epistemic scope — creative freedom
Doubt	doubt	Epistemic scope — adversarial validation
Par	par	Parallel cognitive dispatch
Hibernate	hibernate	Dynamic state yielding / CPS checkpoint
DataSpace	dataspace	In-memory associative data container
Ingest	ingest	Load external data into a DataSpace
Focus	focus	Select data — propagate associations
Associate	associate	Link tables via shared fields
Aggregate	aggregate	Group-by aggregation on selections
Explore	explore	Snapshot current associative state
Deliberate	deliberate	Compute budget control (tokens/depth/strategy)
Consensus	consensus	Best-of-N parallel evaluation & selection
Forge	forge	Directed creative synthesis (Poincaré pipeline)
Agent	agent	Autonomous goal-seeking BDI cognitive system

Epistemic Type System (Partial Order Lattice)

Types represent meaning and cognitive state, not just data structures. AXON implements an epistemic type system based on a partial order lattice (T, ≤), representing formal subsumption relationships:

⊤ (Any)
    │
    ├── FactualClaim
    │   └── CitedFact
    │       └── HighConfidenceFact
    │
    ├── Opinion
    ├── Uncertainty   ← propagates upwards (taint)
    └── Speculation
⊥ (Never)

Rule of Subsumption: If T₁ ≤ T₂, then T₁ can be used where T₂ is expected. For instance, a CitedFact can naturally satisfy a FactualClaim dependency, but an Opinion never can. Furthermore, computations involving Uncertainty structurally taint the result, propagating Uncertainty forwards to guarantee epistemic honesty throughout the execution flow.

Content:      Document · Chunk · EntityMap · Summary · Translation
Analysis:     RiskScore(0..1) · ConfidenceScore(0..1) · SentimentScore(-1..1)
Structural:   Party · Obligation · Risk (user-defined)
Compound:     StructuredReport

---

Project Structure

axon-constructor/
├── axon/
│   ├── compiler/
│   │   ├── lexer.py              # Source → Token stream
│   │   ├── tokens.py             # Token type enum (48 keywords)
│   │   ├── parser.py             # Tokens → AST (recursive descent)
│   │   ├── ast_nodes.py          # AST node class hierarchy
│   │   ├── type_checker.py       # Semantic type validation
│   │   ├── ir_generator.py       # AST → AXON IR
│   │   └── ir_nodes.py           # IR node definitions
│   ├── backends/
│   │   ├── base_backend.py       # Abstract backend interface
│   │   ├── anthropic.py          # Claude
│   │   ├── openai.py             # GPT
│   │   ├── gemini.py             # Gemini
│   │   └── ollama.py             # Local models
│   ├── engine/                   # In-memory associative data engine
│   │   ├── symbol_table.py       # Dictionary encoding
│   │   ├── data_column.py        # Columnar storage + inverted index
│   │   ├── association_index.py  # Cross-table link graph
│   │   ├── selection_state.py    # Selection propagation engine
│   │   └── dataspace.py          # Top-level data container
│   ├── runtime/
│   │   ├── executor.py           # Flow execution engine
│   │   ├── data_dispatcher.py    # Data Science IR → engine bridge
│   │   ├── context_mgr.py        # Mutable state between steps
│   │   ├── semantic_validator.py # Output type validation
│   │   ├── retry_engine.py       # Backoff + failure context
│   │   ├── memory_backend.py     # Abstract + InMemoryBackend
│   │   ├── state_backend.py      # CPS persistence (hibernate/resume)
│   │   ├── tracer.py             # 14 event types, JSON trace
│   │   ├── runtime_errors.py     # 6-level error hierarchy
│   │   └── tools/
│   │       ├── base_tool.py      # BaseTool ABC + ToolResult
│   │       ├── registry.py       # RuntimeToolRegistry (cached)
│   │       ├── dispatcher.py     # IR → runtime tool bridge
│   │       ├── stubs/            # 8 tools (6 stubs + 2 real)
│   │       └── backends/         # 3 production backends
│   └── stdlib/                   # Built-in personas, flows, anchors
└── tests/                        # 1030 tests

---

Installation

# From PyPI
pip install axon-lang

# With real tool backends (WebSearch, etc.)
pip install axon-lang[tools]

# Verify
axon version

From Source

git clone https://github.com/bemarking/axon-constructor.git
cd axon-constructor
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[tools,dev]"  # editable install

Required API Keys

Key	For	Get it at
SERPER_API_KEY	WebSearch backend	serper.dev
ANTHROPIC_API_KEY	Claude backend	console.anthropic.com
OPENAI_API_KEY	GPT backend	platform.openai.com
GEMINI_API_KEY	Gemini backend	aistudio.google.com

None are required for development — stubs work without keys.

---

CLI Usage

# Validate syntax: lex + parse + type-check
axon check program.axon

# Compile to IR JSON
axon compile program.axon                     # → program.ir.json
axon compile program.axon --stdout             # pipe to stdout
axon compile program.axon -b openai            # target backend
axon compile program.axon -o custom.json       # custom output path

# Execute end-to-end (requires API key for chosen backend)
axon run program.axon                          # default: anthropic
axon run program.axon -b gemini                # choose backend
axon run program.axon --trace                  # save execution trace
axon run program.axon --tool-mode hybrid       # stub | real | hybrid

# Pretty-print an execution trace
axon trace program.trace.json

# Version
axon version

# Interactive REPL
axon repl

# Introspect stdlib
axon inspect anchors                       # list all anchors
axon inspect personas                      # list all personas
axon inspect NoHallucination               # detail for a component
axon inspect --all                         # list everything

Python API

from axon import Lexer, Parser, TypeChecker, IRGenerator, get_backend

source = open("program.axon").read()
tokens  = Lexer(source).tokenize()
ast     = Parser(tokens).parse()
errors  = TypeChecker(ast).check()
ir      = IRGenerator().generate(ast)
backend = get_backend("anthropic")
result  = backend.compile(ir)

---

Tests

# Full suite
pytest tests/ -v

# By layer
pytest tests/test_lexer.py tests/test_parser.py         # Phase 1: Language core
pytest tests/test_ir_nodes.py tests/test_backends.py     # Phase 2: Compiler
pytest tests/test_executor.py tests/test_retry.py        # Phase 3: Runtime
pytest tests/test_tool_stubs.py tests/test_tool_backends.py  # Phase 4: Tools

Current Status

1030 passed, 0 failures ✅

Phase	Tests	What's covered
1	83	Lexer, Parser, AST, Type Checker
2	164	IR Generator, Compiler Backends
3	115	Executor, Context, Retry, Tracer, Validator
4	88	Tool infra (53) + Real backends (35)
7	56	Paradigm Shifts (epistemic, par, hibernate)
8	69	Data Science Engine (core)
11	22	Forge (creative synthesis pipeline)
12	28	Agent (BDI pipeline + integration)
misc	405	Stdlib, integration, edge cases

---

Tool System

AXON tools bridge compile-time IRUseTool nodes with runtime implementations.

Registry Modes

from axon.runtime.tools import create_default_registry

# Safe for tests — no API calls, no I/O
registry = create_default_registry(mode="stub")

# Real backends where available, stubs elsewhere
registry = create_default_registry(mode="hybrid")

# Only real backends (fails if deps missing)
registry = create_default_registry(mode="real")

Available Backends

Tool	Stub	Real Backend	Requires
WebSearch	✅	Serper.dev (httpx)	SERPER_API_KEY
FileReader	✅	Local filesystem	—
CodeExecutor	✅	subprocess + asyncio	—
Calculator	—	stdlib (real)	—
DateTime	—	stdlib (real)	—
PDFExtractor	✅	—	—
ImageAnalyzer	✅	—	—
APICall	✅	—	—

---

Error Hierarchy

Level 1: ValidationError    — output type mismatch
Level 2: ConfidenceError    — confidence below floor
Level 3: AnchorBreachError  — anchor constraint violated
Level 4: RefineExhausted    — max retry attempts exceeded
Level 5: RuntimeError       — model call failed
Level 6: TimeoutError       — execution time limit exceeded

---

Runtime Self-Healing

AXON features a native self-healing mechanism for L3 Semantic Gates. When the LLM output violates a hard constraint (AnchorBreachError) or fails structural semantic validation (ValidationError), the AXON RetryEngine automatically intercepts the failure.

Instead of crashing or silently failing, the engine re-injects the exact failure_context (e.g., "Anchor breach detected: Hedging without citation") back into the LLM's next prompt. This creates a closed feedback loop where the model adaptively corrects its logic and structurally self-heals in real-time.

Production Guarantees:

• Strict Boundaries: The correction loop strictly respects the refine limits explicitly defined in the execution configuration. If the model fails to heal within the permitted attempts, AXON deterministically raises a RefineExhaustedError (containing the last failed state) to escalate the failure, preventing infinite execution loops.
• Anchor Dependency: The healing capability is directly proportional to the precision of the defined Anchors. AXON provides the robust recovery mechanism, but ambiguous or poorly defined constraints may cause the model to optimize for passing validation syntactically while failing semantically. Clear, logical Anchors are required.

Phase 4: Logic & Epistemic Anchors

AXON includes specialized standard library anchors (Phase 4) explicitly designed to work with the Self-Healing engine to enforce logical structures and epistemic honesty:

• SyllogismChecker: Enforces explicit logical formats using Premise: and Conclusion: markers to guarantee structurally parseable arguments.
• ChainOfThoughtValidator: Requires explicit sequence step markers before resolving a prompt.
• RequiresCitation: Deep verification enforcing academic-style inline citations/URLs blocking unverifiable claims.
• AgnosticFallback: Penalizes unwarranted speculation, forcing the model to explicitly state a lack of information when sufficient data is unavailable.

---

Roadmap

Phase	What	Status
0	Spec, grammar, type system	✅ Done
1	Lexer, Parser, AST, Type Checker	✅ Done
2	IR Generator, Compiler Backends	✅ Done
3	Runtime (7 modules)	✅ Done
4	Standard Library	✅ Done
5	CLI, REPL, Inspect	✅ Done
6	Test Suite, Hardening, Docs	✅ Done
7	Paradigm Shifts (epistemic/par/hibernate)	✅ Done
8	Data Science Engine + Runtime Integration	✅ Done
9	Executor integration + production backends	✅ Done
10	Compute Budget & Consensus (deliberate/consensus)	✅ Done
11	Directed Creative Synthesis (forge)	✅ Done
12	Autonomous Agents (agent BDI primitive)	✅ Done

---

Design Principles

1. Declarative over imperative — describe what, not how
2. Semantic over syntactic — types carry meaning, not layout
3. Composable cognition — blocks compose like neurons
4. Configurable determinism — spectrum from exploration to precision
5. Failure as first-class citizen — retry, refine, fallback are native

---

How it Compares

	LangChain	DSPy	Guidance	AXON
Own language + grammar	❌	❌	❌	✅
Semantic type system	❌	Partial	❌	✅
Formal anchors	❌	❌	❌	✅
Persona as type	❌	❌	❌	✅
Reasoning as primitive	❌	Partial	❌	✅
Native multi-model	Partial	Partial	❌	✅
Epistemic directives	❌	❌	❌	✅
Native parallel dispatch	❌	❌	❌	✅
State yielding / CPS	❌	❌	❌	✅
Compute budget control	❌	❌	❌	✅
Best-of-N consensus	❌	❌	❌	✅
Creative synthesis engine	❌	❌	❌	✅
Compiled autonomous agents	❌	❌	❌	✅
Formal BDI convergence	❌	❌	❌	✅
Budget-bounded agent loops	❌	❌	❌	✅

---

License

MIT

Authors

Ricardo Velit