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

Ape v1.0.2 is the **analyzer-ready release**, with complete deterministic runtime, governance observability contract, and comprehensive benchmarking.

**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
- **439 tests passing** - Full coverage of parser, linker, codegen, stdlib, runtime, observability, introspection, multi-language, 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

#### 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.0 supports Latin-based languages
- **Deterministic Normalization** - All languages produce identical AST and runtime behavior
- **Keyword-Only Translation** - Identifiers and literals remain unchanged

### 🧱 Scaffolded (Not Yet Integrated)

These modules exist with complete structure and documentation, but are **not wired into the active runtime**. They return `NotImplementedError` if called. Integration work required.

**⚠️ Do NOT assume these features work. They are placeholders for future implementation.**

#### Exception Handling
- Structure: `src/ape/runtime/errors.py` (try/catch/finally AST nodes exist)
- Status: Not integrated into executor
- Documentation: `docs/error_model.md`

#### Structured Types  
- Structure: `src/ape/types/` (List<T>, Map<K,V>, Record, Tuple classes exist)
- Status: Not integrated into type system
- Documentation: `docs/typesystem.md`

#### Expanded Standard Library
- Structure: `src/ape/std/json.py`, `src/ape/std/math_ext.py`
- Status: Stub implementations only
- Documentation: `docs/stdlib_json.md`, `docs/stdlib_math_ext.md`

#### Compiler Backend & VM
- Structure: `src/ape/compiler/optimizer.py`, `src/ape/vm/vm.py`, `src/ape/vm/instructions.py`
- Status: **SCAFFOLDED** headers added, not wired into compilation pipeline
- Documentation: `docs/compiler_optimization.md`, `docs/bytecode_vm.md`

#### Type Validator
- Structure: `src/ape/validator/types.py`
- Status: Not integrated into semantic validation
- Documentation: `docs/typesystem.md`

#### Benchmarking
- Structure: `src/ape/benchmarks/benchmark_runner.py`
- Status: **SCAFFOLDED** header added, infrastructure only
- Documentation: `docs/performance_tuning.md`

**Note:** Scaffolded modules have complete architecture and specifications. Enable them by implementing the stub methods and wiring them into the execution pipeline. See individual module docstrings for integration requirements.

See [docs/ROADMAP.md](docs/ROADMAP.md) for the complete roadmap with status per version.

---

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

---

## 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.2 (Analyzer-Ready 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 |

### 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.0 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
- ✅ **439 tests passing** - No regressions, full coverage

### For Early Adopters

APE v1.0.0 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 (439 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.2 Released (December 7, 2025)

APE v1.0.2 achieved **analyzer-ready** status with deterministic runtime, observability contract (trace_id + explain() + dry-run), and comprehensive benchmarking.

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

This is the **analyzer-ready v1.0.2 release** with deterministic runtime, observability contract, and benchmarking. 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.2  
**Tag:** ape-v1.0.2-analyzer-ready
**Status:** 🟢 Stable release  
**Tests:** 439/439 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 🦍
