ape-lang 1.0.3

A deterministic AI-first programming language for unambiguous human-AI collaboration

Ape — A Deterministic AI-First Programming Language

Ape is a programming language designed for AI and humans to communicate unambiguously.

---

Why Ape Exists

Traditional programming languages allow ambiguity—multiple interpretations of the same code, implicit behavior, and "magic" that confuses both humans and AI systems. This creates a fundamental problem:

AI and humans often miscommunicate because conventional languages were not designed for deterministic collaboration.

Ape solves this by:

• Removing ambiguity with explicit syntax and deterministic semantics
• Predictable module resolution with a strict, ordered search path
• Clear error messages when something is unclear (no guessing)
• Dual-purpose design: Ape works both as a translator layer (human/AI → Python) and as a standalone language growing toward its own runtime

Two Roles, One Language

1. Translator Layer (Bridge Language)
Ape translates human/AI intent into target languages (currently Python). AI models can generate Ape code reliably because the syntax is unambiguous and the compiler enforces correctness.

2. Standalone Language
Ape is evolving into a complete language with its own module system, standard library, type system, and (eventually) bytecode VM.

---

Status: v1.0.3

Ape v1.0.3 is a stability release with critical control flow bug fixes and comprehensive testing guarantees documentation.

Author: David Van Aelst

✅ Production-Ready Features

Core Compiler

• Lexer & Parser - Tokenizes and parses Ape source files into AST
• Module system - module <name> declarations for importable files
• Import system - import <module> statements with deterministic resolution
• Linker - Resolves dependencies, builds module graph, detects circular imports
• Semantic validator - Type checking, symbol resolution, constraint validation
• Code generator - Generates Python code with name mangling for modules

Standard Library (Pure Modules)

Four core modules in ape_std/:

• logic - Boolean operations and conditionals
• strings - String manipulation and formatting
• collections - List/collection operations (count, filter, map)
• math - Arithmetic operations (add, subtract, multiply, divide, power, abs, sqrt, factorial)

Testing & Examples

• 611 tests (539 passing, 72 skipped) - Full coverage of parser, linker, codegen, stdlib, runtime, observability, introspection, multi-language, control flow, tuples, and tutorials
• Working examples - hello_imports, stdlib_complete, custom_lib_project
• Tutorial scenarios - 9 realistic scenarios with 46 enriched tests (AI governance, Anthropic/LangChain/OpenAI integration, risk classification, etc.)
• Documentation - Complete specs for modules, stdlib, runtime, multi-language, and philosophy

See docs/APE_TESTING_GUARANTEES.md for details on what these tests guarantee.

Control Flow & Runtime

• If/else if/else - Conditional branching
• While loops - Iteration with condition
• For loops - Iteration over iterables
• AST-based runtime - Executes control flow without Python exec()
• Sandbox-safe execution - No filesystem, network, or environment access
• Iteration limits - Safety guards against infinite loops

Runtime Observability & Safety

• Execution Tracing - Non-intrusive observation of program execution
• Dry-Run Mode - Safe analysis without mutations or side effects
• Capability Gating - Fine-grained control over side effects and resource access
• TraceCollector - Record enter/exit events with context snapshots
• Deterministic - Same input → same trace, reproducible across executions

Explainable & Replayable Execution

• Explanation Engine - Converts traces into human-readable explanations
• Replay Engine - Validates deterministic execution without re-executing code
• Runtime Profiles - Predefined configurations (analysis, execution, audit, debug, test)
• Fully deterministic - No LLM, pure trace interpretation
• Governance-ready - Complete observability, explainability, and reproducibility

Multi-Language Surface Syntax

• One APE Language, Many Surfaces - Write APE using keywords from your native language
• Supported Languages - English (canonical), Dutch, French, German, Spanish, Italian, Portuguese
• Latin Script Only - v1.0.3 supports Latin-based languages
• Deterministic Normalization - All languages produce identical AST and runtime behavior
• Keyword-Only Translation - Identifiers and literals remain unchanged

🏗️ Scaffolded Features (Structure Complete, Implementation Pending)

These features have complete module structure, documentation, and test skeletons, but return NotImplementedError until future implementation.

Exception Handling (v0.4.0 roadmap)

• Try/Catch/Finally - Structured exception handling
• User-Defined Errors - Raise custom errors with messages
• Error Propagation - Exception propagation through call stack
• Documentation: docs/error_model.md

Structured Types (v0.4.0 roadmap)

• List - Generic typed lists
• Map<K,V> - Generic typed maps/dictionaries
• Record - Named field structures
• Tuple - Fixed-size heterogeneous collections
• Type Inference - Automatic type deduction
• Documentation: docs/typesystem.md

Expanded Standard Library (v0.5.0 roadmap)

• JSON Module - Parse, stringify, path-based access
• Extended Math - Trigonometry, logarithms, rounding (sin, cos, log, floor, ceil, PI, E)
• Extended Collections - reduce, reverse, sort, zip, enumerate, range
• Documentation: docs/stdlib_json.md, docs/stdlib_math_ext.md

Compiler Backend & VM (v0.6.0 roadmap)

• Optimizer - Constant folding, dead code elimination, CSE, loop unrolling, TCO
• Bytecode VM - Stack-based virtual machine with 30+ opcodes
• Compilation Pipeline - Parse → Optimize → Bytecode → Execute
• Benchmarking - Performance measurement infrastructure
• Documentation: docs/compiler_optimization.md, docs/bytecode_vm.md, docs/performance_tuning.md

Note on Scaffolded Features: These features have complete architecture and documentation. Calling them returns NotImplementedError with clear messages. Enable them by implementing the stub methods according to the provided specifications.

• See: Multi-Language Documentation

✅ Standard Library (Pure, Deterministic Core)

• Pure functions - No side effects, deterministic behavior
• Runtime intrinsics - Built into executor, no capabilities needed
• Four modules - logic, collections, strings, math (22 functions total)
• Full type safety - Clear error messages for invalid inputs
• See: Standard Library Documentation

🚧 Not Yet Implemented

• Exception handling (try/catch constructs)
• Structured types beyond basics (lists, maps, records)
• JSON parsing and serialization
• Type system beyond basic types
• Ape bytecode VM
• Package manager

See docs/ROADMAP.md for the complete roadmap with status per version.

---

Test Coverage

✅ 539 passing, 72 skipped

• Total tests: 611 (539 passing + 72 skipped)
• Last verified via pytest from package directory

See docs/APE_TESTING_GUARANTEES.md for what these tests guarantee.

The test suite covers:

• Parser and lexer (tokenization, AST generation)
• Linker and module resolution
• Code generator and Python transpilation
• Standard library (logic, strings, collections, math)
• Runtime execution and control flow (if/while/for)
• Observability (tracing, explanation, replay)
• Introspection and runtime profiles
• Multi-language support (7 languages)
• Tuple returns and list operations
• Tutorial scenarios and integration tests

To verify test counts:

pytest packages/ape/tests --collect-only -q

---

Standard Library (Pure Core)

APE includes a foundational standard library with pure, deterministic functions:

std.logic - Boolean logic and assertions

std.logic.assert_condition(age >= 18, "Must be adult")
std.logic.all_true([True, 1, "yes"])  # True
std.logic.any_true([False, 0, 1])     # True

std.collections - Collection operations

std.collections.count([1, 2, 3])                    # 3
std.collections.filter_items([1, 2, 3], lambda x: x > 1)  # [2, 3]
std.collections.map_items([1, 2, 3], lambda x: x * 2)     # [2, 4, 6]

std.strings - String manipulation

std.strings.lower("HELLO")                  # "hello"
std.strings.trim("  hello  ")               # "hello"
std.strings.starts_with("hello", "he")      # True

std.math - Mathematical operations

std.math.abs_value(-42)           # 42
std.math.clamp(15, 0, 10)         # 10
std.math.sum_values([1, 2, 3])    # 6

Characteristics:

• ✅ Pure (no side effects)
• ✅ Deterministic (same input → same output)
• ✅ Type-safe (clear error messages)
• ✅ Traceable (all calls visible in execution logs)
• ✅ No capabilities required

See: docs/stdlib.md for complete documentation

---

Multi-Language Input — One Language, Many Surfaces

APE supports writing code using keywords from multiple languages. All languages normalize to canonical APE and produce identical execution:

# English (canonical)
if x > 5:
    - set y to 10

# Dutch (Nederlands)
als x > 5:
    - set y to 10

# French (Français)
si x > 5:
    - set y to 10

# German (Deutsch)
wenn x > 5:
    - set y to 10

All produce the same AST and runtime behavior.

Usage:

from ape import run

# Dutch
result = run("""
als x > 5:
    - set result to x * 2
""", context={'x': 10}, language='nl')

# French
result = run("""
si x > 5:
    - set result to x * 2
""", context={'x': 10}, language='fr')

Supported: EN, NL, FR, DE, ES, IT, PT (Latin script only)
See: docs/multilanguage.md for full details

---

Syntax Examples

Example 1: Hello World

module main

import sys

task main:
    inputs:
        none
    outputs:
        success: Boolean
    constraints:
        - deterministic
    steps:
        - call sys.print with "Hello from Ape!"
        - return success

Example 2: Control Flow

module main

import sys

task classify_number:
    inputs:
        x: Integer
    outputs:
        result: String
    constraints:
        - deterministic
    steps:
        if x < 0:
            - set result to "negative"
        else if x == 0:
            - set result to "zero"
        else:
            - set result to "positive"
        - call sys.print with result
        - return result

Example 3: Loops

module main

import sys

task count_and_sum:
    inputs:
        max_count: Integer
    outputs:
        total: Integer
    constraints:
        - deterministic
    steps:
        - set count to 0
        - set total to 0
        
        while count < max_count:
            - set total to total + count
            - set count to count + 1
        
        - call sys.print with total
        - return total

Example 4: Using Math

module main

import sys
import math

task main:
    inputs:
        a: Integer
        b: Integer
    outputs:
        success: Boolean
    constraints:
        - deterministic
    steps:
        - call math.add with a and b to get x
        - call sys.print with x
        - return success

Example 5: Custom Libraries

Ape resolves imports using a deterministic search order. Create a project structure:

project/
├── main.ape
└── lib/
    └── tools.ape

lib/tools.ape:

module tools

import sys

task log_message:
    inputs:
        message: String
    outputs:
        success: Boolean
    constraints:
        - deterministic
    steps:
        - call sys.print with message
        - return success

main.ape:

module main

import tools

task main:
    inputs:
        none
    outputs:
        success: Boolean
    constraints:
        - deterministic
    steps:
        - call tools.log_message with "Hello from custom library!"
        - return success

When main.ape imports tools, the linker searches:

1. ./lib/tools.ape ← Found here
2. ./tools.ape
3. <APE_INSTALL>/ape_std/tools.ape

First match wins. If not found → compile error.

---

---

How Ape Works

Ape compiles source files through a deterministic pipeline:

1. Parse

Ape source files (.ape) are tokenized and parsed into an Abstract Syntax Tree (AST).

2. Link

The linker resolves all import statements using a strict, deterministic order:

Resolution Order:

1. ./lib/<module>.ape - Local project library (highest priority)
2. ./<module>.ape - Same directory as importing file
3. <APE_INSTALL>/ape_std/<module>.ape - Standard library (lowest priority)

First match wins. If no match found → compile error with clear message.

The linker:

• Builds a complete dependency graph
• Detects circular dependencies (e.g., a imports b, b imports a)
• Returns modules in topological order (dependencies first)

3. Validate

The semantic validator checks:

• Symbol resolution (all referenced types exist)
• Type correctness
• Constraint validation
• Policy adherence

4. Generate Code

The code generator produces target language code (currently Python):

• Name mangling: math.add becomes math__add in Python
• Module separation: Each Ape module generates a separate Python file
• Deterministic output: Same Ape code → same Python code every time

5. Backend: Python (Current)

Ape currently compiles to Python. Generated code is:

• Syntactically correct Python
• Type-hinted with dataclasses for entities
• Executable without runtime dependencies (beyond Python stdlib)

Long-term Goal: Ape VM

Future versions will compile to Ape bytecode and run on an Ape VM, making Python an optional backend.

---

Installation

From PyPI

pip install ape-lang

From Source

git clone https://github.com/Quynah/Ape.git
cd Ape
pip install -e .

Verify Installation

ape --version

---

Basic Commands

Validate Ape Source

ape validate main.ape

Runs the full compiler pipeline up to validation (parse → link → validate).

Compile to Python

ape build main.ape --target=python

Generates Python code in generated/ directory.

Parse Only (Debug)

ape parse main.ape

Outputs AST for inspection.

IR Only (Debug)

ape ir main.ape

Outputs Intermediate Representation (IR) as JSON-like structure.

---

---

Ape Standard Library v0.1

Ape v0.2.0 includes three core modules in the standard library (ape_std/):

sys - System Operations

task print:
    inputs:
        message: String
    outputs:
        success: Boolean
    constraints:
        - deterministic

Prints a message to stdout.

task exit:
    inputs:
        code: Integer
    outputs:
        success: Boolean
    constraints:
        - deterministic

Exits the program with the given status code.

io - Input/Output Operations

task read_line:
    inputs:
        prompt: String
    outputs:
        line: String
    constraints:
        - deterministic

Reads a line from stdin with an optional prompt.

task write_file:
    inputs:
        path: String
        content: String
    outputs:
        success: Boolean
    constraints:
        - deterministic

Writes content to a file at the specified path.

task read_file:
    inputs:
        path: String
    outputs:
        content: String
    constraints:
        - deterministic

Reads the entire contents of a file.

math - Mathematical Operations

Basic arithmetic (all work with Integer type):

• add(a: Integer, b: Integer) → result: Integer
• subtract(a: Integer, b: Integer) → result: Integer
• multiply(a: Integer, b: Integer) → result: Integer
• divide(a: Integer, b: Integer) → result: Float
• power(base: Integer, exponent: Integer) → result: Integer
• abs(x: Integer) → result: Integer
• sqrt(x: Float) → result: Float
• factorial(n: Integer) → result: Integer

All math operations are marked as deterministic.

Usage example:

module main

import math
import sys

task demo:
    inputs:
        none
    outputs:
        success: Boolean
    constraints:
        - deterministic
    steps:
        - call math.add with 5 and 3 to get sum
        - call math.multiply with sum and 2 to get result
        - call sys.print with result
        - return success

---

---

Roadmap

Current Version: v1.0.3 (Stability Release)

APE has achieved its v1.0 specification freeze with a complete minimal language. The roadmap documents the actual implementation status across all versions.

Completed Versions

Version	Focus	Status
v0.2.0	Modules, imports, linker, stdlib v0.1	✅ Complete
v0.3.0	Control flow, runtime, observability	✅ Complete
v1.0.0	Complete language release (includes multi-language + roadmap scaffolds)	✅ Complete
v1.0.3	Stability release (while loop fix, +16 tests, testing guarantees)	✅ Complete

Planned Versions

Version	Focus	Status
v0.4.0	Error model + structured types	🚧 Planned Q1 2026
v0.5.0	Expanded stdlib (JSON, advanced math)	🚧 Planned Q2 2026
v0.6.0	Compiler optimizations, bytecode VM	🚧 Planned Q3 2026

See docs/ROADMAP.md for complete version history, implementation details, and future directions.

What APE v1.0.3 Includes

• ✅ Control flow - if/else if/else, while, for loops
• ✅ Expressions - Arithmetic, comparison, logical operators
• ✅ Module system - Deterministic resolution, imports, linker
• ✅ AST-based runtime - No exec/eval, sandbox-safe, deterministic
• ✅ Observability - Tracing, dry-run, capabilities, explanation, replay, profiles
• ✅ Standard library - 4 pure modules (logic, strings, collections, math) + 3 capability modules (sys, io, math)
• ✅ Multi-language - 7 languages (EN, NL, FR, DE, ES, IT, PT), keywords-only translation
• ✅ Tutorials - 8 realistic scenarios with comprehensive test coverage
• ✅ 611 tests passing - No regressions, full coverage

For Early Adopters

APE v1.0.3 is ready for:

• Writing deterministic decision logic (AI safety, governance, policy)
• Multi-language syntax support (write APE in your native language)
• Full observability (trace, explain, replay execution)
• Realistic tutorial examples (not toy demos)
• Production-ready test coverage (595 tests, all passing)

Tutorial Scenarios:

• AI Input Governance (GDPR compliance, multi-factor validation)
• APE + Anthropic (3-tier safety classification)
• APE + LangChain (workflow validation with cascading checks)
• APE + OpenAI (request governance with code execution blocking)
• Dry-Run Auditing (safe analysis with high-risk scoring)
• Explainable Decisions (4-tier risk rating)
• Multilanguage Team (EN/NL examples with manual override)
• Risk Classification (3-tier with account age factor)

See tutorials/ directory for complete scenario implementations.

---

Philosophy

Ape is built on four core principles:

1. Determinism Over Cleverness

Same input → same output, always. No hidden state, no implicit behavior, no "magic."

Bad (ambiguous):

maybe do something

Good (explicit):

task do_something:
    inputs:
        condition: Boolean
    outputs:
        result: String
    constraints:
        - deterministic
    steps:
        - if condition is true then ...
        - return result

2. No Guessing

If the compiler can't determine what you mean with 100% certainty, it fails with a clear error message.

Example:

LINK ERROR: Module 'utils' not found.

Searched:
  1. ./lib/utils.ape (not found)
  2. ./utils.ape (not found)
  3. <APE_INSTALL>/ape_std/utils.ape (not found)

Did you mean to create 'lib/utils.ape'?

3. AI-Optimized Syntax

Ape's syntax is designed so AI models can generate correct code reliably:

• Unambiguous keywords (task, entity, import)
• Clear structure (indentation-based like Python)
• Explicit types and constraints
• Deterministic compilation rules

4. Explicit Over Implicit

Every dependency, type, and behavior is declared. Nothing is inferred unless absolutely safe.

# Explicit module declaration
module main

# Explicit imports
import sys
import math

# Explicit types
task calculate:
    inputs:
        x: Integer
        y: Integer
    outputs:
        result: Integer
    
    # Explicit constraints
    constraints:
        - deterministic
    
    steps:
        - call math.add with x and y to get result
        - return result

📖 Full philosophy: See docs/philosophy.md

---

---

APE v1.0 Status

Status: ✅ v1.0.3 Released (December 2024)

APE v1.0.3 is a stability release with critical control flow bug fixes, comprehensive testing guarantees documentation, and 16 additional control flow tests.

v1.0 Guarantees

When using APE v1.0.x, you can rely on:

• Backward Compatibility - All v1.0 code runs on v1.x (no breaking changes)
• Stable Public API - compile(), validate(), run(), ExecutionContext, RuntimeExecutor will not change
• Deterministic Execution - Same input → same output, always
• Semantic Versioning - Breaking changes require 2.0.0
• Safety Guarantees - No arbitrary code execution, capability-gated side effects

Current Version: v1.0.3

This is a stability release with control flow bug fixes and comprehensive test coverage (611 passing tests). All core features are complete and working:

• Runtime execution (control flow, tracing, dry-run)
• Observability (tracing, explanation, replay)
• Capability gating and profiles
• Module system and standard library
• Multi-language surface syntax (7 languages)
• Tutorial scenarios (8 realistic examples)

What's Next: Additional planned features (v0.4.0-v0.6.0) include exception handling, structured types, JSON support, and compiler optimizations. See docs/ROADMAP.md.

Documentation for v1.0

📄 v1.0 Documentation

• APE 1.0 Specification - Authoritative language specification (frozen)
• Public API Contract - Stable API guarantees
• Capability-Adapter Boundary - Runtime/adapter separation
• Release Governance - SemVer policy and release process

---

Documentation

📖 Core Documentation

• Philosophy & Design - Why Ape exists and how it works
• Module System Specification - Complete module/import semantics
• Standard Library v0.1 - API reference for sys, io, math
• Documentation Index - Navigate all docs

📁 Examples

• examples/hello_imports.ape - Basic module usage
• examples/stdlib_complete.ape - All stdlib modules
• examples/custom_lib_project/ - Project with local library

🧪 Testing

# Run all tests
pytest tests/ -v

# Run specific test suite
pytest tests/linker/ -v
pytest tests/codegen/ -v

Current Test Status: 439/439 passing ✅

---

Contributing

Ape is under active development. Contributions welcome!

Areas needing help:

• Control flow implementation (if, while, for)
• Type system expansion
• Standard library additions
• VS Code extension
• Documentation improvements

See CHANGELOG.md for version history.

---

License

MIT License

Copyright (c) 2025 David Van Aelst

See LICENSE for full details.

---

Project Status

Current Version: v1.0.3
Status: 🟢 Stable release
Tests: 611/611 passing
Target: v0.4.0+ (Planned enhancements)

Quick Links:

• GitHub Repository
• PyPI Package
• Issue Tracker
• Changelog

---

Ape v0.2.0 — Built for deterministic AI collaboration 🦍