# AERI_LANG v0.5.0b1

AERI_LANG is a beginner-friendly language for weather, physics, and research.

## AERI Colors
- Primary background: navy (`#001233`)
- Primary text: white (`#FFFFFF`)

## New Features

- Native parallel execution:
  - `parallel { ... }`
- Sentence syntax:
  - `simulate storm over Seattle with gfs using rapid for 1 hour`
- Tornado math helper:
  - `let impact = math("truck", 500<ft>, 120<mph>);`
  - returns severity/risk with `over_100_mph` flag
  - scenario generator: `let scenario_set = tornado_scenarios(150);`
- Butterfly-effect branching engine:
  - `scenario ...`, `fork ... into [...] { case ... }`, `simulate all scenarios { ... }`
- Calculus-aware slope:
  - `let drag_change = slope of compute_drag with velocity;`
- Physics-first units with conversion:
  - `cm <-> m`, `hour <-> seconds` conversion at runtime + doctor checks
- Reactive entangled variables:
  - `entangle weight = gravity * mass;`
  - updates automatically when sources change
- Oracle solving:
  - `find wind_speed where lift(wind_speed) == roof_weight;`
- Chronos checkpoints + rewind:
  - simulate loops auto-save snapshots
  - `rewind storm to 3;`
- Fastlane hotspot analysis:
  - `aeri-lang compile file.aeri --emit fastlane`
  - `aeri-lang compile file.aeri --emit llvm` emits LLVM prototype IR when `llvmlite` is installed
- Debug visuals:
  - `aeri-lang debug file.aeri` generates both SVG and HTML timeline report
- Image primitives:
  - `new_canvas`, `draw_line`, `draw_circle`, `save_canvas`
- Experiment memory:
  - `run` stores snapshots in `.aeri_history/...` with `+added/-deleted`
- Mission stack (Phase 1):
  - one-command storm case pipeline: ingest -> model -> assimilate -> simulate -> decide
  - reproducible artifacts: manifest, traces, ensemble outputs, decision, report, divergence dashboard
  - replay support: `mission replay <run_dir>` (deterministic rerun from manifest config)
  - queue scaffold: `mission submit ...` + `mission worker ...`
  - run registry: `mission list`
  - queue monitoring: `mission status`
- Fastlane runtime (Phase 2):
  - `aeri-lang fastlane bench` runs Python baseline vs LLVM JIT kernel path (if `llvmlite` installed)
- Native build path:
  - `aeri-lang compile file.aeri --emit cpp` generates C++17 source
  - `aeri-lang native build file.aeri` builds standalone binary with `c++`
  - `aeri-lang native parity file.aeri` checks native support before build
- App SDK bridge (`aeri_lang.api`):
  - stable response envelope for app integrations
  - modes: `interpreter` (full features) and `native` (compiled subset)
  - mission run/replay helpers return structured JSON-safe outputs
- Mission operations (Phase 3):
  - multi-worker queue orchestration: `aeri-lang mission supervisor --workers 4`
  - lease-based worker claims, retry-safe queue handling, tenant-aware filtering
- Reliability and ship-readiness (Phase 4):
  - end-to-end verification runner: `aeri-lang verify` (or `--quick`)
  - emits a pass/fail report across parser/interpreter/compile/mission/release checks
- Advanced Analytics (Phase 5):
  - `tornado_scenarios_summary(scenario_set)` for probabilistic/impact aggregates
- Decision Intelligence (Phase 6):
  - `tornado_rank(scenario_set, top_n)` to rank highest-risk scenarios
- Operational Playbooks (Phase 7):
  - `tornado_playbook(scenario_set, "grid"|"energy"|"life_safety")`
  - generates beginner-readable action plans from advanced analytics
- Final advanced execution helpers:
  - `set_seed(42)` for deterministic reproducible runs
  - `tornado_math_uncertainty(...)` for confidence intervals and `p_over_100_mph`
  - `tornado_export(scenario_set, "run_name")` -> JSON + CSV + Markdown report
- Send-out packaging:
  - `aeri-lang release check <run_dir>`
  - `aeri-lang release bundle <run_dir>`
- Security/auth (multi-tenant):
  - mission/release commands can require token auth via `.aeri_auth.json`
  - supports roles (`admin`, `operator`, `worker`, `viewer`) and tenant scoping
  - audit logs at `.aeri_audit.log`
  - token issue/rotation: `aeri-lang auth issue --role operator --tenant energy-west`
- Delivery pipeline:
  - Dockerfile included
  - GitHub Actions CI + PyPI release workflows included
- Cross-platform portability:
  - system preflight: `aeri-lang syscheck --strict`
  - install scripts: root-level `install_aeri.sh` / `install_aeri.ps1` (wrappers), plus `scripts/install_aeri.sh` / `scripts/install_aeri.ps1`
- Two-part complex roadmap delivery:
  - Part 1 shipped: native parity checks + node heartbeats + auth issue/expiry/audit
  - Part 2 shipped (scaffold): CUDA/ROCm backend detection + fused kernel stub emitter
  - Mandatory release gate: `aeri-lang prod gate --policy production/policy.json`
- Phase 8 performance maturity stack:
  - fused kernel cache artifacts
  - autotuning database
  - graph execution launch-overhead reduction metrics
  - roofline-style profiling report payloads

## Commands

```bash
aeri-lang run examples/storm.aeri
aeri-lang run examples/storm.aeri --mode auto
aeri-lang run examples/storm.aeri --mode native
aeri-lang run examples/hello_world.aeri
aeri-lang run examples/hello_parallel.aeri
aeri-lang run examples/hello_tornado_math.aeri
aeri-lang run examples/hello_tornado_150.aeri
aeri-lang run examples/hello_phase567.aeri
aeri-lang run examples/hello_phase567_plus.aeri
aeri-lang syscheck --strict
aeri-lang verify --quick
aeri-lang mission run examples/storm_case.yaml
aeri-lang mission run examples/hello_mission_case.yaml
aeri-lang mission replay .aeri_runs/<run_id>
aeri-lang mission submit examples/storm_case.yaml
aeri-lang mission worker --drain
aeri-lang mission supervisor --workers 4 --max-cycles 100
aeri-lang mission nodes
aeri-lang mission list
aeri-lang mission status
aeri-lang mission submit examples/storm_case.yaml --tenant energy-west --token $AERI_LANG_TOKEN
aeri-lang fastlane bench --size 200000 --iters 4
aeri-lang fastlane gpu check
aeri-lang fastlane gpu emit --backend cuda --out aeri_fused_kernel.cu
aeri-lang release check .aeri_runs/<run_id>
aeri-lang release bundle .aeri_runs/<run_id>
aeri-lang doctor examples/storm.aeri
aeri-lang debug examples/storm.aeri
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
aeri-lang compile examples/hello_world.aeri --emit cpp
aeri-lang native parity examples/hello_world.aeri
aeri-lang native build examples/hello_world.aeri --out hello_world_native
./hello_world_native
aeri-lang auth issue --role operator --tenant energy-west --days 30
aeri-lang prod gate --policy production/policy.json --json .aeri_prod_gate.json
aeri-lang phase8 init
aeri-lang phase8 status
aeri-lang phase8 compile --source examples/hello_world.aeri --backend cuda --shape 256x256
aeri-lang phase8 tune --op storm_update --backend cuda --shapes 256x256,512x512 --trials 6
aeri-lang phase8 run --backend cuda --ops storm_step,pressure_update,vorticity_update
aeri-lang phase8 profile --backend cuda --op storm_hotloop --size 100000 --iters 50
aeri-lang phase8 report --out .aeri_phase8_report.json
```

## Install On Any Computer

macOS/Linux:
```bash
bash install_aeri.sh
source .venv/bin/activate
aeri-lang syscheck --strict
```

Windows PowerShell:
```powershell
powershell -ExecutionPolicy Bypass -File .\install_aeri.ps1
.\.venv\Scripts\Activate.ps1
aeri-lang syscheck --strict
```

## Example

```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;

entangle turbulence_index = velocity * 2;

simulate storm over Seattle for 1 hour

parallel {
    weather "Seattle";
    weather "Tokyo";
}
```

## Notebook Bridge

Use `aeri_lang.notebook` inside notebooks:

```python
from aeri_lang.notebook import list_runs, load_run, probability_table
runs = list_runs(".aeri_runs")
data = load_run(str(runs[-1]))
tbl = probability_table(str(runs[-1]))
```

## App Integration (No CLI Required)

```python
from aeri_lang.api import AeriAPI

api = AeriAPI()

# Best of both worlds (auto): native when safe, interpreter fallback otherwise
res = api.execute('say "Hello app"; weather "Seattle";', mode="auto")
if res["ok"]:
    print(res["data"]["output"])
else:
    print(res["error"])

# Native binary-backed path (subset)
native = api.execute('say "Hello native";', mode="native")
print(native["ok"], native["data"] if native["ok"] else native["error"])
```

## Auth File Example

Create `.aeri_auth.json` in project root:

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