Set kw_only=True in all dataclasses (#758)

Make all public dataclasses keyword-only using `kw_only=True` to allow
flexible field ordering. This enables adding new fields or reordering
existing ones without breaking positional initialization. This is
important in terms of backwards compatibility of the SDK.

Author: mateusz834

splunklib/ai/engines/langchain.py

@@ -286,9 +286,13 @@ async def awrap_tool_call(
                     assert resp.artifact is None, "artifact is already populated"
 
                     if resp.name.startswith(AGENT_PREFIX):
-                        resp.artifact = SubagentFailureResult(str(resp.content))  # pyright: ignore[reportUnknownArgumentType]
+                        resp.artifact = SubagentFailureResult(
+                            error_message=str(resp.content)  # pyright: ignore[reportUnknownArgumentType]
+                        )
                     else:
-                        resp.artifact = ToolFailureResult(str(resp.content))  # pyright: ignore[reportUnknownArgumentType]
+                        resp.artifact = ToolFailureResult(
+                            error_message=str(resp.content)  # pyright: ignore[reportUnknownArgumentType]
+                        )
 
                 return resp
 
@@ -863,7 +867,9 @@ async def llm_handler(req: ModelRequest) -> ModelResponse:
                     case LC_StructuredOutputValidationError():
                         raise StructuredOutputGenerationException(
                             message=msg,
-                            error=StructuredOutputValidationError(str(e.source)),
+                            error=StructuredOutputValidationError(
+                                validation_error=str(e.source)
+                            ),
                         )
                     case LC_StructuredOutputError():
                         # Langchain only returns the above handled exceptions, LC_StructuredOutputError
@@ -1013,7 +1019,7 @@ async def _sdk_handler(request: ToolRequest) -> ToolResponse:
         assert isinstance(sdk_result, ToolMessage), (
             "Expected tool response from tool middleware handler"
         )
-        return ToolResponse(sdk_result.result)
+        return ToolResponse(result=sdk_result.result)
 
     return _sdk_handler
 
@@ -1033,7 +1039,7 @@ async def _sdk_handler(
         assert isinstance(sdk_result, SubagentMessage), (
             "Expected subagent response from subagent middleware handler"
         )
-        return SubagentResponse(sdk_result.result)
+        return SubagentResponse(result=sdk_result.result)
 
     return _sdk_handler
 
@@ -1276,10 +1282,10 @@ def _convert_model_result_from_lc(model_response: LC_ModelCallResult) -> ModelRe
 
         tool_strategy_messages = [
             StructuredOutputMessage(
-                m.tool_call_id,
-                m.name.removeprefix(TOOL_STRATEGY_TOOL_PREFIX) if m.name else "",
-                m.status,
-                str(m.content),  # pyright: ignore[reportUnknownArgumentType]
+                call_id=m.tool_call_id,
+                name=m.name.removeprefix(TOOL_STRATEGY_TOOL_PREFIX) if m.name else "",
+                status=m.status,
+                content=str(m.content),  # pyright: ignore[reportUnknownArgumentType]
             )
             for m in model_response.result
             if isinstance(m, LC_ToolMessage)
@@ -1404,7 +1410,9 @@ async def _tool_call(
                 "ToolException from LangChain should not be raised in tool.func"
             )
 
-        artifact = ToolResult(result.content, result.structured_content)
+        artifact = ToolResult(
+            content=result.content, structured_content=result.structured_content
+        )
 
         if result.structured_content:
             # For both local tools and remote tools (Splunk MCP Server App), the primary
@@ -1721,9 +1729,9 @@ def _map_message_from_langchain(message: LC_BaseMessage) -> BaseMessage:
                 ],
                 structured_output_calls=[
                     StructuredOutputCall(
-                        tc["id"] or "",
-                        tc["name"].removeprefix(TOOL_STRATEGY_TOOL_PREFIX),
-                        tc["args"],
+                        id=tc["id"] or "",
+                        name=tc["name"].removeprefix(TOOL_STRATEGY_TOOL_PREFIX),
+                        args=tc["args"],
                     )
                     for tc in message.tool_calls
                     if tc["name"].startswith(TOOL_STRATEGY_TOOL_PREFIX)

splunklib/ai/messages.py

@@ -21,7 +21,7 @@
 from splunklib.ai.tools import ToolType
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class TextBlock:
     """Plain text content block returned by a model."""
 
@@ -36,7 +36,7 @@ class TextBlock:
     """
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class OpaqueBlock:
     """Content block of an unrecognized or unsupported type.
 
@@ -62,30 +62,30 @@ class OpaqueBlock:
 ContentBlock = TextBlock | OpaqueBlock
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ToolCall:
     id: str
     name: str
     type: ToolType
     args: dict[str, Any]
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class SubagentCall:
     id: str
     name: str
     args: str | dict[str, Any]
     thread_id: str | None
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class StructuredOutputCall:
     id: str
     name: str
     args: dict[str, Any]
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class BaseMessage:
     role: str = field(init=False)
 
@@ -96,7 +96,7 @@ def __post_init__(self) -> None:
             )
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class HumanMessage(BaseMessage):
     """
     Message originating from a human user.
@@ -110,7 +110,7 @@ class HumanMessage(BaseMessage):
     content: str
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class AIMessage(BaseMessage):
     """
     Message produced by an LLM.
@@ -141,7 +141,7 @@ class AIMessage(BaseMessage):
     """
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ToolResult:
     """
     ToolResult represents a result of a successful tool call.
@@ -151,7 +151,7 @@ class ToolResult:
     structured_content: dict[str, Any] | None
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class SubagentStructuredResult:
     """
     SubagentStructuredResult represents a result of a successful subagent call.
@@ -161,7 +161,7 @@ class SubagentStructuredResult:
     structured_output: dict[str, Any]
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class SubagentTextResult:
     """
     SubagentTextResult represents a result of a successful subagent call.
@@ -171,7 +171,7 @@ class SubagentTextResult:
     content: str
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ToolFailureResult:
     """
     Represents the result of a failed sub-agent call.
@@ -183,7 +183,7 @@ class ToolFailureResult:
     error_message: str
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class SubagentFailureResult:
     """
     Represents the result of a failed tool call.
@@ -195,7 +195,7 @@ class SubagentFailureResult:
     error_message: str
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ToolMessage(BaseMessage):
     """ToolMessage represents a response of a tool call"""
 
@@ -208,7 +208,7 @@ class ToolMessage(BaseMessage):
 
 
 # TODO: do we have a test that uses this?
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class SystemMessage(BaseMessage):
     """
     A message used to prime or control agent behavior.
@@ -218,7 +218,7 @@ class SystemMessage(BaseMessage):
     content: str
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class SubagentMessage(BaseMessage):
     """
     SubagentMessage represents a response of an agent invocation
@@ -231,7 +231,7 @@ class SubagentMessage(BaseMessage):
     result: SubagentStructuredResult | SubagentTextResult | SubagentFailureResult
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class StructuredOutputMessage(BaseMessage):
     """
     StructuredMessage represents a response to the StructuredOutputCall.
@@ -254,7 +254,7 @@ class StructuredOutputMessage(BaseMessage):
 # where developers might want to store messages in say KV store.
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class AgentResponse(Generic[OutputT]):
     # in case output_schema is provided, this will hold the parsed structured output
     structured_output: OutputT

splunklib/ai/middleware.py

@@ -30,7 +30,7 @@
 )
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class AgentState:
     """AgentState is available through certain middlewares and contains information about the current state of an agent execution."""
 
@@ -42,27 +42,27 @@ class AgentState:
     token_count: int
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ToolRequest:
     call: ToolCall
     state: AgentState
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ToolResponse:
     result: ToolResult | ToolFailureResult
 
 
 ToolMiddlewareHandler = Callable[[ToolRequest], Awaitable[ToolResponse]]
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class SubagentRequest:
     call: SubagentCall
     state: AgentState
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class SubagentResponse:
     result: SubagentStructuredResult | SubagentTextResult | SubagentFailureResult
 
@@ -73,13 +73,13 @@ class SubagentResponse:
 ]
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ModelRequest:
     system_message: str
     state: AgentState
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ModelResponse:
     message: AIMessage
     structured_output: Any | None = None
@@ -94,7 +94,7 @@ def __post_init__(self) -> None:
 ModelMiddlewareHandler = Callable[[ModelRequest], Awaitable[ModelResponse]]
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class AgentRequest:
     messages: Sequence[BaseMessage]
 

splunklib/ai/model.py

@@ -18,14 +18,14 @@
 import httpx
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class PredefinedModel:
     """Base class for models that are predefined in the SDK"""
 
     model: str
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class OpenAIModel(PredefinedModel):
     """Predefined OpenAI Model"""
 
@@ -53,7 +53,7 @@ class OpenAIModel(PredefinedModel):
     """
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class AnthropicModel(PredefinedModel):
     """Predefined Anthropic Model"""
 

splunklib/ai/structured_output.py

@@ -17,12 +17,12 @@
 from splunklib.ai.messages import AIMessage
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class StructuredOutputMultipleToolCallsError:
     pass
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class StructuredOutputValidationError:
     validation_error: str
 

splunklib/ai/tool_settings.py

@@ -18,7 +18,7 @@
 from splunklib.ai.tools import ToolMetadata
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ToolAllowlist:
     """Holds tool names and tags allowed to be used by Agents.
 
@@ -41,17 +41,17 @@ def is_allowed(self, tool: ToolMetadata) -> bool:
         return self.custom_predicate(tool) if self.custom_predicate else False
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class RemoteToolSettings:
     allowlist: ToolAllowlist
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class LocalToolSettings:
     allowlist: ToolAllowlist
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class ToolSettings:
     local: LocalToolSettings | bool
     """Controls local tool loading (via ``bin/tools.py``).