Skip to content

proofbyhuman/ghost_balancer

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ghost Balancer v1.0

Dynamic Identity System for Multi-Region Cloud Infrastructure
Adaptive load balancing via exponential decay scoring and tick-based trust recovery.

License: MIT Python Status


What is Ghost Balancer?

Ghost Balancer is a lightweight, dependency-free load balancing algorithm that assigns a dynamic trust score (Ghost Score) to each region or cluster in a multi-region cloud deployment. Instead of treating all regions as equally reliable at all times, it continuously re-evaluates confidence based on recent performance history — and routes traffic proportionally.

The system is designed to:

  • Survive regional failures without manual intervention
  • Recover automatically as a degraded region stabilizes
  • Never completely exclude a region (configurable floor), preserving identity even under stress
  • Run in-process with no external dependencies, sidecars, or control planes

How it works

Each region maintains a sliding window of the last 30 performance events (high = success, low = failure). The Ghost Score is computed using exponential decay weighting — recent events matter more than old ones — plus a 2.5× recovery multiplier that makes successes count more than failures, creating an asymmetric trust curve that favors stability.

Ghost Score = sigmoid( Σ low_weights  −  Σ high_weights × 2.5 )
            = 1 / (1 + e^balance)
            ∈ [0.1, 1.0]

Traffic is routed via weighted random selection across all active regions. A region in crisis receives proportionally less traffic — but never zero, preserving its ability to recover.

Lifecycle phases (150k tick stress test)

Phase Ticks LATAM uptime Behavior
Normal 0 – 50k 95% Balanced distribution across all regions
Crisis 50k – 100k 5% Ghost Score collapses → traffic shifts to USA + EUROPA
Recovery 100k – 150k 95% Score rebuilds gradually via tick accumulation

Results

============================================================
 FINAL REPORT: COMPLETE LIFECYCLE (150K TICKS)
============================================================
Region  LATAM  | Traffic: 27.00% | Final Score: 0.9742
Region   USA   | Traffic: 36.67% | Final Score: 0.9746
Region EUROPA  | Traffic: 36.34% | Final Score: 0.9985
GLOBAL SUCCESS RATE: 92.00%
============================================================

Key observations:

  • EUROPA scored highest (0.9985) because it never experienced a crisis — its event window is clean
  • LATAM recovered to 0.9742 after the crisis, statistically matching USA but carrying residual decay memory — correct behavior for production infrastructure
  • The 92% global success rate reflects intelligent mitigation: a region at 5% uptime for 1/3 of runtime was absorbed without catastrophic degradation

Quick start

from ghost_balancer import GhostBalancerMIT

lb = GhostBalancerMIT(regions=["LATAM", "USA", "EUROPA"], decay_rate=0.2)

# Record a successful event
lb.record_performance("LATAM", is_ok=True)

# Record a failure
lb.record_performance("LATAM", is_ok=False)

# Route the next request
region, score = lb.route()
print(f"→ {region} (score: {score:.4f})")

# Inspect current scores
for r in lb.regions:
    print(f"{r}: {lb.get_score(r):.4f}")

API reference

GhostBalancerMIT(regions, decay_rate=0.2)

Parameter Type Default Description
regions list[str] required Region/cluster names
decay_rate float 0.2 Cooling speed. Higher = more sensitive to recent events

.record_performance(region, is_ok)

Records a performance event for a region. Maintains a sliding window of 30 events per region for memory efficiency.

.get_score(region) → float

Returns the current Ghost Score for a region, in the range [0.1, 1.0]. A score of 1.0 means full trust; 0.1 is the minimum floor (identity preservation).

.route() → tuple[str, float]

Selects a region via weighted random selection based on current Ghost Scores. Returns the chosen region name and its score at the time of selection.


Configuration guide

# More sensitive — reacts faster to failures, recovers faster too
lb = GhostBalancerMIT(regions=[...], decay_rate=0.5)

# More conservative — smooths out transient spikes, slower to penalize
lb = GhostBalancerMIT(regions=[...], decay_rate=0.05)

Choosing decay_rate:

Value Behavior Use case
0.05 – 0.1 Slow reaction, long memory Stable environments, batch workloads
0.2 Balanced (default) General-purpose web infrastructure
0.4 – 0.6 Fast reaction, short memory Real-time systems, strict SLA requirements

Running the stress test

python ghost_balancer.py

This runs the full 150k tick lifecycle simulation (Normal → Crisis → Recovery) and prints the final report. Expected runtime: under 5 seconds.


Design decisions

Why exponential decay instead of a rolling average?
A simple rolling average treats a failure 30 events ago the same as one 2 events ago. Exponential decay lets recent behavior dominate without discarding historical context entirely.

Why a 2.5× recovery multiplier?
Pure symmetric scoring makes recovery as slow as degradation, which is too conservative for cloud infrastructure. The multiplier creates an asymmetric curve: a region that starts performing well should regain trust meaningfully faster than it lost it — but not instantly.

Why a floor of 0.1 instead of 0?
A score of 0 means permanent exclusion with no path back. The floor ensures every region always receives a trickle of traffic, which serves two purposes: it provides live telemetry for recovery detection, and it preserves the region's identity in the routing pool.


Roadmap

  • Adaptive window size (expand during detected crisis phases)
  • Dynamic decay rate per region state (Normal / Degraded / Recovering)
  • Re-admission hysteresis (require N consecutive successes before full re-entry)
  • Configurable score floor as a function of available region count
  • Prometheus metrics export
  • Async-compatible route() for use in asyncio services

License

MIT — see LICENSE for details.


Built by Ramiro · Ghost Balancer v1.0

About

git init ghost-balancer cd ghost-balancer # copiás los archivos acá git add . git commit -m "feat: Ghost Balancer v1.0 — dynamic identity system" gh repo create ghost-balancer --public --push

Resources

License

Stars

0 stars

Watchers

0 watching

Forks

Releases

No releases published

Packages

 
 
 

Contributors