socaity-cli 0.1.1__py3-none-any.whl

socaity_cli/clients/__init__.py

@@ -0,0 +1,18 @@
+"""Domain clients for the socaity platform backend."""
+from socaity_cli.clients.analytics import AnalyticsClient
+from socaity_cli.clients.catalog import CatalogClient
+from socaity_cli.clients.deployment import DeploymentClient
+from socaity_cli.clients.files import FilesClient
+from socaity_cli.clients.jobs import JobsClient
+from socaity_cli.clients.projects import ProjectsClient
+from socaity_cli.clients.sdk_install import SdkInstallClient
+
+__all__ = [
+    "AnalyticsClient",
+    "CatalogClient",
+    "DeploymentClient",
+    "FilesClient",
+    "JobsClient",
+    "ProjectsClient",
+    "SdkInstallClient",
+]

socaity_cli/clients/analytics.py

@@ -0,0 +1,60 @@
+"""Analytics endpoints (`/v1/analytics`)."""
+from typing import Any, Dict, List, Optional
+
+from socaity_schemas.platform import EndpointPricing, EndpointStats, PriceEstimate, SimilarService
+
+
+class AnalyticsClient:
+    """Mixin: estimate, stats, similar services, pricing. Requires ``BackendHttp`` on ``self``."""
+
+    def estimate(
+        self,
+        deployment_id: str,
+        endpoint_id: Optional[str] = None,
+        input_data: Optional[Dict[str, Any]] = None,
+    ) -> Optional[PriceEstimate]:
+        """Predict price and runtime for a job before it runs."""
+        row = self._request(
+            "POST",
+            "v1/analytics/estimate",
+            payload=input_data or {},
+            params={"deployment_id": deployment_id, "endpoint_id": endpoint_id},
+        )
+        return PriceEstimate(**row) if row else None
+
+    def get_stats(
+        self,
+        deployment_id: Optional[str] = None,
+        endpoint_path: Optional[str] = None,
+    ) -> List[EndpointStats]:
+        rows = self._post("v1/analytics/stats", params={
+            "deployment_id": deployment_id,
+            "endpoint_path": endpoint_path,
+        }) or []
+        if not isinstance(rows, list):
+            return []
+        return [EndpointStats(**row) for row in rows]
+
+    def get_similar_services(self, service_id: str, k: int = 8) -> List[SimilarService]:
+        rows = self._get("v1/analytics/similar-services", params={
+            "service_id": service_id,
+            "k": k,
+        }) or []
+        if not isinstance(rows, list):
+            return []
+        return [SimilarService(**row) for row in rows]
+
+    def get_service_pricing(
+        self,
+        service_id: Optional[str] = None,
+        deployment_id: Optional[str] = None,
+        endpoint_id: Optional[str] = None,
+    ) -> List[EndpointPricing]:
+        rows = self._get("v1/analytics/service-pricing", params={
+            "service_id": service_id,
+            "deployment_id": deployment_id,
+            "endpoint_id": endpoint_id,
+        }) or []
+        if not isinstance(rows, list):
+            return []
+        return [EndpointPricing(**row) for row in rows]

socaity_cli/clients/catalog.py

@@ -0,0 +1,147 @@
+"""AI catalog reads (`/v1/catalog`)."""
+from typing import Dict, List, Optional, Union
+
+from socaity_schemas.platform import AIModel, AIService, Job, ServiceCategory
+
+SERVICE_LIST_FIELDS = ["id", "name", "display_name", "short_desc", "categories", "is_official", "n_usages"]
+MODEL_LIST_FIELDS = ["id", "name", "display_name", "family", "release_date", "hugging_face_url"]
+
+
+class CatalogClient:
+    """Mixin: catalog list/get/search. Requires ``BackendHttp`` methods on ``self``."""
+
+    def query_services(
+        self,
+        q: Optional[str] = None,
+        filters: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+        sort: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+        known_ids: Optional[List[str]] = None,
+        known_fieldset: Optional[str] = None,
+    ) -> List[AIService]:
+        rows = self._unwrap_list(self._get("v1/catalog/services", params={
+            "q": q,
+            "filter": filters or [],
+            "expand": expand or [],
+            "fields": fields if fields is not None else SERVICE_LIST_FIELDS,
+            "sort": sort,
+            "limit": limit,
+            "offset": offset,
+            "known_ids": known_ids or [],
+            "known_fieldset": known_fieldset,
+        }))
+        return [AIService(**row) for row in rows]
+
+    def list_services(
+        self,
+        category: Optional[str] = None,
+        fields: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[AIService]:
+        filters = [f"categories:contains:{category}"] if category else None
+        return self.query_services(
+            filters=filters,
+            expand=expand,
+            fields=fields,
+            limit=limit,
+            offset=offset,
+        )
+
+    def get_service(
+        self,
+        id_or_name: str,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+        filters: Optional[List[str]] = None,
+    ) -> Optional[AIService]:
+        row = self._get(f"v1/catalog/services/{id_or_name}", params={
+            "filter": filters or [],
+            "expand": expand if expand is not None else ["deployments", "endpoints", "models"],
+            "fields": fields or [],
+        })
+        return AIService(**row) if row else None
+
+    def query_models(
+        self,
+        q: Optional[str] = None,
+        filters: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+        sort: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+        known_ids: Optional[List[str]] = None,
+        known_fieldset: Optional[str] = None,
+    ) -> List[AIModel]:
+        rows = self._unwrap_list(self._get("v1/catalog/models", params={
+            "q": q,
+            "filter": filters or [],
+            "expand": expand or [],
+            "fields": fields if fields is not None else MODEL_LIST_FIELDS,
+            "sort": sort,
+            "limit": limit,
+            "offset": offset,
+            "known_ids": known_ids or [],
+            "known_fieldset": known_fieldset,
+        }))
+        return [AIModel(**row) for row in rows]
+
+    def list_models(
+        self,
+        family: Optional[str] = None,
+        task: Optional[str] = None,
+        fields: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[AIModel]:
+        filters: List[str] = []
+        if family:
+            filters.append(f"family:eq:{family}")
+        if task:
+            filters.append(f"tasks:contains:{task}")
+        return self.query_models(filters=filters or None, expand=expand, fields=fields, limit=limit, offset=offset)
+
+    def get_model(
+        self,
+        id_or_name: str,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+    ) -> Optional[AIModel]:
+        row = self._get(f"v1/catalog/models/{id_or_name}", params={
+            "expand": expand if expand is not None else ["scores"],
+            "fields": fields or [],
+        })
+        return AIModel(**row) if row else None
+
+    def list_categories(self) -> List[ServiceCategory]:
+        rows = self._get("v1/catalog/categories") or []
+        if isinstance(rows, dict):
+            rows = rows.get("entities") or rows.get("data") or []
+        return [ServiceCategory(**row) for row in rows]
+
+    def list_pricing_rules(self, active_only: bool = True) -> List[Dict]:
+        rows = self._get("v1/catalog/pricing-rules", params={"active_only": active_only}) or []
+        if isinstance(rows, dict):
+            rows = rows.get("entities") or rows.get("data") or []
+        return rows if isinstance(rows, list) else []
+
+    def search(
+        self,
+        query: str,
+        collection: str = "services",
+        filters: Optional[List[str]] = None,
+        limit: int = 20,
+        visibility: str = "user_visible",
+    ) -> List[Union[AIService, AIModel, Job]]:
+        """Full-text search via catalog or jobs ``q`` param (Typesense)."""
+        if collection == "models":
+            return self.query_models(q=query, filters=filters, limit=limit)
+        if collection == "jobs":
+            return self.query_jobs(q=query, filters=filters, visibility=visibility, limit=limit)
+        return self.query_services(q=query, filters=filters, limit=limit)

socaity_cli/clients/deployment.py

@@ -0,0 +1,129 @@
+"""Deployment / hosting write surface (`/v1/deployment`)."""
+from typing import Any, Dict, List, Optional
+
+
+class DeploymentClient:
+    """Mixin: deployment helpers. Requires ``BackendHttp`` methods on ``self``."""
+
+    def analyze_deployment(self, apipod_config: Dict) -> Optional[Dict]:
+        return self._post("v1/deployment/analyze", payload=apipod_config)
+
+    def create_deployment_draft(
+        self,
+        apipod_config: Dict,
+        model_resolutions: Optional[Dict[str, Optional[str]]] = None,
+    ) -> Optional[Dict]:
+        return self._post("v1/deployment/draft", payload={
+            "apipod_config": apipod_config,
+            "model_resolutions": model_resolutions or {},
+        })
+
+    def upsert_hf_token(self, token: str, alias: str = "default") -> Optional[Dict]:
+        return self._post("v1/deployment/hf_token", params={"token": token, "alias": alias})
+
+    def list_hf_tokens(self) -> List[Dict]:
+        return self._get("v1/deployment/hf_token") or []
+
+    # ---- registry deploy pipeline (apipod deploy) ----
+
+    def get_registry_usage(self) -> Optional[Dict]:
+        return self._get("v1/deployment/registry_usage")
+
+    def get_push_credentials(
+        self,
+        deployment_id: str,
+        *,
+        estimated_size_bytes: int = 0,
+    ) -> Optional[Dict]:
+        return self._post(
+            f"v1/deployment/{deployment_id}/push_credentials",
+            params={"estimated_size_bytes": estimated_size_bytes},
+        )
+
+    def confirm_image_pushed(
+        self,
+        deployment_id: str,
+        *,
+        digest: str,
+        size_bytes: int,
+    ) -> Optional[Dict]:
+        return self._post(
+            f"v1/deployment/{deployment_id}/pushed",
+            payload={"digest": digest, "size_bytes": size_bytes},
+        )
+
+    def get_deployment_pipeline_status(self, deployment_id: str) -> Optional[Dict]:
+        return self._get(f"v1/deployment/{deployment_id}")
+
+    def cancel_deployment_pipeline(self, deployment_id: str) -> Optional[Dict]:
+        return self._request("DELETE", f"v1/deployment/{deployment_id}")
+
+    def upsert_ai_service(self, service: Dict[str, Any]) -> Optional[Dict]:
+        return self._post("v1/deployment/upsert_ai_service", payload=service)
+
+    def upsert_service_endpoint(self, service_endpoint: Dict[str, Any]) -> Optional[Dict]:
+        return self._post("v1/deployment/upsert_service_endpoint", payload=service_endpoint)
+
+    def upsert_deployment(
+        self,
+        deployment: Dict[str, Any],
+        service: Optional[Dict[str, Any]] = None,
+    ) -> Optional[Dict]:
+        return self._post("v1/deployment/upsert_deployment", payload={
+            "deployment": deployment,
+            "service": service,
+        })
+
+    def upsert_service(self, service: Dict[str, Any], deployment: Dict[str, Any]) -> Optional[Dict]:
+        return self._post("v1/deployment/upsert_service", payload={
+            "service": service,
+            "deployment": deployment,
+        })
+
+    def order_async_deployment(
+        self,
+        service: Dict[str, Any],
+        deployment: Dict[str, Any],
+    ) -> Optional[Dict]:
+        return self._post("v1/deployment/order_async_deployment", payload={
+            "service": service,
+            "deployment": deployment,
+        })
+
+    def get_deployment_status(
+        self,
+        job_id: str,
+        service_id: str,
+        deployment_id: str,
+        **context,
+    ) -> Optional[Dict]:
+        params = {
+            "job_id": job_id,
+            "service_id": service_id,
+            "deployment_id": deployment_id,
+            **context,
+        }
+        return self._get("v1/deployment/deployment_status", params=params)
+
+    def is_dockerhub_repo_accessible(
+        self,
+        namespace: str,
+        repo: str,
+        tag: str,
+        pat_id: Optional[str] = None,
+    ) -> Any:
+        return self._post("v1/deployment/is_dockerhub_repo_accessible", params={
+            "namespace": namespace,
+            "repo": repo,
+            "tag": tag,
+            "pat_id": pat_id,
+        })
+
+    def is_service_name_available(self, service_name: str) -> bool:
+        return self._get(
+            "v1/deployment/is_service_name_available",
+            params={"service_name": service_name},
+        ) is True
+
+    def delete_service(self, service_id: str) -> Optional[Dict]:
+        return self._post("v1/deployment/delete_service", payload={"service_id": service_id})

socaity_cli/clients/files.py

@@ -0,0 +1,82 @@
+"""User files surface (`/v1/files`)."""
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+
+class FilesClient:
+    """Mixin: storage usage, list, upload, delete. Requires ``BackendHttp`` on ``self``."""
+
+    def get_storage_usage(self) -> Optional[Dict]:
+        return self._get("v1/files/storage_usage")
+
+    def get_user_files(
+        self,
+        purpose: Union[str, List[str]] = "USER_UPLOAD",
+        include_temporary: bool = True,
+        include_deleted: bool = False,
+        is_public: Optional[bool] = None,
+        page: int = 1,
+        page_size: int = 25,
+    ) -> List[Dict]:
+        purposes = purpose if isinstance(purpose, list) else [purpose]
+        rows = self._post("v1/files/user_files", params={
+            "purpose": purposes,
+            "include_temporary": include_temporary,
+            "include_deleted": include_deleted,
+            "is_public": is_public,
+            "page": page,
+            "page_size": page_size,
+        })
+        return rows if isinstance(rows, list) else []
+
+    def delete_file(self, file_id: Union[str, int]) -> bool:
+        return self._post("v1/files/delete_file", params={"file_id": file_id}) is True
+
+    def upload_files(
+        self,
+        files: Union[str, Path, bytes, List[Union[str, Path, bytes]]],
+        file_purpose: str = "USER_UPLOAD",
+        is_public: bool = False,
+        is_temporary: bool = False,
+        job_id: Optional[str] = None,
+    ) -> List[Dict]:
+        """Multipart upload. ``files`` may be paths, bytes, or a list of either."""
+        file_list = files if isinstance(files, list) else [files]
+        multipart = []
+        open_handles = []
+        try:
+            for item in file_list:
+                if isinstance(item, (str, Path)):
+                    handle = open(item, "rb")
+                    open_handles.append(handle)
+                    multipart.append(("files", (Path(item).name, handle)))
+                else:
+                    multipart.append(("files", ("upload.bin", item)))
+
+            params = {
+                "file_purpose": file_purpose,
+                "is_public": str(is_public).lower(),
+                "is_temporary": str(is_temporary).lower(),
+                "job_id": job_id or "",
+            }
+            with httpx.Client() as client:
+                response = client.post(
+                    self.backend_url + "v1/files/upload-files",
+                    params=self._catalog_params(params),
+                    files=multipart,
+                    headers=self._auth_headers,
+                    timeout=400,
+                )
+            if response.status_code == 200:
+                data = response.json()
+                return data if isinstance(data, list) else []
+            print(f"Upload failed with status {response.status_code}: {response.text[:300]}")
+            return []
+        except Exception as exc:
+            print(f"Upload failed: {exc}")
+            return []
+        finally:
+            for handle in open_handles:
+                handle.close()

socaity_cli/clients/jobs.py

@@ -0,0 +1,80 @@
+"""Jobs facade (`/v1/jobs`)."""
+from typing import Dict, List, Optional
+
+from socaity_schemas.platform import Job
+
+
+class JobsClient:
+    """Mixin: jobs list/get/mutate. Requires ``BackendHttp`` methods on ``self``."""
+
+    def query_jobs(
+        self,
+        q: Optional[str] = None,
+        filters: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+        visibility: str = "user_visible",
+        sort: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+        known_ids: Optional[List[str]] = None,
+        known_fieldset: Optional[str] = None,
+    ) -> List[Job]:
+        rows = self._unwrap_list(self._get("v1/jobs", params={
+            "q": q,
+            "visibility": visibility,
+            "filter": filters or [],
+            "expand": expand or [],
+            "fields": fields or [],
+            "sort": sort,
+            "limit": limit,
+            "offset": offset,
+            "known_ids": known_ids or [],
+            "known_fieldset": known_fieldset,
+        }))
+        return [Job(**row) for row in rows]
+
+    def refresh_job(self, job_id: str) -> Optional[Dict]:
+        """Trigger jobs-catalog webhook refresh (cache + Typesense) for one job."""
+        return self._post("v1/jobs/webhooks/finished", params={"job_id": job_id})
+
+    def get_job(
+        self,
+        job_id: str,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+    ) -> Optional[Job]:
+        row = self._get(f"v1/jobs/{job_id}", params={
+            "expand": expand or [],
+            "fields": fields or [],
+        })
+        return Job(**row) if row else None
+
+    def update_job(
+        self,
+        job_id: str,
+        display_name: Optional[str] = None,
+        is_public: Optional[bool] = None,
+    ) -> bool:
+        return self._request("PATCH", f"v1/jobs/{job_id}", params={
+            "display_name": display_name,
+            "is_public": is_public,
+        }) is True
+
+    def update_social_metrics(
+        self,
+        job_id: str,
+        increase_views: Optional[bool] = None,
+        increase_downloads: Optional[bool] = None,
+        increase_shares: Optional[bool] = None,
+        increase_likes: Optional[bool] = None,
+    ) -> bool:
+        return self._post(f"v1/jobs/{job_id}/social", params={
+            "increase_views": increase_views,
+            "increase_downloads": increase_downloads,
+            "increase_shares": increase_shares,
+            "increase_likes": increase_likes,
+        }) is True
+
+    def delete_job(self, job_id: str) -> bool:
+        return self._request("DELETE", f"v1/jobs/{job_id}") is True

socaity_cli/clients/projects.py

@@ -0,0 +1,67 @@
+"""Projects facade (`/v1/projects`)."""
+from typing import List, Optional, Union
+
+from socaity_schemas.platform import Project
+
+
+class ProjectsClient:
+    """Mixin: projects CRUD + members. Requires ``BackendHttp`` methods on ``self``."""
+
+    def query_projects(
+        self,
+        filters: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+        sort: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Project]:
+        rows = self._unwrap_list(self._get("v1/projects", params={
+            "filter": filters or [],
+            "expand": expand or [],
+            "fields": fields or [],
+            "sort": sort or "created_at:desc",
+            "limit": limit,
+            "offset": offset,
+        }))
+        return [Project(**row) for row in rows]
+
+    def get_project(
+        self,
+        project_id: str,
+        expand: Optional[List[str]] = None,
+        fields: Optional[List[str]] = None,
+    ) -> Optional[Project]:
+        row = self._get(f"v1/projects/{project_id}", params={
+            "expand": expand or [],
+            "fields": fields or [],
+        })
+        return Project(**row) if row else None
+
+    def upsert_project(
+        self,
+        display_name: Optional[str] = None,
+        description: Optional[str] = None,
+        project_id: Optional[str] = None,
+    ) -> Optional[str]:
+        return self._request("PUT", "v1/projects", params={
+            "display_name": display_name,
+            "description": description,
+            "project_id": project_id,
+        })
+
+    def delete_project(self, project_id: str) -> bool:
+        return self._request("DELETE", f"v1/projects/{project_id}") is True
+
+    def modify_members(
+        self,
+        project_id: str,
+        job_ids: Optional[List[str]] = None,
+        file_ids: Optional[List[Union[str, int]]] = None,
+        add: bool = True,
+    ) -> bool:
+        return self._post(f"v1/projects/{project_id}/members", params={
+            "job_ids": job_ids or [],
+            "file_ids": file_ids or [],
+            "add": "true" if add else "false",
+        }) is True

socaity_cli/clients/sdk_install.py

@@ -0,0 +1,16 @@
+"""SDK install / update package endpoints."""
+from typing import Dict, List, Optional
+
+
+class SdkInstallClient:
+    """Mixin: SDK package install. Requires ``BackendHttp`` methods on ``self``."""
+
+    def get_service_updates(self, version_index: Dict[str, str]) -> List[Dict]:
+        payload = [
+            {"deployment_id": deployment_id, "specification_hash": spec_hash or ""}
+            for deployment_id, spec_hash in version_index.items()
+        ]
+        return self._post("v1/sdk/update_package", payload) or []
+
+    def install_service(self, service_identifier: str) -> Optional[Dict]:
+        return self._post("v1/sdk/install_service", params={"service": service_identifier})