Skip to content

README_EN.md

Latest commit

 

History

History
260 lines (198 loc) · 10.3 KB

README_EN.md

File metadata and controls

260 lines (198 loc) · 10.3 KB
Nexa Logo

Nexa Language

The First Harness Native Agent Language. Write flows, not glue code.

DOI License Version Python Tests

中文版 | English

📚 Docs: 中文 | English

⚡ What is Nexa?

Nexa is the first Harness Native Agent Language — a programming language designed specifically for Large Language Models (LLMs) and Agentic Systems, where agent safety is a language property, not a runtime convention.

Modern AI application development is plagued by massive Prompt concatenation, bloated JSON parsing suites, unreliable regex belts, and complex frameworks. Nexa elevates high-level intent routing, multi-agent concurrent assembly, pipeline streaming, and tool execution sandboxing as first-class syntax citizens. Through the underlying Transpiler, it transforms into stable, reliable Python Runtime, allowing you to define the most hardcore LLM computation graphs (DAGs) with the most elegant syntax.

🔥 v2.1: Production Hardening for Nexa Code

Nexa v2.1 adds agent-level properties parsed by the compiler and enforced at runtime — not framework configurations, but language primitives:

Property Type Default Description
stream true / false false Stream output token-by-token
output_format "json" / "" "" Force OpenAI response_format JSON
output_schema {...} — JSON Schema; compiler auto-generates Pydantic
max_tool_calls int 10 Max tool call rounds per request
tool_call_strategy "auto" / "required" / "none" "auto" Control tool call behavior 
agent Coder {
    prompt: "You are a coding assistant.",
    stream: true,
    max_tool_calls: 5,
    tool_call_strategy: "auto"
}

Backward compatible: all v1.x and v2.0 code runs unchanged.

🔥 v2.0: Harness Native Runtime

Nexa v2.0 introduces the Harness Native Runtime — transforming the Harness six-tuple H=(E,T,C,S,L,V) from compile-time validation into runtime first-class primitives:

Dimension Primitive Runtime Component Tests
E (Execution) autoloop HarnessKernel + AutoLoopConfig 52
T (Tool) @tool ToolRegistry + ToolSchema 53
C (Context) with_context ContextManager + importance_weighted 52
S (State) snapshot/restore StateStore + fork/merge 45
L (Lifecycle) before_step/after_step/reflect LifecycleHookManager 53
V (Verify) verify ... satisfies EvaluationInterface + LLMRouter 59
Actor spawn/pass/await ActorSystem 18
WASM sandbox integration WASM Sandbox + full harness 15

Total 296 new tests, plus v1.x 1500+ tests = 1935+ tests.

v2.0 Examples

12 complete examples covering all Harness dimensions:

examples/v2.0/
  01_autoloop.nx          — E-dimension: autonomous ReAct loop
  02_with_context.nx      — C-dimension: context management
  03_try_agent.nx         — E+L: fault-tolerant execution + reflection
  04_tool_annotation.nx   — T-dimension: zero-cost tool binding
  05_snapshot_restore.nx  — S-dimension: state snapshots
  06_fork_merge.nx        — S-dimension: branch exploration
  07_verify.nx            — V-dimension: output verification
  08_reflect.nx           — L-dimension: reflection injection
  09_lifecycle_hooks.nx   — L-dimension: lifecycle interception
  10_actor_system.nx      — Actor: multi-agent orchestration
  11_well_harnessed.nx    — full-dimension example
  12_harness_cli.nx       — Claude Code-like CLI framework

🔥 v1.1-v1.3.7 Feature Overview

Nexa released 16 core features from v1.1.0 to v1.3.7, covering 4 priority tiers (P0-P3), with 1500+ tests total.

🏆 P0: Core Differentiation Features

Version Feature Tests Highlights
v1.1.0 Intent-Driven Development (IDD) 104 .nxintent files + IAL term rewriting engine + @implements annotations
v1.2.0 Design by Contract (DbC) 47 requires/ensures/invariant + ContractViolation cross-module integration
v1.3.0 Agent-Native Tooling 41 nexa inspect/validate/lint CLI commands

📦 P1: Essential Features

Version Feature Tests Highlights
v1.3.1 Gradual Type System 79 Int/String/Bool/List[T]/Option[T]/Result[T,E] + 3-level mode
v1.3.2 Error Propagation 82 ? operator + otherwise + NexaResult/NexaOption
v1.3.3 Background Job System 73 job DSL + priority queues + cron + backoff strategies
v1.3.4 Built-In HTTP Server 94 server DSL + CORS/CSP + route guards + hot reload
v1.3.5 Database Integration 79+5 db DSL + SQLite/PostgreSQL + Agent memory API

🎯 P2: Advanced Features

Version Feature Tests Highlights
v1.3.6 Auth & OAuth 79+5 3-layer auth (API Key + JWT + OAuth PKCE)
v1.3.6 Structured Concurrency 172 spawn/parallel/race/channel + 18 API functions
v1.3.6 KV Store 81 SQLite backend + TTL + Agent semantic queries
v1.3.6 Template System 209 template"""...""" + 30+ filters + Agent templates

✨ P3: Language Expressiveness

Version Feature Tests Highlights
v1.3.7 Pipe Operator ` >` 84
v1.3.7 defer Statement 84 LIFO cleanup on scope exit
v1.3.7 Null Coalescing ?? 84 expr ?? fallback safe fallback
v1.3.7 String Interpolation #{} 100 Ruby-style string interpolation
v1.3.7 Pattern Matching 91 7 pattern types + match/let/for destructuring
v1.3.7 ADT (Struct/Enum/Trait) 100 Algebraic data types + handle-as-dict pattern

🦀 Rust AVM Foundation (v1.0-alpha)

Nexa v1.0-alpha introduced the revolutionary Agent Virtual Machine (AVM) — a high-performance, securely isolated agent execution engine written in Rust:

  • High-performance bytecode interpreter — Natively executes compiled Nexa bytecode
  • WASM Security Sandbox — wasmtime integration + 4-level permission model
  • Smart Scheduler — DAG topological sort + automatic dependency resolution
  • Vector Virtual Memory Paging — LRU/LFU/Hybrid eviction + semantic relevance loading

🚀 Quick Start

1. Global Installation

git clone https://github.com/ouyangyipeng/Nexa.git
cd Nexa
pip install -e .

2. Agent Tool Installation 🤖

If you're using AI Agent tools (Claude Code, Cursor, Copilot, etc.), simply enter:

Follow the instructions at https://github.com/ouyangyipeng/Nexa/AGENT_LEARN to install and try this language

Your Agent will automatically access AGENT_LEARN/ to complete installation and learn Nexa syntax.

Agent-specific docs:

3. Execute and Test Workflow

# Run flow
python -m src.cli run examples/01_hello_world.nx

# Semantic assertion tests
python -m src.cli test examples/12_v0.9_features.nx

# Audit generated Python code stack
python -m src.cli build examples/01_hello_world.nx

# Agent-Native tooling (v1.3+)
python -m src.cli inspect examples/01_hello_world.nx
python -m src.cli validate examples/01_hello_world.nx
python -m src.cli lint examples/01_hello_world.nx

📖 Syntax Examples

Agent Declaration + Pipeline

agent ChatBot {
    role: "Helpful Assistant",
    model: "gpt-4o-mini",
    prompt: "Answer user questions concisely"
}

flow main {
    result = user_input |> ChatBot |> format_output;
}

Design by Contract (v1.2)

agent SecureBot {
    requires: input != None and input.length < 1000
    ensures: "response is helpful and accurate"
}

Type Annotations + Error Propagation (v1.3.1-v1.3.2)

let count: Int = parse(input) ?
let result = risky_operation() otherwise 0

HTTP Server (v1.3.4)

server 8080 {
    cors { origins: ["*"], methods: ["GET", "POST"] }
    route GET "/chat" => ChatBot
    route POST "/analyze" => Analyzer
}

Pattern Matching + ADT (v1.3.7)

enum Option { Some(value), None }
struct Point { x: Int, y: Int }

match result {
    Option::Some(answer) => answer
    Option::None => "no response"
}

✅ Documentation & Test Validation

  • Python Tests: 1935 tests passed (v1.x 16 features + v2.0 Harness Runtime + v2.1 Agent Properties)
  • Rust AVM: 0 errors, 0 warnings — cargo check clean build
  • v2.0+2.1 Examples: 16/16 all compile with nexa build --harness=warn

📖 Documentation

Built with ❤️ by the Nexa Genesis Team for the next era of automation.