ai-synapse 4.0.0__tar.gz

ai_synapse-4.0.0/LICENSE

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

ai_synapse-4.0.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: ai-synapse
+Version: 4.0.0
+Summary: Free multi-provider AI SDK — drop-in OpenAI & Anthropic compatibility with 27 free providers
+Author: AI Engine Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/mihir0209/AI_engine
+Project-URL: Documentation, https://github.com/mihir0209/AI_engine/tree/main/docs
+Project-URL: Repository, https://github.com/mihir0209/AI_engine
+Project-URL: Issues, https://github.com/mihir0209/AI_engine/issues
+Keywords: ai,llm,openai,anthropic,inference,free-ai,groq,gemini,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: pydantic>=2.5.0
+Provides-Extra: server
+Requires-Dist: aiohttp>=3.8.0; extra == "server"
+Requires-Dist: fastapi>=0.104.0; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.24.0; extra == "server"
+Requires-Dist: jinja2>=3.1.0; extra == "server"
+Requires-Dist: python-multipart>=0.0.6; extra == "server"
+Requires-Dist: aiofiles>=23.0.0; extra == "server"
+Requires-Dist: prometheus-client>=0.17.0; extra == "server"
+Requires-Dist: slowapi>=0.1.0; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: openai>=2.0.0; extra == "dev"
+Dynamic: license-file
+
+# AI Synapse — Free Multi-Provider AI SDK
+
+[![Tests](https://img.shields.io/badge/tests-573%20passing-brightgreen)]()
+[![Providers](https://img.shields.io/badge/providers-27%20enabled-blue)]()
+[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)]()
+[![OpenAI Compatible](https://img.shields.io/badge/OpenAI-Compatible-412991)]()
+[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED)]()
+
+> **Stop paying for AI inference.** Drop-in `from ai_engine import OpenAI` — routes through 27+ free providers with automatic failover and intelligent routing.
+
+---
+
+## Free Providers
+
+### No API Key Required (Truly Free)
+
+| Provider | Model | Endpoint |
+|----------|-------|----------|
+| **Pollinations** | openai | `text.pollinations.ai/openai` |
+| **Hermes** | Hermes-3-Llama | `hermes.ai.unturf.com/v1` |
+| **G4F Groq** | llama-3.3-70b | `g4f.space/api/groq` |
+| **G4F Gemini** | gemini-2.5-flash | `g4f.space/api/gemini` |
+| **G4F NVIDIA** | nemotron-3 | `g4f.space/api/nvidia` |
+| **OpenCode Zen** | north-mini-code | `opencode.ai/zen/v1` |
+
+### Free Tier APIs (Signup Required)
+
+| Provider | Free Tier | Signup |
+|----------|-----------|--------|
+| **Groq** | 30 RPM, 14,400 RPD | [console.groq.com](https://console.groq.com) |
+| **OpenRouter** | 23 free models | [openrouter.ai](https://openrouter.ai) |
+| **Gemini** | 5-30 RPM | [aistudio.google.com](https://aistudio.google.com) |
+| **NVIDIA** | 40 RPM | [build.nvidia.com](https://build.nvidia.com) |
+| **Cerebras** | 30 RPM | [cloud.cerebras.ai](https://cloud.cerebras.ai) |
+| **Cloudflare** | 10K neurons/day | [dash.cloudflare.com](https://dash.cloudflare.com) |
+| **GitHub** | Varies | [github.com/marketplace](https://github.com/marketplace/models) |
+| **Vercel** | $5/month free | [vercel.com](https://vercel.com) |
+| **Cohere** | 20 RPM, 1K/month | [cohere.com](https://cohere.com) |
+| **Mistral** | 1 RPS, 500K tokens/min | [console.mistral.ai](https://console.mistral.ai) |
+| **HuggingFace** | $0.10/month | [huggingface.co](https://huggingface.co) |
+| **Kilo** | Auto free routing | [app.kilo.ai](https://app.kilo.ai) |
+
+### Custom Providers (Your Keys)
+
+| Provider | Models | Signup |
+|----------|--------|--------|
+| **hcnsec** | [Various](https://api.hcnsec.cn/pricing) | [api.hcnsec.cn](https://api.hcnsec.cn) |
+| **LLM7** | [Various](https://docs.llm7.io/guides/models) | [llm7.io](https://llm7.io) |
+| **PaxSenix** | [Various](https://api.paxsenix.org/v1/models) | [api.paxsenix.org](https://api.paxsenix.org) |
+
+### Self-Hosted Options
+
+| Provider | Setup | Models |
+|----------|-------|--------|
+| **GPT4Free** | `docker run -p 8080:8080 hlohaus789/g4f` | GPT-4o, Claude, Gemini |
+| **Ollama** | `curl -fsSL https://ollama.com/install.sh \| sh` | Llama, Mistral, etc. |
+
+---
+
+## Quick Start
+
+### Option 1: Free Tier APIs (Recommended)
+
+```bash
+# 1. Copy environment template
+cp .env.example .env
+
+# 2. Get free API keys (see guide below)
+# 3. Add keys to .env file
+# 4. Start server
+python server.py
+```
+
+### Option 2: Self-Hosted (No API Keys Needed)
+
+```bash
+# Start g4f server
+docker run -d -p 8080:8080 hlohaus789/g4f
+
+# Start AI Engine
+python server.py
+```
+
+---
+
+## For Developers
+
+### OpenAI SDK Compatible
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:8000/v1",
+    api_key="dummy"  # Not needed for free providers
+)
+
+# Chat completion
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+
+# Streaming
+stream = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Tell me a story"}],
+    stream=True
+)
+for chunk in stream:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="")
+```
+
+### cURL
+
+```bash
+curl http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello!"}]}'
+```
+
+### JavaScript
+
+```javascript
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+    baseURL: 'http://localhost:8000/v1',
+    apiKey: 'dummy'
+});
+
+const response = await client.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Hello!' }]
+});
+```
+
+---
+
+## Features
+
+### Core
+- OpenAI-compatible API with streaming
+- Automatic provider failover
+- Intelligent key rotation
+- Response caching with TTL
+
+### Intelligence
+- Task-based model selection
+- Cost optimization
+- Latency tracking
+- A/B testing
+
+### Enterprise
+- Multi-tenancy with quotas
+- RBAC (Admin/User/Viewer)
+- Audit logging
+- Billing tracking
+
+### Platform
+- Plugin system
+- Workflow engine
+- CLI tool
+- Docker deployment
+
+---
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/chat/completions` | POST | Chat completions (OpenAI-compatible, supports `stream: true`) |
+| `/v1/models` | GET/POST | List all models |
+| `/api/providers` | GET | List providers |
+| `/api/health/{name}/ping` | POST | Live health ping for a provider |
+| `/api/capabilities` | GET | Provider/model capabilities (vision, etc.) |
+| `/api/status` | GET | Engine status |
+| `/api/statistics` | GET | Usage statistics |
+| `/health` | GET | Health check |
+| `/metrics` | GET | Prometheus metrics |
+| `/docs` | GET | Swagger UI (interactive API explorer) |
+| `/redoc` | GET | ReDoc API documentation |
+
+### Rate Limit Headers
+
+All API responses include:
+- `X-RateLimit-Limit` — Max requests per minute
+- `X-RateLimit-Remaining` — Remaining requests in current window
+
+---
+
+## Documentation
+
+- [API Reference](docs/API.md)
+- [User Guide](docs/USER_GUIDE.md)
+- [Deployment Guide](docs/DEPLOYMENT.md)
+- [Security Guide](docs/SECURITY.md)
+- [Provider Setup](docs/collect_api.md)
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT License - See [LICENSE](LICENSE)

ai_synapse-4.0.0/README.md

@@ -0,0 +1,213 @@
+# AI Synapse — Free Multi-Provider AI SDK
+
+[![Tests](https://img.shields.io/badge/tests-573%20passing-brightgreen)]()
+[![Providers](https://img.shields.io/badge/providers-27%20enabled-blue)]()
+[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)]()
+[![OpenAI Compatible](https://img.shields.io/badge/OpenAI-Compatible-412991)]()
+[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED)]()
+
+> **Stop paying for AI inference.** Drop-in `from ai_engine import OpenAI` — routes through 27+ free providers with automatic failover and intelligent routing.
+
+---
+
+## Free Providers
+
+### No API Key Required (Truly Free)
+
+| Provider | Model | Endpoint |
+|----------|-------|----------|
+| **Pollinations** | openai | `text.pollinations.ai/openai` |
+| **Hermes** | Hermes-3-Llama | `hermes.ai.unturf.com/v1` |
+| **G4F Groq** | llama-3.3-70b | `g4f.space/api/groq` |
+| **G4F Gemini** | gemini-2.5-flash | `g4f.space/api/gemini` |
+| **G4F NVIDIA** | nemotron-3 | `g4f.space/api/nvidia` |
+| **OpenCode Zen** | north-mini-code | `opencode.ai/zen/v1` |
+
+### Free Tier APIs (Signup Required)
+
+| Provider | Free Tier | Signup |
+|----------|-----------|--------|
+| **Groq** | 30 RPM, 14,400 RPD | [console.groq.com](https://console.groq.com) |
+| **OpenRouter** | 23 free models | [openrouter.ai](https://openrouter.ai) |
+| **Gemini** | 5-30 RPM | [aistudio.google.com](https://aistudio.google.com) |
+| **NVIDIA** | 40 RPM | [build.nvidia.com](https://build.nvidia.com) |
+| **Cerebras** | 30 RPM | [cloud.cerebras.ai](https://cloud.cerebras.ai) |
+| **Cloudflare** | 10K neurons/day | [dash.cloudflare.com](https://dash.cloudflare.com) |
+| **GitHub** | Varies | [github.com/marketplace](https://github.com/marketplace/models) |
+| **Vercel** | $5/month free | [vercel.com](https://vercel.com) |
+| **Cohere** | 20 RPM, 1K/month | [cohere.com](https://cohere.com) |
+| **Mistral** | 1 RPS, 500K tokens/min | [console.mistral.ai](https://console.mistral.ai) |
+| **HuggingFace** | $0.10/month | [huggingface.co](https://huggingface.co) |
+| **Kilo** | Auto free routing | [app.kilo.ai](https://app.kilo.ai) |
+
+### Custom Providers (Your Keys)
+
+| Provider | Models | Signup |
+|----------|--------|--------|
+| **hcnsec** | [Various](https://api.hcnsec.cn/pricing) | [api.hcnsec.cn](https://api.hcnsec.cn) |
+| **LLM7** | [Various](https://docs.llm7.io/guides/models) | [llm7.io](https://llm7.io) |
+| **PaxSenix** | [Various](https://api.paxsenix.org/v1/models) | [api.paxsenix.org](https://api.paxsenix.org) |
+
+### Self-Hosted Options
+
+| Provider | Setup | Models |
+|----------|-------|--------|
+| **GPT4Free** | `docker run -p 8080:8080 hlohaus789/g4f` | GPT-4o, Claude, Gemini |
+| **Ollama** | `curl -fsSL https://ollama.com/install.sh \| sh` | Llama, Mistral, etc. |
+
+---
+
+## Quick Start
+
+### Option 1: Free Tier APIs (Recommended)
+
+```bash
+# 1. Copy environment template
+cp .env.example .env
+
+# 2. Get free API keys (see guide below)
+# 3. Add keys to .env file
+# 4. Start server
+python server.py
+```
+
+### Option 2: Self-Hosted (No API Keys Needed)
+
+```bash
+# Start g4f server
+docker run -d -p 8080:8080 hlohaus789/g4f
+
+# Start AI Engine
+python server.py
+```
+
+---
+
+## For Developers
+
+### OpenAI SDK Compatible
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:8000/v1",
+    api_key="dummy"  # Not needed for free providers
+)
+
+# Chat completion
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+
+# Streaming
+stream = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Tell me a story"}],
+    stream=True
+)
+for chunk in stream:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="")
+```
+
+### cURL
+
+```bash
+curl http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello!"}]}'
+```
+
+### JavaScript
+
+```javascript
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+    baseURL: 'http://localhost:8000/v1',
+    apiKey: 'dummy'
+});
+
+const response = await client.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Hello!' }]
+});
+```
+
+---
+
+## Features
+
+### Core
+- OpenAI-compatible API with streaming
+- Automatic provider failover
+- Intelligent key rotation
+- Response caching with TTL
+
+### Intelligence
+- Task-based model selection
+- Cost optimization
+- Latency tracking
+- A/B testing
+
+### Enterprise
+- Multi-tenancy with quotas
+- RBAC (Admin/User/Viewer)
+- Audit logging
+- Billing tracking
+
+### Platform
+- Plugin system
+- Workflow engine
+- CLI tool
+- Docker deployment
+
+---
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/chat/completions` | POST | Chat completions (OpenAI-compatible, supports `stream: true`) |
+| `/v1/models` | GET/POST | List all models |
+| `/api/providers` | GET | List providers |
+| `/api/health/{name}/ping` | POST | Live health ping for a provider |
+| `/api/capabilities` | GET | Provider/model capabilities (vision, etc.) |
+| `/api/status` | GET | Engine status |
+| `/api/statistics` | GET | Usage statistics |
+| `/health` | GET | Health check |
+| `/metrics` | GET | Prometheus metrics |
+| `/docs` | GET | Swagger UI (interactive API explorer) |
+| `/redoc` | GET | ReDoc API documentation |
+
+### Rate Limit Headers
+
+All API responses include:
+- `X-RateLimit-Limit` — Max requests per minute
+- `X-RateLimit-Remaining` — Remaining requests in current window
+
+---
+
+## Documentation
+
+- [API Reference](docs/API.md)
+- [User Guide](docs/USER_GUIDE.md)
+- [Deployment Guide](docs/DEPLOYMENT.md)
+- [Security Guide](docs/SECURITY.md)
+- [Provider Setup](docs/collect_api.md)
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT License - See [LICENSE](LICENSE)

ai_synapse-4.0.0/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_synapse-4.0.0/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