Preface #

Why I Created Neam #

In 2024, the landscape of AI agent development looked something like this: a Python script importing LangChain, another importing AutoGen, a third gluing together custom REST calls to OpenAI, and a YAML file describing how they should all talk to each other. The developer stitching these pieces together was effectively writing an ad hoc programming language inside Python -- one without a type system, without a debugger, without a compiler to catch mistakes before they reached production.

I asked a simple question: What if AI agent orchestration had its own language?

Not a framework. Not a library. A language -- with a parser, a compiler, a bytecode format, and a virtual machine purpose-built for the problem domain. A language where "agent," "tool," "knowledge base," and "handoff" are first-class constructs, not Python classes you import and hope behave correctly at runtime.

That question led to Neam.

Neam is a domain-specific programming language for building AI agent systems. It compiles .neam source files through a parser and compiler into .neamb bytecode, which executes on a purpose-built virtual machine. The VM provides native support for LLM provider calls, retrieval-augmented generation, multi-agent orchestration, voice pipelines, tool use, structured output, cognitive features like reasoning and reflection, persistent agents (NeamClaw), 14 specialist data intelligence agents, and -- as of version 1.0.0 (NeamOne) -- full OWASP ASI01-10 and MCP01-10 security compliance, a 7-mode agent evaluation framework, and a cloud agentic stack with gateway, model router, and skill marketplace. Version 0.6.0 extended the language into cloud-native territory with distributed state, an LLM gateway, multi-cloud deployment, and production observability. Subsequent releases through v0.6.9 added skills with impl blocks and extern skill bindings (v0.6.1), guards, policies, and budgets (v0.6.2), enhanced RAG with seven retrieval strategies (v0.6.3), intelligent auto-scaling and the FinOps dashboard (v0.6.4), MCP server declarations with adopt syntax (v0.6.5), Claude skill integration and native tool calling (v0.6.6), extern skill enhancements and brand agents (v0.6.7), the cloud deployment guide with Docker, Kubernetes, and Lambda targets (v0.6.8), and OWASP-aligned agentic security hardening across ten security domains (v0.6.9). Version 0.7.0 then delivered a comprehensive data type overhaul -- Tuple, Set, Range, for-loops, destructuring, pipe operator, f-strings, and the in operator -- followed by v0.7.1 (iterator protocol, TypedArray, Record, broadcasting, comprehensions) and v0.7.2 (Table type, window functions, and advanced aggregations).

The name "Neam" is intentionally short. I wanted something you could type quickly, something that would not collide with existing tools, and something that felt like a natural command on the terminal: neamc compile, neam run, neam-cli watch.

The Neam Ecosystem at a Glance #

Before we dive into the details, here is a bird's-eye view of what Neam provides:

The Problem: Fragmented AI Agent Development #

If you have built production AI agent systems, you have encountered these problems:

No standard execution model. Every framework invents its own agent loop. LangChain has chains and agents. AutoGen has conversations. CrewAI has crews. None of them agree on how an agent should execute, how control should transfer between agents, or how errors should propagate. When you switch frameworks, you rewrite everything.

No compilation step. Python-based agent frameworks are interpreted. Configuration errors, missing tool definitions, type mismatches in structured output, and circular handoff references are all discovered at runtime -- often after you have already spent API credits on LLM calls. There is no compiler to catch these mistakes early.

No unified toolchain. Building a production agent system today requires assembling a patchwork of tools: a package manager (pip), a testing framework (pytest), an API server (FastAPI), a debugger (pdb), observability (custom logging or LangSmith), and deployment scripts (Dockerfiles you write by hand). None of these tools understand the domain of AI agents.

No native support for agent-specific patterns. Handoffs, guardrails, retrieval strategies, voice pipelines, cognitive reasoning, and autonomous execution are all implemented as library features, bolted onto general-purpose languages. They lack the deep integration that comes from being part of the language itself.

Neam addresses all of these problems by design.

Neam's Vision #

Neam's vision can be stated in a single sentence: AI agent orchestration deserves a dedicated language with a complete toolchain.

This means:

• A compiler (neamc) that catches configuration errors, validates agent declarations, resolves module imports, and produces optimized bytecode before any LLM call is made.
• A virtual machine (neam) that natively understands agents, tools, knowledge bases, handoffs, runners, guardrails, voice pipelines, and cognitive features.
• A CLI (neam-cli) with watch mode, REPL, and hot reload for rapid development.
• An API server (neam-api) that exposes agents as REST endpoints and supports the Agent-to-Agent (A2A) protocol out of the box.
• A package manager (neam-pkg) for sharing and reusing agent components, backed by the registry.neam.dev package registry and the .neampkg distribution format.
• A security-first guard/policy system with guard, guardchain, policy, and budget declarations that enforce input/output validation, rate limiting, cost caps, and OWASP-aligned agentic security controls at the language level.
• An LSP server (neam-lsp) and DAP debugger (neam-dap) for IDE integration.
• An evaluation harness (neam-gym) for benchmarking agent performance with statistical rigor.
• A shared library (libneam) for embedding the Neam runtime in other languages.

Every tool in this chain understands the domain. The LSP server knows what a valid agent declaration looks like. The debugger can step through handoff chains. The package manager understands module visibility rules. This level of integration is only possible when the toolchain is built for the domain from the ground up.

A Brief History of Neam #

Neam has evolved through ten major versions and numerous point releases, each adding a distinct capability layer. The timeline below shows this progression:

v0.1 -- Core Language. The foundation: variables, types, functions, control flow, emit statements, and the basic compilation pipeline (.neam source to AST to .neamb bytecode to VM execution). This version established that the approach was viable and that a bytecode VM for agent orchestration could be both fast and expressive.

v0.2 -- Handoffs and Orchestration. First-class support for multi-agent patterns: handoffs between agents, runner declarations for controlled execution loops, guardrails for input/output filtering, and the triage/specialist pattern that became Neam's signature orchestration model.

v0.3 -- Ecosystem and Interoperability. Multiple LLM provider support (OpenAI, Anthropic, Gemini, Ollama), the module/import system, MCP (Model Context Protocol) client integration, and the beginnings of the package manager. This version made it practical to build real-world multi-provider agent systems.

v0.4 -- Production Readiness. The features required for production deployment: voice pipelines (STT/TTS), tool use with JSON Schema parameters, RAG with seven retrieval strategies (basic, MMR, hybrid, HyDE, self-RAG, corrective RAG, agentic RAG), structured output, async/await, persistent memory (SQLite), observability and tracing, the A2A protocol server, the evaluation framework (neam-gym), multi-modal vision, streaming responses, hot reload, the LSP and DAP servers, and the shared library for language bindings.

v0.5 -- Cognitive Features. The leap from tool to thinker: reasoning strategies (chain-of-thought, plan-and-execute, tree-of-thought, self-consistency), self-reflection with configurable quality thresholds, learning loops with experience replay and pattern extraction, prompt evolution that refines an agent's system prompt over time while preserving a core identity, and autonomous goal-driven execution with budget controls and scheduling.

v0.6.0 -- Cloud-Native Deployment. Distributed state backends (PostgreSQL, Redis, DynamoDB, CosmosDB, Firestore), an LLM gateway with circuit breaking, retry with exponential backoff, provider fallback chains, and response caching. OpenTelemetry export with structured logging, privacy modes, and diagnostic triage. Multi-cloud deployment targets (AWS, GCP, Azure) with Terraform generation. Kubernetes production manifests with autoscaling, health checks, network policies, and disruption budgets. Secrets management via AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, and HashiCorp Vault. Cloud-native configuration via neam.toml. All without changing the parser, compiler, or bytecode format.

v0.6.1 -- Skills and Extern Skills. First-class skill declarations with impl blocks that encapsulate typed parameters and implementation functions directly in the language. extern skill declarations with HTTP and MCP bindings, allowing agents to call REST APIs and Model Context Protocol servers as native skills. Claude built-in tool bindings for computer use, text editing, and web search.

v0.6.2 -- Guards, Policies, and Budgets. The security-first release: guard declarations with input/output validation handlers, guardchain declarations for ordered validation pipelines, policy declarations for system-wide security rules, and budget declarations for time, cost, and token caps. Ten agentic security domains aligned with the OWASP Top 10 for Agentic Applications, covering prompt injection defense, identity and privilege controls, tool argument validation, and credential isolation.

v0.6.3 -- Enhanced RAG. Seven retrieval strategies as first-class options in knowledge block declarations: basic vector search, maximal marginal relevance (MMR), hybrid (keyword + vector), hypothetical document embeddings (HyDE), self-RAG with quality reflection, corrective RAG (CRAG) with web fallback, and agentic RAG with multi-step iterative retrieval. MCP server integration strategies (IDE, channel gateway, A2A federation) and OpenClaw interoperability.

v0.6.4 -- Intelligent Auto-Scaling and FinOps. ML-based predictive scaling with time-series analysis, pattern detection (daily/weekly cycles, traffic spikes), and warm pool management for near-zero cold starts. Multi-cloud cost arbitrage across AWS, GCP, Azure, and Alibaba Cloud with real-time spot price monitoring. GPU/SIMD acceleration (CUDA, Metal, OpenCL, AVX-512, NEON) for 470+ operations. The FinOps dashboard for real-time cost tracking per agent, per skill, per invocation with budget alerts and AI-powered optimization recommendations.

v0.6.5 -- MCP Server Declarations and Bulk Tool Import. First-class mcp_server declarations that specify command, arguments, environment isolation, and startup timeouts. The adopt syntax for selective or bulk tool import from MCP servers (adopt server.{tool_a, tool_b} or adopt server.*). Extern skill HTTP bindings with automatic URL-encoding, SSRF protection, and header injection prevention. Extern skill MCP bindings for calling remote MCP tools as native skills.

v0.6.6 -- Claude Skill Integration and Native Tool Calling. First-class Claude built-in tool bindings for computer use, text editing, and web search. Native tool calling support across providers with automatic JSON Schema generation from skill parameter declarations.

v0.6.7 -- Extern Skill Enhancements and Brand Agents. Extended extern skill bindings with richer HTTP and MCP configurations. Brand agent templates for domain-specific agent archetypes including PPTX generation agents and document processing pipelines.

v0.6.8 -- Cloud Deployment Guide. Comprehensive deployment pipeline from development to production: Docker multi-stage builds, AWS EKS (Kubernetes) manifests with autoscaling, AWS Lambda serverless targets, and end-to-end CI/CD pipelines. The neamc deploy --target command generates deployment artifacts for each target. The neam-api server exposes agents as REST endpoints with JIT compilation per request.

v0.6.9 -- Agentic Security. OWASP-aligned security hardening across ten security domains: structured audit logging (D1), tool permission model with policy declarations (D2), prompt injection defense (D3), network and SSRF protection (D4), rate limiting and throttling (D5), MCP and supply chain hardening (D6), credential isolation (D7), input validation and boundaries (D8), behavioral monitoring (D9), and human-in-the-loop controls (D10). Aligned with the OWASP Top 10 for Agentic Applications (2026) and the MAESTRO seven-layer defense model.

v0.7.0 -- DataFlow Phase 1: Core Types and Constructs. The first phase of a comprehensive data type overhaul: three new types (Tuple, Set, Range), for ... in loops with break and continue, the pipe operator (|>), f-strings (f"Hello {name}"), destructuring assignment, the in / not in operator, list slicing, string indexing, Option type exposure with is_some() / unwrap_or() methods, enhanced List methods (20+ new), Map enhancements (non-string keys, get_or, merge), String enhancements (format, regex, indexing), and type coercion rules (String + Number now works).

v0.7.1 -- DataFlow Phase 2: Data Processing and OOP. The iterator protocol with lazy evaluation and 16 chainable adapters (map, filter, take, skip, chain, zip, enumerate, flat_map, take_while, skip_while, chunk, window, unique, flatten, inspect, peekable). TypedArray for homogeneous numeric storage with vectorized operations and SIMD optimization. Record type for lightweight named structs. Broadcasting ([1,2,3] * 10 yields [10,20,30]). List/set/map comprehensions. The spread operator (...). Statistical functions (mean, median, std, percentile). A complete object-oriented type system: struct and mut struct for immutable/mutable data types with positional and named construction, impl blocks for methods (instance and static), trait definitions with required and default methods for polymorphism, sealed types for algebraic data types (discriminated unions), match expressions for exhaustive pattern matching, extend for retroactive method addition, generics (struct Pair<T, U>), property observers (willSet, didSet, guard), and declarative agentic patterns (pipeline, dispatch, parallel, loop).

v0.7.2 -- DataFlow Phase 3: Advanced Data. The Table type for columnar data with filter, sort_by, select, group_by, join, left_join, pivot, head, tail, and output methods (to_csv, to_json, to_string). GroupedTable with aggregation (agg, count, sum, mean, min, max). Window functions (window, scan) for sliding-window and cumulative computations. Table I/O for CSV and JSON import/export.

v0.8.0 -- NeamClaw: Persistent Teammates. Three distinct agent types: agent (stateless, single-turn), claw agent (persistent, multi-session with semantic memory, channels, workspace I/O, and session management), and forge agent (iterative build agents with generate-verify-refine loops). Six composable traits (Schedulable, Channelable, Sandboxable, Monitorable, Orchestrable, Searchable). Lane queue engine for multi-lane concurrent execution. DAG executor for parallel agent orchestration. Checkpoint and rewind for time-travel debugging. VM pool for parallel multi-agent execution.

v0.9.0 -- Data Intelligence Ecosystem. Fourteen specialist agents organized in a 4-layer architecture: DataAgent, ETLAgent, MigrationAgent, DataOpsAgent, GovernanceAgent, ModelingAgent, AnalystAgent (NL2SQL), DataScientistAgent (AutoML), CausalAgent (do-calculus, counterfactuals), MLOpsAgent (drift monitoring, champion-challenger), DataBAAgent (BRD generation), DataTestAgent (quality gates), DeployAgent, and the DIO (Data Intelligent Orchestrator) master agent with RACI delegation, crew formation, and 8 auto-patterns. 429 native functions, 10-domain security, 8 RAG strategies, DataSims experiments, Neam-Gym evaluation harness. For the complete data intelligence architecture, see The Intelligent Data Organization with Neam.

v1.0.0 -- NeamOne: Complete Cloud Agentic AI Stack. The production-ready release. OpCode widening from uint8_t to uint16_t (room for 65,536 operations). Full OWASP compliance: 10 Agentic Security declarations (goal_integrity, tool_validator, agent_identity, supply_chain_policy, code_sandbox, memory_integrity, message_security, circuit_breaker, human_gate, agent_attestation) covering ASI01-ASI10, plus 3 MCP Security declarations (mcp_allowlist, tool_pinning, context_guard) and aibom_config for EU AI Act compliance. RAG modernization with real provider-backed embeddings, HNSW indexing via usearch, GraphRAG, cross-encoder re-ranking, and RAGAS evaluation metrics. 7-mode agent evaluation framework (gym_evaluator) with LLM-as-Judge, Agent-as-Judge, statistical reproducibility, and CI/CD quality gates. Cloud Agentic Stack: gateway (auth, rate limiting, routing), model_router (cost/quality/latency strategies with fallback chains), and marketplace (signed skill packages). Three special agents: securitysentinel agent (OWASP monitoring with kill switches), protocolbridge agent (MCP/A2A firewall), and costguardian agent (budget management with automatic model downgrade). 28 new declaration types, 103 new native functions, bringing the total to 530+.

This book covers all versions through v1.0.0. By the time you finish it, you will have the knowledge to build, secure, evaluate, deploy, and operate production AI agent systems using Neam -- with full OWASP compliance and cloud-native infrastructure.

This is an open-source book. The full source -- every chapter, case study, and appendix -- is available in the Neam repository. You are free to read, share, distribute, and adapt this work under the Apache License, Version 2.0.

Who This Book Is For #

This book is written for four audiences, each with different goals and takeaways:

College students studying computer science, artificial intelligence, or software engineering who want to understand how programming languages work in the context of AI agent systems. You do not need prior experience with language design or compiler construction; the book explains these concepts as they arise. By the end, you will have built agents that reason, retrieve knowledge, use tools, and collaborate -- skills that are immediately applicable in coursework, capstone projects, and job interviews.

Industry professionals building AI-powered products who are tired of wrestling with framework limitations and want a purpose-built tool for the job. If you have shipped a LangChain application and felt the pain of debugging chain execution at 2 AM, this book is for you. Neam's compile-time checks, budget controls, and FinOps dashboard mean fewer surprises in production and predictable costs at scale.

Researchers exploring multi-agent systems, cognitive architectures, autonomous AI, or retrieval-augmented generation who want a reproducible, inspectable platform for experimentation. Neam's tracing, evaluation (neam-gym), and cognitive features (reasoning, reflection, learning, evolution, autonomy) make it particularly suitable for research workflows. The seven RAG retrieval strategies and the Table type for data analysis enable rigorous evaluation pipelines.

AI Operations and deployment engineers who need to package, deploy, monitor, and scale agent systems in production environments across cloud providers. This book covers Docker and Kubernetes deployment with autoscaling and health checks, multi-cloud configuration targeting AWS, GCP, Azure, and Alibaba Cloud with Terraform generation, observability with OpenTelemetry structured logging and diagnostic triage, cost-optimized infrastructure management with the FinOps dashboard, and the neam-pkg package ecosystem for distributing agent components across teams and organizations.

What You Will Build #

By the end of this book, you will have built:

Every project is runnable. Every example compiles. Every deployment target generates real artifacts you can inspect and use.

How This Book Is Organized #

The book is divided into eight parts, six case studies, and five appendices:

• Part I: Getting Started (Chapters 1--3) introduces Neam, walks through installation on macOS, Linux, and Windows, and takes you from emit "Hello, World!" to running your first compiled program.
• Part II: Language Fundamentals (Chapters 4--9b) covers variables, types, operators, functions, control flow, collections, error handling, the module system, and object-oriented programming. The full data type system is covered here: Tuple, Set, Range, TypedArray, Record, and Table types, f-strings for string interpolation, the pipe operator for data transformation chains, for ... in loops with break and continue, destructuring assignment, comprehensions, broadcasting, the iterator protocol with lazy evaluation, and the Option type with safe-access methods. Chapter 9b covers the OOP type system: struct and mut struct, impl blocks for methods, trait for shared interfaces, sealed types for algebraic data types, match expressions for pattern matching, extend for retroactive method addition, generics, property observers, and declarative agentic patterns. These chapters teach you to write Neam programs independent of any AI features.
• Part III: AI Agents (Chapters 10--14) covers agent declarations, LLM providers (OpenAI, Anthropic, Gemini, Ollama, Azure, Bedrock, Vertex AI), tool use with JSON Schema parameters, skills with impl blocks and extern skills (HTTP and MCP bindings), native tool calling, multi-agent orchestration with handoffs and runners, and the security-first guard system including guard, guardchain, policy, and budget declarations with OWASP-aligned agentic security across ten security domains.
• Part IV: Knowledge and Intelligence (Chapters 15--18) covers RAG with seven retrieval strategies (basic, MMR, hybrid, HyDE, self-RAG, corrective RAG, agentic RAG) configured through knowledge block syntax with retrieval_strategy, top_k, and reflection options. Also covers voice pipelines (STT and TTS), cognitive features (reasoning, reflection, learning, evolution, autonomy), and the A2A protocol for inter-agent communication.
• Part V: Production Deployment (Chapters 19--22) covers cloud-native configuration via neam.toml, Docker and Kubernetes deployment, multi-cloud targets (AWS, GCP, Azure, Alibaba Cloud) with Terraform generation, observability with OpenTelemetry structured logging and diagnostic triage, the JIT compilation model for optimized bytecode execution, and the neam-api server for exposing agents as REST endpoints with the A2A protocol.
• Part VI: NeamClaw (Chapters 24--28) covers persistent agent patterns: Claw agents with multi-session memory, channels, and workspace I/O; Forge agents with iterative verification loops; semantic memory and workspace search; the six composable traits (Schedulable, Channelable, Sandboxable, Monitorable, Orchestrable, Searchable); and NeamClaw API, CLI, and deployment patterns.
• Part VII: NeamOne (v1.0) (Chapters 29--32) covers the production-ready cloud agentic AI stack: OWASP security with all 10 ASI risks and 10 MCP risks as compiled declarations (Chapter 29), the 7-mode agent evaluation framework with LLM-as-Judge and RAGAS metrics (Chapter 30), the cloud agentic stack with gateway, model router, and skill marketplace (Chapter 31), and the three special agents -- SecuritySentinel, ProtocolBridge, and CostGuardian (Chapter 32).
• Case Studies include six complete systems built end-to-end: a customer service platform, a research assistant with agentic RAG, an autonomous data pipeline, an autonomous code builder, multi-channel customer support, and a secure data science pipeline with full OWASP compliance (v1.0).
• Appendices provide a complete built-in functions reference (530+ functions across 20+ categories), a neam.toml configuration reference, a CLI commands reference for all ten tools, a glossary of 80+ terms, and a cross-referenced index.

Each chapter includes runnable code examples, architectural diagrams, and exercises. The standard library contains 445+ modules across 27 domains, and the examples directory includes 39 runnable .neam programs covering every feature in this book.

Conventions Used in This Book #

Code examples in Neam syntax are shown in fenced code blocks labeled neam:

agent HelloBot {
  provider: "openai",
  model: "gpt-4o-mini",
  system: "You are a helpful assistant."
}

Shell commands are shown in blocks labeled bash:

neamc hello.neam -o hello.neamb
neam hello.neamb

Architecture and concept diagrams are shown as ASCII box diagrams throughout the book. These diagrams are designed to render clearly in terminals, markdown viewers, and print formats.

Important warnings, tips, and notes are called out in blockquote format:

Prerequisites #

To get the most from this book, you should have:

Acknowledgments #

Neam builds on outstanding open-source foundations: tree-sitter for parsing, nlohmann/json for JSON handling, uSearch for vector indexing, SQLite for persistence, lexbor for HTML parsing, miniz for compression, Google Test and Google Benchmark for testing infrastructure, and the libcurl and OpenSSL libraries that make HTTP and cryptographic operations possible.

I am grateful to the teams behind OpenAI, Anthropic, Google, and Meta (Ollama/Llama) for providing the LLM APIs that Neam orchestrates. The design of Neam's agentic features was informed by the OpenAI Agents SDK, the Model Context Protocol specification, and the Google A2A protocol -- I acknowledge these projects for advancing the state of the art in agent interoperability.

The OWASP Foundation's work on the Top 10 for Agentic Applications (ASI01-ASI10) and the Top 10 for MCP (MCP01-MCP10) directly shaped Neam's security architecture from v0.6.9 through v1.0, where all 20 risks are implemented as compiled language declarations.

Special thanks to the early adopters and testers who filed issues, suggested features, and pushed Neam beyond what I originally imagined.

How to Report Issues and Contribute #

The Neam project is hosted on GitHub. To report bugs, request features, or contribute:

• Get Started with Neam: https://neam.lovable.app/ -- install, explore, and start building with Neam.
• Language Repository: https://github.com/neam-lang/Neam
• Issue Tracker: Use GitHub Issues for bug reports and feature requests.
• Discussions: Use GitHub Discussions for questions, ideas, and community conversation.

When filing a bug report, please include:

1. Your operating system and version
2. Your compiler version (g++ --version or clang++ --version)
3. Your CMake version (cmake --version)
4. The .neam source file that reproduces the issue (or a minimal example)
5. The complete error output

Contributions to both the language and this book are welcome. The contribution workflow follows GitHub Flow: fork, create a feature branch, write tests alongside your implementation, and open a pull request against main. See CONTRIBUTING.md in the Neam repository for the full development workflow and code style guidelines.