Metadata-Version: 2.4
Name: lmagent-plus
Version: 0.3.0rc1
Summary: Local-first AI agent orchestrator — manages llama.cpp, local models, and cloud APIs
License: MIT License
        
        Copyright (c) 2026 3L0_
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/3L0935/LMagent-plus
Project-URL: Repository, https://github.com/3L0935/LMagent-plus
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: websockets>=12.0
Requires-Dist: httpx>=0.27
Requires-Dist: textual>=0.60
Requires-Dist: jsonschema>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Provides-Extra: web
Requires-Dist: fastapi>=0.115; extra == "web"
Requires-Dist: uvicorn[standard]>=0.34; extra == "web"
Provides-Extra: memory
Requires-Dist: chromadb>=0.5; extra == "memory"
Dynamic: license-file

# LMAgent-Plus

> Local-first AI agent orchestrator. No cloud required, no external runtime, no bullshit.

[![CI](https://github.com/3L0935/LMagent-plus/actions/workflows/ci.yml/badge.svg)](https://github.com/3L0935/LMagent-plus/actions/workflows/ci.yml)

---

## What is this?

LMAgent-Plus is an AI agent platform that runs entirely on your machine.

It downloads and manages **llama.cpp internally** — no Ollama, no LM Studio, nothing to install first. Pick a model, it downloads it, it runs.

A Python daemon handles the agent loop, tool execution, and memory. Three frontends connect to it over WebSocket: a **Textual TUI** for terminal power users, a **Tauri + Svelte 5 desktop GUI** for a full graphical experience, and a **web interface** for remote access from any browser (same Svelte GUI served over HTTP). Cloud APIs (Anthropic, OpenAI) are supported as an alternative or fallback to local models.

---

## Features (v0.3)

### Core
- **Self-contained runtime** — downloads the right llama.cpp binary automatically (CUDA / ROCm / Vulkan / Metal / CPU)
- **Built-in model manager** — pull models from HuggingFace directly from the TUI or GUI
- **Multi-persona routing** — `@assistant`, `@coder`, `@writer`, `@research` — each with its own tool set, system prompt, memory, and model
- **Tool use** — bash, file read/write/list, git, memory persistence, agent delegation
- **Two-layer memory** — global context + per-agent memory, injected at the start of each session
- **Streaming responses** — real-time output for local (llama-server SSE) and cloud (Anthropic / OpenAI)
- **Security** — path guard, bash blocklist, git command injection protection
- **Cloud routing** — route to Anthropic/OpenAI instead of or alongside local models
- **Custom tools** — drop a Python file in `~/.lmagent-plus/tools/` and it's available to agents
- **Planning loop** — agents decompose complex tasks into steps before executing (opt-in per persona)
- **Self-reflection** — post-execution review with correction loop (opt-in per persona)
- **Structured outputs** — response_format support (OpenAI/local passthrough, Anthropic tool_choice translation)
- **Metrics collection** — token usage, cost estimation, latency tracking per request (JSONL storage)
- **Eval framework** — benchmark agents against predefined tasks, track outcomes
- **Structured logging** — JSON log formatter with request_id correlation, file rotation
- **GGUF context cap** — reads model metadata, prevents ctx_size from exceeding model max

### Desktop GUI (Tauri + Svelte 5)
- **Chat** — streaming, markdown rendering, tool call display, multi-agent tabs
- **Planning/Reflection cards** — visual step tracking and reflection results in chat
- **Metrics card** — per-request token/latency/tool summary inline
- **Metrics dashboard** — summary cards, hourly bar chart, per-agent breakdown, token split
- **Models** — browse catalog, search HuggingFace, download with real-time progress bar, uninstall
- **Personas** — visual YAML editor (identity, model, system prompt, tool checkboxes), create/duplicate/delete
- **Memory** — tree view of global + per-agent memory, edit context.md and learned.md
- **History** — session browser filterable by agent/date/text, conversation viewer
- **Settings** — full config.yaml editor (7 sections, font size sliders, backend selection)
- **System** — daemon status, loaded model, uptime, notifications, daemon control buttons
- **Setup wizard** — 5-step guided first-run (routing, backend, performance, model, confirmation)
- **Keyboard shortcuts** — Ctrl+1-8 pages, Ctrl+W close tab, Ctrl+T chat
- **Dynamic window title** — shows active persona and model
- **Waiting overlay** — shows loading state while model boots or LLM processes

### Web Interface (Remote Access)
- **Same GUI as desktop** — served over HTTP by a built-in FastAPI server
- **Token auth** — auto-generated Bearer token, login overlay in browser
- **WebSocket proxy** — single port (7772), proxies WS to daemon internally
- **Tailscale support** — interactive setup script, optional Tailscale Serve for HTTPS
- **Web Access settings** — enable/configure directly from the Settings page
- See [docs/WEB_ACCESS.md](docs/WEB_ACCESS.md) for full guide

### TUI (Textual)
- **Modular architecture** — sidebar navigation (Ctrl+1/2/3), dedicated pages (Chat, Metrics, Settings)
- **14 slash commands** — `/help`, `/persona`, `/model`, `/models`, `/tools`, `/hf`, `/hfd`, `/setup`, `/reload`, `/clear`, `/stop`, `/status`, `/metrics`, `/settings`
- **Planning/reflection/metrics display** — step tracking, reflection results, per-request stats
- **Metrics dashboard** — request count, tokens, cost, latency, per-agent breakdown
- **Setup wizard** — 5-step interactive (hardware detection, routing, backend, idle timeout)
- Live tool call display, arrow key autocomplete, theme persistence, persona picker (F2)

---

## Supported backends

| Backend | Hardware | Notes |
|---------|----------|-------|
| CUDA    | NVIDIA GPUs | Best performance on NVIDIA |
| ROCm    | AMD workstation GPUs | Requires ROCm installed |
| Vulkan  | AMD / Intel on Linux | Recommended for AMD RX series |
| Metal   | Apple Silicon | Native on macOS |
| CPU     | Any | Fallback — slow on models >7B |

---

## Install

### One-command install (Linux / macOS)

```bash
curl -fsSL https://raw.githubusercontent.com/3L0935/LMAgent-plus/main/installer/install.sh | bash
```

### One-command install (Windows PowerShell)

```powershell
irm https://raw.githubusercontent.com/3L0935/LMAgent-plus/main/installer/install.ps1 | iex
```

Everything gets installed into `~/.lmagent-plus/` — self-contained, no system pollution.

**Requirements:** Python 3.10+, git. `uv` is auto-installed if missing. For the GUI: Node 20+, Rust/Cargo.

### For developers

```bash
git clone https://github.com/3L0935/LMagent-plus.git
cd LMagent-plus
uv sync
./serve   # daemon
./chat    # TUI
./gui-dev # GUI (dev mode)
```

### Uninstall

```bash
rm -rf ~/.lmagent-plus
```

Or use the interactive uninstaller: `bash ~/.lmagent-plus/app/installer/uninstall.sh`

---

## Run

```bash
lmagent-chat     # Start the TUI (daemon auto-starts)
lmagent-serve    # Start the daemon only
lmagent-gui      # Start the GUI (needs Node + Cargo)
```

Commands are in `~/.lmagent-plus/bin/` — add it to your PATH during install.

### First steps — TUI

```
/setup              guided setup — backend, routing, model download
/hf mistral         search HuggingFace for GGUF models
/hfd owner/repo     browse & download a specific HuggingFace repo (pick quantization)
/model <id>         download and load a model
/models             list available models (downloaded + catalog)
/persona coder      switch to the coder persona
/tools              list tools available for the active persona
/help               full command reference
```

### First steps — GUI

1. Launch with `./gui-dev` — if no `config.yaml` exists, the **setup wizard** opens automatically
2. **Models page** (Ctrl+2) — browse the catalog, search HuggingFace, download with progress bar
3. **Personas page** (Ctrl+3) — edit or create personas with the visual editor
4. **Chat** (Ctrl+1) — pick a persona from the tab bar, start chatting
5. **Memory** (Ctrl+4) — view/edit global context and per-agent memory
6. **History** (Ctrl+5) — browse past sessions, filter by agent or date

### Cloud-only (no local model)

```bash
export ANTHROPIC_API_KEY=sk-...
# or: export OPENAI_API_KEY=sk-...
```

Set routing in `~/.lmagent-plus/config.yaml`:

```yaml
routing:
  default: cloud
```

---

## Personas

| Persona | Recommended model | Min RAM | Tools | Use for |
|---------|-------------------|---------|-------|---------|
| `@assistant` | Harmonic Hermes 9B | 12 GB | bash, file_ops, call_agent | General purpose, tool use, delegation |
| `@coder` | Qwen3-Coder 30B A3B | 24 GB | bash, file_ops, git | Development tasks |
| `@writer` | Qwen3 8B | 10 GB | file_ops | Writing, editing, summarizing |
| `@research` | Qwen3 8B | 10 GB | file_ops | Analysis, reasoning, document review |

Custom personas: create in the GUI (Personas page) or copy `personas/_base.yaml` to `~/.lmagent-plus/personas/`.

---

## Project structure

```
lmagent-plus/
├── core/          # Python daemon — agent loop, tools, memory, runtime, router
├── cli/           # Terminal TUI (Textual)
├── gui/           # Desktop GUI (Tauri v2 + Svelte 5)
├── personas/      # Bundled agent presets (YAML)
├── installer/     # One-command installers + setup helper
├── docs/          # Architecture, memory, runtime, persona docs
└── tests/         # Python tests (289 tests)
```

User data: `~/.lmagent-plus/` — see [docs/USER_DIR.md](docs/USER_DIR.md).

---

## Tests

```bash
# Python tests (289 — core + web)
uv run pytest

# Rust tests — Tauri CRUD commands (21)
cd gui/src-tauri && cargo test

# Vitest — GUI state logic + backend adapters (33)
cd gui && npm test
```

CI runs all 3 suites on every push. See [Actions](https://github.com/3L0935/LMagent-plus/actions).

---

## Documentation

| Doc | Content |
|-----|---------|
| [PLAN.md](PLAN.md) | Project phases and roadmap |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Repo structure, code conventions, multi-agent design |
| [docs/GUI.md](docs/GUI.md) | Desktop GUI architecture (Tauri + Svelte) |
| [docs/RUNTIME.md](docs/RUNTIME.md) | llama.cpp backends, model manager |
| [docs/MEMORY.md](docs/MEMORY.md) | Two-layer memory system |
| [docs/PERSONAS.md](docs/PERSONAS.md) | Persona YAML format, system prompt rules |
| [docs/USER_DIR.md](docs/USER_DIR.md) | `~/.lmagent-plus/` structure, config reference |
| [docs/WEB_ACCESS.md](docs/WEB_ACCESS.md) | Web interface setup, Tailscale, auth |

---

## Contributing

The easiest entry point is **creating or improving personas** — no Python knowledge required.

```bash
cp personas/_base.yaml personas/my-agent.yaml
# edit, test, open a PR
```

For everything else: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

---

## License

See [LICENSE](LICENSE)
