Skip to content
Back to search

ainativelang

AINL helps turn AI from "a smart conversation" into "a structured worker." It is designed for teams building AI workflows that need multiple steps, state and memory, tool use, repeatable execution, validation and control, and lower dependence on long prompt loops. AINL is a compact, graph-canonical, AI-native programming system for (READ: README)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sbhooley--ainativelang/badge.svg)](/listings/sbhooley--ainativelang)

HTML

<a href="/listings/sbhooley--ainativelang"><img src="/api/listings/sbhooley--ainativelang/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

For self-improving loops (generate -> inspect -> mutate -> evaluate), use:

1. **Inspect canonical IR** - `ainl inspect candidate.ainl --strict` 2. **Diff two candidates** - MCP tool: `ainl_ir_diff(file1, file2, strict=true)` 3. **Score fitness** - MCP tool: `ainl_fitness_report(file, runs=5, strict=true)` 4. **Repair invalid outputs** - MCP `ainl_validate` diagnostics include `llm_repair_hint`

Contract and stable payload fields: `docs/operations/MCP_RESEARCH_CONTRACT.md`.

For the full conformance matrix in one command (tokenizer, IR canonicalization, strict validation, runtime parity, emitter stability):

`make conformance` (or `SNAPSHOT_UPDATE=1 make conformance` when intentionally updating snapshots).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,766 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # AI Native Lang (AINL)
  2. <p align="center">
  3. <img src="docs/assets/ainl_logo.png" alt="AINL logo" width="220" />
  4. </p>
  5. <p align="center">
  6. Find Us on X: <a href="https://x.com/ainativelang">@ainativelang</a>
  7. </p>
  8. <p align="center">
  9. <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+" />
  10. <a href="https://github.com/sbhooley/ainativelang/tags">
  11. <img src="https://img.shields.io/github/v/tag/sbhooley/ainativelang?label=release" alt="Latest tag" />
  12. </a>
  13. <a href="tests/snapshots/conformance/summary.md">
  14. <img src="tests/snapshots/conformance/conformance_badge.svg" alt="Conformance status" />
  15. </a>
  16. <a href="https://github.com/sbhooley/ainativelang/actions/workflows/sync-ecosystem.yml">
  17. <img src="https://github.com/sbhooley/ainativelang/actions/workflows/sync-ecosystem.yml/badge.svg" alt="Auto-sync OpenClaw/NemoClaw/Clawflows/Agency-Agents" />
  18. </a>
  19. <a href="LICENSE">
  20. <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache-2.0" />
  21. </a>
  22. <img src="https://img.shields.io/badge/MCP-v1%20server-blueviolet" alt="MCP v1" />
  23. <a href="https://github.com/sbhooley/ainativelang/tree/main/skills/ainl">
  24. <img src="https://img.shields.io/badge/ZeroClaw%20Skill-AINL-blue" alt="ZeroClaw Skill: AINL" />
  25. </a>
  26. <a href="https://github.com/sbhooley/ainativelang/tree/main/skills/openclaw">
  27. <img src="https://img.shields.io/badge/OpenClaw%20Skill-AINL-blue" alt="OpenClaw Skill: AINL" />
  28. </a>
  29. <a href="https://github.com/NousResearch/hermes-agent">
  30. <img src="https://img.shields.io/badge/Hermes%20Agent-AINL-blue" alt="Hermes Agent: AINL" />
  31. </a>
  32. <img src="https://img.shields.io/badge/graph--first-deterministic%20IR-orange" alt="Graph-first deterministic IR" />
  33. <img src="https://img.shields.io/badge/AI%20workflow-language-brightgreen" alt="AI workflow language" />
  34. </p>
  35. > AI-led co-development project, human-initiated by Steven Hooley (`x.com/sbhooley`, `stevenhooley.com`, `linkedin.com/in/sbhooley`). Attribution details: `docs/PROJECT_ORIGIN_AND_ATTRIBUTION.md` and `tooling/project_provenance.json`. -- This project was named by AI :)
  36. ---
  37. ## For agents — install AINL (one step)
  38. If you are an AI coding agent (Claude Code, Cursor, Cline, Codex, Aider, …)
  39. or any MCP-capable runtime and the user wants AINL added to their stack,
  40. run **one command**:
  41. ```bash
  42. pipx install 'ainativelang[mcp]' && ainl setup --auto
  43. ```
  44. Fallback if `pipx` is unavailable:
  45. ```bash
  46. python3 -m pip install --user 'ainativelang[mcp]' && ainl setup --auto
  47. ```
  48. That is the entire install. The `setup` command auto-detects every host
  49. present (Claude Code project + user, Cursor, Cline, Codex CLI/Desktop,
  50. Claude Desktop, OpenClaw, Hermes, ArmaraOS, or any generic MCP host),
  51. merges the right MCP server entry into each config file (atomic write,
  52. timestamped backup), and verifies with `ainl doctor`. Idempotent — safe
  53. to re-run.
  54. If a host is not auto-detected, run `ainl setup --print-config` for a
  55. paste-ready stdio MCP server block.
  56. Machine-readable spec: [`.agent-install.json`](./.agent-install.json) ·
  57. Design: [`docs/architecture/2026-05-05-agent-install-simplification.md`](docs/architecture/2026-05-05-agent-install-simplification.md).
  58. ---
  59. ## Is AINL for you? (60-second filter)
  60. Before the install commands, here is who AINL is and is not for. We would rather you self-select out in 60 seconds than spend a week on a tool that does not fit.
  61. | ✅ AINL is for you if… | ❌ AINL is *not* for you if… |
  62. |:----------------------|:----------------------------|
  63. | Your agents (Cursor, Claude Code, autonomous loops) **author runner / orchestration code** and have shipped broken Python more than once | You write all your runners by hand and your CI test suite catches the bugs |
  64. | You run **20+ recurring monitor / digest / scheduled jobs** that currently **re-prompt an LLM on every run** to decide routing | You already have deterministic runners with the LLM only at judgment gates — congrats, you are baseline **B** below and AINL gives you ~1.3–1.5× on routing only |
  65. | You need **the same workflow source** to emit to LangGraph **and** Temporal **and** FastAPI without re-authoring | One target is fine for you forever |
  66. | You have **compliance audit needs** (SOC 2 / HIPAA / similar) that want tamper-evident execution traces, not application logs | `logger.info` is enough for your team |
  67. | You want **strict compile-time validation** of agent workflows before they hit production | Runtime exceptions are fine, you have alerting |
  68. If you tick two or more left-column rows, keep reading. The long-form answer — three baselines, four anti-fit workload patterns, decision tree, honest reviewer Q&A, persona-to-product mapping — lives in **[`docs/WHO_IS_THIS_FOR.md`](docs/WHO_IS_THIS_FOR.md)** (canonical). If you tick zero, that page explains why and saves you the install. We mean it.
  69. ---
  70. ## Per-host details (advanced)
  71. **Just want something working on your desktop in under 3 minutes?**
  72. ArmaraOS is the desktop agent OS built on AI Native Lang (AINL) — download once, install, and your agents are live with a full dashboard. No terminal, no config files, just plug in your API key.
  73. > **[Download ArmaraOS — ainativelang.com](https://ainativelang.com/)**
  74. > *macOS · Windows · Linux — free to start*
  75. Autonomous agents, 7 pre-built Hands (researcher, lead gen, clip editor, and more), 40 channel adapters (Telegram, Discord, Slack, WhatsApp…), 27 LLM providers, 16 security layers — all in a single ~32 MB binary.
  76. ---
  77. **Already have an AI agent? Add AINL in one command.**
  78. AINL installs directly into OpenClaw, ZeroClaw, Hermes, Claude Code, and any MCP-compatible agent. After install your agent can **author, validate, and run** deterministic workflows — with the largest token wins when you are still on **LLM prompt-loop orchestration** (baseline A below).
  79. | Your agent | Install command | How-to guide |
  80. |:-----------|:----------------|:-------------|
  81. | **OpenClaw** | `ainl install-mcp --host openclaw` | [ainativelang.com/install](https://ainativelang.com/install) |
  82. | **ZeroClaw** | `zeroclaw skills install https://github.com/sbhooley/ainativelang/tree/main/skills/ainl` | [ainativelang.com/install](https://ainativelang.com/install) |
  83. | **Hermes Agent** | `ainl install-mcp --host hermes` | [ainativelang.com/install](https://ainativelang.com/install) |
  84. | **Claude Code** | `pip install 'ainativelang[mcp]'` → add `ainl-mcp` to MCP config | [ainativelang.com/mcp](https://ainativelang.com/mcp) |
  85. | **Any MCP host** | `pip install 'ainativelang[mcp]'` → run `ainl-mcp` (stdio) | [ainativelang.com/mcp](https://ainativelang.com/mcp) |
  86. After install, ask your agent: *"Use AINL to build this workflow"* — it compiles once, runs many times without re-spending tokens on orchestration **when the workload was previously prompt-loop driven**.
  87. **Primary product path:** **[ArmaraOS](https://ainativelang.com/armaraos)** — desktop agent OS with dashboard, **Hands**, scheduled **`ainl run`**, and MCP authoring. See **[`docs/competitive/ARMARAOS_GTM.md`](docs/competitive/ARMARAOS_GTM.md)**.
  88. **Token savings — pick your baseline:**
  89. | Your baseline today | Typical AINL win | Worth it for tokens alone? |
  90. |:--------------------|:-----------------|:---------------------------|
  91. | **A.** LLM re-prompts routing/state on every cron/webhook | **~90–95%** fewer *orchestration* tokens on recurring monitors ([`BENCHMARK.md`](BENCHMARK.md), `benchmark_compile_once_run_many.py`) | **Often yes** |
  92. | **B.** Hand-optimized scripts + LLM only at judgment gates | **~1.3–1.5×** on routing tokens ([`token_savings_results.json`](tooling/token_savings_results.json)) | **Usually no** — consider audit, MCP safety, emit, or ArmaraOS |
  93. | **C.** Pure deterministic runners (no LLM in loop) | **~0%** | **No** |
  94. Full honest filter: **[`docs/competitive/WHEN_AINL_DOES_NOT_HELP.md`](docs/competitive/WHEN_AINL_DOES_NOT_HELP.md)** · **[`docs/competitive/VS_HAND_WRITTEN_RUNNER.md`](docs/competitive/VS_HAND_WRITTEN_RUNNER.md)** (five-axis comparison vs a hand-written Python runner — concedes the token point on baseline B).
  95. | Workload (**baseline A** — prompt-loop today) | Typical savings | Reproducible via |
  96. |:----------------------------------------------|:----------------|:-----------------|
  97. | Recurring monitors, digests, scheduled jobs | **~90–95% fewer orchestration tokens** vs prompt loops | [`scripts/benchmark_compile_once_run_many.py`](scripts/benchmark_compile_once_run_many.py) → [`tooling/compile_once_run_many_results.json`](tooling/compile_once_run_many_results.json) |
  98. | Multi-step automations (LLM-first routing) | **~2–7× reduction** vs LLM-first (A vs C); **~1.3–1.5×** vs hand-optimized (B vs C) | [`scripts/benchmark_token_savings.py`](scripts/benchmark_token_savings.py) → [`tooling/token_savings_results.json`](tooling/token_savings_results.json) |
  99. | Authoring density (LLM-style verbose Python) | **~1.7× mean / up to 2.5×** fewer source tokens vs verbose baselines | [`scripts/benchmark_authoring_density.py`](scripts/benchmark_authoring_density.py) → [`tooling/authoring_density_results.json`](tooling/authoring_density_results.json) |
  100. | Authoring vs hand-written LangGraph | **~1.9–2.0×** fewer source tokens (authoring only, not runtime) | [`scripts/benchmark_competitor_baselines.py`](scripts/benchmark_competitor_baselines.py) → [`tooling/competitor_baseline_tokens.json`](tooling/competitor_baseline_tokens.json) |
  101. > **Important:** every percentage / multiplier above is **vs baseline A** (prompt-loop) or labeled with its baseline pair. Against **baseline B** (hand-optimized runner with LLM only at judgment gates), the irreducible token win is **~1.3–1.5×** on routing only — see [`VS_HAND_WRITTEN_RUNNER.md`](docs/competitive/VS_HAND_WRITTEN_RUNNER.md). Against **baseline C** (pure deterministic, no LLM in loop), it is **~0%**.
  102. The reason: AINL compiles your workflow once. The runtime executes it deterministically — no LLM re-generation on each run for graph routing and adapter orchestration. The model authors the graph once; the runtime runs it on every invocation. **That mechanism produces token savings only when the counterfactual was actually re-prompting on every run.**
  103. > **[Token savings breakdown and benchmarks →](https://ainativelang.com/benchmark)** · **[`BENCHMARK.md`](BENCHMARK.md)** (source tables + methodology) · **[`docs/CLAIMS_AND_EVIDENCE.md`](docs/CLAIMS_AND_EVIDENCE.md)** (claim crosswalk) · **[When AINL does not help →](docs/competitive/WHEN_AINL_DOES_NOT_HELP.md)**
  104. ### Current evidence (honest scope)
  105. We classify every public evidence row by source so reviewers can tell field reports from modeled scenarios:
  106. | Class | What it means | Where it lives |
  107. |-------|---------------|----------------|
  108. | **(a)** Third-party paying customer deployment | Independent company runs AINL, reports measurable token / dollar outcome | **0 rows today.** Tracked: [`LONG_TERM_FIXES_TRACKER.md`](docs/competitive/LONG_TERM_FIXES_TRACKER.md) row **T2.7** |
  109. | **(b)** Operator deployment (project author / close collaborator) | Real logs, real workload, on author's stack — not yet an external customer | **2 rows.** [`PRODUCTION_EVIDENCE.md`](docs/competitive/PRODUCTION_EVIDENCE.md) Cases 1, 2 |
  110. | **(c)** Modeled / analytical scenario | Reproducible benchmark on synthetic workload — no live LLM | **1 row + 4 benchmark scripts.** `scripts/benchmark_*.py`, `tooling/*_results.json` |
  111. | **(d)** Marketing narrative | Story without specific deployment behind it | Flagged for audit + removal — see tracker **T1.10** |
  112. **We do not yet have a Class (a) deployment publicly committed.** If your team would consider being the first, the pilot kit (tracked T2.5) is small. Until then we ask reviewers to **read `WHEN_AINL_DOES_NOT_HELP.md` first**, run the benchmarks, and judge on the published Class (b)/(c) evidence with the baseline qualifier attached.
  113. ---
  114. **Here for the programming language itself?**
  115. AINL is a compact, graph-canonical AI workflow language. You write programs in `.ainl` files, compile them to a deterministic IR graph, and execute them without prompt loops.
  116. [Jump to Get Started (3 minutes) ↓](#get-started-3-minutes) · [Docs →](https://ainativelang.com/docs) · [Quick start →](https://ainativelang.com/quickstart) · [What is AINL? →](https://ainativelang.com/what-is-ainl)
  117. ---
  118. > **This GitHub repo** is the technical source of truth for AINL: compiler, runtime, canonical graph IR, CLI, HTTP runner, MCP server, docs, examples, and conformance suite. For the high-level product story, use cases, and commercial/enterprise paths, visit **[ainativelang.com](https://ainativelang.com)**.
  119. ## Open-core boundary
  120. | Area | Status | Notes |
  121. |:-----|:------:|:------|
  122. | Core DSL, compiler, runtime, `ainl validate/check/inspect/visualize` | **Open** (Apache-2.0) | Language legitimacy; essential tooling |
  123. | MCP server / bridge (`ainl-mcp`, `scripts/ainl_mcp_server.py`) | **Open & pluggable** | Any MCP host; bring your own compliant LLMs |
  124. | OpenSpace / Lead AI style flows | **Open via BYO-LLM** | Implemented via MCP; operators choose their models |
  125. | Enterprise audit/policy packs, managed ops, deployment kits | **Paid / optional** | Governance, SLA-backed support, monitored hosted runtime |
  126. > Full boundary details: [`docs/OPEN_CORE_DECISION_SHEET.md`](docs/OPEN_CORE_DECISION_SHEET.md)
  127. ## Security
  128. Vulnerability reporting and sensitive areas (outbound HTTP, the `a2a` adapter, secrets): see **[SECURITY.md](SECURITY.md)**. A2A-specific policy and wire contract: **[docs/integrations/A2A_ADAPTER.md](docs/integrations/A2A_ADAPTER.md)**.
  129. **Agentic HTTP payments & commerce (x402, MPP, AP2, ACP, AGTP):** integration hub **[docs/integrations/README.md](docs/integrations/README.md)** — HTTP-402 rails on the **`http`** adapter (**[HTTP_MACHINE_PAYMENTS.md](docs/integrations/HTTP_MACHINE_PAYMENTS.md)**), practitioner readiness (**[AGENTIC_PROTOCOLS_PRACTITIONER_READINESS.md](docs/integrations/AGENTIC_PROTOCOLS_PRACTITIONER_READINESS.md)**), and **AGTP** options (**[AGTP.md](docs/integrations/AGTP.md)**).
  130. ## New in v1.8.4
  131. The 42 graphs on **1.8.3** stay as they are. No new verb.
  132. - **`\d`:** a decimal digit, same as Python `re`. A superscript does not match.
  133. - **Long tokens:** a single-character quantifier matches in a loop.
  134. - **Caption and hashtag:** still `REGEX_FINDALL` for the whole match, then `REGEX_REPLACE` of that match. Replacing the whole filing keeps the words around the caption.
  135. ## New in v1.8.3
  136. `EQ`, `CONTAINS`, `TRIM`, `If`, and `Loop` stay as they are.
  137. - **Certified patterns:** caption, counsel, the short docket, hashtags, and a `\u` character class in [`tests/fixtures/ainl_re_1.json`](tests/fixtures/ainl_re_1.json). `REGEX_FINDALL` returns the full match. Counsel's Unicode `\w` matches Python `re`.
  138. - **Public fetch, opt-in:** `allow_public` / `--http-allow-public`. Default deny stays. `*` is not a wildcard. Metadata stays refused.
  139. - **Extract:** `core.EXTRACT` returns text and links from HTML or RSS/Atom. `HTML_TEXT` is still only a tag stripper.
  140. - **Already in published 1.8.2:** `core.UNTRUSTED_PROMPT`, `core.SHAPE`, and the `queue.PUT` idempotency key.
  141. ## New in v1.8.2
  142. `EQ`, `CONTAINS`, `TRIM`, `If`, and `Loop` are unchanged.
  143. - **Decision graphs:** `Uses`, `AINL_SECURITY_PROFILE=firm`, `core.UNTRUSTED_PROMPT`, `core.SHAPE`, a `queue.PUT` idempotency key, `limits["now"]`, and a compile rejection of cloud-key literals. `X core.ENV` uses the host allowlist in any case. Platform names such as `AzureWebJobsStorage` stay unreadable.
  144. - **Deny by default:** `SimpleHttpAdapter()` and an empty A2A allowlist deny every host. Metadata addresses stay closed. The runner log records argument counts and types, not values.
  145. - **Contract:** [`docs/operations/DECISION_OPS_1_8_2.md`](docs/operations/DECISION_OPS_1_8_2.md). List: [`docs/CHANGELOG.md`](docs/CHANGELOG.md) § **v1.8.2**.
  146. ## New in v1.8.0
  147. - **MCP authoring & strict-valid corpus:** **`ainl_step_examples`**; **`ainl_get_started`** with **`wizard_state_json`** for session continuity; MCP resource **`ainl://strict-valid-families`** (mined **`corpus/strict_valid_family_index.json`**, **`tooling/corpus_mining.py`**); **`ainl_validate`** / **`ainl_compile`** responses include **`contract_validation_status`** and **`contract_alignment.mismatched_calls`** (lightweight drift vs `ADAPTER_CONTRACTS`); **`tooling/mcp_exposure_profiles.json`** registers the wizard tool + family resource on **`design_impact_first`**, **`inspect_only`**, **`safe_workflow`**, and **`full`**. Hub: **`docs/operations/MCP_AINL_WIZARD_AND_CORPUS.md`**. ArmaraOS pairs with **`mcp:ainl:wizard_state`** graph facts and **`mcp_ainl_wizard_state_hint`** in the system prompt (see **`armaraos/docs/mcp-a2a.md`**).
  148. - **HTTP machine payments (opt-in):** **`http`** adapter **`payment_profile`** (**`none`/`auto`/`x402`/`mpp`**) with structured **402** **`payment_required`** + **`http_payment`** frame merges; CLI **`--http-payment-profile`** / **`--http-max-payment-rounds`**; runner + MCP **`adapters.http`** keys. Docs: **`docs/integrations/HTTP_MACHINE_PAYMENTS.md`**, hub **`docs/integrations/README.md`**.
  149. ## New in v1.7.1
  150. - **A2A (Agent-to-Agent) adapter (opt-in):** **`a2a`** — wire profile **1.0** (`GET …/.well-known/agent.json`, **`tasks/send`** / **`tasks/get`**); **`allow_hosts`** / optional **`strict_ssrf`** / **redirects off by default**; enable via **`--enable-adapter a2a`** and **`--a2a-allow-hosts`**, or **`adapters` + `adapters.a2a`**. MCP **exposure profiles** do not enable **a2a** without **`adapters`** (see **`tooling/mcp_exposure_profiles.json`** + **`docs/integrations/A2A_ADAPTER.md`**). Tests: **`tests/test_a2a_adapter.py`**, **`tests/test_a2a_adapter_integration.py`**; example: **`examples/compact/a2a_delegate.ainl`**.
  151. - **Release hygiene:** **`pyproject.toml`**, **`RUNTIME_VERSION`**, **`CITATION.cff`**, **`tooling/bot_bootstrap.json`**, mirrored emit server engine aligned to **1.7.1** for that tag's PyPI publish (see **`docs/CHANGELOG.md`** § **v1.7.1**, **`docs/RELEASE_NOTES.md`**; **Known limitations** point at **`A2A_ADAPTER`**: TOCTOU, empty allowlist, IDNA).
  152. ## New in v1.7.0
  153. - **Cognitive vitals (Python graph bridge):** episodic **`MemoryNode`** fields **`vitals_gate`**, **`vitals_phase`**, **`vitals_trust`**; Rust snapshot import; inbox schema + **`tests/test_vitals_bridge.py`** — keeps Python graph store / inbox aligned with ArmaraOS Rust **`EpisodeNode`** vitals (pair with current ArmaraOS for **`patch`** inbox drain on the Rust side).
  154. - **ArmaraOS Rust crate convergence (`ainl-*` + OpenFang):** integration contracts and docs now explicitly track the `ainl-runtime`/`openfang-runtime`/`openfang-kernel`/`openfang-types` path used in production ArmaraOS builds, including optional **`ainl-runtime-engine`** turn routing, internal delegation-depth guards, and shared graph-memory session semantics for mixed Python/Rust deployments.
  155. - **Patch registry + GraphPatch adapter path:** ArmaraOS-side **`PatchAdapter`** / **`AdapterRegistry`** dispatch with **`GraphPatchAdapter`** host forwarding is now documented alongside Python GraphPatch so label-keyed procedural patches can converge on a single cross-runtime contract while Python remains the rich `memory.patch` executor.
  156. - **Persona evolution / extractor / semantic tagger alignment:** release docs and bridge wiring now call out the default ArmaraOS feature stack (**`ainl-persona-evolution`**, **`ainl-extractor`**, **`ainl-tagger`**) and runtime gates (**`AINL_PERSONA_EVOLUTION`**, **`AINL_EXTRACTOR_ENABLED`**, **`AINL_TAGGER_ENABLED`**) that back `ExtractionReport` phase warnings and graph-memory enrichment across the Rust and Python boundary.
  157. - **Hand pack `schema_version`:** **`ainl emit --target armaraos`** writes **`schema_version`** on **`HAND.toml`**, IR JSON, and **`security.json`** — **`tests/test_emit_armaraos_handpack.py`**.
  158. - **Monitor registry bootstrap:** **`build_armaraos_monitor_registry`**, **`boot_armaraos_graph_memory`**, **`CronDriftCheckAdapter`**, **`tests/test_armaraos_monitor_registry.py`**.
  159. - **Runtime:** public **`AdapterRegistry.get`**; graph-patch uses **`adapters.get("ainl_graph_memory")`**.
  160. - **Release hygiene (v1.7.0 line):** **`pyproject.toml`**, **`RUNTIME_VERSION`**, **`CITATION.cff`**, **`tooling/bot_bootstrap.json`**, mirrored emit server engine bumped to **1.7.0** for that tag's PyPI publish (**superseded by v1.8.0** in this tree — see **New in v1.8.0** above; **PyPI** shows **1.8.0** only after that release is uploaded — **`docs/RELEASING.md`**).
  161. ## New in v1.6.0
  162. - **GraphPatch:** runtime **`R memory.patch`** (and graph **`memory.patch`**) installs procedural label bodies from the JSON graph store via **`ainl_graph_memory.graph_patch`**, with compile-time strict literal checks, runtime dataflow validation (**`_analyze_step_rw`**), overwrite protection for compiled labels, boot-time **`_reinstall_patches`**, and per-label fitness EMA (including early **`J`** exits). Tests: **`tests/test_graph_patch_op.py`**.
  163. - **Foundation for unified graph execution:** v1.6.0 established the canonical Python GraphPatch semantics while the ArmaraOS Rust stack formalized adapter-based patch dispatch (`PatchAdapter` registry + `GraphPatchAdapter` fallback), creating a stable integration seam that **v1.7.0** extended through vitals, extractor, persona, and semantic-tagging convergence, and that **v1.7.1** extended with the opt-in **a2a** (Agent-to-Agent) network adapter — **v1.8.0** layers MCP authoring depth (wizard, corpus index, contract alignment) and HTTP **402** payment profiles on **`http`**.
  164. - **Release hygiene:** **`pyproject.toml`**, **`RUNTIME_VERSION`**, **`CITATION.cff`**, **`tooling/bot_bootstrap.json`**, mirrored emit server engine, and **`ADAPTER_REGISTRY.json`** / **`docs/reference/ADAPTER_REGISTRY.md`** aligned to **1.6.0**.
  165. ## Unified graph execution engine vision (1.6.0 → 1.8.0)
  166. - **Single typed substrate:** the same graph artifact carries executable workflow structure plus memory layers (episodic, semantic, procedural, persona), rather than splitting execution and memory into separate systems.
  167. - **Memory as compiled knowledge:** GraphPatch (`memory.patch`) promotes proven behavior into reusable procedural graph structure under strict dataflow and overwrite guards.
  168. - **Cross-runtime convergence:** Python AINL runtime semantics and ArmaraOS Rust patch-dispatch contracts (`PatchAdapter` / `GraphPatchAdapter`) are intentionally aligned to support one portable graph-memory model across both stacks.
  169. - **Persona/tooling in graph form:** persona evolution, semantic extraction/tagging, and adapter-driven tooling are treated as graph-native concerns, not bolt-on prompt metadata.
  170. - **Primary references:** [`LATE_NIGHT_CONVO_WITH_AI.md`](LATE_NIGHT_CONVO_WITH_AI.md), [`WHITEPAPERDRAFT.md`](WHITEPAPERDRAFT.md), and ArmaraOS prior-art lineage in [`sbhooley/armaraos/PRIOR_ART.md`](https://github.com/sbhooley/armaraos/blob/main/PRIOR_ART.md).
  171. ## New in v1.5.2
  172. - **Graph memory IR closure:** optional **`memory_type`** on compiled **`R`** steps; typed **`emit_edges`** + **`tooling/graph_api`** helpers (**`emit_edges`**, **`data_flow_edges`**, **`memory_nodes`**); **`memory.pattern_recall`** + **`__last_pattern__`** for procedural **`memory.merge`** round-trips — **`docs/architecture/GRAPH_INTROSPECTION.md`**, **`docs/adapters/AINL_GRAPH_MEMORY.md`**.
  173. - **Persona + strict registry:** **`persona.load`** injects graph-store traits into the execution frame; memory / persona graph ops registered for strict validation — **`examples/persona_demo.ainl`**, **`tests/test_persona_load_engine.py`**, **`tests/test_strict_adapter_contracts.py`**.
  174. - **Single portable bundle:** **`AINLBundle`** / **`AINLBundleBuilder`** (**`runtime/ainl_bundle.py`**) round-trip workflow IR + memory + persona + tool strings to **`.ainlbundle`** JSON — **`tests/test_ainl_bundle.py`**.
  175. - **MCP + limits:** workspace **`ainl_mcp_limits.json`** warnings on successful runs; invalid workspace **`cache.json`** → **`adapter_config_error`** during MCP auto-cache; **`max_adapter_calls: 0`** enforced at the first adapter dispatch.
  176. - **ArmaraOS emit metadata:** **`security.json`** **`capability_declarations.adapters`**; **`HAND.toml`** **`ainl_ir_version`**.
  177. - **Release hygiene:** **`pyproject.toml`**, **`RUNTIME_VERSION`**, **`CITATION.cff`**, **`tooling/bot_bootstrap.json`**, and mirrored emit server engine aligned to **1.5.2**.
  178. - **Whitepaper:** **`WHITEPAPERDRAFT.md`** **v1.5.2** + **§6.8** (graph-memory gap audit narrative).
  179. ## New in v1.5.1
  180. - **Graph memory in the runtime:** IR ops **`MemoryRecall`** / **`MemorySearch`** dispatch the **`ainl_graph_memory`** adapter (ArmaraOS JSON graph store); see **`docs/adapters/AINL_GRAPH_MEMORY.md`**, **`tests/test_memory_recall_op.py`** (dispatch contract), and **`tests/test_memory_search_op.py`** (search + temp **`GraphStore`**).
  181. - **ArmaraOS bridge:** `armaraos/bridge/ainl_graph_memory.py`, runner registration + delegation hook, optional **`graph_viz`** server, **`demo/procedural_roundtrip_demo.py`**, **`demo/ainl_graph_memory_demo.py`** (graph-memory walkthrough + export), token-budget bridge shim (**`bridge_token_budget_adapter.py`**).
  182. - **Release hygiene:** **`pyproject.toml`**, **`RUNTIME_VERSION`**, **`CITATION.cff`**, **`tooling/bot_bootstrap.json`**, and mirrored emit server engine aligned to **1.5.1**.
  183. - **Catalog parity:** **`ainl_graph_memory`** appears in **`tooling/adapter_manifest.json`**, **`ADAPTER_REGISTRY.json`**, and **`tooling/effect_analysis.py`** (**`ADAPTER_EFFECT`**) alongside the human registry in **`docs/reference/ADAPTER_REGISTRY.md`**.
  184. ## New in v1.5.0
  185. - **Minor release:** **`RUNTIME_VERSION`**, **`CITATION.cff`**, and **`tooling/bot_bootstrap.json`** aligned with PyPI **`ainativelang` 1.5.0** (see **`docs/CHANGELOG.md`** § v1.5.0).
  186. - **Docs:** hub pages, OpenClaw integration pointers, contributor guides, and whitepaper draft refreshed so “current release” references match **v1.5.0**.
  187. ## New in v1.4.6
  188. - **Repo completeness**: `apollo-x-bot/api-cost-monitor.ainl` (promoter / API-cost workflow sample), `demo/test_openspace_http.ainl` (experimental OpenSpace HTTP probe), and `run_openspace_test.py` (portable dev harness for `demo/test_openspace_mcp.ainl` — no hard-coded workspace paths).
  189. ## New in v1.4.5
  190. - **`ainl install-mcp --host armaraos`**: merges `env` pass-through (`AINL_MCP_EXPOSURE_PROFILE`, tools/resources allow/deny lists) into **existing** `[[mcp_servers]]` `name = "ainl"` blocks so upgrades do not require hand-editing `~/.armaraos/config.toml`.
  191. - **MCP server (`ainl-mcp`)**: `ainl://authoring-cheatsheet` resource, process-local validate telemetry, and tighter validate/compile integration for agent-facing diagnostics.
  192. - **Compiler (strict)**: richer graph validation diagnostics, optional `contract_violation_reason` on include-related diagnostics, and targeted exemptions for labels whose last step is inner **`Loop`** / **`While`** (fewer false strict failures on assembly-style pipelines).
  193. ## New in v1.4.4
  194. - **PyPI `ainativelang` 1.4.4**: version surfaces aligned (`pyproject.toml`, `RUNTIME_VERSION`, `CITATION.cff`, `tooling/bot_bootstrap.json`).
  195. - **Solana client emit**: `emit_solana_client` header now uses live `RUNTIME_VERSION` so generated clients never drift from the installed runtime.
  196. ## New in v1.4.3
  197. - **`core.*` builtins expanded**: `EQ`/`NEQ`/`GT`/`LT`/`GTE`/`LTE` comparisons, `TRIM`/`STRIP`/`LSTRIP`/`RSTRIP` whitespace, `STARTSWITH`/`ENDSWITH`, `KEYS`/`VALUES`, `STR`/`INT`/`FLOAT`/`BOOL` coercions — all now implemented in `runtime/adapters/builtins.py`. These verbs were already in the validator contract; now they work at runtime too.
  198. - **MCP `ainl_compile` returns `frame_hints[]`**: list of `{name, type, source}` entries so agents can auto-construct the `frame` parameter before calling `ainl_run`. Add `# frame: name: type` comment lines to source for authoritative hints (`# frame: name` alone is allowed and yields `type: "any"`).
  199. - **MCP per-workspace limits**: place `ainl_mcp_limits.json` in the `fs.root` directory to tune `max_steps`/`max_time_ms`/`max_adapter_calls` per workspace without editing global server config. Invalid JSON in that file is ignored for limit purposes; successful `ainl_run` responses may include a `warnings` entry. **`max_adapter_calls: 0`** blocks all adapter dispatches (first `R` fails with a structured runtime error).
  200. - **MCP auto-cache**: when `fs` is enabled and `cache` is not explicitly listed in `adapters.enable`, the MCP server registers `cache` against `output/cache.json` or `cache.json` under `fs.root` if that file exists; non-empty files must be valid JSON. See **`docs/operations/MCP_RESEARCH_CONTRACT.md`** and tests **`tests/test_mcp_auto_cache_adapter.py`**, **`tests/test_mcp_workspace_limits.py`**, **`tests/test_mcp_frame_hints.py`**, **`tests/test_emit_armaraos_handpack.py`**.
  201. - **MCP per-run adapters** (from earlier in v1.4.3): `ainl_run` `adapters` parameter for scoped `http`, `fs`, `cache`, `sqlite` per call.
  202. - **Limit alignment**: `_SERVER_DEFAULT_LIMITS` in `runtime_runner_service.py` raised to match MCP defaults (`max_steps: 500000`, `max_adapter_calls: 50000`, `max_time_ms: 900000`).
  203. ## New in v1.4.2
  204. - **Host adapter policy**: **`AINL_ALLOW_IR_DECLARED_ADAPTERS`** relaxes env **`AINL_HOST_ADAPTER_ALLOWLIST`** when set; intelligence paths under **`intelligence/`** opt in by default unless **`AINL_INTELLIGENCE_FORCE_HOST_POLICY=1`**.
  205. - **CLI / MCP / runner**: **`ainl run`** registers **`web`**, **`tiktok`**, **`queue`**; MCP **`ainl_run`** grants match the HTTP runner; capabilities document host security env (see **`docs/LLM_ADAPTER_USAGE.md`**).
  206. - **Compiler + tooling**: strict-mode fixes for label-jump (**`J`**) graphs; **`effect_analysis`** / **`adapter_manifest`** coverage for **`web`**, **`tiktok`**, **`svc`**, **`crm`**, and expanded **`core`** verbs; intelligence examples use **`R queue Put`** and valid prelude layout; **`demo/.ainl-library-skip`** excludes dev demos from ArmaraOS App Store listings.
  207. ## New in v1.4.1
  208. - **Offline LLM provider (`offline`)**: deterministic **`AbstractLLMAdapter`** for **`config.yaml`** + **`register_llm_adapters`** demos and CI; use in **`llm.fallback_chain`** without live API keys (see **`fixtures/llm_offline.yaml`**).
  209. - **Wishlist examples + CI**: **`05b_unified_llm_offline_config.ainl`** — unified **`llm`** path vs **`llm_query`** mock in **`05_route_then_llm_mock.ainl`**; **`parser-compat`** runs strict wishlist validation + no-network smoke for graphs **01** and **05b**.
  210. - **`core.GET`**: real **`R`** target on **`CoreBuiltinAdapter`** (deep key/index reads via **`deep_get`**); strict entries in **`tooling/effect_analysis.py`** alongside **`llm.COMPLETION`**.
  211. - **LLM runtime**: **`LLMRuntimeAdapter`** normalizes verb casing so **`R llm.COMPLETION`** matches registry verbs (e.g. **`completion`**).
  212. ## New in v1.4.0
  213. - **ArmaraOS host pack** (optional — no hard dependency on the ArmaraOS binary): **`ainl emit --target armaraos`** (hand package: **`HAND.toml`**, **`<stem>.ainl.json`**, **`security.json`**, README), **`ainl status --host armaraos`** (canonical **`ARMARAOS_*`** + legacy **`OPENFANG_*`** env), **`ainl install-mcp --host armaraos`** (**`[[mcp_servers]]`** in **`~/.armaraos/config.toml`**, **`~/.armaraos/bin/ainl-run`**, PATH hints).
  214. - **Release / surfaces**: version alignment across **`pyproject.toml`**, **`RUNTIME_VERSION`**, **`CITATION.cff`**, **`tooling/bot_bootstrap.json`**; **`ainl serve`** **`GET /health`** reports **`version`** from **`RUNTIME_VERSION`**.
  215. - **Docs**: [`docs/ARMARAOS_INTEGRATION.md`](docs/ARMARAOS_INTEGRATION.md), host hub [`docs/getting_started/HOST_MCP_INTEGRATIONS.md`](docs/getting_started/HOST_MCP_INTEGRATIONS.md); integration tests and emitter import path fixes.
  216. ## New in v1.3.4
  217. - **Enhanced diagnostics** (`--enhanced-diagnostics`): graph context + Mermaid snippets on compile errors.
  218. - **Error highlighting** (`ainl visualize --highlight-errors`): error nodes styled in Mermaid output.
  219. - **Static cost estimates** (`--estimate` on `check`, `inspect`, `status`): per-node token/USD estimates.
  220. - **Audit trail adapter** (`--enable-adapter audit_trail --audit-sink file:///...`): immutable JSONL compliance log (graph must invoke `audit_trail.record`).
  221. - **Compact syntax preprocessor** (`ainl_preprocess.py`): Python-like **compact** `.ainl` authoring alongside opcodes — same IR, fewer surface tokens; see [`examples/compact/`](examples/compact/) and [`AGENTS.md`](AGENTS.md).
  222. > Tutorials: [Debugging with the Visualizer](docs/tutorials/debugging_with_visualizer.md) · [Production: Estimates & Audit](docs/tutorials/production_with_estimates_and_audit.md)
  223. **Full version history:** [`docs/CHANGELOG.md`](docs/CHANGELOG.md) · [`docs/RELEASE_NOTES.md`](docs/RELEASE_NOTES.md)
  224. **AINL helps turn AI from "a smart conversation" into "a structured worker."**
  225. > **v1.3.3 — Native Solana + prediction markets:** See [`docs/solana_quickstart.md`](docs/solana_quickstart.md) for strict graphs, env vars, dry-run-first flows, and `--emit solana-client` / `blockchain-client` usage, plus [`examples/prediction_market_demo.ainl`](examples/prediction_market_demo.ainl) for a concrete resolution → conditional payout pattern.
  226. ### v1.3.3 — Native Solana Support for Prediction Markets
  227. - **Deterministic Solana agents:** Strict AINL graphs for market creation, Pyth/Hermes resolution monitoring, and on-chain trades/payouts keep behavior explainable and testable.
  228. - **Key verbs:** `DERIVE_PDA` with **single-quoted JSON** seeds, `GET_PYTH_PRICE` (legacy + PriceUpdateV2), `HERMES_FALLBACK`, and `INVOKE` / `TRANSFER_SPL` with explicit priority fees (micro-lamports per CU).
  229. - **Dry-run + emit:** Full dry-run safety (`AINL_DRY_RUN=1`) and emitted standalone clients via `--emit solana-client` so you can rehearse flows before sending real transactions.
  230. - **Start here:** `docs/solana_quickstart.md` and `examples/prediction_market_demo.ainl`.
  231. All Solana additions are additive-only and preserve full Hyperspace compatibility.
  232. ### Recommended production stack: AINL graphs + AVM or general agent sandboxes
  233. AINL provides the deterministic, capability-declared graph layer. Pair it with Hyperspace AVM (`avmd`) or general runtimes (Firecracker microVMs, gVisor, Kubernetes Agent Sandbox, E2B-style runtimes, AVM Codes platform) for stronger isolation.
  234. - New metadata: optional `execution_requirements` in compiled IR (`avm_policy_fragment`, isolation/resource hints).
  235. - New CLI: `ainl generate-sandbox-config <file.ainl> [--target avm|firecracker|gvisor|k8s|general]`.
  236. - New unified shim: optional `runtime/sandbox_shim.py` auto-detects AVM/general sandbox endpoints and falls back cleanly.
  237. It is designed for teams building AI workflows that need multiple steps, state and memory, tool use, repeatable execution, validation and control, and lower dependence on long prompt loops.
  238. **Compile-once, run-many:** you author (or import) a graph once; the runtime executes it deterministically without re-spending LLM tokens on orchestration each time. Size economics are tracked with **tiktoken cl100k_base**; the **viable subset** (e.g. **public_mixed**) shows about **~1.02×** leverage for **minimal_emit** vs unstructured baselines—see **[`BENCHMARK.md`](BENCHMARK.md)**, **[`docs/benchmarks.md`](docs/benchmarks.md)**, and **[`docs/architecture/COMPILE_ONCE_RUN_MANY.md`](docs/architecture/COMPILE_ONCE_RUN_MANY.md)**.
  239. **Performance & benchmarks (updated Mar 2026):** Size results use **tiktoken cl100k_base** (billing-aligned for GPT-4o–class models). Reports separate **viable subset** rows from **legacy-inclusive** aggregates; **minimal_emit fallback stub** and **emitter compaction** (e.g. prisma / react_ts stubs) are documented in the transparency blocks. See **[`BENCHMARK.md`](BENCHMARK.md)** for tables; narrative hub **[`docs/benchmarks.md`](docs/benchmarks.md)** (highlights, commands, CI). Runtime economics and optional reliability batches: **`tooling/benchmark_runtime_results.json`** via `make benchmark` / `scripts/benchmark_runtime.py`. For long-lived OpenClaw deployments, pair these static benchmarks with live token-budget observability and cost tracking via **`docs/operations/TOKEN_AND_USAGE_OBSERVABILITY.md`** and the monitoring components documented in **`docs/MONITORING_OPERATIONS.md`**.
  240. ### CLI polish (OpenClaw, v1.3.3+)
  241. These commands are implemented in **`cli/main.py`** and documented in **`docs/agents/openclaw-operator.md`**. For bots and IDE tools, **`tooling/bot_bootstrap.json`** exposes the same surface under **`openclaw_commands`** (plus **`ai_native_lang_example_yml`**). Project lock example files: **`aiNativeLang.example.yml`** (repo root) and **`tooling/aiNativeLang.example.yml`** (packaged wheels).
  242. | Command | What it does |
  243. |--------|----------------|
  244. | **`ainl install openclaw --workspace PATH`** | Merges **`env.shellEnv`** into **`<workspace>/.openclaw/openclaw.json`**, bootstraps SQLite, registers three gold-standard crons, restarts gateway; use **`--dry-run`** to preview. |
  245. | **`ainl status`** | Unified health: workspace, schema, weekly budget (**`memory_records`** fallback), crons, drift, 7d tokens, estimated cost avoided (7d), caps. **`--json`** (pretty), **`--json-summary`** (one-line JSON), **`--summary`** (one-line text for alerts). |
  246. | **`ainl doctor --ainl`** | Validates OpenClaw + AINL integration (env, schema, cron names, bootstrap flag). |
  247. | **`ainl cron add FILE.ainl`** | Wraps **`openclaw cron add`** with message **`ainl run <path>`**; **`--cron`** or **`--every`**; **`--dry-run`** prints argv only. |
  248. | **`ainl dashboard`** | Runs **`scripts/serve_dashboard.py`** (emitted server under **`tests/emits/server`** — build first with **`scripts/run_tests_and_emit.py`** in a dev checkout); **`--port`**, **`--no-browser`**. |
  249. The CLI **fails fast** if **`tests/emits/server/server.py`** is missing (typical for PyPI-only installs), with the same **`run_tests_and_emit`** hint.
  250. **Shell shortcut:** **`scripts/setup_ainl_integration.sh`** delegates to **`ainl install openclaw`** (supports **`--dry-run`**, **`--workspace`**, **`--verbose`**).
  251. ---
  252. ## Get Started (3 minutes)
  253. **Requires Python 3.10+.** No git clone needed to try it.
  254. ```bash
  255. # 1. Install the CLI
  256. pip install ainativelang
  257. # 2. Create a new project (generates main.ainl + README)
  258. ainl init my-first-worker
  259. cd my-first-worker
  260. # 3. Check the program compiles cleanly (strict graph semantics)
  261. ainl check main.ainl --strict
  262. # 4. Run it
  263. ainl run main.ainl
  264. # 5. Visualise the control-flow graph
  265. ainl visualize main.ainl --output - # paste into https://mermaid.live
  266. ```
  267. That's it. Edit `main.ainl`, add adapter calls (cache, HTTP, LLM, memory), revalidate, run again.
  268. The `ainl init` command creates a clean, well-commented `main.ainl` designed for newcomers. It demonstrates core concepts — graph labels (`L1:` = control-flow node), requests (`R cache get` = read from the cache adapter), joins (`J` = return a value and finish the node), and branching — while remaining production-ready. Open `main.ainl` after scaffolding; the comments tell you exactly what each line does.
  269. ### Compact syntax (new in v1.3.3)
  270. AINL now supports a human-friendly **compact syntax** alongside the original opcodes.
  271. Both compile to the same IR. Compact is recommended for new code — 66% fewer tokens.
  272. ```ainl
  273. # examples/compact/hello_compact.ainl
  274. adder:
  275. result = core.ADD 2 3
  276. out result
  277. ```
  278. ```ainl
  279. # Branching, inputs, adapter calls, cron — all work
  280. classifier:
  281. in: level message
  282. severity = llm.classify level message
  283. if severity == "CRITICAL":
  284. http.POST ${SLACK_WEBHOOK} {text: message}
  285. out "alerted"
  286. out "logged"
  287. ```
  288. See [`examples/compact/`](examples/compact/) for more, and [`AGENTS.md`](AGENTS.md) for the full compact syntax reference.
  289. ### write → check → visualize → run loop
  290. 1. **Write** — author in compact or opcode syntax, or have an LLM emit a `.ainl` program.
  291. 2. **Validate** strict graph semantics:
  292. `ainl validate your.ainl --strict`
  293. Or the equivalent: `ainl check your.ainl --strict`
  294. Failures include structured diagnostics (line, suggestion, optional `llm_repair_hint`).
  295. Use `--json-diagnostics` for CI/machine-readable output.
  296. 3. **Visualize** control flow as Mermaid:
  297. `ainl visualize your.ainl --output - > graph.mmd` — paste into [mermaid.live](https://mermaid.live).
  298. 4. **Run** locally: `ainl run your.ainl`
  299. 5. **Emit** to other platforms: `ainl emit your.ainl --target langgraph -o graph.py`
  300. 6. **Serve** as HTTP API: `ainl serve --port 8080` (POST /validate, /compile, /run)
  301. 7. **Inspect canonical IR** (for agent/meta-agent loops): `ainl inspect your.ainl --strict`
  302. 8. **Emit JSONL execution tape** for grading/evolution: `ainl run your.ainl --trace-jsonl run.trace.jsonl`
  303. <details>
  304. <summary><strong>Advanced: Contributing or Custom Build (clone + editable install + CI bootstrap)</strong></summary>
  305. ```bash
  306. # Clone and create an isolated env (match CI: Python 3.10)
  307. git clone https://github.com/sbhooley/ainativelang.git
  308. cd ainativelang
  309. PYTHON_BIN=python3.10 VENV_DIR=.venv-py310 bash scripts/bootstrap.sh
  310. source .venv-py310/bin/activate # Windows: .venv-py310\Scripts\activate
  311. # Install with dev + web extras
  312. python -m pip install --upgrade pip
  313. python -m pip install -e ".[dev,web]"
  314. # Validate an example
  315. ainl check examples/hello.ainl --strict
  316. # Run the core test suite
  317. python scripts/run_test_profiles.py --profile core
  318. # Environment diagnostics
  319. ainl doctor
  320. # Full conformance matrix
  321. make conformance
  322. # Runner service (for API/orchestrator integration)
  323. python scripts/runtime_runner_service.py
  324. # GET http://localhost:8770/capabilities
  325. # POST http://localhost:8770/run {"code": "S app api /api\nL1:\nR core.ADD 2 3 ->sum\nJ sum"}
  326. ```
  327. See `docs/INSTALL.md` and `CONTRIBUTING.md` for full contributor setup.
  328. </details>
  329. ### Research-loop quickstart (meta-agent)
  330. For self-improving loops (generate -> inspect -> mutate -> evaluate), use:
  331. 1. **Inspect canonical IR**
  332. - `ainl inspect candidate.ainl --strict`
  333. 2. **Diff two candidates**
  334. - MCP tool: `ainl_ir_diff(file1, file2, strict=true)`
  335. 3. **Score fitness**
  336. - MCP tool: `ainl_fitness_report(file, runs=5, strict=true)`
  337. 4. **Repair invalid outputs**
  338. - MCP `ainl_validate` diagnostics include `llm_repair_hint`
  339. Contract and stable payload fields: `docs/operations/MCP_RESEARCH_CONTRACT.md`.
  340. For the full conformance matrix in one command (tokenizer, IR canonicalization, strict validation, runtime parity, emitter stability):
  341. `make conformance` (or `SNAPSHOT_UPDATE=1 make conformance` when intentionally updating snapshots).
  342. ### Community & Growth (start here too)
  343. - Growth strategy and milestones: [`GROWTH-PLAN.md`](GROWTH-PLAN.md)
  344. - Validation transparency: [`docs/validation-deep-dive.md`](docs/validation-deep-dive.md)
  345. - GitHub Discussions: <https://github.com/sbhooley/ainativelang/discussions>
  346. - Telegram: <https://t.me/AINL_Portal>
  347. - X / Twitter: <https://x.com/ainativelang>
  348. Short primer for stakeholders: **[`docs/WHAT_IS_AINL.md`](docs/WHAT_IS_AINL.md)** (canonical). [`WHAT_IS_AINL.md`](WHAT_IS_AINL.md) at repo root is a **stub** that points to the same content.
  349. ### Getting started with includes
  350. Pull in shared subgraphs from `modules/` (paths resolve next to your source file, then CWD, then `./modules/`):
  351. ```ainl
  352. include "modules/common/retry.ainl" as retry
  353. L1: Call retry/ENTRY ->out J out
  354. ```
  355. See **Includes & modules** below for `timeout.ainl`, strict rules, and the starter table.
  356. **AI agents:** See `docs/agents/openclaw-quickstart.md` for a full agent onboarding guide, or `docs/BOT_ONBOARDING.md` for the machine-readable bootstrap path.
  357. **Deeper setup:** See `docs/INSTALL.md` for platform-specific install, Docker, and pre-commit setup.
  358. ---
  359. ## Ecosystem & agent hosts (OpenClaw, ZeroClaw, Hermes)
  360. Import **Clawflows**-style `WORKFLOW.md` or **Agency-Agents**-style personality Markdown into a **deterministic** `.ainl` graph (cron trigger, sequential `Call` steps or agent gates, optional `memory` / `queue` hooks for OpenClaw-style bridges). If structured parsing cannot extract steps or agent fields, the importer **falls back** to a compiling **minimal_emit fallback stub** (Phase‑1 style) so you still get valid, reviewable graph source.
  361. **Host quick links:** [OpenClaw](https://openclaw.ai/) · [ZeroClaw skill (AINL)](https://github.com/sbhooley/ainativelang/tree/main/skills/ainl) · **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** · **[ArmaraOS](https://ainativelang.com/)** — AINL wiring for all four is in [`docs/getting_started/HOST_MCP_INTEGRATIONS.md`](docs/getting_started/HOST_MCP_INTEGRATIONS.md) (**`ainl install-mcp --host openclaw|zeroclaw|hermes|armaraos`**).
  362. The same path is exposed over MCP as **`ainl_list_ecosystem`**, **`ainl_import_clawflow`**, **`ainl_import_agency_agent`**, and **`ainl_import_markdown`** (stdio **`ainl-mcp`**). **Weekly auto-sync** ( **[`.github/workflows/sync-ecosystem.yml`](.github/workflows/sync-ecosystem.yml)** ) refreshes **[`examples/ecosystem/`](examples/ecosystem/)** from upstream public Markdown; community additions use **[`.github/PULL_REQUEST_TEMPLATE/`](.github/PULL_REQUEST_TEMPLATE/)** (workflow / agent templates).
  363. ```bash
  364. ainl import markdown https://raw.githubusercontent.com/nikilster/clawflows/main/workflows/available/community/check-calendar/WORKFLOW.md \
  365. --type workflow -o morning.ainl
  366. ainl compile morning.ainl
  367. ```
  368. Agent imports support `--personality "…"` and optional **`--generate-soul`** (writes `SOUL.md` and `IDENTITY.md` next to `-o`). Use **`--no-openclaw-bridge`** to emit `cache` instead of `memory` / `queue`.
  369. Shortcuts (fetch five samples from upstream into `examples/ecosystem/` — requires network):
  370. ```bash
  371. ainl import clawflows
  372. ainl import agency-agents
  373. ```
  374. ### Install AINL as a ZeroClaw skill
  375. ```bash
  376. zeroclaw skills install https://github.com/sbhooley/ainativelang/tree/main/skills/ainl
  377. ```
  378. This installs the AINL importer, runtime shim, and MCP tools directly into ZeroClaw.
  379. **Bootstrap** (PyPI self-upgrade, **`ainl-mcp`** in **`~/.zeroclaw/mcp.json`**, **`~/.zeroclaw/bin/ainl-run`**, **`PATH`** hint): from the skill directory run **`./install.sh`**, or run **`ainl install-mcp --host zeroclaw`** (use **`--dry-run`** / **`--verbose`** as needed). Alternative skill URL (standalone repo, when published): `https://github.com/sbhooley/ainl-zeroclaw-skill`.
  380. **Try in chat:** *“Import the morning briefing using AINL.”* (Then point the agent at a Clawflows URL, a preset from **`ainl_list_ecosystem`**, or **`ainl import markdown …`**.)
  381. Details: **[`docs/ZEROCLAW_INTEGRATION.md`](docs/ZEROCLAW_INTEGRATION.md)** · skill files: **[`skills/ainl/README.md`](skills/ainl/README.md)**.
  382. ### Install AINL as an OpenClaw skill
  383. [OpenClaw](https://openclaw.ai/) uses **npm** + **`openclaw onboard`** for the host CLI. AINL is added as a **skill folder** (not via **`zeroclaw skills install`**): copy **[`skills/openclaw/`](skills/openclaw/)** to **`~/.openclaw/skills/`** or **`<workspace>/skills/`**, or install from **ClawHub** when the skill is listed there.
  384. **Bootstrap** (PyPI self-upgrade, **`mcp.servers.ainl`** in **`~/.openclaw/openclaw.json`**, **`~/.openclaw/bin/ainl-run`**, **`PATH`** hint): from the skill directory run **`./install.sh`**, or run **`ainl install-mcp --host openclaw`** (use **`--dry-run`** / **`--verbose`** as needed). **`install.sh`** may run **`npm install -g openclaw@latest`** when npm is on PATH; set **`OPENCLAW_SKIP_NPM=1`** to skip.
  385. Once bootstrapped, the OpenClaw bridge automatically activates AINL's intelligence layer, including the cap auto-tuner and memory hydration/embedding pilot. This creates a self-managing runtime that continuously adjusts execution caps and prunes caches based on observed token usage — helping sustain **90–95%** token savings on high-frequency monitors and digests with zero recurring LLM orchestration cost (see **[`BENCHMARK.md`](BENCHMARK.md)** compile-once/run-many scenarios + [`scripts/benchmark_compile_once_run_many.py`](scripts/benchmark_compile_once_run_many.py)).
  386. For restricted Python sandboxes (PEP 668 externally-managed environments, common on OpenClaw/Clawbot hosts), no-root install order is: **venv first**, then **`--user`**, then **`--break-system-packages`** only as a last resort. `skills/ainl/install.sh` runs a compatible fallback sequence automatically and continues with MCP setup once `ainl` is available.
  387. **Intelligence layer (after bootstrap):** `install-mcp` / `./install.sh` wires **MCP** and **`ainl-run`**; **bridge cron, env profiles, and `run_intelligence`** still need the one-time operator pass in [`docs/operations/OPENCLAW_AINL_GOLD_STANDARD.md`](docs/operations/OPENCLAW_AINL_GOLD_STANDARD.md). With that wiring, the **OpenClaw bridge + intelligence** path exposes AINL’s **cap auto-tuner**, **rolling budget → monitor hydration**, and optional **embedding pilot**—a **self-managing resource & budget layer** (not self-tuning workflow logic: compiled graphs stay deterministic) that adjusts **caps and cache pressure** from observed usage. See [`docs/INTELLIGENCE_PROGRAMS.md`](docs/INTELLIGENCE_PROGRAMS.md) and [`docs/operations/TOKEN_AND_USAGE_OBSERVABILITY.md`](docs/operations/TOKEN_AND_USAGE_OBSERVABILITY.md). On **typical high-frequency monitoring and digest** workloads, that stack helps sustain **~90–95%** token savings versus prompt-loop orchestration for the same scheduled work, with **near-zero recurring orchestration cost** after compile—**validate** on your host (`ainl bridge-sizing-probe`, weekly trends).
  388. If you need a clean uninstall in managed sandboxes:
  389. ```bash
  390. pip3 uninstall -y ainl mcp aiohttp langgraph temporalio
  391. rm -rf /tmp/ainl-repo /data/.openclaw/workspace/skills/ainl /data/.local/lib/python3.13/site-packages/*ainl*
  392. ```
  393. **Try in chat:** *“Import the morning briefing using AINL.”*
  394. Details: **[`docs/OPENCLAW_INTEGRATION.md`](docs/OPENCLAW_INTEGRATION.md)** · skill files: **[`skills/openclaw/README.md`](skills/openclaw/README.md)**.
  395. **Standalone skill repo (optional, later):** publish the contents of **[`skills/openclaw/`](skills/openclaw/)** as the root of **[github.com/sbhooley/ainl-openclaw-skill](https://github.com/sbhooley/ainl-openclaw-skill)** so users can clone or vendor a single-purpose tree (same three files: `SKILL.md`, `install.sh`, `README.md`).
  396. ### Install AINL for Hermes Agent
  397. [Hermes Agent](https://github.com/NousResearch/hermes-agent) is a skill-native runtime with a closed learning loop. AINL pairs **deterministic compiled graphs** with Hermes via **`ainl-mcp`** (`ainl_run`) and **`--emit hermes-skill`** bundles (agentskills-style `SKILL.md` + `workflow.ainl` + `ir.json`).
  398. **Bootstrap:** **`pip install 'ainativelang[mcp]'`** then **`ainl install-mcp --host hermes`** (alias **`ainl hermes-install`**), or run **`skills/hermes/install.sh`**. Emit skills to **`~/.hermes/skills/ainl-imports/<name>/`**.
  399. Details: **[`docs/HERMES_INTEGRATION.md`](docs/HERMES_INTEGRATION.md)** · hub one-pager: **[`docs/integrations/hermes-agent.md`](docs/integrations/hermes-agent.md)** · skill pack: **[`skills/hermes/README.md`](skills/hermes/README.md)**.
  400. Curated templates with `original.md`, `converted.ainl`, and notes: **[`examples/ecosystem/README.md`](examples/ecosystem/README.md)**.
  401. **Weekly auto-sync:** the repo can refresh those sample trees from upstream on a schedule via GitHub Actions — see **[`.github/workflows/sync-ecosystem.yml`](.github/workflows/sync-ecosystem.yml)** (Monday 04:00 UTC, plus manual **workflow_dispatch**). PRs are opened only when `examples/ecosystem/**` conversions change. That workflow also **creates** the GitHub labels `ecosystem`, `automation`, `workflow`, and `agent` if missing (idempotent), then applies `ecosystem` + `automation` to the sync PR. If your org **disallows `GITHUB_TOKEN` from opening PRs**, set repository secret **`GH_PAT`** (PAT with repo + PR access to this repo only); see **[`docs/ECOSYSTEM_OPENCLAW.md`](docs/ECOSYSTEM_OPENCLAW.md)** — no access to upstream Clawflows/Agency-Agents orgs is required (public raw fetches only).
  402. ### Contributing workflows & agents
  403. After you push a branch, **open a pull request** on GitHub and use the **template** dropdown to choose **Submit Workflow (Clawflows-style)** or **Submit Agent (Agency-Agents-style)** (see [`.github/PULL_REQUEST_TEMPLATE/`](.github/PULL_REQUEST_TEMPLATE/)).
  404. You can also append `?quick_pull=1&template=workflow-submission.md` or `template=agent-submission.md` to your **compare** URL (`main`…`your-branch`).
  405. Templates: [`workflow-submission.md`](.github/PULL_REQUEST_TEMPLATE/workflow-submission.md) · [`agent-submission.md`](.github/PULL_REQUEST_TEMPLATE/agent-submission.md) · default [`pull_request_template.md`](.github/pull_request_template.md).
  406. ---
  407. ## Ultra Cost-Efficient Mode — `modules/efficient_styles.ainl`
  408. AINL ships a reusable output style module that routes user-facing responses through a dense, professional prose style and tool/agentic steps through structured JSON — eliminating redundancy at the LLM output layer.
  409. ```ainl
  410. include "modules/efficient_styles.ainl" as style
  411. my_workflow:
  412. in: question
  413. # ... do work ...
  414. result = core.GET work_result
  415. if is_user_facing:
  416. out = style.human_dense_response result
  417. out = style.terse_structured result
  418. ```
  419. **`human_dense_response`** — natural English, full paragraphs, examples where helpful. Strips hedging (`I think`, `basically`), redundancy, pleasantries. Code, numbers, steps remain 100 % exact and detailed.
  420. **`terse_structured`** — JSON-only output for tool steps and internal state. Never use for end-user responses.
  421. When combined with the ArmaraOS **Ultra Cost-Efficient Mode** input compressor (heuristic **input** reduction in Rust, **under 30 ms** target; typical **~40–56 %** input savings in Balanced mode on conversational text), using this module on **output** as well stacks savings on both sides of the LLM. Total bill impact depends on your input/output token mix and model pricing (e.g. Claude Sonnet 4.6 list **$3/M input · $15/M output**).
  422. **Cross-repo reference:** [docs/operations/EFFICIENT_MODE_ARMARAOS_BRIDGE.md](docs/operations/EFFICIENT_MODE_ARMARAOS_BRIDGE.md) — how CLI env, `efficient_styles.ainl`, and ArmaraOS `docs/prompt-compression-efficient-mode.md` relate.
  423. **CLI hint for ArmaraOS-hosted graphs** (sets `AINL_EFFICIENT_MODE` env var — Rust compression is on the host):
  424. ```bash
  425. ainl run my_workflow.ainl --efficient-mode balanced
  426. ```
  427. Note: the `--efficient-mode` flag only signals the ArmaraOS kernel via environment. **No compression runs in Python** — implementation is in **`openfang-runtime`** (`prompt_compressor`).
  428. ---
  429. ## Includes & modules
  430. Reuse battle-tested patterns without copy-pasting whole graphs. **Compile-time** `include` merges each module’s labels under **`alias/LABEL`** keys (for example `retry/ENTRY`, `retry/EXIT_OK`, `timeout/WORK`).
  431. **Syntax** (paths resolve next to the source file, then the current working directory, then `./modules/`):
  432. ```ainl
  433. include "modules/common/retry.ainl" as retry
  434. include modules/common/timeout.ainl as timeout
  435. ```
  436. Quotes around the path are optional when unambiguous; **`as alias`** sets the prefix for every label from that file.
  437. **Prelude order:** put every **`include`** line **before** the first top-level **`S`** or **`E`** (service / endpoint). Lines after **`S`** / **`E`** are not part of the include prelude; modules merged too late will not expose **`Call alias/…`** targets. See **`modules/common/README.md`**.
  438. ```ainl
  439. include "modules/common/retry.ainl" as retry
  440. include "modules/common/timeout.ainl" as timeout
  441. S app api /api
  442. L1: Call retry/ENTRY ->r J r
  443. L2: Call timeout/ENTRY ->t J t
  444. ```
  445. Subgraphs must define **`LENTRY:`** (merged as `alias/ENTRY`) and **at least one `LEXIT_*:`** label in **strict** mode. Do not declare top-level **`E`** / **`S`** inside includes—endpoints and services belong in the main program. Use **quoted** jumps for string payloads (`J "ok"`) so strict dataflow treats them as literals.
  446. Shared modules live in a **`modules/`** directory next to your files (with CWD / `./modules/` fallback—see compiler path resolution).
  447. **Starter modules in this repo**
  448. | Module | What it is |
  449. |--------|------------|
  450. | `modules/common/retry.ainl` | Minimal **ENTRY → EXIT_OK / EXIT_FAIL** pattern with sample `core.ADD` work—copy and extend with your own retry / backoff steps in the parent or module. |
  451. | `modules/common/timeout.ainl` | **Timeout / cancellation shape** (`ENTRY` → `Call WORK`, plus `LTIMEOUT` for the failure branch). The strict build uses `core.SLEEP` / `core.ECHO` stand-ins until real timer adapters are allowlisted—swap the `R` lines when your runtime supports them. |
  452. | `modules/common/token_cost_memory.ainl` | Shared deterministic memory helper for monitor workflows using the `workflow` namespace (`WRITE` + bounded `LIST` with metadata and filters). |
  453. | `modules/common/ops_memory.ainl` | Shared deterministic memory helper for monitor workflows using the `ops` namespace (`WRITE` + bounded `LIST` with metadata and filters). |
  454. | `modules/common/generic_memory.ainl` | Shared namespace-aware deterministic memory helper for workflows that write/list outside `workflow`/`ops` (for example `session`, `long_term`, `intel`). |
  455. | `modules/common/access_aware_memory.ainl` | Opt-in **access metadata** on reads/lists/writes: bumps **`metadata.last_accessed`** and **`metadata.access_count`** via **`LACCESS_READ`**, **`LACCESS_WRITE`**, **`LACCESS_LIST`**, or graph-safe **`LACCESS_LIST_SAFE`** (recommended when using graph-preferred execution for list snapshots). See module header and **`modules/common/README.md`**. |
  456. ### Starter Modules (in `modules/common/`)
  457. - `retry.ainl` — exponential backoff + max retries
  458. - `timeout.ainl` — timeout wrapper with placeholder delay (swap to real timer later)
  459. ```ainl
  460. include "modules/common/timeout.ainl" as timeout
  461. L1:
  462. Call timeout/ENTRY ->out
  463. J out
  464. ```
  465. More patterns coming soon (approval gate, circuit breaker, RAG retrieval, etc.). **Contract (strict):** included subgraphs expose **`LENTRY:`** (merged as `alias/ENTRY`) and at least one **`LEXIT_*:`** exit label; call them with **`Call alias/ENTRY ->out`** from the parent. **Agents** benefit from smaller, verified building blocks and stable qualified names (`retry/n1`, …) in the graph IR. Full behavior, path resolution, and tests: `tests/test_includes.py`, `docs/architecture/GRAPH_INTROSPECTION.md`.
  466. **See your includes in a diagram:** `ainl visualize main.ainl -o graph.mmd` — each alias becomes a Mermaid subgraph cluster; synthetic `Call →` edges into `alias/ENTRY` are annotated in the output.
  467. ### Reference bots
  468. - **Apollo X promoter** — production-shaped **strict** graph, HTTP **executor gateway**, OpenClaw/cron entrypoints, `executor_request_builder`, `record_decision`, and KV snapshot hooks: **[`apollo-x-bot/README.md`](apollo-x-bot/README.md)**. Optional **Growth Pack (v1.3)** (follow/discovery/like/thread/awareness, env-gated) is documented in the same README under *Optional Apollo-X Growth Pack*.
  469. ---
  470. ## Choose Your Path
  471. AINL can be used through three integration surfaces. All three run the same
  472. compiler and runtime; they differ in how you connect.
  473. External runtime option (opt-in): AINL can call PTC-Lisp through `ptc_runner`
  474. for reliability overlays and trace interoperability; see `docs/adapters/PTC_RUNNER.md`.
  475. The canonical "hello world" workflow used below:
  476. ```
  477. S app api /api
  478. L1:
  479. R core.ADD 2 3 ->x
  480. J x
  481. ```
  482. ### Path A — CLI only (fastest start)
  483. ```bash
  484. # Validate and inspect IR
  485. ainl-validate examples/hello.ainl --strict --emit ir
  486. # Mermaid diagram (paste into mermaid.live)
  487. ainl visualize examples/hello.ainl --output - > hello.mmd
  488. # Run directly
  489. ainl run examples/hello.ainl --json
  490. ```
  491. No server needed. Good for local development, scripting, and CI.
  492. ### Path B — HTTP runner (orchestrator integration)
  493. ```bash
  494. # Start the runner service
  495. ainl-runner-service
  496. # default: http://localhost:8770
  497. # Discover capabilities
  498. curl http://localhost:8770/capabilities
  499. # Execute a workflow
  500. curl -X POST http://localhost:8770/run \
  501. -H "Content-Type: application/json" \
  502. -d '{"code": "S app api /api\nL1:\nR core.ADD 2 3 ->x\nJ x", "strict": true}'
  503. ```
  504. Best for container deployments, sandbox controllers, and external orchestrators.
  505. See `docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md`.
  506. ### Path C — MCP host (AI coding agents)
  507. ```bash
  508. # Install with MCP extra
  509. pip install -e ".[mcp]"
  510. # Start the stdio MCP server
  511. ainl-mcp
  512. ```
  513. Then configure your MCP-compatible host (Gemini CLI, Claude Code, Codex, etc.)
  514. to use the `ainl-mcp` stdio transport. The host can call `ainl_validate`,
  515. `ainl_compile`, `ainl_capabilities`, `ainl_security_report`, and `ainl_run`.
  516. MCP v1 runs with safe defaults (core-only adapters, conservative limits).
  517. Operators can scope which tools/resources are exposed via named exposure
  518. profiles (`AINL_MCP_EXPOSURE_PROFILE`) or env-var inclusion/exclusion lists.
  519. See section 9 of `docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md` for the
  520. full quickstart, exposure scoping, and gateway deployment guidance.
  521. **Three layers:** *MCP exposure profile* → what tools/resources the host can
  522. discover. *Security profile / capability grant* → what execution is allowed.
  523. *Policy / limits* → what each run is constrained by.
  524. > **For Claude Code / Cowork / Dispatch users:** Treat AINL as a scoped MCP
  525. > tool provider and deterministic workflow/runtime layer underneath your host.
  526. > Start with `validate_only` or `inspect_only` exposure profiles, and only
  527. > enable `safe_workflow` after operators have reviewed security profiles,
  528. > grants, policies, limits, and adapter exposure. AINL is not the host, not
  529. > Cowork, not a gateway, and not a control plane. For a concrete
  530. > validator → inspector → safe-runner walkthrough, see the
  531. > *End-to-end example* section of
  532. > `docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md`.
  533. > **Core first, advanced later.** The paths above use the core compiler and
  534. > runtime only. Advanced/operator-only surfaces (agent coordination, memory
  535. > migration, OpenClaw extensions) are documented separately under
  536. > `docs/advanced/` and are not the recommended starting point for new users.
  537. For the full getting-started guide, see `docs/getting_started/README.md`.
  538. ---
  539. ## Why AINL Exists
  540. Modern AI systems are increasingly powerful at reasoning, but still unreliable and expensive when forced to orchestrate whole workflows through long prompt loops. Long prompt loops create:
  541. - Prompt bloat and rising token cost
  542. - Hidden state and brittle orchestration
  543. - Poor auditability and hard-to-debug tool behavior
  544. AINL addresses this by moving orchestration out of the model and into a deterministic execution substrate:
  545. 1. The model describes the workflow once
  546. 2. The compiler validates it
  547. 3. The runtime executes it deterministically
  548. 4. State lives in variables, cache, memory, databases, and adapters — not in prompt history
  549. ```mermaid
  550. flowchart LR
  551. A[AINL Source] --> B[Compiler]
  552. B --> C[Canonical Graph IR]
  553. C --> D[Runtime Engine]
  554. D --> E[Adapters / Tools / State]
  555. D --> F[Optional LLM Calls]
  556. ```
  557. The graph is the source of truth. The runtime is the orchestrator. The model is a bounded reasoning component inside the system.
  558. ---
  559. ## What Makes AINL Different
  560. ### 1. Graph-first, not prompt-first
  561. AINL programs compile to canonical graph IR. Execution follows graph semantics, not ad hoc conversational state.
  562. ### 2. AI-oriented surface syntax
  563. The surface language is intentionally compact and structured for parseability, determinism, and low-entropy generation by models.
  564. ### 3. Strict-mode guarantees
  565. AINL's strict mode enforces high-value invariants such as:
  566. - Canonical graph emission
  567. - No undeclared references
  568. - No unknown module operations
  569. - Adapter arity validation
  570. - No unreachable or duplicate nodes
  571. - Canonical node IDs
  572. - Validated call returns
  573. - Controlled exits
  574. Strict validation is paired with **structured diagnostics** (native `Diagnostic` records: lineno, spans, kinds, suggested fixes) surfaced on the CLI with **rich** or plain text, or **JSON** for automation (`ainl-validate`, `ainl visualize`, language server). See `docs/INSTALL.md` and `docs/CONFORMANCE.md`.
  575. ### 4. Adapters separate "what" from "how"
  576. AINL describes what should happen. Adapters implement how it happens. This allows the same graph language to drive HTTP, SQLite, filesystem operations, email/calendar/social integrations, service checks, cache/memory, queues, WASM modules, and OpenClaw-specific operational workflows.
  577. PTC-style overlays are additive and opt-in:
  578. - `ptc_runner` for external PTC-Lisp execution (`R ptc_runner run ...`)
  579. - `llm_query` for ad-hoc LLM calls in graph steps
  580. - optional `# signature: ...` metadata with runtime checks via `intelligence/signature_enforcer.py`
  581. - `_`-prefixed context firewall at adapter/export serialization boundaries
  582. - trajectory export to PTC-compatible JSONL via `intelligence/trace_export_ptc_jsonl.py`
  583. ### 5. Multi-target leverage
  584. One AINL program can describe a workflow once and emit multiple downstream artifacts (FastAPI, React/TypeScript, Prisma, OpenAPI, Docker/Compose, Kubernetes, cron/queue/scraper outputs), rather than forcing an agent to regenerate parallel implementations.
  585. **Emitters:** `--emit hyperspace` via `python3 scripts/validate_ainl.py …` writes `hyperspace_agent.py` (use `-o path`). It embeds the compiled IR and runs it with `RuntimeEngine`, registers `vector_memory` / `tool_registry`, optional `hyperspace_sdk` import stub, and respects `AINL_LOG_TRAJECTORY` for `SOURCE_STEM.trajectory.jsonl` in the current working directory.
  586. Hyperspace happy path (use `--enable-adapter vector_memory` and `--enable-adapter tool_registry` with `ainl run` when the graph calls those adapters). After emit, run `python3 demo_agent.py` from **repo root** (or any working tree that contains `runtime/engine.py` and `adapters/`) so imports resolve:
  587. ```bash
  588. ainl-validate examples/hyperspace_demo.ainl --strict --emit hyperspace -o demo_agent.py
  589. cd /path/to/AI_Native_Lang && AINL_LOG_TRAJECTORY=1 python3 demo_agent.py
  590. # optional: ainl run examples/hyperspace_demo.ainl --enable-adapter vector_memory --enable-adapter tool_registry --log-trajectory --json
  591. ```
  592. ### 6. Compile-once, run-many
  593. Once a workflow is compiled, it executes repeatedly without needing the model to regenerate orchestration logic. Runtime state is handled by adapters. Recurring workflows avoid repeated prompt-loop costs.
  594. ---
  595. ## Competitive Landscape
  596. AINL sits at the intersection of graph-native agent orchestration, deterministic workflow execution, and AI-native programming languages.
  597. | System | Focus | Difference vs AINL |
  598. |--------|------|-------------------|
  599. | LangChain / LangGraph | Chain/graph-based agent orchestration | No canonical IR, no compiler, no compile-once/run-many; LangGraph adds graphs but remains prompt-driven |
  600. | CrewAI | Multi-agent role-based orchestration | Role/prompt-driven, no deterministic graph execution or adapter-level effect control |
  601. | Temporal | Durable workflow execution | Not AI-native, no DSL or emitters |
  602. | Restate | Durable agents & services | Runtime-focused, no language layer |
  603. | Microsoft Agent Framework | Typed graph workflows | Framework, not a compiled language |
  604. | AutoGen | Multi-agent coordination | Prompt/event-driven, not deterministic graphs |
  605. For a detailed comparison of graph-native vs prompt-loop architectures with production evidence, see `docs/case_studies/graph_agents_vs_prompt_agents.md`.
  606. AINL uniquely combines:
  607. - graph-first canonical IR
  608. - strict validation & conformance
  609. - adapter-based effect system
  610. - compile-once, run-many execution
  611. - multi-target emission (API, UI, DB, infra)
  612. → Treating AI systems as **deterministic programs**, not prompt loops.
  613. ---
  614. ## Who AINL Is For
  615. AINL is best suited for:
  616. - AI engineers and agent builders
  617. - teams building internal AI workers and structured automations
  618. - platform and ops teams that need controlled AI workflows
  619. - enterprises that care about repeatability, auditability, and workflow governance
  620. AINL is less optimized for casual chatbot prototyping, one-off prompt hacks, or no-code-first usage.
  621. ### Why businesses care
  622. AINL matters when AI moves beyond demos and starts doing real operational work. It helps reduce the gap between "a clever AI demo" and "a workflow a business can actually run" — repeatable, inspectable, stateful, tool-using, cost-aware, and easier to validate and maintain.
  623. ### Why AI agents care
  624. An AINL program gives an agent explicit control flow, explicit side effects, compile-time validation, capability-aware boundaries, externalized memory, and reproducible runtime behavior. The LLM stops being the whole control plane and becomes a reasoning component inside a deterministic system.
  625. ---
  626. ## Real-World Usage: Apollo + OpenClaw
  627. AINL is not just a speculative language design. It is already used in live OpenClaw-integrated workflows.
  628. The Apollo / OpenClaw stack exercises adapters such as `email`, `calendar`, `social`, `db`, `svc`, `cache`, `queue`, `wasm`, `memory`, `extras`, and `tiktok`.
  629. Production-validated examples include:
  630. - `demo/monitor_system.lang` — recurring multi-module monitor
  631. - Daily digest workflows
  632. - Infrastructure watchdogs
  633. - Lead enrichment
  634. - Token cost tracking
  635. - TikTok SLA monitoring
  636. - Canary probes
  637. - Memory pruning
  638. - Session continuity
  639. - Meta-monitoring of the monitor fleet itself
  640. These programs demonstrate that AINL is effective for recurring monitors, stateful automation, autonomous ops, safety-aware tool orchestration, and long-lived agent systems.
  641. ### Where AINL helps most
  642. AINL is most valuable when workflows are recurring, stateful, branching, safety-sensitive, multi-step, multi-target, or shared across teams or agents. For trivial one-off scripts, the gain is smaller. For multi-step agent systems and autonomous operational workflows, the gain can be substantial.
  643. ---
  644. ## Token Efficiency
  645. AINL's compactness and cost benefits should be described carefully.
  646. - **Compile-once, run-many:** You pay generation cost once; the **deterministic runtime** executes the graph without a prompt loop per invocation. **Runtime benchmarks** (`scripts/benchmark_runtime.py`, `tooling/benchmark_runtime_results.json`) measure post-compile latency, RSS, optional **execution reliability** batches, and **tiktoken**-based cost estimates—see **[`docs/benchmarks.md`](docs/benchmarks.md)**.
  647. - **Token Cost Efficiency:** AINL can save tokens in two ways. First, at authoring time, because the DSL is denser than general-purpose code. Second, at runtime, because compiled AINL programs execute deterministically through adapters and do not require recurring model inference on each execution. In practice, this can significantly reduce prompt and code-generation volume for non-trivial workflows while also eliminating repeated model-generation cost during normal operation. Complex monitors and similar programs that take roughly 30k–70k tokens in AINL (including the program itself and relevant runtime context) are estimated to require 3–5× more tokens, depending on workload, when generated as equivalent Python or TypeScript by an LLM. Those equivalents would also typically lack AINL's strict validation, graph introspection, and multi-target emission. After the initial learning curve, AINL is estimated to reduce per-task token burn by 2–5× for non-trivial automation. For simple tasks, the savings are smaller but still generally positive due to DSL density.
  648. Bottom line: AINL lowers overall token usage while increasing capability, predictability, and reliability.
  649. **What is supported today:**
  650. - **Reproducible size metrics** default to **tiktoken cl100k_base** (see **[`BENCHMARK.md`](BENCHMARK.md)**). Headline ratios use a **viable subset** for mixed profiles so representative workloads are not drowned out by tiny legacy shells; **legacy-inclusive** totals are printed **separately** for honesty.
  651. - AINL is often denser than equivalent generated implementation artifacts *in the benchmark setup we publish*—always profile- and mode-scoped
  652. - **minimal_emit** is the more honest deployment comparison; **full_multitarget** is downstream expansion leverage, not apples-to-apples terseness
  653. - **`--strict-mode`** on `scripts/benchmark_size.py` enables true strict compilation (reachability pruning) for **`canonical_strict_valid`** only—see `BENCHMARK.md` callout when active
  654. - Compile-once / run-many workflows reduce repeated model-generation cost
  655. **What is not supported:**
  656. - Universal compactness claims against all mainstream languages
  657. - Guaranteed tokenizer pricing savings from lexical proxy metrics alone
  658. **Current benchmark framing:**
  659. - **`canonical_strict_valid`** is the primary headline profile (**19/19** viable example programs in `tooling/artifact_profiles.json`).
  660. - Default sizing is **tiktoken cl100k_base** in markdown tables; JSON still records the CLI `--metric` (default `tiktoken`). Legacy `--metric=approx_chunks` is optional and **deprecated** for billing claims.
  661. - **Highlights (from [`BENCHMARK.md`](BENCHMARK.md), Mar 2026):** `make benchmark` uses **`--mode wide`**: strict-valid **~3.2×** `full_multitarget_core` (six compiler emitters) / **~362×** `full_multitarget` (+ hybrid **langgraph**/**temporal** wrappers with embedded IR) / **~0.76×** `minimal_emit` (tk). **`public_mixed` viable** **72/85**; **`compatibility_only` viable** **53/66**. Full detail: **[`docs/benchmarks.md#benchmark-highlights-march-2026`](docs/benchmarks.md#benchmark-highlights-march-2026)**.
  662. - **Transparency:** **`prisma` / `react_ts`** benchmark stubs **compacted Mar 2026** (~50–70% tk reduction on those emit lines); **minimal_emit** may add a small **python_api fallback stub** (~20–30 tk) when no selected target emits code—both are documented in `BENCHMARK.md`.
  663. - In `full_multitarget`, canonical strict examples show strong expansion leverage; runtime traces on the tracked benchmark JSON typically show **100%** success on optional reliability batches for strict-valid workloads with **sub-millisecond** measured latency (machine-dependent).
  664. - In `minimal_emit`, mixed compatibility examples can be smaller or larger depending on artifact class and required targets
  665. - **Evidence pack:** reproducible **size** + **runtime** benchmarks (tiktoken sizing, compile-time column, latency/RSS, cost estimates, reliability batches, handwritten baselines) live in [`BENCHMARK.md`](BENCHMARK.md) with automation in `make benchmark` / `make benchmark-ci` and CI regression gating—see **[`docs/benchmarks.md`](docs/benchmarks.md)** for the full map.
  666. ```bash
  667. # Refresh size markdown + JSON and runtime JSON (local).
  668. # Uses `scripts/benchmark_size.py --mode wide` (core + full hybrid + minimal_emit).
  669. make benchmark
  670. # CI-style JSON only (does not rewrite BENCHMARK.md)
  671. make benchmark-ci
  672. ```
  673. Hybrid / LangGraph / Temporal optional deps: **`pip install -e ".[interop]"`** or **`".[benchmark]"`** — see **[`docs/PACKAGING_AND_INTEROP.md`](docs/PACKAGING_AND_INTEROP.md)**.
  674. > AINL provides a compact, reproducible, profile-segmented way to express graph workflows and multi-target systems, while often reducing repeated AI generation effort and avoiding repeated orchestration token burn during runtime.
  675. ---
  676. ## Status
  677. AI Native Lang is an actively developed open-core project. The core compiler/runtime and graph tooling are real and usable; some language surfaces, examples, targets, and evaluation workflows are still being stabilized.
  678. Public release expectations:
  679. - the **graph-first compiler/runtime core** is the most stable part of the project,
  680. - **server/OpenAPI/runtime/tooling** are the strongest current implementation lanes,
  681. - some examples and compatibility artifacts are intentionally classified as non-strict or legacy,
  682. - broad target coverage exists, but not every target is equally mature or equally validated.
  683. For implementation and shipped-capability status, see:
  684. - [docs/CONFORMANCE.md](docs/CONFORMANCE.md)
  685. - [docs/RELEASE_READINESS.md](docs/RELEASE_READINESS.md)
  686. - [docs/runtime/TARGETS_ROADMAP.md](docs/runtime/TARGETS_ROADMAP.md)
  687. - [docs/AINL_CANONICAL_CORE.md](docs/AINL_CANONICAL_CORE.md)
  688. - [docs/EXAMPLE_SUPPORT_MATRIX.md](docs/EXAMPLE_SUPPORT_MATRIX.md)
  689. - [docs/advanced/SAFE_USE_AND_THREAT_MODEL.md](docs/advanced/SAFE_USE_AND_THREAT_MODEL.md)
  690. ### Best supported today
  691. - Canonical compile path in `compiler_v2.py`
  692. - Graph-first runtime execution in `runtime/engine.py`
  693. - Formal prefix grammar orchestration in `compiler_grammar.py`
  694. - Graph normalization, diff, patch, and canonicalization tooling in `tooling/`
  695. - Server/OpenAPI emission and runtime-backed execution flow
  696. - Runtime-native adapters with contract tests: `http`, `sqlite`, `postgres`, `mysql`, `redis`, `dynamodb`, `airtable`, `supabase`, `fs`, `tools`
  697. - Runner service with policy-gated `/run`, `/capabilities`, health/metrics: `scripts/runtime_runner_service.py`
  698. - Adapter privilege-tier metadata and security profiles: `tooling/adapter_manifest.json`, `tooling/security_profiles.json`
  699. - Security/privilege introspection tooling: `tooling/security_report.py`
  700. - Adapter tier model — **29 core + 16 extended (all supported, no deprecations)**: `docs/adapters/ADAPTER_TIERS.md`
  701. ### Use with care
  702. - Compatibility examples are retained intentionally; do not assume all public examples are strict-valid.
  703. - Some emitters are more mature than others; treat `docs/runtime/TARGETS_ROADMAP.md` as a capability map, not a promise that every target is equally production-ready.
  704. - Model-training and benchmark artifacts are included, but they should be read together with `BENCHMARK.md`, `docs/OLLAMA_EVAL.md`, and `docs/TEST_PROFILES.md` rather than as standalone proof of maturity.
  705. ---
  706. ## Documentation
  707. ### Essential reading
  708. - What is AINL? (canonical primer + capabilities): **`docs/WHAT_IS_AINL.md`** · root **`WHAT_IS_AINL.md`** (stub → docs)
  709. - Whitepaper draft (architecture, benchmarks, OpenClaw ops + token economics through **v1.8.0**, async runtime, reactive DB/realtime adapters; native Solana — **`docs/solana_quickstart.md`**): **`WHITEPAPERDRAFT.md`**
  710. - Reactive / event-driven workflows (DynamoDB Streams, Supabase Realtime, Redis Pub/Sub, Airtable webhooks) + examples: `docs/reactive/REACTIVE_EVENTS.md`, `examples/reactive/`
  711. - Advanced durability patterns for multi-node/cross-process checkpoints and cursors using existing adapters only: `docs/reactive/ADVANCED_DURABILITY.md`
  712. - Packaged durability templates (Redis + Postgres checkpoint helpers): `templates/durability/`
  713. - Production starter templates (durability + observability-ready workers): `templates/production/`
  714. - AINL → HTTP workers (bridge envelope, schema, include): `docs/integrations/EXTERNAL_EXECUTOR_BRIDGE.md` · `schemas/executor_bridge_request.schema.json` · `modules/common/executor_bridge_request.ainl`
  715. - Getting started (3 integration paths): `docs/getting_started/README.md`
  716. - Primary docs hub: `docs/README.md`
  717. - Audience guide: `docs/AUDIENCE_GUIDE.md`
  718. - Spec: `docs/AINL_SPEC.md`
  719. - Canonical core: `docs/AINL_CANONICAL_CORE.md`
  720. - Full docs reference map: `docs/DOCS_INDEX.md`
  721. - Benchmarks & evidence (size, runtime, CI, LLM/cloud): `docs/benchmarks.md`
  722. ### Architecture and internals
  723. - Graph/IR introspection: `docs/architecture/GRAPH_INTROSPECTION.md`
  724. - State discipline (tiered state model): `docs/architecture/STATE_DISCIPLINE.md`
  725. - Memory adapter contract (v1 + additive v1.1 deterministic metadata/filtering): `docs/adapters/MEMORY_CONTRACT.md`, `docs/adapters/MEMORY_CONTRACT_V1_1_RFC.md`
  726. #### Memory & State
  727. Workflow memory is **externalized through adapters** (not the prompt). Production-style programs combine **session or workflow namespaces**, **TTLs**, **bounded list filters**, and **prune** so retention stays predictable under load. For a full OpenClaw-style illustration of cache + memory + budget enforcement (including audit rows and pruning hooks), see **`demo/session_budget_enforcer.lang`**. Optional **access-aware** touches (recency / frequency metadata on **`memory`** records) live in **`modules/common/access_aware_memory.ainl`**; use **`LACCESS_LIST_SAFE`** when you need list-wide touches under **graph-preferred** execution (see module header).
  728. - Runtime semantics: `SEMANTICS.md`
  729. - Runtime/compiler ownership: `docs/RUNTIME_COMPILER_CONTRACT.md`
  730. - Grammar reference: `docs/language/grammar.md`
  731. - Conformance and strict policy: `docs/CONFORMANCE.md`
  732. - Embedding in meta-agent loops: `docs/EMBEDDING_RESEARCH_LOOPS.md`
  733. - MCP research payload contract: `docs/operations/MCP_RESEARCH_CONTRACT.md`
  734. ### Operations and deployment
  735. - Sandbox execution profiles: `docs/operations/SANDBOX_EXECUTION_PROFILE.md`
  736. - Runtime container guide: `docs/operations/RUNTIME_CONTAINER_GUIDE.md`
  737. - External orchestration guide: `docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md`
  738. - Integration story (AINL in agent stacks): `docs/INTEGRATION_STORY.md`
  739. - Autonomous ops playbook: `docs/operations/AUTONOMOUS_OPS_PLAYBOOK.md`
  740. - Named security profiles: `tooling/security_profiles.json`
  741. - Security/privilege report: `tooling/security_report.py`
  742. - Safe use and threat model: `docs/advanced/SAFE_USE_AND_THREAT_MODEL.md`
  743. - MCP server overview: section **9** of `docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md`
  744. - MCP server for AI coding agents: `scripts/ainl_mcp_server.py` (see external orchestration guide, section 9)
  745. - LLM/tool cost & budget observability pack (CostTracker/BudgetPolicy/dashboard): `docs/MONITORING_OPERATIONS.md` and `docs/INTELLIGENCE_PROGRAMS_INTEGRATION.md`
  746. ### Examples and case studies
  747. - Example support levels: `docs/EXAMPLE_SUPPORT_MATRIX.md`
  748. - OpenClaw agent quickstart: `docs/agents/openclaw-quickstart.md`
  749. - Case studies: `docs/case_studies/` — graph-native vs prompt-loop agents, runtime cost advantage
  750. - Workflow patterns: `docs/PATTERNS.md`
  751. ### For AI agents and bots
  752. - **Bots / implementation discipline:** `docs/BOT_ONBOARDING.md` — onboarding for agents; **`docs/OPENCLAW_IMPLEMENTATION_PREFLIGHT.md`** is required before implementation work. Machine-readable pointers: `tooling/bot_bootstrap.json`.
  753. ### Release and contribution
  754. - **Target package version (this tree / next PyPI upload):** **`ainativelang` 1.8.0** (see `pyproject.toml`, `runtime/engine.py` **`RUNTIME_VERSION`**, `docs/CHANGELOG.md`, `docs/RELEASE_NOTES.md`). **Latest published on PyPI:** [pypi.org/project/ainativelang](https://pypi.org/project/ainativelang/#history) — run **`pip install -U ainativelang`** after **1.8.0** appears there (**`docs/RELEASING.md`**).
  755. - Release readiness matrix: `docs/RELEASE_READINESS.md`
  756. - No-break migration tracker: `docs/NO_BREAK_MIGRATION_PLAN.md`
  757. - Release notes: `docs/RELEASE_NOTES.md`
  758. - Maintainer release execution guide: `docs/RELEASING.md`
  759. - Hybrid deployment runbook: `docs/hybrid/OPERATOR_RUNBOOK.md`
  760. - Immediate post-release roadmap: `docs/POST_RELEASE_ROADMAP.md`
  761. - Docs maintenance contract: `docs/DOCS_MAINTENANCE.md`
  762. - Contributor guide: `CONTRIBUTING.md`
  763. - Security and support: `SECURITY.md`, `SUPPORT.md`
  764. - Machine-readable support levels: `tooling/support_matrix.json`
  765. - Safe optimization guidance: `docs/runtime/SAFE_OPTIMIZATION_POLICY.md`
  766. ---
  767. ## Technical Architecture
  768. AI Native Lang (AINL) is a compact language and toolchain for agent-oriented workflows. The compiler emits canonical graph IR and compatibility `legacy.steps`; the runtime executes graph-first semantics through `runtime/engine.py`.
  769. AINL is best understood as a **graph-canonical intermediate programming system** with:
  770. - a compact textual surface for generation and transport,
  771. - a compiler/runtime pair designed around deterministic IR,
  772. - emitters for practical targets,
  773. - and tooling for constrained decoding, diffing, patching, and evaluation.
  774. ### Core invariant
  775. > **Canonical IR = nodes + edges; everything else is serialization.**
  776. AINL source is a compact surface language for producing the canonical graph. That graph can then be executed by the runtime, inspected and diffed, validated in strict mode, or emitted into targets such as FastAPI, React/TypeScript, Prisma, OpenAPI, Docker/Compose, cron/queue/scraper/MT5 outputs.
  777. ### Surfaces and usage lanes
  778. **Core / safe-default surface:** The canonical compiler/runtime and graph IR (`compiler_v2.py`, `runtime/engine.py`), canonical language scope (`docs/AINL_CANONICAL_CORE.md`, `docs/AINL_SPEC.md`), strict/compatible examples classified in `docs/EXAMPLE_SUPPORT_MATRIX.md`, graph/IR tooling (`docs/architecture/GRAPH_INTROSPECTION.md`), server/OpenAPI emission and basic workflows.
  779. **Sandboxed and operator-controlled deployments:** AINL is architecturally suited to run inside sandboxed, containerized, or operator-controlled execution environments. The runtime's adapter allowlist, resource limits, and policy validation tooling provide the configuration surface that external orchestrators and sandbox controllers need to restrict and govern AINL execution. AINL is the **workflow layer**, not the sandbox or security layer; containment, network policy, and process isolation are the responsibility of the hosting environment.
  780. Current security and operator capabilities:
  781. - **Capability grant model** — each execution surface (runner, MCP server) loads a server-level grant at startup from a named security profile (`AINL_SECURITY_PROFILE` / `AINL_MCP_PROFILE` env vars). Callers can tighten restrictions per-request but never widen beyond what the server allows. See `docs/operations/CAPABILITY_GRANT_MODEL.md`.
  782. - **Adapter capability gating** — explicit allowlists via `AdapterRegistry`; only adapters in the effective grant's allowlist can be called.
  783. - **Policy-gated execution** — the `/run` endpoint validates compiled IR against the effective policy (derived from the grant) before execution. Forbidden adapters, effects, privilege tiers, and destructive adapters trigger HTTP 403 with structured errors.
  784. - **Capability discovery** — `GET /capabilities` exposes available adapters, verbs, effect defaults, privilege tiers, and adapter metadata (`destructive`, `network_facing`, `sandbox_safe`) so orchestrators can make informed decisions before submitting workflows.
  785. - **Named security profiles** — `tooling/security_profiles.json` packages recommended adapter allowlists, privilege-tier restrictions, runtime limits, and orchestrator expectations for common deployment scenarios (`local_minimal`, `sandbox_compute_and_store`, `sandbox_network_restricted`, `operator_full`, `firm`). `AINL_SECURITY_PROFILE=firm` is the decision-graph grant (`core`, `llm`, `db`, `queue`; no `db.D`; no `core.ENV`). Contract: `docs/operations/DECISION_OPS_1_8_2.md`.
  786. - **Mandatory default limits** — runner and MCP execution surfaces apply conservative resource ceilings (`max_steps`, `max_depth`, `max_adapter_calls`, etc.) by default. Callers can tighten limits but not widen them.
  787. - **Privilege-tier metadata** — each adapter carries a `privilege_tier` (`pure`, `local_state`, `network`, `operator_sensitive`) plus `destructive`, `network_facing`, and `sandbox_safe` boolean classification fields in `tooling/adapter_manifest.json`.
  788. - **Structured audit logging** — the runner service emits structured JSON log events (`run_start`, `adapter_call`, `run_complete`, `run_failed`, `policy_rejected`) with UTC timestamps, trace IDs, duration, and result hashes. The `adapter_call` line records `arg_count` and `arg_types`, not argument values. See `docs/operations/AUDIT_LOGGING.md`.
  789. - **Security introspection** — `tooling/security_report.py` generates a per-label, per-graph privilege map showing which adapters, verbs, privilege tiers, and adapter metadata flags a workflow uses.
  790. AINL does **not** provide container isolation, process sandboxing, network policy enforcement, authentication/encryption, or multi-tenant isolation. These remain the responsibility of the hosting environment.
  791. See:
  792. - `docs/INTEGRATION_STORY.md` — how AINL fits inside agent stacks, pain-to-solution map, integration surface
  793. - Generic external executors via HTTP bridge (multi-backend capable): [`docs/integrations/EXTERNAL_EXECUTOR_BRIDGE.md`](docs/integrations/EXTERNAL_EXECUTOR_BRIDGE.md) — **MCP (`ainl-mcp`) remains primary for OpenClaw/NemoClaw**; HTTP bridge is secondary. **Artifacts:** [`schemas/executor_bridge_request.schema.json`](schemas/executor_bridge_request.schema.json), [`schemas/executor_bridge_validate.py`](schemas/executor_bridge_validate.py), [`modules/common/executor_bridge_request.ainl`](modules/common/executor_bridge_request.ainl).
  794. - `docs/operations/CAPABILITY_GRANT_MODEL.md` — host handshake, restrictive-only merge, env-var profile loading
  795. - `docs/operations/AUDIT_LOGGING.md` — structured runtime event logging
  796. - `docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md` — capability discovery, policy-gated execution, integration checklist
  797. - `docs/operations/SANDBOX_EXECUTION_PROFILE.md` — adapter profiles, limit profiles, environment guidance, named security profiles
  798. - `docs/operations/RUNTIME_CONTAINER_GUIDE.md` — containerized deployment patterns
  799. - `docs/advanced/SAFE_USE_AND_THREAT_MODEL.md` — trust model, safe-use guidance, and privilege-tier explanation
  800. **Advanced / operator-only / experimental surface:** AINL also includes advanced, extension/OpenClaw-oriented features that are not the safe-default entry path and are not a built-in secure orchestration or multi-agent safety layer. These are intended for operators who understand the risks and have added their own safeguards.
  801. Key docs in this lane:
  802. - `docs/advanced/SAFE_USE_AND_THREAT_MODEL.md` — safe use, threat model, and advisory vs enforced fields.
  803. - `docs/advanced/AGENT_COORDINATION_CONTRACT.md` — AgentTaskRequest/AgentTaskResult/AgentManifest envelopes and local mailbox contract.
  804. - `docs/EXAMPLE_SUPPORT_MATRIX.md` (OpenClaw compatibility family) — advanced coordination and OpenClaw examples.
  805. - `tooling/coordination_validator.py`, `scripts/validate_coordination_mailbox.py` — optional mailbox linter for advanced coordination usage.
  806. ### Stability boundaries
  807. - **Canonical today:** compiler semantics and strict validation in `compiler_v2.py`, runtime semantics in `runtime/engine.py` (`RuntimeEngine`), formal grammar orchestration in `compiler_grammar.py`
  808. - **Compatibility surfaces:** `runtime/compat.py` and `runtime.py` are compatibility wrappers/re-exports, `grammar_constraint.py` is a compatibility composition layer, `legacy.steps` are compatibility IR fields
  809. - **Artifact profile contract:** strict/non-strict/legacy expectations are defined in `tooling/artifact_profiles.json`
  810. - **Support-level contract:** canonical/compatible/deprecated intent is declared in `tooling/support_matrix.json`; public recommended language scope is described in `docs/AINL_CANONICAL_CORE.md`
  811. ### Standardized health envelope
  812. All production monitors use a common message envelope for notifications:
  813. ```json
  814. {
  815. "envelope": {"version":"1.0","generated_at":"<ISO>"},
  816. "module": "<monitor_name>",
  817. "status": "ok" | "alert",
  818. "ts": "<ISO>",
  819. "metrics": { ... },
  820. "history_24h": { ... },
  821. "meta": {}
  822. }
  823. ```
  824. See [`docs/operations/STANDARDIZED_HEALTH_ENVELOPE.md`](docs/operations/STANDARDIZED_HEALTH_ENVELOPE.md).
  825. ---
  826. ## Deployment
  827. ### Production deploy (Docker)
  828. From repo root after emitting:
  829. ```bash
  830. cd tests/emits/server
  831. docker compose up --build
  832. ```
  833. Or build image from repo root: `docker build -f tests/emits/server/Dockerfile .`
  834. The emitted server also includes **openapi.json** for API docs, codegen, and gateways.
  835. ### Production: logging, rate limit, K8s
  836. The emitted server includes **structured logging** (request_id, method, path, status, duration_ms) and optional **rate limiting** via env `RATE_LIMIT` (requests per minute per client; 0 = off). **Kubernetes**: emitted `k8s.yaml` (Deployment + Service, health/ready probes); use `compiler.emit_k8s(ir, with_ingress=True)` for Ingress.
  837. ### Requirements
  838. See [docs/INSTALL.md](docs/INSTALL.md) for full setup details. At a minimum: Python 3.10+, pip and virtual environment support, Docker for container-based deployment flows. **Match CI:** use a 3.10 venv at `.venv-py310` (`PYTHON_BIN=python3.10 VENV_DIR=.venv-py310 bash scripts/bootstrap.sh`) and run tools as `./.venv-py310/bin/python`.
  839. ---
  840. ## Hybrid Deployments
  841. > **Validator:** `scripts/validate_ainl.py` supports **`--emit langgraph`** (single `StateGraph` wrapper module) and **`--emit temporal`** (paired `*_activities.py` + `*_workflow.py`). These are additive CLI options; default `IR` / server / hyperspace behavior is unchanged. See **[`docs/HYBRID_GUIDE.md`](docs/HYBRID_GUIDE.md)** and **[`examples/hybrid/README.md`](examples/hybrid/README.md)**. To include hybrid wrappers in benchmark **`minimal_emit`** / planner slices, declare **`S hybrid langgraph`**, **`S hybrid temporal`**, or both (see the guide). Ops checklist: **[`docs/hybrid/OPERATOR_RUNBOOK.md`](docs/hybrid/OPERATOR_RUNBOOK.md)**.
  842. | Mode | When to use | AINL role | Host / extras |
  843. |------|-------------|-----------|----------------|
  844. | **Pure AINL** | You want CLI, MCP, or emitted HTTP worker only | Full program | None required |
  845. | **LangGraph hybrid** | Cyclic LLM/tool graphs, LangGraph checkpoints, ecosystem interop | Deterministic core inside one (or more) nodes | `pip install langgraph` for generated runner |
  846. | **Temporal hybrid** | Durable long-running workflows, retries, Temporal visibility | Same, inside an activity | `pip install temporalio` on worker / workflow import |
  847. **LangGraph:** emit a ready-made `StateGraph` with `python3 scripts/validate_ainl.py your.ainl --emit langgraph -o your_langgraph.py`. The module calls `run_ainl_graph()` from `runtime/wrappers/langgraph_wrapper.py` (`RuntimeEngine`, `{"ok", "result", "error"}`-style payload). Example: [`examples/hybrid/langgraph_outer_ainl_core/`](examples/hybrid/langgraph_outer_ainl_core/) · [`docs/hybrid_langgraph.md`](docs/hybrid_langgraph.md).
  848. **Temporal:** `python3 scripts/validate_ainl.py your.ainl --emit temporal` writes `<stem>_activities.py` and `<stem>_workflow.py` (use `-o` for directory or `.py` prefix; see [`docs/hybrid_temporal.md`](docs/hybrid_temporal.md)). Activities use `execute_ainl_activity()` from `runtime/wrappers/temporal_wrapper.py`. Example: [`examples/hybrid/temporal_durable_ainl/`](examples/hybrid/temporal_durable_ainl/).
  849. **LangChain / CrewAI (tools):** optional **`langchain_tool`** adapter — `python3 -m cli.main run ... --enable-adapter langchain_tool`. Demo: [`examples/hybrid/langchain_tool_demo.ainl`](examples/hybrid/langchain_tool_demo.ainl).
  850. **code_context (optional)** — Tiered, ctxzip-style codebase context for a local tree: index Python and basic JS/TS into JSON (default store: `.ainl_code_context.json`, override with `AINL_CODE_CONTEXT_STORE`). After indexing, `QUERY_CONTEXT` returns Tier 0 (signature list), Tier 1 (TF–IDF–ranked signatures plus doc/summary), or Tier 2 (full source when requested). Also: **`GET_DEPENDENCIES`** / **`GET_IMPACT`** (import graph + transitive importers + PageRank) and **`COMPRESS_CONTEXT`** (TF–IDF order, greedy token-budget packing). Enable with **`--enable-adapter code_context`** on **`ainl run`** (installing MCP alone does not enable optional adapters). Full reference: [`docs/adapters/CODE_CONTEXT.md`](docs/adapters/CODE_CONTEXT.md). Tiered design: [BradyD2003/ctxzip](https://github.com/BradyD2003/ctxzip), **Brady Drexler**. Graph/impact/packing ideas: [chrismicah/forgeindex](https://github.com/chrismicah/forgeindex), **Chris Micah**.
  851. Example usage from an AINL graph (adapter target `code_context`): `INDEX /path/to/repo` builds the store; `QUERY_CONTEXT "user authentication flow" 1` returns Tier 1 (signatures plus summaries for top chunks); `QUERY_CONTEXT "user authentication flow" 2` includes full source for those ranked chunks; `COMPRESS_CONTEXT "…" 8000` packs signatures/summaries under a token budget; `STATS` reports chunk count, indexed root, store path, and last update time.
  852. **Example (requires `--enable-adapter code_context`):** index once, then query in a loop — Tier 1 is usually token-efficient; `STATS` exposes chunk count and store metadata.
  853. ```ainl
  854. S app coding_agent /agent
  855. # Index once (setup step or dedicated entrypoint)
  856. L_index:
  857. R code_context.INDEX "/path/to/your/repo" ->index_result
  858. J index_result
  859. # Main loop: query repeatedly (Tier 1 = signatures + summaries)
  860. L_query:
  861. R code_context.QUERY_CONTEXT developer_query 1 50 ->context
  862. R code_context.COMPRESS_CONTEXT developer_query 8000 ->packed
  863. R code_context.STATS ->stats
  864. # ... feed context into an LLM node or tool ...
  865. J context
  866. ```
  867. Bind `developer_query` from a slot, prior step, or input. The JSON store persists, so `INDEX` is typically run once per workspace.
  868. ---
  869. ## Repo Layout
  870. | Path | Purpose |
  871. |------|--------|
  872. | `docs/AINL_SPEC.md` | AINL 1.0 formal spec: principles, grammar, execution, targets |
  873. | `docs/CONFORMANCE.md` | Implementation conformance vs spec (IR shape, graph emission, P, meta) |
  874. | `docs/runtime/TARGETS_ROADMAP.md` | Expanded targets for production and adoption |
  875. | `docs/language/grammar.md` | Ops/slots reference (v1.0) |
  876. | `compiler_v2.py` | Parser + IR + all emitters (OpenAPI, Docker, K8s, Next/Vue/Svelte, SQL, env) |
  877. | `runtime/engine.py` | `RuntimeEngine` (graph-first execution; step fallback) |
  878. | `runtime/compat.py` | `ExecutionEngine` compatibility shim over canonical runtime |
  879. | `runtime.py` | compatibility re-export for historical imports |
  880. | `adapters/` | Pluggable DB/API/Pay/Scrape (mock + base) |
  881. | `compiler_grammar.py` | Compiler-owned formal prefix grammar/state machine (lexical + structural admissibility) |
  882. | `grammar_priors.py` | Non-authoritative token sampling priors (state/class-driven; no formal rule ownership) |
  883. | `grammar_constraint.py` | Thin compatibility layer that composes formal grammar + priors + pruning APIs |
  884. | `docs/RUNTIME_COMPILER_CONTRACT.md` | Runtime/compiler/decoder ownership + conformance contract |
  885. | `scripts/validate_ainl.py` | CLI validator: compile .lang, print IR or emit artifact |
  886. | `scripts/validate_s_cron_schedules.py` | Guardrail: malformed `S <adapter> cron "…"` lines (also **`ainl-validate-s-cron`**); see `docs/CRON_ORCHESTRATION.md` |
  887. | `scripts/visualize_ainl.py` | Graph visualizer: compile to Mermaid (clusters for `include` aliases); see **Visualize your workflow** below |
  888. | `scripts/validator_app.py` | Web validator (FastAPI): POST .lang → validate, GET / for paste UI |
  889. | `scripts/generate_synthetic_dataset.py` | Generate 10k+ valid .lang programs into `data/synthetic/` |
  890. | `tests/test_conformance.py` | Conformance tests (IR shape + emit outputs); run with `pytest tests/test_conformance.py` |
  891. | `tests/test_compact_opcode_ir_parity.py` | Compact vs golden opcode: preprocess contract + semantic IR checksum parity (`graph_semantic_checksum`); opcode **`While`** compile smoke |
  892. | `tests/test_memory_search_op.py` | **`MemorySearch`** runtime + **`GraphStore`** (matches, limits, empty envelope, special chars, missing adapter **`AinlRuntimeError`**) |
  893. | `tests/test_core_builtins_v143.py` | v1.4.3 **`core.*`** verbs: comparisons, **`TRIM`**/**`STRIP`**, **`STARTSWITH`**/**`ENDSWITH`**, coercions, **`KEYS`**/**`VALUES`** |
  894. | `tests/test_*.lang` | Example specs |
  895. | `examples/` | Example programs with explicit strict/non-strict classes (see `tooling/artifact_profiles.json`) |
  896. | `intelligence/` | OpenClaw-oriented monitors (digest, memory consolidation, token-aware bootstrap); see `docs/INTELLIGENCE_PROGRAMS.md` |
  897. | `agent_reports/` | Agent field reports from production OpenClaw runs; index in `agent_reports/README.md` |
  898. | `scripts/run_intelligence.py` | Dev runner for selected `intelligence/*.lang` programs |
  899. | `tests/emits/server/` | Emitted server (logging, rate limit, health/ready), static, ir.json, openapi.json, Dockerfile, docker-compose.yml, k8s.yaml |
  900. | `.github/workflows/ci.yml` | CI: pytest conformance, emit pipeline, example validation |
  901. ---
  902. ## Tooling Reference
  903. ### Visualize your workflow
  904. Compile a `.ainl` file to **Mermaid** for GitHub, [mermaid.live](https://mermaid.live), Obsidian, or any Mermaid-capable viewer. **Include aliases** become subgraph clusters automatically; synthetic `Call →` edges show how the main flow enters an included module.
  905. **Your first diagram** (from repo root):
  906. ```bash
  907. python3 -m cli.main visualize examples/hello.ainl --output - > hello.mmd
  908. # After pip install -e .
  909. ainl visualize examples/hello.ainl --output - > hello.mmd
  910. ```
  911. 1. Open [mermaid.live](https://mermaid.live).
  912. 2. Click the left editor pane and paste the **entire** contents of `hello.mmd`.
  913. **What you should see** for `examples/hello.ainl`: a top-down graph (`graph TD` + `direction TB`), one **`main`** cluster (`c_main`), rectangular **R** nodes and circular **J** nodes, and edges between them. **Pink fill** (`classDef labelstyle`) applies to nodes in labels whose id ends with `ENTRY` or `EXIT_*` (this hello program only uses `L1`, so you will not see that styling here—try an `include` module to get `retry/ENTRY`, `retry/EXIT_OK`, etc.).
  914. **Includes** (e.g. a file with `include modules/common/retry.ainl as retry` and a `Call` into `retry/ENTRY`): run `visualize` on that file. You should see a separate **`retry`** cluster, nodes such as `"retry/ENTRY/n1"`, cross-cluster edges **after** the subgraphs, and a `%% Synthetic edges: Call → …` comment before the synthetic `|call|` edge into the included entry.
  915. **Save / share** on mermaid.live: **Export → PNG or SVG**, **Share** (link for X/Reddit), or **Edit → copy** the Mermaid block for README or posts.
  916. ```bash
  917. # Write to a file, or stdout
  918. ainl visualize examples/hello.ainl --output diagram.md
  919. ainl-visualize examples/hello.ainl -o diagram.md
  920. ```
  921. #### Export as image (PNG/SVG)
  922. ```bash
  923. # PNG export
  924. ainl visualize examples/hello.ainl --png diagram.png
  925. # SVG export
  926. ainl visualize examples/hello.ainl --svg diagram.svg
  927. # Optional render size
  928. ainl visualize examples/hello.ainl --png diagram.png --width 1600 --height 1000
  929. # Denser graph: timeout module + workflow memory put/list/prune (strict-safe example)
  930. ainl visualize examples/timeout_memory_prune_demo.ainl --png docs/assets/timeout_memory_prune_flow.png
  931. ```
  932. Image export uses Playwright. Install dev deps and Chromium once:
  933. ```bash
  934. pip install -e ".[dev]"
  935. playwright install chromium
  936. ```
  937. | Flag | Purpose |
  938. |------|---------|
  939. | `--output` / `-o` | Write Mermaid to a file, or `-` for stdout (default). |
  940. | `--no-clusters` | Single flat graph (fully qualified node ids, no subgraphs). |
  941. | `--labels-only` | Minimal node text (mostly `op` names) for dense programs. |
  942. | `--format mermaid` | Default; `dot` reserved (use `scripts/render_graph.py` for Graphviz DOT today). |
  943. | `--diagnostics-format` | On compile failure: `auto`, `plain`, `rich`, or `json` (same family as `ainl-validate`). |
  944. | `--no-color` | Plain diagnostics on stderr. |
  945. Use `--no-clusters` for a flat graph, `--labels-only` for dense programs, and `-o -` for stdout.
  946. #### Example output (paste into https://mermaid.live)
  947. Illustrative **include** layout (ids with `/` are **quoted** so Mermaid parses them). The tool emits the same structure with fully qualified node ids such as `"retry/ENTRY/n1"` instead of shorthand labels:
  948. ```mermaid
  949. graph TD
  950. direction TB
  951. subgraph c_retry ["retry"]
  952. "retry/ENTRY"[ENTRY] --> "retry/n1"[EXPONENTIAL 5 200]
  953. "retry/n1" --> "retry/EXIT_OK"[EXIT_OK]
  954. "retry/n1" --> "retry/EXIT_FAIL"[EXIT_FAIL]
  955. end
  956. %% Synthetic edges: Call → included label entry (not explicit in IR)
  957. L1[Your Main Logic] -->|"call"| "retry/ENTRY"
  958. ```
  959. Real output uses fully qualified IDs like `"retry/ENTRY/n1"` and clusters automatically by include **alias** prefix (`retry/…` → subgraph `retry`).
  960. - **Validator CLI**: `python3 scripts/validate_ainl.py [file.lang] [--emit server|react|openapi|prisma|sql|hyperspace] [-o path]`; stdin supported.
  961. - **Strict diagnostics**: `--strict` uses structured compiler diagnostics; stderr shows a numbered report (3-line source context, carets when spans exist, suggestions). **`--diagnostics-format=auto|plain|json|rich`** controls output (`auto` uses rich when the package is installed, stderr is a TTY, and `--no-color` is off). **`--json-diagnostics`** is a legacy alias for `json`. Install optional `pip install -e ".[dev]"` for **rich**. **`--no-color`** forces plain text instead of rich styling.
  962. - **Validator web**: `uvicorn scripts.validator_app:app --port 8766` then open http://127.0.0.1:8766/ to paste and validate.
  963. - **Installed CLIs**: `ainl-validate`, `ainl-validator-web`, `ainl-generate-dataset`, `ainl-compat-report`, `ainl-tool-api`, `ainl-ollama-eval`, `ainl-ollama-benchmark`, `ainl-validate-examples`, `ainl-check-viability`, `ainl-playbook-retrieve`, `ainl-test-runtime`, `ainl-visualize`, `ainl`.
  964. - **Runtime modes**: `ainl run ... --execution-mode graph-preferred|steps-only|graph-only --unknown-op-policy skip|error`.
  965. - **Strict literal policy**: in strict mode, bare identifier-like tokens in read positions are treated as variable refs; quote string literals explicitly (see `docs/RUNTIME_COMPILER_CONTRACT.md` and `docs/language/grammar.md`).
  966. - **Golden fixtures**: `ainl golden` validates `examples/*.ainl` against `*.expected.json`.
  967. - **Replay tooling**: `ainl run ... --record-adapters calls.json` and `ainl run ... --replay-adapters calls.json` for deterministic adapter replay.
  968. - **Reference adapters**: `http`, `sqlite`, `postgres`, `mysql`, `redis`, `dynamodb`, `airtable`, `supabase`, `fs` (sandboxed), and `tools` bridge with contract tests. Optional network adapters include `ptc_runner` and `llm_query` (explicit enablement required).
  969. - **Runner service**: `ainl-runner-service` (FastAPI) with `/run`, `/enqueue`, `/result/{id}`, `/capabilities`, `/health`, `/ready`, and `/metrics`.
  970. - **MCP server**: `ainl-mcp` (stdio-only) exposes `ainl_validate`, `ainl_compile`, `ainl_run`, `ainl_capabilities`, `ainl_security_report`, `ainl_fitness_report`, and `ainl_ir_diff` as MCP tools for Gemini CLI, Claude Code, Codex, and other MCP-compatible agents. PTC-related tools (`ainl_ptc_signature_check`, `ainl_trace_export`, `ainl_ptc_run`, `ainl_ptc_health_check`, `ainl_ptc_audit`) are also available when your MCP exposure profile includes them. It is a thin workflow-level surface over the existing compiler/runtime, not a replacement for the runner service, and currently runs with safe-default restrictions (core-only adapters, hardcoded conservative limits). Requires `pip install -e ".[mcp]"`.
  971. - **Tool API schema**: `tooling/ainl_tool_api.schema.json` (structured compile/validate/emit loop contract).
  972. - **Synthetic dataset**: `python3 scripts/generate_synthetic_dataset.py --count 10000 --out data/synthetic` — writes only programs that compile.
  973. - **Formal prefix grammar (compiler-owned)**: `compiler_grammar.py` is the source of truth for prefix lexical/syntactic/scope admissibility.
  974. - **Grammar ownership contract**: Grammar law lives in `compiler_v2.py`. Formal orchestration lives in `compiler_grammar.py`. Non-authoritative sampling priors live in `grammar_priors.py`. Compatibility composition APIs live in `grammar_constraint.py`.
  975. - **Decoder helpers**: `next_token_priors(prefix)`, `next_token_mask(prefix, raw_candidates)`, `next_valid_tokens(prefix)`.
  976. - **Compile-once / run-many proof pack**: see `docs/architecture/COMPILE_ONCE_RUN_MANY.md`.
  977. - **Program summary**: `python scripts/inspect_ainl.py examples/hello.ainl`
  978. - **Full canonical IR dump**: `ainl inspect examples/hello.ainl --strict`
  979. - **Run summary**: `python scripts/summarize_runs.py run1.json run2.json`
  980. - **Benchmarks (size + runtime + CI gate):** `make benchmark` (full, updates [`BENCHMARK.md`](BENCHMARK.md)); `make benchmark-ci` (JSON-only CI-style). Narrative + metrics glossary: [`docs/benchmarks.md`](docs/benchmarks.md). Optional: `pip install -e ".[benchmark]"` for `tiktoken`/`psutil`; `pip install -e ".[anthropic]"` for `ainl-ollama-benchmark --cloud-model claude-3-5-sonnet`.
  981. - **Corpus tools**: `python scripts/evaluate_corpus.py --mode dual`, `python scripts/validate_corpus.py --include-negatives`, `pytest tests/test_corpus_layout.py -v`
  982. - **Fine-tune**: `bash scripts/setup_finetune_env.sh`, `.venv-ci-smoke/bin/python scripts/finetune_ainl.py --profile fast --epochs 1 --seed 42`
  983. - **Post-train inference**: `.venv-py310/bin/python scripts/infer_ainl_lora.py --adapter-path models/ainl-phi3-lora --max-new-tokens 120 --device cpu`
  984. - **Docs contract guard**: `ainl-check-docs` for cross-link/staleness/coupling checks.
  985. - **Pre-commit**: `pre-commit install` to run docs/quality hooks locally.
  986. - **Test profiles**: `.venv-py310/bin/python scripts/run_test_profiles.py --profile <name>` — `core` (default), `emits`, `lsp`, `integration`, `full`.
  987. ### Async runtime (optional)
  988. AINL keeps sync runtime behavior by default. To run with the native async engine path:
  989. ```bash
  990. AINL_RUNTIME_ASYNC=1 ainl run examples/hello.ainl --enable-adapter postgres
  991. # or
  992. ainl run examples/hello.ainl --enable-adapter postgres --runtime-async
  993. ```
  994. See `docs/runtime/ASYNC_RUNTIME.md` for adapter coverage and fallback behavior.
  995. Current async-capable adapters include postgres/mysql/supabase, redis (full async verb parity with bounded pub/sub listening), dynamodb streams (bounded async subscribe/unsubscribe batching), and airtable attachment/webhook extension verbs.
  996. ### Reactive observability (optional)
  997. AINL can emit lightweight adapter timing + reactive batch metrics (off by default):
  998. ```bash
  999. AINL_RUNTIME_ASYNC=1 AINL_OBSERVABILITY=1 \
  1000. ainl run examples/reactive/hybrid_stream_broadcast.ainl \
  1001. --runtime-async --observability --enable-adapter dynamodb --enable-adapter supabase --enable-adapter redis --enable-adapter memory
  1002. ```
  1003. When enabled, runtime writes structured JSON metric lines to stderr (for example `adapter.call.duration_ms`, `reactive.events_per_batch`, `reactive.sequence_gap`, `reactive.ack.success_rate`).
  1004. You can also persist metrics to a JSONL sink file:
  1005. ```bash
  1006. AINL_RUNTIME_ASYNC=1 AINL_OBSERVABILITY=1 AINL_OBSERVABILITY_JSONL=/tmp/ainl-reactive-metrics.jsonl \
  1007. ainl run examples/reactive/hybrid_stream_broadcast.ainl \
  1008. --runtime-async --observability --observability-jsonl /tmp/ainl-reactive-metrics.jsonl \
  1009. --enable-adapter dynamodb --enable-adapter supabase --enable-adapter redis --enable-adapter memory
  1010. ```
  1011. This makes it easy to consume metrics with `jq`, `vector`, `promtail`, or simple log tail/aggregation tools. Stderr and JSONL file sink can be used together.
  1012. For production multi-node durability (shared checkpoints/cursors), see `docs/reactive/ADVANCED_DURABILITY.md` for Redis-backed, Postgres-backed, and hybrid patterns that require no new adapter code.
  1013. ## Status: Production Ready for Reactive Workflows
  1014. AINL is now production-ready for reactive/event-driven graph workflows with a complete end-to-end stack:
  1015. - **Full native async runtime** (`--runtime-async`) with async-capable adapter execution.
  1016. - **Comprehensive database adapters** across `sqlite`, `postgres`, `mysql`, `redis`, `dynamodb`, `airtable`, and `supabase`.
  1017. - **Reactive primitives** with bounded, practical semantics:
  1018. - DynamoDB Streams with checkpointing and ack flows
  1019. - Supabase Realtime with fan-out, replay, cursor, and ack helpers
  1020. - Redis pub/sub for low-latency internal fan-out
  1021. - **Observability support** for reactive workloads, including structured metrics and JSONL sink output (`--observability-jsonl` / `AINL_OBSERVABILITY_JSONL`).
  1022. - **Production starter templates** in `templates/production/` for immediate rollout patterns.
  1023. - **Durability guidance** in `docs/reactive/ADVANCED_DURABILITY.md` for multi-process and multi-node checkpoint/cursor persistence using existing adapters.
  1024. What's next: shared multi-node durability coordination beyond process-local helpers, runtime scheduling optimizations for very high-throughput pipelines, and optional advanced adapter features for specialized deployments.
  1025. ### PostgreSQL adapter (runtime-native)
  1026. Enable `postgres` explicitly and configure credentials via environment variables (preferred) or CLI flags:
  1027. ```bash
  1028. export AINL_POSTGRES_URL='postgresql://user:pass@localhost:5432/appdb'
  1029. ainl run examples/hello.ainl --enable-adapter postgres --postgres-allow-table users --postgres-allow-write
  1030. ```
  1031. AINL graph syntax:
  1032. ```ainl
  1033. S app core noop
  1034. L1:
  1035. R postgres.query "SELECT id, email FROM users WHERE id = %s" [42] ->rows
  1036. J rows
  1037. ```
  1038. Supported verbs: `query`, `execute`, and `transaction` (`R postgres.transaction [{verb, sql, params}] ->out`). For production, keep `allow_write` off unless needed, use parameterized SQL, and scope table access with `--postgres-allow-table`.
  1039. Full contract and security guidance: `docs/adapters/POSTGRES.md`.
  1040. ### MySQL adapter (runtime-native)
  1041. Enable `mysql` explicitly and configure credentials via environment variables (preferred) or CLI flags:
  1042. ```bash
  1043. export AINL_MYSQL_URL='mysql://user:pass@localhost:3306/appdb'
  1044. ainl run examples/hello.ainl --enable-adapter mysql --mysql-allow-table users --mysql-allow-write
  1045. ```
  1046. AINL graph syntax:
  1047. ```ainl
  1048. S app core noop
  1049. L1:
  1050. R mysql.query "SELECT id, email FROM users WHERE id = %s" [42] ->rows
  1051. J rows
  1052. ```
  1053. Supported verbs: `query`, `execute`, and `transaction` (`R mysql.transaction [{verb, sql, params}] ->out`). For production, keep `allow_write` off unless needed, use parameterized SQL, and scope table access with `--mysql-allow-table`.
  1054. Full contract and security guidance: `docs/adapters/MYSQL.md`.
  1055. ### Redis adapter (runtime-native)
  1056. Enable `redis` explicitly and configure via environment variables (preferred) or CLI flags:
  1057. ```bash
  1058. export AINL_REDIS_URL='redis://localhost:6379/0'
  1059. ainl run examples/hello.ainl --enable-adapter redis --redis-allow-write --redis-allow-prefix session:
  1060. ```
  1061. AINL graph syntax:
  1062. ```ainl
  1063. S app core noop
  1064. L1:
  1065. R redis.set "session:42" "{\"state\":\"active\"}" 300 ->ok
  1066. R redis.get "session:42" ->value
  1067. J value
  1068. ```
  1069. Supported verbs include key/value (`get/set/delete/incr/decr`), hashes (`hget/hset/hdel/hmget`), lists (`lpush/rpush/lpop/rpop/llen`), pub/sub (`publish/subscribe`), health (`ping/info`), and `transaction`.
  1070. Full contract and security guidance: `docs/adapters/REDIS.md`.
  1071. ### DynamoDB adapter (runtime-native)
  1072. Enable `dynamodb` explicitly and configure endpoint/region via environment variables (preferred) or CLI flags:
  1073. ```bash
  1074. export AINL_DYNAMODB_URL='http://127.0.0.1:8000'
  1075. export AWS_ACCESS_KEY_ID='dummy'
  1076. export AWS_SECRET_ACCESS_KEY='dummy'
  1077. export AWS_DEFAULT_REGION='us-east-1'
  1078. ainl run examples/hello.ainl --enable-adapter dynamodb --dynamodb-allow-table users --dynamodb-allow-write
  1079. ```
  1080. AINL graph syntax:
  1081. ```ainl
  1082. S app core noop
  1083. L1:
  1084. R dynamodb.get "users" {"pk":"u#42","sk":"profile"} ->out
  1085. J out
  1086. ```
  1087. Supported verbs include single-item (`get/put/update/delete`), collection (`query/scan`), batch/transaction (`batch_get/batch_write/transact_get/transact_write`), health (`describe_table/list_tables`), and bounded streams (`streams.subscribe/streams.unsubscribe`).
  1088. Full contract and security guidance: `docs/adapters/DYNAMODB.md`.
  1089. ### Airtable adapter (runtime-native)
  1090. Enable `airtable` explicitly with scoped API key + base id:
  1091. ```bash
  1092. export AINL_AIRTABLE_API_KEY='pat_xxx'
  1093. export AINL_AIRTABLE_BASE_ID='app_xxx'
  1094. ainl run examples/hello.ainl --enable-adapter airtable --airtable-allow-table users --airtable-allow-write
  1095. ```
  1096. AINL graph syntax:
  1097. ```ainl
  1098. S app core noop
  1099. L1:
  1100. R airtable.list "users" {"maxRecords": 20, "pageSize": 20} ->rows
  1101. J rows
  1102. ```
  1103. Supported verbs include `list/find/create/update/delete`, discovery (`get_table/list_tables/list_bases`), `upsert`, plus scoped attachment and webhook helpers (`attachment.upload/attachment.download`, `webhook.create/webhook.list/webhook.delete`).
  1104. Full contract and security guidance: `docs/adapters/AIRTABLE.md`.
  1105. ### Supabase adapter (runtime-native wrapper)
  1106. Enable `supabase` explicitly with Supabase DB + project credentials:
  1107. ```bash
  1108. export AINL_SUPABASE_DB_URL='postgresql://user:pass@localhost:5432/appdb'
  1109. export AINL_SUPABASE_URL='https://your-project.supabase.co'
  1110. export AINL_SUPABASE_SERVICE_ROLE_KEY='ey...'
  1111. ainl run examples/hello.ainl --enable-adapter supabase --supabase-allow-table users --supabase-allow-write
  1112. ```
  1113. AINL graph syntax:
  1114. ```ainl
  1115. S app core noop
  1116. L1:
  1117. R supabase.select "users" {"id": 42} ["id","email"] ->out
  1118. J out
  1119. ```
  1120. Supported verbs include DB wrapper operations (`from/select/query/insert/update/upsert/delete/rpc`) plus auth (`auth.*`), storage (`storage.*`), and advanced realtime helpers (`realtime.subscribe/unsubscribe/broadcast/replay/get_cursor/ack`) for lightweight fan-out/replay/checkpoint flows.
  1121. Full contract and security guidance: `docs/adapters/SUPABASE.md`.
  1122. ---
  1123. ## Project Origin
  1124. AI Native Lang began from a human-initiated idea and has been developed in explicit human+AI co-development from the start. AI systems have been active contributors in naming, architecture, and implementation iteration; notably, the name **"AI Native Lang"** was proposed by an AI model and adopted by the project.
  1125. The human initiator of AINL is **Steven Hooley**.
  1126. - X: <https://x.com/sbhooley>
  1127. - Website: <https://stevenhooley.com>
  1128. - LinkedIn: <https://linkedin.com/in/sbhooley>
  1129. Timeline anchor: Foundational AI research and cross-platform experimentation by the human founder began in **2024**. After partial loss of early artifacts, AINL workstreams were rebuilt, retested, and formalized in overlapping phases through **2025-2026**.
  1130. For full attribution context, see [docs/PROJECT_ORIGIN_AND_ATTRIBUTION.md](docs/PROJECT_ORIGIN_AND_ATTRIBUTION.md), [tooling/project_provenance.json](tooling/project_provenance.json), and [docs/CHANGELOG.md](docs/CHANGELOG.md).
  1131. ---
  1132. ## Community and Support
  1133. - Contribution workflow: `CONTRIBUTING.md`
  1134. - Contributor behavior policy: `CODE_OF_CONDUCT.md`
  1135. - Security reporting: `SECURITY.md`
  1136. - Support expectations and channels: `SUPPORT.md`
  1137. - Commercial/licensing inquiries: `COMMERCIAL.md`
  1138. ---
  1139. ## Community & Growth
  1140. Join the conversation:
  1141. - [GitHub Discussions](https://github.com/sbhooley/ainativelang/discussions) (enable if not already)
  1142. - [Telegram](https://t.me/AINL_Portal)
  1143. - [X / Twitter](https://x.com/ainativelang)
  1144. See [GROWTH-PLAN.md](GROWTH-PLAN.md) for how we're scaling sustainably.
  1145. ---
  1146. ## Licensing
  1147. AI Native Lang uses an open-core licensing model.
  1148. - **Open Core:** Designated core code is licensed under the Apache License 2.0. See `LICENSE`.
  1149. - **Documentation and Content:** Non-code docs/content are licensed under `LICENSE.docs`, unless noted otherwise.
  1150. - **Models, Weights, and Data Assets:** Model/checkpoint/data-style artifacts may be governed by separate terms. See `MODEL_LICENSE.md`.
  1151. - **Commercial Offerings:** Some hosted/enterprise/premium capabilities are available under separate commercial terms. See `COMMERCIAL.md`.
  1152. - **Trademarks:** `AINL` and `AI Native Lang` branding rights are governed separately from code licenses. See `TRADEMARKS.md`.
  1153. ---
  1154. ## OpenClaw integration
  1155. All agent orchestration, cron unification, memory bridging, and OpenClaw-specific supervision glue lives in **`openclaw/bridge/`** (with backward-compatible **`scripts/`** shims). See **[`openclaw/bridge/README.md`](openclaw/bridge/README.md)** for runners, drift checks, `AINL_WORKSPACE` cron patterns, and the `ainl_bridge_main.py` entrypoint.
  1156. ---
  1157. ## ArmaraOS Integration
  1158. AINL integrates seamlessly with [OpenFang](https://github.com/RightNow-AI/openfang), the open-source Agent Operating System.
  1159. ### Quick Start
  1160. ```bash
  1161. # Install AINL for OpenFang
  1162. ainl install armaraos
  1163. # Emit a hand package
  1164. ainl emit --target armaraos -o my_hand/ workflow.ainl
  1165. # Run with OpenFang
  1166. armaraos hand run my_hand --input '{}'
  1167. # Check status
  1168. ainl status --host armaraos
  1169. ```
  1170. ### Features
  1171. - **WASM Sandbox**: All hands run in a secure WASM sandbox with configurable memory/instruction limits
  1172. - **Merkle Audit Trail**: Token usage is recorded with cryptographic proofs for accountability
  1173. - **Taint Tracking**: Data lineage tracking for sensitive information
  1174. - **MCP Native**: OpenFang uses AINL as a first-class MCP server
  1175. - **Tauri Sidecar**: Desktop apps can embed AINL via OpenFang sidecar
  1176. ### Configuration
  1177. After `ainl install armaraos`, your `~/.armaraos/config.toml` will contain:
  1178. ```toml
  1179. [[mcp_servers]]
  1180. name = "ainl"
  1181. command = "ainl-mcp"
  1182. args = []
  1183. ```
  1184. Refer to [armaraos/docs/](armaraos/docs/) for detailed documentation.
  1185. ---
  1186. ## Production monitoring
  1187. OpenClaw-scheduled **bridge wrappers** report token usage, enforce budget awareness, and write operator-facing markdown under **`~/.openclaw/workspace/memory/YYYY-MM-DD.md`** (override with `OPENCLAW_MEMORY_DIR` / `OPENCLAW_DAILY_MEMORY_DIR`).
  1188. | Piece | What it does |
  1189. |-------|----------------|
  1190. | **`token-budget-alert`** | Daily (`0 23 * * *` UTC): `## Token Usage Report` append, monitor-cache **stat** / optional **prune** when cache is large, **one consolidated** notify (`Daily AINL Status - … UTC`) when lines are queued (Telegram/OpenClaw queue). |
  1191. | **Sentinel duplicate guard** | Live runs use `token_report_today_sent` / `token_report_today_touch` (default file `/tmp/token_report_today_sent`; override **`AINL_TOKEN_REPORT_SENTINEL`**) so the **main** report is not appended twice the same UTC day. **`--dry-run`** skips sentinel and main append. |
  1192. | **`weekly-token-trends`** | Weekly Sunday 09:00 UTC (`0 9 * * 0`): scans recent daily `*.md` files, parses `## Token Usage Report`, appends **`## Weekly Token Trends`**. |
  1193. | **Docs & ops** | Operator hub: **[`docs/operations/UNIFIED_MONITORING_GUIDE.md`](docs/operations/UNIFIED_MONITORING_GUIDE.md)** · Wrapper detail: **[`docs/openclaw/BRIDGE_TOKEN_BUDGET_ALERT.md`](docs/openclaw/BRIDGE_TOKEN_BUDGET_ALERT.md)** · Cron drift & registry: **[`docs/CRON_ORCHESTRATION.md`](docs/CRON_ORCHESTRATION.md)** |
  1194. **Quick validate (no writes):**
  1195. ```bash
  1196. python3 openclaw/bridge/run_wrapper_ainl.py token-budget-alert --dry-run
  1197. python3 openclaw/bridge/run_wrapper_ainl.py weekly-token-trends --dry-run
  1198. ```
  1199. Wrappers live under **`openclaw/bridge/wrappers/`** (`token_budget_alert.ainl`, `weekly_token_trends.ainl`); adapter logic in **`openclaw/bridge/bridge_token_budget_adapter.py`**.
  1200. ---
  1201. ## KEYWORDS
  1202. - AI-native programming language
  1203. - agent workflow language
  1204. - deterministic agent workflows
  1205. - graph-based agent orchestration
  1206. - LLM orchestration
  1207. - AI agent workflow engine
  1208. - workflow language for AI agents
  1209. - deterministic AI workflows
  1210. - production AI agents
  1211. - reliable AI agent workflows
  1212. - auditable AI workflows
  1213. - deterministic workflow engine for AI
  1214. - compile-once run-many AI workflows
  1215. - long-running AI agents
  1216. - stateful AI agents
  1217. - autonomous ops workflows
  1218. - LangChain alternative
  1219. - LangGraph alternative
  1220. - CrewAI alternative
  1221. - Temporal for AI agents
  1222. - sandboxed agent deployment
  1223. ---
  1224. ---
  1225. ## ArmaraOS
  1226. > ArmaraOS is an independent open-source project and is not affiliated with any entities using similar names (e.g., Amaros AI or other).
  1227. > It is a customized fork and extension of OpenFang by RightNow-AI (https://github.com/RightNow-AI/openfang), licensed under Apache-2.0 OR MIT.
  1228. > It includes and integrates AINativeLang (https://github.com/sbhooley/ainativelang) for deterministic AI workflows.
  1229. > Modifications Copyright (c) 2026 sbhooley. Original OpenFang and AINativeLang works retain their respective licenses.
  1230. **ArmaraOS — The regenerative Agent OS.**
  1231. Powered by AINativeLang’s deterministic workflows.
  1232. Like a starfish, it adapts, regrows reliable processes, and thrives with multiple arms (tools, channels, memory, and autonomous Hands) — never breaking, always regenerating.
  1233. **Quickstart**
  1234. ```bash
  1235. ainl init my-worker --target armaraos && ainl install armaraos
  1236. ```
  1237. Downloads & full docs: https://ainativelang.com/

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.