bbagents 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.
- bbagents/__init__.py +70 -0
- bbagents/compaction.py +38 -0
- bbagents/context.py +124 -0
- bbagents/core.py +49 -0
- bbagents/decision.py +225 -0
- bbagents/evaluation.py +114 -0
- bbagents/execution.py +216 -0
- bbagents/experiments.py +172 -0
- bbagents/governed_memory.py +85 -0
- bbagents/hooks.py +78 -0
- bbagents/integrations/__init__.py +1 -0
- bbagents/integrations/filesystem_skills.py +101 -0
- bbagents/integrations/langfuse.py +115 -0
- bbagents/integrations/langgraph.py +99 -0
- bbagents/integrations/langsmith.py +117 -0
- bbagents/integrations/ollama.py +85 -0
- bbagents/intervention.py +510 -0
- bbagents/learning.py +55 -0
- bbagents/lifecycle.py +168 -0
- bbagents/memory.py +157 -0
- bbagents/models.py +199 -0
- bbagents/observability.py +216 -0
- bbagents/optimization.py +47 -0
- bbagents/organization.py +40 -0
- bbagents/persistence.py +274 -0
- bbagents/planning.py +278 -0
- bbagents/promotion.py +67 -0
- bbagents/provenance.py +37 -0
- bbagents/py.typed +1 -0
- bbagents/recovery.py +184 -0
- bbagents/reference.py +5 -0
- bbagents/retrieval.py +122 -0
- bbagents/revisions.py +161 -0
- bbagents/runtime.py +218 -0
- bbagents/safety.py +85 -0
- bbagents/skills.py +57 -0
- bbagents/tools.py +61 -0
- bbagents-0.1.0.dist-info/METADATA +80 -0
- bbagents-0.1.0.dist-info/RECORD +42 -0
- bbagents-0.1.0.dist-info/WHEEL +5 -0
- bbagents-0.1.0.dist-info/licenses/LICENSE +22 -0
- bbagents-0.1.0.dist-info/top_level.txt +1 -0
bbagents/execution.py
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
"""Bounded async execution; adapters must cooperate with task cancellation."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
import math
|
|
8
|
+
import time
|
|
9
|
+
from typing import Any, Awaitable, Callable, Mapping, Protocol
|
|
10
|
+
|
|
11
|
+
from .runtime import (
|
|
12
|
+
Action,
|
|
13
|
+
ActionPolicy,
|
|
14
|
+
ActionResult,
|
|
15
|
+
ActionStatus,
|
|
16
|
+
AllowAllPolicy,
|
|
17
|
+
FailureKind,
|
|
18
|
+
_evaluate_policy,
|
|
19
|
+
)
|
|
20
|
+
from .hooks import HookBoundary, HookContext, HookRejected, HookRunner
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True, slots=True)
|
|
24
|
+
class ExecutionContext:
|
|
25
|
+
deadline: float
|
|
26
|
+
|
|
27
|
+
@property
|
|
28
|
+
def remaining_seconds(self) -> float:
|
|
29
|
+
return max(0.0, self.deadline - time.monotonic())
|
|
30
|
+
|
|
31
|
+
def check_deadline(self) -> None:
|
|
32
|
+
if self.remaining_seconds <= 0:
|
|
33
|
+
raise TimeoutError("execution deadline expired")
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class ExecutionAdapter(Protocol):
|
|
37
|
+
async def execute(self, action: Action, context: ExecutionContext) -> Any: ...
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class ExecutionFailure(Exception):
|
|
41
|
+
def __init__(
|
|
42
|
+
self, message: str, kind: FailureKind, *, outcome_unknown: bool = False
|
|
43
|
+
) -> None:
|
|
44
|
+
super().__init__(message)
|
|
45
|
+
self.kind = kind
|
|
46
|
+
self.outcome_unknown = outcome_unknown
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class RetryPolicy(Protocol):
|
|
50
|
+
def should_retry(self, action: Action, result: ActionResult) -> bool: ...
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
@dataclass(frozen=True, slots=True)
|
|
54
|
+
class SafeRetryPolicy:
|
|
55
|
+
max_attempts: int = 1
|
|
56
|
+
|
|
57
|
+
def __post_init__(self) -> None:
|
|
58
|
+
if self.max_attempts < 1:
|
|
59
|
+
raise ValueError("max_attempts must be positive")
|
|
60
|
+
|
|
61
|
+
def should_retry(self, action: Action, result: ActionResult) -> bool:
|
|
62
|
+
return (
|
|
63
|
+
action.retry_safe
|
|
64
|
+
and not result.outcome_unknown
|
|
65
|
+
and result.failure_kind == FailureKind.TRANSIENT
|
|
66
|
+
and result.attempts < self.max_attempts
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
AsyncHandler = Callable[[Action, ExecutionContext], Awaitable[Any]]
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class AsyncFunctionAdapter:
|
|
74
|
+
"""Handlers must not block the event loop or suppress cancellation."""
|
|
75
|
+
|
|
76
|
+
def __init__(self, handlers: Mapping[str, AsyncHandler]) -> None:
|
|
77
|
+
self.handlers = dict(handlers)
|
|
78
|
+
|
|
79
|
+
async def execute(self, action: Action, context: ExecutionContext) -> Any:
|
|
80
|
+
if action.name not in self.handlers:
|
|
81
|
+
raise ExecutionFailure("Unknown action", FailureKind.VALIDATION)
|
|
82
|
+
return await self.handlers[action.name](action, context)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
class SubprocessAdapter:
|
|
86
|
+
"""Run application-allowlisted commands without a shell; kill/reap on cancel.
|
|
87
|
+
|
|
88
|
+
This is process control, not an OS security sandbox. Commands must bound their
|
|
89
|
+
output and manage descendants; external side effects can survive termination.
|
|
90
|
+
"""
|
|
91
|
+
|
|
92
|
+
def __init__(self, commands: Mapping[str, tuple[str, ...]]) -> None:
|
|
93
|
+
self.commands = dict(commands)
|
|
94
|
+
|
|
95
|
+
async def execute(self, action: Action, context: ExecutionContext) -> str:
|
|
96
|
+
if action.name not in self.commands or action.parameters:
|
|
97
|
+
raise ExecutionFailure("Command not allowlisted", FailureKind.VALIDATION)
|
|
98
|
+
context.check_deadline()
|
|
99
|
+
process = await asyncio.create_subprocess_exec(
|
|
100
|
+
*self.commands[action.name],
|
|
101
|
+
stdout=asyncio.subprocess.PIPE,
|
|
102
|
+
stderr=asyncio.subprocess.PIPE,
|
|
103
|
+
)
|
|
104
|
+
try:
|
|
105
|
+
stdout, stderr = await process.communicate()
|
|
106
|
+
except BaseException:
|
|
107
|
+
if process.returncode is None:
|
|
108
|
+
process.kill()
|
|
109
|
+
await process.wait()
|
|
110
|
+
raise
|
|
111
|
+
if process.returncode:
|
|
112
|
+
raise ExecutionFailure(
|
|
113
|
+
stderr.decode(errors="replace"),
|
|
114
|
+
FailureKind.PERMANENT,
|
|
115
|
+
outcome_unknown=True,
|
|
116
|
+
)
|
|
117
|
+
return stdout.decode(errors="replace")
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class AsyncActionRuntime:
|
|
121
|
+
def __init__(
|
|
122
|
+
self,
|
|
123
|
+
adapter: ExecutionAdapter,
|
|
124
|
+
*,
|
|
125
|
+
policy: ActionPolicy | None = None,
|
|
126
|
+
retry_policy: RetryPolicy | None = None,
|
|
127
|
+
hooks: HookRunner | None = None,
|
|
128
|
+
) -> None:
|
|
129
|
+
self.adapter = adapter
|
|
130
|
+
self.policy = policy or AllowAllPolicy()
|
|
131
|
+
self.retry_policy = retry_policy or SafeRetryPolicy()
|
|
132
|
+
self.hooks = hooks or HookRunner()
|
|
133
|
+
|
|
134
|
+
async def execute(self, action: Action) -> ActionResult:
|
|
135
|
+
if not math.isfinite(action.timeout_seconds) or action.timeout_seconds <= 0:
|
|
136
|
+
raise ValueError("timeout_seconds must be finite and positive")
|
|
137
|
+
started = time.monotonic()
|
|
138
|
+
context = ExecutionContext(started + action.timeout_seconds)
|
|
139
|
+
attempt = 0
|
|
140
|
+
while True:
|
|
141
|
+
decision = _evaluate_policy(self.policy, action)
|
|
142
|
+
if not decision.allowed:
|
|
143
|
+
return ActionResult(
|
|
144
|
+
ActionStatus.PENDING_INTERVENTION
|
|
145
|
+
if decision.pending
|
|
146
|
+
else ActionStatus.DENIED,
|
|
147
|
+
error=decision.reason,
|
|
148
|
+
attempts=attempt,
|
|
149
|
+
intervention_request_id=decision.intervention_request_id,
|
|
150
|
+
)
|
|
151
|
+
attempt += 1
|
|
152
|
+
dispatched = False
|
|
153
|
+
try:
|
|
154
|
+
async with asyncio.timeout(context.remaining_seconds):
|
|
155
|
+
context.check_deadline()
|
|
156
|
+
await self.hooks.run(
|
|
157
|
+
HookContext(HookBoundary.BEFORE_ACTION, {"action": action})
|
|
158
|
+
)
|
|
159
|
+
dispatched = True
|
|
160
|
+
output = await self.adapter.execute(action, context)
|
|
161
|
+
context.check_deadline()
|
|
162
|
+
await self.hooks.run(
|
|
163
|
+
HookContext(
|
|
164
|
+
HookBoundary.AFTER_RESULT,
|
|
165
|
+
{"action": action, "output": output},
|
|
166
|
+
)
|
|
167
|
+
)
|
|
168
|
+
return ActionResult(
|
|
169
|
+
ActionStatus.SUCCEEDED,
|
|
170
|
+
output,
|
|
171
|
+
attempts=attempt,
|
|
172
|
+
duration_seconds=time.monotonic() - started,
|
|
173
|
+
)
|
|
174
|
+
except HookRejected as exc:
|
|
175
|
+
result = ActionResult(
|
|
176
|
+
ActionStatus.FAILED if dispatched else ActionStatus.DENIED,
|
|
177
|
+
error=str(exc),
|
|
178
|
+
attempts=attempt,
|
|
179
|
+
failure_kind=FailureKind.UNKNOWN
|
|
180
|
+
if dispatched
|
|
181
|
+
else FailureKind.VALIDATION,
|
|
182
|
+
outcome_unknown=dispatched,
|
|
183
|
+
)
|
|
184
|
+
except TimeoutError as exc:
|
|
185
|
+
result = ActionResult(
|
|
186
|
+
ActionStatus.TIMED_OUT,
|
|
187
|
+
error=str(exc) or "Deadline exceeded",
|
|
188
|
+
attempts=attempt,
|
|
189
|
+
failure_kind=FailureKind.TIMEOUT,
|
|
190
|
+
outcome_unknown=True,
|
|
191
|
+
)
|
|
192
|
+
except ExecutionFailure as exc:
|
|
193
|
+
result = ActionResult(
|
|
194
|
+
ActionStatus.FAILED,
|
|
195
|
+
error=str(exc),
|
|
196
|
+
attempts=attempt,
|
|
197
|
+
failure_kind=exc.kind,
|
|
198
|
+
outcome_unknown=exc.outcome_unknown,
|
|
199
|
+
)
|
|
200
|
+
except Exception as exc:
|
|
201
|
+
result = ActionResult(
|
|
202
|
+
ActionStatus.FAILED,
|
|
203
|
+
error=str(exc),
|
|
204
|
+
attempts=attempt,
|
|
205
|
+
failure_kind=FailureKind.UNKNOWN,
|
|
206
|
+
outcome_unknown=True,
|
|
207
|
+
)
|
|
208
|
+
result = _duration(result, time.monotonic() - started)
|
|
209
|
+
if not self.retry_policy.should_retry(action, result):
|
|
210
|
+
return result
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def _duration(result: ActionResult, seconds: float) -> ActionResult:
|
|
214
|
+
from dataclasses import replace
|
|
215
|
+
|
|
216
|
+
return replace(result, duration_seconds=seconds)
|
bbagents/experiments.py
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
"""Reference dataset trials with application-owned isolated environments."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
import hashlib
|
|
5
|
+
import json
|
|
6
|
+
import math
|
|
7
|
+
from statistics import mean, pstdev
|
|
8
|
+
from typing import Any, Callable, ContextManager, Generic, Mapping, Sequence, TypeVar
|
|
9
|
+
from uuid import uuid4
|
|
10
|
+
|
|
11
|
+
from .evaluation import (
|
|
12
|
+
Grade,
|
|
13
|
+
Grader,
|
|
14
|
+
TrialEvidence,
|
|
15
|
+
TrialGrades,
|
|
16
|
+
TrialReport,
|
|
17
|
+
grade_trial,
|
|
18
|
+
report_trials,
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
InputT = TypeVar("InputT")
|
|
22
|
+
EnvironmentT = TypeVar("EnvironmentT")
|
|
23
|
+
OutcomeT = TypeVar("OutcomeT")
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass(frozen=True, slots=True)
|
|
27
|
+
class EvaluationCase(Generic[InputT]):
|
|
28
|
+
id: str
|
|
29
|
+
input: InputT
|
|
30
|
+
split: str = "regression"
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
@dataclass(frozen=True, slots=True)
|
|
34
|
+
class Dataset(Generic[InputT]):
|
|
35
|
+
id: str
|
|
36
|
+
version: str
|
|
37
|
+
cases: tuple[EvaluationCase[InputT], ...]
|
|
38
|
+
|
|
39
|
+
def __post_init__(self) -> None:
|
|
40
|
+
if (
|
|
41
|
+
not self.id
|
|
42
|
+
or not self.version
|
|
43
|
+
or len({case.id for case in self.cases}) != len(self.cases)
|
|
44
|
+
):
|
|
45
|
+
raise ValueError("Datasets require identity, version and unique cases")
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass(frozen=True, slots=True)
|
|
49
|
+
class ExperimentReport:
|
|
50
|
+
dataset_id: str
|
|
51
|
+
dataset_version: str
|
|
52
|
+
configuration_fingerprint: str
|
|
53
|
+
grades: tuple[TrialGrades, ...]
|
|
54
|
+
summary: TrialReport
|
|
55
|
+
mean_duration_seconds: float | None
|
|
56
|
+
duration_stddev_seconds: float | None
|
|
57
|
+
total_known_cost: float
|
|
58
|
+
trials_without_cost: int
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def run_dataset(
|
|
62
|
+
dataset: Dataset[InputT],
|
|
63
|
+
*,
|
|
64
|
+
configuration: Mapping[str, Any],
|
|
65
|
+
environment: Callable[[EvaluationCase[InputT]], ContextManager[EnvironmentT]],
|
|
66
|
+
execute: Callable[
|
|
67
|
+
[EvaluationCase[InputT], EnvironmentT, str, Mapping[str, Any]],
|
|
68
|
+
TrialEvidence[OutcomeT],
|
|
69
|
+
],
|
|
70
|
+
graders: Mapping[str, Grader[OutcomeT]],
|
|
71
|
+
repetitions: int = 1,
|
|
72
|
+
split: str = "regression",
|
|
73
|
+
) -> ExperimentReport:
|
|
74
|
+
"""Hosts must create/reset isolated state in each fixture and clean up on exit.
|
|
75
|
+
|
|
76
|
+
Failures propagate after fixture cleanup. This is a reference synchronous
|
|
77
|
+
evaluation loop, not an agent scheduler. Held-out cases run only when selected.
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
if repetitions < 1 or not graders:
|
|
81
|
+
raise ValueError("Evaluation requires positive repetitions and graders")
|
|
82
|
+
fingerprint = _fingerprint(configuration)
|
|
83
|
+
results: list[TrialGrades] = []
|
|
84
|
+
evidence: list[TrialEvidence[OutcomeT]] = []
|
|
85
|
+
experiment_id = uuid4().hex
|
|
86
|
+
for case in dataset.cases:
|
|
87
|
+
if case.split != split:
|
|
88
|
+
continue
|
|
89
|
+
for repetition in range(repetitions):
|
|
90
|
+
trial_id = f"{experiment_id}:{case.id}:{repetition}"
|
|
91
|
+
with environment(case) as isolated:
|
|
92
|
+
trial = execute(case, isolated, trial_id, configuration)
|
|
93
|
+
if trial.case_id != case.id or trial.trial_id != trial_id:
|
|
94
|
+
raise ValueError("Runner returned mismatched trial identity")
|
|
95
|
+
if _fingerprint(trial.configuration) != fingerprint:
|
|
96
|
+
raise ValueError("Runner returned mismatched configuration")
|
|
97
|
+
results.append(grade_trial(trial, graders))
|
|
98
|
+
evidence.append(trial)
|
|
99
|
+
durations = [trial.duration_seconds for trial in evidence]
|
|
100
|
+
return ExperimentReport(
|
|
101
|
+
dataset.id,
|
|
102
|
+
dataset.version,
|
|
103
|
+
fingerprint,
|
|
104
|
+
tuple(results),
|
|
105
|
+
report_trials(results),
|
|
106
|
+
mean(durations) if durations else None,
|
|
107
|
+
pstdev(durations) if durations else None,
|
|
108
|
+
sum(trial.cost for trial in evidence if trial.cost is not None),
|
|
109
|
+
sum(trial.cost is None for trial in evidence),
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _fingerprint(configuration: Mapping[str, Any]) -> str:
|
|
114
|
+
return hashlib.sha256(
|
|
115
|
+
json.dumps(
|
|
116
|
+
dict(configuration),
|
|
117
|
+
sort_keys=True,
|
|
118
|
+
allow_nan=False,
|
|
119
|
+
).encode()
|
|
120
|
+
).hexdigest()
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def success_interval(
|
|
124
|
+
results: Sequence[TrialGrades],
|
|
125
|
+
*,
|
|
126
|
+
independent_trials: bool = False,
|
|
127
|
+
) -> tuple[float, float] | None:
|
|
128
|
+
"""95% Wilson interval, ONLY if caller justifies independent Bernoulli trials.
|
|
129
|
+
|
|
130
|
+
Unknown grades are not demonstrated successes. Correlated repetitions of a
|
|
131
|
+
task usually violate the independence assumption; default returns no interval.
|
|
132
|
+
"""
|
|
133
|
+
|
|
134
|
+
if not independent_trials or not results:
|
|
135
|
+
return None
|
|
136
|
+
report = report_trials(results)
|
|
137
|
+
n = report.trials
|
|
138
|
+
p = report.passed / n
|
|
139
|
+
z = 1.959963984540054
|
|
140
|
+
denominator = 1 + z * z / n
|
|
141
|
+
center = (p + z * z / (2 * n)) / denominator
|
|
142
|
+
half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / denominator
|
|
143
|
+
return max(0.0, center - half), min(1.0, center + half)
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
@dataclass(frozen=True, slots=True)
|
|
147
|
+
class CalibrationReport:
|
|
148
|
+
judge_version: str
|
|
149
|
+
rubric_version: str
|
|
150
|
+
compared: int
|
|
151
|
+
agreements: int
|
|
152
|
+
insufficient: int
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def calibrate(
|
|
156
|
+
pairs: Sequence[tuple[Grade, Grade]],
|
|
157
|
+
*,
|
|
158
|
+
judge_version: str,
|
|
159
|
+
rubric_version: str,
|
|
160
|
+
) -> CalibrationReport:
|
|
161
|
+
compared = [
|
|
162
|
+
(judge, human)
|
|
163
|
+
for judge, human in pairs
|
|
164
|
+
if judge.passed is not None and human.passed is not None
|
|
165
|
+
]
|
|
166
|
+
return CalibrationReport(
|
|
167
|
+
judge_version,
|
|
168
|
+
rubric_version,
|
|
169
|
+
len(compared),
|
|
170
|
+
sum(judge.passed == human.passed for judge, human in compared),
|
|
171
|
+
len(pairs) - len(compared),
|
|
172
|
+
)
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
"""Scoped memory with revision history and authorization before ranking."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import asdict, replace
|
|
4
|
+
from datetime import datetime
|
|
5
|
+
from typing import Any, Callable
|
|
6
|
+
|
|
7
|
+
from .memory import Embedder, MemoryKind, MemoryRecord, MemoryResult, MemoryStore
|
|
8
|
+
from .provenance import Provenance, TrustLevel
|
|
9
|
+
from .revisions import RevisionRepository
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class ScopedMemoryStore:
|
|
13
|
+
def __init__(
|
|
14
|
+
self,
|
|
15
|
+
revisions: RevisionRepository[dict[str, Any]],
|
|
16
|
+
*,
|
|
17
|
+
embed: Embedder | None = None,
|
|
18
|
+
) -> None:
|
|
19
|
+
self.revisions = revisions
|
|
20
|
+
self.embed = embed
|
|
21
|
+
|
|
22
|
+
def get(self, record_id: str) -> MemoryRecord | None:
|
|
23
|
+
revision = self.revisions.current(record_id)
|
|
24
|
+
return None if revision is None else _decode(revision.value, revision.number)
|
|
25
|
+
|
|
26
|
+
def remember(
|
|
27
|
+
self, record: MemoryRecord, *, expected_version: int | None = None
|
|
28
|
+
) -> MemoryRecord:
|
|
29
|
+
history = self.revisions.history(record.id)
|
|
30
|
+
revision = self.revisions.append(
|
|
31
|
+
record.id,
|
|
32
|
+
_encode(record),
|
|
33
|
+
expected_revision=len(history)
|
|
34
|
+
if expected_version is None
|
|
35
|
+
else expected_version,
|
|
36
|
+
reason="memory update",
|
|
37
|
+
activate=True,
|
|
38
|
+
)
|
|
39
|
+
return replace(record, version=revision.number)
|
|
40
|
+
|
|
41
|
+
def retrieve(
|
|
42
|
+
self, query: str, *, limit: int = 10, kind: MemoryKind | None = None
|
|
43
|
+
) -> list[MemoryResult]:
|
|
44
|
+
# Authorization and scope selection happen before embeddings or scoring.
|
|
45
|
+
items = self.revisions.items()
|
|
46
|
+
memory = MemoryStore(self.embed)
|
|
47
|
+
versions: dict[str, int] = {}
|
|
48
|
+
for item_id, revision in items:
|
|
49
|
+
memory.remember(_decode(revision.value, revision.number))
|
|
50
|
+
versions[item_id] = revision.number
|
|
51
|
+
return [
|
|
52
|
+
MemoryResult(
|
|
53
|
+
replace(result.record, version=versions[result.record.id]), result.score
|
|
54
|
+
)
|
|
55
|
+
for result in memory.retrieve(query, limit=limit, kind=kind)
|
|
56
|
+
]
|
|
57
|
+
|
|
58
|
+
def forget(self, predicate: Callable[[MemoryRecord], bool]) -> int:
|
|
59
|
+
removed = 0
|
|
60
|
+
for item_id, revision in self.revisions.items():
|
|
61
|
+
if predicate(_decode(revision.value, revision.number)):
|
|
62
|
+
self.revisions.activate(
|
|
63
|
+
item_id, None, expected_active=revision.number, reason="archived"
|
|
64
|
+
)
|
|
65
|
+
removed += 1
|
|
66
|
+
return removed
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _encode(record: MemoryRecord) -> dict[str, Any]:
|
|
70
|
+
data = asdict(record)
|
|
71
|
+
data["created_at"] = record.created_at.isoformat()
|
|
72
|
+
data["provenance"]["received_at"] = record.provenance.received_at.isoformat()
|
|
73
|
+
return data
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _decode(data: dict[str, Any], version: int) -> MemoryRecord:
|
|
77
|
+
values = dict(data)
|
|
78
|
+
values["kind"] = MemoryKind(values["kind"])
|
|
79
|
+
values["created_at"] = datetime.fromisoformat(values["created_at"])
|
|
80
|
+
provenance = dict(values["provenance"])
|
|
81
|
+
provenance["trust"] = TrustLevel(provenance["trust"])
|
|
82
|
+
provenance["received_at"] = datetime.fromisoformat(provenance["received_at"])
|
|
83
|
+
values["provenance"] = Provenance(**provenance)
|
|
84
|
+
values["version"] = version
|
|
85
|
+
return MemoryRecord(**values)
|
bbagents/hooks.py
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
"""Bounded, traced async enforcement boundaries with explicit failure behavior."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
from dataclasses import dataclass, field
|
|
5
|
+
from enum import Enum
|
|
6
|
+
import math
|
|
7
|
+
from typing import Any, Awaitable, Callable, Mapping
|
|
8
|
+
|
|
9
|
+
from .core import NullTrace, TraceSink
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class HookBoundary(str, Enum):
|
|
13
|
+
BEFORE_MODEL = "before_model"
|
|
14
|
+
BEFORE_ACTION = "before_action"
|
|
15
|
+
AFTER_RESULT = "after_result"
|
|
16
|
+
BEFORE_COMPLETE = "before_complete"
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass(frozen=True, slots=True)
|
|
20
|
+
class HookContext:
|
|
21
|
+
boundary: HookBoundary
|
|
22
|
+
values: Mapping[str, Any] = field(default_factory=dict)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@dataclass(frozen=True, slots=True)
|
|
26
|
+
class HookDecision:
|
|
27
|
+
allowed: bool
|
|
28
|
+
reason: str = ""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass(frozen=True, slots=True)
|
|
32
|
+
class Hook:
|
|
33
|
+
name: str
|
|
34
|
+
boundary: HookBoundary
|
|
35
|
+
callback: Callable[[HookContext], Awaitable[HookDecision]]
|
|
36
|
+
timeout_seconds: float = 5.0
|
|
37
|
+
blocking: bool = True
|
|
38
|
+
|
|
39
|
+
def __post_init__(self) -> None:
|
|
40
|
+
if not math.isfinite(self.timeout_seconds) or self.timeout_seconds <= 0:
|
|
41
|
+
raise ValueError("hook timeout must be finite and positive")
|
|
42
|
+
if not self.blocking and self.boundary != HookBoundary.AFTER_RESULT:
|
|
43
|
+
raise ValueError("Only observational AFTER_RESULT hooks may fail open")
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class HookRejected(RuntimeError):
|
|
47
|
+
pass
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class HookRunner:
|
|
51
|
+
"""Callbacks must cooperate with cancellation; hooks confer no capabilities."""
|
|
52
|
+
|
|
53
|
+
def __init__(
|
|
54
|
+
self, hooks: tuple[Hook, ...] = (), *, trace: TraceSink | None = None
|
|
55
|
+
) -> None:
|
|
56
|
+
self.hooks = hooks
|
|
57
|
+
self.trace = trace or NullTrace()
|
|
58
|
+
|
|
59
|
+
async def run(self, context: HookContext) -> None:
|
|
60
|
+
for hook in self.hooks:
|
|
61
|
+
if hook.boundary != context.boundary:
|
|
62
|
+
continue
|
|
63
|
+
self.trace.record(
|
|
64
|
+
"hook.started", {"hook": hook.name, "boundary": context.boundary.value}
|
|
65
|
+
)
|
|
66
|
+
try:
|
|
67
|
+
async with asyncio.timeout(hook.timeout_seconds):
|
|
68
|
+
decision = await hook.callback(context)
|
|
69
|
+
except Exception as exc:
|
|
70
|
+
self.trace.record("hook.failed", {"hook": hook.name, "error": str(exc)})
|
|
71
|
+
if hook.blocking:
|
|
72
|
+
raise HookRejected(f"Hook {hook.name} failed") from exc
|
|
73
|
+
continue
|
|
74
|
+
self.trace.record(
|
|
75
|
+
"hook.finished", {"hook": hook.name, "allowed": decision.allowed}
|
|
76
|
+
)
|
|
77
|
+
if not decision.allowed:
|
|
78
|
+
raise HookRejected(f"Hook {hook.name}: {decision.reason}")
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Optional adapters for external orchestration and integration runtimes."""
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
"""Optional reviewed-manifest Agent Skills loader; never executes bundled code."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass, field
|
|
4
|
+
import hashlib
|
|
5
|
+
from importlib import import_module
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Mapping
|
|
8
|
+
|
|
9
|
+
from ..revisions import AccessContext, AccessPolicy
|
|
10
|
+
from ..skills import Skill, SkillDescriptor
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
@dataclass(frozen=True, slots=True)
|
|
14
|
+
class PinnedSkill:
|
|
15
|
+
"""Trusted deployment manifest, kept outside the agent-writable workspace."""
|
|
16
|
+
|
|
17
|
+
descriptor: SkillDescriptor
|
|
18
|
+
directory: str
|
|
19
|
+
sha256: str
|
|
20
|
+
resources: Mapping[str, str] = field(default_factory=dict)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class FilesystemSkillSource:
|
|
24
|
+
def __init__(
|
|
25
|
+
self,
|
|
26
|
+
root: Path,
|
|
27
|
+
pins: tuple[PinnedSkill, ...],
|
|
28
|
+
context: AccessContext,
|
|
29
|
+
policy: AccessPolicy,
|
|
30
|
+
*,
|
|
31
|
+
max_bytes: int = 1_000_000,
|
|
32
|
+
) -> None:
|
|
33
|
+
self.root = root.resolve()
|
|
34
|
+
self.context = context
|
|
35
|
+
self.policy = policy
|
|
36
|
+
self.max_bytes = max_bytes
|
|
37
|
+
self.pins = {(pin.descriptor.id, pin.descriptor.version): pin for pin in pins}
|
|
38
|
+
if len(self.pins) != len(pins):
|
|
39
|
+
raise ValueError("Duplicate skill revision")
|
|
40
|
+
|
|
41
|
+
def _authorize(self, operation: str) -> None:
|
|
42
|
+
if not self.policy.permits(self.context, operation):
|
|
43
|
+
raise PermissionError(f"Skill access denied: {operation}")
|
|
44
|
+
|
|
45
|
+
def discover(self, *, scope: str) -> tuple[SkillDescriptor, ...]:
|
|
46
|
+
self._authorize("skill.discover")
|
|
47
|
+
if scope != self.context.scope:
|
|
48
|
+
raise PermissionError("Skill scope mismatch")
|
|
49
|
+
return tuple(
|
|
50
|
+
pin.descriptor
|
|
51
|
+
for pin in self.pins.values()
|
|
52
|
+
if pin.descriptor.scope == scope
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
def _pin(self, skill_id: str, version: str) -> PinnedSkill:
|
|
56
|
+
pin = self.pins[(skill_id, version)]
|
|
57
|
+
if pin.descriptor.scope != self.context.scope:
|
|
58
|
+
raise PermissionError("Skill scope mismatch")
|
|
59
|
+
return pin
|
|
60
|
+
|
|
61
|
+
def _read(self, pin: PinnedSkill, relative: str, digest: str) -> bytes:
|
|
62
|
+
directory = (self.root / pin.directory).resolve()
|
|
63
|
+
path = (directory / relative).resolve()
|
|
64
|
+
if not directory.is_relative_to(self.root) or not path.is_relative_to(
|
|
65
|
+
directory
|
|
66
|
+
):
|
|
67
|
+
raise PermissionError("Skill path escapes its reviewed directory")
|
|
68
|
+
with path.open("rb") as handle:
|
|
69
|
+
data = handle.read(self.max_bytes + 1)
|
|
70
|
+
if len(data) > self.max_bytes:
|
|
71
|
+
raise ValueError("Skill resource exceeds size limit")
|
|
72
|
+
if hashlib.sha256(data).hexdigest() != digest:
|
|
73
|
+
raise ValueError("Skill revision digest changed")
|
|
74
|
+
return data
|
|
75
|
+
|
|
76
|
+
def load(self, skill_id: str, *, version: str) -> Skill:
|
|
77
|
+
self._authorize("skill.load")
|
|
78
|
+
pin = self._pin(skill_id, version)
|
|
79
|
+
text = (
|
|
80
|
+
self._read(pin, "SKILL.md", pin.sha256)
|
|
81
|
+
.decode("utf-8")
|
|
82
|
+
.replace("\r\n", "\n")
|
|
83
|
+
)
|
|
84
|
+
if not text.startswith("---\n") or "\n---\n" not in text[4:]:
|
|
85
|
+
raise ValueError("SKILL.md requires YAML frontmatter")
|
|
86
|
+
header, instructions = text[4:].split("\n---\n", 1)
|
|
87
|
+
try:
|
|
88
|
+
yaml = import_module("yaml")
|
|
89
|
+
except ModuleNotFoundError as exc:
|
|
90
|
+
raise RuntimeError("Install bbagents[skills] to parse SKILL.md") from exc
|
|
91
|
+
metadata = yaml.safe_load(header)
|
|
92
|
+
if not isinstance(metadata, dict) or metadata.get("name") != skill_id:
|
|
93
|
+
raise ValueError("Skill name does not match manifest")
|
|
94
|
+
if metadata.get("description") != pin.descriptor.description:
|
|
95
|
+
raise ValueError("Skill description does not match manifest")
|
|
96
|
+
return Skill(pin.descriptor, instructions, tuple(pin.resources))
|
|
97
|
+
|
|
98
|
+
def read_resource(self, skill_id: str, *, version: str, resource: str) -> bytes:
|
|
99
|
+
self._authorize("skill.resource")
|
|
100
|
+
pin = self._pin(skill_id, version)
|
|
101
|
+
return self._read(pin, resource, pin.resources[resource])
|