keble-task 2.22.0__py3-none-any.whl

keble_task/__init__.py

@@ -0,0 +1,143 @@
+from .crud import CRUDTask, CRUDTaskCost, CRUDTaskRelation
+from .exceptions import (
+    TaskException,
+    TaskExceptionType,
+    TaskFailedToStartException,
+    TaskNoSufficientDataException,
+)
+from .actions import (
+    CreateRelatedTaskAction,
+    CreateRelatedTaskActionedResult,
+    TaskAction,
+    TaskActionCreatedRelation,
+    TaskActionCreatedTask,
+    TaskActionEvent,
+    TaskActionType,
+    TaskActionedResult,
+    TaskActionedResults,
+    TaskActions,
+    TaskEventType,
+    TaskLifecycleEvent,
+    TaskLifecycleEventPayload,
+    TaskUxContext,
+)
+from .main import (
+    TaskClient,
+    TaskHandlerRequest,
+    TaskHandlerResponse,
+    TokenConsumptionPayload,
+    TokenConsumptionType,
+)
+from .agent import (
+    TaskAgentContext,
+    TaskAgentDeps,
+    TaskAgentMutationToolsConfig,
+    TaskAgentQueryToolsConfig,
+    TaskQueryChatToolProvider,
+    TaskSummaryForAgent,
+    register_mutation_tools,
+    register_query_tools,
+)
+from .schemas import (
+    TaskBase,
+    TaskCostAggregateBucket,
+    TaskCostAggregateGroupBy,
+    TaskCostAggregateRequest,
+    TaskCostAggregateResponse,
+    TaskCostBase,
+    TaskCostCreate,
+    TaskCostFilterBase,
+    TaskCostListRequest,
+    TaskCostListResponse,
+    TaskCostMetadata,
+    TaskCostMongoObject,
+    TaskCostTimeBucket,
+    TaskCostTokenRates,
+    TaskMongoObject,
+    TaskMongoObjectExtended,
+    TaskPublicRef,
+    TaskRelationMetadata,
+    TaskRoomGraphContext,
+    TaskRoomGraphRelation,
+    TaskRoomGraphTask,
+    TaskRoomResolution,
+    TaskRelationBase,
+    TaskRelationCreate,
+    TaskRelationMongoObject,
+    TaskRelationType,
+    TaskRelationUpdate,
+    TaskStage,
+    TaskUpdate,
+    build_task_cost_metadata,
+    build_task_relation_metadata,
+)
+from .utils import Difficulty
+
+__all__ = [
+    "CRUDTask",
+    "CRUDTaskCost",
+    "CRUDTaskRelation",
+    "Difficulty",
+    "TaskBase",
+    "TaskCostAggregateBucket",
+    "TaskCostAggregateGroupBy",
+    "TaskCostAggregateRequest",
+    "TaskCostAggregateResponse",
+    "TaskCostBase",
+    "TaskCostCreate",
+    "TaskCostFilterBase",
+    "TaskCostListRequest",
+    "TaskCostListResponse",
+    "TaskCostMetadata",
+    "TaskCostMongoObject",
+    "TaskCostTimeBucket",
+    "TaskCostTokenRates",
+    "CreateRelatedTaskAction",
+    "CreateRelatedTaskActionedResult",
+    "TaskClient",
+    "TaskException",
+    "TaskExceptionType",
+    "TaskFailedToStartException",
+    "TaskHandlerRequest",
+    "TaskHandlerResponse",
+    "TaskMongoObject",
+    "TaskMongoObjectExtended",
+    "TaskPublicRef",
+    "TaskNoSufficientDataException",
+    "TaskAction",
+    "TaskActionCreatedRelation",
+    "TaskActionCreatedTask",
+    "TaskAgentContext",
+    "TaskAgentDeps",
+    "TaskActionEvent",
+    "TaskActionType",
+    "TaskActionedResult",
+    "TaskActionedResults",
+    "TaskActions",
+    "TaskEventType",
+    "TaskLifecycleEvent",
+    "TaskLifecycleEventPayload",
+    "TaskAgentMutationToolsConfig",
+    "TaskAgentQueryToolsConfig",
+    "TaskRelationBase",
+    "TaskRelationCreate",
+    "TaskRelationMetadata",
+    "TaskRelationMongoObject",
+    "TaskRelationType",
+    "TaskRoomGraphContext",
+    "TaskRoomGraphRelation",
+    "TaskRoomGraphTask",
+    "TaskRoomResolution",
+    "TaskRelationUpdate",
+    "TaskStage",
+    "TaskQueryChatToolProvider",
+    "TaskSummaryForAgent",
+    "TaskUpdate",
+    "TaskUxContext",
+    "TokenConsumptionPayload",
+    "TokenConsumptionType",
+    "build_task_cost_metadata",
+    "build_task_relation_metadata",
+    "register_mutation_tools",
+    "register_query_tools",
+]

keble_task/actions.py

@@ -0,0 +1,304 @@
+"""Generic task action schemas owned by `keble-task`.
+
+The task package owns task creation, parent/root validation, relation rows,
+terminal completion, and action events. Feature packages must expose their own
+typed tools for feature-specific side effects.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal
+
+from keble_helpers import (
+    AgenticActionEvent,
+    AgenticActionEventSource,
+    AgenticActionEventStatus,
+    AgenticActionPayload,
+    AgenticActionWarningLevel,
+    ObjectId,
+    PydanticModelConfig,
+    SharingScope,
+)
+from pydantic import BaseModel, Field, field_validator
+
+from .schemas import (
+    TaskRelationMetadata,
+    TaskMongoObject,
+    TaskRelationMongoObject,
+    TaskRelationType,
+    TaskStage,
+    build_task_relation_metadata,
+)
+
+TASK_ACTION_EVENT_SOURCE = AgenticActionEventSource.KEBLE_TASK
+
+
+class TaskActionType(str, Enum):
+    """Canonical action commands owned by `keble-task`."""
+
+    CREATE_RELATED_TASK = "CREATE_RELATED_TASK"
+
+
+class TaskEventType(str, Enum):
+    """Canonical non-action task lifecycle events owned by `keble-task`."""
+
+    TASK_STAGE_CHANGED = "TASK_STAGE_CHANGED"
+
+
+class TaskUxContext(BaseModel):
+    """Optional UI/task selection context for one task action batch.
+
+    Step by step:
+    1. `selected_root_task_id` lets callers prove the visible root workspace;
+    2. `selected_task_ids` captures extra user-selected task ids for future action
+       types without changing the canonical task model.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    selected_root_task_id: ObjectId | None = None
+    selected_task_ids: list[ObjectId] = Field(default_factory=list)
+
+
+class CreateRelatedTaskAction(AgenticActionPayload):
+    """Create one child task and optional relation edges.
+
+    This action IS a single `AgenticActionPayload`: it carries its own
+    confirmation `message` and `warning_level`, so one approval card maps to
+    exactly one action. An agent that wants several related tasks emits several
+    `mutate_task_workspace` tool calls (the deferred batch holds them and the
+    frontend resolves one card per click) — it must NEVER be re-wrapped in a
+    `actions: list[...]` payload that inherits the single-action contract.
+
+    Step by step:
+    1. create a task under `parent_task_id` or the current task by default;
+    2. create relation rows from `from_task_ids` or the current task by default;
+    3. optionally mark the created task successful for lightweight generic work.
+
+    Side effect if changes:
+    - `keble_task.agent.registry.mutate_task_workspace` binds this as the single
+      tool payload; `TaskClient.aapply_action` executes one of these.
+    - reused as the element type of the plain REST batch `TaskActions`.
+    """
+
+    model_config = PydanticModelConfig.default(extra="forbid")
+
+    # Defaulted approval copy (not required) so REST/programmatic callers that
+    # build this inside the plain `TaskActions` batch need not author per-action
+    # confirmation text; an agent may override `message` for a friendlier card.
+    message: str = Field(
+        default="Create a related task.",
+        min_length=1,
+        description="Human-friendly confirmation reason for this single action.",
+    )
+    warning_level: AgenticActionWarningLevel = AgenticActionWarningLevel.MUTATION
+
+    action_type: Literal[TaskActionType.CREATE_RELATED_TASK] = (
+        TaskActionType.CREATE_RELATED_TASK
+    )
+    relation_type: TaskRelationType
+    task_type: str | None = None
+    expected_token: int = Field(default=0, ge=0)
+    progress_key: str | None = None
+    image: str | None = None
+    title: str | None = None
+    subtitle: str | None = None
+    metadata: TaskRelationMetadata = Field(default_factory=dict)
+    timeout_mins: int = Field(default=120, ge=1)
+    sharing_scope: SharingScope | None = None
+    parent_task_id: ObjectId | None = Field(
+        default=None,
+        description=(
+            "Leave unset to attach the new task under the current task (the default). "
+            "Only set this to a real task id explicitly provided in the conversation or "
+            "context — never invent an id."
+        ),
+    )
+    from_task_ids: list[ObjectId] = Field(
+        default_factory=list,
+        description=(
+            "Leave empty to draw the relation from the current task (the default). Only "
+            "include real task ids explicitly provided in context — never invent ids."
+        ),
+    )
+    complete_created_task: bool = False
+    consuming_token: int = Field(default=0, ge=0)
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def _normalize_metadata(cls, value: object) -> TaskRelationMetadata:
+        """Normalize action metadata before it is reused for tasks and relations."""
+
+        return build_task_relation_metadata(value)
+
+
+TaskAction = CreateRelatedTaskAction
+
+
+class TaskActionCreatedTask(BaseModel):
+    """Slim public payload for a task created by a task action.
+
+    Step by step:
+    1. expose stable identifiers and display/status fields needed by tools;
+    2. omit Mongo-only fields such as metadata, owner, and timestamps;
+    3. keep `ObjectId` annotations so `model_dump(mode="json")` emits string ids.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    task_id: ObjectId
+    root_task_id: ObjectId | None = None
+    parent_task_id: ObjectId | None = None
+    task_type: str
+    stage: TaskStage
+    title: str | None = None
+    progress_key: str | None = None
+
+    @classmethod
+    def build(cls, *, task: TaskMongoObject) -> "TaskActionCreatedTask":
+        """Convert one internal Mongo task row into the slim action payload."""
+
+        return cls(
+            task_id=task.id,
+            root_task_id=task.root_task,
+            parent_task_id=task.parent_task,
+            task_type=task.task_type,
+            stage=task.stage,
+            title=task.title,
+            progress_key=task.progress_key,
+        )
+
+
+class TaskActionCreatedRelation(BaseModel):
+    """Slim public payload for a relation created by a task action.
+
+    Step by step:
+    1. expose the relation id, root id, endpoints, relation type, and metadata;
+    2. omit Mongo timestamps while preserving public relation metadata;
+    3. keep `ObjectId` annotations for JSON-mode string serialization.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    relation_id: ObjectId
+    root_task_id: ObjectId
+    from_task_id: ObjectId
+    to_task_id: ObjectId
+    relation_type: TaskRelationType
+    metadata: TaskRelationMetadata = Field(default_factory=dict)
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def _normalize_metadata(cls, value: object) -> TaskRelationMetadata:
+        """Normalize relation event metadata before public JSON-mode dumps."""
+
+        return build_task_relation_metadata(value)
+
+    @classmethod
+    def build(cls, *, relation: TaskRelationMongoObject) -> "TaskActionCreatedRelation":
+        """Convert one internal Mongo relation row into the slim action payload.
+
+        Step by step:
+        1. copy the stable relation ids and type;
+        2. carry the persisted relation metadata through the public event DTO;
+        3. leave persistence-only timestamps on the Mongo object.
+        """
+
+        return cls(
+            relation_id=relation.id,
+            root_task_id=relation.root_task,
+            from_task_id=relation.from_task_id,
+            to_task_id=relation.to_task_id,
+            relation_type=relation.relation_type,
+            metadata=relation.metadata,
+        )
+
+
+class TaskActions(BaseModel):
+    """Plain ordered batch of canonical task actions for the REST/programmatic seam.
+
+    This is NOT an `AgenticActionPayload`: a batch cannot honestly carry a single
+    approval `message`/`warning_level`. Each element is itself a single
+    `AgenticActionPayload` action. The agent surface is one-action-per-tool-call
+    (`mutate_task_workspace` + `aapply_action`); only the REST endpoint and
+    programmatic callers use this container via `aapply_actions`.
+
+    Side effect if changes:
+    - `keble.backend` `app/api/endpoints/v3/features/tasks.py` REST body.
+    - `TaskClient.aapply_actions` iterates `actions` in order.
+    """
+
+    model_config = PydanticModelConfig.default(extra="forbid")
+
+    actions: list[TaskAction] = Field(default_factory=list)
+
+
+class CreateRelatedTaskActionedResult(BaseModel):
+    """Result for one `CREATE_RELATED_TASK` action using tool-safe DTOs."""
+
+    model_config = PydanticModelConfig.default()
+
+    action_type: Literal[TaskActionType.CREATE_RELATED_TASK] = (
+        TaskActionType.CREATE_RELATED_TASK
+    )
+    created_task: TaskActionCreatedTask
+    created_relations: list[TaskActionCreatedRelation] = Field(default_factory=list)
+
+
+TaskActionedResult = CreateRelatedTaskActionedResult
+
+
+class TaskActionEvent(AgenticActionEvent[TaskActionedResult]):
+    """Task action event envelope backed by the shared helper event protocol."""
+
+    source: AgenticActionEventSource = TASK_ACTION_EVENT_SOURCE
+    status: AgenticActionEventStatus = AgenticActionEventStatus.SUCCEEDED
+
+
+class TaskLifecycleEventPayload(BaseModel):
+    """Payload for one persisted task lifecycle transition.
+
+    Step by step:
+    1. carry the reloaded persisted task after the stage mutation is committed;
+    2. let consumers use the same task schema as task read APIs;
+    3. keep lifecycle events separate from task action result payloads.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    task: TaskMongoObject
+
+
+class TaskLifecycleEvent(AgenticActionEvent[TaskLifecycleEventPayload]):
+    """Task stage-change event envelope emitted by `TaskClient` lifecycle APIs."""
+
+    source: AgenticActionEventSource = TASK_ACTION_EVENT_SOURCE
+
+
+class TaskActionedResults(BaseModel):
+    """Batch result returned by canonical task action execution."""
+
+    model_config = PydanticModelConfig.default()
+
+    actioned_results: list[TaskActionedResult] = Field(default_factory=list)
+    events: list[TaskActionEvent] = Field(default_factory=list)
+
+
+__all__ = [
+    "TASK_ACTION_EVENT_SOURCE",
+    "CreateRelatedTaskAction",
+    "CreateRelatedTaskActionedResult",
+    "TaskActionCreatedRelation",
+    "TaskActionCreatedTask",
+    "TaskAction",
+    "TaskActionEvent",
+    "TaskActionType",
+    "TaskActionedResult",
+    "TaskActionedResults",
+    "TaskActions",
+    "TaskEventType",
+    "TaskLifecycleEvent",
+    "TaskLifecycleEventPayload",
+    "TaskUxContext",
+]

keble_task/agent/__init__.py

@@ -0,0 +1,27 @@
+"""Public agent-runtime exports for task-owned tool registration.
+
+Agent tool I/O schemas + configs are re-exported from
+``keble_task.schemas.for_agent`` for convenience; the registrars live in
+``keble_task.agent.tools`` (symmetric ``mutation``/``query``).
+"""
+
+from keble_task.schemas.for_agent import (
+    TaskAgentMutationToolsConfig,
+    TaskAgentQueryToolsConfig,
+    TaskSummaryForAgent,
+)
+
+from .chat_provider import TaskQueryChatToolProvider
+from .deps import TaskAgentContext, TaskAgentDeps
+from .tools import register_mutation_tools, register_query_tools
+
+__all__ = [
+    "TaskAgentContext",
+    "TaskAgentDeps",
+    "TaskAgentMutationToolsConfig",
+    "TaskAgentQueryToolsConfig",
+    "TaskQueryChatToolProvider",
+    "TaskSummaryForAgent",
+    "register_mutation_tools",
+    "register_query_tools",
+]

keble_task/agent/chat_provider.py

@@ -0,0 +1,117 @@
+"""Native chat tool provider for task-owned READ/QUERY tools.
+
+keble.backend used to wrap ``register_query_tools`` in a generic backend-side
+adapter just to satisfy ``keble_helpers.ChatToolProviderProtocol``. This module
+ships the provider natively from the package that OWNS the tools, so any
+agentic-chat host can compose the task query tools declaratively (via
+``compose_tool_providers``-style assembly) without writing its own wrapper.
+
+The provider captures its dependencies (``TaskClient`` + optional tool config)
+at construction time; the protocol's ``register(*, agent)`` carries no per-request
+context (deps are construction-captured).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from keble_task.main import TaskClient
+
+from keble_helpers import (
+    ChatToolKind,
+    ChatToolProviderId,
+    ChatToolProviderManifest,
+    AgentToolDescriptor,
+)
+
+from keble_task.schemas.for_agent import TaskAgentQueryToolsConfig
+
+from .tools import register_query_tools
+
+if TYPE_CHECKING:
+    from keble_helpers import ChatToolProviderProtocol
+
+__all__ = ["TaskQueryChatToolProvider"]
+
+
+class TaskQueryChatToolProvider:
+    """Native ``ChatToolProviderProtocol`` provider for owner-scoped task query tools.
+
+    One instance contributes the task-owned, non-mutating ``list_tasks`` /
+    ``get_task`` tools to a single chat-scope agent build. It satisfies the
+    framework-neutral ``keble_helpers.ChatToolProviderProtocol``
+    (``provider_id`` + ``manifest`` + ``register(*, agent)``) so hosts no longer
+    need a generic adapter around ``register_query_tools``.
+    """
+
+    def __init__(
+        self,
+        *,
+        task_client: TaskClient,
+        tools_config: TaskAgentQueryToolsConfig | dict[str, Any] | None = None,
+    ) -> None:
+        """Capture the registration dependencies at construction.
+
+        Step by step:
+        1. store the ``TaskClient`` that backs the owner-scoped task reads;
+        2. store the optional per-tool name/description override config
+           (validated later by ``TaskAgentQueryToolsConfig.build`` inside the
+           registrar, so dict payloads are accepted as-is here).
+        """
+
+        self._task_client = task_client
+        self._tools_config = tools_config
+
+    @property
+    def provider_id(self) -> ChatToolProviderId:
+        """Stable provider id recorded in room diagnostics.
+
+        The ``ChatToolProviderId.TASK_QUERY`` member's wire value
+        (``"task_query"``) is what the frontend maps to a user-readable label
+        and rooms persist in diagnostics.
+        """
+
+        return ChatToolProviderId.TASK_QUERY
+
+    def register(self, *, agent: Any) -> None:
+        """Attach the task query tools to ``agent`` for one scope build.
+
+        Run the canonical ``register_query_tools`` registrar with the
+        construction-captured client and config, mounting ``list_tasks`` /
+        ``get_task`` on the agent's tool registry.
+        """
+
+        register_query_tools(
+            agent,
+            task_client=self._task_client,
+            tools_config=self._tools_config,
+        )
+
+    @property
+    def manifest(self) -> ChatToolProviderManifest:
+        """Declared read-tool inventory (program Phase 6)."""
+
+        config = TaskAgentQueryToolsConfig.build(self._tools_config)
+        return ChatToolProviderManifest(
+            provider_id=self.provider_id,
+            tools=[
+                AgentToolDescriptor(
+                    name=config.list_tasks.name or "list_tasks",
+                    kind=ChatToolKind.QUERY,
+                    summary="List the owner's recent tasks (filterable by type).",
+                ),
+                AgentToolDescriptor(
+                    name=config.get_task.name or "get_task",
+                    kind=ChatToolKind.QUERY,
+                    summary="Read one task by id.",
+                ),
+            ],
+        )
+
+
+if TYPE_CHECKING:
+    # Static structural conformance to the cross-repo standard (no runtime cost).
+    _conformance: ChatToolProviderProtocol = TaskQueryChatToolProvider(
+        task_client=cast(TaskClient, object()),
+    )
+    _ = _conformance

keble_task/agent/deps.py

@@ -0,0 +1,38 @@
+"""Typed pydantic-ai deps contract for task-owned agent tools."""
+
+from __future__ import annotations
+
+from keble_db import AgentDbDeps
+from keble_helpers import AgenticEventEmitter, PydanticModelConfig
+from pydantic import BaseModel, Field, SkipValidation
+
+from keble_task.actions import TaskUxContext
+from keble_task.schemas import TaskMongoObject
+
+
+class TaskAgentContext(BaseModel):
+    """Task-owned runtime context nested under database-wide deps.
+
+    Step by step this context gives package registrars the runtime pieces that
+    cannot live in `AgentDbDeps`:
+    1. `current_task` anchors generic task actions;
+    2. `ux_context` optionally proves the visible task workspace;
+    3. `event_emitter` forwards task action events when the parent runtime has one.
+    """
+
+    model_config = PydanticModelConfig.default(arbitrary_types_allowed=True)
+
+    current_task: TaskMongoObject
+    ux_context: TaskUxContext | None = None
+    event_emitter: SkipValidation[AgenticEventEmitter | None] = Field(default=None)
+
+
+class TaskAgentDeps(AgentDbDeps):
+    """Database-wide deps plus task-owned runtime state."""
+
+    model_config = PydanticModelConfig.default(arbitrary_types_allowed=True)
+
+    task: TaskAgentContext
+
+
+__all__ = ["TaskAgentContext", "TaskAgentDeps"]

keble_task/agent/tools/__init__.py

@@ -0,0 +1,14 @@
+"""Task agent tool registrars (behavior only — symmetric mutation/query).
+
+Schemas for these tools live in ``keble_task.schemas.for_agent`` (agent tool I/O)
+and the external action module ``keble_task.actions`` (mutation payloads). These
+modules contain ONLY registrars — no contract classes.
+"""
+
+from .mutation import register_mutation_tools
+from .query import register_query_tools
+
+__all__ = [
+    "register_mutation_tools",
+    "register_query_tools",
+]