code-analysis-client-dev 1.6.341__py3-none-any.whl

code_analysis_client/validation.py

@@ -0,0 +1,98 @@
+"""
+Shallow JSON-schema validation aligned with BaseMCPCommand.validate_params_against_schema.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from code_analysis_client.exceptions import ClientValidationError
+
+
+def prepare_params_for_schema(
+    params: Dict[str, Any], schema: Dict[str, Any]  # noqa: ARG001
+) -> Dict[str, Any]:
+    """Return a shallow copy of params for validation and dispatch."""
+    return dict(params)
+
+
+def validate_params_against_schema(
+    params: Dict[str, Any],
+    schema: Dict[str, Any],
+    command_name: str = "command",
+) -> None:
+    """Validate params against a command ``get_schema()``-style object (subset)."""
+    if not isinstance(params, dict):
+        raise ClientValidationError(
+            f"{command_name}: params must be a dict, got {type(params).__name__}",
+            field="params",
+        )
+    props = schema.get("properties") or {}
+    additional_ok = schema.get("additionalProperties", False)
+    required_set = set(schema.get("required") or [])
+    for key, value in params.items():
+        if key not in props:
+            if not additional_ok:
+                raise ClientValidationError(
+                    f"{command_name}: unknown parameter {key!r}. "
+                    "Only schema-defined properties are allowed.",
+                    field=key,
+                    details={"allowed": list(props.keys())},
+                )
+            continue
+        if value is None:
+            continue
+        prop = props[key]
+        expected_type = prop.get("type")
+        if expected_type == "string":
+            if not isinstance(value, str):
+                raise ClientValidationError(
+                    f"{command_name}: parameter {key!r} must be string, got {type(value).__name__}",
+                    field=key,
+                )
+        elif expected_type == "integer":
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise ClientValidationError(
+                    f"{command_name}: parameter {key!r} must be integer, got {type(value).__name__}",
+                    field=key,
+                )
+        elif expected_type == "number":
+            if not isinstance(value, (int, float)) or isinstance(value, bool):
+                raise ClientValidationError(
+                    f"{command_name}: parameter {key!r} must be number, got {type(value).__name__}",
+                    field=key,
+                )
+        elif expected_type == "boolean":
+            if not isinstance(value, bool):
+                raise ClientValidationError(
+                    f"{command_name}: parameter {key!r} must be boolean, got {type(value).__name__}",
+                    field=key,
+                )
+        elif expected_type == "array":
+            if not isinstance(value, list):
+                raise ClientValidationError(
+                    f"{command_name}: parameter {key!r} must be array, got {type(value).__name__}",
+                    field=key,
+                )
+        elif expected_type == "object":
+            if not isinstance(value, dict):
+                raise ClientValidationError(
+                    f"{command_name}: parameter {key!r} must be object, got {type(value).__name__}",
+                    field=key,
+                )
+        if "enum" in prop and value is not None:
+            if value not in prop["enum"]:
+                raise ClientValidationError(
+                    f"{command_name}: parameter {key!r} must be one of {prop['enum']!r}, got {value!r}",
+                    field=key,
+                    details={"enum": prop["enum"]},
+                )
+    for key in required_set:
+        if key not in params or params[key] is None:
+            raise ClientValidationError(
+                f"{command_name}: required parameter {key!r} is missing",
+                field=key,
+            )

code_analysis_client/vectorizer_state.py

@@ -0,0 +1,159 @@
+"""Typed models for vectorizer availability state from health and get_worker_status.
+
+The vectorizer_availability section of pipeline/matrix.yaml defines the contract.
+Clients must tolerate absence of these fields (deployed 1.6.190 server does not emit
+them yet) without raising.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class ServiceState(TypedDict, total=False):
+    """State of one vectorizer service (embedding or chunker).
+
+    All fields are optional to tolerate absence in pre-V1 deployments.
+    """
+
+    state: str  # "available", "unavailable", or "unknown"
+    since: str  # ISO-8601 UTC timestamp
+    last_probe_at: Optional[str]  # ISO-8601 UTC timestamp or null
+    last_ok_at: Optional[str]  # ISO-8601 UTC timestamp or null
+    reason: Optional[str]  # One of reason_enum or null
+    consecutive_failures: int
+
+
+class VectorizerState(TypedDict, total=False):
+    """Shared vectorizer availability state read by health and get_worker_status.
+
+    All fields are optional to tolerate absence in pre-V1 deployments.
+    Fields are presented as TypedDict with total=False; callers use .get()
+    to safely access optional fields.
+    """
+
+    state: str  # "available", "unavailable", or "unknown"
+    paused: bool  # True when state == unavailable
+    paused_reason: Optional[str]  # Reason from the earliest-failing unavailable service
+    paused_since: Optional[str]  # ISO-8601 UTC, from the earliest-failing service
+    services: Dict[str, ServiceState]  # {embedding: ..., chunker: ...}
+    probe_interval_seconds: int
+    probe_timeout_seconds: int
+    staleness_bound_seconds: int
+
+
+class VectorizerWarning(TypedDict, total=False):
+    """A warning from health.data.warnings or get_worker_status.data.warnings.
+
+    Only populated for VECTORIZER_UNAVAILABLE warnings.
+    All fields are optional to tolerate absence.
+    """
+
+    code: str  # "VECTORIZER_UNAVAILABLE"
+    service: str  # "embedding" or "chunker"
+    since: str  # ISO-8601 UTC timestamp
+    reason: Optional[str]  # Reason enum value
+    message: str  # Human-readable text
+
+
+class VectorizationWorkerBlock(TypedDict, total=False):
+    """The vectorization worker block from get_worker_status.
+
+    Present when worker_type in {vectorization, all} or omitted (defaults to all).
+    All fields are optional to tolerate absence in pre-V1 deployments.
+    """
+
+    paused: bool  # True when vectorizer state == unavailable
+    paused_reason: Optional[str]  # Reason from the unavailable service
+    paused_since: Optional[str]  # ISO-8601 UTC
+    last_heartbeat_at: str  # ISO-8601 UTC
+    heartbeat_age_seconds: float  # Age of the last heartbeat
+    rpc_in_flight: Optional[Dict[str, Any]]  # {service, started_at, elapsed_seconds}
+    dead_letter: Dict[str, Any]  # {total, by_reason}
+
+
+def safe_get_vectorizer_state(data: Any) -> Optional[VectorizerState]:
+    """Extract vectorizer state from a response dict, tolerating absence.
+
+    Supports both response formats:
+    - health: data.components.vectorizer
+    - get_worker_status: data.vectorizer
+
+    Args:
+        data: Response dict (e.g., from health or get_worker_status)
+
+    Returns:
+        VectorizerState dict if present, None if absent
+    """
+    if not isinstance(data, dict):
+        return None
+
+    # Try direct path first (get_worker_status)
+    vectorizer = data.get("vectorizer")
+    if isinstance(vectorizer, dict):
+        return vectorizer  # type: ignore
+
+    # Try components path (health)
+    components = data.get("components")
+    if isinstance(components, dict):
+        vectorizer = components.get("vectorizer")
+        if isinstance(vectorizer, dict):
+            return vectorizer  # type: ignore
+
+    return None
+
+
+def safe_get_warnings(data: Any) -> List[VectorizerWarning]:
+    """Extract warnings list from a response dict, tolerating absence.
+
+    Args:
+        data: Response dict (e.g., from health or get_worker_status)
+
+    Returns:
+        List of VectorizerWarning dicts, empty list if absent
+    """
+    if not isinstance(data, dict):
+        return []
+    warnings = data.get("warnings")
+    if not isinstance(warnings, list):
+        return []
+    return warnings  # type: ignore
+
+
+def safe_get_vectorization_worker(data: Any) -> Optional[VectorizationWorkerBlock]:
+    """Extract vectorization worker block from response data, tolerating absence.
+
+    Args:
+        data: Worker status data dict (e.g., from get_worker_status)
+
+    Returns:
+        VectorizationWorkerBlock dict if present, None if absent
+    """
+    if not isinstance(data, dict):
+        return None
+    # The worker block is in the response at the same level as other worker types
+    # when worker_type is vectorization or all (or omitted which defaults to all)
+    worker = data.get("vectorization")
+    if not isinstance(worker, dict):
+        return None
+    return worker  # type: ignore
+
+
+def extract_vectorizer_state_from_response(response: Dict[str, Any]) -> Optional[VectorizerState]:
+    """Extract vectorizer state from any response that may contain it.
+
+    Checks both data.components.vectorizer (health/get_worker_status) paths.
+
+    Args:
+        response: Response dict from a command
+
+    Returns:
+        VectorizerState dict if found, None otherwise
+    """
+    if not isinstance(response, dict):
+        return None
+    data = response.get("data")
+    return safe_get_vectorizer_state(data)

code_analysis_client/version.txt

@@ -0,0 +1 @@
+1.6.341