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,19 @@
|
|
|
1
|
+
"""
|
|
2
|
+
agentspec_sdk — Python SDK for AgentSpec Universal Agent Manifests.
|
|
3
|
+
|
|
4
|
+
Usage:
|
|
5
|
+
from agentspec_sdk import AgentSpecReporter
|
|
6
|
+
|
|
7
|
+
reporter = AgentSpecReporter.from_yaml("agent.yaml")
|
|
8
|
+
reporter.start_push_mode(
|
|
9
|
+
control_plane_url="https://control-plane.agentspec.io",
|
|
10
|
+
api_key="<agent token from POST /api/v1/register>",
|
|
11
|
+
)
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from .evidence_points import guardrail, mcp_client, structured_logging, tool
|
|
15
|
+
from .memory_points import memory_write, vector_store
|
|
16
|
+
from .reporter import AgentSpecReporter
|
|
17
|
+
from .types import HealthReport, HealthCheck
|
|
18
|
+
|
|
19
|
+
__all__ = ["AgentSpecReporter", "guardrail", "tool", "mcp_client", "structured_logging", "memory_write", "vector_store", "HealthReport", "HealthCheck"]
|
|
@@ -0,0 +1,522 @@
|
|
|
1
|
+
# generated by datamodel-codegen:
|
|
2
|
+
# filename: contract.schema.json
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
from enum import Enum
|
|
7
|
+
from typing import Any, Literal
|
|
8
|
+
|
|
9
|
+
from pydantic import BaseModel, ConfigDict, Field, RootModel, confloat, conint, constr
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Env(BaseModel):
|
|
13
|
+
model_config = ConfigDict(
|
|
14
|
+
extra='forbid',
|
|
15
|
+
)
|
|
16
|
+
manifestPath: Literal['MANIFEST_PATH'] = 'MANIFEST_PATH'
|
|
17
|
+
upstreamUrl: Literal['UPSTREAM_URL'] = 'UPSTREAM_URL'
|
|
18
|
+
proxyPort: Literal['PROXY_PORT'] = 'PROXY_PORT'
|
|
19
|
+
controlPlanePort: Literal['CONTROL_PLANE_PORT'] = 'CONTROL_PLANE_PORT'
|
|
20
|
+
controlPlaneUrl: Literal['AGENTSPEC_CONTROL_PLANE_URL'] = (
|
|
21
|
+
'AGENTSPEC_CONTROL_PLANE_URL'
|
|
22
|
+
)
|
|
23
|
+
agentKey: Literal['AGENTSPEC_API_KEY'] = 'AGENTSPEC_API_KEY'
|
|
24
|
+
trustPolicy: Literal['AGENTSPEC_TRUST_POLICY'] = 'AGENTSPEC_TRUST_POLICY'
|
|
25
|
+
podspecFindings: Literal['AGENTSPEC_PODSPEC_FINDINGS'] = (
|
|
26
|
+
'AGENTSPEC_PODSPEC_FINDINGS'
|
|
27
|
+
)
|
|
28
|
+
gatewayKey: Literal['AGENTSPEC_GATEWAY_KEY'] = 'AGENTSPEC_GATEWAY_KEY'
|
|
29
|
+
agentHost: Literal['HOST'] = 'HOST'
|
|
30
|
+
agentPort: Literal['PORT'] = 'PORT'
|
|
31
|
+
azureResourceName: Literal['AZURE_OPENAI_RESOURCE_NAME'] = (
|
|
32
|
+
'AZURE_OPENAI_RESOURCE_NAME'
|
|
33
|
+
)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class ProviderBaseUrlEnv(BaseModel):
|
|
37
|
+
model_config = ConfigDict(
|
|
38
|
+
extra='forbid',
|
|
39
|
+
)
|
|
40
|
+
openai: Literal['OPENAI_BASE_URL'] = 'OPENAI_BASE_URL'
|
|
41
|
+
anthropic: Literal['ANTHROPIC_BASE_URL'] = 'ANTHROPIC_BASE_URL'
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class Paths(BaseModel):
|
|
45
|
+
model_config = ConfigDict(
|
|
46
|
+
extra='forbid',
|
|
47
|
+
)
|
|
48
|
+
manifestDir: Literal['/manifest'] = '/manifest'
|
|
49
|
+
manifestFile: Literal['/manifest/agent.yaml'] = '/manifest/agent.yaml'
|
|
50
|
+
gatewayDatabase: Literal['/gateway-data/agentgateway.db'] = (
|
|
51
|
+
'/gateway-data/agentgateway.db'
|
|
52
|
+
)
|
|
53
|
+
gatewayConfigDir: Literal['/gateway'] = '/gateway'
|
|
54
|
+
gatewayConfigFile: Literal['/gateway/config.yaml'] = '/gateway/config.yaml'
|
|
55
|
+
sidecarEntrypoint: Literal['dist/index.js'] = 'dist/index.js'
|
|
56
|
+
gatewayDataDir: Literal['/gateway-data'] = '/gateway-data'
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
class Images(BaseModel):
|
|
60
|
+
model_config = ConfigDict(
|
|
61
|
+
extra='forbid',
|
|
62
|
+
)
|
|
63
|
+
sidecar: Literal['ghcr.io/agents-oss/agentspec-sidecar:latest'] = (
|
|
64
|
+
'ghcr.io/agents-oss/agentspec-sidecar:latest'
|
|
65
|
+
)
|
|
66
|
+
gateway: Literal['cr.agentgateway.dev/agentgateway:v1.6.0'] = (
|
|
67
|
+
'cr.agentgateway.dev/agentgateway:v1.6.0'
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class Ports(BaseModel):
|
|
72
|
+
model_config = ConfigDict(
|
|
73
|
+
extra='forbid',
|
|
74
|
+
)
|
|
75
|
+
agentDefault: Literal[8000] = 8000
|
|
76
|
+
agentBind: Literal[18000] = 18000
|
|
77
|
+
proxy: Literal[4000] = 4000
|
|
78
|
+
controlPlane: Literal[4001] = 4001
|
|
79
|
+
gateway: Literal[4002] = 4002
|
|
80
|
+
gatewayStats: Literal[15020] = 15020
|
|
81
|
+
gatewayReadiness: Literal[15021] = 15021
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
class SidecarPaths(BaseModel):
|
|
85
|
+
model_config = ConfigDict(
|
|
86
|
+
extra='forbid',
|
|
87
|
+
)
|
|
88
|
+
healthReady: Literal['/health/ready'] = '/health/ready'
|
|
89
|
+
gap: Literal['/gap'] = '/gap'
|
|
90
|
+
explore: Literal['/explore'] = '/explore'
|
|
91
|
+
proof: Literal['/proof'] = '/proof'
|
|
92
|
+
traces: Literal['/v1/traces'] = '/v1/traces'
|
|
93
|
+
spans: Literal['/spans'] = '/spans'
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
class AgentPaths(BaseModel):
|
|
97
|
+
model_config = ConfigDict(
|
|
98
|
+
extra='forbid',
|
|
99
|
+
)
|
|
100
|
+
health: Literal['/agentspec/health'] = '/agentspec/health'
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
class ControlPlanePaths(BaseModel):
|
|
104
|
+
model_config = ConfigDict(
|
|
105
|
+
extra='forbid',
|
|
106
|
+
)
|
|
107
|
+
register_: Literal['/api/v1/register'] = Field('/api/v1/register', alias='register')
|
|
108
|
+
heartbeat: Literal['/api/v1/heartbeat'] = '/api/v1/heartbeat'
|
|
109
|
+
declaredAudit: Literal['/api/v1/agents/{name}/declared-audit'] = (
|
|
110
|
+
'/api/v1/agents/{name}/declared-audit'
|
|
111
|
+
)
|
|
112
|
+
sidecarPush: Literal['/api/v1/agents/{name}/sidecar-push'] = (
|
|
113
|
+
'/api/v1/agents/{name}/sidecar-push'
|
|
114
|
+
)
|
|
115
|
+
evidence: Literal['/api/v1/agents/{name}/evidence'] = (
|
|
116
|
+
'/api/v1/agents/{name}/evidence'
|
|
117
|
+
)
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class PodPatch(BaseModel):
|
|
121
|
+
model_config = ConfigDict(
|
|
122
|
+
extra='forbid',
|
|
123
|
+
)
|
|
124
|
+
sidecarContainer: Literal['agentspec-sidecar'] = 'agentspec-sidecar'
|
|
125
|
+
podspecFindingsAnnotation: Literal['agentspec.io/podspec-findings'] = (
|
|
126
|
+
'agentspec.io/podspec-findings'
|
|
127
|
+
)
|
|
128
|
+
agentNameAnnotation: Literal['agentspec.io/agent-name'] = 'agentspec.io/agent-name'
|
|
129
|
+
manifestVolume: Literal['agentspec-manifest'] = 'agentspec-manifest'
|
|
130
|
+
proxyPortName: Literal['proxy'] = 'proxy'
|
|
131
|
+
controlPortName: Literal['control'] = 'control'
|
|
132
|
+
gatewayContainer: Literal['agentspec-gateway'] = 'agentspec-gateway'
|
|
133
|
+
gatewayConfigInitContainer: Literal['agentspec-gateway-config'] = (
|
|
134
|
+
'agentspec-gateway-config'
|
|
135
|
+
)
|
|
136
|
+
gatewayConfigCommand: Literal['gateway-config'] = 'gateway-config'
|
|
137
|
+
gatewayConfigVolume: Literal['agentspec-gateway-config'] = (
|
|
138
|
+
'agentspec-gateway-config'
|
|
139
|
+
)
|
|
140
|
+
gatewayDataVolume: Literal['agentspec-gateway-data'] = 'agentspec-gateway-data'
|
|
141
|
+
agentTokenSecretSuffix: Literal['-agentspec-token'] = '-agentspec-token'
|
|
142
|
+
agentTokenSecretKey: Literal['token'] = 'token'
|
|
143
|
+
loopback: Literal['127.0.0.1'] = '127.0.0.1'
|
|
144
|
+
gatewayCpuRequest: Literal['25m'] = '25m'
|
|
145
|
+
gatewayMemoryRequest: Literal['32Mi'] = '32Mi'
|
|
146
|
+
gatewayMemoryLimit: Literal['128Mi'] = '128Mi'
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
class Webhook(BaseModel):
|
|
150
|
+
model_config = ConfigDict(
|
|
151
|
+
extra='forbid',
|
|
152
|
+
)
|
|
153
|
+
injectPath: Literal['/inject-sidecar'] = '/inject-sidecar'
|
|
154
|
+
namespaceLabel: Literal['agentspec.io/enabled'] = 'agentspec.io/enabled'
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
class SeverityWeights(BaseModel):
|
|
158
|
+
model_config = ConfigDict(
|
|
159
|
+
extra='forbid',
|
|
160
|
+
)
|
|
161
|
+
critical: Literal[4] = 4
|
|
162
|
+
high: Literal[3] = 3
|
|
163
|
+
medium: Literal[2] = 2
|
|
164
|
+
low: Literal[1] = 1
|
|
165
|
+
info: Literal[0] = 0
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
class GradeBands(BaseModel):
|
|
169
|
+
model_config = ConfigDict(
|
|
170
|
+
extra='forbid',
|
|
171
|
+
)
|
|
172
|
+
A: Literal[90] = 90
|
|
173
|
+
B: Literal[75] = 75
|
|
174
|
+
C: Literal[60] = 60
|
|
175
|
+
D: Literal[45] = 45
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
class Otlp(BaseModel):
|
|
179
|
+
model_config = ConfigDict(
|
|
180
|
+
extra='forbid',
|
|
181
|
+
)
|
|
182
|
+
resourceAgentName: Literal['agentspec.agent.name'] = 'agentspec.agent.name'
|
|
183
|
+
resourceManifestSha256: Literal['agentspec.manifest.sha256'] = (
|
|
184
|
+
'agentspec.manifest.sha256'
|
|
185
|
+
)
|
|
186
|
+
endpointEnv: Literal['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'OTEL_EXPORTER_OTLP_ENDPOINT'
|
|
187
|
+
resourceServiceName: Literal['service.name'] = 'service.name'
|
|
188
|
+
gatewayServiceName: Literal['agentgateway'] = 'agentgateway'
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
class Severity(str, Enum):
|
|
192
|
+
critical = 'critical'
|
|
193
|
+
high = 'high'
|
|
194
|
+
medium = 'medium'
|
|
195
|
+
low = 'low'
|
|
196
|
+
info = 'info'
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
class ReadinessFinding(BaseModel):
|
|
200
|
+
model_config = ConfigDict(
|
|
201
|
+
extra='forbid',
|
|
202
|
+
)
|
|
203
|
+
code: constr(min_length=1)
|
|
204
|
+
severity: Severity
|
|
205
|
+
message: constr(min_length=1)
|
|
206
|
+
subject: str | None = None
|
|
207
|
+
ruleIds: list[constr(min_length=1)] | None = None
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
class Source(str, Enum):
|
|
211
|
+
independent = 'independent'
|
|
212
|
+
sdk_observed = 'sdk-observed'
|
|
213
|
+
lower_bound = 'lower-bound'
|
|
214
|
+
self_declared = 'self-declared'
|
|
215
|
+
declared = 'declared'
|
|
216
|
+
offline = 'offline'
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
class TrustPolicy(str, Enum):
|
|
220
|
+
standard = 'standard'
|
|
221
|
+
strict = 'strict'
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
class Origin(str, Enum):
|
|
225
|
+
ingress = 'ingress'
|
|
226
|
+
gateway = 'gateway'
|
|
227
|
+
egress_proxy = 'egress_proxy'
|
|
228
|
+
in_process = 'in_process'
|
|
229
|
+
probe = 'probe'
|
|
230
|
+
manifest = 'manifest'
|
|
231
|
+
judge = 'judge'
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
class Collector(str, Enum):
|
|
235
|
+
gateway_config = 'gateway-config'
|
|
236
|
+
gateway_traffic = 'gateway-traffic'
|
|
237
|
+
sidecar_probe = 'sidecar-probe'
|
|
238
|
+
sidecar_forwarder = 'sidecar-forwarder'
|
|
239
|
+
sidecar_eval = 'sidecar-eval'
|
|
240
|
+
operator_webhook = 'operator-webhook'
|
|
241
|
+
operator_logs = 'operator-logs'
|
|
242
|
+
sdk = 'sdk'
|
|
243
|
+
lock = 'lock'
|
|
244
|
+
manifest = 'manifest'
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
class TraceId(RootModel[constr(min_length=1)]):
|
|
248
|
+
root: constr(min_length=1)
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
class Status(str, Enum):
|
|
252
|
+
fail = 'fail'
|
|
253
|
+
not_verifiable = 'not_verifiable'
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
class EvidenceReason(BaseModel):
|
|
257
|
+
model_config = ConfigDict(
|
|
258
|
+
extra='forbid',
|
|
259
|
+
)
|
|
260
|
+
code: constr(min_length=1)
|
|
261
|
+
detail: str | None = None
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
class EvidenceWindow(BaseModel):
|
|
265
|
+
model_config = ConfigDict(
|
|
266
|
+
extra='forbid',
|
|
267
|
+
)
|
|
268
|
+
start: constr(pattern=r'^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:\d{2})$')
|
|
269
|
+
end: constr(pattern=r'^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:\d{2})$')
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
class Sha256(RootModel[constr(pattern=r'^[a-f0-9]{64}$')]):
|
|
273
|
+
root: constr(pattern=r'^[a-f0-9]{64}$')
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
class Class(str, Enum):
|
|
277
|
+
independent = 'independent'
|
|
278
|
+
evidence_point = 'evidence-point'
|
|
279
|
+
offline = 'offline'
|
|
280
|
+
declared = 'declared'
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
class Point(str, Enum):
|
|
284
|
+
guardrail = 'guardrail'
|
|
285
|
+
tool = 'tool'
|
|
286
|
+
mcpClient = 'mcpClient'
|
|
287
|
+
memoryWrite = 'memoryWrite'
|
|
288
|
+
vectorStore = 'vectorStore'
|
|
289
|
+
logging = 'logging'
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
class Proves(str, Enum):
|
|
293
|
+
declared = 'declared'
|
|
294
|
+
configured = 'configured'
|
|
295
|
+
enforced = 'enforced'
|
|
296
|
+
observed = 'observed'
|
|
297
|
+
ran_where_wired = 'ran-where-wired'
|
|
298
|
+
every_path = 'every-path'
|
|
299
|
+
effective = 'effective'
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
class WiredBy(str, Enum):
|
|
303
|
+
none = 'none'
|
|
304
|
+
operator_render = 'operator-render'
|
|
305
|
+
agent_code = 'agent-code'
|
|
306
|
+
user_schedule = 'user-schedule'
|
|
307
|
+
opt_in = 'opt-in'
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
class Mode(str, Enum):
|
|
311
|
+
standalone = 'standalone'
|
|
312
|
+
operator = 'operator'
|
|
313
|
+
|
|
314
|
+
|
|
315
|
+
class Status1(str, Enum):
|
|
316
|
+
built = 'built'
|
|
317
|
+
partial = 'partial'
|
|
318
|
+
planned = 'planned'
|
|
319
|
+
open = 'open'
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
class CrossCheck(str, Enum):
|
|
323
|
+
gateway_config = 'gateway-config'
|
|
324
|
+
gateway_traffic = 'gateway-traffic'
|
|
325
|
+
sidecar_probe = 'sidecar-probe'
|
|
326
|
+
sidecar_forwarder = 'sidecar-forwarder'
|
|
327
|
+
sidecar_eval = 'sidecar-eval'
|
|
328
|
+
operator_webhook = 'operator-webhook'
|
|
329
|
+
operator_logs = 'operator-logs'
|
|
330
|
+
sdk = 'sdk'
|
|
331
|
+
lock = 'lock'
|
|
332
|
+
manifest = 'manifest'
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
class RuleEvidenceSource(BaseModel):
|
|
336
|
+
model_config = ConfigDict(
|
|
337
|
+
extra='forbid',
|
|
338
|
+
)
|
|
339
|
+
class_: Class = Field(..., alias='class')
|
|
340
|
+
collector: Collector
|
|
341
|
+
point: Point | None = None
|
|
342
|
+
proves: Proves
|
|
343
|
+
wiredBy: WiredBy
|
|
344
|
+
modes: list[Mode] = Field(..., min_length=1)
|
|
345
|
+
status: Status1
|
|
346
|
+
when: constr(min_length=1) | None = None
|
|
347
|
+
crossCheck: CrossCheck | None = None
|
|
348
|
+
question: constr(min_length=1) | None = None
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
class State(str, Enum):
|
|
352
|
+
fired = 'fired'
|
|
353
|
+
wired = 'wired'
|
|
354
|
+
not_wired = 'not_wired'
|
|
355
|
+
|
|
356
|
+
|
|
357
|
+
class Counts(BaseModel):
|
|
358
|
+
model_config = ConfigDict(
|
|
359
|
+
extra='forbid',
|
|
360
|
+
)
|
|
361
|
+
pass_: conint(ge=0, strict=True) = Field(..., alias='pass')
|
|
362
|
+
fail: conint(ge=0, strict=True)
|
|
363
|
+
not_verifiable: conint(ge=0, strict=True)
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
class EvalResult(BaseModel):
|
|
367
|
+
model_config = ConfigDict(
|
|
368
|
+
extra='forbid',
|
|
369
|
+
)
|
|
370
|
+
metric: constr(min_length=1)
|
|
371
|
+
n: conint(ge=0, strict=True)
|
|
372
|
+
passRate: confloat(ge=0.0, le=1.0, strict=True)
|
|
373
|
+
ciLow: confloat(ge=0.0, le=1.0, strict=True)
|
|
374
|
+
ciHigh: confloat(ge=0.0, le=1.0, strict=True)
|
|
375
|
+
threshold: confloat(ge=0.0, le=1.0, strict=True)
|
|
376
|
+
window: EvidenceWindow
|
|
377
|
+
judgeModel: constr(min_length=1)
|
|
378
|
+
rubricHash: Sha256
|
|
379
|
+
source: Source
|
|
380
|
+
dataset: constr(min_length=1) | None = None
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
class EvidenceRecordPass(BaseModel):
|
|
384
|
+
model_config = ConfigDict(
|
|
385
|
+
extra='forbid',
|
|
386
|
+
)
|
|
387
|
+
checkId: constr(min_length=1)
|
|
388
|
+
ruleId: constr(min_length=1) | None = None
|
|
389
|
+
source: Source
|
|
390
|
+
origin: Origin
|
|
391
|
+
collector: Collector | None = None
|
|
392
|
+
observedAt: constr(pattern=r'^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:\d{2})$')
|
|
393
|
+
window: EvidenceWindow
|
|
394
|
+
ttlSeconds: conint(ge=0, strict=True)
|
|
395
|
+
sampleSize: conint(ge=0, strict=True)
|
|
396
|
+
traceIds: list[TraceId] = Field(..., max_length=20)
|
|
397
|
+
manifestSha256: Sha256
|
|
398
|
+
status: Literal['pass']
|
|
399
|
+
reason: EvidenceReason | None = None
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
class EvidenceRecordNotPass(BaseModel):
|
|
403
|
+
model_config = ConfigDict(
|
|
404
|
+
extra='forbid',
|
|
405
|
+
)
|
|
406
|
+
checkId: constr(min_length=1)
|
|
407
|
+
ruleId: constr(min_length=1) | None = None
|
|
408
|
+
source: Source
|
|
409
|
+
origin: Origin
|
|
410
|
+
collector: Collector | None = None
|
|
411
|
+
observedAt: constr(pattern=r'^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:\d{2})$')
|
|
412
|
+
window: EvidenceWindow
|
|
413
|
+
ttlSeconds: conint(ge=0, strict=True)
|
|
414
|
+
sampleSize: conint(ge=0, strict=True)
|
|
415
|
+
traceIds: list[TraceId] = Field(..., max_length=20)
|
|
416
|
+
manifestSha256: Sha256
|
|
417
|
+
status: Status
|
|
418
|
+
reason: EvidenceReason
|
|
419
|
+
|
|
420
|
+
|
|
421
|
+
class RuleEvidenceEntry(BaseModel):
|
|
422
|
+
model_config = ConfigDict(
|
|
423
|
+
extra='forbid',
|
|
424
|
+
)
|
|
425
|
+
sources: list[RuleEvidenceSource] = Field([], validate_default=True)
|
|
426
|
+
derivedFrom: list[constr(min_length=1)] | None = None
|
|
427
|
+
notProven: str | None = None
|
|
428
|
+
|
|
429
|
+
|
|
430
|
+
class AgentSpecContract(BaseModel):
|
|
431
|
+
model_config = ConfigDict(
|
|
432
|
+
extra='forbid',
|
|
433
|
+
)
|
|
434
|
+
version: Literal['1.0.0'] = '1.0.0'
|
|
435
|
+
env: Env = Field({}, validate_default=True)
|
|
436
|
+
providerBaseUrlEnv: ProviderBaseUrlEnv = Field({}, validate_default=True)
|
|
437
|
+
paths: Paths = Field({}, validate_default=True)
|
|
438
|
+
images: Images = Field({}, validate_default=True)
|
|
439
|
+
ports: Ports = Field({}, validate_default=True)
|
|
440
|
+
sidecarPaths: SidecarPaths = Field({}, validate_default=True)
|
|
441
|
+
agentPaths: AgentPaths = Field({}, validate_default=True)
|
|
442
|
+
controlPlanePaths: ControlPlanePaths = Field({}, validate_default=True)
|
|
443
|
+
podPatch: PodPatch = Field({}, validate_default=True)
|
|
444
|
+
webhook: Webhook = Field({}, validate_default=True)
|
|
445
|
+
reasonCodes: list[str] = [
|
|
446
|
+
'stale',
|
|
447
|
+
'source_not_admitted',
|
|
448
|
+
'source_mismatch',
|
|
449
|
+
'no_evidence',
|
|
450
|
+
'not_wired',
|
|
451
|
+
'no_calls_observed',
|
|
452
|
+
'no_failover_observed',
|
|
453
|
+
'no_budget_evidence',
|
|
454
|
+
'no_approval_token_evidence',
|
|
455
|
+
'no_retrieval_spans',
|
|
456
|
+
'unrecognised_conventions',
|
|
457
|
+
'instrumentation_unavailable',
|
|
458
|
+
'declared_env_missing',
|
|
459
|
+
'provider_key_on_agent',
|
|
460
|
+
'response_cap_exceeded',
|
|
461
|
+
'temperature_above_max',
|
|
462
|
+
'undeclared_tool',
|
|
463
|
+
'undeclared_model',
|
|
464
|
+
'unpinned_model',
|
|
465
|
+
'self_declared',
|
|
466
|
+
'unpriced_model',
|
|
467
|
+
'undeclared_namespace',
|
|
468
|
+
]
|
|
469
|
+
severityWeights: SeverityWeights = Field({}, validate_default=True)
|
|
470
|
+
gradeBands: GradeBands = Field({}, validate_default=True)
|
|
471
|
+
coverageThreshold: Literal[60] = 60
|
|
472
|
+
ruleEvidence: dict[str, RuleEvidenceEntry] = Field(
|
|
473
|
+
{'MODEL-01': {'sources': [{'class': 'independent', 'collector': 'gateway-config', 'proves': 'configured', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}, {'class': 'independent', 'collector': 'gateway-traffic', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}]}, 'MODEL-02': {'sources': [{'class': 'independent', 'collector': 'gateway-traffic', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}, {'class': 'independent', 'collector': 'gateway-config', 'proves': 'configured', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'planned'}]}, 'MODEL-03': {'sources': [{'class': 'independent', 'collector': 'gateway-config', 'proves': 'enforced', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}]}, 'MODEL-04': {'sources': [{'class': 'independent', 'collector': 'gateway-config', 'proves': 'enforced', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'when': 'client retries', 'question': "Do the agent's own provider clients retry more than spec.model.fallback.maxRetries, or stack retries on the gateway's?"}], 'notProven': "That the gateway's attempts match `spec.model.fallback.maxRetries` at runtime beyond the rendered config."}, 'MODEL-05': {'sources': [{'class': 'independent', 'collector': 'gateway-traffic', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built', 'when': 'agw.ai.usage.cost.total'}], 'notProven': 'Requests with no token usage: not counted.'}, 'SEC-LLM-01': {'sources': [{'class': 'independent', 'collector': 'sidecar-probe', 'proves': 'effective', 'wiredBy': 'opt-in', 'modes': ['standalone', 'operator'], 'status': 'planned', 'when': 'opt-in'}, {'class': 'evidence-point', 'collector': 'sdk', 'point': 'guardrail', 'proves': 'ran-where-wired', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Does every path that sends user input to a model run the declared input guardrails first?'}]}, 'SEC-LLM-02': {'sources': [{'class': 'evidence-point', 'collector': 'sdk', 'point': 'guardrail', 'proves': 'ran-where-wired', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Does every path that returns model output run the declared output guardrails first?'}], 'notProven': 'Effective: a no-op output guardrail still fires.'}, 'SEC-LLM-03': {'sources': [{'class': 'declared', 'collector': 'manifest', 'proves': 'declared', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}]}, 'SEC-LLM-04': {'sources': [{'class': 'independent', 'collector': 'gateway-config', 'proves': 'enforced', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}, {'class': 'independent', 'collector': 'gateway-traffic', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'planned'}], 'notProven': 'Cost: MODEL-03 covers it.'}, 'SEC-LLM-05': {'sources': [{'class': 'independent', 'collector': 'gateway-traffic', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}, {'class': 'independent', 'collector': 'gateway-config', 'proves': 'configured', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'planned'}]}, 'SEC-LLM-06': {'sources': [], 'derivedFrom': ['MEM-01'], 'notProven': 'Same as MEM-01.'}, 'SEC-LLM-07': {'sources': [{'class': 'independent', 'collector': 'sidecar-probe', 'proves': 'configured', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built', 'when': 'HTTP MCP'}, {'class': 'evidence-point', 'collector': 'sdk', 'point': 'mcpClient', 'proves': 'ran-where-wired', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned', 'when': 'stdio MCP'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Does the agent call any MCP tool the manifest does not declare, or one that serves no annotations?'}, {'class': 'declared', 'collector': 'manifest', 'proves': 'declared', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built', 'when': 'local tools'}]}, 'SEC-LLM-08': {'sources': [{'class': 'independent', 'collector': 'sidecar-probe', 'proves': 'configured', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'independent', 'collector': 'gateway-traffic', 'proves': 'enforced', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'evidence-point', 'collector': 'sdk', 'point': 'mcpClient', 'proves': 'ran-where-wired', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned', 'when': 'stdio MCP'}], 'notProven': 'Which tools are destructive: the server declares it; nothing checks the claim.'}, 'SEC-LLM-09': {'sources': [], 'derivedFrom': ['EVAL-01', 'EVAL-02']}, 'SEC-LLM-10': {'sources': [{'class': 'independent', 'collector': 'operator-webhook', 'proves': 'configured', 'wiredBy': 'none', 'modes': ['operator'], 'status': 'planned'}, {'class': 'declared', 'collector': 'manifest', 'proves': 'declared', 'wiredBy': 'none', 'modes': ['standalone'], 'status': 'built'}]}, 'TOOL-01': {'sources': [{'class': 'independent', 'collector': 'gateway-traffic', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built', 'when': 'HTTP MCP'}, {'class': 'evidence-point', 'collector': 'sdk', 'point': 'tool', 'proves': 'ran-where-wired', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned', 'when': 'local tools'}, {'class': 'evidence-point', 'collector': 'sdk', 'point': 'mcpClient', 'proves': 'ran-where-wired', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned', 'when': 'stdio MCP'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Which tools does the agent code register or call, local, HTTP MCP and stdio MCP?'}], 'notProven': 'Unwrapped local or stdio calls at runtime: only the lock inventory catches them.'}, 'MEM-01': {'sources': [{'class': 'evidence-point', 'collector': 'sdk', 'point': 'memoryWrite', 'proves': 'enforced', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Does every memory write pass through the PII scrubber for the declared fields?'}], 'notProven': 'Full coverage: the scrubber is a regex baseline (Presidio optional in Python). Writes that bypass the evidence point at runtime.'}, 'MEM-02': {'sources': [{'class': 'evidence-point', 'collector': 'sdk', 'point': 'memoryWrite', 'proves': 'enforced', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Does every memory write apply the declared retention TTL?'}], 'notProven': 'Writes that bypass the evidence point at runtime. Backends that cannot apply a TTL (record `ttl: unsupported`): the evidence point is `not_verifiable` there and only the lock remains.'}, 'MEM-03': {'sources': [{'class': 'evidence-point', 'collector': 'sdk', 'point': 'memoryWrite', 'proves': 'enforced', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Does every memory write honour the declared memory audit setting?'}], 'notProven': 'Writes that bypass the evidence point at runtime.'}, 'MEM-04': {'sources': [{'class': 'evidence-point', 'collector': 'sdk', 'point': 'vectorStore', 'proves': 'ran-where-wired', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Does every vector store query and write use the declared namespace or tenant isolation?'}], 'notProven': 'Isolation: the right namespace does not prove other tenants cannot read it.'}, 'MEM-05': {'sources': [{'class': 'independent', 'collector': 'gateway-traffic', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built', 'when': 'gen_ai.usage.output_tokens'}, {'class': 'declared', 'collector': 'manifest', 'proves': 'declared', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built', 'when': 'until a call is observed'}], 'notProven': 'The tolerance for the system prompt and tool schemas is set in Phase 2, with an ADR-0015 amendment; a call without gen_ai.usage.output_tokens leaves the check not_verifiable.'}, 'EVAL-01': {'sources': [{'class': 'independent', 'collector': 'sidecar-eval', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'planned'}]}, 'EVAL-02': {'sources': [{'class': 'independent', 'collector': 'sidecar-eval', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': "Does the agent's CI run the declared evaluation gate before deploy?"}], 'notProven': 'That a failed gate actually blocks a deploy: CI is outside the system.'}, 'EVAL-03': {'sources': [{'class': 'independent', 'collector': 'sidecar-eval', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'planned'}]}, 'OBS-01': {'sources': [{'class': 'independent', 'collector': 'sidecar-forwarder', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}, {'class': 'independent', 'collector': 'sidecar-probe', 'proves': 'configured', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}], 'notProven': 'That the agent exports every span: the rule is about the backend, not span coverage. agentops is not a target: it has no OTLP ingest.'}, 'OBS-02': {'sources': [{'class': 'independent', 'collector': 'operator-logs', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['operator'], 'status': 'planned'}, {'class': 'evidence-point', 'collector': 'sdk', 'point': 'logging', 'proves': 'ran-where-wired', 'wiredBy': 'agent-code', 'modes': ['standalone', 'operator'], 'status': 'planned'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Does every log statement emit structured JSON?'}]}, 'OBS-03': {'sources': [{'class': 'independent', 'collector': 'operator-logs', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['operator'], 'status': 'planned'}, {'class': 'offline', 'collector': 'lock', 'proves': 'every-path', 'wiredBy': 'user-schedule', 'modes': ['standalone', 'operator'], 'status': 'planned', 'question': 'Does any log statement write one of the declared sensitive fields?'}], 'notProven': 'Full coverage: the scanner is a regex and pattern baseline, so recall is limited.'}, 'META-01': {'sources': [{'class': 'declared', 'collector': 'manifest', 'proves': 'declared', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built'}]}, 'META-02': {'sources': [{'class': 'independent', 'collector': 'gateway-traffic', 'proves': 'observed', 'wiredBy': 'none', 'modes': ['standalone', 'operator'], 'status': 'built', 'when': 'gen_ai.request.temperature'}], 'notProven': 'Requests that set no temperature: `not_verifiable`, not counted.'}},
|
|
474
|
+
validate_default=True,
|
|
475
|
+
)
|
|
476
|
+
evidencePoints: dict[str, dict[str, str]] = {
|
|
477
|
+
'guardrail': {'input': 'SEC-LLM-01', 'output': 'SEC-LLM-02'},
|
|
478
|
+
'tool': {'local': 'TOOL-01'},
|
|
479
|
+
'mcpClient': {'tools/list': 'SEC-LLM-07', 'tools/call': 'TOOL-01'},
|
|
480
|
+
'memoryWrite': {'scrub': 'MEM-01', 'ttl': 'MEM-02', 'audit': 'MEM-03'},
|
|
481
|
+
'vectorStore': {'namespace': 'MEM-04'},
|
|
482
|
+
'logging': {'json': 'OBS-02'},
|
|
483
|
+
}
|
|
484
|
+
evidencePointRecordLimit: Literal[5] = 5
|
|
485
|
+
heartbeatMaxBytes: Literal[65536] = 65536
|
|
486
|
+
otlp: Otlp = Field({}, validate_default=True)
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
class EvidenceRecord(RootModel[EvidenceRecordPass | EvidenceRecordNotPass]):
|
|
490
|
+
root: EvidenceRecordPass | EvidenceRecordNotPass
|
|
491
|
+
|
|
492
|
+
|
|
493
|
+
class SidecarPush(BaseModel):
|
|
494
|
+
model_config = ConfigDict(
|
|
495
|
+
extra='forbid',
|
|
496
|
+
)
|
|
497
|
+
manifestSha256: Sha256
|
|
498
|
+
declared: dict[str, Any] | None = None
|
|
499
|
+
records: list[EvidenceRecord] = Field([], validate_default=True)
|
|
500
|
+
|
|
501
|
+
|
|
502
|
+
class EvidencePointAggregate(BaseModel):
|
|
503
|
+
model_config = ConfigDict(
|
|
504
|
+
extra='forbid',
|
|
505
|
+
)
|
|
506
|
+
point: Point
|
|
507
|
+
target: constr(min_length=1)
|
|
508
|
+
state: State
|
|
509
|
+
counts: Counts
|
|
510
|
+
records: list[EvidenceRecord] = Field(..., max_length=5)
|
|
511
|
+
|
|
512
|
+
|
|
513
|
+
class Heartbeat(BaseModel):
|
|
514
|
+
model_config = ConfigDict(
|
|
515
|
+
extra='forbid',
|
|
516
|
+
)
|
|
517
|
+
contract: constr(pattern=r'^\d+\.\d+\.\d+$') | None = None
|
|
518
|
+
health: dict[str, Any]
|
|
519
|
+
records: list[EvidenceRecord] = Field([], validate_default=True)
|
|
520
|
+
evidencePoints: list[EvidencePointAggregate] = Field([], validate_default=True)
|
|
521
|
+
usage: dict[str, Any] | None = None
|
|
522
|
+
tools: dict[str, Any] | None = None
|