ape-lang 1.0.6
A deterministic AI-first programming language for unambiguous human-AI collaboration
License: MIT
Requires Python: >=3.11
Keywords: programming-language, compiler, AI, deterministic, CDS, ape

# Ape — A Deterministic AI-First Programming Language

**Ape is a programming language designed for AI and humans to communicate unambiguously.**

---

## Runtime Status

**APE includes a standalone runtime that executes APE programs without requiring a host-language runtime for execution semantics.**

The runtime is a complete execution engine that:
- **Parses and executes .ape files directly** using an AST-based interpreter
- **Implements all standard library functions natively** (JSON, DateTime, Collections, Math, Strings, Logic)
- **Executes decision logic at runtime** (decision tables with DMN hit policies, policy engine, rule engine, constraint checker)
- **Provides deterministic, observable, reproducible execution** with tracing, explanation, and replay capabilities
- **No Python eval/exec dependency** for execution semantics

### How to Run

Execute APE programs using the standalone runtime:

```bash
# Direct execution with input/output
ape run file.ape --input data.json --output result.json

# Execute without input
ape run program.ape

# Validate before running
ape validate file.ape

# Generate Python code (transpiler mode)
ape build file.ape --target python --out-dir generated
```

### Runtime Architecture (High-Level)

```
.ape source file
      ↓
Parser (tokenizer → AST)
      ↓
Validator (semantic + strictness checks)
      ↓
Executor (AST-based interpreter)
      ↓
Result (deterministic output)
```

The runtime supports:
- **Module system:** `import` statements, qualified calls (`std.json.get()`)
- **Control flow:** if/else, while loops, for loops
- **Decision logic:** Decision tables, policies, rules, constraints
- **Observability:** Execution tracing, human-readable explanations, deterministic replay
- **Safety:** Iteration limits, dry-run mode, capability gating

### Runtime Contract

**Input:** JSON data structure (or empty)
**Output:** Deterministic result + execution context
**Errors:** Structured errors with file/line/column information
**Exit codes:**
- `0` — Success
- `1` — Parse error, validation error, or execution error

**Guarantees:**
- Same input → same output (deterministic)
- No network/filesystem access during execution (pure computation)
- Observable execution with complete trace
- Replayable for audit and verification

---

## 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.5

**Ape v1.0.5 is the standalone runtime release with full execution engine and native stdlib.**

**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
- **660 tests (660 passing, 71 skipped)** — Full coverage of compiler, linker, codegen, stdlib, runtime, decision engine, observability, introspection, multi-language, control flow, tuples, and tutorials
- **Zero failures** — Production-ready quality
- **Working examples** — hello_imports, stdlib_complete, custom_lib_project
- **Tutorial scenarios** — 9 realistic scenarios with comprehensive tests (AI governance, Anthropic/LangChain/OpenAI integration, risk classification, etc.)
- **Documentation** — Complete specs for runtime, stdlib, modules, decision engine, and testing guarantees

See [docs/DONE_DEFINITION.md](docs/DONE_DEFINITION.md) for the complete runtime feature checklist.
See [docs/TEST_EVIDENCE.md](docs/TEST_EVIDENCE.md) for detailed test run evidence.

#### 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<T>** - 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](docs/multilanguage.md)

### ✅ 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](docs/stdlib.md)

### 🚧 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](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](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:
```bash
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
```python
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
```python
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
```python
std.strings.lower("HELLO")                  # "hello"
std.strings.trim("  hello  ")               # "hello"
std.strings.starts_with("hello", "he")      # True
```

**std.math** - Mathematical operations
```python
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](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**:

```python
# 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:**
```python
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](docs/multilanguage.md) for full details

---

## Syntax Examples

### Example 1: Hello World

```ape
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

```ape
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

```ape
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

```ape
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`:**
```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`:**
```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.

---

## Decision Engine Validation

The APE Decision Engine is validated through a comprehensive runtime test suite
that verifies semantic correctness beyond parsing.

### Covered Areas

**Runtime Type Evaluation**
- Record literal creation and serialization
- Map and List literal runtime behavior
- Nested structure integrity
- APE → Python type mapping

**DateTime & Duration Semantics**
- UTC-based temporal operations
- Deterministic datetime arithmetic
- ISO-8601 serialization/deserialization
- Comparison operations

**Collection Intelligence**
- Aggregation primitives (group_by, unique, sum/max/min)
- Predicate functions (any_match, all_match)
- Transformations (reduce, sort, reverse)
- Edge case handling (empty lists, None values)

**Nested Data Access**
- Dotted path navigation (json.get)
- Missing path graceful degradation
- Immutable updates (json.set)
- Mixed dict/list structure handling

### Run Validation Tests

```bash
# Full Decision Engine test suite
pytest tests/test_datetime.py tests/test_collections.py tests/test_json_path.py -v

# Individual modules
pytest tests/test_datetime.py -v
pytest tests/test_collections.py -v
pytest tests/test_json_path.py -v
```

**Test Results:** See [../../TEST_RESULTS.md](../../TEST_RESULTS.md) for detailed validation evidence.

---

## Installation

### From PyPI

```bash
pip install ape-lang
```

### From Source

```bash
git clone https://github.com/Quynah/Ape.git
cd Ape
pip install -e .
```

### Verify Installation

```bash
ape --version
```

---

## Basic Commands

### Validate Ape Source

```bash
ape validate main.ape
```

Runs the full compiler pipeline up to validation (parse → link → validate).

### Compile to Python

```bash
ape build main.ape --target=python
```

Generates Python code in `generated/` directory.

### Parse Only (Debug)

```bash
ape parse main.ape
```

Outputs AST for inspection.

### IR Only (Debug)

```bash
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

```ape
task print:
    inputs:
        message: String
    outputs:
        success: Boolean
    constraints:
        - deterministic
```

Prints a message to stdout.

```ape
task exit:
    inputs:
        code: Integer
    outputs:
        success: Boolean
    constraints:
        - deterministic
```

Exits the program with the given status code.

### `io` - Input/Output Operations

```ape
task read_line:
    inputs:
        prompt: String
    outputs:
        line: String
    constraints:
        - deterministic
```

Reads a line from stdin with an optional prompt.

```ape
task write_file:
    inputs:
        path: String
        content: String
    outputs:
        success: Boolean
    constraints:
        - deterministic
```

Writes content to a file at the specified path.

```ape
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:**

```ape
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](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):**
```ape
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.

```ape
# 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`](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](docs/ROADMAP.md).

### Documentation for v1.0

📄 **v1.0 Documentation**
- [APE 1.0 Specification](docs/APE_1.0_SPECIFICATION.md) - **Authoritative language specification (frozen)**
- [Public API Contract](docs/PUBLIC_API_CONTRACT.md) - Stable API guarantees
- [Capability-Adapter Boundary](docs/CAPABILITY_ADAPTER_BOUNDARY.md) - Runtime/adapter separation
- [Release Governance](docs/RELEASE_GOVERNANCE.md) - SemVer policy and release process

---

## Documentation

📖 **Core Documentation**
- [Philosophy & Design](docs/philosophy.md) - Why Ape exists and how it works
- [Module System Specification](docs/modules_and_imports.md) - Complete module/import semantics
- [Standard Library v0.1](docs/stdlib_v0.1.md) - API reference for sys, io, math
- [Documentation Index](docs/README.md) - Navigate all docs

📁 **Examples**
- [examples/hello_imports.ape](examples/hello_imports.ape) - Basic module usage
- [examples/stdlib_complete.ape](examples/stdlib_complete.ape) - All stdlib modules
- [examples/custom_lib_project/](examples/custom_lib_project/) - Project with local library

🧪 **Testing**
```bash
# 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](CHANGELOG.md) for version history.

---

## License

MIT License

Copyright (c) 2025 David Van Aelst

See [LICENSE](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](https://github.com/Quynah/Ape)
- [PyPI Package](https://pypi.org/project/ape-lang/)
- [Issue Tracker](https://github.com/Quynah/Ape/issues)
- [Changelog](CHANGELOG.md)

---

**Ape v0.2.0** — Built for deterministic AI collaboration 🦍