harmonyrun 0.4.9__py3-none-any.whl

harmonyrun/__init__.py

@@ -0,0 +1,186 @@
+"""
+HarmonyRun - A framework for automating HarmonyOS devices through LLM agents.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING
+
+# Silence ``transformers`` "None of PyTorch, TensorFlow >= 2.0, or Flax have
+# been found." advisory. ``langchain_core`` imports ``transformers`` purely to
+# pull in ``GPT2TokenizerFast``; we never run model inference through it, so
+# the advisory is noise. Must be set *before* the transitive transformers
+# import (triggered by any langchain import), hence done here at package root.
+os.environ.setdefault("TRANSFORMERS_NO_ADVISORY_WARNINGS", "1")
+
+try:
+    __version__ = version("harmonyrun")
+except PackageNotFoundError:
+    # Running from a checkout without installing the distribution (e.g. scripts).
+    __version__ = "0.0.0+unknown"
+
+# Attach a default CLILogHandler so that every consumer (CLI, SDK, tools-only)
+# gets visible output without explicit setup.  CLI may replace this via
+# ``configure_logging()``.
+_logger = logging.getLogger("harmonyrun")
+try:
+    from harmonyrun.log_handlers import CLILogHandler
+
+    _logger.addHandler(CLILogHandler())
+    _logger.setLevel(logging.INFO)
+    _logger.propagate = False
+except ImportError:
+    # e.g. ``rich`` not installed — skip; subpackages like ``hdcutils`` still import.
+    pass
+
+# Type checking imports for static analyzers
+if TYPE_CHECKING:
+    from harmonyrun.agent.harmony import HarmonyAgent
+    from harmonyrun.events import ResultEvent
+    from harmonyrun.agent.llm import load_llm
+    from harmonyrun.agent.state import StepObservation
+    from harmonyrun.events import FastAgentToolCallEvent
+    from harmonyrun.config import (
+        AgentConfig,
+        AppCardConfig,
+        ConfigManager,
+        DeviceConfig,
+        HarmonyRunConfig,
+        ExecutorConfig,
+        FastAgentConfig,
+        LLMProfile,
+        LoggingConfig,
+        ManagerConfig,
+        ToolsConfig,
+    )
+    from harmonyrun.env_keys import load_runtime_dotenv
+    from harmonyrun.hdcutils import hdc
+    from harmonyrun.mcp import create_server as create_mcp_server
+    from harmonyrun.mcp import serve_stdio as serve_mcp_stdio
+    from harmonyrun.tools.driver.base import DeviceDriver
+    from harmonyrun.tools.driver.harmony import HarmonyDriver
+    from harmonyrun.tools.driver.recording import RecordingDriver
+    from harmonyrun.tools.perception.ui.provider import StateProvider as TreeStateProvider
+    from harmonyrun.tools.perception.ui.state import UIState
+    from harmonyrun.tools.perception.ui.offline import OfflineStateProvider
+    from harmonyrun.tools.perception.processors import load_capture_bundle, load_device_info
+    from harmonyrun.config.schema.overrides import apply_overrides
+    from harmonyrun.traces.case_report import render_case_html
+    from harmonyrun.traces.folder import TraceFolder
+    from harmonyrun.tools.driver.factory import build_harmony_driver
+    from harmonyrun.batch.loading.validation import iter_json_schema_errors
+    from harmonyrun.batch.reporting import find_latest_suite_run
+    from harmonyrun.batch.loading.loader import load_test_cases
+    from harmonyrun.batch.loading.prompts import build_test_execution_goal
+    from harmonyrun.batch.models import SuiteMeta, TestCase, TestCaseResult
+    from harmonyrun.batch.execution.runner import run_test_case
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "ResultEvent": ("harmonyrun.events", "ResultEvent"),
+    "HarmonyAgent": ("harmonyrun.agent.harmony", "HarmonyAgent"),
+    "load_llm": ("harmonyrun.agent.llm", "load_llm"),
+    "StepObservation": ("harmonyrun.agent.state", "StepObservation"),
+    "FastAgentToolCallEvent": ("harmonyrun.events", "FastAgentToolCallEvent"),
+    "AgentConfig": ("harmonyrun.config", "AgentConfig"),
+    "AppCardConfig": ("harmonyrun.config", "AppCardConfig"),
+    "FastAgentConfig": ("harmonyrun.config", "FastAgentConfig"),
+    "DeviceConfig": ("harmonyrun.config", "DeviceConfig"),
+    "HarmonyRunConfig": ("harmonyrun.config", "HarmonyRunConfig"),
+    "ExecutorConfig": ("harmonyrun.config", "ExecutorConfig"),
+    "LLMProfile": ("harmonyrun.config", "LLMProfile"),
+    "LoggingConfig": ("harmonyrun.config", "LoggingConfig"),
+    "ManagerConfig": ("harmonyrun.config", "ManagerConfig"),
+    "ToolsConfig": ("harmonyrun.config", "ToolsConfig"),
+    "ConfigManager": ("harmonyrun.config", "ConfigManager"),
+    "load_runtime_dotenv": ("harmonyrun.env_keys", "load_runtime_dotenv"),
+    "hdc": ("harmonyrun.hdcutils", "hdc"),
+    "DeviceDriver": ("harmonyrun.tools", "DeviceDriver"),
+    "TreeStateProvider": ("harmonyrun.tools", "TreeStateProvider"),
+    "HarmonyDriver": ("harmonyrun.tools", "HarmonyDriver"),
+    "RecordingDriver": ("harmonyrun.tools", "RecordingDriver"),
+    "UIState": ("harmonyrun.tools.perception.ui.state", "UIState"),
+    "OfflineStateProvider": ("harmonyrun.tools.perception.ui.offline", "OfflineStateProvider"),
+    "load_capture_bundle": ("harmonyrun.tools.perception.processors", "load_capture_bundle"),
+    "load_device_info": ("harmonyrun.tools.perception.processors", "load_device_info"),
+    "apply_overrides": ("harmonyrun.config.schema.overrides", "apply_overrides"),
+    "create_mcp_server": ("harmonyrun.mcp", "create_server"),
+    "serve_mcp_stdio": ("harmonyrun.mcp", "serve_stdio"),
+    "render_case_html": ("harmonyrun.traces.case_report", "render_case_html"),
+    "TraceFolder": ("harmonyrun.traces.folder", "TraceFolder"),
+    "build_harmony_driver": ("harmonyrun.tools.driver.factory", "build_harmony_driver"),
+    "iter_json_schema_errors": ("harmonyrun.batch.loading.validation", "iter_json_schema_errors"),
+    "find_latest_suite_run": ("harmonyrun.batch.reporting", "find_latest_suite_run"),
+    "load_test_cases": ("harmonyrun.batch.loading.loader", "load_test_cases"),
+    "SuiteMeta": ("harmonyrun.batch.models", "SuiteMeta"),
+    "TestCase": ("harmonyrun.batch.models", "TestCase"),
+    "TestCaseResult": ("harmonyrun.batch.models", "TestCaseResult"),
+    "DeviceRequirements": ("harmonyrun.batch.models", "DeviceRequirements"),
+    "run_test_case": ("harmonyrun.batch.execution.runner", "run_test_case"),
+    "build_test_execution_goal": ("harmonyrun.batch.loading.prompts", "build_test_execution_goal"),
+}
+
+
+def __getattr__(name: str) -> object:
+    spec = _LAZY_EXPORTS.get(name)
+    if spec is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    mod_name, attr = spec
+    return getattr(import_module(mod_name), attr)
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals().keys(), *_LAZY_EXPORTS.keys(), "__version__"})
+
+
+# Make main components available at package level
+__all__ = [
+    # Agent
+    "HarmonyAgent",
+    "load_llm",
+    "ResultEvent",
+    # Tools / Drivers
+    "DeviceDriver",
+    "TreeStateProvider",
+    "HarmonyDriver",
+    "RecordingDriver",
+    # Configuration
+    "ConfigManager",
+    "HarmonyRunConfig",
+    "AgentConfig",
+    "FastAgentConfig",
+    "ManagerConfig",
+    "ExecutorConfig",
+    "AppCardConfig",
+    "DeviceConfig",
+    "LoggingConfig",
+    "ToolsConfig",
+    "LLMProfile",
+    # Env / secrets
+    "load_runtime_dotenv",
+    # Device enumeration / connection (async hdc client singleton)
+    "hdc",
+    # MCP
+    "create_mcp_server",
+    "serve_mcp_stdio",
+    # Agent internals (advanced users)
+    "FastAgentToolCallEvent",
+    # Perception facade (offline eval)
+    "OfflineStateProvider",
+    "load_capture_bundle",
+    "load_device_info",
+    # Config override engine
+    "apply_overrides",
+    # Traces
+    "render_case_html",
+    "TraceFolder",
+    # Driver factory
+    "build_harmony_driver",
+    # Schema validation
+    "iter_json_schema_errors",
+    # Batch helpers
+    "find_latest_suite_run",
+]

harmonyrun/__main__.py

@@ -0,0 +1,8 @@
+"""
+HarmonyRun main entry point
+"""
+
+from harmonyrun.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

harmonyrun/agent/__init__.py

@@ -0,0 +1,5 @@
+"""HarmonyRun agent layer.
+
+Event types are imported from the ``harmonyrun.events`` vocabulary leaf, not
+re-exported here.
+"""

harmonyrun/agent/events/__init__.py

@@ -0,0 +1,18 @@
+"""Agent-side event **consumption** + wiring.
+
+The event *vocabulary*, the ``EventBus`` and the stream ``WorkflowEventEmitter``
+all live in the ``harmonyrun.events`` leaf — import them from there. This
+package holds only the agent-layer consumer side:
+
+- ``handler``         — ``ConsoleSink``, the stream-transport console renderer.
+- ``render_registry`` — the type→renderer dispatch table that each sub-agent's
+  ``_render`` module self-registers into (IoC; the registry imports no concrete
+  event class).
+- ``_render``         — coordination + ``traces`` device-event renderers.
+"""
+
+from __future__ import annotations
+
+from harmonyrun.agent.events.handler import ConsoleSink
+
+__all__ = ["ConsoleSink"]

harmonyrun/agent/events/_render.py

@@ -0,0 +1,258 @@
+"""Log renderers for every workflow event, centralized in one module.
+
+The events themselves live in the ``harmonyrun.events`` vocabulary leaf; their
+*consumer-side* CLI rendering belongs here in the agent layer. Renderers used to
+be scattered across each sub-agent package ("co-located with the event"), but
+once the event vocabulary sank to the ``events/`` leaf that justification went
+away — the per-agent ``_render`` modules imported only the leaf event classes
+plus the registry, never their own package. So all renderers now live here and
+register on this module's import (triggered by ``handler.py``), which also makes
+registration deterministic instead of depending on which sub-agent packages got
+imported first.
+
+Grouping below is by *publisher* (orchestrator/coordination + traces, then each
+sub-agent's own telemetry). This module imports only ``harmonyrun.events`` event
+classes and ``render_registry`` — never a sub-agent package — so the IoC rule
+(registry/ConsoleSink never reach up into ``fast_agent``/``manager``/``executor``)
+still holds.
+
+Rendering strings are byte-identical to the historical isinstance chain — do not
+reword without updating ``tests/unit/agent/events/test_handler_render.py`` and
+running an on-device smoke.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from harmonyrun.agent.events.render_registry import register
+from harmonyrun.events import (
+    ActiveInterventionEvent,
+    ExecutorActionEvent,
+    ExecutorActionResultEvent,
+    ExecutorResponseEvent,
+    ExecutorResultEvent,
+    FastAgentEndEvent,
+    FastAgentExecuteEvent,
+    FastAgentInputEvent,
+    FastAgentOutputEvent,
+    FastAgentResponseEvent,
+    FastAgentResultEvent,
+    FastAgentToolCallEvent,
+    FinalizeEvent,
+    ManagerContextEvent,
+    ManagerPlanDetailsEvent,
+    ManagerResponseEvent,
+    RecordUIStateEvent,
+    ScreenshotEvent,
+    StructuredFailureEvent,
+)
+
+logger = logging.getLogger("harmonyrun")
+
+
+# ---- coordination (orchestrator-published) + traces/device ----
+
+
+def _render_screenshot(event: ScreenshotEvent) -> None:
+    logger.debug("📸 Taking screenshot...")
+
+
+def _render_record_ui_state(event: RecordUIStateEvent) -> None:
+    logger.debug("✏️ Recording UI state")
+
+
+def _render_executor_result(event: ExecutorResultEvent) -> None:
+    logger.debug("Step complete", extra={"color": "magenta"})
+
+
+def _render_fast_agent_execute(event: FastAgentExecuteEvent) -> None:
+    logger.debug("🔧 Starting task execution...", extra={"color": "magenta"})
+
+
+def _render_fast_agent_result(event: FastAgentResultEvent) -> None:
+    if event.success:
+        logger.debug(f"Task result: {event.reason}", extra={"color": "green"})
+    else:
+        logger.debug(f"Task failed: {event.reason}", extra={"color": "red"})
+
+
+def _render_finalize(event: FinalizeEvent) -> None:
+    if event.success:
+        logger.info(f"🎉 Goal achieved: {event.reason}", extra={"color": "green"})
+    else:
+        logger.info(f"❌ Goal failed: {event.reason}", extra={"color": "red"})
+
+
+# ---- fast_agent telemetry ----
+
+
+def _render_input(event: FastAgentInputEvent) -> None:
+    logger.debug("💬 Task input received...")
+
+
+def _render_response(event: FastAgentResponseEvent) -> None:
+    logger.debug("FastAgent response", extra={"color": "magenta"})
+    if event.thought:
+        preview = (
+            event.thought[:150] + "..."
+            if len(event.thought) > 150
+            else event.thought
+        )
+        logger.debug(f"🧠 Thinking: {preview}", extra={"color": "cyan"})
+    if event.code:
+        logger.debug("💻 Executing action code", extra={"color": "yellow"})
+        logger.debug(f"{event.code}", extra={"color": "blue"})
+    usage_line = event.usage.summary_line() if event.usage else ""
+    if usage_line:
+        logger.debug(
+            f"📊 fast_agent tokens — {usage_line}",
+            extra={"color": "cyan"},
+        )
+
+
+def _render_tool_call(event: FastAgentToolCallEvent) -> None:
+    logger.debug("⚡ Executing tool calls...", extra={"color": "yellow"})
+
+
+def _render_output(event: FastAgentOutputEvent) -> None:
+    if event.output:
+        output = str(event.output)
+        preview = output[:100] + "..." if len(output) > 100 else output
+        if "Error" in output or "Exception" in output:
+            logger.debug(f"❌ Action error: {preview}", extra={"color": "red"})
+        else:
+            logger.debug(f"⚡ Action result: {preview}", extra={"color": "green"})
+
+
+def _render_end(event: FastAgentEndEvent) -> None:
+    status = "done" if event.success else "failed"
+    color = "green" if event.success else "red"
+    logger.debug(
+        f"■ {status}: {event.reason} ({event.tool_call_count} runs)",
+        extra={"color": color},
+    )
+
+
+def _render_structured_failure(event: StructuredFailureEvent) -> None:
+    logger.warning(
+        f"🧩 Structured failure [{event.mode}/{event.severity}]: "
+        f"{event.conclusion} (target={event.target_ref})",
+        extra={"color": "red"},
+    )
+
+
+def _render_active_intervention(event: ActiveInterventionEvent) -> None:
+    logger.warning(
+        f"🛠️ Active intervention [{event.kind}] → {event.target} "
+        f"(#{event.count}): {event.reason}",
+        extra={"color": "yellow"},
+    )
+
+
+# ---- manager telemetry ----
+
+
+def _render_context(event: ManagerContextEvent) -> None:
+    logger.debug("🧠 Manager preparing context...")
+
+
+def _render_manager_response(event: ManagerResponseEvent) -> None:
+    logger.debug("📥 Manager received LLM response")
+    usage_line = event.usage.summary_line() if event.usage else ""
+    if usage_line:
+        logger.debug(f"📊 manager tokens — {usage_line}", extra={"color": "cyan"})
+
+
+def _render_plan_details(event: ManagerPlanDetailsEvent) -> None:
+    if event.thought:
+        preview = (
+            event.thought[:120] + "..."
+            if len(event.thought) > 120
+            else event.thought
+        )
+        logger.debug(f"💭 Thought: {preview}", extra={"color": "cyan"})
+    if event.subgoal:
+        preview = (
+            event.subgoal[:150] + "..."
+            if len(event.subgoal) > 150
+            else event.subgoal
+        )
+        logger.debug(f"📋 Next step: {preview}", extra={"color": "yellow"})
+    if event.answer:
+        preview = (
+            event.answer[:200] + "..."
+            if len(event.answer) > 200
+            else event.answer
+        )
+        logger.debug(f"💬 Answer: {preview}", extra={"color": "green"})
+    if event.plan:
+        logger.debug(f"▸ {event.plan}", extra={"color": "yellow"})
+    if event.memory_update:
+        mem = event.memory_update
+        mem_preview = mem[:100] + "..." if len(mem) > 100 else mem
+        logger.debug(
+            f"🧠 Memory: {mem_preview}",
+            extra={"color": "cyan"},
+        )
+
+
+# ---- executor telemetry ----
+# ``ExecutorContextEvent`` is intentionally NOT registered — the former
+# ``EventHandler`` had no branch for it, so it falls through to the generic
+# fallback exactly as before.
+
+
+def _render_executor_response(event: ExecutorResponseEvent) -> None:
+    usage_line = event.usage.summary_line() if event.usage else ""
+    if usage_line:
+        logger.debug(
+            f"📊 executor tokens — {usage_line}",
+            extra={"color": "cyan"},
+        )
+
+
+def _render_action(event: ExecutorActionEvent) -> None:
+    if event.description:
+        logger.debug(f"🎯 Action: {event.description}", extra={"color": "yellow"})
+    if event.thought:
+        preview = (
+            event.thought[:120] + "..."
+            if len(event.thought) > 120
+            else event.thought
+        )
+        logger.debug(f"💭 Reasoning: {preview}", extra={"color": "cyan"})
+
+
+def _render_action_result(event: ExecutorActionResultEvent) -> None:
+    if event.success:
+        logger.debug(f"✅ {event.summary}", extra={"color": "green"})
+    else:
+        error_msg = event.error or "Unknown error"
+        logger.debug(f"❌ {event.summary} ({error_msg})", extra={"color": "red"})
+
+
+# ---- registration (centralized; handler.py's import triggers all of it) ----
+
+register(ScreenshotEvent, _render_screenshot)
+register(RecordUIStateEvent, _render_record_ui_state)
+register(ExecutorResultEvent, _render_executor_result)
+register(FastAgentExecuteEvent, _render_fast_agent_execute)
+register(FastAgentResultEvent, _render_fast_agent_result)
+register(FinalizeEvent, _render_finalize)
+
+register(FastAgentInputEvent, _render_input)
+register(FastAgentResponseEvent, _render_response)
+register(FastAgentToolCallEvent, _render_tool_call)
+register(FastAgentOutputEvent, _render_output)
+register(FastAgentEndEvent, _render_end)
+register(StructuredFailureEvent, _render_structured_failure)
+register(ActiveInterventionEvent, _render_active_intervention)
+
+register(ManagerContextEvent, _render_context)
+register(ManagerResponseEvent, _render_manager_response)
+register(ManagerPlanDetailsEvent, _render_plan_details)
+
+register(ExecutorResponseEvent, _render_executor_response)
+register(ExecutorActionEvent, _render_action)
+register(ExecutorActionResultEvent, _render_action_result)

harmonyrun/agent/events/handler.py

@@ -0,0 +1,36 @@
+"""Workflow event → logger translator shared by CLI and batch runner.
+
+Pure dispatch: every renderer is centralized in ``_render.py`` (imported here
+for its registration side-effect) and registered against an exact event type.
+``handle`` just looks the renderer up and applies a generic fallback for unknown
+events — so this module references no concrete event type and no sub-agent
+package (the registry holds only ``type -> callable``).
+
+Renderers emit ``logging`` calls with ``extra`` params (color, etc.); the
+attached ``logging.Handler`` (typically CLILogHandler) does the rendering.
+"""
+
+import logging
+
+# Import side-effect: registers every renderer (coordination/traces + all
+# sub-agent telemetry, centralized in ``_render``).
+import harmonyrun.agent.events._render  # noqa: F401
+from harmonyrun.agent.events.render_registry import render
+
+logger = logging.getLogger("harmonyrun")
+
+
+class ConsoleSink:
+    """Console-rendering sink (consumption ④) for the LangGraph stream transport.
+
+    Despite the name, this sink writes **no** console output itself — it only
+    translates workflow events into ``logging`` records (with ``extra`` params
+    such as ``color``) via the render registry, and the attached cli-layer
+    ``CLILogHandler`` does the actual terminal rendering. No UI state tracking.
+    The CLI / batch runners consume ``AgentHandle.stream_events()`` and feed each
+    event to :meth:`handle`.
+    """
+
+    def handle(self, event) -> None:
+        if not render(event):
+            logger.debug(f"🔄 {event.__class__.__name__}")

harmonyrun/agent/events/render_registry.py

@@ -0,0 +1,41 @@
+"""Event → log-rendering dispatch registry (pure infra, knows no event types).
+
+``EventHandler`` used to be a ~150-line ``isinstance`` chain that imported the
+three sub-agents' telemetry events — an inversion (events/ is a shared *leaf*
+infra layer, yet reached *up* into ``fast_agent`` / ``manager`` / ``executor``).
+
+This registry inverts that control: all renderers live in ``_render.py`` (which
+imports only ``harmonyrun.events`` event classes — never a sub-agent package)
+and self-register here on import. The registry itself holds only
+``type -> callable`` and imports no concrete event class, so neither it nor
+``handler.py`` references any sub-agent package.
+
+Lookup is exact-type (events are leaf classes; no subclass fan-out is needed),
+matching the old ``isinstance`` chain's first-match-wins behaviour.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+EventRenderer = Callable[[Any], None]
+
+_RENDERERS: dict[type, EventRenderer] = {}
+
+
+def register(event_type: type, renderer: EventRenderer) -> None:
+    """Register the renderer for an exact event type (last registration wins)."""
+    _RENDERERS[event_type] = renderer
+
+
+def render(event: Any) -> bool:
+    """Render ``event`` via its registered renderer.
+
+    Returns ``True`` if a renderer handled it, ``False`` otherwise (caller
+    applies the generic fallback). Exact-type lookup only.
+    """
+    renderer = _RENDERERS.get(type(event))
+    if renderer is None:
+        return False
+    renderer(event)
+    return True

harmonyrun/agent/execution/__init__.py

@@ -0,0 +1,27 @@
+"""Execution scaffolding shared by every agent that drives a LangGraph run.
+
+Two public concepts live here:
+
+- ``BaseExecutionAgent`` — the thin base class for ManagerAgent /
+  ExecutorAgent / FastAgent. Consolidates the cross-cutting code every
+  per-LLM-call agent needs: device-state capture, UI mirroring into the
+  shared state, hilog event draining, screenshot annotation, app-card
+  refresh, and usage recording. Anti-loop detection (``anti_loop`` /
+  ``thresholds``) is part of this scaffolding.
+- ``AgentHandle`` — the awaitable wrapper every agent's ``run()`` returns
+  over a compiled LangGraph (``await handle`` / ``handle.stream_events()``).
+"""
+
+from harmonyrun.agent.execution.base_agent import (
+    BaseExecutionAgent,
+    build_record_ui_state_event,
+)
+from harmonyrun.agent.execution.formatting import compact_args_repr
+from harmonyrun.agent.execution.handle import AgentHandle
+
+__all__ = [
+    "BaseExecutionAgent",
+    "AgentHandle",
+    "compact_args_repr",
+    "build_record_ui_state_event",
+]