octostar-python-client 0.1.759__py3-none-any.whl

octostar/utils/chat/list_models.py

@@ -0,0 +1,91 @@
+import httpx
+from typing import Optional
+from ...client import Client, get_default_client
+from ..exceptions import ApiConnectionError
+from typing import Optional
+from ..commons import network_retry_strategy
+
+
+def _prepare_list_models_request(client):
+    endpoint_url = f"{client.get_base_url_v1()}/api/v1/chat/models"
+    headers = {
+        "Authorization": f"Bearer {client.token}",
+        "x-ontology": client.ontology,
+    }
+    return {
+        "url": endpoint_url,
+        "headers": headers,
+        "timeout": 60,
+    }
+
+
+def sync(
+    client: Optional[Client] = None,
+) -> list[dict]:
+    """
+    # List the available AI chat models.
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of information for each available AI model.
+
+    ## Raises
+    - `ApiConnectionError`: If the query was unsuccessful.
+    """
+    if not client:
+        client = get_default_client()
+    response = None
+    try:
+        for attempt in network_retry_strategy(retries=3):
+            with attempt:
+                with httpx.Client() as httpx_client:
+                    response = httpx_client.get(**_prepare_list_models_request(client))
+                    response.raise_for_status()
+                try:
+                    response = response.json()
+                except Exception as e:
+                    raise ConnectionError(
+                        f"Unparsable response format {response.content} with exception {e}"
+                    )
+    except Exception:
+        raise ApiConnectionError("list_models", response, client)
+    return response
+
+
+async def asyncio(
+    client: Optional[Client] = None,
+) -> list[dict]:
+    """
+    # List asynchronously the available AI chat models.
+
+    ## Arguments
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of information for each available AI model.
+
+    ## Raises
+    - `ApiConnectionError`: If the query was unsuccessful.
+    """
+    if not client:
+        client = get_default_client()
+    response = None
+    try:
+        for attempt in network_retry_strategy(retries=3):
+            with attempt:
+                async with httpx.AsyncClient() as httpx_client:
+                    response = await httpx_client.get(
+                        **_prepare_list_models_request(client)
+                    )
+                    response.raise_for_status()
+                try:
+                    response = response.json()
+                except Exception as e:
+                    raise ConnectionError(
+                        f"Unparsable response format {response.content} with exception {e}"
+                    )
+    except Exception:
+        raise ApiConnectionError("list_models", response, client)
+    return response

octostar/utils/chat/tokenize.py

@@ -0,0 +1,105 @@
+import httpx
+from typing import Optional
+from ...client import Client, get_default_client
+from ..exceptions import ApiConnectionError
+from typing import Optional
+from ..commons import network_retry_strategy
+
+
+def _prepare_tokenize_request(client, text, model_name):
+    endpoint_url = f"{client.get_base_url_v1()}/api/v2/ai/llm/tokenize"
+    headers = {
+        "Authorization": f"Bearer {client.token}",
+        "x-ontology": client.ontology,
+    }
+    return {
+        "url": endpoint_url,
+        "headers": headers,
+        "timeout": 60,
+        "json": {
+            "text": text,
+            "model_name": model_name,
+        },
+    }
+
+
+def sync(
+    text: str,
+    model_name: str,
+    client: Optional[Client] = None,
+) -> list[int]:
+    """
+    # Tokenize a string into a list of LLM tokens.
+
+    ## Arguments
+    - `text`: The input string to tokenize.
+    - `model_name`: The model with which to tokenize the input text.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of tokens.
+
+    ## Raises
+    - `ApiConnectionError`: If the query was unsuccessful.
+    """
+    if not client:
+        client = get_default_client()
+    response = None
+    try:
+        for attempt in network_retry_strategy(retries=3):
+            with attempt:
+                with httpx.Client() as httpx_client:
+                    response = httpx_client.post(
+                        **_prepare_tokenize_request(client, text, model_name)
+                    )
+                    response.raise_for_status()
+                try:
+                    response = response.json()["tokens"]
+                except Exception as e:
+                    raise ConnectionError(
+                        f"Unparsable response format {response.content} with exception {e}"
+                    )
+    except Exception:
+        raise ApiConnectionError("tokenize", response, client)
+    return response  # pyright: ignore[reportReturnType]
+
+
+async def asyncio(
+    text: str,
+    model_name: str,
+    client: Optional[Client] = None,
+) -> list[int]:
+    """
+    # Tokenize a string into a list of LLM tokens.
+
+    ## Arguments
+    - `text`: The input string to tokenize.
+    - `model_name`: The model with which to tokenize the input text.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    A list of tokens.
+
+    ## Raises
+    - `ApiConnectionError`: If the query was unsuccessful.
+    """
+    if not client:
+        client = get_default_client()
+    response = None
+    try:
+        for attempt in network_retry_strategy(retries=3):
+            with attempt:
+                async with httpx.AsyncClient() as httpx_client:
+                    response = await httpx_client.post(
+                        **_prepare_tokenize_request(client, text, model_name)
+                    )
+                    response.raise_for_status()
+                try:
+                    response = response.json()["tokens"]
+                except Exception as e:
+                    raise ConnectionError(
+                        f"Unparsable response format {response.content} with exception {e}"
+                    )
+    except Exception:
+        raise ApiConnectionError("tokenize", response, client)
+    return response  # pyright: ignore[reportReturnType]

octostar/utils/commons.py

@@ -0,0 +1,226 @@
+import asyncio
+from typing import Callable, Optional, List
+import time
+from tenacity import (
+    Retrying,
+    stop_after_attempt,
+    wait_exponential_jitter,
+    retry_if_exception,
+)
+import httpx
+from calendar import timegm
+from pytimeparse import parse as timeparse
+
+from .exceptions import ApiConnectionError, StopAsyncIterationWithResult
+from ..types import Response
+
+
+TIMESTAMP_SKEW = 10
+
+network_retry_strategy = lambda retries=3, retry_type=wait_exponential_jitter: Retrying(
+    stop=stop_after_attempt(retries),
+    wait=lambda state: network_wait_strategy(state, retry_type),
+    retry=retry_if_exception(network_retry_condition),
+    reraise=True,
+)
+
+
+def network_get_retry_after(exception):
+    if not isinstance(exception, ApiConnectionError):
+        return None
+    resp = getattr(exception, "response", None)
+    if not resp or not resp.headers:
+        return None
+    headers = resp.headers
+    headers = {k.lower(): v for k, v in resp.headers.items()}
+    wait_candidates = []
+
+    # Standard Retry-After header (RFC 7231)
+    retry_after = headers.get("retry-after")
+    if retry_after:
+        retry_after = retry_after.strip()
+        if retry_after.replace(".", "", 1).isdigit():
+            wait_candidates.append(float(retry_after))
+        else:
+            try:
+                retry_time = timegm(
+                    time.strptime(retry_after, "%a, %d %b %Y %H:%M:%S GMT")
+                )
+                delta = retry_time - time.time()
+                if delta > 0:
+                    wait_candidates.append(delta)
+            except Exception:
+                pass
+
+    # OpenAI / LiteLLM rate-limit reset headers
+    for key in ("x-ratelimit-reset-requests", "x-ratelimit-reset-tokens"):
+        val = headers.get(key)
+        if not val:
+            continue
+        val = val.strip()
+        if val.replace(".", "", 1).isdigit():
+            numeric = float(val)
+            now = time.time()
+            if numeric > now + TIMESTAMP_SKEW:
+                delta = numeric - now
+                if delta > 0:
+                    wait_candidates.append(delta)
+            else:
+                if numeric > 0:
+                    wait_candidates.append(numeric)
+        else:
+            try:
+                delta = timeparse(val)
+                if delta > 0:
+                    wait_candidates.append(delta)
+            except Exception:
+                pass
+
+    if wait_candidates:
+        return max(wait_candidates)
+    return None
+
+
+def network_retry_condition(exception):
+    if isinstance(exception, httpx.RequestError):
+        return True
+    if isinstance(exception, ApiConnectionError):
+        if hasattr(exception, "response") and exception.response:
+            sc = exception.response.status_code
+            return (300 <= sc <= 399) or (500 <= sc <= 599) or sc in [429, 408]
+        return True
+    if isinstance(exception, ConnectionError):
+        return True
+    return False
+
+
+def network_wait_strategy(retry_state, default_retry_type=wait_exponential_jitter):
+    exception = retry_state.outcome.exception()
+    retry_after = network_get_retry_after(exception)
+    if retry_after is not None:
+        return retry_after
+    else:
+        return default_retry_type()(retry_state)
+
+
+class FailCondition:
+    def __init__(self, callable: Callable[[Response], bool]):
+        self.callable = callable
+
+
+class ChunksFailCondition:
+    def __init__(self, callable: Callable[[List[Response]], bool]):
+        self.callable = callable
+
+
+class ChunksEndCondition:
+    def __init__(
+        self,
+        callable: Callable[[List[Response]], bool],
+        timeout: Optional[float] = None,
+    ):
+        self.callable = callable
+        self.timeout = timeout
+
+
+class TimeoutAsyncGenerator:
+    def __init__(self, generator, timeout):
+        self.generator = generator
+        self.timeout = timeout
+        self.start_time = time.monotonic()
+
+    async def __aiter__(self):
+        gen_iter = self.generator.__aiter__()
+        while True:
+            elapsed_time = time.monotonic() - self.start_time
+            remaining_time = self.timeout - elapsed_time
+            if remaining_time <= 0:
+                raise asyncio.TimeoutError()
+            try:
+                item = await asyncio.wait_for(gen_iter.__anext__(), remaining_time)
+                yield item
+            except StopAsyncIteration:
+                break
+
+
+def sync_request(
+    client,
+    module,
+    fail_condition=None,
+    retry_strategy=network_retry_strategy,
+    **request_kwargs,
+):
+    if not fail_condition:
+        fail_condition = FailCondition(callable=lambda resp: resp.status_code != 200)
+    for attempt in retry_strategy():
+        with attempt:
+            response = module.sync_detailed(**request_kwargs, client=client)
+        if fail_condition.callable(response):
+            raise ApiConnectionError(module.__name__, response, client)
+    return response
+
+
+async def asyncio_request(
+    client,
+    module,
+    fail_condition=None,
+    retry_strategy=network_retry_strategy,
+    **request_kwargs,
+):
+    if not fail_condition:
+        fail_condition = FailCondition(callable=lambda resp: resp.status_code != 200)
+    for attempt in retry_strategy():
+        with attempt:
+            response = await module.asyncio_detailed(**request_kwargs, client=client)
+        if fail_condition.callable(response):
+            raise ApiConnectionError(module.__name__, response, client)
+    return response
+
+
+async def streaming_request(
+    client,
+    module,
+    fail_condition=None,
+    end_condition=None,
+    retry_strategy=network_retry_strategy,
+    **request_kwargs,
+):
+    async def _collect_chunks(
+        generator, collected_chunks, fail_condition, end_condition
+    ):
+        if end_condition.timeout:
+            generator = TimeoutAsyncGenerator(generator, end_condition.timeout)
+        try:
+            async for chunk in generator:
+                if fail_condition.callable(collected_chunks + [chunk]):
+                    raise ApiConnectionError(module.__name__, chunk, client)
+                else:
+                    collected_chunks.append(chunk)
+                    if end_condition.callable(collected_chunks):
+                        raise StopAsyncIterationWithResult(value=collected_chunks)
+                    else:
+                        yield chunk
+        except asyncio.TimeoutError:
+            raise StopAsyncIterationWithResult(value=collected_chunks)
+
+    if not fail_condition:
+        fail_condition = ChunksFailCondition(
+            callable=lambda resps: not resps or resps[0].status_code != 200
+        )
+    if not end_condition:
+        end_condition = ChunksEndCondition(callable=lambda resps: False)
+    collected_chunks = []
+    for attempt in retry_strategy():
+        with attempt:
+            generator = module.streaming_detailed(**request_kwargs, client=client)
+            generator = _collect_chunks(
+                generator, collected_chunks, fail_condition, end_condition
+            )
+            async for chunk in generator:
+                yield chunk
+    raise StopAsyncIterationWithResult(value=collected_chunks)
+
+
+def streaming_get_full_content(responses):
+    chunks = [part.content for part in responses if part.content.strip()]
+    return b"".join(chunks)

octostar/utils/exceptions.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+class StopAsyncIterationWithResult(Exception):
+    def __init__(self, value):
+        self.value = value
+
+
+class ApiConnectionError(ConnectionError):
+    def __init__(self, method_name, response, client, max_message_length=10000):
+        self.method_name = method_name
+        self.response = response
+        self.client = client
+
+        message = (
+            "{method_name} failed with status code {code} and response\n{response}"
+        )
+        status_code = getattr(response, "status_code", "Unknown")
+        content = getattr(response, "content", "No content available")
+        message = message.format(
+            method_name=method_name, code=status_code, response=content
+        )
+        if len(message) > max_message_length:
+            message = message[: max_message_length - 3] + "..."
+        super().__init__(message)
+
+
+# FIXME: TEAM-6154 — drop this regex once the server returns the
+# rejected field as a structured attribute on EntityError. Today
+# UpsertResponse carries each rejection only as a free-form
+# ``error: str``, so we extract the field name client-side to
+# populate ``invalid_fields``.
+#
+# Matches per-field server validation rejections inside an entity's error text:
+#   "Invalid <type> value for field '<name>'[: '<value>']"
+_FIELD_FAILURE_RE = re.compile(
+    r"Invalid\s+\S+\s+value\s+for\s+field\s+'(?P<field>[^']+)'",
+    re.IGNORECASE,
+)
+
+# FIXME: TEAM-6154 — drop this regex too, same task as
+# _FIELD_FAILURE_RE above. The server should expose the rejected
+# reserved-keyword token as a structured attribute on EntityError.
+#
+# Matches "reserved keyword" mentions inside an entity's error text, capturing
+# the offending token when it appears quoted (e.g. ``reserved keyword 'call'``).
+# Some backends omit the quotes, so callers should also fall back to
+# ``"reserved keyword" in err["error"]`` for boolean detection.
+_RESERVED_KEYWORD_RE = re.compile(
+    r"reserved\s+keyword[^'\"]*['\"](?P<keyword>[^'\"]+)['\"]",
+    re.IGNORECASE,
+)
+
+
+class ApiValidationError(ApiConnectionError):
+    """Raised when the server accepted the upsert request but rejected one
+    or more entities server-side.
+
+    Subclass of :class:`ApiConnectionError`, so handlers catching the
+    parent class still receive validation failures.
+
+    The per-entity breakdown is exposed via structured attributes:
+
+    Attributes:
+        entity_errors: ``list[dict]`` — ``[{"entity_id": str, "error":
+            str}, ...]``, the per-entity error rows as returned by the
+            server. Use this when you need the raw message text for
+            each failing entity.
+        missing_entity_ids: ``set[str]`` — IDs that were sent but appear
+            in neither ``response.entities`` nor ``response.errors``.
+            The server has no record of these: neither written nor
+            explicitly rejected.
+        mismatched_keys: ``list[tuple[str, str]]`` — ``(entity_id,
+            os_workspace)`` pairs the server returned under an
+            ``os_workspace`` different from the one you sent. Typically
+            indicates a stale record was matched; refetching is the
+            usual recovery.
+        invalid_fields: ``dict[str, list[str]]`` — ``{entity_id:
+            [field_name, ...]}`` covering per-field rejections
+            (malformed datetime, bad number, etc.). To recover, drop
+            the listed fields from the payload for each entity and
+            re-upsert.
+        reserved_keyword_entity_types: ``set[str]`` — entity-type
+            tokens the server's query parser flagged as reserved
+            keywords (e.g. Cypher ``call``, ``match``). Resolution is
+            usually renaming the entity type at the source ontology.
+    """
+
+    def __init__(
+        self,
+        method_name,
+        response,
+        client,
+        *,
+        entity_errors: list[dict[str, Any]] | None = None,
+        missing_entity_ids: set[str] | None = None,
+        mismatched_keys: list[tuple[str, str]] | None = None,
+        max_message_length: int = 10000,
+    ):
+        self.entity_errors: list[dict[str, Any]] = list(entity_errors or [])
+        self.missing_entity_ids: set[str] = set(missing_entity_ids or ())
+        self.mismatched_keys: list[tuple[str, str]] = list(mismatched_keys or ())
+        super().__init__(
+            method_name, response, client, max_message_length=max_message_length
+        )
+
+    @property
+    def invalid_fields(self) -> dict[str, list[str]]:
+        """Per-entity invalid field names parsed from the server's error strings."""
+        result: dict[str, list[str]] = {}
+        for err in self.entity_errors:
+            entity_id = err.get("entity_id")
+            error_text = err.get("error") or ""
+            if not entity_id:
+                continue
+            for m in _FIELD_FAILURE_RE.finditer(error_text):
+                bucket = result.setdefault(entity_id, [])
+                field = m.group("field")
+                if field not in bucket:
+                    bucket.append(field)
+        return result
+
+    @property
+    def reserved_keyword_entity_types(self) -> set[str]:
+        """Entity-type tokens extracted from quoted "reserved keyword '<x>'" mentions."""
+        result: set[str] = set()
+        for err in self.entity_errors:
+            error_text = err.get("error") or ""
+            for m in _RESERVED_KEYWORD_RE.finditer(error_text):
+                result.add(m.group("keyword"))
+        return result

octostar/utils/jobs/apps/deploy_app.py

@@ -0,0 +1,81 @@
+import os
+import logging
+from typing import Any, Optional
+
+_logger = logging.getLogger(__name__)
+
+from ....api.apps import deploy_app
+from ....models.deploy_app_json_body import DeployAppJsonBody
+from ....models.deploy_app_json_body_secrets import DeployAppJsonBodySecrets
+from ....client import Client
+from ...exceptions import ApiConnectionError
+
+
+def sync(
+    workspace_id: str,
+    os_entity_uid: str,
+    secrets: Optional[dict[str, Any]] = None,
+    client: Client = None,
+):
+    """
+    # Deploys the App defined by a given workspace and entity (the app root folder).
+
+    ## Arguments
+    - `workspace_id`: The ID of the workspace containing the app folder.
+    - `os_entity_uid`: The entity ID of the app folder.
+    - `secrets`: An optional key-value pair of secrets to deploy the app with.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    The app entity.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    if not secrets:
+        secrets = {}
+    secrets_body = DeployAppJsonBody(DeployAppJsonBodySecrets(**secrets))
+    response = deploy_app.sync_detailed(
+        workspace=workspace_id,
+        os_entity_uid=os_entity_uid,
+        json_body=secrets_body,
+        client=client,
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("deploy_app", response, client)
+    return response.parsed
+
+
+async def asyncio(
+    workspace_id: str,
+    os_entity_uid: str,
+    secrets: Optional[dict[str, Any]] = None,
+    client: Client = None,
+):
+    """
+    # Deploys asynchronously the App defined by a given workspace and entity (the app root folder).
+
+    ## Arguments
+    - `workspace_id`: The ID of the workspace containing the app folder.
+    - `os_entity_uid`: The entity ID of the app folder.
+    - `secrets`: An optional key-value pair of secrets to deploy the app with.
+    - `client`: The Client with which to connect to Octostar. If None, the default one is used.
+
+    ## Returns
+    The app entity.
+
+    ## Raises
+    - `ApiConnectionError`: If the request was unsuccessful on the server.
+    """
+    if not secrets:
+        secrets = {}
+    secrets_body = DeployAppJsonBody(DeployAppJsonBodySecrets(**secrets))
+    response = await deploy_app.asyncio_detailed(
+        workspace=workspace_id,
+        os_entity_uid=os_entity_uid,
+        json_body=secrets_body,
+        client=client,
+    )
+    if response.status_code != 200:
+        raise ApiConnectionError("deploy_app", response, client)
+    return response.parsed