kuberoute 0.1.0__tar.gz

kuberoute-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+.venv/
+bin/
+*.out
+*.log
+.env
+.env.local
+node_modules/
+.next/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/
+.terraform/
+*.tfstate
+*.tfstate.*
+.terraform.lock.hcl
+*.zip
+.DS_Store
+.pids/
+logs/

kuberoute-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: kuberoute
+Version: 0.1.0
+Summary: Official Python SDK for Kuberoute AI Intelligent Routing & Orchestration
+Author-email: Kuberoute AI Team <vikas.budde@hotmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Kuberoute Python SDK
+
+Official Python SDK for [Kuberoute AI](https://kuberoute.ai) — Intelligent Kubernetes Workload Placement & Cost Optimization.
+
+## Installation
+
+```bash
+pip install kuberoute
+```
+
+Or install in editable mode from this monorepo:
+
+```bash
+pip install -e packages/sdk-python
+```
+
+## Quickstart
+
+### Synchronous Usage
+
+```python
+from kuberoute import KubeRoute
+
+# Initialize the client
+client = KubeRoute(
+    base_url="http://localhost:8080", # or https://api.kuberoute.ai
+    token="your-jwt-token"            # or KUBEROUTE_TOKEN env var
+)
+
+# In local dev mode, you can log in directly:
+client.login_dev()
+
+# Check health
+health = client.health()
+print(f"Server status: {health.status}")
+
+# List registered Kubernetes clusters
+clusters = client.clusters.list()
+for cluster in clusters.clusters:
+    print(f"Cluster: {cluster.name} ({cluster.provider}/{cluster.region})")
+
+# Register a new cluster
+new_cluster = client.clusters.create(
+    name="production-eks",
+    provider="aws",
+    region="us-west-2"
+)
+print(f"Registered cluster ID: {new_cluster.id}")
+
+# Fetch routing & placement decisions
+decisions = client.decisions.list(cluster_id=new_cluster.id)
+for d in decisions.decisions:
+    print(f"Decision: {d.id} | Savings: ${d.predicted_cost_savings}/mo | Reason: {d.reason}")
+    if d.confidence_score > 0.9:
+        client.decisions.apply(cluster_id=new_cluster.id, decision_id=d.id)
+        print("Applied decision!")
+
+# Get aggregate infrastructure costs and savings
+costs = client.costs.get_total()
+print(f"Total: ${costs.total} | Optimized: ${costs.optimized} | Savings: ${costs.savings}")
+```
+
+### Asynchronous Usage (`AsyncKubeRoute`)
+
+```python
+import asyncio
+from kuberoute import AsyncKubeRoute
+
+async def main():
+    async with AsyncKubeRoute(base_url="http://localhost:8080", token="your-token") as client:
+        clusters = await client.clusters.list()
+        print(f"Found {clusters.total} clusters")
+
+asyncio.run(main())
+```
+
+## Resources
+
+- **`client.clusters`**: `list()`, `get(id)`, `create(name, provider, region)`, `delete(id)`
+- **`client.decisions`**: `list(cluster_id, status, page, limit)`, `get(cluster_id, decision_id)`, `apply(...)`, `reject(...)`, `revert(...)`
+- **`client.costs`**: `get_total()`, `get_cluster(cluster_id)`
+- **`client.me()`**: Get current authenticated user and tenant credit stats.

kuberoute-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Kuberoute Python SDK
+
+Official Python SDK for [Kuberoute AI](https://kuberoute.ai) — Intelligent Kubernetes Workload Placement & Cost Optimization.
+
+## Installation
+
+```bash
+pip install kuberoute
+```
+
+Or install in editable mode from this monorepo:
+
+```bash
+pip install -e packages/sdk-python
+```
+
+## Quickstart
+
+### Synchronous Usage
+
+```python
+from kuberoute import KubeRoute
+
+# Initialize the client
+client = KubeRoute(
+    base_url="http://localhost:8080", # or https://api.kuberoute.ai
+    token="your-jwt-token"            # or KUBEROUTE_TOKEN env var
+)
+
+# In local dev mode, you can log in directly:
+client.login_dev()
+
+# Check health
+health = client.health()
+print(f"Server status: {health.status}")
+
+# List registered Kubernetes clusters
+clusters = client.clusters.list()
+for cluster in clusters.clusters:
+    print(f"Cluster: {cluster.name} ({cluster.provider}/{cluster.region})")
+
+# Register a new cluster
+new_cluster = client.clusters.create(
+    name="production-eks",
+    provider="aws",
+    region="us-west-2"
+)
+print(f"Registered cluster ID: {new_cluster.id}")
+
+# Fetch routing & placement decisions
+decisions = client.decisions.list(cluster_id=new_cluster.id)
+for d in decisions.decisions:
+    print(f"Decision: {d.id} | Savings: ${d.predicted_cost_savings}/mo | Reason: {d.reason}")
+    if d.confidence_score > 0.9:
+        client.decisions.apply(cluster_id=new_cluster.id, decision_id=d.id)
+        print("Applied decision!")
+
+# Get aggregate infrastructure costs and savings
+costs = client.costs.get_total()
+print(f"Total: ${costs.total} | Optimized: ${costs.optimized} | Savings: ${costs.savings}")
+```
+
+### Asynchronous Usage (`AsyncKubeRoute`)
+
+```python
+import asyncio
+from kuberoute import AsyncKubeRoute
+
+async def main():
+    async with AsyncKubeRoute(base_url="http://localhost:8080", token="your-token") as client:
+        clusters = await client.clusters.list()
+        print(f"Found {clusters.total} clusters")
+
+asyncio.run(main())
+```
+
+## Resources
+
+- **`client.clusters`**: `list()`, `get(id)`, `create(name, provider, region)`, `delete(id)`
+- **`client.decisions`**: `list(cluster_id, status, page, limit)`, `get(cluster_id, decision_id)`, `apply(...)`, `reject(...)`, `revert(...)`
+- **`client.costs`**: `get_total()`, `get_cluster(cluster_id)`
+- **`client.me()`**: Get current authenticated user and tenant credit stats.

kuberoute-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kuberoute"
+version = "0.1.0"
+description = "Official Python SDK for Kuberoute AI Intelligent Routing & Orchestration"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Kuberoute AI Team", email = "vikas.budde@hotmail.com" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Distributed Computing",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.24.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-mock>=3.10.0",
+    "respx>=0.20.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kuberoute"]

kuberoute-0.1.0/src/kuberoute/__init__.py

@@ -0,0 +1,49 @@
+"""Kuberoute Python SDK."""
+
+from .client import KubeRoute, ClustersResource, DecisionsResource, CostsResource
+from .async_client import AsyncKubeRoute, AsyncClustersResource, AsyncDecisionsResource, AsyncCostsResource
+from .models import (
+    User,
+    TenantInfo,
+    CurrentUserResponse,
+    Cluster,
+    ClusterListResponse,
+    Decision,
+    DecisionListResponse,
+    CostSummary,
+    HealthResponse,
+    AuthResponse,
+)
+from .exceptions import (
+    KubeRouteError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+)
+
+__all__ = [
+    "KubeRoute",
+    "AsyncKubeRoute",
+    "ClustersResource",
+    "DecisionsResource",
+    "CostsResource",
+    "AsyncClustersResource",
+    "AsyncDecisionsResource",
+    "AsyncCostsResource",
+    "User",
+    "TenantInfo",
+    "CurrentUserResponse",
+    "Cluster",
+    "ClusterListResponse",
+    "Decision",
+    "DecisionListResponse",
+    "CostSummary",
+    "HealthResponse",
+    "AuthResponse",
+    "KubeRouteError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+]

kuberoute-0.1.0/src/kuberoute/async_client.py

@@ -0,0 +1,182 @@
+"""Asynchronous Kuberoute Client."""
+
+import os
+from typing import Optional, Dict, Any
+import httpx
+
+from .models import (
+    CurrentUserResponse,
+    Cluster,
+    ClusterListResponse,
+    Decision,
+    DecisionListResponse,
+    CostSummary,
+    HealthResponse,
+    AuthResponse,
+)
+from .client import _handle_response
+
+
+class AsyncClustersResource:
+    """Async operations on Kubernetes clusters."""
+
+    def __init__(self, client: "AsyncKubeRoute") -> None:
+        self._client = client
+
+    async def list(self, page: int = 1, limit: int = 20) -> ClusterListResponse:
+        """List all clusters registered with Kuberoute."""
+        data = await self._client._get("/api/v1/clusters", params={"page": page, "limit": limit})
+        return ClusterListResponse.model_validate(data)
+
+    async def get(self, cluster_id: str) -> Cluster:
+        """Get details of a specific cluster by ID."""
+        data = await self._client._get(f"/api/v1/clusters/{cluster_id}")
+        return Cluster.model_validate(data)
+
+    async def create(self, name: str, provider: Optional[str] = None, region: Optional[str] = None) -> Cluster:
+        """Register a new cluster."""
+        payload: Dict[str, Any] = {"name": name}
+        if provider:
+            payload["provider"] = provider
+        if region:
+            payload["region"] = region
+        data = await self._client._post("/api/v1/clusters", json_data=payload)
+        return Cluster.model_validate(data)
+
+    async def delete(self, cluster_id: str) -> None:
+        """Deregister and delete a cluster."""
+        await self._client._delete(f"/api/v1/clusters/{cluster_id}")
+
+
+class AsyncDecisionsResource:
+    """Async operations on AI routing decisions."""
+
+    def __init__(self, client: "AsyncKubeRoute") -> None:
+        self._client = client
+
+    async def list(
+        self,
+        cluster_id: str,
+        status: Optional[str] = None,
+        page: int = 1,
+        limit: int = 20,
+    ) -> DecisionListResponse:
+        """List AI placement and routing decisions for a cluster."""
+        params: Dict[str, Any] = {"page": page, "limit": limit}
+        if status:
+            params["status"] = status
+        data = await self._client._get(f"/api/v1/clusters/{cluster_id}/decisions", params=params)
+        return DecisionListResponse.model_validate(data)
+
+    async def get(self, cluster_id: str, decision_id: str) -> Decision:
+        """Get a single decision by ID."""
+        data = await self._client._get(f"/api/v1/clusters/{cluster_id}/decisions/{decision_id}")
+        return Decision.model_validate(data)
+
+    async def apply(self, cluster_id: str, decision_id: str) -> bool:
+        """Apply an AI routing decision to the cluster."""
+        data = await self._client._post(f"/api/v1/clusters/{cluster_id}/decisions/{decision_id}/apply")
+        return data.get("status") == "applied"
+
+    async def reject(self, cluster_id: str, decision_id: str) -> bool:
+        """Reject an AI routing decision."""
+        data = await self._client._post(f"/api/v1/clusters/{cluster_id}/decisions/{decision_id}/reject")
+        return data.get("status") == "rejected"
+
+    async def revert(self, cluster_id: str, decision_id: str) -> Decision:
+        """Revert a previously applied decision."""
+        data = await self._client._post(f"/api/v1/clusters/{cluster_id}/decisions/{decision_id}/revert")
+        return Decision.model_validate(data)
+
+
+class AsyncCostsResource:
+    """Async operations on infrastructure cost summaries and analytics."""
+
+    def __init__(self, client: "AsyncKubeRoute") -> None:
+        self._client = client
+
+    async def get_total(self) -> CostSummary:
+        """Get aggregate cost summary across all registered clusters."""
+        data = await self._client._get("/api/v1/costs")
+        return CostSummary.model_validate(data)
+
+    async def get_cluster(self, cluster_id: str) -> CostSummary:
+        """Get cost summary and estimated savings for a specific cluster."""
+        data = await self._client._get(f"/api/v1/clusters/{cluster_id}/costs")
+        return CostSummary.model_validate(data)
+
+
+class AsyncKubeRoute:
+    """Asynchronous client for Kuberoute AI Orchestrator API."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        token: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = (
+            base_url
+            or os.environ.get("KUBEROUTE_API_URL")
+            or "http://localhost:8080"
+        ).rstrip("/")
+        self.token = token or os.environ.get("KUBEROUTE_TOKEN")
+        self.timeout = timeout
+        self._client = httpx.AsyncClient(timeout=self.timeout)
+
+        self.clusters = AsyncClustersResource(self)
+        self.decisions = AsyncDecisionsResource(self)
+        self.costs = AsyncCostsResource(self)
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    async def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        resp = await self._client.get(url, headers=self._headers(), params=params)
+        return _handle_response(resp)
+
+    async def _post(self, path: str, json_data: Optional[Dict[str, Any]] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        resp = await self._client.post(url, headers=self._headers(), json=json_data, params=params)
+        return _handle_response(resp)
+
+    async def _delete(self, path: str) -> Any:
+        url = f"{self.base_url}{path}"
+        resp = await self._client.delete(url, headers=self._headers())
+        return _handle_response(resp)
+
+    async def health(self) -> HealthResponse:
+        """Check Orchestrator health status."""
+        data = await self._get("/health")
+        return HealthResponse.model_validate(data)
+
+    async def login_dev(self) -> AuthResponse:
+        """Perform dev authentication (local dev only) and save JWT token."""
+        url = f"{self.base_url}/auth/dev?format=json"
+        resp = await self._client.post(url, headers={"Accept": "application/json"})
+        data = _handle_response(resp)
+        auth_resp = AuthResponse.model_validate(data)
+        self.token = auth_resp.token
+        return auth_resp
+
+    async def me(self) -> CurrentUserResponse:
+        """Get current authenticated user and tenant info."""
+        data = await self._get("/api/v1/me")
+        return CurrentUserResponse.model_validate(data)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncKubeRoute":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()

kuberoute-0.1.0/src/kuberoute/client.py

@@ -0,0 +1,216 @@
+"""Synchronous Kuberoute Client."""
+
+import os
+from typing import Optional, Dict, Any
+import httpx
+
+from .models import (
+    User,
+    CurrentUserResponse,
+    Cluster,
+    ClusterListResponse,
+    Decision,
+    DecisionListResponse,
+    CostSummary,
+    HealthResponse,
+    AuthResponse,
+)
+from .exceptions import (
+    KubeRouteError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+)
+
+
+def _handle_response(resp: httpx.Response) -> Any:
+    if resp.status_code == 204:
+        return None
+    try:
+        data = resp.json()
+    except Exception:
+        data = {"raw": resp.text}
+
+    if resp.status_code >= 400:
+        err_msg = data.get("error") if isinstance(data, dict) else str(data)
+        if not err_msg:
+            err_msg = f"HTTP {resp.status_code}"
+
+        if resp.status_code in (401, 403):
+            raise AuthenticationError(err_msg, status_code=resp.status_code, details=data)
+        elif resp.status_code == 404:
+            raise NotFoundError(err_msg, status_code=resp.status_code, details=data)
+        elif resp.status_code == 400:
+            raise ValidationError(err_msg, status_code=resp.status_code, details=data)
+        elif resp.status_code >= 500:
+            raise ServerError(err_msg, status_code=resp.status_code, details=data)
+        else:
+            raise KubeRouteError(err_msg, status_code=resp.status_code, details=data)
+
+    return data
+
+
+class ClustersResource:
+    """Operations on Kubernetes clusters."""
+
+    def __init__(self, client: "KubeRoute") -> None:
+        self._client = client
+
+    def list(self, page: int = 1, limit: int = 20) -> ClusterListResponse:
+        """List all clusters registered with Kuberoute."""
+        data = self._client._get("/api/v1/clusters", params={"page": page, "limit": limit})
+        return ClusterListResponse.model_validate(data)
+
+    def get(self, cluster_id: str) -> Cluster:
+        """Get details of a specific cluster by ID."""
+        data = self._client._get(f"/api/v1/clusters/{cluster_id}")
+        return Cluster.model_validate(data)
+
+    def create(self, name: str, provider: Optional[str] = None, region: Optional[str] = None) -> Cluster:
+        """Register a new cluster."""
+        payload: Dict[str, Any] = {"name": name}
+        if provider:
+            payload["provider"] = provider
+        if region:
+            payload["region"] = region
+        data = self._client._post("/api/v1/clusters", json_data=payload)
+        return Cluster.model_validate(data)
+
+    def delete(self, cluster_id: str) -> None:
+        """Deregister and delete a cluster."""
+        self._client._delete(f"/api/v1/clusters/{cluster_id}")
+
+
+class DecisionsResource:
+    """Operations on AI routing decisions."""
+
+    def __init__(self, client: "KubeRoute") -> None:
+        self._client = client
+
+    def list(
+        self,
+        cluster_id: str,
+        status: Optional[str] = None,
+        page: int = 1,
+        limit: int = 20,
+    ) -> DecisionListResponse:
+        """List AI placement and routing decisions for a cluster."""
+        params: Dict[str, Any] = {"page": page, "limit": limit}
+        if status:
+            params["status"] = status
+        data = self._client._get(f"/api/v1/clusters/{cluster_id}/decisions", params=params)
+        return DecisionListResponse.model_validate(data)
+
+    def get(self, cluster_id: str, decision_id: str) -> Decision:
+        """Get a single decision by ID."""
+        data = self._client._get(f"/api/v1/clusters/{cluster_id}/decisions/{decision_id}")
+        return Decision.model_validate(data)
+
+    def apply(self, cluster_id: str, decision_id: str) -> bool:
+        """Apply an AI routing decision to the cluster."""
+        data = self._client._post(f"/api/v1/clusters/{cluster_id}/decisions/{decision_id}/apply")
+        return data.get("status") == "applied"
+
+    def reject(self, cluster_id: str, decision_id: str) -> bool:
+        """Reject an AI routing decision."""
+        data = self._client._post(f"/api/v1/clusters/{cluster_id}/decisions/{decision_id}/reject")
+        return data.get("status") == "rejected"
+
+    def revert(self, cluster_id: str, decision_id: str) -> Decision:
+        """Revert a previously applied decision."""
+        data = self._client._post(f"/api/v1/clusters/{cluster_id}/decisions/{decision_id}/revert")
+        return Decision.model_validate(data)
+
+
+class CostsResource:
+    """Operations on infrastructure cost summaries and analytics."""
+
+    def __init__(self, client: "KubeRoute") -> None:
+        self._client = client
+
+    def get_total(self) -> CostSummary:
+        """Get aggregate cost summary across all registered clusters."""
+        data = self._client._get("/api/v1/costs")
+        return CostSummary.model_validate(data)
+
+    def get_cluster(self, cluster_id: str) -> CostSummary:
+        """Get cost summary and estimated savings for a specific cluster."""
+        data = self._client._get(f"/api/v1/clusters/{cluster_id}/costs")
+        return CostSummary.model_validate(data)
+
+
+class KubeRoute:
+    """Synchronous client for Kuberoute AI Orchestrator API."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        token: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = (
+            base_url
+            or os.environ.get("KUBEROUTE_API_URL")
+            or "http://localhost:8080"
+        ).rstrip("/")
+        self.token = token or os.environ.get("KUBEROUTE_TOKEN")
+        self.timeout = timeout
+        self._client = httpx.Client(timeout=self.timeout)
+
+        self.clusters = ClustersResource(self)
+        self.decisions = DecisionsResource(self)
+        self.costs = CostsResource(self)
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        resp = self._client.get(url, headers=self._headers(), params=params)
+        return _handle_response(resp)
+
+    def _post(self, path: str, json_data: Optional[Dict[str, Any]] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        resp = self._client.post(url, headers=self._headers(), json=json_data, params=params)
+        return _handle_response(resp)
+
+    def _delete(self, path: str) -> Any:
+        url = f"{self.base_url}{path}"
+        resp = self._client.delete(url, headers=self._headers())
+        return _handle_response(resp)
+
+    def health(self) -> HealthResponse:
+        """Check Orchestrator health status."""
+        data = self._get("/health")
+        return HealthResponse.model_validate(data)
+
+    def login_dev(self) -> AuthResponse:
+        """Perform dev authentication (local dev only) and save JWT token."""
+        url = f"{self.base_url}/auth/dev?format=json"
+        resp = self._client.post(url, headers={"Accept": "application/json"})
+        data = _handle_response(resp)
+        auth_resp = AuthResponse.model_validate(data)
+        self.token = auth_resp.token
+        return auth_resp
+
+    def me(self) -> CurrentUserResponse:
+        """Get current authenticated user and tenant info."""
+        data = self._get("/api/v1/me")
+        return CurrentUserResponse.model_validate(data)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "KubeRoute":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()

kuberoute-0.1.0/src/kuberoute/exceptions.py

@@ -0,0 +1,38 @@
+"""Kuberoute SDK Exceptions."""
+
+from typing import Optional, Any
+
+
+class KubeRouteError(Exception):
+    """Base exception for all KubeRoute SDK errors."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None, details: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.details = details
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(KubeRouteError):
+    """Raised when authentication fails (401 Unauthorized or 403 Forbidden)."""
+    pass
+
+
+class NotFoundError(KubeRouteError):
+    """Raised when a requested resource is not found (404)."""
+    pass
+
+
+class ValidationError(KubeRouteError):
+    """Raised when request payload or parameters fail validation (400 Bad Request)."""
+    pass
+
+
+class ServerError(KubeRouteError):
+    """Raised when the Kuberoute server returns an internal server error (500+)."""
+    pass

kuberoute-0.1.0/src/kuberoute/models.py

@@ -0,0 +1,91 @@
+"""Pydantic Models for Kuberoute SDK."""
+
+from datetime import datetime
+from typing import Dict, List, Optional, Any
+from pydantic import BaseModel, Field
+
+
+class User(BaseModel):
+    id: str
+    email: Optional[str] = None
+    name: Optional[str] = None
+    avatar_url: Optional[str] = None
+    role: Optional[str] = None
+    tenant_id: Optional[str] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+
+class TenantInfo(BaseModel):
+    id: str
+    plan: str = "free"
+    task_credits: int = 0
+    task_credits_used: int = 0
+
+
+class CurrentUserResponse(BaseModel):
+    user: User
+    tenant: TenantInfo
+
+
+class Cluster(BaseModel):
+    id: str
+    tenant_id: Optional[str] = None
+    name: str
+    provider: Optional[str] = None
+    region: Optional[str] = None
+    k8s_version: Optional[str] = None
+    agent_version: Optional[str] = None
+    status: Optional[str] = "active"
+    node_count: Optional[int] = 0
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+
+class ClusterListResponse(BaseModel):
+    clusters: List[Cluster] = Field(default_factory=list)
+    total: int = 0
+    page: int = 1
+    limit: int = 20
+
+
+class Decision(BaseModel):
+    id: str
+    cluster_id: str
+    workload_id: Optional[str] = None
+    decision_type: Optional[str] = None
+    target_node_id: Optional[str] = None
+    confidence_score: Optional[float] = None
+    predicted_cost_savings: Optional[float] = None
+    predicted_latency_ms: Optional[int] = None
+    reason: Optional[str] = None
+    status: Optional[str] = "pending"
+    applied: Optional[bool] = False
+    applied_at: Optional[datetime] = None
+    applied_by: Optional[str] = None
+    revert_of: Optional[str] = None
+    created_at: Optional[datetime] = None
+
+
+class DecisionListResponse(BaseModel):
+    decisions: List[Decision] = Field(default_factory=list)
+    total: int = 0
+    page: int = 1
+    limit: int = 20
+
+
+class CostSummary(BaseModel):
+    cluster_id: Optional[str] = None
+    total: float = 0.0
+    optimized: float = 0.0
+    savings: float = 0.0
+    breakdown: Dict[str, float] = Field(default_factory=dict)
+
+
+class HealthResponse(BaseModel):
+    status: str = "ok"
+
+
+class AuthResponse(BaseModel):
+    user: User
+    token: str

kuberoute-0.1.0/tests/test_client.py

@@ -0,0 +1,251 @@
+"""Unit tests for Kuberoute Python SDK using built-in httpx.MockTransport."""
+
+import json
+import pytest
+import httpx
+from kuberoute import (
+    KubeRoute,
+    AsyncKubeRoute,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+)
+
+
+def create_mock_transport():
+    def handler(request: httpx.Request) -> httpx.Response:
+        url_path = request.url.path
+        method = request.method
+
+        if url_path == "/health":
+            return httpx.Response(200, json={"status": "ok"})
+
+        if url_path == "/auth/dev":
+            return httpx.Response(
+                200,
+                json={
+                    "user": {
+                        "id": "11111111-1111-1111-1111-111111111111",
+                        "email": "dev@kuberoute.local",
+                        "name": "Dev User",
+                        "role": "admin",
+                        "tenant_id": "22222222-2222-2222-2222-222222222222",
+                    },
+                    "token": "jwt-token-12345",
+                },
+            )
+
+        if url_path == "/api/v1/clusters":
+            if method == "GET":
+                return httpx.Response(
+                    200,
+                    json={
+                        "clusters": [
+                            {
+                                "id": "c111",
+                                "name": "prod-us-east",
+                                "provider": "aws",
+                                "region": "us-east-1",
+                                "status": "active",
+                                "node_count": 5,
+                            }
+                        ],
+                        "total": 1,
+                        "page": 1,
+                        "limit": 20,
+                    },
+                )
+            elif method == "POST":
+                body = json.loads(request.content)
+                return httpx.Response(
+                    201,
+                    json={
+                        "id": "c222",
+                        "name": body.get("name"),
+                        "provider": body.get("provider"),
+                        "region": body.get("region"),
+                        "status": "active",
+                        "node_count": 3,
+                    },
+                )
+
+        if url_path == "/api/v1/clusters/c222":
+            if method == "GET":
+                return httpx.Response(
+                    200,
+                    json={
+                        "id": "c222",
+                        "name": "staging-eu",
+                        "provider": "gcp",
+                        "region": "europe-west1",
+                        "status": "active",
+                        "node_count": 3,
+                    },
+                )
+            elif method == "DELETE":
+                return httpx.Response(204)
+
+        if url_path == "/api/v1/clusters/c111/decisions":
+            return httpx.Response(
+                200,
+                json={
+                    "decisions": [
+                        {
+                            "id": "d111",
+                            "cluster_id": "c111",
+                            "workload_id": "w1",
+                            "decision_type": "placement",
+                            "target_node_id": "node-spot-1",
+                            "confidence_score": 0.95,
+                            "predicted_cost_savings": 42.50,
+                            "predicted_latency_ms": 12,
+                            "status": "pending",
+                        }
+                    ],
+                    "total": 1,
+                    "page": 1,
+                    "limit": 20,
+                },
+            )
+
+        if url_path == "/api/v1/clusters/c111/decisions/d111/apply":
+            return httpx.Response(200, json={"status": "applied"})
+
+        if url_path == "/api/v1/clusters/c111/decisions/d111/reject":
+            return httpx.Response(200, json={"status": "rejected"})
+
+        if url_path == "/api/v1/costs":
+            return httpx.Response(
+                200,
+                json={
+                    "total": 1500.0,
+                    "optimized": 1050.0,
+                    "savings": 450.0,
+                    "breakdown": {"compute": 300.0, "storage": 150.0},
+                },
+            )
+
+        if url_path == "/api/v1/clusters/nonexistent":
+            return httpx.Response(404, json={"error": "not found"})
+
+        if url_path == "/api/v1/me":
+            auth = request.headers.get("Authorization")
+            if not auth or "invalid" in auth:
+                return httpx.Response(401, json={"error": "unauthorized"})
+            return httpx.Response(
+                200,
+                json={
+                    "user": {"id": "u1", "email": "me@kuberoute.local"},
+                    "tenant": {"id": "t1", "plan": "pro", "task_credits": 100, "task_credits_used": 10},
+                },
+            )
+
+        return httpx.Response(404, json={"error": f"route not found: {url_path}"})
+
+    return httpx.MockTransport(handler)
+
+
+@pytest.fixture
+def sync_client():
+    client = KubeRoute(base_url="http://localhost:8080", token="test-token")
+    client._client = httpx.Client(transport=create_mock_transport(), timeout=client.timeout)
+    yield client
+    client.close()
+
+
+@pytest.fixture
+def async_client():
+    client = AsyncKubeRoute(base_url="http://localhost:8080", token="test-token")
+    client._client = httpx.AsyncClient(transport=create_mock_transport(), timeout=client.timeout)
+    yield client
+
+
+def test_health_check(sync_client):
+    resp = sync_client.health()
+    assert resp.status == "ok"
+
+
+def test_dev_login(sync_client):
+    res = sync_client.login_dev()
+    assert res.token == "jwt-token-12345"
+    assert sync_client.token == "jwt-token-12345"
+    assert res.user.email == "dev@kuberoute.local"
+
+
+def test_clusters_crud(sync_client):
+    # List
+    clusters_resp = sync_client.clusters.list()
+    assert clusters_resp.total == 1
+    assert len(clusters_resp.clusters) == 1
+    assert clusters_resp.clusters[0].name == "prod-us-east"
+
+    # Create
+    new_cluster = sync_client.clusters.create(name="staging-eu", provider="gcp", region="europe-west1")
+    assert new_cluster.id == "c222"
+    assert new_cluster.name == "staging-eu"
+
+    # Get
+    fetched = sync_client.clusters.get("c222")
+    assert fetched.id == "c222"
+
+    # Delete
+    sync_client.clusters.delete("c222")
+
+
+def test_decisions_workflow(sync_client):
+    cluster_id = "c111"
+    decision_id = "d111"
+
+    # List decisions
+    decisions = sync_client.decisions.list(cluster_id)
+    assert len(decisions.decisions) == 1
+    assert decisions.decisions[0].predicted_cost_savings == 42.50
+
+    # Apply decision
+    assert sync_client.decisions.apply(cluster_id, decision_id) is True
+
+    # Reject decision
+    assert sync_client.decisions.reject(cluster_id, decision_id) is True
+
+
+def test_costs(sync_client):
+    costs = sync_client.costs.get_total()
+    assert costs.total == 1500.0
+    assert costs.savings == 450.0
+    assert costs.breakdown["compute"] == 300.0
+
+
+def test_me(sync_client):
+    me = sync_client.me()
+    assert me.user.email == "me@kuberoute.local"
+    assert me.tenant.plan == "pro"
+
+
+def test_error_handling(sync_client):
+    with pytest.raises(NotFoundError) as exc_info:
+        sync_client.clusters.get("nonexistent")
+    assert exc_info.value.status_code == 404
+
+    sync_client.token = "invalid"
+    with pytest.raises(AuthenticationError) as exc_info:
+        sync_client.me()
+    assert exc_info.value.status_code == 401
+
+
+def test_async_client():
+    import asyncio
+
+    async def _test():
+        client = AsyncKubeRoute(base_url="http://localhost:8080", token="test-token")
+        client._client = httpx.AsyncClient(transport=create_mock_transport(), timeout=client.timeout)
+
+        resp = await client.health()
+        assert resp.status == "ok"
+
+        clusters = await client.clusters.list()
+        assert len(clusters.clusters) == 1
+        assert clusters.clusters[0].name == "prod-us-east"
+        await client.close()
+
+    asyncio.run(_test())