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/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
+ )
@@ -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