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 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
@@ -0,0 +1,10 @@
1
+ """
2
+ Module execution entrypoint for python -m tezca.
3
+ """
4
+
5
+ import sys
6
+
7
+ from tezca.cli import main
8
+
9
+ if __name__ == "__main__":
10
+ sys.exit(main())
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