<div align="center">
    
<img width="3200" height="1344" alt="MapanareDevTo" src="https://github.com/user-attachments/assets/99b80387-afd9-4b07-beb8-59a8f63f7ac7" />

# Mapanare

**The AI-native programming language.**

*Agents. Signals. Streams. Tensors. First-class, not frameworks.*

Mapanare compiles to Python (transpiler) and native binaries (LLVM), with a self-hosted compiler in progress.

<br>

![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white)
![LLVM](https://img.shields.io/badge/LLVM-Native_Backend-262D3A?style=for-the-badge&logo=llvm&logoColor=white)
![Platform](https://img.shields.io/badge/Linux%20%7C%20macOS%20%7C%20Windows-grey?style=for-the-badge)

[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg?style=flat-square)](CHANGELOG.md)
[![Tests](https://img.shields.io/badge/tests-~60_files-brightgreen.svg?style=flat-square)]()
[![CI](https://github.com/Mapanare-Research/Mapanare/actions/workflows/ci.yml/badge.svg)](https://github.com/Mapanare-Research/Mapanare/actions/workflows/ci.yml)

<br>

[Why Mapanare?](#why-mapanare) · [Install](#install) · [The Language](#the-language) · [Benchmarks](#benchmarks) · [CLI](#cli) · [Architecture](#compiler-architecture) · [Contributing](#contributing)

</div>

---

## Why Mapanare?

Every mainstream language treats agents, signals, streams, and tensors as library constructs — one abstraction layer away from the compiler. That means no compile-time data-flow verification, no static tensor shape checking, and no language-level guarantees about message passing.

Mapanare makes these primitives **part of the language**:

- **Agents** are as natural as functions — declare, spawn, send, receive, all with dedicated syntax checked by the compiler
- **Signals** replace callback hell with automatic dependency tracking
- **Streams** compose with `|>` the way you think about data, with operator fusion built in
- **Tensors** get compile-time shape validation — shape errors caught before runtime
- **No OOP** — structs, enums, and pattern matching instead of class hierarchies

Read the full [manifesto](docs/manifesto.md).

---

## Install

### Linux / macOS

```bash
curl -fsSL https://raw.githubusercontent.com/Mapanare-Research/Mapanare/main/install.sh | bash
```

### Windows (PowerShell)

```powershell
irm https://raw.githubusercontent.com/Mapanare-Research/Mapanare/main/install.ps1 | iex
```

### Manual Download

Download the latest binary from [Releases](https://github.com/Mapanare-Research/Mapanare/releases).

| Platform | Archive |
|----------|---------|
| Linux (x64) | `mapanare-linux-x64.tar.gz` |
| macOS (Apple Silicon) | `mapanare-mac-arm64.tar.gz` |
| Windows (x64) | `mapanare-win-x64.zip` |

Extract and add `mapanare` to your PATH, then verify:

```bash
mapanare --version
```

---

## The Language

### Agents

Concurrent actors with typed channels, lifecycle management, and supervision.

```mn
agent Greeter {
    input name: String
    output greeting: String

    fn handle(name: String) -> String {
        return "Hello, " + name + "!"
    }
}

fn main() {
    let greeter = spawn Greeter()
    greeter.name <- "World"
    let result = sync greeter.greeting
    print(result)
}
```

### Signals

Reactive state with automatic dependency tracking and change propagation.

```mn
let mut count = signal(0)
let doubled = computed { count * 2 }

count.set(5)
print(doubled)  // 10

batch {
    count.set(10)
    // notifications coalesced until batch ends
}
```

### Streams

Async pipelines with backpressure, fusion, and composable operators.

```mn
let data = stream([1, 2, 3, 4, 5])
let result = data
    |> filter(fn(x) { x > 2 })
    |> map(fn(x) { x * 10 })
    |> fold(0, fn(acc, x) { acc + x })
```

Adjacent `map`/`filter` operators fuse into a single pass automatically.

### Pipes

Declarative multi-agent composition with type-checked data flow.

```mn
pipe ClassifyText {
    Tokenizer |> Classifier
}
```

### Tensors

N-dimensional arrays with compile-time shape validation.

```mn
let a: Tensor<Float>[3, 3] = identity(3)
let b: Tensor<Float>[3, 4] = zeros(3, 4)
let c = a @ b  // shape [3, 4] — inner dimensions checked at compile time
```

### Type System

Static typing with inference, generics, pattern matching, and error propagation.

```mn
fn divide(a: Float, b: Float) -> Result<Float, String> {
    if b == 0.0 {
        return Err("division by zero")
    }
    return Ok(a / b)
}

let value = divide(10.0, 3.0)?
```

### No OOP

No classes, no inheritance, no virtual methods. Structs, enums, and pattern matching instead.

```mn
enum Shape {
    Circle(Float),
    Rect(Float, Float),
}

fn area(s: Shape) -> Float {
    match s {
        Circle(r) => 3.14159 * r * r,
        Rect(w, h) => w * h,
    }
}
```

---

## Benchmarks

Cross-language benchmarks comparing Mapanare against Python, Go, and Rust. Each benchmark runs 3 times; median wall time reported. Run `python -m test_vs.run_benchmarks` to reproduce.

### Performance (wall time, lower is better)

| Benchmark | Mapanare | MN Native (LLVM) | Python | Go | Rust | vs Python |
|-----------|----------|-------------------|--------|----|------|-----------|
| Fibonacci (recursive, n=35) | 1.2104s | **0.0448s** | 1.1885s | 0.0341s | 0.0211s | 26.5x (native) |
| Message Passing (10K msgs) | 0.9989s | — | 1.0978s | 0.0025s | 0.0203s | 1.1x |
| Stream Pipeline (1M items) | 1.1141s | **0.0165s** | 1.0342s | 0.0005s | 0.0001s | 62.8x (native) |
| Matrix Multiply (100x100) | 0.1769s | **0.0199s** | 0.4556s | 0.0005s | 0.0009s | 22.9x (native) |

### Expressiveness (lines of code, lower is better)

| Benchmark | Mapanare | Python | Go | Rust |
|-----------|----------|--------|----|------|
| Fibonacci (recursive, n=35) | **10** | 12 | 18 | 23 |
| Message Passing (10K msgs) | **18** | 28 | 27 | 32 |
| Stream Pipeline (1M items) | **10** | 17 | 18 | 20 |
| Matrix Multiply (100x100) | **14** | 21 | 37 | 33 |

> **Key takeaway:** Mapanare's interpreted backend matches Python speed (it transpiles to Python), but the LLVM native backend delivers **22–63x** speedups over Python. Mapanare programs are consistently the shortest across all benchmarks.

### Stream Pipelines (1M items, runtime microbenchmarks)

| Pipeline | Throughput | Avg Latency |
|----------|-----------|-------------|
| `fold_sum` | **10.3M items/sec** | 0.10 us |
| `take(1000)` | **6.3M items/sec** | 0.16 us |
| `filter` | **4.2M items/sec** | 0.24 us |
| `map` | **4.2M items/sec** | 0.24 us |
| `map \| filter` | **2.6M items/sec** | 0.39 us |
| `chained_maps(5)` | **1.7M items/sec** | 0.60 us |
| `chained_maps(10)` | **1.2M items/sec** | 0.80 us |

```bash
make benchmark                       # run all benchmarks
python -m test_vs.run_benchmarks     # cross-language comparison suite
```

---

## CLI

```
mapanare run <file>           Compile and run
mapanare build <file>         Compile to native binary via LLVM
mapanare jit <file>           JIT-compile and run natively
mapanare check <file>         Type-check only
mapanare compile <file>       Transpile to Python
mapanare emit-llvm <file>     Emit LLVM IR
mapanare fmt <file>           Format source code
mapanare init [path]          Initialize a new project
mapanare install <pkg>        Install a package (git-based)
mapanare targets              List supported compilation targets
```

Options: `-O0` to `-O3` optimization levels, `-o <path>` output file, `--target <triple>` cross-compilation target.

---

## Compiler Architecture

```
.mn source → Lexer → Parser → AST → Semantic Analysis → Optimizer → Emit
                                                                      ↓
                                                               Python | LLVM IR
                                                                      ↓
                                                       Interpreter | Native Binary
```

| Stage | Details |
|-------|---------|
| **Lexer** | Lark-based tokenizer (18 keywords, 29 operators) |
| **Parser** | LALR with precedence climbing |
| **Semantic** | Type checking, scope analysis, builtins registry |
| **Optimizer** | Constant folding, dead code elimination, agent inlining, stream fusion (`-O0` to `-O3`) |
| **Emit Python** | Agents map to asyncio, signals to reactive containers, streams to async generators |
| **Emit LLVM** | Full IR generation via llvmlite with cross-compilation targets |

---

## Runtime

| Primitive | Capabilities |
|-----------|-------------|
| **Agents** | Lifecycle management, typed channels, supervision (restart/stop), backpressure, metrics |
| **Signals** | Dependency graph with automatic recomputation, batched updates, change streams |
| **Streams** | Async iterables with fusion, hot/cold semantics, backpressure strategies (buffer, drop, error) |
| **Result/Option** | `Ok`/`Err`/`Some`/`None` with `?` operator support |
| **Native C** | Lock-free SPSC ring buffers, per-core thread pool, atomic backpressure counters |

---

## Standard Library

| Module | Provides |
|--------|----------|
| `io` | File I/O agents, read/write helpers |
| `http` | HTTP client/server agents, get/post |
| `time` | Timers, intervals, debounce, throttle, stopwatch |
| `math` | Constants, trig, statistics, linear algebra helpers |
| `text` | Case conversion, search, split/join, slug, padding |
| `log` | Structured logging with agent context, JSON/text output |
| `pkg` | Project manifests, git-based package install, lock files |

---

## GPU & Tensors

- Device detection: CUDA, Metal, Vulkan
- `@gpu` / `@cpu` annotations for kernel dispatch
- Model loading: `.mnw` (native format), ONNX, safetensors, HuggingFace

---

## Editor Support

### VS Code

Extension in `editors/vscode/` with:

- Syntax highlighting for `.mn` files
- Code snippets (agent, pipe, fn, signal, stream)
- LSP integration: hover, go-to-definition, find-references, diagnostics, autocomplete

Install the LSP server: `mapanare-lsp`

---

## Self-Hosted Compiler

The compiler is being rewritten in Mapanare itself (`mapanare/self/`):

- `lexer.mn` — Tokenizer
- `parser.mn` — Recursive descent parser
- `ast.mn` — 31 AST definitions
- `semantic.mn` — Type checker
- `emit_llvm.mn` — LLVM IR emitter

Bootstrap strategy: Python compiler (Stage 0) compiles self-hosted `.mn` sources (Stage 1), which must reproduce identical output (Stage 2 fixed-point verification).

---

## Project Structure

```
mapanare/
├── mapanare/              Compiler (lexer, parser, semantic, emit, optimizer, jit)
│   ├── self/              Self-hosted .mn compiler sources
│   └── lsp/               Language Server Protocol
├── runtime/               Runtime (agents, signals, streams, result types)
│   └── native/            Native C runtime (thread pool, ring buffers)
├── stdlib/                Standard library (io, http, time, math, text, log, pkg)
├── bootstrap/             Frozen Python compiler for bootstrapping
├── editors/vscode/        VS Code extension
├── tests/                 Test suite (~60 test files)
├── benchmarks/            Performance benchmarks
├── docs/                  Documentation
│   ├── rfcs/              Language change proposals
│   ├── SPEC.md            Language specification
│   └── ROADMAP.md         Development roadmap
├── packaging/             Installers and build specs
│   ├── install.sh         Linux/macOS installer
│   ├── install.ps1        Windows installer
│   └── mapanare.spec      PyInstaller spec for binary builds

```

---

## Development

```bash
git clone https://github.com/Mapanare-Research/Mapanare.git
cd Mapanare
make install        # pip install -e ".[dev]"
make test           # pytest tests/ -v
make lint           # ruff, black, mypy
make fmt            # auto-format
make benchmark      # run benchmarks
```

Requires Python 3.11+.

---

## Roadmap

| Phase | Name | Status |
|-------|------|--------|
| 1 | Foundation | In Progress |
| 2 | Transpiler | Planned |
| 3 | Runtime | Planned |
| 4 | LLVM | Planned |
| 5 | Tensor | Planned |
| 6 | Self-Hosting | Planned |
| 7 | Ecosystem | Planned |

See [ROADMAP.md](docs/ROADMAP.md) for the full breakdown.

---

## The Story Behind Mapanare

Mapanare wasn't born from a weekend tutorial or a trending tweet. It comes from 15 years of writing code across more languages and paradigms than most developers will ever touch.

It started at 14, self-taught, building a calculator in ActionScript 2 for math class in Venezuela — no formal training, no English, no Stack Overflow in Spanish. From Flash games inspired by the Flappy Bird era, to ColdFusion, PHP, and eventually Python — each language taught something, and each one eventually showed its limits.

Python was the one that stuck the longest. But after years of building with it, the cracks became impossible to ignore — especially for the kind of AI-native, concurrent, data-heavy work that defines modern software. Mapanare is the answer to a question that's been forming for over a decade: *what would a language look like if it was designed for how we actually build software today?*

This is not another language from someone who learned to code yesterday. It's the product of real experience, real frustration, and a genuine vision for what programming languages should be in the age of AI.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Language changes require an [RFC](docs/rfcs/).

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

<div align="center">

**Mapanare** — The language AI deserves.

[Report Bug](https://github.com/Mapanare-Research/Mapanare/issues) · [Request Feature](https://github.com/Mapanare-Research/Mapanare/issues) · [Spec](docs/SPEC.md) · [Roadmap](docs/ROADMAP.md)

Made with care by [Juan Denis](https://juandenis.com)

</div>
