agent-control-models 7.3.0__tar.gz → 7.3.2__tar.gz

{agent_control_models-7.3.0 → agent_control_models-7.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-control-models
-Version: 7.3.0
+Version: 7.3.2
 Summary: Shared data models for Agent Control server and SDK
 Author: Agent Control Team
 License: Apache-2.0

{agent_control_models-7.3.0 → agent_control_models-7.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-control-models"
-version = "7.3.0"
+version = "7.3.2"
 description = "Shared data models for Agent Control server and SDK"
 requires-python = ">=3.12"
 dependencies = [

{agent_control_models-7.3.0 → agent_control_models-7.3.2}/src/agent_control_models/__init__.py

@@ -7,6 +7,12 @@ try:
 except PackageNotFoundError:
     __version__ = "0.0.0.dev"
 
+from .actions import (
+    ActionDecision,
+    expand_action_filter,
+    normalize_action,
+    normalize_action_list,
+)
 from .agent import (
     BUILTIN_STEP_TYPES,
     STEP_TYPE_LLM,
@@ -91,6 +97,7 @@ __all__ = [
     "STEP_TYPE_TOOL",
     "STEP_TYPE_LLM",
     "BUILTIN_STEP_TYPES",
+    "ActionDecision",
     # Policy
     "Policy",
     # Evaluation
@@ -107,6 +114,9 @@ __all__ = [
     "EvaluatorSpec",
     "EvaluatorResult",
     "SteeringContext",
+    "normalize_action",
+    "normalize_action_list",
+    "expand_action_filter",
     # Error models
     "ProblemDetail",
     "ErrorCode",

agent_control_models-7.3.2/src/agent_control_models/actions.py

@@ -0,0 +1,53 @@
+"""Shared control-action types and normalization helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal, cast
+
+type ActionDecision = Literal["deny", "steer", "observe"]
+
+_OBSERVE_ACTION_ALIASES = frozenset({"allow", "observe", "warn", "log"})
+_ACTION_QUERY_EXPANSION: dict[ActionDecision, tuple[str, ...]] = {
+    "deny": ("deny",),
+    "steer": ("steer",),
+    "observe": ("observe", "allow", "warn", "log"),
+}
+
+
+def normalize_action(action: str) -> ActionDecision:
+    """Normalize a public or legacy action name to the canonical action."""
+    if action in _OBSERVE_ACTION_ALIASES:
+        return "observe"
+    if action in ("deny", "steer"):
+        return cast(ActionDecision, action)
+    raise ValueError(
+        "Invalid action. Expected one of: deny, steer, observe "
+        "(legacy aliases allow/warn/log are also accepted temporarily)."
+    )
+
+
+def normalize_action_list(actions: Sequence[str]) -> list[ActionDecision]:
+    """Normalize a list of actions while preserving order and removing duplicates."""
+    normalized: list[ActionDecision] = []
+    seen: set[ActionDecision] = set()
+    for action in actions:
+        canonical = normalize_action(action)
+        if canonical in seen:
+            continue
+        seen.add(canonical)
+        normalized.append(canonical)
+    return normalized
+
+
+def expand_action_filter(actions: Sequence[ActionDecision]) -> list[str]:
+    """Expand canonical action filters to include legacy stored event values."""
+    expanded: list[str] = []
+    seen: set[str] = set()
+    for action in actions:
+        for candidate in _ACTION_QUERY_EXPANSION[action]:
+            if candidate in seen:
+                continue
+            seen.add(candidate)
+            expanded.append(candidate)
+    return expanded

{agent_control_models-7.3.0 → agent_control_models-7.3.2}/src/agent_control_models/controls.py

@@ -10,6 +10,7 @@ from uuid import uuid4
 import re2
 from pydantic import ConfigDict, Field, ValidationInfo, field_validator, model_validator
 
+from .actions import ActionDecision, normalize_action
 from .base import BaseModel
 
 
@@ -265,7 +266,7 @@ class SteeringContext(BaseModel):
 class ControlAction(BaseModel):
     """What to do when control matches."""
 
-    decision: Literal["allow", "deny", "steer", "warn", "log"] = Field(
+    decision: ActionDecision = Field(
         ..., description="Action to take when control is triggered"
     )
     steering_context: SteeringContext | None = Field(
@@ -277,6 +278,11 @@ class ControlAction(BaseModel):
         )
     )
 
+    @field_validator("decision", mode="before")
+    @classmethod
+    def normalize_decision(cls, value: str) -> ActionDecision:
+        return normalize_action(value)
+
 
 MAX_CONDITION_DEPTH = 6
 
@@ -649,7 +655,7 @@ class ControlMatch(BaseModel):
     )
     control_id: int = Field(..., description="Database ID of the control")
     control_name: str = Field(..., description="Name of the control")
-    action: Literal["allow", "deny", "steer", "warn", "log"] = Field(
+    action: ActionDecision = Field(
         ..., description="Action configured for this control"
     )
     result: EvaluatorResult = Field(
@@ -659,3 +665,8 @@ class ControlMatch(BaseModel):
         None,
         description="Steering context for steer actions if configured"
     )
+
+    @field_validator("action", mode="before")
+    @classmethod
+    def normalize_action_value(cls, value: str) -> ActionDecision:
+        return normalize_action(value)

{agent_control_models-7.3.0 → agent_control_models-7.3.2}/src/agent_control_models/observability.py

@@ -14,6 +14,7 @@ from uuid import uuid4
 
 from pydantic import Field, field_validator
 
+from .actions import ActionDecision, normalize_action, normalize_action_list
 from .agent import AGENT_NAME_MIN_LENGTH, AGENT_NAME_PATTERN, normalize_agent_name
 from .base import BaseModel
 
@@ -42,7 +43,7 @@ class ControlExecutionEvent(BaseModel):
         control_name: Name of the control (denormalized for queries)
         check_stage: "pre" (before execution) or "post" (after execution)
         applies_to: "llm_call" or "tool_call"
-        action: The action taken (allow, deny, warn, log)
+        action: The action taken (deny, steer, observe)
         matched: Whether the control evaluator matched
         confidence: Confidence score from the evaluator (0.0-1.0)
         timestamp: When the control was executed (UTC)
@@ -90,7 +91,7 @@ class ControlExecutionEvent(BaseModel):
     )
 
     # Result
-    action: Literal["allow", "deny", "steer", "warn", "log"] = Field(
+    action: ActionDecision = Field(
         ..., description="Action taken by the control"
     )
     matched: bool = Field(
@@ -160,6 +161,11 @@ class ControlExecutionEvent(BaseModel):
     def validate_and_normalize_agent_name(cls, value: str) -> str:
         return normalize_agent_name(str(value))
 
+    @field_validator("action", mode="before")
+    @classmethod
+    def normalize_event_action(cls, value: str) -> ActionDecision:
+        return normalize_action(value)
+
     model_config = {
         "json_schema_extra": {
             "examples": [
@@ -265,7 +271,7 @@ class EventQueryRequest(BaseModel):
         control_execution_id: Filter by specific event ID
         agent_name: Filter by agent identifier
         control_ids: Filter by control IDs
-        actions: Filter by actions (allow, deny, steer, warn, log)
+        actions: Filter by actions (deny, steer, observe)
         matched: Filter by matched status
         check_stages: Filter by check stages (pre, post)
         applies_to: Filter by call type (llm_call, tool_call)
@@ -293,7 +299,7 @@ class EventQueryRequest(BaseModel):
     control_ids: list[int] | None = Field(
         default=None, description="Filter by control IDs"
     )
-    actions: list[Literal["allow", "deny", "steer", "warn", "log"]] | None = Field(
+    actions: list[ActionDecision] | None = Field(
         default=None, description="Filter by actions"
     )
     matched: bool | None = Field(default=None, description="Filter by matched status")
@@ -318,7 +324,7 @@ class EventQueryRequest(BaseModel):
                 {"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"},
                 {
                     "agent_name": "my-agent",
-                    "actions": ["deny", "warn"],
+                    "actions": ["deny", "observe"],
                     "start_time": "2025-01-09T00:00:00Z",
                     "limit": 50,
                 },
@@ -335,6 +341,15 @@ class EventQueryRequest(BaseModel):
             return None
         return normalize_agent_name(str(value))
 
+    @field_validator("actions", mode="before")
+    @classmethod
+    def normalize_actions_filter(
+        cls, value: list[str] | None
+    ) -> list[ActionDecision] | None:
+        if value is None:
+            return None
+        return normalize_action_list(value)
+
 
 class EventQueryResponse(BaseModel):
     """
@@ -368,14 +383,15 @@ class ControlStats(BaseModel):
         execution_count: Total number of executions
         match_count: Number of times the control matched
         non_match_count: Number of times the control did not match
-        allow_count: Number of allow actions
         deny_count: Number of deny actions
         steer_count: Number of steer actions
-        warn_count: Number of warn actions
-        log_count: Number of log actions
+        observe_count: Number of observe actions
         error_count: Number of errors during evaluation
         avg_confidence: Average confidence score
         avg_duration_ms: Average execution duration in milliseconds
+
+    Invariant:
+        deny_count + steer_count + observe_count == match_count
     """
 
     control_id: int = Field(..., description="Control ID")
@@ -383,11 +399,9 @@ class ControlStats(BaseModel):
     execution_count: int = Field(..., ge=0, description="Total executions")
     match_count: int = Field(..., ge=0, description="Total matches")
     non_match_count: int = Field(..., ge=0, description="Total non-matches")
-    allow_count: int = Field(..., ge=0, description="Allow actions")
     deny_count: int = Field(..., ge=0, description="Deny actions")
     steer_count: int = Field(..., ge=0, description="Steer actions")
-    warn_count: int = Field(..., ge=0, description="Warn actions")
-    log_count: int = Field(..., ge=0, description="Log actions")
+    observe_count: int = Field(..., ge=0, description="Observe actions")
     error_count: int = Field(..., ge=0, description="Evaluation errors")
     avg_confidence: float = Field(..., ge=0.0, le=1.0, description="Average confidence")
     avg_duration_ms: float | None = Field(
@@ -460,7 +474,7 @@ class TimeseriesBucket(BaseModel):
     error_count: int = Field(..., ge=0, description="Errors in bucket")
     action_counts: dict[str, int] = Field(
         default_factory=dict,
-        description="Action breakdown: {allow, deny, steer, warn, log}",
+        description="Action breakdown: {deny, steer, observe}",
     )
     avg_confidence: float | None = Field(
         default=None, ge=0.0, le=1.0, description="Average confidence score"
@@ -476,7 +490,7 @@ class StatsTotals(BaseModel):
 
     Invariant: execution_count = match_count + non_match_count + error_count
 
-    Matches have actions (allow, deny, steer, warn, log) tracked in action_counts.
+    Matches have actions (deny, steer, observe) tracked in action_counts.
     sum(action_counts.values()) == match_count
 
     Attributes:
@@ -494,7 +508,7 @@ class StatsTotals(BaseModel):
     error_count: int = Field(default=0, ge=0, description="Total errors")
     action_counts: dict[str, int] = Field(
         default_factory=dict,
-        description="Action breakdown for matches: {allow, deny, steer, warn, log}",
+        description="Action breakdown for matches: {deny, steer, observe}",
     )
     timeseries: list[TimeseriesBucket] | None = Field(
         default=None,

agent_control_models-7.3.2/tests/test_actions.py

@@ -0,0 +1,60 @@
+"""Tests for shared control-action compatibility behavior."""
+
+from __future__ import annotations
+
+import pytest
+from agent_control_models import (
+    ControlAction,
+    ControlExecutionEvent,
+    ControlMatch,
+    EventQueryRequest,
+    EvaluatorResult,
+    expand_action_filter,
+)
+from pydantic import ValidationError
+
+
+def test_event_query_actions_normalize_and_expand_for_legacy_observability() -> None:
+    # Given: a query that mixes canonical and legacy advisory action names
+    query = EventQueryRequest(
+        actions=["warn", "observe", "deny", "log", "deny", "steer", "allow", "steer"]
+    )
+
+    # When: expanding the normalized public action filter for stored event rows
+    expanded = expand_action_filter(query.actions or [])
+
+    # Then: the public filter is canonicalized, deduped, and expanded for legacy rows
+    assert query.actions == ["observe", "deny", "steer"]
+    assert expanded == ["observe", "allow", "warn", "log", "deny", "steer"]
+
+
+def test_invalid_action_is_rejected_across_public_model_boundaries() -> None:
+    # Given: the same invalid action at each public model boundary
+    invalid_action = "block"
+    invalid_builders = [
+        lambda: ControlAction.model_validate({"decision": invalid_action}),
+        lambda: ControlMatch(
+            control_id=123,
+            control_name="pii-check",
+            action=invalid_action,
+            result=EvaluatorResult(matched=True, confidence=0.9),
+        ),
+        lambda: ControlExecutionEvent(
+            trace_id="trace-123",
+            span_id="span-123",
+            agent_name="test-agent",
+            control_id=123,
+            control_name="pii-check",
+            check_stage="pre",
+            applies_to="llm_call",
+            action=invalid_action,
+            matched=True,
+            confidence=0.9,
+        ),
+        lambda: EventQueryRequest(actions=[invalid_action]),
+    ]
+
+    for build_invalid_model in invalid_builders:
+        # When / Then: validation fails before the invalid action can enter the system
+        with pytest.raises(ValidationError, match="Invalid action"):
+            build_invalid_model()