ainativelang AGENTS.md

AGENTS.md — Ground Truth for AI Agents

For agents — install AINL (one step)

If you are an AI agent that needs AINL set up in your host stack, run:

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 your host (Claude Code, Cursor, Cline, Codex CLI, Codex Desktop, Claude Desktop, OpenClaw, Hermes, ArmaraOS, or any generic MCP host), merges the right MCP server entry into its config, and verifies with ainl doctor. Existing config files are backed up with a timestamp before any change.

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

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

---

Read this FIRST before doing anything in this repository.

Headline repo stats: If you edit the compiler, runtime, CLI, adapters, tests, or examples, run python scripts/refresh_repo_stats.py or install pre-commit (pre-commit install — see CONTRIBUTING.md) so STATUS.yaml and this file’s Repository Layout stay accurate. CI enforces this on every PR.

What This Repo Is

Python compiler + runtime for AINL (AI Native Language), version 1.8.0. AINL compiles .ainl source files into an IR (intermediate representation) graph, then executes that graph via adapters (database, HTTP, LLM, Solana, etc).

Repository Layout

compiler_v2.py          — The compiler (7052 lines). Parses .ainl → IR dict.
compiler_diagnostics.py — Error/warning types used by compiler.
runtime/engine.py       — The runtime engine (3106 lines). Executes IR graphs.
runtime/adapters/       — Runtime adapter base classes and builtins.
cli/main.py             — CLI entry point (3766 lines). All `ainl` commands.
adapters/               — 70 Python files under `adapters/` (recursive); ArmaraOS monitor bootstrap: `armaraos_integration.py`, `armaraos_defaults.py` (`build_armaraos_monitor_registry`, `boot_armaraos_graph_memory`). See `docs/ARMARAOS_INTEGRATION.md`, `docs/adapters/AINL_GRAPH_MEMORY.md`.
armaraos/emitter/       — `armaraos.py`: `ainl emit --target armaraos` Hand pack (`HAND.toml`, IR JSON, `security.json`, README) with `schema_version` for openfang-hands validation.
scripts/                — Standalone scripts (`refresh_repo_stats.py`, emit_langgraph, emit_temporal, `ainl_mcp_server.py` MCP entrypoint, etc).
tooling/                — Graph analysis, normalization, effect analysis; `ainl_get_started.py` (authoring wizard + adapter contracts), `corpus_mining.py` (strict-valid family index for `corpus/strict_valid_family_index.json`).
corpus/                 — Generated/mined JSON (e.g. `strict_valid_family_index.json`, `reverse_prompt_fixtures.json`); see `docs/operations/MCP_AINL_WIZARD_AND_CORPUS.md`.
examples/               — 110+ `.ainl` files under `examples/` (strict CI subset: `tooling/artifact_profiles.json`). See `examples/README.md`.
tests/                  — 264 `*.py` files under `tests/` (~32k lines total); 234 `test_*.py` modules; pytest —collect-only: 1636/1675 (see STATUS.yaml). Definitions: **`STATUS.yaml`** → `real_and_working.tests`.
docs/                   — Documentation (some accurate, some aspirational — see **`STATUS.yaml`**).