keble-task 2.22.0__py3-none-any.whl

keble_task/schemas/__init__.py

@@ -0,0 +1,1295 @@
+from collections.abc import Sequence
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated, Any, Optional
+from urllib.parse import urlparse
+
+import keble_exceptions
+from bson import ObjectId as BsonObjectId
+from keble_helpers import (
+    Currency,
+    ExchangeRateInUsd,
+    Language,
+    Money,
+    MongoObjectBase,
+    ObjectId,
+    PydanticModelConfig,
+    SchemaBase,
+    SharingScope,
+    Status,
+    Timestamp,
+    UsageAccountingSource,
+    ensure_aware_utc,
+    utc_now,
+)
+from pydantic import (
+    AliasChoices,
+    BaseModel,
+    BeforeValidator,
+    Field,
+    JsonValue,
+    TypeAdapter,
+    field_validator,
+    model_validator,
+)
+from pydantic_ai.usage import RunUsage
+from pydantic_core import to_jsonable_python
+
+from ..exceptions import TaskExceptionType
+
+def _metadata_json_fallback(value: object) -> str:
+    """Serialize the few non-JSON-native scalars task metadata may carry.
+
+    Step by step:
+    1. accept BSON ObjectIds because callers often reference Mongo ids internally;
+    2. let `to_jsonable_python` handle native JSON, UUIDs, datetimes, and models;
+    3. reject genuinely unknown objects instead of silently stringifying runtime state.
+    """
+
+    if isinstance(value, BsonObjectId):
+        return str(value)
+    raise ValueError(f"Unsupported task metadata type: {type(value).__name__}")
+
+
+def _normalize_task_metadata(value: object) -> object:
+    """Normalize Mongo-native scalars in task metadata to JSON-safe values on READ.
+
+    Why: task metadata persisted before the JSON-safe write contract stored some
+    fields (e.g. `user_id`) as native `UUID`/BSON Binary. The strict
+    `dict[str, JsonValue]` shape rejects those on read. Running the same
+    JSON-normalization the write path uses keeps historic rows readable and makes
+    the model expose a consistent JSON-safe shape regardless of how the row was
+    stored. A no-op for already-JSON metadata; non-dicts pass through so
+    `Optional`/`None` and real type errors still surface from normal validation.
+    """
+
+    if not isinstance(value, dict):
+        return value
+    return to_jsonable_python(value, fallback=_metadata_json_fallback)
+
+
+# Canonical JSON-native shape for free-form task metadata (title/subtitle/etc. context).
+# The BeforeValidator normalizes Mongo-native scalars on read so task state,
+# relations, and costs share one strongly-typed, JSON-safe metadata contract that
+# stays readable across historic rows instead of a bare `dict`.
+TaskRelationMetadata = Annotated[
+    dict[str, JsonValue], BeforeValidator(_normalize_task_metadata)
+]
+_TASK_RELATION_METADATA_ADAPTER = TypeAdapter(TaskRelationMetadata)
+TaskCostMetadata = Annotated[
+    dict[str, JsonValue], BeforeValidator(_normalize_task_metadata)
+]
+_TASK_COST_METADATA_ADAPTER = TypeAdapter(TaskCostMetadata)
+TaskMetadata = Annotated[
+    dict[str, JsonValue], BeforeValidator(_normalize_task_metadata)
+]
+_MILLION = Decimal("1000000")
+
+
+def build_task_relation_metadata(value: object | None) -> TaskRelationMetadata:
+    """Convert relation metadata into the public JSON-safe metadata contract.
+
+    Step by step:
+    1. treat missing metadata as an empty object;
+    2. convert supported Python values into JSON-compatible primitives;
+    3. validate that the final value is a JSON object before persistence/events.
+    """
+
+    if value is None:
+        return {}
+    json_value = to_jsonable_python(
+        value,
+        fallback=_metadata_json_fallback,
+    )
+    return _TASK_RELATION_METADATA_ADAPTER.validate_python(json_value)
+
+
+def build_task_cost_metadata(value: object | None) -> TaskCostMetadata:
+    """Convert task-cost metadata into the public JSON-safe metadata contract.
+
+    Step by step:
+    1. normalize missing metadata to an empty object;
+    2. convert supported Python values into JSON-compatible values;
+    3. validate that the stored metadata remains a JSON object.
+    """
+
+    if value is None:
+        return {}
+    json_value = to_jsonable_python(
+        value,
+        fallback=_metadata_json_fallback,
+    )
+    return _TASK_COST_METADATA_ADAPTER.validate_python(json_value)
+
+
+def _zero_usd_money() -> Money:
+    """Build a fresh zero-USD money value for default cost fields."""
+
+    return Money(float_money=0, currency=Currency.USD)
+
+
+def _money_true_amount(*, money: Money) -> Decimal:
+    """Return the true decimal amount represented by `Money`.
+
+    Step by step:
+    1. read the existing `StdMoneyAmount` integer minor-unit value;
+    2. divide by 100 only once because `Money` stores cents;
+    3. return Decimal so token costs below one cent are preserved.
+    """
+
+    return Decimal(money.amount.value) / Decimal("100")
+
+
+def _convert_money_true_amount(
+    *,
+    money: Money,
+    exchange_rates: list[ExchangeRateInUsd],
+    currency: Currency,
+) -> Decimal:
+    """Convert a `Money` value and expose its true decimal amount.
+
+    Step by step:
+    1. delegate currency conversion to `Money.exchange_to(...)`;
+    2. convert the returned `Money` into a Decimal amount;
+    3. keep sub-cent math available to aggregate responses.
+    """
+
+    converted = money.exchange_to(exchange_rates=exchange_rates, currency=currency)
+    return _money_true_amount(money=converted)
+
+
+# [MOVED + RENAMED] from keble-product-report, ReportStage
+# and renamed to ReportStage -> ReportStage
+class TaskStage(str, Enum):
+    PENDING = "PENDING"
+    PROCESSING = "PROCESSING"
+    SUCCESS = "SUCCESS"
+    FAILURE = "FAILURE"
+
+    @property
+    def allow_to_start(self):
+        return self in [
+            # start from 0
+            TaskStage.PENDING,
+            # restart
+            TaskStage.PROCESSING,
+        ]
+
+
+def is_http_url(v: Any) -> bool:
+    try:
+        parsed = urlparse(str(v))
+    except (TypeError, ValueError):
+        return False
+    if parsed.scheme not in {"http", "https"}:
+        return False
+    if not parsed.netloc:
+        return False
+    return True
+
+
+# [MOVED + RENAMED] from keble-product-report, ReportBase
+# and renamed to ReportBase -> TaskBase
+class TaskBase(SchemaBase):
+    error: Optional[str] = None
+    exception_type: Optional[TaskExceptionType] = None
+
+    stage: TaskStage
+
+    # [RENAMED] report_type -> task_type
+    task_type: str  # Type of Task, similar to keble-product-report ReportType
+
+    progress_key: Optional[str]
+
+    title: Optional[str]
+    subtitle: Optional[str]
+    image: Optional[str]
+    metadata: Optional[TaskMetadata]
+
+    # [ADDED] Canonical output/report language owned by the task framework. A task
+    # is the single source of truth for the language its handler should produce
+    # output in (report copy, localized labels, child tasks), so consumers read
+    # `task.language` instead of digging it out of domain-specific metadata blobs.
+    # Optional so legacy tasks created before this field still validate and load.
+    language: Optional[Language] = None
+
+    # [RENAMED] scope -> sharing_scope
+    sharing_scope: SharingScope = SharingScope.PRIVATE
+    # Public short id for sharing (only set when task is public)
+    public_id: Optional[str] = None
+    status: Status = Status.ACTIVE
+
+    owner: str
+
+    # processing started at what timestamp
+    started_ts: Optional[Timestamp] = None
+    success_ts: Optional[Timestamp] = None
+    failure_ts: Optional[Timestamp] = None
+
+    # [RENAMED] expected_feature_token -> expected_token
+    expected_token: int  # expect to consume
+
+    # [RENAMED] consumed_feature_token -> consumed_token
+    consumed_token: int = 0  # actual consume
+
+    # [ADDED], retry mechanism
+    attempts: int = 0  # by default, attempts 0 times. Each times, it will increment further until reached maximum retried and should be marked as failure
+    timeout_mins: int = 120
+
+    # [ADDED] at 1.0.2, allow task to create subtasks
+    root_task: Optional[ObjectId] = (
+        None  # which ROOT task, in otherword, the very first task in the chain, it should belongs to itself
+    )
+    parent_task: Optional[ObjectId] = (
+        None  # which PARENT task, immediate parent task; In other word, which task created this subtask
+    )
+
+    @property
+    def unfinshed_timeout(self) -> bool:
+        before = utc_now() - timedelta(minutes=self.timeout_mins)
+        if self.created is None:
+            return False
+        c = ensure_aware_utc(self.created)
+        return before > c and self.stage in [TaskStage.PENDING, TaskStage.PROCESSING]
+
+    @property
+    def allow_to_retry(self) -> bool:
+        return self.attempts < 3 and self.stage.allow_to_start
+
+    @field_validator("image")
+    @classmethod
+    def validate_image_url(cls, v: Any) -> Optional[str]:
+        """
+        Validate image URL. If it's not a valid URL, keep it as a string.
+        """
+
+        if v is None:
+            return None
+
+        if not is_http_url(v):
+            raise keble_exceptions.ServerSideInvalidParams(
+                admin_note={"image": v},
+                alert_admin=True,
+                but_got="Image URL is not valid",
+                expected="Image URL is valid",
+                invalid_params="image",
+            )
+
+        return str(v)
+
+
+class TaskUpdate(BaseModel):
+    """Owner-editable task patch.
+
+    Only fields the owner may change post-creation belong here. Fields left
+    unset are not written (``aowner_update`` dumps with ``exclude_unset``),
+    so partial patches never clobber other columns.
+    """
+
+    sharing_scope: Optional[SharingScope] = None
+    title: Optional[str] = None
+    # [ADDED] Owner-set thumbnail. An owner may re-image a task post-creation
+    # (e.g. attach a product photo). Optional + default None so omitting it leaves
+    # the persisted image untouched; passing None explicitly clears it.
+    image: Optional[str] = None
+
+    @field_validator("image")
+    @classmethod
+    def _validate_image(cls, v: Any) -> Optional[str]:
+        """Reuse the SAME rule as creation (:meth:`TaskBase.validate_image_url`).
+
+        Keeping one validator is the single source of truth for what a stored task
+        thumbnail may be, so an owner edit can never introduce an image that task
+        creation would have rejected.
+        """
+
+        return TaskBase.validate_image_url(v)
+
+
+class TaskMongoObject(MongoObjectBase, TaskBase):
+    @property
+    def is_root_task(self) -> bool:
+        return self.parent_task is None
+
+
+class TaskMongoObjectExtended(TaskMongoObject):
+    childs: list["TaskMongoObjectExtended"] = Field(default_factory=list)
+
+
+TaskMongoObjectExtended.model_rebuild()
+
+
+class TaskPublicRef(BaseModel):
+    """Lean public-task reference: id + last-updated only.
+
+    Intention: a projection-shaped read for sitemap-scale listings of PUBLIC tasks
+    (`apublic_list_indexable`) where loading the full `TaskMongoObject` (and its
+    childs / redis-backed extras) is wasteful. Carries ONLY what a sitemap `<url>`
+    needs: the task id (route param) and `updated` (lastmod).
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    id: ObjectId = Field(
+        ...,
+        validation_alias=AliasChoices("_id", "id"),
+        pattern=r"^[0-9a-fA-F]{24}$",
+    )
+    updated: Optional[datetime] = None
+
+
+class TaskRoomResolution(SchemaBase):
+    """Resolve one requested task into its canonical root-room identity.
+
+    Step by step:
+    1. `root_task_id` is the durable workspace/session identifier;
+    2. `requested_task_id` is the task the caller asked to focus on.
+    """
+
+    root_task_id: ObjectId
+    requested_task_id: ObjectId
+
+
+class TaskRelationType(str, Enum):
+    """Supported non-tree lineage edge types inside one root-task workspace."""
+
+    MAPPED = "MAPPED"
+    REDUCED = "REDUCED"
+
+
+class TaskRelationBase(SchemaBase):
+    """Extra lineage edge that does not change canonical task parentage.
+
+    Step by step:
+    1. `root_task` scopes the relation to one task workspace;
+    2. `from_task_id` records one source task that influenced another task;
+    3. `to_task_id` records the derived task;
+    4. `relation_type` describes why the edge exists.
+    """
+
+    root_task: 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 persisted relation metadata before storing or emitting it."""
+
+        return build_task_relation_metadata(value)
+
+
+class TaskRelationCreate(TaskRelationBase):
+    """Create payload for one extra task-lineage relation row."""
+
+
+class TaskRelationUpdate(BaseModel):
+    """Update payload for mutable relation fields only."""
+
+    metadata: Optional[TaskRelationMetadata] = None
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def _normalize_metadata(
+        cls, value: object | None
+    ) -> TaskRelationMetadata | None:
+        """Normalize relation metadata updates while preserving omitted updates."""
+
+        if value is None:
+            return None
+        return build_task_relation_metadata(value)
+
+
+class TaskRelationMongoObject(MongoObjectBase, TaskRelationBase):
+    """Mongo representation of one extra task-lineage relation row."""
+
+
+class TaskCostTimeBucket(str, Enum):
+    """Supported time buckets for task-cost aggregation."""
+
+    TOTAL = "TOTAL"
+    HOUR = "HOUR"
+    DAY = "DAY"
+    WEEK = "WEEK"
+    MONTH = "MONTH"
+
+
+class TaskCostAggregateGroupBy(str, Enum):
+    """Task-cost aggregate dimensions supported by the stored row contract."""
+
+    TOTAL = "TOTAL"
+    TAG = "TAG"
+    SOURCE = "SOURCE"
+    TASK_TYPE = "TASK_TYPE"
+
+
+class TaskCostTokenRates(BaseModel):
+    """Per-million token price table used to price one Pydantic AI run.
+
+    Step by step:
+    1. store each `RunUsage` token field as a typed `Money` rate per million;
+    2. default missing rates to zero USD so callers can price only charged fields;
+    3. compute row costs with Decimal math so sub-cent token usage is not lost.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    input_tokens: Money = Field(default_factory=_zero_usd_money)
+    cache_write_tokens: Money = Field(default_factory=_zero_usd_money)
+    cache_read_tokens: Money = Field(default_factory=_zero_usd_money)
+    output_tokens: Money = Field(default_factory=_zero_usd_money)
+    input_audio_tokens: Money = Field(default_factory=_zero_usd_money)
+    cache_audio_read_tokens: Money = Field(default_factory=_zero_usd_money)
+    output_audio_tokens: Money = Field(default_factory=_zero_usd_money)
+
+    def calculate_usage_cost(
+        self,
+        *,
+        run_usage: RunUsage,
+        exchange_rates: list[ExchangeRateInUsd],
+        currency: Currency,
+    ) -> Decimal:
+        """Calculate the token-only cost for one `RunUsage` payload.
+
+        Step by step:
+        1. convert every configured per-million rate into the requested currency;
+        2. multiply each converted rate by its matching token count over one million;
+        3. return the Decimal sum without rounding to cents.
+        """
+
+        return (
+            self._calculate_token_cost(
+                tokens=run_usage.input_tokens,
+                rate=self.input_tokens,
+                exchange_rates=exchange_rates,
+                currency=currency,
+            )
+            + self._calculate_token_cost(
+                tokens=run_usage.cache_write_tokens,
+                rate=self.cache_write_tokens,
+                exchange_rates=exchange_rates,
+                currency=currency,
+            )
+            + self._calculate_token_cost(
+                tokens=run_usage.cache_read_tokens,
+                rate=self.cache_read_tokens,
+                exchange_rates=exchange_rates,
+                currency=currency,
+            )
+            + self._calculate_token_cost(
+                tokens=run_usage.output_tokens,
+                rate=self.output_tokens,
+                exchange_rates=exchange_rates,
+                currency=currency,
+            )
+            + self._calculate_token_cost(
+                tokens=run_usage.input_audio_tokens,
+                rate=self.input_audio_tokens,
+                exchange_rates=exchange_rates,
+                currency=currency,
+            )
+            + self._calculate_token_cost(
+                tokens=run_usage.cache_audio_read_tokens,
+                rate=self.cache_audio_read_tokens,
+                exchange_rates=exchange_rates,
+                currency=currency,
+            )
+            + self._calculate_token_cost(
+                tokens=run_usage.output_audio_tokens,
+                rate=self.output_audio_tokens,
+                exchange_rates=exchange_rates,
+                currency=currency,
+            )
+        )
+
+    @staticmethod
+    def _calculate_token_cost(
+        *,
+        tokens: int,
+        rate: Money,
+        exchange_rates: list[ExchangeRateInUsd],
+        currency: Currency,
+    ) -> Decimal:
+        """Calculate one token-field cost from a per-million rate.
+
+        Step by step:
+        1. convert the rate into the response currency through `Money.exchange_to`;
+        2. divide token count by one million because rates are per-million;
+        3. multiply with Decimal values to preserve sub-cent totals.
+        """
+
+        rate_amount = _convert_money_true_amount(
+            money=rate,
+            exchange_rates=exchange_rates,
+            currency=currency,
+        )
+        return rate_amount * Decimal(tokens) / _MILLION
+
+
+class TaskCostBase(SchemaBase):
+    """Durable task-cost row stored separately from `TaskMongoObject`.
+
+    Step by step:
+    1. keep cost accounting in its own collection so task state remains compact;
+    2. denormalize task scope fields required by admin cost reports;
+    3. store raw `RunUsage`, token rates, extra spend, timing, retry, and metadata.
+    """
+
+    task_id: ObjectId
+    root_task: ObjectId
+    owner: str
+    task_type: str
+    source: UsageAccountingSource | None = None
+    tags: list[str] = Field(default_factory=list)
+    run_usage: RunUsage
+    token_rates_per_million: TaskCostTokenRates = Field(
+        default_factory=TaskCostTokenRates
+    )
+    additional_cost: Money = Field(default_factory=_zero_usd_money)
+    seconds: float = Field(default=0, ge=0)
+    retry: int = Field(default=0, ge=0)
+    occurred_at: datetime = Field(default_factory=utc_now)
+    metadata: TaskCostMetadata = Field(default_factory=dict)
+
+    @field_validator("tags")
+    @classmethod
+    def _normalize_tags(cls, value: list[str]) -> list[str]:
+        """Normalize tag filters before persistence and aggregation.
+
+        Step by step:
+        1. trim whitespace from each tag;
+        2. drop empty tags because `untagged` is derived at aggregation time;
+        3. preserve first-seen order while removing duplicates.
+        """
+
+        tags: list[str] = []
+        seen: set[str] = set()
+        for tag in value:
+            normalized = tag.strip()
+            if not normalized:
+                continue
+            if normalized in seen:
+                continue
+            seen.add(normalized)
+            tags.append(normalized)
+        return tags
+
+    @field_validator("occurred_at")
+    @classmethod
+    def _normalize_occurred_at(cls, value: datetime) -> datetime:
+        """Store occurrence timestamps as timezone-aware UTC datetimes."""
+
+        return ensure_aware_utc(value)
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def _normalize_metadata(cls, value: object) -> TaskCostMetadata:
+        """Normalize cost metadata before storing it."""
+
+        return build_task_cost_metadata(value)
+
+    @property
+    def total_tokens(self) -> int:
+        """Return the complete token count represented by `run_usage`."""
+
+        return (
+            self.run_usage.input_tokens
+            + self.run_usage.cache_write_tokens
+            + self.run_usage.cache_read_tokens
+            + self.run_usage.output_tokens
+            + self.run_usage.input_audio_tokens
+            + self.run_usage.cache_audio_read_tokens
+            + self.run_usage.output_audio_tokens
+        )
+
+    def calculate_total_cost(
+        self,
+        *,
+        exchange_rates: list[ExchangeRateInUsd],
+        currency: Currency,
+    ) -> Decimal:
+        """Calculate this row's total cost in the requested currency.
+
+        Step by step:
+        1. calculate token spend from `RunUsage` and per-million rates;
+        2. convert additional non-token spend through the same exchange table;
+        3. return the Decimal sum without cent-rounding.
+        """
+
+        token_cost = self.token_rates_per_million.calculate_usage_cost(
+            run_usage=self.run_usage,
+            exchange_rates=exchange_rates,
+            currency=currency,
+        )
+        additional_cost = _convert_money_true_amount(
+            money=self.additional_cost,
+            exchange_rates=exchange_rates,
+            currency=currency,
+        )
+        return token_cost + additional_cost
+
+
+class TaskCostCreate(TaskCostBase):
+    """Create payload for one durable task-cost row.
+
+    Step by step:
+    1. accept the stored task row as the source of owner/task-type truth;
+    2. accept the caller-resolved root task id used for workspace reports;
+    3. combine usage, rates, extra cost, timing, retry, and metadata into the
+       durable cost-row contract.
+    """
+
+    @classmethod
+    def from_task_usage(
+        cls,
+        *,
+        task: TaskMongoObject,
+        root_task: ObjectId,
+        tags: list[str] | None,
+        run_usage: RunUsage,
+        source: UsageAccountingSource | None = None,
+        token_rates_per_million: TaskCostTokenRates | None = None,
+        additional_cost: Money | None = None,
+        seconds: float = 0,
+        retry: int = 0,
+        occurred_at: datetime | None = None,
+        metadata: TaskCostMetadata | None = None,
+    ) -> "TaskCostCreate":
+        """Build one create row from a persisted task and usage payload.
+
+        Step by step:
+        1. denormalize `owner` and `task_type` from the stored task row;
+        2. normalize omitted rates and additional spend to zero-USD values;
+        3. preserve caller-provided timing, retry, occurrence time, tags, and
+           metadata for later list and aggregate reporting.
+        """
+
+        return cls(
+            task_id=task.id,
+            root_task=root_task,
+            owner=task.owner,
+            task_type=task.task_type,
+            source=source,
+            tags=tags or [],
+            run_usage=run_usage,
+            token_rates_per_million=token_rates_per_million or TaskCostTokenRates(),
+            additional_cost=additional_cost or Money(
+                float_money=0,
+                currency=Currency.USD,
+            ),
+            seconds=seconds,
+            retry=retry,
+            occurred_at=occurred_at or utc_now(),
+            metadata=metadata or {},
+        )
+
+
+class TaskCostMongoObject(MongoObjectBase, TaskCostBase):
+    """Mongo representation of one task-cost row."""
+
+
+class TaskCostFilterBase(BaseModel):
+    """Canonical indexed filter contract for task-cost reads.
+
+    Step by step:
+    1. own every field shared by list and aggregate task-cost reads;
+    2. normalize tag and time filters once before CRUD receives them;
+    3. convert the shared contract into the Mongo filter used by indexed reads.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    task_id: ObjectId | None = None
+    root_task: ObjectId | None = None
+    owner: str | None = None
+    task_types: list[str] | None = None
+    sources: list[UsageAccountingSource] | None = None
+    tags: list[str] | None = None
+    start_at: datetime | None = None
+    end_at: datetime | None = None
+
+    @field_validator("sources")
+    @classmethod
+    def _normalize_sources(
+        cls,
+        value: list[UsageAccountingSource] | None,
+    ) -> list[UsageAccountingSource] | None:
+        """Normalize source filters while preserving caller order."""
+
+        if value is None:
+            return None
+        sources: list[UsageAccountingSource] = []
+        seen: set[UsageAccountingSource] = set()
+        for source in value:
+            if source in seen:
+                continue
+            sources.append(source)
+            seen.add(source)
+        return sources
+
+    @field_validator("tags")
+    @classmethod
+    def _normalize_tags(cls, value: list[str] | None) -> list[str] | None:
+        """Normalize all-tags filters while preserving omitted filters."""
+
+        if value is None:
+            return None
+        return TaskCostBase._normalize_tags(value)
+
+    @field_validator("start_at", "end_at")
+    @classmethod
+    def _normalize_time_filter(cls, value: datetime | None) -> datetime | None:
+        """Normalize optional time filters to timezone-aware UTC datetimes."""
+
+        if value is None:
+            return None
+        return ensure_aware_utc(value)
+
+    def to_mongo_filters(self) -> dict[str, Any]:
+        """Convert this canonical filter into an indexed Mongo query.
+
+        Step by step:
+        1. map optional equality filters onto stored task-cost fields;
+        2. apply `tags` with `$all` so every requested tag must be present;
+        3. apply `start_at <= occurred_at < end_at` for occurrence windows.
+        """
+
+        filters: dict[str, Any] = {}
+        if self.task_id is not None:
+            filters["task_id"] = self.task_id
+        if self.root_task is not None:
+            filters["root_task"] = self.root_task
+        if self.owner is not None:
+            filters["owner"] = self.owner
+        if self.task_types is not None:
+            filters["task_type"] = {"$in": self.task_types}
+        if self.sources is not None:
+            filters["source"] = {"$in": self.sources}
+        if self.tags:
+            filters["tags"] = {"$all": self.tags}
+        occurred_at_filter: dict[str, datetime] = {}
+        if self.start_at is not None:
+            occurred_at_filter["$gte"] = self.start_at
+        if self.end_at is not None:
+            occurred_at_filter["$lt"] = self.end_at
+        if occurred_at_filter:
+            filters["occurred_at"] = occurred_at_filter
+        return filters
+
+
+class TaskCostListRequest(TaskCostFilterBase):
+    """Paginated task-cost list request using canonical read filters.
+
+    Step by step:
+    1. inherit every filter field from `TaskCostFilterBase`;
+    2. keep list-only pagination fields on this request schema;
+    3. leave Mongo filter construction to the shared base contract.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    skip: int = Field(default=0, ge=0)
+    limit: int = Field(default=100, ge=1, le=1000)
+
+
+class TaskCostListResponse(BaseModel):
+    """Paginated task-cost list response."""
+
+    model_config = PydanticModelConfig.default()
+
+    costs: list[TaskCostMongoObject]
+    total: int
+    skip: int
+    limit: int
+
+
+class TaskCostAggregateRequest(TaskCostFilterBase):
+    """Task-cost aggregation request using canonical read filters.
+
+    Step by step:
+    1. inherit every filter field from `TaskCostFilterBase`;
+    2. choose one time bucket or `TOTAL` for the whole filtered period;
+    3. optionally fan each row into tag buckets for tag-level reporting.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    bucket: TaskCostTimeBucket = TaskCostTimeBucket.TOTAL
+    group_by: TaskCostAggregateGroupBy = TaskCostAggregateGroupBy.TOTAL
+    group_by_tag: bool = False
+    currency: Currency = Currency.USD
+
+    @model_validator(mode="after")
+    def _normalize_group_by(self) -> "TaskCostAggregateRequest":
+        """Map legacy tag grouping onto the canonical aggregate enum."""
+
+        if self.group_by_tag and self.group_by is TaskCostAggregateGroupBy.TOTAL:
+            self.group_by = TaskCostAggregateGroupBy.TAG
+        if self.group_by_tag and self.group_by is not TaskCostAggregateGroupBy.TAG:
+            raise ValueError("group_by_tag=True is only compatible with group_by=TAG")
+        self.group_by_tag = self.group_by is TaskCostAggregateGroupBy.TAG
+        return self
+
+
+class TaskCostAggregateBucket(BaseModel):
+    """One aggregated task-cost bucket.
+
+    Step by step:
+    1. identify the optional time and tag bucket;
+    2. expose precise Decimal cost in the requested currency;
+    3. include counts, token totals, seconds, and retries for diagnostics.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    start_at: datetime | None = None
+    end_at: datetime | None = None
+    tag: str | None = None
+    source: UsageAccountingSource | None = None
+    task_type: str | None = None
+    currency: Currency
+    total_cost: Decimal
+    count: int
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    seconds: float
+    retry: int
+
+    @classmethod
+    def empty(
+        cls,
+        *,
+        start_at: datetime | None,
+        end_at: datetime | None,
+        tag: str | None,
+        source: UsageAccountingSource | None,
+        task_type: str | None,
+        currency: Currency,
+    ) -> "TaskCostAggregateBucket":
+        """Open one zeroed bucket for a (time, tag, source, task_type) key.
+
+        Step by step:
+        1. fix the bucket identity (window + optional group keys + currency);
+        2. start every running total at a typed zero so `accumulate` can fold rows;
+        3. keep bucket creation on the type that owns the aggregate contract.
+        """
+
+        return cls(
+            start_at=start_at,
+            end_at=end_at,
+            tag=tag,
+            source=source,
+            task_type=task_type,
+            currency=currency,
+            total_cost=Decimal("0"),
+            count=0,
+            input_tokens=0,
+            output_tokens=0,
+            total_tokens=0,
+            seconds=0.0,
+            retry=0,
+        )
+
+    def accumulate(self, *, cost: "TaskCostBase", row_cost: Decimal) -> None:
+        """Fold one already-converted cost row into this bucket's running totals.
+
+        Step by step:
+        1. add the precomputed `row_cost` (already in the bucket currency);
+        2. advance counts, token totals, seconds, and retries from the row;
+        3. mutate in place so the bucket stays the single source of bucket math.
+        """
+
+        self.total_cost = self.total_cost + row_cost
+        self.count = self.count + 1
+        self.input_tokens = self.input_tokens + cost.run_usage.input_tokens
+        self.output_tokens = self.output_tokens + cost.run_usage.output_tokens
+        self.total_tokens = self.total_tokens + cost.total_tokens
+        self.seconds = self.seconds + cost.seconds
+        self.retry = self.retry + cost.retry
+
+
+class TaskCostAggregateResponse(BaseModel):
+    """Task-cost aggregate response for admin reporting.
+
+    Step by step:
+    1. receive already-filtered task-cost rows from CRUD;
+    2. calculate row spend in the requested currency;
+    3. group rows by requested time bucket and optional tag bucket.
+    """
+
+    model_config = PydanticModelConfig.default()
+
+    bucket: TaskCostTimeBucket
+    group_by: TaskCostAggregateGroupBy
+    group_by_tag: bool
+    currency: Currency
+    buckets: list[TaskCostAggregateBucket]
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        costs: Sequence[TaskCostBase],
+        query: TaskCostAggregateRequest,
+        exchange_rates: list[ExchangeRateInUsd],
+    ) -> "TaskCostAggregateResponse":
+        """Aggregate cost rows into the public admin response contract.
+
+        Step by step:
+        1. resolve the time and tag bucket keys for every row;
+        2. fold precise Decimal cost, counts, tokens, seconds, and retries into
+           the typed `TaskCostAggregateBucket` that owns the bucket math;
+        3. sort the typed buckets deterministically for stable API responses.
+
+        `costs` is a read-only `Sequence` so `list[TaskCostMongoObject]` from CRUD
+        is accepted without invariance errors (build never mutates the input list).
+        """
+
+        bucket_data: dict[
+            tuple[
+                datetime | None,
+                str | None,
+                UsageAccountingSource | None,
+                str | None,
+            ],
+            TaskCostAggregateBucket,
+        ] = {}
+        for cost in costs:
+            start_at = cls._bucket_start(
+                occurred_at=cost.occurred_at,
+                bucket=query.bucket,
+            )
+            row_cost = cost.calculate_total_cost(
+                exchange_rates=exchange_rates,
+                currency=query.currency,
+            )
+            for tag, source, task_type in cls._aggregate_group_values(
+                cost=cost,
+                group_by=query.group_by,
+            ):
+                key = (start_at, tag, source, task_type)
+                if key not in bucket_data:
+                    bucket_data[key] = TaskCostAggregateBucket.empty(
+                        start_at=start_at,
+                        end_at=cls._bucket_end(
+                            start_at=start_at,
+                            bucket=query.bucket,
+                        ),
+                        tag=tag,
+                        source=source,
+                        task_type=task_type,
+                        currency=query.currency,
+                    )
+                bucket_data[key].accumulate(cost=cost, row_cost=row_cost)
+        return cls(
+            bucket=query.bucket,
+            group_by=query.group_by,
+            group_by_tag=query.group_by_tag,
+            currency=query.currency,
+            buckets=[
+                bucket
+                for _, bucket in sorted(
+                    bucket_data.items(),
+                    key=lambda item: cls._bucket_sort_key(key=item[0]),
+                )
+            ],
+        )
+
+    @staticmethod
+    def _bucket_start(
+        *,
+        occurred_at: datetime,
+        bucket: TaskCostTimeBucket,
+    ) -> datetime | None:
+        """Resolve the inclusive start timestamp for one aggregate bucket."""
+
+        if bucket is TaskCostTimeBucket.TOTAL:
+            return None
+        if bucket is TaskCostTimeBucket.HOUR:
+            return occurred_at.replace(minute=0, second=0, microsecond=0)
+        if bucket is TaskCostTimeBucket.DAY:
+            return occurred_at.replace(hour=0, minute=0, second=0, microsecond=0)
+        if bucket is TaskCostTimeBucket.WEEK:
+            day_start = occurred_at.replace(
+                hour=0,
+                minute=0,
+                second=0,
+                microsecond=0,
+            )
+            return day_start - timedelta(days=day_start.weekday())
+        return occurred_at.replace(
+            day=1,
+            hour=0,
+            minute=0,
+            second=0,
+            microsecond=0,
+        )
+
+    @staticmethod
+    def _bucket_end(
+        *,
+        start_at: datetime | None,
+        bucket: TaskCostTimeBucket,
+    ) -> datetime | None:
+        """Resolve the exclusive end timestamp for one aggregate bucket."""
+
+        if start_at is None:
+            return None
+        if bucket is TaskCostTimeBucket.HOUR:
+            return start_at + timedelta(hours=1)
+        if bucket is TaskCostTimeBucket.DAY:
+            return start_at + timedelta(days=1)
+        if bucket is TaskCostTimeBucket.WEEK:
+            return start_at + timedelta(days=7)
+        if start_at.month == 12:
+            return start_at.replace(year=start_at.year + 1, month=1)
+        return start_at.replace(month=start_at.month + 1)
+
+    @staticmethod
+    def _aggregate_group_values(
+        *,
+        cost: TaskCostBase,
+        group_by: TaskCostAggregateGroupBy,
+    ) -> list[tuple[str | None, UsageAccountingSource | None, str | None]]:
+        """Resolve the aggregate grouping values for one cost row."""
+
+        if group_by is TaskCostAggregateGroupBy.TAG:
+            if len(cost.tags) == 0:
+                return [("untagged", None, None)]
+            return [(tag, None, None) for tag in cost.tags]
+        if group_by is TaskCostAggregateGroupBy.SOURCE:
+            return [(None, cost.source, None)]
+        if group_by is TaskCostAggregateGroupBy.TASK_TYPE:
+            return [(None, None, cost.task_type)]
+        return [(None, None, None)]
+
+    @staticmethod
+    def _bucket_sort_key(
+        *,
+        key: tuple[
+            datetime | None,
+            str | None,
+            UsageAccountingSource | None,
+            str | None,
+        ],
+    ) -> tuple[datetime, str, str, str]:
+        """Build a stable sort key for aggregate response buckets."""
+
+        start_at, tag, source, task_type = key
+        normalized_start_at = start_at or datetime.min.replace(tzinfo=timezone.utc)
+        return normalized_start_at, tag or "", source.value if source else "", task_type or ""
+
+
+def _flatten_task_room_graph_tasks(
+    *, task: TaskMongoObjectExtended
+) -> list["TaskRoomGraphTask"]:
+    """Flatten one task tree into prompt-safe room graph task nodes.
+
+    Step by step:
+    1. convert the current task row into the compact graph shape;
+    2. recurse through persisted child task rows in stored order;
+    3. return a stable pre-order list so prompts read parent before child.
+    """
+
+    flattened = [
+        TaskRoomGraphTask(
+            task_id=task.id,
+            parent_task_id=task.parent_task,
+            task_type=task.task_type,
+            title=task.title,
+            subtitle=task.subtitle,
+        )
+    ]
+    for child in task.childs:
+        flattened.extend(_flatten_task_room_graph_tasks(task=child))
+    return flattened
+
+
+def _summarize_task_relation_metadata(
+    *, metadata: dict[str, Any]
+) -> dict[str, str]:
+    """Convert relation metadata into compact scalar prompt strings.
+
+    Step by step:
+    1. keep simple scalar values because they are useful for agent routing;
+    2. summarize nested values by shape instead of dumping raw payloads;
+    3. truncate long scalar text so relation lines stay compact.
+    """
+
+    summary: dict[str, str] = {}
+    for key, value in metadata.items():
+        if isinstance(value, dict):
+            summary[key] = f"dict({len(value)} keys)"
+            continue
+        if isinstance(value, list):
+            summary[key] = f"list({len(value)} items)"
+            continue
+        text = "null" if value is None else str(value)
+        summary[key] = text[:117] + "..." if len(text) > 120 else text
+    return summary
+
+
+def _format_task_room_metadata_summary(*, metadata: dict[str, str]) -> str:
+    """Render compact relation metadata in stable key order.
+
+    Step by step:
+    1. return a fixed empty marker when no metadata exists;
+    2. sort metadata keys so prompt diffs remain stable;
+    3. join key/value pairs into one relation-line suffix.
+    """
+
+    if len(metadata) == 0:
+        return "{}"
+    return "{" + ", ".join(f"{key}={metadata[key]}" for key in sorted(metadata)) + "}"
+
+
+class TaskRoomGraphTask(SchemaBase):
+    """Compact task node used to explain one root-task room to agents."""
+
+    task_id: ObjectId
+    parent_task_id: ObjectId | None = None
+    task_type: str
+    title: str | None = None
+    subtitle: str | None = None
+
+    def to_prompt_line(self) -> str:
+        """Render one task node as a compact, stable prompt line.
+
+        Step by step:
+        1. expose ids and task type for deterministic agent references;
+        2. render the parent edge inline so tree structure is visible;
+        3. include only title/subtitle display text when present.
+        """
+
+        parent_text = str(self.parent_task_id) if self.parent_task_id else "ROOT"
+        parts = [
+            f"- task {self.task_id}",
+            f"type={self.task_type}",
+            f"parent={parent_text}",
+        ]
+        if self.title:
+            parts.append(f"title={self.title}")
+        if self.subtitle:
+            parts.append(f"subtitle={self.subtitle}")
+        return " | ".join(parts)
+
+
+class TaskRoomGraphRelation(SchemaBase):
+    """Compact non-tree relation edge inside one root-task room."""
+
+    from_task_id: ObjectId
+    to_task_id: ObjectId
+    relation_type: TaskRelationType
+    metadata_summary: dict[str, str] = Field(default_factory=dict)
+
+    @classmethod
+    def build(cls, *, relation: TaskRelationMongoObject) -> "TaskRoomGraphRelation":
+        """Build one prompt-safe relation edge from the persisted relation row.
+
+        Step by step:
+        1. copy stable endpoint ids and relation type unchanged;
+        2. reduce arbitrary metadata to compact scalar strings;
+        3. return a feature-agnostic edge with no grid or positioning knowledge.
+        """
+
+        return cls(
+            from_task_id=relation.from_task_id,
+            to_task_id=relation.to_task_id,
+            relation_type=relation.relation_type,
+            metadata_summary=_summarize_task_relation_metadata(
+                metadata=relation.metadata
+            ),
+        )
+
+    def to_prompt_line(self) -> str:
+        """Render one relation edge as a compact, stable prompt line.
+
+        Step by step:
+        1. expose relation type and task endpoint ids;
+        2. append reduced metadata in sorted order;
+        3. keep the output single-line for token-efficient room context.
+        """
+
+        metadata_text = _format_task_room_metadata_summary(
+            metadata=self.metadata_summary
+        )
+        return (
+            f"- relation {self.relation_type.value}: "
+            f"{self.from_task_id} -> {self.to_task_id} | metadata={metadata_text}"
+        )
+
+
+class TaskRoomGraphContext(SchemaBase):
+    """Generic task-room graph context; feature packages may enrich it externally."""
+
+    root_task_id: ObjectId
+    focused_task_id: ObjectId
+    tasks: list[TaskRoomGraphTask]
+    relations: list[TaskRoomGraphRelation]
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        root_task: TaskMongoObjectExtended,
+        focused_task_id: ObjectId,
+        relations: list[TaskRelationMongoObject],
+    ) -> "TaskRoomGraphContext":
+        """Build generic graph context from one loaded task tree and relation rows.
+
+        Step by step:
+        1. flatten the loaded root task tree into prompt-safe task nodes;
+        2. convert relation rows into compact relation edges;
+        3. validate that the focused task is present in the same root room.
+        """
+
+        tasks = _flatten_task_room_graph_tasks(task=root_task)
+        task_ids = {task.task_id for task in tasks}
+        if focused_task_id not in task_ids:
+            raise keble_exceptions.ServerSideInvalidParams(
+                admin_note={
+                    "root_task_id": root_task.id,
+                    "focused_task_id": focused_task_id,
+                },
+                alert_admin=True,
+                but_got="focused task outside loaded root room",
+                expected="focused task belongs to loaded root room",
+                invalid_params="focused_task_id",
+            )
+        return cls(
+            root_task_id=root_task.id,
+            focused_task_id=focused_task_id,
+            tasks=tasks,
+            relations=[
+                TaskRoomGraphRelation.build(relation=relation)
+                for relation in relations
+            ],
+        )
+
+    def to_prompt_text(self) -> str:
+        """Render the generic task-room graph as compact Markdown-like text.
+
+        Step by step:
+        1. identify the durable root room and current focus;
+        2. render task nodes before sidecar relation edges;
+        3. avoid feature-specific grid or positioning fields by design.
+        """
+
+        lines = [
+            "Task Room Graph Context",
+            f"Root task: {self.root_task_id}",
+            f"Focused task: {self.focused_task_id}",
+            "",
+            "Tasks:",
+        ]
+        lines.extend(task.to_prompt_line() for task in self.tasks)
+        lines.extend(["", "Relations:"])
+        if len(self.relations) == 0:
+            lines.append("- none")
+        else:
+            lines.extend(relation.to_prompt_line() for relation in self.relations)
+        return "\n".join(lines)