synaptoroute 0.1.0__tar.gz

synaptoroute-0.1.0/.env

@@ -0,0 +1,13 @@
+# API Keys
+GROQ_API_KEY="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"
+GEMINI_API_KEY="AIzaSyABX8yf5xLvkJEJ211GJ-6N-akmPVM8n54."
+
+# Kaggle API Credentials
+KAGGLE_USERNAME="sitanshukr"
+KAGGLE_KEY="KGAT_447253d2b97a93aa3faae30bb4481004y"
+
+# Database Paths
+SQLITE_DB_PATH="data/router_memory.sqlite"
+# CHROMA_DB_PATH="persistence/chroma_db" # Not used in SynaptoRoute
+GROQ_API_KEY_2="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"
+GOOGLE_API_KEY_2="AIzaSyAFt-hiURmYOxt6ckafhI-43NcU2lPaHY0"

synaptoroute-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Create a report to help us improve SynaptoRoute
+title: '[BUG] '
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Initialize router with '...'
+2. Call router.add_route(...)
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Environment (please complete the following information):**
+ - OS: [e.g. Ubuntu 22.04, Windows 11]
+ - Python Version: [e.g. 3.11]
+ - SynaptoRoute Version: [e.g. 0.1.0]

synaptoroute-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for SynaptoRoute
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

synaptoroute-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Description
+<!-- Please include a summary of the change and which issue is fixed. -->
+
+Fixes # (issue)
+
+## Type of change
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] This change requires a documentation update
+
+## Checklist:
+- [ ] My code follows the architectural guidelines of this project (e.g. preserves $O(1)$ updates).
+- [ ] I have performed a self-review of my own code.
+- [ ] I have commented my code, particularly in hard-to-understand areas.
+- [ ] I have made corresponding changes to the documentation (`README.md`, `notebooks/`).
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] New and existing unit tests pass locally with my changes.

synaptoroute-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[test]
+          
+      - name: Run Tests
+        run: |
+          pytest
+          
+  docker-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Build Docker Image
+        run: |
+          docker build -t synaptoroute-test .
+
+  benchmark:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          
+      - name: Run Dynamic Batching Benchmark
+        run: |
+          echo "### Dynamic Batching Throughput" >> $GITHUB_STEP_SUMMARY
+          python benchmarks/bench_dynamic_batching.py >> $GITHUB_STEP_SUMMARY
+          
+      - name: Run System Performance Benchmark
+        run: |
+          echo "### System Performance & Hot-Reload Latency" >> $GITHUB_STEP_SUMMARY
+          python benchmarks/bench_performance.py >> $GITHUB_STEP_SUMMARY

synaptoroute-0.1.0/BENCHMARKS.md

@@ -0,0 +1,76 @@
+# SynaptoRoute: Master Empirical Benchmarks
+
+This document serves as the immutable, objective record of all performance, accuracy, and memory metrics recorded during the engineering of the SynaptoRoute engine.
+
+## 1. Hardware Inference Latency (Batch Size = 1)
+| Environment | P50 Latency | P99 Latency |
+| :--- | :--- | :--- |
+| **Cloud CPU (Ubuntu 2-Core)** | 3.07 ms | 3.94 ms |
+| **Local GPU (RTX 3050)** | 8.51 ms | 14.11 ms |
+
+> **Note:** The quantized INT8 ONNX architecture allows standard CPUs to outpace entry-level GPUs for sequential inferences due to minimized PCIe transfer overhead.
+
+## 2. Dynamic Batching Throughput (Batch Size = 1000)
+*Test: Firing 1000 concurrent async queries.*
+
+| Environment | Amortized Latency (per query) |
+| :--- | :--- |
+| **Cloud CPU (Ubuntu 2-Core)** | 2.69 ms |
+| **Local GPU (RTX 3050)** | 0.157 ms |
+
+> **Note:** Under heavy concurrent load, the 5-millisecond dynamic batching queue kicks in, drastically increasing throughput and allowing hardware accelerators to shine.
+
+## 3. Memory Profiling: Hot-Reloading ($O(1)$ vs $O(N)$)
+*Test: Sequentially adding 500 routes dynamically.*
+
+| Compilation Strategy | 10th Route Addition | 490th Route Addition | Behavior |
+| :--- | :--- | :--- | :--- |
+| **Eager (NumPy `vstack`)** | 1.15 ms | 4.88 ms | Linearly Degrading $O(N)$ |
+| **SynaptoRoute Lazy** | 0.02 ms | 0.02 ms | Perfectly Flat $O(1)$ |
+
+> **Note:** Deferred reallocation prevents server freezes during live updates. Average SynaptoRoute hot-reload penalty: 5.04 ms.
+
+## 4. Classification Accuracy & Optimization
+
+| Metric | Score |
+| :--- | :--- |
+| **Baseline Cosine Similarity Accuracy** | ~82.0% |
+| **Optimized Threshold Accuracy** | > 98.0% |
+| **Threshold Optimizer F1 Score** | 0.985 |
+
+> **Note:** We achieved this by implementing an automatic ML optimizer (`fit_thresholds`) that calculates the mathematically perfect cosine threshold for every individual route based on a labeled dataset.
+
+## 5. System Vulnerabilities & Leaks Fixed
+- **Zombie Futures:** Resolved a critical async bug where cancelling the worker left client requests hanging.
+- **DDoS Vulnerability:** Bounded the batching queue at `maxsize=10000` to prevent OOM errors.
+- **SQLite Dangling Embeddings:** Implemented memory rebuilding via NumPy masks to prevent the router from retaining and matching against deleted utterances.
+
+## 6. System Stability and Stress Testing
+
+### Test 1: Concurrency Limits (20,000 Concurrent Requests)
+| Metric | Count |
+| :--- | :--- |
+| **Processed Requests** | 10,000 |
+| **Rejected Requests (RouterOverloadedError)** | 10,000 |
+| **Unhandled Exceptions** | 0 |
+
+> **Note:** The bounded queue (`maxsize=10000`) successfully prevented Out-of-Memory (OOM) errors during high concurrency. The system rejected excess requests as expected without process degradation. Total execution time: 31.42 seconds.
+
+### Test 2: Memory Allocation Durability (2,000 Consecutive Reloads)
+| Iteration | Peak RAM |
+| :--- | :--- |
+| **Iteration 0** | 0.01 MB |
+| **Iteration 2000** | 0.32 MB |
+
+> **Note:** Continuous route modification and reallocation over 2,000 iterations maintained stable memory usage, confirming that the NumPy mask replacement effectively mitigated prior memory leaks associated with eager compilation.
+
+### Test 3: Edge-Case Input Handling
+| Input Type | Status | Latency |
+| :--- | :--- | :--- |
+| **Empty String** | Processed | 10.66 ms |
+| **Whitespace Only** | Processed | 14.68 ms |
+| **Large Payload (1 MB)** | Processed | 461.85 ms |
+| **Unstructured Noise (5000 chars)** | Processed | 145.79 ms |
+| **Extended Unicode / Emojis** | Processed | 23.80 ms |
+
+> **Note:** The ONNX runtime and asyncio worker thread successfully processed atypical and malformed inputs without raising critical exceptions or halting execution.

synaptoroute-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,19 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+Examples of behavior that contributes to a positive environment for our community include:
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+
+Examples of unacceptable behavior include:
+* The use of sexualized language or imagery
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Other conduct which could reasonably be considered inappropriate in a professional setting.

synaptoroute-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to SynaptoRoute
+
+First off, thank you for considering contributing to SynaptoRoute! It's people like you that make open source such a great community.
+
+## Development Setup
+
+1. **Fork the repository** on GitHub.
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/SynaptoRoute.git
+   cd SynaptoRoute
+   ```
+3. **Create a virtual environment and install dependencies:**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
+   pip install -e .[api]
+   pip install pytest
+   ```
+
+## Running Tests
+We enforce strict testing for all architectural components (encoding, latency, routing accuracy). Before submitting a PR, ensure all tests pass:
+```bash
+pytest tests/
+```
+
+## Pull Request Process
+1. Ensure your code strictly adheres to the existing architectural philosophy (e.g., preserving $O(1)$ Lazy Compilation).
+2. Update the `README.md` or Jupyter Notebooks in `notebooks/` if you add new features.
+3. Open a Pull Request using the provided GitHub PR template.
+4. Wait for CI/CD checks to pass.

synaptoroute-0.1.0/Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install any required system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy python project configuration
+COPY pyproject.toml .
+COPY README.md .
+COPY src/ src/
+
+# Install the package
+RUN pip install --no-cache-dir .[api]
+
+# Cache fastembed weights during build
+RUN python -c "from fastembed import TextEmbedding; TextEmbedding()" || true
+
+COPY examples/ examples/
+
+EXPOSE 8000
+
+CMD ["uvicorn", "examples.api_server:app", "--host", "0.0.0.0", "--port", "8000"]

synaptoroute-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sitanshu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synaptoroute-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: synaptoroute
+Version: 0.1.0
+Summary: A dynamic zero-token semantic router
+Project-URL: Repository, https://github.com/sitanshukr08/SynaptoRoute
+Project-URL: Issues, https://github.com/sitanshukr08/SynaptoRoute/issues
+Author-email: Sitanshu <contact@example.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: fastembed>=0.8.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: scikit-learn>=1.3.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.100.0; extra == 'api'
+Requires-Dist: uvicorn>=0.22.0; extra == 'api'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# SynaptoRoute
+
+[![PyPI version](https://badge.fury.io/py/synaptoroute.svg)](https://pypi.org/project/synaptoroute/)
+[![CI/CD Pipeline](https://github.com/sitanshukr08/SynaptoRoute/actions/workflows/ci.yml/badge.svg)](https://github.com/sitanshukr08/SynaptoRoute/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/sitanshukr08/SynaptoRoute/blob/main/CONTRIBUTING.md)
+
+SynaptoRoute is a high-throughput, local semantic routing engine built for production Python microservices. Designed as a mathematically optimal alternative to Large Language Model (LLM) routing chains and slower local routers, it provides zero-token intent classification in under 3 milliseconds on standard cloud hardware.
+
+## Table of Contents
+- [Why SynaptoRoute?](#why-synaptoroute)
+- [Architecture & Optimizations](#architecture--optimizations)
+- [Performance Benchmarks](#performance-benchmarks)
+- [Installation & Deployment](#installation--deployment)
+- [Quick Start Guide](#quick-start-guide)
+- [System Limitations](#system-limitations)
+- [Community & Contributing](#community--contributing)
+
+---
+
+## Why SynaptoRoute?
+
+In modern agentic systems, relying on an external API (like OpenAI or Anthropic) to make simple routing decisions—such as determining if a user wants to reset their password or check their balance—introduces unacceptable latency (300ms+) and high token costs.
+
+SynaptoRoute solves this by executing intent classification entirely locally using INT8 quantized vector embeddings. 
+
+SynaptoRoute was engineered specifically to solve the $O(N)$ memory degradation problem during live hot-reloading and to maximize hardware utilization via asynchronous dynamic batching.
+
+## Architecture & Optimizations
+
+### 1. Lazy Memory Compilation
+Traditional routers suffer from severe performance degradation during live updates. When a new route is added, they execute an immediate `numpy.vstack`, copying the entire vector array in memory ($O(N)$ complexity). SynaptoRoute defers this reallocation, appending new vectors to a lightweight list ($O(1)$) and only executing the heavy compilation precisely when the next query arrives, preventing server freezes.
+
+### 2. Dynamic Asynchronous Batching
+Hardware accelerators (GPUs, AVX512 CPUs) are optimized for large matrix multiplications. Sending single queries sequentially incurs massive transfer overhead. SynaptoRoute utilizes a background `asyncio.Queue` worker that traps parallel HTTP requests, waits 5 milliseconds, groups them into a batch, and processes them in a single hardware cycle.
+
+### 3. INT8 Quantization
+By default, SynaptoRoute leverages the `BAAI/bge-small-en-v1.5` model quantized to 8-bit integers via the ONNX runtime, slashing memory bandwidth requirements by 4x and maximizing CPU cache utilization.
+
+---
+
+## Performance Benchmarks
+
+The following metrics were captured via automated GitHub Actions CI/CD running on a standard, unaccelerated `ubuntu-latest` 2-core cloud CPU.
+
+| Metric | Cloud CPU Latency | Context |
+| :--- | :--- | :--- |
+| **Inference P99** | 3.94 ms | Single sequential query latency. |
+| **Amortized P50** | 2.69 ms | Per-query latency when processing 1,000 concurrent requests via dynamic batching. |
+| **Hot-Reload** | 5.04 ms | Time required to dynamically inject a new utterance into memory without dropping active API requests. |
+
+> **📊 View Full Benchmarks:** For detailed analysis including Memory Leak Endurance, GPU Scaling, Classification F1-Scores, and Input Poisoning Survival Metrics, see our official [BENCHMARKS.md](BENCHMARKS.md).
+
+---
+
+## Installation & Deployment
+
+### Method 1: Docker REST API (Recommended)
+
+SynaptoRoute ships with a fully asynchronous FastAPI wrapper, designed for immediate drop-in deployment as a scalable microservice.
+
+```bash
+# Build the Docker image
+docker build -t synaptoroute .
+
+# Run the container
+docker run -p 8000:8000 synaptoroute
+```
+
+You can interface with the router immediately:
+```bash
+curl -X POST http://localhost:8000/route \
+     -H "Content-Type: application/json" \
+     -d '{"query": "I need help resetting my password"}'
+```
+
+### Method 2: Standard Python Package
+
+To embed SynaptoRoute natively into your existing Python pipelines, install directly from pip (or via git if testing the latest main branch):
+
+```bash
+pip install synaptoroute
+```
+
+---
+
+## Quick Start Guide
+
+```python
+import asyncio
+from synaptoroute.router import AdaptiveRouter
+from synaptoroute.encoder import Encoder
+from synaptoroute.storage import SQLiteStorage
+from synaptoroute.models import Route
+
+async def main():
+    # 1. Initialize Components
+    encoder = Encoder()
+    storage = SQLiteStorage("data/memory.sqlite")
+    router = AdaptiveRouter(encoder, storage)
+    
+    # 2. Define Routes
+    billing_route = Route(
+        name="billing", 
+        utterances=["I need a refund", "Where is my receipt?", "Cancel my subscription"]
+    )
+    router.add_route(billing_route)
+    
+    # 3. Start the Background Batching Worker
+    await router.start()
+    
+    # 4. Execute Async Queries
+    result = await router.aquery("How do I get my money back?")
+    print(f"Matched Intent: {result.name}") # Output: billing
+    
+    # 5. Graceful Shutdown
+    await router.stop()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## System Limitations
+
+**Horizontal Scaling (Kubernetes Split-Brain)**  
+SynaptoRoute relies on a highly optimized, local in-memory NumPy matrix to achieve its microsecond latency. As such, it is structurally bound to a single node. If deployed across multiple load-balanced Kubernetes pods, a hot-reload request hitting Pod A will update Pod A's local memory, but Pod B will remain unaware. Scaling horizontally requires implementing an external event bus (e.g., Redis Pub/Sub) to broadcast memory invalidation events across the cluster.
+
+---
+
+## Community & Contributing
+
+We welcome contributions of all sizes from the open-source community! 
+
+- **Contributing:** Please read our [Contributing Guidelines](CONTRIBUTING.md) to learn how to set up your development environment, run the test suite, and submit Pull Requests.
+- **Code of Conduct:** We are committed to fostering a welcoming environment. Please review our [Code of Conduct](CODE_OF_CONDUCT.md).
+- **Issues:** If you discover a bug or have a feature request, please [open an issue](https://github.com/sitanshukr08/SynaptoRoute/issues).

synaptoroute-0.1.0/README.md

@@ -0,0 +1,140 @@
+# SynaptoRoute
+
+[![PyPI version](https://badge.fury.io/py/synaptoroute.svg)](https://pypi.org/project/synaptoroute/)
+[![CI/CD Pipeline](https://github.com/sitanshukr08/SynaptoRoute/actions/workflows/ci.yml/badge.svg)](https://github.com/sitanshukr08/SynaptoRoute/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/sitanshukr08/SynaptoRoute/blob/main/CONTRIBUTING.md)
+
+SynaptoRoute is a high-throughput, local semantic routing engine built for production Python microservices. Designed as a mathematically optimal alternative to Large Language Model (LLM) routing chains and slower local routers, it provides zero-token intent classification in under 3 milliseconds on standard cloud hardware.
+
+## Table of Contents
+- [Why SynaptoRoute?](#why-synaptoroute)
+- [Architecture & Optimizations](#architecture--optimizations)
+- [Performance Benchmarks](#performance-benchmarks)
+- [Installation & Deployment](#installation--deployment)
+- [Quick Start Guide](#quick-start-guide)
+- [System Limitations](#system-limitations)
+- [Community & Contributing](#community--contributing)
+
+---
+
+## Why SynaptoRoute?
+
+In modern agentic systems, relying on an external API (like OpenAI or Anthropic) to make simple routing decisions—such as determining if a user wants to reset their password or check their balance—introduces unacceptable latency (300ms+) and high token costs.
+
+SynaptoRoute solves this by executing intent classification entirely locally using INT8 quantized vector embeddings. 
+
+SynaptoRoute was engineered specifically to solve the $O(N)$ memory degradation problem during live hot-reloading and to maximize hardware utilization via asynchronous dynamic batching.
+
+## Architecture & Optimizations
+
+### 1. Lazy Memory Compilation
+Traditional routers suffer from severe performance degradation during live updates. When a new route is added, they execute an immediate `numpy.vstack`, copying the entire vector array in memory ($O(N)$ complexity). SynaptoRoute defers this reallocation, appending new vectors to a lightweight list ($O(1)$) and only executing the heavy compilation precisely when the next query arrives, preventing server freezes.
+
+### 2. Dynamic Asynchronous Batching
+Hardware accelerators (GPUs, AVX512 CPUs) are optimized for large matrix multiplications. Sending single queries sequentially incurs massive transfer overhead. SynaptoRoute utilizes a background `asyncio.Queue` worker that traps parallel HTTP requests, waits 5 milliseconds, groups them into a batch, and processes them in a single hardware cycle.
+
+### 3. INT8 Quantization
+By default, SynaptoRoute leverages the `BAAI/bge-small-en-v1.5` model quantized to 8-bit integers via the ONNX runtime, slashing memory bandwidth requirements by 4x and maximizing CPU cache utilization.
+
+---
+
+## Performance Benchmarks
+
+The following metrics were captured via automated GitHub Actions CI/CD running on a standard, unaccelerated `ubuntu-latest` 2-core cloud CPU.
+
+| Metric | Cloud CPU Latency | Context |
+| :--- | :--- | :--- |
+| **Inference P99** | 3.94 ms | Single sequential query latency. |
+| **Amortized P50** | 2.69 ms | Per-query latency when processing 1,000 concurrent requests via dynamic batching. |
+| **Hot-Reload** | 5.04 ms | Time required to dynamically inject a new utterance into memory without dropping active API requests. |
+
+> **📊 View Full Benchmarks:** For detailed analysis including Memory Leak Endurance, GPU Scaling, Classification F1-Scores, and Input Poisoning Survival Metrics, see our official [BENCHMARKS.md](BENCHMARKS.md).
+
+---
+
+## Installation & Deployment
+
+### Method 1: Docker REST API (Recommended)
+
+SynaptoRoute ships with a fully asynchronous FastAPI wrapper, designed for immediate drop-in deployment as a scalable microservice.
+
+```bash
+# Build the Docker image
+docker build -t synaptoroute .
+
+# Run the container
+docker run -p 8000:8000 synaptoroute
+```
+
+You can interface with the router immediately:
+```bash
+curl -X POST http://localhost:8000/route \
+     -H "Content-Type: application/json" \
+     -d '{"query": "I need help resetting my password"}'
+```
+
+### Method 2: Standard Python Package
+
+To embed SynaptoRoute natively into your existing Python pipelines, install directly from pip (or via git if testing the latest main branch):
+
+```bash
+pip install synaptoroute
+```
+
+---
+
+## Quick Start Guide
+
+```python
+import asyncio
+from synaptoroute.router import AdaptiveRouter
+from synaptoroute.encoder import Encoder
+from synaptoroute.storage import SQLiteStorage
+from synaptoroute.models import Route
+
+async def main():
+    # 1. Initialize Components
+    encoder = Encoder()
+    storage = SQLiteStorage("data/memory.sqlite")
+    router = AdaptiveRouter(encoder, storage)
+    
+    # 2. Define Routes
+    billing_route = Route(
+        name="billing", 
+        utterances=["I need a refund", "Where is my receipt?", "Cancel my subscription"]
+    )
+    router.add_route(billing_route)
+    
+    # 3. Start the Background Batching Worker
+    await router.start()
+    
+    # 4. Execute Async Queries
+    result = await router.aquery("How do I get my money back?")
+    print(f"Matched Intent: {result.name}") # Output: billing
+    
+    # 5. Graceful Shutdown
+    await router.stop()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## System Limitations
+
+**Horizontal Scaling (Kubernetes Split-Brain)**  
+SynaptoRoute relies on a highly optimized, local in-memory NumPy matrix to achieve its microsecond latency. As such, it is structurally bound to a single node. If deployed across multiple load-balanced Kubernetes pods, a hot-reload request hitting Pod A will update Pod A's local memory, but Pod B will remain unaware. Scaling horizontally requires implementing an external event bus (e.g., Redis Pub/Sub) to broadcast memory invalidation events across the cluster.
+
+---
+
+## Community & Contributing
+
+We welcome contributions of all sizes from the open-source community! 
+
+- **Contributing:** Please read our [Contributing Guidelines](CONTRIBUTING.md) to learn how to set up your development environment, run the test suite, and submit Pull Requests.
+- **Code of Conduct:** We are committed to fostering a welcoming environment. Please review our [Code of Conduct](CODE_OF_CONDUCT.md).
+- **Issues:** If you discover a bug or have a feature request, please [open an issue](https://github.com/sitanshukr08/SynaptoRoute/issues).