nexus-protocol 0.1.0
The TCP/IP of Latent Space. Direct Vector Injection for AI Agents.
Requires Python: >=3.9
Keywords: ai, llm, agents, interoperability, latent-space, neural-network, telepathy

# Nexus Protocol 🧠
> **The TCP/IP of Latent Space.**

[![PyPI](https://img.shields.io/pypi/v/nexus-protocol)](https://pypi.org/project/nexus-protocol/)
[![License](https://img.shields.io/github/license/nexus-protocol/core)](https://github.com/nexus-protocol/core)
[![Build](https://img.shields.io/github/actions/workflow/status/nexus-protocol/core/ci.yml)](https://github.com/nexus-protocol/core/actions)

**Stop wasting tokens. Start sharing minds.**

Nexus is a high-speed transport layer for Artificial Intelligence. It replaces slow, expensive natural language communication between Agents with direct, zero-loss **Latent Vector Injection**.

---

## ⚡️ Why Nexus?

We are effectively building the **Universal Embedding Standard** for AI-to-AI communication.

| Feature | 🐢 The Old Way (JSON/Text) | 🚀 The Nexus Way (Vectors) |
| :--- | :--- | :--- |
| **Medium** | English / Text | High-Dimensional Vectors |
| **Cost** | High (Generation + Parsing Tokens) | **Zero** (Hidden State Transfer) |
| **Speed** | Slow (Autoregressive Generation) | **Instant** (Matrix Multiplication) |
| **Loss** | High (Semantic drift in parsing) | **Lossless** (Mathematical Precision) |
| **Privacy** | Public (Text is readable) | **Obfuscated** (Abstract Math) |

---

## 📦 Installation

```bash
pip install nexus-protocol
```

*Requires Python 3.9+ and PyTorch.*

---

## 🚀 Quickstart

Transmit a concept from Llama-3 to Mistral without generating a single word of text.

```python
from nexus.client import NexusClient
from nexus.receiver import NexusReceiver
from nexus.protocol import TensorPacket

# 1. Initialize Sender (The Thinker)
sender = NexusClient("meta-llama/Meta-Llama-3-8B")

# 2. Encode a Thought (No text generation happens here)
# "The sky is blue" -> [1, 4096] Float32 Vector
thought_vector = sender.encode_thought("The atmospheric scattering of light...")

# 3. Packetize (TOON Format)
packet = TensorPacket.from_tensor(sender="Llama-3", tensor=thought_vector)

# --- 🌐 NETWORK TRANSMISSION (JSON Serialized) --- 

# 4. Initialize Receiver (The Listener)
receiver = NexusReceiver("mistralai/Mistral-7B-v0.1")

# 5. Inject Thought & Generate
# The model starts generating from the *concept* you injected
output = receiver.receive_thought(packet.model_dump_json())

print(output) 
# Output: "...creates a blue hue visible from the surface."
```

---

## 🧠 Core Architecture

Nexus solves the "Tower of Babel" problem in AI. Every model thinks in a different vector space. Nexus provides the **Universal Bridge**.

1.  **`NexusClient`**: Extracts the "EOS Token" hidden state from the source model.
2.  **`NexusBridge`**: A neural adapter that projects the specific model space (e.g., 4096d) into the **Universal Nexus Space** (2048d).
3.  **`TensorPacket`**: Wraps the vector in the **TOON** (Token Oriented Object Notation) format for transport.
4.  **`InverseBridge`**: Projects the Universal Vector into the Target Model's space.
5.  **`NexusReceiver`**: Performs **Prompt Injection**, inserting the vector directly into the model's context window.

---

## 🗺 Roadmap

- [x] **Protocol v1:** TOON-compliant packet structure.
- [x] **Adapters:** Base `NexusBridge` architecture with Cosine Similarity normalization.
- [ ] **Genesis Bridge:** Pre-trained weights for Llama-3 <-> Mistral <-> GPT-2.
- [ ] **HuggingFace Hub:** Auto-download adapters from `nexus-protocol/adapters`.

---

## 🤝 Contributing

We are building the internet for AIs. We need **Bridge Builders**.

If you have compute, help us train adapters between popular models.
See [CONTRIBUTING.md](./CONTRIBUTING.md) for training guides.

**License:** MIT