Skip to content

Arnav #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Halleys123 merged 2 commits into from
Apr 18, 2026
Merged

Arnav #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
17a0abe
Refactor configuration files and update documentation
Halleys123 Apr 18, 2026
4641b8d
Merge branch 'main' of https://github.com/MeshMind-Labs/MeshMind into…
Halleys123 Apr 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.11"]
python-version: ['3.11']

steps:
- name: Checkout
Expand Down
126 changes: 45 additions & 81 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,56 +28,14 @@ This is not distributed inference for a single giant model. MeshMind is built ar
- **Parallel fan-out**: Multi-capability queries can be sent to multiple nodes concurrently.
- **Coordinator aggregation**: Responses are combined into a single final answer.
- **Built-in dashboard**: Monitor mesh topology, routing activity, query traces, and node availability.
- **Dashboard cards**: Hover a node to inspect capabilities, knowledge domains, tools, and system prompt previews without exposing raw knowledge file lists or plugin ids.
- **CLI-first workflow**: Bootstrap, validate, run, and query the mesh from the terminal.
- **Python SDK**: Create and control meshes programmatically.
- **Local-model runtime**: Uses Ollama-backed local models instead of remote APIs.
- **Knowledge-aware nodes**: Load local knowledge files into specific nodes.
- **Manual discovery fallback**: Useful for restrictive firewalls, unusual LANs, or offline field setups.

---

## What Makes MeshMind Different

Other tools split one model across devices to make it run faster. **MeshMind does something different** — each device runs its own specialized AI agent, and they collaborate to solve complex queries that no single agent could answer alone.

```
Exo / mesh-llm: "Split one 70B model across three laptops"
MeshMind: "A medical AI, a logistics AI, and a coordinator
work as a team across three laptops"

DISTRIBUTED INFERENCE VS DISTRIBUTED COLLABORATION
```

---

## How It Works

```
User sends query
↓
┌───────────────┐
│ COORDINATOR │ Decomposes query, classifies capabilities needed
└───────────────┘
↓
┌───────────────┐ ┌───────────────┐
│ AGENT A │ │ AGENT B │ Each runs its own LLM + knowledge base
│ Medical │ │ Logistics │ Processes in parallel via function calling
└───────────────┘ └───────────────┘
↓ ↓
┌───────────────┐
│ AGGREGATION │ Combines responses into unified answer
└───────────────┘
↓
User sees one coherent response
Dashboard shows routing in real-time
```

1. Define your AI agents in a `meshmind.yaml` file
2. Run `meshmind up` — agents discover each other automatically via mDNS
3. Send a query — MeshMind decomposes it, routes sub-queries to the right agents, and aggregates their answers
4. Everything runs locally. No internet. No cloud. No data leaves your network

---
- **Plugins**: Drop-in packages under `~/.meshmind/plugins/` (or `MESHMIND_PLUGIN_DIR`) merged into specialist nodes via `plugin: <id>` in `meshmind.yaml`. See [docs/plugins.md](docs/plugins.md) for layout and merge rules.
- **Init presets / wizard**: `meshmind init <dir> --preset code` for a multi-specialist template; `meshmind init --wizard` for an interactive flow.

## Dashboard

Expand Down Expand Up @@ -108,10 +66,12 @@ http://localhost:8080

Paths on the same coordinator UI:

- `/dashboard` - topology canvas, connected nodes, and live event log
- `/chat` - full-page mesh query composer (same `POST /api/query` backend)
- **`/dashboard`** — topology canvas, connected nodes, and live event log
- **`/chat`** — full-page mesh query composer (same `POST /api/query` backend)

The dashboard sidebar also shows plugin cards for installed prompt packs, with prompt previews and tool summaries. When a plugin lives inside this repository, its source folder is linked directly from the card.

If `/chat` returns `{"detail":"Not Found"}`, the running process is an older MeshMind build: stop the mesh (Ctrl+C), then from the repo root run `pip install -e .` and start again with `meshmind up` so the coordinator loads the current `meshmind.ui.app` routes.
If **`/chat`** returns `{"detail":"Not Found"}`, the running process is an older MeshMind build: stop the mesh (type `stop` in the `meshmind up` REPL, or Ctrl+C if you used `--no-interactive`), then from the repo root run `pip install -e .` and start again with `meshmind up` so the coordinator loads the current `meshmind.ui.app` routes.

## Benchmarks

Expand All @@ -131,14 +91,6 @@ Current benchmarking priorities:
- disconnect and rejoin behavior
- failure handling under node loss

Run current benchmark suite:

```bash
meshmind benchmark --suite minimum --runs 5 -o benchmark-report.json
```

---

## Quick Start

Devices running MeshMind can discover each other automatically over local networks. The default generated project also exposes a local dashboard on the configured `ui_port`.
Expand All @@ -160,7 +112,7 @@ Prerequisites:
Clone the repo and bootstrap the environment:

```bash
git clone https://github.com/MeshMind-Labs/MeshMind.git
git clone https://github.com/Nexarion-Distributed-AI/MeshMind.git
cd MeshMind

# Windows PowerShell
Expand All @@ -180,7 +132,7 @@ source .venv/bin/activate
# .\.venv\Scripts\Activate.ps1
```

Run environment diagnostics:
Run the environment diagnostics:

```bash
meshmind doctor
Expand All @@ -195,12 +147,30 @@ meshmind config validate -c meshmind.yaml
meshmind up -c meshmind.yaml
```

Query it from another terminal:
**Presets:** `meshmind init <dir> --preset default` (same as omitting `--preset`) uses the generic assistant + coordinator template. `meshmind init <dir> --preset code` generates a reviewer + security + coordinator mesh and, by default, copies bundled demo plugins `demo_review` and `demo_security` into your plugin directory. Use `--skip-bundled-plugins` to only write YAML. In a normal terminal, bare `meshmind init` (no name, default options) starts the same interactive wizard as `meshmind init --wizard`; the wizard shows a Rich preview and asks for confirmation before creating files.

**Wizard:** `meshmind init --wizard` interactively chooses a preset and project name (optional NAME as the first argument).

**Plugins CLI:** `meshmind plugin list`, `meshmind plugin list --available` / `meshmind plugin catalog`, `meshmind plugin install <path-or-bundled-id>`, `meshmind plugin sync -c meshmind.yaml`, `meshmind plugin validate <path-or-id>`, `meshmind plugin remove <id>`. Details: [docs/plugins.md](docs/plugins.md).

**Two-terminal workflow (Claude Code–style):** the terminal where you run `meshmind up` starts an **interactive REPL** with a **`›`** prompt. Mesh **INFO** logs are written to **`.meshmind/logs/mesh-<mesh-name>.log`** next to your YAML (not mixed into that REPL). Open a **second** terminal and tail them:

```bash
meshmind logs -f -c meshmind.yaml
```

**REPL behavior:** use **`/help`** (or `help`) for commands. **`/status`**, **`/urls`**, **`/query …`**, and **`/stop`** (or `stop` / `exit`) work with or without the leading slash. **Enter** submits; **Ctrl+J** inserts a newline for multi-line questions. Answers are rendered with **Rich** (metadata panel + markdown). **Tab** completes commands and configured node names. Input history is stored in **`.meshmind/repl_history`** next to your `meshmind.yaml`.

Query from either terminal: in the REPL type a line (it is sent as a query) or **`/query …`**; or from another shell:

```bash
meshmind query "Summarize the latest AI trends in 5 bullets" -c meshmind.yaml -t 300
```

**CLI output format:** `meshmind query` defaults to **`--format auto`** — **markdown** when stdout is a TTY (styled panel + markdown body), **plain text** when not (e.g. pipes/CI). Use **`--format json`** for a stable JSON object (`result`, `nodes_used`, `duration`, `unavailable_nodes`, `trace`).

For a **single** terminal with the old log stream on stdout (e.g. CI), use `meshmind up -c meshmind.yaml --log-to-stdout`. To skip the REPL and wait until Ctrl+C only: `--no-interactive`.

### Python SDK

MeshMind also provides a Python SDK for programmatic mesh creation:
Expand Down Expand Up @@ -237,7 +207,7 @@ await mesh.stop()

## Example Configuration

`meshmind.yaml` defines the mesh, default model settings, and participating nodes:
`meshmind.yaml` defines the mesh, default model settings, and the participating nodes:

```yaml
mesh:
Expand All @@ -256,6 +226,11 @@ nodes:
capabilities:
- 'data_analysis'
- 'statistics'
knowledge_domains:
- 'data'
- 'statistics'
knowledge:
- ./data/knowledge.json

writer:
type: 'specialist'
Expand All @@ -273,23 +248,26 @@ nodes:
ui_port: 8080
```

Additional committed examples:

- [my-project/meshmind.yaml](my-project/meshmind.yaml)
- [smoke-local/meshmind.yaml](smoke-local/meshmind.yaml)

## CLI Reference

```bash
meshmind init <name>
meshmind up
meshmind up [-c meshmind.yaml] [--no-interactive] [--log-to-stdout] [--log-file PATH]
meshmind logs [-c meshmind.yaml] [-f] [-n 200]
meshmind down
meshmind stats
meshmind nodes
meshmind query "text"
meshmind benchmark
meshmind doctor
meshmind config validate
meshmind config show
```

---

## Architecture

```text
Expand All @@ -305,8 +283,6 @@ meshmind/
|- ui/ FastAPI dashboard
```

---

## Current Status

MeshMind is currently an early open source release focused on:
Expand All @@ -325,8 +301,6 @@ Current focus areas:
- offline/manual-peer workflows
- mobile-node interoperability

---

## Current Limitations

- Large models may exceed available RAM and create unstable first-run behavior.
Expand All @@ -335,25 +309,21 @@ Current focus areas:
- Multi-device routing is implemented, but guaranteed speedup has not yet been comprehensively benchmarked.
- Mobile-node support is still experimental and not yet a stable documented flow.

---

## Guides

- [2-device LAN guide](docs/lan-two-device.md)
- [Testing and benchmarking guide](docs/tests.md)
- [Known limitations](docs/known-limitations.md)

---
- [Vision](VISION.md)

## Testing

Run the automated test suite from repository root:
Run the automated test suite from the repository root:

```bash
python -m pytest tests -q
```

The current suite covers:
The current test suite covers:

- protocol serialization
- routing behavior
Expand All @@ -362,8 +332,6 @@ The current suite covers:
- CLI helper logic
- SDK lifecycle behavior

---

## Use Cases

- private local developer assistants
Expand All @@ -372,8 +340,6 @@ The current suite covers:
- offline or degraded-network operations
- edge and field-device intelligence coordination

---

## Contributing

See:
Expand All @@ -388,8 +354,6 @@ python -m pip install -e .
python -m pytest tests -q
```

---

## License

MeshMind is licensed under the [Apache License 2.0](LICENSE).
Loading
Loading