licos-dev-sdk 0.2.1__tar.gz → 0.2.3__tar.gz

{licos_dev_sdk-0.2.1 → licos_dev_sdk-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: licos-dev-sdk
-Version: 0.2.1
+Version: 0.2.3
 Summary: LICOS Dev SDK - file generation and model capability clients
 Requires-Python: >=3.10
 Requires-Dist: graphviz>=0.20

{licos_dev_sdk-0.2.1 → licos_dev_sdk-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "licos-dev-sdk"
-version = "0.2.1"
+version = "0.2.3"
 description = "LICOS Dev SDK - file generation and model capability clients"
 requires-python = ">=3.10"
 dependencies = [

{licos_dev_sdk-0.2.1 → licos_dev_sdk-0.2.3}/src/licos_dev_sdk/__init__.py

@@ -43,12 +43,14 @@ def __getattr__(name: str):
         "ConfigurationError": ("model", "ConfigurationError"),
         "LLMClient": ("model", "LLMClient"),
         "VisionClient": ("model", "VisionClient"),
+        "VisionUnderstandingClient": ("model", "VisionUnderstandingClient"),
         "ImageGenerationClient": ("model", "ImageGenerationClient"),
         "VideoGenerationClient": ("model", "VideoGenerationClient"),
         "SpeechRecognitionClient": ("model", "SpeechRecognitionClient"),
         "ASRClient": ("model", "ASRClient"),
         "fetch_model_catalogs": ("model", "fetch_model_catalogs"),
         "resolve_llm_endpoint": ("model", "resolve_llm_endpoint"),
+        "resolve_vision_endpoint": ("model", "resolve_vision_endpoint"),
         "resolve_image_generation_endpoint": ("model", "resolve_image_generation_endpoint"),
         "resolve_video_generation_endpoint": ("model", "resolve_video_generation_endpoint"),
         "resolve_speech_recognition_endpoint": ("model", "resolve_speech_recognition_endpoint"),
@@ -57,6 +59,17 @@ def __getattr__(name: str):
         "generate_video": ("model", "generate_video"),
         "recognize_speech": ("model", "recognize_speech"),
         "understand_image": ("model", "understand_image"),
+        # observability
+        "ObservabilityClient": ("observability", "ObservabilityClient"),
+        "ObservabilityRuntime": ("observability", "ObservabilityRuntime"),
+        "ensure_observability_database": ("observability", "ensure_observability_database"),
+        "log": ("observability", "log"),
+        "log_info": ("observability", "log_info"),
+        "log_warning": ("observability", "log_warning"),
+        "log_error": ("observability", "log_error"),
+        "record_trace": ("observability", "record_trace"),
+        "record_metric": ("observability", "record_metric"),
+        "record_error": ("observability", "record_error"),
     }
     if name in _map:
         mod_name, attr = _map[name]
@@ -78,10 +91,14 @@ __all__ = [
     "create_pptx",
     "ModelRuntime", "ModelEndpoint", "ModelResult",
     "ApiError", "ConfigurationError",
-    "LLMClient", "VisionClient", "ImageGenerationClient", "VideoGenerationClient",
+    "LLMClient", "VisionClient", "VisionUnderstandingClient", "ImageGenerationClient", "VideoGenerationClient",
     "SpeechRecognitionClient", "ASRClient",
-    "fetch_model_catalogs", "resolve_llm_endpoint",
+    "fetch_model_catalogs", "resolve_llm_endpoint", "resolve_vision_endpoint",
     "resolve_image_generation_endpoint", "resolve_video_generation_endpoint",
     "resolve_speech_recognition_endpoint",
     "invoke_llm", "generate_image", "generate_video", "recognize_speech", "understand_image",
+    "ObservabilityClient", "ObservabilityRuntime",
+    "ensure_observability_database",
+    "log", "log_info", "log_warning", "log_error",
+    "record_trace", "record_metric", "record_error",
 ]

{licos_dev_sdk-0.2.1 → licos_dev_sdk-0.2.3}/src/licos_dev_sdk/model.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import json
 import time
-from dataclasses import dataclass, field, replace
+from dataclasses import dataclass, field, replace
 from typing import Any, Iterator, Sequence
 from urllib import error as urlerror
 from urllib import parse, request
@@ -11,11 +11,11 @@ from licos_platform_sdk._runtime import (
     ApiError,
     ConfigurationError,
     env,
-    normalize_base_url,
-    platform_base_url,
-    resolve_user_token,
-    should_refresh_user_token,
-)
+    normalize_base_url,
+    platform_base_url,
+    resolve_user_token,
+    should_refresh_user_token,
+)
 
 
 MODEL_CATALOG_PATH = "/api/v1/llm-gateway/ai/model-catalog"
@@ -112,6 +112,16 @@ def resolve_llm_endpoint(
     return _resolve_endpoint(runtime, "chat", model_group=model_group)
 
 
+def resolve_vision_endpoint(
+    *,
+    base_url: str | None = None,
+    user_token: str | None = None,
+    user_id: str | None = None,
+) -> ModelEndpoint:
+    runtime = _model_runtime(base_url=base_url, user_token=user_token, user_id=user_id)
+    return _resolve_endpoint(runtime, "chat", model_group="vision")
+
+
 def resolve_image_generation_endpoint(
     *,
     base_url: str | None = None,
@@ -266,6 +276,9 @@ class VisionClient:
         )
 
 
+VisionUnderstandingClient = VisionClient
+
+
 class ImageGenerationClient:
     def __init__(
         self,
@@ -442,7 +455,7 @@ def clear_model_catalog_cache_for_tests() -> None:
     _CATALOG_CACHE.clear()
 
 
-def _model_runtime(
+def _model_runtime(
     *,
     base_url: str | None = None,
     user_token: str | None = None,
@@ -450,13 +463,13 @@ def _model_runtime(
 ) -> ModelRuntime:
     resolved_base_url = normalize_base_url(base_url) if base_url else platform_base_url()
     owner_user_id = user_id or env("LICOS_USER_ID") or env("AGENT_USER_ID")
-    token = (user_token or "").strip() or resolve_user_token(resolved_base_url, owner_user_id)
-    return ModelRuntime(base_url=resolved_base_url, token=token, user_id=owner_user_id)
-
-
-def _refresh_model_runtime(runtime: ModelRuntime) -> ModelRuntime:
-    token = resolve_user_token(runtime.base_url, runtime.user_id, force_refresh=True)
-    return replace(runtime, token=token)
+    token = (user_token or "").strip() or resolve_user_token(resolved_base_url, owner_user_id)
+    return ModelRuntime(base_url=resolved_base_url, token=token, user_id=owner_user_id)
+
+
+def _refresh_model_runtime(runtime: ModelRuntime) -> ModelRuntime:
+    token = resolve_user_token(runtime.base_url, runtime.user_id, force_refresh=True)
+    return replace(runtime, token=token)
 
 
 def _fetch_model_catalogs(runtime: ModelRuntime, *, refresh: bool = False) -> list[dict[str, Any]]:
@@ -466,17 +479,17 @@ def _fetch_model_catalogs(runtime: ModelRuntime, *, refresh: bool = False) -> li
     if cached and not refresh and time.time() - cached[0] <= ttl:
         return cached[1]
 
-    try:
-        payload = _request_json(
-            "GET",
-            f"{runtime.base_url}{MODEL_CATALOG_PATH}",
-            token=runtime.token,
-            timeout=30,
-        )
-    except ApiError as exc:
-        if not refresh and should_refresh_user_token(exc):
-            return _fetch_model_catalogs(_refresh_model_runtime(runtime), refresh=True)
-        raise
+    try:
+        payload = _request_json(
+            "GET",
+            f"{runtime.base_url}{MODEL_CATALOG_PATH}",
+            token=runtime.token,
+            timeout=30,
+        )
+    except ApiError as exc:
+        if not refresh and should_refresh_user_token(exc):
+            return _fetch_model_catalogs(_refresh_model_runtime(runtime), refresh=True)
+        raise
     catalogs = _catalogs_from_payload(payload)
     if not catalogs:
         raise ApiError("model catalog has no provider entries", details=payload)
@@ -596,35 +609,35 @@ def _first_string(value: Any) -> str | None:
     return None
 
 
-def _post_model_json(
+def _post_model_json(
     endpoint: ModelEndpoint,
     runtime: ModelRuntime,
     body: dict[str, Any],
     *,
     timeout: int | None = None,
-) -> Any:
-    request_timeout = timeout or _request_timeout()
-    try:
-        return _request_json(
-            "POST",
-            endpoint.base_url,
-            token=runtime.token,
-            body=body,
-            headers=endpoint.required_headers,
-            timeout=request_timeout,
-        )
-    except ApiError as exc:
-        if should_refresh_user_token(exc):
-            refreshed = _refresh_model_runtime(runtime)
-            return _request_json(
-                "POST",
-                endpoint.base_url,
-                token=refreshed.token,
-                body=body,
-                headers=endpoint.required_headers,
-                timeout=request_timeout,
-            )
-        raise
+) -> Any:
+    request_timeout = timeout or _request_timeout()
+    try:
+        return _request_json(
+            "POST",
+            endpoint.base_url,
+            token=runtime.token,
+            body=body,
+            headers=endpoint.required_headers,
+            timeout=request_timeout,
+        )
+    except ApiError as exc:
+        if should_refresh_user_token(exc):
+            refreshed = _refresh_model_runtime(runtime)
+            return _request_json(
+                "POST",
+                endpoint.base_url,
+                token=refreshed.token,
+                body=body,
+                headers=endpoint.required_headers,
+                timeout=request_timeout,
+            )
+        raise
 
 
 def _submit_model_task(
@@ -657,46 +670,46 @@ def _submit_model_task(
     )
 
 
-def _stream_model_json(
+def _stream_model_json(
     endpoint: ModelEndpoint,
     runtime: ModelRuntime,
     body: dict[str, Any],
     *,
     timeout: int | None = None,
-) -> Iterator[str]:
-    active_runtime = runtime
-    for attempt in range(2):
-        req = _json_request(
-            "POST",
-            endpoint.base_url,
-            token=active_runtime.token,
-            body=body,
-            headers=endpoint.required_headers,
-        )
-        try:
-            with request.urlopen(req, timeout=timeout or _request_timeout()) as response:
-                for raw_line in response:
-                    line = raw_line.decode("utf-8", errors="replace").strip()
-                    if not line:
-                        continue
-                    if line.startswith("data:"):
-                        data = line[len("data:") :].strip()
-                        if data == "[DONE]":
-                            break
-                        content = _extract_stream_content(data)
-                        if content:
-                            yield content
-                        continue
-                    yield line
-                return
-        except urlerror.HTTPError as exc:
-            error = _api_error_from_http(exc)
-            if attempt == 0 and should_refresh_user_token(error):
-                active_runtime = _refresh_model_runtime(active_runtime)
-                continue
-            raise error from exc
-        except urlerror.URLError as exc:
-            raise ApiError(f"model stream request failed: {exc}") from exc
+) -> Iterator[str]:
+    active_runtime = runtime
+    for attempt in range(2):
+        req = _json_request(
+            "POST",
+            endpoint.base_url,
+            token=active_runtime.token,
+            body=body,
+            headers=endpoint.required_headers,
+        )
+        try:
+            with request.urlopen(req, timeout=timeout or _request_timeout()) as response:
+                for raw_line in response:
+                    line = raw_line.decode("utf-8", errors="replace").strip()
+                    if not line:
+                        continue
+                    if line.startswith("data:"):
+                        data = line[len("data:") :].strip()
+                        if data == "[DONE]":
+                            break
+                        content = _extract_stream_content(data)
+                        if content:
+                            yield content
+                        continue
+                    yield line
+                return
+        except urlerror.HTTPError as exc:
+            error = _api_error_from_http(exc)
+            if attempt == 0 and should_refresh_user_token(error):
+                active_runtime = _refresh_model_runtime(active_runtime)
+                continue
+            raise error from exc
+        except urlerror.URLError as exc:
+            raise ApiError(f"model stream request failed: {exc}") from exc
 
 
 def _request_json(
@@ -769,28 +782,28 @@ def _await_async_model_result(
         raise ApiError("async model response is missing task_id", details=submit_response)
     query_url = _build_task_query_url(endpoint, task_id)
     deadline = time.time() + (max_wait_seconds or _async_timeout())
-    last_status = _task_status(submit_response) or "UNKNOWN"
-    while time.time() < deadline:
-        try:
-            response = _request_json(
-                "GET",
-                query_url,
-                token=runtime.token,
-                headers=endpoint.required_headers,
-                timeout=timeout or _request_timeout(),
-            )
-        except ApiError as exc:
-            if should_refresh_user_token(exc):
-                refreshed = _refresh_model_runtime(runtime)
-                response = _request_json(
-                    "GET",
-                    query_url,
-                    token=refreshed.token,
-                    headers=endpoint.required_headers,
-                    timeout=timeout or _request_timeout(),
-                )
-            else:
-                raise
+    last_status = _task_status(submit_response) or "UNKNOWN"
+    while time.time() < deadline:
+        try:
+            response = _request_json(
+                "GET",
+                query_url,
+                token=runtime.token,
+                headers=endpoint.required_headers,
+                timeout=timeout or _request_timeout(),
+            )
+        except ApiError as exc:
+            if should_refresh_user_token(exc):
+                refreshed = _refresh_model_runtime(runtime)
+                response = _request_json(
+                    "GET",
+                    query_url,
+                    token=refreshed.token,
+                    headers=endpoint.required_headers,
+                    timeout=timeout or _request_timeout(),
+                )
+            else:
+                raise
         last_status = _task_status(response) or last_status
         if _is_successful_task_response(response):
             return response
@@ -942,13 +955,13 @@ def _normalize_messages(messages: Sequence[Any] | str) -> list[dict[str, Any]]:
     return result
 
 
-def _selected_model(model: str | None, default: str) -> str:
-    if not isinstance(model, str):
-        return default
-    selected = model.strip()
-    if not selected or selected.lower() == "auto":
-        return default
-    return selected
+def _selected_model(model: str | None, default: str) -> str:
+    if not isinstance(model, str):
+        return default
+    selected = model.strip()
+    if not selected or selected.lower() == "auto":
+        return default
+    return selected
 
 
 def _image_count(count: int | None, parameters: dict[str, Any]) -> int:

licos_dev_sdk-0.2.3/src/licos_dev_sdk/observability.py

@@ -0,0 +1,527 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+from typing import Any
+from urllib import error as urlerror
+from urllib import parse, request
+
+from licos_platform_sdk._runtime import (
+    ApiError,
+    ConfigurationError,
+    auth_headers,
+    env,
+    normalize_base_url,
+    platform_base_url,
+    resolve_user_token,
+    should_refresh_user_token,
+)
+
+
+OBSERVABILITY_PATH = "/api/v1/studio/observability"
+DEFAULT_TIMEOUT_SECS = 15
+
+
+@dataclass(frozen=True)
+class ObservabilityRuntime:
+    base_url: str
+    project_id: str
+    token: str
+    workspace_id: str | None = None
+    user_id: str | None = None
+    project_type: str | None = None
+    deployment_version: str = "dev"
+    hash_version: str = "dev"
+
+
+class ObservabilityClient:
+    """Client for project observability records stored by the LICOS platform."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        user_token: str | None = None,
+        user_id: str | None = None,
+        project_id: str | None = None,
+        workspace_id: str | None = None,
+        project_type: str | None = None,
+        deployment_version: str | None = None,
+        hash_version: str | None = None,
+        timeout: int | float = DEFAULT_TIMEOUT_SECS,
+    ) -> None:
+        self.runtime = _observability_runtime(
+            base_url=base_url,
+            user_token=user_token,
+            user_id=user_id,
+            project_id=project_id,
+            workspace_id=workspace_id,
+            project_type=project_type,
+            deployment_version=deployment_version,
+            hash_version=hash_version,
+        )
+        self.timeout = timeout
+
+    def ensure_database(self) -> Any:
+        """Create or confirm the platform observability database for this project."""
+        return _request_data(
+            "POST",
+            self.runtime,
+            "/database",
+            query={"projectId": self.runtime.project_id},
+            timeout=self.timeout,
+        )
+
+    def log(
+        self,
+        level: str,
+        content: Any,
+        *,
+        log_time: datetime | str | None = None,
+        deployment_version: str | None = None,
+    ) -> Any:
+        body = {
+            "logTime": _iso_time(log_time),
+            "deploymentVersion": deployment_version or self.runtime.deployment_version,
+            "level": _normalize_level(level),
+            "logContent": _to_text(content),
+        }
+        return _request_data(
+            "POST",
+            self.runtime,
+            "/logs",
+            query={"projectId": self.runtime.project_id},
+            body=body,
+            timeout=self.timeout,
+        )
+
+    def log_info(self, content: Any, **kwargs: Any) -> Any:
+        return self.log("info", content, **kwargs)
+
+    def log_warning(self, content: Any, **kwargs: Any) -> Any:
+        return self.log("warning", content, **kwargs)
+
+    def log_error(self, content: Any, *, error_code: str | None = None, **kwargs: Any) -> Any:
+        message = _error_content(content, error_code)
+        return self.log("error", message, **kwargs)
+
+    def record_trace(
+        self,
+        *,
+        trace_id: str,
+        log_id: str | None = None,
+        hash_version: str | None = None,
+        input: Any = None,
+        output: Any = None,
+        input_tokens: int | None = None,
+        output_tokens: int | None = None,
+        latency_seconds: int | float | None = None,
+        latency_first_resp_ms: int | float | None = None,
+    ) -> Any:
+        body = {
+            "traceId": _required(trace_id, "trace_id"),
+            "logId": log_id,
+            "hashVersion": hash_version or self.runtime.hash_version,
+            "input": _to_text(input),
+            "output": _to_text(output),
+            "inputTokens": _int_or_zero(input_tokens),
+            "outputTokens": _int_or_zero(output_tokens),
+            "latencySeconds": _float_or_zero(latency_seconds),
+            "latencyFirstRespMs": _int_or_zero(latency_first_resp_ms),
+        }
+        return _request_data(
+            "POST",
+            self.runtime,
+            "/traces",
+            query={"projectId": self.runtime.project_id},
+            body=_compact(body),
+            timeout=self.timeout,
+        )
+
+    def record_metric(
+        self,
+        *,
+        route: str,
+        method: str,
+        latency_ms: int | float | None = None,
+        status_code: int | None = None,
+        window_start: datetime | str | None = None,
+        window_seconds: int = 60,
+        request_count: int = 1,
+        error_count: int | None = None,
+        latency_total_ms: int | float | None = None,
+        latency_count: int | None = None,
+        latency_min_ms: int | float | None = None,
+        latency_max_ms: int | float | None = None,
+        status2xx_count: int | None = None,
+        status3xx_count: int | None = None,
+        status4xx_count: int | None = None,
+        status5xx_count: int | None = None,
+        latency_buckets: dict[str, int] | None = None,
+    ) -> Any:
+        status = status_code or 200
+        latency = _number_or_none(latency_ms)
+        body = {
+            "projectId": self.runtime.project_id,
+            "workspaceId": self.runtime.workspace_id,
+            "userId": self.runtime.user_id,
+            "projectType": self.runtime.project_type,
+            "route": _required(route, "route"),
+            "method": _required(method, "method").upper(),
+            "windowStart": _window_start(window_start),
+            "windowSeconds": int(window_seconds),
+            "requestCount": int(request_count),
+            "errorCount": int(error_count) if error_count is not None else (1 if status >= 400 else 0),
+            "latencyTotalMs": _number_or_zero(latency_total_ms if latency_total_ms is not None else latency),
+            "latencyCount": int(latency_count) if latency_count is not None else (1 if latency is not None else 0),
+            "latencyMinMs": _number_or_zero(latency_min_ms if latency_min_ms is not None else latency),
+            "latencyMaxMs": _number_or_zero(latency_max_ms if latency_max_ms is not None else latency),
+            "status2xxCount": int(status2xx_count) if status2xx_count is not None else (1 if 200 <= status < 300 else 0),
+            "status3xxCount": int(status3xx_count) if status3xx_count is not None else (1 if 300 <= status < 400 else 0),
+            "status4xxCount": int(status4xx_count) if status4xx_count is not None else (1 if 400 <= status < 500 else 0),
+            "status5xxCount": int(status5xx_count) if status5xx_count is not None else (1 if status >= 500 else 0),
+            "latencyBuckets": latency_buckets or _latency_bucket(latency),
+        }
+        return _request_data(
+            "POST",
+            self.runtime,
+            "/analysis/metrics",
+            query={"projectId": self.runtime.project_id},
+            body=_compact(body),
+            timeout=self.timeout,
+        )
+
+    def record_error(
+        self,
+        *,
+        route: str,
+        method: str,
+        status_code: int = 500,
+        error_code: str | None = None,
+        error_message: Any = "",
+        trace_id: str | None = None,
+        occurred_at: datetime | str | None = None,
+    ) -> Any:
+        body = {
+            "projectId": self.runtime.project_id,
+            "workspaceId": self.runtime.workspace_id,
+            "userId": self.runtime.user_id,
+            "route": _required(route, "route"),
+            "method": _required(method, "method").upper(),
+            "statusCode": int(status_code),
+            "errorCode": error_code,
+            "errorMessage": _to_text(error_message),
+            "traceId": trace_id,
+            "occurredAt": _iso_time(occurred_at),
+        }
+        return _request_data(
+            "POST",
+            self.runtime,
+            "/analysis/errors",
+            query={"projectId": self.runtime.project_id},
+            body=_compact(body),
+            timeout=self.timeout,
+        )
+
+
+def ensure_observability_database(**kwargs: Any) -> Any:
+    return ObservabilityClient(**kwargs).ensure_database()
+
+
+def log(level: str, content: Any, **kwargs: Any) -> Any:
+    client_kwargs, call_kwargs = _split_client_kwargs(kwargs)
+    return ObservabilityClient(**client_kwargs).log(level, content, **call_kwargs)
+
+
+def log_info(content: Any, **kwargs: Any) -> Any:
+    client_kwargs, call_kwargs = _split_client_kwargs(kwargs)
+    return ObservabilityClient(**client_kwargs).log_info(content, **call_kwargs)
+
+
+def log_warning(content: Any, **kwargs: Any) -> Any:
+    client_kwargs, call_kwargs = _split_client_kwargs(kwargs)
+    return ObservabilityClient(**client_kwargs).log_warning(content, **call_kwargs)
+
+
+def log_error(content: Any, **kwargs: Any) -> Any:
+    client_kwargs, call_kwargs = _split_client_kwargs(kwargs)
+    return ObservabilityClient(**client_kwargs).log_error(content, **call_kwargs)
+
+
+def record_trace(**kwargs: Any) -> Any:
+    client_kwargs, call_kwargs = _split_client_kwargs(kwargs)
+    return ObservabilityClient(**client_kwargs).record_trace(**call_kwargs)
+
+
+def record_metric(**kwargs: Any) -> Any:
+    client_kwargs, call_kwargs = _split_client_kwargs(kwargs)
+    return ObservabilityClient(**client_kwargs).record_metric(**call_kwargs)
+
+
+def record_error(**kwargs: Any) -> Any:
+    client_kwargs, call_kwargs = _split_client_kwargs(kwargs)
+    return ObservabilityClient(**client_kwargs).record_error(**call_kwargs)
+
+
+def _observability_runtime(
+    *,
+    base_url: str | None = None,
+    user_token: str | None = None,
+    user_id: str | None = None,
+    project_id: str | None = None,
+    workspace_id: str | None = None,
+    project_type: str | None = None,
+    deployment_version: str | None = None,
+    hash_version: str | None = None,
+) -> ObservabilityRuntime:
+    resolved_base_url = normalize_base_url(base_url) if base_url else platform_base_url()
+    owner_user_id = user_id or env("LICOS_USER_ID") or env("AGENT_USER_ID")
+    token = (user_token or "").strip() or resolve_user_token(resolved_base_url, owner_user_id)
+    resolved_project_id = project_id or env("LICOS_PROJECT_ID") or env("AGENT_PROJECT_ID")
+    if not resolved_project_id:
+        raise ConfigurationError("LICOS_PROJECT_ID or AGENT_PROJECT_ID is not configured")
+    resolved_hash = hash_version or _hash_version()
+    return ObservabilityRuntime(
+        base_url=resolved_base_url,
+        project_id=resolved_project_id,
+        token=token,
+        workspace_id=workspace_id or env("LICOS_WORKSPACE_ID") or env("AGENT_WORKSPACE_ID"),
+        user_id=owner_user_id,
+        project_type=project_type or env("LICOS_PROJECT_TYPE") or env("AGENT_PROJECT_TYPE"),
+        deployment_version=deployment_version or _deployment_version(resolved_hash),
+        hash_version=resolved_hash,
+    )
+
+
+def _refresh_runtime(runtime: ObservabilityRuntime) -> ObservabilityRuntime:
+    token = resolve_user_token(runtime.base_url, runtime.user_id, force_refresh=True)
+    return replace(runtime, token=token)
+
+
+def _request_data(
+    method: str,
+    runtime: ObservabilityRuntime,
+    path: str,
+    *,
+    query: dict[str, Any] | None = None,
+    body: dict[str, Any] | None = None,
+    timeout: int | float = DEFAULT_TIMEOUT_SECS,
+    refresh: bool = False,
+) -> Any:
+    url = f"{runtime.base_url}{OBSERVABILITY_PATH}{path}"
+    if query:
+        url = f"{url}?{parse.urlencode(_compact(query))}"
+    data = json.dumps(body or {}).encode("utf-8") if body is not None else None
+    req = request.Request(url, method=method, data=data, headers=auth_headers(runtime))  # type: ignore[arg-type]
+    try:
+        with request.urlopen(req, timeout=timeout) as response:
+            return _decode_response(response.read(), status=getattr(response, "status", None))
+    except urlerror.HTTPError as exc:
+        api_error = _api_error_from_http_error(exc)
+        if not refresh and should_refresh_user_token(api_error):
+            return _request_data(
+                method,
+                _refresh_runtime(runtime),
+                path,
+                query=query,
+                body=body,
+                timeout=timeout,
+                refresh=True,
+            )
+        raise api_error from exc
+    except urlerror.URLError as exc:
+        raise ApiError(f"observability API request failed: {exc}") from exc
+
+
+def _decode_response(raw: bytes, *, status: int | None = None) -> Any:
+    if not raw:
+        return None
+    try:
+        payload = json.loads(raw.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ApiError("parse observability API response failed", status=status) from exc
+    if not isinstance(payload, dict):
+        raise ApiError("observability API response is not an object", status=status, details=payload)
+    code = payload.get("code")
+    if code not in (None, 0) or payload.get("success") is False:
+        raise ApiError(
+            str(payload.get("message") or "observability API failed"),
+            status=status,
+            code=code if isinstance(code, int) else None,
+            details=payload,
+        )
+    return payload.get("data")
+
+
+def _api_error_from_http_error(exc: urlerror.HTTPError) -> ApiError:
+    detail = exc.read()
+    if detail:
+        try:
+            payload = json.loads(detail.decode("utf-8"))
+        except json.JSONDecodeError:
+            payload = None
+        if isinstance(payload, dict):
+            code = payload.get("code")
+            return ApiError(
+                str(payload.get("message") or f"observability API returned {exc.code}"),
+                status=exc.code,
+                code=code if isinstance(code, int) else None,
+                details=payload,
+            )
+        return ApiError(detail.decode("utf-8", errors="replace"), status=exc.code)
+    return ApiError(f"observability API returned {exc.code}", status=exc.code)
+
+
+def _split_client_kwargs(kwargs: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    client_keys = {
+        "base_url",
+        "user_token",
+        "user_id",
+        "project_id",
+        "workspace_id",
+        "project_type",
+        "deployment_version",
+        "hash_version",
+        "timeout",
+    }
+    client_kwargs: dict[str, Any] = {}
+    call_kwargs: dict[str, Any] = {}
+    for key, value in kwargs.items():
+        if key in client_keys:
+            client_kwargs[key] = value
+        else:
+            call_kwargs[key] = value
+    return client_kwargs, call_kwargs
+
+
+def _required(value: str | None, name: str) -> str:
+    text = (value or "").strip()
+    if not text:
+        raise ValueError(f"{name} is required")
+    return text
+
+
+def _compact(value: dict[str, Any]) -> dict[str, Any]:
+    return {key: item for key, item in value.items() if item is not None}
+
+
+def _iso_time(value: datetime | str | None) -> str:
+    if value is None:
+        value = datetime.now(timezone.utc)
+    if isinstance(value, str):
+        return value
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.isoformat().replace("+00:00", "Z")
+
+
+def _window_start(value: datetime | str | None) -> str:
+    if value is not None:
+        return _iso_time(value)
+    now = datetime.now(timezone.utc).replace(second=0, microsecond=0)
+    return _iso_time(now)
+
+
+def _normalize_level(level: str) -> str:
+    text = (level or "info").strip().lower()
+    if text in {"warn", "warning"}:
+        return "warning"
+    if text in {"err", "error", "fatal"}:
+        return "error"
+    return "info"
+
+
+def _to_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(value, ensure_ascii=False, default=str)
+    except TypeError:
+        return str(value)
+
+
+def _error_content(content: Any, error_code: str | None) -> str:
+    text = _to_text(content)
+    code = (error_code or "").strip()
+    return f"[{code}] {text}" if code else text
+
+
+def _int_or_zero(value: int | float | None) -> int:
+    if value is None:
+        return 0
+    return int(value)
+
+
+def _float_or_zero(value: int | float | None) -> float:
+    if value is None:
+        return 0.0
+    return float(value)
+
+
+def _number_or_none(value: int | float | None) -> int | float | None:
+    if value is None:
+        return None
+    return value
+
+
+def _number_or_zero(value: int | float | None) -> int | float:
+    if value is None:
+        return 0
+    return value
+
+
+def _latency_bucket(latency_ms: int | float | None) -> dict[str, int]:
+    if latency_ms is None:
+        return {}
+    latency = float(latency_ms)
+    if latency < 100:
+        return {"0-100": 1}
+    if latency < 500:
+        return {"100-500": 1}
+    return {"500+": 1}
+
+
+def _deployment_version(hash_version: str) -> str:
+    return (
+        env("LICOS_DEPLOYMENT_VERSION")
+        or env("DEPLOY_VERSION")
+        or env("LICOS_RELEASE_VERSION")
+        or hash_version
+        or "dev"
+    )
+
+
+def _hash_version() -> str:
+    return (
+        env("LICOS_DEPLOYMENT_HASH")
+        or env("LICOS_DEPLOY_HASH")
+        or env("SOURCE_COMMIT")
+        or env("GIT_COMMIT")
+        or _git_commit_short()
+        or env("AGENT_PROJECT_ID")
+        or "dev"
+    )
+
+
+def _git_commit_short() -> str | None:
+    cwd = os.environ.get("LICOS_PROJECT_PATH") or os.getcwd()
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=cwd,
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=1,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    text = result.stdout.strip()
+    return text if result.returncode == 0 and text else None
+

{licos_dev_sdk-0.2.1 → licos_dev_sdk-0.2.3}/tests/test_model.py

@@ -4,10 +4,10 @@ import json
 import os
 import sys
 import unittest
-from pathlib import Path
-from typing import Any
-from unittest import mock
-from urllib import error as urlerror
+from pathlib import Path
+from typing import Any
+from unittest import mock
+from urllib import error as urlerror
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "licos-platform-sdk" / "src"))
@@ -16,7 +16,7 @@ from licos_dev_sdk import model
 from licos_platform_sdk import _runtime
 
 
-class _FakeResponse:
+class _FakeResponse:
     status = 200
 
     def __init__(self, payload: dict[str, Any]) -> None:
@@ -28,19 +28,19 @@ class _FakeResponse:
     def __exit__(self, *_args: Any) -> None:
         return None
 
-    def read(self) -> bytes:
-        return json.dumps(self._payload).encode("utf-8")
-
-
-class _FakeErrorBody:
-    def __init__(self, payload: dict[str, Any]) -> None:
-        self._payload = payload
-
-    def read(self) -> bytes:
-        return json.dumps(self._payload).encode("utf-8")
-
-
-def _catalog_payload() -> dict[str, Any]:
+    def read(self) -> bytes:
+        return json.dumps(self._payload).encode("utf-8")
+
+
+class _FakeErrorBody:
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self._payload = payload
+
+    def read(self) -> bytes:
+        return json.dumps(self._payload).encode("utf-8")
+
+
+def _catalog_payload() -> dict[str, Any]:
     return {
         "code": 0,
         "success": True,
@@ -111,62 +111,62 @@ class ModelSdkTests(unittest.TestCase):
         self.assertEqual(result.text, "hello")
         self.assertEqual(captured["exchange_headers"]["Authorization"], "Bearer ai-agent-token")
         self.assertEqual(captured["exchange_body"], {"userId": "user-1"})
-        self.assertEqual(captured["catalog_headers"]["Authorization"], "Bearer user-token")
-        self.assertEqual(captured["chat_headers"]["Authorization"], "Bearer user-token")
-        self.assertEqual(captured["chat_body"]["model"], "chat-text")
-
-    def test_llm_explicit_model_overrides_catalog_default(self) -> None:
-        captured: dict[str, Any] = {}
-
-        def fake_urlopen(req: Any, timeout: int = 0) -> _FakeResponse:
-            if req.full_url == "http://platform.example/api/v1/internal/auth/ai-user-token":
-                return _FakeResponse({"code": 0, "success": True, "data": {"accessToken": "user-token"}})
-            if req.full_url == "http://platform.example/api/v1/llm-gateway/ai/model-catalog":
-                return _FakeResponse(_catalog_payload())
-            if req.full_url == "http://gateway.example/v1/chat/completions":
-                captured["chat_body"] = json.loads(req.data.decode("utf-8"))
-                return _FakeResponse({"choices": [{"message": {"content": "hello"}}]})
-            raise AssertionError(req.full_url)
-
-        with mock.patch.object(model.request, "urlopen", fake_urlopen):
-            result = model.LLMClient().invoke("Say hello", model="custom-chat-model")
-
-        self.assertEqual(result.text, "hello")
-        self.assertEqual(captured["chat_body"]["model"], "custom-chat-model")
-
-    def test_llm_invoke_refreshes_user_token_once_after_unauthorized(self) -> None:
-        tokens = iter(["old-token", "new-token"])
-        catalog_tokens: list[str] = []
-        chat_tokens: list[str] = []
-
-        def fake_urlopen(req: Any, timeout: int = 0) -> _FakeResponse:
-            if req.full_url == "http://platform.example/api/v1/internal/auth/ai-user-token":
-                return _FakeResponse({"code": 0, "success": True, "data": {"accessToken": next(tokens)}})
-            if req.full_url == "http://platform.example/api/v1/llm-gateway/ai/model-catalog":
-                catalog_tokens.append(dict(req.header_items())["Authorization"])
-                return _FakeResponse(_catalog_payload())
-            if req.full_url == "http://gateway.example/v1/chat/completions":
-                chat_tokens.append(dict(req.header_items())["Authorization"])
-                if len(chat_tokens) == 1:
-                    raise urlerror.HTTPError(
-                        req.full_url,
-                        401,
-                        "Unauthorized",
-                        hdrs=None,
-                        fp=_FakeErrorBody({"code": 10002, "message": "token invalid or expired", "success": False}),
-                    )
-                return _FakeResponse({"choices": [{"message": {"content": "hello"}}]})
-            raise AssertionError(req.full_url)
-
-        with mock.patch.object(model.request, "urlopen", fake_urlopen):
-            result = model.LLMClient().invoke("Say hello", model="auto")
-
-        self.assertEqual(result.text, "hello")
-        self.assertEqual(catalog_tokens, ["Bearer old-token"])
-        self.assertEqual(chat_tokens, ["Bearer old-token", "Bearer new-token"])
-
-    def test_image_generation_defaults_to_one_image(self) -> None:
-        captured: dict[str, Any] = {}
+        self.assertEqual(captured["catalog_headers"]["Authorization"], "Bearer user-token")
+        self.assertEqual(captured["chat_headers"]["Authorization"], "Bearer user-token")
+        self.assertEqual(captured["chat_body"]["model"], "chat-text")
+
+    def test_llm_explicit_model_overrides_catalog_default(self) -> None:
+        captured: dict[str, Any] = {}
+
+        def fake_urlopen(req: Any, timeout: int = 0) -> _FakeResponse:
+            if req.full_url == "http://platform.example/api/v1/internal/auth/ai-user-token":
+                return _FakeResponse({"code": 0, "success": True, "data": {"accessToken": "user-token"}})
+            if req.full_url == "http://platform.example/api/v1/llm-gateway/ai/model-catalog":
+                return _FakeResponse(_catalog_payload())
+            if req.full_url == "http://gateway.example/v1/chat/completions":
+                captured["chat_body"] = json.loads(req.data.decode("utf-8"))
+                return _FakeResponse({"choices": [{"message": {"content": "hello"}}]})
+            raise AssertionError(req.full_url)
+
+        with mock.patch.object(model.request, "urlopen", fake_urlopen):
+            result = model.LLMClient().invoke("Say hello", model="custom-chat-model")
+
+        self.assertEqual(result.text, "hello")
+        self.assertEqual(captured["chat_body"]["model"], "custom-chat-model")
+
+    def test_llm_invoke_refreshes_user_token_once_after_unauthorized(self) -> None:
+        tokens = iter(["old-token", "new-token"])
+        catalog_tokens: list[str] = []
+        chat_tokens: list[str] = []
+
+        def fake_urlopen(req: Any, timeout: int = 0) -> _FakeResponse:
+            if req.full_url == "http://platform.example/api/v1/internal/auth/ai-user-token":
+                return _FakeResponse({"code": 0, "success": True, "data": {"accessToken": next(tokens)}})
+            if req.full_url == "http://platform.example/api/v1/llm-gateway/ai/model-catalog":
+                catalog_tokens.append(dict(req.header_items())["Authorization"])
+                return _FakeResponse(_catalog_payload())
+            if req.full_url == "http://gateway.example/v1/chat/completions":
+                chat_tokens.append(dict(req.header_items())["Authorization"])
+                if len(chat_tokens) == 1:
+                    raise urlerror.HTTPError(
+                        req.full_url,
+                        401,
+                        "Unauthorized",
+                        hdrs=None,
+                        fp=_FakeErrorBody({"code": 10002, "message": "token invalid or expired", "success": False}),
+                    )
+                return _FakeResponse({"choices": [{"message": {"content": "hello"}}]})
+            raise AssertionError(req.full_url)
+
+        with mock.patch.object(model.request, "urlopen", fake_urlopen):
+            result = model.LLMClient().invoke("Say hello", model="auto")
+
+        self.assertEqual(result.text, "hello")
+        self.assertEqual(catalog_tokens, ["Bearer old-token"])
+        self.assertEqual(chat_tokens, ["Bearer old-token", "Bearer new-token"])
+
+    def test_image_generation_defaults_to_one_image(self) -> None:
+        captured: dict[str, Any] = {}
 
         def fake_urlopen(req: Any, timeout: int = 0) -> _FakeResponse:
             if req.full_url == "http://platform.example/api/v1/internal/auth/ai-user-token":
@@ -205,6 +205,22 @@ class ModelSdkTests(unittest.TestCase):
         self.assertEqual(captured["body"]["messages"][0]["content"][1]["image_url"]["url"], "https://cdn.example/a.png")
         self.assertEqual(result.text, "a blue sky")
 
+    def test_resolve_vision_endpoint_uses_vision_model_group(self) -> None:
+        def fake_urlopen(req: Any, timeout: int = 0) -> _FakeResponse:
+            if req.full_url == "http://platform.example/api/v1/internal/auth/ai-user-token":
+                return _FakeResponse({"code": 0, "success": True, "data": {"accessToken": "user-token"}})
+            if req.full_url == "http://platform.example/api/v1/llm-gateway/ai/model-catalog":
+                return _FakeResponse(_catalog_payload())
+            raise AssertionError(req.full_url)
+
+        with mock.patch.object(model.request, "urlopen", fake_urlopen):
+            endpoint = model.resolve_vision_endpoint()
+
+        self.assertEqual(endpoint.capability, "chat")
+        self.assertEqual(endpoint.model, "chat-vision")
+        self.assertEqual(endpoint.base_url, "http://gateway.example/v1/chat/completions")
+        self.assertIs(model.VisionUnderstandingClient, model.VisionClient)
+
 
 if __name__ == "__main__":
     unittest.main()

licos_dev_sdk-0.2.3/tests/test_observability.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import unittest
+from pathlib import Path
+from typing import Any
+from unittest import mock
+from urllib import error as urlerror
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "licos-platform-sdk" / "src"))
+
+from licos_dev_sdk import observability
+from licos_platform_sdk import _runtime
+
+
+class _FakeResponse:
+    status = 200
+
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self._payload = payload
+
+    def __enter__(self) -> "_FakeResponse":
+        return self
+
+    def __exit__(self, *_args: Any) -> None:
+        return None
+
+    def read(self) -> bytes:
+        return json.dumps(self._payload).encode("utf-8")
+
+
+class _FakeErrorBody:
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self._payload = payload
+
+    def read(self) -> bytes:
+        return json.dumps(self._payload).encode("utf-8")
+
+
+class ObservabilitySdkTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.env = mock.patch.dict(
+            os.environ,
+            {
+                "LICOS_PLATFORM_API_BASE_URL": "http://platform.example/api/v1",
+                "AGENT_USER_ID": "user-1",
+                "AGENT_WORKSPACE_ID": "workspace-1",
+                "AGENT_PROJECT_ID": "project-1",
+                "AGENT_PROJECT_TYPE": "AGENT",
+                "LICOS_AI_AGENT_TOKEN": "ai-agent-token",
+                "LICOS_DEPLOYMENT_VERSION": "v1",
+                "LICOS_DEPLOYMENT_HASH": "hash-1",
+            },
+            clear=True,
+        )
+        self.env.start()
+        self.addCleanup(self.env.stop)
+        _runtime._clear_token_cache_for_tests()
+
+    def test_log_uses_runtime_context_and_owner_token(self) -> None:
+        captured: dict[str, Any] = {}
+
+        def fake_urlopen(req: Any, timeout: int = 0) -> _FakeResponse:
+            if req.full_url == "http://platform.example/api/v1/internal/auth/ai-user-token":
+                captured["exchange_headers"] = dict(req.header_items())
+                captured["exchange_body"] = json.loads(req.data.decode("utf-8"))
+                return _FakeResponse({"code": 0, "success": True, "data": {"accessToken": "user-token"}})
+            if req.full_url == "http://platform.example/api/v1/studio/observability/logs?projectId=project-1":
+                captured["log_headers"] = dict(req.header_items())
+                captured["log_body"] = json.loads(req.data.decode("utf-8"))
+                return _FakeResponse({"code": 0, "success": True, "data": {"id": 1}})
+            raise AssertionError(req.full_url)
+
+        with mock.patch.object(observability.request, "urlopen", fake_urlopen):
+            result = observability.log_info("started", log_time="2026-05-22T10:00:00+08:00")
+
+        self.assertEqual(result, {"id": 1})
+        self.assertEqual(captured["exchange_headers"]["Authorization"], "Bearer ai-agent-token")
+        self.assertEqual(captured["exchange_body"], {"userId": "user-1"})
+        self.assertEqual(captured["log_headers"]["Authorization"], "Bearer user-token")
+        log_headers = {key.lower(): value for key, value in captured["log_headers"].items()}
+        self.assertEqual(log_headers["x-workspace-id"], "workspace-1")
+        self.assertEqual(captured["log_body"]["deploymentVersion"], "v1")
+        self.assertEqual(captured["log_body"]["level"], "info")
+        self.assertEqual(captured["log_body"]["logContent"], "started")
+
+    def test_trace_metric_and_error_payloads(self) -> None:
+        calls: list[tuple[str, dict[str, Any]]] = []
+
+        def fake_urlopen(req: Any, timeout: int = 0) -> _FakeResponse:
+            if req.full_url == "http://platform.example/api/v1/internal/auth/ai-user-token":
+                return _FakeResponse({"code": 0, "success": True, "data": {"accessToken": "user-token"}})
+            calls.append((req.full_url, json.loads(req.data.decode("utf-8"))))
+            return _FakeResponse({"code": 0, "success": True, "data": {"ok": True}})
+
+        with mock.patch.object(observability.request, "urlopen", fake_urlopen):
+            client = observability.ObservabilityClient()
+            client.record_trace(trace_id="trace-1", input={"q": "hi"}, output="ok", input_tokens=3, output_tokens=4, latency_seconds=1.2)
+            client.record_metric(route="/stream_run", method="post", latency_ms=640, status_code=500)
+            client.record_error(route="/stream_run", method="post", error_code="MODEL_TIMEOUT", error_message="timeout", trace_id="trace-1")
+
+        self.assertEqual(calls[0][0], "http://platform.example/api/v1/studio/observability/traces?projectId=project-1")
+        self.assertEqual(calls[0][1]["traceId"], "trace-1")
+        self.assertEqual(calls[0][1]["hashVersion"], "hash-1")
+        self.assertEqual(calls[0][1]["input"], '{"q": "hi"}')
+        self.assertEqual(calls[0][1]["inputTokens"], 3)
+
+        self.assertEqual(calls[1][0], "http://platform.example/api/v1/studio/observability/analysis/metrics?projectId=project-1")
+        self.assertEqual(calls[1][1]["workspaceId"], "workspace-1")
+        self.assertEqual(calls[1][1]["projectType"], "AGENT")
+        self.assertEqual(calls[1][1]["method"], "POST")
+        self.assertEqual(calls[1][1]["errorCount"], 1)
+        self.assertEqual(calls[1][1]["status5xxCount"], 1)
+        self.assertEqual(calls[1][1]["latencyBuckets"], {"500+": 1})
+
+        self.assertEqual(calls[2][0], "http://platform.example/api/v1/studio/observability/analysis/errors?projectId=project-1")
+        self.assertEqual(calls[2][1]["errorCode"], "MODEL_TIMEOUT")
+        self.assertEqual(calls[2][1]["traceId"], "trace-1")
+
+    def test_refreshes_owner_token_once_after_unauthorized(self) -> None:
+        tokens = iter(["old-token", "new-token"])
+        log_tokens: list[str] = []
+
+        def fake_urlopen(req: Any, timeout: int = 0) -> _FakeResponse:
+            if req.full_url == "http://platform.example/api/v1/internal/auth/ai-user-token":
+                return _FakeResponse({"code": 0, "success": True, "data": {"accessToken": next(tokens)}})
+            if req.full_url == "http://platform.example/api/v1/studio/observability/logs?projectId=project-1":
+                log_tokens.append(dict(req.header_items())["Authorization"])
+                if len(log_tokens) == 1:
+                    raise urlerror.HTTPError(
+                        req.full_url,
+                        401,
+                        "Unauthorized",
+                        hdrs=None,
+                        fp=_FakeErrorBody({"code": 10002, "message": "token invalid or expired", "success": False}),
+                    )
+                return _FakeResponse({"code": 0, "success": True, "data": {"id": 1}})
+            raise AssertionError(req.full_url)
+
+        with mock.patch.object(observability.request, "urlopen", fake_urlopen):
+            observability.log_error("failed")
+
+        self.assertEqual(log_tokens, ["Bearer old-token", "Bearer new-token"])
+
+
+if __name__ == "__main__":
+    unittest.main()