ai-watcher 0.2.0__tar.gz

ai_watcher-0.2.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: ai-watcher
+Version: 0.2.0
+Summary: AI agent observability and control — AgentWatch SDK
+License-Expression: MIT
+Project-URL: Homepage, https://agentwatch.vercel.app
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ai-watcher
+
+Python SDK for [AgentWatch](https://agentwatch.vercel.app) — AI agent observability and control.
+
+## Install
+
+```bash
+pip install ai-watcher
+```
+
+## Quickstart
+
+```bash
+export AGENTWATCH_API_KEY=aw_live_...
+```
+
+### One-liner wrapper (Lambda / serverless)
+
+```python
+from agentwatch import track_llm
+
+result = track_llm(
+    'classify-document',
+    lambda: openai.chat.completions.create(...),
+    {
+        'human_id': customer_id,
+        'agent_name': 'doc-classifier',
+        'model': 'gpt-4o',
+        'framework': 'aws-lambda',
+        'session_name': 'Classify: invoice',
+        'input': {'doc_type': 'invoice', 'pages': 3},
+    }
+)
+```
+
+### Chained model calls (multi-step pipeline)
+
+```python
+from agentwatch import track_chain
+
+results = track_chain(
+    steps=[
+        {
+            'action': 'extract',
+            'model': 'gpt-4o',
+            'fn': lambda: openai.chat.completions.create(...),
+            'input': {'pages': 3},
+        },
+        {
+            'action': 'classify',
+            'model': 'claude-sonnet-4-20250514',
+            'fn': lambda: anthropic.messages.create(...),
+            'input': {'text': '...'},
+        },
+    ],
+    opts={
+        'human_id': customer_id,
+        'agent_name': 'shipping-pipeline',
+        'session_name': 'Process Shipping Document',
+    }
+)
+```
+
+Both wrappers are zero-dependency and **never break your app** — if AgentWatch
+is unreachable, the underlying function still runs.
+
+### Session context manager (full control)
+
+```python
+from agentwatch import Session, tool
+
+with Session(human_id="you@example.com") as session:
+
+    @tool(session)
+    def search_web(query: str) -> str:
+        return "results..."
+
+    result = search_web("AI agent security")
+```
+
+### Full Session config
+
+```python
+from agentwatch import Session, tool
+
+with Session(
+    api_key="aw_live_...",
+    human_id="sarah@acme.com",
+    agent_name="billing-agent",
+    agent_version="2.0.0",
+    model="claude-sonnet-4-20250514",
+    system_prompt="You are a billing assistant.",
+    tools=["send_invoice", "fetch_invoice"],
+    framework="langchain",
+) as session:
+
+    @tool(session, action_class="send", data_scope="financial")
+    def send_invoice(recipient: str, amount: float) -> dict:
+        return {"sent": True}
+
+    send_invoice("client@acme.com", 1200.00)
+```
+
+## API reference
+
+### `track_llm(action, fn, opts)`
+
+| Field | Type | Description |
+|---|---|---|
+| `action` | `str` | Name of the operation (e.g. `"classify-document"`) |
+| `fn` | `Callable` | Zero-argument callable that makes the model call |
+| `opts` | `dict` | Session options (see below) |
+
+### `track_chain(steps, opts)`
+
+Each step: `{'action': str, 'fn': callable, 'model': str, 'input': dict}`
+
+### Common opts fields
+
+| Key | Default | Description |
+|---|---|---|
+| `human_id` | `"anonymous"` | User or customer identifier |
+| `agent_name` | `"agent"` | Name of the agent/pipeline |
+| `model` | `"unknown"` | Default model (overridden per step in `track_chain`) |
+| `framework` | `"python"` | Runtime (e.g. `"aws-lambda"`, `"langchain"`) |
+| `session_name` | action name | Human-readable session title in the dashboard |
+| `input` | `None` | Input metadata to log with the event |
+
+## Exceptions
+
+| Exception | When raised |
+|---|---|
+| `ExecutionBlockedException` | Policy blocked the tool call |
+| `HitlDeniedException` | Human reviewer denied the action |
+| `AgentwatchAPIError` | Non-2xx response from the API |
+| `AgentwatchConnectionError` | Network error after retries |
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENTWATCH_API_KEY` | — | Required. Your `aw_live_...` key. |
+| `AGENTWATCH_API_URL` | `https://agentwatch.vercel.app` | Override for self-hosted. |

ai_watcher-0.2.0/README.md

@@ -0,0 +1,143 @@
+# ai-watcher
+
+Python SDK for [AgentWatch](https://agentwatch.vercel.app) — AI agent observability and control.
+
+## Install
+
+```bash
+pip install ai-watcher
+```
+
+## Quickstart
+
+```bash
+export AGENTWATCH_API_KEY=aw_live_...
+```
+
+### One-liner wrapper (Lambda / serverless)
+
+```python
+from agentwatch import track_llm
+
+result = track_llm(
+    'classify-document',
+    lambda: openai.chat.completions.create(...),
+    {
+        'human_id': customer_id,
+        'agent_name': 'doc-classifier',
+        'model': 'gpt-4o',
+        'framework': 'aws-lambda',
+        'session_name': 'Classify: invoice',
+        'input': {'doc_type': 'invoice', 'pages': 3},
+    }
+)
+```
+
+### Chained model calls (multi-step pipeline)
+
+```python
+from agentwatch import track_chain
+
+results = track_chain(
+    steps=[
+        {
+            'action': 'extract',
+            'model': 'gpt-4o',
+            'fn': lambda: openai.chat.completions.create(...),
+            'input': {'pages': 3},
+        },
+        {
+            'action': 'classify',
+            'model': 'claude-sonnet-4-20250514',
+            'fn': lambda: anthropic.messages.create(...),
+            'input': {'text': '...'},
+        },
+    ],
+    opts={
+        'human_id': customer_id,
+        'agent_name': 'shipping-pipeline',
+        'session_name': 'Process Shipping Document',
+    }
+)
+```
+
+Both wrappers are zero-dependency and **never break your app** — if AgentWatch
+is unreachable, the underlying function still runs.
+
+### Session context manager (full control)
+
+```python
+from agentwatch import Session, tool
+
+with Session(human_id="you@example.com") as session:
+
+    @tool(session)
+    def search_web(query: str) -> str:
+        return "results..."
+
+    result = search_web("AI agent security")
+```
+
+### Full Session config
+
+```python
+from agentwatch import Session, tool
+
+with Session(
+    api_key="aw_live_...",
+    human_id="sarah@acme.com",
+    agent_name="billing-agent",
+    agent_version="2.0.0",
+    model="claude-sonnet-4-20250514",
+    system_prompt="You are a billing assistant.",
+    tools=["send_invoice", "fetch_invoice"],
+    framework="langchain",
+) as session:
+
+    @tool(session, action_class="send", data_scope="financial")
+    def send_invoice(recipient: str, amount: float) -> dict:
+        return {"sent": True}
+
+    send_invoice("client@acme.com", 1200.00)
+```
+
+## API reference
+
+### `track_llm(action, fn, opts)`
+
+| Field | Type | Description |
+|---|---|---|
+| `action` | `str` | Name of the operation (e.g. `"classify-document"`) |
+| `fn` | `Callable` | Zero-argument callable that makes the model call |
+| `opts` | `dict` | Session options (see below) |
+
+### `track_chain(steps, opts)`
+
+Each step: `{'action': str, 'fn': callable, 'model': str, 'input': dict}`
+
+### Common opts fields
+
+| Key | Default | Description |
+|---|---|---|
+| `human_id` | `"anonymous"` | User or customer identifier |
+| `agent_name` | `"agent"` | Name of the agent/pipeline |
+| `model` | `"unknown"` | Default model (overridden per step in `track_chain`) |
+| `framework` | `"python"` | Runtime (e.g. `"aws-lambda"`, `"langchain"`) |
+| `session_name` | action name | Human-readable session title in the dashboard |
+| `input` | `None` | Input metadata to log with the event |
+
+## Exceptions
+
+| Exception | When raised |
+|---|---|
+| `ExecutionBlockedException` | Policy blocked the tool call |
+| `HitlDeniedException` | Human reviewer denied the action |
+| `AgentwatchAPIError` | Non-2xx response from the API |
+| `AgentwatchConnectionError` | Network error after retries |
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENTWATCH_API_KEY` | — | Required. Your `aw_live_...` key. |
+| `AGENTWATCH_API_URL` | `https://agentwatch.vercel.app` | Override for self-hosted. |

ai_watcher-0.2.0/ai_watcher.egg-info/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: ai-watcher
+Version: 0.2.0
+Summary: AI agent observability and control — AgentWatch SDK
+License-Expression: MIT
+Project-URL: Homepage, https://agentwatch.vercel.app
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ai-watcher
+
+Python SDK for [AgentWatch](https://agentwatch.vercel.app) — AI agent observability and control.
+
+## Install
+
+```bash
+pip install ai-watcher
+```
+
+## Quickstart
+
+```bash
+export AGENTWATCH_API_KEY=aw_live_...
+```
+
+### One-liner wrapper (Lambda / serverless)
+
+```python
+from agentwatch import track_llm
+
+result = track_llm(
+    'classify-document',
+    lambda: openai.chat.completions.create(...),
+    {
+        'human_id': customer_id,
+        'agent_name': 'doc-classifier',
+        'model': 'gpt-4o',
+        'framework': 'aws-lambda',
+        'session_name': 'Classify: invoice',
+        'input': {'doc_type': 'invoice', 'pages': 3},
+    }
+)
+```
+
+### Chained model calls (multi-step pipeline)
+
+```python
+from agentwatch import track_chain
+
+results = track_chain(
+    steps=[
+        {
+            'action': 'extract',
+            'model': 'gpt-4o',
+            'fn': lambda: openai.chat.completions.create(...),
+            'input': {'pages': 3},
+        },
+        {
+            'action': 'classify',
+            'model': 'claude-sonnet-4-20250514',
+            'fn': lambda: anthropic.messages.create(...),
+            'input': {'text': '...'},
+        },
+    ],
+    opts={
+        'human_id': customer_id,
+        'agent_name': 'shipping-pipeline',
+        'session_name': 'Process Shipping Document',
+    }
+)
+```
+
+Both wrappers are zero-dependency and **never break your app** — if AgentWatch
+is unreachable, the underlying function still runs.
+
+### Session context manager (full control)
+
+```python
+from agentwatch import Session, tool
+
+with Session(human_id="you@example.com") as session:
+
+    @tool(session)
+    def search_web(query: str) -> str:
+        return "results..."
+
+    result = search_web("AI agent security")
+```
+
+### Full Session config
+
+```python
+from agentwatch import Session, tool
+
+with Session(
+    api_key="aw_live_...",
+    human_id="sarah@acme.com",
+    agent_name="billing-agent",
+    agent_version="2.0.0",
+    model="claude-sonnet-4-20250514",
+    system_prompt="You are a billing assistant.",
+    tools=["send_invoice", "fetch_invoice"],
+    framework="langchain",
+) as session:
+
+    @tool(session, action_class="send", data_scope="financial")
+    def send_invoice(recipient: str, amount: float) -> dict:
+        return {"sent": True}
+
+    send_invoice("client@acme.com", 1200.00)
+```
+
+## API reference
+
+### `track_llm(action, fn, opts)`
+
+| Field | Type | Description |
+|---|---|---|
+| `action` | `str` | Name of the operation (e.g. `"classify-document"`) |
+| `fn` | `Callable` | Zero-argument callable that makes the model call |
+| `opts` | `dict` | Session options (see below) |
+
+### `track_chain(steps, opts)`
+
+Each step: `{'action': str, 'fn': callable, 'model': str, 'input': dict}`
+
+### Common opts fields
+
+| Key | Default | Description |
+|---|---|---|
+| `human_id` | `"anonymous"` | User or customer identifier |
+| `agent_name` | `"agent"` | Name of the agent/pipeline |
+| `model` | `"unknown"` | Default model (overridden per step in `track_chain`) |
+| `framework` | `"python"` | Runtime (e.g. `"aws-lambda"`, `"langchain"`) |
+| `session_name` | action name | Human-readable session title in the dashboard |
+| `input` | `None` | Input metadata to log with the event |
+
+## Exceptions
+
+| Exception | When raised |
+|---|---|
+| `ExecutionBlockedException` | Policy blocked the tool call |
+| `HitlDeniedException` | Human reviewer denied the action |
+| `AgentwatchAPIError` | Non-2xx response from the API |
+| `AgentwatchConnectionError` | Network error after retries |
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENTWATCH_API_KEY` | — | Required. Your `aw_live_...` key. |
+| `AGENTWATCH_API_URL` | `https://agentwatch.vercel.app` | Override for self-hosted. |

ai_watcher-0.2.0/ai_watcher.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+ai_watcher.egg-info/PKG-INFO
+ai_watcher.egg-info/SOURCES.txt
+ai_watcher.egg-info/dependency_links.txt
+ai_watcher.egg-info/top_level.txt
+aiwatcher/__init__.py
+aiwatcher/chain.py
+aiwatcher/client.py
+aiwatcher/decorators.py
+aiwatcher/exceptions.py
+aiwatcher/fingerprint.py
+aiwatcher/session.py

ai_watcher-0.2.0/ai_watcher.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ai_watcher-0.2.0/ai_watcher.egg-info/top_level.txt

@@ -0,0 +1 @@
+aiwatcher

ai_watcher-0.2.0/aiwatcher/__init__.py

@@ -0,0 +1,24 @@
+from .client import track_chain, track_llm
+from .decorators import tool
+from .exceptions import (
+    AgentwatchAPIError,
+    AgentwatchConnectionError,
+    AgentwatchError,
+    ExecutionBlockedException,
+    HitlDeniedException,
+)
+from .session import Session
+
+__all__ = [
+    'Session',
+    'tool',
+    'track_llm',
+    'track_chain',
+    'ExecutionBlockedException',
+    'HitlDeniedException',
+    'AgentwatchError',
+    'AgentwatchAPIError',
+    'AgentwatchConnectionError',
+]
+
+__version__ = '0.2.0'

ai_watcher-0.2.0/aiwatcher/chain.py

@@ -0,0 +1,29 @@
+import hashlib
+import json
+from typing import Any, Optional
+
+
+def stable_json(value: Any) -> str:
+    """Compact, key-sorted JSON — must match TypeScript stableStringify in src/lib/chain.ts."""
+    return json.dumps(value, sort_keys=True, separators=(',', ':'))
+
+
+def compute_entry_hash(
+    session_id: str,
+    sequence_num: int,
+    event_type: str,
+    action: Optional[str],
+    input_data: Any,
+    output_data: Any,
+    prev_hash: str,
+) -> str:
+    payload = '|'.join([
+        session_id,
+        str(sequence_num),
+        event_type,
+        action or '',
+        stable_json(input_data),   # json.dumps(None) → 'null', matches TS stableStringify(null)
+        stable_json(output_data),
+        prev_hash,
+    ])
+    return hashlib.sha256(payload.encode('utf-8')).hexdigest()

ai_watcher-0.2.0/aiwatcher/client.py

@@ -0,0 +1,253 @@
+import json
+import sys
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+from .exceptions import AgentwatchAPIError, AgentwatchConnectionError
+
+T = TypeVar('T')
+
+
+class AgentwatchClient:
+    def __init__(
+        self,
+        api_url: str,
+        api_key: str,
+        max_retries: int = 3,
+        timeout: int = 30,
+    ):
+        self.api_url = api_url.rstrip('/')
+        self.api_key = api_key
+        self.max_retries = max_retries
+        self.timeout = timeout
+
+    def post(self, path: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        url = f"{self.api_url}{path}"
+        # Keep falsy values (0, False, [], {}) but drop None
+        clean = {k: v for k, v in data.items() if v is not None}
+        payload = json.dumps(clean).encode('utf-8')
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries):
+            try:
+                req = urllib.request.Request(
+                    url,
+                    data=payload,
+                    headers={
+                        'Content-Type': 'application/json',
+                        'X-API-Key': self.api_key,
+                    },
+                    method='POST',
+                )
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    return json.loads(resp.read().decode('utf-8'))
+            except urllib.error.HTTPError as e:
+                body = e.read().decode('utf-8', errors='replace')
+                raise AgentwatchAPIError(e.code, body) from e
+            except urllib.error.URLError as e:
+                last_exc = e
+                if attempt < self.max_retries - 1:
+                    time.sleep(min(2 ** attempt, 8))
+
+        raise AgentwatchConnectionError(
+            f"POST {path} failed after {self.max_retries} attempts: {last_exc}"
+        )
+
+    def get(self, path: str) -> Dict[str, Any]:
+        url = f"{self.api_url}{path}"
+        req = urllib.request.Request(
+            url,
+            headers={'X-API-Key': self.api_key},
+            method='GET',
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode('utf-8'))
+        except urllib.error.HTTPError as e:
+            body = e.read().decode('utf-8', errors='replace')
+            raise AgentwatchAPIError(e.code, body) from e
+
+    def poll_hitl(
+        self,
+        hitl_id: str,
+        timeout: int = 900,
+        poll_interval: int = 5,
+    ) -> Dict[str, Any]:
+        path = f"/api/v1/ingest/hitl/{hitl_id}/status"
+        deadline = time.monotonic() + timeout
+
+        while time.monotonic() < deadline:
+            try:
+                data = self.get(path)
+                if data.get('status') != 'pending':
+                    return data
+            except Exception:
+                pass
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            time.sleep(min(poll_interval, max(remaining, 0)))
+
+        return {'status': 'expired'}
+
+
+# ── Convenience wrappers ──────────────────────────────────────────────────────
+# Lazy import of Session inside functions to avoid the circular import that
+# would occur if imported at module level (session.py imports AgentwatchClient).
+
+def track_llm(
+    action: str,
+    fn: Callable[[], T],
+    opts: Optional[Dict[str, Any]] = None,
+) -> T:
+    """
+    Wrap any synchronous AI/LLM call with AgentWatch telemetry.
+    Zero dependencies. Never breaks the host app.
+
+    Usage:
+        from aiwatcher import track_llm
+
+        result = track_llm('classify-document',
+            lambda: openai.chat.completions.create(...),
+            {
+                'human_id': customer_id,
+                'agent_name': 'doc-classifier',
+                'model': 'gpt-4o',
+                'framework': 'aws-lambda',
+                'session_name': 'Classify: invoice',
+                'input': {'doc_type': 'invoice', 'pages': 3}
+            }
+        )
+    """
+    from .session import Session  # lazy — session.py imports this module; defer to call time
+
+    o = opts or {}
+
+    try:
+        session = Session(
+            human_id=o.get('human_id', 'anonymous'),
+            agent_name=o.get('agent_name', 'agent'),
+            framework=o.get('framework', 'python'),
+            model=o.get('model', 'unknown'),
+            metadata={'session_name': o.get('session_name', action)},
+            product_context=o.get('product_context'),
+        )
+        session.__enter__()
+        print(f"[AgentWatch] session/start: {session.session_id}", file=sys.stderr)
+    except Exception as e:
+        print(f"[AgentWatch] ERROR in {action}: {type(e).__name__}: {e}", file=sys.stderr)
+        return fn()  # AgentWatch down — still run fn()
+
+    t0 = time.monotonic()
+    caught: Optional[BaseException] = None
+    result: Any = None
+
+    try:
+        result = fn()
+        latency_ms = int((time.monotonic() - t0) * 1000)
+        try:
+            session.log_event(
+                event_type='llm_call',
+                agent_name=session.agent_name,
+                action=action,
+                input_data=o.get('input'),
+                output_data={'success': True},
+                model=o.get('model'),
+                latency_ms=latency_ms,
+                product_context=o.get('product_context'),
+                outcome_context=o.get('outcome_context'),
+            )
+            print(f"[AgentWatch] event posted seq={session.sequence_num}: {action}", file=sys.stderr)
+        except Exception as e:
+            print(f"[AgentWatch] ERROR in {action}: {type(e).__name__}: {e}", file=sys.stderr)
+    except Exception as e:
+        caught = e
+    finally:
+        try:
+            session.__exit__(type(caught) if caught else None, caught, None)
+        except Exception:
+            pass
+
+    if caught is not None:
+        raise caught  # type: ignore[misc]
+    return result  # type: ignore[return-value]
+
+
+def track_chain(
+    steps: List[Dict[str, Any]],
+    opts: Optional[Dict[str, Any]] = None,
+) -> List[Any]:
+    """
+    Wrap chained model calls — one session, multiple events.
+    Each step: {'action': str, 'fn': callable, 'model': str, 'input': dict}
+
+    Usage:
+        results = track_chain([
+            {'action': 'ocr', 'model': 'gpt-4o',
+             'fn': lambda: openai.chat(...), 'input': {'pages': 3}},
+            {'action': 'classify', 'model': 'claude-sonnet-4-20250514',
+             'fn': lambda: anthropic.messages(...), 'input': {'text': '...'}}
+        ], {
+            'human_id': customer_id,
+            'agent_name': 'shipping-pipeline',
+            'session_name': 'Process Shipping Document'
+        })
+    """
+    from .session import Session  # lazy — see note in track_llm
+
+    o = opts or {}
+    first_model = steps[0].get('model', 'unknown') if steps else 'unknown'
+
+    try:
+        session = Session(
+            human_id=o.get('human_id', 'anonymous'),
+            agent_name=o.get('agent_name', 'agent'),
+            framework=o.get('framework', 'python'),
+            model=o.get('model', first_model),
+            metadata={'session_name': o.get('session_name', 'chained-workflow')},
+            product_context=o.get('product_context'),
+        )
+        session.__enter__()
+        print(f"[AgentWatch] session/start: {session.session_id}", file=sys.stderr)
+    except Exception as e:
+        print(f"[AgentWatch] ERROR session/start: {type(e).__name__}: {e}", file=sys.stderr)
+        return [step['fn']() for step in steps]  # AgentWatch down — still run steps
+
+    t0 = time.monotonic()
+    results: List[Any] = []
+    caught: Optional[BaseException] = None
+
+    try:
+        for step in steps:
+            t_step = time.monotonic()
+            step_result = step['fn']()
+            latency_ms = int((time.monotonic() - t_step) * 1000)
+            results.append(step_result)
+            try:
+                session.log_event(
+                    event_type='llm_call',
+                    agent_name=session.agent_name,
+                    action=step['action'],
+                    input_data=step.get('input'),
+                    output_data={'success': True},
+                    model=step.get('model', o.get('model', 'unknown')),
+                    latency_ms=latency_ms,
+                    product_context=step.get('product_context', o.get('product_context')),
+                    outcome_context=step.get('outcome_context'),
+                )
+                print(f"[AgentWatch] event posted seq={session.sequence_num}: {step['action']}", file=sys.stderr)
+            except Exception as e:
+                print(f"[AgentWatch] ERROR in {step['action']}: {type(e).__name__}: {e}", file=sys.stderr)
+    except Exception as e:
+        caught = e
+    finally:
+        try:
+            session.__exit__(type(caught) if caught else None, caught, None)
+        except Exception:
+            pass
+
+    if caught is not None:
+        raise caught  # type: ignore[misc]
+    return results

ai_watcher-0.2.0/aiwatcher/decorators.py

@@ -0,0 +1,67 @@
+import time
+from functools import wraps
+from typing import Any, Callable
+
+from .exceptions import ExecutionBlockedException, HitlDeniedException
+
+
+def tool(
+    session: Any,
+    action_class: str = 'read',
+    data_scope: str = 'any',
+) -> Callable:
+    """
+    Decorator that wraps a function with AgentWatch observability and policy enforcement.
+
+    Usage:
+        @tool(session, action_class="send", data_scope="financial")
+        def send_invoice(recipient: str, amount: float) -> dict:
+            ...
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            start = time.monotonic()
+            input_data = {'args': list(args), 'kwargs': kwargs}
+
+            resp = session.log_event(
+                event_type='tool_call',
+                agent_name=session.agent_name,
+                action=func.__name__,
+                input_data=input_data,
+                output_data=None,
+                action_class=action_class,
+                data_scope=data_scope,
+            )
+
+            if resp.get('block'):
+                raise ExecutionBlockedException(
+                    f"Policy blocked execution of '{func.__name__}'"
+                )
+
+            if resp.get('hitl_required'):
+                hitl_id = resp.get('hitl_request_id')
+                if hitl_id:
+                    approval = session.client.poll_hitl(hitl_id, timeout=900)
+                    if approval.get('status') == 'denied':
+                        raise HitlDeniedException(
+                            f"Human denied execution of '{func.__name__}'"
+                        )
+
+            result = func(*args, **kwargs)
+            latency = int((time.monotonic() - start) * 1000)
+
+            session.log_event(
+                event_type='tool_result',
+                agent_name=session.agent_name,
+                action=func.__name__,
+                input_data=input_data,
+                output_data=result,
+                latency_ms=latency,
+                action_class=action_class,
+                data_scope=data_scope,
+            )
+
+            return result
+        return wrapper
+    return decorator

ai_watcher-0.2.0/aiwatcher/exceptions.py

@@ -0,0 +1,21 @@
+class AgentwatchError(Exception):
+    """Base class for all AgentWatch SDK errors."""
+
+
+class AgentwatchAPIError(AgentwatchError):
+    def __init__(self, status_code: int, body: str):
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"API error {status_code}: {body}")
+
+
+class AgentwatchConnectionError(AgentwatchError):
+    pass
+
+
+class ExecutionBlockedException(AgentwatchError):
+    """Raised when a tool call is blocked by policy."""
+
+
+class HitlDeniedException(AgentwatchError):
+    """Raised when a human reviewer denied the requested action."""

ai_watcher-0.2.0/aiwatcher/fingerprint.py

@@ -0,0 +1,25 @@
+import hashlib
+import json
+from typing import Any, Dict, List, Optional
+
+
+def _sha256(text: str) -> str:
+    return hashlib.sha256(text.encode('utf-8')).hexdigest()
+
+
+def compute_fingerprint(
+    model: Optional[str] = None,
+    system_prompt: Optional[str] = None,
+    tools: Optional[List[str]] = None,
+    config: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    fp: Dict[str, Any] = {
+        'model': model or 'unknown',
+        'prompt_hash': _sha256(system_prompt or ''),
+        'tools': sorted(tools or []),
+    }
+    if config is not None:
+        fp['config_hash'] = _sha256(
+            json.dumps(config, sort_keys=True, separators=(',', ':'))
+        )
+    return fp

ai_watcher-0.2.0/aiwatcher/session.py

@@ -0,0 +1,162 @@
+import os
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from .chain import compute_entry_hash
+from .client import AgentwatchClient
+from .fingerprint import compute_fingerprint
+
+
+class Session:
+    def __init__(
+        self,
+        human_id: str,
+        api_key: Optional[str] = None,
+        api_url: Optional[str] = None,
+        **kwargs: Any,
+    ):
+        self.api_key = api_key or os.environ.get('AGENTWATCH_API_KEY')
+        self.api_url = (
+            api_url
+            or os.environ.get('AGENTWATCH_API_URL', 'https://agentwatch-pi.vercel.app')
+        )
+
+        if not self.api_key:
+            raise ValueError(
+                "api_key is required. Pass it directly or set AGENTWATCH_API_KEY env var."
+            )
+
+        self.human_id: str = human_id
+        self.agent_name: str = kwargs.get('agent_name', 'default-agent')
+        self.agent_version: Optional[str] = kwargs.get('agent_version')
+        self.model: Optional[str] = kwargs.get('model')
+        self.system_prompt: Optional[str] = kwargs.get('system_prompt')
+        self.tools: List[str] = kwargs.get('tools') or []
+        self.framework: Optional[str] = kwargs.get('framework')
+        self.metadata: Optional[Dict[str, Any]] = kwargs.get('metadata')
+        self.product_context: Optional[Dict[str, Any]] = kwargs.get('product_context')
+        self.human_metadata: Optional[Dict[str, Any]] = kwargs.get('human_metadata')
+
+        self.sequence_num: int = 0
+        self.prev_hash: str = 'genesis'
+        self.session_id: Optional[str] = None
+        self.policy: Optional[Dict[str, Any]] = None
+        self.fingerprint_status: Optional[str] = None
+        self._start_time: Optional[float] = None
+
+        self.client = AgentwatchClient(self.api_url, self.api_key)
+
+    def __enter__(self) -> 'Session':
+        self._start_time = time.monotonic()
+
+        fingerprint = compute_fingerprint(
+            model=self.model,
+            system_prompt=self.system_prompt,
+            tools=self.tools,
+        )
+
+        try:
+            resp = self.client.post('/api/v1/ingest/session/start', {
+                'human_id': self.human_id,
+                'human_metadata': self.human_metadata,
+                'agent_name': self.agent_name,
+                'agent_version': self.agent_version,
+                'fingerprint': fingerprint,
+                'framework': self.framework,
+                'metadata': self.metadata,
+                'product_context': self.product_context,
+            })
+            self.session_id = resp['session_id']
+            self.policy = resp.get('policy')
+            self.fingerprint_status = resp.get('fingerprint_status')
+        except Exception as e:
+            # API unreachable — degrade silently. session_id stays None.
+            # log_event() and __exit__() are no-ops when session_id is None.
+            import sys
+            print(f'[AIWatcher] session/start failed (offline mode): {e}', file=sys.stderr)
+
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
+        if self.session_id and self._start_time is not None:
+            elapsed_ms = int((time.monotonic() - self._start_time) * 1000)
+            status = 'error' if exc_type is not None else 'completed'
+            try:
+                self.client.post('/api/v1/ingest/session/end', {
+                    'session_id': self.session_id,
+                    'status': status,
+                    'duration_ms': elapsed_ms,
+                })
+            except Exception:
+                pass  # Never suppress the original exception
+        return False  # Propagate any exception from the with-block
+
+    def log_event(
+        self,
+        event_type: str,
+        agent_name: str,
+        action: Optional[str],
+        input_data: Any,
+        output_data: Any,
+        model: Optional[str] = None,
+        tokens_in: Optional[int] = None,
+        tokens_out: Optional[int] = None,
+        cost_usd: Optional[float] = None,
+        latency_ms: Optional[int] = None,
+        action_class: str = 'read',
+        data_scope: str = 'any',
+        product_context: Optional[Dict[str, Any]] = None,
+        outcome_context: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        if not self.session_id:
+            # Offline mode — API unreachable at session start, skip silently
+            return {}
+
+        self.sequence_num += 1
+        resolved_product_context = product_context or self.product_context
+        if resolved_product_context:
+            input_data = {
+                **(input_data if isinstance(input_data, dict) else {'value': input_data}),
+                'product_context': resolved_product_context,
+            }
+        if outcome_context:
+            output_data = {
+                **(output_data if isinstance(output_data, dict) else {'value': output_data}),
+                'outcome_context': outcome_context,
+            }
+
+        entry_hash = compute_entry_hash(
+            session_id=self.session_id,
+            sequence_num=self.sequence_num,
+            event_type=event_type,
+            action=action,
+            input_data=input_data,
+            output_data=output_data,
+            prev_hash=self.prev_hash,
+        )
+
+        now = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')
+
+        resp = self.client.post('/api/v1/ingest/event', {
+            'session_id': self.session_id,
+            'event_type': event_type,
+            'agent_name': agent_name,
+            'action': action,
+            'sequence_num': self.sequence_num,
+            'input_data': input_data,
+            'output_data': output_data,
+            'model': model,
+            'tokens_in': tokens_in,
+            'tokens_out': tokens_out,
+            'cost_usd': cost_usd,
+            'latency_ms': latency_ms,
+            'prev_hash': self.prev_hash,
+            'entry_hash': entry_hash,
+            'timestamp': now,
+            'action_class': action_class,
+            'data_scope': data_scope,
+        })
+
+        self.prev_hash = entry_hash
+        return resp

ai_watcher-0.2.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-watcher"
+version = "0.2.0"
+description = "AI agent observability and control — AgentWatch SDK"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = []
+
+[project.urls]
+Homepage = "https://agentwatch.vercel.app"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["aiwatcher*"]

ai_watcher-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+