Coverage for /home/admin/Documents/AI/applications/lexigram-dev/lexigram/experimental/ai/lexigram-ai-agents/src/lexigram/ai/agents/types.py: 97%

1"""Agent types — concrete implementations for agent execution. 

2 

3Defines ToolExecutionRecord and ReasoningStep (concrete agent data structures). 

4AgentResponse is re-exported from contracts as it's used in protocol signatures. 

5""" 

6 

7from __future__ import annotations 

8 

9from dataclasses import dataclass, field 

10from datetime import UTC, datetime 

11from typing import Any 

12 

13from lexigram.contracts.ai.agents import AgentResponse 

14 

15 

16@dataclass 

17class ToolExecutionRecord: 

18 """Record of a single tool invocation during agent execution. 

19 

20 Captures the tool name, arguments, result (or error), and timing 

21 for observability and debugging. 

22 """ 

23 

24 tool_name: str 

25 """Name of the tool that was called.""" 

26 

27 arguments: dict[str, Any] = field(default_factory=dict) 

28 """Arguments passed to the tool.""" 

29 

30 result: Any = None 

31 """Return value from the tool (None if error).""" 

32 

33 error: str | None = None 

34 """Error message if the tool call failed.""" 

35 

36 duration_ms: float = 0.0 

37 """Execution time in milliseconds.""" 

38 

39 timestamp: datetime = field(default_factory=lambda: datetime.now(UTC)) 

40 """When the tool was called.""" 

41 

42 @property 

43 def succeeded(self) -> bool: 

44 """Whether the tool call completed without error.""" 

45 return self.error is None 

46 

47 

48@dataclass 

49class ReasoningStep: 

50 """A single step in the agent's reasoning process. 

51 

52 Each step captures the agent's thought, the action it decided 

53 to take (if any), the tool call (if any), and the observation 

54 from the tool result or LLM response. 

55 """ 

56 

57 step_number: int 

58 """Sequential step number (1-based).""" 

59 

60 thought: str = "" 

61 """The agent's reasoning at this step.""" 

62 

63 action: str | None = None 

64 """The action decided (tool name or 'respond').""" 

65 

66 tool_call: ToolExecutionRecord | None = None 

67 """Tool call details (if action was a tool call).""" 

68 

69 observation: str | None = None 

70 """Result of the action — tool output or final response.""" 

71 

72 timestamp: datetime = field(default_factory=lambda: datetime.now(UTC)) 

73 """When this step occurred.""" 

74 

75 

76__all__ = [ 

77 "AgentResponse", 

78 "ReasoningStep", 

79 "ToolExecutionRecord", 

80]