lmm 0.2.1

A language agnostic framework for emulating reality.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

# 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

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

Or as a feature of the root `lmm` crate:

```toml
[dependencies]
lmm = { version = "0.2.1", features = ["agent"] }
```

## 🏗️ Core Architecture

```mermaid
flowchart TD
    U["Custom Struct\n#[derive(Auto)]"]
    L["LmmAgent\n(core state)"]
    E["Executor trait\n(your logic)"]
    O["AutoAgent\norchestrator"]
    G["equation_generate\n(n-gram symbolic)"]
    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

```rust
use lmm_agent::prelude::*;
use lmm_agent::types::{Task, Status, Message};
use lmm_agent::agent::LmmAgent;
use lmm_agent::runtime::AutoAgent;
use lmm_agent::agents;
use std::borrow::Cow;
use async_trait::async_trait;
use anyhow::Result;

// Define your agent struct
#[derive(Debug, Default, Auto)]
pub struct MyAgent {
    pub persona:  Cow<'static, str>,
    pub behavior: Cow<'static, str>,
    pub status:   Status,
    pub agent:    LmmAgent,
    pub memory:   Vec<Message>,
}

// 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.persona().to_string();
        let response = self.generate(&prompt).await?;
        self.agent.add_message(Message::new("assistant", response));
        self.agent.update(Status::Completed);
        Ok(())
    }
}

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

## 🔧 LmmAgent Builder

```rust
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:

```rust,ignore
// 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

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

## 📎 Further Reading

- [lmm-agent crate README](lmm-agent/README.md)
- [lmm-derive macro README](lmm-derive/README.md)
- [Full workspace README](README.md)
- [Custom agent example](lmm-agent/examples/custom_agent.rs)