ai-synapse 4.0.0__py3-none-any.whl

ai_engine/__init__.py

@@ -0,0 +1,25 @@
+"""AI Synapse SDK — Drop-in OpenAI & Anthropic compatibility with free multi-provider routing."""
+
+__version__ = "4.0.0"
+
+from .openai import OpenAI, AsyncOpenAI
+from ._engine import AIEngine, get_engine, set_engine, _global_config
+from ._exceptions import (
+    AIEngineError,
+    OpenAIError,
+    BadRequestError,
+    AuthenticationError,
+    RateLimitError,
+    InternalServerError,
+    NotFoundError,
+)
+
+# Lazy Anthropic import (not implemented yet)
+try:
+    from .anthropic import Anthropic, AsyncAnthropic
+except ImportError:
+    pass
+
+def use(**kwargs):
+    """Configure global AI Engine settings (late configuration)."""
+    _global_config.update(kwargs)

ai_engine/_engine.py

@@ -0,0 +1,121 @@
+"""Shared AI Synapse engine singleton — initialized once, used by all SDK classes."""
+import os
+import json
+import logging
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+logger = logging.getLogger("ai_engine")
+
+_global_config: Dict[str, Any] = {}
+_engine_instance = None
+
+
+def _load_config_json(config_path: str = None) -> Dict[str, Any]:
+    """Load config from JSON file."""
+    if config_path:
+        path = Path(config_path)
+    else:
+        # Default: config.json next to this package
+        path = Path(__file__).parent / "config.json"
+
+    if path.exists():
+        with open(path) as f:
+            return json.load(f)
+    return {}
+
+
+def _resolve_config(config=None, cdn_config=None, **kwargs) -> Dict[str, Any]:
+    """Merge config from: JSON file → constructor args → env vars → defaults."""
+    # 1. Load from config.json
+    if isinstance(config, str):
+        base = _load_config_json(config)
+    elif isinstance(config, dict):
+        base = config.copy()
+    else:
+        base = _load_config_json()
+
+    # 2. Merge global config
+    base.update(_global_config)
+
+    # 3. Merge constructor kwargs
+    if "api_keys" in kwargs:
+        base.setdefault("api_keys", {}).update(kwargs["api_keys"])
+    for key in ("timeout", "max_retries", "default_provider"):
+        if key in kwargs:
+            base[key] = kwargs[key]
+    if cdn_config is not None:
+        base["cdn_config_url"] = cdn_config
+
+    # 4. Environment variable overrides
+    env_prefix = "AI_ENGINE_"
+    env_map = {
+        "AI_ENGINE_CDN_CONFIG": "cdn_config_url",
+        "AI_ENGINE_TIMEOUT": "timeout",
+        "AI_ENGINE_DEFAULT_PROVIDER": "default_provider",
+    }
+    for env_var, config_key in env_map.items():
+        val = os.environ.get(env_var)
+        if val is not None:
+            base[config_key] = int(val) if config_key == "timeout" else val
+
+    # 5. API key env vars: AI_ENGINE_API_KEY_{PROVIDER}
+    for env_key, env_val in os.environ.items():
+        if env_key.startswith("AI_ENGINE_API_KEY_"):
+            provider = env_key[len("AI_ENGINE_API_KEY_"):].lower()
+            base.setdefault("api_keys", {})[provider] = env_val
+
+    return base
+
+
+def _init_engine(config: Dict[str, Any]):
+    """Initialize AI_engine from merged config."""
+    import sys
+    sys.path.insert(0, str(Path(__file__).parent.parent))
+    from core.ai_engine import AI_engine
+
+    # Apply provider overrides
+    engine = AI_engine(verbose=False)
+
+    # Set API keys from config
+    api_keys = config.get("api_keys", {})
+    for provider_name, key in api_keys.items():
+        if provider_name in engine.providers:
+            engine.providers[provider_name]["api_keys"] = [key]
+            engine.providers[provider_name]["enabled"] = True
+
+    # Apply provider priority/enable overrides
+    provider_overrides = config.get("providers", {})
+    for provider_name, overrides in provider_overrides.items():
+        if provider_name in engine.providers:
+            for k, v in overrides.items():
+                engine.providers[provider_name][k] = v
+
+    return engine
+
+
+def get_engine(config=None, **kwargs):
+    """Get or create the shared engine singleton."""
+    global _engine_instance
+    if _engine_instance is None:
+        resolved = _resolve_config(config, **kwargs)
+        _engine_instance = _init_engine(resolved)
+    return _engine_instance
+
+
+def set_engine(engine):
+    """Manually set the engine singleton."""
+    global _engine_instance
+    _engine_instance = engine
+
+
+def reset_engine():
+    """Reset the engine (for testing)."""
+    global _engine_instance
+    _engine_instance = None
+
+
+# Re-export for convenience
+class AIEngine:
+    """Advanced AI Engine client with provider-specific features."""
+    pass

ai_engine/_exceptions.py

@@ -0,0 +1,89 @@
+"""Exception hierarchy for AI Synapse SDK."""
+
+
+class AIEngineError(Exception):
+    """Base exception for AI Engine SDK."""
+    def __init__(self, message=None, status_code=None, error_type=None, param=None, code=None):
+        self.status_code = status_code
+        self.error_type = error_type
+        self.param = param
+        self.code = code
+        super().__init__(message or "An error occurred")
+
+
+class OpenAIError(AIEngineError):
+    """Error matching OpenAI SDK format."""
+    pass
+
+
+class BadRequestError(OpenAIError):
+    def __init__(self, message=None, response=None, body=None, **kwargs):
+        super().__init__(message, status_code=400, error_type="invalid_request_error", **kwargs)
+
+
+class AuthenticationError(OpenAIError):
+    def __init__(self, message=None, response=None, body=None, **kwargs):
+        super().__init__(message, status_code=401, error_type="authentication_error", **kwargs)
+
+
+class PermissionDeniedError(OpenAIError):
+    def __init__(self, message=None, response=None, body=None, **kwargs):
+        super().__init__(message, status_code=403, error_type="permission_error", **kwargs)
+
+
+class NotFoundError(OpenAIError):
+    def __init__(self, message=None, response=None, body=None, **kwargs):
+        super().__init__(message, status_code=404, error_type="not_found_error", **kwargs)
+
+
+class RateLimitError(OpenAIError):
+    def __init__(self, message=None, response=None, body=None, **kwargs):
+        super().__init__(message, status_code=429, error_type="rate_limit_error", **kwargs)
+
+
+class InternalServerError(OpenAIError):
+    def __init__(self, message=None, response=None, body=None, **kwargs):
+        super().__init__(message, status_code=500, error_type="server_error", **kwargs)
+
+
+class AnthropicError(AIEngineError):
+    """Error matching Anthropic SDK format."""
+    pass
+
+
+class AnthropicBadRequestError(AnthropicError):
+    def __init__(self, message=None):
+        super().__init__(message, status_code=400, error_type="invalid_request_error")
+
+
+class AnthropicAuthenticationError(AnthropicError):
+    def __init__(self, message=None):
+        super().__init__(message, status_code=401, error_type="authentication_error")
+
+
+class AnthropicRateLimitError(AnthropicError):
+    def __init__(self, message=None):
+        super().__init__(message, status_code=429, error_type="rate_limit_error")
+
+
+def raise_for_status(status_code, error_body):
+    """Raise the appropriate exception for a given status code."""
+    error_dict = error_body.get("error", {})
+    message = error_dict.get("message", "Unknown error")
+    error_type = error_dict.get("type", "unknown")
+    param = error_dict.get("param")
+    code = error_dict.get("code")
+
+    exc_map = {
+        400: BadRequestError,
+        401: AuthenticationError,
+        403: PermissionDeniedError,
+        404: NotFoundError,
+        429: RateLimitError,
+        500: InternalServerError,
+    }
+
+    exc_cls = exc_map.get(status_code, OpenAIError)
+    if exc_cls in (OpenAIError,):
+        raise exc_cls(message=message, status_code=status_code, error_type=error_type, param=param, code=code)
+    raise exc_cls(message=message, param=param, code=code)

ai_engine/anthropic.py

@@ -0,0 +1,33 @@
+"""Anthropic SDK compatibility — placeholder for future implementation."""
+from ._engine import get_engine
+
+
+class Anthropic:
+    """Drop-in replacement for anthropic.Anthropic (future implementation).
+
+    Usage:
+        from ai_engine import Anthropic
+        client = Anthropic(api_key="dummy")
+        response = client.messages.create(
+            model="claude-3-haiku-20240307",
+            max_tokens=100,
+            messages=[{"role": "user", "content": "Hello!"}]
+        )
+    """
+
+    def __init__(self, *, api_key: str = "dummy", **kwargs):
+        self._api_key = api_key
+        raise NotImplementedError(
+            "Anthropic compatibility is coming in a future release. "
+            "Use OpenAI compatibility instead: from ai_engine import OpenAI"
+        )
+
+
+class AsyncAnthropic:
+    """Async Anthropic placeholder (future implementation)."""
+
+    def __init__(self, **kwargs):
+        raise NotImplementedError(
+            "AsyncAnthropic compatibility is coming in a future release. "
+            "Use AsyncOpenAI instead: from ai_engine import AsyncOpenAI"
+        )

ai_engine/openai.py

@@ -0,0 +1,120 @@
+"""Drop-in replacement for openai.OpenAI — routes through AI Synapse core."""
+from functools import cached_property
+from typing import Dict, Any, Optional
+import logging
+
+from ._engine import get_engine, _resolve_config, _init_engine
+from .resources.chat import Completions
+from .resources.models import Models
+
+logger = logging.getLogger("ai_engine")
+
+
+class _ChatNamespace:
+    """Namespace for client.chat.*"""
+
+    def __init__(self, engine):
+        self._completions = Completions(engine)
+
+    @property
+    def completions(self) -> Completions:
+        return self._completions
+
+
+class OpenAI:
+    """Drop-in replacement for openai.OpenAI.
+
+    Routes all requests through AI Engine's free multi-provider infrastructure.
+
+    Usage:
+        from ai_engine import OpenAI
+
+        client = OpenAI()
+        response = client.chat.completions.create(
+            model="gpt-4",
+            messages=[{"role": "user", "content": "Hello!"}]
+        )
+        print(response.choices[0].message.content)
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str = "dummy",
+        base_url: str = None,
+        config=None,
+        cdn_config: str = None,
+        timeout: int = 30,
+        max_retries: int = 2,
+        api_keys: Dict[str, str] = None,
+        **kwargs,
+    ):
+        self._config = _resolve_config(
+            config=config,
+            cdn_config=cdn_config,
+            api_keys=api_keys or {},
+            timeout=timeout,
+            max_retries=max_retries,
+            **kwargs,
+        )
+        self._engine = _init_engine(self._config)
+        self._chat = _ChatNamespace(self._engine)
+        self._models = Models(self._engine)
+
+    @property
+    def chat(self) -> _ChatNamespace:
+        return self._chat
+
+    @property
+    def models(self) -> Models:
+        return self._models
+
+    def config_status(self):
+        """Get CDN config sync status."""
+        try:
+            from core.config_sync import config_fetcher
+            return config_fetcher.get_status()
+        except ImportError:
+            return {"enabled": False}
+
+    def refresh_config(self):
+        """Force refresh CDN config."""
+        try:
+            from core.config_sync import config_fetcher, CACHE_META, CACHE_FILE
+            CACHE_META.unlink(missing_ok=True)
+            CACHE_FILE.unlink(missing_ok=True)
+            config_fetcher.fetch_and_apply()
+        except Exception as e:
+            logger.warning(f"CDN refresh failed: {e}")
+
+    def check_image_compatibility(self, provider: str, model: str = None):
+        """Check if a provider/model supports image uploads."""
+        from core.capabilities import capability_manager
+        return capability_manager.check_image_compatibility(provider, model)
+
+
+class AsyncOpenAI:
+    """Async drop-in replacement for openai.AsyncOpenAI.
+
+    Usage:
+        from ai_engine import AsyncOpenAI
+
+        async def main():
+            client = AsyncOpenAI()
+            response = await client.chat.completions.create(
+                model="gpt-4",
+                messages=[{"role": "user", "content": "Hello!"}]
+            )
+            print(response.choices[0].message.content)
+    """
+
+    def __init__(self, **kwargs):
+        self._sync_client = OpenAI(**kwargs)
+
+    @property
+    def chat(self):
+        return self._sync_client.chat
+
+    @property
+    def models(self):
+        return self._sync_client.models

ai_engine/resources/__init__.py

@@ -0,0 +1,2 @@
+from .chat import Completions
+from .models import Models

ai_engine/resources/chat.py

@@ -0,0 +1,135 @@
+"""Chat completions resource — wraps AI_engine.chat_completion()."""
+import time
+import uuid
+from typing import List, Dict, Any, Optional, Iterator, Union
+
+
+class Completions:
+    """Chat.Completions resource — client.chat.completions.create(...)"""
+
+    def __init__(self, engine):
+        self._engine = engine
+
+    def create(
+        self,
+        *,
+        model: str = "auto",
+        messages: List[Dict[str, str]],
+        stream: bool = False,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        top_p: Optional[float] = None,
+        stop: Optional[List[str]] = None,
+        n: int = 1,
+        user: Optional[str] = None,
+        **kwargs,
+    ):
+        """Create a chat completion.
+
+        Returns ChatCompletion for non-streaming, or yields ChatCompletionChunk for streaming.
+        """
+        if stream:
+            return self._stream(model, messages, temperature=temperature,
+                              max_tokens=max_tokens, **kwargs)
+
+        from ..types import ChatCompletion, ChatCompletionChoice, ChatCompletionMessage, Usage
+
+        result = self._engine.chat_completion(
+            messages=messages,
+            model=model if model != "auto" else None,
+            preferred_provider=kwargs.get("preferred_provider"),
+            force_provider=kwargs.get("force_provider", False),
+        )
+
+        if not result or not getattr(result, "success", False):
+            from .._exceptions import raise_for_status, InternalServerError
+            error_msg = getattr(result, "error_message", "Unknown error") if result else "No response"
+            raise InternalServerError(message=error_msg)
+
+        # Build OpenAI-compatible response
+        prompt_tokens = sum(len(m.get("content", "").split()) for m in messages)
+        completion_tokens = len(result.content.split())
+
+        return ChatCompletion(
+            id=f"chatcmpl-{uuid.uuid4().hex[:24]}",
+            object="chat.completion",
+            created=int(time.time()),
+            model=result.model_used or model,
+            choices=[ChatCompletionChoice(
+                index=0,
+                message=ChatCompletionMessage(
+                    role="assistant",
+                    content=result.content,
+                ),
+                finish_reason="stop",
+            )],
+            usage=Usage(
+                prompt_tokens=max(1, prompt_tokens),
+                completion_tokens=max(1, completion_tokens),
+                total_tokens=max(1, prompt_tokens + completion_tokens),
+            ),
+        )
+
+    def _stream(self, model, messages, temperature=None, max_tokens=None, **kwargs):
+        """Yield ChatCompletionChunk objects for streaming."""
+        from ..types import ChatCompletionChunk, ChatCompletionChunkChoice, ChatCompletionChunkDelta
+
+        completion_id = f"chatcmpl-{uuid.uuid4().hex[:24]}"
+        created = int(time.time())
+
+        result = self._engine.chat_completion(
+            messages=messages,
+            model=model if model != "auto" else None,
+            preferred_provider=kwargs.get("preferred_provider"),
+            force_provider=kwargs.get("force_provider", False),
+        )
+
+        if not result or not getattr(result, "success", False):
+            from .._exceptions import InternalServerError
+            error_msg = getattr(result, "error_message", "Unknown error") if result else "No response"
+            raise InternalServerError(message=error_msg)
+
+        actual_model = result.model_used or model
+        content = getattr(result, "content", "")
+
+        # First chunk: role
+        yield ChatCompletionChunk(
+            id=completion_id,
+            object="chat.completion.chunk",
+            created=created,
+            model=actual_model,
+            choices=[ChatCompletionChunkChoice(
+                index=0,
+                delta=ChatCompletionChunkDelta(role="assistant", content=""),
+                finish_reason=None,
+            )],
+        )
+
+        # Content chunks (word by word)
+        words = content.split(" ")
+        for i, word in enumerate(words):
+            chunk_content = (" " if i > 0 else "") + word + (" " if i < len(words) - 1 else "")
+            yield ChatCompletionChunk(
+                id=completion_id,
+                object="chat.completion.chunk",
+                created=created,
+                model=actual_model,
+                choices=[ChatCompletionChunkChoice(
+                    index=0,
+                    delta=ChatCompletionChunkDelta(content=chunk_content),
+                    finish_reason=None,
+                )],
+            )
+
+        # Final chunk
+        yield ChatCompletionChunk(
+            id=completion_id,
+            object="chat.completion.chunk",
+            created=created,
+            model=actual_model,
+            choices=[ChatCompletionChunkChoice(
+                index=0,
+                delta=ChatCompletionChunkDelta(),
+                finish_reason="stop",
+            )],
+        )

ai_engine/resources/models.py

@@ -0,0 +1,48 @@
+"""Models resource — wraps AI_engine model discovery."""
+import time
+from typing import Optional
+
+
+class Models:
+    """Models resource — client.models.list(), client.models.retrieve()"""
+
+    def __init__(self, engine):
+        self._engine = engine
+
+    def list(self, **kwargs):
+        """List all available models."""
+        from ..types import ModelList, Model
+
+        # Use shared model cache for fast listing
+        try:
+            from core.model_cache import shared_model_cache
+            if shared_model_cache.is_cache_valid():
+                model_ids = shared_model_cache.get_models()
+            else:
+                model_ids = []
+        except ImportError:
+            model_ids = []
+
+        models = []
+        for model_id in model_ids:
+            parts = model_id.split("/", 1)
+            owned_by = parts[0] if len(parts) > 1 else "unknown"
+            models.append(Model(
+                id=model_id,
+                object="model",
+                created=int(time.time()),
+                owned_by=owned_by,
+            ))
+
+        return ModelList(object="list", data=models)
+
+    def retrieve(self, model: str, **kwargs):
+        """Retrieve a single model by ID."""
+        from ..types import Model
+
+        return Model(
+            id=model,
+            object="model",
+            created=int(time.time()),
+            owned_by=model.split("/")[0] if "/" in model else "unknown",
+        )