neuralbridge-sdk 0.1.0__tar.gz

neuralbridge_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NeuralBridge Team
+
+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.

neuralbridge_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: neuralbridge-sdk
+Version: 0.1.0
+Summary: Self-healing decision engine for AI API calls - diagnose, strategize, recover automatically
+Author-email: NeuralBridge Team <team@neuralbridge.dev>
+License: MIT
+Keywords: ai,api,self-healing,recovery,openai,llm,fallback
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Requires-Dist: requests>=2.28.0
+Dynamic: license-file
+
+# NeuralBridge SDK
+
+Self-healing decision engine for AI API calls. Drop-in replacement for `openai.OpenAI` with automatic fault diagnosis, cascade recovery, and transparent model switching.
+
+## Install
+
+```bash
+pip install neuralbridge
+```
+
+## Quick Start
+
+```python
+from neuralbridge import NeuralBridge
+
+client = NeuralBridge(
+    api_key="sk-xxx",
+    primary_model="gpt-4o",
+    fallback_models=["gpt-4o-mini"]
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+```
+
+## 4-Layer Cascade Recovery
+
+| Layer | Strategy | When |
+|-------|----------|------|
+| LAYER 0 | Predictive model switch | Same fault pattern seen 3+ times |
+| LAYER 1 | Smart retry + immediate model switch | Timeout, rate limit |
+| LAYER 2 | Fault-model mapping switch | Model not found, internal error |
+| LAYER 3 | Request degradation | Context too long, content blocked |
+
+## License
+
+MIT

neuralbridge_sdk-0.1.0/README.md

@@ -0,0 +1,40 @@
+# NeuralBridge SDK
+
+Self-healing decision engine for AI API calls. Drop-in replacement for `openai.OpenAI` with automatic fault diagnosis, cascade recovery, and transparent model switching.
+
+## Install
+
+```bash
+pip install neuralbridge
+```
+
+## Quick Start
+
+```python
+from neuralbridge import NeuralBridge
+
+client = NeuralBridge(
+    api_key="sk-xxx",
+    primary_model="gpt-4o",
+    fallback_models=["gpt-4o-mini"]
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+```
+
+## 4-Layer Cascade Recovery
+
+| Layer | Strategy | When |
+|-------|----------|------|
+| LAYER 0 | Predictive model switch | Same fault pattern seen 3+ times |
+| LAYER 1 | Smart retry + immediate model switch | Timeout, rate limit |
+| LAYER 2 | Fault-model mapping switch | Model not found, internal error |
+| LAYER 3 | Request degradation | Context too long, content blocked |
+
+## License
+
+MIT

neuralbridge_sdk-0.1.0/neuralbridge/__init__.py

@@ -0,0 +1,7 @@
+"""NeuralBridge - Self-healing decision engine for AI API calls."""
+from .adapters.openai_adapter import NeuralBridge
+from .core.engine import FlywheelEngine
+from .core.types import RecoveryRecord, ModelPerformance, CascadeLevel
+
+__version__ = "0.1.0"
+__all__ = ["NeuralBridge", "FlywheelEngine", "RecoveryRecord", "ModelPerformance", "CascadeLevel"]

neuralbridge_sdk-0.1.0/neuralbridge/adapters/__init__.py

@@ -0,0 +1,4 @@
+"""NeuralBridge Adapters Package"""
+from .openai_adapter import NeuralBridge
+
+__all__ = ["NeuralBridge"]

neuralbridge_sdk-0.1.0/neuralbridge/adapters/openai_adapter.py

@@ -0,0 +1,135 @@
+"""NeuralBridge OpenAI Adapter - Drop-in replacement for openai.OpenAI"""
+import time
+from typing import List, Dict, Any, Optional
+
+from ..core.engine import FlywheelEngine
+
+
+class ChatCompletions:
+    """Chat completions interface compatible with OpenAI API."""
+
+    def __init__(self, engine: FlywheelEngine):
+        self.engine = engine
+
+    def create(self, model: str = None, messages: List[Dict[str, str]] = None, **kwargs):
+        """Create chat completion with automatic fault recovery."""
+        if messages is None:
+            raise ValueError("messages parameter is required")
+
+        model = model or self.engine.primary_model
+        
+        # First attempt with original model
+        response, latency = self.engine._execute_request(messages, model, **kwargs)
+
+        if self.engine._check_success(response):
+            self.engine.record_model_result(model, True, latency)
+            return self._format_response(response["response"])
+
+        # Cascade recovery
+        self.engine.record_model_result(model, False, latency)
+        recovered_response, record = self.engine.cascade_recover(
+            initial_error=response,
+            messages=messages,
+            original_model=model,
+            **kwargs
+        )
+
+        if record.recovered:
+            return self._format_response(recovered_response["response"])
+        else:
+            raise Exception(f"Recovery failed after {record.total_attempts} attempts. "
+                          f"Fault: {record.fault_type}, Strategy: {record.strategy_used}")
+
+    def _format_response(self, response_data: Dict) -> Any:
+        """Format response to match OpenAI API structure."""
+        class Choice:
+            def __init__(self, index, message, finish_reason):
+                self.index = index
+                self.message = message
+                self.finish_reason = finish_reason
+
+        class Message:
+            def __init__(self, role, content):
+                self.role = role
+                self.content = content
+
+        class Usage:
+            def __init__(self, prompt_tokens, completion_tokens, total_tokens):
+                self.prompt_tokens = prompt_tokens
+                self.completion_tokens = completion_tokens
+                self.total_tokens = total_tokens
+
+        class ChatCompletion:
+            def __init__(self, data):
+                self.id = data.get("id", "")
+                self.object = "chat.completion"
+                self.created = int(time.time())
+                self.model = data.get("model", "")
+                choices_data = data.get("choices", [])
+                self.choices = []
+                for c in choices_data:
+                    msg = c.get("message", {})
+                    message_obj = Message(msg.get("role", "assistant"), msg.get("content", ""))
+                    choice_obj = Choice(c.get("index", 0), message_obj, c.get("finish_reason", "stop"))
+                    self.choices.append(choice_obj)
+                usage_data = data.get("usage", {})
+                self.usage = Usage(
+                    usage_data.get("prompt_tokens", 0),
+                    usage_data.get("completion_tokens", 0),
+                    usage_data.get("total_tokens", 0)
+                )
+
+        return ChatCompletion(response_data)
+
+
+class NeuralBridge:
+    """
+    Self-healing decision engine for AI API calls.
+    Drop-in replacement for openai.OpenAI with automatic fault diagnosis and cascade recovery.
+    """
+
+    def __init__(self, api_key: str, base_url: str = "https://api.openai.com/v1",
+                 primary_model: str = "gpt-4o", fallback_models: Optional[List[str]] = None):
+        """
+        Initialize NeuralBridge client.
+
+        Args:
+            api_key: API key for authentication
+            base_url: Base URL for API endpoint
+            primary_model: Primary model to use (default: gpt-4o)
+            fallback_models: List of fallback models (default: ["gpt-4o-mini"])
+        """
+        self.engine = FlywheelEngine(
+            api_key=api_key,
+            base_url=base_url,
+            primary_model=primary_model,
+            fallback_models=fallback_models
+        )
+        self.chat = type('Chat', (), {'completions': ChatCompletions(self.engine)})()
+
+    def get_recovery_stats(self) -> Dict[str, Any]:
+        """Get statistics about recovery operations."""
+        return {
+            "total_recovery_attempts": len(self.engine.recovery_records),
+            "successful_recoveries": sum(1 for r in self.engine.recovery_records if r.recovered),
+            "diagnosis_stats": dict(self.engine.diagnosis_stats),
+            "model_performance": {
+                model: {
+                    "success_rate": perf.success_rate,
+                    "avg_latency_ms": perf.avg_latency_ms,
+                    "total_calls": perf.success_count + perf.failure_count
+                }
+                for model, perf in self.engine.model_performance.items()
+            }
+        }
+
+    def clear_history(self):
+        """Clear recovery history and reset performance metrics."""
+        self.engine.recovery_records.clear()
+        self.engine.diagnosis_stats.clear()
+        for perf in self.engine.model_performance.values():
+            perf.success_count = 0
+            perf.failure_count = 0
+            perf.total_latency_ms = 0.0
+            perf.timeout_count = 0
+            perf.rate_limit_count = 0

neuralbridge_sdk-0.1.0/neuralbridge/core/__init__.py

@@ -0,0 +1,8 @@
+"""NeuralBridge Core Package"""
+from .engine import FlywheelEngine
+from .types import (FaultCategory, FaultSeverity, CascadeLevel, ModelPerformance,
+                    RecoveryRecord, AdaptiveTimeout, DynamicBackoff, FaultPredictor, RequestProfile)
+
+__all__ = ["FlywheelEngine", "FaultCategory", "FaultSeverity", "CascadeLevel",
+           "ModelPerformance", "RecoveryRecord", "AdaptiveTimeout",
+           "DynamicBackoff", "FaultPredictor", "RequestProfile"]

neuralbridge_sdk-0.1.0/neuralbridge/core/engine.py

@@ -0,0 +1,362 @@
+"""NeuralBridge Core - Self-healing Engine (V8.2)"""
+import hashlib
+import re
+import time
+import threading
+import requests
+from collections import defaultdict, deque
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple, Any
+
+from .types import (ModelPerformance, RecoveryRecord, AdaptiveTimeout, DynamicBackoff, FaultPredictor, RequestProfile)
+from .strategies import CASCADE_STRATEGIES, DEFAULT_CASCADE, FAULT_MODEL_MAPPING
+
+
+class FlywheelEngine:
+    """NeuralBridge self-healing decision engine - 4-layer cascade recovery."""
+
+    def __init__(self, api_key: str, base_url: str = "https://api.openai.com/v1",
+                 models: Optional[List[str]] = None, primary_model: str = "gpt-4o",
+                 fallback_models: Optional[List[str]] = None):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.primary_model = primary_model
+        self.fallback_models = fallback_models or ["gpt-4o-mini"]
+        self.all_models = [primary_model] + self.fallback_models
+        self.model_performance: Dict[str, ModelPerformance] = {m: ModelPerformance(model_name=m) for m in self.all_models}
+        self.response_time_history: deque = deque(maxlen=50)
+        self.dynamic_backoff = DynamicBackoff()
+        self.fault_predictor = FaultPredictor()
+        self.adaptive_timeout = AdaptiveTimeout()
+        self.recovery_records: List[RecoveryRecord] = []
+        self.lock = threading.Lock()
+        self.diagnosis_stats: Dict[str, int] = defaultdict(int)
+        self._timeout_consecutive_failures = 0
+
+    def diagnose(self, error_msg=None, status_code=None, response_data=None):
+        fault_type, confidence = "internal_error", 0.5
+        
+        if error_msg:
+            el = str(error_msg).lower()
+            if any(p in el for p in ["timeout", "timed out", "timed_out", "connection timeout"]):
+                fault_type, confidence = "connection_timeout", 0.95
+            elif any(p in el for p in ["model", "invalid", "not found", "does not exist"]):
+                fault_type, confidence = "model_not_found", 0.90
+            elif any(p in el for p in ["rate limit", "rate_limit", "429", "too many requests"]):
+                fault_type, confidence = "rate_limit_exceeded", 0.95
+            elif any(p in el for p in ["context", "length", "too long", "token limit", "exceeded"]):
+                fault_type, confidence = "context_length_exceeded", 0.85
+            elif any(p in el for p in ["overload", "503", "unavailable"]):
+                fault_type, confidence = "service_overloaded", 0.90
+            elif any(p in el for p in ["safety", "blocked", "content", "filter"]):
+                fault_type, confidence = "content_safety_blocked", 0.80
+            elif any(p in el for p in ["401", "unauthorized", "api key", "invalid key"]):
+                fault_type, confidence = "invalid_api_key", 0.95
+            elif any(p in el for p in ["500", "internal"]):
+                fault_type, confidence = "internal_error", 0.85
+
+        if status_code:
+            sc_map = {408: ("connection_timeout", 0.90), 429: ("rate_limit_exceeded", 0.95),
+                      503: ("service_overloaded", 0.90), 401: ("invalid_api_key", 0.95)}
+            if status_code in sc_map:
+                ft, c = sc_map[status_code]
+                fault_type, confidence = ft, max(confidence, c)
+            elif status_code == 400:
+                if "model" in str(error_msg or "").lower():
+                    fault_type, confidence = "model_not_found", max(confidence, 0.85)
+                elif "context" in str(error_msg or "").lower():
+                    fault_type, confidence = "context_length_exceeded", max(confidence, 0.85)
+
+        self.diagnosis_stats[fault_type] += 1
+        return fault_type, confidence
+
+    def select_best_model(self, fault_type=None, prefer_speed=False, prefer_reliability=False):
+        if fault_type and fault_type in FAULT_MODEL_MAPPING:
+            return self._select_by_strategy(FAULT_MODEL_MAPPING[fault_type]["select_strategy"])
+
+        best_model, best_score = self.primary_model, -1
+        for model in self.all_models:
+            perf = self.model_performance.get(model, ModelPerformance(model_name=model))
+            if prefer_speed:
+                score = max(0, 1 - perf.avg_latency_ms / 10000) * 0.7 + perf.success_rate * 0.3
+            elif prefer_reliability:
+                score = perf.success_rate * 0.7 + max(0, 1 - perf.avg_latency_ms / 10000) * 0.3
+            else:
+                score = perf.get_score()
+
+            if fault_type == "connection_timeout":
+                score *= 1 - (perf.timeout_count / max(1, perf.success_count + perf.timeout_count)) * 0.5
+
+            if score > best_score:
+                best_score, best_model = score, model
+
+        return best_model
+
+    def _select_by_strategy(self, strategy):
+        if strategy == "speed_priority":
+            return min(self.all_models, key=lambda m: self.model_performance.get(m, ModelPerformance(model_name=m)).avg_latency_ms)
+        if strategy == "load_balance":
+            return self.fallback_models[0] if self.primary_model == self.all_models[0] else self.primary_model
+        if strategy == "reliability_priority":
+            return max(self.all_models, key=lambda m: self.model_performance.get(m, ModelPerformance(model_name=m)).success_rate)
+        return self.primary_model
+
+    def generate_fault_fingerprint(self, fault_type, error_msg, model):
+        pattern_hash = hashlib.md5(str(error_msg)[:50].encode()).hexdigest()[:8]
+        timestamp = datetime.now().strftime("%Y%m%d%H")
+        return hashlib.sha256(f"{fault_type}:{pattern_hash}:{model}:{timestamp}".encode()).hexdigest()[:16]
+
+    def analyze_request(self, messages, kwargs):
+        total_tokens = sum(len(str(m.get("content", "")).split()) * 1.3 for m in messages)
+        complexity = "high" if total_tokens > 2000 or kwargs.get("max_tokens", 2048) > 2000 else ("medium" if total_tokens > 500 else "low")
+        return RequestProfile(
+            complexity=complexity,
+            estimated_tokens=int(total_tokens),
+            streaming=kwargs.get("stream", False),
+            has_system_prompt=any(m.get("role") == "system" for m in messages),
+            max_tokens_requested=kwargs.get("max_tokens", 2048),
+            temperature=kwargs.get("temperature", 0.7)
+        )
+
+    def degrade_request(self, messages, fault_type, profile=None):
+        info = {"action": "no_degradation", "changes": []}
+
+        if fault_type == "context_length_exceeded":
+            preserved = [m for m in messages if m.get("role") in ("system", "user")]
+            other = [m for m in messages if m.get("role") not in ("system", "user")]
+            return preserved + other[-2:], {"action": "smart_truncate"}
+
+        if fault_type == "content_safety_blocked":
+            triggers = ["暴力", "色情", "政治", "敏感", "违法", "hack", "porn", "violent"]
+            degraded = []
+            for m in messages:
+                content = m.get("content", "")
+                for w in triggers:
+                    content = re.sub(w, "[redacted]", content, flags=re.IGNORECASE)
+                degraded.append({"role": m.get("role"), "content": content})
+            return degraded, {"action": "prompt_rewrite"}
+
+        return messages, info
+
+    def _execute_request(self, messages, model=None, timeout=60, **kwargs):
+        model = model or self.primary_model
+        start = time.time()
+        headers = {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+        payload = {"model": model, "messages": messages}
+        for key in ("max_tokens", "temperature", "top_p", "stream"):
+            if key in kwargs:
+                payload[key] = kwargs[key]
+
+        try:
+            resp = requests.post(f"{self.base_url}/chat/completions", headers=headers, json=payload, timeout=timeout)
+            latency_ms = (time.time() - start) * 1000
+            self.response_time_history.append(latency_ms)
+
+            if resp.status_code == 200:
+                return {"success": True, "response": resp.json(), "status_code": 200}, latency_ms
+
+            err = resp.json() if resp.content else {}
+            return {"success": False, "error": err.get("error", {}).get("message", f"HTTP {resp.status_code}"),
+                    "error_code": err.get("error", {}).get("code"), "status_code": resp.status_code}, latency_ms
+
+        except requests.exceptions.Timeout:
+            latency_ms = (time.time() - start) * 1000
+            self.dynamic_backoff.record_result(False, latency_ms, is_timeout=True)
+            return {"success": False, "error": "Request timeout", "error_code": "timeout"}, latency_ms
+
+        except Exception as e:
+            return {"success": False, "error": str(e)}, (time.time() - start) * 1000
+
+    def _check_success(self, response):
+        if not response or not isinstance(response, dict):
+            return False
+        if response.get("success") is True:
+            return True
+        rd = response.get("response", {})
+        return isinstance(rd, dict) and bool(rd.get("choices"))
+
+    def record_model_result(self, model, success, latency_ms, is_timeout=False, is_rate_limit=False):
+        with self.lock:
+            if model not in self.model_performance:
+                self.model_performance[model] = ModelPerformance(model_name=model)
+            perf = self.model_performance[model]
+            if success:
+                perf.record_success(latency_ms)
+                self._timeout_consecutive_failures = 0
+            else:
+                perf.record_failure(is_timeout, is_rate_limit)
+                if is_timeout:
+                    self._timeout_consecutive_failures += 1
+
+    def cascade_recover(self, initial_error, messages, original_model=None, **kwargs):
+        start = time.time()
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")
+        model = original_model or self.primary_model
+
+        fault_type, confidence = self.diagnose(
+            error_msg=initial_error.get("error"),
+            status_code=initial_error.get("status_code")
+        )
+
+        if fault_type == "connection_timeout":
+            model = self.fallback_models[0] if model == self.primary_model else self.primary_model
+
+        fingerprint = self.generate_fault_fingerprint(fault_type, initial_error.get("error", ""), model)
+        need_predictive = self.fault_predictor.record_fault(fingerprint)
+        profile = self.analyze_request(messages, kwargs)
+
+        current_messages, current_model, current_kwargs = messages, model, kwargs.copy()
+        cascade_level, strategy_used, strategy_params = 0, "", {}
+        recovery_response, recovery_latency_ms = None, 0.0
+        total_attempts = 0
+
+        for strategy in CASCADE_STRATEGIES.get(fault_type, DEFAULT_CASCADE):
+            cascade_level = strategy["level"]
+            strategy_used = strategy.get("name", strategy["action"])
+            strategy_params = strategy.copy()
+            total_attempts += 1
+
+            action = strategy["action"]
+            timeout_override = strategy.get("timeout_override", 60)
+
+            if action == "predictive_switch":
+                if need_predictive:
+                    new_model = self.select_best_model(fault_type)
+                    if new_model != current_model:
+                        current_model = new_model
+                        strategy_params["switched_to"] = new_model
+                    current_kwargs["timeout"] = timeout_override
+                    response, latency = self._execute_request(current_messages, current_model, **current_kwargs)
+                    recovery_response, recovery_latency_ms = response, latency
+                    if self._check_success(response):
+                        self.record_model_result(current_model, True, latency)
+                        break
+                    need_predictive = False
+                continue
+
+            if action == "immediate_model_switch":
+                new_model = self.fallback_models[0] if current_model == self.primary_model else self.primary_model
+                if new_model != current_model:
+                    current_model = new_model
+                    strategy_params["switched_to"] = new_model
+                current_kwargs["timeout"] = timeout_override
+                response, latency = self._execute_request(current_messages, current_model, **current_kwargs)
+                recovery_response, recovery_latency_ms = response, latency
+                if self._check_success(response):
+                    self.record_model_result(current_model, True, latency)
+                    break
+                self.record_model_result(current_model, False, latency, is_timeout="timeout" in str(response).lower())
+                continue
+
+            if action == "dynamic_backoff_switch_retry":
+                new_model = self.fallback_models[0] if current_model == self.primary_model else self.primary_model
+                if new_model != current_model:
+                    current_model = new_model
+                    strategy_params["switched_to"] = new_model
+                time.sleep(strategy.get("wait_before_retry", 3))
+                current_kwargs["timeout"] = timeout_override
+                response, latency = self._execute_request(current_messages, current_model, **current_kwargs)
+                is_timeout = "timeout" in str(response).lower()
+                self.dynamic_backoff.record_result(self._check_success(response), latency, is_timeout)
+                recovery_response, recovery_latency_ms = response, latency
+                if self._check_success(response):
+                    self.record_model_result(current_model, True, latency)
+                    break
+                self.record_model_result(current_model, False, latency, is_timeout=is_timeout)
+                continue
+
+            if action == "dynamic_backoff_retry":
+                time.sleep(self.dynamic_backoff.calculate_delay(fault_type))
+                current_kwargs["timeout"] = timeout_override
+                response, latency = self._execute_request(current_messages, current_model, **current_kwargs)
+                recovery_response, recovery_latency_ms = response, latency
+                if self._check_success(response):
+                    self.record_model_result(current_model, True, latency)
+                    break
+                self.record_model_result(current_model, False, latency)
+                continue
+
+            if action == "fault_model_mapping_switch":
+                new_model = self.select_best_model(fault_type)
+                if new_model != current_model:
+                    current_model = new_model
+                    strategy_params["switched_to"] = new_model
+                current_kwargs["timeout"] = timeout_override
+                response, latency = self._execute_request(current_messages, current_model, **current_kwargs)
+                recovery_response, recovery_latency_ms = response, latency
+                if self._check_success(response):
+                    self.record_model_result(current_model, True, latency)
+                    break
+                self.record_model_result(current_model, False, latency)
+                continue
+
+            if action == "smart_truncate":
+                degraded, deg = self.degrade_request(current_messages, fault_type, profile)
+                current_messages = degraded
+                strategy_params["degradation"] = deg
+                current_kwargs["timeout"] = timeout_override
+                response, latency = self._execute_request(current_messages, current_model, **current_kwargs)
+                recovery_response, recovery_latency_ms = response, latency
+                if self._check_success(response):
+                    self.record_model_result(current_model, True, latency)
+                    break
+                self.record_model_result(current_model, False, latency)
+                continue
+
+            if action in ("basic_retry", "extended_wait_retry"):
+                if action == "extended_wait_retry":
+                    time.sleep(strategy.get("wait_seconds", 10))
+                current_kwargs["timeout"] = timeout_override
+                response, latency = self._execute_request(current_messages, current_model, **current_kwargs)
+                recovery_response, recovery_latency_ms = response, latency
+                if self._check_success(response):
+                    self.record_model_result(current_model, True, latency)
+                    break
+                self.record_model_result(current_model, False, latency)
+                continue
+
+            if action == "model_switch":
+                current_model = self.fallback_models[0] if current_model == self.primary_model else self.primary_model
+                strategy_params["switched_to"] = current_model
+                current_kwargs["timeout"] = timeout_override
+                response, latency = self._execute_request(current_messages, current_model, **current_kwargs)
+                recovery_response, recovery_latency_ms = response, latency
+                if self._check_success(response):
+                    self.record_model_result(current_model, True, latency)
+                    break
+                self.record_model_result(current_model, False, latency)
+                continue
+
+            if action == "request_degrade":
+                degraded, deg = self.degrade_request(current_messages, fault_type, profile)
+                current_messages = degraded
+                strategy_params["degradation"] = deg
+                current_kwargs["timeout"] = timeout_override
+                response, latency = self._execute_request(current_messages, current_model, **current_kwargs)
+                recovery_response, recovery_latency_ms = response, latency
+                if self._check_success(response):
+                    self.record_model_result(current_model, True, latency)
+                    break
+                self.record_model_result(current_model, False, latency)
+                continue
+
+        total_time_ms = (time.time() - start) * 1000
+        recovered = self._check_success(recovery_response) if recovery_response else False
+
+        record = RecoveryRecord(
+            timestamp=timestamp,
+            fault_type=fault_type,
+            diagnosis_confidence=confidence,
+            first_error=initial_error.get("error", ""),
+            cascade_level=cascade_level,
+            strategy_used=strategy_used,
+            strategy_params=strategy_params,
+            recovered=recovered,
+            total_attempts=total_attempts,
+            total_time_ms=total_time_ms,
+            fault_fingerprint=fingerprint,
+            recovery_latency_ms=recovery_latency_ms
+        )
+        self.recovery_records.append(record)
+
+        return recovery_response, record

neuralbridge_sdk-0.1.0/neuralbridge/core/strategies.py

@@ -0,0 +1,34 @@
+"""NeuralBridge Core - Recovery Strategies"""
+from typing import Dict, List, Any
+
+FAULT_MODEL_MAPPING: Dict[str, Dict[str, Any]] = {
+    "connection_timeout": {"select_strategy": "speed_priority"},
+    "rate_limit_exceeded": {"select_strategy": "load_balance"},
+    "context_length_exceeded": {"select_strategy": "context_window"},
+    "internal_error": {"select_strategy": "reliability_priority"},
+}
+
+CASCADE_STRATEGIES: Dict[str, List[Dict[str, Any]]] = {
+    "connection_timeout": [
+        {"level": 0, "name": "predictive_model_switch", "action": "predictive_switch", "trigger_on_fingerprint_count": 2},
+        {"level": 1, "name": "immediate_model_switch", "action": "immediate_model_switch", "timeout_override": 60},
+        {"level": 1, "name": "dynamic_backoff_switch_retry", "action": "dynamic_backoff_switch_retry", "timeout_override": 60, "wait_before_retry": 3},
+        {"level": 2, "name": "fault_model_mapping_switch", "action": "fault_model_mapping_switch", "select_by": "fault_type_mapping", "timeout_override": 60},
+    ],
+    "rate_limit_exceeded": [
+        {"level": 0, "name": "predictive_load_balance", "action": "predictive_load_balance", "trigger_on_fingerprint_count": 1},
+        {"level": 1, "name": "dynamic_backoff_retry", "action": "dynamic_backoff_retry", "use_adaptive_backoff": True},
+    ],
+    "service_overloaded": [{"level": 1, "name": "extended_wait_retry", "action": "extended_wait_retry", "wait_seconds": 10}],
+    "model_not_found": [{"level": 2, "name": "fault_model_mapping_switch", "action": "fault_model_mapping_switch", "select_by": "fault_type_mapping"}],
+    "internal_error": [{"level": 2, "name": "fault_model_mapping_switch", "action": "fault_model_mapping_switch", "select_by": "fault_type_mapping"}],
+    "context_length_exceeded": [{"level": 3, "name": "smart_truncate", "action": "smart_truncate", "preserve_ratio": 0.8, "preserve_system": True, "preserve_recent": True}],
+    "content_safety_blocked": [{"level": 3, "name": "rewrite_prompt", "action": "rewrite_prompt", "remove_triggers": True}],
+}
+
+DEFAULT_CASCADE: List[Dict[str, Any]] = [
+    {"level": 0, "name": "predictive_switch", "action": "predictive_switch"},
+    {"level": 1, "name": "basic_retry", "action": "basic_retry"},
+    {"level": 2, "name": "model_switch", "action": "model_switch"},
+    {"level": 3, "name": "request_degrade", "action": "request_degrade"},
+]

neuralbridge_sdk-0.1.0/neuralbridge/core/types.py

@@ -0,0 +1,171 @@
+"""NeuralBridge Core - Types and Data Structures"""
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Any, Tuple
+
+
+class FaultCategory(Enum):
+    NETWORK = "network"
+    AUTH = "authentication"
+    REQUEST = "request"
+    RESPONSE = "response"
+    SYSTEM = "system"
+    BUSINESS = "business"
+    ROUTING = "routing"
+
+
+class FaultSeverity(Enum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+
+class CascadeLevel(Enum):
+    LAYER_0_PREDICTIVE = 0
+    LAYER_1_SMART_RETRY = 1
+    LAYER_2_SMART_SWITCH = 2
+    LAYER_3_REQUEST_DEGRADE = 3
+
+
+@dataclass
+class ModelPerformance:
+    model_name: str
+    success_count: int = 0
+    failure_count: int = 0
+    total_latency_ms: float = 0.0
+    timeout_count: int = 0
+    last_used: float = 0.0
+    last_success: float = 0.0
+    rate_limit_count: int = 0
+
+    @property
+    def success_rate(self) -> float:
+        total = self.success_count + self.failure_count
+        return self.success_count / total if total > 0 else 0.5
+
+    @property
+    def avg_latency_ms(self) -> float:
+        total_calls = self.success_count + self.timeout_count
+        return self.total_latency_ms / total_calls if total_calls > 0 else 5000.0
+
+    def record_success(self, latency_ms: float):
+        self.success_count += 1
+        self.total_latency_ms += latency_ms
+        self.last_success = self.last_used = _now()
+
+    def record_failure(self, is_timeout: bool = False, is_rate_limit: bool = False):
+        self.failure_count += 1
+        self.last_used = _now()
+        if is_timeout:
+            self.timeout_count += 1
+        if is_rate_limit:
+            self.rate_limit_count += 1
+
+    def get_score(self) -> float:
+        return self.success_rate * 0.6 + max(0, 1 - (self.avg_latency_ms / 10000)) * 0.4
+
+
+@dataclass
+class RecoveryRecord:
+    timestamp: str
+    fault_type: str
+    diagnosis_confidence: float
+    first_error: str
+    cascade_level: int
+    strategy_used: str
+    strategy_params: Dict
+    recovered: bool
+    total_attempts: int
+    total_time_ms: float
+    fault_fingerprint: str = ""
+    recovery_latency_ms: float = 0.0
+
+
+@dataclass
+class AdaptiveTimeout:
+    base_timeout_ms: int = 30000
+    history_window: int = 20
+    multiplier: float = 1.5
+    min_timeout_ms: int = 5000
+    max_timeout_ms: int = 180000
+
+    def calculate(self, avg_response_time: Optional[float] = None) -> int:
+        if avg_response_time:
+            calculated = int(avg_response_time * self.multiplier)
+        else:
+            calculated = self.base_timeout_ms
+        return max(self.min_timeout_ms, min(self.max_timeout_ms, calculated))
+
+
+@dataclass
+class DynamicBackoff:
+    base_delay_s: float = 1.0
+    max_delay_s: float = 60.0
+    min_delay_s: float = 1.0
+    timeout_min_delay_s: float = 3.0
+    last_response_time_ms: float = 0.0
+    last_timeout_ms: float = 0.0
+    consecutive_timeouts: int = 0
+
+    def calculate_delay(self, fault_type: Optional[str] = None) -> float:
+        if self.last_timeout_ms > 0 or (fault_type and "timeout" in fault_type.lower()):
+            base_delay = max(3.0, min(self.last_timeout_ms / 1000 * 0.5, 15.0)) if self.last_timeout_ms > 0 else self.timeout_min_delay_s
+            if self.consecutive_timeouts > 0:
+                base_delay = min(base_delay * (1 + self.consecutive_timeouts * 0.2), self.max_delay_s)
+            return base_delay
+        
+        if self.last_response_time_ms > 0:
+            if self.last_response_time_ms < 1000:
+                delay = max(self.min_delay_s, 1.0)
+            elif self.last_response_time_ms < 5000:
+                delay = 1.5
+            elif self.last_response_time_ms < 10000:
+                delay = 2.0
+            else:
+                delay = max(3.0, self.last_response_time_ms / 1000 * 0.3)
+            return min(delay, self.max_delay_s)
+        
+        return self.base_delay_s
+
+    def record_result(self, success: bool, latency_ms: float, is_timeout: bool = False):
+        self.last_response_time_ms = latency_ms
+        if is_timeout:
+            self.last_timeout_ms = latency_ms
+            self.consecutive_timeouts += 1
+        else:
+            self.last_timeout_ms = 0.0
+            self.consecutive_timeouts = 0
+
+
+@dataclass
+class FaultPredictor:
+    fingerprint_history: Dict[str, List[float]] = field(default_factory=dict)
+    prediction_threshold: int = 3
+
+    def record_fault(self, fingerprint: str) -> bool:
+        import time as _time
+        now = _time.time()
+        if fingerprint not in self.fingerprint_history:
+            self.fingerprint_history[fingerprint] = []
+        self.fingerprint_history[fingerprint].append(now)
+        self.fingerprint_history[fingerprint] = [t for t in self.fingerprint_history[fingerprint] if now - t < 3600]
+        return len(self.fingerprint_history[fingerprint]) >= self.prediction_threshold
+
+    def should_predictive_switch(self, fingerprint: str) -> bool:
+        return fingerprint in self.fingerprint_history and len(self.fingerprint_history[fingerprint]) >= self.prediction_threshold
+
+
+@dataclass
+class RequestProfile:
+    complexity: str
+    estimated_tokens: int
+    streaming: bool
+    has_system_prompt: bool
+    max_tokens_requested: int
+    temperature: float
+
+
+def _now() -> float:
+    import time as _time
+    return _time.time()

neuralbridge_sdk-0.1.0/neuralbridge_sdk.egg-info/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: neuralbridge-sdk
+Version: 0.1.0
+Summary: Self-healing decision engine for AI API calls - diagnose, strategize, recover automatically
+Author-email: NeuralBridge Team <team@neuralbridge.dev>
+License: MIT
+Keywords: ai,api,self-healing,recovery,openai,llm,fallback
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Requires-Dist: requests>=2.28.0
+Dynamic: license-file
+
+# NeuralBridge SDK
+
+Self-healing decision engine for AI API calls. Drop-in replacement for `openai.OpenAI` with automatic fault diagnosis, cascade recovery, and transparent model switching.
+
+## Install
+
+```bash
+pip install neuralbridge
+```
+
+## Quick Start
+
+```python
+from neuralbridge import NeuralBridge
+
+client = NeuralBridge(
+    api_key="sk-xxx",
+    primary_model="gpt-4o",
+    fallback_models=["gpt-4o-mini"]
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+```
+
+## 4-Layer Cascade Recovery
+
+| Layer | Strategy | When |
+|-------|----------|------|
+| LAYER 0 | Predictive model switch | Same fault pattern seen 3+ times |
+| LAYER 1 | Smart retry + immediate model switch | Timeout, rate limit |
+| LAYER 2 | Fault-model mapping switch | Model not found, internal error |
+| LAYER 3 | Request degradation | Context too long, content blocked |
+
+## License
+
+MIT

neuralbridge_sdk-0.1.0/neuralbridge_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+neuralbridge/__init__.py
+neuralbridge/adapters/__init__.py
+neuralbridge/adapters/openai_adapter.py
+neuralbridge/core/__init__.py
+neuralbridge/core/engine.py
+neuralbridge/core/strategies.py
+neuralbridge/core/types.py
+neuralbridge_sdk.egg-info/PKG-INFO
+neuralbridge_sdk.egg-info/SOURCES.txt
+neuralbridge_sdk.egg-info/dependency_links.txt
+neuralbridge_sdk.egg-info/requires.txt
+neuralbridge_sdk.egg-info/top_level.txt

neuralbridge_sdk-0.1.0/neuralbridge_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

neuralbridge_sdk-0.1.0/neuralbridge_sdk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+openai>=1.0.0
+requests>=2.28.0

neuralbridge_sdk-0.1.0/neuralbridge_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+neuralbridge

neuralbridge_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neuralbridge-sdk"
+version = "0.1.0"
+description = "Self-healing decision engine for AI API calls - diagnose, strategize, recover automatically"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{name = "NeuralBridge Team", email = "team@neuralbridge.dev"}]
+keywords = ["ai", "api", "self-healing", "recovery", "openai", "llm", "fallback"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["openai>=1.0.0", "requests>=2.28.0"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["neuralbridge*"]

neuralbridge_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+