iis-access 0.1.1__py3-none-any.whl

iis_access/__init__.py

@@ -0,0 +1,19 @@
+"""IIS Tools Python access library - optional auth integration for CLI tools."""
+
+from ._types import AuthContext, ProviderResolution, NoProviderAvailable
+from .auth import get_auth_context, is_authenticated
+from .provider import resolve_provider, register_free_provider
+from .managed_keys import get_managed_key
+from .usage import report_usage
+
+__all__ = [
+    "AuthContext",
+    "ProviderResolution",
+    "NoProviderAvailable",
+    "get_auth_context",
+    "is_authenticated",
+    "resolve_provider",
+    "register_free_provider",
+    "get_managed_key",
+    "report_usage",
+]

iis_access/_types.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class AuthContext:
+    account_id: str
+    access_token: str
+    plan: str  # "free", "pro", "enterprise"
+
+
+@dataclass
+class ProviderResolution:
+    provider: str  # "openai", "elevenlabs", "edge-tts", etc.
+    method: str  # "nexus", "managed_key", "local_key", "free"
+    api_key: str | None  # The key to use (None for free providers)
+    endpoint: str | None  # Override endpoint (for Nexus)
+    credits_estimated: float | None  # Estimated credit cost
+
+
+class NoProviderAvailable(Exception):
+    """Raised when no provider can fulfill the request."""
+
+    pass

iis_access/auth.py

@@ -0,0 +1,150 @@
+import asyncio
+import logging
+
+from ._types import AuthContext
+from .config import get_account_url, get_credentials, is_auth_disabled
+
+logger = logging.getLogger("iis_access")
+
+_cached_context: AuthContext | None = None
+_refresh_lock: asyncio.Lock | None = None
+
+
+def _get_lock() -> asyncio.Lock:
+    global _refresh_lock
+    if _refresh_lock is None:
+        _refresh_lock = asyncio.Lock()
+    return _refresh_lock
+
+
+async def get_auth_context() -> AuthContext | None:
+    """Get authentication context. Returns None if not authenticated."""
+    global _cached_context
+
+    if is_auth_disabled():
+        return None
+
+    if _cached_context is not None:
+        return _cached_context
+
+    async with _get_lock():
+        # Double-check after acquiring lock
+        if _cached_context is not None:
+            return _cached_context
+
+        creds = get_credentials()
+        if not creds or "accountId" not in creds:
+            return None
+
+        account_id = creds["accountId"]
+        refresh_token = _get_refresh_token(account_id)
+        if not refresh_token:
+            return None
+
+        # Exchange refresh token for access token
+        try:
+            import aiohttp
+
+            account_url = get_account_url()
+            timeout = aiohttp.ClientTimeout(total=5)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                resp = await session.post(
+                    f"{account_url}/auth/refresh",
+                    json={"refreshToken": refresh_token},
+                )
+                if resp.status != 200:
+                    logger.info(
+                        "Token refresh failed (status %d), continuing without auth",
+                        resp.status,
+                    )
+                    return None
+
+                data = await resp.json()
+                access_token = data.get("accessToken")
+                new_refresh_token = data.get("refreshToken")
+                plan = data.get("plan") or _extract_plan_from_jwt(access_token)
+
+                if not access_token:
+                    return None
+
+                # Store new refresh token back
+                if new_refresh_token:
+                    _store_refresh_token(account_id, new_refresh_token)
+
+                _cached_context = AuthContext(
+                    account_id=account_id,
+                    access_token=access_token,
+                    plan=plan,
+                )
+                return _cached_context
+
+        except Exception as e:
+            logger.warning("Auth failed (non-fatal): %s", e)
+            return None
+
+
+def is_authenticated() -> bool:
+    """Synchronous check if there are credentials available."""
+    creds = get_credentials()
+    return creds is not None and "accountId" in creds
+
+
+def _get_refresh_token(account_id: str) -> str | None:
+    """Try keyring first, then fall back to credentials file."""
+    # Try keyring (optional dependency)
+    kr = _get_keyring()
+    if kr:
+        try:
+            token = kr.get_password("iis.tools", account_id)
+            if token:
+                return token
+        except Exception:
+            pass
+
+    # Fall back to credentials file
+    creds = get_credentials()
+    if creds and "refreshToken" in creds:
+        return creds["refreshToken"]
+
+    return None
+
+
+def _store_refresh_token(account_id: str, token: str) -> None:
+    """Store refresh token in keyring if available."""
+    kr = _get_keyring()
+    if kr:
+        try:
+            kr.set_password("iis.tools", account_id, token)
+        except Exception as e:
+            logger.debug("Failed to store refresh token in keyring: %s", e)
+
+
+def _extract_plan_from_jwt(token: str | None) -> str:
+    """Extract plan claim from JWT payload without verifying signature."""
+    if not token:
+        return "free"
+    try:
+        import base64, json as _json
+        payload = token.split(".")[1]
+        payload += "=" * (4 - len(payload) % 4)
+        claims = _json.loads(base64.urlsafe_b64decode(payload))
+        return claims.get("plan", "free")
+    except Exception:
+        return "free"
+
+
+def _get_keyring():
+    """Lazy import keyring (optional dependency)."""
+    try:
+        import keyring
+
+        return keyring
+    except ImportError:
+        return None
+
+
+def _reset_auth_cache() -> None:
+    """Reset auth cache (for testing)."""
+    global _cached_context, _refresh_lock
+    _cached_context = None
+    _refresh_lock = None

iis_access/config.py

@@ -0,0 +1,45 @@
+import json
+import os
+from pathlib import Path
+
+_IIS_DIR = Path.home() / ".iis"
+
+
+def get_account_url() -> str:
+    if url := os.environ.get("IIS_ACCOUNT_URL"):
+        return url.rstrip("/")
+    config = _load_config()
+    return config.get("accountUrl", "https://account.iis.tools").rstrip("/")
+
+
+def get_nexus_url() -> str:
+    if url := os.environ.get("IIS_NEXUS_URL"):
+        return url.rstrip("/")
+    config = _load_config()
+    return config.get("nexusUrl", "http://localhost:9666").rstrip("/")
+
+
+def is_auth_disabled() -> bool:
+    return os.environ.get("IIS_NO_AUTH") == "1"
+
+
+def get_credentials() -> dict | None:
+    path = _IIS_DIR / "credentials.json"
+    if not path.exists():
+        return None
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _load_config() -> dict:
+    path = _IIS_DIR / "config.json"
+    if not path.exists():
+        return {}
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}

iis_access/managed_keys.py

@@ -0,0 +1,54 @@
+import logging
+
+from .auth import get_auth_context
+from .config import get_account_url
+
+logger = logging.getLogger("iis_access")
+
+# In-memory cache for managed keys (process lifetime)
+_key_cache: dict[str, str] = {}
+
+
+async def get_managed_key(provider: str) -> str | None:
+    """
+    Retrieve user's managed API key for a provider from iis-account.
+    Returns None if not authenticated, no key exists, or unreachable.
+    """
+    if provider in _key_cache:
+        return _key_cache[provider]
+
+    context = await get_auth_context()
+    if context is None:
+        return None
+
+    try:
+        import aiohttp
+
+        account_url = get_account_url()
+        timeout = aiohttp.ClientTimeout(total=5)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            resp = await session.get(
+                f"{account_url}/keys/managed/{provider}",
+                headers={"Authorization": f"Bearer {context.access_token}"},
+            )
+            if resp.status == 200:
+                data = await resp.json()
+                key = data.get("key")
+                if key:
+                    _key_cache[provider] = key
+                    return key
+            elif resp.status == 404:
+                logger.debug("No managed key for provider '%s'", provider)
+            else:
+                logger.debug(
+                    "Managed key retrieval failed (status %d)", resp.status
+                )
+    except Exception as e:
+        logger.debug("Managed key retrieval failed (non-fatal): %s", e)
+
+    return None
+
+
+def _reset_key_cache() -> None:
+    """Reset managed key cache (for testing)."""
+    _key_cache.clear()

iis_access/nexus.py

@@ -0,0 +1,19 @@
+import logging
+
+from .config import get_nexus_url
+
+logger = logging.getLogger("iis_access")
+
+
+async def is_nexus_running() -> bool:
+    """Check if Nexus local agent is running and responsive."""
+    try:
+        import aiohttp
+
+        nexus_url = get_nexus_url()
+        timeout = aiohttp.ClientTimeout(total=1)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            resp = await session.get(f"{nexus_url}/health")
+            return resp.status == 200
+    except Exception:
+        return False

iis_access/provider.py

@@ -0,0 +1,142 @@
+import os
+import logging
+import shutil
+from typing import Callable
+
+from ._types import ProviderResolution, NoProviderAvailable
+from .nexus import is_nexus_running
+from .managed_keys import get_managed_key
+from .auth import get_auth_context
+
+logger = logging.getLogger("iis_access")
+
+# Known env var names for local API keys
+_ENV_KEY_MAP: dict[str, str] = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "elevenlabs": "ELEVENLABS_API_KEY",
+    "azure-openai": "AZURE_OPENAI_API_KEY",
+    "google-ai": "GOOGLE_AI_API_KEY",
+    "mistral": "MISTRAL_API_KEY",
+    "groq": "GROQ_API_KEY",
+    "deepseek": "DEEPSEEK_API_KEY",
+}
+
+# Free provider registry
+_FREE_PROVIDERS: dict[str, list[tuple[str, Callable[[], bool] | None]]] = {
+    "tts": [
+        ("edge-tts", None),  # Always available (pip package)
+        ("mac-say", lambda: shutil.which("say") is not None),
+    ],
+    "transcription": [
+        ("whisper-local", lambda: shutil.which("whisper") is not None),
+    ],
+}
+
+
+def register_free_provider(
+    task_type: str,
+    provider: str,
+    check: Callable[[], bool] | None = None,
+) -> None:
+    """Register a free provider for a task type."""
+    if task_type not in _FREE_PROVIDERS:
+        _FREE_PROVIDERS[task_type] = []
+    _FREE_PROVIDERS[task_type].append((provider, check))
+
+
+async def resolve_provider(
+    task_type: str,
+    preferred: str | None = None,
+    require_capability: str | None = None,
+) -> ProviderResolution:
+    """
+    Resolve the best provider for the given task type.
+
+    Resolution order:
+    1. Nexus with pooled credits
+    2. Nexus with managed key
+    3. Local API key (env var)
+    4. Free provider
+    5. Raise NoProviderAvailable
+    """
+    context = await get_auth_context()
+
+    # Branch 1 & 2: Nexus
+    if await is_nexus_running():
+        nexus_url = _get_nexus_endpoint()
+
+        # Branch 1: Nexus with pooled credits (if authenticated with plan)
+        if context and context.plan in ("pro", "enterprise"):
+            return ProviderResolution(
+                provider=preferred or "nexus-default",
+                method="nexus",
+                api_key=None,
+                endpoint=nexus_url,
+                credits_estimated=None,  # Nexus handles pricing
+            )
+
+        # Branch 2: Nexus with managed key
+        if context and preferred:
+            managed_key = await get_managed_key(preferred)
+            if managed_key:
+                return ProviderResolution(
+                    provider=preferred,
+                    method="managed_key",
+                    api_key=managed_key,
+                    endpoint=nexus_url,
+                    credits_estimated=None,
+                )
+
+    # Branch 3: Local API key
+    providers_to_check = [preferred] if preferred else list(_ENV_KEY_MAP.keys())
+    for provider in providers_to_check:
+        if not provider:
+            continue
+        env_var = _ENV_KEY_MAP.get(provider)
+        if env_var:
+            key = os.environ.get(env_var)
+            if key:
+                return ProviderResolution(
+                    provider=provider,
+                    method="local_key",
+                    api_key=key,
+                    endpoint=None,
+                    credits_estimated=None,
+                )
+
+    # Also check managed key without Nexus (direct access)
+    if context and preferred:
+        managed_key = await get_managed_key(preferred)
+        if managed_key:
+            return ProviderResolution(
+                provider=preferred,
+                method="managed_key",
+                api_key=managed_key,
+                endpoint=None,
+                credits_estimated=None,
+            )
+
+    # Branch 4: Free provider
+    free_providers = _FREE_PROVIDERS.get(task_type, [])
+    for name, check_fn in free_providers:
+        if check_fn is None or check_fn():
+            return ProviderResolution(
+                provider=name,
+                method="free",
+                api_key=None,
+                endpoint=None,
+                credits_estimated=0,
+            )
+
+    # Branch 5: No provider available
+    raise NoProviderAvailable(
+        f"No provider available for task type '{task_type}'"
+        + (f" (preferred: {preferred})" if preferred else "")
+    )
+
+
+def _get_nexus_endpoint() -> str:
+    from .config import get_nexus_url
+
+    return get_nexus_url()

iis_access/sync.py

@@ -0,0 +1,30 @@
+import asyncio
+
+from ._types import ProviderResolution
+
+
+def resolve_provider_sync(
+    task_type: str,
+    preferred: str | None = None,
+    require_capability: str | None = None,
+) -> ProviderResolution:
+    """Sync wrapper for resolve_provider."""
+    from .provider import resolve_provider
+
+    return asyncio.run(resolve_provider(task_type, preferred, require_capability))
+
+
+def get_managed_key_sync(provider: str) -> str | None:
+    """Sync wrapper for get_managed_key."""
+    from .managed_keys import get_managed_key
+
+    return asyncio.run(get_managed_key(provider))
+
+
+def report_usage_sync(
+    service: str, credits: float = 0, requests: int = 1
+) -> None:
+    """Sync wrapper for report_usage."""
+    from .usage import report_usage
+
+    asyncio.run(report_usage(service, credits, requests))

iis_access/usage.py

@@ -0,0 +1,40 @@
+import logging
+
+from .auth import get_auth_context
+from .config import get_account_url
+
+logger = logging.getLogger("iis_access")
+
+
+async def report_usage(
+    service: str,
+    credits: float = 0,
+    requests: int = 1,
+) -> None:
+    """
+    Fire-and-forget usage report to iis-account.
+    Never raises - logs warnings on failure.
+    Skipped if not authenticated.
+    """
+    context = await get_auth_context()
+    if context is None:
+        return
+
+    try:
+        import aiohttp
+
+        account_url = get_account_url()
+        timeout = aiohttp.ClientTimeout(total=5)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            await session.post(
+                f"{account_url}/usage/record",
+                json={
+                    "accountId": context.account_id,
+                    "service": service,
+                    "requests": requests,
+                    "credits": credits,
+                },
+                headers={"Authorization": f"Bearer {context.access_token}"},
+            )
+    except Exception as e:
+        logger.debug("Usage reporting failed (non-fatal): %s", e)

iis_access-0.1.1.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: iis-access
+Version: 0.1.1
+Summary: Python auth library for IIS tools ecosystem
+Project-URL: Repository, https://github.com/hschmied/account
+Project-URL: Homepage, https://iis.tools
+Author-email: IIS Labs <dev@iis.tools>
+License-Expression: MIT
+Keywords: api-key,auth,iis,provider-resolution
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: aioresponses>=0.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: keyring
+Requires-Dist: keyring>=25.0; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# iis-access
+
+Python auth library for IIS tools ecosystem. Provides optional authentication, provider resolution, managed key retrieval, and usage reporting for Python-based IIS CLI tools (aria, sonar, iris).
+
+## Installation
+
+```bash
+pip install iis-access
+```
+
+## Quick Start
+
+```python
+from iis_access import resolve_provider, report_usage
+
+# Resolve the best available provider for a task
+resolution = await resolve_provider("tts", preferred="elevenlabs")
+print(resolution.provider, resolution.method)
+
+# Report usage (fire-and-forget, never raises)
+await report_usage("aria", credits=1.5)
+```

iis_access-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+iis_access/__init__.py,sha256=pOCjnVHB--w0Eq46f7akfQ2WHqO1y7HCKCg-8oa2Rzw,577
+iis_access/_types.py,sha256=WwyOteO-VyDgRBclXhczSCa-d6g-kZuJfAAcOnT2WB8,613
+iis_access/auth.py,sha256=P4IKxhDvzWPBGHevGs09LaoV3c6BiULL9yNlwieAzQg,4427
+iis_access/config.py,sha256=II9rbpyiUNOq3u5FxjQsbjVaHALtvIO_5j1eHasj1aw,1091
+iis_access/managed_keys.py,sha256=newufFQIbU0NspHWKKWWagWaQeVajDL4zEbbfqDt9Es,1652
+iis_access/nexus.py,sha256=57Em0iS2fXF-eEdywp-iPpki3OfOf5TVFlz0OPUByQA,525
+iis_access/provider.py,sha256=QY9OoE9vAYEiFOzMGncb_Q3iZzpKEIWtysMEOHKEPAE,4359
+iis_access/sync.py,sha256=qqcqK_3XkMrrFN3joMwsU6d895N83vFrl1nveHOKIfA,804
+iis_access/usage.py,sha256=5DNNHTTsbjnb2expBMM-kkXc2z6EfxsiezAPEzfQllI,1126
+iis_access-0.1.1.dist-info/METADATA,sha256=p5f8p8D-5Ou_ifeIugffbQtvIGCD-ncSMInUOPg0CyM,1587
+iis_access-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+iis_access-0.1.1.dist-info/RECORD,,

iis_access-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any