Metadata-Version: 2.4
Name: vaayu
Version: 1.0.0
Summary: Vaayu: 245M & 492M Small Language Machine Model (SLMM) with Native MCP & Tool Calling
Author: Meet Mendapara
License: MIT
Keywords: slmm,machine-model,mcp,tool-calling,agent,pytorch,transformers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.1.0
Requires-Dist: transformers>=4.40.0
Requires-Dist: tokenizers>=0.19.0
Requires-Dist: huggingface_hub>=0.23.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: numpy>=1.24.0
Dynamic: requires-python

# Vaayu (SLMM) - Small Language Machine Model

[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Vaayu--Base-blue)](https://huggingface.co/meetmendapara/Vaayu-Base)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**Vaayu** is a high-performance **Small Language Machine Model (SLMM)** family engineered from scratch specifically for local machine execution, seamless application embedding, and native **Model Context Protocol (MCP)** tool calling.

- **Vaayu-Base (245M)**: Live on Hugging Face 👉 [**`meetmendapara/Vaayu-Base`**](https://huggingface.co/meetmendapara/Vaayu-Base)
- **Vaayu-Large (492M)**: Advanced multi-tool orchestration and self-correction variant.

---

## Key Highlights

- **From Scratch Architecture**: Not a fine-tune. Built with modern LLM innovations:
  - **Rotary Position Embeddings (RoPE)** with context window of 2,048 tokens
  - **Grouped Query Attention (GQA)** (16 Q heads, 4 KV heads) for 4x KV-cache memory reduction during local inference
  - **SwiGLU Gated Feed-Forward Networks** for superior parameter efficiency
  - **RMSNorm** pre-normalization for numerical stability
- **Parameter Footprint**: 245 Million parameters (~490MB in FP16 / ~245MB in 8-bit quantized), fitting comfortably inside consumer laptops, edge devices, and embedded desktop runtimes.
- **Native MCP Bridge**: First-class support for MCP client & server interactions over `stdio` and `SSE`, enabling direct connection to local IDEs, CLI tools, browsers, and filesystem agents.
- **Trained on Kaggle GPUs**: Sourced from premier tool-use datasets via Kaggle CLI and trained on accelerated GPU kernels under a strict 12-hour compute budget.

---

## Repository Structure

```
.
├── @docs/                          # Step-by-step design, training & deployment documentation
│   ├── step-0-architecture-and-specs.md
│   ├── step-1-dataset-curation.md
│   ├── step-2-tokenizer-and-special-tokens.md
│   ├── step-3-training-from-scratch.md
│   ├── step-4-mcp-connector-and-tool-calling.md
│   ├── step-5-software-embedding-guide.md
│   └── step-6-deployment-and-huggingface.md
├── src/                            # Core model & training codebase
│   ├── model/                      # Custom Transformer architecture & configuration
│   ├── tokenizer/                  # Custom BPE tokenizer & tool tokens
│   ├── data/                       # Kaggle dataset fetcher & MCP synthesizer
│   └── training/                   # AMP training engine & Kaggle runner
├── vaayu/                          # Embeddable runtime package
│   ├── core.py                     # Local inference engine with KV caching
│   ├── mcp_client.py               # Native Model Context Protocol connector
│   └── embed.py                    # High-level embedding API for software integration
├── scripts/                        # Automation scripts (Kaggle submission, HF upload)
└── examples/                       # Embedded tool-calling & MCP usage examples
```

---

## Quickstart

### 1. Installation
```bash
pip install -r requirements.txt
pip install -e .
```

### 2. Embedding Vaayu in Any Local Software
```python
from vaayu import Vaayu

# Initialize embedded local model
vaayu = Vaayu.load_local("checkpoints/vaayu-final.pt")

# Connect to any local MCP server (e.g., filesystem, git, or custom app)
vaayu.connect_mcp_server(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "./"])

# Run autonomous agentic loop
response = vaayu.chat("List all files in the current workspace and summarize their purpose.")
print(response)
```

---

## Documentation
Refer to the [`@docs`](./@docs) directory for complete technical specifications:
- [`@docs/step-0-architecture-and-specs.md`](./@docs/step-0-architecture-and-specs.md)
- [`@docs/step-1-dataset-curation.md`](./@docs/step-1-dataset-curation.md)
- [`@docs/step-2-tokenizer-and-special-tokens.md`](./@docs/step-2-tokenizer-and-special-tokens.md)
- [`@docs/step-3-training-from-scratch.md`](./@docs/step-3-training-from-scratch.md)
- [`@docs/step-4-mcp-connector-and-tool-calling.md`](./@docs/step-4-mcp-connector-and-tool-calling.md)
- [`@docs/step-5-software-embedding-guide.md`](./@docs/step-5-software-embedding-guide.md)
- [`@docs/step-6-deployment-and-huggingface.md`](./@docs/step-6-deployment-and-huggingface.md)
