khoj 1.41.1.dev43__py3-none-any.whl → 1.41.1.dev90__py3-none-any.whl

khoj/processor/operator/operate_browser.py

@@ -0,0 +1,152 @@
+import asyncio
+import json
+import logging
+import os
+from typing import Callable, List, Optional
+
+import requests
+
+from khoj.database.adapters import AgentAdapters, ConversationAdapters
+from khoj.database.models import Agent, ChatModel, KhojUser
+from khoj.processor.operator.operator_actions import *
+from khoj.processor.operator.operator_agent_anthropic import AnthropicOperatorAgent
+from khoj.processor.operator.operator_agent_base import OperatorAgent
+from khoj.processor.operator.operator_agent_binary import BinaryOperatorAgent
+from khoj.processor.operator.operator_agent_openai import OpenAIOperatorAgent
+from khoj.processor.operator.operator_environment_base import EnvStepResult
+from khoj.processor.operator.operator_environment_browser import BrowserEnvironment
+from khoj.routers.helpers import ChatEvent
+from khoj.utils.helpers import timer
+from khoj.utils.rawconfig import LocationData
+
+logger = logging.getLogger(__name__)
+
+
+# --- Browser Operator Function ---
+async def operate_browser(
+    query: str,
+    user: KhojUser,
+    conversation_log: dict,
+    location_data: LocationData,
+    send_status_func: Optional[Callable] = None,
+    query_images: Optional[List[str]] = None,  # TODO: Handle query images
+    agent: Agent = None,
+    query_files: str = None,  # TODO: Handle query files
+    cancellation_event: Optional[asyncio.Event] = None,
+    tracer: dict = {},
+):
+    response, summary_message, user_input_message = None, None, None
+    environment: Optional[BrowserEnvironment] = None
+
+    # Get the agent chat model
+    agent_chat_model = await AgentAdapters.aget_agent_chat_model(agent, user) if agent else None
+    reasoning_model: ChatModel = await ConversationAdapters.aget_default_chat_model(user, agent_chat_model)
+    if not reasoning_model or not reasoning_model.vision_enabled:
+        reasoning_model = await ConversationAdapters.aget_vision_enabled_config()
+    if not reasoning_model:
+        raise ValueError(f"No vision enabled chat model found. Configure a vision chat model to operate browser.")
+
+    # Initialize Agent
+    max_iterations = int(os.getenv("KHOJ_OPERATOR_ITERATIONS", 40))
+    operator_agent: OperatorAgent
+    if reasoning_model.name.startswith("gpt-4o"):
+        operator_agent = OpenAIOperatorAgent(query, reasoning_model, max_iterations, tracer)
+    elif reasoning_model.name.startswith("claude-3-7-sonnet"):
+        operator_agent = AnthropicOperatorAgent(query, reasoning_model, max_iterations, tracer)
+    else:
+        grounding_model_name = "ui-tars-1.5"
+        grounding_model = await ConversationAdapters.aget_chat_model_by_name(grounding_model_name)
+        if (
+            not grounding_model
+            or not grounding_model.vision_enabled
+            or not grounding_model.model_type == ChatModel.ModelType.OPENAI
+        ):
+            raise ValueError("No supported visual grounding model for binary operator agent found.")
+        operator_agent = BinaryOperatorAgent(query, reasoning_model, grounding_model, max_iterations, tracer)
+
+    # Initialize Environment
+    if send_status_func:
+        async for event in send_status_func(f"**Launching Browser**"):
+            yield {ChatEvent.STATUS: event}
+    environment = BrowserEnvironment()
+    await environment.start(width=1024, height=768)
+
+    # Start Operator Loop
+    try:
+        summarize_prompt = f"Use the results of our research to provide a comprehensive, self-contained answer for the target query:\n{query}."
+        task_completed = False
+        iterations = 0
+
+        with timer(f"Operating browser with {reasoning_model.model_type} {reasoning_model.name}", logger):
+            while iterations < max_iterations and not task_completed:
+                if cancellation_event and cancellation_event.is_set():
+                    logger.debug(f"Browser operator cancelled by client disconnect")
+                    break
+
+                iterations += 1
+
+                # 1. Get current environment state
+                browser_state = await environment.get_state()
+
+                # 2. Agent decides action(s)
+                agent_result = await operator_agent.act(browser_state)
+
+                # 3. Execute actions in the environment
+                env_steps: List[EnvStepResult] = []
+                for action in agent_result.actions:
+                    if cancellation_event and cancellation_event.is_set():
+                        logger.debug(f"Browser operator cancelled by client disconnect")
+                        break
+                    # Handle request for user action and break the loop
+                    if isinstance(action, RequestUserAction):
+                        user_input_message = action.request
+                        if send_status_func:
+                            async for event in send_status_func(f"**Requesting User Input**:\n{action.request}"):
+                                yield {ChatEvent.STATUS: event}
+                        break
+                    env_step = await environment.step(action)
+                    env_steps.append(env_step)
+
+                # Render status update
+                latest_screenshot = f"data:image/webp;base64,{env_steps[-1].screenshot_base64 if env_steps else browser_state.screenshot}"
+                render_payload = agent_result.rendered_response
+                render_payload["image"] = latest_screenshot
+                render_content = f"**Action**: {json.dumps(render_payload)}"
+                if send_status_func:
+                    async for event in send_status_func(f"**Operating Browser**:\n{render_content}"):
+                        yield {ChatEvent.STATUS: event}
+
+                # Check if termination conditions are met
+                task_completed = not agent_result.actions  # No actions requested by agent
+                trigger_iteration_limit = iterations == max_iterations
+                if user_input_message:
+                    logger.info(f"User input requested: {user_input_message}")
+                    break
+                if task_completed or trigger_iteration_limit:
+                    # Summarize results of operator run on last iteration
+                    operator_agent.add_action_results(env_steps, agent_result)
+                    summary_message = await operator_agent.summarize(summarize_prompt, browser_state)
+                    logger.info(f"Task completed: {task_completed}, Iteration limit: {trigger_iteration_limit}")
+                    break
+
+                # 4. Update agent on the results of its action on the environment
+                operator_agent.add_action_results(env_steps, agent_result)
+
+            # Determine final response message
+            if user_input_message:
+                response = user_input_message
+            elif task_completed:
+                response = summary_message
+            else:  # Hit iteration limit
+                response = f"Operator hit iteration limit ({max_iterations}). If the results seem incomplete try again, assign a smaller task or try a different approach.\nThese were the results till now:\n{summary_message}"
+    finally:
+        if environment and not user_input_message:  # Don't close browser if user input required
+            await environment.close()
+        if operator_agent:
+            operator_agent.reset()
+
+    yield {
+        "query": query,
+        "result": user_input_message or response,
+        "webpages": [{"link": url, "snippet": ""} for url in environment.visited_urls],
+    }

khoj/processor/operator/operator_actions.py

@@ -0,0 +1,149 @@
+# --- Standardized Action Models ---
+from typing import List, Literal, Optional, Union
+
+from pydantic import BaseModel
+
+
+class Point(BaseModel):
+    x: float
+    y: float
+
+
+class BaseAction(BaseModel):
+    type: str
+
+
+class ClickAction(BaseAction):
+    type: Literal["click"] = "click"
+    x: float
+    y: float
+    button: Literal["left", "right", "middle", "wheel"] = "left"
+    modifiers: str = None
+
+
+class DoubleClickAction(BaseAction):
+    type: Literal["double_click"] = "double_click"
+    x: float
+    y: float
+
+
+class TripleClickAction(BaseAction):
+    type: Literal["triple_click"] = "triple_click"
+    x: float
+    y: float
+
+
+class ScrollAction(BaseAction):
+    type: Literal["scroll"] = "scroll"
+    x: Optional[float] = None
+    y: Optional[float] = None
+    scroll_x: Optional[float] = None
+    scroll_y: Optional[float] = None
+    scroll_direction: Optional[Literal["up", "down", "left", "right"]] = None
+    scroll_amount: Optional[float] = 2.0
+
+
+class KeypressAction(BaseAction):
+    type: Literal["keypress"] = "keypress"
+    keys: List[str]  # Standardized on list of keys
+
+
+class TypeAction(BaseAction):
+    type: Literal["type"] = "type"
+    text: str
+
+
+class WaitAction(BaseAction):
+    type: Literal["wait"] = "wait"
+    duration: float = 1.0
+
+
+class ScreenshotAction(BaseAction):
+    type: Literal["screenshot"] = "screenshot"
+
+
+class MoveAction(BaseAction):
+    type: Literal["move"] = "move"
+    x: float
+    y: float
+
+
+class DragAction(BaseAction):
+    type: Literal["drag"] = "drag"
+    path: List[Point]
+
+
+class MouseDownAction(BaseAction):
+    type: Literal["mouse_down"] = "mouse_down"
+    button: Literal["left", "right", "middle"] = "left"
+
+
+class MouseUpAction(BaseAction):
+    type: Literal["mouse_up"] = "mouse_up"
+    button: Literal["left", "right", "middle"] = "left"
+
+
+class HoldKeyAction(BaseAction):
+    type: Literal["hold_key"] = "hold_key"
+    text: str  # xdotool style key combination string
+    duration: float = 1.0
+
+
+class KeyUpAction(BaseAction):
+    type: Literal["key_up"] = "key_up"
+    key: str
+
+
+class KeyDownAction(BaseAction):
+    type: Literal["key_down"] = "key_down"
+    key: str
+
+
+class CursorPositionAction(BaseAction):
+    type: Literal["cursor_position"] = "cursor_position"
+
+
+class GotoAction(BaseAction):
+    type: Literal["goto"] = "goto"
+    url: str
+
+
+class BackAction(BaseAction):
+    type: Literal["back"] = "back"
+
+
+class RequestUserAction(BaseAction):
+    """Request user action to confirm or provide input."""
+
+    type: Literal["request_user"] = "request_user"
+    request: str
+
+
+class NoopAction(BaseAction):
+    """No operation action."""
+
+    type: Literal["noop"] = "noop"
+
+
+OperatorAction = Union[
+    ClickAction,
+    DoubleClickAction,
+    TripleClickAction,
+    ScrollAction,
+    KeypressAction,
+    TypeAction,
+    WaitAction,
+    ScreenshotAction,
+    MoveAction,
+    DragAction,
+    MouseDownAction,
+    MouseUpAction,
+    HoldKeyAction,
+    KeyDownAction,
+    KeyUpAction,
+    CursorPositionAction,
+    GotoAction,
+    BackAction,
+    RequestUserAction,
+    NoopAction,
+]

khoj/processor/operator/operator_agent_anthropic.py

@@ -0,0 +1,383 @@
+import ast
+import json
+import logging
+from copy import deepcopy
+from datetime import datetime
+from typing import Any, List, Optional, cast
+
+from anthropic.types.beta import BetaContentBlock
+
+from khoj.processor.operator.operator_actions import *
+from khoj.processor.operator.operator_agent_base import (
+    AgentActResult,
+    AgentMessage,
+    OperatorAgent,
+)
+from khoj.processor.operator.operator_environment_base import EnvState, EnvStepResult
+from khoj.utils.helpers import get_anthropic_async_client, is_none_or_empty
+
+logger = logging.getLogger(__name__)
+
+
+# --- Anthropic Operator Agent ---
+class AnthropicOperatorAgent(OperatorAgent):
+    async def act(self, current_state: EnvState) -> AgentActResult:
+        client = get_anthropic_async_client(
+            self.vision_model.ai_model_api.api_key, self.vision_model.ai_model_api.api_base_url
+        )
+        tool_version = "2025-01-24"
+        betas = [f"computer-use-{tool_version}", "token-efficient-tools-2025-02-19"]
+        temperature = 1.0
+        actions: List[OperatorAction] = []
+        action_results: List[dict] = []
+        self._commit_trace()  # Commit trace before next action
+
+        system_prompt = f"""<SYSTEM_CAPABILITY>
+* You are Khoj, a smart web browser operating assistant. You help the users accomplish tasks using a web browser.
+* You operate a Chromium browser using Playwright via the 'computer' tool.
+* You cannot access the OS or filesystem.
+* You can interact with the web browser to perform tasks like clicking, typing, scrolling, and more.
+* You can use the additional back() and goto() helper functions to ease navigating the browser. If you see nothing, try goto duckduckgo.com
+* When viewing a webpage it can be helpful to zoom out so that you can see everything on the page. Either that, or make sure you scroll down to see everything before deciding something isn't available.
+* When using your computer function calls, they take a while to run and send back to you. Where possible/feasible, try to chain multiple of these calls all into one function calls request.
+* Perform web searches using DuckDuckGo. Don't use Google even if requested as the query will fail.
+* The current date is {datetime.today().strftime('%A, %B %-d, %Y')}.
+* The current URL is {current_state.url}.
+</SYSTEM_CAPABILITY>
+
+<IMPORTANT>
+* You are allowed upto {self.max_iterations} iterations to complete the task.
+* Do not loop on wait, screenshot for too many turns without taking any action.
+* After initialization if the browser is blank, enter a website URL using the goto() function instead of waiting
+</IMPORTANT>
+"""
+        if is_none_or_empty(self.messages):
+            self.messages = [AgentMessage(role="user", content=self.query)]
+
+        tools = [
+            {
+                "type": f"computer_20250124",
+                "name": "computer",
+                "display_width_px": 1024,
+                "display_height_px": 768,
+            },  # TODO: Get from env
+            {
+                "name": "back",
+                "description": "Go back to the previous page.",
+                "input_schema": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "goto",
+                "description": "Go to a specific URL.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {"url": {"type": "string", "description": "Fully qualified URL to navigate to."}},
+                    "required": ["url"],
+                },
+            },
+        ]
+
+        thinking: dict[str, str | int] = {"type": "disabled"}
+        if self.vision_model.name.startswith("claude-3-7"):
+            thinking = {"type": "enabled", "budget_tokens": 1024}
+
+        messages_for_api = self._format_message_for_api(self.messages)
+        response = await client.beta.messages.create(
+            messages=messages_for_api,
+            model=self.vision_model.name,
+            system=system_prompt,
+            tools=tools,
+            betas=betas,
+            thinking=thinking,
+            max_tokens=4096,  # TODO: Make configurable?
+            temperature=temperature,
+        )
+
+        logger.debug(f"Anthropic response: {response.model_dump_json()}")
+        self.messages.append(AgentMessage(role="assistant", content=response.content))
+        rendered_response = self._render_response(response.content, current_state.screenshot)
+
+        for block in response.content:
+            if block.type == "tool_use":
+                content = None
+                is_error = False
+
+                action_to_run: Optional[OperatorAction] = None
+                tool_input = block.input
+                tool_name = block.input.get("action") if block.name == "computer" else block.name
+                tool_use_id = block.id
+
+                try:
+                    if tool_name == "mouse_move":
+                        coord = self.get_coordinates(tool_input)
+                        if coord:
+                            action_to_run = MoveAction(x=coord[0], y=coord[1])
+                    elif tool_name == "left_click":
+                        coord = self.get_coordinates(tool_input)
+                        if coord:
+                            action_to_run = ClickAction(
+                                x=coord[0], y=coord[1], button="left", modifier=tool_input.get("text")
+                            )
+                    elif tool_name == "right_click":
+                        coord = self.get_coordinates(tool_input)
+                        if coord:
+                            action_to_run = ClickAction(x=coord[0], y=coord[1], button="right")
+                    elif tool_name == "middle_click":
+                        coord = self.get_coordinates(tool_input)
+                        if coord:
+                            action_to_run = ClickAction(x=coord[0], y=coord[1], button="middle")
+                    elif tool_name == "double_click":
+                        coord = self.get_coordinates(tool_input)
+                        if coord:
+                            action_to_run = DoubleClickAction(x=coord[0], y=coord[1])
+                    elif tool_name == "triple_click":
+                        coord = self.get_coordinates(tool_input)
+                        if coord:
+                            action_to_run = TripleClickAction(x=coord[0], y=coord[1])
+                    elif tool_name == "left_click_drag":
+                        start_coord = self.get_coordinates(tool_input, key="start_coordinate")
+                        end_coord = self.get_coordinates(tool_input)
+                        if start_coord and end_coord:
+                            action_to_run = DragAction(path=[Point(x=p[0], y=p[1]) for p in [start_coord, end_coord]])
+                    elif tool_name == "left_mouse_down":
+                        action_to_run = MouseDownAction(button="left")
+                    elif tool_name == "left_mouse_up":
+                        action_to_run = MouseUpAction(button="left")
+                    elif tool_name == "type":
+                        text: str = tool_input.get("text")
+                        if text:
+                            action_to_run = TypeAction(text=text)
+                    elif tool_name == "scroll":
+                        direction = tool_input.get("scroll_direction")
+                        amount = int(tool_input.get("scroll_amount", 5))
+                        coord = self.get_coordinates(tool_input)
+                        x = coord[0] if coord else None
+                        y = coord[1] if coord else None
+                        if direction:
+                            action_to_run = ScrollAction(scroll_direction=direction, scroll_amount=amount, x=x, y=y)
+                    elif tool_name == "key":
+                        text = tool_input.get("text")
+                        if text:
+                            action_to_run = KeypressAction(keys=text.split("+"))  # Split xdotool style
+                    elif tool_name == "hold_key":
+                        text = tool_input.get("text")
+                        duration = tool_input.get("duration", 1.0)
+                        if text:
+                            action_to_run = HoldKeyAction(text=text, duration=duration)
+                    elif tool_name == "wait":
+                        duration = tool_input.get("duration", 1.0)
+                        action_to_run = WaitAction(duration=duration)
+                    elif tool_name == "screenshot":
+                        action_to_run = ScreenshotAction()
+                    elif tool_name == "cursor_position":
+                        action_to_run = CursorPositionAction()
+                    elif tool_name == "goto":
+                        url = tool_input.get("url")
+                        if url:
+                            action_to_run = GotoAction(url=url)
+                        else:
+                            logger.warning("Goto tool called without URL.")
+                    elif tool_name == "back":
+                        action_to_run = BackAction()
+                    else:
+                        logger.warning(f"Unsupported Anthropic computer action type: {tool_name}")
+
+                except Exception as e:
+                    error_msg = f"Error converting Anthropic action {tool_name} ({tool_input}): {e}"
+                    logger.error(error_msg)
+                    content = error_msg
+                    is_error = True
+                    action_to_run = NoopAction()
+
+                if action_to_run:
+                    actions.append(action_to_run)
+                    action_results.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": tool_use_id,
+                            "content": content,  # Updated after environment step
+                            "is_error": is_error,  # Updated after environment step
+                        }
+                    )
+
+        self._update_usage(
+            response.usage.input_tokens,
+            response.usage.output_tokens,
+            response.usage.cache_read_input_tokens,
+            response.usage.cache_creation_input_tokens,
+        )
+        self.tracer["temperature"] = temperature
+
+        return AgentActResult(
+            actions=actions,
+            action_results=action_results,
+            rendered_response=rendered_response,
+        )
+
+    def add_action_results(self, env_steps: list[EnvStepResult], agent_action: AgentActResult):
+        if not agent_action.action_results:
+            return
+
+        # Update action results with results of applying suggested actions on the environment
+        for idx, env_step in enumerate(env_steps):
+            action_result = agent_action.action_results[idx]
+            result_content = env_step.error or env_step.output or "[Action completed]"
+            if env_step.type == "image" and isinstance(result_content, dict):
+                # Add screenshot data in anthropic message format
+                action_result["content"] = [
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/webp",
+                            "data": result_content["image"],
+                        },
+                    }
+                ]
+            else:
+                # Add text data
+                action_result["content"] = result_content
+            if env_step.error:
+                action_result["is_error"] = True
+
+        # Append tool results to the message history
+        self.messages += [AgentMessage(role="environment", content=agent_action.action_results)]
+
+        # Mark the final tool result as a cache break point
+        agent_action.action_results[-1]["cache_control"] = {"type": "ephemeral"}
+        # Remove previous cache controls
+        for msg in self.messages:
+            if msg.role == "environment" and isinstance(msg.content, list):
+                for block in msg.content:
+                    if isinstance(block, dict) and "cache_control" in block:
+                        del block["cache_control"]
+
+    def _format_message_for_api(self, messages: list[AgentMessage]) -> list[dict]:
+        """Format Anthropic response into a single string."""
+        formatted_messages = []
+        for message in messages:
+            role = "user" if message.role == "environment" else message.role
+            content = (
+                [{"type": "text", "text": message.content}]
+                if not isinstance(message.content, list)
+                else message.content
+            )
+            formatted_messages.append(
+                {
+                    "role": role,
+                    "content": content,
+                }
+            )
+        return formatted_messages
+
+    def compile_response(self, response_content: list[BetaContentBlock | dict] | str) -> str:
+        """Compile Anthropic response into a single string."""
+        if isinstance(response_content, str):
+            return response_content
+        elif is_none_or_empty(response_content):
+            return ""
+        # action results are a list dictionaries,
+        # beta content blocks are objects with a type attribute
+        elif isinstance(response_content[0], dict):
+            return json.dumps(response_content)
+
+        compiled_response = [""]
+        for block in deepcopy(response_content):
+            block = cast(BetaContentBlock, block)  # Ensure block is of type BetaContentBlock
+            if block.type == "text":
+                compiled_response.append(block.text)
+            elif block.type == "tool_use":
+                block_input = {"action": block.name}
+                if block.name == "computer":
+                    block_input = block.input  # Computer action details are in input dict
+                elif block.name == "goto":
+                    block_input["url"] = block.input.get("url", "[Missing URL]")
+
+                # Avoid showing large image data in compiled text log
+                if isinstance(block_input, dict) and block_input.get("action") == "screenshot":
+                    block_input["image"] = "[placeholder for screenshot]"
+                    compiled_response.append(f"**Action**: {json.dumps(block_input)}")
+                else:
+                    compiled_response.append(f"**Action**: {json.dumps(block_input)}")
+            elif block.type == "thinking":
+                # Check if thinking content exists before appending
+                thinking_content = getattr(block, "thinking", None)
+                if thinking_content:
+                    compiled_response.append(f"**Thought**: {thinking_content}")
+
+        return "\n- ".join(filter(None, compiled_response))  # Filter out empty strings
+
+    def _render_response(self, response_content: list[BetaContentBlock], screenshot: str | None) -> dict:
+        """Render Anthropic response, potentially including actual screenshots."""
+        render_texts = []
+        for block in deepcopy(response_content):  # Use deepcopy to avoid modifying original
+            if block.type == "thinking":
+                thinking_content = getattr(block, "thinking", None)
+                if thinking_content:
+                    render_texts += [f"**Thought**: {thinking_content}"]
+            elif block.type == "text":
+                render_texts += [block.text]
+            elif block.type == "tool_use":
+                if block.name == "goto":
+                    render_texts += [f"Open URL: {block.input.get('url', '[Missing URL]')}"]
+                elif block.name == "back":
+                    render_texts += ["Go back to the previous page."]
+                elif block.name == "computer":
+                    block_input = block.input
+                    if not isinstance(block_input, dict):
+                        render_texts += [json.dumps(block_input)]
+                    # Handle computer action details
+                    elif "action" in block_input:
+                        action = block_input["action"]
+                        if action == "type":
+                            text: str = block_input.get("text")
+                            if text:
+                                render_texts += [f'Type "{text}"']
+                        elif action == "key":
+                            text = block_input.get("text")
+                            if text:
+                                render_texts += [f"Press {text}"]
+                        elif action == "hold_key":
+                            text = block_input.get("text")
+                            duration = block_input.get("duration", 1.0)
+                            if text:
+                                render_texts += [f"Hold {text} for {duration} seconds"]
+                        else:
+                            # Handle other actions
+                            render_texts += [f"{action.capitalize()}"]
+
+                # If screenshot is not available when screenshot action was requested
+                if isinstance(block.input, dict) and block.input.get("action") == "screenshot" and not screenshot:
+                    render_texts += ["Failed to get screenshot"]
+
+        # Do not show screenshot if no actions requested
+        if all([block.type != "tool_use" for block in response_content]):
+            # If all blocks are not tool_use, return None
+            screenshot = None
+
+        # Create render payload
+        render_payload = {
+            # Combine text into a single string and filter out empty strings
+            "text": "\n- ".join(filter(None, render_texts)),
+            # Add screenshot data if available
+            "image": f"data:image/webp;base64,{screenshot}" if screenshot else None,
+        }
+
+        return render_payload
+
+    def get_coordinates(self, tool_input: dict, key: str = "coordinate") -> Optional[list | tuple]:
+        """Get coordinates from tool input."""
+        raw_coord = tool_input.get(key)
+        if not raw_coord:
+            return None
+        try:
+            coord = ast.literal_eval(raw_coord) if isinstance(raw_coord, str) else raw_coord
+        except (ValueError, SyntaxError):
+            logger.warning(f"Could not parse coordinate from value: {raw_coord}")
+            return None
+
+        if not isinstance(coord, (list, tuple)) or not len(coord) == 2:
+            logger.warning(f"Parsed coordinate string '{raw_coord}' is not a 2-element list/tuple: {coord}")
+            return None
+
+        return coord