# AERI_LANG: Building the Mission Language for Weather, Physics, and Research

Author draft for editing

---

## Chapter 1: Why AERI_LANG Exists
AERI_LANG was created to make scientific computing feel natural, readable, and powerful for beginners and advanced users alike. Most scientific stacks force people to choose between readability and speed. AERI_LANG is designed to bridge that gap.

Core idea:
- Write code like clear short sentences.
- Keep scientific correctness through units and diagnostics.
- Build mission-level workflows from raw data to decisions.

AERI_LANG focuses on three high-impact domains:
- Weather intelligence
- Physics-based simulation
- Research-to-decision pipelines

---

## Chapter 2: Installation and First Run
### Requirements
- Python 3.9+

### Install
```bash
git clone https://github.com/mustafamyildiz33/AERI_LANG.git
cd AERI_LANG
pip install -e .
```

### First execution
```bash
aeri-lang run examples/storm.aeri
```

If the command runs, your environment is ready.

---

## Chapter 3: Project Structure
Typical folders and files:
- `aeri_lang/`: compiler, parser, interpreter, mission runtime, security
- `examples/`: sample `.aeri` programs and mission case files
- `tests/`: unit and integration tests
- `.github/workflows/`: CI and release automation
- `Dockerfile`: container runtime
- `README.md`: quick command reference

This layout supports local development and production packaging.

---

## Chapter 4: Your First AERI Program
AERI syntax is built to read like concise intent.

```aeri
let temp = 24;
let wind = 12;
say "Storm setup ready";
```

Run it:
```bash
aeri-lang run your_file.aeri
```

Common statement styles:
- `let` for declaration
- `set` for updates
- `fn` for functions
- `if/else` and `while` for control flow

---

## Chapter 5: Sentence Syntax (AERI Style)
AERI supports sentence-like simulation commands.

```aeri
simulate storm over Seattle for 1 hour
simulate storm over Seattle with gfs using rapid for 1 hour
```

Design purpose:
- Domain experts can read and write commands directly.
- Syntax stays short while preserving structure.

---

## Chapter 6: Scientific Units and Safer Math
AERI includes units-aware expressions to reduce category errors.

```aeri
let distance = 100<m>;
let time = 10<s>;
let velocity = distance / time;
```

Doctor checks and unit handling help users avoid invalid operations and improve trust in scientific outputs.

---

## Chapter 7: Calculus-Aware Expressions
AERI includes a slope operation for derivative-style workflows.

```aeri
fn compute_drag(v) {
    return 0.5 * v * v;
}
let velocity = 50<m> / 1<s>;
let drag_change = slope of compute_drag with velocity;
```

This lowers boilerplate when building physics/optimization pipelines.

---

## Chapter 8: Parallel and Scenario Execution
AERI supports native parallel blocks and branching scenarios.

Parallel:
```aeri
parallel {
    weather "Seattle";
    weather "Tokyo";
}
```

Scenario branching:
```aeri
scenario baseline {
    let temp = 25;
}

fork baseline into [hot, cold, normal] {
    case hot { set temp = temp + 1; }
    case cold { set temp = temp - 1; }
    case normal { say "baseline"; }
}

simulate all scenarios {
    say "running";
}
```

---

## Chapter 9: Mission Stack (Ingest -> Model -> Assimilate -> Simulate -> Decide)
AERI mission mode turns a storm case into a full run.

```bash
aeri-lang mission run examples/storm_case.yaml
```

Generated artifacts typically include:
- `manifest.json`
- `trace.jsonl`
- `ensemble.json`
- `decision.json`
- `report.md`
- `divergence.svg`

This is the foundation for operational forecasting and energy decision support.

---

## Chapter 10: Deterministic Replay and Reproducibility
Every serious research platform needs rerun consistency.

Replay a run exactly:
```bash
aeri-lang mission replay .aeri_runs/<run_id>
```

Reproducibility features:
- Manifest-based replay
- Stored artifacts per run
- Trace outputs for review and debugging

---

## Chapter 11: Queue Workers and Cloud-Style Execution
AERI includes a local queue/worker scaffold that mirrors distributed patterns.

Submit:
```bash
aeri-lang mission submit examples/storm_case.yaml
```

Execute worker:
```bash
aeri-lang mission worker --drain
```

Operations commands:
```bash
aeri-lang mission list
aeri-lang mission status
```

Worker runtime includes lease/retry style behavior for safer orchestration.

---

## Chapter 12: Security, Auth, and Multi-Tenant Control
AERI mission and release commands can require auth tokens and tenant scoping.

Example `.aeri_auth.json`:
```json
{
  "tokens": [
    {
      "token_sha256": "REPLACE_WITH_SHA256_OF_TOKEN",
      "role": "admin",
      "tenants": ["*"]
    }
  ]
}
```

Use flags:
- `--token`
- `--tenant`
- `--auth-file`

Or env var:
- `AERI_LANG_TOKEN`

---

## Chapter 13: Debugging and Diagnostics (Doctor + Visual Reports)
Doctor checks source quality:
```bash
aeri-lang doctor examples/storm.aeri
```

Visual debug report generation:
```bash
aeri-lang debug examples/storm.aeri
```

Outputs include SVG/HTML artifacts for flow and execution review.

---

## Chapter 14: Fastlane, Performance, and Release Bundles
AERI includes a fastlane benchmark path:
```bash
aeri-lang fastlane bench --size 200000 --iters 4
```

Compilation emits:
```bash
aeri-lang compile examples/storm.aeri --emit ir
aeri-lang compile examples/storm.aeri --emit python
aeri-lang compile examples/storm.aeri --emit fastlane
aeri-lang compile examples/storm.aeri --emit llvm
```

Release packaging:
```bash
aeri-lang release check .aeri_runs/<run_id>
aeri-lang release bundle .aeri_runs/<run_id>
```

---

## Chapter 15: Roadmap to Mission-Grade AERI
Current strengths:
- Sentence syntax for domain readability
- Mission pipeline with replay and artifacts
- Queue/worker orchestration scaffold
- Security/auth/tenant controls
- Debug, diagnostics, and release workflows

Next milestones:
- Production CUDA/ROCm fused kernel backend
- Stronger distributed multi-node control plane
- Hardened internet-facing deployment posture
- Formal package publishing and version lifecycle

AERI_LANG’s long-term goal is to become the mission language that turns weather and research intelligence into real-world decisions.

---

## Appendix A: Full CLI Command Reference
```bash
aeri-lang run <file.aeri>
aeri-lang compile <file.aeri> [--emit ir|python|fastlane|llvm] [--out <path>]
aeri-lang mission run <storm_case.yaml> [--out <dir>] [--token <token>] [--tenant <tenant>] [--auth-file <path>]
aeri-lang mission replay <run_dir> [--out <dir>] [--token <token>] [--tenant <tenant>] [--auth-file <path>]
aeri-lang mission submit <storm_case.yaml> [--queue <dir>] [--token <token>] [--tenant <tenant>] [--auth-file <path>]
aeri-lang mission worker [--queue <dir>] [--out <dir>] [--drain] [--worker-id <id>] [--lease-seconds <n>] [--token <token>] [--tenant <tenant>] [--auth-file <path>]
aeri-lang mission list [--out <dir>] [--token <token>] [--tenant <tenant>] [--auth-file <path>]
aeri-lang mission status [--queue <dir>] [--token <token>] [--tenant <tenant>] [--auth-file <path>]
aeri-lang fastlane bench [--size N] [--iters N]
aeri-lang release check <run_dir> [--token <token>] [--tenant <tenant>] [--auth-file <path>]
aeri-lang release bundle <run_dir> [--out <dir>] [--token <token>] [--tenant <tenant>] [--auth-file <path>]
aeri-lang doctor <file.aeri>
aeri-lang debug <file.aeri> [--out <path.svg>]
aeri-lang repl
aeri-lang build
aeri-lang ui <build|unit_error|runtime_error>
```

## Appendix B: Download/Share Package
If you need a shareable package, zip the repo:
```bash
zip -r AERI_LANG_book_and_code.zip . -x '.git/*' -x '__pycache__/*' -x '*/__pycache__/*' -x '*.pyc'
```
