agent-control-models 7.4.0__tar.gz → 7.4.1__tar.gz

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.
Files changed (20) hide show
  1. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/PKG-INFO +1 -1
  2. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/pyproject.toml +1 -1
  3. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/__init__.py +4 -0
  4. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/actions.py +33 -3
  5. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/controls.py +3 -3
  6. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/observability.py +7 -3
  7. agent_control_models-7.4.1/tests/test_actions.py +250 -0
  8. agent_control_models-7.4.0/tests/test_actions.py +0 -60
  9. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/.gitignore +0 -0
  10. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/README.md +0 -0
  11. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/agent.py +0 -0
  12. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/base.py +0 -0
  13. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/errors.py +0 -0
  14. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/evaluation.py +0 -0
  15. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/health.py +0 -0
  16. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/policy.py +0 -0
  17. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/py.typed +0 -0
  18. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/src/agent_control_models/server.py +0 -0
  19. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/tests/test_control_templates.py +0 -0
  20. {agent_control_models-7.4.0 → agent_control_models-7.4.1}/tests/test_controls.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agent-control-models
3
- Version: 7.4.0
3
+ Version: 7.4.1
4
4
  Summary: Shared data models for Agent Control server and SDK
5
5
  Author: Agent Control Team
6
6
  License: Apache-2.0
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "agent-control-models"
3
- version = "7.4.0"
3
+ version = "7.4.1"
4
4
  description = "Shared data models for Agent Control server and SDK"
5
5
  requires-python = ">=3.12"
6
6
  dependencies = [
@@ -12,6 +12,8 @@ from .actions import (
12
12
  expand_action_filter,
13
13
  normalize_action,
14
14
  normalize_action_list,
15
+ validate_action,
16
+ validate_action_list,
15
17
  )
16
18
  from .agent import (
17
19
  BUILTIN_STEP_TYPES,
@@ -144,6 +146,8 @@ __all__ = [
144
146
  "UnrenderedTemplateControl",
145
147
  "normalize_action",
146
148
  "normalize_action_list",
149
+ "validate_action",
150
+ "validate_action_list",
147
151
  "expand_action_filter",
148
152
  # Error models
149
153
  "ProblemDetail",
@@ -7,6 +7,7 @@ from typing import Literal, cast
7
7
 
8
8
  type ActionDecision = Literal["deny", "steer", "observe"]
9
9
 
10
+ _CANONICAL_ACTIONS = frozenset({"deny", "steer", "observe"})
10
11
  _OBSERVE_ACTION_ALIASES = frozenset({"allow", "observe", "warn", "log"})
11
12
  _ACTION_QUERY_EXPANSION: dict[ActionDecision, tuple[str, ...]] = {
12
13
  "deny": ("deny",),
@@ -15,15 +16,44 @@ _ACTION_QUERY_EXPANSION: dict[ActionDecision, tuple[str, ...]] = {
15
16
  }
16
17
 
17
18
 
19
+ def validate_action(action: str) -> ActionDecision:
20
+ """Validate that *action* is one of the canonical action values.
21
+
22
+ Use this on public API boundaries (control create/update, query filters)
23
+ where legacy values should be rejected.
24
+ """
25
+ if action in _CANONICAL_ACTIONS:
26
+ return cast(ActionDecision, action)
27
+ raise ValueError(
28
+ f"Invalid action {action!r}. Must be one of: deny, steer, observe."
29
+ )
30
+
31
+
32
+ def validate_action_list(actions: Sequence[str]) -> list[ActionDecision]:
33
+ """Validate a list of actions, preserving order and removing duplicates."""
34
+ validated: list[ActionDecision] = []
35
+ seen: set[ActionDecision] = set()
36
+ for action in actions:
37
+ canonical = validate_action(action)
38
+ if canonical in seen:
39
+ continue
40
+ seen.add(canonical)
41
+ validated.append(canonical)
42
+ return validated
43
+
44
+
18
45
  def normalize_action(action: str) -> ActionDecision:
19
- """Normalize a public or legacy action name to the canonical action."""
46
+ """Normalize a stored or legacy action name to the canonical action.
47
+
48
+ Use this on internal read paths (deserializing DB rows, server responses)
49
+ where historical data may contain legacy values.
50
+ """
20
51
  if action in _OBSERVE_ACTION_ALIASES:
21
52
  return "observe"
22
53
  if action in ("deny", "steer"):
23
54
  return cast(ActionDecision, action)
24
55
  raise ValueError(
25
- "Invalid action. Expected one of: deny, steer, observe "
26
- "(legacy aliases allow/warn/log are also accepted temporarily)."
56
+ f"Invalid action {action!r}. Expected one of: deny, steer, observe."
27
57
  )
28
58
 
29
59
 
@@ -11,7 +11,7 @@ from uuid import uuid4
11
11
  import re2
12
12
  from pydantic import ConfigDict, Field, ValidationInfo, field_validator, model_validator
13
13
 
14
- from .actions import ActionDecision, normalize_action
14
+ from .actions import ActionDecision, normalize_action, validate_action
15
15
  from .agent import JSONValue
16
16
  from .base import BaseModel
17
17
 
@@ -520,8 +520,8 @@ class ControlAction(BaseModel):
520
520
 
521
521
  @field_validator("decision", mode="before")
522
522
  @classmethod
523
- def normalize_decision(cls, value: str) -> ActionDecision:
524
- return normalize_action(value)
523
+ def validate_decision(cls, value: str) -> ActionDecision:
524
+ return validate_action(value)
525
525
 
526
526
 
527
527
  MAX_CONDITION_DEPTH = 6
@@ -14,7 +14,11 @@ from uuid import uuid4
14
14
 
15
15
  from pydantic import Field, field_validator
16
16
 
17
- from .actions import ActionDecision, normalize_action, normalize_action_list
17
+ from .actions import (
18
+ ActionDecision,
19
+ normalize_action,
20
+ validate_action_list,
21
+ )
18
22
  from .agent import AGENT_NAME_MIN_LENGTH, AGENT_NAME_PATTERN, normalize_agent_name
19
23
  from .base import BaseModel
20
24
 
@@ -343,12 +347,12 @@ class EventQueryRequest(BaseModel):
343
347
 
344
348
  @field_validator("actions", mode="before")
345
349
  @classmethod
346
- def normalize_actions_filter(
350
+ def validate_actions_filter(
347
351
  cls, value: list[str] | None
348
352
  ) -> list[ActionDecision] | None:
349
353
  if value is None:
350
354
  return None
351
- return normalize_action_list(value)
355
+ return validate_action_list(value)
352
356
 
353
357
 
354
358
  class EventQueryResponse(BaseModel):
@@ -0,0 +1,250 @@
1
+ """Tests for shared control-action types, validation, and normalization."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import pytest
6
+ from agent_control_models import (
7
+ ControlAction,
8
+ ControlExecutionEvent,
9
+ ControlMatch,
10
+ EventQueryRequest,
11
+ EvaluatorResult,
12
+ expand_action_filter,
13
+ )
14
+ from agent_control_models.actions import normalize_action, validate_action
15
+ from pydantic import ValidationError
16
+
17
+
18
+ # ---------------------------------------------------------------------------
19
+ # validate_action (strict, for API boundaries)
20
+ # ---------------------------------------------------------------------------
21
+
22
+
23
+ class TestValidateAction:
24
+ """Tests for the strict validate_action used on public API boundaries."""
25
+
26
+ @pytest.mark.parametrize("action", ["deny", "steer", "observe"])
27
+ def test_accepts_canonical_actions(self, action: str) -> None:
28
+ # Given: a canonical action name
29
+ # When: validating the action
30
+ result = validate_action(action)
31
+
32
+ # Then: the same canonical value is returned
33
+ assert result == action
34
+
35
+ @pytest.mark.parametrize("legacy", ["allow", "warn", "log"])
36
+ def test_rejects_legacy_actions(self, legacy: str) -> None:
37
+ # Given: a legacy action name that is no longer accepted at API boundaries
38
+ # When / Then: validation raises ValueError
39
+ with pytest.raises(ValueError, match="Invalid action"):
40
+ validate_action(legacy)
41
+
42
+ def test_rejects_unknown_action(self) -> None:
43
+ # Given: a completely unknown action name
44
+ # When / Then: validation raises ValueError
45
+ with pytest.raises(ValueError, match="Invalid action"):
46
+ validate_action("block")
47
+
48
+
49
+ # ---------------------------------------------------------------------------
50
+ # normalize_action (lenient, for internal read paths)
51
+ # ---------------------------------------------------------------------------
52
+
53
+
54
+ class TestNormalizeAction:
55
+ """Tests for the lenient normalize_action used on read paths."""
56
+
57
+ @pytest.mark.parametrize("action", ["deny", "steer", "observe"])
58
+ def test_passes_canonical_actions(self, action: str) -> None:
59
+ # Given: a canonical action name
60
+ # When: normalizing
61
+ result = normalize_action(action)
62
+
63
+ # Then: the same value is returned unchanged
64
+ assert result == action
65
+
66
+ @pytest.mark.parametrize("legacy", ["allow", "warn", "log"])
67
+ def test_normalizes_legacy_to_observe(self, legacy: str) -> None:
68
+ # Given: a legacy advisory action stored in a historical DB row
69
+ # When: normalizing on the read path
70
+ result = normalize_action(legacy)
71
+
72
+ # Then: it maps to the canonical "observe" action
73
+ assert result == "observe"
74
+
75
+ def test_rejects_unknown_action(self) -> None:
76
+ # Given: a completely unknown action name
77
+ # When / Then: normalization raises ValueError even on the lenient path
78
+ with pytest.raises(ValueError, match="Invalid action"):
79
+ normalize_action("block")
80
+
81
+
82
+ # ---------------------------------------------------------------------------
83
+ # ControlAction (API input boundary — strict)
84
+ # ---------------------------------------------------------------------------
85
+
86
+
87
+ class TestControlActionValidation:
88
+ """ControlAction.decision uses strict validation (rejects legacy values)."""
89
+
90
+ @pytest.mark.parametrize("action", ["deny", "steer", "observe"])
91
+ def test_accepts_canonical_actions(self, action: str) -> None:
92
+ # Given: a control action payload with a canonical decision
93
+ # When: validating via Pydantic
94
+ ca = ControlAction.model_validate({"decision": action})
95
+
96
+ # Then: the decision is accepted as-is
97
+ assert ca.decision == action
98
+
99
+ @pytest.mark.parametrize("legacy", ["allow", "warn", "log"])
100
+ def test_rejects_legacy_actions(self, legacy: str) -> None:
101
+ # Given: a control action payload using a legacy decision value
102
+ # When / Then: Pydantic validation rejects it at the API boundary
103
+ with pytest.raises(ValidationError, match="Invalid action"):
104
+ ControlAction.model_validate({"decision": legacy})
105
+
106
+ def test_rejects_unknown_action(self) -> None:
107
+ # Given: a control action payload with an unknown decision
108
+ # When / Then: Pydantic validation rejects it
109
+ with pytest.raises(ValidationError, match="Invalid action"):
110
+ ControlAction.model_validate({"decision": "block"})
111
+
112
+
113
+ # ---------------------------------------------------------------------------
114
+ # EventQueryRequest.actions (API input boundary — strict)
115
+ # ---------------------------------------------------------------------------
116
+
117
+
118
+ class TestEventQueryRequestValidation:
119
+ """EventQueryRequest.actions uses strict validation."""
120
+
121
+ def test_accepts_canonical_actions(self) -> None:
122
+ # Given: a query filter with all three canonical action values
123
+ # When: constructing the query request
124
+ query = EventQueryRequest(actions=["deny", "steer", "observe"])
125
+
126
+ # Then: all actions are accepted
127
+ assert query.actions == ["deny", "steer", "observe"]
128
+
129
+ def test_deduplicates_actions(self) -> None:
130
+ # Given: a query filter with duplicate action values
131
+ # When: constructing the query request
132
+ query = EventQueryRequest(actions=["deny", "deny", "observe"])
133
+
134
+ # Then: duplicates are removed while preserving order
135
+ assert query.actions == ["deny", "observe"]
136
+
137
+ @pytest.mark.parametrize("legacy", ["allow", "warn", "log"])
138
+ def test_rejects_legacy_actions(self, legacy: str) -> None:
139
+ # Given: a query filter using a legacy action value
140
+ # When / Then: Pydantic validation rejects it at the API boundary
141
+ with pytest.raises(ValidationError, match="Invalid action"):
142
+ EventQueryRequest(actions=[legacy])
143
+
144
+ def test_rejects_unknown_action(self) -> None:
145
+ # Given: a query filter with an unknown action
146
+ # When / Then: Pydantic validation rejects it
147
+ with pytest.raises(ValidationError, match="Invalid action"):
148
+ EventQueryRequest(actions=["block"])
149
+
150
+
151
+ # ---------------------------------------------------------------------------
152
+ # ControlMatch / ControlExecutionEvent (read path — lenient normalization)
153
+ # ---------------------------------------------------------------------------
154
+
155
+
156
+ class TestReadPathNormalization:
157
+ """Internal read-path models normalize legacy values from DB rows."""
158
+
159
+ @pytest.mark.parametrize("legacy,expected", [
160
+ ("allow", "observe"),
161
+ ("warn", "observe"),
162
+ ("log", "observe"),
163
+ ("observe", "observe"),
164
+ ("deny", "deny"),
165
+ ("steer", "steer"),
166
+ ])
167
+ def test_control_match_normalizes_legacy(self, legacy: str, expected: str) -> None:
168
+ # Given: a ControlMatch deserialized from a DB row with a legacy action
169
+ # When: constructing the model
170
+ match = ControlMatch(
171
+ control_id=1,
172
+ control_name="test",
173
+ action=legacy,
174
+ result=EvaluatorResult(matched=True, confidence=0.9),
175
+ )
176
+
177
+ # Then: the action is normalized to the canonical value
178
+ assert match.action == expected
179
+
180
+ @pytest.mark.parametrize("legacy,expected", [
181
+ ("allow", "observe"),
182
+ ("warn", "observe"),
183
+ ("log", "observe"),
184
+ ("observe", "observe"),
185
+ ("deny", "deny"),
186
+ ("steer", "steer"),
187
+ ])
188
+ def test_control_execution_event_normalizes_legacy(
189
+ self, legacy: str, expected: str
190
+ ) -> None:
191
+ # Given: a ControlExecutionEvent deserialized from a historical event row
192
+ # When: constructing the model
193
+ event = ControlExecutionEvent(
194
+ trace_id="4bf92f3577b34da6a3ce929d0e0e4736",
195
+ span_id="00f067aa0ba902b7",
196
+ agent_name="test-agent",
197
+ control_id=1,
198
+ control_name="test",
199
+ check_stage="pre",
200
+ applies_to="llm_call",
201
+ action=legacy,
202
+ matched=True,
203
+ confidence=0.9,
204
+ )
205
+
206
+ # Then: the action is normalized to the canonical value
207
+ assert event.action == expected
208
+
209
+ def test_control_match_rejects_unknown(self) -> None:
210
+ # Given: a ControlMatch with a completely unknown action
211
+ # When / Then: validation rejects it even on the lenient read path
212
+ with pytest.raises(ValidationError, match="Invalid action"):
213
+ ControlMatch(
214
+ control_id=1,
215
+ control_name="test",
216
+ action="block",
217
+ result=EvaluatorResult(matched=True, confidence=0.9),
218
+ )
219
+
220
+
221
+ # ---------------------------------------------------------------------------
222
+ # expand_action_filter (internal query expansion)
223
+ # ---------------------------------------------------------------------------
224
+
225
+
226
+ class TestExpandActionFilter:
227
+ """expand_action_filter expands canonical actions for SQL queries against historical data."""
228
+
229
+ def test_observe_expands_to_include_legacy(self) -> None:
230
+ # Given: a canonical "observe" filter
231
+ # When: expanding for SQL WHERE clause against historical events
232
+ expanded = expand_action_filter(["observe"])
233
+
234
+ # Then: it includes all legacy advisory action values stored in old rows
235
+ assert expanded == ["observe", "allow", "warn", "log"]
236
+
237
+ def test_deny_and_steer_do_not_expand(self) -> None:
238
+ # Given: deny and steer filters (no legacy aliases)
239
+ # When: expanding
240
+ # Then: they map only to themselves
241
+ assert expand_action_filter(["deny"]) == ["deny"]
242
+ assert expand_action_filter(["steer"]) == ["steer"]
243
+
244
+ def test_full_expansion(self) -> None:
245
+ # Given: all three canonical actions
246
+ # When: expanding
247
+ expanded = expand_action_filter(["deny", "steer", "observe"])
248
+
249
+ # Then: deny and steer are unchanged, observe expands to include legacy
250
+ assert expanded == ["deny", "steer", "observe", "allow", "warn", "log"]
@@ -1,60 +0,0 @@
1
- """Tests for shared control-action compatibility behavior."""
2
-
3
- from __future__ import annotations
4
-
5
- import pytest
6
- from agent_control_models import (
7
- ControlAction,
8
- ControlExecutionEvent,
9
- ControlMatch,
10
- EventQueryRequest,
11
- EvaluatorResult,
12
- expand_action_filter,
13
- )
14
- from pydantic import ValidationError
15
-
16
-
17
- def test_event_query_actions_normalize_and_expand_for_legacy_observability() -> None:
18
- # Given: a query that mixes canonical and legacy advisory action names
19
- query = EventQueryRequest(
20
- actions=["warn", "observe", "deny", "log", "deny", "steer", "allow", "steer"]
21
- )
22
-
23
- # When: expanding the normalized public action filter for stored event rows
24
- expanded = expand_action_filter(query.actions or [])
25
-
26
- # Then: the public filter is canonicalized, deduped, and expanded for legacy rows
27
- assert query.actions == ["observe", "deny", "steer"]
28
- assert expanded == ["observe", "allow", "warn", "log", "deny", "steer"]
29
-
30
-
31
- def test_invalid_action_is_rejected_across_public_model_boundaries() -> None:
32
- # Given: the same invalid action at each public model boundary
33
- invalid_action = "block"
34
- invalid_builders = [
35
- lambda: ControlAction.model_validate({"decision": invalid_action}),
36
- lambda: ControlMatch(
37
- control_id=123,
38
- control_name="pii-check",
39
- action=invalid_action,
40
- result=EvaluatorResult(matched=True, confidence=0.9),
41
- ),
42
- lambda: ControlExecutionEvent(
43
- trace_id="trace-123",
44
- span_id="span-123",
45
- agent_name="test-agent",
46
- control_id=123,
47
- control_name="pii-check",
48
- check_stage="pre",
49
- applies_to="llm_call",
50
- action=invalid_action,
51
- matched=True,
52
- confidence=0.9,
53
- ),
54
- lambda: EventQueryRequest(actions=[invalid_action]),
55
- ]
56
-
57
- for build_invalid_model in invalid_builders:
58
- # When / Then: validation fails before the invalid action can enter the system
59
- with pytest.raises(ValidationError, match="Invalid action"):
60
- build_invalid_model()