Metadata-Version: 2.4
Name: mesh-cognition
Version: 1.2.0
Summary: Python coupling kernel for Mesh Cognition — per-field admission and state blending for CfC neural networks
Author-email: Hongwei Xu <editor@meshcognition.org>
License: Apache-2.0
Project-URL: Homepage, https://meshcognition.org
Project-URL: Documentation, https://meshcognition.org/spec/mmp
Project-URL: Repository, https://github.com/sym-bot/mesh-cognition
Project-URL: Issues, https://github.com/sym-bot/mesh-cognition/issues
Keywords: mesh-cognition,mmp,svaf,cfc,neural-networks,distributed-ai,kuramoto,collective-intelligence,liquid-neural-networks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# mesh-cognition

**Python coupling kernel for Mesh Cognition** — per-field admission and state blending for CfC neural networks.

A pure-Python library that turns any agent running a continuous-time neural network into a Mesh Cognition node. Each agent evaluates incoming peer state per neuron and decides locally whether, how much, and which dimensions to couple.

Canonical home: [meshcognition.org](https://meshcognition.org) · Protocol spec: [meshcognition.org/spec/mmp](https://meshcognition.org/spec/mmp)

## Install

```bash
pip install mesh-cognition
```

Zero external dependencies. Python ≥ 3.10.

## Quick start

```python
from mesh_cognition import MeshNode

# Create a node matching your model's hidden dimension
node = MeshNode(hidden_dim=64)

# After each inference step — update local state
node.update_local_state(new_h1, new_h2, confidence=0.8)

# Receive peer state (from network, another agent, etc.)
node.add_peer("peer-1", peer_h1, peer_h2, confidence=0.9)

# Before next inference — get coupled state
h1, h2 = node.coupled_state()
# Feed h1, h2 into your next inference step

# Inspect what the agent decided
print(node.coherence)             # Kuramoto r(t): 0 = desynced, 1 = locked in sync
print(node.coupling_decisions)    # per-peer: aligned / guarded / rejected
```

## How it works

For each peer, the agent evaluates per-neuron drift:

| Outcome | Drift band | Behavior |
|---|---|---|
| **aligned** | ≤ 0.25 | strong coupling — agent admits peer state |
| **guarded** | 0.25 – 0.5 | reduced coupling — admitted with lowered weight |
| **rejected** | > 0.5 | no coupling — peer state discarded for this dimension |

Each hidden dimension is gated independently. The agent decides locally; no central coordinator.

## Two modes

- **`SemanticCoupler`** (default) — cosine drift, suitable for shared-memory or LLM-style agents
- **`NeuralCoupler`** — per-neuron time constants τ, real Kuramoto order parameter r(t), tuned for CfC (closed-form continuous-time) models

```python
from mesh_cognition import MeshNode, NeuralCouplingConfig

# Neural mode using tau from a trained CfC model
node = MeshNode(hidden_dim=64, config=NeuralCouplingConfig(tau=model_tau))
```

Same API surface for both modes.

## Where this fits

This package implements the per-agent **admission + state-blending** behavior — the cognition kernel. Wire-protocol concerns (identity, transport, peer discovery, CMB serialization) are handled by other Mesh Memory Protocol implementations. Bring your own networking; let this library handle the math of coupling.

For the full protocol specification, see [meshcognition.org/spec/mmp](https://meshcognition.org/spec/mmp).

## License

Apache 2.0. © 2026 SYM.BOT Ltd.
