tezca 0.3.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tezca/__init__.py +40 -0
- tezca/__main__.py +10 -0
- tezca/canonical.py +55 -0
- tezca/cli.py +207 -0
- tezca/events.py +61 -0
- tezca/integrations/__init__.py +15 -0
- tezca/integrations/interceptors.py +228 -0
- tezca/integrations/langchain.py +129 -0
- tezca/ledger.py +263 -0
- tezca/merkle.py +164 -0
- tezca/proof.py +117 -0
- tezca/receipt.py +86 -0
- tezca/storage.py +238 -0
- tezca-0.3.0.dist-info/METADATA +272 -0
- tezca-0.3.0.dist-info/RECORD +19 -0
- tezca-0.3.0.dist-info/WHEEL +5 -0
- tezca-0.3.0.dist-info/entry_points.txt +2 -0
- tezca-0.3.0.dist-info/licenses/LICENSE +201 -0
- tezca-0.3.0.dist-info/top_level.txt +1 -0
tezca/__init__.py
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""
|
|
2
|
+
tezca: Zero-dependency, hash-chained forensic ledger for AI agents.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from tezca.canonical import GENESIS_HASH, canonical_dumps, compute_receipt_hash
|
|
8
|
+
from tezca.events import AgentEvent, AgentEventType
|
|
9
|
+
from tezca.integrations.interceptors import track_agent_call, wrap_completion, wrap_tool
|
|
10
|
+
from tezca.integrations.langchain import TezcaCallbackHandler
|
|
11
|
+
from tezca.ledger import Ledger
|
|
12
|
+
from tezca.merkle import MerkleProof, MerkleStep, MerkleTree
|
|
13
|
+
from tezca.proof import PROOF_SCHEMA_VERSION, ProofBundle
|
|
14
|
+
from tezca.receipt import Receipt
|
|
15
|
+
from tezca.storage import JSONLStorage, SQLiteStorage, StorageBackend
|
|
16
|
+
|
|
17
|
+
__version__ = "0.3.0"
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"AgentEvent",
|
|
21
|
+
"AgentEventType",
|
|
22
|
+
"GENESIS_HASH",
|
|
23
|
+
"JSONLStorage",
|
|
24
|
+
"Ledger",
|
|
25
|
+
"MerkleProof",
|
|
26
|
+
"MerkleStep",
|
|
27
|
+
"MerkleTree",
|
|
28
|
+
"PROOF_SCHEMA_VERSION",
|
|
29
|
+
"ProofBundle",
|
|
30
|
+
"Receipt",
|
|
31
|
+
"SQLiteStorage",
|
|
32
|
+
"StorageBackend",
|
|
33
|
+
"TezcaCallbackHandler",
|
|
34
|
+
"__version__",
|
|
35
|
+
"canonical_dumps",
|
|
36
|
+
"compute_receipt_hash",
|
|
37
|
+
"track_agent_call",
|
|
38
|
+
"wrap_completion",
|
|
39
|
+
"wrap_tool",
|
|
40
|
+
]
|
tezca/__main__.py
ADDED
tezca/canonical.py
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Canonical serialization and cryptographic hashing utilities for tezca.
|
|
3
|
+
|
|
4
|
+
All comments and documentation are in English.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import hashlib
|
|
10
|
+
import json
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
GENESIS_HASH = "0" * 64
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def canonical_dumps(obj: Any) -> str:
|
|
17
|
+
"""
|
|
18
|
+
Produce a deterministic, compact JSON string.
|
|
19
|
+
|
|
20
|
+
Keys are sorted lexicographically, separators are minimal without spaces,
|
|
21
|
+
and non-string keys/types fallback cleanly.
|
|
22
|
+
"""
|
|
23
|
+
return json.dumps(
|
|
24
|
+
obj,
|
|
25
|
+
sort_keys=True,
|
|
26
|
+
separators=(",", ":"),
|
|
27
|
+
ensure_ascii=False,
|
|
28
|
+
default=str,
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def compute_receipt_hash(
|
|
33
|
+
index: int,
|
|
34
|
+
timestamp: str,
|
|
35
|
+
agent_id: str,
|
|
36
|
+
event_type: str,
|
|
37
|
+
canonical_data: str,
|
|
38
|
+
canonical_metadata: str,
|
|
39
|
+
prev_hash: str,
|
|
40
|
+
) -> str:
|
|
41
|
+
"""
|
|
42
|
+
Calculate the SHA-256 digest of a receipt payload.
|
|
43
|
+
|
|
44
|
+
The payload concatenates all fields with deterministic separators.
|
|
45
|
+
"""
|
|
46
|
+
payload = (
|
|
47
|
+
f"{index}\n"
|
|
48
|
+
f"{timestamp}\n"
|
|
49
|
+
f"{agent_id}\n"
|
|
50
|
+
f"{event_type}\n"
|
|
51
|
+
f"{canonical_data}\n"
|
|
52
|
+
f"{canonical_metadata}\n"
|
|
53
|
+
f"{prev_hash}"
|
|
54
|
+
)
|
|
55
|
+
return hashlib.sha256(payload.encode("utf-8")).hexdigest()
|
tezca/cli.py
ADDED
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Command line interface for forensic verification and inspection of tezca ledgers.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import argparse
|
|
8
|
+
import json
|
|
9
|
+
import sys
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
|
|
12
|
+
from tezca.ledger import Ledger
|
|
13
|
+
from tezca.proof import ProofBundle
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def cmd_verify(args: argparse.Namespace) -> int:
|
|
17
|
+
path = Path(args.ledger)
|
|
18
|
+
if not path.exists():
|
|
19
|
+
print(f"[ERROR] Ledger file not found: {path}", file=sys.stderr)
|
|
20
|
+
return 1
|
|
21
|
+
|
|
22
|
+
try:
|
|
23
|
+
with Ledger(path, secret_key=args.secret_key) as ledger:
|
|
24
|
+
valid, report = ledger.verify()
|
|
25
|
+
|
|
26
|
+
if valid:
|
|
27
|
+
total = report["verified_events"]
|
|
28
|
+
latest = report["latest_hash"]
|
|
29
|
+
print(f"[OK] {total:,} events verified.")
|
|
30
|
+
print(f"[OK] Chain integrity: INTACT (Genesis: {report['genesis_hash'][:16]}... -> Latest: {latest[:16]}...)")
|
|
31
|
+
return 0
|
|
32
|
+
else:
|
|
33
|
+
print(f"[FAIL] Tampering detected at record #{report.get('failed_at_index')}", file=sys.stderr)
|
|
34
|
+
print(f"Error: {report.get('error')}", file=sys.stderr)
|
|
35
|
+
if "expected_prev_hash" in report:
|
|
36
|
+
print(f"Expected prev_hash: {report['expected_prev_hash']}", file=sys.stderr)
|
|
37
|
+
print(f"Actual prev_hash: {report['actual_prev_hash']}", file=sys.stderr)
|
|
38
|
+
print("Chain broken.", file=sys.stderr)
|
|
39
|
+
return 1
|
|
40
|
+
except Exception as exc:
|
|
41
|
+
print(f"[ERROR] Verification failed: {exc}", file=sys.stderr)
|
|
42
|
+
return 1
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def cmd_tail(args: argparse.Namespace) -> int:
|
|
46
|
+
path = Path(args.ledger)
|
|
47
|
+
if not path.exists():
|
|
48
|
+
print(f"[ERROR] Ledger file not found: {path}", file=sys.stderr)
|
|
49
|
+
return 1
|
|
50
|
+
|
|
51
|
+
with Ledger(path) as ledger:
|
|
52
|
+
receipts = ledger.tail(n=args.n)
|
|
53
|
+
|
|
54
|
+
if args.json:
|
|
55
|
+
for r in receipts:
|
|
56
|
+
print(json.dumps(r.to_dict(), ensure_ascii=False))
|
|
57
|
+
else:
|
|
58
|
+
for r in receipts:
|
|
59
|
+
sig_badge = " [signed]" if r.signature else ""
|
|
60
|
+
print(f"#{r.index} [{r.timestamp}] agent={r.agent_id} type={r.event_type} hash={r.hash[:16]}...{sig_badge}")
|
|
61
|
+
return 0
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def cmd_export(args: argparse.Namespace) -> int:
|
|
65
|
+
path = Path(args.ledger)
|
|
66
|
+
if not path.exists():
|
|
67
|
+
print(f"[ERROR] Ledger file not found: {path}", file=sys.stderr)
|
|
68
|
+
return 1
|
|
69
|
+
|
|
70
|
+
out_file = None
|
|
71
|
+
if args.output:
|
|
72
|
+
out_file = open(args.output, "w", encoding="utf-8")
|
|
73
|
+
|
|
74
|
+
try:
|
|
75
|
+
with Ledger(path) as ledger:
|
|
76
|
+
for r in ledger:
|
|
77
|
+
line = json.dumps(r.to_dict(), ensure_ascii=False) + "\n"
|
|
78
|
+
if out_file:
|
|
79
|
+
out_file.write(line)
|
|
80
|
+
else:
|
|
81
|
+
sys.stdout.write(line)
|
|
82
|
+
if args.output:
|
|
83
|
+
print(f"[OK] Exported ledger to {args.output}")
|
|
84
|
+
return 0
|
|
85
|
+
finally:
|
|
86
|
+
if out_file:
|
|
87
|
+
out_file.close()
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def cmd_inspect(args: argparse.Namespace) -> int:
|
|
91
|
+
path = Path(args.ledger)
|
|
92
|
+
if not path.exists():
|
|
93
|
+
print(f"[ERROR] Ledger file not found: {path}", file=sys.stderr)
|
|
94
|
+
return 1
|
|
95
|
+
|
|
96
|
+
with Ledger(path) as ledger:
|
|
97
|
+
target = ledger.storage.get_by_index(args.index)
|
|
98
|
+
|
|
99
|
+
if not target:
|
|
100
|
+
print(f"[ERROR] Record #{args.index} not found.", file=sys.stderr)
|
|
101
|
+
return 1
|
|
102
|
+
|
|
103
|
+
print(json.dumps(target.to_dict(), indent=2, ensure_ascii=False))
|
|
104
|
+
return 0
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def cmd_proof(args: argparse.Namespace) -> int:
|
|
108
|
+
path = Path(args.ledger)
|
|
109
|
+
if not path.exists():
|
|
110
|
+
print(f"[ERROR] Ledger file not found: {path}", file=sys.stderr)
|
|
111
|
+
return 1
|
|
112
|
+
|
|
113
|
+
try:
|
|
114
|
+
with Ledger(path) as ledger:
|
|
115
|
+
out_path = args.output or f"{path.stem}_event_{args.index}.tezcaproof"
|
|
116
|
+
bundle = ledger.export_proof(args.index, output_path=out_path)
|
|
117
|
+
|
|
118
|
+
print(f"[OK] Cryptographic proof bundle exported to {out_path}")
|
|
119
|
+
print(f"[OK] Merkle root: {bundle.merkle_root}")
|
|
120
|
+
print(f"[OK] Receipt hash: {bundle.receipt.hash}")
|
|
121
|
+
return 0
|
|
122
|
+
except IndexError as ex:
|
|
123
|
+
print(f"[ERROR] {ex}", file=sys.stderr)
|
|
124
|
+
return 1
|
|
125
|
+
except Exception as exc:
|
|
126
|
+
print(f"[ERROR] Failed to export proof: {exc}", file=sys.stderr)
|
|
127
|
+
return 1
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def cmd_verify_proof(args: argparse.Namespace) -> int:
|
|
131
|
+
path = Path(args.proof_file)
|
|
132
|
+
if not path.exists():
|
|
133
|
+
print(f"[ERROR] Proof file not found: {path}", file=sys.stderr)
|
|
134
|
+
return 1
|
|
135
|
+
|
|
136
|
+
try:
|
|
137
|
+
bundle = ProofBundle.load(path)
|
|
138
|
+
valid, msg = bundle.verify(secret_key=args.secret_key)
|
|
139
|
+
if valid:
|
|
140
|
+
print(f"[OK] Proof verified: Receipt #{bundle.receipt.index} is cryptographically sealed.")
|
|
141
|
+
print(f"[OK] Merkle Root: {bundle.merkle_root}")
|
|
142
|
+
print(f"[OK] Event Hash: {bundle.receipt.hash}")
|
|
143
|
+
return 0
|
|
144
|
+
else:
|
|
145
|
+
print(f"[FAIL] Proof verification failed: {msg}", file=sys.stderr)
|
|
146
|
+
return 1
|
|
147
|
+
except Exception as exc:
|
|
148
|
+
print(f"[ERROR] Invalid proof bundle: {exc}", file=sys.stderr)
|
|
149
|
+
return 1
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
153
|
+
parser = argparse.ArgumentParser(
|
|
154
|
+
prog="tezca",
|
|
155
|
+
description="Zero-dependency, hash-chained forensic ledger CLI for AI agents.",
|
|
156
|
+
)
|
|
157
|
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
158
|
+
|
|
159
|
+
# verify
|
|
160
|
+
p_verify = subparsers.add_parser("verify", help="Verify cryptographic integrity of a ledger.")
|
|
161
|
+
p_verify.add_argument("ledger", help="Path to audit.db or audit.jsonl")
|
|
162
|
+
p_verify.add_argument("--secret-key", help="Optional HMAC secret key to verify receipt signatures")
|
|
163
|
+
p_verify.set_defaults(func=cmd_verify)
|
|
164
|
+
|
|
165
|
+
# tail
|
|
166
|
+
p_tail = subparsers.add_parser("tail", help="Show the most recent receipts.")
|
|
167
|
+
p_tail.add_argument("ledger", help="Path to audit.db or audit.jsonl")
|
|
168
|
+
p_tail.add_argument("-n", type=int, default=10, help="Number of records to show (default: 10)")
|
|
169
|
+
p_tail.add_argument("--json", action="store_true", help="Output raw JSON format")
|
|
170
|
+
p_tail.set_defaults(func=cmd_tail)
|
|
171
|
+
|
|
172
|
+
# export
|
|
173
|
+
p_export = subparsers.add_parser("export", help="Export ledger records to JSON Lines.")
|
|
174
|
+
p_export.add_argument("ledger", help="Path to audit.db or audit.jsonl")
|
|
175
|
+
p_export.add_argument("-o", "--output", help="Output file path (default: stdout)")
|
|
176
|
+
p_export.set_defaults(func=cmd_export)
|
|
177
|
+
|
|
178
|
+
# inspect
|
|
179
|
+
p_inspect = subparsers.add_parser("inspect", help="Inspect a specific receipt by index.")
|
|
180
|
+
p_inspect.add_argument("ledger", help="Path to audit.db or audit.jsonl")
|
|
181
|
+
p_inspect.add_argument("index", type=int, help="Record index number")
|
|
182
|
+
p_inspect.set_defaults(func=cmd_inspect)
|
|
183
|
+
|
|
184
|
+
# proof
|
|
185
|
+
p_proof = subparsers.add_parser("proof", help="Export a standalone cryptographic proof bundle (.tezcaproof).")
|
|
186
|
+
p_proof.add_argument("ledger", help="Path to audit.db or audit.jsonl")
|
|
187
|
+
p_proof.add_argument("index", type=int, help="Record index to prove")
|
|
188
|
+
p_proof.add_argument("-o", "--output", help="Output path (default: <ledger>_event_<idx>.tezcaproof)")
|
|
189
|
+
p_proof.set_defaults(func=cmd_proof)
|
|
190
|
+
|
|
191
|
+
# verify-proof
|
|
192
|
+
p_vproof = subparsers.add_parser("verify-proof", help="Verify an offline cryptographic proof bundle.")
|
|
193
|
+
p_vproof.add_argument("proof_file", help="Path to .tezcaproof file")
|
|
194
|
+
p_vproof.add_argument("--secret-key", help="Optional secret key to verify HMAC signature")
|
|
195
|
+
p_vproof.set_defaults(func=cmd_verify_proof)
|
|
196
|
+
|
|
197
|
+
return parser
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def main(argv: list[str] | None = None) -> int:
|
|
201
|
+
parser = build_parser()
|
|
202
|
+
args = parser.parse_args(argv)
|
|
203
|
+
return args.func(args)
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
if __name__ == "__main__":
|
|
207
|
+
sys.exit(main())
|
tezca/events.py
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Standardized event schema and typed enumerations for AI agent audit logging.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import enum
|
|
8
|
+
from dataclasses import dataclass, field
|
|
9
|
+
from typing import Any, Optional, Union
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class AgentEventType(str, enum.Enum):
|
|
13
|
+
"""Canonical event types for AI agent forensic audit trails."""
|
|
14
|
+
|
|
15
|
+
PROMPT = "prompt"
|
|
16
|
+
COMPLETION = "completion"
|
|
17
|
+
TOOL_CALL = "tool_call"
|
|
18
|
+
TOOL_RESULT = "tool_result"
|
|
19
|
+
GUARDRAIL_VERDICT = "guardrail_verdict"
|
|
20
|
+
AGENT_THOUGHT = "thought"
|
|
21
|
+
DELEGATION = "delegation"
|
|
22
|
+
ERROR = "error"
|
|
23
|
+
CUSTOM = "custom"
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass
|
|
27
|
+
class AgentEvent:
|
|
28
|
+
"""
|
|
29
|
+
Standardized, high-level representation of an AI agent event.
|
|
30
|
+
Provides structured schemas for LLM prompts, tool invocations, and guardrail verdicts.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
agent_id: str
|
|
34
|
+
event_type: Union[AgentEventType, str]
|
|
35
|
+
data: dict[str, Any]
|
|
36
|
+
session_id: Optional[str] = None
|
|
37
|
+
model: Optional[str] = None
|
|
38
|
+
token_usage: Optional[dict[str, int]] = None
|
|
39
|
+
latency_ms: Optional[float] = None
|
|
40
|
+
metadata: dict[str, Any] = field(default_factory=dict)
|
|
41
|
+
|
|
42
|
+
def to_record_kwargs(self) -> dict[str, Any]:
|
|
43
|
+
"""Convert this event into Ledger.record() arguments."""
|
|
44
|
+
ev_type = self.event_type.value if isinstance(self.event_type, AgentEventType) else str(self.event_type)
|
|
45
|
+
combined_meta = dict(self.metadata)
|
|
46
|
+
|
|
47
|
+
if self.session_id is not None:
|
|
48
|
+
combined_meta["session_id"] = self.session_id
|
|
49
|
+
if self.model is not None:
|
|
50
|
+
combined_meta["model"] = self.model
|
|
51
|
+
if self.token_usage is not None:
|
|
52
|
+
combined_meta["token_usage"] = self.token_usage
|
|
53
|
+
if self.latency_ms is not None:
|
|
54
|
+
combined_meta["latency_ms"] = self.latency_ms
|
|
55
|
+
|
|
56
|
+
return {
|
|
57
|
+
"agent_id": self.agent_id,
|
|
58
|
+
"event_type": ev_type,
|
|
59
|
+
"data": self.data,
|
|
60
|
+
"metadata": combined_meta,
|
|
61
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Framework integrations and interceptors for tezca.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from tezca.integrations.interceptors import track_agent_call, wrap_completion, wrap_tool
|
|
8
|
+
from tezca.integrations.langchain import TezcaCallbackHandler
|
|
9
|
+
|
|
10
|
+
__all__ = [
|
|
11
|
+
"TezcaCallbackHandler",
|
|
12
|
+
"track_agent_call",
|
|
13
|
+
"wrap_completion",
|
|
14
|
+
"wrap_tool",
|
|
15
|
+
]
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Zero-dependency interceptors and decorators for OpenAI, Anthropic, and custom agent tools.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import asyncio
|
|
8
|
+
import functools
|
|
9
|
+
import inspect
|
|
10
|
+
import time
|
|
11
|
+
from contextlib import contextmanager
|
|
12
|
+
from typing import Any, Callable, Iterator, Optional
|
|
13
|
+
|
|
14
|
+
from tezca.events import AgentEventType
|
|
15
|
+
from tezca.ledger import Ledger
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def wrap_tool(
|
|
19
|
+
ledger: Ledger,
|
|
20
|
+
agent_id: str = "tool-runner",
|
|
21
|
+
tool_name: Optional[str] = None,
|
|
22
|
+
) -> Callable:
|
|
23
|
+
"""
|
|
24
|
+
Decorator for Python tool functions and agent actions.
|
|
25
|
+
Automatically captures arguments, execution latency, and return values/exceptions.
|
|
26
|
+
Supports both synchronous and asynchronous functions.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
def decorator(fn: Callable) -> Callable:
|
|
30
|
+
name = tool_name or fn.__name__
|
|
31
|
+
|
|
32
|
+
if inspect.iscoroutinefunction(fn):
|
|
33
|
+
|
|
34
|
+
@functools.wraps(fn)
|
|
35
|
+
async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
|
|
36
|
+
bound_args = {"args": args, "kwargs": kwargs}
|
|
37
|
+
ledger.record(
|
|
38
|
+
agent_id=agent_id,
|
|
39
|
+
event_type=AgentEventType.TOOL_CALL.value,
|
|
40
|
+
data={"tool": name, "arguments": bound_args},
|
|
41
|
+
)
|
|
42
|
+
start = time.perf_counter()
|
|
43
|
+
try:
|
|
44
|
+
result = await fn(*args, **kwargs)
|
|
45
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
46
|
+
ledger.record(
|
|
47
|
+
agent_id=agent_id,
|
|
48
|
+
event_type=AgentEventType.TOOL_RESULT.value,
|
|
49
|
+
data={"tool": name, "result": result},
|
|
50
|
+
metadata={"latency_ms": round(elapsed, 2)},
|
|
51
|
+
)
|
|
52
|
+
return result
|
|
53
|
+
except Exception as ex:
|
|
54
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
55
|
+
ledger.record(
|
|
56
|
+
agent_id=agent_id,
|
|
57
|
+
event_type=AgentEventType.ERROR.value,
|
|
58
|
+
data={"tool": name, "error_type": type(ex).__name__, "error": str(ex)},
|
|
59
|
+
metadata={"latency_ms": round(elapsed, 2)},
|
|
60
|
+
)
|
|
61
|
+
raise
|
|
62
|
+
|
|
63
|
+
return async_wrapper
|
|
64
|
+
|
|
65
|
+
else:
|
|
66
|
+
|
|
67
|
+
@functools.wraps(fn)
|
|
68
|
+
def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
|
|
69
|
+
bound_args = {"args": args, "kwargs": kwargs}
|
|
70
|
+
ledger.record(
|
|
71
|
+
agent_id=agent_id,
|
|
72
|
+
event_type=AgentEventType.TOOL_CALL.value,
|
|
73
|
+
data={"tool": name, "arguments": bound_args},
|
|
74
|
+
)
|
|
75
|
+
start = time.perf_counter()
|
|
76
|
+
try:
|
|
77
|
+
result = fn(*args, **kwargs)
|
|
78
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
79
|
+
ledger.record(
|
|
80
|
+
agent_id=agent_id,
|
|
81
|
+
event_type=AgentEventType.TOOL_RESULT.value,
|
|
82
|
+
data={"tool": name, "result": result},
|
|
83
|
+
metadata={"latency_ms": round(elapsed, 2)},
|
|
84
|
+
)
|
|
85
|
+
return result
|
|
86
|
+
except Exception as ex:
|
|
87
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
88
|
+
ledger.record(
|
|
89
|
+
agent_id=agent_id,
|
|
90
|
+
event_type=AgentEventType.ERROR.value,
|
|
91
|
+
data={"tool": name, "error_type": type(ex).__name__, "error": str(ex)},
|
|
92
|
+
metadata={"latency_ms": round(elapsed, 2)},
|
|
93
|
+
)
|
|
94
|
+
raise
|
|
95
|
+
|
|
96
|
+
return sync_wrapper
|
|
97
|
+
|
|
98
|
+
return decorator
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def wrap_completion(
|
|
102
|
+
ledger: Ledger,
|
|
103
|
+
agent_id: str = "llm-agent",
|
|
104
|
+
model: Optional[str] = None,
|
|
105
|
+
) -> Callable:
|
|
106
|
+
"""
|
|
107
|
+
Decorator for OpenAI, Anthropic, or custom LLM client completion functions.
|
|
108
|
+
Extracts prompts, generated responses, token usage, and latency.
|
|
109
|
+
"""
|
|
110
|
+
|
|
111
|
+
def decorator(fn: Callable) -> Callable:
|
|
112
|
+
if inspect.iscoroutinefunction(fn):
|
|
113
|
+
|
|
114
|
+
@functools.wraps(fn)
|
|
115
|
+
async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
|
|
116
|
+
messages = kwargs.get("messages") or kwargs.get("prompt") or args
|
|
117
|
+
used_model = kwargs.get("model") or model or "unknown"
|
|
118
|
+
ledger.record(
|
|
119
|
+
agent_id=agent_id,
|
|
120
|
+
event_type=AgentEventType.PROMPT.value,
|
|
121
|
+
data={"messages": messages, "model": used_model},
|
|
122
|
+
)
|
|
123
|
+
start = time.perf_counter()
|
|
124
|
+
try:
|
|
125
|
+
response = await fn(*args, **kwargs)
|
|
126
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
127
|
+
usage = getattr(response, "usage", None)
|
|
128
|
+
usage_dict = usage if isinstance(usage, dict) else (usage.__dict__ if hasattr(usage, "__dict__") else None)
|
|
129
|
+
|
|
130
|
+
ledger.record(
|
|
131
|
+
agent_id=agent_id,
|
|
132
|
+
event_type=AgentEventType.COMPLETION.value,
|
|
133
|
+
data={"response": str(response)},
|
|
134
|
+
metadata={
|
|
135
|
+
"model": used_model,
|
|
136
|
+
"latency_ms": round(elapsed, 2),
|
|
137
|
+
"token_usage": usage_dict,
|
|
138
|
+
},
|
|
139
|
+
)
|
|
140
|
+
return response
|
|
141
|
+
except Exception as ex:
|
|
142
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
143
|
+
ledger.record(
|
|
144
|
+
agent_id=agent_id,
|
|
145
|
+
event_type=AgentEventType.ERROR.value,
|
|
146
|
+
data={"error_type": type(ex).__name__, "error": str(ex)},
|
|
147
|
+
metadata={"model": used_model, "latency_ms": round(elapsed, 2)},
|
|
148
|
+
)
|
|
149
|
+
raise
|
|
150
|
+
|
|
151
|
+
return async_wrapper
|
|
152
|
+
|
|
153
|
+
else:
|
|
154
|
+
|
|
155
|
+
@functools.wraps(fn)
|
|
156
|
+
def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
|
|
157
|
+
messages = kwargs.get("messages") or kwargs.get("prompt") or args
|
|
158
|
+
used_model = kwargs.get("model") or model or "unknown"
|
|
159
|
+
ledger.record(
|
|
160
|
+
agent_id=agent_id,
|
|
161
|
+
event_type=AgentEventType.PROMPT.value,
|
|
162
|
+
data={"messages": messages, "model": used_model},
|
|
163
|
+
)
|
|
164
|
+
start = time.perf_counter()
|
|
165
|
+
try:
|
|
166
|
+
response = fn(*args, **kwargs)
|
|
167
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
168
|
+
usage = getattr(response, "usage", None)
|
|
169
|
+
usage_dict = usage if isinstance(usage, dict) else (usage.__dict__ if hasattr(usage, "__dict__") else None)
|
|
170
|
+
|
|
171
|
+
ledger.record(
|
|
172
|
+
agent_id=agent_id,
|
|
173
|
+
event_type=AgentEventType.COMPLETION.value,
|
|
174
|
+
data={"response": str(response)},
|
|
175
|
+
metadata={
|
|
176
|
+
"model": used_model,
|
|
177
|
+
"latency_ms": round(elapsed, 2),
|
|
178
|
+
"token_usage": usage_dict,
|
|
179
|
+
},
|
|
180
|
+
)
|
|
181
|
+
return response
|
|
182
|
+
except Exception as ex:
|
|
183
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
184
|
+
ledger.record(
|
|
185
|
+
agent_id=agent_id,
|
|
186
|
+
event_type=AgentEventType.ERROR.value,
|
|
187
|
+
data={"error_type": type(ex).__name__, "error": str(ex)},
|
|
188
|
+
metadata={"model": used_model, "latency_ms": round(elapsed, 2)},
|
|
189
|
+
)
|
|
190
|
+
raise
|
|
191
|
+
|
|
192
|
+
return sync_wrapper
|
|
193
|
+
|
|
194
|
+
return decorator
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
@contextmanager
|
|
198
|
+
def track_agent_call(
|
|
199
|
+
ledger: Ledger,
|
|
200
|
+
agent_id: str,
|
|
201
|
+
event_type: str = "action",
|
|
202
|
+
data: Optional[dict[str, Any]] = None,
|
|
203
|
+
) -> Iterator[dict[str, Any]]:
|
|
204
|
+
"""
|
|
205
|
+
Context manager to trace and seal an arbitrary block of agent logic.
|
|
206
|
+
Yields a mutable context dict where extra metadata can be attached.
|
|
207
|
+
"""
|
|
208
|
+
ctx: dict[str, Any] = {}
|
|
209
|
+
payload = data if data is not None else {}
|
|
210
|
+
start = time.perf_counter()
|
|
211
|
+
try:
|
|
212
|
+
yield ctx
|
|
213
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
214
|
+
ledger.record(
|
|
215
|
+
agent_id=agent_id,
|
|
216
|
+
event_type=event_type,
|
|
217
|
+
data=payload,
|
|
218
|
+
metadata={"latency_ms": round(elapsed, 2), **ctx},
|
|
219
|
+
)
|
|
220
|
+
except Exception as ex:
|
|
221
|
+
elapsed = (time.perf_counter() - start) * 1000.0
|
|
222
|
+
ledger.record(
|
|
223
|
+
agent_id=agent_id,
|
|
224
|
+
event_type=AgentEventType.ERROR.value,
|
|
225
|
+
data={"error_type": type(ex).__name__, "error": str(ex), **payload},
|
|
226
|
+
metadata={"latency_ms": round(elapsed, 2), **ctx},
|
|
227
|
+
)
|
|
228
|
+
raise
|