AILang: Natural Language Programming for the AI Era

Version 0.8.2 | fleetingswallow.com | Execution runtime: AIEX

What is AILang?

AILang is a natural language programming system that lets you write programs in structured English that AI can reliably interpret and execute. It uses RAG (Retrieval-Augmented Generation) architecture to constrain AI operations to known boundaries, enabling production deployment.

Instead of forcing human logic through the bottleneck of artificial syntax, AILang allows you to express computational intent in the same structured natural language you use to think through problems.

AILang vs. Prompt Engineering

Thesis: prompt engineering optimizes a black box by guessing words; AILang exposes the dials so optimization becomes systematic.

Reasoning type is named, not implied. "Think about X" hedges across DEDUCE / TRACE / RETRIEVE / etc., activating ~1,531 neurons. Saying RETRIEVE activates ~865 (43.5% fewer) — and produces better output because the model commits to one pathway instead of hedging. v0.8.0 tests showed typed TRACE reached mechanism-level root causes ("heartbeat timing mismatch") where untyped TRACE stopped at event-level ("firmware update").
Orthogonal axes instead of prose mush. Operation × style × DEPTH × RETRIEVAL_BUDGET are independent knobs. In prose you smash them together ambiguously ("think carefully and creatively but don't speculate").
Composition is first-class. THEN chains, REASONING_CONTEXT accumulators, and EMIT_DIGEST pass structured output between steps. Prompt-engineering pipelines rely on you concatenating strings by hand.
Constraints are formalizable. CONSTRAIN, SUPPRESS, and REALITY_CONTEXT express what the model may not do in a way that can later be checked. Prose "don't do X" is honored or not, with no audit trail.
Programs, not artifacts. AILang is diffable, versionable, testable. Prompts are fragile — change a comma, behavior shifts.

Qualitative Idempotency

LLMs are stochastic — bit-for-bit determinism is impossible. But v0.8.2 deliberately maximises the next-best property: same input + same program produces functionally equivalent output across runs. Same conclusions. Same key findings. Same downstream behavior. We call this qualitative idempotency, and it's the closest LLMs get to deterministic computation.

Five v0.8.2 mechanisms compose to produce it:

Typed reasoning operations commit the model to one neural pathway. Untyped INTELLIGENTLY hedges across DEDUCE / TRACE / RETRIEVE / etc., which means each run can land on a different mixture and produce divergent reasoning chains. DEDUCE always activates the deductive circuit; rerun the same DEDUCE against the same inputs and the conclusions converge.
DEPTH pins compute investment. DEPTH: STANDARD always allocates the standard token budget and pass count — no accidental "the model felt thorough today" variation between runs.
RETRIEVAL_BUDGET pins what knowledge is pulled in. RETRIEVAL_BUDGET: NONE is closed-book; MINIMAL is bounded; runs no longer differ based on which random retrievals happened to fire.
CONSTRAIN and SUPPRESS remove degrees of freedom that would otherwise vary. If SUPPRESS: [SYNTHESIZE] is in scope, the model never chooses to synthesize on one run and not the next.
REASONING_PROFILE and REALITY_CONTEXT declare the active policy explicitly. Two runs always interpret the same program through the same lens, instead of one run treating it as "creative" and another as "analytical".

Together: rerun the same v0.8.2 program against the same inputs and the substantive output — conclusions, recommendations, propagated bindings, contract validity — converges across runs. Surface text wording will vary; load-bearing semantics will not. This is the property that makes v0.8.2 a credible substrate for business systems where decisions need to be reproducible-enough for audit, even when they cannot be deterministic in the bit-exact sense.

Why AILang Exists

Real-world software virtually always requires three interwoven types of thinking:

Logical flow (if-then decisions, loops, data management)
Mathematical computation (calculations, optimizations, physical constraints)
Domain expertise (business rules, industry knowledge, contextual judgment)

The Problem with Using the Traditional Programming Paradigm with AI

The Fundamental Domain Mismatch:

AI operates in a qualitative logic domain—it reasons with concepts, patterns, relationships, and contextual understanding. Traditional programming operates in a quantitative logic domain—it executes precise, discrete operations on explicit data structures.

When we force AI to work within the traditional programming paradigm, we create a constant translation problem. We reduce qualitative reasoning ("this customer seems dissatisfied based on their communication patterns") into quantitative predicates (if sentiment_score < 0.3), execute quantitative operations, then translate back to qualitative outputs. Each domain crossing loses information and constrains what's possible.

This back-and-forth switching between domains means we never fully explore the possibilities of qualitative logic "programming" that should be possible with AI. We limit AI to being a helper that feeds data into traditional code, rather than allowing it to reason directly in its native qualitative domain throughout the entire computational process.

How This Manifests:

The traditional programming paradigm forces developers to fragment naturally unified thought processes, even when working with AI systems:

The Fragmentation Problem:

Logic gets expressed in control structures (if/else, for loops)
Math gets relegated to libraries or external tools
Domain expertise gets buried in comments or external documentation
Business rules become hard-coded magic numbers and brittle conditionals

How This Is "Solved" Today:

Multi-language stacks: Python for logic, R for statistics, SQL for data, JavaScript for UI
Framework proliferation: Different tools for different aspects of the same problem
Abstraction layers: ORMs, middleware, API layers that add complexity while trying to hide it
Documentation overhead: Extensive wikis explaining what the code actually means

The Persistent Problems:

Cognitive context switching: Constantly translating between different syntaxes and paradigms
Lost intent: The "why" disappears in the "how" of implementation
Expertise bottleneck: Domain experts can't directly contribute without learning to code
Maintenance nightmare: Changes require understanding multiple layers and their interactions
Testing complexity: Unit tests for logic, integration tests for systems, but nothing tests whether the business intent is preserved

The AILang Solution: Three Execution Modes

AILang allows programs to exist primarily in the qualitative logic domain and step out to the quantitative logic domain only when needed.

This mirrors how the human mind actually functions: we think in concepts, patterns, and contextual relationships (qualitative), occasionally invoking precise calculation (quantitative) when required, then returning to qualitative reasoning to interpret and apply the results. Rather than forcing everything through quantitative operations, AILang lets computation remain in the mode most natural to the problem.

AILang provides three distinct execution modes, each operating in its natural domain with appropriate guarantees:

1. Typed Reasoning Operations: Qualitative Reasoning at Full Strength

When humans face ambiguous situations, we apply judgment, experience, and creativity—all qualitative reasoning. AILang v0.8 names the type of reasoning explicitly. Six typed operations cover the canonical reasoning patterns; each commits the model to a focused neural pathway with measurable efficiency and quality gains over untyped prompting:

Operation	Purpose
`RETRIEVE`	Factual lookup — find and return known information
`COMPARE`	Side-by-side evaluation of options against criteria
`TRACE`	Causal chain analysis — follow cause→effect or effect→cause
`DEDUCE`	Logical inference from premises using formal rules
`SYNTHESIZE`	Integrate multiple inputs into a unified recommendation
`WEIGH`	Evaluate competing authorities, evidence, or expert opinions

Each operation accepts orthogonal modifiers: a style (INTELLIGENTLY, CREATIVELY, ADAPTIVELY, CONTEXTUALLY), a DEPTH (SHALLOW / STANDARD / THOROUGH / DEEP / EXHAUSTIVE), and a RETRIEVAL_BUDGET (NONE / MINIMAL / STANDARD / FULL).

# Typed reasoning -- the engine commits to one pathway and the
# AIEX runtime routes RETRIEVE to a cheap retrieval-class model.
RETRIEVE customer_history FOR account_id WITH:
    SOURCES: [crm]
    RETRIEVAL_BUDGET: STANDARD
    MUST_INCLUDE: [recent_tickets, lifecycle_stage]
END

# Trace cause-to-effect with thorough depth and constrained sources.
ADAPTIVELY TRACE outage_root_cause FROM incident_timeline WITH:
    DEPTH: THOROUGH
    DIRECTION: BACKWARD
    RETRIEVAL_BUDGET: MINIMAL
    CANNOT_INCLUDE: [speculation_beyond_evidence]
END

# Compose typed operations with THEN -- output of one feeds the next.
RETRIEVE pricing_history FOR product_sku WITH: SOURCES: [market_db] END
    THEN COMPARE current_quote AGAINST pricing_history WITH:
        DIMENSIONS: [margin, win_rate, customer_segment]
    END

INTELLIGENTLY is retained as a fallback for situations where the programmer doesn't yet know which typed op fits — the engine auto-classifies via linguistic pattern matching. Use it freely during exploration; replace it with a typed op once the reasoning shape is clear, and you'll get neuron savings, sharper output, and reproducible behavior for free.

Two more v0.8 features round out the composition story: REASONING_CONTEXT accumulators thread EMIT_DIGEST summaries between pipeline steps so downstream operations consume compressed structured input rather than raw transcripts; and CONSTRAIN lets you graduate restriction (e.g., CONSTRAIN: WEIGH TO "published_clinical_data_only") where v0.8.1's SUPPRESS was binary.

2. DETERMINISTIC Operations: Qualitative Structure with Predictable Flow

Just as humans rely on consistent logical patterns, AILang's deterministic layer provides structured operations in the qualitative domain—though these are more accurately "highly structured AI interpretations" rather than truly guaranteed computation.

# Qualitative logic with predictable structure
SET total_cost TO 0
FOR EACH item IN shopping_cart DO:
    SET total_cost TO total_cost + item.price
    IF item.category EQUALS "electronics" THEN:
        APPLY warranty_option
    END_IF
END_FOR

Stream operators (<<, >>) for input/output, the = assignment operator alongside SET and LET, enhanced pattern matching with MATCH/CASE, and REPEAT loops.

3. CODE Blocks: Stepping Into the Quantitative Domain

When problems require true mathematical precision or algorithmic determinism, AILang explicitly steps out of the qualitative domain into quantitative computation—then returns with results that can be interpreted qualitatively.

# Explicit transition to quantitative domain when needed
EXECUTE_CODE python:
    import numpy as np
    from scipy.optimize import minimize
    
    # Precise mathematical computation in quantitative domain
    result = minimize(
        objective_function,
        initial_guess,
        method='SLSQP',
        constraints=constraints
    )
END_EXECUTE

# Return to qualitative domain with results
SET optimal_parameters TO result.x
INTELLIGENTLY interpret_optimization_results FROM optimal_parameters

Explicit CODE blocks supporting Python, JavaScript, R, and SQL with full deterministic guarantees and seamless integration with AILang variables.

The Key Insight: Most of your program lives in the qualitative domain (modes 1 and 2), stepping into the quantitative domain (mode 3) only when mathematical precision is required, then returning to qualitative reasoning to interpret and apply results. This is how humans actually think.

Core Language Constructs

Build from simple to complex with these fundamental building blocks:

Variables & Arithmetic

Variables in AILang can store both quantitative values and qualitative constructs that set context for AI reasoning:

DO subtotal_example:
    SET prices TO [12.99, 4.50, 7.25]
    # The = operator as alternative to SET
    subtotal = SUM(prices)
    SEND "Subtotal is {subtotal}" TO console
END

Variables as Qualitative Context (New Pattern):

Variables can store rich qualitative constructs that guide AI behavior throughout the program:

# Store execution policy as qualitative context
POLICY:
    MODE = "ai_driven_bidirectional_analysis"
    USER_INTERACTION = "minimal_focused_questions"
    AI_RESPONSIBILITY = "demonstrate_decomposition_and_reintegration"
    METHODOLOGY_SELECTION = "ai_driven_with_rationale"
    TRACING_VISIBILITY = "maximum"
    GAP_ANALYSIS = "automatic"
END

# Store qualitative project characteristics
SET uncertainty_level = "high"  # Guides methodology selection
SET project_type = "research"   # Contextualizes decisions
SET core_purpose = "Build sustainable community platform"  # Sets intention

# These qualitative variables then influence intelligent operations:
IF uncertainty_level EQUALS "high" THEN:
    INTELLIGENTLY select_methodology WITH:
        PREFERENCE: "iterative_hypothesis_testing"
        RATIONALE: "High uncertainty requires systematic learning cycles"
    END
END_IF

Unlike traditional programming where variables hold only data, AILang variables can hold contextual constructs that the AI interpreter uses to understand the program's intent and adapt its behavior accordingly. See the ai_native_project_planning example for extensive use of this pattern.

Stream Operators

Intuitive data flow with input (<<) and output (>>) operators:

# Input from sources
user_data << "input.csv"
weather << "weather_api.com/current"

# Output to destinations  
report >> "output.txt"
notification >> email_system

# Chaining for sequential operations
raw_data << "input.csv"
processed_data << PROCESS(raw_data)
results >> "results.json"
results >> backup_storage

Conditions (IF / ELSE)

DEFINE PROCEDURE apply_discount WITH PARAMETERS [amount]:
    IF amount >= 100 THEN:
        RETURN amount * 0.9
    ELSE:
        RETURN amount
    END_IF
END_PROCEDURE

Loops (FOR EACH, WHILE, REPEAT)

DO count_electronics:
    SET count TO 0
    FOR EACH item IN shopping_cart DO:
        IF item.category EQUALS "electronics" THEN:
            SET count TO count + 1
        END_IF
    END_FOR
    
    # REPEAT loops
    REPEAT 3 TIMES:
        SEND "Processing batch {count}" TO console
    END_REPEAT
END

Pattern Matching (MATCH / CASE)

DEFINE PROCEDURE shipping_cost WITH PARAMETERS [region]:
    MATCH region WITH:
        CASE "US": RETURN 5
        CASE "EU": RETURN 8
        CASE "APAC": RETURN 10
        DEFAULT: RETURN 12
    END_MATCH
END_PROCEDURE

Data I/O (GET / SEND)

DO pipeline:
    GET orders FROM "orders.csv"
    SET avg TO MEAN(orders.total)
    SEND {average_order: avg} TO "reports/daily.json"
END

Intelligent Operations with Bounded Constraints

DO summarize_feedback:
    GET feedback FROM "feedback.csv"
    INTELLIGENTLY assess_customer_sentiment FROM feedback WITH:
        MUST_INCLUDE: [emotion_indicators, satisfaction_level]
        CANNOT_INCLUDE: [personal_information, internal_codes]
        OUTPUT_FORMAT: summary
        MAX_SCOPE: current_quarter_only
    END
    SEND summary TO stakeholders
END

Gap-Filling Syntax

Use ellipsis (...) to indicate where AI should apply intelligence:

GET user_data FROM ...appropriate_data_source
PROCESS information USING ...suitable_analysis_method
RESPOND TO user WITH ...contextually_relevant_message

# Smart defaults that adapt to context
SET response_time TO reasonable_duration FOR current_context
SET message_style TO appropriate_for user_preference

Confidence Levels and Action Authority

Declare confidence and branch based on certainty:

WITH_CONFIDENCE estimate_completion_time:
    IF data_sufficient THEN:
        DECLARE CONFIDENCE high
        RETURN calculated_estimate
    ELSE:
        DECLARE CONFIDENCE low
        RETURN range_estimate
    END_IF
END

# Confidence-based branching
IF CONFIDENT ABOUT risk_assessment THEN:
    PROCEED with_planned_approach
ELSE:
    REQUEST additional_analysis
END_IF

The Qualitative Spectrum

AILang recognizes two types of qualitative phenomena:

Observable Qualitative Phenomena - directly perceivable:

IF room_temperature FEELS uncomfortably_cold THEN:
    ADJUST thermostat
END_IF

Interpretive Qualitative Assessments - requiring judgment:

INTELLIGENTLY assess_team_morale FROM:
    meeting_participation, communication_patterns, delivery_velocity
    OUTPUT: morale_evaluation WITH confidence_level
END

Advanced Features

Code Execution Blocks

Execute actual programming language code for true deterministic computation:

DO complex_calculation:
    # Deterministic setup
    GET sensor_data FROM "readings.csv"
    SET threshold TO 0.95
    
    # CODE block for mathematical precision
    EXECUTE_CODE python:
        import pandas as pd
        import numpy as np
        from sklearn.preprocessing import StandardScaler
        
        # Process with guaranteed mathematical accuracy
        df = pd.DataFrame(sensor_data)
        scaler = StandardScaler()
        normalized = scaler.fit_transform(df)
        outliers = np.where(normalized > threshold)[0]
    END_EXECUTE
    
    # Continue with AILang flow
    SEND outlier_report TO monitoring_system
END

Supported languages: Python, JavaScript, R, SQL

The Qualitative-Quantitative Interface

AILang handles the complex transition between qualitative understanding and quantitative computation:

Simple Computation (Direct Interface)

INTELLIGENTLY assess revenue_health FROM financial_data
# Returns: "strong" (qualitative)

IF revenue_health QUALIFIES_AS "strong" THEN:
    EXECUTE_CODE python:
        growth_rate = 0.15  # Confident single value
    END_EXECUTE
END_IF

Complex Decisions (Parameter Space Exploration)

When qualitative assessment connects to multiple quantitative parameters, explore the parameter space:

INTELLIGENTLY assess market_conditions FROM market_data

EXECUTE_CODE python WITH PARAMETER_SPACE_EXPLORATION:
    # Define parameter ranges based on qualitative assessment
    if market_conditions == "volatile":
        risk_factor = explore_range(0.7, 0.9)
        diversification = explore_range(0.6, 0.8)
    elif market_conditions == "stable":
        risk_factor = explore_range(0.3, 0.5)
        diversification = explore_range(0.2, 0.4)
    
    # Test multiple parameter combinations
    for rf in sample(risk_factor, 20):
        for div in sample(diversification, 20):
            portfolio_value = calculate_portfolio(rf, div)
            log_result(rf, div, portfolio_value)
    
    # Select robust configuration
    optimal = find_stable_region(logged_results)
END_EXECUTE

This explores the parameter space to find robust solutions rather than forcing single-point estimates that may be fragile.

Mathematical Operations

AILang provides comprehensive guidance on when to use CODE blocks for mathematics versus simpler expressions:

Use CODE blocks when:

Operations require guaranteed precision (financial calculations, physics simulations)
Complex algorithms or optimization needed
Performance-critical computation
Specialized mathematical libraries required

Simple expressions work for:

SET result TO (price * quantity) + tax
SET average TO SUM(values) / COUNT(values)
ASSERT energy_in EQUALS energy_out + losses

Domain-specific operations with CODE:

# Physics simulation
EXECUTE_CODE python:
    import scipy.integrate as integrate
    
    # Solve differential equation with guaranteed accuracy
    solution = integrate.odeint(
        equations_of_motion,
        initial_conditions,
        time_points
    )
END_EXECUTE

Universal Space and Accomplishment Systems

A Kantian-inspired framework for modeling journeys through abstract spaces. The key insight: space is not an objective container but the form through which we perceive and experience our passage. Whether moving through physical geography, navigating organizational hierarchies, or progressing through workflows, we don't experience raw coordinates—we experience structured journeys with landmarks, constraints, and meaningful transitions.

Three Space Types:

Physical Space: Geographic navigation representing how a person perceives their passage through the world—not objective coordinates, but the experienced journey with routes, landmarks, and embodied constraints (Kantian: space as the form through which we experience movement)
Process Space: Workflows with states, transitions, and procedural logic—how we perceive progress through procedures
Organizational Space: Hierarchies with positions, authorities, and governance—how we experience our position within structures

Key Concepts:

Formal Structure (A Priori): The fundamental rules and constraints of the space—what must be true before any specific journey begins
Empirical Content (A Posteriori): The actual details and specifics—what we discover through experience
Synthesis (Intelligent Navigation): Combining structure and content to navigate—how we actually move through the space by uniting what must be true with what we encounter
Accomplishment: Actualizing potential into realized outcomes—the journey completed

# Physical journey example - modeling perceived passage, not coordinates
DEFINE_SPACE physical_journey:
    FORMAL_STRUCTURE:
        # What must be true for any journey (a priori)
        origin: "Newcastle"
        destination: "Madrid"
        mode: "flight"
        constraints: [passport_required, booking_needed]
    END_FORMAL
    
    EMPIRICAL_CONTENT:
        # What is discovered through experience (a posteriori)
        # Not lat/long coordinates but perceived options
        flight_options: [...available_flights]
        accommodation: [...hotel_options]
        perceived_distance: "far" # How it feels, not kilometers
        expected_experience: "exciting but tiring"
    END_EMPIRICAL
    
    SYNTHESIS:
        # How the person navigates by combining structure and content
        INTELLIGENTLY select_optimal_route BALANCING:
            cost, duration, comfort, reliability
        END
    END_SYNTHESIS
    
    TRACK_ACCOMPLISHMENT:
        # The journey as experienced progression
        stages: [booked, traveled, arrived]
        current_state: "booked"
    END_TRACK
END_SPACE

Person Entities: Computational Agents with Human-Like Attributes

Person entities are computational models of human agents with cognition, personality, and social dynamics, enabling sophisticated multi-agent simulations where behavior emerges from character interactions.

Important: When using Person entities in detail, load the Person extension specification (AILang_Specification_Person_Extension.md) into your AI system's RAG knowledge base alongside the core specification. This provides the AI with complete details of all Person systems, methods, and behavioral patterns.

Creating People

# Create a person with background and personality
INTELLIGENTLY create_person FROM "London" WITH:
    OUTPUT: alice
    MUST_INCLUDE: [name, background, personality, interaction_system]
    BOUNDS: "fictional but locally plausible"
    HINTS: {name: "Alice Chen", age_range: [25,35], profession: "data analyst"}
END

# Set personality traits (Logos/Energiae/Ethos model)
SET alice.personality.logos.reasoning_style TO "analytical"
SET alice.personality.energiae.drives TO {achievement: 0.8, connection: 0.7}
SET alice.personality.ethos.core_values TO ["integrity", "growth"]

Person Architecture

Each Person has interconnected systems:

Cognitive: Thought processing with qualitative cognitive load ("clear", "manageable", "strained", "overwhelmed"), memory systems (episodic, semantic, procedural), thinking styles
Communication: Speech system with tone, pace, language proficiency using descriptive levels ("native", "fluent", "conversational")
Personality: Three-component model
- Logos: Reasoning style and cognitive patterns
- Energiae: Drives and motivations
- Ethos: Core values and moral frameworks
Social: Interaction systems, group memberships, relationship dynamics
Physical: Embodied properties with qualitative descriptors (energy: "exhausted" to "energized", coordination, sensory capabilities)
Planning: Goal pursuit with adaptive navigation
Economic: Financial awareness and resource management
Identity: Self-concept and social positioning

Multi-Person Simulations

# Example: Team collaboration with emergent dynamics
DO simulate_project_meeting:
    # Create team with different personalities
    INTELLIGENTLY create_person WITH:
        OUTPUT: sophie
        HINTS: {traits: ["detail-oriented", "morning-person"]}
    END
    
    INTELLIGENTLY create_person WITH:
        OUTPUT: james
        HINTS: {traits: ["creative", "night-owl"]}
    END
    
    # Their interactions emerge from personality differences
    SET discussion TO sophie.interact_with_person(james, work_context)
    
    # Natural conflicts arise and resolve
    IF sophie.prefers_morning_meeting AND james.prefers_afternoon THEN:
        # Resolution emerges from their interaction systems
        ADAPTIVELY find_compromise BASED_ON:
            sophie.personality.ethos  # Values efficiency
            james.personality.energiae # Peak creativity afternoon
        END
        # Result: Agree on late morning with coffee
    END_IF
END

Why Person Entities Matter

Emergent Behavior: Actions arise from personality and context, not scripts
Consistency: People remain themselves while adapting to situations
Social Realism: Group dynamics emerge from individual interactions
Explainability: Can trace why someone made a particular choice
Qualitative Modeling: Uses descriptive states rather than arbitrary numeric scales

Matter Entities: Representing Concerns Through Abstraction Levels

Matters represent units of human concern (projects, organizations, issues) that exist across multiple levels of abstraction. A critical insight: a matter cannot be fully defined at its own level of abstraction.

Important: When using Matter entities in detail, load the Matter extension specification (AILang_Specification_Matter_Extension.md) into your AI system's RAG knowledge base alongside the core specification. This provides the AI with complete details of the abstraction hierarchy, corporealisation process, and validation mechanisms.

The Five-Layer Abstraction Hierarchy

Every matter exists within this structure:

PHILOSOPHICAL FOUNDATION: Deepest abstractions about the nature of the concern ("Why do organizations exist?")
CATEGORICAL FRAMEWORK: Patterns and types that define kinds of matters ("This is a legacy modernization project")
INSTANCE: The specific matter as experienced ("Our Q4 platform migration")
COMPONENTS: Concrete parts and mechanisms ("The authentication module", "The finance team")
PRIMITIVES: Atomic facts and singular events ("The 2pm standup on Tuesday", "Sarah's commit at 3:47pm")

Key Principles

Cross-Level Definition: Understanding requires vertical movement between abstraction levels. Same-level operations (tautology, level-characterization, instance-comparison) are insufficient.

Corporealisation: The process of moving from abstract intention to concrete form, crossing abstraction levels.

Memorial Persistence: How completed matters persist as patterns at multiple levels, influencing future instances.

Actor Position: In-system actors (working within the matter) access different levels than on-system actors (observing from outside).

Validation Through Adjacency: Checking coherence requires examining proximate levels, not the target level alone.

# Define a matter with explicit abstraction hierarchy
CREATE_MATTER platform_migration:
    
    PHILOSOPHICAL_FOUNDATION:
        "Systems must evolve or become liabilities"
        "Technical debt compounds over time"
    END_FOUNDATION
    
    CATEGORICAL_FRAMEWORK:
        type: "legacy_modernization"
        pattern: "incremental_refactoring"
        methodology: "strangler_fig"
    END_FRAMEWORK
    
    INSTANCE:
        name: "Q4 Platform Migration"
        context: "Moving from monolith to microservices"
        timeline: "Oct-Dec 2025"
    END_INSTANCE
    
    COMPONENTS:
        modules: ["authentication", "payment", "reporting"]
        teams: ["backend_team", "devops_team", "qa_team"]
        infrastructure: ["kubernetes_cluster", "ci_cd_pipeline"]
    END_COMPONENTS
    
    PRIMITIVES:
        events: [
            {timestamp: "2025-10-01 14:00", action: "kickoff_meeting"},
            {timestamp: "2025-10-15 09:30", action: "first_module_deployed"}
        ]
    END_PRIMITIVES
    
    # Actors positioned at different levels
    ACTORS:
        in_system: [developers, team_leads]
        on_system: [executives, external_consultants]
    END_ACTORS
    
    # Corporealisation process (abstract → concrete)
    CORPOREALISATION_STAGES:
        conceptual: "High-level migration strategy"
        planned: "Detailed module breakdown"
        executing: "Active development and deployment"
        actualized: "New system operational"
    END_STAGES
    
END_MATTER

# Validate across levels
VALIDATE platform_migration THROUGH_ADJACENCY:
    CHECK philosophical_foundation GROUNDS categorical_framework
    CHECK categorical_framework MANIFESTS_IN instance
    CHECK instance DECOMPOSES_TO components
    CHECK components AGGREGATE_FROM primitives
END_VALIDATE

Why Matter Entities Matter

Multi-Level Thinking: Explicitly models how concerns exist across abstraction levels
No Self-Definition Paradox: Respects the principle that things cannot be fully defined at their own level
Actor Perspective: Recognizes that different stakeholders experience matters from different positions
Vertical Dynamics: Understanding and validation require cross-level movement
Practical Implementation: Provides concrete constructs for representing organizational reality

Combining Layers: Real Solutions

The true power of AILang emerges when all execution modes work together:

# Insurance pricing combines all three layers naturally
DEFINE PROCEDURE price_insurance_policy WITH PARAMETERS [applicant]:
    # Logic and domain knowledge interweave naturally
    IF applicant.age > 65 AND applicant.has_pre_existing_conditions THEN:
        # CODE block for mathematical precision from actuarial science
        EXECUTE_CODE python:
            import actuarial_tables as act
            base_risk = act.calculate_risk(
                mortality_tables,
                applicant.age,
                applicant.health_factors
            )
        END_EXECUTE
        
        # Domain expertise expressed directly
        INTELLIGENTLY adjust_for_lifestyle_factors:
            CONSIDER exercise_habits, occupation_risks, family_history
            APPLY industry_best_practices
            ENSURE regulatory_compliance
        END
        
        # More mathematical reality in CODE
        EXECUTE_CODE python:
            premium = price_premium(
                base_risk,
                loadings,
                target_margin
            )
            
            # Assert actuarial soundness
            assert premium * expected_policies > (
                expected_payouts + operational_costs
            )
        END_EXECUTE
    END_IF
END_PROCEDURE

Real-World Application Examples

1. Scientific Diagnosis with Physics

Diagnose why bread isn't rising by testing hypotheses with actual physics:

DEFINE PROCEDURE diagnose_bread_problem WITH PARAMETERS [user_observation]:
    GET description FROM "My bread's been coming out flat and dense lately."
    GET environmental_data FROM kitchen_sensors
    
    # Build testable hypotheses
    SET potential_factors TO []
    
    # Temperature hypothesis with CODE block for precision
    IF kitchen_sensors.temperature != previous_location.temperature THEN:
        EXECUTE_CODE python:
            import math
            
            # Arrhenius equation for yeast activity
            A = 1e10  # Pre-exponential factor
            Ea = 50000  # Activation energy (J/mol)
            R = 8.314  # Gas constant
            
            T1 = kitchen_sensors.temperature + 273.15
            T2 = previous_location.temperature + 273.15
            
            k1 = A * math.exp(-Ea / (R * T1))
            k2 = A * math.exp(-Ea / (R * T2))
            activity_ratio = k2 / k1
        END_EXECUTE
        
        IF activity_ratio < 0.5 THEN:
            RECOMMEND: "Your yeast is working at {activity_ratio*100}% speed. 
                       Try proofing {1/activity_ratio} times longer."
        END_IF
    END_IF
END_PROCEDURE

2. Parameter Space Exploration for Strategic Decisions

Automatically discover patterns and test parameter spaces:

DEFINE PROCEDURE optimize_product_strategy WITH PARAMETERS [market_data]:
    # Intelligent assessment
    INTELLIGENTLY assess_market_conditions FROM market_data
    
    # Explore parameter space rather than point estimates
    EXECUTE_CODE python WITH PARAMETER_SPACE_EXPLORATION:
        import numpy as np
        from itertools import product
        
        # Define ranges based on qualitative assessment
        if market_conditions == "competitive":
            price_range = np.linspace(15, 25, 20)
            marketing_range = np.linspace(0.15, 0.30, 20)
        elif market_conditions == "blue_ocean":
            price_range = np.linspace(30, 50, 20)
            marketing_range = np.linspace(0.05, 0.15, 20)
        
        # Test all combinations
        results = []
        for price, marketing_pct in product(price_range, marketing_range):
            revenue = simulate_revenue(price, marketing_pct, market_data)
            profit = revenue - costs(marketing_pct)
            results.append({
                'price': price,
                'marketing': marketing_pct,
                'profit': profit
            })
        
        # Find robust region (not just optimal point)
        optimal_region = find_stable_high_performance_region(results)
    END_EXECUTE
    
    RETURN strategy_recommendations FROM optimal_region
END_PROCEDURE

3. Group Holiday Simulation with Person Entities

Simulate five friends planning and experiencing a trip with emergent behavior:

# Five friends from Newcastle plan Madrid trip
CREATE group WITH [lee, ayesha, callum, sophie, gavin]

# Each person's traits influence the trip
# Sophie (runner) → dawn runs in Retiro
# Lee (social) → late-night bars  
# Ayesha (vegetarian) → restaurant choices

# Track through Universal Space framework
DEFINE_SPACE madrid_holiday:
    FORMAL_STRUCTURE:
        origin: "Newcastle"
        destination: "Madrid"
        duration: 5 days
        participants: group
    END_FORMAL
    
    EMPIRICAL_CONTENT:
        INTELLIGENTLY populate_with_preferences FROM:
            lee.personality, sophie.personality, ayesha.personality,
            callum.personality, gavin.personality
        END
    END_EMPIRICAL
    
    SYNTHESIS:
        # Natural friction emerges and resolves
        IF venue_too_loud FOR sophie THEN:
            GROUP splits_temporarily
            lee.continues_night
            sophie.returns_for_sleep
            AGREEMENT: "Meet for breakfast"
        END_IF
    END_SYNTHESIS
END_SPACE

# Outputs both structured data and narrative
SEND holiday_report TO "trip_data.json"
SEND holiday_memoir TO "trip_story.md"

4. Organizational Matter Management

Model a complex organizational initiative with full abstraction hierarchy:

CREATE_MATTER digital_transformation:
    PHILOSOPHICAL_FOUNDATION:
        "Organizations must adapt to technological change"
        "Value creation requires alignment across levels"
    END_FOUNDATION
    
    CATEGORICAL_FRAMEWORK:
        type: "enterprise_transformation"
        patterns: ["top_down_strategy", "bottom_up_innovation"]
        governance: "steering_committee"
    END_FRAMEWORK
    
    INSTANCE:
        name: "2025 Digital Transformation Initiative"
        scope: "Customer-facing systems and internal operations"
        stakeholders: [executives, managers, employees, customers]
    END_INSTANCE
    
    COMPONENTS:
        systems: ["CRM_upgrade", "automation_platform", "analytics_suite"]
        teams: ["product", "engineering", "operations", "change_management"]
        processes: ["agile_sprints", "stakeholder_reviews", "training_programs"]
    END_COMPONENTS
    
    PRIMITIVES:
        events: [
            {date: "2025-01-15", type: "kickoff"},
            {date: "2025-02-01", type: "first_sprint"},
            {date: "2025-03-10", type: "pilot_launch"}
        ]
        metrics: [
            {date: "2025-02-28", adoption_rate: 0.23},
            {date: "2025-03-31", adoption_rate: 0.45}
        ]
    END_PRIMITIVES
    
    # Different actors access different levels
    ACTORS:
        executives: {level: "INSTANCE", view: "strategic_overview"}
        managers: {level: "COMPONENTS", view: "operational_detail"}
        employees: {level: "PRIMITIVES", view: "daily_tasks"}
        consultants: {level: "CATEGORICAL", view: "pattern_recognition"}
    END_ACTORS
    
    # Track corporealisation (abstract → concrete)
    CORPOREALISATION:
        stage: "executing"
        progress: {
            conceptual: complete,
            planned: complete,
            executing: 0.45,
            actualized: 0.12
        }
    END_CORPOREALISATION
    
    # Validate coherence across levels
    VALIDATION:
        philosophical_grounds_categorical: true
        categorical_manifests_in_instance: true
        instance_decomposes_to_components: true
        components_aggregate_from_primitives: true
    END_VALIDATION
    
END_MATTER

# Intelligent navigation based on actor position
CONTEXTUALLY guide_action FOR actor POSITIONED_AT level:
    IF level EQUALS "INSTANCE" THEN:
        PROVIDE strategic_guidance
    ELSE IF level EQUALS "COMPONENTS" THEN:
        PROVIDE operational_coordination
    ELSE IF level EQUALS "PRIMITIVES" THEN:
        PROVIDE task_execution_support
    END_IF
END

Why AILang Transforms Development

Rapid Prototyping: Move from idea to working solution without translation overhead
Living Documentation: Code explains itself; business stakeholders can read and verify logic directly
Adaptive Systems: Build systems that intelligently handle unexpected situations while maintaining reliability where needed
Domain Expert Accessibility: Subject matter experts express complex domain logic without learning syntax
Reduced Cognitive Load: Focus on solving problems, not remembering syntax
No Syntax Translation: Express all types of thinking in natural language
No Context Loss: Domain expertise remains visible and executable
No Artificial Separation: Math, logic, and business rules coexist naturally
True Determinism When Needed: CODE blocks provide guaranteed mathematical precision
Explicit Execution Modes: Clear boundaries between deterministic, intelligent, and code-executed operations
Multi-Level Modeling: Person and Matter entities enable sophisticated simulations of human and organizational reality
Parameter Space Exploration: Robust solutions through exploring ranges rather than fragile point estimates

Getting Started

Prerequisites

An AI system with RAG (Retrieval-Augmented Generation) capabilities
The complete AILang specification (AILang_Specification.md) loaded into the AI's knowledge base

For Person Entity Programs:

Load AILang_Specification_Person_Extension.md into the AI's RAG knowledge base when using Person entities in detail

For Matter Entity Programs:

Load AILang_Specification_Matter_Extension.md into the AI's RAG knowledge base when using Matter entities in detail

The extensions provide comprehensive details that enable the AI to properly interpret and execute programs using these advanced features.

Basic Setup

Load the core specification (AILang_Specification.md) into your AI system's knowledge base
If using Person entities in detail, also load AILang_Specification_Person_Extension.md
If using Matter entities in detail, also load AILang_Specification_Matter_Extension.md
Write your program using natural language constructs
Declare any extensions at the top of your program:

# Declare extensions your program uses
EXTENSION "person"
EXTENSION "matter"

# Your program continues...
DO analyze_team_dynamics:
    # Person entity operations...
END

Execute through AI interpretation

Complete Starter Program

# A complete program combining all execution modes
DO analyze_customer_behavior:
    # Deterministic: Load data with stream operators
    customer_data << "customer_transactions.csv"
    
    # CODE: Calculate metrics with guaranteed precision
    EXECUTE_CODE python:
        import pandas as pd
        import numpy as np
        
        df = pd.DataFrame(customer_data)
        average_order = df['amount'].mean()
        
        # Linear regression for trend
        from sklearn.linear_model import LinearRegression
        X = np.array(range(len(df))).reshape(-1, 1)
        y = df['amount'].values
        model = LinearRegression()
        model.fit(X, y)
        trend_slope = model.coef_[0]
    END_EXECUTE
    
    # Intelligent: Understand behavior patterns
    INTELLIGENTLY segment_customers FROM customer_data WITH:
        BASED_ON: [transaction_patterns, timing, product_preferences]
        OUTPUT: customer_segments WITH characteristics
        MUST_INCLUDE: [segment_size, key_behaviors, value_potential]
    END
    
    # Creative: Generate strategies
    FOR EACH segment IN customer_segments DO:
        CREATIVELY design_retention_strategy CONSIDERING:
            segment.characteristics, market_conditions, company_resources
            CONSTRAINTS: [budget_limits, brand_consistency]
        END
    END_FOR
    
    # Deterministic: Output results
    analysis_report >> "customer_analysis.json"
    analysis_report >> stakeholder_dashboard
END

The Paradigm Shift

AILang isn't just another programming language—it's a fundamental rethinking of how humans should interact with computational systems. By aligning with natural human thought patterns and leveraging AI's understanding capabilities, AILang makes programming accessible to anyone who can think logically and express ideas clearly.

AILang represents a major evolution with:

Three explicit execution modes providing the right tool for each computational need
CODE blocks for genuine mathematical determinism
Person entities that model human agents with emergent behavior
Matter entities that represent concerns across abstraction levels
Universal spaces for modeling abstract navigation and accomplishment
Qualitative computing that respects subjective phenomena
Parameter space exploration for robust solutions

The future of programming is understanding qualitative logic—how we actually think—and how to implement these patterns of thought in a predictable manner. It's about recognizing that human reasoning operates primarily through concepts, relationships, and contextual understanding, and building computational systems that can work directly in this domain. AILang is that future, available today.

AIEX: The Execution Runtime

AILang is the language; AIEX is the execution engine that makes it economical to run at scale. AILang predicts neuron savings per typed operation; AIEX realises them by routing each transaction to the right model tier:

Operation type	Default model tier	Why
`RETRIEVE`, `COMPARE`	BERT-class / Haiku-class	Cheap and fast; minimal qualitative generation needed
`TRACE`, `DEDUCE`	Sonnet-class	Mid-range reasoning capability suffices
`WEIGH`, `SYNTHESIZE`	Opus-class	Sophisticated judgment / integration required

DEPTH: DEEP and DEPTH: EXHAUSTIVE escalate one tier; qualitative output schemas escalate BERT to a generative tier.

What you get from AIEX that bare AILang cannot give you:

Pre-execution budget reports. Cost, latency, and routing visible before you spend. A typical four-step program shows ~85% savings vs naive all-Opus baselines.
Five-DIVISION COBOL-style execution plan. Compiler analyses dependencies, detects parallel groups, builds a contract per transaction, and emits an ordered plan you can audit before running.
Dispatch-validate-commit transactions. MUST_INCLUDE / CANNOT_INCLUDE / OUTPUT_FORMAT / RETRIEVAL_BUDGET become validators with severity escalation (CRITICAL / MAJOR / MINOR), retry with reinforced prompts, and rollback on hard failure. Failed transactions don't corrupt state.
EXECUTE_CODE blocks integrated. Code blocks compile to zero-cost local-execution transactions interleaved with reasoning ops; AILang variables marshal in/out automatically.
Auditable execution log. Every variable mutation, every transaction commit/rollback, every contract violation is timestamped for post-run inspection.

AIEX lives in its own repository: github.com/pcoz/aiex. Clone it, install editable with pip install -e . from the project root, and programs in this repo's tests/ run under it as aiex compile <file.ailang> or aiex run <file.ailang>.

License

MIT License - See LICENSE file for details

Documentation

Language Specification: AILang_Specification.md — complete v0.8.2 reference (typed reasoning, depth, retrieval budget, contracts, REASONING_CONTEXT, EXECUTE_CODE)
Person Extension: AILang_Specification_Person_Extension.md — Person entity modeling with cognitive routing
Matter Extension: AILang_Specification_Matter_Extension.md — categorical structures across abstraction levels
Evolution Notes: ailang_evolution_v0.8.md — how v0.8.0 → v0.8.1 → v0.8.2 was driven by test results
Tests: tests/ — executable AILang programs that validate v0.8.2 features (run with AIEX)
Test Results: test_results/ — captured outputs from v0.8.2 validation
Examples: examples/ — domain-oriented AILang programs
AIEX Runtime: github.com/pcoz/aiex — separate project; the execution engine
Archive: archive/ — prior versions (v0.1.0 through v0.8.1) preserved for reference

AILang: Write programs in structured English that AI can reliably interpret and execute. v0.8.2 introduces typed reasoning operations, depth/retrieval-budget control, and qualitative idempotency — making production deployment of AI reasoning systems possible. Pair with the AIEX runtime for multi-tier model routing, contract enforcement, and pre-execution budget reports.

Name		Name	Last commit message	Last commit date
archive		archive
examples		examples
test_results		test_results
tests		tests
.gitignore		.gitignore
AILang_Specification.md		AILang_Specification.md
AILang_Specification_Matter_Extension.md		AILang_Specification_Matter_Extension.md
AILang_Specification_Person_Extension.md		AILang_Specification_Person_Extension.md
AILang_ebook.pdf		AILang_ebook.pdf
LICENSE		LICENSE
README.md		README.md
ailang_evolution_v0.8.md		ailang_evolution_v0.8.md

Latest commit

History

Folders and files

Repository files navigation