splashcodex-api-manager 5.0.0__tar.gz → 5.0.2__tar.gz

splashcodex_api_manager-5.0.2/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: splashcodex-api-manager
+Version: 5.0.2
+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)
+
+### Auto-Scaffold (New!)
+The fastest way to get started is to run the `init` command in your project directory:
+```bash
+splashcodex-api-manager init
+# or
+python -m splashcodex_api_manager init
+```
+This will automatically create a `.env` template and a `demo.py` file showing the Gemini Preset in action.
+
+### 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.2/README.md

@@ -0,0 +1,149 @@
+# 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)
+
+### Auto-Scaffold (New!)
+The fastest way to get started is to run the `init` command in your project directory:
+```bash
+splashcodex-api-manager init
+# or
+python -m splashcodex_api_manager init
+```
+This will automatically create a `.env` template and a `demo.py` file showing the Gemini Preset in action.
+
+### 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.2/demo.py

@@ -0,0 +1,31 @@
+import asyncio
+import os
+# If leveraging the .env file locally:
+# from dotenv import load_dotenv
+# load_dotenv()
+
+from splashcodex_api_manager.presets.gemini import GeminiManager
+from splashcodex_api_manager.core.types import ExecuteOptions
+
+async def main():
+    print("Initialize GeminiManager...")
+    gemini = await GeminiManager.get_instance()
+
+    print("Executing resilient request...")
+    try:
+        # Automatically handles key rotation on failure (e.g. 429 quota limits)
+        response = await gemini.execute(
+            lambda key: simulate_api_call(key),
+            ExecuteOptions(maxRetries=3)
+        )
+        print(f"Result: {response}")
+    except Exception as e:
+        print(f"FAILED: {e}")
+
+def simulate_api_call(key):
+    print(f"[Network] Sending request with key: {key[:8]}...")
+    # Put your favorite LLM client call here, like google-genai!
+    return "Success: Simulated API Response!"
+
+if __name__ == '__main__':
+    asyncio.run(main())

splashcodex_api_manager-5.0.2/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "splashcodex-api-manager"
+version = "5.0.2"
+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.scripts]
+splashcodex-api-manager = "splashcodex_api_manager.__main__:main"
+api-key-manager = "splashcodex_api_manager.__main__:main"
+
+[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.2/splashcodex_api_manager/__init__.py

@@ -0,0 +1,42 @@
+"""
+splashcodex-api-manager
+=======================
+Universal API Key Management Gateway with Provider Presets,
+Built-in Persistence, and Multi-Provider Vault.
+
+Quick Start
+-----------
+>>> import asyncio
+>>> from splashcodex_api_manager.presets.gemini import GeminiManager
+>>> from splashcodex_api_manager.core.types import ExecuteOptions
+>>>
+>>> async def main():
+>>>     gemini = await GeminiManager.get_instance()
+>>>     result = await gemini.execute(
+>>>         lambda key: call_my_llm(key, "Hello"),
+>>>         ExecuteOptions(maxRetries=3)
+>>>     )
+>>>     print(result)
+>>>
+>>> asyncio.run(main())
+
+To view all features, run in your terminal:
+$ splashcodex-api-manager
+"""
+
+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'
+]

splashcodex_api_manager-5.0.2/splashcodex_api_manager/__main__.py

@@ -0,0 +1,89 @@
+import sys
+import os
+import textwrap
+
+def print_usage():
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+    print('\033[92m* splashcodex-api-manager v5.0\033[0m')
+    print('\033[96m  Documentation: https://pypi.org/project/splashcodex-api-manager/\033[0m\n')
+    print('\033[93m  Commands:\033[0m')
+    print('   splashcodex-api-manager init    \033[90m# Scaffold a demo project in the current directory\033[0m')
+    print('\n\033[95m  Tip: Need help? Run init to see it in action!\033[0m\n')
+
+def init_project():
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+    cwd = os.getcwd()
+    env_path = os.path.join(cwd, '.env')
+    demo_path = os.path.join(cwd, 'demo.py')
+
+    print('\n\033[96m>> Initializing splashcodex-api-manager environment...\033[0m\n')
+
+    # Create .env
+    if not os.path.exists(env_path):
+        with open(env_path, 'w') as f:
+            f.write('GOOGLE_GEMINI_API_KEY="your_api_key_1,your_api_key_2"\nOPENAI_API_KEY="sk-..."\n')
+        print('\033[92m[OK] Created .env file\033[0m')
+    else:
+        print('\033[90m[-] .env already exists. Remember to add GOOGLE_GEMINI_API_KEY!\033[0m')
+
+    # Create demo.py
+    if not os.path.exists(demo_path):
+        py_code = textwrap.dedent("""\
+            import asyncio
+            import os
+            # If leveraging the .env file locally:
+            # from dotenv import load_dotenv
+            # load_dotenv()
+
+            from splashcodex_api_manager.presets.gemini import GeminiManager
+            from splashcodex_api_manager.core.types import ExecuteOptions
+
+            async def main():
+                print("Initialize GeminiManager...")
+                gemini = await GeminiManager.get_instance()
+
+                print("Executing resilient request...")
+                try:
+                    # Automatically handles key rotation on failure (e.g. 429 quota limits)
+                    response = await gemini.execute(
+                        lambda key: simulate_api_call(key),
+                        ExecuteOptions(maxRetries=3)
+                    )
+                    print(f"Result: {response}")
+                except Exception as e:
+                    print(f"FAILED: {e}")
+
+            def simulate_api_call(key):
+                print(f"[Network] Sending request with key: {key[:8]}...")
+                # Put your favorite LLM client call here, like google-genai!
+                return "Success: Simulated API Response!"
+
+            if __name__ == '__main__':
+                asyncio.run(main())
+        """)
+        with open(demo_path, 'w') as f:
+            f.write(py_code)
+        print('\033[92m[OK] Created demo.py\033[0m')
+    else:
+        print('\033[90m[-] demo.py already exists.\033[0m')
+
+    print('\n\033[93m>> Setup Complete!\033[0m')
+    print('To run the demo:')
+    print('\033[36m   pip install python-dotenv\033[0m')
+    print('\033[36m   python demo.py\033[0m\n')
+
+def main():
+    args = sys.argv[1:]
+    if args and args[0] == 'init':
+        init_project()
+    else:
+        print_usage()
+
+if __name__ == '__main__':
+    main()

splashcodex_api_manager-5.0.2/venv/Lib/site-packages/charset_normalizer/__init__.py

@@ -0,0 +1,48 @@
+"""
+Charset-Normalizer
+~~~~~~~~~~~~~~
+The Real First Universal Charset Detector.
+A library that helps you read text from an unknown charset encoding.
+Motivated by chardet, This package is trying to resolve the issue by taking a new approach.
+All IANA character set names for which the Python core library provides codecs are supported.
+
+Basic usage:
+   >>> from charset_normalizer import from_bytes
+   >>> results = from_bytes('Bсеки човек има право на образование. Oбразованието!'.encode('utf_8'))
+   >>> best_guess = results.best()
+   >>> str(best_guess)
+   'Bсеки човек има право на образование. Oбразованието!'
+
+Others methods and usages are available - see the full documentation
+at <https://github.com/Ousret/charset_normalizer>.
+:copyright: (c) 2021 by Ahmed TAHRI
+:license: MIT, see LICENSE for more details.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .api import from_bytes, from_fp, from_path, is_binary
+from .legacy import detect
+from .models import CharsetMatch, CharsetMatches
+from .utils import set_logging_handler
+from .version import VERSION, __version__
+
+__all__ = (
+    "from_fp",
+    "from_path",
+    "from_bytes",
+    "is_binary",
+    "detect",
+    "CharsetMatch",
+    "CharsetMatches",
+    "__version__",
+    "VERSION",
+    "set_logging_handler",
+)
+
+# Attach a NullHandler to the top level logger by default
+# https://docs.python.org/3.3/howto/logging.html#configuring-logging-for-a-library
+
+logging.getLogger("charset_normalizer").addHandler(logging.NullHandler())

splashcodex_api_manager-5.0.2/venv/Lib/site-packages/charset_normalizer/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import cli_detect
+
+if __name__ == "__main__":
+    cli_detect()