initial commit sentience sdk for python

Author: SentienceDEV

README.md

@@ -0,0 +1,81 @@
+# Sentience Python SDK
+
+**Status**: ✅ Week 1 Complete
+
+Python SDK for Sentience AI Agent Browser Automation.
+
+## Installation
+
+```bash
+cd sdk-python
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from sentience import SentienceBrowser, snapshot, find, click
+
+# Start browser with extension
+with SentienceBrowser(headless=False) as browser:
+    browser.page.goto("https://example.com")
+    browser.page.wait_for_load_state("networkidle")
+    
+    # Take snapshot
+    snap = snapshot(browser)
+    print(f"Found {len(snap.elements)} elements")
+    
+    # Find and click a link
+    link = find(snap, "role=link")
+    if link:
+        result = click(browser, link.id)
+        print(f"Click success: {result.success}")
+```
+
+## Features
+
+### Day 2: Browser Harness
+- `SentienceBrowser` - Launch Playwright with extension loaded
+- Automatic extension loading and verification
+
+### Day 3: Snapshot
+- `snapshot(browser, options)` - Capture page state
+- Pydantic models for type safety
+- `snapshot.save(filepath)` - Save to JSON
+
+### Day 4: Query Engine
+- `query(snapshot, selector)` - Find elements matching selector
+- `find(snapshot, selector)` - Find single best match
+- String DSL: `"role=button text~'Sign in'"`
+
+### Day 5: Actions
+- `click(browser, element_id)` - Click element
+- `type_text(browser, element_id, text)` - Type into element
+- `press(browser, key)` - Press keyboard key
+
+### Day 6: Wait & Assert
+- `wait_for(browser, selector, timeout)` - Wait for element
+- `expect(browser, selector)` - Assertion helper
+  - `.to_exist()`
+  - `.to_be_visible()`
+  - `.to_have_text(text)`
+  - `.to_have_count(n)`
+
+## Examples
+
+See `examples/` directory:
+- `hello.py` - Extension bridge verification
+- `basic_agent.py` - Basic snapshot
+- `query_demo.py` - Query engine
+- `wait_and_click.py` - Wait and actions
+
+## Testing
+
+```bash
+pytest tests/
+```
+
+## Documentation
+
+- API Contract: `../spec/SNAPSHOT_V1.md`
+- Type Definitions: `../spec/sdk-types.md`

examples/basic_agent.py

@@ -0,0 +1,33 @@
+"""
+Day 3 Example: Basic snapshot functionality
+"""
+
+from sentience import SentienceBrowser, snapshot
+
+
+def main():
+    with SentienceBrowser(headless=False) as browser:
+        # Navigate to a test page
+        browser.page.goto("https://example.com")
+        browser.page.wait_for_load_state("networkidle")
+        
+        # Take snapshot
+        snap = snapshot(browser)
+        
+        print(f"Status: {snap.status}")
+        print(f"URL: {snap.url}")
+        print(f"Elements found: {len(snap.elements)}")
+        
+        # Show top 5 elements
+        print("\nTop 5 elements:")
+        for i, el in enumerate(snap.elements[:5], 1):
+            print(f"{i}. [{el.role}] {el.text or '(no text)'} (importance: {el.importance})")
+        
+        # Save snapshot
+        snap.save("snapshot_example.json")
+        print("\n✅ Snapshot saved to snapshot_example.json")
+
+
+if __name__ == "__main__":
+    main()
+

examples/hello.py

@@ -0,0 +1,22 @@
+"""
+Day 2 Example: Verify extension bridge is loaded
+"""
+
+from sentience import SentienceBrowser
+
+
+def main():
+    with SentienceBrowser(headless=False) as browser:
+        # Check if extension API is available
+        bridge_ok = browser.page.evaluate("typeof window.sentience !== 'undefined'")
+        print(f"bridge_ok={bridge_ok}")
+        
+        if bridge_ok:
+            print("✅ Extension loaded successfully!")
+        else:
+            print("❌ Extension not loaded")
+
+
+if __name__ == "__main__":
+    main()
+

examples/query_demo.py

@@ -0,0 +1,45 @@
+"""
+Day 4 Example: Query engine demonstration
+"""
+
+from sentience import SentienceBrowser, snapshot, query, find
+
+
+def main():
+    with SentienceBrowser(headless=False) as browser:
+        # Navigate to a page with links
+        browser.page.goto("https://example.com")
+        browser.page.wait_for_load_state("networkidle")
+        
+        snap = snapshot(browser)
+        
+        # Query examples
+        print("=== Query Examples ===\n")
+        
+        # Find all buttons
+        buttons = query(snap, "role=button")
+        print(f"Found {len(buttons)} buttons")
+        
+        # Find all links
+        links = query(snap, "role=link")
+        print(f"Found {len(links)} links")
+        
+        # Find clickable elements
+        clickables = query(snap, "clickable=true")
+        print(f"Found {len(clickables)} clickable elements")
+        
+        # Find element with text containing "More"
+        more_link = find(snap, "text~'More'")
+        if more_link:
+            print(f"\nFound 'More' link: {more_link.text} (id: {more_link.id})")
+        else:
+            print("\nNo 'More' link found")
+        
+        # Complex query: clickable links
+        clickable_links = query(snap, "role=link clickable=true")
+        print(f"\nFound {len(clickable_links)} clickable links")
+
+
+if __name__ == "__main__":
+    main()
+

examples/wait_and_click.py

@@ -0,0 +1,55 @@
+"""
+Day 5-6 Example: Wait for element and click
+"""
+
+from sentience import SentienceBrowser, snapshot, find, wait_for, click, expect
+
+
+def main():
+    with SentienceBrowser(headless=False) as browser:
+        # Navigate to example.com
+        browser.page.goto("https://example.com")
+        browser.page.wait_for_load_state("networkidle")
+        
+        # Take initial snapshot
+        snap = snapshot(browser)
+        
+        # Find a link
+        link = find(snap, "role=link")
+        
+        if link:
+            print(f"Found link: {link.text} (id: {link.id})")
+            
+            # Click it
+            result = click(browser, link.id)
+            print(f"Click result: success={result.success}, outcome={result.outcome}")
+            
+            # Wait for navigation
+            browser.page.wait_for_load_state("networkidle")
+            print(f"New URL: {browser.page.url}")
+        else:
+            print("No link found")
+        
+        # Example: Wait for element using wait_for
+        print("\n=== Wait Example ===")
+        browser.page.goto("https://example.com")
+        browser.page.wait_for_load_state("networkidle")
+        
+        wait_result = wait_for(browser, "role=link", timeout=5.0)
+        if wait_result.found:
+            print(f"✅ Found element after {wait_result.duration_ms}ms")
+        else:
+            print(f"❌ Element not found (timeout: {wait_result.timeout})")
+        
+        # Example: Expect assertion
+        print("\n=== Expect Example ===")
+        try:
+            element = expect(browser, "role=link").to_exist(timeout=5.0)
+            print(f"✅ Element exists: {element.text}")
+        except AssertionError as e:
+            print(f"❌ Assertion failed: {e}")
+
+
+if __name__ == "__main__":
+    main()
+

package-lock.json

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sentience-python"
+version = "0.1.0"
+description = "Python SDK for Sentience AI Agent Browser Automation"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "playwright>=1.40.0",
+    "pydantic>=2.0.0",
+    "jsonschema>=4.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sentience*"]
+

pyproject.toml

@@ -0,0 +1,7 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+asyncio_mode = auto
+

pytest.ini

@@ -0,0 +1,30 @@
+"""
+Sentience Python SDK - AI Agent Browser Automation
+"""
+
+from .browser import SentienceBrowser
+from .models import Snapshot, Element, BBox, Viewport, ActionResult, WaitResult
+from .query import query, find
+from .actions import click, type_text, press
+from .wait import wait_for
+from .expect import expect
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SentienceBrowser",
+    "Snapshot",
+    "Element",
+    "BBox",
+    "Viewport",
+    "ActionResult",
+    "WaitResult",
+    "query",
+    "find",
+    "click",
+    "type_text",
+    "press",
+    "wait_for",
+    "expect",
+]
+