Metadata-Version: 2.4
Name: meshmind
Version: 0.1.1
Summary: Orchestrate local LLMs across devices with no cloud dependency
Author: Nexarion Distributed AI
License: Copyright 2026 Meshmind
        
        Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
        "License" shall mean the terms and conditions for use, reproduction, and
        distribution as defined by Sections 1 through 9 of this document.
        
        "Licensor" shall mean the copyright owner or entity authorized by the copyright
        owner that is granting the License.
        
        "Legal Entity" shall mean the union of the acting entity and all other entities
        that control, are controlled by, or are under common control with that entity.
        For the purposes of this definition, "control" means (i) the power, direct or
        indirect, to cause the direction or management of such entity, whether by
        contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
        outstanding shares, or (iii) beneficial ownership of such entity.
        
        "You" (or "Your") shall mean an individual or Legal Entity exercising
        permissions granted by this License.
        
        "Source" form shall mean the preferred form for making modifications, including
        but not limited to software source code, documentation source, and configuration
        files.
        
        "Object" form shall mean any form resulting from mechanical transformation or
        translation of a Source form, including but not limited to compiled object code,
        generated documentation, and conversions to other media types.
        
        "Work" shall mean the work of authorship, whether in Source or Object form, made
        available under the License, as indicated by a copyright notice that is included
        in or attached to the work (an example is provided in the Appendix below).
        
        "Derivative Works" shall mean any work, whether in Source or Object form, that
        is based on (or derived from) the Work and for which the editorial revisions,
        annotations, elaborations, or other modifications represent, as a whole, an
        original work of authorship. For the purposes of this License, Derivative Works
        shall not include works that remain separable from, or merely link (or bind by
        name) to the interfaces of, the Work and Derivative Works thereof.
        
        "Contribution" shall mean any work of authorship, including the original version
        of the Work and any modifications or additions to that Work or Derivative Works
        thereof, that is intentionally submitted to Licensor for inclusion in the Work
        by the copyright owner or by an individual or Legal Entity authorized to submit
        on behalf of the copyright owner. For the purposes of this definition,
        "submitted" means any form of electronic, verbal, or written communication sent
        to the Licensor or its representatives, including but not limited to
        communication on electronic mailing lists, source code control systems, and
        issue tracking systems that are managed by, or on behalf of, the Licensor for
        the purpose of discussing and improving the Work, but excluding communication
        that is conspicuously marked or otherwise designated in writing by the copyright
        owner as "Not a Contribution."
        
        "Contributor" shall mean Licensor and any individual or Legal Entity on behalf
        of whom a Contribution has been received by Licensor and subsequently
        incorporated within the Work.
        
        2. Grant of Copyright License. Subject to the terms and conditions of this
        License, each Contributor hereby grants to You a perpetual, worldwide,
        non-exclusive, no-charge, royalty-free, irrevocable copyright license to
        reproduce, prepare Derivative Works of, publicly display, publicly perform,
        sublicense, and distribute the Work and such Derivative Works in Source or
        Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of this License,
        each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
        no-charge, royalty-free, irrevocable (except as stated in this section) patent
        license to make, have made, use, offer to sell, sell, import, and otherwise
        transfer the Work, where such license applies only to those patent claims
        licensable by such Contributor that are necessarily infringed by their
        Contribution(s) alone or by combination of their Contribution(s) with the Work
        to which such Contribution(s) was submitted. If You institute patent litigation
        against any entity (including a cross-claim or counterclaim in a lawsuit)
        alleging that the Work or a Contribution incorporated within the Work
        constitutes direct or contributory patent infringement, then any patent licenses
        granted to You under this License for that Work shall terminate as of the date
        such litigation is filed.
        
        4. Redistribution. You may reproduce and distribute copies of the Work or
        Derivative Works thereof in any medium, with or without modifications, and in
        Source or Object form, provided that You meet the following conditions:
        
        (a) You must give any other recipients of the Work or Derivative Works a copy of
        this License; and
        
        (b) You must cause any modified files to carry prominent notices stating that
        You changed the files; and
        
        (c) You must retain, in the Source form of any Derivative Works that You
        distribute, all copyright, patent, trademark, and attribution notices from the
        Source form of the Work, excluding those notices that do not pertain to any part
        of the Derivative Works; and
        
        (d) If the Work includes a "NOTICE" text file as part of its distribution, then
        any Derivative Works that You distribute must include a readable copy of the
        attribution notices contained within such NOTICE file, excluding those notices
        that do not pertain to any part of the Derivative Works, in at least one of the
        following places: within a NOTICE text file distributed as part of the
        Derivative Works; within the Source form or documentation, if provided along
        with the Derivative Works; or, within a display generated by the Derivative
        Works, if and wherever such third-party notices normally appear. The contents of
        the NOTICE file are for informational purposes only and do not modify the
        License. You may add Your own attribution notices within Derivative Works that
        You distribute, alongside or as an addendum to the NOTICE text from the Work,
        provided that such additional attribution notices cannot be construed as
        modifying the License.
        
        You may add Your own copyright statement to Your modifications and may provide
        additional or different license terms and conditions for use, reproduction, or
        distribution of Your modifications, or for any such Derivative Works as a whole,
        provided Your use, reproduction, and distribution of the Work otherwise complies
        with the conditions stated in this License.
        
        5. Submission of Contributions. Unless You explicitly state otherwise, any
        Contribution intentionally submitted for inclusion in the Work by You to the
        Licensor shall be under the terms and conditions of this License, without any
        additional terms or conditions. Notwithstanding the above, nothing herein shall
        supersede or modify the terms of any separate license agreement you may have
        executed with Licensor regarding such Contributions.
        
        6. Trademarks. This License does not grant permission to use the trade names,
        trademarks, service marks, or product names of the Licensor, except as required
        for reasonable and customary use in describing the origin of the Work and
        reproducing the content of the NOTICE file.
        
        7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
        writing, Licensor provides the Work (and each Contributor provides its
        Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
        KIND, either express or implied, including, without limitation, any warranties
        or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
        PARTICULAR PURPOSE. You are solely responsible for determining the
        appropriateness of using or redistributing the Work and assume any risks
        associated with Your exercise of permissions under this License.
        
        8. Limitation of Liability. In no event and under no legal theory, whether in
        tor t (including negligence), contract, or otherwise, unless required by
        applicable law (such as deliberate and grossly negligent acts) or agreed to in
        writing, shall any Contributor be liable to You for damages, including any
        direct, indirect, special, incidental, or consequential damages of any character
        arising as a result of this License or out of the use or inability to use the
        Work (including but not limited to damages for loss of goodwill, work stoppage,
        computer failure or malfunction, or any and all other commercial damages or
        losses), even if such Contributor has been advised of the possibility of such
        damages.
        
        9. Accepting Warranty or Additional Liability. While redistributing the Work or
        Derivative Works thereof, You may choose to offer, and charge a fee for,
        acceptance of support, warranty, indemnity, or other liability obligations
        and/or rights consistent with this License. However, in accepting such
        obligations, You may act only on Your own behalf and on Your sole
        responsibility, not on behalf of any other Contributor, and only if You agree to
        indemnify, defend, and hold each Contributor harmless for any liability incurred
        by, or claims asserted against, such Contributor by reason of your accepting any
        such warranty or additional liability.
        
        END OF TERMS AND CONDITIONS
        
        APPENDIX: How to apply the Apache License to your work.
        
        To apply the Apache License to your work, attach the following boilerplate
        notice, with the fields enclosed by brackets "[]" replaced with your own
        identifying information. (Don't include the brackets!) The text should be
        enclosed in the appropriate comment syntax for the file format. We also
        recommend that a file or class name and description of purpose be included on the
        same "printed page" as the copyright notice for easier identification within
        third-party archives.
        
        Copyright 2026 Meshmind
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
        
Project-URL: Homepage, https://github.com/Nexarion-Distributed-AI/MeshMind
Project-URL: Repository, https://github.com/Nexarion-Distributed-AI/MeshMind
Project-URL: Issues, https://github.com/Nexarion-Distributed-AI/MeshMind/issues
Project-URL: Changelog, https://github.com/Nexarion-Distributed-AI/MeshMind/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/Nexarion-Distributed-AI/MeshMind/tree/main/docs
Keywords: llm,ollama,fastapi,local-first,distributed-systems,agent,plugins
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: zeroconf>=0.131.0
Requires-Dist: ollama>=0.4.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: websockets>=12.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.7
Requires-Dist: click>=8.1
Requires-Dist: prompt-toolkit>=3.0.43
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.2.0; extra == "mcp"
Dynamic: license-file

﻿<div align="center">

# MeshMind

**A local intelligence mesh for disconnected and local-first AI systems.**

MeshMind is a resilient edge AI coordination layer for running specialized AI nodes across laptops, desktops, phones, and other edge devices without depending on the internet.

<p align="center">
  <a href="https://github.com/Nexarion-Distributed-AI/MeshMind/actions/workflows/ci.yml" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/github/actions/workflow/status/Nexarion-Distributed-AI/MeshMind/ci.yml?branch=main" alt="CI"></a>
  <a href="https://www.apache.org/licenses/LICENSE-2.0.html" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache-2.0"></a>
  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/Ollama-Local%20Models-black" alt="Ollama">
</p>

</div>

---

MeshMind connects local AI systems into a collaborative mesh. Each device runs its own model, capabilities, and context. A coordinator node discovers peers, routes sub-queries, executes work in parallel where possible, and aggregates the results into a unified answer.

This is not distributed inference for a single giant model. MeshMind is built around **distributed collaboration**: multiple specialized nodes working together over local networks and offline-capable environments.

## MeshMind v0.1.1

**What this is:** A **local-first** mesh for **Ollama**-backed specialist nodes on a **trusted LAN**, with a coordinator that routes work and aggregates answers. There is **no MeshMind cloud**; configuration and traffic stay on machines you control.

**Install (released package):** Python **3.11+** and [Ollama](https://ollama.com). Stable installs:

```bash
pip install -U meshmind
```

**Install (from source, contributors):** from the repo root:

```bash
pip install -e ".[dev]"   # or: pip install -e .
```

**Golden path:**

1. `meshmind init my-project` — creates **`data/knowledge.json`** and `meshmind.yaml` (or `meshmind init --wizard`; use `--preset code` for demo plugins).
2. `cd my-project`
3. `meshmind doctor -c meshmind.yaml` — environment, Ollama, config, ports, and plugin directories.
4. `meshmind config validate -c meshmind.yaml`
5. `meshmind up -c meshmind.yaml` — interactive REPL (`›` prompt), or open **Dashboard** / **Chat** at `http://localhost:<ui_port>`, or run `meshmind query "…"`.

**Interoperability:** OpenAI-compatible **`GET /v1/models`** and **`POST /v1/chat/completions`** on the coordinator **`ui_port`**; optional **`MESHMIND_API_TOKEN`** for `/v1/*`. **MCP:** `pip install "meshmind[mcp]"` then **`meshmind mcp-serve`** ([docs/mcp.md](docs/mcp.md)).

**Plugins** (`plugin:` in YAML): [docs/plugins.md](docs/plugins.md).

**Release notes:** [docs/RELEASE_v0.1.md](docs/RELEASE_v0.1.md), [CHANGELOG.md](CHANGELOG.md).

**First-time user guide:** [docs/USER_GUIDE.md](docs/USER_GUIDE.md).

**Not in v0.1.x yet:** QR or PWA onboarding, `meshmind join` / `go`-style scanning, or full OpenAI API parity (embeddings, images, …).

## Features

- **Automatic peer discovery**: Nodes discover each other over mDNS with manual-peer fallback when deterministic networking matters.
- **Capability-based routing**: Queries are routed to the nodes best suited to answer them.
- **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.
- **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.
- **OpenAI-compatible API:** `GET /v1/models` and `POST /v1/chat/completions` on the coordinator UI port — same process as Dashboard/Chat. See [docs/USER_GUIDE.md](docs/USER_GUIDE.md).
- **MCP (optional)**: `pip install "meshmind[mcp]"` and `meshmind mcp-serve` for editor/agent tools. See [docs/mcp.md](docs/mcp.md).

## Dashboard

MeshMind includes a built-in dashboard for inspecting your mesh in real time.

- mesh topology
- node state
- query routing
- event log
- query history
- unavailable-node warnings

Enable the dashboard on a coordinator with:

```yaml
coordinator:
  type: 'coordinator'
  port: 8403
  ui: true
  ui_port: 8080
```

Then open:

```text
http://localhost:8080
```

Paths on the same coordinator UI (one HTTP server on `ui_port`):

- **`/dashboard`** — topology canvas, connected nodes, and live event log
- **`/chat`** — full-page mesh query composer (`POST /api/query` and streaming `POST /api/query/stream`)
- **`/v1/models`**, **`/v1/chat/completions`** — OpenAI-compatible API for external clients (subset of the OpenAI schema; see [docs/USER_GUIDE.md](docs/USER_GUIDE.md))

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 (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

The CLI includes **`meshmind benchmark`** (synthetic or real AI) for repeatable routing and latency scenarios in development. Multi-device SLOs and published performance numbers are still evolving.

What is already true today:

- MeshMind can route work across multiple nodes.
- Parallel fan-out is implemented for multi-capability queries.
- Real-world speedup depends on query shape, model size, discovery overhead, and aggregation cost.

Ongoing measurement priorities:

- discovery time across 2 and 3 devices
- routing correctness
- single-node vs multi-node latency
- disconnect and rejoin behavior
- failure handling under node loss

## 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`.

You can install a **released** build (`pip install meshmind`) or **run from a clone** for development.

### Run from PyPI

Prerequisites:

- Python `3.11+`
- [Ollama](https://ollama.com) installed and running
- A local model, for example:

  ```bash
  ollama pull gemma3:1b
  ```

```bash
pip install meshmind
meshmind doctor
meshmind init my-project
cd my-project
meshmind up -c meshmind.yaml
```

### Run from Source

Prerequisites: same as above. Clone the repo and bootstrap the environment:

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

# Windows PowerShell
./scripts/bootstrap.ps1

# Linux/macOS
# ./scripts/bootstrap.sh
```

Activate the virtual environment if needed:

```bash
# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
# .\.venv\Scripts\Activate.ps1
```

Run the environment diagnostics:

```bash
meshmind doctor
```

Create a project, validate it, and start the mesh:

```bash
meshmind init my-project
cd my-project
meshmind doctor -c meshmind.yaml
meshmind config validate -c meshmind.yaml
meshmind up -c meshmind.yaml
```

**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`** for a **Rich command table**. **`/status`** shows mesh and node tables (plus UI URLs). **`/urls`**, **`/query …`**, **`/clear`** (clears screen and **in-session transcript**), **`/export <path>`** (save transcript as Markdown), **`/compact`** (placeholder — mesh has no token budget), **`/version`**, and **`/stop`** work with or without the leading slash. The prompt shows **`MeshMind ›`** with a bottom hint and mesh name on the right. **Enter** submits; **Ctrl+J** inserts a newline. **Ctrl+C:** empty line = exit; non-empty = clear line; during a query = cancel. Each turn prints a **You** panel (question preview), then **Assistant**: if the mesh streams chunks, a **Rich Live** panel updates with **rendered Markdown** (bold, bullets, emphasis—not raw `**` syntax), then dim routing/duration; if there are **no** stream chunks (result only on `done`), the answer is shown in a single **Markdown panel** instead. **Tab** completes commands and node names; **auto-suggest** uses history. History file: **`.meshmind/repl_history`** beside 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:

```python
from meshmind.sdk.mesh import Mesh
from meshmind.sdk.node_def import NodeDef

mesh = Mesh("my-mesh", default_model="gemma3:1b")

mesh.add_node(NodeDef(
    name="researcher",
    model="gemma3:1b",
    capabilities=["research", "analysis", "summarization"],
    system_prompt="You are a research assistant.",
    port=8401,
))

mesh.add_node(NodeDef(
    name="writer",
    model="gemma3:1b",
    capabilities=["writing", "editing"],
    system_prompt="You are a technical writer.",
    port=8402,
))

mesh.add_coordinator(port=8403)

await mesh.start()
result = await mesh.query("Research recent AI papers and write a summary")
print(result.text)
await mesh.stop()
```

## Example Configuration

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

```yaml
mesh:
  name: 'my-team'
  discovery: 'mdns'

defaults:
  model: 'gemma3:1b'

nodes:
  analyst:
    type: 'specialist'
    port: 8401
    system_prompt: |
      You are a data analyst. Analyze data and provide insights.
    capabilities:
      - 'data_analysis'
      - 'statistics'
    knowledge_domains:
      - 'data'
      - 'statistics'
    knowledge:
      - ./data/knowledge.json

  writer:
    type: 'specialist'
    port: 8402
    system_prompt: |
      You are a technical writer. Write clear documentation.
    capabilities:
      - 'writing'
      - 'documentation'

  coordinator:
    type: 'coordinator'
    port: 8403
    ui: true
    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 [-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 doctor
meshmind config validate
meshmind config show
```

## Architecture

```text
meshmind/
|- core/          protocol, discovery, registry, router, orchestrator, node
|- network/       async TCP transport
|- ai/            Ollama integration and function calling
|- sdk/           Python SDK
|- cli/           Click-based command line interface
|- config/        YAML schema and parser
|- knowledge/     local knowledge loading
|- plugins/       plugin loading
|- ui/            FastAPI dashboard
```

## Current Status

MeshMind is currently an early open source release focused on:

- local multi-agent orchestration across laptops and desktops
- Ollama-backed local models
- mDNS discovery with manual-peer fallback
- CLI and SDK workflows
- dashboard-based mesh visibility

Current focus areas:

- discovery hardening
- routing observability
- repeatable benchmarking
- offline/manual-peer workflows
- mobile-node interoperability

## Current Limitations

- Large models may exceed available RAM and create unstable first-run behavior.
- First-query latency can be significantly slower than warm runs.
- mDNS behavior varies across networks, firewalls, and operating systems.
- 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)
- [Known limitations](docs/known-limitations.md)
- [Vision](VISION.md)

## Testing

Run the automated test suite from the repository root:

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

The current test suite covers:

- protocol serialization
- routing behavior
- registry state
- configuration parsing and validation
- CLI helper logic
- SDK lifecycle behavior

## Use Cases

- private local developer assistants
- research workflows across multiple machines
- on-prem AI coordination for sensitive environments
- offline or degraded-network operations
- edge and field-device intelligence coordination

## Contributing

See:

- [CONTRIBUTING.md](CONTRIBUTING.md)
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)

For local development:

```bash
python -m pip install -e .
python -m pytest tests -q
```

## License

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