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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: licos-dev-sdk
-Version: 0.2.1
+Version: 0.2.2
 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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "licos-dev-sdk"
-version = "0.2.1"
+version = "0.2.2"
 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.2}/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"),
@@ -78,9 +80,9 @@ __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",

{licos_dev_sdk-0.2.1 → licos_dev_sdk-0.2.2}/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.1 → licos_dev_sdk-0.2.2}/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()