AI Native Lang (AINL)

Find Us on X: @ainativelang

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 :)

For agents — install AINL (one step)

If you are an AI coding agent (Claude Code, Cursor, Cline, Codex, Aider, …) or any MCP-capable runtime and the user wants AINL added to their stack, run one command:

pipx install 'ainativelang[mcp]' && ainl setup --auto

Fallback if pipx is unavailable:

python3 -m pip install --user 'ainativelang[mcp]' && ainl setup --auto

That is the entire install. The setup command auto-detects every host present (Claude Code project + user, Cursor, Cline, Codex CLI/Desktop, Claude Desktop, OpenClaw, Hermes, ArmaraOS, or any generic MCP host), merges the right MCP server entry into each config file (atomic write, timestamped backup), and verifies with ainl doctor. Idempotent — safe to re-run.

If a host is not auto-detected, run ainl setup --print-config for a paste-ready stdio MCP server block.

Machine-readable spec: .agent-install.json · Design: docs/architecture/2026-05-05-agent-install-simplification.md.

Is AINL for you? (60-second filter)

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.

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 (canonical). If you tick zero, that page explains why and saves you the install. We mean it.

Per-host details (advanced)

Just want something working on your desktop in under 3 minutes?

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.

Download ArmaraOS — ainativelang.com macOS · Windows · Linux — free to start

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.

Already have an AI agent? Add AINL in one command.

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

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.

Primary product path: ArmaraOS — desktop agent OS with dashboard, Hands, scheduled ainl run, and MCP authoring. See docs/competitive/ARMARAOS_GTM.md.

Token savings — pick your baseline:

Full honest filter: docs/competitive/WHEN_AINL_DOES_NOT_HELP.md · docs/competitive/VS_HAND_WRITTEN_RUNNER.md (five-axis comparison vs a hand-written Python runner — concedes the token point on baseline B).

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. Against baseline C (pure deterministic, no LLM in loop), it is ~0%.

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.

Token savings breakdown and benchmarks → · BENCHMARK.md (source tables + methodology) · docs/CLAIMS_AND_EVIDENCE.md (claim crosswalk) · When AINL does not help →

Current evidence (honest scope)

We classify every public evidence row by source so reviewers can tell field reports from modeled scenarios:

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.

Here for the programming language itself?

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.

Jump to Get Started (3 minutes) ↓ · Docs → · Quick start → · What is AINL? →

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.

Open-core boundary

Full boundary details: docs/OPEN_CORE_DECISION_SHEET.md

Security

Vulnerability reporting and sensitive areas (outbound HTTP, the a2a adapter, secrets): see SECURITY.md. A2A-specific policy and wire contract: docs/integrations/A2A_ADAPTER.md.

Agentic HTTP payments & commerce (x402, MPP, AP2, ACP, AGTP): integration hub docs/integrations/README.md — HTTP-402 rails on the http adapter (HTTP_MACHINE_PAYMENTS.md), practitioner readiness (AGENTIC_PROTOCOLS_PRACTITIONER_READINESS.md), and AGTP options (AGTP.md).

New in v1.8.0

• 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).
• 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.

New in v1.7.1

• 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.
• 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).

New in v1.7.0

• 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).
• 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.
• 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.
• 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.
• 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.
• Monitor registry bootstrap: build_armaraos_monitor_registry, boot_armaraos_graph_memory, CronDriftCheckAdapter, tests/test_armaraos_monitor_registry.py.
• Runtime: public AdapterRegistry.get; graph-patch uses adapters.get("ainl_graph_memory").
• 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).

New in v1.6.0

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

Unified graph execution engine vision (1.6.0 → 1.8.0)

• 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.
• Memory as compiled knowledge: GraphPatch (memory.patch) promotes proven behavior into reusable procedural graph structure under strict dataflow and overwrite guards.
• 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.
• 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.
• Primary references: LATE_NIGHT_CONVO_WITH_AI.md, WHITEPAPERDRAFT.md, and ArmaraOS prior-art lineage in sbhooley/armaraos/PRIOR_ART.md.

New in v1.5.2

• 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.
• 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.
• 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.
• 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.
• ArmaraOS emit metadata: security.json capability_declarations.adapters; HAND.toml ainl_ir_version.
• Release hygiene: pyproject.toml, RUNTIME_VERSION, CITATION.cff, tooling/bot_bootstrap.json, and mirrored emit server engine aligned to 1.5.2.
• Whitepaper: WHITEPAPERDRAFT.md v1.5.2 + §6.8 (graph-memory gap audit narrative).

New in v1.5.1

• 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).
• 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).
• Release hygiene: pyproject.toml, RUNTIME_VERSION, CITATION.cff, tooling/bot_bootstrap.json, and mirrored emit server engine aligned to 1.5.1.
• 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.

New in v1.5.0

• 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).
• Docs: hub pages, OpenClaw integration pointers, contributor guides, and whitepaper draft refreshed so “current release” references match v1.5.0.

New in v1.4.6

• 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).

New in v1.4.5

• 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.
• MCP server (ainl-mcp): ainl://authoring-cheatsheet resource, process-local validate telemetry, and tighter validate/compile integration for agent-facing diagnostics.
• 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).

New in v1.4.4

• PyPI ainativelang 1.4.4: version surfaces aligned (pyproject.toml, RUNTIME_VERSION, CITATION.cff, tooling/bot_bootstrap.json).
• Solana client emit: emit_solana_client header now uses live RUNTIME_VERSION so generated clients never drift from the installed runtime.

New in v1.4.3

• 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.
• 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").
• 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).
• 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.
• MCP per-run adapters (from earlier in v1.4.3): ainl_run adapters parameter for scoped http, fs, cache, sqlite per call.
• 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).

New in v1.4.2

• 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.
• 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).
• 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.

New in v1.4.1

• 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).
• 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.
• core.GET: real R target on CoreBuiltinAdapter (deep key/index reads via deep_get); strict entries in tooling/effect_analysis.py alongside llm.COMPLETION.
• LLM runtime: LLMRuntimeAdapter normalizes verb casing so R llm.COMPLETION matches registry verbs (e.g. completion).

New in v1.4.0

• 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).
• Release / surfaces: version alignment across pyproject.toml, RUNTIME_VERSION, CITATION.cff, tooling/bot_bootstrap.json; ainl serve GET /health reports version from RUNTIME_VERSION.
• Docs: docs/ARMARAOS_INTEGRATION.md, host hub docs/getting_started/HOST_MCP_INTEGRATIONS.md; integration tests and emitter import path fixes.

New in v1.3.4

• Enhanced diagnostics (--enhanced-diagnostics): graph context + Mermaid snippets on compile errors.
• Error highlighting (ainl visualize --highlight-errors): error nodes styled in Mermaid output.
• Static cost estimates (--estimate on check, inspect, status): per-node token/USD estimates.
• Audit trail adapter (--enable-adapter audit_trail --audit-sink file:///...): immutable JSONL compliance log (graph must invoke audit_trail.record).
• Compact syntax preprocessor (ainl_preprocess.py): Python-like compact .ainl authoring alongside opcodes — same IR, fewer surface tokens; see examples/compact/ and AGENTS.md.

Tutorials: Debugging with the Visualizer · Production: Estimates & Audit

Full version history: docs/CHANGELOG.md · docs/RELEASE_NOTES.md

AINL helps turn AI from "a smart conversation" into "a structured worker."

v1.3.3 — Native Solana + prediction markets: See 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 for a concrete resolution → conditional payout pattern.

v1.3.3 — Native Solana Support for Prediction Markets

• Deterministic Solana agents: Strict AINL graphs for market creation, Pyth/Hermes resolution monitoring, and on-chain trades/payouts keep behavior explainable and testable.
• 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).
• 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.
• Start here: docs/solana_quickstart.md and examples/prediction_market_demo.ainl.

All Solana additions are additive-only and preserve full Hyperspace compatibility.

Recommended production stack: AINL graphs + AVM or general agent sandboxes

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.

• New metadata: optional execution_requirements in compiled IR (avm_policy_fragment, isolation/resource hints).
• New CLI: ainl generate-sandbox-config <file.ainl> [--target avm|firecracker|gvisor|k8s|general].
• New unified shim: optional runtime/sandbox_shim.py auto-detects AVM/general sandbox endpoints and falls back cleanly.

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.

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, docs/benchmarks.md, and docs/architecture/COMPILE_ONCE_RUN_MANY.md.

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 for tables; narrative hub 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.

CLI polish (OpenClaw, v1.3.3+)

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

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.

Shell shortcut: scripts/setup_ainl_integration.sh delegates to ainl install openclaw (supports --dry-run, --workspace, --verbose).

Get Started (3 minutes)

Requires Python 3.10+. No git clone needed to try it.

# 1. Install the CLI
pip install ainativelang

# 2. Create a new project (generates main.ainl + README)
ainl init my-first-worker
cd my-first-worker

# 3. Check the program compiles cleanly (strict graph semantics)
ainl check main.ainl --strict

# 4. Run it
ainl run main.ainl

# 5. Visualise the control-flow graph
ainl visualize main.ainl --output -    # paste into https://mermaid.live

That's it. Edit main.ainl, add adapter calls (cache, HTTP, LLM, memory), revalidate, run again.

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.

Compact syntax (new in v1.3.3)

AINL now supports a human-friendly compact syntax alongside the original opcodes. Both compile to the same IR. Compact is recommended for new code — 66% fewer tokens.

# examples/compact/hello_compact.ainl
adder:
  result = core.ADD 2 3
  out result

# Branching, inputs, adapter calls, cron — all work
classifier:
  in: level message
  severity = llm.classify level message
  if severity == "CRITICAL":
    http.POST ${SLACK_WEBHOOK} {text: message}
    out "alerted"
  out "logged"

See examples/compact/ for more, and AGENTS.md for the full compact syntax reference.

write → check → visualize → run loop

1. Write — author in compact or opcode syntax, or have an LLM emit a .ainl program.
2. Validate strict graph semantics: ainl validate your.ainl --strict Or the equivalent: ainl check your.ainl --strict Failures include structured diagnostics (line, suggestion, optional llm_repair_hint). Use --json-diagnostics for CI/machine-readable output.
3. Visualize control flow as Mermaid:
   ainl visualize your.ainl --output - > graph.mmd — paste into mermaid.live.
4. Run locally: ainl run your.ainl
5. Emit to other platforms: ainl emit your.ainl --target langgraph -o graph.py
6. Serve as HTTP API: ainl serve --port 8080 (POST /validate, /compile, /run)
7. Inspect canonical IR (for agent/meta-agent loops): ainl inspect your.ainl --strict
8. Emit JSONL execution tape for grading/evolution: ainl run your.ainl --trace-jsonl run.trace.jsonl

# Clone and create an isolated env (match CI: Python 3.10)
git clone https://github.com/sbhooley/ainativelang.git
cd ainativelang

PYTHON_BIN=python3.10 VENV_DIR=.venv-py310 bash scripts/bootstrap.sh
source .venv-py310/bin/activate  # Windows: .venv-py310\Scripts\activate

# Install with dev + web extras
python -m pip install --upgrade pip
python -m pip install -e ".[dev,web]"

# Validate an example
ainl check examples/hello.ainl --strict

# Run the core test suite
python scripts/run_test_profiles.py --profile core

# Environment diagnostics
ainl doctor

# Full conformance matrix
make conformance

# Runner service (for API/orchestrator integration)
python scripts/runtime_runner_service.py
# GET http://localhost:8770/capabilities
# POST http://localhost:8770/run  {"code": "S app api /api\nL1:\nR core.ADD 2 3 ->sum\nJ sum"}

Research-loop quickstart (meta-agent)

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

Community & Growth (start here too)

• Growth strategy and milestones: GROWTH-PLAN.md
• Validation transparency: docs/validation-deep-dive.md
• GitHub Discussions: https://github.com/sbhooley/ainativelang/discussions
• Telegram: https://t.me/AINL_Portal
• X / Twitter: https://x.com/ainativelang

Short primer for stakeholders: docs/WHAT_IS_AINL.md (canonical). WHAT_IS_AINL.md at repo root is a stub that points to the same content.

Getting started with includes

Pull in shared subgraphs from modules/ (paths resolve next to your source file, then CWD, then ./modules/):

include "modules/common/retry.ainl" as retry

L1: Call retry/ENTRY ->out J out

See Includes & modules below for timeout.ainl, strict rules, and the starter table.

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.

Deeper setup: See docs/INSTALL.md for platform-specific install, Docker, and pre-commit setup.

Ecosystem & agent hosts (OpenClaw, ZeroClaw, Hermes)

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.

Host quick links: OpenClaw · ZeroClaw skill (AINL) · Hermes Agent · ArmaraOS — AINL wiring for all four is in docs/getting_started/HOST_MCP_INTEGRATIONS.md (ainl install-mcp --host openclaw|zeroclaw|hermes|armaraos).

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 ) refreshes examples/ecosystem/ from upstream public Markdown; community additions use .github/PULL_REQUEST_TEMPLATE/ (workflow / agent templates).

ainl import markdown https://raw.githubusercontent.com/nikilster/clawflows/main/workflows/available/community/check-calendar/WORKFLOW.md \
  --type workflow -o morning.ainl
ainl compile morning.ainl

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.

Shortcuts (fetch five samples from upstream into examples/ecosystem/ — requires network):

ainl import clawflows
ainl import agency-agents

Install AINL as a ZeroClaw skill

zeroclaw skills install https://github.com/sbhooley/ainativelang/tree/main/skills/ainl

This installs the AINL importer, runtime shim, and MCP tools directly into ZeroClaw.

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.

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 ….)

Details: docs/ZEROCLAW_INTEGRATION.md · skill files: skills/ainl/README.md.

Install AINL as an OpenClaw skill

OpenClaw uses npm + openclaw onboard for the host CLI. AINL is added as a skill folder (not via zeroclaw skills install): copy skills/openclaw/ to ~/.openclaw/skills/ or <workspace>/skills/, or install from ClawHub when the skill is listed there.

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.

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 compile-once/run-many scenarios + scripts/benchmark_compile_once_run_many.py).

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.

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. 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 and 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).

If you need a clean uninstall in managed sandboxes:

pip3 uninstall -y ainl mcp aiohttp langgraph temporalio
rm -rf /tmp/ainl-repo /data/.openclaw/workspace/skills/ainl /data/.local/lib/python3.13/site-packages/*ainl*

Try in chat: “Import the morning briefing using AINL.”

Details: docs/OPENCLAW_INTEGRATION.md · skill files: skills/openclaw/README.md.

Standalone skill repo (optional, later): publish the contents of skills/openclaw/ as the root of 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).

Install AINL for Hermes Agent

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

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

Details: docs/HERMES_INTEGRATION.md · hub one-pager: docs/integrations/hermes-agent.md · skill pack: skills/hermes/README.md.

Curated templates with original.md, converted.ainl, and notes: examples/ecosystem/README.md.

Weekly auto-sync: the repo can refresh those sample trees from upstream on a schedule via GitHub Actions — see .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 — no access to upstream Clawflows/Agency-Agents orgs is required (public raw fetches only).

Contributing workflows & agents

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/).
You can also append ?quick_pull=1&template=workflow-submission.md or template=agent-submission.md to your compare URL (main…your-branch).

Templates: workflow-submission.md · agent-submission.md · default pull_request_template.md.

Ultra Cost-Efficient Mode — modules/efficient_styles.ainl

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.

include "modules/efficient_styles.ainl" as style

my_workflow:
  in: question
  # ... do work ...
  result = core.GET work_result
  if is_user_facing:
    out = style.human_dense_response result
  out = style.terse_structured result

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.

terse_structured — JSON-only output for tool steps and internal state. Never use for end-user responses.

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

Cross-repo reference: docs/operations/EFFICIENT_MODE_ARMARAOS_BRIDGE.md — how CLI env, efficient_styles.ainl, and ArmaraOS docs/prompt-compression-efficient-mode.md relate.

CLI hint for ArmaraOS-hosted graphs (sets AINL_EFFICIENT_MODE env var — Rust compression is on the host):

ainl run my_workflow.ainl --efficient-mode balanced

Note: the --efficient-mode flag only signals the ArmaraOS kernel via environment. No compression runs in Python — implementation is in openfang-runtime (prompt_compressor).

Includes & modules

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

Syntax (paths resolve next to the source file, then the current working directory, then ./modules/):

include "modules/common/retry.ainl" as retry
include modules/common/timeout.ainl as timeout

Quotes around the path are optional when unambiguous; as alias sets the prefix for every label from that file.

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.

include "modules/common/retry.ainl" as retry
include "modules/common/timeout.ainl" as timeout

S app api /api
L1: Call retry/ENTRY ->r J r
L2: Call timeout/ENTRY ->t J t

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.

Shared modules live in a modules/ directory next to your files (with CWD / ./modules/ fallback—see compiler path resolution).

Starter modules in this repo

Starter Modules (in modules/common/)

• retry.ainl — exponential backoff + max retries
• timeout.ainl — timeout wrapper with placeholder delay (swap to real timer later)

include "modules/common/timeout.ainl" as timeout

L1:
  Call timeout/ENTRY ->out
  J out

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.

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.

Reference bots

• 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. Optional Growth Pack (v1.3) (follow/discovery/like/thread/awareness, env-gated) is documented in the same README under Optional Apollo-X Growth Pack.

Choose Your Path

AINL can be used through three integration surfaces. All three run the same compiler and runtime; they differ in how you connect.

External runtime option (opt-in): AINL can call PTC-Lisp through ptc_runner for reliability overlays and trace interoperability; see docs/adapters/PTC_RUNNER.md.

The canonical "hello world" workflow used below:

S app api /api
L1:
R core.ADD 2 3 ->x
J x

Path A — CLI only (fastest start)

# Validate and inspect IR
ainl-validate examples/hello.ainl --strict --emit ir

# Mermaid diagram (paste into mermaid.live)
ainl visualize examples/hello.ainl --output - > hello.mmd

# Run directly
ainl run examples/hello.ainl --json

No server needed. Good for local development, scripting, and CI.

Path B — HTTP runner (orchestrator integration)

# Start the runner service
ainl-runner-service
# default: http://localhost:8770

# Discover capabilities
curl http://localhost:8770/capabilities

# Execute a workflow
curl -X POST http://localhost:8770/run \
  -H "Content-Type: application/json" \
  -d '{"code": "S app api /api\nL1:\nR core.ADD 2 3 ->x\nJ x", "strict": true}'

Best for container deployments, sandbox controllers, and external orchestrators. See docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md.

Path C — MCP host (AI coding agents)

# Install with MCP extra
pip install -e ".[mcp]"

# Start the stdio MCP server
ainl-mcp

Then configure your MCP-compatible host (Gemini CLI, Claude Code, Codex, etc.) to use the ainl-mcp stdio transport. The host can call ainl_validate, ainl_compile, ainl_capabilities, ainl_security_report, and ainl_run.

MCP v1 runs with safe defaults (core-only adapters, conservative limits). Operators can scope which tools/resources are exposed via named exposure profiles (AINL_MCP_EXPOSURE_PROFILE) or env-var inclusion/exclusion lists. See section 9 of docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md for the full quickstart, exposure scoping, and gateway deployment guidance.

Three layers: MCP exposure profile → what tools/resources the host can discover. Security profile / capability grant → what execution is allowed. Policy / limits → what each run is constrained by.

For Claude Code / Cowork / Dispatch users: Treat AINL as a scoped MCP tool provider and deterministic workflow/runtime layer underneath your host. Start with validate_only or inspect_only exposure profiles, and only enable safe_workflow after operators have reviewed security profiles, grants, policies, limits, and adapter exposure. AINL is not the host, not Cowork, not a gateway, and not a control plane. For a concrete validator → inspector → safe-runner walkthrough, see the End-to-end example section of docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md.

Core first, advanced later. The paths above use the core compiler and runtime only. Advanced/operator-only surfaces (agent coordination, memory migration, OpenClaw extensions) are documented separately under docs/advanced/ and are not the recommended starting point for new users.

For the full getting-started guide, see docs/getting_started/README.md.

Why AINL Exists

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:

• Prompt bloat and rising token cost
• Hidden state and brittle orchestration
• Poor auditability and hard-to-debug tool behavior

AINL addresses this by moving orchestration out of the model and into a deterministic execution substrate:

1. The model describes the workflow once
2. The compiler validates it
3. The runtime executes it deterministically
4. State lives in variables, cache, memory, databases, and adapters — not in prompt history

flowchart LR
A[AINL Source] --> B[Compiler]
B --> C[Canonical Graph IR]
C --> D[Runtime Engine]
D --> E[Adapters / Tools / State]
D --> F[Optional LLM Calls]

The graph is the source of truth. The runtime is the orchestrator. The model is a bounded reasoning component inside the system.

What Makes AINL Different

1. Graph-first, not prompt-first

AINL programs compile to canonical graph IR. Execution follows graph semantics, not ad hoc conversational state.

2. AI-oriented surface syntax

The surface language is intentionally compact and structured for parseability, determinism, and low-entropy generation by models.

3. Strict-mode guarantees

AINL's strict mode enforces high-value invariants such as:

• Canonical graph emission
• No undeclared references
• No unknown module operations
• Adapter arity validation
• No unreachable or duplicate nodes
• Canonical node IDs
• Validated call returns
• Controlled exits

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.

4. Adapters separate "what" from "how"

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.

PTC-style overlays are additive and opt-in:

• ptc_runner for external PTC-Lisp execution (R ptc_runner run ...)
• llm_query for ad-hoc LLM calls in graph steps
• optional # signature: ... metadata with runtime checks via intelligence/signature_enforcer.py
• _-prefixed context firewall at adapter/export serialization boundaries
• trajectory export to PTC-compatible JSONL via intelligence/trace_export_ptc_jsonl.py

5. Multi-target leverage

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.

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.

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:

ainl-validate examples/hyperspace_demo.ainl --strict --emit hyperspace -o demo_agent.py
cd /path/to/AI_Native_Lang && AINL_LOG_TRAJECTORY=1 python3 demo_agent.py
# optional: ainl run examples/hyperspace_demo.ainl --enable-adapter vector_memory --enable-adapter tool_registry --log-trajectory --json

6. Compile-once, run-many

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.

Competitive Landscape

AINL sits at the intersection of graph-native agent orchestration, deterministic workflow execution, and AI-native programming languages.

For a detailed comparison of graph-native vs prompt-loop architectures with production evidence, see docs/case_studies/graph_agents_vs_prompt_agents.md.

AINL uniquely combines:

• graph-first canonical IR
• strict validation & conformance
• adapter-based effect system
• compile-once, run-many execution
• multi-target emission (API, UI, DB, infra)

→ Treating AI systems as deterministic programs, not prompt loops.

Who AINL Is For

AINL is best suited for:

• AI engineers and agent builders
• teams building internal AI workers and structured automations
• platform and ops teams that need controlled AI workflows
• enterprises that care about repeatability, auditability, and workflow governance

AINL is less optimized for casual chatbot prototyping, one-off prompt hacks, or no-code-first usage.

Why businesses care

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.

Why AI agents care

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.

Real-World Usage: Apollo + OpenClaw

AINL is not just a speculative language design. It is already used in live OpenClaw-integrated workflows.

The Apollo / OpenClaw stack exercises adapters such as email, calendar, social, db, svc, cache, queue, wasm, memory, extras, and tiktok.

Production-validated examples include:

• demo/monitor_system.lang — recurring multi-module monitor
• Daily digest workflows
• Infrastructure watchdogs
• Lead enrichment
• Token cost tracking
• TikTok SLA monitoring
• Canary probes
• Memory pruning
• Session continuity
• Meta-monitoring of the monitor fleet itself

These programs demonstrate that AINL is effective for recurring monitors, stateful automation, autonomous ops, safety-aware tool orchestration, and long-lived agent systems.

Where AINL helps most

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.

Token Efficiency

AINL's compactness and cost benefits should be described carefully.

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

Bottom line: AINL lowers overall token usage while increasing capability, predictability, and reliability.

What is supported today:

• Reproducible size metrics default to tiktoken cl100k_base (see 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.
• AINL is often denser than equivalent generated implementation artifacts in the benchmark setup we publish—always profile- and mode-scoped
• minimal_emit is the more honest deployment comparison; full_multitarget is downstream expansion leverage, not apples-to-apples terseness
• --strict-mode on scripts/benchmark_size.py enables true strict compilation (reachability pruning) for canonical_strict_valid only—see BENCHMARK.md callout when active
• Compile-once / run-many workflows reduce repeated model-generation cost

What is not supported:

• Universal compactness claims against all mainstream languages
• Guaranteed tokenizer pricing savings from lexical proxy metrics alone

Current benchmark framing:

• canonical_strict_valid is the primary headline profile (19/19 viable example programs in tooling/artifact_profiles.json).
• 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.
• Highlights (from 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.
• 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.
• 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).
• In minimal_emit, mixed compatibility examples can be smaller or larger depending on artifact class and required targets
• Evidence pack: reproducible size + runtime benchmarks (tiktoken sizing, compile-time column, latency/RSS, cost estimates, reliability batches, handwritten baselines) live in BENCHMARK.md with automation in make benchmark / make benchmark-ci and CI regression gating—see docs/benchmarks.md for the full map.

# Refresh size markdown + JSON and runtime JSON (local).
# Uses `scripts/benchmark_size.py --mode wide` (core + full hybrid + minimal_emit).
make benchmark

# CI-style JSON only (does not rewrite BENCHMARK.md)
make benchmark-ci

Hybrid / LangGraph / Temporal optional deps: pip install -e ".[interop]" or ".[benchmark]" — see docs/PACKAGING_AND_INTEROP.md.

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.

Status

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.

Public release expectations:

• the graph-first compiler/runtime core is the most stable part of the project,
• server/OpenAPI/runtime/tooling are the strongest current implementation lanes,
• some examples and compatibility artifacts are intentionally classified as non-strict or legacy,
• broad target coverage exists, but not every target is equally mature or equally validated.

For implementation and shipped-capability status, see:

• docs/CONFORMANCE.md
• docs/RELEASE_READINESS.md
• docs/runtime/TARGETS_ROADMAP.md
• docs/AINL_CANONICAL_CORE.md
• docs/EXAMPLE_SUPPORT_MATRIX.md
• docs/advanced/SAFE_USE_AND_THREAT_MODEL.md

Best supported today

• Canonical compile path in compiler_v2.py
• Graph-first runtime execution in runtime/engine.py
• Formal prefix grammar orchestration in compiler_grammar.py
• Graph normalization, diff, patch, and canonicalization tooling in tooling/
• Server/OpenAPI emission and runtime-backed execution flow
• Runtime-native adapters with contract tests: http, sqlite, postgres, mysql, redis, dynamodb, airtable, supabase, fs, tools
• Runner service with policy-gated /run, /capabilities, health/metrics: scripts/runtime_runner_service.py
• Adapter privilege-tier metadata and security profiles: tooling/adapter_manifest.json, tooling/security_profiles.json
• Security/privilege introspection tooling: tooling/security_report.py
• Adapter tier model — 29 core + 16 extended (all supported, no deprecations): docs/adapters/ADAPTER_TIERS.md

Use with care

• Compatibility examples are retained intentionally; do not assume all public examples are strict-valid.
• 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.
• 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.

Documentation

Essential reading

• What is AINL? (canonical primer + capabilities): docs/WHAT_IS_AINL.md · root WHAT_IS_AINL.md (stub → docs)
• 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
• Reactive / event-driven workflows (DynamoDB Streams, Supabase Realtime, Redis Pub/Sub, Airtable webhooks) + examples: docs/reactive/REACTIVE_EVENTS.md, examples/reactive/
• Advanced durability patterns for multi-node/cross-process checkpoints and cursors using existing adapters only: docs/reactive/ADVANCED_DURABILITY.md
• Packaged durability templates (Redis + Postgres checkpoint helpers): templates/durability/
• Production starter templates (durability + observability-ready workers): templates/production/
• 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
• Getting started (3 integration paths): docs/getting_started/README.md
• Primary docs hub: docs/README.md
• Audience guide: docs/AUDIENCE_GUIDE.md
• Spec: docs/AINL_SPEC.md
• Canonical core: docs/AINL_CANONICAL_CORE.md
• Full docs reference map: docs/DOCS_INDEX.md
• Benchmarks & evidence (size, runtime, CI, LLM/cloud): docs/benchmarks.md

Architecture and internals

• Graph/IR introspection: docs/architecture/GRAPH_INTROSPECTION.md
• State discipline (tiered state model): docs/architecture/STATE_DISCIPLINE.md
• Memory adapter contract (v1 + additive v1.1 deterministic metadata/filtering): docs/adapters/MEMORY_CONTRACT.md, docs/adapters/MEMORY_CONTRACT_V1_1_RFC.md

Memory & State

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

• Runtime semantics: SEMANTICS.md
• Runtime/compiler ownership: docs/RUNTIME_COMPILER_CONTRACT.md
• Grammar reference: docs/language/grammar.md
• Conformance and strict policy: docs/CONFORMANCE.md
• Embedding in meta-agent loops: docs/EMBEDDING_RESEARCH_LOOPS.md
• MCP research payload contract: docs/operations/MCP_RESEARCH_CONTRACT.md

Operations and deployment

• Sandbox execution profiles: docs/operations/SANDBOX_EXECUTION_PROFILE.md
• Runtime container guide: docs/operations/RUNTIME_CONTAINER_GUIDE.md
• External orchestration guide: docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md
• Integration story (AINL in agent stacks): docs/INTEGRATION_STORY.md
• Autonomous ops playbook: docs/operations/AUTONOMOUS_OPS_PLAYBOOK.md
• Named security profiles: tooling/security_profiles.json
• Security/privilege report: tooling/security_report.py
• Safe use and threat model: docs/advanced/SAFE_USE_AND_THREAT_MODEL.md
• MCP server overview: section 9 of docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md
• MCP server for AI coding agents: scripts/ainl_mcp_server.py (see external orchestration guide, section 9)
• LLM/tool cost & budget observability pack (CostTracker/BudgetPolicy/dashboard): docs/MONITORING_OPERATIONS.md and docs/INTELLIGENCE_PROGRAMS_INTEGRATION.md

Examples and case studies

• Example support levels: docs/EXAMPLE_SUPPORT_MATRIX.md
• OpenClaw agent quickstart: docs/agents/openclaw-quickstart.md
• Case studies: docs/case_studies/ — graph-native vs prompt-loop agents, runtime cost advantage
• Workflow patterns: docs/PATTERNS.md

For AI agents and bots

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

Release and contribution

• 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 — run pip install -U ainativelang after 1.8.0 appears there (docs/RELEASING.md).
• Release readiness matrix: docs/RELEASE_READINESS.md
• No-break migration tracker: docs/NO_BREAK_MIGRATION_PLAN.md
• Release notes: docs/RELEASE_NOTES.md
• Maintainer release execution guide: docs/RELEASING.md
• Hybrid deployment runbook: docs/hybrid/OPERATOR_RUNBOOK.md
• Immediate post-release roadmap: docs/POST_RELEASE_ROADMAP.md
• Docs maintenance contract: docs/DOCS_MAINTENANCE.md
• Contributor guide: CONTRIBUTING.md
• Security and support: SECURITY.md, SUPPORT.md
• Machine-readable support levels: tooling/support_matrix.json
• Safe optimization guidance: docs/runtime/SAFE_OPTIMIZATION_POLICY.md

Technical Architecture

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.

AINL is best understood as a graph-canonical intermediate programming system with:

• a compact textual surface for generation and transport,
• a compiler/runtime pair designed around deterministic IR,
• emitters for practical targets,
• and tooling for constrained decoding, diffing, patching, and evaluation.

Core invariant

Canonical IR = nodes + edges; everything else is serialization.

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.

Surfaces and usage lanes

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.

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.

Current security and operator capabilities:

• 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.
• Adapter capability gating — explicit allowlists via AdapterRegistry; only adapters in the effective grant's allowlist can be called.
• 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.
• 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.
• 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). Profiles are loaded as capability grants at startup.
• 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.
• 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.
• 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, result hashes (no raw payloads), and redacted arguments. See docs/operations/AUDIT_LOGGING.md.
• 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.

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.

See:

• docs/INTEGRATION_STORY.md — how AINL fits inside agent stacks, pain-to-solution map, integration surface
• Generic external executors via HTTP bridge (multi-backend capable): 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_validate.py, modules/common/executor_bridge_request.ainl.
• docs/operations/CAPABILITY_GRANT_MODEL.md — host handshake, restrictive-only merge, env-var profile loading
• docs/operations/AUDIT_LOGGING.md — structured runtime event logging
• docs/operations/EXTERNAL_ORCHESTRATION_GUIDE.md — capability discovery, policy-gated execution, integration checklist
• docs/operations/SANDBOX_EXECUTION_PROFILE.md — adapter profiles, limit profiles, environment guidance, named security profiles
• docs/operations/RUNTIME_CONTAINER_GUIDE.md — containerized deployment patterns
• docs/advanced/SAFE_USE_AND_THREAT_MODEL.md — trust model, safe-use guidance, and privilege-tier explanation

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.

Key docs in this lane:

• docs/advanced/SAFE_USE_AND_THREAT_MODEL.md — safe use, threat model, and advisory vs enforced fields.
• docs/advanced/AGENT_COORDINATION_CONTRACT.md — AgentTaskRequest/AgentTaskResult/AgentManifest envelopes and local mailbox contract.
• docs/EXAMPLE_SUPPORT_MATRIX.md (OpenClaw compatibility family) — advanced coordination and OpenClaw examples.
• tooling/coordination_validator.py, scripts/validate_coordination_mailbox.py — optional mailbox linter for advanced coordination usage.

Stability boundaries

• 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
• 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
• Artifact profile contract: strict/non-strict/legacy expectations are defined in tooling/artifact_profiles.json
• 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

Standardized health envelope

All production monitors use a common message envelope for notifications:

{
  "envelope": {"version":"1.0","generated_at":"<ISO>"},
  "module": "<monitor_name>",
  "status": "ok" | "alert",
  "ts": "<ISO>",
  "metrics": { ... },
  "history_24h": { ... },
  "meta": {}
}

See docs/operations/STANDARDIZED_HEALTH_ENVELOPE.md.

Deployment

Production deploy (Docker)

From repo root after emitting:

cd tests/emits/server
docker compose up --build

Or build image from repo root: docker build -f tests/emits/server/Dockerfile .

The emitted server also includes openapi.json for API docs, codegen, and gateways.

Production: logging, rate limit, K8s

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.

Requirements

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

Hybrid Deployments

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

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/ · docs/hybrid_langgraph.md.

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). Activities use execute_ainl_activity() from runtime/wrappers/temporal_wrapper.py. Example: examples/hybrid/temporal_durable_ainl/.

LangChain / CrewAI (tools): optional langchain_tool adapter — python3 -m cli.main run ... --enable-adapter langchain_tool. Demo: examples/hybrid/langchain_tool_demo.ainl.

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. Tiered design: BradyD2003/ctxzip, Brady Drexler. Graph/impact/packing ideas: chrismicah/forgeindex, Chris Micah.

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.

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.

S app coding_agent /agent

# Index once (setup step or dedicated entrypoint)
L_index:
  R code_context.INDEX "/path/to/your/repo" ->index_result
  J index_result

# Main loop: query repeatedly (Tier 1 = signatures + summaries)
L_query:
  R code_context.QUERY_CONTEXT developer_query 1 50 ->context
  R code_context.COMPRESS_CONTEXT developer_query 8000 ->packed
  R code_context.STATS ->stats
  # ... feed context into an LLM node or tool ...
  J context

Bind developer_query from a slot, prior step, or input. The JSON store persists, so INDEX is typically run once per workspace.

Repo Layout

Tooling Reference

Visualize your workflow

Compile a .ainl file to Mermaid for GitHub, 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.

Your first diagram (from repo root):

python3 -m cli.main visualize examples/hello.ainl --output - > hello.mmd
# After pip install -e .
ainl visualize examples/hello.ainl --output - > hello.mmd

1. Open mermaid.live.
2. Click the left editor pane and paste the entire contents of hello.mmd.

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

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.

Save / share on mermaid.live: Export → PNG or SVG, Share (link for X/Reddit), or Edit → copy the Mermaid block for README or posts.

# Write to a file, or stdout
ainl visualize examples/hello.ainl --output diagram.md
ainl-visualize examples/hello.ainl -o diagram.md

Export as image (PNG/SVG)

# PNG export
ainl visualize examples/hello.ainl --png diagram.png

# SVG export
ainl visualize examples/hello.ainl --svg diagram.svg

# Optional render size
ainl visualize examples/hello.ainl --png diagram.png --width 1600 --height 1000

# Denser graph: timeout module + workflow memory put/list/prune (strict-safe example)
ainl visualize examples/timeout_memory_prune_demo.ainl --png docs/assets/timeout_memory_prune_flow.png

Image export uses Playwright. Install dev deps and Chromium once:

pip install -e ".[dev]"
playwright install chromium

Use --no-clusters for a flat graph, --labels-only for dense programs, and -o - for stdout.

Example output (paste into https://mermaid.live)

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:

graph TD
    direction TB

    subgraph c_retry ["retry"]
        "retry/ENTRY"[ENTRY] --> "retry/n1"[EXPONENTIAL 5 200]
        "retry/n1" --> "retry/EXIT_OK"[EXIT_OK]
        "retry/n1" --> "retry/EXIT_FAIL"[EXIT_FAIL]
    end

    %% Synthetic edges: Call → included label entry (not explicit in IR)
    L1[Your Main Logic] -->|"call"| "retry/ENTRY"

Real output uses fully qualified IDs like "retry/ENTRY/n1" and clusters automatically by include alias prefix (retry/… → subgraph retry).

• Validator CLI: python3 scripts/validate_ainl.py [file.lang] [--emit server|react|openapi|prisma|sql|hyperspace] [-o path]; stdin supported.
• 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.
• Validator web: uvicorn scripts.validator_app:app --port 8766 then open http://127.0.0.1:8766/ to paste and validate.
• 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.
• Runtime modes: ainl run ... --execution-mode graph-preferred|steps-only|graph-only --unknown-op-policy skip|error.
• 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).
• Golden fixtures: ainl golden validates examples/*.ainl against *.expected.json.
• Replay tooling: ainl run ... --record-adapters calls.json and ainl run ... --replay-adapters calls.json for deterministic adapter replay.
• 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).
• Runner service: ainl-runner-service (FastAPI) with /run, /enqueue, /result/{id}, /capabilities, /health, /ready, and /metrics.
• 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]".
• Tool API schema: tooling/ainl_tool_api.schema.json (structured compile/validate/emit loop contract).
• Synthetic dataset: python3 scripts/generate_synthetic_dataset.py --count 10000 --out data/synthetic — writes only programs that compile.
• Formal prefix grammar (compiler-owned): compiler_grammar.py is the source of truth for prefix lexical/syntactic/scope admissibility.
• 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.
• Decoder helpers: next_token_priors(prefix), next_token_mask(prefix, raw_candidates), next_valid_tokens(prefix).
• Compile-once / run-many proof pack: see docs/architecture/COMPILE_ONCE_RUN_MANY.md.
• Program summary: python scripts/inspect_ainl.py examples/hello.ainl
• Full canonical IR dump: ainl inspect examples/hello.ainl --strict
• Run summary: python scripts/summarize_runs.py run1.json run2.json
• Benchmarks (size + runtime + CI gate): make benchmark (full, updates BENCHMARK.md); make benchmark-ci (JSON-only CI-style). Narrative + metrics glossary: 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.
• Corpus tools: python scripts/evaluate_corpus.py --mode dual, python scripts/validate_corpus.py --include-negatives, pytest tests/test_corpus_layout.py -v
• Fine-tune: bash scripts/setup_finetune_env.sh, .venv-ci-smoke/bin/python scripts/finetune_ainl.py --profile fast --epochs 1 --seed 42
• Post-train inference: .venv-py310/bin/python scripts/infer_ainl_lora.py --adapter-path models/ainl-phi3-lora --max-new-tokens 120 --device cpu
• Docs contract guard: ainl-check-docs for cross-link/staleness/coupling checks.
• Pre-commit: pre-commit install to run docs/quality hooks locally.
• Test profiles: .venv-py310/bin/python scripts/run_test_profiles.py --profile <name> — core (default), emits, lsp, integration, full.

Async runtime (optional)

AINL keeps sync runtime behavior by default. To run with the native async engine path:

AINL_RUNTIME_ASYNC=1 ainl run examples/hello.ainl --enable-adapter postgres
# or
ainl run examples/hello.ainl --enable-adapter postgres --runtime-async

See docs/runtime/ASYNC_RUNTIME.md for adapter coverage and fallback behavior. 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.

Reactive observability (optional)

AINL can emit lightweight adapter timing + reactive batch metrics (off by default):

AINL_RUNTIME_ASYNC=1 AINL_OBSERVABILITY=1 \
  ainl run examples/reactive/hybrid_stream_broadcast.ainl \
  --runtime-async --observability --enable-adapter dynamodb --enable-adapter supabase --enable-adapter redis --enable-adapter memory

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

You can also persist metrics to a JSONL sink file:

AINL_RUNTIME_ASYNC=1 AINL_OBSERVABILITY=1 AINL_OBSERVABILITY_JSONL=/tmp/ainl-reactive-metrics.jsonl \
  ainl run examples/reactive/hybrid_stream_broadcast.ainl \
  --runtime-async --observability --observability-jsonl /tmp/ainl-reactive-metrics.jsonl \
  --enable-adapter dynamodb --enable-adapter supabase --enable-adapter redis --enable-adapter memory

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.

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.

Status: Production Ready for Reactive Workflows

AINL is now production-ready for reactive/event-driven graph workflows with a complete end-to-end stack:

• Full native async runtime (--runtime-async) with async-capable adapter execution.
• Comprehensive database adapters across sqlite, postgres, mysql, redis, dynamodb, airtable, and supabase.
• Reactive primitives with bounded, practical semantics:
  • DynamoDB Streams with checkpointing and ack flows
  • Supabase Realtime with fan-out, replay, cursor, and ack helpers
  • Redis pub/sub for low-latency internal fan-out
• Observability support for reactive workloads, including structured metrics and JSONL sink output (--observability-jsonl / AINL_OBSERVABILITY_JSONL).
• Production starter templates in templates/production/ for immediate rollout patterns.
• Durability guidance in docs/reactive/ADVANCED_DURABILITY.md for multi-process and multi-node checkpoint/cursor persistence using existing adapters.

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.

PostgreSQL adapter (runtime-native)

Enable postgres explicitly and configure credentials via environment variables (preferred) or CLI flags:

export AINL_POSTGRES_URL='postgresql://user:pass@localhost:5432/appdb'
ainl run examples/hello.ainl --enable-adapter postgres --postgres-allow-table users --postgres-allow-write

AINL graph syntax:

S app core noop
L1:
  R postgres.query "SELECT id, email FROM users WHERE id = %s" [42] ->rows
  J rows

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. Full contract and security guidance: docs/adapters/POSTGRES.md.

MySQL adapter (runtime-native)

Enable mysql explicitly and configure credentials via environment variables (preferred) or CLI flags:

export AINL_MYSQL_URL='mysql://user:pass@localhost:3306/appdb'
ainl run examples/hello.ainl --enable-adapter mysql --mysql-allow-table users --mysql-allow-write

AINL graph syntax:

S app core noop
L1:
  R mysql.query "SELECT id, email FROM users WHERE id = %s" [42] ->rows
  J rows

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. Full contract and security guidance: docs/adapters/MYSQL.md.

Redis adapter (runtime-native)

Enable redis explicitly and configure via environment variables (preferred) or CLI flags:

export AINL_REDIS_URL='redis://localhost:6379/0'
ainl run examples/hello.ainl --enable-adapter redis --redis-allow-write --redis-allow-prefix session:

AINL graph syntax:

S app core noop
L1:
  R redis.set "session:42" "{\"state\":\"active\"}" 300 ->ok
  R redis.get "session:42" ->value
  J value

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. Full contract and security guidance: docs/adapters/REDIS.md.

DynamoDB adapter (runtime-native)

Enable dynamodb explicitly and configure endpoint/region via environment variables (preferred) or CLI flags:

export AINL_DYNAMODB_URL='http://127.0.0.1:8000'
export AWS_ACCESS_KEY_ID='dummy'
export AWS_SECRET_ACCESS_KEY='dummy'
export AWS_DEFAULT_REGION='us-east-1'
ainl run examples/hello.ainl --enable-adapter dynamodb --dynamodb-allow-table users --dynamodb-allow-write

AINL graph syntax:

S app core noop
L1:
  R dynamodb.get "users" {"pk":"u#42","sk":"profile"} ->out
  J out

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). Full contract and security guidance: docs/adapters/DYNAMODB.md.

Airtable adapter (runtime-native)

Enable airtable explicitly with scoped API key + base id:

export AINL_AIRTABLE_API_KEY='pat_xxx'
export AINL_AIRTABLE_BASE_ID='app_xxx'
ainl run examples/hello.ainl --enable-adapter airtable --airtable-allow-table users --airtable-allow-write

AINL graph syntax:

S app core noop
L1:
  R airtable.list "users" {"maxRecords": 20, "pageSize": 20} ->rows
  J rows

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). Full contract and security guidance: docs/adapters/AIRTABLE.md.

Supabase adapter (runtime-native wrapper)

Enable supabase explicitly with Supabase DB + project credentials:

export AINL_SUPABASE_DB_URL='postgresql://user:pass@localhost:5432/appdb'
export AINL_SUPABASE_URL='https://your-project.supabase.co'
export AINL_SUPABASE_SERVICE_ROLE_KEY='ey...'
ainl run examples/hello.ainl --enable-adapter supabase --supabase-allow-table users --supabase-allow-write

AINL graph syntax:

S app core noop
L1:
  R supabase.select "users" {"id": 42} ["id","email"] ->out
  J out

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. Full contract and security guidance: docs/adapters/SUPABASE.md.

Project Origin

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.

The human initiator of AINL is Steven Hooley.

• X: https://x.com/sbhooley
• Website: https://stevenhooley.com
• LinkedIn: https://linkedin.com/in/sbhooley

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.

For full attribution context, see docs/PROJECT_ORIGIN_AND_ATTRIBUTION.md, tooling/project_provenance.json, and docs/CHANGELOG.md.

Community and Support

• Contribution workflow: CONTRIBUTING.md
• Contributor behavior policy: CODE_OF_CONDUCT.md
• Security reporting: SECURITY.md
• Support expectations and channels: SUPPORT.md
• Commercial/licensing inquiries: COMMERCIAL.md

Community & Growth

Join the conversation:

• GitHub Discussions (enable if not already)
• Telegram
• X / Twitter

See GROWTH-PLAN.md for how we're scaling sustainably.

Licensing

AI Native Lang uses an open-core licensing model.

• Open Core: Designated core code is licensed under the Apache License 2.0. See LICENSE.
• Documentation and Content: Non-code docs/content are licensed under LICENSE.docs, unless noted otherwise.
• Models, Weights, and Data Assets: Model/checkpoint/data-style artifacts may be governed by separate terms. See MODEL_LICENSE.md.
• Commercial Offerings: Some hosted/enterprise/premium capabilities are available under separate commercial terms. See COMMERCIAL.md.
• Trademarks: AINL and AI Native Lang branding rights are governed separately from code licenses. See TRADEMARKS.md.

OpenClaw integration

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 for runners, drift checks, AINL_WORKSPACE cron patterns, and the ainl_bridge_main.py entrypoint.

ArmaraOS Integration

AINL integrates seamlessly with OpenFang, the open-source Agent Operating System.

Quick Start

# Install AINL for OpenFang
ainl install armaraos

# Emit a hand package
ainl emit --target armaraos -o my_hand/ workflow.ainl

# Run with OpenFang
armaraos hand run my_hand --input '{}'

# Check status
ainl status --host armaraos

Features

• WASM Sandbox: All hands run in a secure WASM sandbox with configurable memory/instruction limits
• Merkle Audit Trail: Token usage is recorded with cryptographic proofs for accountability
• Taint Tracking: Data lineage tracking for sensitive information
• MCP Native: OpenFang uses AINL as a first-class MCP server
• Tauri Sidecar: Desktop apps can embed AINL via OpenFang sidecar

Configuration

After ainl install armaraos, your ~/.armaraos/config.toml will contain:

[[mcp_servers]]
name = "ainl"
command = "ainl-mcp"
args = []

Refer to armaraos/docs/ for detailed documentation.

Production monitoring

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

Quick validate (no writes):

python3 openclaw/bridge/run_wrapper_ainl.py token-budget-alert --dry-run
python3 openclaw/bridge/run_wrapper_ainl.py weekly-token-trends --dry-run

Wrappers live under openclaw/bridge/wrappers/ (token_budget_alert.ainl, weekly_token_trends.ainl); adapter logic in openclaw/bridge/bridge_token_budget_adapter.py.

KEYWORDS

• AI-native programming language
• agent workflow language
• deterministic agent workflows
• graph-based agent orchestration
• LLM orchestration
• AI agent workflow engine
• workflow language for AI agents
• deterministic AI workflows
• production AI agents
• reliable AI agent workflows
• auditable AI workflows
• deterministic workflow engine for AI
• compile-once run-many AI workflows
• long-running AI agents
• stateful AI agents
• autonomous ops workflows
• LangChain alternative
• LangGraph alternative
• CrewAI alternative
• Temporal for AI agents
• sandboxed agent deployment

ArmaraOS

ArmaraOS is an independent open-source project and is not affiliated with any entities using similar names (e.g., Amaros AI or other). 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. It includes and integrates AINativeLang (https://github.com/sbhooley/ainativelang) for deterministic AI workflows. Modifications Copyright (c) 2026 sbhooley. Original OpenFang and AINativeLang works retain their respective licenses.

ArmaraOS — The regenerative Agent OS.

Powered by AINativeLang’s deterministic workflows. Like a starfish, it adapts, regrows reliable processes, and thrives with multiple arms (tools, channels, memory, and autonomous Hands) — never breaking, always regenerating.

Quickstart

ainl init my-worker --target armaraos && ainl install armaraos

Downloads & full docs: https://ainativelang.com/