unique_toolkit 1.77.2__tar.gz → 1.77.3__tar.gz

{unique_toolkit-1.77.2 → unique_toolkit-1.77.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 1.77.2
+Version: 1.77.3
 Summary: 
 Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
 Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>

{unique_toolkit-1.77.2 → unique_toolkit-1.77.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "1.77.2"
+version = "1.77.3"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"

unique_toolkit-1.77.3/unique_toolkit/experimental/__init__.py

@@ -0,0 +1,23 @@
+"""``unique_toolkit.experimental`` — opt-in surface for experimental services.
+
+.. warning::
+
+    Anything exported from this subpackage is **experimental**. The public API,
+    method names, argument shapes, and return types may change at any time and
+    are **not** covered by the toolkit's normal stability guarantees. Pin the
+    toolkit version if you depend on a specific shape.
+
+Currently exposes:
+
+- :class:`unique_toolkit.experimental.scheduled_task.ScheduledTasks` — cron-based
+  scheduled tasks that trigger assistants on a recurring schedule (wrapper over
+  :class:`unique_sdk.ScheduledTask`).
+"""
+
+from unique_toolkit.experimental.scheduled_task import (
+    ScheduledTasks as ScheduledTasks,
+)
+
+__all__ = [
+    "ScheduledTasks",
+]

unique_toolkit-1.77.3/unique_toolkit/experimental/scheduled_task/__init__.py

@@ -0,0 +1,71 @@
+"""``unique_toolkit.experimental.scheduled_task`` — cron-based assistant triggers.
+
+.. warning::
+
+    **Experimental.** This subpackage is exposed under
+    :mod:`unique_toolkit.experimental` and its public API may change without
+    notice. It is not covered by the toolkit's normal stability guarantees.
+
+A thin, typed wrapper around :class:`unique_sdk.ScheduledTask`. The single
+entry point is :class:`ScheduledTasks`; the subpackage also re-exports the
+Pydantic schemas used on responses, plus a :class:`Cron` ``StrEnum`` of
+ready-made cron strings for the most common schedules.
+"""
+
+from unique_toolkit.experimental.scheduled_task.cron import Cron as Cron
+from unique_toolkit.experimental.scheduled_task.functions import (
+    create_scheduled_task as create_scheduled_task,
+)
+from unique_toolkit.experimental.scheduled_task.functions import (
+    create_scheduled_task_async as create_scheduled_task_async,
+)
+from unique_toolkit.experimental.scheduled_task.functions import (
+    delete_scheduled_task as delete_scheduled_task,
+)
+from unique_toolkit.experimental.scheduled_task.functions import (
+    delete_scheduled_task_async as delete_scheduled_task_async,
+)
+from unique_toolkit.experimental.scheduled_task.functions import (
+    get_scheduled_task as get_scheduled_task,
+)
+from unique_toolkit.experimental.scheduled_task.functions import (
+    get_scheduled_task_async as get_scheduled_task_async,
+)
+from unique_toolkit.experimental.scheduled_task.functions import (
+    list_scheduled_tasks as list_scheduled_tasks,
+)
+from unique_toolkit.experimental.scheduled_task.functions import (
+    list_scheduled_tasks_async as list_scheduled_tasks_async,
+)
+from unique_toolkit.experimental.scheduled_task.functions import (
+    update_scheduled_task as update_scheduled_task,
+)
+from unique_toolkit.experimental.scheduled_task.functions import (
+    update_scheduled_task_async as update_scheduled_task_async,
+)
+from unique_toolkit.experimental.scheduled_task.schemas import (
+    DeletedScheduledTask as DeletedScheduledTask,
+)
+from unique_toolkit.experimental.scheduled_task.schemas import (
+    ScheduledTask as ScheduledTask,
+)
+from unique_toolkit.experimental.scheduled_task.service import (
+    ScheduledTasks as ScheduledTasks,
+)
+
+__all__ = [
+    "Cron",
+    "DeletedScheduledTask",
+    "ScheduledTask",
+    "ScheduledTasks",
+    "create_scheduled_task",
+    "create_scheduled_task_async",
+    "delete_scheduled_task",
+    "delete_scheduled_task_async",
+    "get_scheduled_task",
+    "get_scheduled_task_async",
+    "list_scheduled_tasks",
+    "list_scheduled_tasks_async",
+    "update_scheduled_task",
+    "update_scheduled_task_async",
+]

unique_toolkit-1.77.3/unique_toolkit/experimental/scheduled_task/cron.py

@@ -0,0 +1,90 @@
+"""Convenience catalogue of 5-field (UTC) cron strings for scheduled tasks.
+
+The server stores schedules as plain cron strings. :class:`Cron` is a
+:class:`~enum.StrEnum` of the most common schedules — every member *is* a
+``str``, so you can drop it straight into :meth:`ScheduledTasks.create`
+without any conversion. For schedules that aren't covered, pass a raw cron
+string.
+
+.. note::
+
+    All expressions are interpreted in **UTC** by the server.
+
+.. warning::
+
+    **Experimental.** Ships under :mod:`unique_toolkit.experimental`. API may
+    change without notice.
+
+Example
+-------
+
+    >>> from unique_toolkit.experimental.scheduled_task import Cron
+    >>> Cron.DAILY_MIDNIGHT
+    <Cron.DAILY_MIDNIGHT: '0 0 * * *'>
+    >>> str(Cron.DAILY_MIDNIGHT)
+    '0 0 * * *'
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Cron(StrEnum):
+    """Named ready-made 5-field cron expressions (UTC).
+
+    Each member is a ``str`` subclass, so instances can be passed straight
+    through to anything expecting a cron string — including
+    :meth:`ScheduledTasks.create`.
+    """
+
+    EVERY_MINUTE = "* * * * *"
+    """Fires every minute."""
+
+    EVERY_FIVE_MINUTES = "*/5 * * * *"
+    """Fires every 5 minutes."""
+
+    EVERY_FIFTEEN_MINUTES = "*/15 * * * *"
+    """Fires every 15 minutes."""
+
+    EVERY_THIRTY_MINUTES = "*/30 * * * *"
+    """Fires every 30 minutes."""
+
+    HOURLY = "0 * * * *"
+    """Fires once an hour on the hour (``:00``)."""
+
+    DAILY_MIDNIGHT = "0 0 * * *"
+    """Fires once a day at 00:00 UTC."""
+
+    DAILY_NOON = "0 12 * * *"
+    """Fires once a day at 12:00 UTC."""
+
+    DAILY_9AM = "0 9 * * *"
+    """Fires once a day at 09:00 UTC."""
+
+    WEEKDAYS_9AM = "0 9 * * 1-5"
+    """Fires on weekdays (Mon-Fri) at 09:00 UTC."""
+
+    WEEKDAYS_MIDNIGHT = "0 0 * * 1-5"
+    """Fires on weekdays (Mon-Fri) at 00:00 UTC."""
+
+    WEEKENDS_MIDNIGHT = "0 0 * * 0,6"
+    """Fires on weekends (Sat & Sun) at 00:00 UTC."""
+
+    WEEKLY_SUNDAY_MIDNIGHT = "0 0 * * 0"
+    """Fires every Sunday at 00:00 UTC."""
+
+    WEEKLY_MONDAY_MIDNIGHT = "0 0 * * 1"
+    """Fires every Monday at 00:00 UTC."""
+
+    MONTHLY_FIRST_MIDNIGHT = "0 0 1 * *"
+    """Fires on the 1st of every month at 00:00 UTC."""
+
+    MONTHLY_FIFTEENTH_MIDNIGHT = "0 0 15 * *"
+    """Fires on the 15th of every month at 00:00 UTC."""
+
+    YEARLY_JAN_FIRST = "0 0 1 1 *"
+    """Fires on January 1st at 00:00 UTC."""
+
+
+__all__ = ["Cron"]

unique_toolkit-1.77.3/unique_toolkit/experimental/scheduled_task/functions.py

@@ -0,0 +1,311 @@
+"""Low-level function wrappers around :class:`unique_sdk.ScheduledTask`.
+
+Each SDK operation gets a ``<verb>`` and ``<verb>_async`` pair. The functions
+take ``user_id`` and ``company_id`` as the first two positional arguments (the
+acting user's credentials) and return toolkit Pydantic models — SDK
+``TypedDict``\\s never leak out of this module.
+
+Notes on update semantics
+-------------------------
+
+:func:`update_scheduled_task` / :func:`update_scheduled_task_async` support two
+mutually-exclusive intents for :attr:`chat_id`:
+
+- Pass ``chat_id="chat_…"`` to repoint the task at a different chat.
+- Pass ``clear_chat_id=True`` to drop the current link (the SDK sends
+  ``chatId=None`` on the wire; the server then spawns a fresh chat on every
+  trigger).
+- Omit both to leave the current chat setting untouched.
+
+Mixing them raises :class:`TypeError` before the SDK call.
+
+.. warning::
+
+    **Experimental.** Lives under :mod:`unique_toolkit.experimental`. The API
+    may change without notice.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import unique_sdk
+
+from unique_toolkit.experimental.scheduled_task.schemas import (
+    DeletedScheduledTask,
+    ScheduledTask,
+)
+
+
+def create_scheduled_task(
+    user_id: str,
+    company_id: str,
+    *,
+    cron_expression: str,
+    assistant_id: str,
+    prompt: str,
+    enabled: bool = True,
+    chat_id: str | None = None,
+) -> ScheduledTask:
+    """Create a new cron-based scheduled task.
+
+    Args:
+        user_id: Acting user (SDK requirement).
+        company_id: Owning company (SDK requirement).
+        cron_expression: 5-field UTC cron expression (``"m h dom mon dow"``).
+        assistant_id: Assistant id to execute on every trigger.
+        prompt: Prompt text sent to the assistant on each run.
+        enabled: Whether the task is active from creation. Defaults to
+            ``True`` so tasks fire as soon as they are registered; pass
+            ``False`` to stage a task that can be enabled later via
+            :func:`update_scheduled_task`.
+        chat_id: Optional chat to continue; ``None`` (default) means a fresh
+            chat is created every run.
+
+    Returns:
+        The created :class:`ScheduledTask` as echoed by the server.
+    """
+    params: dict[str, Any] = {
+        "cronExpression": cron_expression,
+        "assistantId": assistant_id,
+        "prompt": prompt,
+        "enabled": enabled,
+    }
+    if chat_id is not None:
+        params["chatId"] = chat_id
+
+    payload = unique_sdk.ScheduledTask.create(
+        user_id=user_id,
+        company_id=company_id,
+        **params,
+    )
+    return ScheduledTask.model_validate(payload, by_alias=True, by_name=True)
+
+
+async def create_scheduled_task_async(
+    user_id: str,
+    company_id: str,
+    *,
+    cron_expression: str,
+    assistant_id: str,
+    prompt: str,
+    enabled: bool = True,
+    chat_id: str | None = None,
+) -> ScheduledTask:
+    """Async :func:`create_scheduled_task`."""
+    params: dict[str, Any] = {
+        "cronExpression": cron_expression,
+        "assistantId": assistant_id,
+        "prompt": prompt,
+        "enabled": enabled,
+    }
+    if chat_id is not None:
+        params["chatId"] = chat_id
+
+    payload = await unique_sdk.ScheduledTask.create_async(
+        user_id=user_id,
+        company_id=company_id,
+        **params,
+    )
+    return ScheduledTask.model_validate(payload, by_alias=True, by_name=True)
+
+
+def list_scheduled_tasks(user_id: str, company_id: str) -> list[ScheduledTask]:
+    """List every scheduled task visible to the acting user."""
+    result = unique_sdk.ScheduledTask.list(user_id=user_id, company_id=company_id)
+    return [
+        ScheduledTask.model_validate(task, by_alias=True, by_name=True)
+        for task in result
+    ]
+
+
+async def list_scheduled_tasks_async(
+    user_id: str, company_id: str
+) -> list[ScheduledTask]:
+    """Async :func:`list_scheduled_tasks`."""
+    result = await unique_sdk.ScheduledTask.list_async(
+        user_id=user_id, company_id=company_id
+    )
+    return [
+        ScheduledTask.model_validate(task, by_alias=True, by_name=True)
+        for task in result
+    ]
+
+
+def get_scheduled_task(
+    user_id: str,
+    company_id: str,
+    *,
+    task_id: str,
+) -> ScheduledTask:
+    """Fetch the full detail of a single scheduled task by id."""
+    payload = unique_sdk.ScheduledTask.retrieve(
+        user_id=user_id,
+        company_id=company_id,
+        id=task_id,
+    )
+    return ScheduledTask.model_validate(payload, by_alias=True, by_name=True)
+
+
+async def get_scheduled_task_async(
+    user_id: str,
+    company_id: str,
+    *,
+    task_id: str,
+) -> ScheduledTask:
+    """Async :func:`get_scheduled_task`."""
+    payload = await unique_sdk.ScheduledTask.retrieve_async(
+        user_id=user_id,
+        company_id=company_id,
+        id=task_id,
+    )
+    return ScheduledTask.model_validate(payload, by_alias=True, by_name=True)
+
+
+def update_scheduled_task(
+    user_id: str,
+    company_id: str,
+    *,
+    task_id: str,
+    cron_expression: str | None = None,
+    assistant_id: str | None = None,
+    prompt: str | None = None,
+    chat_id: str | None = None,
+    clear_chat_id: bool = False,
+    enabled: bool | None = None,
+) -> ScheduledTask:
+    """Update an existing scheduled task (server-side partial update).
+
+    Only the keyword arguments you pass are sent to the API; everything else is
+    left untouched. Pass ``clear_chat_id=True`` to remove the current chat link
+    (``chatId=None`` on the wire) — the server will then spin up a brand-new
+    chat on every future trigger.
+
+    Raises:
+        TypeError: If ``chat_id`` and ``clear_chat_id=True`` are combined.
+    """
+    params = _build_update_params(
+        cron_expression=cron_expression,
+        assistant_id=assistant_id,
+        prompt=prompt,
+        chat_id=chat_id,
+        clear_chat_id=clear_chat_id,
+        enabled=enabled,
+    )
+    payload = unique_sdk.ScheduledTask.modify(
+        user_id=user_id,
+        company_id=company_id,
+        id=task_id,
+        **params,
+    )
+    return ScheduledTask.model_validate(payload, by_alias=True, by_name=True)
+
+
+async def update_scheduled_task_async(
+    user_id: str,
+    company_id: str,
+    *,
+    task_id: str,
+    cron_expression: str | None = None,
+    assistant_id: str | None = None,
+    prompt: str | None = None,
+    chat_id: str | None = None,
+    clear_chat_id: bool = False,
+    enabled: bool | None = None,
+) -> ScheduledTask:
+    """Async :func:`update_scheduled_task`."""
+    params = _build_update_params(
+        cron_expression=cron_expression,
+        assistant_id=assistant_id,
+        prompt=prompt,
+        chat_id=chat_id,
+        clear_chat_id=clear_chat_id,
+        enabled=enabled,
+    )
+    payload = await unique_sdk.ScheduledTask.modify_async(
+        user_id=user_id,
+        company_id=company_id,
+        id=task_id,
+        **params,
+    )
+    return ScheduledTask.model_validate(payload, by_alias=True, by_name=True)
+
+
+def delete_scheduled_task(
+    user_id: str,
+    company_id: str,
+    *,
+    task_id: str,
+) -> DeletedScheduledTask:
+    """Permanently delete a scheduled task. This action cannot be undone."""
+    payload = unique_sdk.ScheduledTask.delete(
+        user_id=user_id,
+        company_id=company_id,
+        id=task_id,
+    )
+    return DeletedScheduledTask.model_validate(payload, by_alias=True, by_name=True)
+
+
+async def delete_scheduled_task_async(
+    user_id: str,
+    company_id: str,
+    *,
+    task_id: str,
+) -> DeletedScheduledTask:
+    """Async :func:`delete_scheduled_task`.
+
+    Falls back to :func:`asyncio.to_thread` if the SDK method does not provide
+    an ``_async`` variant, so the event loop is never blocked.
+    """
+    sdk_async = getattr(unique_sdk.ScheduledTask, "delete_async", None)
+    if sdk_async is None:
+        return await asyncio.to_thread(
+            delete_scheduled_task,
+            user_id,
+            company_id,
+            task_id=task_id,
+        )
+    payload = await sdk_async(
+        user_id=user_id,
+        company_id=company_id,
+        id=task_id,
+    )
+    return DeletedScheduledTask.model_validate(payload, by_alias=True, by_name=True)
+
+
+def _build_update_params(
+    *,
+    cron_expression: str | None,
+    assistant_id: str | None,
+    prompt: str | None,
+    chat_id: str | None,
+    clear_chat_id: bool,
+    enabled: bool | None,
+) -> dict[str, Any]:
+    """Translate toolkit kwargs into the SDK ``ScheduledTask.ModifyParams`` shape.
+
+    Fields that were not provided are omitted entirely (partial update). The
+    ``chat_id`` / ``clear_chat_id`` pair is mutually exclusive; passing both is
+    a usage error and raises :class:`TypeError` here — never at the SDK layer.
+    """
+    if chat_id is not None and clear_chat_id:
+        raise TypeError(
+            "update_scheduled_task: pass either chat_id= to set a new chat or "
+            "clear_chat_id=True to clear it, not both."
+        )
+
+    params: dict[str, Any] = {}
+    if cron_expression is not None:
+        params["cronExpression"] = cron_expression
+    if assistant_id is not None:
+        params["assistantId"] = assistant_id
+    if prompt is not None:
+        params["prompt"] = prompt
+    if chat_id is not None:
+        params["chatId"] = chat_id
+    elif clear_chat_id:
+        params["chatId"] = None
+    if enabled is not None:
+        params["enabled"] = enabled
+    return params

unique_toolkit-1.77.3/unique_toolkit/experimental/scheduled_task/schemas.py

@@ -0,0 +1,152 @@
+"""Pydantic schemas for the :mod:`unique_toolkit.experimental.scheduled_task` subpackage.
+
+These models mirror the :class:`unique_sdk.ScheduledTask` TypedDicts but add:
+
+- field-level documentation (``Field(..., description=...)``) so the intent of each
+  attribute is visible in IDEs, the docs site, and ``help(...)``;
+- camelCase aliases so the SDK's wire payload (``cronExpression``, ``assistantId``, …)
+  can be validated directly via :meth:`BaseModel.model_validate`.
+
+.. warning::
+
+    **Experimental.** Lives under :mod:`unique_toolkit.experimental`; the public
+    shape of these models may still change without notice.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from humps import camelize
+from pydantic import BaseModel, ConfigDict, Field
+
+_model_config = ConfigDict(
+    alias_generator=camelize,
+    populate_by_name=True,
+    arbitrary_types_allowed=True,
+)
+
+
+class ScheduledTask(BaseModel):
+    """A cron-based scheduled task that triggers an assistant on a recurring schedule.
+
+    Scheduled tasks are stored and executed on the Unique AI Platform by a
+    Kubernetes CronJob — they are **not** local crontab entries. Every minute,
+    the platform evaluates all enabled tasks and triggers the ones whose cron
+    expression matches the current time (UTC).
+
+    Each task carries:
+
+    - a :attr:`cron_expression` in **5-field UTC** form,
+    - the :attr:`assistant_id` to execute on each tick,
+    - the :attr:`prompt` sent to that assistant,
+    - an optional :attr:`chat_id` used to *continue* an existing conversation
+      (omit / set to ``None`` to get a fresh chat on every run), and
+    - an :attr:`enabled` flag to pause/resume execution without deleting the task.
+
+    Maps to ``unique_sdk.ScheduledTask`` and is the return value of every toolkit
+    CRUD method except :meth:`~unique_toolkit.experimental.scheduled_task.service.ScheduledTasks.delete`.
+    """
+
+    model_config = _model_config
+
+    id: str = Field(
+        description=(
+            "Unique scheduled-task identifier. Stable for the lifetime of the "
+            "task; use it to :meth:`get`, :meth:`update`, or :meth:`delete` "
+            "later."
+        ),
+    )
+    object: Literal["scheduled_task"] = Field(
+        default="scheduled_task",
+        description=(
+            'Server-side object-type tag; always the literal ``"scheduled_task"``.'
+        ),
+    )
+    cron_expression: str = Field(
+        description=(
+            "5-field cron expression evaluated in **UTC** as returned by the "
+            "server. Stored as the raw wire string so that compound patterns "
+            "(ranges, steps, lists) survive round-trips; use "
+            ":meth:`CronExpression.parse` on the client if you want a typed "
+            "view."
+        ),
+    )
+
+    assistant_id: str = Field(
+        description=(
+            "Id of the assistant to invoke on each trigger. Typically starts with "
+            "``assistant_``. The acting user must have access to the assistant."
+        ),
+    )
+    assistant_name: str | None = Field(
+        default=None,
+        description=(
+            "Display name of the assistant, as resolved by the server at read time. "
+            "``None`` if the assistant was deleted or the caller cannot see it."
+        ),
+    )
+    chat_id: str | None = Field(
+        default=None,
+        description=(
+            "Id of the chat to continue on each trigger. When ``None`` (the default), "
+            "a brand-new chat is created for every run; when set, the assistant "
+            "appends to that chat, so prompts should be idempotent or progressive."
+        ),
+    )
+    prompt: str = Field(
+        description=(
+            "Prompt text delivered to the assistant on every trigger. Treat as a "
+            "user message sent by the acting user."
+        ),
+    )
+    enabled: bool = Field(
+        description=(
+            "Whether the task is active. Disabled tasks are preserved (id, cron, "
+            "history) but are skipped by the scheduler until re-enabled."
+        ),
+    )
+    last_run_at: datetime | None = Field(
+        default=None,
+        description=(
+            "ISO-8601 timestamp of the last execution, or ``None`` if the task has "
+            "never run (e.g. freshly created or permanently disabled)."
+        ),
+    )
+    created_at: datetime = Field(
+        description="ISO-8601 timestamp set by the server when the task was created.",
+    )
+    updated_at: datetime = Field(
+        description=(
+            "ISO-8601 timestamp of the last modification, including toggles of "
+            ":attr:`enabled` and edits to :attr:`chat_id` or :attr:`prompt`."
+        ),
+    )
+
+
+class DeletedScheduledTask(BaseModel):
+    """Response returned by :meth:`unique_sdk.ScheduledTask.delete`.
+
+    The API echoes the deleted task's id and flags the row as removed. Deletion
+    is permanent; a deleted task cannot be recovered, so re-scheduling requires
+    calling :meth:`~unique_toolkit.experimental.scheduled_task.service.ScheduledTasks.create`
+    with fresh parameters.
+    """
+
+    model_config = _model_config
+
+    id: str = Field(description="Id of the scheduled task that was deleted.")
+    object: Literal["scheduled_task"] = Field(
+        default="scheduled_task",
+        description=(
+            'Server-side object-type tag; always the literal ``"scheduled_task"``.'
+        ),
+    )
+    deleted: bool = Field(
+        description=(
+            "``True`` when the server successfully removed the row. The toolkit "
+            "surfaces this verbatim — a ``False`` value should be treated as an "
+            "unexpected server response and reported."
+        ),
+    )