feat: initial release of ARTEMIS Android Agent & Automation Platform

ARTEMIS is an autonomous multimodal Android agent and mobile UI automation
platform engineered for physical devices and emulators. It combines state-of-the-art
multimodal Vision-Language Models (VLMs) with hierarchical closed-loop planning,
resilient self-healing, and deep Android subsystem integration.

Key Features & Architectural Highlights:
- Dual-Engine Orchestration:
  * Pro Engine: Multi-agent closed-loop (Planner -> Operator -> Validator/Failure Analyzer -> Summarizer) powered by LangGraph.
  * Flash Engine: Ultra-fast reactive loop for deterministic, low-latency UI execution (<35 steps).
- Multimodal Perception & Grounding:
  * Hybrid visual screenshot grounding, real-time OCR extraction, and XML accessibility hierarchy parsing.
  * Dynamic-First, Coordinate-Fallback locating strategy for maximum resilience against UI drift.
- Autonomous Self-Healing & Diagnostics:
  * Failure analyzer and safety net for popup dismissal, crash recovery, and auto-retry.
  * Diagnostic sub-agents for log analysis, video recording inspection, and object detection.
- Unified CLI & Python SDK:
  * Rich CLI with commands: init, doctor, run, trace, batch, bench, server, and mcp.
  * Fluent Python SDK with Pydantic structured output models and package locking.
- Multi-Provider LLM Architecture:
  * Support for Google Gemini, OpenAI, Anthropic Claude, Vertex AI, OpenRouter, xAI Grok, and local endpoints (Ollama/vLLM).
  * Centralized configuration in config/artemis.jsonc.
- Native MCP & Observability:
  * Model Context Protocol (MCP) server endpoints for AI IDEs.
  * Full trace recording with before/after screenshots, action overlays, and execution replays.

Change-Id: I430b93ee2b76b54cc5a3c6eeccd15d2cf29830a1

artemis/utils/decorators.py

@@ -0,0 +1,138 @@
+# 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 asyncio
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import Any, TypeVar, cast, overload
+
+R = TypeVar("R")
+
+
+def wrap_with_callbacks_sync(
+    fn: Callable[..., R],
+    *,
+    before: Callable[..., None] | None = None,
+    on_success: Callable[[R], None] | None = None,
+    on_failure: Callable[[Exception], None] | None = None,
+    suppress_exceptions: bool = False,
+) -> Callable[..., R]:
+    @wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> R:
+        if before:
+            before()
+        try:
+            result = fn(*args, **kwargs)
+            if on_success:
+                on_success(result)
+            return result
+        except Exception as e:
+            if on_failure:
+                on_failure(e)
+            if suppress_exceptions:
+                return None  # type: ignore
+            raise
+
+    return wrapper
+
+
+def wrap_with_callbacks_async(
+    fn: Callable[..., Awaitable[R]],
+    *,
+    before: Callable[..., None] | None = None,
+    on_success: Callable[[R], None] | None = None,
+    on_failure: Callable[[Exception], None] | None = None,
+    suppress_exceptions: bool = False,
+) -> Callable[..., Awaitable[R]]:
+    @wraps(fn)
+    async def wrapper(*args: Any, **kwargs: Any) -> R:
+        if before:
+            before()
+        try:
+            result = await fn(*args, **kwargs)
+            if on_success:
+                on_success(result)
+            return result
+        except Exception as e:
+            if on_failure:
+                on_failure(e)
+            if suppress_exceptions:
+                return None  # type: ignore
+            raise
+
+    return wrapper
+
+
+@overload
+def wrap_with_callbacks(
+    fn: Callable[..., Awaitable[R]],
+    *,
+    before: Callable[[], None] | None = ...,
+    on_success: Callable[[R], None] | None = ...,
+    on_failure: Callable[[Exception], None] | None = ...,
+    suppress_exceptions: bool = ...,
+) -> Callable[..., Awaitable[R]]: ...
+
+
+@overload
+def wrap_with_callbacks(
+    *,
+    before: Callable[..., None] | None = ...,
+    on_success: Callable[[Any], None] | None = ...,
+    on_failure: Callable[[Exception], None] | None = ...,
+    suppress_exceptions: bool = ...,
+) -> Callable[[Callable[..., R]], Callable[..., R]]: ...
+
+
+@overload
+def wrap_with_callbacks(
+    fn: Callable[..., R],
+    *,
+    before: Callable[[], None] | None = ...,
+    on_success: Callable[[R], None] | None = ...,
+    on_failure: Callable[[Exception], None] | None = ...,
+    suppress_exceptions: bool = ...,
+) -> Callable[..., R]: ...
+
+
+def wrap_with_callbacks(
+    fn: Callable[..., Any] | None = None,
+    *,
+    before: Callable[[], None] | None = None,
+    on_success: Callable[[Any], None] | None = None,
+    on_failure: Callable[[Exception], None] | None = None,
+    suppress_exceptions: bool = False,
+) -> Any:
+    def decorator(func: Callable[..., Any]) -> Any:
+        if asyncio.iscoroutinefunction(func):
+            return wrap_with_callbacks_async(
+                cast(Callable[..., Awaitable[Any]], func),
+                before=before,
+                on_success=on_success,
+                on_failure=on_failure,
+                suppress_exceptions=suppress_exceptions,
+            )
+        else:
+            return wrap_with_callbacks_sync(
+                cast(Callable[..., Any], func),
+                before=before,
+                on_success=on_success,
+                on_failure=on_failure,
+                suppress_exceptions=suppress_exceptions,
+            )
+
+    if fn is None:
+        return decorator
+    else:
+        return decorator(fn)