imperal-sdk 0.1.0__py3-none-any.whl

imperal_sdk/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+"""Imperal Cloud SDK — build extensions for the Imperal platform."""
+from imperal_sdk.extension import Extension, ToolDef, SignalDef, ScheduleDef
+from imperal_sdk.context import Context
+from imperal_sdk.auth import ImperalAuth, AuthError, User
+from imperal_sdk.manifest import generate_manifest, save_manifest
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Extension", "ToolDef", "SignalDef", "ScheduleDef",
+    "Context", "ImperalAuth", "AuthError", "User",
+    "generate_manifest", "save_manifest",
+]

imperal_sdk/ai/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from imperal_sdk.ai.client import AIClient, CompletionResult
+__all__ = ["AIClient", "CompletionResult"]

imperal_sdk/ai/client.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from __future__ import annotations
+from dataclasses import dataclass
+import httpx
+
+
+@dataclass
+class CompletionResult:
+    text: str
+    tokens_used: int = 0
+    model: str = ""
+
+
+class AIClient:
+    """AI completion client. Usage auto-metered by platform."""
+
+    def __init__(self, gateway_url: str, auth_token: str, extension_id: str):
+        self._gateway_url = gateway_url.rstrip("/")
+        self._auth_token = auth_token
+        self._extension_id = extension_id
+
+    async def complete(self, prompt: str, model: str = "claude-sonnet", **kwargs) -> CompletionResult:
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(f"{self._gateway_url}/v1/internal/ai/complete", json={"prompt": prompt, "model": model, "extension_id": self._extension_id, **kwargs}, headers={"Authorization": f"Bearer {self._auth_token}"}, timeout=120)
+            resp.raise_for_status()
+            data = resp.json()
+            return CompletionResult(text=data.get("text", ""), tokens_used=data.get("tokens_used", 0), model=data.get("model", model))

imperal_sdk/auth/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from imperal_sdk.auth.client import ImperalAuth, AuthError
+from imperal_sdk.auth.user import User
+
+__all__ = ["ImperalAuth", "AuthError", "User"]

imperal_sdk/auth/client.py

@@ -0,0 +1,77 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from __future__ import annotations
+import time
+import logging
+
+import httpx
+import jwt
+from jwt import PyJWKClient
+
+from imperal_sdk.auth.user import User
+
+logger = logging.getLogger(__name__)
+
+
+class AuthError(Exception):
+    pass
+
+
+class ImperalAuth:
+    def __init__(self, gateway_url: str = "https://auth.imperal.io"):
+        self._gateway_url = gateway_url.rstrip("/")
+        self._jwks_client: PyJWKClient | None = None
+        self._jwks_last_refresh: float = 0
+        self._jwks_cache_seconds: int = 3600
+
+    def _get_jwks_client(self) -> PyJWKClient:
+        now = time.time()
+        if self._jwks_client is None or (now - self._jwks_last_refresh) > self._jwks_cache_seconds:
+            jwks_url = f"{self._gateway_url}/v1/auth/.well-known/jwks.json"
+            self._jwks_client = PyJWKClient(jwks_url)
+            self._jwks_last_refresh = now
+        return self._jwks_client
+
+    def verify(self, token: str) -> User:
+        try:
+            jwks_client = self._get_jwks_client()
+            signing_key = jwks_client.get_signing_key_from_jwt(token)
+            payload = jwt.decode(
+                token, signing_key.key, algorithms=["RS256"],
+                options={"require": ["sub", "exp", "iat"]},
+            )
+            return User(
+                id=payload["sub"],
+                tenant_id=payload.get("tenant_id", "default"),
+                org_id=payload.get("org_id"),
+                role=payload.get("role", "user"),
+                scopes=payload.get("scopes", []),
+            )
+        except jwt.ExpiredSignatureError:
+            raise AuthError("Token expired")
+        except jwt.InvalidTokenError as e:
+            raise AuthError(f"Invalid token: {e}")
+        except Exception as e:
+            self._jwks_client = None
+            try:
+                jwks_client = self._get_jwks_client()
+                signing_key = jwks_client.get_signing_key_from_jwt(token)
+                payload = jwt.decode(token, signing_key.key, algorithms=["RS256"])
+                return User(
+                    id=payload["sub"],
+                    tenant_id=payload.get("tenant_id", "default"),
+                    org_id=payload.get("org_id"),
+                    role=payload.get("role", "user"),
+                    scopes=payload.get("scopes", []),
+                )
+            except Exception:
+                raise AuthError(f"Token verification failed: {e}")
+
+    async def get_user_info(self, token: str) -> dict:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(
+                f"{self._gateway_url}/v1/auth/me",
+                headers={"Authorization": f"Bearer {token}"},
+            )
+            resp.raise_for_status()
+            return resp.json()

imperal_sdk/auth/middleware.py

@@ -0,0 +1,36 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from __future__ import annotations
+from fastapi import Header, HTTPException
+from imperal_sdk.auth.client import ImperalAuth, AuthError
+from imperal_sdk.auth.user import User
+
+
+def require_auth(auth: ImperalAuth | None = None, gateway_url: str = "https://auth.imperal.io"):
+    _auth = auth or ImperalAuth(gateway_url)
+
+    async def dependency(authorization: str | None = Header(None)) -> User:
+        if not authorization:
+            raise HTTPException(status_code=401, detail="Missing Authorization header")
+        if not authorization.startswith("Bearer "):
+            raise HTTPException(status_code=401, detail="Invalid Authorization header")
+        token = authorization.removeprefix("Bearer ")
+        try:
+            return _auth.verify(token)
+        except AuthError as e:
+            raise HTTPException(status_code=401, detail=str(e))
+
+    return dependency
+
+
+def require_scope(*required_scopes: str, auth: ImperalAuth | None = None, gateway_url: str = "https://auth.imperal.io"):
+    _auth_dep = require_auth(auth=auth, gateway_url=gateway_url)
+
+    async def dependency(authorization: str | None = Header(None)) -> User:
+        user = await _auth_dep(authorization)
+        for scope in required_scopes:
+            if not user.has_scope(scope):
+                raise HTTPException(status_code=403, detail=f"Missing required scope: {scope}")
+        return user
+
+    return dependency

imperal_sdk/auth/user.py

@@ -0,0 +1,25 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from dataclasses import dataclass, field
+
+
+@dataclass
+class User:
+    id: str
+    email: str = ""
+    tenant_id: str = "default"
+    org_id: str | None = None
+    role: str = "user"
+    scopes: list[str] = field(default_factory=list)
+
+    def has_scope(self, scope: str) -> bool:
+        if "*" in self.scopes:
+            return True
+        for s in self.scopes:
+            if s == scope:
+                return True
+            if s.endswith(".*"):
+                prefix = s[:-2]
+                if scope.startswith(prefix + ".") or scope == prefix:
+                    return True
+        return False

imperal_sdk/billing/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from imperal_sdk.billing.client import BillingClient, LimitsResult, SubscriptionInfo
+__all__ = ["BillingClient", "LimitsResult", "SubscriptionInfo"]

imperal_sdk/billing/client.py

@@ -0,0 +1,53 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any
+import httpx
+
+
+@dataclass
+class LimitsResult:
+    plan: str
+    usage: dict[str, int]
+    limits: dict[str, int]
+    exceeded: list[str]
+
+    def is_exceeded(self, meter: str) -> bool:
+        return meter in self.exceeded
+
+    @property
+    def any_exceeded(self) -> bool:
+        return len(self.exceeded) > 0
+
+
+@dataclass
+class SubscriptionInfo:
+    plan: str
+    status: str
+    started_at: str | None = None
+    expires_at: str | None = None
+
+
+class BillingClient:
+    """Read-only billing client for extensions."""
+
+    def __init__(self, gateway_url: str, auth_token: str):
+        self._gateway_url = gateway_url.rstrip("/")
+        self._auth_token = auth_token
+
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bearer {self._auth_token}"}
+
+    async def check_limits(self, user: Any = None) -> LimitsResult:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(f"{self._gateway_url}/v1/billing/usage", headers=self._headers(), timeout=10)
+            resp.raise_for_status()
+            data = resp.json()
+            return LimitsResult(plan=data["plan"], usage=data["usage"], limits=data["limits"], exceeded=data["exceeded"])
+
+    async def get_subscription(self, user: Any = None) -> SubscriptionInfo:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(f"{self._gateway_url}/v1/billing/subscription", headers=self._headers(), timeout=10)
+            resp.raise_for_status()
+            return SubscriptionInfo(**resp.json())

imperal_sdk/cli/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.

imperal_sdk/cli/main.py

@@ -0,0 +1,117 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+"""Imperal Cloud SDK CLI."""
+import os
+import click
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def cli():
+    """Imperal Cloud SDK — build extensions for the Imperal platform."""
+    pass
+
+
+@cli.command()
+@click.argument("name")
+def init(name: str):
+    """Scaffold a new extension project."""
+    os.makedirs(name, exist_ok=True)
+    os.makedirs(f"{name}/tests", exist_ok=True)
+
+    with open(f"{name}/main.py", "w") as f:
+        f.write(f'''from imperal_sdk import Extension
+
+ext = Extension("{name}", version="0.1.0")
+
+
+@ext.tool("hello", description="Say hello")
+async def hello(ctx, name: str = "World"):
+    """Say hello."""
+    return {{"message": f"Hello, {{name}}!"}}
+''')
+
+    with open(f"{name}/requirements.txt", "w") as f:
+        f.write("imperal-sdk>=0.1.0\n")
+
+    with open(f"{name}/tests/__init__.py", "w") as f:
+        pass
+
+    with open(f"{name}/tests/test_hello.py", "w") as f:
+        f.write(f'''import pytest
+from main import ext
+
+
+def test_hello_tool_registered():
+    assert "hello" in ext.tools
+
+
+@pytest.mark.asyncio
+async def test_hello_tool():
+    result = await ext.call_tool("hello", ctx=None, name="Imperal")
+    assert result == {{"message": "Hello, Imperal!"}}
+''')
+
+    with open(f"{name}/.gitignore", "w") as f:
+        f.write("venv/\n__pycache__/\n*.pyc\n.env\nmanifest.json\n")
+
+    click.echo(f"Extension '{name}' created!")
+    click.echo(f"  cd {name}")
+    click.echo(f"  pip install imperal-sdk")
+    click.echo(f"  imperal dev")
+
+
+@cli.command()
+def dev():
+    """Run local development server with hot reload."""
+    import sys
+    sys.path.insert(0, ".")
+    try:
+        from main import ext
+        from imperal_sdk.manifest import generate_manifest
+        manifest = generate_manifest(ext)
+        click.echo(f"Extension: {ext.app_id} v{ext.version}")
+        click.echo(f"Tools: {', '.join(ext.tools.keys()) or 'none'}")
+        click.echo(f"Signals: {', '.join(ext.signals.keys()) or 'none'}")
+        click.echo(f"Schedules: {', '.join(ext.schedules.keys()) or 'none'}")
+        click.echo("Dev server ready. Ctrl+C to stop.")
+    except ImportError:
+        click.echo("Error: No main.py found with 'ext' Extension object.", err=True)
+        raise SystemExit(1)
+
+
+@cli.command()
+def test():
+    """Run extension tests."""
+    import subprocess
+    result = subprocess.run(["python", "-m", "pytest", "tests/", "-v"])
+    raise SystemExit(result.returncode)
+
+
+@cli.command()
+def deploy():
+    """Deploy extension to Imperal Cloud."""
+    import sys
+    sys.path.insert(0, ".")
+    try:
+        from main import ext
+        from imperal_sdk.manifest import generate_manifest, save_manifest
+        save_manifest(ext)
+        click.echo(f"Manifest generated: manifest.json")
+        click.echo(f"Extension: {ext.app_id} v{ext.version}")
+        click.echo("Deploy to Imperal Cloud...")
+        click.echo("(Not yet implemented — will push to Registry)")
+    except ImportError:
+        click.echo("Error: No main.py found.", err=True)
+        raise SystemExit(1)
+
+
+@cli.command()
+def logs():
+    """Tail production logs."""
+    click.echo("Connecting to Imperal Cloud logs...")
+    click.echo("(Not yet implemented — will stream from SigNoz)")
+
+
+if __name__ == "__main__":
+    cli()

imperal_sdk/context.py

@@ -0,0 +1,74 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class StoreProtocol(Protocol):
+    async def create(self, collection: str, data: dict) -> Any: ...
+    async def get(self, collection: str, doc_id: str) -> Any: ...
+    async def query(self, collection: str, where: dict | None = None, order_by: str | None = None, limit: int = 100) -> list: ...
+    async def update(self, collection: str, doc_id: str, data: dict) -> Any: ...
+    async def delete(self, collection: str, doc_id: str) -> bool: ...
+    async def count(self, collection: str, where: dict | None = None) -> int: ...
+
+
+@runtime_checkable
+class DBProtocol(Protocol):
+    async def acquire(self): ...
+    async def session(self): ...
+
+
+@runtime_checkable
+class AIProtocol(Protocol):
+    async def complete(self, prompt: str, model: str = "claude-sonnet", **kwargs) -> Any: ...
+
+
+@runtime_checkable
+class SkeletonProtocol(Protocol):
+    async def get(self, section: str) -> Any: ...
+    async def update(self, section: str, data: Any) -> None: ...
+
+
+@runtime_checkable
+class BillingProtocol(Protocol):
+    async def check_limits(self, user: Any = None) -> Any: ...
+    async def get_subscription(self, user: Any = None) -> Any: ...
+
+
+@runtime_checkable
+class NotifyProtocol(Protocol):
+    async def __call__(self, message: str, **kwargs) -> None: ...
+
+
+@runtime_checkable
+class StorageProtocol(Protocol):
+    async def upload(self, path: str, data: bytes, content_type: str = "application/octet-stream") -> str: ...
+    async def download(self, path: str) -> bytes: ...
+    async def delete(self, path: str) -> bool: ...
+    async def list(self, prefix: str = "") -> list[str]: ...
+
+
+@runtime_checkable
+class HTTPProtocol(Protocol):
+    async def get(self, url: str, **kwargs) -> Any: ...
+    async def post(self, url: str, **kwargs) -> Any: ...
+
+
+@dataclass
+class Context:
+    """The context object passed to every extension tool/signal/schedule call."""
+    user: Any
+    tenant: Any = None
+    store: StoreProtocol | None = None
+    db: DBProtocol | None = None
+    ai: AIProtocol | None = None
+    skeleton: SkeletonProtocol | None = None
+    billing: BillingProtocol | None = None
+    notify: NotifyProtocol | None = None
+    storage: StorageProtocol | None = None
+    http: HTTPProtocol | None = None
+    _extension_id: str = ""
+    _metadata: dict = field(default_factory=dict)

imperal_sdk/db/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from imperal_sdk.db.client import DBClient
+__all__ = ["DBClient"]

imperal_sdk/db/client.py

@@ -0,0 +1,36 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from __future__ import annotations
+from contextlib import asynccontextmanager
+from typing import Any
+
+
+class DBClient:
+    """Tier 2: Dedicated schema access."""
+
+    def __init__(self, connection_factory):
+        self._factory = connection_factory
+
+    @asynccontextmanager
+    async def acquire(self):
+        conn = await self._factory.acquire()
+        try:
+            yield conn
+        finally:
+            await self._factory.release(conn)
+
+    @asynccontextmanager
+    async def session(self):
+        session = await self._factory.create_session()
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()
+
+    async def raw(self, query: str, params: tuple | None = None) -> list[dict[str, Any]]:
+        async with self.acquire() as conn:
+            return await conn.execute(query, params)

imperal_sdk/extension.py

@@ -0,0 +1,96 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from __future__ import annotations
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class ToolDef:
+    name: str
+    func: Callable
+    scopes: list[str] = field(default_factory=list)
+    description: str = ""
+
+
+@dataclass
+class SignalDef:
+    name: str
+    func: Callable
+
+
+@dataclass
+class ScheduleDef:
+    name: str
+    func: Callable
+    cron: str
+
+
+class Extension:
+    """Imperal Cloud Extension."""
+
+    def __init__(
+        self,
+        app_id: str,
+        version: str = "0.1.0",
+        capabilities: list[str] | None = None,
+        migrations_dir: str | None = None,
+    ):
+        self.app_id = app_id
+        self.version = version
+        self.capabilities = capabilities or []
+        self.migrations_dir = migrations_dir
+        self._tools: dict[str, ToolDef] = {}
+        self._signals: dict[str, SignalDef] = {}
+        self._schedules: dict[str, ScheduleDef] = {}
+
+    def tool(self, name: str, scopes: list[str] | None = None, description: str = ""):
+        """Register a tool that the AI assistant can call."""
+        def decorator(func: Callable) -> Callable:
+            self._tools[name] = ToolDef(
+                name=name,
+                func=func,
+                scopes=scopes or [],
+                description=description or func.__doc__ or "",
+            )
+            return func
+        return decorator
+
+    def signal(self, name: str):
+        """Register a signal handler for platform events."""
+        def decorator(func: Callable) -> Callable:
+            self._signals[name] = SignalDef(name=name, func=func)
+            return func
+        return decorator
+
+    def schedule(self, name: str, cron: str):
+        """Register a scheduled task."""
+        def decorator(func: Callable) -> Callable:
+            self._schedules[name] = ScheduleDef(name=name, func=func, cron=cron)
+            return func
+        return decorator
+
+    @property
+    def tools(self) -> dict[str, ToolDef]:
+        return self._tools
+
+    @property
+    def signals(self) -> dict[str, SignalDef]:
+        return self._signals
+
+    @property
+    def schedules(self) -> dict[str, ScheduleDef]:
+        return self._schedules
+
+    async def call_tool(self, name: str, ctx: Any, **kwargs) -> Any:
+        """Call a registered tool with context."""
+        if name not in self._tools:
+            raise ValueError(f"Unknown tool: {name}")
+        return await self._tools[name].func(ctx, **kwargs)
+
+    async def call_signal(self, name: str, ctx: Any, **kwargs) -> Any:
+        """Call a registered signal handler."""
+        if name not in self._signals:
+            raise ValueError(f"Unknown signal: {name}")
+        return await self._signals[name].func(ctx, **kwargs)

imperal_sdk/http/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from imperal_sdk.http.client import HTTPClient
+__all__ = ["HTTPClient"]

imperal_sdk/http/client.py

@@ -0,0 +1,30 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from __future__ import annotations
+import httpx
+
+
+class HTTPClient:
+    def __init__(self, timeout: int = 30, max_redirects: int = 5):
+        self._timeout = timeout
+        self._max_redirects = max_redirects
+
+    async def get(self, url: str, **kwargs) -> httpx.Response:
+        async with httpx.AsyncClient(timeout=self._timeout, follow_redirects=True, max_redirects=self._max_redirects) as client:
+            return await client.get(url, **kwargs)
+
+    async def post(self, url: str, **kwargs) -> httpx.Response:
+        async with httpx.AsyncClient(timeout=self._timeout, follow_redirects=True, max_redirects=self._max_redirects) as client:
+            return await client.post(url, **kwargs)
+
+    async def put(self, url: str, **kwargs) -> httpx.Response:
+        async with httpx.AsyncClient(timeout=self._timeout, follow_redirects=True, max_redirects=self._max_redirects) as client:
+            return await client.put(url, **kwargs)
+
+    async def patch(self, url: str, **kwargs) -> httpx.Response:
+        async with httpx.AsyncClient(timeout=self._timeout, follow_redirects=True, max_redirects=self._max_redirects) as client:
+            return await client.patch(url, **kwargs)
+
+    async def delete(self, url: str, **kwargs) -> httpx.Response:
+        async with httpx.AsyncClient(timeout=self._timeout, follow_redirects=True, max_redirects=self._max_redirects) as client:
+            return await client.delete(url, **kwargs)