Metadata-Version: 2.4
Name: nexus_gateway
Version: 3.1.6
Summary: High-performance AI infrastructure with semantic caching and sovereign governance.
Home-page: https://nexus-gateway.org
Author: Sunny Anand
Author-email: asunny583@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: rich>=10.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🐍 Nexus Gateway Python SDK

> **Sovereign AI Infrastructure for the Modern Edge**  
> One line of code to reduce LLM latency by **95%**, costs by **90%**, and enforce deterministic governance at the edge.

---

##  Key Metrics at a Glance

[![PyPI version](https://badge.fury.io/py/nexus-gateway.svg)](https://badge.fury.io/py/nexus-gateway)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Infrastructure Status](https://img.shields.io/badge/Infrastructure-v3.1.0_Stable-00d27a?style=flat-square)](https://nexus-gateway.org)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-0066ff?style=flat-square)](https://www.python.org)
[![Latency](https://img.shields.io/badge/Latency-5ms-ff6b6b?style=flat-square)](https://nexus-gateway.org)

---

##  Why Nexus Gateway?

### Real-World Impact

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| **API Latency** | 1200ms+ | 5ms | **99.6%** ↓ |
| **Cost per Call** | Full Price | Near Zero | **90%** ↓ |
| **Failover Time** | Single Point | <100ms | **Self-Healing** |
| **Data Privacy** | None | AES-256 | **Enterprise-Grade** |

---

##  Core Features

###  **Semantic Caching (Layer 0 & 1)**
Intelligent hybrid caching with Redis & Pinecone. Get responses in **<5ms** by eliminating redundant API calls.
```
Cache Hit: 5ms 
Network Round Trip: 1200ms 
Savings per hit: 100% 
```

###  **DeepSeek Native Streaming**
Full support for OpenAI-compatible reasoning models with **Thinking Tokens** streaming directly to your terminal.

### 🔀 **Adaptive Universal Router**
Single API signature, infinite model combinations:
- **Groq** — Lightning-fast inference
- **Google Gemini** — Multimodal powerhouse  
- **OpenAI** — Production reliability
- **Anthropic Claude** — Reasoning excellence

Automatic failover with **self-healing load balancing**.

###  **Sovereign Shield (v3.0)**
Enterprise-grade governance at the edge:
- ✅ PII redaction before API calls
- ✅ Deterministic data governance
- ✅ AES-256 encryption
- ✅ Audit logging
- ✅ Compliance-ready

### 💎 **Multi-Provider BYOK**
Bring Your Own Key to bypass Nexus credits entirely. Use provider billing directly with **zero overhead**.

---

##  Quick Start

### 1️⃣ Installation

```bash
pip install nexus-gateway
```

### 2️⃣ Get Your API Key
Head to **[Nexus Dashboard](https://www.nexus-gateway.org/dashboard)** and grab your provisioned key.

### 3️⃣ Initialize the Client

```python
from nexus_gateway import NexusClient

client = NexusClient(api_key="nk-your-key-here")
```

### 4️⃣ Start Streaming (Your First Call)

```python
# Works with DeepSeek, Groq, Gemini, Claude, GPT-4... 
# Same syntax. Zero friction.

stream = client.chat(
    model="deepseek-r1",
    message="Explain the architecture of a multi-currency reconciliation engine.",
    stream=True
)

for token in stream:
    print(token, end="", flush=True)
```

---

##  Usage Examples

### Real-Time Streaming with Auto-Fallback

```python
# Automatic failover if primary model is unavailable
response = client.chat(
    model="gpt-4o",
    message="Analyze this market trend...",
    stream=True,
    fallback_model="claude-3-5-sonnet-latest"  # Automatic pivot
)

for chunk in response:
    print(chunk, end="", flush=True)
```

### BYOK Mode (Zero-Cost Scaling)

```python
# Skip Nexus credits entirely. Use your own provider API keys.

response = client.chat(
    model="gpt-4o",
    message="Summarize legal implications of AI governance.",
    provider_key="sk-your-openai-key",  
    stream=False
)

print(response)
```

### Semantic Caching in Action

```python
# First call: Hits the API, caches the embedding
response1 = client.chat(
    model="llama-3.3-70b",
    message="What is machine learning?",
    cache=True  # Enable semantic caching
)

# Second call: Semantically similar query
# ⚡ Cache hit in 5ms! No API call needed.
response2 = client.chat(
    model="llama-3.3-70b",
    message="Define machine learning for beginners.",
    cache=True
)
```

### Sovereign Shield (Data Privacy)

```python
# Automatic PII redaction before API calls

response = client.chat(
    model="gpt-4o",
    message="My email is john@example.com. Help me with...",
    sovereign_shield=True 
)
# → John's email never leaves your infrastructure
```

---

##  Interactive CLI Tool

Launch the Nexus Sovereign Shell:

```bash
nexus
```

### Available Commands

| Command | Example | Purpose |
|---------|---------|---------|
| `/model [name]` | `/model r1` | Switch inference engine on-the-fly |
| `/key [sk-...]` | `/key sk-proj-123abc` | Inject BYOK provider credentials |
| `/cache [on/off]` | `/cache on` | Toggle semantic caching |
| `/shield [on/off]` | `/shield on` | Toggle PII redaction |
| `/history` | `/history` | View session messages |
| `/clear` | `/clear` | Wipe session history |
| `/exit` | `/exit` | Close secure data plane |

**Example Session:**
```
Nexus> /model gpt-4o
✓ Switched to gpt-4o

Nexus> What are the top 3 AI trends in 2025?
[Response streaming...]

Nexus> /key sk-your-openai-key
✓ BYOK credentials loaded. Nexus credits bypassed.

Nexus> /shield on
✓ Sovereign Shield enabled. PII redaction active.
```

---

##  Supported Infrastructure Engines

Deploy across the world's fastest inference providers with zero code changes. Nexus handles routing, failover, and optimization automatically.

| Provider | Engine Tier | Core Models | Specialty |
|----------|-------------|------------|-----------|
| **DeepSeek** | Reasoning (R1) | `deepseek-r1`, `deepseek-v3` | 🧠 Extended Thinking, Math & Logic |
| **Groq** | Ultra-Fast (Llama) | `llama-3.3-70b-versatile`, `llama-3.1-8b-instant` | ⚡ Sub-100ms Latency, Token Streaming |
| **Google** | Adaptive (Gemini) | `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash` | 🎬 Multimodal, Vision, Audio |
| **Anthropic** | Reasoning (Claude) | `claude-3-5-sonnet-latest`, `claude-3-opus-20240229` | 🔬 Constitutional AI, Lengthy Context |
| **OpenAI** | Standard (GPT) | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` | 🚀 Industry Standard, Production Proven |

### Provider Decision Matrix

```
Speed Champion:        Groq (llama-3.3-70b)          → <100ms
Reasoning Champion:    DeepSeek R1                   → Advanced problem-solving
Vision Champion:       Google Gemini 2.0             → Image/Video understanding
Cost Champion:         OpenAI gpt-4o-mini            → Budget-friendly
Reliability Champion:  OpenAI gpt-4o                 → Enterprise SLA
```

---

##  Authentication & Security

### Step 1: Register
Head to **[Nexus Gateway Dashboard](https://www.nexus-gateway.org/dashboard)** and sign up.

### Step 2: Create API Key
Generate a provisioned key (`nk-...`) from your dashboard.

### Step 3: Store Securely
```bash
# Set as environment variable (recommended)
export NEXUS_API_KEY="nk-your-key-here"
```

### Step 4: Initialize
```python
from nexus_gateway import NexusClient
import os

client = NexusClient(api_key=os.getenv("NEXUS_API_KEY"))
```

### Security Features
-  **AES-256 Encryption** at rest and in transit
-  **PII Redaction** before provider APIs
-  **Audit Logging** for compliance
-  **BYOK Support** for zero trust architectures
-  **Key Rotation** friendly

---

##  Performance Benchmarks

### Latency Comparison

```
Nexus Gateway (Cache Hit):        5ms    ████░░░░░░░░░░░░░░░░░░
OpenAI SDK (Network):          1200ms    ████████████████████████
Improvement:                   99.6%    
```

### Cost Reduction

```
Standard Provider Calls:        $0.001/call
Nexus Cached Calls:            $0.000/call  (after first hit)
Annual Savings (10M calls):    $10,000     
```

---

## 🎓 Documentation & Resources

| Resource | Link |
|----------|------|
|  **Full Documentation** | [nexus-gateway.org/docs](https://nexus-gateway.org/docs) |
|  **Interactive Dashboard** | [nexus-gateway.org/dashboard](https://www.nexus-gateway.org/dashboard) |
|  **GitHub Issues** | [ANANDSUNNY0899/NexusGateway](https://github.com/ANANDSUNNY0899/NexusGateway) |
|  **Report a Bug** | [Issues](https://github.com/ANANDSUNNY0899/NexusGateway/issues) |
|  **Request Features** | [Discussions](https://github.com/ANANDSUNNY0899/NexusGateway/discussions) |

---

##  Community & Support

- **Email Support**: support@nexus-gateway.org

---

## 📄 License & Attribution

Licensed under the **MIT License** — free for commercial and personal use.

**© 2025 Sunny Anand**  
[Mission Control](https://www.nexus-gateway.org/dashboard) · [Docs](https://nexus-gateway.org/docs) · [GitHub](https://github.com/ANANDSUNNY0899/NexusGateway)

---

##  Getting Started Right Now

```python
# 3 lines to production
from nexus_gateway import NexusClient
client = NexusClient(api_key="nk-your-key")
print(client.chat(model="gpt-4o", message="Hello, Nexus!"))
```

**Ready to reduce latency by 95%?** [Get your API key →](https://www.nexus-gateway.org/dashboard)

---

<div align="center">

**Made with 🔥 by SUNNY ANAND**

*Sovereign AI Infrastructure for developers who demand performance, privacy, and control.*

[⭐ Star us on GitHub](https://github.com/ANANDSUNNY0899/NexusGateway) 
</div>
