licos-dev-sdk 0.2.2__tar.gz → 0.2.4__tar.gz

{licos_dev_sdk-0.2.2 → licos_dev_sdk-0.2.4}/PKG-INFO

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

{licos_dev_sdk-0.2.2 → licos_dev_sdk-0.2.4}/pyproject.toml

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

{licos_dev_sdk-0.2.2 → licos_dev_sdk-0.2.4}/src/licos_dev_sdk/__init__.py

@@ -47,9 +47,10 @@ def __getattr__(name: str):
         "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"),
+        "ASRClient": ("model", "ASRClient"),
+        "fetch_model_catalogs": ("model", "fetch_model_catalogs"),
+        "fetch_model_detail": ("model", "fetch_model_detail"),
+        "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"),
@@ -59,6 +60,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]
@@ -81,9 +93,13 @@ __all__ = [
     "ModelRuntime", "ModelEndpoint", "ModelResult",
     "ApiError", "ConfigurationError",
     "LLMClient", "VisionClient", "VisionUnderstandingClient", "ImageGenerationClient", "VideoGenerationClient",
-    "SpeechRecognitionClient", "ASRClient",
-    "fetch_model_catalogs", "resolve_llm_endpoint", "resolve_vision_endpoint",
+    "SpeechRecognitionClient", "ASRClient",
+    "fetch_model_catalogs", "fetch_model_detail", "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.2 → licos_dev_sdk-0.2.4}/src/licos_dev_sdk/model.py

@@ -18,13 +18,15 @@ from licos_platform_sdk._runtime import (
 )
 
 
-MODEL_CATALOG_PATH = "/api/v1/llm-gateway/ai/model-catalog"
-DEFAULT_REQUEST_TIMEOUT_SECS = 120
-DEFAULT_ASYNC_TIMEOUT_SECS = 600
-DEFAULT_ASYNC_POLL_INTERVAL_SECS = 2.0
-DEFAULT_CATALOG_CACHE_TTL_SECS = 300
-
-_CATALOG_CACHE: dict[tuple[str, str], tuple[float, list[dict[str, Any]]]] = {}
+MODEL_CATALOG_PATH = "/api/v1/llm-gateway/ai/model-catalog"
+MODEL_DETAIL_PATH = "/api/v1/admin/workspaces/models/detail"
+DEFAULT_REQUEST_TIMEOUT_SECS = 120
+DEFAULT_ASYNC_TIMEOUT_SECS = 600
+DEFAULT_ASYNC_POLL_INTERVAL_SECS = 2.0
+DEFAULT_CATALOG_CACHE_TTL_SECS = 300
+
+_CATALOG_CACHE: dict[tuple[str, str], tuple[float, list[dict[str, Any]]]] = {}
+_DETAIL_CACHE: dict[tuple[str, str, str, str], tuple[float, dict[str, Any] | None]] = {}
 
 
 @dataclass(frozen=True)
@@ -35,13 +37,18 @@ class ModelRuntime:
 
 
 @dataclass(frozen=True)
-class ModelEndpoint:
-    provider: str
-    capability: str
-    base_url: str
-    model: str
-    required_headers: dict[str, str] = field(default_factory=dict)
-    endpoint: dict[str, Any] = field(default_factory=dict)
+class ModelEndpoint:
+    provider: str
+    capability: str
+    base_url: str
+    model: str
+    required_headers: dict[str, str] = field(default_factory=dict)
+    endpoint: dict[str, Any] = field(default_factory=dict)
+    response_url: str | None = None
+    cache_context: bool = False
+    context_length: int | None = None
+    max_input_length: int | None = None
+    max_output_length: int | None = None
 
     @property
     def async_task(self) -> bool:
@@ -89,7 +96,7 @@ class ModelResult:
         return result
 
 
-def fetch_model_catalogs(
+def fetch_model_catalogs(
     *,
     base_url: str | None = None,
     user_token: str | None = None,
@@ -97,19 +104,33 @@ def fetch_model_catalogs(
     refresh: bool = False,
 ) -> list[dict[str, Any]]:
     """Fetch platform model capability catalog using the project owner token."""
-    runtime = _model_runtime(base_url=base_url, user_token=user_token, user_id=user_id)
-    return _fetch_model_catalogs(runtime, refresh=refresh)
-
-
-def resolve_llm_endpoint(
+    runtime = _model_runtime(base_url=base_url, user_token=user_token, user_id=user_id)
+    return _fetch_model_catalogs(runtime, refresh=refresh)
+
+
+def fetch_model_detail(
+    model_code: str,
+    *,
+    base_url: str | None = None,
+    user_token: str | None = None,
+    user_id: str | None = None,
+    workspace_id: str | None = None,
+    refresh: bool = False,
+) -> dict[str, Any] | None:
+    """Fetch model detail, including base URL, Response API support and token limits."""
+    runtime = _model_runtime(base_url=base_url, user_token=user_token, user_id=user_id)
+    return _fetch_model_detail(runtime, model_code, workspace_id=workspace_id, refresh=refresh)
+
+
+def resolve_llm_endpoint(
     *,
     model_group: str = "text",
     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=model_group)
+) -> ModelEndpoint:
+    runtime = _model_runtime(base_url=base_url, user_token=user_token, user_id=user_id)
+    return _resolve_chat_endpoint(runtime, model_group=model_group)
 
 
 def resolve_vision_endpoint(
@@ -164,7 +185,7 @@ class LLMClient:
         self.ctx = ctx
         self.runtime = _model_runtime(base_url=base_url, user_token=user_token, user_id=user_id)
 
-    def invoke(
+    def invoke(
         self,
         messages: Sequence[Any] | str,
         *,
@@ -173,19 +194,22 @@ class LLMClient:
         max_completion_tokens: int | None = None,
         timeout: int | None = None,
         **extra: Any,
-    ) -> ModelResult:
-        endpoint = _resolve_endpoint(self.runtime, "chat", model_group="text")
-        selected_model = _selected_model(model, endpoint.model)
-        body = {
-            "model": selected_model,
-            "messages": _normalize_messages(messages),
-            **_not_none(
-                {
-                    "temperature": temperature,
-                    "max_completion_tokens": max_completion_tokens,
-                    **extra,
-                }
-            ),
+    ) -> ModelResult:
+        endpoint = _resolve_chat_endpoint(self.runtime, model_group="text", requested_model=model)
+        selected_model = endpoint.model
+        body = {
+            "model": selected_model,
+            "messages": _normalize_messages(messages),
+            **_not_none(
+                {
+                    "temperature": temperature,
+                    "max_completion_tokens": _effective_max_completion_tokens(
+                        max_completion_tokens,
+                        endpoint,
+                    ),
+                    **extra,
+                }
+            ),
         }
         response = _post_model_json(endpoint, self.runtime, body, timeout=timeout)
         texts = _extract_chat_texts(response) or _collect_texts(response)
@@ -207,20 +231,23 @@ class LLMClient:
         max_completion_tokens: int | None = None,
         timeout: int | None = None,
         **extra: Any,
-    ) -> Iterator[str]:
-        endpoint = _resolve_endpoint(self.runtime, "chat", model_group="text")
-        selected_model = _selected_model(model, endpoint.model)
-        body = {
-            "model": selected_model,
-            "messages": _normalize_messages(messages),
-            "stream": True,
-            **_not_none(
-                {
-                    "temperature": temperature,
-                    "max_completion_tokens": max_completion_tokens,
-                    **extra,
-                }
-            ),
+    ) -> Iterator[str]:
+        endpoint = _resolve_chat_endpoint(self.runtime, model_group="text", requested_model=model)
+        selected_model = endpoint.model
+        body = {
+            "model": selected_model,
+            "messages": _normalize_messages(messages),
+            "stream": True,
+            **_not_none(
+                {
+                    "temperature": temperature,
+                    "max_completion_tokens": _effective_max_completion_tokens(
+                        max_completion_tokens,
+                        endpoint,
+                    ),
+                    **extra,
+                }
+            ),
         }
         yield from _stream_model_json(endpoint, self.runtime, body, timeout=timeout)
 
@@ -451,8 +478,9 @@ def understand_image(**kwargs: Any) -> ModelResult:
     return VisionClient().understand(**kwargs)
 
 
-def clear_model_catalog_cache_for_tests() -> None:
-    _CATALOG_CACHE.clear()
+def clear_model_catalog_cache_for_tests() -> None:
+    _CATALOG_CACHE.clear()
+    _DETAIL_CACHE.clear()
 
 
 def _model_runtime(
@@ -472,7 +500,7 @@ def _refresh_model_runtime(runtime: ModelRuntime) -> ModelRuntime:
     return replace(runtime, token=token)
 
 
-def _fetch_model_catalogs(runtime: ModelRuntime, *, refresh: bool = False) -> list[dict[str, Any]]:
+def _fetch_model_catalogs(runtime: ModelRuntime, *, refresh: bool = False) -> list[dict[str, Any]]:
     cache_key = (runtime.base_url, runtime.token)
     ttl = _int_env("LICOS_MODEL_CATALOG_CACHE_TTL_SECS", DEFAULT_CATALOG_CACHE_TTL_SECS)
     cached = _CATALOG_CACHE.get(cache_key)
@@ -493,11 +521,81 @@ def _fetch_model_catalogs(runtime: ModelRuntime, *, refresh: bool = False) -> li
     catalogs = _catalogs_from_payload(payload)
     if not catalogs:
         raise ApiError("model catalog has no provider entries", details=payload)
-    _CATALOG_CACHE[cache_key] = (time.time(), catalogs)
-    return catalogs
-
-
-def _catalogs_from_payload(payload: Any) -> list[dict[str, Any]]:
+    _CATALOG_CACHE[cache_key] = (time.time(), catalogs)
+    return catalogs
+
+
+def _workspace_id(workspace_id: str | None = None) -> str | None:
+    value = workspace_id or env("AGENT_WORKSPACE_ID") or env("LICOS_WORKSPACE_ID")
+    if value is None:
+        return None
+    value = str(value).strip()
+    return value or None
+
+
+def _fetch_model_detail(
+    runtime: ModelRuntime,
+    model_code: str,
+    *,
+    workspace_id: str | None = None,
+    refresh: bool = False,
+) -> dict[str, Any] | None:
+    model_code = str(model_code or "").strip()
+    if not model_code:
+        return None
+    resolved_workspace_id = _workspace_id(workspace_id) or ""
+    cache_key = (runtime.base_url, runtime.token, model_code, resolved_workspace_id)
+    ttl = _int_env("LICOS_MODEL_CATALOG_CACHE_TTL_SECS", DEFAULT_CATALOG_CACHE_TTL_SECS)
+    cached = _DETAIL_CACHE.get(cache_key)
+    if cached and not refresh and time.time() - cached[0] <= ttl:
+        return cached[1]
+
+    query = {"code": model_code}
+    if resolved_workspace_id:
+        query["workspaceId"] = resolved_workspace_id
+    url = f"{runtime.base_url}{MODEL_DETAIL_PATH}?{parse.urlencode(query)}"
+    headers = {"X-Workspace-Id": resolved_workspace_id} if resolved_workspace_id else None
+    try:
+        payload = _request_json(
+            "GET",
+            url,
+            token=runtime.token,
+            headers=headers,
+            timeout=30,
+        )
+    except ApiError as exc:
+        if not refresh and should_refresh_user_token(exc):
+            return _fetch_model_detail(
+                _refresh_model_runtime(runtime),
+                model_code,
+                workspace_id=workspace_id,
+                refresh=True,
+            )
+        raise
+    detail = _model_detail_from_payload(payload)
+    _DETAIL_CACHE[cache_key] = (time.time(), detail)
+    return detail
+
+
+def _model_detail_from_payload(payload: Any) -> dict[str, Any] | None:
+    if not isinstance(payload, dict):
+        raise ApiError("model detail response is not an object", 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 "model detail API failed"),
+            code=code if isinstance(code, int) else None,
+            details=payload,
+        )
+    data = payload.get("data")
+    if data is None:
+        return None
+    if not isinstance(data, dict):
+        raise ApiError("model detail data is not an object", details=payload)
+    return data
+
+
+def _catalogs_from_payload(payload: Any) -> list[dict[str, Any]]:
     if not isinstance(payload, dict):
         raise ApiError("model catalog response is not an object", details=payload)
     code = payload.get("code")
@@ -516,10 +614,26 @@ def _catalogs_from_payload(payload: Any) -> list[dict[str, Any]]:
         items = []
     if not isinstance(items, list):
         raise ApiError("model catalog data is not a list", details=payload)
-    return [item for item in items if isinstance(item, dict)]
-
-
-def _resolve_endpoint(
+    return [item for item in items if isinstance(item, dict)]
+
+
+def _resolve_chat_endpoint(
+    runtime: ModelRuntime,
+    *,
+    model_group: str,
+    requested_model: str | None = None,
+) -> ModelEndpoint:
+    endpoint = _resolve_endpoint(runtime, "chat", model_group=model_group)
+    selected_model = _selected_model(requested_model, endpoint.model)
+    endpoint = replace(endpoint, model=selected_model)
+    try:
+        detail = _fetch_model_detail(runtime, selected_model)
+    except ApiError:
+        return endpoint
+    return _apply_model_detail(endpoint, detail)
+
+
+def _resolve_endpoint(
     runtime: ModelRuntime,
     capability_key: str,
     *,
@@ -552,7 +666,59 @@ def _resolve_endpoint(
             required_headers=_parse_required_headers(capability.get("requiredHeaders")),
             endpoint=capability,
         )
-    raise ApiError(f"capability `{capability_key}` is not available in model catalog", details=catalogs)
+    raise ApiError(f"capability `{capability_key}` is not available in model catalog", details=catalogs)
+
+
+def _apply_model_detail(endpoint: ModelEndpoint, detail: dict[str, Any] | None) -> ModelEndpoint:
+    if not detail:
+        return endpoint
+    base_url = _first_non_empty_field(detail, ["baseUrl", "base_url", "url"]) or endpoint.base_url
+    response_url = _first_non_empty_field(
+        detail,
+        ["responseUrl", "response_url", "responsesUrl", "responses_url"],
+    )
+    cache_context = _bool_field(detail, ["cacheContext", "cache_context"])
+    return replace(
+        endpoint,
+        base_url=base_url,
+        response_url=response_url or endpoint.response_url,
+        cache_context=endpoint.cache_context if cache_context is None else cache_context,
+        context_length=_int_field(
+            detail,
+            [
+                "contextLength",
+                "context_length",
+                "contextWindow",
+                "context_window",
+                "maxContextTokens",
+                "max_context_tokens",
+            ],
+        ),
+        max_input_length=_int_field(
+            detail,
+            [
+                "maxInputLength",
+                "max_input_length",
+                "maxInputTokens",
+                "max_input_tokens",
+                "inputTokenLimit",
+                "input_token_limit",
+            ],
+        ),
+        max_output_length=_int_field(
+            detail,
+            [
+                "maxOutputLength",
+                "max_output_length",
+                "maxOutputTokens",
+                "max_output_tokens",
+                "outputTokenLimit",
+                "output_token_limit",
+                "maxCompletionTokens",
+                "max_completion_tokens",
+            ],
+        ),
+    )
 
 
 def _capability_base_url(item: dict[str, Any], capability: dict[str, Any]) -> str | None:
@@ -598,7 +764,7 @@ def _first_array_model(models: Any) -> str | None:
     return _first_string(models)
 
 
-def _first_string(value: Any) -> str | None:
+def _first_string(value: Any) -> str | None:
     if isinstance(value, str):
         trimmed = value.strip()
         return trimmed or None
@@ -606,10 +772,60 @@ def _first_string(value: Any) -> str | None:
         for item in value:
             if isinstance(item, str) and item.strip():
                 return item.strip()
-    return None
-
-
-def _post_model_json(
+    return None
+
+
+def _first_non_empty_field(data: dict[str, Any], names: Sequence[str]) -> str | None:
+    for name in names:
+        value = data.get(name)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _bool_field(data: dict[str, Any], names: Sequence[str]) -> bool | None:
+    for name in names:
+        value = data.get(name)
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            normalized = value.strip().lower()
+            if normalized in {"true", "1", "yes", "y"}:
+                return True
+            if normalized in {"false", "0", "no", "n"}:
+                return False
+    return None
+
+
+def _int_field(data: dict[str, Any], names: Sequence[str]) -> int | None:
+    for name in names:
+        value = data.get(name)
+        if isinstance(value, bool):
+            continue
+        if isinstance(value, int):
+            return value if value > 0 else None
+        if isinstance(value, float):
+            parsed = int(value)
+            return parsed if parsed > 0 else None
+        if isinstance(value, str):
+            try:
+                parsed = int(value.strip())
+            except ValueError:
+                continue
+            return parsed if parsed > 0 else None
+    return None
+
+
+def _effective_max_completion_tokens(requested: int | None, endpoint: ModelEndpoint) -> int | None:
+    limit = endpoint.max_output_length
+    if requested is None:
+        return limit
+    if limit is None:
+        return requested
+    return min(requested, limit)
+
+
+def _post_model_json(
     endpoint: ModelEndpoint,
     runtime: ModelRuntime,
     body: dict[str, Any],