Buckets:
| """Async SDK client for the yaai monitoring platform.""" | |
| from __future__ import annotations | |
| import uuid | |
| import httpx | |
| from yaai.schemas.inference import ( | |
| GroundTruthCreate, | |
| InferenceBatchCreate, | |
| InferenceBatchResult, | |
| InferenceCreate, | |
| InferenceRead, | |
| ReferenceDataResult, | |
| ReferenceDataUpload, | |
| ) | |
| from yaai.schemas.model import ( | |
| BatchValidationResult, | |
| InferSchemaBatchRequest, | |
| InferSchemaResponse, | |
| ModelCreate, | |
| ModelRead, | |
| ModelVersionCreate, | |
| ModelVersionRead, | |
| ModelVersionSummary, | |
| SchemaFieldCreate, | |
| ValidateModelVersionBatchRequest, | |
| ValidateModelVersionRequest, | |
| ValidateSchemaBatchRequest, | |
| ValidateSchemaRequest, | |
| ValidationResult, | |
| ) | |
| class YaaiClient: | |
| """Async client for the yaai monitoring API. | |
| Authenticates with either an explicit API key or Google Application | |
| Default Credentials (ADC). When no ``api_key`` is provided the client | |
| tries to obtain credentials via ``google.auth.default()`` — install | |
| ``yaai[gcp]`` to enable this. | |
| When ``target_audience`` is provided (recommended for Google SA auth), | |
| the client requests an ID token scoped to that audience. The audience | |
| must match the server's configured | |
| ``GOOGLE_SA_AUDIENCE``. | |
| Usage:: | |
| # With API key | |
| async with YaaiClient("http://localhost:8000/api/v1", api_key="yaam_...") as client: | |
| model = await client.create_model("my-model") | |
| # With Google ADC + ID token (recommended for service accounts) | |
| async with YaaiClient("http://localhost:8000/api/v1", target_audience="https://yaai.example.com") as client: | |
| model = await client.create_model("my-model") | |
| # With Google user ADC (ID token) | |
| async with YaaiClient("http://localhost:8000/api/v1") as client: | |
| model = await client.create_model("my-model") | |
| # With a longer timeout for slow server responses | |
| async with YaaiClient("http://localhost:8000/api/v1", api_key="yaam_...", timeout=60.0) as client: | |
| model = await client.create_model("my-model") | |
| """ | |
| def __init__( | |
| self, | |
| base_url: str, | |
| *, | |
| api_key: str | None = None, | |
| target_audience: str | None = None, | |
| timeout: float = 30.0, | |
| ) -> None: | |
| self._base_url = base_url.rstrip("/") | |
| self._credentials = None | |
| self._google_request = None | |
| if api_key is not None: | |
| headers: dict[str, str] = {"X-API-Key": api_key} | |
| else: | |
| headers = self._init_google_credentials(target_audience) | |
| self._client = httpx.AsyncClient(base_url=self._base_url, headers=headers, timeout=timeout) | |
| def _init_google_credentials(self, target_audience: str | None = None) -> dict[str, str]: | |
| """Obtain Google ADC and return initial auth headers.""" | |
| try: | |
| import google.auth # noqa: PLC0415 | |
| import google.auth.transport.requests # noqa: PLC0415 | |
| from google.auth import exceptions as google_auth_exceptions # noqa: PLC0415 # noqa: PLC0415 | |
| from google.oauth2 import id_token as google_id_token # noqa: PLC0415 | |
| except ImportError as exc: | |
| msg = ( | |
| "No api_key provided and google-auth is not installed. " | |
| "Either pass api_key= or install yaai[gcp] for Google " | |
| "Application Default Credentials." | |
| ) | |
| raise ImportError(msg) from exc | |
| self._google_request = google.auth.transport.requests.Request() | |
| credentials, _ = google.auth.default() | |
| if target_audience: | |
| try: | |
| self._credentials = google_id_token.fetch_id_token_credentials( | |
| target_audience, | |
| request=self._google_request, | |
| ) | |
| except google_auth_exceptions.DefaultCredentialsError: | |
| if hasattr(credentials, "with_target_audience"): | |
| self._credentials = credentials.with_target_audience(target_audience) | |
| else: | |
| self._credentials = credentials | |
| else: | |
| self._credentials = credentials | |
| self._credentials.refresh(self._google_request) | |
| token = self._current_google_token() | |
| if not token: | |
| if target_audience: | |
| msg = ( | |
| "Could not obtain an ID token for the configured target_audience. " | |
| "Cloud Run and service-account credentials should use metadata or " | |
| "GOOGLE_APPLICATION_CREDENTIALS; user ADC falls back to a generic " | |
| "Google ID token when available." | |
| ) | |
| else: | |
| msg = "Could not obtain an ID token from user credentials. Run: gcloud auth application-default login" | |
| raise RuntimeError(msg) | |
| return {"Authorization": f"Bearer {token}"} | |
| def _current_google_token(self) -> str | None: | |
| """Return the current Google bearer token for the active credential.""" | |
| if self._credentials is None: | |
| return None | |
| token = getattr(self._credentials, "id_token", None) | |
| if token: | |
| return token | |
| return getattr(self._credentials, "token", None) | |
| def _refresh_google_credentials(self) -> None: | |
| """Refresh Google credentials if expired. No-op for API key auth.""" | |
| if self._credentials is None: | |
| return | |
| if not self._credentials.valid: | |
| self._credentials.refresh(self._google_request) | |
| token = self._current_google_token() | |
| self._client.headers["Authorization"] = f"Bearer {token}" | |
| async def _request(self, method: str, url: str, **kwargs: object) -> httpx.Response: | |
| """Send a request with automatic credential refresh.""" | |
| self._refresh_google_credentials() | |
| resp = await self._client.request(method, url, **kwargs) | |
| self._raise_for_status(resp) | |
| return resp | |
| async def __aenter__(self) -> YaaiClient: | |
| return self | |
| async def __aexit__(self, *args: object) -> None: | |
| await self.close() | |
| async def close(self) -> None: | |
| await self._client.aclose() | |
| def _raise_for_status(self, response: httpx.Response) -> None: | |
| if response.is_error: | |
| try: | |
| body = response.json() | |
| detail = body.get("detail", response.text) if isinstance(body, dict) else response.text | |
| except Exception: | |
| detail = response.text | |
| raise httpx.HTTPStatusError( | |
| f"{response.status_code}: {detail}", | |
| request=response.request, | |
| response=response, | |
| ) | |
| # -- Models -- | |
| async def create_model(self, name: str, description: str | None = None) -> ModelRead: | |
| payload = ModelCreate(name=name, description=description) | |
| resp = await self._request("POST", "/models", json=payload.model_dump()) | |
| return ModelRead.model_validate(resp.json()["data"]) | |
| async def get_model(self, model_id: uuid.UUID) -> ModelRead: | |
| resp = await self._request("GET", f"/models/{model_id}") | |
| return ModelRead.model_validate(resp.json()["data"]) | |
| async def list_models(self) -> list[ModelRead]: | |
| resp = await self._request("GET", "/models") | |
| return [ModelRead.model_validate(m) for m in resp.json()["data"]] | |
| async def delete_model(self, model_id: uuid.UUID) -> None: | |
| await self._request("DELETE", f"/models/{model_id}") | |
| # -- Versions -- | |
| async def get_version( | |
| self, | |
| model_id: uuid.UUID, | |
| version_id: uuid.UUID, | |
| ) -> ModelVersionRead: | |
| """Fetch full details for a specific model version.""" | |
| resp = await self._request("GET", f"/models/{model_id}/versions/{version_id}") | |
| return ModelVersionRead.model_validate(resp.json()["data"]) | |
| async def create_model_version( | |
| self, | |
| model_id: uuid.UUID, | |
| version: str, | |
| schema_fields: list[SchemaFieldCreate], | |
| *, | |
| description: str | None = None, | |
| keep_previous_active: bool = False, | |
| ) -> ModelVersionRead: | |
| payload = ModelVersionCreate( | |
| version=version, | |
| schema_fields=schema_fields, | |
| description=description, | |
| keep_previous_active=keep_previous_active, | |
| ) | |
| resp = await self._request( | |
| "POST", | |
| f"/models/{model_id}/versions", | |
| json=payload.model_dump(by_alias=True), | |
| ) | |
| return ModelVersionRead.model_validate(resp.json()["data"]) | |
| async def get_version_by_label( | |
| self, | |
| model_id: uuid.UUID, | |
| version: str, | |
| ) -> ModelVersionSummary | None: | |
| """Look up a model version by its label. | |
| Returns the :class:`ModelVersionSummary` if a version with the given | |
| label exists, or ``None`` otherwise. | |
| """ | |
| model = await self.get_model(model_id) | |
| return next((v for v in model.versions if v.version == version), None) | |
| async def get_or_create_version( | |
| self, | |
| model_id: uuid.UUID, | |
| version: str, | |
| *, | |
| sample_data: dict[str, dict] | None = None, | |
| schema_fields: list[SchemaFieldCreate] | None = None, | |
| description: str | None = None, | |
| keep_previous_active: bool = False, | |
| ) -> ModelVersionRead | ModelVersionSummary: | |
| """Idempotent version upsert: return existing or create new. | |
| Always requires exactly one of ``sample_data`` or ``schema_fields`` | |
| so the call is deterministic regardless of server state. If the | |
| version already exists the creation parameters are ignored and the | |
| existing :class:`ModelVersionSummary` is returned. If it doesn't | |
| exist, a new version is created from the provided schema info. | |
| For a pure lookup without creation parameters, use | |
| :meth:`get_version_by_label` instead. | |
| Args: | |
| model_id: The UUID of the parent model. | |
| version: Human-readable version label (e.g. ``"v2.0"``). | |
| sample_data: A dict with ``"inputs"`` and ``"outputs"`` keys used | |
| to infer the schema. Mutually exclusive with | |
| ``schema_fields``. | |
| schema_fields: An explicit list of :class:`SchemaFieldCreate` | |
| objects defining the version's schema. Mutually exclusive | |
| with ``sample_data``. | |
| description: Optional description for the new version. | |
| keep_previous_active: If *True*, existing active versions stay | |
| active when creating a new version. | |
| Returns: | |
| The matched :class:`ModelVersionSummary` if the version already | |
| exists, or a freshly created :class:`ModelVersionRead`. | |
| Raises: | |
| ValueError: If both ``sample_data`` and ``schema_fields`` are | |
| provided, or if neither is provided. | |
| """ | |
| if sample_data is not None and schema_fields is not None: | |
| msg = "sample_data and schema_fields are mutually exclusive. Provide one or the other, not both." | |
| raise ValueError(msg) | |
| if sample_data is None and schema_fields is None: | |
| msg = ( | |
| "Either sample_data or schema_fields must be provided. " | |
| "Pass sample_data={'inputs': {...}, 'outputs': {...}} to " | |
| "auto-infer the schema, or pass schema_fields=[...] to " | |
| "define it explicitly. For a pure lookup use " | |
| "get_version_by_label() instead." | |
| ) | |
| raise ValueError(msg) | |
| model = await self.get_model(model_id) | |
| for v in model.versions: | |
| if v.version == version: | |
| return v | |
| # Version doesn't exist — create it | |
| if schema_fields is not None: | |
| return await self.create_model_version( | |
| model_id, | |
| version, | |
| schema_fields, | |
| description=description, | |
| keep_previous_active=keep_previous_active, | |
| ) | |
| inferred = await self.infer_schema(sample_data) | |
| return await self.create_model_version( | |
| model_id, | |
| version, | |
| inferred.schema_fields, | |
| description=description, | |
| keep_previous_active=keep_previous_active, | |
| ) | |
| # -- Inferences -- | |
| async def add_inference( | |
| self, | |
| model_version_id: uuid.UUID, | |
| inputs: dict, | |
| outputs: dict, | |
| ) -> InferenceRead: | |
| payload = InferenceCreate( | |
| model_version_id=model_version_id, | |
| inputs=inputs, | |
| outputs=outputs, | |
| ) | |
| resp = await self._request("POST", "/inferences", json=payload.model_dump(mode="json")) | |
| return InferenceRead.model_validate(resp.json()["data"]) | |
| async def add_inferences( | |
| self, | |
| model_version_id: uuid.UUID, | |
| records: list[dict], | |
| ) -> InferenceBatchResult: | |
| payload = InferenceBatchCreate( | |
| model_version_id=model_version_id, | |
| records=records, | |
| ) | |
| resp = await self._request("POST", "/inferences/batch", json=payload.model_dump(mode="json")) | |
| return InferenceBatchResult.model_validate(resp.json()["data"]) | |
| # -- Reference data -- | |
| async def add_reference_data( | |
| self, | |
| model_id: uuid.UUID, | |
| model_version_id: uuid.UUID, | |
| records: list[dict], | |
| ) -> ReferenceDataResult: | |
| payload = ReferenceDataUpload(records=records) | |
| resp = await self._request( | |
| "POST", | |
| f"/models/{model_id}/versions/{model_version_id}/reference-data", | |
| json=payload.model_dump(mode="json"), | |
| ) | |
| return ReferenceDataResult.model_validate(resp.json()["data"]) | |
| # -- Ground truth -- | |
| async def add_ground_truth( | |
| self, | |
| inference_id: uuid.UUID, | |
| label: dict, | |
| ) -> dict: | |
| payload = GroundTruthCreate(inference_id=inference_id, label=label) | |
| resp = await self._request("POST", "/ground-truth", json=payload.model_dump(mode="json")) | |
| return resp.json()["data"] | |
| # -- Jobs -- | |
| async def get_version_job( | |
| self, | |
| model_id: uuid.UUID, | |
| model_version_id: uuid.UUID, | |
| ) -> dict | None: | |
| """Get the single job for a model version, or None if none exists.""" | |
| resp = await self._request("GET", f"/models/{model_id}/versions/{model_version_id}/jobs") | |
| jobs = resp.json()["data"] | |
| return jobs[0] if jobs else None | |
| async def get_job(self, job_id: uuid.UUID) -> dict: | |
| resp = await self._request("GET", f"/jobs/{job_id}") | |
| return resp.json()["data"] | |
| async def update_job(self, job_id: uuid.UUID, **fields: object) -> dict: | |
| resp = await self._request("PATCH", f"/jobs/{job_id}", json=fields) | |
| return resp.json()["data"] | |
| async def trigger_job(self, job_id: uuid.UUID) -> dict: | |
| resp = await self._request("POST", f"/jobs/{job_id}/trigger") | |
| return resp.json()["data"] | |
| async def backfill_job(self, job_id: uuid.UUID) -> dict: | |
| resp = await self._request("POST", f"/jobs/{job_id}/backfill", timeout=300.0) | |
| return resp.json()["data"] | |
| # -- Schema inference -- | |
| async def infer_schema(self, sample: dict[str, dict]) -> InferSchemaResponse: | |
| resp = await self._request("POST", "/schema/infer", json={"sample": sample}) | |
| return InferSchemaResponse.model_validate(resp.json()["data"]) | |
| async def infer_schema_batch(self, samples: list[dict[str, dict]]) -> InferSchemaResponse: | |
| payload = InferSchemaBatchRequest(samples=samples) | |
| resp = await self._request("POST", "/schema/infer/batch", json=payload.model_dump()) | |
| return InferSchemaResponse.model_validate(resp.json()["data"]) | |
| # -- Schema validation (general) -- | |
| async def validate_schema( | |
| self, | |
| schema_fields: list[SchemaFieldCreate], | |
| inputs: dict, | |
| outputs: dict, | |
| ) -> ValidationResult: | |
| payload = ValidateSchemaRequest(schema_fields=schema_fields, inputs=inputs, outputs=outputs) | |
| resp = await self._request("POST", "/schema/validate", json=payload.model_dump(by_alias=True)) | |
| return ValidationResult.model_validate(resp.json()["data"]) | |
| async def validate_schema_batch( | |
| self, | |
| schema_fields: list[SchemaFieldCreate], | |
| records: list[dict], | |
| ) -> BatchValidationResult: | |
| payload = ValidateSchemaBatchRequest(schema_fields=schema_fields, records=records) | |
| resp = await self._request("POST", "/schema/validate/batch", json=payload.model_dump(by_alias=True)) | |
| return BatchValidationResult.model_validate(resp.json()["data"]) | |
| # -- Schema validation (model version) -- | |
| async def validate_model_version_schema( | |
| self, | |
| model_id: uuid.UUID, | |
| version_id: uuid.UUID, | |
| inputs: dict, | |
| outputs: dict, | |
| ) -> ValidationResult: | |
| payload = ValidateModelVersionRequest(inputs=inputs, outputs=outputs) | |
| resp = await self._request( | |
| "POST", | |
| f"/models/{model_id}/versions/{version_id}/schema/validate", | |
| json=payload.model_dump(), | |
| ) | |
| return ValidationResult.model_validate(resp.json()["data"]) | |
| async def validate_model_version_schema_batch( | |
| self, | |
| model_id: uuid.UUID, | |
| version_id: uuid.UUID, | |
| records: list[dict], | |
| ) -> BatchValidationResult: | |
| payload = ValidateModelVersionBatchRequest(records=records) | |
| resp = await self._request( | |
| "POST", | |
| f"/models/{model_id}/versions/{version_id}/schema/validate/batch", | |
| json=payload.model_dump(), | |
| ) | |
| return BatchValidationResult.model_validate(resp.json()["data"]) | |
Xet Storage Details
- Size:
- 17.9 kB
- Xet hash:
- 54612e4ac930f2529ae8731165118bde3311557c48f6a936d2f3a3d229872264
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.