AI Native Lang (AINL)

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% fewe