aistatus 0.0.1__tar.gz

aistatus-0.0.1/LICENSE

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

aistatus-0.0.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: aistatus
+Version: 0.0.1
+Summary: Smart AI model routing with real-time status awareness. Pre-flight checks, auto-fallback, budget constraints.
+Author-email: LeTau Robotics <hello@aistatus.cc>
+License-Expression: MIT
+Project-URL: Homepage, https://aistatus.cc
+Project-URL: Documentation, https://aistatus.cc/docs
+Project-URL: Repository, https://github.com/fangxm233/aistatus-python
+Keywords: ai,llm,routing,fallback,agent,openai,anthropic,gemini
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.50; extra == "openai"
+Provides-Extra: google
+Requires-Dist: google-genai>=1.0; extra == "google"
+Provides-Extra: gateway
+Requires-Dist: aiohttp>=3.9; extra == "gateway"
+Requires-Dist: pyyaml>=6.0; extra == "gateway"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == "all"
+Requires-Dist: openai>=1.50; extra == "all"
+Requires-Dist: google-genai>=1.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Dynamic: license-file
+
+# aistatus
+
+Smart AI model routing with real-time status awareness.
+
+`aistatus` checks provider/model availability through `aistatus.cc`, then calls
+your installed provider SDK directly. Your prompts and API keys stay on your side.
+
+## Install
+
+```bash
+pip install aistatus
+pip install aistatus[anthropic]
+pip install aistatus[openai]
+pip install aistatus[google]
+pip install aistatus[all]
+```
+
+## Quickstart
+
+Set at least one provider API key, then route by model name:
+
+```python
+from aistatus import route
+
+resp = route(
+    "Summarize the latest deployment status.",
+    model="claude-sonnet-4-6",
+)
+
+print(resp.content)
+print(resp.model_used)
+print(resp.provider_used)
+print(resp.was_fallback)
+```
+
+If the primary provider is unavailable, `aistatus` tries other compatible providers
+that are available in your environment.
+
+## Tier Routing
+
+Tier routing is supported, but tiers must be configured explicitly:
+
+```python
+from aistatus import Router
+
+router = Router(check_timeout=2.0)
+router.add_tier("fast", [
+    "claude-haiku-4-5",
+    "gpt-4o-mini",
+    "gemini-2.0-flash",
+])
+router.add_tier("standard", [
+    "claude-sonnet-4-6",
+    "gpt-4o",
+    "gemini-2.5-pro",
+])
+
+resp = router.route(
+    "Explain quantum computing in one sentence.",
+    tier="fast",
+)
+```
+
+## Async
+
+```python
+from aistatus import aroute
+
+resp = await aroute(
+    [{"role": "user", "content": "Hello"}],
+    model="gpt-4o-mini",
+)
+```
+
+## Status API
+
+```python
+from aistatus import StatusAPI
+
+api = StatusAPI()
+
+check = api.check_provider("anthropic")
+print(check.status)
+print(check.is_available)
+
+for provider in api.providers():
+    print(provider.name, provider.status.value)
+
+for model in api.search_models("sonnet"):
+    print(model.id, model.prompt_price, model.completion_price)
+```
+
+## Response Object
+
+Every `route()` call returns a `RouteResponse`:
+
+```python
+@dataclass
+class RouteResponse:
+    content: str
+    model_used: str
+    provider_used: str
+    was_fallback: bool
+    fallback_reason: str | None = None
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost_usd: float = 0.0
+    raw: Any = None
+```
+
+## Errors
+
+```python
+from aistatus import AllProvidersDown, ProviderNotInstalled, route
+
+try:
+    resp = route("Hello", model="claude-sonnet-4-6")
+except AllProvidersDown as e:
+    print(e.tried)
+except ProviderNotInstalled as e:
+    print(f"Install support for: {e.provider}")
+```
+
+## Environment Variables
+
+The SDK auto-discovers providers from standard environment variables:
+
+```bash
+ANTHROPIC_API_KEY=...
+OPENAI_API_KEY=...
+GEMINI_API_KEY=...
+OPENROUTER_API_KEY=...
+DEEPSEEK_API_KEY=...
+MISTRAL_API_KEY=...
+XAI_API_KEY=...
+GROQ_API_KEY=...
+TOGETHER_API_KEY=...
+MOONSHOT_API_KEY=...
+DASHSCOPE_API_KEY=...
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

aistatus-0.0.1/README.md

@@ -0,0 +1,144 @@
+# aistatus
+
+Smart AI model routing with real-time status awareness.
+
+`aistatus` checks provider/model availability through `aistatus.cc`, then calls
+your installed provider SDK directly. Your prompts and API keys stay on your side.
+
+## Install
+
+```bash
+pip install aistatus
+pip install aistatus[anthropic]
+pip install aistatus[openai]
+pip install aistatus[google]
+pip install aistatus[all]
+```
+
+## Quickstart
+
+Set at least one provider API key, then route by model name:
+
+```python
+from aistatus import route
+
+resp = route(
+    "Summarize the latest deployment status.",
+    model="claude-sonnet-4-6",
+)
+
+print(resp.content)
+print(resp.model_used)
+print(resp.provider_used)
+print(resp.was_fallback)
+```
+
+If the primary provider is unavailable, `aistatus` tries other compatible providers
+that are available in your environment.
+
+## Tier Routing
+
+Tier routing is supported, but tiers must be configured explicitly:
+
+```python
+from aistatus import Router
+
+router = Router(check_timeout=2.0)
+router.add_tier("fast", [
+    "claude-haiku-4-5",
+    "gpt-4o-mini",
+    "gemini-2.0-flash",
+])
+router.add_tier("standard", [
+    "claude-sonnet-4-6",
+    "gpt-4o",
+    "gemini-2.5-pro",
+])
+
+resp = router.route(
+    "Explain quantum computing in one sentence.",
+    tier="fast",
+)
+```
+
+## Async
+
+```python
+from aistatus import aroute
+
+resp = await aroute(
+    [{"role": "user", "content": "Hello"}],
+    model="gpt-4o-mini",
+)
+```
+
+## Status API
+
+```python
+from aistatus import StatusAPI
+
+api = StatusAPI()
+
+check = api.check_provider("anthropic")
+print(check.status)
+print(check.is_available)
+
+for provider in api.providers():
+    print(provider.name, provider.status.value)
+
+for model in api.search_models("sonnet"):
+    print(model.id, model.prompt_price, model.completion_price)
+```
+
+## Response Object
+
+Every `route()` call returns a `RouteResponse`:
+
+```python
+@dataclass
+class RouteResponse:
+    content: str
+    model_used: str
+    provider_used: str
+    was_fallback: bool
+    fallback_reason: str | None = None
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost_usd: float = 0.0
+    raw: Any = None
+```
+
+## Errors
+
+```python
+from aistatus import AllProvidersDown, ProviderNotInstalled, route
+
+try:
+    resp = route("Hello", model="claude-sonnet-4-6")
+except AllProvidersDown as e:
+    print(e.tried)
+except ProviderNotInstalled as e:
+    print(f"Install support for: {e.provider}")
+```
+
+## Environment Variables
+
+The SDK auto-discovers providers from standard environment variables:
+
+```bash
+ANTHROPIC_API_KEY=...
+OPENAI_API_KEY=...
+GEMINI_API_KEY=...
+OPENROUTER_API_KEY=...
+DEEPSEEK_API_KEY=...
+MISTRAL_API_KEY=...
+XAI_API_KEY=...
+GROQ_API_KEY=...
+TOGETHER_API_KEY=...
+MOONSHOT_API_KEY=...
+DASHSCOPE_API_KEY=...
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

aistatus-0.0.1/aistatus/__init__.py

@@ -0,0 +1,139 @@
+"""aistatus — Smart AI model routing with real-time status awareness.
+
+Quickstart::
+
+    from aistatus import route
+
+    resp = route("Hello!", model="claude-sonnet-4-6")
+    print(resp.content)          # "Hello! How can I help?"
+    print(resp.model_used)       # "anthropic/claude-sonnet-4-6"
+    print(resp.was_fallback)     # False
+
+Tier-based routing (requires configuration)::
+
+    from aistatus import Router
+
+    router = Router()
+    router.add_tier("fast", ["claude-haiku-4-5", "gpt-4o-mini"])
+    resp = router.route("Hello!", tier="fast")
+"""
+
+__version__ = "0.0.1"
+
+# Core routing
+from .router import Router  # noqa: F401
+
+# Data models (for type hints and advanced usage)
+from .models import (  # noqa: F401
+    RouteResponse,
+    RouteConfig,
+    CheckResult,
+    Status,
+    ProviderStatus,
+    ProviderConfig,
+    ModelInfo,
+)
+
+# Status API (for direct queries without routing)
+from .api import StatusAPI  # noqa: F401
+
+# Exceptions
+from .exceptions import (  # noqa: F401
+    AIStatusError,
+    AllProvidersDown,
+    ProviderCallFailed,
+    NoBudgetMatch,
+    ProviderNotInstalled,
+    CheckAPIUnreachable,
+)
+
+# Trigger adapter registration on import
+from . import providers as _providers  # noqa: F401
+
+# ---------------------------------------------------------------------------
+# Module-level convenience functions (lazy-initialized default Router)
+# ---------------------------------------------------------------------------
+
+_default_router: Router | None = None
+
+
+def _get_default_router() -> Router:
+    global _default_router
+    if _default_router is None:
+        _default_router = Router()
+    return _default_router
+
+
+def route(
+    messages: str | list[dict],
+    *,
+    model: str | None = None,
+    tier: str | None = None,
+    system: str | None = None,
+    allow_fallback: bool = True,
+    timeout: float = 30.0,
+    prefer: list[str] | None = None,
+    **kwargs,
+) -> RouteResponse:
+    """One-liner routing with auto-discovered providers.
+
+    Args:
+        messages: User message string or OpenAI-style message list.
+        model: Model name (e.g. "claude-sonnet-4-6"). Provider resolved via API.
+        tier: Tier name. Requires prior configuration on the default router.
+        system: Optional system prompt (convenience for string messages).
+        allow_fallback: Try alternatives if primary provider is down.
+        timeout: Provider call timeout in seconds.
+        prefer: Provider preference order for fallback.
+        **kwargs: Passed to provider SDK (max_tokens, temperature, etc.).
+    """
+    return _get_default_router().route(
+        messages, model=model, tier=tier, system=system,
+        allow_fallback=allow_fallback, timeout=timeout, prefer=prefer,
+        **kwargs,
+    )
+
+
+async def aroute(
+    messages: str | list[dict],
+    *,
+    model: str | None = None,
+    tier: str | None = None,
+    system: str | None = None,
+    allow_fallback: bool = True,
+    timeout: float = 30.0,
+    prefer: list[str] | None = None,
+    **kwargs,
+) -> RouteResponse:
+    """Async version of route()."""
+    return await _get_default_router().aroute(
+        messages, model=model, tier=tier, system=system,
+        allow_fallback=allow_fallback, timeout=timeout, prefer=prefer,
+        **kwargs,
+    )
+
+
+__all__ = [
+    # One-liners
+    "route",
+    "aroute",
+    # Router class
+    "Router",
+    # API client
+    "StatusAPI",
+    # Models
+    "RouteResponse",
+    "RouteConfig",
+    "CheckResult",
+    "Status",
+    "ProviderStatus",
+    "ProviderConfig",
+    "ModelInfo",
+    # Exceptions
+    "AIStatusError",
+    "AllProvidersDown",
+    "ProviderCallFailed",
+    "NoBudgetMatch",
+    "ProviderNotInstalled",
+    "CheckAPIUnreachable",
+]

aistatus-0.0.1/aistatus/_defaults.py

@@ -0,0 +1,39 @@
+"""Default configuration constants for auto-discovery."""
+
+from __future__ import annotations
+
+# Provider slug → (default_env_var, adapter_type_name)
+# Used by Router to auto-discover available providers from environment variables.
+AUTO_PROVIDERS: dict[str, tuple[str, str]] = {
+    "anthropic":  ("ANTHROPIC_API_KEY",  "anthropic"),
+    "openai":     ("OPENAI_API_KEY",     "openai"),
+    "google":     ("GEMINI_API_KEY",     "google"),
+    "openrouter": ("OPENROUTER_API_KEY", "openrouter"),
+    "deepseek":   ("DEEPSEEK_API_KEY",   "deepseek"),
+    "mistral":    ("MISTRAL_API_KEY",    "mistralai"),
+    "xai":        ("XAI_API_KEY",        "xai"),
+    "groq":       ("GROQ_API_KEY",       "groq"),
+    "together":   ("TOGETHER_API_KEY",   "together"),
+    "moonshot":   ("MOONSHOT_API_KEY",   "moonshotai"),
+    "qwen":       ("DASHSCOPE_API_KEY",  "qwen"),
+}
+
+# Model name prefix → provider slug.
+# Used as fallback when aistatus.cc API is unreachable.
+MODEL_PREFIX_MAP: dict[str, str] = {
+    "claude":     "anthropic",
+    "gpt":        "openai",
+    "o1":         "openai",
+    "o3":         "openai",
+    "o4":         "openai",
+    "chatgpt":    "openai",
+    "gemini":     "google",
+    "deepseek":   "deepseek",
+    "mistral":    "mistral",
+    "codestral":  "mistral",
+    "pixtral":    "mistral",
+    "grok":       "xai",
+    "llama":      "groq",
+    "qwen":       "qwen",
+    "moonshot":   "moonshot",
+}

aistatus-0.0.1/aistatus/api.py

@@ -0,0 +1,114 @@
+"""Thin client for the aistatus.cc public API."""
+
+from __future__ import annotations
+
+import httpx
+
+from .models import Alternative, CheckResult, ModelInfo, ProviderStatus, Status
+
+BASE_URL = "https://aistatus.cc"
+
+
+class StatusAPI:
+    """Stateless HTTP client for aistatus.cc.  All methods are class-level."""
+
+    def __init__(self, base_url: str = BASE_URL, timeout: float = 3.0):
+        self._base = base_url.rstrip("/")
+        self._timeout = timeout
+
+    # ---- sync helpers ------------------------------------------------
+
+    def _get(self, path: str, params: dict | None = None) -> dict:
+        with httpx.Client(timeout=self._timeout) as c:
+            r = c.get(f"{self._base}{path}", params=params)
+            r.raise_for_status()
+            return r.json()
+
+    async def _aget(self, path: str, params: dict | None = None) -> dict:
+        async with httpx.AsyncClient(timeout=self._timeout) as c:
+            r = await c.get(f"{self._base}{path}", params=params)
+            r.raise_for_status()
+            return r.json()
+
+    # ---- public methods (sync) ----------------------------------------
+
+    def check_provider(self, slug: str) -> CheckResult:
+        """Pre-flight check for a provider.  GET /api/check?provider=..."""
+        data = self._get("/api/check", {"provider": slug})
+        return self._parse_check(data)
+
+    def check_model(self, model_id: str) -> CheckResult:
+        """Pre-flight check for a specific model.  GET /api/check?model=..."""
+        data = self._get("/api/check", {"model": model_id})
+        return self._parse_check(data)
+
+    def providers(self) -> list[ProviderStatus]:
+        """All provider statuses.  GET /api/providers"""
+        data = self._get("/api/providers")
+        return [
+            ProviderStatus(
+                slug=p["slug"],
+                name=p["name"],
+                status=Status(p["status"]),
+                status_detail=p.get("statusDetail"),
+                model_count=p.get("modelCount", 0),
+            )
+            for p in data.get("providers", [])
+        ]
+
+    def model(self, model_id: str) -> ModelInfo | None:
+        """Get single model info.  GET /api/models/:provider/:model"""
+        try:
+            data = self._get(f"/api/models/{model_id}")
+        except httpx.HTTPStatusError:
+            return None
+        return self._parse_model(data)
+
+    def search_models(self, query: str) -> list[ModelInfo]:
+        """Search models.  GET /api/models?q=..."""
+        data = self._get("/api/models", {"q": query})
+        return [self._parse_model(m) for m in data.get("models", [])]
+
+    # ---- public methods (async) ----------------------------------------
+
+    async def acheck_provider(self, slug: str) -> CheckResult:
+        data = await self._aget("/api/check", {"provider": slug})
+        return self._parse_check(data)
+
+    async def acheck_model(self, model_id: str) -> CheckResult:
+        data = await self._aget("/api/check", {"model": model_id})
+        return self._parse_check(data)
+
+    # ---- parsers -------------------------------------------------------
+
+    @staticmethod
+    def _parse_check(data: dict) -> CheckResult:
+        return CheckResult(
+            provider=data.get("provider", data.get("slug", "")),
+            status=Status(data.get("status", "unknown")),
+            status_detail=data.get("statusDetail"),
+            model=data.get("model"),
+            alternatives=[
+                Alternative(
+                    slug=a["slug"],
+                    name=a["name"],
+                    status=Status(a["status"]),
+                    suggested_model=a.get("suggestedModel", ""),
+                )
+                for a in data.get("alternatives", [])
+            ],
+        )
+
+    @staticmethod
+    def _parse_model(data: dict) -> ModelInfo:
+        pricing = data.get("pricing", {})
+        prov = data.get("provider", {})
+        return ModelInfo(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            provider_slug=prov.get("slug", "") if isinstance(prov, dict) else "",
+            context_length=data.get("context_length", 0),
+            modality=data.get("modality", "text->text"),
+            prompt_price=float(pricing.get("prompt", 0)),
+            completion_price=float(pricing.get("completion", 0)),
+        )

aistatus-0.0.1/aistatus/exceptions.py

@@ -0,0 +1,58 @@
+"""Exceptions for aistatus SDK."""
+
+
+class AIStatusError(Exception):
+    """Base exception for all aistatus errors."""
+
+
+class AllProvidersDown(AIStatusError):
+    """Raised when no provider in the routing chain is available."""
+
+    def __init__(self, tried: list[str]):
+        self.tried = tried
+        super().__init__(
+            f"All providers unavailable. Tried: {', '.join(tried)}. "
+            f"Check https://aistatus.cc for current status."
+        )
+
+
+class ProviderCallFailed(AIStatusError):
+    """Raised when a provider API call fails (after status was operational)."""
+
+    def __init__(self, provider: str, model: str, cause: Exception):
+        self.provider = provider
+        self.model = model
+        self.cause = cause
+        super().__init__(f"{provider} ({model}) call failed: {cause}")
+
+
+class NoBudgetMatch(AIStatusError):
+    """Raised when no available model fits the budget constraint."""
+
+    def __init__(self, max_cost: float, tier: str):
+        self.max_cost = max_cost
+        super().__init__(
+            f"No operational model in tier '{tier}' under ${max_cost}/M tokens."
+        )
+
+
+class ProviderNotInstalled(AIStatusError):
+    """Raised when the required provider SDK is not installed."""
+
+    def __init__(self, provider: str, package: str):
+        self.provider = provider
+        self.package = package
+        super().__init__(
+            f"Provider '{provider}' requires package '{package}'. "
+            f"Install with: pip install aistatus[{provider}]"
+        )
+
+
+class CheckAPIUnreachable(AIStatusError):
+    """Raised when aistatus.cc API itself is unreachable."""
+
+    def __init__(self):
+        super().__init__(
+            "Could not reach aistatus.cc API. "
+            "Proceeding with primary provider without status check."
+        )