keble-task 2.22.0__py3-none-any.whl

keble_task/schemas/for_agent.py

@@ -0,0 +1,177 @@
+"""Agent-facing task schemas (pydantic-ai tool I/O contracts).
+
+Every type here is part of the contract an AI agent sees: the typed RETURN
+projection of the task READ/QUERY tools, plus the tool-registration configs for
+the QUERY and MUTATION tools. They are named with the ``ForAgent`` suffix (and
+``Agent`` infix on the configs) so a reader can tell them apart from:
+
+- persisted/CRUD/event/domain models (``TaskBase``/``TaskUpdate``/
+  ``TaskMongoObject``/``TaskActionEvent``);
+- the external action module ``keble_task.actions`` (``TaskActions`` etc.),
+  which is the typed mutation payload, NOT a tool I/O projection.
+
+Placement rule (enforced by ``tests/schemas/test_for_agent.py``): agent tool I/O
+schemas live HERE in ``schemas/``, never inside the behavior registrars under
+``agent/tools/``.
+
+Side effect if changes:
+- ``TaskSummaryForAgent`` is the return type of the query tools in
+  ``agent/tools/query.py`` (``list_tasks``, ``get_task``). Field renames change
+  the agent-visible JSON.
+- ``TaskAgentQueryToolsConfig`` / ``TaskAgentMutationToolsConfig`` are consumed
+  by ``agent/tools/query.py``, ``agent/tools/mutation.py``,
+  ``agent/chat_provider.py``, and keble.backend chat composition.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from keble_helpers import AgentToolRegistrationConfig, PydanticModelConfig
+from pydantic import BaseModel, Field
+
+from keble_task.schemas import TaskMongoObject, TaskStage
+
+
+# ---------------------------------------------------------------------------
+# Query tool RETURN projection (compact, JSON-safe, never raw payloads).
+# ---------------------------------------------------------------------------
+
+
+class TaskSummaryForAgent(BaseModel):
+    """Compact, JSON-safe projection of one task for agent reads.
+
+    Only safe, user-presentable identity/status fields are exposed; raw
+    ``metadata`` is intentionally omitted so the agent never sees provider
+    payloads, stable keys, or internal dumps. Failure facts (``error`` /
+    ``exception_type``) ARE exposed so the agent can explain WHY a task
+    failed instead of guessing.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    id: str = Field(description="Task id (ObjectId as string).")
+    task_type: str
+    title: str | None = None
+    subtitle: str | None = None
+    stage: TaskStage = Field(description="Task lifecycle stage (PENDING/PROCESSING/SUCCESS/FAILURE).")
+    root_task_id: str | None = None
+    parent_task_id: str | None = None
+    created: str | None = None
+    error: str | None = Field(
+        default=None,
+        description="Failure message recorded by the worker (only set when the task failed).",
+    )
+    exception_type: str | None = Field(
+        default=None,
+        description=(
+            "Failure category, e.g. NO_SUFFICIENT_DATA / TIMEOUT / FAILED_TO_START / "
+            "UNKNOWN (only set when the task failed)."
+        ),
+    )
+
+    @classmethod
+    def from_task(cls, task: TaskMongoObject) -> "TaskSummaryForAgent":
+        """Build the compact projection from a stored task.
+
+        Step by step:
+        1. stringify every ObjectId so the projection is JSON-safe for the model;
+        2. carry the lifecycle stage as its `TaskStage` enum (a `(str, Enum)` that
+           serializes to its value while staying typed);
+        3. carry only safe title/subtitle, dropping internal metadata;
+        4. carry failure facts (error + exception_type value) so a failed task
+           is explainable by the agent.
+        """
+
+        return cls(
+            id=str(task.id),
+            task_type=task.task_type,
+            title=task.title,
+            subtitle=task.subtitle,
+            stage=task.stage,
+            root_task_id=str(task.root_task) if task.root_task is not None else None,
+            parent_task_id=str(task.parent_task) if task.parent_task is not None else None,
+            created=task.created.isoformat() if task.created is not None else None,
+            error=task.error,
+            exception_type=(
+                task.exception_type.value if task.exception_type is not None else None
+            ),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Tool-registration configs (query + mutation).
+# ---------------------------------------------------------------------------
+
+
+class TaskAgentQueryToolsConfig(BaseModel):
+    """Tool-registration config for the task-owned read/query tools.
+
+    Side effect if changes:
+    - `agent/tools/query.py::register_query_tools` resolves each field through
+      `AgentToolRegistrationConfig.build(...)`; changing field names changes
+      backend chat provider override payloads.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    list_tasks: AgentToolRegistrationConfig = Field(
+        default_factory=AgentToolRegistrationConfig
+    )
+    get_task: AgentToolRegistrationConfig = Field(
+        default_factory=AgentToolRegistrationConfig
+    )
+
+    @classmethod
+    def build(
+        cls,
+        value: "TaskAgentQueryToolsConfig | dict[str, Any] | None" = None,
+    ) -> "TaskAgentQueryToolsConfig":
+        """Build validated query-tool config from optional input."""
+
+        if value is None:
+            return cls()
+        if isinstance(value, cls):
+            return value
+        return cls.model_validate(value)
+
+
+class TaskAgentMutationToolsConfig(BaseModel):
+    """Tool registration config for task-owned pydantic-ai mutation tools.
+
+    Side effect if changes:
+    - `agent/tools/mutation.py::register_mutation_tools` resolves this metadata
+      before registering the model-facing `mutate_task_workspace` tool.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    mutate_task_workspace: AgentToolRegistrationConfig = Field(
+        default_factory=AgentToolRegistrationConfig
+    )
+
+    @classmethod
+    def build(
+        cls,
+        value: "TaskAgentMutationToolsConfig | dict[str, Any] | None" = None,
+    ) -> "TaskAgentMutationToolsConfig":
+        """Build validated task tool config from optional input.
+
+        Step by step:
+        1. return the default config when callers pass no override;
+        2. preserve already validated config objects;
+        3. validate raw dict payloads at the package registrar boundary.
+        """
+
+        if value is None:
+            return cls()
+        if isinstance(value, cls):
+            return value
+        return cls.model_validate(value)
+
+
+__all__ = [
+    "TaskSummaryForAgent",
+    "TaskAgentQueryToolsConfig",
+    "TaskAgentMutationToolsConfig",
+]

keble_task/task_tree.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import keble_exceptions
+from keble_helpers import ObjectId
+
+from .schemas import TaskMongoObject, TaskMongoObjectExtended
+
+
+def build_task_tree(
+    *, roots: list[TaskMongoObject], tasks: list[TaskMongoObject]
+) -> list[TaskMongoObjectExtended]:
+    """Compose persisted task rows into nested root trees.
+
+    The given `roots` are the requested subtree tops, so a root's own `parent_task`
+    may legitimately point at an ancestor outside the loaded set (e.g. list filters
+    surface a descendant while excluding its parent). For every NON-root task,
+    however, the parent must be present: an absent parent, a missing requested root,
+    or a parent cycle is corrupted persisted data rather than a partial view, and per
+    the corrupted-reference rule these raise typed domain errors instead of silently
+    shrinking the tree.
+
+    Step by step:
+    1. index tasks by id and group children under their parent, recording any
+       non-root task whose parent is missing from the loaded set;
+    2. raise `ObjectNotFound` if a non-root parent or a requested root is absent;
+    3. sort each sibling group newest-first by persisted `created`;
+    4. build nodes depth-first, raising `DataIntegrityCompromised` on a parent cycle.
+    """
+
+    tasks_by_id = {task.id: task for task in tasks}
+    root_ids = {root.id for root in roots}
+    children_by_parent: dict[ObjectId, list[ObjectId]] = {}
+    missing_parent_ids: list[ObjectId] = []
+
+    for task in tasks:
+        if task.parent_task is None:
+            continue
+        if task.parent_task not in tasks_by_id:
+            # A requested subtree root may point at an ancestor outside the set;
+            # any other orphan is corrupted lineage and must fail hard.
+            if task.id in root_ids:
+                continue
+            missing_parent_ids.append(task.parent_task)
+            continue
+        children_by_parent.setdefault(task.parent_task, []).append(task.id)
+
+    if missing_parent_ids:
+        raise keble_exceptions.ObjectNotFound(
+            object_name="Task",
+            id=missing_parent_ids,
+            alert_admin=True,
+            admin_note={
+                "reason": "child task references a parent absent from its root tree"
+            },
+        )
+
+    def created_sort_key(task_id: ObjectId) -> float:
+        # `created` is a non-Optional persisted datetime for rows loaded from Mongo.
+        return tasks_by_id[task_id].created.timestamp()
+
+    for child_ids in children_by_parent.values():
+        child_ids.sort(key=created_sort_key, reverse=True)
+
+    def build_node(task_id: ObjectId, stack: set[ObjectId]) -> TaskMongoObjectExtended:
+        if task_id in stack:
+            raise keble_exceptions.DataIntegrityCompromised(
+                object_name="Task",
+                id=task_id,
+                alert_admin=True,
+                admin_note={"reason": "parent cycle detected while building task tree"},
+            )
+        task = tasks_by_id[task_id]
+        next_stack = set(stack)
+        next_stack.add(task_id)
+        childs = [
+            build_node(child_id, next_stack)
+            for child_id in children_by_parent.get(task_id, [])
+        ]
+        return TaskMongoObjectExtended(**task.model_dump(), childs=childs)
+
+    missing_root_ids = [root.id for root in roots if root.id not in tasks_by_id]
+    if missing_root_ids:
+        raise keble_exceptions.ObjectNotFound(
+            object_name="Task",
+            id=missing_root_ids,
+            alert_admin=True,
+            admin_note={
+                "reason": "requested root task absent from the loaded task set"
+            },
+        )
+
+    return [build_node(root.id, set()) for root in roots]
+
+
+def find_task_in_tree(
+    *, nodes: list[TaskMongoObjectExtended], task_id: ObjectId
+) -> Optional[TaskMongoObjectExtended]:
+    stack = list(nodes)
+    while len(stack) > 0:
+        node = stack.pop()
+        if node.id == task_id:
+            return node
+        stack.extend(node.childs)
+    return None

keble_task/utils.py

@@ -0,0 +1,58 @@
+from enum import Enum
+from typing import List, Optional
+
+import keble_exceptions
+
+
+class Difficulty(str, Enum):
+    """A difficulty class for everythings"""
+
+    UNKNOWN = "UNKNOWN"
+    LOW = "LOW"
+    MEDIAN = "MEDIAN"
+    HIGH = "HIGH"
+
+    @classmethod
+    def from_reason(
+        cls,
+        # reason can be any type of enum
+        # starting by Difficulty.value
+        # for example, UNKNOWN_DUE_TO_LACK_OF_DATA
+        # HIGH_RND
+        reason: Enum | str,
+    ) -> "Difficulty":
+        if isinstance(reason, Enum):
+            reason_str = reason.value
+        else:
+            reason_str = reason
+        difficulties = list(Difficulty)
+        for d in difficulties:
+            if d.value in reason_str and d.value == reason_str[: len(d.value)]:
+                return d
+        raise keble_exceptions.UnhandledScenarioOrCase(
+            admin_note={
+                "reason": reason,
+                "error": "Failed to convert reason to Difficulty",
+            },
+            alert_admin=True,
+            unhandled_case=f"reason={reason}",
+        )
+
+    @classmethod
+    def merge(cls, difficulties: List["Difficulty"]) -> Optional["Difficulty"]:
+        difficulty_score = {"UNKNOWN": 0, "LOW": 1, "MEDIAN": 2, "HIGH": 3}
+        scores = []
+        for d in difficulties:
+            if d.value not in difficulty_score:
+                raise keble_exceptions.UnhandledScenarioOrCase(
+                    admin_note={"difficulty": d.value},
+                    alert_admin=True,
+                    unhandled_case=f"difficulty={d.value}",
+                )
+            scores.append(difficulty_score[d.value])
+        if len(scores) == 0:
+            return None
+        max_s = max(scores)
+        for k, v in difficulty_score.items():
+            if v == max_s:
+                return Difficulty(k)