Crate apex_spec 

APEX Spec (v1.1)

APEX (Agent Planning & Execution Specification) is a deterministic, human-readable planning DSL for structuring LLM reasoning, tool invocation sequences, and validation gates.

This crate provides the reference implementation of the APEX v1.1 grammar, parser, validator, and interpreter.

Core APIs

Parse entire document

use apex_spec::parse_full;

let input = r#"
TASK
Fix search parameter

GOALS
Improve recall

PLAN
Scan code
Fix param
Run tests

CONSTRAINTS
no_mocks

VALIDATION
cargo test

TOOLS
code_search "query"

META
version=1.1
"#;

let plan = parse_full(input).unwrap();
println!("Task: {}", plan.task);

Parse & validate only

use apex_spec::parse_and_validate;

let validated = parse_and_validate("TASK\nDo something").unwrap();
assert_eq!(validated.task.line, "Do something");

Access execution plan

use apex_spec::{ExecutionPlan, ExecutionStep, parse_full};

let plan = parse_full("TASK\nBuild feature\nPLAN\nStep 1\nStep 2").unwrap();
for step in &plan.steps {
    println!("Step: {}", step.description);
}

Prompts for LLMs

Embedded prompts for generating and executing APEX:

• prompts::APEX_GENERATOR_V1_1 - Converts natural language to APEX documents
• prompts::APEX_EXECUTOR_V1_1 - Executes APEX documents step-by-step
• prompts::APEX_SPEC_V1_1 - The v1.1 specification addendum

These define the full LLM-side behavior required to produce or execute APEX documents safely and deterministically.

use apex_spec::prompts::{APEX_GENERATOR_V1_1, APEX_EXECUTOR_V1_1};

// Prepend to user query for APEX generation
let generator_prompt = format!("{}\n\n{}", APEX_GENERATOR_V1_1, "Fix the search bug");

// Prepend to APEX document for execution
let apex_document = "TASK\nDo something";
let executor_prompt = format!("{}\n\n{}", APEX_EXECUTOR_V1_1, apex_document);

Parse Modes

• ParseMode::Strict - Exact EBNF compliance (v1.0 behavior)
• ParseMode::Tolerant - Repairs lowercase headers, records fixes

use apex_spec::{parse_str_with_mode, ParseMode};

let input = "task\nDo something\nplan\nStep 1";
let result = parse_str_with_mode(input, ParseMode::Tolerant).unwrap();
assert!(!result.fixes.is_empty()); // Recorded header case fixes

Constraint Canonicalization

Constraints are normalized to lowercase with underscores:

• “No Mocks” → no_mocks
• “REAL DBS” → real_dbs
• “< 300 LOC” → 300_loc

use apex_spec::canonicalize;

assert_eq!(canonicalize("No Mocks"), "no_mocks");
assert_eq!(canonicalize("REAL DBS"), "real_dbs");

Tool Registry

APEX validates all tools against a fixed registry to prevent hallucinated tool usage:

use apex_spec::{ToolRegistry, validate_with_mode, ValidationMode, parse_str};

let registry = ToolRegistry::new();
assert!(registry.is_valid("code_search"));
assert!(!registry.is_valid("fake_tool"));

// MCP tools (mcp__*) are always valid
assert!(registry.is_valid("mcp__jenkins__build_job"));

Execution State

Models for recording step progress, enabling checkpointing:

use apex_spec::{ExecutionState, StepStatus};

let mut state = ExecutionState::new(3); // 3-step plan
state.step_states[0] = StepStatus::Complete;
state.checkpoint = 1;

Block Types

Block	Required	Description
TASK	Yes	Single-line task description
GOALS	No	Success criteria
PLAN	No	Ordered execution steps
CONSTRAINTS	No	Execution constraints
VALIDATION	No	Post-execution checks
TOOLS	No	Tool declarations
DIFF	No	Expected file changes
CONTEXT	No	Pre-loaded context
META	No	Metadata key-value pairs

Precedence

CONSTRAINTS > TASK > GOALS > PLAN > CONTEXT

Constraints always win in conflict resolution.

Validation Modes

• ValidationMode::Strict - Requires version, rejects unknown tools
• ValidationMode::Lenient - Warns but allows unknown tools
• ValidationMode::Legacy - v1.0 behavior, no version required

This crate is dependency-free and designed for integration with any agent runtime.

Re-exports

pub use ast::ApexDocument;

pub use ast::Block;

pub use ast::BlockKind;

pub use ast::Span;

pub use errors::ApexError;

pub use errors::ApexErrorKind;

pub use errors::ApexResult;

pub use interpreter::ExecutionPlan;

pub use interpreter::ExecutionStep;

pub use interpreter::ExecutionState;

pub use interpreter::StepStatus;

pub use interpreter::ToolInvocation;

pub use interpreter::build_execution_plan;

pub use parser::parse_str;

pub use parser::parse_str_with_mode;

pub use parser::ParseMode;

pub use parser::ParseFix;

pub use prompts::APEX_GENERATOR_V1_1;

pub use prompts::APEX_EXECUTOR_V1_1;

pub use prompts::APEX_SPEC_V1_1;

pub use sem::Constraint;

pub use sem::Precedence;

pub use sem::Semantics;

pub use sem::normalize_constraint;

pub use sem::canonicalize;

pub use tool_registry::ToolRegistry;

pub use tool_registry::VALID_TOOLS;

pub use tool_registry::extract_tool_name;

pub use validate::ValidatedDocument;

pub use validate::validate;

pub use validate::validate_with_mode;

pub use validate::DiffFormat;

pub use validate::ValidationMode;

Modules

ast

APEX Abstract Syntax Tree

errors

APEX Error Types

interpreter

APEX Interpreter

parser

APEX Parser Module

prompts

APEX Prompts Module

sem

APEX Semantics

tool_registry

APEX Tool Registry

validate

APEX Validator

Constants

APEX_MIN_VERSION

Minimum supported APEX version

APEX_VERSION

APEX format version supported by this crate

Functions

parse_and_validate

Parse and validate APEX input in one call

parse_full

Full pipeline: parse → validate → interpret