agentspec-sdk 0.5.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.
- agentspec_sdk/__init__.py +19 -0
- agentspec_sdk/agentspec_contract.py +522 -0
- agentspec_sdk/evidence_points.py +385 -0
- agentspec_sdk/manifest.py +36 -0
- agentspec_sdk/manifest_hash.py +52 -0
- agentspec_sdk/memory_points.py +359 -0
- agentspec_sdk/reporter.py +319 -0
- agentspec_sdk/types.py +33 -0
- agentspec_sdk-0.5.0.dist-info/METADATA +75 -0
- agentspec_sdk-0.5.0.dist-info/RECORD +11 -0
- agentspec_sdk-0.5.0.dist-info/WHEEL +4 -0
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
"""
|
|
2
|
+
memory_write and vector_store evidence points (ADR-0038, ADR-0039).
|
|
3
|
+
|
|
4
|
+
`memory_write` returns the LangGraph checkpointer or Store it is given, with its writes scrubbed of
|
|
5
|
+
the PII fields the manifest declares, given the declared TTL where the backend can apply it, and
|
|
6
|
+
audited. Each write is a record for MEM-01 (scrub), MEM-02 (TTL) and MEM-03 (audit entry).
|
|
7
|
+
`vector_store` wraps a vector store client; each call is a MEM-04 record carrying its namespace.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import contextlib
|
|
13
|
+
import contextvars
|
|
14
|
+
import functools
|
|
15
|
+
import inspect
|
|
16
|
+
import json
|
|
17
|
+
import logging
|
|
18
|
+
import re
|
|
19
|
+
from typing import Any, Callable, Dict, Iterator, Optional, Tuple
|
|
20
|
+
|
|
21
|
+
from .evidence_points import (
|
|
22
|
+
AUDIT, CONTRACT, MEMORY_WRITE, NAMESPACE, SCRUB, TTL, VECTOR_STORE,
|
|
23
|
+
EvidencePoints, _default_points,
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
AUDIT_LOGGER = logging.getLogger("agentspec.memory.audit")
|
|
27
|
+
REDACTED = "[REDACTED]"
|
|
28
|
+
TTL_APPLIED, TTL_PASSED_THROUGH, TTL_UNSUPPORTED = "applied", "passed-through", "unsupported"
|
|
29
|
+
_NOT_VERIFIABLE_CODE = "instrumentation_unavailable"
|
|
30
|
+
_WRONG_NAMESPACE_CODE = "undeclared_namespace"
|
|
31
|
+
_NO_NAMESPACE_CODE = "no_evidence"
|
|
32
|
+
for _code in (_NOT_VERIFIABLE_CODE, _WRONG_NAMESPACE_CODE, _NO_NAMESPACE_CODE):
|
|
33
|
+
assert _code in CONTRACT.reasonCodes, f"contract.reasonCodes lacks {_code!r}"
|
|
34
|
+
|
|
35
|
+
# Regex baseline for the entity names spec.memory.hygiene.piiScrubFields uses; other names match by key only.
|
|
36
|
+
_PATTERNS: Dict[str, "re.Pattern[str]"] = {
|
|
37
|
+
"email": re.compile(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+"),
|
|
38
|
+
"ssn": re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
|
|
39
|
+
"credit_card": re.compile(r"\b(?:\d[ -]?){13,16}\b"),
|
|
40
|
+
"iban": re.compile(r"\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b"),
|
|
41
|
+
"phone_number": re.compile(r"\+\d[\d ().-]{7,}\d|\(?\b\d{3}\)?[ .-]\d{3}[ .-]\d{4}\b"), # an international +, or a 3-3-4 layout: not dates or ids
|
|
42
|
+
"ip_address": re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b"),
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def scrub(value: Any, fields: Tuple[str, ...], by_value: bool = True) -> Tuple[Any, int]:
|
|
47
|
+
"""
|
|
48
|
+
`value` with the declared PII fields redacted, and how many were. Dict, list and tuple containers
|
|
49
|
+
and pydantic models (LangChain messages) keep their shape and type, every other object is left as it is; a new structure is returned, the
|
|
50
|
+
argument is never mutated. Everything under a dict key or model field named as a declared field is redacted; a string is
|
|
51
|
+
also searched for the declared fields that have a pattern when `by_value`.
|
|
52
|
+
"""
|
|
53
|
+
wanted = {f.lower() for f in fields}
|
|
54
|
+
patterns = [p for name, p in _PATTERNS.items() if name in wanted] if by_value else []
|
|
55
|
+
|
|
56
|
+
def walk(node: Any, declared: bool = False) -> Tuple[Any, int]:
|
|
57
|
+
"""`declared`: the node sits under a declared field, so every leaf in it is redacted."""
|
|
58
|
+
if isinstance(node, dict):
|
|
59
|
+
out, found = {}, 0
|
|
60
|
+
for key, child in node.items():
|
|
61
|
+
out[key], n = walk(child, declared or (isinstance(key, str) and key.lower() in wanted))
|
|
62
|
+
found += n
|
|
63
|
+
return out, found
|
|
64
|
+
if type(node) in (list, tuple):
|
|
65
|
+
walked = [walk(child, declared) for child in node]
|
|
66
|
+
return type(node)(w[0] for w in walked), sum(w[1] for w in walked)
|
|
67
|
+
if hasattr(node, "model_copy") and hasattr(node, "model_fields_set"):
|
|
68
|
+
return walk_model(node, declared) # a LangChain message or another pydantic model: copied, type kept
|
|
69
|
+
if declared and not isinstance(node, (dict, list, tuple)) and node is not None:
|
|
70
|
+
return REDACTED, 1
|
|
71
|
+
if isinstance(node, str):
|
|
72
|
+
found = 0
|
|
73
|
+
for pattern in patterns:
|
|
74
|
+
node, n = pattern.subn(REDACTED, node)
|
|
75
|
+
found += n
|
|
76
|
+
return node, found
|
|
77
|
+
return node, 0
|
|
78
|
+
|
|
79
|
+
def walk_model(node: Any, declared: bool) -> Tuple[Any, int]:
|
|
80
|
+
changes, found = {}, 0
|
|
81
|
+
for name in type(node).model_fields:
|
|
82
|
+
child = getattr(node, name, None)
|
|
83
|
+
new, n = walk(child, declared or name.lower() in wanted)
|
|
84
|
+
if n:
|
|
85
|
+
changes[name], found = new, found + n
|
|
86
|
+
return (node.model_copy(update=changes) if changes else node), found
|
|
87
|
+
|
|
88
|
+
return walk(value)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
_inside: contextvars.ContextVar[bool] = contextvars.ContextVar("agentspec_memory_write_inside", default=False)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@contextlib.contextmanager
|
|
95
|
+
def _outermost() -> Iterator[bool]:
|
|
96
|
+
"""True for the outermost write only: a backend's `aput` that calls its own `put` is one write, not two."""
|
|
97
|
+
if _inside.get():
|
|
98
|
+
yield False
|
|
99
|
+
return
|
|
100
|
+
token = _inside.set(True)
|
|
101
|
+
try:
|
|
102
|
+
yield True
|
|
103
|
+
finally:
|
|
104
|
+
_inside.reset(token)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class _Writes:
|
|
108
|
+
"""What one wrapped backend does on a write; the checkpointer and Store proxies share it."""
|
|
109
|
+
|
|
110
|
+
def __init__(self, points: EvidencePoints, kind: str, fields: Tuple[str, ...], ttl_seconds: Optional[int]) -> None:
|
|
111
|
+
self.points = points
|
|
112
|
+
self.kind = kind
|
|
113
|
+
self.fields = fields
|
|
114
|
+
self.ttl_seconds = ttl_seconds
|
|
115
|
+
|
|
116
|
+
@staticmethod
|
|
117
|
+
def capped(requested: Optional[float], declared: float) -> float:
|
|
118
|
+
"""The declared TTL, or the caller's own when it is shorter: a write never outlives the declared retention."""
|
|
119
|
+
return declared if requested is None or requested > declared else requested
|
|
120
|
+
|
|
121
|
+
def scrubbed(self, value: Any, by_value: bool = True) -> Tuple[Any, int]:
|
|
122
|
+
return scrub(value, self.fields, by_value) if self.fields else (value, 0)
|
|
123
|
+
|
|
124
|
+
def record(self, operation: str, scrubbed: int, ttl: Optional[str]) -> None:
|
|
125
|
+
"""One write: the MEM-01 record, the MEM-02 record when a TTL is declared, the audit entry and MEM-03 record."""
|
|
126
|
+
subject = f"memory:{self.kind}:{operation}"
|
|
127
|
+
self.points.record_call(MEMORY_WRITE, SCRUB, subject)
|
|
128
|
+
if ttl is not None:
|
|
129
|
+
applied = ttl != TTL_UNSUPPORTED
|
|
130
|
+
self.points.record_call(
|
|
131
|
+
MEMORY_WRITE, TTL, f"{subject}:ttl={ttl}", "pass" if applied else "not_verifiable",
|
|
132
|
+
None if applied else {"code": _NOT_VERIFIABLE_CODE, "detail": f"the {self.kind} backend cannot apply a TTL"},
|
|
133
|
+
)
|
|
134
|
+
if self.points.applies(MEMORY_WRITE, AUDIT):
|
|
135
|
+
AUDIT_LOGGER.info(json.dumps({
|
|
136
|
+
"event": "memory.write", "backend": self.kind, "operation": operation,
|
|
137
|
+
"scrubbed": scrubbed, "ttl": ttl,
|
|
138
|
+
}))
|
|
139
|
+
if AUDIT_LOGGER.isEnabledFor(logging.INFO) and AUDIT_LOGGER.hasHandlers():
|
|
140
|
+
self.points.record_call(MEMORY_WRITE, AUDIT, subject)
|
|
141
|
+
else: # Python's default logging drops INFO: the entry went nowhere, so it proves nothing
|
|
142
|
+
self.points.record_call(
|
|
143
|
+
MEMORY_WRITE, AUDIT, subject, "not_verifiable",
|
|
144
|
+
{"code": _NOT_VERIFIABLE_CODE, "detail": f"no log output receives INFO from {AUDIT_LOGGER.name!r}; configure logging"},
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _accepts_ttl(fn: Callable[..., Any]) -> bool:
|
|
149
|
+
try:
|
|
150
|
+
return "ttl" in inspect.signature(fn).parameters
|
|
151
|
+
except (TypeError, ValueError):
|
|
152
|
+
return False
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
class _CheckpointerWrites:
|
|
156
|
+
"""Overrides of a LangGraph checkpointer's writes; `_agentspec` holds the `_Writes`."""
|
|
157
|
+
|
|
158
|
+
def _prepare(self, method: str, kwargs: Dict[str, Any]) -> Optional[str]:
|
|
159
|
+
"""Hand the declared TTL to a write that accepts one: a checkpointer has no per-item TTL otherwise."""
|
|
160
|
+
writes: _Writes = self._agentspec
|
|
161
|
+
if writes.ttl_seconds is None:
|
|
162
|
+
return None
|
|
163
|
+
if writes.ttl_seconds == 0: # session-scoped retention: no per-item expiry to forward
|
|
164
|
+
return TTL_UNSUPPORTED
|
|
165
|
+
if _accepts_ttl(getattr(super(), method)):
|
|
166
|
+
kwargs["ttl"] = writes.capped(kwargs.get("ttl"), writes.ttl_seconds)
|
|
167
|
+
return TTL_PASSED_THROUGH
|
|
168
|
+
return TTL_UNSUPPORTED
|
|
169
|
+
|
|
170
|
+
def _scrub_checkpoint(self, checkpoint: Any, metadata: Any) -> Tuple[Any, Any, int]:
|
|
171
|
+
values, n = self._agentspec.scrubbed(checkpoint.get("channel_values"))
|
|
172
|
+
meta, m = self._agentspec.scrubbed(metadata, by_value=False) # metadata keeps its ids and counters: by key only
|
|
173
|
+
return {**checkpoint, "channel_values": values}, meta, n + m
|
|
174
|
+
|
|
175
|
+
def _scrub_pending(self, pending: Any) -> Tuple[list, int]:
|
|
176
|
+
"""Pending writes are (channel, value): a channel named as a declared field is redacted whole."""
|
|
177
|
+
scrubbed = [(channel, *self._agentspec.scrubbed({channel: value})) for channel, value in pending]
|
|
178
|
+
return [(channel, one[channel]) for channel, one, _ in scrubbed], sum(n for _, _, n in scrubbed)
|
|
179
|
+
|
|
180
|
+
def put(self, config, checkpoint, metadata, new_versions, *args, **kwargs):
|
|
181
|
+
with _outermost() as outer:
|
|
182
|
+
if not outer:
|
|
183
|
+
return super().put(config, checkpoint, metadata, new_versions, *args, **kwargs)
|
|
184
|
+
checkpoint, metadata, n = self._scrub_checkpoint(checkpoint, metadata)
|
|
185
|
+
ttl = self._prepare("put", kwargs)
|
|
186
|
+
result = super().put(config, checkpoint, metadata, new_versions, *args, **kwargs)
|
|
187
|
+
self._agentspec.record("put", n, ttl)
|
|
188
|
+
return result
|
|
189
|
+
|
|
190
|
+
def put_writes(self, config, pending, task_id, *args, **kwargs):
|
|
191
|
+
with _outermost() as outer:
|
|
192
|
+
if not outer:
|
|
193
|
+
return super().put_writes(config, pending, task_id, *args, **kwargs)
|
|
194
|
+
pending, n = self._scrub_pending(pending)
|
|
195
|
+
ttl = self._prepare("put_writes", kwargs)
|
|
196
|
+
result = super().put_writes(config, pending, task_id, *args, **kwargs)
|
|
197
|
+
self._agentspec.record("put_writes", n, ttl)
|
|
198
|
+
return result
|
|
199
|
+
|
|
200
|
+
async def aput(self, config, checkpoint, metadata, new_versions, *args, **kwargs):
|
|
201
|
+
with _outermost() as outer:
|
|
202
|
+
if not outer:
|
|
203
|
+
return await super().aput(config, checkpoint, metadata, new_versions, *args, **kwargs)
|
|
204
|
+
checkpoint, metadata, n = self._scrub_checkpoint(checkpoint, metadata)
|
|
205
|
+
ttl = self._prepare("aput", kwargs)
|
|
206
|
+
result = await super().aput(config, checkpoint, metadata, new_versions, *args, **kwargs)
|
|
207
|
+
self._agentspec.record("put", n, ttl)
|
|
208
|
+
return result
|
|
209
|
+
|
|
210
|
+
async def aput_writes(self, config, pending, task_id, *args, **kwargs):
|
|
211
|
+
with _outermost() as outer:
|
|
212
|
+
if not outer:
|
|
213
|
+
return await super().aput_writes(config, pending, task_id, *args, **kwargs)
|
|
214
|
+
pending, n = self._scrub_pending(pending)
|
|
215
|
+
ttl = self._prepare("aput_writes", kwargs)
|
|
216
|
+
result = await super().aput_writes(config, pending, task_id, *args, **kwargs)
|
|
217
|
+
self._agentspec.record("put_writes", n, ttl)
|
|
218
|
+
return result
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
class _StoreWrites:
|
|
222
|
+
"""Overrides of a LangGraph Store's `batch` and `abatch`, which `put`, `aput` and `delete` go through."""
|
|
223
|
+
|
|
224
|
+
def _prepare(self, ops: Any) -> Tuple[list, list]:
|
|
225
|
+
"""The ops with each put's value scrubbed and TTL set, and one (scrubbed, ttl state) per put."""
|
|
226
|
+
writes: _Writes = self._agentspec
|
|
227
|
+
prepared, puts = [], []
|
|
228
|
+
for op in ops:
|
|
229
|
+
if getattr(op, "value", None) is None or not hasattr(op, "_replace"):
|
|
230
|
+
prepared.append(op)
|
|
231
|
+
continue
|
|
232
|
+
value, n = writes.scrubbed(op.value)
|
|
233
|
+
changes: Dict[str, Any] = {"value": value}
|
|
234
|
+
ttl = None
|
|
235
|
+
if writes.ttl_seconds is not None:
|
|
236
|
+
supported = bool(getattr(self, "supports_ttl", False)) and writes.ttl_seconds > 0
|
|
237
|
+
if supported:
|
|
238
|
+
changes["ttl"] = writes.capped(getattr(op, "ttl", None), writes.ttl_seconds / 60) # the Store takes minutes
|
|
239
|
+
ttl = TTL_APPLIED if supported else TTL_UNSUPPORTED
|
|
240
|
+
prepared.append(op._replace(**changes))
|
|
241
|
+
puts.append((n, ttl))
|
|
242
|
+
return prepared, puts
|
|
243
|
+
|
|
244
|
+
def batch(self, ops):
|
|
245
|
+
with _outermost() as outer:
|
|
246
|
+
if not outer:
|
|
247
|
+
return super().batch(ops)
|
|
248
|
+
prepared, puts = self._prepare(ops)
|
|
249
|
+
result = super().batch(prepared)
|
|
250
|
+
for n, ttl in puts:
|
|
251
|
+
self._agentspec.record("put", n, ttl)
|
|
252
|
+
return result
|
|
253
|
+
|
|
254
|
+
async def abatch(self, ops):
|
|
255
|
+
with _outermost() as outer:
|
|
256
|
+
if not outer:
|
|
257
|
+
return await super().abatch(ops)
|
|
258
|
+
prepared, puts = self._prepare(ops)
|
|
259
|
+
result = await super().abatch(prepared)
|
|
260
|
+
for n, ttl in puts:
|
|
261
|
+
self._agentspec.record("put", n, ttl)
|
|
262
|
+
return result
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def _proxy(backend: Any, mixin: type, writes: _Writes) -> Any:
|
|
266
|
+
"""`backend` with the mixin's methods first: a subclass instance (LangGraph checks isinstance) sharing the backend's state."""
|
|
267
|
+
proxy_class = type(f"AgentSpec{type(backend).__name__}", (mixin, type(backend)), {})
|
|
268
|
+
proxy = object.__new__(proxy_class)
|
|
269
|
+
if hasattr(backend, "__dict__"):
|
|
270
|
+
proxy.__dict__ = backend.__dict__
|
|
271
|
+
for klass in type(backend).__mro__: # classes with __slots__ keep their state there
|
|
272
|
+
for slot in getattr(klass, "__slots__", ()):
|
|
273
|
+
if slot not in ("__dict__", "__weakref__") and hasattr(backend, slot):
|
|
274
|
+
setattr(proxy, slot, getattr(backend, slot))
|
|
275
|
+
proxy._agentspec = writes
|
|
276
|
+
return proxy
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
def memory_write(backend: Any) -> Any:
|
|
280
|
+
"""
|
|
281
|
+
Wrap a LangGraph checkpointer or Store (`graph = builder.compile(checkpointer=memory_write(saver))`).
|
|
282
|
+
|
|
283
|
+
Its writes are scrubbed of `spec.memory.hygiene.piiScrubFields`, given the declared TTL where the
|
|
284
|
+
backend can apply it, and audited when `hygiene.auditLog` is true. A checkpointer is the
|
|
285
|
+
short-term memory (`shortTerm.ttlSeconds`), a Store the long-term one (`longTerm.ttlDays`).
|
|
286
|
+
"""
|
|
287
|
+
points = _default_points("memory_write")
|
|
288
|
+
memory = points.memory_spec()
|
|
289
|
+
fields = tuple((memory.get("hygiene") or {}).get("piiScrubFields") or ())
|
|
290
|
+
if hasattr(backend, "put_writes"):
|
|
291
|
+
kind, ttl, mixin = "checkpointer", (memory.get("shortTerm") or {}).get("ttlSeconds"), _CheckpointerWrites
|
|
292
|
+
elif hasattr(backend, "batch"):
|
|
293
|
+
days = (memory.get("longTerm") or {}).get("ttlDays")
|
|
294
|
+
kind, ttl, mixin = "store", None if days is None else days * 24 * 60 * 60, _StoreWrites
|
|
295
|
+
else:
|
|
296
|
+
raise TypeError(f"memory_write: {type(backend).__name__} is neither a checkpointer (put_writes) nor a Store (batch)")
|
|
297
|
+
for target in CONTRACT.evidencePoints[MEMORY_WRITE]:
|
|
298
|
+
points.register(MEMORY_WRITE, target)
|
|
299
|
+
return _proxy(backend, mixin, _Writes(points, kind, fields, ttl))
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
class _VectorStore:
|
|
303
|
+
"""Delegating proxy around a vector store client: each public call records the namespace it used."""
|
|
304
|
+
|
|
305
|
+
def __init__(self, points: EvidencePoints, client: Any, namespace: Optional[str]) -> None:
|
|
306
|
+
self._points = points
|
|
307
|
+
self._client = client
|
|
308
|
+
self._namespace = namespace
|
|
309
|
+
self._declared = ((points.memory_spec().get("vector") or {}).get("namespace"))
|
|
310
|
+
points.register(VECTOR_STORE, NAMESPACE)
|
|
311
|
+
|
|
312
|
+
def _used_namespace(self, call: Callable[..., Any], args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> Optional[str]:
|
|
313
|
+
"""The namespace the call passes (keyword or positional, even an empty one), else the one the client is bound to."""
|
|
314
|
+
try:
|
|
315
|
+
passed = inspect.signature(call).bind_partial(*args, **kwargs).arguments
|
|
316
|
+
except (TypeError, ValueError): # the signature is unreadable: only a keyword is certain, a positional one is unknown
|
|
317
|
+
passed = kwargs if not args else {"namespace": kwargs.get("namespace")}
|
|
318
|
+
return passed["namespace"] if "namespace" in passed else self._namespace
|
|
319
|
+
|
|
320
|
+
def _record(self, used: Optional[str]) -> None:
|
|
321
|
+
if used is None:
|
|
322
|
+
self._points.record_call(
|
|
323
|
+
VECTOR_STORE, NAMESPACE, None, "not_verifiable",
|
|
324
|
+
{"code": _NO_NAMESPACE_CODE, "detail": "the call names no namespace; bind the client to one"},
|
|
325
|
+
)
|
|
326
|
+
elif used == self._declared:
|
|
327
|
+
self._points.record_call(VECTOR_STORE, NAMESPACE, f"vector:{used}")
|
|
328
|
+
else:
|
|
329
|
+
self._points.record_call(
|
|
330
|
+
VECTOR_STORE, NAMESPACE, f"vector:{used}", "fail",
|
|
331
|
+
{"code": _WRONG_NAMESPACE_CODE, "detail": f"namespace {used!r} is not the declared {self._declared!r}"},
|
|
332
|
+
)
|
|
333
|
+
|
|
334
|
+
def __getattr__(self, name: str) -> Any:
|
|
335
|
+
attr = getattr(self._client, name)
|
|
336
|
+
if name.startswith("_") or not callable(attr):
|
|
337
|
+
return attr
|
|
338
|
+
if inspect.iscoroutinefunction(attr):
|
|
339
|
+
@functools.wraps(attr)
|
|
340
|
+
async def acall(*args: Any, **kwargs: Any) -> Any:
|
|
341
|
+
self._record(self._used_namespace(attr, args, kwargs))
|
|
342
|
+
return await attr(*args, **kwargs)
|
|
343
|
+
return acall
|
|
344
|
+
|
|
345
|
+
@functools.wraps(attr)
|
|
346
|
+
def call(*args: Any, **kwargs: Any) -> Any:
|
|
347
|
+
self._record(self._used_namespace(attr, args, kwargs))
|
|
348
|
+
return attr(*args, **kwargs)
|
|
349
|
+
return call
|
|
350
|
+
|
|
351
|
+
|
|
352
|
+
def vector_store(client: Any, namespace: Optional[str] = None) -> _VectorStore:
|
|
353
|
+
"""
|
|
354
|
+
Wrap a vector store client; each call is a MEM-04 record naming its namespace.
|
|
355
|
+
|
|
356
|
+
The namespace is the call's `namespace=` argument, else `namespace` here (a client bound to one
|
|
357
|
+
namespace); MEM-04 passes when it is `spec.memory.vector.namespace`.
|
|
358
|
+
"""
|
|
359
|
+
return _VectorStore(_default_points("vector_store"), client, namespace)
|
|
@@ -0,0 +1,319 @@
|
|
|
1
|
+
"""
|
|
2
|
+
AgentSpecReporter — Python agent-side SDK module.
|
|
3
|
+
|
|
4
|
+
Runs live health checks and optionally self-reports to the AgentSpec control
|
|
5
|
+
plane via startPushMode(). Works in both sync and async environments:
|
|
6
|
+
|
|
7
|
+
- Sync (no running event loop): uses threading.Timer (daemon) so the process
|
|
8
|
+
can still exit cleanly.
|
|
9
|
+
- Async (running event loop detected): uses asyncio.create_task().
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import asyncio
|
|
15
|
+
import json
|
|
16
|
+
import math
|
|
17
|
+
import os
|
|
18
|
+
import threading
|
|
19
|
+
from datetime import datetime, timezone
|
|
20
|
+
from typing import Any, Callable, Dict, Optional
|
|
21
|
+
|
|
22
|
+
import httpx
|
|
23
|
+
|
|
24
|
+
from .agentspec_contract import AgentSpecContract
|
|
25
|
+
from .evidence_points import EvidencePoints, Shipped, set_default
|
|
26
|
+
from .manifest import load_manifest
|
|
27
|
+
from .types import HealthCheck, HealthReport
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
CONTRACT = AgentSpecContract()
|
|
31
|
+
MAX_HEARTBEAT_BYTES = CONTRACT.heartbeatMaxBytes
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _size(payload: Dict[str, Any]) -> int:
|
|
35
|
+
return len(json.dumps(payload, separators=(",", ":")).encode("utf-8"))
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class AgentSpecReporter:
|
|
39
|
+
"""Runs health checks and optionally pushes heartbeats to the control plane."""
|
|
40
|
+
|
|
41
|
+
def __init__(self, manifest: Dict[str, Any]) -> None:
|
|
42
|
+
self._manifest = manifest
|
|
43
|
+
self.evidence = EvidencePoints(manifest)
|
|
44
|
+
set_default(self.evidence)
|
|
45
|
+
self._active = False
|
|
46
|
+
self._timer: Optional[threading.Timer] = None
|
|
47
|
+
self._lock = threading.Lock() # guards _generation and _timer; never held across a push
|
|
48
|
+
self._shipping: Optional[Shipped] = None # the window the heartbeat in flight carries
|
|
49
|
+
self._heartbeat_in_flight = False # one POST at a time: the window it carries is already on the wire
|
|
50
|
+
self._generation = 0 # bumped on every start/stop; a timer chain dies when its generation is stale
|
|
51
|
+
self._task: Optional[asyncio.Task[None]] = None
|
|
52
|
+
self._control_plane_url = ""
|
|
53
|
+
self._api_key = ""
|
|
54
|
+
self._interval_seconds = 30
|
|
55
|
+
self._on_error: Optional[Callable[[Exception], None]] = None
|
|
56
|
+
|
|
57
|
+
@classmethod
|
|
58
|
+
def from_yaml(cls, path: str) -> "AgentSpecReporter":
|
|
59
|
+
"""Create a reporter from an agent.yaml file path."""
|
|
60
|
+
return cls(manifest=load_manifest(path))
|
|
61
|
+
|
|
62
|
+
# ── Health check ──────────────────────────────────────────────────────────
|
|
63
|
+
|
|
64
|
+
def get_report(self) -> HealthReport:
|
|
65
|
+
"""
|
|
66
|
+
Run live health checks and return a HealthReport.
|
|
67
|
+
Phase 4: minimal implementation — env var presence only.
|
|
68
|
+
"""
|
|
69
|
+
checks: list[HealthCheck] = []
|
|
70
|
+
passed = 0
|
|
71
|
+
failed = 0
|
|
72
|
+
|
|
73
|
+
# Check model API key env var
|
|
74
|
+
model = self._manifest.get("spec", {}).get("model", {})
|
|
75
|
+
api_key_ref: str = model.get("apiKey", "")
|
|
76
|
+
if api_key_ref.startswith("$env:"):
|
|
77
|
+
env_var = api_key_ref[5:]
|
|
78
|
+
if os.environ.get(env_var):
|
|
79
|
+
checks.append(
|
|
80
|
+
HealthCheck(
|
|
81
|
+
id=f"env:{env_var}",
|
|
82
|
+
category="env",
|
|
83
|
+
status="pass",
|
|
84
|
+
severity="error",
|
|
85
|
+
)
|
|
86
|
+
)
|
|
87
|
+
passed += 1
|
|
88
|
+
else:
|
|
89
|
+
checks.append(
|
|
90
|
+
HealthCheck(
|
|
91
|
+
id=f"env:{env_var}",
|
|
92
|
+
category="env",
|
|
93
|
+
status="fail",
|
|
94
|
+
severity="error",
|
|
95
|
+
message=f"Environment variable {env_var} is not set",
|
|
96
|
+
)
|
|
97
|
+
)
|
|
98
|
+
failed += 1
|
|
99
|
+
|
|
100
|
+
status: str
|
|
101
|
+
if failed > 0:
|
|
102
|
+
status = "unhealthy"
|
|
103
|
+
else:
|
|
104
|
+
status = "healthy"
|
|
105
|
+
|
|
106
|
+
return HealthReport(
|
|
107
|
+
agent_name=self._manifest["metadata"]["name"],
|
|
108
|
+
timestamp=datetime.now(timezone.utc).isoformat(),
|
|
109
|
+
status=status, # type: ignore[arg-type]
|
|
110
|
+
summary={"passed": passed, "failed": failed, "warnings": 0, "skipped": 0},
|
|
111
|
+
checks=checks,
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
def wsgi_app(self) -> Callable[..., Any]:
|
|
115
|
+
"""WSGI app serving GET on the contract agent health path; mount it in any WSGI framework (a prefix mount lands in SCRIPT_NAME) or run it with wsgiref."""
|
|
116
|
+
|
|
117
|
+
def app(environ: Dict[str, Any], start_response: Callable[..., Any]) -> list[bytes]:
|
|
118
|
+
if environ.get("SCRIPT_NAME", "") + environ.get("PATH_INFO", "") != CONTRACT.agentPaths.health:
|
|
119
|
+
start_response("404 Not Found", [("Content-Type", "text/plain")])
|
|
120
|
+
return [b"not found"]
|
|
121
|
+
if environ.get("REQUEST_METHOD") != "GET":
|
|
122
|
+
start_response("405 Method Not Allowed", [("Allow", "GET"), ("Content-Type", "text/plain")])
|
|
123
|
+
return [b"method not allowed"]
|
|
124
|
+
body = self.get_report().model_dump_json().encode("utf-8")
|
|
125
|
+
start_response("200 OK", [("Content-Type", "application/json"), ("Content-Length", str(len(body)))])
|
|
126
|
+
return [body]
|
|
127
|
+
|
|
128
|
+
return app
|
|
129
|
+
|
|
130
|
+
# ── Push mode ─────────────────────────────────────────────────────────────
|
|
131
|
+
|
|
132
|
+
def start_push_mode(
|
|
133
|
+
self,
|
|
134
|
+
control_plane_url: Optional[str] = None,
|
|
135
|
+
api_key: str = "",
|
|
136
|
+
interval_seconds: int = 30,
|
|
137
|
+
on_error: Optional[Callable[[Exception], None]] = None,
|
|
138
|
+
) -> None:
|
|
139
|
+
"""
|
|
140
|
+
Start sending heartbeats to the control plane.
|
|
141
|
+
|
|
142
|
+
Auto-detects runtime:
|
|
143
|
+
- Running event loop → asyncio.create_task()
|
|
144
|
+
- No event loop → threading.Timer(daemon=True)
|
|
145
|
+
|
|
146
|
+
control_plane_url falls back to AGENTSPEC_CONTROL_PLANE_URL (injected into the
|
|
147
|
+
agent container by the operator webhook); raises ValueError when neither is set.
|
|
148
|
+
|
|
149
|
+
Idempotent: calling twice has no effect.
|
|
150
|
+
"""
|
|
151
|
+
if self._active:
|
|
152
|
+
return
|
|
153
|
+
|
|
154
|
+
control_plane_url = control_plane_url or os.environ.get(CONTRACT.env.controlPlaneUrl)
|
|
155
|
+
if not control_plane_url:
|
|
156
|
+
raise ValueError(
|
|
157
|
+
"start_push_mode: no control plane URL — pass control_plane_url "
|
|
158
|
+
f"or set {CONTRACT.env.controlPlaneUrl}"
|
|
159
|
+
)
|
|
160
|
+
if not api_key:
|
|
161
|
+
raise ValueError("start_push_mode: api_key is required (the per-agent token from POST /api/v1/register)")
|
|
162
|
+
|
|
163
|
+
with self._lock:
|
|
164
|
+
self._active = True
|
|
165
|
+
self._generation += 1
|
|
166
|
+
generation = self._generation
|
|
167
|
+
self._control_plane_url = control_plane_url
|
|
168
|
+
self._api_key = api_key
|
|
169
|
+
self._interval_seconds = interval_seconds
|
|
170
|
+
self._on_error = on_error
|
|
171
|
+
|
|
172
|
+
try:
|
|
173
|
+
asyncio.get_running_loop()
|
|
174
|
+
# Async mode: schedule with asyncio
|
|
175
|
+
self._task = asyncio.create_task(self._async_push_loop())
|
|
176
|
+
except RuntimeError:
|
|
177
|
+
# Sync mode: fire immediately, then use threading.Timer to repeat
|
|
178
|
+
self._fire_and_reschedule(generation)
|
|
179
|
+
|
|
180
|
+
def stop_push_mode(self) -> None:
|
|
181
|
+
"""Stop sending heartbeats to the control plane."""
|
|
182
|
+
with self._lock:
|
|
183
|
+
self._active = False
|
|
184
|
+
self._generation += 1
|
|
185
|
+
if self._timer is not None:
|
|
186
|
+
self._timer.cancel()
|
|
187
|
+
self._timer = None
|
|
188
|
+
if self._task is not None:
|
|
189
|
+
self._task.cancel()
|
|
190
|
+
self._task = None
|
|
191
|
+
|
|
192
|
+
def is_push_mode_active(self) -> bool:
|
|
193
|
+
"""Returns True if heartbeats are currently being sent."""
|
|
194
|
+
return self._active
|
|
195
|
+
|
|
196
|
+
# ── Internals ─────────────────────────────────────────────────────────────
|
|
197
|
+
|
|
198
|
+
def _fire_and_reschedule(self, generation: int) -> None:
|
|
199
|
+
"""Run one push synchronously, then schedule the next via threading.Timer.
|
|
200
|
+
|
|
201
|
+
A callback in flight across stop/start sees a newer generation and ends its chain.
|
|
202
|
+
"""
|
|
203
|
+
if generation != self._generation:
|
|
204
|
+
return
|
|
205
|
+
self._push_sync()
|
|
206
|
+
with self._lock: # a stop/start landing between the check and the Timer would orphan a stale timer
|
|
207
|
+
if generation != self._generation:
|
|
208
|
+
return
|
|
209
|
+
self._timer = threading.Timer(self._interval_seconds, self._fire_and_reschedule, args=(generation,))
|
|
210
|
+
self._timer.daemon = True
|
|
211
|
+
self._timer.start()
|
|
212
|
+
|
|
213
|
+
def _heartbeat_payload(self) -> Dict[str, Any]:
|
|
214
|
+
"""Heartbeat body: health telemetry plus EvidenceRecord[] and evidence point aggregates; never `gap` (ADR-0008)."""
|
|
215
|
+
points, self._shipping = self.evidence.begin_ship(ttl_seconds=math.ceil(self._interval_seconds * 2))
|
|
216
|
+
payload: Dict[str, Any] = {
|
|
217
|
+
"contract": CONTRACT.version,
|
|
218
|
+
"health": self.get_report().model_dump(),
|
|
219
|
+
"records": [],
|
|
220
|
+
"evidencePoints": points,
|
|
221
|
+
}
|
|
222
|
+
if _size(payload) > MAX_HEARTBEAT_BYTES:
|
|
223
|
+
# Over the limit: keep every point's state and counts, drop the sample records.
|
|
224
|
+
for aggregate in payload["evidencePoints"]:
|
|
225
|
+
aggregate["records"] = []
|
|
226
|
+
return payload
|
|
227
|
+
|
|
228
|
+
def _too_large(self, payload: Dict[str, Any]) -> bool:
|
|
229
|
+
"""A heartbeat the control plane would reject (HTTP 413) is not sent; the next one still goes out."""
|
|
230
|
+
size = _size(payload)
|
|
231
|
+
if size <= MAX_HEARTBEAT_BYTES:
|
|
232
|
+
return False
|
|
233
|
+
if self._on_error:
|
|
234
|
+
self._on_error(Exception(f"Heartbeat not sent: {size} bytes exceeds the {MAX_HEARTBEAT_BYTES} byte limit (health data too large)"))
|
|
235
|
+
return True
|
|
236
|
+
|
|
237
|
+
def _heartbeat_answered(self, status_code: int) -> None:
|
|
238
|
+
"""A shipped evidence window leaves the SDK only on success; a failed one rides the next heartbeat."""
|
|
239
|
+
if 200 <= status_code < 300: # httpx does not follow redirects: a 3xx never reached the control plane
|
|
240
|
+
self.evidence.subtract(self._shipping)
|
|
241
|
+
elif self._on_error:
|
|
242
|
+
self._on_error(Exception(f"Heartbeat failed: HTTP {status_code}"))
|
|
243
|
+
|
|
244
|
+
def _begin_heartbeat(self) -> bool:
|
|
245
|
+
"""Claim the single heartbeat slot; False when a heartbeat is already in flight."""
|
|
246
|
+
with self._lock:
|
|
247
|
+
if self._heartbeat_in_flight:
|
|
248
|
+
return False
|
|
249
|
+
self._heartbeat_in_flight = True
|
|
250
|
+
return True
|
|
251
|
+
|
|
252
|
+
def _end_heartbeat(self) -> None:
|
|
253
|
+
with self._lock:
|
|
254
|
+
self._heartbeat_in_flight = False
|
|
255
|
+
|
|
256
|
+
def _push_sync(self) -> None:
|
|
257
|
+
"""Send one heartbeat synchronously via httpx."""
|
|
258
|
+
if not self._begin_heartbeat():
|
|
259
|
+
return
|
|
260
|
+
try:
|
|
261
|
+
self._push_sync_claimed()
|
|
262
|
+
finally:
|
|
263
|
+
self._end_heartbeat()
|
|
264
|
+
|
|
265
|
+
def _push_sync_claimed(self) -> None:
|
|
266
|
+
payload = self._heartbeat_payload()
|
|
267
|
+
if self._too_large(payload):
|
|
268
|
+
return
|
|
269
|
+
try:
|
|
270
|
+
resp = httpx.post(
|
|
271
|
+
f"{self._control_plane_url}{CONTRACT.controlPlanePaths.heartbeat}",
|
|
272
|
+
json=payload,
|
|
273
|
+
headers={
|
|
274
|
+
"Authorization": f"Bearer {self._api_key}",
|
|
275
|
+
"Content-Type": "application/json",
|
|
276
|
+
},
|
|
277
|
+
timeout=10.0,
|
|
278
|
+
)
|
|
279
|
+
self._heartbeat_answered(resp.status_code)
|
|
280
|
+
except Exception as exc:
|
|
281
|
+
if self._on_error:
|
|
282
|
+
msg = str(exc).replace(self._api_key, "[REDACTED]")
|
|
283
|
+
self._on_error(Exception(msg))
|
|
284
|
+
|
|
285
|
+
async def _async_push_loop(self) -> None:
|
|
286
|
+
"""Async loop: push, sleep, repeat until stopped."""
|
|
287
|
+
while self._active:
|
|
288
|
+
await self._push_async()
|
|
289
|
+
await asyncio.sleep(self._interval_seconds)
|
|
290
|
+
|
|
291
|
+
async def _push_async(self) -> None:
|
|
292
|
+
"""Send one heartbeat asynchronously via httpx."""
|
|
293
|
+
if not self._begin_heartbeat():
|
|
294
|
+
return
|
|
295
|
+
try:
|
|
296
|
+
await self._push_async_claimed()
|
|
297
|
+
finally:
|
|
298
|
+
self._end_heartbeat()
|
|
299
|
+
|
|
300
|
+
async def _push_async_claimed(self) -> None:
|
|
301
|
+
payload = self._heartbeat_payload()
|
|
302
|
+
if self._too_large(payload):
|
|
303
|
+
return
|
|
304
|
+
try:
|
|
305
|
+
async with httpx.AsyncClient() as client:
|
|
306
|
+
resp = await client.post(
|
|
307
|
+
f"{self._control_plane_url}{CONTRACT.controlPlanePaths.heartbeat}",
|
|
308
|
+
json=payload,
|
|
309
|
+
headers={
|
|
310
|
+
"Authorization": f"Bearer {self._api_key}",
|
|
311
|
+
"Content-Type": "application/json",
|
|
312
|
+
},
|
|
313
|
+
timeout=10.0,
|
|
314
|
+
)
|
|
315
|
+
self._heartbeat_answered(resp.status_code)
|
|
316
|
+
except Exception as exc:
|
|
317
|
+
if self._on_error:
|
|
318
|
+
msg = str(exc).replace(self._api_key, "[REDACTED]")
|
|
319
|
+
self._on_error(Exception(msg))
|