> ## Documentation Index
> Fetch the complete documentation index at: https://ricardovelit.com/axon-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to AXON

> A programming language whose primitives are cognitive primitives of AI

## 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.

<Note>
  AXON is currently in **alpha** status (v0.4.0) with 731 passing tests. The language is under active development.
</Note>

## A Real Example

Here's a complete AXON program that analyzes legal contracts:

```axon theme={null}
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]
    }
}
```

## Architecture Overview

AXON follows a traditional compiler architecture:

```text theme={null}
.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)
```

## 12 Cognitive Primitives

AXON's language constructs map directly to how AI models think:

<CardGroup cols={2}>
  <Card title="persona" icon="user">
    Cognitive identity of the model
  </Card>

  <Card title="context" icon="brain">
    Working memory / session config
  </Card>

  <Card title="intent" icon="bullseye">
    Atomic semantic instruction
  </Card>

  <Card title="flow" icon="diagram-project">
    Composable pipeline of cognitive steps
  </Card>

  <Card title="reason" icon="thought-bubble">
    Explicit chain-of-thought
  </Card>

  <Card title="anchor" icon="anchor">
    Hard constraint (never violable)
  </Card>

  <Card title="validate" icon="check">
    Semantic validation gate
  </Card>

  <Card title="refine" icon="rotate">
    Adaptive retry with failure context
  </Card>

  <Card title="memory" icon="database">
    Persistent semantic storage
  </Card>

  <Card title="tool" icon="wrench">
    External invocable capability
  </Card>

  <Card title="probe" icon="magnifying-glass">
    Directed information extraction
  </Card>

  <Card title="weave" icon="wand-magic-sparkles">
    Semantic synthesis of multiple outputs
  </Card>
</CardGroup>

## Epistemic Type System

AXON implements an epistemic type system based on a partial order lattice, representing formal subsumption relationships:

```text theme={null}
⊤ (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.

<Tip>
  Computations involving `Uncertainty` structurally taint the result, propagating `Uncertainty` forwards to guarantee epistemic honesty throughout the execution flow.
</Tip>

## How AXON 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 | ❌        | ✅        |

## Design Principles

AXON is built on five core 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

## Runtime Self-Healing

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

<Warning>
  The correction loop strictly respects the `refine` limits. If the model fails to heal within permitted attempts, AXON raises a `RefineExhaustedError` to prevent infinite execution loops.
</Warning>

Instead of crashing, the engine re-injects the exact `failure_context` 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.

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/axon-docs/axon-docs/installation">
    Install AXON and set up your development environment
  </Card>

  <Card title="Quickstart" icon="rocket" href="/axon-docs/axon-docs/quickstart">
    Build your first AXON program in minutes
  </Card>
</CardGroup>