Metadata-Version: 2.4
Name: openbalancer
Version: 1.5.0
Summary: Intelligent Asynchronous Reverse Proxy & High-Performance Load Balancer for AI Clusters and APIs
Author-email: INCONTROL PLUS EOOD <support@openbalancer.com>
License-Expression: MIT
Project-URL: Homepage, https://www.openbalancer.com
Project-URL: Documentation, https://www.openbalancer.com/docs
Project-URL: Repository, https://github.com/incontrolplus/openbalancer
Project-URL: Issues, https://github.com/incontrolplus/openbalancer/issues
Project-URL: Changelog, https://github.com/incontrolplus/openbalancer/releases
Keywords: loadbalancer,reverse-proxy,asyncio,ai-gateway,llm-streaming,sse,websockets,devops
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Classifier: Topic :: Internet :: Proxy Servers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ⚡ OpenBalancer & INCONTROL PLUS Ecosystem

<p align="center">
  <a href="README.bg.md"><b>🇧🇬 Българска версия (Bulgarian Version)</b></a> | 
  <a href="README.md"><b>🇬🇧 English Version</b></a>
</p>

[![CI](https://github.com/incontrolplus/openbalancer/actions/workflows/ci.yml/badge.svg)](https://github.com/incontrolplus/openbalancer/actions/workflows/ci.yml)
[![Docker Build](https://github.com/incontrolplus/openbalancer/actions/workflows/docker.yml/badge.svg)](https://github.com/incontrolplus/openbalancer/actions/workflows/docker.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12-3776AB?logo=python&logoColor=white)](core/openbalancer.py)
[![Cloudflare Pages](https://img.shields.io/badge/Cloudflare%20Pages-Live-F38020?logo=cloudflare&logoColor=white)](https://openbalancer.pages.dev)
[![Enterprise Support](https://img.shields.io/badge/Enterprise-SLA%20Available-10b981)](https://www.openbalancer.com/#enterprise)
[![Operated by](https://img.shields.io/badge/Operated%20by-INCONTROL%20PLUS-3b82f6)](https://www.openbalancer.com)

**OpenBalancer** is a modern, high-performance, asynchronous load balancer, reverse proxy, and open-source infrastructure suite engineered by **INCONTROL PLUS ЕООД**. Built for AI inference clusters, high-throughput microservices, and mission-critical API routing.

---

## 🏗️ Repository Architecture

```
openbalancer/
├── README.md                                # Root Documentation (English)
├── README.bg.md                             # Root Documentation (Bulgarian)
├── LICENSE                                  # MIT Open Source License
├── core/                                    # OpenBalancer Core Engine & Testing
│   ├── openbalancer.py                      # Asynchronous Python Load Balancer & Proxy
│   ├── config.json                          # Sample Node & Strategy Configuration
│   ├── Dockerfile                           # Production Alpine Docker Image
│   ├── docker-compose.yml                   # Cluster Sandbox with Upstream Mocks
│   ├── test_balancer.py                     # Automated Verification Test Suite
│   ├── awesome-selfhosted-pr.md             # Awesome-Selfhosted PR Submission
│   └── README.md                            # Engine-specific Documentation
├── website/                                 # Official Website (Cloudflare Pages)
│   ├── index.html                           # Landing Page with Interactive Traffic Simulator
│   ├── css/style.css                        # Modern Vanilla CSS Theme & Animations
│   ├── js/main.js                           # Real-time Balancer Visualizer Logic
│   ├── terms.html                           # Terms of Service
│   ├── privacy.html                         # GDPR-Compliant Privacy Policy
│   ├── refunds.html                         # SLA Credit & Refund Policy
│   ├── contact.html                         # Impressum & Corporate Verification
│   └── _headers                             # Security Headers (CSP, HSTS, X-Frame)
├── compliance/                              # Legal Framework & Commercial Contracts
│   ├── Brand_Isolation_Legal_Matrix.md      # 3-Tier Corporate & Anti-Fronting Hierarchy
│   ├── B2B_Master_Services_Agreement_Template.md # Enterprise B2B Contract Template
│   ├── B2B_Statement_Of_Work_SLA_Template.md     # 99.9% Uptime SLA Specification
│   ├── Stripe_Onboarding_Step_by_Step_Guide.md  # Stripe KYB & Approval Guide
│   └── FinansProtect_B2B_Billing_Workflow.md    # Third-party Client Invoicing Flow
├── cloudflare/                              # Zero-Cost Edge Hosting & DNS
│   └── Cloudflare_Pages_and_DNS_Deployment_Guide.md # CI/CD & Custom Domain Setup
└── social/                                  # Brand Visibility & Digital Footprint
    ├── LinkedIn_Company_Page_Copy.md        # INCONTROL PLUS Company Profile
    ├── LinkedIn_Product_Page_Copy.md        # OpenBalancer Showcase Profile
    ├── Twitter_Launch_Strategy.md           # Announcement & Feature Threads
    └── Discord_Community_Setup.md           # Developer & Support Server Structure
```

---

## 🌟 Core Engine Features

* **⚡ Non-Blocking Async I/O**: Pure Python async proxy with sub-millisecond overhead (p50 < 4.7ms).
* **🧠 AI & LLM Inference Aware**: Zero-buffer chunked transfers and SSE (Server-Sent Events) passthrough.
* **🛡️ Active Health Checks & Circuit Breaker**: Automated background health monitoring with automatic traffic draining and failover.
* **🎯 Routing Strategies**: `round_robin`, `weighted_round_robin`, `least_connections`, `least_latency`, `ip_hash`, `power_of_two`.
* **📊 Dual Observability API**:
  * JSON Status Endpoint: `/openbalancer/status`
  * Prometheus Plaintext Metrics Exporter: `/metrics`
* **📈 Official Grafana Dashboard**: Ready-to-import template in `telemetry/grafana-openbalancer-dashboard.json`.
* **🐳 Docker & Kubernetes Ready**: Ultralight multi-arch container footprint (<45MB).

---

## 🚀 Quickstart

### 0. Install via PyPI (Recommended for CLI & Python API)
```bash
pip install openbalancer

# Launch interactive demo sandbox with 3 mock backends:
openbalancer demo

# Or start with custom configuration:
openbalancer start -c config.json
```

### 1. Instant Interactive Demo Sandbox (Zero Configuration)
Launch OpenBalancer together with 3 built-in mock upstream backends (ALPHA, BETA, GAMMA) in a single command:
```bash
python3 core/openbalancer.py demo
# Or on custom port:
python3 core/openbalancer.py demo -p 8088
```

Now in another terminal:
```bash
# Send load balanced requests across ALPHA, BETA, GAMMA:
curl -s http://localhost:8088/

# Inspect real-time cluster telemetry:
curl -s http://localhost:8088/openbalancer/status | jq .
curl -s http://localhost:8088/metrics
```

### 2. Standard Production Mode (Custom Upstream Targets)
```bash
# Validate your configuration
python3 core/openbalancer.py validate -c core/config.json

# Start OpenBalancer service
python3 core/openbalancer.py start -c core/config.json
```

Or 1-line curl installer:
```bash
curl -fsSL https://www.openbalancer.com/install.sh | bash
```

### 3. Run Turnkey Docker Mesh (OpenBalancer + Prometheus + Grafana)
```bash
docker compose -f docker-compose.mesh.yml up -d
```

### 4. Run High-Concurrency Benchmark (5,300+ RPS)
```bash
python3 benchmark/run_benchmark.py
```
View full benchmark results: [benchmark/BENCHMARK_RESULTS.md](benchmark/BENCHMARK_RESULTS.md).

### 3. Run Automated Unit & Verification Tests
```bash
python3 -m unittest discover -s tests -p "test_*.py" -v
python3 core/test_balancer.py
```

### 4. Prometheus & Grafana Monitoring
OpenBalancer exports standard Prometheus metrics on `/metrics`:
```bash
curl http://localhost:8088/metrics
curl http://localhost:8088/openbalancer/status
```
Import [`telemetry/grafana-openbalancer-dashboard.json`](telemetry/grafana-openbalancer-dashboard.json) into Grafana for real-time throughput and health telemetry.

---

## 📚 Technical Documentation

Explore in-depth documentation in [`docs/`](docs/):
* [Architecture & Event Loop](docs/architecture.md)
* [Routing Algorithms](docs/algorithms.md)
* [Configuration Schema](docs/configuration.md)
* [Telemetry & Prometheus API](docs/telemetry-api.md)
* [Production Deployment](docs/deployment.md)

---

## 🏢 Enterprise Support & SLAs

OpenBalancer is maintained and commercially operated by **INCONTROL PLUS ЕООД** (Sofia, Bulgaria). We offer dedicated enterprise services:
* **99.9% Guaranteed Monthly Uptime SLA**
* **Sub-15 Minute Incident Response**
* **Net-14 Corporate Invoicing & Stripe Card Payments**
* **Custom AI Routing & Load Balancer Module Engineering**
* **Managed Turnkey Infrastructure Deployments**

For inquiries, contact: **support@openbalancer.com** or visit **[https://www.openbalancer.com](https://www.openbalancer.com)**.

---

## 📜 License & Compliance

* **Software License**: Distributed under the [MIT License](LICENSE).
* **Corporate Operator**: INCONTROL PLUS ЕООД, Sofia, Bulgaria (UIC 204882190).
* **Compliance**: Full GDPR, Stripe KYB, and EU consumer protection alignment.
