splashcodex-api-manager 5.0.0__tar.gz

splashcodex_api_manager-5.0.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+*.js.map
+.DS_Store
+.env
+node_modules
+test_output_multi.txt
+*.log
+*.bak

splashcodex_api_manager-5.0.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: splashcodex-api-manager
+Version: 5.0.0
+Summary: Universal API Key Management Gateway with Provider Presets, Built-in Persistence, and Multi-Provider Vault.
+Project-URL: Homepage, https://github.com/splashcodex/codedex-api-manager
+Project-URL: Repository, https://github.com/splashcodex/codedex-api-manager.git
+Author-email: Adema <codex@splashcodex.com>
+License: ISC
+Keywords: api,circuit breaker,gemini,key manager,load balancer,openai
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+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
+Requires-Python: >=3.9
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# splashcodex-api-manager v5.0 — Ecosystem Edition (Python)
+
+> Universal API Key Management Gateway with Provider Presets, Built-in Persistence, and Multi-Provider Vault.
+
+[![PyPI version](https://img.shields.io/pypi/v/splashcodex-api-manager)](https://pypi.org/project/splashcodex-api-manager/)
+
+## New in v5.0 (Ecosystem Edition)
+
+- **Provider Presets** — One-line setup for `GeminiManager`, `OpenAIManager`, and `MultiManager`.
+- **Automatic Env Parsing** — Reads `GOOGLE_GEMINI_API_KEY`, etc. (supports JSON arrays and comma-separated strings).
+- **Built-in Persistence** — `FileStorage` (survives restarts) and `MemoryStorage` included.
+- **Singleton Pattern** — Thread-safe singletons with async `get_instance()`.
+- **Multi-Provider Vault** — Manage multiple providers (`gemini`, `openai`, `anthropic`) from a single entry point.
+
+## Features
+
+- **Circuit Breaker** — Keys transition through `CLOSED → OPEN → HALF_OPEN → DEAD`
+- **Error Classification** — Automatic detection of 429 (Quota), 403 (Auth), 5xx (Transient), Timeout
+- **Pluggable Strategies** — `StandardStrategy`, `WeightedStrategy`, `LatencyStrategy`
+- **`execute()` Wrapper** — Single async method: get key → call → latency → retry → fallback
+
+## Installation
+
+```bash
+pip install splashcodex-api-manager
+# or using uv
+uv add splashcodex-api-manager
+```
+
+## Quick Start (v5 Presets)
+
+The fastest way to get started in any Python application.
+
+### Gemini Preset
+Reads `GOOGLE_GEMINI_API_KEY` or `GEMINI_API_KEY` from the environment.
+
+```python
+import asyncio
+from splashcodex_api_manager.presets.gemini import GeminiManager
+from splashcodex_api_manager.core.types import ExecuteOptions
+
+async def call_gemini(key, prompt):
+    # Your arbitrary LLM call logic here
+    # Example using google-genai:
+    # return await client.aio.models.generate_content(...)
+    pass
+
+async def main():
+    gemini = await GeminiManager.get_instance()
+
+    # The manager automatically handles key rotation on failure (429, 500)
+    response = await gemini.execute(
+        lambda key: call_gemini(key, "Hello!"),
+        ExecuteOptions(maxRetries=3)
+    )
+    print(response)
+
+asyncio.run(main())
+```
+
+### Multi-Provider Vault
+Perfect for gateways or complex AI agents handling multiple models.
+
+```python
+import asyncio
+from splashcodex_api_manager.presets.multi import MultiManager
+
+async def main():
+    vault = await MultiManager.get_instance({
+        "providers": {
+            "gemini": { "envKeys": ["GOOGLE_GEMINI_API_KEY"] },
+            "openai": { "envKeys": ["OPENAI_API_KEY"] }
+        }
+    })
+
+    # Route by provider explicitly
+    res = await vault.execute(
+        lambda key: call_gemini(key, "Hi"),
+        provider="gemini"
+    )
+
+asyncio.run(main())
+```
+
+---
+
+## v5.0 — Architecture & Persistence
+
+### Built-in Persistence
+State (cooling down keys, dead keys, usage counts) survives application restarts to prevent spamming exhausted keys.
+
+```python
+import asyncio
+from splashcodex_api_manager.core.manager import ApiKeyManager
+from splashcodex_api_manager.persistence.file import FileStorage
+
+async def main():
+    manager = ApiKeyManager(["key1", "key2"])
+
+    # Load past failure history
+    storage = FileStorage(file_path='./api_state.json')
+    await manager.load_state(storage)
+
+    # ... use the keys ...
+
+    # Save before exiting
+    await manager.save_state(storage)
+```
+
+## Execute Wrapper
+
+Wraps the entire lifecycle into one async method. Automatically trips circuit breakers on persistent failures and seamlessly rotates to the next available key.
+
+```python
+from splashcodex_api_manager.core.types import ExecuteOptions
+
+result = await manager.execute(
+  fn=lambda key: httpx_call(key),
+  options=ExecuteOptions(maxRetries=5, timeoutMs=10000)
+)
+```
+
+## API Reference
+
+### Presets
+
+| Class | Env Vars | Description |
+|-------|----------|-------------|
+| `GeminiManager` | `GOOGLE_GEMINI_API_KEY`, `GEMINI_API_KEY` | Gemini-optimized asynchronous singleton |
+| `OpenAIManager` | `OPENAI_API_KEY` | OpenAI-optimized asynchronous singleton |
+| `MultiManager` | Custom | Thread-safe Vault for multiple provider pools |
+
+### Persistence
+
+| Class | Description |
+|-------|-------------|
+| `FileStorage` | Persists to a JSON file (recommended for servers and CLI tools) |
+| `MemoryStorage` | In-memory only (best for serverless/short-lived processes) |
+
+## License
+
+ISC

splashcodex_api_manager-5.0.0/README.md

@@ -0,0 +1,142 @@
+# splashcodex-api-manager v5.0 — Ecosystem Edition (Python)
+
+> Universal API Key Management Gateway with Provider Presets, Built-in Persistence, and Multi-Provider Vault.
+
+[![PyPI version](https://img.shields.io/pypi/v/splashcodex-api-manager)](https://pypi.org/project/splashcodex-api-manager/)
+
+## New in v5.0 (Ecosystem Edition)
+
+- **Provider Presets** — One-line setup for `GeminiManager`, `OpenAIManager`, and `MultiManager`.
+- **Automatic Env Parsing** — Reads `GOOGLE_GEMINI_API_KEY`, etc. (supports JSON arrays and comma-separated strings).
+- **Built-in Persistence** — `FileStorage` (survives restarts) and `MemoryStorage` included.
+- **Singleton Pattern** — Thread-safe singletons with async `get_instance()`.
+- **Multi-Provider Vault** — Manage multiple providers (`gemini`, `openai`, `anthropic`) from a single entry point.
+
+## Features
+
+- **Circuit Breaker** — Keys transition through `CLOSED → OPEN → HALF_OPEN → DEAD`
+- **Error Classification** — Automatic detection of 429 (Quota), 403 (Auth), 5xx (Transient), Timeout
+- **Pluggable Strategies** — `StandardStrategy`, `WeightedStrategy`, `LatencyStrategy`
+- **`execute()` Wrapper** — Single async method: get key → call → latency → retry → fallback
+
+## Installation
+
+```bash
+pip install splashcodex-api-manager
+# or using uv
+uv add splashcodex-api-manager
+```
+
+## Quick Start (v5 Presets)
+
+The fastest way to get started in any Python application.
+
+### Gemini Preset
+Reads `GOOGLE_GEMINI_API_KEY` or `GEMINI_API_KEY` from the environment.
+
+```python
+import asyncio
+from splashcodex_api_manager.presets.gemini import GeminiManager
+from splashcodex_api_manager.core.types import ExecuteOptions
+
+async def call_gemini(key, prompt):
+    # Your arbitrary LLM call logic here
+    # Example using google-genai:
+    # return await client.aio.models.generate_content(...)
+    pass
+
+async def main():
+    gemini = await GeminiManager.get_instance()
+
+    # The manager automatically handles key rotation on failure (429, 500)
+    response = await gemini.execute(
+        lambda key: call_gemini(key, "Hello!"),
+        ExecuteOptions(maxRetries=3)
+    )
+    print(response)
+
+asyncio.run(main())
+```
+
+### Multi-Provider Vault
+Perfect for gateways or complex AI agents handling multiple models.
+
+```python
+import asyncio
+from splashcodex_api_manager.presets.multi import MultiManager
+
+async def main():
+    vault = await MultiManager.get_instance({
+        "providers": {
+            "gemini": { "envKeys": ["GOOGLE_GEMINI_API_KEY"] },
+            "openai": { "envKeys": ["OPENAI_API_KEY"] }
+        }
+    })
+
+    # Route by provider explicitly
+    res = await vault.execute(
+        lambda key: call_gemini(key, "Hi"),
+        provider="gemini"
+    )
+
+asyncio.run(main())
+```
+
+---
+
+## v5.0 — Architecture & Persistence
+
+### Built-in Persistence
+State (cooling down keys, dead keys, usage counts) survives application restarts to prevent spamming exhausted keys.
+
+```python
+import asyncio
+from splashcodex_api_manager.core.manager import ApiKeyManager
+from splashcodex_api_manager.persistence.file import FileStorage
+
+async def main():
+    manager = ApiKeyManager(["key1", "key2"])
+
+    # Load past failure history
+    storage = FileStorage(file_path='./api_state.json')
+    await manager.load_state(storage)
+
+    # ... use the keys ...
+
+    # Save before exiting
+    await manager.save_state(storage)
+```
+
+## Execute Wrapper
+
+Wraps the entire lifecycle into one async method. Automatically trips circuit breakers on persistent failures and seamlessly rotates to the next available key.
+
+```python
+from splashcodex_api_manager.core.types import ExecuteOptions
+
+result = await manager.execute(
+  fn=lambda key: httpx_call(key),
+  options=ExecuteOptions(maxRetries=5, timeoutMs=10000)
+)
+```
+
+## API Reference
+
+### Presets
+
+| Class | Env Vars | Description |
+|-------|----------|-------------|
+| `GeminiManager` | `GOOGLE_GEMINI_API_KEY`, `GEMINI_API_KEY` | Gemini-optimized asynchronous singleton |
+| `OpenAIManager` | `OPENAI_API_KEY` | OpenAI-optimized asynchronous singleton |
+| `MultiManager` | Custom | Thread-safe Vault for multiple provider pools |
+
+### Persistence
+
+| Class | Description |
+|-------|-------------|
+| `FileStorage` | Persists to a JSON file (recommended for servers and CLI tools) |
+| `MemoryStorage` | In-memory only (best for serverless/short-lived processes) |
+
+## License
+
+ISC

splashcodex_api_manager-5.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "splashcodex-api-manager"
+version = "5.0.0"
+description = "Universal API Key Management Gateway with Provider Presets, Built-in Persistence, and Multi-Provider Vault."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "Adema", email = "codex@splashcodex.com" }
+]
+license = { text = "ISC" }
+keywords = ["api", "key manager", "gemini", "openai", "circuit breaker", "load balancer"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: ISC License (ISCL)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "pydantic>=2.0.0",
+    "loguru>=0.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/splashcodex/codedex-api-manager"
+Repository = "https://github.com/splashcodex/codedex-api-manager.git"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

splashcodex_api_manager-5.0.0/splashcodex_api_manager/__init__.py

@@ -0,0 +1,16 @@
+from .core.manager import ApiKeyManager, SemanticCache
+from .core.types import KeyState, ErrorClassification, ErrorType, ExecuteOptions, ApiKeyManagerStats, CircuitState
+from .core.strategies import LatencyStrategy, WeightedStrategy
+
+__all__ = [
+    'ApiKeyManager',
+    'SemanticCache',
+    'KeyState',
+    'ErrorClassification',
+    'ErrorType',
+    'ExecuteOptions',
+    'ApiKeyManagerStats',
+    'CircuitState',
+    'LatencyStrategy',
+    'WeightedStrategy'
+]