android-midscene-automation 0.2.4 → 1.1.1

package/artemis-main/artemis/data_engine/history_reader.py

@@ -0,0 +1,142 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Read-only access to live and stored session history.
+
+DataEngine implements HistoryReader for active sessions. OfflineHistoryReader
+opens an existing database and uses the same step renderer for trace inspection.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sqlite3
+from typing import Any, Protocol, runtime_checkable
+
+from artemis.data_engine.engine import build_image_describer, friendly_step
+from artemis.data_engine.models import HistoryChunkRecord, StepRecord
+from artemis.data_engine.storage import StorageManager
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+__all__ = ["HistoryReader", "OfflineHistoryReader", "friendly_step"]
+
+
+@runtime_checkable
+class HistoryReader(Protocol):
+    """Everything the history tools need from a session's stored history."""
+
+    session_start_time: float | None
+    base_dir: Path
+    storage: StorageManager
+
+    def get_agent_friendly_steps(self) -> list[dict[str, Any]]: ...
+
+    def get_agent_friendly_steps_in_range(
+        self, start_step: int, end_step: int | None = None
+    ) -> list[dict[str, Any]]: ...
+
+    def get_agent_friendly_step(self, step_number: int) -> dict[str, Any] | None: ...
+
+    def get_step_record(self, step_number: int) -> StepRecord | None: ...
+
+    def get_step_image_path(self, step_number: int, which: str = "pre") -> Path | None: ...
+
+    def get_image_path(self, image_name: str) -> Path: ...
+
+    def get_history_chunks(self) -> list[HistoryChunkRecord]: ...
+
+
+class OfflineHistoryReader:
+    """Read-only history of one session straight from the traces database.
+
+    ``traces_dir`` is the traces root (``data_engine.db`` and ``images/`` live
+    there); ``base_dir`` resolves to the session's own directory, where its
+    notes are stored — the same layout the live ``DataEngine`` writes.
+    """
+
+    def __init__(self, db_path: str | Path, traces_dir: str | Path, session_id: Any):
+        self.global_base_dir = Path(traces_dir)
+        self.session_id = str(session_id)
+        self.storage = StorageManager(db_path, traces_dir, read_only=True)
+        self.base_dir = self.global_base_dir / self.session_id
+        self.session_start_time: float | None = None
+        try:
+            session = self.storage.get_session(self.session_id)
+            self.session_start_time = session.start_time if session else None
+        except (sqlite3.Error, ValueError) as e:
+            logger.debug(f"Session clock unavailable for {self.session_id}: {e}")
+
+    # --- Images ----------------------------------------------------------------------
+
+    def get_image_path(self, image_name: str) -> Path:
+        return self.global_base_dir / "images" / f"{image_name}.jpg"
+
+    def get_step_image_path(self, step_number: int, which: str = "pre") -> Path | None:
+        step = self.get_step_record(step_number)
+        if step is None:
+            return None
+        image_name = step.pre_image_name if which == "pre" else step.post_image_name
+        if not image_name:
+            return None
+        path = self.get_image_path(image_name)
+        return path if path.exists() else None
+
+    # --- Steps -----------------------------------------------------------------------
+
+    def _steps(self) -> list[StepRecord]:
+        return self.storage.get_steps(self.session_id) or []
+
+    def _friendly(self, step: StepRecord, describer) -> dict[str, Any]:
+        traces = self.storage.get_traces_for_step(step.step_id)
+        return friendly_step(step, traces, describer, session_start_time=self.session_start_time)
+
+    def get_agent_friendly_steps(self) -> list[dict[str, Any]]:
+        steps = self._steps()
+        describer = build_image_describer(steps)
+        return [self._friendly(step, describer) for step in steps]
+
+    def get_agent_friendly_steps_in_range(
+        self, start_step: int, end_step: int | None = None
+    ) -> list[dict[str, Any]]:
+        end_step = start_step if end_step is None else end_step
+        if start_step > end_step:
+            start_step, end_step = end_step, start_step
+        steps = self._steps()
+        describer = build_image_describer(steps)
+        return [
+            self._friendly(step, describer)
+            for step in steps
+            if start_step <= step.step_number <= end_step
+        ]
+
+    def get_agent_friendly_step(self, step_number: int) -> dict[str, Any] | None:
+        rows = self.get_agent_friendly_steps_in_range(step_number, step_number)
+        return rows[0] if rows else None
+
+    def get_step_record(self, step_number: int) -> StepRecord | None:
+        for step in self._steps():
+            if step.step_number == step_number:
+                return step
+        return None
+
+    # --- Chunks ----------------------------------------------------------------------
+
+    def get_history_chunks(self) -> list[HistoryChunkRecord]:
+        try:
+            return self.storage.get_history_chunks(self.session_id)
+        except (sqlite3.Error, ValueError) as e:
+            logger.debug(f"History chunks unavailable for {self.session_id}: {e}")
+            return []

package/artemis-main/artemis/data_engine/models.py

@@ -0,0 +1,131 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import time
+from typing import Any
+from uuid import UUID
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SessionMetadata(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    session_id: UUID | str
+    initial_goal: str
+    start_time: float = Field(default_factory=time.time)
+    end_time: float | None = None
+    status: str = "running"  # running, success, failed
+    device_info: dict[str, Any] = Field(default_factory=dict)
+    pid: int | None = None
+    video_filepath: str | None = None
+
+
+class ImageRecord(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    image_name: str  # SHA-256 hash
+    timestamp: float = Field(default_factory=time.time)
+    ocr_result: Any | None = None
+    ui_tree: Any | None = None
+    extra_metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class StepRecord(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    step_id: UUID | str
+    session_id: UUID | str
+    step_number: int
+    timestamp: float = Field(default_factory=time.time)
+    pre_image_name: str | None = None
+    post_image_name: str | None = None
+    summary: str | None = None
+    action_taken: Any | None = None
+    operator_raw_thinking: str | None = None
+    operator_native_thinking: str | None = None
+    last_execution_result: Any | None = None
+    extra_metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class HistoryChunkRecord(BaseModel):
+    """One version of a compressed history segment (history redesign §3.3/§6.1).
+
+    Identity is the step *range* ``(session_id, start_step_number,
+    end_step_number)``; the milestone ``subgoal_hash`` is label metadata only.
+    Rows are append-only: a later write for the same range carries a higher
+    ``version`` (capsule readiness, post-hoc checkpoint annotations).
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    chunk_id: UUID | str
+    session_id: UUID | str
+    start_step_id: str | None = None
+    end_step_id: str | None = None
+    start_step_number: int
+    end_step_number: int
+    source_step_ids: list[str] = Field(default_factory=list)
+    subgoal_hash: str | None = None
+    version: int = 1
+    status: str = "pending"  # pending (band ③ only), ready (bands ①②③)
+    band1: dict[str, Any] = Field(default_factory=dict)  # synopsis + structured fields
+    band2: str | None = None  # interval narrative
+    band3: str | None = None  # mechanical per-step action ledger
+    rendered_text: str | None = None
+    created_at: float = Field(default_factory=time.time)
+
+
+class TraceRecord(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    trace_id: UUID | str
+    session_id: UUID | str
+    step_id: UUID | str | None = None
+    parent_trace_id: UUID | str | None = None
+    type: str  # "agent", "tool", "log"
+    name: str
+    timestamp: float = Field(default_factory=time.time)
+    duration: float | None = None
+    status: str = "success"  # success, failed, running
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class FailedOutputRecord(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    session_id: UUID | str
+    trace_id: UUID | str
+    model_name: str
+    prompt: str
+    raw_output: str
+    error_message: str
+    timestamp: float = Field(default_factory=time.time)
+
+
+class BackgroundTaskRecord(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    task_id: str
+    session_id: UUID
+    summary: str
+    status: str = "running"  # running, completed, failed
+    start_time: float = Field(default_factory=time.time)
+    end_time: float | None = None
+    trace_id: str | None = None
+    logs: str | None = None
+
+
+class VideoRecordingRecord(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    video_id: UUID
+    session_id: UUID | None = None
+    device_id: str
+    start_time: float
+    end_time: float | None = None
+    local_video_path: str | None = None
+    status: str = "recording"
+    error: str | None = None