> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Snapshot Hooks

> Capture exact LLM call boundary state for debugging and verification

Snapshot hooks capture the exact state of messages and tools at the LLM call boundary, enabling verification that snapshots match actual payloads.

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ContextManager

manager = ContextManager(model="gpt-4o-mini")

# Capture at LLM boundary
hook_data = manager.capture_llm_boundary(messages, tools)

# Verify hashes
print(f"Message hash: {hook_data.message_hash}")
print(f"Tools hash: {hook_data.tools_hash}")
```

## Architecture

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant A as Agent
    participant C as ContextManager
    participant L as LLM
    
    A->>C: process(messages)
    C->>C: Optimize if needed
    A->>C: capture_llm_boundary(messages, tools)
    C->>C: Compute hashes
    C->>C: Store snapshot
    C-->>A: SnapshotHookData
    A->>L: Send to LLM
    Note over A,L: Hashes can verify<br/>snapshot == payload
```

## SnapshotHookData

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
@dataclass
class SnapshotHookData:
    timestamp: str           # ISO timestamp
    messages: List[Dict]     # Exact messages
    tools: List[Dict]        # Exact tool schemas
    message_hash: str        # SHA256 hash (16 chars)
    tools_hash: str          # SHA256 hash (16 chars)
    ledger: ContextLedger    # Token accounting
    budget: BudgetAllocation # Budget info
```

## Snapshot Callbacks

Register callbacks to be notified at every LLM boundary:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def on_llm_call(hook_data):
    """Called before each LLM request."""
    print(f"Sending {len(hook_data.messages)} messages")
    print(f"Hash: {hook_data.message_hash}")
    
    # Log for debugging
    with open("llm_calls.log", "a") as f:
        f.write(f"{hook_data.timestamp}: {hook_data.message_hash}\n")

manager.register_snapshot_callback(on_llm_call)
```

## Hash Verification

Verify snapshot matches actual payload:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import hashlib
import json

# Capture snapshot
hook_data = manager.capture_llm_boundary(messages, tools)

# Later, verify payload matches
def verify_payload(actual_messages, expected_hash):
    actual_json = json.dumps(actual_messages, sort_keys=True, default=str)
    actual_hash = hashlib.sha256(actual_json.encode()).hexdigest()[:16]
    return actual_hash == expected_hash

# Before sending to LLM
assert verify_payload(messages, hook_data.message_hash)
```

## Snapshot Timing

Configure when snapshots are taken:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ManagerConfig

config = ManagerConfig(
    snapshot_timing="both",  # pre_optimization, post_optimization, or both
)
```

| Timing              | Description                  |
| ------------------- | ---------------------------- |
| `pre_optimization`  | Before any optimization      |
| `post_optimization` | After optimization (default) |
| `both`              | Capture both states          |

## Drift Detection

Detect if context drifted between snapshot and LLM call:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Take snapshot
hook1 = manager.capture_llm_boundary(messages, tools)

# ... some operations ...

# Take another snapshot
hook2 = manager.capture_llm_boundary(messages, tools)

# Check for drift
if hook1.message_hash != hook2.message_hash:
    print("Warning: Context changed between snapshots")
```

## Integration with Monitor

Snapshots are automatically included in monitor output:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
config = ManagerConfig(
    monitor_enabled=True,
    monitor_format="json",
)
manager = ContextManager(config=config)

# Snapshots include hash metadata
# {
#   "timestamp": "...",
#   "message_hash": "abc123...",
#   "tools_hash": "def456...",
#   ...
# }
```

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable monitoring to capture snapshots
praisonai chat --context-monitor

# Snapshots written to context.txt
# Include message/tool hashes for verification
```

## Use Cases

1. **Debugging** - Verify exact state sent to LLM
2. **Auditing** - Log all LLM calls with hashes
3. **Testing** - Assert snapshot == expected payload
4. **Replay** - Reproduce exact LLM calls