Merge pull request #56 from SentienceAPI/refactor_phase1.1_1.2

Phase 1.1-1.2 Producer

Author: rcholic

.python-version

@@ -0,0 +1 @@
+3.11.5

CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to the Sentience Python SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.12.0] - 2025-12-26
+
+### Added
+
+#### Agent Tracing & Debugging
+- **New Module: `sentience.tracing`** - Built-in tracing infrastructure for debugging and analyzing agent behavior
+  - `Tracer` class for recording agent execution
+  - `TraceSink` abstract base class for custom trace storage
+  - `JsonlTraceSink` for saving traces to JSONL files
+  - `TraceEvent` dataclass for structured trace events
+  - Trace events: `step_start`, `snapshot`, `llm_query`, `action`, `step_end`, `error`
+- **New Module: `sentience.agent_config`** - Centralized agent configuration
+  - `AgentConfig` dataclass with defaults for snapshot limits, LLM settings, screenshot options
+- **New Module: `sentience.utils`** - Snapshot digest utilities
+  - `compute_snapshot_digests()` - Generate SHA256 fingerprints for loop detection
+  - `canonical_snapshot_strict()` - Digest including element text
+  - `canonical_snapshot_loose()` - Digest excluding text (layout only)
+  - `sha256_digest()` - Hash computation helper
+- **New Module: `sentience.formatting`** - LLM prompt formatting
+  - `format_snapshot_for_llm()` - Convert snapshots to LLM-friendly text format
+- **Schema File: `sentience/schemas/trace_v1.json`** - JSON Schema for trace events, bundled with package
+
+#### Enhanced SentienceAgent
+- Added optional `tracer` parameter to `SentienceAgent.__init__()` for execution tracking
+- Added optional `config` parameter to `SentienceAgent.__init__()` for advanced configuration
+- Automatic tracing throughout `act()` method when tracer is provided
+- All tracing is **opt-in** - backward compatible with existing code
+
+### Changed
+- Bumped version from `0.11.0` to `0.12.0`
+- Updated `__init__.py` to export new modules: `AgentConfig`, `Tracer`, `TraceSink`, `JsonlTraceSink`, `TraceEvent`, and utility functions
+- Added `MANIFEST.in` to include JSON schema files in package distribution
+
+### Fixed
+- Fixed linting errors across multiple files:
+  - `sentience/cli.py` - Removed unused variable `code` (F841)
+  - `sentience/inspector.py` - Removed unused imports (F401)
+  - `tests/test_inspector.py` - Removed unused `pytest` import (F401)
+  - `tests/test_recorder.py` - Removed unused imports (F401)
+  - `tests/test_smart_selector.py` - Removed unused `pytest` import (F401)
+  - `tests/test_stealth.py` - Added `noqa` comments for intentional violations (E402, C901, F541)
+  - `tests/test_tracing.py` - Removed unused `TraceSink` import (F401)
+
+### Documentation
+- Updated `README.md` with comprehensive "Advanced Features" section covering tracing and utilities
+- Updated `docs/SDK_MANUAL.md` to v0.12.0 with new "Agent Tracing & Debugging" section
+- Added examples for:
+  - Basic tracing setup
+  - AgentConfig usage
+  - Snapshot digests for loop detection
+  - LLM prompt formatting
+  - Custom trace sinks
+
+### Testing
+- Added comprehensive test suites for new modules:
+  - `tests/test_tracing.py` - 10 tests for tracing infrastructure
+  - `tests/test_utils.py` - 22 tests for digest utilities
+  - `tests/test_formatting.py` - 9 tests for LLM formatting
+  - `tests/test_agent_config.py` - 9 tests for configuration
+- All 50 new tests passing ✅
+
+### Migration Guide
+
+#### For Existing Users
+No breaking changes! All new features are opt-in:
+
+```python
+# Old code continues to work exactly the same
+agent = SentienceAgent(browser, llm)
+agent.act("Click the button")
+
+# New optional features
+tracer = Tracer(run_id="run-123", sink=JsonlTraceSink("trace.jsonl"))
+config = AgentConfig(snapshot_limit=100, temperature=0.5)
+agent = SentienceAgent(browser, llm, tracer=tracer, config=config)
+agent.act("Click the button")  # Now traced!
+```
+
+#### Importing New Modules
+
+```python
+# Tracing
+from sentience.tracing import Tracer, JsonlTraceSink, TraceEvent, TraceSink
+
+# Configuration
+from sentience.agent_config import AgentConfig
+
+# Utilities
+from sentience.utils import (
+    compute_snapshot_digests,
+    canonical_snapshot_strict,
+    canonical_snapshot_loose,
+    sha256_digest
+)
+
+# Formatting
+from sentience.formatting import format_snapshot_for_llm
+```
+
+### Notes
+- This release focuses on developer experience and debugging capabilities
+- No changes to browser automation APIs
+- No changes to snapshot APIs
+- No changes to query/action APIs
+- Fully backward compatible with v0.11.0
+
+---
+
+## [0.11.0] - Previous Release
+
+(Previous changelog entries would go here)

MANIFEST.in

@@ -1,4 +1 @@
-include README.md
-include LICENSE
-recursive-include spec *
-recursive-include sentience *.py
+include sentience/schemas/*.json

README.md

@@ -456,6 +456,86 @@ cd sentience-chrome
 - Check visibility: `element.in_viewport and not element.is_occluded`
 - Scroll to element: `browser.page.evaluate(f"window.sentience_registry[{element.id}].scrollIntoView()")`
 
+## Advanced Features (v0.12.0+)
+
+### Agent Tracing & Debugging
+
+The SDK now includes built-in tracing infrastructure for debugging and analyzing agent behavior:
+
+```python
+from sentience import SentienceBrowser, SentienceAgent
+from sentience.llm_provider import OpenAIProvider
+from sentience.tracing import Tracer, JsonlTraceSink
+from sentience.agent_config import AgentConfig
+
+# Create tracer to record agent execution
+tracer = Tracer(
+    run_id="my-agent-run-123",
+    sink=JsonlTraceSink("trace.jsonl")
+)
+
+# Configure agent behavior
+config = AgentConfig(
+    snapshot_limit=50,
+    temperature=0.0,
+    max_retries=1,
+    capture_screenshots=True
+)
+
+browser = SentienceBrowser()
+llm = OpenAIProvider(api_key="your-key", model="gpt-4o")
+
+# Pass tracer and config to agent
+agent = SentienceAgent(browser, llm, tracer=tracer, config=config)
+
+with browser:
+    browser.page.goto("https://example.com")
+
+    # All actions are automatically traced
+    agent.act("Click the sign in button")
+    agent.act("Type 'user@example.com' into email field")
+
+# Trace events saved to trace.jsonl
+# Events: step_start, snapshot, llm_query, action, step_end, error
+```
+
+**Trace Events Captured:**
+- `step_start` - Agent begins executing a goal
+- `snapshot` - Page state captured
+- `llm_query` - LLM decision made (includes tokens, model, response)
+- `action` - Action executed (click, type, press)
+- `step_end` - Step completed successfully
+- `error` - Error occurred during execution
+
+**Use Cases:**
+- Debug why agent failed or got stuck
+- Analyze token usage and costs
+- Replay agent sessions
+- Train custom models from successful runs
+- Monitor production agents
+
+### Snapshot Utilities
+
+New utility functions for working with snapshots:
+
+```python
+from sentience import snapshot
+from sentience.utils import compute_snapshot_digests, canonical_snapshot_strict
+from sentience.formatting import format_snapshot_for_llm
+
+snap = snapshot(browser)
+
+# Compute snapshot fingerprints (detect page changes)
+digests = compute_snapshot_digests(snap.elements)
+print(f"Strict digest: {digests['strict']}")  # Changes when text changes
+print(f"Loose digest: {digests['loose']}")   # Only changes when layout changes
+
+# Format snapshot for LLM prompts
+llm_context = format_snapshot_for_llm(snap, limit=50)
+print(llm_context)
+# Output: [1] <button> "Sign In" {PRIMARY,CLICKABLE} @ (100,50) (Imp:10)
+```
+
 ## Documentation
 
 - **📖 [Amazon Shopping Guide](../docs/AMAZON_SHOPPING_GUIDE.md)** - Complete tutorial with real-world example

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sentience-python"
-version = "0.11.0"
+version = "0.12.0"
 description = "Python SDK for Sentience AI Agent Browser Automation"
 readme = "README.md"
 requires-python = ">=3.11"

sentience/__init__.py

@@ -4,12 +4,16 @@
 
 from .actions import click, click_rect, press, type_text
 from .agent import SentienceAgent
+from .agent_config import AgentConfig
 
 # Agent Layer (Phase 1 & 2)
 from .base_agent import BaseAgent
 from .browser import SentienceBrowser
 from .conversational_agent import ConversationalAgent
 from .expect import expect
+
+# Formatting (v0.12.0+)
+from .formatting import format_snapshot_for_llm
 from .generator import ScriptGenerator, generate
 from .inspector import Inspector, inspect
 from .llm_provider import (
@@ -39,9 +43,20 @@
 from .recorder import Recorder, Trace, TraceStep, record
 from .screenshot import screenshot
 from .snapshot import snapshot
+
+# Tracing (v0.12.0+)
+from .tracing import JsonlTraceSink, TraceEvent, Tracer, TraceSink
+
+# Utilities (v0.12.0+)
+from .utils import (
+    canonical_snapshot_loose,
+    canonical_snapshot_strict,
+    compute_snapshot_digests,
+    sha256_digest,
+)
 from .wait import wait_for
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"
 
 __all__ = [
     # Core SDK
@@ -88,4 +103,18 @@
     "SnapshotOptions",
     "SnapshotFilter",
     "ScreenshotConfig",
+    # Tracing (v0.12.0+)
+    "Tracer",
+    "TraceSink",
+    "JsonlTraceSink",
+    "TraceEvent",
+    # Utilities (v0.12.0+)
+    "canonical_snapshot_strict",
+    "canonical_snapshot_loose",
+    "compute_snapshot_digests",
+    "sha256_digest",
+    # Formatting (v0.12.0+)
+    "format_snapshot_for_llm",
+    # Agent Config (v0.12.0+)
+    "AgentConfig",
 ]