Crate lmm

Expand description

§👁️ LMM 🦀

LMM (Large Mathematical Model) is a pure‑Rust framework that models higher‑dimensional reality through symbolic mathematics and physics simulation; Inspired by the Pharaonic model of intelligence: compress the world into durable, universal equations. No training. No GPU. No API key.

🐧 Linux `(Recommended)`	🪟 Windows	🐳 Docker

Download `lmm` binary	Download `lmm.exe` binary	`docker pull wiseaidev/lmm`
`cargo install lmm --features rust-binary`	`cargo install lmm --features rust-binary`	`docker run -it wiseaidev/lmm`
`lmm` ← launches CLI	`lmm` ← launches CLI	Read DOCKER.md

§🎬 Demo

The following demonstrates the symbolic prediction engine generating coherent English sentences powered entirely by deterministic mathematical equations and structural Subject-Verb-Object grammar; No neural networks, no statistical models. The engine supports a full suite of CLI subcommands including predict, summarize, sentence, paragraph, essay, and ask, enabling multi-paragraph construction driven entirely by mathematics.

§🧠 What Does LMM Provide?

LMM bridges multimodal perception and actionable scientific discovery through five tightly integrated layers:

Layer	Modules	Purpose
Perception	`perception.rs`, `tensor.rs`	Raw bytes → normalised tensors
Symbolic	`equation.rs`, `symbolic.rs`, `discovery.rs`	GP symbolic regression, differentiation, simplification
Physics	`physics.rs`, `simulation.rs`	ODE models + Euler / RK4 / RK45 / leapfrog integrators
Causal	`causal.rs`	SCM graphs, do-calculus interventions, counterfactuals
Cognition	`consciousness.rs`, `world.rs`, `operator.rs`	Full perceive → encode → predict → act loop

§⚙️ Architecture

flowchart TD
    A["Raw Input\n(bytes / sensors)"]
    B["MultiModalPerception\n → Tensor"]
    C["Consciousness Loop\nperceive → encode → predict\nevaluate → plan (lookahead)"]
    D["WorldModel\n(RK4 physics)"]
    E["SymbolicRegression\n(GP equation search)"]
    F["CausalGraph\nintervention / counterfactual"]
    G["Expression AST\ndifferentiate / simplify"]

    A --> B --> C
    C --> D
    C --> E
    E --> G
    G --> F
    D --> F

§🔬 Key Capabilities

🧬 Genetic Programming: population-based symbolic regression with template seeding (linear, quadratic, periodic) and variable-enforcement guards.
📐 Symbolic Calculus: automatic differentiation (chain rule, product rule, trig) and constant-folding simplification.
🌀 Physics Suite: Harmonic Oscillator, Lorenz Attractor, Pendulum, SIR Epidemic, N-body Gravity; All implement Simulatable.
🔢 Field Calculus: N-D gradient, Laplacian, divergence, and 3-D curl via central differences.
🔗 Causal Reasoning: structural causal models, do(X=v) interventions, and counterfactual queries.
🧩 Neural Operators: circular convolution with SGD kernel learning and Fourier spectral operators.
🔤 Text ↔ Equation: losslessly encode any text string into a symbolic equation and recover it exactly via integer residuals.
🔮 Symbolic Prediction: equation-native text continuation using sliding-window GP regression and vocabulary anchoring.
🎲 Stochastic Enhancement: synonym-bank word replacement (--stochastic) delivers unique output each run while preserving mathematical sentence structure.
🎨 Spectral Image Synthesis: generate procedural PPM images from a text prompt by hashing it into Fourier wave components.

§📦 Installation

The lmm crate ships the following Cargo features:

Feature	Description
`rust-binary`	Enables the standalone `lmm` terminal CLI executable
`cli`	Core CLI scaffolding (subsets of `rust-binary`)
`net`	Internet-aware `ask` command via DuckDuckGo search
`python`	Python extension module via `pyo3` / maturin
`node`	Node.js native add-on via `napi-derive`

§🦀 Rust

The lmm library is available on crates.io. For the complete API reference, installation guide, and worked examples, see the Rust usage guide.

§💻 Command-Line Interface

The lmm binary supports 15 subcommands spanning simulation, discovery, encoding, prediction, summarisation, and rich text generation: all powered by pure equations.

For the full option reference and usage examples, see the CLI documentation or run lmm --help after installing with cargo install lmm --features rust-binary.

§🐍 Python

The Python bindings are published to PyPI as lmm-rs and are installed with pip install lmm-rs. Built with maturin, the package ships pre-compiled wheels for major CPython versions and runs a fully embedded Tokio runtime; no asyncio required.

For installation instructions, configuration options, and full method signatures, see the Python usage guide.

§🟩 Node.js

The Node.js bindings are published to npm as @wiseaidev/lmm and are installed with npm install @wiseaidev/lmm. Built with napi-rs, the package ships a pre-compiled .node add-on with TypeScript type definitions.

For installation instructions, type definitions, and examples, see the Node.js usage guide.

§🌐 WebAssembly (WASM)

LMM natively targets wasm32-unknown-unknown. Because reqwest switches to the browser fetch API automatically, you can deploy LMM inside Rust frontend frameworks such as Yew, Dioxus, and Leptos without any additional glue code.

For CORS considerations, build steps, and usage details, see the WASM usage guide.

§🤖 Agent Framework

The lmm-agent crate extends LMM with a fully autonomous, equation-based agent layer; no LLM, no API key, no training data.

Document	Description
AGENT.md	Architecture, quick-start, types, and async API reference
DERIVE.md	`#[derive(Auto)]` macro: generated traits and field contract
lmm-agent README	Crate-level API reference, builder, and example
lmm-derive README	Macro crate details and field rules

§📰 Publications & Research

The architecture, formal mathematics, and paradigm are fully documented in the official whitepaper: Read the Whitepaper (PDF).

§Blog Posts

LLMs are Useful. LMMs will Break Reality: the original post that started this project.
Training Is An Evil Concept. LMMs Eliminates It Altogether: ethical, architectural, and data advantages of training-free models.

§📝 Citation

If you use LMM in your research, please cite our whitepaper:

@article{harmouch2026lmm,
  author  = {Mahmoud Harmouch},
  title   = {Mathematics Is All You Need: Training-Free Language Generation via
             Symbolic Regression and Stochastic Determinism},
  year    = {2026},
  url     = {https://github.com/wiseaidotdev/lmm}
}

§🤝 Contributing

Contributions are welcome! Feel free to open issues or pull requests on GitHub.

§📄 License

Licensed under the MIT License.

§⭐ Star Us

If you use or enjoy LMM, please leave us a star on GitHub! It helps others discover the project and keeps the momentum going ☕.

§LMM Agent Framework 🤖

The lmm-agent crate provides an equation-based, training-free autonomous agent framework built on top of the lmm core engine. Agents reason through symbolic mathematics, not neural networks: no GPU, no API key, no token quotas.

§📦 Installation

# Cargo.toml
[dependencies]
lmm-agent = "0.1.2"

§🏗️ Core Architecture

flowchart TD
    U["Custom Struct\n#[derive(Auto)]"]
    L["LmmAgent\n(core state)"]
    E["Executor trait\n(your logic)"]
    O["AutoAgent\norchestrator"]
    G["TextPredictor\n(symbolic regression)"]
    S["DuckDuckGo search\n(optional enrichment)"]

    U -->|"delegates to"| L
    U -->|"implements"| E
    O -->|"runs pool of"| E
    L -->|"uses"| G
    L -->|"uses"| S

§🚀 Quick Start

use lmm_agent::prelude::*;
use async_trait::async_trait;

// Define your agent struct
// The `Auto` macro only requires one field: `agent: LmmAgent`
#[derive(Debug, Default, Auto)]
pub struct MyAgent {
    pub agent: LmmAgent,
}

// Implement only your task logic
#[async_trait]
impl Executor for MyAgent {
    async fn execute<'a>(
        &'a mut self,
        _tasks: &'a mut Task,
        _execute: bool, _browse: bool, _max_tries: u64,
    ) -> Result<()> {
        let prompt   = self.agent.behavior.clone();
        let response = self.generate(&prompt).await?;
        self.agent.add_message(Message::new("assistant", response));
        self.agent.update(Status::Completed);
        Ok(())
    }
}

// Run
#[tokio::main]
async fn main() {
    let agent = MyAgent::new(
        "Research Agent".into(),
        "Survey the Rust ecosystem.".into()
    );
    let _ = AutoAgent::default()
        .with(agents![agent]);
}

§🔧 LmmAgent Builder

use lmm_agent::agent::LmmAgent;
use lmm_agent::types::{Message, Planner, Goal};

let agent = LmmAgent::builder()
    .persona("My Agent")
    .behavior("Summarise Rust papers.")
    .memory(vec![Message::new("system", "You are an LMM agent.")])
    .planner(Planner {
        current_plan: vec![Goal {
            description: "Read paper list.".into(),
            priority: 1,
            completed: false,
        }],
    })
    .build();

§🧩 Key Types

Type	Purpose
`LmmAgent`	Core agent struct (memory, tools, planner, knowledge, etc.)
`LmmAgentBuilder`	Fluent builder for `LmmAgent`
`Message`	A chat message with `role` + `content`
`Status`	`Idle`, `Active`, `InUnitTesting`, `Completed`, `Thinking`
`Knowledge`	Map of fact keys to natural-language descriptions
`Planner`	Ordered list of `Goal`s with priorities and completion flags
`Profile`	Agent personality traits and behavioural script
`ContextManager`	Recent messages + current focus topics
`Task`	Work unit with description, scope, URLs, and code fields
`AutoAgent`	Orchestrator that runs a pool of agents

§📡 AsyncFunctions Trait

The Auto derive macro generates:

// All below methods are generated automatically
async fn generate(&mut self, prompt: &str) -> Result<String>;
async fn search(&self, query: &str)         -> Result<Vec<LiteSearchResult>>;
async fn think(&mut self, goal: &str)       -> Result<ThinkResult>;
async fn save_ltm(&mut self, msg: Message)  -> Result<()>;
async fn get_ltm(&self)                     -> Result<Vec<Message>>;
async fn ltm_context(&self)                 -> Result<String>;

§🔄 Agent Lifecycle

Idle → [execute() called] → Active → [task done] → Completed
                                   ↘ [think() called]   → Thinking → Completed
                                   ↘ [testing]          → InUnitTesting

§📎 Further Reading

§LMM Derive Macros ⚙️

The lmm-derive crate provides procedural macros that eliminate agent boilerplate. The primary export is #[derive(Auto)].

§📦 Installation

Pulled in automatically with lmm-agent. No manual dependency needed.

§🚀 The `Auto` Macro

§Required struct shape

use lmm_agent::prelude::*;
use async_trait::async_trait;

#[derive(Debug, Default, Auto)]
pub struct MyAgent {
    pub agent: LmmAgent,
}

#[async_trait]
impl Executor for MyAgent {
    async fn execute<'a>(
        &'a mut self, _tasks: &'a mut Task,
        _execute: bool, _browse: bool, _max_tries: u64,
    ) -> Result<()> { Ok(()) }
}

Auto inspects the required field agent: LmmAgent and generates three trait implementations automatically.

§Generated traits

§`Agent`

Delegates all methods to the inner LmmAgent field:

impl Agent for MyAgent {
    fn new(persona: Cow<'static, str>, behavior: Cow<'static, str>) -> Self {
         let mut s = Self::default();
         s.agent = LmmAgent::new(persona, behavior);
         s
    }
    fn persona(&self)     -> &str          { &self.agent.persona }
    fn behavior(&self)    -> &str          { &self.agent.behavior }
    fn status(&self)      -> &Status       { &self.agent.status }
    fn memory(&self)      -> &Vec<Message> { &self.agent.memory }
    fn memory_mut(&mut self) -> &mut Vec<Message> { &mut self.agent.memory }
}

§`Functions`

impl Functions for MyAgent {
    fn get_agent(&self)         -> &LmmAgent     { &self.agent }
    fn get_agent_mut(&mut self) -> &mut LmmAgent { &mut self.agent }
}

§`AsyncFunctions`

#[async_trait]
impl AsyncFunctions for MyAgent {
    async fn generate(&mut self, prompt: &str) -> Result<String>      { unimplemented!() }
    async fn search(&self, query: &str)         -> Result<Vec<LiteSearchResult>>   { unimplemented!() }
    async fn save_ltm(&mut self, msg: Message)  -> Result<()>         { unimplemented!() }
    async fn get_ltm(&self)                     -> Result<Vec<Message>>{ unimplemented!() }
    async fn ltm_context(&self)                 -> Result<String>     { unimplemented!() }
}

§Additional fields

Fields beyond the five required ones are ignored by Auto. You can freely add domain-specific data:

use lmm_agent::prelude::*;
use std::collections::HashMap;

#[derive(Debug, Default, Auto)]
pub struct DataAgent {
    pub agent:     LmmAgent,
    // custom fields, ignored by the macro
    pub db_url:    String,
    pub cache:     HashMap<String, String>,
}

#[async_trait]
impl Executor for DataAgent {
    async fn execute<'a>(
        &'a mut self, _tasks: &'a mut Task,
        _execute: bool, _browse: bool, _max_tries: u64,
    ) -> Result<()> { Ok(()) }
}

§⚠️ Field Name Contract

Field	Type	Must be named
`agent`	`LmmAgent`	exactly `agent`

Compile errors will occur if the agent field is missing or misnamed.

§📄 License

Licensed under the MIT License.

§LMM Rust Documentation 🦀

The lmm library is a pure-Rust symbolic intelligence framework available on crates.io. It requires Rust 1.86+ and exposes the full engine as a library crate with no mandatory runtime dependencies.

§📦 Installation

Add this to your Cargo.toml:

[dependencies]
lmm = "0.2.7"

§Cargo Features

Feature	Description
`rust-binary`	Enables the standalone `lmm` terminal CLI executable
`cli`	Core CLI scaffolding (subset of `rust-binary`)
`net`	Internet-aware `ask` command via DuckDuckGo Lite
`python`	Python extension module (pyo3 / maturin)
`node`	Node.js native add-on (napi-derive)

Enable all features for a fully featured local build:

cargo build --release --all-features

§📚 Library Usage

§Tensor arithmetic

use lmm::prelude::*;

let t = Tensor::new(vec![2, 3], vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]).unwrap();
println!("{}", t.norm());

§Symbolic expressions

use lmm::equation::Expression;
use std::collections::HashMap;

let expr: Expression = "(sin(x) * 2)".parse().unwrap();
let mut vars = HashMap::new();
vars.insert("x".to_string(), std::f64::consts::PI);
println!("{}", expr.evaluate(&vars).unwrap()); // ≈ 0

let deriv = expr.symbolic_diff("x").simplify();
println!("{}", deriv); // (cos(x) * 2)

§Causal graph + do-calculus

use lmm::causal::CausalGraph;

let mut g = CausalGraph::new();
g.add_node("x", Some(3.0));
g.add_node("y", None);
g.add_edge("x", "y", Some(2.0)).unwrap();
g.forward_pass().unwrap();

let y_cf = g.counterfactual("x", 10.0, "y").unwrap();
println!("do(x=10) → y = {y_cf}"); // 20.0

§Physics simulation

use lmm::prelude::*;

let osc = HarmonicOscillator::new(1.0, 1.0, 0.0).unwrap();
let sim = Simulator { step_size: 0.01 };
let state = sim.rk4_step(&osc, osc.state()).unwrap();
println!("{:?}", state.data);

§Text → Symbolic equation (lossless round-trip)

use lmm::encode::{encode_text, decode_message};

let enc = encode_text("The Pharaohs encoded reality.", 80, 4).unwrap();
let recovered = decode_message(&enc).unwrap();
assert_eq!(recovered, "The Pharaohs encoded reality.");

§Symbolic text continuation

use lmm::predict::TextPredictor;

let predictor = TextPredictor::new(20, 40, 3);
let result = predictor.predict_continuation("Wise AI built the first LMM", 80).unwrap();
println!("{}", result.continuation);

§Genetic programming symbolic regression

use lmm::prelude::*;

let mut sr = SymbolicRegression::new(3, 100);
let inputs: Vec<Vec<f64>> = (0..10).map(|i| vec![i as f64 * 0.5]).collect();
let targets: Vec<f64> = (0..10).map(|i| 2.0 * i as f64 * 0.5 + 1.0).collect();
let eq = sr.fit(&inputs, &targets).unwrap();
println!("Discovered: {eq}");

§Consciousness loop

use lmm::prelude::*;

let state = Tensor::zeros(vec![4]);
let mut brain = Consciousness::new(state, 3, 0.01);
let new_state = brain.tick(b"The Pharaohs built the pyramids").unwrap();
println!("{:?}", new_state);

§Spectral image generation

use lmm::prelude::*;

let params = ImagenParams {
    prompt: "ancient egypt mathematics".into(),
    width: 512, height: 512, components: 8,
    style: StyleMode::Plasma,
    palette_name: "warm".into(),
    output: "egypt.ppm".into(),
};
let path = render(&params).unwrap();
println!("Saved to {path}");

§🏗️ Architecture

flowchart TD
    A["Raw Input\n(bytes / sensors)"]
    B["MultiModalPerception\n → Tensor"]
    C["Consciousness Loop\nperceive → encode → predict\nevaluate → plan (lookahead)"]
    D["WorldModel\n(RK4 physics)"]
    E["SymbolicRegression\n(GP equation search)"]
    F["CausalGraph\nintervention / counterfactual"]
    G["Expression AST\ndifferentiate / simplify"]

    A --> B --> C
    C --> D
    C --> E
    E --> G
    G --> F
    D --> F

§📖 Core Types Reference

Type / Function	Description
`Tensor::new(shape, data)`	N-D row-major f64 tensor; `.norm()`, `.scale()`, `.add()`, `.dot()`
`Expression` (impl `FromStr`)	Symbolic AST; `.evaluate()`, `.symbolic_diff()`, `.simplify()`, `Display`
`CausalGraph`	SCM with `add_node`, `add_edge`, `forward_pass`, `intervene`, `counterfactual`
`HarmonicOscillator`, `LorenzSystem`, `Pendulum`, `SIRModel`	Physics models; all implement `Simulatable`
`Simulator`	`.euler_step_osc()`, `.rk4_step_osc()`, `.rk45_adaptive()`
`SymbolicRegression`	GP regressor; `.fit(inputs, targets) → String`
`TextPredictor`	`.predict_continuation(text, length) → PredictionResult`
`SentenceGenerator`	`.generate(seed) → String`
`ParagraphGenerator`	`.generate(seed) → String`
`TextSummarizer`	`.summarize(text) → String`
`StochasticEnhancer`	`.enhance(text) → String`
`Consciousness`	`.tick(bytes) → Vec<f64>`
`encode_text(text, iters, depth)`	Returns `EncodedText { expression, length, residuals }`
`decode_message(expr, length, residuals)`	Losslessly reconstructs original text
`mdl_score`, `compute_mse`, `r_squared`, `aic_score`, `bic_score`	Model-fit metrics
`render_image(prompt, w, h, style, palette, n, out)`	Spectral field synthesis → PPM file

§📄 License

Licensed under the MIT License.

§LMM WebAssembly Guide 🌐

LMM natively targets wasm32-unknown-unknown. Because the HTTP client (reqwest) automatically switches to the browser fetch API on WASM targets, you can deploy LMM inside Rust frontend frameworks without any additional glue code.

§Supported Frameworks

LMM WASM integration is actively used and tested with:

Yew: the most popular Rust / WASM frontend framework
Dioxus: cross-platform Rust UI framework
Leptos: fine-grained reactive framework

§📦 Adding to a WASM Project

Add lmm to your Cargo.toml with the appropriate feature set. Avoid enabling rust-binary, python, or node on WASM targets.

[dependencies]
lmm = { version = "0.2.7", default-features = false, features = ["wasm-net"] }

Build with Trunk (Yew / Leptos):

trunk serve

§🌍 CORS Considerations

DuckDuckGo’s endpoints set permissive CORS headers on most responses, but the behaviour can vary by endpoint and region. If you encounter CORS errors:

Use a server-side proxy to forward requests from your own origin.
Use the wt-wt (worldwide) region which tends to have the broadest CORS coverage.
Consider caching results server-side and serving them from your own API.

§🔬 Feature Flags for WASM

Feature	WASM-safe	Description
(default)	✅	Core symbolic engine (no networking)
`wasm-net`	✅	Enables `reqwest` fetch-based HTTP on WASM
`net`	❌	Native Tokio networking: incompatible with WASM
`rust-binary`	❌	CLI binary: incompatible with WASM
`python`	❌	pyo3 bindings: incompatible with WASM
`node`	❌	napi bindings: incompatible with WASM

§📖 Example: Yew Component

use lmm::prelude::*;
use yew::prelude::*;

#[function_component(PredictorDemo)]
fn predictor_demo() -> Html {
    let output = use_state(|| String::from("Click to generate..."));
    let onclick = {
        let output = output.clone();
        Callback::from(move |_| {
            let predictor = TextPredictor::new(20, 30, 3);
            if let Ok(result) = predictor.predict_continuation("Wise AI built the first LMM", 80) {
                output.set(result.continuation);
            }
        })
    };
    html! {
        <div>
            <button {onclick}>{ "Generate" }</button>
            <p>{ (*output).clone() }</p>
        </div>
    }
}

§📄 License

Licensed under the MIT License.

Modules§

app: Application Entry-Point
causal: Causal Graphs
compression: Information-Theoretic Compression Metrics
consciousness: Consciousness Perception-Action Loop
discovery: Symbolic Regression
encode: Text-Equation Encoding and Decoding
equation: Symbolic Expression Engine
error: Error Types
field: Tensor Field Operations
imagen: Procedural Image Generation (“Imagen”)
lexicon: System Dictionary Lexicon
models: Mathematical Models
operator: Neural and Fourier Operators
perception: Multi-Modal Perception
physics: Physics Models
predict: Symbolic Text Prediction
prelude: Prelude
reasoner: Compositional Symbolic Reasoner
simulation: ODE/PDE Numerical Integration
stochastic: Stochastic Text Enhancement
symbolic: Symbolic Expression Tools
tensor: Tensor - N-Dimensional Array
text: Symbolic Text Generation
traits: Core Traits
uncertainty: Calibrated Uncertainty Quantification
world: World Model

Crate lmm

Crate lmm Copy item path

§👁️ LMM 🦀

§🎬 Demo

§🧠 What Does LMM Provide?

§⚙️ Architecture

§🔬 Key Capabilities

§📦 Installation

§🦀 Rust

§💻 Command-Line Interface

§🐍 Python

§🟩 Node.js

§🌐 WebAssembly (WASM)

§🤖 Agent Framework

§📰 Publications & Research

§Blog Posts

§📝 Citation

§🤝 Contributing

§📄 License

§⭐ Star Us

§LMM Agent Framework 🤖

§📦 Installation

§🏗️ Core Architecture

§🚀 Quick Start

§🔧 LmmAgent Builder

§🧩 Key Types

§📡 AsyncFunctions Trait

§🔄 Agent Lifecycle

§📎 Further Reading

§LMM Derive Macros ⚙️

§📦 Installation

§🚀 The Auto Macro

§Required struct shape

§Generated traits

§Agent

§Functions

§AsyncFunctions

§Additional fields

§⚠️ Field Name Contract

§📄 License

§LMM Rust Documentation 🦀

§📦 Installation

§Cargo Features

§📚 Library Usage

§Tensor arithmetic

§Symbolic expressions

§Causal graph + do-calculus

§Physics simulation

§Text → Symbolic equation (lossless round-trip)

§Symbolic text continuation

§Genetic programming symbolic regression

§Consciousness loop

§Spectral image generation

§🏗️ Architecture

§📖 Core Types Reference

§📄 License

§LMM WebAssembly Guide 🌐

§Supported Frameworks

§📦 Adding to a WASM Project

§🌍 CORS Considerations

§🔬 Feature Flags for WASM

§📖 Example: Yew Component

§📄 License

Modules§

Crate lmm

§🚀 The `Auto` Macro

§`Agent`

§`Functions`

§`AsyncFunctions`