From 96e88f2928f1a1344cb5528ed31e47b5661d1d77 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Wed, 24 Dec 2025 04:44:55 -0800
Subject: [PATCH 1/2] Agent abstraction Phase 1:

---
 examples/test_local_llm_agent.py |  86 ++++++
 sentience/__init__.py            |  14 +-
 sentience/agent.py               | 355 ++++++++++++++++++++++++
 sentience/llm_provider.py        | 452 +++++++++++++++++++++++++++++++
 tests/test_agent.py              | 414 ++++++++++++++++++++++++++++
 5 files changed, 1320 insertions(+), 1 deletion(-)
 create mode 100644 examples/test_local_llm_agent.py
 create mode 100644 sentience/agent.py
 create mode 100644 sentience/llm_provider.py
 create mode 100644 tests/test_agent.py

diff --git a/examples/test_local_llm_agent.py b/examples/test_local_llm_agent.py
new file mode 100644
index 0000000..f2a5c1b
--- /dev/null
+++ b/examples/test_local_llm_agent.py
@@ -0,0 +1,86 @@
+"""
+Test script for LocalLLMProvider with Qwen2.5-3B-Instruct
+Demonstrates using a local LLM with SentienceAgent
+"""
+
+from sentience.llm_provider import LocalLLMProvider
+
+def test_local_llm_basic():
+    """Test basic LLM response generation"""
+    print("="*70)
+    print("Testing LocalLLMProvider with Qwen2.5-3B-Instruct")
+    print("="*70)
+
+    # Initialize local LLM
+    # Using the model from your local cache
+    llm = LocalLLMProvider(
+        model_name="Qwen/Qwen2.5-3B-Instruct",
+        device="auto",  # Will use CUDA if available, else CPU
+        load_in_4bit=False,  # Set to True to save memory
+        torch_dtype="auto"
+    )
+
+    print("\n" + "="*70)
+    print("Test 1: Simple question")
+    print("="*70)
+
+    response = llm.generate(
+        system_prompt="You are a helpful web automation assistant.",
+        user_prompt="What is 2+2?",
+        max_new_tokens=50,
+        temperature=0.1
+    )
+
+    print(f"Response: {response.content}")
+    print(f"Tokens: {response.total_tokens} (prompt: {response.prompt_tokens}, completion: {response.completion_tokens})")
+
+    print("\n" + "="*70)
+    print("Test 2: Action parsing (for agent)")
+    print("="*70)
+
+    system_prompt = """You are an AI web automation agent.
+
+GOAL: Click the search box
+
+VISIBLE ELEMENTS (sorted by importance, max 50):
+[1] <button> "Sign In" {PRIMARY,CLICKABLE,color:blue} @ (100,50) (Imp:900)
+[2] <textbox> "" {CLICKABLE} @ (200,100) (Imp:850)
+[3] <link> "Help" {} @ (50,150) (Imp:700)
+
+VISUAL CUES:
+- {PRIMARY}: Main call-to-action element
+- {CLICKABLE}: Element is clickable
+- {color:X}: Background color name
+
+RESPONSE FORMAT (return ONLY the function call):
+- CLICK(id) - Click element by ID
+- TYPE(id, "text") - Type text into element
+- PRESS("key") - Press keyboard key
+- FINISH() - Task complete
+"""
+
+    user_prompt = "What is the next step to achieve the goal?"
+
+    response = llm.generate(
+        system_prompt=system_prompt,
+        user_prompt=user_prompt,
+        max_new_tokens=20,
+        temperature=0.0
+    )
+
+    print(f"Agent Response: {response.content}")
+    print(f"Tokens: {response.total_tokens}")
+
+    # Check if response is parseable
+    if "CLICK(2)" in response.content or "click(2)" in response.content.lower():
+        print("\n✅ SUCCESS: LLM correctly identified textbox (element 2) as search box!")
+    else:
+        print(f"\n⚠️  Response may need adjustment: {response.content}")
+
+    print("\n" + "="*70)
+    print("LocalLLMProvider Test Complete!")
+    print("="*70)
+
+
+if __name__ == "__main__":
+    test_local_llm_basic()
diff --git a/sentience/__init__.py b/sentience/__init__.py
index 287ffb9..f5f59e1 100644
--- a/sentience/__init__.py
+++ b/sentience/__init__.py
@@ -15,9 +15,14 @@
 from .read import read
 from .screenshot import screenshot
 
-__version__ = "0.10.6"
+# Agent Layer (Phase 1 & 2)
+from .llm_provider import LLMProvider, LLMResponse, OpenAIProvider, AnthropicProvider, LocalLLMProvider
+from .agent import SentienceAgent
+
+__version__ = "0.10.7"
 
 __all__ = [
+    # Core SDK
     "SentienceBrowser",
     "Snapshot",
     "Element",
@@ -44,5 +49,12 @@
     "generate",
     "read",
     "screenshot",
+    # Agent Layer
+    "LLMProvider",
+    "LLMResponse",
+    "OpenAIProvider",
+    "AnthropicProvider",
+    "LocalLLMProvider",
+    "SentienceAgent",
 ]
 
diff --git a/sentience/agent.py b/sentience/agent.py
new file mode 100644
index 0000000..158c4d9
--- /dev/null
+++ b/sentience/agent.py
@@ -0,0 +1,355 @@
+"""
+Sentience Agent: High-level automation agent using LLM + SDK
+Implements observe-think-act loop for natural language commands
+"""
+
+import re
+import time
+from typing import Dict, Any, List, Optional
+from .llm_provider import LLMProvider, LLMResponse
+from .browser import SentienceBrowser
+from .snapshot import snapshot
+from .actions import click, type_text, press
+from .models import Snapshot, Element, ActionResult
+
+
+class SentienceAgent:
+    """
+    High-level agent that combines Sentience SDK with any LLM provider.
+
+    Uses observe-think-act loop to execute natural language commands:
+    1. OBSERVE: Get snapshot of current page state
+    2. THINK: Query LLM to decide next action
+    3. ACT: Execute action using SDK
+
+    Example:
+        >>> from sentience import SentienceBrowser, SentienceAgent
+        >>> from sentience.llm_provider import OpenAIProvider
+        >>>
+        >>> browser = SentienceBrowser(api_key="sentience_key")
+        >>> llm = OpenAIProvider(api_key="openai_key", model="gpt-4o")
+        >>> agent = SentienceAgent(browser, llm)
+        >>>
+        >>> with browser:
+        >>>     browser.page.goto("https://google.com")
+        >>>     agent.act("Click the search box")
+        >>>     agent.act("Type 'magic mouse' into the search field")
+        >>>     agent.act("Press Enter key")
+    """
+
+    def __init__(
+        self,
+        browser: SentienceBrowser,
+        llm: LLMProvider,
+        snapshot_limit: int = 50,
+        verbose: bool = True
+    ):
+        """
+        Initialize Sentience Agent
+
+        Args:
+            browser: SentienceBrowser instance
+            llm: LLM provider (OpenAIProvider, AnthropicProvider, etc.)
+            snapshot_limit: Maximum elements to include in context (default: 50)
+            verbose: Print execution logs (default: True)
+        """
+        self.browser = browser
+        self.llm = llm
+        self.snapshot_limit = snapshot_limit
+        self.verbose = verbose
+
+        # Execution history
+        self.history: List[Dict[str, Any]] = []
+
+        # Token usage tracking
+        self.token_usage = {
+            "total_prompt_tokens": 0,
+            "total_completion_tokens": 0,
+            "total_tokens": 0,
+            "by_action": []
+        }
+
+    def act(
+        self,
+        goal: str,
+        max_retries: int = 2,
+        snapshot_options: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Execute a high-level goal using observe → think → act loop
+
+        Args:
+            goal: Natural language instruction (e.g., "Click the Sign In button")
+            max_retries: Number of retries on failure (default: 2)
+            snapshot_options: Optional snapshot parameters (limit, filter, etc.)
+
+        Returns:
+            Result dict with status, action_taken, reasoning, and execution data
+
+        Example:
+            >>> result = agent.act("Click the search box")
+            >>> print(result)
+            {'success': True, 'action': 'click', 'element_id': 42, 'reasoning': '...'}
+        """
+        if self.verbose:
+            print(f"\n{'='*70}")
+            print(f"🤖 Agent Goal: {goal}")
+            print(f"{'='*70}")
+
+        for attempt in range(max_retries + 1):
+            try:
+                # 1. OBSERVE: Get refined semantic snapshot
+                start_time = time.time()
+
+                snap_opts = snapshot_options or {}
+                snap_opts.setdefault('limit', self.snapshot_limit)
+
+                snap = snapshot(self.browser, **snap_opts)
+
+                if snap.status != "success":
+                    raise RuntimeError(f"Snapshot failed: {snap.error}")
+
+                # 2. GROUND: Format elements for LLM context
+                context = self._build_context(snap, goal)
+
+                # 3. THINK: Query LLM for next action
+                llm_response = self._query_llm(context, goal)
+
+                if self.verbose:
+                    print(f"🧠 LLM Decision: {llm_response.content}")
+
+                # Track token usage
+                self._track_tokens(goal, llm_response)
+
+                # Parse action from LLM response
+                action_str = llm_response.content.strip()
+
+                # 4. EXECUTE: Parse and run action
+                result = self._execute_action(action_str, snap)
+
+                duration_ms = int((time.time() - start_time) * 1000)
+                result['duration_ms'] = duration_ms
+                result['attempt'] = attempt
+                result['goal'] = goal
+
+                # 5. RECORD: Track history
+                self.history.append({
+                    "goal": goal,
+                    "action": action_str,
+                    "result": result,
+                    "success": result.get("success", False),
+                    "attempt": attempt,
+                    "duration_ms": duration_ms
+                })
+
+                if self.verbose:
+                    status = "✅" if result.get("success") else "❌"
+                    print(f"{status} Completed in {duration_ms}ms")
+
+                return result
+
+            except Exception as e:
+                if attempt < max_retries:
+                    if self.verbose:
+                        print(f"⚠️  Retry {attempt + 1}/{max_retries}: {e}")
+                    time.sleep(1.0)  # Brief delay before retry
+                    continue
+                else:
+                    error_result = {
+                        "success": False,
+                        "goal": goal,
+                        "error": str(e),
+                        "attempt": attempt
+                    }
+                    self.history.append(error_result)
+                    raise RuntimeError(f"Failed after {max_retries} retries: {e}")
+
+    def _build_context(self, snap: Snapshot, goal: str) -> str:
+        """
+        Convert snapshot elements to token-efficient prompt string
+
+        Format: [ID] <role> "text" {cues} @ (x,y) (Imp:score)
+
+        Args:
+            snap: Snapshot object
+            goal: User goal (for context)
+
+        Returns:
+            Formatted element context string
+        """
+        lines = []
+        for el in snap.elements[:self.snapshot_limit]:
+            # Extract visual cues
+            cues = []
+            if el.visual_cues.is_primary:
+                cues.append("PRIMARY")
+            if el.visual_cues.is_clickable:
+                cues.append("CLICKABLE")
+            if el.visual_cues.background_color_name:
+                cues.append(f"color:{el.visual_cues.background_color_name}")
+
+            # Format element line
+            cues_str = f" {{{','.join(cues)}}}" if cues else ""
+            text_preview = (el.text[:50] + "...") if el.text and len(el.text) > 50 else (el.text or "")
+
+            lines.append(
+                f"[{el.id}] <{el.role}> \"{text_preview}\"{cues_str} "
+                f"@ ({int(el.bbox.x)},{int(el.bbox.y)}) (Imp:{el.importance})"
+            )
+
+        return "\n".join(lines)
+
+    def _query_llm(self, dom_context: str, goal: str) -> LLMResponse:
+        """
+        Query LLM with standardized prompt template
+
+        Args:
+            dom_context: Formatted element context
+            goal: User goal
+
+        Returns:
+            LLMResponse from LLM provider
+        """
+        system_prompt = f"""You are an AI web automation agent.
+
+GOAL: {goal}
+
+VISIBLE ELEMENTS (sorted by importance, max {self.snapshot_limit}):
+{dom_context}
+
+VISUAL CUES EXPLAINED:
+- {{PRIMARY}}: Main call-to-action element on the page
+- {{CLICKABLE}}: Element is clickable
+- {{color:X}}: Background color name
+
+RESPONSE FORMAT:
+Return ONLY the function call, no explanation or markdown.
+
+Available actions:
+- CLICK(id) - Click element by ID
+- TYPE(id, "text") - Type text into element
+- PRESS("key") - Press keyboard key (Enter, Escape, Tab, ArrowDown, etc)
+- FINISH() - Task complete
+
+Examples:
+- CLICK(42)
+- TYPE(15, "magic mouse")
+- PRESS("Enter")
+- FINISH()
+"""
+
+        user_prompt = "What is the next step to achieve the goal?"
+
+        return self.llm.generate(system_prompt, user_prompt, temperature=0.0)
+
+    def _execute_action(self, action_str: str, snap: Snapshot) -> Dict[str, Any]:
+        """
+        Parse action string and execute SDK call
+
+        Args:
+            action_str: Action string from LLM (e.g., "CLICK(42)")
+            snap: Current snapshot (for context)
+
+        Returns:
+            Execution result dictionary
+        """
+        # Parse CLICK(42)
+        if match := re.match(r'CLICK\s*\(\s*(\d+)\s*\)', action_str, re.IGNORECASE):
+            element_id = int(match.group(1))
+            result = click(self.browser, element_id)
+            return {
+                "success": result.success,
+                "action": "click",
+                "element_id": element_id,
+                "outcome": result.outcome,
+                "url_changed": result.url_changed
+            }
+
+        # Parse TYPE(42, "hello world")
+        elif match := re.match(r'TYPE\s*\(\s*(\d+)\s*,\s*["\']([^"\']*)["\']\s*\)', action_str, re.IGNORECASE):
+            element_id = int(match.group(1))
+            text = match.group(2)
+            result = type_text(self.browser, element_id, text)
+            return {
+                "success": result.success,
+                "action": "type",
+                "element_id": element_id,
+                "text": text,
+                "outcome": result.outcome
+            }
+
+        # Parse PRESS("Enter")
+        elif match := re.match(r'PRESS\s*\(\s*["\']([^"\']+)["\']\s*\)', action_str, re.IGNORECASE):
+            key = match.group(1)
+            result = press(self.browser, key)
+            return {
+                "success": result.success,
+                "action": "press",
+                "key": key,
+                "outcome": result.outcome
+            }
+
+        # Parse FINISH()
+        elif re.match(r'FINISH\s*\(\s*\)', action_str, re.IGNORECASE):
+            return {
+                "success": True,
+                "action": "finish",
+                "message": "Task marked as complete"
+            }
+
+        else:
+            raise ValueError(
+                f"Unknown action format: {action_str}\n"
+                f"Expected: CLICK(id), TYPE(id, \"text\"), PRESS(\"key\"), or FINISH()"
+            )
+
+    def _track_tokens(self, goal: str, llm_response: LLMResponse):
+        """
+        Track token usage for analytics
+
+        Args:
+            goal: User goal
+            llm_response: LLM response with token usage
+        """
+        if llm_response.prompt_tokens:
+            self.token_usage["total_prompt_tokens"] += llm_response.prompt_tokens
+        if llm_response.completion_tokens:
+            self.token_usage["total_completion_tokens"] += llm_response.completion_tokens
+        if llm_response.total_tokens:
+            self.token_usage["total_tokens"] += llm_response.total_tokens
+
+        self.token_usage["by_action"].append({
+            "goal": goal,
+            "prompt_tokens": llm_response.prompt_tokens,
+            "completion_tokens": llm_response.completion_tokens,
+            "total_tokens": llm_response.total_tokens,
+            "model": llm_response.model_name
+        })
+
+    def get_token_stats(self) -> Dict[str, Any]:
+        """
+        Get token usage statistics
+
+        Returns:
+            Dictionary with token usage breakdown
+        """
+        return self.token_usage.copy()
+
+    def get_history(self) -> List[Dict[str, Any]]:
+        """
+        Get execution history
+
+        Returns:
+            List of all actions taken with results
+        """
+        return self.history.copy()
+
+    def clear_history(self):
+        """Clear execution history and reset token counters"""
+        self.history.clear()
+        self.token_usage = {
+            "total_prompt_tokens": 0,
+            "total_completion_tokens": 0,
+            "total_tokens": 0,
+            "by_action": []
+        }
diff --git a/sentience/llm_provider.py b/sentience/llm_provider.py
new file mode 100644
index 0000000..a8bf8a0
--- /dev/null
+++ b/sentience/llm_provider.py
@@ -0,0 +1,452 @@
+"""
+LLM Provider abstraction layer for Sentience SDK
+Enables "Bring Your Own Brain" (BYOB) pattern - plug in any LLM provider
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any
+from dataclasses import dataclass
+
+
+@dataclass
+class LLMResponse:
+    """Standardized LLM response across all providers"""
+    content: str
+    prompt_tokens: Optional[int] = None
+    completion_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    model_name: Optional[str] = None
+    finish_reason: Optional[str] = None
+
+
+class LLMProvider(ABC):
+    """
+    Abstract base class for LLM providers.
+
+    Implement this interface to add support for any LLM:
+    - OpenAI (GPT-4, GPT-3.5)
+    - Anthropic (Claude)
+    - Local models (Ollama, LlamaCpp)
+    - Azure OpenAI
+    - Any other completion API
+    """
+
+    @abstractmethod
+    def generate(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        **kwargs
+    ) -> LLMResponse:
+        """
+        Generate a response from the LLM
+
+        Args:
+            system_prompt: System instruction/context
+            user_prompt: User query/request
+            **kwargs: Provider-specific parameters (temperature, max_tokens, etc.)
+
+        Returns:
+            LLMResponse with content and token usage
+        """
+        pass
+
+    @abstractmethod
+    def supports_json_mode(self) -> bool:
+        """
+        Whether this provider supports structured JSON output
+
+        Returns:
+            True if provider has native JSON mode, False otherwise
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def model_name(self) -> str:
+        """
+        Model identifier (e.g., "gpt-4o", "claude-3-sonnet")
+
+        Returns:
+            Model name string
+        """
+        pass
+
+
+class OpenAIProvider(LLMProvider):
+    """
+    OpenAI provider implementation (GPT-4, GPT-4o, GPT-3.5-turbo, etc.)
+
+    Example:
+        >>> from sentience.llm_provider import OpenAIProvider
+        >>> llm = OpenAIProvider(api_key="sk-...", model="gpt-4o")
+        >>> response = llm.generate("You are a helpful assistant", "Hello!")
+        >>> print(response.content)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "gpt-4o",
+        base_url: Optional[str] = None,
+        organization: Optional[str] = None
+    ):
+        """
+        Initialize OpenAI provider
+
+        Args:
+            api_key: OpenAI API key (or set OPENAI_API_KEY env var)
+            model: Model name (gpt-4o, gpt-4-turbo, gpt-3.5-turbo, etc.)
+            base_url: Custom API base URL (for compatible APIs)
+            organization: OpenAI organization ID
+        """
+        try:
+            from openai import OpenAI
+        except ImportError:
+            raise ImportError(
+                "OpenAI package not installed. Install with: pip install openai"
+            )
+
+        self.client = OpenAI(
+            api_key=api_key,
+            base_url=base_url,
+            organization=organization
+        )
+        self._model_name = model
+
+    def generate(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        temperature: float = 0.0,
+        max_tokens: Optional[int] = None,
+        json_mode: bool = False,
+        **kwargs
+    ) -> LLMResponse:
+        """
+        Generate response using OpenAI API
+
+        Args:
+            system_prompt: System instruction
+            user_prompt: User query
+            temperature: Sampling temperature (0.0 = deterministic, 1.0 = creative)
+            max_tokens: Maximum tokens to generate
+            json_mode: Enable JSON response format (requires model support)
+            **kwargs: Additional OpenAI API parameters
+
+        Returns:
+            LLMResponse object
+        """
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": user_prompt})
+
+        # Build API parameters
+        api_params = {
+            "model": self._model_name,
+            "messages": messages,
+            "temperature": temperature,
+        }
+
+        if max_tokens:
+            api_params["max_tokens"] = max_tokens
+
+        if json_mode and self.supports_json_mode():
+            api_params["response_format"] = {"type": "json_object"}
+
+        # Merge additional parameters
+        api_params.update(kwargs)
+
+        # Call OpenAI API
+        response = self.client.chat.completions.create(**api_params)
+
+        choice = response.choices[0]
+        usage = response.usage
+
+        return LLMResponse(
+            content=choice.message.content,
+            prompt_tokens=usage.prompt_tokens if usage else None,
+            completion_tokens=usage.completion_tokens if usage else None,
+            total_tokens=usage.total_tokens if usage else None,
+            model_name=response.model,
+            finish_reason=choice.finish_reason
+        )
+
+    def supports_json_mode(self) -> bool:
+        """OpenAI models support JSON mode (GPT-4, GPT-3.5-turbo)"""
+        model_lower = self._model_name.lower()
+        return any(x in model_lower for x in ["gpt-4", "gpt-3.5"])
+
+    @property
+    def model_name(self) -> str:
+        return self._model_name
+
+
+class AnthropicProvider(LLMProvider):
+    """
+    Anthropic provider implementation (Claude 3 Opus, Sonnet, Haiku, etc.)
+
+    Example:
+        >>> from sentience.llm_provider import AnthropicProvider
+        >>> llm = AnthropicProvider(api_key="sk-ant-...", model="claude-3-sonnet-20240229")
+        >>> response = llm.generate("You are a helpful assistant", "Hello!")
+        >>> print(response.content)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "claude-3-5-sonnet-20241022"
+    ):
+        """
+        Initialize Anthropic provider
+
+        Args:
+            api_key: Anthropic API key (or set ANTHROPIC_API_KEY env var)
+            model: Model name (claude-3-opus, claude-3-sonnet, claude-3-haiku, etc.)
+        """
+        try:
+            from anthropic import Anthropic
+        except ImportError:
+            raise ImportError(
+                "Anthropic package not installed. Install with: pip install anthropic"
+            )
+
+        self.client = Anthropic(api_key=api_key)
+        self._model_name = model
+
+    def generate(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        temperature: float = 0.0,
+        max_tokens: int = 1024,
+        **kwargs
+    ) -> LLMResponse:
+        """
+        Generate response using Anthropic API
+
+        Args:
+            system_prompt: System instruction
+            user_prompt: User query
+            temperature: Sampling temperature
+            max_tokens: Maximum tokens to generate (required by Anthropic)
+            **kwargs: Additional Anthropic API parameters
+
+        Returns:
+            LLMResponse object
+        """
+        # Build API parameters
+        api_params = {
+            "model": self._model_name,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            "messages": [{"role": "user", "content": user_prompt}]
+        }
+
+        if system_prompt:
+            api_params["system"] = system_prompt
+
+        # Merge additional parameters
+        api_params.update(kwargs)
+
+        # Call Anthropic API
+        response = self.client.messages.create(**api_params)
+
+        content = response.content[0].text if response.content else ""
+
+        return LLMResponse(
+            content=content,
+            prompt_tokens=response.usage.input_tokens if hasattr(response, 'usage') else None,
+            completion_tokens=response.usage.output_tokens if hasattr(response, 'usage') else None,
+            total_tokens=(response.usage.input_tokens + response.usage.output_tokens) if hasattr(response, 'usage') else None,
+            model_name=response.model,
+            finish_reason=response.stop_reason
+        )
+
+    def supports_json_mode(self) -> bool:
+        """Anthropic doesn't have native JSON mode (requires prompt engineering)"""
+        return False
+
+    @property
+    def model_name(self) -> str:
+        return self._model_name
+
+
+class LocalLLMProvider(LLMProvider):
+    """
+    Local LLM provider using HuggingFace Transformers
+    Supports Qwen, Llama, Gemma, Phi, and other instruction-tuned models
+
+    Example:
+        >>> from sentience.llm_provider import LocalLLMProvider
+        >>> llm = LocalLLMProvider(model_name="Qwen/Qwen2.5-3B-Instruct")
+        >>> response = llm.generate("You are helpful", "Hello!")
+    """
+
+    def __init__(
+        self,
+        model_name: str = "Qwen/Qwen2.5-3B-Instruct",
+        device: str = "auto",
+        load_in_4bit: bool = False,
+        load_in_8bit: bool = False,
+        torch_dtype: str = "auto"
+    ):
+        """
+        Initialize local LLM using HuggingFace Transformers
+
+        Args:
+            model_name: HuggingFace model identifier
+                Popular options:
+                - "Qwen/Qwen2.5-3B-Instruct" (recommended, 3B params)
+                - "meta-llama/Llama-3.2-3B-Instruct" (3B params)
+                - "google/gemma-2-2b-it" (2B params)
+                - "microsoft/Phi-3-mini-4k-instruct" (3.8B params)
+            device: Device to run on ("cpu", "cuda", "mps", "auto")
+            load_in_4bit: Use 4-bit quantization (saves 75% memory)
+            load_in_8bit: Use 8-bit quantization (saves 50% memory)
+            torch_dtype: Data type ("auto", "float16", "bfloat16", "float32")
+        """
+        try:
+            import torch
+            from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
+        except ImportError:
+            raise ImportError(
+                "transformers and torch required for local LLM. "
+                "Install with: pip install transformers torch"
+            )
+
+        self._model_name = model_name
+
+        # Load tokenizer
+        self.tokenizer = AutoTokenizer.from_pretrained(
+            model_name,
+            trust_remote_code=True
+        )
+
+        # Set padding token if not present
+        if self.tokenizer.pad_token is None:
+            self.tokenizer.pad_token = self.tokenizer.eos_token
+
+        # Configure quantization
+        quantization_config = None
+        if load_in_4bit:
+            quantization_config = BitsAndBytesConfig(
+                load_in_4bit=True,
+                bnb_4bit_compute_dtype=torch.float16,
+                bnb_4bit_use_double_quant=True,
+                bnb_4bit_quant_type="nf4"
+            )
+        elif load_in_8bit:
+            quantization_config = BitsAndBytesConfig(load_in_8bit=True)
+
+        # Determine torch dtype
+        if torch_dtype == "auto":
+            dtype = torch.float16 if device != "cpu" else torch.float32
+        else:
+            dtype = getattr(torch, torch_dtype)
+
+        # Load model
+        self.model = AutoModelForCausalLM.from_pretrained(
+            model_name,
+            quantization_config=quantization_config,
+            torch_dtype=dtype if quantization_config is None else None,
+            device_map=device,
+            trust_remote_code=True,
+            low_cpu_mem_usage=True
+        )
+        self.model.eval()
+
+    def generate(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        max_new_tokens: int = 512,
+        temperature: float = 0.1,
+        top_p: float = 0.9,
+        **kwargs
+    ) -> LLMResponse:
+        """
+        Generate response using local model
+
+        Args:
+            system_prompt: System instruction
+            user_prompt: User query
+            max_new_tokens: Maximum tokens to generate
+            temperature: Sampling temperature (0 = greedy, higher = more random)
+            top_p: Nucleus sampling parameter
+            **kwargs: Additional generation parameters
+
+        Returns:
+            LLMResponse object
+        """
+        import torch
+
+        # Auto-determine sampling based on temperature
+        do_sample = temperature > 0
+
+        # Format prompt using model's chat template
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": user_prompt})
+
+        # Use model's native chat template if available
+        if hasattr(self.tokenizer, 'apply_chat_template'):
+            formatted_prompt = self.tokenizer.apply_chat_template(
+                messages,
+                tokenize=False,
+                add_generation_prompt=True
+            )
+        else:
+            # Fallback formatting
+            formatted_prompt = ""
+            if system_prompt:
+                formatted_prompt += f"System: {system_prompt}\n\n"
+            formatted_prompt += f"User: {user_prompt}\n\nAssistant:"
+
+        # Tokenize
+        inputs = self.tokenizer(
+            formatted_prompt,
+            return_tensors="pt",
+            truncation=True
+        ).to(self.model.device)
+
+        input_length = inputs['input_ids'].shape[1]
+
+        # Generate
+        with torch.no_grad():
+            outputs = self.model.generate(
+                **inputs,
+                max_new_tokens=max_new_tokens,
+                temperature=temperature if do_sample else 1.0,
+                top_p=top_p,
+                do_sample=do_sample,
+                pad_token_id=self.tokenizer.pad_token_id,
+                eos_token_id=self.tokenizer.eos_token_id,
+                **kwargs
+            )
+
+        # Decode only the new tokens
+        generated_tokens = outputs[0][input_length:]
+        response_text = self.tokenizer.decode(
+            generated_tokens,
+            skip_special_tokens=True
+        ).strip()
+
+        return LLMResponse(
+            content=response_text,
+            prompt_tokens=input_length,
+            completion_tokens=len(generated_tokens),
+            total_tokens=input_length + len(generated_tokens),
+            model_name=self._model_name
+        )
+
+    def supports_json_mode(self) -> bool:
+        """Local models typically need prompt engineering for JSON"""
+        return False
+
+    @property
+    def model_name(self) -> str:
+        return self._model_name
diff --git a/tests/test_agent.py b/tests/test_agent.py
new file mode 100644
index 0000000..e837487
--- /dev/null
+++ b/tests/test_agent.py
@@ -0,0 +1,414 @@
+"""
+Unit tests for Sentience Agent Layer (Phase 1)
+Tests LLM providers and SentienceAgent without requiring browser
+"""
+
+import pytest
+from unittest.mock import Mock, MagicMock, patch
+from sentience.llm_provider import LLMProvider, LLMResponse, OpenAIProvider, AnthropicProvider
+from sentience.agent import SentienceAgent
+from sentience.models import Snapshot, Element, BBox, VisualCues, Viewport
+
+
+class MockLLMProvider(LLMProvider):
+    """Mock LLM provider for testing"""
+
+    def __init__(self, responses=None):
+        self.responses = responses or []
+        self.call_count = 0
+        self.calls = []
+
+    def generate(self, system_prompt: str, user_prompt: str, **kwargs):
+        self.calls.append({
+            "system": system_prompt,
+            "user": user_prompt,
+            "kwargs": kwargs
+        })
+
+        if self.responses:
+            response = self.responses[self.call_count % len(self.responses)]
+        else:
+            response = "CLICK(1)"
+
+        self.call_count += 1
+
+        return LLMResponse(
+            content=response,
+            prompt_tokens=100,
+            completion_tokens=20,
+            total_tokens=120,
+            model_name="mock-model"
+        )
+
+    def supports_json_mode(self) -> bool:
+        return True
+
+    @property
+    def model_name(self) -> str:
+        return "mock-model"
+
+
+# ========== LLM Provider Tests ==========
+
+def test_llm_response_dataclass():
+    """Test LLMResponse dataclass creation"""
+    response = LLMResponse(
+        content="CLICK(42)",
+        prompt_tokens=100,
+        completion_tokens=20,
+        total_tokens=120,
+        model_name="gpt-4o"
+    )
+
+    assert response.content == "CLICK(42)"
+    assert response.prompt_tokens == 100
+    assert response.completion_tokens == 20
+    assert response.total_tokens == 120
+    assert response.model_name == "gpt-4o"
+
+
+def test_mock_llm_provider():
+    """Test mock LLM provider"""
+    provider = MockLLMProvider(responses=["CLICK(1)", "TYPE(2, \"test\")"])
+
+    # First call
+    response1 = provider.generate("system", "user")
+    assert response1.content == "CLICK(1)"
+    assert provider.call_count == 1
+
+    # Second call
+    response2 = provider.generate("system", "user")
+    assert response2.content == "TYPE(2, \"test\")"
+    assert provider.call_count == 2
+
+    # Check calls were recorded
+    assert len(provider.calls) == 2
+    assert provider.calls[0]["system"] == "system"
+
+
+@pytest.mark.skipif(True, reason="Requires openai package and API key")
+def test_openai_provider_init():
+    """Test OpenAI provider initialization (skipped without API key)"""
+    provider = OpenAIProvider(api_key="test-key", model="gpt-4o")
+    assert provider.model_name == "gpt-4o"
+    assert provider.supports_json_mode() is True
+
+
+@pytest.mark.skipif(True, reason="Requires anthropic package and API key")
+def test_anthropic_provider_init():
+    """Test Anthropic provider initialization (skipped without API key)"""
+    provider = AnthropicProvider(api_key="test-key", model="claude-3-sonnet")
+    assert provider.model_name == "claude-3-sonnet"
+    assert provider.supports_json_mode() is False
+
+
+# ========== SentienceAgent Tests ==========
+
+def create_mock_browser():
+    """Create mock browser for testing"""
+    browser = Mock()
+    browser.page = Mock()
+    browser.page.url = "https://example.com"
+    return browser
+
+
+def create_mock_snapshot():
+    """Create mock snapshot with test elements"""
+    elements = [
+        Element(
+            id=1,
+            role="button",
+            text="Click Me",
+            importance=900,
+            bbox=BBox(x=100, y=200, width=80, height=30),
+            visual_cues=VisualCues(
+                is_primary=True,
+                is_clickable=True,
+                background_color_name="blue"
+            ),
+            in_viewport=True,
+            is_occluded=False,
+            z_index=10
+        ),
+        Element(
+            id=2,
+            role="textbox",
+            text="",
+            importance=850,
+            bbox=BBox(x=100, y=100, width=200, height=40),
+            visual_cues=VisualCues(
+                is_primary=False,
+                is_clickable=True,
+                background_color_name=None
+            ),
+            in_viewport=True,
+            is_occluded=False,
+            z_index=5
+        )
+    ]
+
+    return Snapshot(
+        status="success",
+        timestamp="2024-12-24T10:00:00Z",
+        url="https://example.com",
+        viewport=Viewport(width=1920, height=1080),
+        elements=elements
+    )
+
+
+def test_agent_initialization():
+    """Test SentienceAgent initialization"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+
+    agent = SentienceAgent(browser, llm, snapshot_limit=50, verbose=False)
+
+    assert agent.browser == browser
+    assert agent.llm == llm
+    assert agent.snapshot_limit == 50
+    assert agent.verbose is False
+    assert len(agent.history) == 0
+    assert agent.token_usage["total_tokens"] == 0
+
+
+def test_agent_build_context():
+    """Test context building from snapshot"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    snap = create_mock_snapshot()
+    context = agent._build_context(snap, "test goal")
+
+    # Should contain both elements
+    assert "[1]" in context
+    assert "[2]" in context
+    assert "button" in context
+    assert "textbox" in context
+    assert "Click Me" in context
+    assert "PRIMARY" in context
+    assert "CLICKABLE" in context
+    assert "color:blue" in context
+    assert "(Imp:900)" in context
+
+
+def test_agent_execute_click_action():
+    """Test parsing and executing CLICK action"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    snap = create_mock_snapshot()
+
+    # Mock click function
+    with patch('sentience.agent.click') as mock_click:
+        from sentience.models import ActionResult
+        mock_click.return_value = ActionResult(
+            success=True,
+            duration_ms=150,
+            outcome="dom_updated",
+            url_changed=False
+        )
+
+        result = agent._execute_action("CLICK(1)", snap)
+
+        assert result["success"] is True
+        assert result["action"] == "click"
+        assert result["element_id"] == 1
+        mock_click.assert_called_once_with(browser, 1)
+
+
+def test_agent_execute_type_action():
+    """Test parsing and executing TYPE action"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    snap = create_mock_snapshot()
+
+    # Mock type_text function
+    with patch('sentience.agent.type_text') as mock_type:
+        from sentience.models import ActionResult
+        mock_type.return_value = ActionResult(
+            success=True,
+            duration_ms=200,
+            outcome="dom_updated"
+        )
+
+        result = agent._execute_action('TYPE(2, "hello world")', snap)
+
+        assert result["success"] is True
+        assert result["action"] == "type"
+        assert result["element_id"] == 2
+        assert result["text"] == "hello world"
+        mock_type.assert_called_once_with(browser, 2, "hello world")
+
+
+def test_agent_execute_press_action():
+    """Test parsing and executing PRESS action"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    snap = create_mock_snapshot()
+
+    # Mock press function
+    with patch('sentience.agent.press') as mock_press:
+        from sentience.models import ActionResult
+        mock_press.return_value = ActionResult(
+            success=True,
+            duration_ms=50,
+            outcome="dom_updated"
+        )
+
+        result = agent._execute_action('PRESS("Enter")', snap)
+
+        assert result["success"] is True
+        assert result["action"] == "press"
+        assert result["key"] == "Enter"
+        mock_press.assert_called_once_with(browser, "Enter")
+
+
+def test_agent_execute_finish_action():
+    """Test parsing FINISH action"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    snap = create_mock_snapshot()
+    result = agent._execute_action("FINISH()", snap)
+
+    assert result["success"] is True
+    assert result["action"] == "finish"
+
+
+def test_agent_execute_invalid_action():
+    """Test handling of invalid action format"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    snap = create_mock_snapshot()
+
+    with pytest.raises(ValueError, match="Unknown action format"):
+        agent._execute_action("INVALID_ACTION", snap)
+
+
+def test_agent_act_full_cycle():
+    """Test full act() cycle with mocked dependencies"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider(responses=["CLICK(1)"])
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    # Mock snapshot and click
+    with patch('sentience.agent.snapshot') as mock_snapshot, \
+         patch('sentience.agent.click') as mock_click:
+
+        from sentience.models import ActionResult
+        mock_snapshot.return_value = create_mock_snapshot()
+        mock_click.return_value = ActionResult(
+            success=True,
+            duration_ms=150,
+            outcome="dom_updated"
+        )
+
+        result = agent.act("Click the button", max_retries=0)
+
+        assert result["success"] is True
+        assert result["action"] == "click"
+        assert result["element_id"] == 1
+        assert result["goal"] == "Click the button"
+
+        # Check history was recorded
+        assert len(agent.history) == 1
+        assert agent.history[0]["goal"] == "Click the button"
+
+        # Check tokens were tracked
+        assert agent.token_usage["total_tokens"] > 0
+
+
+def test_agent_token_tracking():
+    """Test token usage tracking"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    # Simulate multiple actions
+    response1 = LLMResponse(content="CLICK(1)", prompt_tokens=100, completion_tokens=20, total_tokens=120)
+    response2 = LLMResponse(content="TYPE(2, \"test\")", prompt_tokens=150, completion_tokens=30, total_tokens=180)
+
+    agent._track_tokens("goal 1", response1)
+    agent._track_tokens("goal 2", response2)
+
+    stats = agent.get_token_stats()
+    assert stats["total_prompt_tokens"] == 250
+    assert stats["total_completion_tokens"] == 50
+    assert stats["total_tokens"] == 300
+    assert len(stats["by_action"]) == 2
+
+
+def test_agent_clear_history():
+    """Test clearing history and token stats"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    # Add some history
+    agent.history.append({"goal": "test"})
+    agent.token_usage["total_tokens"] = 100
+
+    agent.clear_history()
+
+    assert len(agent.history) == 0
+    assert agent.token_usage["total_tokens"] == 0
+
+
+def test_agent_retry_on_failure():
+    """Test retry logic on action failure"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider(responses=["CLICK(999)"])  # Invalid element ID
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    # Mock snapshot and click (click will fail)
+    with patch('sentience.agent.snapshot') as mock_snapshot, \
+         patch('sentience.agent.click') as mock_click:
+
+        mock_snapshot.return_value = create_mock_snapshot()
+        # Simulate click failure
+        mock_click.side_effect = RuntimeError("Element not found")
+
+        with pytest.raises(RuntimeError, match="Failed after 2 retries"):
+            agent.act("Click invalid element", max_retries=2)
+
+        # Should have attempted 3 times (initial + 2 retries)
+        assert mock_click.call_count == 3
+
+
+def test_agent_action_parsing_variations():
+    """Test various action string format variations"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = SentienceAgent(browser, llm, verbose=False)
+
+    snap = create_mock_snapshot()
+
+    with patch('sentience.agent.click') as mock_click, \
+         patch('sentience.agent.type_text') as mock_type, \
+         patch('sentience.agent.press') as mock_press:
+
+        from sentience.models import ActionResult
+        mock_result = ActionResult(success=True, duration_ms=100, outcome="dom_updated")
+        mock_click.return_value = mock_result
+        mock_type.return_value = mock_result
+        mock_press.return_value = mock_result
+
+        # Test variations
+        agent._execute_action("click(1)", snap)  # lowercase
+        agent._execute_action("CLICK( 1 )", snap)  # extra spaces
+        agent._execute_action("TYPE(2, 'single quotes')", snap)  # single quotes
+        agent._execute_action("PRESS('Enter')", snap)  # single quotes
+        agent._execute_action("finish()", snap)  # lowercase finish
+
+        assert mock_click.call_count == 2
+        assert mock_type.call_count == 1
+        assert mock_press.call_count == 1

From 7f8f4504b8a179facc71a6783029700735771931 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Wed, 24 Dec 2025 04:52:33 -0800
Subject: [PATCH 2/2] Phase 2/2 Conversational agent support

---
 README.md                          |  60 +++-
 examples/agent_layers_demo.py      | 222 ++++++++++++
 sentience/__init__.py              |   4 +-
 sentience/conversational_agent.py  | 525 +++++++++++++++++++++++++++++
 tests/test_conversational_agent.py | 468 +++++++++++++++++++++++++
 5 files changed, 1275 insertions(+), 4 deletions(-)
 create mode 100644 examples/agent_layers_demo.py
 create mode 100644 sentience/conversational_agent.py
 create mode 100644 tests/test_conversational_agent.py

diff --git a/README.md b/README.md
index 618981b..5740ad4 100644
--- a/README.md
+++ b/README.md
@@ -9,16 +9,66 @@ pip install -e .
 
 # Install Playwright browsers (required)
 playwright install chromium
+
+# For LLM Agent features (optional)
+pip install openai  # For OpenAI models
+pip install anthropic  # For Claude models
+pip install transformers torch  # For local LLMs
+```
+
+## Quick Start: Choose Your Abstraction Level
+
+Sentience SDK offers **three abstraction levels** - use what fits your needs:
+
+### 🎯 **Level 3: Natural Language (Easiest)** - For non-technical users
+
+```python
+from sentience import SentienceBrowser, ConversationalAgent
+from sentience.llm_provider import OpenAIProvider
+
+browser = SentienceBrowser()
+llm = OpenAIProvider(api_key="your-key", model="gpt-4o")
+agent = ConversationalAgent(browser, llm)
+
+with browser:
+    response = agent.execute("Search for magic mouse on google.com")
+    print(response)
+    # → "I searched for 'magic mouse' and found several results.
+    #    The top result is from amazon.com selling Magic Mouse 2 for $79."
 ```
 
-## Quick Start
+**Best for:** End users, chatbots, no-code platforms
+**Code required:** 3-5 lines
+**Technical knowledge:** None
+
+### ⚙️ **Level 2: Technical Commands (Recommended)** - For AI developers
+
+```python
+from sentience import SentienceBrowser, SentienceAgent
+from sentience.llm_provider import OpenAIProvider
+
+browser = SentienceBrowser()
+llm = OpenAIProvider(api_key="your-key", model="gpt-4o")
+agent = SentienceAgent(browser, llm)
+
+with browser:
+    browser.page.goto("https://google.com")
+    agent.act("Click the search box")
+    agent.act("Type 'magic mouse' into the search field")
+    agent.act("Press Enter key")
+```
+
+**Best for:** Building AI agents, automation scripts
+**Code required:** 10-15 lines
+**Technical knowledge:** Medium (Python basics)
+
+### 🔧 **Level 1: Direct SDK (Most Control)** - For production automation
 
 ```python
 from sentience import SentienceBrowser, snapshot, find, click
 
-# Start browser with extension
 with SentienceBrowser(headless=False) as browser:
-    browser.goto("https://example.com", wait_until="domcontentloaded")
+    browser.page.goto("https://example.com")
 
     # Take snapshot - captures all interactive elements
     snap = snapshot(browser)
@@ -31,6 +81,10 @@ with SentienceBrowser(headless=False) as browser:
         print(f"Click success: {result.success}")
 ```
 
+**Best for:** Maximum control, performance-critical apps
+**Code required:** 20-50 lines
+**Technical knowledge:** High (SDK API, selectors)
+
 ## Real-World Example: Amazon Shopping Bot
 
 This example demonstrates navigating Amazon, finding products, and adding items to cart:
diff --git a/examples/agent_layers_demo.py b/examples/agent_layers_demo.py
new file mode 100644
index 0000000..c5432e7
--- /dev/null
+++ b/examples/agent_layers_demo.py
@@ -0,0 +1,222 @@
+"""
+Demonstration of all three abstraction layers in Sentience SDK
+
+Layer 1: Direct SDK (Full Control)
+Layer 2: SentienceAgent (Technical Commands)
+Layer 3: ConversationalAgent (Natural Language)
+
+This script shows how the same task can be accomplished at different abstraction levels.
+"""
+
+import os
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+def demo_layer1_direct_sdk():
+    """
+    Layer 1: Direct SDK Usage
+    - Full control over every action
+    - Requires knowing exact element selectors
+    - 50+ lines of code for typical automation
+    """
+    print("\n" + "="*70)
+    print("LAYER 1: Direct SDK Usage (Full Control)")
+    print("="*70)
+
+    from sentience import SentienceBrowser, snapshot, find, click, type_text, press
+
+    with SentienceBrowser(headless=False) as browser:
+        # Navigate
+        browser.page.goto("https://google.com")
+
+        # Get snapshot
+        snap = snapshot(browser)
+
+        # Find search box manually
+        search_box = find(snap, "role=searchbox")
+        if not search_box:
+            search_box = find(snap, "role=textbox")
+
+        # Click search box
+        click(browser, search_box.id)
+
+        # Type query
+        type_text(browser, search_box.id, "magic mouse")
+
+        # Press Enter
+        press(browser, "Enter")
+
+        print("\n✅ Layer 1 Demo Complete")
+        print("   Code required: ~20 lines")
+        print("   Technical knowledge: High")
+        print("   Flexibility: Maximum")
+
+
+def demo_layer2_sentience_agent():
+    """
+    Layer 2: SentienceAgent (Technical Commands)
+    - High-level commands with LLM intelligence
+    - No need to know selectors
+    - 15 lines of code for typical automation
+    """
+    print("\n" + "="*70)
+    print("LAYER 2: SentienceAgent (Technical Commands)")
+    print("="*70)
+
+    from sentience import SentienceBrowser, SentienceAgent
+    from sentience.llm_provider import OpenAIProvider
+
+    # Initialize
+    browser = SentienceBrowser(headless=False)
+    llm = OpenAIProvider(api_key=os.getenv("OPENAI_API_KEY"), model="gpt-4o-mini")
+    agent = SentienceAgent(browser, llm, verbose=True)
+
+    with browser:
+        browser.page.goto("https://google.com")
+
+        # Execute technical commands
+        agent.act("Click the search box")
+        agent.act("Type 'magic mouse' into the search field")
+        agent.act("Press Enter key")
+
+        print("\n✅ Layer 2 Demo Complete")
+        print("   Code required: ~10 lines")
+        print("   Technical knowledge: Medium")
+        print("   Flexibility: High")
+        print(f"   Tokens used: {agent.get_token_stats()['total_tokens']}")
+
+
+def demo_layer3_conversational_agent():
+    """
+    Layer 3: ConversationalAgent (Natural Language)
+    - Pure natural language interface
+    - Automatic planning and execution
+    - 3 lines of code for typical automation
+    """
+    print("\n" + "="*70)
+    print("LAYER 3: ConversationalAgent (Natural Language)")
+    print("="*70)
+
+    from sentience import SentienceBrowser, ConversationalAgent
+    from sentience.llm_provider import OpenAIProvider
+
+    # Initialize
+    browser = SentienceBrowser(headless=False)
+    llm = OpenAIProvider(api_key=os.getenv("OPENAI_API_KEY"), model="gpt-4o")
+    agent = ConversationalAgent(browser, llm, verbose=True)
+
+    with browser:
+        # Execute in natural language (agent plans and executes automatically)
+        response = agent.execute("Search for magic mouse on google.com")
+
+        print("\n✅ Layer 3 Demo Complete")
+        print("   Code required: ~5 lines")
+        print("   Technical knowledge: None")
+        print("   Flexibility: Medium")
+        print(f"   Agent Response: {response}")
+
+
+def demo_layer3_with_local_llm():
+    """
+    Layer 3 with Local LLM (Zero Cost)
+    - Uses local Qwen 2.5 3B model
+    - No API costs
+    - Runs on your hardware
+    """
+    print("\n" + "="*70)
+    print("LAYER 3: ConversationalAgent with Local LLM (Zero Cost)")
+    print("="*70)
+
+    from sentience import SentienceBrowser, ConversationalAgent
+    from sentience.llm_provider import LocalLLMProvider
+
+    # Initialize with local LLM
+    browser = SentienceBrowser(headless=False)
+    llm = LocalLLMProvider(
+        model_name="Qwen/Qwen2.5-3B-Instruct",
+        device="auto",  # Use CUDA if available
+        load_in_4bit=True  # Save memory with quantization
+    )
+    agent = ConversationalAgent(browser, llm, verbose=True)
+
+    with browser:
+        # Execute in natural language
+        response = agent.execute("Go to google.com and search for python tutorials")
+
+        print("\n✅ Layer 3 with Local LLM Demo Complete")
+        print("   API Cost: $0 (runs locally)")
+        print("   Privacy: 100% (no data sent to cloud)")
+        print(f"   Agent Response: {response}")
+
+
+def demo_comparison():
+    """
+    Side-by-side comparison of all layers
+    """
+    print("\n" + "="*70)
+    print("COMPARISON: All Three Layers")
+    print("="*70)
+
+    comparison_table = """
+    | Feature                  | Layer 1 (SDK)    | Layer 2 (Agent)  | Layer 3 (Conversational) |
+    |--------------------------|------------------|------------------|--------------------------|
+    | Lines of code            | 50+              | 15               | 3-5                      |
+    | Technical knowledge      | High             | Medium           | None                     |
+    | Requires selectors?      | Yes              | No               | No                       |
+    | LLM required?            | No               | Yes              | Yes                      |
+    | Cost per action          | $0               | ~$0.005          | ~$0.010                  |
+    | Speed                    | Fastest          | Fast             | Medium                   |
+    | Error handling           | Manual           | Auto-retry       | Auto-recovery            |
+    | Multi-step planning      | Manual           | Manual           | Automatic                |
+    | Natural language I/O     | No               | Commands only    | Full conversation        |
+    | Best for                 | Production       | AI developers    | End users                |
+    """
+
+    print(comparison_table)
+
+
+def main():
+    """Run all demos"""
+    print("\n" + "="*70)
+    print("SENTIENCE SDK: Multi-Layer Abstraction Demo")
+    print("="*70)
+    print("\nThis demo shows how to use the SDK at different abstraction levels:")
+    print("  1. Layer 1: Direct SDK (maximum control)")
+    print("  2. Layer 2: SentienceAgent (technical commands)")
+    print("  3. Layer 3: ConversationalAgent (natural language)")
+    print("\nChoose which demo to run:")
+    print("  1 - Layer 1: Direct SDK")
+    print("  2 - Layer 2: SentienceAgent")
+    print("  3 - Layer 3: ConversationalAgent (OpenAI)")
+    print("  4 - Layer 3: ConversationalAgent (Local LLM)")
+    print("  5 - Show comparison table")
+    print("  0 - Exit")
+
+    choice = input("\nEnter your choice (0-5): ").strip()
+
+    if choice == "1":
+        demo_layer1_direct_sdk()
+    elif choice == "2":
+        if not os.getenv("OPENAI_API_KEY"):
+            print("\n❌ Error: OPENAI_API_KEY not set")
+            return
+        demo_layer2_sentience_agent()
+    elif choice == "3":
+        if not os.getenv("OPENAI_API_KEY"):
+            print("\n❌ Error: OPENAI_API_KEY not set")
+            return
+        demo_layer3_conversational_agent()
+    elif choice == "4":
+        demo_layer3_with_local_llm()
+    elif choice == "5":
+        demo_comparison()
+    elif choice == "0":
+        print("Goodbye!")
+    else:
+        print("Invalid choice")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/sentience/__init__.py b/sentience/__init__.py
index f5f59e1..31094a3 100644
--- a/sentience/__init__.py
+++ b/sentience/__init__.py
@@ -18,6 +18,7 @@
 # Agent Layer (Phase 1 & 2)
 from .llm_provider import LLMProvider, LLMResponse, OpenAIProvider, AnthropicProvider, LocalLLMProvider
 from .agent import SentienceAgent
+from .conversational_agent import ConversationalAgent
 
 __version__ = "0.10.7"
 
@@ -49,12 +50,13 @@
     "generate",
     "read",
     "screenshot",
-    # Agent Layer
+    # Agent Layer (Phase 1 & 2)
     "LLMProvider",
     "LLMResponse",
     "OpenAIProvider",
     "AnthropicProvider",
     "LocalLLMProvider",
     "SentienceAgent",
+    "ConversationalAgent",
 ]
 
diff --git a/sentience/conversational_agent.py b/sentience/conversational_agent.py
new file mode 100644
index 0000000..c3f4e83
--- /dev/null
+++ b/sentience/conversational_agent.py
@@ -0,0 +1,525 @@
+"""
+Conversational Agent: Natural language interface for Sentience SDK
+Enables end users to control web automation using plain English
+"""
+
+import json
+import time
+from typing import Dict, Any, List, Optional
+from .llm_provider import LLMProvider, LLMResponse
+from .browser import SentienceBrowser
+from .agent import SentienceAgent
+from .snapshot import snapshot
+from .models import Snapshot
+
+
+class ConversationalAgent:
+    """
+    Natural language agent that translates user intent into SDK actions
+    and returns human-readable results.
+
+    This is Layer 4 - the highest abstraction level for non-technical users.
+
+    Example:
+        >>> agent = ConversationalAgent(browser, llm)
+        >>> result = agent.execute("Search for magic mouse on google.com")
+        >>> print(result)
+        "I searched for 'magic mouse' on Google and found several results.
+         The top result is from amazon.com selling the Apple Magic Mouse 2 for $79."
+    """
+
+    def __init__(
+        self,
+        browser: SentienceBrowser,
+        llm: LLMProvider,
+        verbose: bool = True
+    ):
+        """
+        Initialize conversational agent
+
+        Args:
+            browser: SentienceBrowser instance
+            llm: LLM provider (OpenAI, Anthropic, LocalLLM, etc.)
+            verbose: Print step-by-step execution logs (default: True)
+        """
+        self.browser = browser
+        self.llm = llm
+        self.verbose = verbose
+
+        # Underlying technical agent
+        self.technical_agent = SentienceAgent(browser, llm, verbose=False)
+
+        # Conversation history and context
+        self.conversation_history: List[Dict[str, Any]] = []
+        self.execution_context: Dict[str, Any] = {
+            "current_url": None,
+            "last_action": None,
+            "discovered_elements": [],
+            "session_data": {}
+        }
+
+    def execute(self, user_input: str) -> str:
+        """
+        Execute a natural language command and return natural language result
+
+        Args:
+            user_input: Natural language instruction (e.g., "Search for magic mouse")
+
+        Returns:
+            Human-readable result description
+
+        Example:
+            >>> agent.execute("Go to google.com and search for magic mouse")
+            "I navigated to google.com, searched for 'magic mouse', and found 10 results.
+             The top result is from amazon.com selling Magic Mouse 2 for $79."
+        """
+        if self.verbose:
+            print(f"\n{'='*70}")
+            print(f"👤 User: {user_input}")
+            print(f"{'='*70}")
+
+        start_time = time.time()
+
+        # Step 1: Plan the execution (break down into atomic steps)
+        plan = self._create_plan(user_input)
+
+        if self.verbose:
+            print(f"\n📋 Execution Plan:")
+            for i, step in enumerate(plan['steps'], 1):
+                print(f"  {i}. {step['description']}")
+
+        # Step 2: Execute each step
+        execution_results = []
+        for step in plan['steps']:
+            step_result = self._execute_step(step)
+            execution_results.append(step_result)
+
+            if not step_result.get('success', False):
+                # Early exit on failure
+                if self.verbose:
+                    print(f"⚠️  Step failed: {step['description']}")
+                break
+
+        # Step 3: Synthesize natural language response
+        response = self._synthesize_response(user_input, plan, execution_results)
+
+        duration_ms = int((time.time() - start_time) * 1000)
+
+        # Step 4: Update conversation history
+        self.conversation_history.append({
+            "user_input": user_input,
+            "plan": plan,
+            "results": execution_results,
+            "response": response,
+            "duration_ms": duration_ms
+        })
+
+        if self.verbose:
+            print(f"\n🤖 Agent: {response}")
+            print(f"⏱️  Completed in {duration_ms}ms\n")
+
+        return response
+
+    def _create_plan(self, user_input: str) -> Dict[str, Any]:
+        """
+        Use LLM to break down user input into atomic executable steps
+
+        Args:
+            user_input: Natural language command
+
+        Returns:
+            Plan dictionary with list of atomic steps
+        """
+        # Get current page context
+        current_url = self.browser.page.url if self.browser.page else "None"
+
+        system_prompt = """You are a web automation planning assistant.
+
+Your job is to analyze a natural language request and break it down into atomic steps
+that can be executed by a web automation agent.
+
+AVAILABLE ACTIONS:
+1. NAVIGATE - Go to a URL
+2. FIND_AND_CLICK - Find and click an element by description
+3. FIND_AND_TYPE - Find input field and type text
+4. PRESS_KEY - Press a keyboard key (Enter, Escape, etc.)
+5. WAIT - Wait for page to load or element to appear
+6. EXTRACT_INFO - Extract specific information from the page
+7. VERIFY - Verify a condition is met
+
+RESPONSE FORMAT (JSON):
+{
+  "intent": "brief summary of user intent",
+  "steps": [
+    {
+      "action": "NAVIGATE" | "FIND_AND_CLICK" | "FIND_AND_TYPE" | "PRESS_KEY" | "WAIT" | "EXTRACT_INFO" | "VERIFY",
+      "description": "human-readable description",
+      "parameters": {
+        "url": "https://...",
+        "element_description": "search box",
+        "text": "magic mouse",
+        "key": "Enter",
+        "duration": 2.0,
+        "info_type": "product link",
+        "condition": "page contains results"
+      }
+    }
+  ],
+  "expected_outcome": "what success looks like"
+}
+
+IMPORTANT: Return ONLY valid JSON, no markdown, no code blocks."""
+
+        user_prompt = f"""Current URL: {current_url}
+
+User Request: {user_input}
+
+Create a step-by-step execution plan."""
+
+        try:
+            response = self.llm.generate(
+                system_prompt,
+                user_prompt,
+                json_mode=self.llm.supports_json_mode(),
+                temperature=0.0
+            )
+
+            # Parse JSON response
+            plan = json.loads(response.content)
+            return plan
+
+        except json.JSONDecodeError as e:
+            # Fallback: create simple plan
+            if self.verbose:
+                print(f"⚠️  JSON parsing failed, using fallback plan: {e}")
+
+            return {
+                "intent": user_input,
+                "steps": [
+                    {
+                        "action": "FIND_AND_CLICK",
+                        "description": user_input,
+                        "parameters": {"element_description": user_input}
+                    }
+                ],
+                "expected_outcome": "Complete user request"
+            }
+
+    def _execute_step(self, step: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute a single atomic step from the plan
+
+        Args:
+            step: Step dictionary with action and parameters
+
+        Returns:
+            Execution result with success status and data
+        """
+        action = step['action']
+        params = step.get('parameters', {})
+
+        if self.verbose:
+            print(f"\n⚙️  Executing: {step['description']}")
+
+        try:
+            if action == "NAVIGATE":
+                url = params['url']
+                # Add https:// if missing
+                if not url.startswith(('http://', 'https://')):
+                    url = 'https://' + url
+
+                self.browser.page.goto(url, wait_until="domcontentloaded")
+                self.execution_context['current_url'] = url
+                time.sleep(1)  # Brief wait for page to settle
+
+                return {
+                    "success": True,
+                    "action": action,
+                    "data": {"url": url}
+                }
+
+            elif action == "FIND_AND_CLICK":
+                element_desc = params['element_description']
+                # Use technical agent to find and click
+                result = self.technical_agent.act(f"Click the {element_desc}")
+                return {
+                    "success": result.get('success', False),
+                    "action": action,
+                    "data": result
+                }
+
+            elif action == "FIND_AND_TYPE":
+                element_desc = params['element_description']
+                text = params['text']
+                # Use technical agent to find input and type
+                result = self.technical_agent.act(f"Type '{text}' into {element_desc}")
+                return {
+                    "success": result.get('success', False),
+                    "action": action,
+                    "data": {"text": text}
+                }
+
+            elif action == "PRESS_KEY":
+                key = params['key']
+                result = self.technical_agent.act(f"Press {key} key")
+                return {
+                    "success": result.get('success', False),
+                    "action": action,
+                    "data": {"key": key}
+                }
+
+            elif action == "WAIT":
+                duration = params.get('duration', 2.0)
+                time.sleep(duration)
+                return {
+                    "success": True,
+                    "action": action,
+                    "data": {"duration": duration}
+                }
+
+            elif action == "EXTRACT_INFO":
+                info_type = params['info_type']
+                # Get current page snapshot and extract info
+                snap = snapshot(self.browser, limit=50)
+
+                # Use LLM to extract specific information
+                extracted = self._extract_information(snap, info_type)
+
+                return {
+                    "success": True,
+                    "action": action,
+                    "data": {"extracted": extracted, "info_type": info_type}
+                }
+
+            elif action == "VERIFY":
+                condition = params['condition']
+                # Verify condition using current page state
+                is_verified = self._verify_condition(condition)
+                return {
+                    "success": is_verified,
+                    "action": action,
+                    "data": {"condition": condition, "verified": is_verified}
+                }
+
+            else:
+                raise ValueError(f"Unknown action: {action}")
+
+        except Exception as e:
+            if self.verbose:
+                print(f"❌ Step failed: {e}")
+            return {
+                "success": False,
+                "action": action,
+                "error": str(e)
+            }
+
+    def _extract_information(self, snap: Snapshot, info_type: str) -> Dict[str, Any]:
+        """
+        Extract specific information from snapshot using LLM
+
+        Args:
+            snap: Snapshot object
+            info_type: Type of info to extract (e.g., "product link", "price")
+
+        Returns:
+            Extracted information dictionary
+        """
+        # Build context from snapshot
+        elements_text = "\n".join([
+            f"[{el.id}] {el.role}: {el.text} (importance: {el.importance})"
+            for el in snap.elements[:30]  # Top 30 elements
+        ])
+
+        system_prompt = f"""Extract {info_type} from the following page elements.
+
+ELEMENTS:
+{elements_text}
+
+Return JSON with extracted information:
+{{
+  "found": true/false,
+  "data": {{
+    // extracted information fields
+  }},
+  "summary": "brief description of what was found"
+}}"""
+
+        user_prompt = f"Extract {info_type} from the elements above."
+
+        try:
+            response = self.llm.generate(
+                system_prompt,
+                user_prompt,
+                json_mode=self.llm.supports_json_mode()
+            )
+            return json.loads(response.content)
+        except:
+            return {"found": False, "data": {}, "summary": "Failed to extract information"}
+
+    def _verify_condition(self, condition: str) -> bool:
+        """
+        Verify a condition is met on current page
+
+        Args:
+            condition: Natural language condition to verify
+
+        Returns:
+            True if condition is met, False otherwise
+        """
+        try:
+            snap = snapshot(self.browser, limit=30)
+
+            # Build context
+            elements_text = "\n".join([
+                f"{el.role}: {el.text}"
+                for el in snap.elements[:20]
+            ])
+
+            system_prompt = f"""Verify if the following condition is met based on page elements.
+
+CONDITION: {condition}
+
+PAGE ELEMENTS:
+{elements_text}
+
+Return JSON:
+{{
+  "verified": true/false,
+  "reasoning": "explanation"
+}}"""
+
+            response = self.llm.generate(
+                system_prompt,
+                "",
+                json_mode=self.llm.supports_json_mode()
+            )
+            result = json.loads(response.content)
+            return result.get('verified', False)
+        except:
+            return False
+
+    def _synthesize_response(
+        self,
+        user_input: str,
+        plan: Dict[str, Any],
+        execution_results: List[Dict[str, Any]]
+    ) -> str:
+        """
+        Synthesize a natural language response from execution results
+
+        Args:
+            user_input: Original user input
+            plan: Execution plan
+            execution_results: List of step execution results
+
+        Returns:
+            Human-readable response string
+        """
+        # Build summary of what happened
+        successful_steps = [r for r in execution_results if r.get('success')]
+        failed_steps = [r for r in execution_results if not r.get('success')]
+
+        # Extract key data
+        extracted_data = []
+        for result in execution_results:
+            if result.get('action') == 'EXTRACT_INFO':
+                extracted_data.append(result.get('data', {}).get('extracted', {}))
+
+        # Use LLM to create natural response
+        system_prompt = """You are a helpful assistant that summarizes web automation results
+in natural, conversational language.
+
+Your job is to take technical execution results and convert them into a friendly,
+human-readable response that answers the user's original request.
+
+Be concise but informative. Include key findings or data discovered.
+If the task failed, explain what went wrong in simple terms.
+
+IMPORTANT: Return only the natural language response, no JSON, no markdown."""
+
+        results_summary = {
+            "user_request": user_input,
+            "plan_intent": plan.get('intent'),
+            "total_steps": len(execution_results),
+            "successful_steps": len(successful_steps),
+            "failed_steps": len(failed_steps),
+            "extracted_data": extracted_data,
+            "final_url": self.browser.page.url if self.browser.page else None
+        }
+
+        user_prompt = f"""Summarize these automation results in 1-3 natural sentences:
+
+{json.dumps(results_summary, indent=2)}
+
+Respond as if you're talking to a user, not listing technical details."""
+
+        try:
+            response = self.llm.generate(system_prompt, user_prompt, temperature=0.3)
+            return response.content.strip()
+        except:
+            # Fallback response
+            if failed_steps:
+                return f"I attempted to {user_input}, but encountered an error during execution."
+            else:
+                return f"I completed your request: {user_input}"
+
+    def chat(self, message: str) -> str:
+        """
+        Conversational interface with context awareness
+
+        Args:
+            message: User message (can reference previous context)
+
+        Returns:
+            Agent response
+
+        Example:
+            >>> agent.chat("Go to google.com")
+            "I've navigated to google.com"
+            >>> agent.chat("Search for magic mouse")  # Contextual
+            "I searched for 'magic mouse' and found 10 results"
+        """
+        return self.execute(message)
+
+    def get_summary(self) -> str:
+        """
+        Get a summary of the entire conversation/session
+
+        Returns:
+            Natural language summary of all actions taken
+        """
+        if not self.conversation_history:
+            return "No actions have been performed yet."
+
+        system_prompt = """Summarize this web automation session in a brief, natural paragraph.
+Focus on what was accomplished and key findings."""
+
+        session_data = {
+            "total_interactions": len(self.conversation_history),
+            "actions": [
+                {
+                    "request": h['user_input'],
+                    "outcome": h['response']
+                }
+                for h in self.conversation_history
+            ]
+        }
+
+        user_prompt = f"Summarize this session:\n{json.dumps(session_data, indent=2)}"
+
+        try:
+            summary = self.llm.generate(system_prompt, user_prompt)
+            return summary.content.strip()
+        except:
+            return f"Session with {len(self.conversation_history)} interactions completed."
+
+    def clear_history(self):
+        """Clear conversation history"""
+        self.conversation_history.clear()
+        self.technical_agent.clear_history()
+        self.execution_context = {
+            "current_url": None,
+            "last_action": None,
+            "discovered_elements": [],
+            "session_data": {}
+        }
diff --git a/tests/test_conversational_agent.py b/tests/test_conversational_agent.py
new file mode 100644
index 0000000..7411be9
--- /dev/null
+++ b/tests/test_conversational_agent.py
@@ -0,0 +1,468 @@
+"""
+Integration tests for ConversationalAgent (Phase 2)
+Tests natural language interface without requiring browser
+"""
+
+import pytest
+import json
+from unittest.mock import Mock, MagicMock, patch
+from sentience.conversational_agent import ConversationalAgent
+from sentience.llm_provider import LLMProvider, LLMResponse
+from sentience.models import Snapshot, Element, BBox, VisualCues, Viewport
+
+
+class MockLLMProvider(LLMProvider):
+    """Mock LLM provider for testing conversational agent"""
+
+    def __init__(self, responses=None):
+        self.responses = responses or {}
+        self.call_count = 0
+        self.calls = []
+
+    def generate(self, system_prompt: str, user_prompt: str, **kwargs):
+        self.calls.append({
+            "system": system_prompt,
+            "user": user_prompt,
+            "kwargs": kwargs
+        })
+
+        # Determine response based on content
+        if "planning assistant" in system_prompt.lower():
+            # Return plan
+            response = self.responses.get('plan', self._default_plan())
+        elif "extract" in system_prompt.lower():
+            # Return extraction result
+            response = self.responses.get('extract', '{"found": true, "data": {}, "summary": "Info extracted"}')
+        elif "verify" in system_prompt.lower():
+            # Return verification result
+            response = self.responses.get('verify', '{"verified": true, "reasoning": "Condition met"}')
+        elif "summarize" in system_prompt.lower():
+            # Return summary
+            response = self.responses.get('summary', "Task completed successfully")
+        else:
+            # Default technical agent response
+            response = self.responses.get('action', "CLICK(1)")
+
+        self.call_count += 1
+
+        return LLMResponse(
+            content=response,
+            prompt_tokens=100,
+            completion_tokens=20,
+            total_tokens=120,
+            model_name="mock-model"
+        )
+
+    def _default_plan(self):
+        return json.dumps({
+            "intent": "Test intent",
+            "steps": [
+                {
+                    "action": "NAVIGATE",
+                    "description": "Go to test.com",
+                    "parameters": {"url": "https://test.com"}
+                }
+            ],
+            "expected_outcome": "Success"
+        })
+
+    def supports_json_mode(self) -> bool:
+        return True
+
+    @property
+    def model_name(self) -> str:
+        return "mock-model"
+
+
+def create_mock_browser():
+    """Create mock browser for testing"""
+    browser = Mock()
+    browser.page = Mock()
+    browser.page.url = "https://test.com"
+    browser.page.goto = Mock()
+    return browser
+
+
+def create_mock_snapshot():
+    """Create mock snapshot with test elements"""
+    elements = [
+        Element(
+            id=1,
+            role="button",
+            text="Click Me",
+            importance=900,
+            bbox=BBox(x=100, y=200, width=80, height=30),
+            visual_cues=VisualCues(
+                is_primary=True,
+                is_clickable=True,
+                background_color_name="blue"
+            ),
+            in_viewport=True,
+            is_occluded=False,
+            z_index=10
+        )
+    ]
+
+    return Snapshot(
+        status="success",
+        timestamp="2024-12-24T10:00:00Z",
+        url="https://test.com",
+        viewport=Viewport(width=1920, height=1080),
+        elements=elements
+    )
+
+
+# ========== ConversationalAgent Tests ==========
+
+def test_conversational_agent_initialization():
+    """Test ConversationalAgent initialization"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    assert agent.browser == browser
+    assert agent.llm == llm
+    assert agent.verbose is False
+    assert len(agent.conversation_history) == 0
+    assert agent.technical_agent is not None
+
+
+def test_create_plan():
+    """Test plan creation from natural language"""
+    browser = create_mock_browser()
+
+    plan_json = json.dumps({
+        "intent": "Search for magic mouse",
+        "steps": [
+            {
+                "action": "NAVIGATE",
+                "description": "Go to google.com",
+                "parameters": {"url": "https://google.com"}
+            },
+            {
+                "action": "FIND_AND_CLICK",
+                "description": "Click search box",
+                "parameters": {"element_description": "search box"}
+            }
+        ],
+        "expected_outcome": "Search initiated"
+    })
+
+    llm = MockLLMProvider(responses={'plan': plan_json})
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    plan = agent._create_plan("Search for magic mouse on google")
+
+    assert plan['intent'] == "Search for magic mouse"
+    assert len(plan['steps']) == 2
+    assert plan['steps'][0]['action'] == "NAVIGATE"
+    assert plan['steps'][1]['action'] == "FIND_AND_CLICK"
+
+
+def test_create_plan_json_fallback():
+    """Test plan creation with invalid JSON fallback"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider(responses={'plan': 'INVALID JSON{'})
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    plan = agent._create_plan("Click button")
+
+    # Should fall back to simple plan
+    assert 'intent' in plan
+    assert 'steps' in plan
+    assert len(plan['steps']) > 0
+
+
+def test_execute_navigate_step():
+    """Test NAVIGATE step execution"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    step = {
+        "action": "NAVIGATE",
+        "description": "Go to google.com",
+        "parameters": {"url": "google.com"}  # Without https://
+    }
+
+    result = agent._execute_step(step)
+
+    assert result['success'] is True
+    assert result['action'] == "NAVIGATE"
+    browser.page.goto.assert_called_once()
+    # Should have added https://
+    assert "https://google.com" in str(browser.page.goto.call_args)
+
+
+def test_execute_find_and_click_step():
+    """Test FIND_AND_CLICK step execution"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider(responses={'action': 'CLICK(1)'})
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    step = {
+        "action": "FIND_AND_CLICK",
+        "description": "Click the button",
+        "parameters": {"element_description": "button"}
+    }
+
+    # Patch at the agent module level where it's imported
+    with patch('sentience.agent.snapshot') as mock_snapshot, \
+         patch('sentience.agent.click') as mock_click:
+
+        from sentience.models import ActionResult
+        mock_snapshot.return_value = create_mock_snapshot()
+        mock_click.return_value = ActionResult(
+            success=True,
+            duration_ms=150,
+            outcome="dom_updated"
+        )
+
+        result = agent._execute_step(step)
+
+        assert result['action'] == "FIND_AND_CLICK"
+        # Technical agent should have been called
+        assert len(agent.technical_agent.history) > 0
+
+
+def test_execute_find_and_type_step():
+    """Test FIND_AND_TYPE step execution"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider(responses={'action': 'TYPE(1, "test")'})
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    step = {
+        "action": "FIND_AND_TYPE",
+        "description": "Type into search box",
+        "parameters": {
+            "element_description": "search box",
+            "text": "magic mouse"
+        }
+    }
+
+    # Patch at the agent module level where it's imported
+    with patch('sentience.agent.snapshot') as mock_snapshot, \
+         patch('sentience.agent.type_text') as mock_type:
+
+        from sentience.models import ActionResult
+        mock_snapshot.return_value = create_mock_snapshot()
+        mock_type.return_value = ActionResult(
+            success=True,
+            duration_ms=200,
+            outcome="dom_updated"
+        )
+
+        result = agent._execute_step(step)
+
+        assert result['action'] == "FIND_AND_TYPE"
+        assert result['data']['text'] == "magic mouse"
+
+
+def test_execute_wait_step():
+    """Test WAIT step execution"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    step = {
+        "action": "WAIT",
+        "description": "Wait for page to load",
+        "parameters": {"duration": 0.1}  # Short wait for testing
+    }
+
+    result = agent._execute_step(step)
+
+    assert result['success'] is True
+    assert result['action'] == "WAIT"
+    assert result['data']['duration'] == 0.1
+
+
+def test_execute_extract_info_step():
+    """Test EXTRACT_INFO step execution"""
+    browser = create_mock_browser()
+
+    extract_response = json.dumps({
+        "found": True,
+        "data": {"price": "$79"},
+        "summary": "Found price information"
+    })
+
+    llm = MockLLMProvider(responses={'extract': extract_response})
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    step = {
+        "action": "EXTRACT_INFO",
+        "description": "Extract price",
+        "parameters": {"info_type": "product price"}
+    }
+
+    with patch('sentience.conversational_agent.snapshot') as mock_snapshot:
+        mock_snapshot.return_value = create_mock_snapshot()
+
+        result = agent._execute_step(step)
+
+        assert result['success'] is True
+        assert result['action'] == "EXTRACT_INFO"
+        assert result['data']['extracted']['found'] is True
+
+
+def test_execute_verify_step():
+    """Test VERIFY step execution"""
+    browser = create_mock_browser()
+
+    verify_response = json.dumps({
+        "verified": True,
+        "reasoning": "Page contains results"
+    })
+
+    llm = MockLLMProvider(responses={'verify': verify_response})
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    step = {
+        "action": "VERIFY",
+        "description": "Verify results",
+        "parameters": {"condition": "page contains search results"}
+    }
+
+    with patch('sentience.conversational_agent.snapshot') as mock_snapshot:
+        mock_snapshot.return_value = create_mock_snapshot()
+
+        result = agent._execute_step(step)
+
+        assert result['success'] is True
+        assert result['action'] == "VERIFY"
+        assert result['data']['verified'] is True
+
+
+def test_synthesize_response():
+    """Test natural language response synthesis"""
+    browser = create_mock_browser()
+
+    llm = MockLLMProvider(responses={
+        'summary': "I navigated to google.com and found the search results you requested."
+    })
+
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    plan = {
+        "intent": "Search for magic mouse",
+        "steps": [],
+        "expected_outcome": "Success"
+    }
+
+    execution_results = [
+        {"success": True, "action": "NAVIGATE"}
+    ]
+
+    response = agent._synthesize_response("Search for magic mouse", plan, execution_results)
+
+    assert isinstance(response, str)
+    assert len(response) > 0
+
+
+def test_execute_full_workflow():
+    """Test full execute() workflow"""
+    browser = create_mock_browser()
+
+    plan_json = json.dumps({
+        "intent": "Navigate to test site",
+        "steps": [
+            {
+                "action": "NAVIGATE",
+                "description": "Go to test.com",
+                "parameters": {"url": "https://test.com"}
+            }
+        ],
+        "expected_outcome": "Navigation complete"
+    })
+
+    llm = MockLLMProvider(responses={
+        'plan': plan_json,
+        'summary': "Successfully navigated to test.com"
+    })
+
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    response = agent.execute("Go to test.com")
+
+    assert isinstance(response, str)
+    assert len(agent.conversation_history) == 1
+    assert agent.conversation_history[0]['user_input'] == "Go to test.com"
+
+
+def test_chat_method():
+    """Test chat() method as alias for execute()"""
+    browser = create_mock_browser()
+
+    plan_json = json.dumps({
+        "intent": "Test",
+        "steps": [],
+        "expected_outcome": "Done"
+    })
+
+    llm = MockLLMProvider(responses={
+        'plan': plan_json,
+        'summary': "Task complete"
+    })
+
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    response = agent.chat("Test message")
+
+    assert isinstance(response, str)
+    assert len(agent.conversation_history) == 1
+
+
+def test_get_summary():
+    """Test session summary generation"""
+    browser = create_mock_browser()
+
+    llm = MockLLMProvider(responses={
+        'plan': '{"intent": "test", "steps": [], "expected_outcome": "done"}',
+        'summary': "Session completed with 2 interactions"
+    })
+
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    # Add some history
+    agent.conversation_history.append({
+        "user_input": "Test 1",
+        "response": "Done 1"
+    })
+    agent.conversation_history.append({
+        "user_input": "Test 2",
+        "response": "Done 2"
+    })
+
+    summary = agent.get_summary()
+
+    assert isinstance(summary, str)
+    assert len(summary) > 0
+
+
+def test_get_summary_empty_history():
+    """Test summary with no history"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    summary = agent.get_summary()
+
+    assert summary == "No actions have been performed yet."
+
+
+def test_clear_history():
+    """Test clearing conversation history"""
+    browser = create_mock_browser()
+    llm = MockLLMProvider()
+    agent = ConversationalAgent(browser, llm, verbose=False)
+
+    # Add history
+    agent.conversation_history.append({"test": "data"})
+    agent.technical_agent.history.append({"test": "data"})
+
+    agent.clear_history()
+
+    assert len(agent.conversation_history) == 0
+    assert len(agent.technical_agent.history) == 0