agentdevlabs 0.1.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.
- agentdevlabs/__init__.py +7 -0
- agentdevlabs/api_types.py +466 -0
- agentdevlabs/background.py +149 -0
- agentdevlabs/cache.py +113 -0
- agentdevlabs/cache_key.py +69 -0
- agentdevlabs/config.py +95 -0
- agentdevlabs/decrypt.py +18 -0
- agentdevlabs/events.py +93 -0
- agentdevlabs/hook.py +1009 -0
- agentdevlabs/log.py +22 -0
- agentdevlabs/playback.py +173 -0
- agentdevlabs/providers.py +97 -0
- agentdevlabs/recorder.py +226 -0
- agentdevlabs/redact.py +71 -0
- agentdevlabs/replay.py +184 -0
- agentdevlabs/rules.py +55 -0
- agentdevlabs/server.py +446 -0
- agentdevlabs/trace.py +227 -0
- agentdevlabs-0.1.0.dist-info/METADATA +100 -0
- agentdevlabs-0.1.0.dist-info/RECORD +22 -0
- agentdevlabs-0.1.0.dist-info/WHEEL +4 -0
- agentdevlabs-0.1.0.dist-info/licenses/LICENSE +202 -0
agentdevlabs/cache.py
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import tempfile
|
|
3
|
+
import threading
|
|
4
|
+
from collections.abc import Mapping
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
|
|
7
|
+
CAP_BYTES = 1_000_000_000
|
|
8
|
+
MAX_HELD = 1_000
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def default_cache_dir(env: Mapping[str, str], platform: str, home: str) -> str:
|
|
12
|
+
"""The OS cache dir, unless the app points the SDK elsewhere (L1)."""
|
|
13
|
+
if env.get("AGENT_DEV_LABS_CACHE_DIR"):
|
|
14
|
+
return env["AGENT_DEV_LABS_CACHE_DIR"]
|
|
15
|
+
if platform == "darwin":
|
|
16
|
+
return str(Path(home, "Library", "Caches"))
|
|
17
|
+
if platform == "win32":
|
|
18
|
+
return env.get("LOCALAPPDATA") or str(Path(home, "AppData", "Local"))
|
|
19
|
+
return env.get("XDG_CACHE_HOME") or str(Path(home, ".cache"))
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class ObjectCache:
|
|
23
|
+
"""Capture objects kept as downloaded: ciphertext only, least recently read removed first
|
|
24
|
+
once past the cap (L3)."""
|
|
25
|
+
|
|
26
|
+
def __init__(self, directory: str, cap_bytes: int = CAP_BYTES):
|
|
27
|
+
self._root = Path(directory, "agentdevlabs", "objects")
|
|
28
|
+
self._cap_bytes = cap_bytes
|
|
29
|
+
self._total: int | None = None
|
|
30
|
+
self._guard = threading.Lock() # downloads on several threads write at once
|
|
31
|
+
|
|
32
|
+
def _path_of(self, first_cache_key: str, capture_id: str) -> Path:
|
|
33
|
+
return self._root / first_cache_key / capture_id
|
|
34
|
+
|
|
35
|
+
def held(self, first_cache_key: str) -> list[str]:
|
|
36
|
+
try:
|
|
37
|
+
names = os.listdir(self._root / first_cache_key)
|
|
38
|
+
except FileNotFoundError:
|
|
39
|
+
return []
|
|
40
|
+
return [name for name in names if not name.startswith(".")][:MAX_HELD]
|
|
41
|
+
|
|
42
|
+
def read(self, first_cache_key: str, capture_id: str) -> bytes | None:
|
|
43
|
+
path = self._path_of(first_cache_key, capture_id)
|
|
44
|
+
try:
|
|
45
|
+
data = path.read_bytes()
|
|
46
|
+
os.utime(path)
|
|
47
|
+
except FileNotFoundError:
|
|
48
|
+
return None
|
|
49
|
+
return data
|
|
50
|
+
|
|
51
|
+
def write(self, first_cache_key: str, capture_id: str, data: bytes) -> None:
|
|
52
|
+
with self._guard:
|
|
53
|
+
self._write(first_cache_key, capture_id, data)
|
|
54
|
+
|
|
55
|
+
def _write(self, first_cache_key: str, capture_id: str, data: bytes) -> None:
|
|
56
|
+
path = self._path_of(first_cache_key, capture_id)
|
|
57
|
+
folder = path.parent
|
|
58
|
+
folder.mkdir(mode=0o700, parents=True, exist_ok=True)
|
|
59
|
+
known = self._total_bytes()
|
|
60
|
+
handle, temporary = tempfile.mkstemp(dir=folder, prefix=f".{capture_id}.", suffix=".tmp")
|
|
61
|
+
with os.fdopen(handle, "wb") as out:
|
|
62
|
+
out.write(data)
|
|
63
|
+
os.replace(temporary, path)
|
|
64
|
+
self._total = known + len(data)
|
|
65
|
+
if self._total > self._cap_bytes:
|
|
66
|
+
self._evict(keep=path)
|
|
67
|
+
|
|
68
|
+
def remove(self, first_cache_key: str, capture_id: str) -> None:
|
|
69
|
+
with self._guard:
|
|
70
|
+
self._remove(first_cache_key, capture_id)
|
|
71
|
+
|
|
72
|
+
def _remove(self, first_cache_key: str, capture_id: str) -> None:
|
|
73
|
+
path = self._path_of(first_cache_key, capture_id)
|
|
74
|
+
size = _size_of(path)
|
|
75
|
+
path.unlink(missing_ok=True)
|
|
76
|
+
if self._total is not None:
|
|
77
|
+
self._total -= size
|
|
78
|
+
|
|
79
|
+
def _total_bytes(self) -> int:
|
|
80
|
+
if self._total is None:
|
|
81
|
+
self._total = sum(size for _, size, _ in self._entries())
|
|
82
|
+
return self._total
|
|
83
|
+
|
|
84
|
+
def _entries(self) -> list[tuple[Path, int, float]]:
|
|
85
|
+
entries = []
|
|
86
|
+
try:
|
|
87
|
+
first_keys = os.listdir(self._root)
|
|
88
|
+
except FileNotFoundError:
|
|
89
|
+
return []
|
|
90
|
+
for first in first_keys:
|
|
91
|
+
for name in os.listdir(self._root / first):
|
|
92
|
+
if name.startswith("."):
|
|
93
|
+
continue
|
|
94
|
+
path = self._root / first / name
|
|
95
|
+
info = path.stat()
|
|
96
|
+
entries.append((path, info.st_size, info.st_mtime))
|
|
97
|
+
return entries
|
|
98
|
+
|
|
99
|
+
def _evict(self, keep: Path) -> None:
|
|
100
|
+
for path, size, _ in sorted(self._entries(), key=lambda entry: entry[2]):
|
|
101
|
+
if (self._total or 0) <= self._cap_bytes:
|
|
102
|
+
return
|
|
103
|
+
if path == keep:
|
|
104
|
+
continue
|
|
105
|
+
path.unlink(missing_ok=True)
|
|
106
|
+
self._total = (self._total or 0) - size
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _size_of(path: Path) -> int:
|
|
110
|
+
try:
|
|
111
|
+
return path.stat().st_size
|
|
112
|
+
except FileNotFoundError:
|
|
113
|
+
return 0
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
"""The cache-key spec in spec/cache-key/, ported. spec/cache-key/vectors.json proves it."""
|
|
2
|
+
|
|
3
|
+
import copy
|
|
4
|
+
import hashlib
|
|
5
|
+
import re
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
import rfc8785
|
|
9
|
+
|
|
10
|
+
SPEC_VERSION = 1
|
|
11
|
+
EXCLUDED_FIELDS = {
|
|
12
|
+
"openai": {"user", "metadata", "safety_identifier", "prompt_cache_key"},
|
|
13
|
+
"anthropic": {"metadata"},
|
|
14
|
+
}
|
|
15
|
+
EXCLUDED_PATHS = {
|
|
16
|
+
"openai": ["tools.*.authorization", "tools.*.headers"],
|
|
17
|
+
"anthropic": ["mcp_servers.*.authorization_token"],
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def _drop_nulls(value: Any) -> Any:
|
|
22
|
+
if isinstance(value, list):
|
|
23
|
+
return [_drop_nulls(item) for item in value]
|
|
24
|
+
if isinstance(value, dict):
|
|
25
|
+
return {key: _drop_nulls(member) for key, member in value.items() if member is not None}
|
|
26
|
+
return value
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _rename_max_tokens(body: dict) -> dict:
|
|
30
|
+
if "max_completion_tokens" not in body:
|
|
31
|
+
return body
|
|
32
|
+
renamed = {key: member for key, member in body.items() if key != "max_completion_tokens"}
|
|
33
|
+
return {**renamed, "max_tokens": body["max_completion_tokens"]}
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _ignore_path(value: Any, path: list[str]) -> Any:
|
|
37
|
+
head, rest = path[0], path[1:]
|
|
38
|
+
if isinstance(value, list):
|
|
39
|
+
return [_ignore_path(item, rest) for item in value] if head == "*" else value
|
|
40
|
+
if not isinstance(value, dict) or head not in value:
|
|
41
|
+
return value
|
|
42
|
+
if not rest:
|
|
43
|
+
return {key: member for key, member in value.items() if key != head}
|
|
44
|
+
return {**value, head: _ignore_path(value[head], rest)}
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _mask_strings(value: Any, pattern: re.Pattern) -> Any:
|
|
48
|
+
if isinstance(value, str):
|
|
49
|
+
return pattern.sub("[masked]", value)
|
|
50
|
+
if isinstance(value, list):
|
|
51
|
+
return [_mask_strings(item, pattern) for item in value]
|
|
52
|
+
if isinstance(value, dict):
|
|
53
|
+
return {key: _mask_strings(member, pattern) for key, member in value.items()}
|
|
54
|
+
return value
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _canonical(provider: str, body: dict, rules: dict) -> bytes:
|
|
58
|
+
hashed = _rename_max_tokens(_drop_nulls(body))
|
|
59
|
+
hashed = {key: member for key, member in hashed.items() if key not in EXCLUDED_FIELDS[provider]}
|
|
60
|
+
for path in [*EXCLUDED_PATHS[provider], *rules.get("ignore", [])]:
|
|
61
|
+
hashed = _ignore_path(hashed, path.split("."))
|
|
62
|
+
for pattern in rules.get("mask", []):
|
|
63
|
+
hashed = _mask_strings(hashed, re.compile(pattern))
|
|
64
|
+
return rfc8785.dumps({"v": SPEC_VERSION, "provider": provider, "body": hashed})
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def cache_key(provider: str, body: dict, rules: dict | None = None) -> str:
|
|
68
|
+
"""The sha256 of the canonical request. The input is never changed."""
|
|
69
|
+
return hashlib.sha256(_canonical(provider, copy.deepcopy(body), rules or {})).hexdigest()
|
agentdevlabs/config.py
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import math
|
|
2
|
+
import os
|
|
3
|
+
import re
|
|
4
|
+
import sys
|
|
5
|
+
from collections.abc import Mapping
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
from .cache import default_cache_dir
|
|
10
|
+
|
|
11
|
+
MODES = ("auto", "capture", "replay", "off")
|
|
12
|
+
DISABLED_TRUE = ("1", "true", "yes", "on")
|
|
13
|
+
DISABLED_FALSE = ("0", "false", "no", "off")
|
|
14
|
+
HOSTED_API_URL = "https://api.agentdevlabs.dev"
|
|
15
|
+
# The same rule the API holds a group name to; a name it would refuse must fail here, loudly.
|
|
16
|
+
GROUP_NAME = re.compile(r"[A-Za-z0-9._/-]{1,100}")
|
|
17
|
+
NAMED_SPEEDS = {"realtime": 1.0, "fast": 10.0, "instant": math.inf}
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass(frozen=True)
|
|
21
|
+
class Config:
|
|
22
|
+
token: str | None
|
|
23
|
+
mode: str | None
|
|
24
|
+
# The mode as typed when it is not one of the four; `mode` is then "auto".
|
|
25
|
+
unknown_mode: str | None
|
|
26
|
+
disabled: bool
|
|
27
|
+
# The DISABLED value as typed when it is neither a true nor a false value; `disabled` is
|
|
28
|
+
# then True.
|
|
29
|
+
unknown_disabled: str | None
|
|
30
|
+
api_url: str
|
|
31
|
+
# Divisor for recorded waits: 1 is real time, infinity does not wait; None leaves it to the
|
|
32
|
+
# response kind.
|
|
33
|
+
replay_speed: float | None
|
|
34
|
+
cache_dir: str
|
|
35
|
+
# Names the trace group a CI run captures into and replays from.
|
|
36
|
+
group: str | None
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _read_speed(value: str | None) -> float | None:
|
|
40
|
+
if value is None:
|
|
41
|
+
return None
|
|
42
|
+
if value in NAMED_SPEEDS:
|
|
43
|
+
return NAMED_SPEEDS[value]
|
|
44
|
+
try:
|
|
45
|
+
number = float(value)
|
|
46
|
+
except ValueError:
|
|
47
|
+
return None
|
|
48
|
+
return number if number > 0 else None
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _read_group(value: str | None) -> str | None:
|
|
52
|
+
if not value:
|
|
53
|
+
return None
|
|
54
|
+
if not GROUP_NAME.fullmatch(value):
|
|
55
|
+
raise ValueError(
|
|
56
|
+
"AGENT_DEV_LABS_GROUP must be letters, digits, . _ / - and at most 100 characters long"
|
|
57
|
+
)
|
|
58
|
+
return value
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _read_mode(value: str | None) -> tuple[str | None, str | None]:
|
|
62
|
+
"""An unset or empty mode is the server's to choose; an unknown one runs as auto (R1). Returns
|
|
63
|
+
the mode and, for an unknown one, the value as typed."""
|
|
64
|
+
typed = (value or "").strip()
|
|
65
|
+
if not typed:
|
|
66
|
+
return None, None
|
|
67
|
+
if typed.lower() in MODES:
|
|
68
|
+
return typed.lower(), None
|
|
69
|
+
return "auto", typed
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _read_disabled(value: str | None) -> tuple[bool, str | None]:
|
|
73
|
+
"""The kill switch never fails and never stays on by mistake: only a false value leaves the
|
|
74
|
+
SDK on (A-floor). Returns whether it is off and, for an unrecognised value, the value typed."""
|
|
75
|
+
typed = (value or "").strip()
|
|
76
|
+
if not typed or typed.lower() in DISABLED_FALSE:
|
|
77
|
+
return False, None
|
|
78
|
+
return True, None if typed.lower() in DISABLED_TRUE else typed
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def read_config(env: Mapping[str, str] | None = None) -> Config:
|
|
82
|
+
env = os.environ if env is None else env
|
|
83
|
+
mode, unknown_mode = _read_mode(env.get("AGENT_DEV_LABS_MODE"))
|
|
84
|
+
disabled, unknown_disabled = _read_disabled(env.get("AGENT_DEV_LABS_DISABLED"))
|
|
85
|
+
return Config(
|
|
86
|
+
token=env.get("AGENT_DEV_LABS_TOKEN") or None,
|
|
87
|
+
mode=mode,
|
|
88
|
+
unknown_mode=unknown_mode,
|
|
89
|
+
disabled=disabled,
|
|
90
|
+
unknown_disabled=unknown_disabled,
|
|
91
|
+
api_url=(env.get("AGENT_DEV_LABS_API_URL") or HOSTED_API_URL).rstrip("/"),
|
|
92
|
+
replay_speed=_read_speed(env.get("AGENT_DEV_LABS_REPLAY_SPEED")),
|
|
93
|
+
cache_dir=default_cache_dir(env, sys.platform, str(Path.home())),
|
|
94
|
+
group=None if disabled else _read_group(env.get("AGENT_DEV_LABS_GROUP")),
|
|
95
|
+
)
|
agentdevlabs/decrypt.py
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import base64
|
|
2
|
+
|
|
3
|
+
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
|
|
4
|
+
|
|
5
|
+
NONCE_BYTES = 12
|
|
6
|
+
TAG_BYTES = 16
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def decrypt_object(sealed: bytes, key: str, capture_id: str) -> str:
|
|
10
|
+
"""An object is a random nonce, then the ciphertext and its tag, sealed with the capture id
|
|
11
|
+
as associated data (L2)."""
|
|
12
|
+
if len(sealed) < NONCE_BYTES + TAG_BYTES:
|
|
13
|
+
raise ValueError("the capture object is too short")
|
|
14
|
+
raw_key = base64.urlsafe_b64decode(key + "=" * (-len(key) % 4))
|
|
15
|
+
plain = AESGCM(raw_key).decrypt(
|
|
16
|
+
sealed[:NONCE_BYTES], sealed[NONCE_BYTES:], capture_id.encode("utf-8")
|
|
17
|
+
)
|
|
18
|
+
return plain.decode("utf-8")
|
agentdevlabs/events.py
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import threading
|
|
2
|
+
from collections.abc import Callable
|
|
3
|
+
from typing import Any
|
|
4
|
+
|
|
5
|
+
from . import background
|
|
6
|
+
from .log import warn
|
|
7
|
+
|
|
8
|
+
BATCH_SIZE = 500
|
|
9
|
+
MAX_WAITING = 10_000
|
|
10
|
+
QUIET_S = 1.0
|
|
11
|
+
|
|
12
|
+
_with_events: set["EventQueue"] = set()
|
|
13
|
+
_registry_lock = threading.Lock()
|
|
14
|
+
_exit_hook_added = False
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def flush_all() -> None:
|
|
18
|
+
_queue_flushes()
|
|
19
|
+
background.wait_idle(None)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _queue_flushes() -> None:
|
|
23
|
+
with _registry_lock:
|
|
24
|
+
queues = list(_with_events)
|
|
25
|
+
for queue in queues:
|
|
26
|
+
queue.flush()
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _add_exit_hook() -> None:
|
|
30
|
+
global _exit_hook_added
|
|
31
|
+
with _registry_lock:
|
|
32
|
+
if _exit_hook_added:
|
|
33
|
+
return
|
|
34
|
+
_exit_hook_added = True
|
|
35
|
+
background.before_exit(_queue_flushes)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class EventQueue:
|
|
39
|
+
"""Call events wait here and go out in batches of 500: at trace end, at 500, and after a
|
|
40
|
+
quiet second (OP3)."""
|
|
41
|
+
|
|
42
|
+
def __init__(self, send: Callable[[list[Any]], None], limit: int = MAX_WAITING):
|
|
43
|
+
self._send = send
|
|
44
|
+
self._limit = limit
|
|
45
|
+
self._lock = threading.Lock()
|
|
46
|
+
self._pending: list[Any] = []
|
|
47
|
+
self._in_flight = 0
|
|
48
|
+
self._draining = False
|
|
49
|
+
|
|
50
|
+
def waiting(self) -> int:
|
|
51
|
+
with self._lock:
|
|
52
|
+
return len(self._pending) + self._in_flight
|
|
53
|
+
|
|
54
|
+
def add(self, event: Any) -> None:
|
|
55
|
+
with self._lock:
|
|
56
|
+
if len(self._pending) + self._in_flight >= self._limit:
|
|
57
|
+
return
|
|
58
|
+
self._pending.append(event)
|
|
59
|
+
full = len(self._pending) >= BATCH_SIZE
|
|
60
|
+
if not full:
|
|
61
|
+
background.after(QUIET_S, self, self.flush)
|
|
62
|
+
with _registry_lock:
|
|
63
|
+
_with_events.add(self)
|
|
64
|
+
_add_exit_hook()
|
|
65
|
+
if full:
|
|
66
|
+
self.flush()
|
|
67
|
+
|
|
68
|
+
def flush(self) -> None:
|
|
69
|
+
with self._lock:
|
|
70
|
+
background.cancel(self)
|
|
71
|
+
if self._draining or not self._pending:
|
|
72
|
+
return
|
|
73
|
+
self._draining = True
|
|
74
|
+
background.run(self._drain)
|
|
75
|
+
|
|
76
|
+
def _drain(self) -> None:
|
|
77
|
+
while True:
|
|
78
|
+
with self._lock:
|
|
79
|
+
if not self._pending:
|
|
80
|
+
self._draining = False
|
|
81
|
+
with _registry_lock:
|
|
82
|
+
_with_events.discard(self)
|
|
83
|
+
return
|
|
84
|
+
batch = self._pending[:BATCH_SIZE]
|
|
85
|
+
del self._pending[:BATCH_SIZE]
|
|
86
|
+
self._in_flight = len(batch)
|
|
87
|
+
try:
|
|
88
|
+
self._send(batch)
|
|
89
|
+
except Exception:
|
|
90
|
+
warn("call events were dropped: the SDK hit an internal error")
|
|
91
|
+
finally:
|
|
92
|
+
with self._lock:
|
|
93
|
+
self._in_flight = 0
|