# Mapanare v0.3.0

> Mapanare is an AI-native compiled programming language where agents, signals, streams, and tensors are first-class language primitives — not libraries.

## Overview

Mapanare compiles to Python (transpiler) and native binaries via LLVM. It features a self-hosted compiler written in Mapanare itself.

Website: https://mapanare.dev
GitHub: https://github.com/Mapanare-Research/Mapanare
Discord: https://discord.gg/5hpGBm3WXf
License: MIT

## Key Features

- **Agents**: Concurrent actors with typed input/output channels, lifecycle management, supervision, and backpressure. Native LLVM backend uses OS threads with lock-free SPSC ring buffers. Keywords: `agent`, `spawn`, `sync`, `<-`.
- **Signals**: Reactive state with automatic dependency tracking and computed values. Keywords: `signal`, `computed`, `batch`.
- **Streams**: Async pipelines with the `|>` pipe operator. Adjacent map/filter operations fuse automatically into a single pass.
- **Tensors**: N-dimensional arrays with compile-time shape validation. The `@` operator performs matrix multiplication with shape checking at compile time.
- **Traits**: Generic abstractions over types with trait bounds on generics. Builtin traits: `Display`, `Eq`, `Ord`, `Hash`. Keywords: `trait`, `impl Trait for Type`.
- **Modules**: File-based module resolution with `pub` visibility enforcement and circular import detection. Keywords: `import`, `pub`, `export`.
- **No OOP**: No classes, no inheritance. Structs, enums, and pattern matching instead.
- **Dual compilation**: Transpile to Python for ecosystem access, or compile to native binaries via LLVM (22-63x faster than Python).
- **Type system**: Static typing with inference, generics, trait bounds, Option<T>, Result<T,E>, and `?` error propagation.
- **Arena memory**: Arena-based allocation for the LLVM backend with tag-bit heap string detection. No memory leaks for function-local temporaries.

## Installation

```bash
pip install mapanare
# or
curl -fsSL https://mapanare.dev/install | bash
```

## Quick Example

```mn
agent Classifier {
    input text: String
    output label: String

    fn handle(text: String) -> String {
        return "positive"
    }
}

fn main() {
    let cls = spawn Classifier()
    cls.text <- "Mapanare is fast"
    let result = sync cls.label
    print(result)
}
```

## Traits Example

```mn
trait Display {
    fn to_string(self) -> String
}

impl Display for Point {
    fn to_string(self) -> String {
        return str(self.x) + ", " + str(self.y)
    }
}

fn print_all<T: Display>(items: List<T>) {
    for item in items {
        println(item.to_string())
    }
}
```

## CLI Commands

- `mapanare run <file>` — Compile and run
- `mapanare build <file>` — Compile to native binary via LLVM
- `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` — Create new project scaffold

## Primitive Types

Int, Float, Bool, String, Char, Void, Option<T>, Result<T,E>, List<T>, Map<K,V>, Tensor<T>, Signal<T>, Stream<T>, Channel<T>

## Documentation Pages

- Getting Started: https://mapanare.dev/docs/getting-started
- Variables & Mutability: https://mapanare.dev/docs/variables
- Functions & Lambdas: https://mapanare.dev/docs/functions
- Control Flow: https://mapanare.dev/docs/control-flow
- Structs & Enums: https://mapanare.dev/docs/structs-enums
- Type System: https://mapanare.dev/docs/type-system
- Error Handling: https://mapanare.dev/docs/error-handling
- Operators: https://mapanare.dev/docs/operators
- Modules & Imports: https://mapanare.dev/docs/modules
- Traits: https://mapanare.dev/docs/traits
- Decorators: https://mapanare.dev/docs/decorators
- Agents: https://mapanare.dev/docs/agents
- Signals: https://mapanare.dev/docs/signals
- Streams: https://mapanare.dev/docs/streams
- Tensors: https://mapanare.dev/docs/tensors
- Pipes: https://mapanare.dev/docs/pipes
- CLI Reference: https://mapanare.dev/docs/cli
- Standard Library: https://mapanare.dev/docs/standard-library
- Benchmarks: https://mapanare.dev/benchmarks

## Performance

| Benchmark | MN (Native) | Python | Go | Rust | vs Python |
|-----------|-------------|--------|----|------|-----------|
| Fibonacci (n=35) | 0.045s | 1.189s | 0.034s | 0.021s | 26.5x |
| Message Passing (10K) | — | 1.098s | 0.003s | 0.020s | 1.1x (transpiled) |
| Stream Pipeline (1M) | 0.017s | 1.034s | 0.001s | 0.0001s | 62.8x |
| Matrix Multiply (100x100) | 0.020s | 0.456s | 0.001s | 0.001s | 22.9x |

## What's New in v0.3.0

- Traits system with `Display`, `Eq`, `Ord`, `Hash` builtin traits and trait bounds on generics
- File-based module resolution with `pub` visibility and circular import detection
- Native LLVM agents with OS threads, lock-free SPSC ring buffers, and semaphore scheduling
- Arena-based memory management eliminating leaks for the LLVM backend
- Formal type representation with 25-kind TypeKind enum
- 1,968 tests (up from ~1,400 in v0.2.0)

## Full Documentation

For complete documentation with all code examples, see: https://mapanare.dev/llms-full.txt

## Contact

Created by Juan Denis — https://juandenis.com