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

# Syntax Overview

> Core syntax and structure of the AXON programming language

## Introduction

AXON is a domain-specific language designed for AI agent orchestration. Unlike traditional programming languages, AXON uses **cognitive primitives** rather than mechanical constructs—there are no loops, variables, or assignments. Instead, you define personas, contexts, flows, and semantic constraints.

## File Structure

An AXON program consists of top-level declarations:

```axon theme={null}
// Import statements (optional)
import axon.anchors.{NoHallucination, NoBias}

// Declarations (in any order)
persona LegalExpert { ... }
context LegalReview { ... }
anchor NoHallucination { ... }
type Party { ... }
flow AnalyzeContract(...) { ... }

// Execution
run AnalyzeContract(myContract)
  as LegalExpert
  within LegalReview
```

## Comments

AXON supports single-line comments using `//`:

```axon theme={null}
// This is a comment
persona Analyst {  // inline comment
  domain: ["finance"]
}
```

## Identifiers

Identifiers follow standard programming conventions:

* Start with a letter or underscore
* Contain letters, numbers, and underscores
* Case-sensitive
* Examples: `MyPersona`, `legal_expert`, `_privateFlow`

## Literals

### String Literals

Strings are enclosed in double quotes:

```axon theme={null}
ask: "Extract all parties and obligations"
language: "en"
```

### Numeric Literals

```axon theme={null}
confidence_threshold: 0.85        // Float
max_tokens: 4096                  // Integer
temperature: 0.3                  // Float
```

### Boolean Literals

```axon theme={null}
cite_sources: true
show_work: false
```

### Duration Literals

Durations use numeric values with suffixes:

```axon theme={null}
timeout: 10s    // seconds
timeout: 500ms  // milliseconds
decay: 7d       // days
timeout: 2h     // hours
timeout: 30m    // minutes
```

Valid suffixes: `ms`, `s`, `m`, `h`, `d`

## Collections

### Lists

Lists are enclosed in square brackets:

```axon theme={null}
// String lists
domain: ["contract law", "IP", "corporate"]

// Identifier lists
constrained_by: [NoHallucination, StrictFactual]
refuse_if: [offensive, harmful]
```

### Structured Types

Structured types use curly braces:

```axon theme={null}
type Party {
  name: FactualClaim,
  role: FactualClaim
}
```

## Operators and Symbols

### Delimiters

* `{ }` — Block delimiters for definitions
* `( )` — Parameter and argument lists
* `[ ]` — List literals and collections

### Punctuation

* `:` — Field assignment separator
* `,` — List and parameter separator
* `.` — Dotted references (e.g., `Extract.output`)
* `?` — Optional type marker (e.g., `Opinion?`)

### Special Operators

* `->` — Function return type or conditional action
* `..` — Range operator (e.g., `0.0..1.0`)
* `<>` — Generic type parameters (e.g., `List<Party>`)

### Comparison Operators

Used in validation rules and conditionals:

```axon theme={null}
confidence < 0.80      // less than
confidence > 0.90      // greater than
confidence <= 0.85     // less than or equal
confidence >= 0.75     // greater than or equal
value == expected      // equality
value != invalid       // inequality
```

## Declaration Keywords

These keywords introduce top-level declarations:

| Keyword   | Purpose                            |
| --------- | ---------------------------------- |
| `persona` | Define an AI agent identity        |
| `context` | Define execution environment       |
| `anchor`  | Define hard constraints            |
| `memory`  | Define semantic memory store       |
| `tool`    | Define external capability         |
| `type`    | Define semantic type               |
| `flow`    | Define cognitive pipeline          |
| `intent`  | Define atomic semantic instruction |
| `run`     | Execute a flow                     |
| `import`  | Import declarations from modules   |

## Flow Control Keywords

These keywords are used within flow definitions:

| Keyword       | Purpose                    |
| ------------- | -------------------------- |
| `step`        | Named cognitive step       |
| `probe`       | Targeted extraction        |
| `reason`      | Chain-of-thought reasoning |
| `validate`    | Validation checkpoint      |
| `refine`      | Adaptive retry logic       |
| `weave`       | Semantic synthesis         |
| `use`         | Invoke external tool       |
| `remember`    | Store to memory            |
| `recall`      | Retrieve from memory       |
| `if` / `else` | Conditional branching      |

## Field Keywords

Common fields used in blocks:

| Keyword   | Usage                         |
| --------- | ----------------------------- |
| `given`   | Input specification           |
| `ask`     | Instruction or question       |
| `output`  | Output type specification     |
| `for`     | Target specification (probe)  |
| `into`    | Destination (weave)           |
| `against` | Schema reference (validate)   |
| `about`   | Topic specification (reason)  |
| `from`    | Source specification (recall) |
| `where`   | Constraint predicate          |

## Run Modifiers

Modifiers for `run` statements:

```axon theme={null}
run AnalyzeContract(myContract)
  as LegalExpert              // persona
  within LegalReview          // context
  constrained_by [...]        // anchors
  on_failure: retry(...)      // error handling
  output_to: "report.json"    // output destination
  effort: high                // effort level
```

## Type Annotations

### Basic Types

```axon theme={null}
flow ProcessDoc(doc: Document) -> Summary
```

### Generic Types

```axon theme={null}
output: List<Party>
```

### Optional Types

```axon theme={null}
type Risk {
  score: RiskScore,
  mitigation: Opinion?     // Optional field
}
```

### Range-Constrained Types

```axon theme={null}
type RiskScore(0.0..1.0)
```

### Refined Types

```axon theme={null}
type HighConfidenceClaim where confidence >= 0.85
```

## Dotted References

Reference outputs from previous steps:

```axon theme={null}
step Assess {
  given: Extract.output        // Reference Extract step's output
  ask: "Identify risky clauses"
}

weave [Extract.output, Assess.output] into FinalReport
```

## Expression Patterns

### Single References

```axon theme={null}
given: doc
given: previousStep.output
```

### Multiple Inputs

```axon theme={null}
given: [Extract.output, Assess.output]
```

### Bracketed Lists

```axon theme={null}
probe document for [parties, dates, obligations]
weave [EntityMap, RiskAnalysis] into Report
```

## Common Patterns

### Define and Execute

```axon theme={null}
// Define the flow
flow Analyze(input: Document) -> Report {
  step Extract { ... }
  step Process { ... }
}

// Execute it
run Analyze(myDocument)
  as Analyst
  within Production
```

### Multi-Step Processing

```axon theme={null}
flow Pipeline(data: Input) -> Output {
  step First {
    given: data
    output: IntermediateA
  }
  
  step Second {
    given: First.output
    output: IntermediateB
  }
  
  step Final {
    given: Second.output
    output: Output
  }
}
```

### Conditional Logic

```axon theme={null}
if confidence < 0.5 -> step Retry { ... }
else -> step Accept { ... }
```

## Style Conventions

### Naming Conventions

* **Types and Personas**: PascalCase (`LegalExpert`, `RiskScore`)
* **Flows and Steps**: PascalCase (`AnalyzeContract`, `Extract`)
* **Fields and parameters**: snake\_case (`confidence_threshold`, `max_tokens`)
* **Identifiers in lists**: lowercase when representing concepts (`offensive`, `harmful`)

### Formatting

```axon theme={null}
// Use clear indentation
persona Expert {
  domain: ["law"],
  tone: precise
}

// Break long lists across lines
constrained_by: [
  NoHallucination,
  StrictFactual,
  NoBias
]

// Separate logical sections
flow Analyze(doc: Document) -> Report {
  step Extract { ... }
  
  step Process { ... }
  
  step Synthesize { ... }
}
```

## Next Steps

* [Persona](/axon-docs/axon-docs/language/persona) — Define AI agent identities
* [Context](/axon-docs/axon-docs/language/context) — Configure execution environments
* [Flow](/axon-docs/axon-docs/language/flow) — Build cognitive pipelines
* [Types](/axon-docs/axon-docs/language/types) — Understand AXON's type system