sinapsis_core 1.0.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.
Files changed (50) hide show
  1. sinapsis_core/__init__.py +0 -0
  2. sinapsis_core/agent/__init__.py +5 -0
  3. sinapsis_core/agent/agent.py +362 -0
  4. sinapsis_core/agent/agent_helpers.py +112 -0
  5. sinapsis_core/agent/base_models.py +361 -0
  6. sinapsis_core/agent/builder.py +112 -0
  7. sinapsis_core/agent/profiler_agent.py +117 -0
  8. sinapsis_core/cli/__init__.py +0 -0
  9. sinapsis_core/cli/arg_parser.py +29 -0
  10. sinapsis_core/cli/display_template_info.py +202 -0
  11. sinapsis_core/cli/run_agent_from_config.py +40 -0
  12. sinapsis_core/context_managers/__init__.py +0 -0
  13. sinapsis_core/context_managers/env_var_override_context_manager.py +39 -0
  14. sinapsis_core/context_managers/working_dir_context_manager.py +57 -0
  15. sinapsis_core/data_containers/__init__.py +0 -0
  16. sinapsis_core/data_containers/annotations.py +152 -0
  17. sinapsis_core/data_containers/data_packet.py +364 -0
  18. sinapsis_core/data_containers/model_types/__init__.py +38 -0
  19. sinapsis_core/data_containers/model_types/_asr_base_models.py +39 -0
  20. sinapsis_core/data_containers/model_types/llm_types.py +189 -0
  21. sinapsis_core/exceptions/agent_exceptions.py +2 -0
  22. sinapsis_core/hooks/__init__.py +15 -0
  23. sinapsis_core/hooks/pre_init_hook_registry.py +225 -0
  24. sinapsis_core/template_base/__init__.py +10 -0
  25. sinapsis_core/template_base/base_models.py +59 -0
  26. sinapsis_core/template_base/copy_data_container.py +46 -0
  27. sinapsis_core/template_base/dynamic_template.py +169 -0
  28. sinapsis_core/template_base/dynamic_template_factory.py +454 -0
  29. sinapsis_core/template_base/dynamic_template_helpers/__init__.py +0 -0
  30. sinapsis_core/template_base/dynamic_template_helpers/builder_methods.py +92 -0
  31. sinapsis_core/template_base/dynamic_template_helpers/signature_parser.py +625 -0
  32. sinapsis_core/template_base/empty_data_container.py +23 -0
  33. sinapsis_core/template_base/input_template.py +8 -0
  34. sinapsis_core/template_base/merge_data_flow.py +33 -0
  35. sinapsis_core/template_base/multi_execute_template.py +65 -0
  36. sinapsis_core/template_base/output_template.py +8 -0
  37. sinapsis_core/template_base/split_data_flow.py +50 -0
  38. sinapsis_core/template_base/template.py +292 -0
  39. sinapsis_core/template_base/transfer_data_container.py +13 -0
  40. sinapsis_core/utils/__init__.py +0 -0
  41. sinapsis_core/utils/base_model_updater.py +148 -0
  42. sinapsis_core/utils/doc_string_generator.py +20 -0
  43. sinapsis_core/utils/env_var_keys.py +249 -0
  44. sinapsis_core/utils/env_var_utils.py +6 -0
  45. sinapsis_core/utils/logging_utils.py +53 -0
  46. sinapsis_core-1.0.0.dist-info/METADATA +239 -0
  47. sinapsis_core-1.0.0.dist-info/RECORD +50 -0
  48. sinapsis_core-1.0.0.dist-info/WHEEL +4 -0
  49. sinapsis_core-1.0.0.dist-info/licenses/LICENSE-APACHE +202 -0
  50. sinapsis_core-1.0.0.dist-info/licenses/LICENSE-MIT +21 -0
@@ -0,0 +1,364 @@
1
+ # -*- coding: utf-8 -*-
2
+ """
3
+ Data packets and container definitions. These objects define
4
+ the Universal Data Transport in Sinapsis, native Packet support
5
+ and additional helper methods.
6
+ """
7
+
8
+ import uuid
9
+ from enum import Enum
10
+ from pathlib import Path
11
+ from typing import Any, TypeAlias
12
+
13
+ from pydantic import ConfigDict, computed_field
14
+ from typing_extensions import Self
15
+
16
+ from sinapsis_core.data_containers.annotations import (
17
+ AudioAnnotations,
18
+ ImageAnnotations,
19
+ TextAnnotations,
20
+ )
21
+ from sinapsis_core.data_containers.model_types import (
22
+ LLMContextItem,
23
+ LLMIdentity,
24
+ LLMMessage,
25
+ LLMPerformance,
26
+ LLMProviderInfo,
27
+ LLMTermination,
28
+ LLMToolCall,
29
+ LLMToolDefinition,
30
+ LLMToolResult,
31
+ LLMUsage,
32
+ )
33
+ from sinapsis_core.utils.env_var_keys import SINAPSIS_PRODUCTION_MODE
34
+
35
+ if SINAPSIS_PRODUCTION_MODE:
36
+ from dataclasses import dataclass
37
+ from dataclasses import field as Field
38
+ else:
39
+ from pydantic import Field # type:ignore[no-redef]
40
+ from pydantic.dataclasses import dataclass # type:ignore[no-redef]
41
+
42
+
43
+ __all__ = [
44
+ "CONTENT_SHAPE",
45
+ "AudioPacket",
46
+ "BinaryPacket",
47
+ "DataContainer",
48
+ "DataFramePacket",
49
+ "ImageColor",
50
+ "ImagePacket",
51
+ "LLMConversationPacket",
52
+ "Packet",
53
+ "SupportedPacketTypes",
54
+ "TextPacket",
55
+ "TimeSeriesPacket",
56
+ "get_uuid",
57
+ ]
58
+
59
+ CONTENT_SHAPE: TypeAlias = tuple[int, int, int] | tuple[int, int] | tuple[int, int]
60
+
61
+
62
+ def get_uuid() -> str:
63
+ """Method to return a unique
64
+ id for DataContainers and Packets"""
65
+ return str(uuid.uuid4())
66
+
67
+
68
+ class ImageColor(Enum):
69
+ """Defines the type of color of the image
70
+ ImageColor supports RGB, BRG, GRAY and RGBA color spaces
71
+ """
72
+
73
+ RGB = 1
74
+ BGR = 2
75
+ GRAY = 3
76
+ RGBA = 4
77
+
78
+
79
+ @dataclass(slots=True)
80
+ class Packet:
81
+ """
82
+ Base dataclass for types of Packets that are transported in DataContainers
83
+ Specialized data types can inherit from it.
84
+
85
+ - content (Any): Packet content in any format.
86
+ - id (str | int): identifier for the packet.
87
+ - source (str): source of the given packet.
88
+ - embedding (list[float]): embedding representation for the content.
89
+ - generic_data (dict): Any other information should be placed in this field
90
+ """
91
+
92
+ content: Any
93
+ id: str | int = Field(default_factory=get_uuid)
94
+ source: str | None = None
95
+ embedding: list[float] | Any = Field(default_factory=list)
96
+ generic_data: dict[str, Any] = Field(default_factory=dict)
97
+ model_config = ConfigDict(arbitrary_types_allowed=True)
98
+
99
+
100
+ @dataclass(slots=True)
101
+ class ImagePacket(Packet):
102
+ """Dataclass for images.
103
+
104
+ - annotations (list[ImageAnnotations]): Annotations obtained from image segmentation,
105
+ keypoints detection, etc.
106
+ - color_space (ImageColor | None): Space color of the image (e.g. RGB, BGR, etc)
107
+ """
108
+
109
+ annotations: list[ImageAnnotations] = Field(default_factory=list)
110
+ color_space: ImageColor | None = None
111
+
112
+ @computed_field
113
+ def shape(self) -> CONTENT_SHAPE:
114
+ """Computed field to calculate the shape of the image if it's numpy.ndarray or torch.Tensor"""
115
+ if not hasattr(self.content, "shape"):
116
+ return (0, 0)
117
+ content_shape: CONTENT_SHAPE = self.content.shape
118
+ return content_shape
119
+
120
+
121
+ @dataclass(slots=True)
122
+ class AudioPacket(Packet):
123
+ """Dataclass for audio.
124
+ - sample_rate (int): sample rate of the audio data (samples per second).
125
+ - audio_duration (int | None): duration of the audio in seconds.
126
+ """
127
+
128
+ audio_duration: int | None = None
129
+ sample_rate: int | None = None
130
+ annotations: list[AudioAnnotations] = Field(default_factory=list)
131
+
132
+
133
+ @dataclass(slots=True)
134
+ class TimeSeriesPacket(Packet):
135
+ """
136
+ Data class for time series data.
137
+ Args:
138
+ predictions (Any | None): predictions of the forecasting analysis
139
+ past_covariates (Any | None): covariates known only into the past
140
+ future_covariates (Any | None): covariates known in the future
141
+ """
142
+
143
+ predictions: Any | None = None
144
+ past_covariates: Any | None = None
145
+ future_covariates: Any | None = None
146
+
147
+
148
+ @dataclass(slots=True)
149
+ class BinaryPacket(Packet):
150
+ """Data class for binary data."""
151
+
152
+
153
+ @dataclass(slots=True)
154
+ class TextPacket(Packet):
155
+ """Dataclass for text.
156
+ - annotations (TextAnnotations | None): annotations predicted by
157
+ zero-shot or language classifiers.
158
+ - n_tokens (int | None): number of tokens in the text.
159
+ """
160
+
161
+ annotations: list[TextAnnotations] = Field(default_factory=list)
162
+
163
+ @computed_field
164
+ @property
165
+ def n_tokens(self) -> int:
166
+ if isinstance(self.content, str):
167
+ return len(self.content.split())
168
+ log_msg = f"Invalid type: {type(self.content)} for TextPacket content, must be {str}."
169
+ raise AttributeError(log_msg)
170
+
171
+
172
+ @dataclass(slots=True)
173
+ class LLMConversationPacket(Packet):
174
+ """Dataclass for LLM request and response state.
175
+
176
+ - content (Any): primary prompt or latest user input.
177
+ - system_prompt (str | None): top-level system instruction.
178
+ - messages (list[LLMMessage]): normalized conversation state.
179
+ - contexts (list[LLMContextItem]): retrieved or injected context items.
180
+ - response (str | None): final model response text.
181
+ - reasoning (str | None): optional reasoning trace or summary.
182
+ - structured_output (dict | list | None): parsed structured response payload.
183
+ - tools (list[LLMToolDefinition]): tool definitions available to the model for this request.
184
+ - tool_calls (list[LLMToolCall]): tool calls emitted by the model.
185
+ - tool_results (list[LLMToolResult]): results returned to the model.
186
+ - identity (LLMIdentity | None): user, session, run, and agent identity metadata.
187
+ - provider_info (LLMProviderInfo | None): provider and model identity metadata.
188
+ - termination (LLMTermination | None): normalized finish/stop state for the response.
189
+ - usage (LLMUsage | None): token accounting metadata.
190
+ - performance (LLMPerformance | None): timing and throughput metadata.
191
+ """
192
+
193
+ system_prompt: str | None = None
194
+ messages: list[LLMMessage] = Field(default_factory=list)
195
+ contexts: list[LLMContextItem] = Field(default_factory=list)
196
+ response: str | None = None
197
+ reasoning: str | None = None
198
+ structured_output: dict[str, Any] | list[Any] | None = None
199
+ tools: list[LLMToolDefinition] = Field(default_factory=list)
200
+ tool_calls: list[LLMToolCall] = Field(default_factory=list)
201
+ tool_results: list[LLMToolResult] = Field(default_factory=list)
202
+ identity: LLMIdentity | None = None
203
+ provider_info: LLMProviderInfo | None = None
204
+ termination: LLMTermination | None = None
205
+ usage: LLMUsage | None = None
206
+ performance: LLMPerformance | None = None
207
+
208
+ @property
209
+ def prompt(self) -> Any:
210
+ """Alias for the primary prompt stored in content."""
211
+ return self.content
212
+
213
+
214
+ @dataclass(slots=True)
215
+ class DataFramePacket(Packet):
216
+ """
217
+ Dataclass for Tabular data (Pandas/Polars DataFrames).
218
+
219
+ - index_column (str | None): The name of the index or primary key column.
220
+ - dataframe_type (str | None): Metadata to distinguish between 'pandas', 'polars', etc.
221
+ """
222
+
223
+ index_column: str | None = None
224
+
225
+ @computed_field
226
+ def columns(self) -> list[str]:
227
+ """Read-only property to get columns."""
228
+ if hasattr(self.content, "columns"):
229
+ return list(self.content.columns)
230
+ return []
231
+
232
+ @computed_field
233
+ def column_info(self) -> dict[str, str]:
234
+ """Mapping names to their data types."""
235
+ if self.content is None:
236
+ return {}
237
+
238
+ if self.dataframe_type == "pandas":
239
+ return {str(k): str(v) for k, v in self.content.dtypes.to_dict().items()}
240
+ elif self.dataframe_type == "polars":
241
+ return {k: str(v) for k, v in self.content.schema.items()}
242
+ return {}
243
+
244
+ @property
245
+ def dataframe_type(self) -> str:
246
+ module = type(self.content).__module__
247
+ if "pandas" in module:
248
+ return "pandas"
249
+ elif "polars" in module:
250
+ return "polars"
251
+ else:
252
+ return "unknown"
253
+
254
+
255
+ @dataclass(slots=True)
256
+ class FilePacket(Packet):
257
+ # content: Path | str
258
+
259
+ @property
260
+ def file_size(self) -> int:
261
+ path_obj = Path(self.content) if isinstance(self.content, str) else self.content
262
+ size_in_bytes = path_obj.stat().st_size
263
+ return size_in_bytes
264
+
265
+
266
+ @dataclass(slots=True)
267
+ class DataContainer:
268
+ """Universal unit to transport data. It can be composed of one, some, or all the specific data
269
+ packets, i.e., DataPacket can contain ImagePacket, TextPacket, etc.
270
+ - container_id (Union[str, int]):
271
+ - images: list[ImagePacket] class. Defaults to empty list.
272
+ - audios: list[AudioPacket] class. Defaults to empty list.
273
+ - texts: list[TextPacket] class. Defaults to empty list.
274
+ - time_series: list[TimeSeriesPacket] class. Defaults empty list.
275
+ - binary_data: list[BinaryPacket] class. Defaults to empty list.
276
+ - generic_data: dictionary for generic data. Defaults to empty dict.
277
+ """
278
+
279
+ container_id: str | int = Field(default_factory=get_uuid)
280
+ images: list[ImagePacket] = Field(default_factory=list)
281
+ audios: list[AudioPacket] = Field(default_factory=list)
282
+ texts: list[TextPacket] = Field(default_factory=list)
283
+ llm_conversations: list[LLMConversationPacket] = Field(default_factory=list)
284
+ files: list[FilePacket] = Field(default_factory=list)
285
+ time_series: list[TimeSeriesPacket] = Field(default_factory=list)
286
+ data_frames: list[DataFramePacket] = Field(default_factory=list)
287
+ binary_data: list[BinaryPacket] = Field(default_factory=list)
288
+ generic_data: dict[str, Any] = Field(default_factory=dict)
289
+
290
+ def is_empty_packet(self, packet: str) -> bool:
291
+ """Generalized method to check if a field is empty."""
292
+ value = getattr(self, packet)
293
+
294
+ return not bool(value)
295
+
296
+ @property
297
+ def is_empty(self) -> bool:
298
+ """Determines if the DataContainer is empty (all attributes are empty)."""
299
+ return not any(
300
+ (
301
+ self.images,
302
+ self.audios,
303
+ self.texts,
304
+ self.llm_conversations,
305
+ self.files,
306
+ self.time_series,
307
+ self.binary_data,
308
+ self.generic_data,
309
+ self.data_frames,
310
+ )
311
+ )
312
+
313
+ def __repr__(self) -> str:
314
+ attr_strings = []
315
+ for slot_name in self.__slots__:
316
+ attr_value = getattr(self, slot_name)
317
+ if attr_value is not None:
318
+ attr_strings.append(f"{slot_name}={attr_value}")
319
+
320
+ return f"{self.__class__.__name__}({', '.join(attr_strings)})"
321
+
322
+ def __add__(self, other: Self) -> "DataContainer":
323
+ """Method to add a packet to the corresponding field
324
+ of the DataContainer, preserving the original DataContainer
325
+ """
326
+ return DataContainer(
327
+ images=self.images + other.images,
328
+ audios=self.audios + other.audios,
329
+ texts=self.texts + other.texts,
330
+ llm_conversations=self.llm_conversations + other.llm_conversations,
331
+ files=self.files + other.files,
332
+ time_series=self.time_series + other.time_series,
333
+ binary_data=self.binary_data + other.binary_data,
334
+ generic_data=self.generic_data | other.generic_data,
335
+ data_frames=self.data_frames + other.data_frames,
336
+ )
337
+
338
+ def __iadd__(self, other: Self) -> Self:
339
+ """Method to add a packet to the corresponding field
340
+ of the DataContainer, updating the original DataContainer
341
+ """
342
+ self.images += other.images
343
+ self.audios += other.audios
344
+ self.texts += other.texts
345
+ self.llm_conversations += other.llm_conversations
346
+ self.files += other.files
347
+ self.time_series += other.time_series
348
+ self.binary_data += other.binary_data
349
+ self.generic_data |= other.generic_data
350
+ self.data_frames += other.data_frames
351
+ return self
352
+
353
+
354
+ SupportedPacketTypes = (
355
+ Packet
356
+ | ImagePacket
357
+ | AudioPacket
358
+ | TextPacket
359
+ | LLMConversationPacket
360
+ | FilePacket
361
+ | TimeSeriesPacket
362
+ | BinaryPacket
363
+ | DataFramePacket
364
+ )
@@ -0,0 +1,38 @@
1
+ # -*- coding: utf-8 -*-
2
+ from sinapsis_core.data_containers.model_types._asr_base_models import (
3
+ DiarizedTranscript,
4
+ PredictedEmotion,
5
+ SpeakerTurn,
6
+ SpeechConstantKeys,
7
+ TranscriptSegment,
8
+ )
9
+ from sinapsis_core.data_containers.model_types.llm_types import (
10
+ LLMContextItem,
11
+ LLMIdentity,
12
+ LLMMessage,
13
+ LLMPerformance,
14
+ LLMProviderInfo,
15
+ LLMTermination,
16
+ LLMToolCall,
17
+ LLMToolDefinition,
18
+ LLMToolResult,
19
+ LLMUsage,
20
+ )
21
+
22
+ __all__ = [
23
+ "DiarizedTranscript",
24
+ "LLMContextItem",
25
+ "LLMIdentity",
26
+ "LLMMessage",
27
+ "LLMPerformance",
28
+ "LLMProviderInfo",
29
+ "LLMTermination",
30
+ "LLMToolCall",
31
+ "LLMToolDefinition",
32
+ "LLMToolResult",
33
+ "LLMUsage",
34
+ "PredictedEmotion",
35
+ "SpeakerTurn",
36
+ "SpeechConstantKeys",
37
+ "TranscriptSegment",
38
+ ]
@@ -0,0 +1,39 @@
1
+ # -*- coding: utf-8 -*-
2
+ from dataclasses import dataclass
3
+ from datetime import datetime
4
+
5
+ from pydantic import BaseModel, ConfigDict, Field
6
+
7
+
8
+ @dataclass
9
+ class SpeechConstantKeys:
10
+ unknown_speaker_tag: str = "UNKNOWN"
11
+ start: str = "start"
12
+ end: str = "end"
13
+
14
+
15
+ class PredictedEmotion(BaseModel):
16
+ name: str
17
+ confidence: float | None = None
18
+
19
+
20
+ class SpeakerTurn(BaseModel):
21
+ speaker: str = SpeechConstantKeys.unknown_speaker_tag
22
+ start_time: float = Field(..., description="Start time in seconds")
23
+ end_time: float = Field(..., description="End time in seconds")
24
+
25
+
26
+ class TranscriptSegment(SpeakerTurn):
27
+ """A single unit of speech with timing, text, and identity."""
28
+
29
+ text: list[str] | str
30
+ emotions: list[PredictedEmotion] | None = None
31
+
32
+
33
+ class DiarizedTranscript(BaseModel):
34
+ """The complete processed conversation with metadata."""
35
+
36
+ model_config = ConfigDict(frozen=True)
37
+ filename: str | None = None
38
+ processed_at: datetime = Field(default_factory=datetime.now)
39
+ segments: list[TranscriptSegment]
@@ -0,0 +1,189 @@
1
+ # -*- coding: utf-8 -*-
2
+ from typing import Any, Literal
3
+
4
+ from pydantic import Field
5
+
6
+ from sinapsis_core.utils.env_var_keys import SINAPSIS_PRODUCTION_MODE
7
+
8
+ if SINAPSIS_PRODUCTION_MODE:
9
+ from dataclasses import dataclass
10
+ from dataclasses import field as Field # type:ignore[no-redef]
11
+ else:
12
+ from pydantic import Field # type:ignore[no-redef]
13
+ from pydantic.dataclasses import dataclass # type:ignore[no-redef]
14
+
15
+
16
+ @dataclass(slots=True)
17
+ class LLMMessage:
18
+ """Normalized message exchanged with an LLM.
19
+
20
+ Attributes:
21
+ role (Literal["system", "user", "assistant", "tool", "developer"]): Semantic role of the message in the
22
+ conversation.
23
+ content (Any): Message payload. This can be plain text or provider-specific structured content blocks.
24
+ name (str | None): Optional speaker or tool name associated with the message.
25
+ metadata (dict[str, Any]): Extra message-level metadata that does not belong in the normalized fields.
26
+ """
27
+
28
+ role: Literal["system", "user", "assistant", "tool", "developer"]
29
+ content: Any
30
+ name: str | None = None
31
+ metadata: dict[str, Any] = Field(default_factory=dict)
32
+
33
+
34
+ @dataclass(slots=True)
35
+ class LLMContextItem:
36
+ """Context retrieved or injected into an LLM request.
37
+
38
+ Attributes:
39
+ category (Literal["rag", "memory", "document", "instruction", "other"]): High-level category describing where
40
+ the context came from or how it should be interpreted.
41
+ content (str): The actual context text to inject or track.
42
+ source (str | None): Optional origin for the context, such as a file path, database record, or URL.
43
+ score (float | None): Optional relevance score, typically used for retrieved context such as RAG chunks.
44
+ metadata (dict[str, Any]): Extra context metadata that callers may want to preserve.
45
+ """
46
+
47
+ category: Literal["rag", "memory", "document", "instruction", "other"]
48
+ content: str
49
+ source: str | None = None
50
+ score: float | None = None
51
+ metadata: dict[str, Any] = Field(default_factory=dict)
52
+
53
+
54
+ @dataclass(slots=True)
55
+ class LLMToolDefinition:
56
+ """Provider-neutral tool definition exposed to an LLM.
57
+
58
+ Attributes:
59
+ name (str): Public tool name exposed to the model.
60
+ description (str | None): Optional human-readable description of what the tool does.
61
+ input_schema (dict[str, Any] | None): Optional JSON-schema-like definition of accepted tool arguments.
62
+ metadata (dict[str, Any]): Extra provider-specific or application-specific metadata for the tool.
63
+ """
64
+
65
+ name: str
66
+ description: str | None = None
67
+ input_schema: dict[str, Any] | None = None
68
+ metadata: dict[str, Any] = Field(default_factory=dict)
69
+
70
+
71
+ @dataclass(slots=True)
72
+ class LLMToolCall:
73
+ """Normalized tool call emitted by a model.
74
+
75
+ Attributes:
76
+ name (str): Name of the tool the model wants to invoke.
77
+ arguments (dict[str, Any]): Parsed arguments that should be passed to the tool.
78
+ id (str | None): Optional provider-specific identifier for correlating calls and results.
79
+ metadata (dict[str, Any]): Extra provider-specific tool call metadata.
80
+ """
81
+
82
+ name: str
83
+ arguments: dict[str, Any] = Field(default_factory=dict)
84
+ id: str | None = None
85
+ metadata: dict[str, Any] = Field(default_factory=dict)
86
+
87
+
88
+ @dataclass(slots=True)
89
+ class LLMToolResult:
90
+ """Normalized result returned after executing a tool call.
91
+
92
+ Attributes:
93
+ name (str): Name of the tool that produced the result.
94
+ content (Any): Tool output payload returned to the orchestration layer or back to the model.
95
+ tool_call_id (str | None): Optional identifier linking this result to the originating tool call.
96
+ is_error (bool): Indicates whether the tool execution failed.
97
+ metadata (dict[str, Any]): Extra metadata produced during tool execution.
98
+ """
99
+
100
+ name: str
101
+ content: Any = None
102
+ tool_call_id: str | None = None
103
+ is_error: bool = False
104
+ metadata: dict[str, Any] = Field(default_factory=dict)
105
+
106
+
107
+ @dataclass(slots=True)
108
+ class LLMUsage:
109
+ """Token and usage accounting for an LLM request/response cycle.
110
+
111
+ Attributes:
112
+ input_tokens (int | None): Tokens consumed by the request payload sent to the model.
113
+ output_tokens (int | None): Tokens generated in the model response.
114
+ reasoning_tokens (int | None): Optional tokens spent on reasoning or thinking traces when the provider
115
+ exposes them.
116
+ total_tokens (int | None): Total tokens reported for the full request/response cycle.
117
+ """
118
+
119
+ input_tokens: int | None = None
120
+ output_tokens: int | None = None
121
+ reasoning_tokens: int | None = None
122
+ total_tokens: int | None = None
123
+
124
+
125
+ @dataclass(slots=True)
126
+ class LLMPerformance:
127
+ """Performance metrics captured during an LLM request/response cycle.
128
+
129
+ Attributes:
130
+ time_to_first_token (float | None): Seconds elapsed before the first token was emitted in streaming
131
+ scenarios.
132
+ latency_seconds (float | None): Total request latency from invocation to final response.
133
+ tokens_per_second (float | None): Throughput observed for generated output tokens.
134
+ """
135
+
136
+ time_to_first_token: float | None = None
137
+ latency_seconds: float | None = None
138
+ tokens_per_second: float | None = None
139
+
140
+
141
+ @dataclass(slots=True)
142
+ class LLMProviderInfo:
143
+ """Provider and model identity metadata for an LLM execution.
144
+
145
+ Attributes:
146
+ provider (str | None): Provider or adapter name used for the call, such as OpenAI, Anthropic, or vLLM.
147
+ model_name (str | None): Resolved model identifier used during execution.
148
+ """
149
+
150
+ provider: str | None = None
151
+ model_name: str | None = None
152
+
153
+
154
+ @dataclass(slots=True)
155
+ class LLMIdentity:
156
+ """Identity metadata for conversation, memory, and run scoping.
157
+
158
+ Attributes:
159
+ user_id (str | None): Stable identifier for the end user associated with the packet.
160
+ session_id (str | None): Conversation or chat session identifier used for chat history.
161
+ run_id (str | None): Execution-scoped identifier for a particular run or workflow instance.
162
+ agent_id (str | None): Identifier for the assistant or agent associated with the packet.
163
+ """
164
+
165
+ user_id: str | None = None
166
+ session_id: str | None = None
167
+ run_id: str | None = None
168
+ agent_id: str | None = None
169
+
170
+
171
+ @dataclass(slots=True)
172
+ class LLMTermination:
173
+ """Termination metadata for an LLM response.
174
+
175
+ Attributes:
176
+ finish_reason (str | None): Normalized completion reason, such as stop, length, tool_calls, or
177
+ content_filter.
178
+ stop_reason (str | None): Provider-specific stop explanation when exposed separately from the finish reason.
179
+ is_partial (bool): Indicates that the packet contains a partial streaming response rather than a final one.
180
+ consecutive_tool_failures (int): Number of consecutive MCP tool rounds that ended with at least one error.
181
+ Incremented each iteration where any tool result has is_error=True, reset to 0 on a clean round or
182
+ when the conversation completes. Used by MCP loop templates to break out after a configurable
183
+ number of repeated failures.
184
+ """
185
+
186
+ finish_reason: str | None = None
187
+ stop_reason: str | None = None
188
+ is_partial: bool = False
189
+ consecutive_tool_failures: int = 0
@@ -0,0 +1,2 @@
1
+ class AgentCancelledException(Exception):
2
+ pass
@@ -0,0 +1,15 @@
1
+ # -*- coding: utf-8 -*-
2
+
3
+ from .pre_init_hook_registry import (
4
+ AgentCallBackRegistry,
5
+ AgentClassDecoratorRegistry,
6
+ AgentPreInitHooks,
7
+ PreInitMetaclass,
8
+ )
9
+
10
+ __all__ = [
11
+ "AgentCallBackRegistry",
12
+ "AgentClassDecoratorRegistry",
13
+ "AgentPreInitHooks",
14
+ "PreInitMetaclass",
15
+ ]