frontend-perception-engine 0.1.0__py3-none-any.whl

navigation/browser_use/llm.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+def get_bedrock_config() -> dict[str, Any]:
+    return {
+        "model": os.getenv("BEDROCK_MODEL", "amazon.nova-pro-v1:0"),
+        "region": os.getenv("AWS_REGION") or os.getenv("AWS_DEFAULT_REGION", "us-east-1"),
+        "aws_access_key_id": os.getenv("AWS_ACCESS_KEY_ID"),
+        "aws_secret_access_key": os.getenv("AWS_SECRET_ACCESS_KEY"),
+        "aws_session_token": os.getenv("AWS_SESSION_TOKEN"),
+        "aws_sso_auth": os.getenv("AWS_SSO_AUTH", "").lower() in {"1", "true", "yes"},
+    }
+
+
+def create_bedrock_llm(
+    model: str | None = None,
+    region: str | None = None,
+    temperature: float = 0.2,
+):
+    """Create Browser Use ChatAWSBedrock for Nova / other Bedrock models."""
+    cfg = get_bedrock_config()
+    model = model or cfg["model"]
+    region = region or cfg["region"]
+
+    try:
+        from browser_use.llm import ChatAWSBedrock
+    except ImportError as exc:
+        raise RuntimeError("browser-use is not installed") from exc
+
+    kwargs: dict[str, Any] = {
+        "model": model,
+        "aws_region": region,
+        "temperature": temperature,
+        "aws_sso_auth": cfg["aws_sso_auth"],
+    }
+    if cfg["aws_access_key_id"] and cfg["aws_secret_access_key"]:
+        kwargs["aws_access_key_id"] = cfg["aws_access_key_id"]
+        kwargs["aws_secret_access_key"] = cfg["aws_secret_access_key"]
+        if cfg["aws_session_token"]:
+            kwargs["aws_session_token"] = cfg["aws_session_token"]
+    else:
+        # Fall back to boto3 default credential chain (~/.aws/credentials, SSO, etc.)
+        try:
+            import boto3
+
+            session = boto3.Session(region_name=region)
+            if session.get_credentials() is not None:
+                kwargs["session"] = session
+                kwargs["aws_sso_auth"] = True
+        except ImportError:
+            pass
+
+    return ChatAWSBedrock(**kwargs)
+
+
+def credentials_available() -> bool:
+    cfg = get_bedrock_config()
+    if cfg["aws_sso_auth"]:
+        return True
+    if cfg["aws_access_key_id"] and cfg["aws_secret_access_key"]:
+        return True
+    try:
+        import boto3
+
+        return boto3.Session().get_credentials() is not None
+    except Exception:
+        return False

navigation/codeGraph/__init__.py

@@ -0,0 +1,4 @@
+from .factory import create_code_graph
+from .interface import GraphQueryResult, ICodeGraph
+
+__all__ = ["ICodeGraph", "GraphQueryResult", "create_code_graph"]

navigation/codeGraph/crg_impl.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable
+
+from .interface import GraphQueryResult, ICodeGraph
+
+CRGError = Exception
+_build_or_update_graph: Callable[..., dict[str, Any]] | None = None
+_query_graph: Callable[..., dict[str, Any]] | None = None
+_semantic_search_nodes: Callable[..., dict[str, Any]] | None = None
+_get_impact_radius: Callable[..., dict[str, Any]] | None = None
+_list_graph_stats: Callable[..., dict[str, Any]] | None = None
+_traverse_graph_func: Callable[..., dict[str, Any]] | None = None
+
+try:
+    from code_review_graph.tools.build import build_or_update_graph as _build_or_update_graph
+    from code_review_graph.tools.query import (
+        get_impact_radius as _get_impact_radius,
+        list_graph_stats as _list_graph_stats,
+        query_graph as _query_graph,
+        semantic_search_nodes as _semantic_search_nodes,
+        traverse_graph_func as _traverse_graph_func,
+    )
+except Exception as exc:  # pragma: no cover - defensive import
+    CRGError = type(exc)
+
+
+class CRGCodeGraph(ICodeGraph):
+    """CRG-backed code graph adapter hidden behind ICodeGraph."""
+
+    def __init__(self, repo_root: str | Path) -> None:
+        self.repo_root = str(Path(repo_root))
+
+    def _ok(self, summary: str, payload: dict[str, Any]) -> GraphQueryResult:
+        return GraphQueryResult(ok=True, source="crg", summary=summary, payload=payload)
+
+    def _err(self, action: str, exc: Exception) -> GraphQueryResult:
+        return GraphQueryResult(
+            ok=False,
+            source="crg",
+            summary=f"CRG {action} failed.",
+            error=str(exc),
+        )
+
+    @staticmethod
+    def _ensure_available() -> None:
+        required = [
+            _build_or_update_graph,
+            _query_graph,
+            _semantic_search_nodes,
+            _get_impact_radius,
+            _list_graph_stats,
+            _traverse_graph_func,
+        ]
+        if any(fn is None for fn in required):
+            raise RuntimeError("code-review-graph is not available")
+
+    def initialize(self) -> GraphQueryResult:
+        try:
+            self._ensure_available()
+            payload = _build_or_update_graph(repo_root=self.repo_root, full_rebuild=False, postprocess="minimal")
+            return self._ok(payload.get("summary", "Graph initialized"), payload)
+        except Exception as exc:
+            return self._err("initialize", exc)
+
+    def refresh(self) -> GraphQueryResult:
+        try:
+            self._ensure_available()
+            payload = _build_or_update_graph(repo_root=self.repo_root, full_rebuild=False)
+            return self._ok(payload.get("summary", "Graph refreshed"), payload)
+        except Exception as exc:
+            return self._err("refresh", exc)
+
+    def rebuild(self) -> GraphQueryResult:
+        try:
+            self._ensure_available()
+            payload = _build_or_update_graph(repo_root=self.repo_root, full_rebuild=True)
+            return self._ok(payload.get("summary", "Graph rebuilt"), payload)
+        except Exception as exc:
+            return self._err("rebuild", exc)
+
+    def search(self, query: str, *, kind: str | None = None, limit: int = 20) -> GraphQueryResult:
+        try:
+            self._ensure_available()
+            payload = _semantic_search_nodes(query=query, kind=kind, limit=limit, repo_root=self.repo_root)
+            return self._ok(payload.get("summary", f"Search for {query}"), payload)
+        except Exception as exc:
+            return self._err("search", exc)
+
+    def shortest_path(self, query: str, *, depth: int = 3, mode: str = "bfs") -> GraphQueryResult:
+        try:
+            self._ensure_available()
+            payload = _traverse_graph_func(query=query, depth=depth, mode=mode, repo_root=self.repo_root)
+            return self._ok(payload.get("summary", f"Traversal for {query}"), payload)
+        except Exception as exc:
+            return self._err("shortest_path", exc)
+
+    def get_neighbors(self, target: str, *, relation: str = "callees_of") -> GraphQueryResult:
+        try:
+            self._ensure_available()
+            payload = _query_graph(pattern=relation, target=target, repo_root=self.repo_root)
+            return self._ok(payload.get("summary", f"{relation} for {target}"), payload)
+        except Exception as exc:
+            return self._err("get_neighbors", exc)
+
+    def get_component(self, name: str) -> GraphQueryResult:
+        return self.search(name, kind="Class", limit=10)
+
+    def get_file(self, file_path: str) -> GraphQueryResult:
+        try:
+            self._ensure_available()
+            payload = _query_graph(pattern="file_summary", target=file_path, repo_root=self.repo_root)
+            return self._ok(payload.get("summary", f"File summary for {file_path}"), payload)
+        except Exception as exc:
+            return self._err("get_file", exc)
+
+    def get_route(self, changed_files: list[str] | None = None, *, max_depth: int = 2) -> GraphQueryResult:
+        try:
+            self._ensure_available()
+            payload = _get_impact_radius(
+                changed_files=changed_files,
+                max_depth=max_depth,
+                repo_root=self.repo_root,
+            )
+            return self._ok(payload.get("summary", "Impact route"), payload)
+        except Exception as exc:
+            return self._err("get_route", exc)
+
+    def query(self, query_type: str, **kwargs: Any) -> GraphQueryResult:
+        # Public, graph-agnostic API contract for current + future methods.
+        if query_type == "search":
+            return self.search(kwargs["query"], kind=kwargs.get("kind"), limit=kwargs.get("limit", 20))
+        if query_type == "neighbors":
+            return self.get_neighbors(kwargs["target"], relation=kwargs.get("relation", "callees_of"))
+        if query_type == "component":
+            return self.get_component(kwargs["name"])
+        if query_type == "file":
+            return self.get_file(kwargs["file_path"])
+        if query_type == "route":
+            return self.get_route(kwargs.get("changed_files"), max_depth=kwargs.get("max_depth", 2))
+        if query_type == "shortest_path":
+            return self.shortest_path(kwargs["query"], depth=kwargs.get("depth", 3), mode=kwargs.get("mode", "bfs"))
+        if query_type == "stats":
+            try:
+                self._ensure_available()
+                payload = _list_graph_stats(repo_root=self.repo_root)
+                return self._ok(payload.get("summary", "Graph stats"), payload)
+            except Exception as exc:
+                return self._err("stats", exc)
+
+        # Future API shape examples (defer to search/traversal today):
+        if query_type in {
+            "find_navigation_hint",
+            "find_relevant_components",
+            "find_likely_route",
+            "find_related_files",
+            "find_button_candidates",
+            "find_component_hierarchy",
+            "find_entry_point",
+        }:
+            prompt = " ".join(str(v) for v in kwargs.values())
+            return self.search(prompt, limit=10)
+
+        return GraphQueryResult(
+            ok=False,
+            source="crg",
+            summary=f"Unknown query type: {query_type}",
+            error="unknown_query_type",
+        )

navigation/codeGraph/factory.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .crg_impl import CRGCodeGraph
+from .interface import ICodeGraph
+from .null_impl import NullCodeGraph
+
+
+def create_code_graph(repo_root: str | Path, enabled: bool = True) -> ICodeGraph:
+    if not enabled:
+        return NullCodeGraph()
+    graph = CRGCodeGraph(repo_root=repo_root)
+    init = graph.initialize()
+    if not init.ok:
+        return NullCodeGraph()
+    # First-time sandbox: incremental init may succeed with 0 nodes — force full build.
+    stats = graph.query("stats")
+    node_count = (stats.payload or {}).get("node_count", 0)
+    if node_count == 0:
+        rebuild = graph.rebuild()
+        if not rebuild.ok:
+            return NullCodeGraph()
+    return graph

navigation/codeGraph/interface.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class GraphQueryResult:
+    ok: bool
+    source: str
+    summary: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+
+
+class ICodeGraph(ABC):
+    @abstractmethod
+    def initialize(self) -> GraphQueryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def refresh(self) -> GraphQueryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def rebuild(self) -> GraphQueryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def search(self, query: str, *, kind: str | None = None, limit: int = 20) -> GraphQueryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def shortest_path(self, query: str, *, depth: int = 3, mode: str = "bfs") -> GraphQueryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_neighbors(self, target: str, *, relation: str = "callees_of") -> GraphQueryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_component(self, name: str) -> GraphQueryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_file(self, file_path: str) -> GraphQueryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_route(self, changed_files: list[str] | None = None, *, max_depth: int = 2) -> GraphQueryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def query(self, query_type: str, **kwargs: Any) -> GraphQueryResult:
+        raise NotImplementedError
+
+    # Future-facing methods (designed now, can remain no-op in implementations)
+    def find_navigation_hint(self, goal: str, **kwargs: Any) -> GraphQueryResult:
+        return self.query("find_navigation_hint", goal=goal, **kwargs)
+
+    def find_relevant_components(self, intent: str, **kwargs: Any) -> GraphQueryResult:
+        return self.query("find_relevant_components", intent=intent, **kwargs)
+
+    def find_likely_route(self, intent: str, **kwargs: Any) -> GraphQueryResult:
+        return self.query("find_likely_route", intent=intent, **kwargs)
+
+    def find_related_files(self, symbol: str, **kwargs: Any) -> GraphQueryResult:
+        return self.query("find_related_files", symbol=symbol, **kwargs)
+
+    def find_button_candidates(self, label_hint: str, **kwargs: Any) -> GraphQueryResult:
+        return self.query("find_button_candidates", label_hint=label_hint, **kwargs)
+
+    def find_component_hierarchy(self, component: str, **kwargs: Any) -> GraphQueryResult:
+        return self.query("find_component_hierarchy", component=component, **kwargs)
+
+    def find_entry_point(self, feature: str, **kwargs: Any) -> GraphQueryResult:
+        return self.query("find_entry_point", feature=feature, **kwargs)

navigation/codeGraph/null_impl.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .interface import GraphQueryResult, ICodeGraph
+
+
+class NullCodeGraph(ICodeGraph):
+    """Safe fallback when CRG is unavailable."""
+
+    def _disabled(self, action: str) -> GraphQueryResult:
+        return GraphQueryResult(
+            ok=False,
+            source="null",
+            summary=f"Code graph unavailable: {action} skipped.",
+            error="code_graph_unavailable",
+        )
+
+    def initialize(self) -> GraphQueryResult:
+        return self._disabled("initialize")
+
+    def refresh(self) -> GraphQueryResult:
+        return self._disabled("refresh")
+
+    def rebuild(self) -> GraphQueryResult:
+        return self._disabled("rebuild")
+
+    def search(self, query: str, *, kind: str | None = None, limit: int = 20) -> GraphQueryResult:
+        return self._disabled("search")
+
+    def shortest_path(self, query: str, *, depth: int = 3, mode: str = "bfs") -> GraphQueryResult:
+        return self._disabled("shortest_path")
+
+    def get_neighbors(self, target: str, *, relation: str = "callees_of") -> GraphQueryResult:
+        return self._disabled("get_neighbors")
+
+    def get_component(self, name: str) -> GraphQueryResult:
+        return self._disabled("get_component")
+
+    def get_file(self, file_path: str) -> GraphQueryResult:
+        return self._disabled("get_file")
+
+    def get_route(self, changed_files: list[str] | None = None, *, max_depth: int = 2) -> GraphQueryResult:
+        return self._disabled("get_route")
+
+    def query(self, query_type: str, **kwargs: Any) -> GraphQueryResult:
+        return self._disabled(query_type)

navigation/mcp/__init__.py

@@ -0,0 +1,4 @@
+"""Frontend Perception MCP package."""
+from .server import PerceptionMCPServer, main
+
+__all__ = ["PerceptionMCPServer", "main"]

navigation/mcp/__main__.py

@@ -0,0 +1,4 @@
+from navigation.mcp.server import main
+
+if __name__ == "__main__":
+    main()

navigation/mcp/diff.py

@@ -0,0 +1,28 @@
+"""Compare two observation snapshots by scan_id."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def _blocking_issues(obs: dict[str, Any]) -> list[str]:
+    di = obs.get("dev_insights") or {}
+    summary = di.get("summary") or {}
+    return list(summary.get("blocking_issues") or [])
+
+
+def diff_observations(before: dict[str, Any], after: dict[str, Any]) -> dict[str, Any]:
+    b_block = set(_blocking_issues(before))
+    a_block = set(_blocking_issues(after))
+    b_dom = str(before.get("dom_text") or "")
+    a_dom = str(after.get("dom_text") or "")
+    excerpt_len = 500
+    return {
+        "url_before": before.get("url") or "",
+        "url_after": after.get("url") or "",
+        "url_changed": (before.get("url") or "") != (after.get("url") or ""),
+        "dom_text_changed": b_dom != a_dom,
+        "new_blocking_issues": sorted(a_block - b_block),
+        "removed_blocking_issues": sorted(b_block - a_block),
+        "dom_excerpt_before": b_dom[:excerpt_len],
+        "dom_excerpt_after": a_dom[:excerpt_len],
+    }

navigation/mcp/envelope.py

@@ -0,0 +1,50 @@
+"""Standard MCP tool response envelope (contract v1.0)."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+CONTRACT_VERSION = "1.0"
+
+
+def make_envelope(
+    tool: str,
+    *,
+    ok: bool = True,
+    session_id: str | None = None,
+    run_id: str | None = None,
+    scan_id: str | None = None,
+    url: str = "",
+    error: str | None = None,
+    degraded: list[str] | None = None,
+    data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return {
+        "contract_version": CONTRACT_VERSION,
+        "tool": tool,
+        "ok": ok,
+        "session_id": session_id,
+        "run_id": run_id,
+        "scan_id": scan_id,
+        "url": url,
+        "error": error,
+        "degraded": list(degraded or []),
+        "data": data or {},
+    }
+
+
+def envelope_json(**kwargs: Any) -> str:
+    return json.dumps(make_envelope(**kwargs), indent=2, default=str)
+
+
+def agent_summary_from_observation(obs_dict: dict[str, Any]) -> dict[str, Any]:
+    """Compact summary for host agent reasoning (no planning hints)."""
+    di = obs_dict.get("dev_insights") or {}
+    summary = di.get("summary") or {}
+    page_meta = di.get("page_meta")
+    return {
+        "blocking": summary.get("blocking_issues") or [],
+        "advisory": summary.get("advisory_issues") or [],
+        "page_meta": page_meta,
+        "degraded": list(obs_dict.get("degraded") or []) + list(di.get("degraded") or []),
+    }