ainativelang

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)/© 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.4

The 42 graphs on 1.8.3 stay as they are. No new verb.

• \d: a decimal digit, same as Python re. A superscript does not match.
• Long tokens: a single-character quantifier matches in a loop.
• Caption and hashtag: still REGEX_FINDALL for the whole match, then REGEX_REPLACE of that match. Replacing the whole filing keeps the words around the caption.

New in v1.8.3

EQ, CONTAINS, TRIM, If, and Loop stay as they are.

• Certified patterns: caption, counsel, the short docket, hashtags, and a \u character class in tests/fixtures/ainl_re_1.json. REGEX_FINDALL returns the full match. Counsel’s Unicode \w matches Python re.
• Public fetch, opt-in: allow_public / --http-allow-public. Default deny stays. * is not a wildcard. Metadata stays refused.
• Extract: core.EXTRACT returns text and links from HTML or RSS/Atom. HTML_TEXT is still only a tag stripper.
• Already in published 1.8.2: core.UNTRUSTED_PROMPT, core.SHAPE, and the queue.PUT idempotency key.

New in v1.8.2

EQ, CONTAINS, TRIM, If, and Loop are unchanged.

• Decision graphs: Uses, AINL_SECURITY_PROFILE=firm, core.UNTRUSTED_PROMPT, core.SHAPE, a queue.PUT idempotency key, limits["now"], and a compile rejection of cloud-key literals. X core.ENV uses the host allowlist in any case. Platform names such as AzureWebJobsStorage stay unreadable.
• Deny by default: SimpleHttpAdapter() and an empty A2A allowlist deny every host. Metadata addresses stay closed. The runner log records argument counts and types, not values.
• Contract: docs/operations/DECISION_OPS_1_8_2.md. List: docs/CHANGELOG.md § v1.8.2.

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

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 descri</https:></https:></https:>

README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。