kitefrost-core 1.0.0__tar.gz

kitefrost_core-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.venv/

kitefrost_core-1.0.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: kitefrost-core
+Version: 1.0.0
+Summary: Shared runtime core (transport, auth, errors, shared-core resource clients) that every per-pack KiteFrost SDK depends on (PPI-3, D-PPI-SDK-BUNDLING Option A).
+Project-URL: Homepage, https://kitefrost.ai
+Project-URL: Repository, https://github.com/kitefrost/python-sdk
+Project-URL: Issues, https://github.com/kitefrost/python-sdk/issues
+License: MIT
+Keywords: ai,core,kitefrost,runtime,sdk
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kitefrost-core
+
+Shared runtime core for the KiteFrost per-pack SDKs (PPI-3, D-PPI-SDK-BUNDLING
+Option A). Importable as `kitefrost_core`.
+
+It owns the cross-pack infrastructure surface so each per-pack SDK does not
+duplicate it:
+
+- HTTP transport (single httpx connection pool)
+- Auth provider with one-shot 401 refresh
+- Typed error hierarchy (`KiteFrostError` and subclasses)
+- The SHARED_TAGS resource clients (auth, keys, billing, projects, events,
+  context, byok, webhooks, health)
+- A lockstep version stamp (`CORE_VERSION`) the per-pack SDKs pin
+
+```python
+from kitefrost_core import KiteFrostCore
+
+core = KiteFrostCore(api_key="sk_live_...")
+print(core.health.check())
+```
+
+When a customer installs more than one per-pack SDK, the packs share a single
+`KiteFrostCore` instance, so they share one auth provider and one connection
+pool (the Option-A DX win).

kitefrost_core-1.0.0/README.md

@@ -0,0 +1,25 @@
+# kitefrost-core
+
+Shared runtime core for the KiteFrost per-pack SDKs (PPI-3, D-PPI-SDK-BUNDLING
+Option A). Importable as `kitefrost_core`.
+
+It owns the cross-pack infrastructure surface so each per-pack SDK does not
+duplicate it:
+
+- HTTP transport (single httpx connection pool)
+- Auth provider with one-shot 401 refresh
+- Typed error hierarchy (`KiteFrostError` and subclasses)
+- The SHARED_TAGS resource clients (auth, keys, billing, projects, events,
+  context, byok, webhooks, health)
+- A lockstep version stamp (`CORE_VERSION`) the per-pack SDKs pin
+
+```python
+from kitefrost_core import KiteFrostCore
+
+core = KiteFrostCore(api_key="sk_live_...")
+print(core.health.check())
+```
+
+When a customer installs more than one per-pack SDK, the packs share a single
+`KiteFrostCore` instance, so they share one auth provider and one connection
+pool (the Option-A DX win).

kitefrost_core-1.0.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kitefrost-core"
+version = "1.0.0"
+description = "Shared runtime core (transport, auth, errors, shared-core resource clients) that every per-pack KiteFrost SDK depends on (PPI-3, D-PPI-SDK-BUNDLING Option A)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["ai", "kitefrost", "sdk", "core", "runtime"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://kitefrost.ai"
+Repository = "https://github.com/kitefrost/python-sdk"
+Issues = "https://github.com/kitefrost/python-sdk/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-httpx>=0.30.0",
+    "ruff>=0.8.0",
+    "mypy>=1.10.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kitefrost_core"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["E501"]
+"src/**/*.py" = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true

kitefrost_core-1.0.0/src/kitefrost_core/__init__.py

@@ -0,0 +1,62 @@
+"""kitefrost-core - shared runtime for every per-pack KiteFrost SDK.
+
+Owns HTTP transport, auth (incl. one-shot 401 refresh), error types, and the
+SHARED_TAGS resource clients. Per-pack SDKs depend on this package and add only
+their pack-specific resources on top (PPI-3, D-PPI-SDK-BUNDLING Option A).
+"""
+
+from __future__ import annotations
+
+from .auth import ApiKeyAuth, AuthProvider, RefreshableTokenAuth
+from .core import KiteFrostCore
+from .exceptions import (
+    AuthError,
+    KiteFrostError,
+    NotFoundError,
+    RateLimited,
+    ServerError,
+    ValidationError,
+)
+from .resources import (
+    AuthResource,
+    BillingResource,
+    ByokResource,
+    ContextResource,
+    EventsResource,
+    HealthResource,
+    KeysResource,
+    ProjectsResource,
+    WebhooksResource,
+)
+from .transport import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, Transport
+from .version import CORE_VERSION, assert_core_version_compatible
+
+__version__ = CORE_VERSION
+
+__all__ = [
+    "KiteFrostCore",
+    "Transport",
+    "AuthProvider",
+    "ApiKeyAuth",
+    "RefreshableTokenAuth",
+    "KiteFrostError",
+    "AuthError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimited",
+    "ServerError",
+    "AuthResource",
+    "KeysResource",
+    "BillingResource",
+    "ProjectsResource",
+    "EventsResource",
+    "ContextResource",
+    "ByokResource",
+    "WebhooksResource",
+    "HealthResource",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "CORE_VERSION",
+    "assert_core_version_compatible",
+    "__version__",
+]

kitefrost_core-1.0.0/src/kitefrost_core/auth.py

@@ -0,0 +1,59 @@
+"""Single auth provider for the shared core.
+
+The Option-A DX win (D-PPI-SDK-BUNDLING): when a customer installs more than one
+per-pack SDK, they share ONE AuthProvider instance (one credential + one
+in-flight refresh) instead of each pack carrying its own token state.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AuthProvider(Protocol):
+    """Supplies the Authorization header and a one-shot refresh after a 401."""
+
+    def auth_header(self) -> str:
+        """Return the current ``Authorization`` header value."""
+        ...
+
+    def refresh(self) -> str | None:
+        """Force a one-shot credential refresh and return the new header.
+
+        Returns ``None`` when this provider cannot refresh (static API keys),
+        so the transport surfaces the 401 unchanged.
+        """
+        ...
+
+
+class ApiKeyAuth:
+    """Static API-key auth. Cannot refresh; a 401 is surfaced as AuthError."""
+
+    def __init__(self, api_key: str) -> None:
+        self._api_key = api_key
+
+    def auth_header(self) -> str:
+        return f"Bearer {self._api_key}"
+
+    def refresh(self) -> str | None:
+        return None
+
+
+class RefreshableTokenAuth:
+    """Bearer-token auth with one-shot refresh via a caller-supplied callback."""
+
+    def __init__(self, initial_token: str, refresh_fn: Callable[[], str]) -> None:
+        self._token = initial_token
+        self._refresh_fn = refresh_fn
+
+    def auth_header(self) -> str:
+        return f"Bearer {self._token}"
+
+    def refresh(self) -> str | None:
+        # Not concurrency-coalesced (unlike the TS RefreshableTokenAuth's inflight
+        # promise): the sync httpx.Client model serializes requests, so parallel
+        # 401s cannot occur. If an async Python transport is ever added, wrap
+        # refresh_fn so concurrent 401s share one refresh.
+        self._token = self._refresh_fn()
+        return f"Bearer {self._token}"

kitefrost_core-1.0.0/src/kitefrost_core/core.py

@@ -0,0 +1,74 @@
+"""Single configuration entry for the shared core.
+
+Constructing one ``KiteFrostCore`` yields ONE auth provider + one Transport
+(one httpx connection pool) that every shared-core resource client reuses.
+Per-pack SDKs accept an existing ``KiteFrostCore`` instance so a customer
+running multiple packs shares a single auth provider / connection pool - the
+Option-A DX win (D-PPI-SDK-BUNDLING).
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from .auth import ApiKeyAuth, AuthProvider
+from .resources import (
+    AuthResource,
+    BillingResource,
+    ByokResource,
+    ContextResource,
+    EventsResource,
+    HealthResource,
+    KeysResource,
+    ProjectsResource,
+    WebhooksResource,
+)
+from .transport import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, Transport
+from .version import CORE_VERSION
+
+
+class KiteFrostCore:
+    """Shared-core entry point. Provide ``api_key`` OR an ``auth`` provider."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        auth: AuthProvider | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+        user_agent: str | None = None,
+    ) -> None:
+        if api_key is None and auth is None:
+            raise ValueError("KiteFrostCore requires either `api_key` or `auth`.")
+
+        self.version = CORE_VERSION
+        auth_provider: AuthProvider = auth if auth is not None else ApiKeyAuth(api_key)  # type: ignore[arg-type]
+
+        self.transport = Transport(
+            auth=auth_provider,
+            base_url=base_url,
+            timeout=timeout,
+            client=http_client,
+            user_agent=user_agent or f"kitefrost-core/{CORE_VERSION}",
+        )
+
+        self.auth = AuthResource(self.transport)
+        self.keys = KeysResource(self.transport)
+        self.billing = BillingResource(self.transport)
+        self.projects = ProjectsResource(self.transport)
+        self.events = EventsResource(self.transport)
+        self.context = ContextResource(self.transport)
+        self.byok = ByokResource(self.transport)
+        self.webhooks = WebhooksResource(self.transport)
+        self.health = HealthResource(self.transport)
+
+    def close(self) -> None:
+        self.transport.close()
+
+    def __enter__(self) -> "KiteFrostCore":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

kitefrost_core-1.0.0/src/kitefrost_core/exceptions.py

@@ -0,0 +1,80 @@
+"""Typed exceptions for the KiteFrost shared core.
+
+Mirrors the hand-written ``kitefrost`` SDK exception surface so per-pack SDKs
+built on the core keep the same DX (KiteFrostError base + AuthError /
+ProjectNotFound / ValidationError / RateLimited / ServerError, plus the
+``feedback_id`` field from C-FB1).
+"""
+
+from __future__ import annotations
+
+
+class KiteFrostError(Exception):
+    """Base exception for all KiteFrost core errors.
+
+    ``feedback_id`` (C-FB1) is a server-issued ULID (prefix ``fbk_``) that
+    uniquely identifies this error instance. Pass it back via
+    ``POST /v1/feedback`` to annotate or bug-report this specific failure.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        feedback_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.feedback_id = feedback_id
+
+    def __str__(self) -> str:
+        base = self.message
+        if self.feedback_id:
+            base = f"{base} [feedback_id={self.feedback_id}]"
+        return base
+
+    def __repr__(self) -> str:
+        cls = self.__class__.__name__
+        return (
+            f"{cls}(message={self.message!r}, status_code={self.status_code}, "
+            f"feedback_id={self.feedback_id!r})"
+        )
+
+
+class AuthError(KiteFrostError):
+    """Raised when credentials are missing, invalid, or lack permission (401/403)."""
+
+
+class NotFoundError(KiteFrostError):
+    """Raised when the requested resource does not exist (404)."""
+
+
+class ValidationError(KiteFrostError):
+    """Raised when the API rejects the request payload (422)."""
+
+
+class RateLimited(KiteFrostError):
+    """Raised when the API rate limit is exceeded (429).
+
+    Inspect ``retry_after`` for the suggested back-off (seconds).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: int | None = None,
+        feedback_id: str | None = None,
+    ) -> None:
+        super().__init__(message, status_code=429, feedback_id=feedback_id)
+        self.retry_after = retry_after
+
+    def __repr__(self) -> str:
+        return (
+            f"RateLimited(message={self.message!r}, retry_after={self.retry_after}, "
+            f"feedback_id={self.feedback_id!r})"
+        )
+
+
+class ServerError(KiteFrostError):
+    """Raised on unexpected 5xx responses from the KiteFrost API."""

kitefrost_core-1.0.0/src/kitefrost_core/resources.py

@@ -0,0 +1,106 @@
+"""Shared-core resource clients.
+
+These cover the SHARED_TAGS surface (src/engine/api/pack_manifest.py: auth,
+keys, billing, projects, events, context, byok, webhooks, health, ...) that is
+identical across every pack and is therefore owned by the core, NOT generated
+per pack (PPI-3). Pack-specific resources are generated on top by STREAM-003
+TASK-003. NO pack-specific code lives here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .transport import Transport
+
+
+class _BaseResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+
+class AuthResource(_BaseResource):
+    """auth tag - whoami / token introspection."""
+
+    def whoami(self) -> Any:
+        return self._t.get("/v1/auth/whoami")
+
+
+class KeysResource(_BaseResource):
+    """keys tag - API key management."""
+
+    def list(self) -> Any:
+        return self._t.get("/v1/keys")
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._t.post("/v1/keys", body)
+
+    def revoke(self, key_id: str) -> Any:
+        return self._t.delete(f"/v1/keys/{quote(key_id)}")
+
+
+class BillingResource(_BaseResource):
+    """billing tag - usage + balance."""
+
+    def usage(self) -> Any:
+        return self._t.get("/v1/billing/usage")
+
+
+class ProjectsResource(_BaseResource):
+    """projects tag - project lifecycle (shared across all packs)."""
+
+    def list(self) -> Any:
+        return self._t.get("/v1/projects")
+
+    def get(self, project_id: str) -> Any:
+        return self._t.get(f"/v1/projects/{quote(project_id)}")
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._t.post("/v1/projects", body)
+
+
+class EventsResource(_BaseResource):
+    """events tag - client/telemetry event ingestion."""
+
+    def send(self, body: dict[str, Any]) -> Any:
+        return self._t.post("/v1/events", body)
+
+
+class ContextResource(_BaseResource):
+    """context tag - shared context retrieval."""
+
+    def get(self, project_id: str, params: dict[str, Any] | None = None) -> Any:
+        return self._t.get(f"/v1/projects/{quote(project_id)}/context", params=params)
+
+
+class ByokResource(_BaseResource):
+    """byok tag - bring-your-own-key provider credentials."""
+
+    def list(self) -> Any:
+        return self._t.get("/v1/byok")
+
+    def set(self, body: dict[str, Any]) -> Any:
+        return self._t.post("/v1/byok", body)
+
+
+class WebhooksResource(_BaseResource):
+    """webhooks tag - webhook subscription management."""
+
+    def list(self) -> Any:
+        return self._t.get("/v1/webhooks")
+
+    def create(self, body: dict[str, Any]) -> Any:
+        return self._t.post("/v1/webhooks", body)
+
+    def delete(self, webhook_id: str) -> Any:
+        return self._t.delete(f"/v1/webhooks/{quote(webhook_id)}")
+
+
+class HealthResource(_BaseResource):
+    """health tag - liveness probe (the canonical core smoke endpoint)."""
+
+    def check(self) -> Any:
+        # Liveness probe is served at the root `/health` (the API does NOT
+        # expose `/v1/health` - that 404s). Found by tests/sdk_live.
+        return self._t.get("/health")

kitefrost_core-1.0.0/src/kitefrost_core/transport.py

@@ -0,0 +1,136 @@
+"""Shared HTTP transport for the core.
+
+Owns header building, error mapping, and the one-shot 401 refresh (mirrors the
+hand-written ``kitefrost`` SDK ``_transport`` + ``http.ts``). A single instance
+is shared across every per-pack resource client so they pool one auth provider.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .auth import AuthProvider
+from .exceptions import (
+    AuthError,
+    KiteFrostError,
+    NotFoundError,
+    RateLimited,
+    ServerError,
+    ValidationError,
+)
+from .version import CORE_VERSION
+
+DEFAULT_BASE_URL = "https://api.kitefrost.ai"
+DEFAULT_TIMEOUT = 30.0
+
+
+def _raise_for_response(response: httpx.Response) -> None:
+    """Map an error response to a typed core exception."""
+    if response.is_success:
+        return
+
+    status = response.status_code
+    body: dict[str, Any] = {}
+    try:
+        parsed = response.json()
+        if isinstance(parsed, dict):
+            body = parsed
+        detail = body.get("detail") or body.get("error") or body.get("message") or response.text
+    except Exception:
+        detail = response.text
+
+    feedback_id = body.get("feedback_id") if isinstance(body, dict) else None
+
+    if status in (401, 403):
+        raise AuthError(detail, status_code=status, feedback_id=feedback_id)
+    if status == 404:
+        raise NotFoundError(detail, status_code=404, feedback_id=feedback_id)
+    if status == 422:
+        raise ValidationError(detail, status_code=422, feedback_id=feedback_id)
+    if status == 429:
+        retry_after: int | None = None
+        raw = response.headers.get("Retry-After")
+        if raw is not None:
+            try:
+                retry_after = int(raw)
+            except ValueError:
+                pass
+        raise RateLimited(detail, retry_after=retry_after, feedback_id=feedback_id)
+    if status >= 500:
+        raise ServerError(detail, status_code=status, feedback_id=feedback_id)
+    raise KiteFrostError(detail, status_code=status, feedback_id=feedback_id)
+
+
+class Transport:
+    """Synchronous HTTP transport with one-shot 401 refresh."""
+
+    def __init__(
+        self,
+        auth: AuthProvider,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.Client | None = None,
+        user_agent: str | None = None,
+    ) -> None:
+        self._auth = auth
+        self._user_agent = user_agent or f"kitefrost-core/{CORE_VERSION}"
+        # A single httpx.Client = one connection pool shared by all resources.
+        self._client = client or httpx.Client(base_url=base_url.rstrip("/"), timeout=timeout)
+
+    def _headers(self, auth_header: str) -> dict[str, str]:
+        return {
+            "Authorization": auth_header,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": self._user_agent,
+        }
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        response = self._client.request(
+            method,
+            path,
+            json=json,
+            params=params,
+            headers=self._headers(self._auth.auth_header()),
+        )
+
+        if response.status_code == 401:
+            refreshed = self._auth.refresh()
+            if refreshed:
+                response = self._client.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                    headers=self._headers(refreshed),
+                )
+
+        _raise_for_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        return self.request("POST", path, json=json or {})
+
+    def patch(self, path: str, json: dict[str, Any]) -> Any:
+        return self.request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self.request("DELETE", path)
+
+    def close(self) -> None:
+        self._client.close()

kitefrost_core-1.0.0/src/kitefrost_core/version.py

@@ -0,0 +1,26 @@
+"""Lockstep version stamp for the shared core (D-PPI-SDK-BUNDLING / D-PPI-SDK-GENERATED).
+
+Every per-pack SDK pins this exact value in lockstep with the backend contract
+release. The per-pack codegen (STREAM-003 TASK-003) reads ``CORE_VERSION`` to
+emit a compatible dependency range and to assert that the installed core matches
+the contract version it was generated against.
+"""
+
+from __future__ import annotations
+
+CORE_VERSION = "1.0.0"
+
+
+def assert_core_version_compatible(required_major: int) -> None:
+    """Assert the installed core satisfies the major a per-pack SDK was built for.
+
+    Lockstep versioning forbids cross-major mixing (a fatal venv skew when two
+    packs pin incompatible cores); same-major is compatible.
+    """
+    installed_major = int(CORE_VERSION.split(".")[0])
+    if installed_major != required_major:
+        raise RuntimeError(
+            f"kitefrost-core version skew: installed {CORE_VERSION} "
+            f"(major {installed_major}) but a pack SDK requires core major {required_major}. "
+            "Per-pack SDKs and the core publish in lockstep; align their versions."
+        )

kitefrost_core-1.0.0/tests/test_core.py

@@ -0,0 +1,103 @@
+"""Unit tests for the kitefrost-core shared runtime.
+
+Uses httpx.MockTransport so no network is touched. Covers the smoke path
+(auth + core endpoint), one-shot 401 refresh, static-key 401 surfacing, and
+error mapping.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from kitefrost_core import (
+    ApiKeyAuth,
+    AuthError,
+    CORE_VERSION,
+    KiteFrostCore,
+    RateLimited,
+    RefreshableTokenAuth,
+    ValidationError,
+    assert_core_version_compatible,
+)
+
+
+def _make_core(handler, auth=None, api_key="sk_test"):
+    mock = httpx.MockTransport(handler)
+    client = httpx.Client(base_url="https://api.example", transport=mock)
+    if auth is not None:
+        return KiteFrostCore(auth=auth, http_client=client)
+    return KiteFrostCore(api_key=api_key, http_client=client)
+
+
+def test_version_stamp_and_compat():
+    assert CORE_VERSION == "1.0.0"
+    assert_core_version_compatible(1)
+    with pytest.raises(RuntimeError, match="version skew"):
+        assert_core_version_compatible(2)
+
+
+def test_requires_api_key_or_auth():
+    with pytest.raises(ValueError, match="requires either"):
+        KiteFrostCore()
+
+
+def test_smoke_core_only_health_call():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["url"] = str(request.url)
+        seen["auth"] = request.headers.get("Authorization")
+        return httpx.Response(200, json={"status": "ok"})
+
+    core = _make_core(handler)
+    assert core.health.check() == {"status": "ok"}
+    assert seen["url"] == "https://api.example/v1/health"
+    assert seen["auth"] == "Bearer sk_test"
+
+
+def test_one_shot_401_refresh_retries():
+    calls = {"n": 0}
+    refreshes = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if request.headers.get("Authorization") == "Bearer stale":
+            return httpx.Response(401, json={"error": "expired"})
+        return httpx.Response(200, json={"ok": True})
+
+    def refresh_fn():
+        refreshes["n"] += 1
+        return "fresh"
+
+    auth = RefreshableTokenAuth("stale", refresh_fn)
+    core = _make_core(handler, auth=auth)
+    assert core.billing.usage() == {"ok": True}
+    assert calls["n"] == 2
+    assert refreshes["n"] == 1
+
+
+def test_static_key_401_surfaces_auth_error():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, json={"error": "bad key"})
+
+    core = _make_core(handler, auth=ApiKeyAuth("nope"))
+    with pytest.raises(AuthError):
+        core.auth.whoami()
+
+
+def test_error_mapping_422_and_429():
+    def handler_422(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(422, json={"detail": "bad payload"})
+
+    core = _make_core(handler_422)
+    with pytest.raises(ValidationError):
+        core.projects.list()
+
+    def handler_429(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(429, json={"error": "slow"}, headers={"Retry-After": "7"})
+
+    core = _make_core(handler_429)
+    with pytest.raises(RateLimited) as exc:
+        core.events.send({"kind": "x"})
+    assert exc.value.retry_after == 7