ums.utils.types

This represents the basic types used to interact with the management. The types are implemented using pydantic. It provides validation, allow JSON serialization and works well with FastAPI which is used internally for the http request between the agents and the management.

Example

        ex = AgentMessage(
                id="ex1",
                riddle={
                        "context":"Example 1",
                        "question":"Get the name of the person."
                },
                data=[
                        RiddleData(
                                type=RiddleDataType.TEXT,
                                file_plain="./cv.txt"
                        )
                ]
        )
        ex.status.extract.required = False
        {
                "id": "ex1",
                "sub_ids": [],
                "riddle": {
                        "context": "Example 1",
                        "question": "Get the name of the person.",
                        "solutions_before": []
                },
                "solution": null,
                "data": [
                        {
                                "type": "text",
                                "file_plain": "/ums-agenten/share/cv.txt",
                                "file_extracted": null
                        }
                ],
                "status": {
                        "extract": {
                                "required": false,
                                "finished": false
                        },
                        "solve": {
                                "required": true,
                                "finished": false
                        },
                        "validate": {
                                "required": true,
                                "finished": false
                        },
                        "trial": 0,
                        "solved": false
                }
        }
        ex.solution = RiddleSolution(
                solution="Otto",
                explanation="Written in line 6 after 'Name:'"
        )
        {
                ...
                "solution": {
                        "solution": "Otto",
                        "explanation": "Written in line 6 after 'Name:'",
                        "used_data": [],
                        "accepted": false,
                        "review": null
                },
                ...
        }
  1# Agenten Plattform
  2#
  3# (c) 2024 Magnus Bender
  4# 	Institute of Humanities-Centered Artificial Intelligence (CHAI)
  5# 	Universitaet Hamburg
  6# 	https://www.chai.uni-hamburg.de/~bender
  7#  
  8# source code released under the terms of GNU Public License Version 3
  9# https://www.gnu.org/licenses/gpl-3.0.txt
 10
 11"""
 12	This represents the basic types used to interact with the management.
 13	The types are implemented using [pydantic](https://docs.pydantic.dev/).
 14	It provides validation, allow JSON serialization and works well with [FastAPI](https://fastapi.tiangolo.com/) which is used internally for the http request between the agents and the management.
 15
 16	### Example
 17
 18	```python
 19		ex = AgentMessage(
 20			id="ex1",
 21			riddle={
 22				"context":"Example 1",
 23				"question":"Get the name of the person."
 24			},
 25			data=[
 26				RiddleData(
 27					type=RiddleDataType.TEXT,
 28					file_plain="./cv.txt"
 29				)
 30			]
 31		)
 32		ex.status.extract.required = False
 33	```
 34	```json
 35		{
 36			"id": "ex1",
 37			"sub_ids": [],
 38			"riddle": {
 39				"context": "Example 1",
 40				"question": "Get the name of the person.",
 41				"solutions_before": []
 42			},
 43			"solution": null,
 44			"data": [
 45				{
 46					"type": "text",
 47					"file_plain": "/ums-agenten/share/cv.txt",
 48					"file_extracted": null
 49				}
 50			],
 51			"status": {
 52				"extract": {
 53					"required": false,
 54					"finished": false
 55				},
 56				"solve": {
 57					"required": true,
 58					"finished": false
 59				},
 60				"validate": {
 61					"required": true,
 62					"finished": false
 63				},
 64				"trial": 0,
 65				"solved": false
 66			}
 67		}
 68	```
 69	```python
 70		ex.solution = RiddleSolution(
 71			solution="Otto",
 72			explanation="Written in line 6 after 'Name:'"
 73		)
 74	```
 75	```json
 76		{
 77			...
 78			"solution": {
 79				"solution": "Otto",
 80				"explanation": "Written in line 6 after 'Name:'",
 81				"used_data": [],
 82				"accepted": false,
 83				"review": null
 84			},
 85			...
 86		}
 87	```
 88
 89"""
 90
 91import os
 92
 93from enum import Enum
 94
 95from typing import List
 96from typing_extensions import Annotated
 97
 98from pydantic import BaseModel
 99from pydantic.functional_validators import AfterValidator
100
101from ums.utils.const import SHARE_PATH
102
103class RiddleInformation(BaseModel):
104	"""
105		This is the basic class used as superclass for all message and infos
106		about a riddle.
107	"""
108
109class RiddleDataType(Enum):
110	"""
111		Enum for the three types of data used in a riddle.
112	"""
113	
114	TEXT = "text"
115	IMAGE = "image"
116	AUDIO = "audio"
117
118def _check_data_file(file_name:str) -> str:
119	if not file_name.startswith('/'):
120		file_name = os.path.join(SHARE_PATH, file_name)
121	
122	assert file_name.startswith(SHARE_PATH), "The data file needs to be in {}!".format(SHARE_PATH)
123
124	file_name = os.path.realpath(file_name, strict=False)
125
126	assert os.path.isfile(file_name), "The data file {} does not exist!".format(file_name)
127	
128	return file_name
129
130class RiddleData(RiddleInformation):
131	"""
132		A data item to be used to solve the riddle
133	"""
134
135	type: RiddleDataType
136	"""
137		The type of the data item.
138	"""
139
140	file_plain: Annotated[str, AfterValidator(_check_data_file)] 
141	"""
142		The plain file (as path to file system) without any processing.
143
144		The path will be validated and must start with `SHARE_PATH` (or be relative to `SHARE_PATH`).
145		The file must exist.
146	"""
147
148	file_extracted: Annotated[str, AfterValidator(_check_data_file)] | None = None
149	"""
150		The processed files (as path to file system), i.e., a schematic file containing all extracted informations.
151
152		The path will be validated and must start with `SHARE_PATH` (or be relative to `SHARE_PATH`).
153		The file must exist.
154	"""
155
156class RiddleSolution(RiddleInformation):
157	"""
158		A solution of a riddle.
159	"""
160
161	solution: str
162	"""
163		The textual value of the solution.
164	"""
165
166	explanation: str
167	"""
168		An explanation of the solution.
169	"""
170
171	used_data: List[RiddleData] = []
172	"""
173		The data items used to create the solution (optional).
174	"""
175
176	accepted : bool = False
177	"""
178		If the solution is accepted by validator/ gatekeeper.
179	"""
180
181	review: str | None = None
182	"""
183		A review of the solution (if None: not tried to validate)
184	"""
185
186class Riddle(RiddleInformation):
187	"""
188		The riddle (the task description and possibly a solution)
189	"""
190	
191	context: str
192	"""
193		The context of the riddle (as textual string).
194	"""
195
196	question: str
197	"""
198		The actual main question of the riddle (as textual string).
199	"""
200
201	solutions_before: List[RiddleSolution] = []
202	"""
203		If already tried to solve this riddle before, the (not accepted) solutions are stored here
204	"""
205
206class RiddleSubStatus(RiddleInformation):
207	"""
208		The sub status for each possible step a riddle may go though.
209	"""
210	
211	required: bool = True
212	"""
213		Is this step required (i.e., requested)
214	"""
215
216	finished: bool = False
217	"""
218		Was this step already executed.
219	"""
220
221class RiddleStatus(RiddleInformation):
222	"""
223		The status of a riddle, will be mostly changed by Management when the riddle is sent to different agents while solving it.
224	"""
225	
226	extract: RiddleSubStatus = RiddleSubStatus()
227	"""
228		The first extract step (image, text, audio -> more sematic data)
229
230		The `RiddleData` items in `AgentMessage.data` shall have `file_extracted` afterwards. 
231	"""
232	
233	solve: RiddleSubStatus = RiddleSubStatus()
234	"""
235		The *main* solving step.
236
237		`AgentMessage.solution` shall be an `RiddleSolution` afterwards.
238	"""
239
240	validate: RiddleSubStatus = RiddleSubStatus()
241	"""
242		The validation step, i.e., does the gatekeeper accept the solution in `AgentMessage.solution`.
243	"""
244
245	trial: int = 0
246	"""
247		A counter for the number of trials.
248		Each time the gatekeeper does not accept a solution of this riddle, the value is incremented.
249	"""
250
251	solved: bool = False
252	"""
253		True, after the gatekeeper accepts the solution at `AgentMessage.solution`
254	"""
255
256class AgentMessage(RiddleInformation):
257	"""
258		The basic message, which is sent be the agent and the management.
259		The objects will be JSON en- and decoded.
260	"""
261
262	id: str
263	"""
264		The riddle id, e.g., ``ex1``
265		This is a unique string and identifies the riddle.
266	"""
267
268	sub_ids: List[str] = []
269	"""
270		There might be cases, when an agent decided to split in riddle in multiple *smaller* steps.
271		Each *sub* riddle will then get its own id (i.e., ``ex1-sub1``) while the sub id is added here as reference.
272	"""
273
274	riddle: Riddle
275	"""
276		The riddle to solve.
277	"""
278
279	solution: RiddleSolution | None = None
280	"""
281		The solution of the riddle (or empty if no solution available)
282	"""
283
284	data: List[RiddleData] = []
285	"""
286		The data to get the solution from.
287	"""
288
289	status: RiddleStatus = RiddleStatus()
290	"""
291		The status of the riddle.
292	"""
293
294class AgentResponse(RiddleInformation):
295	"""
296		Returned by the management when receiving an `AgentMessage`.
297	"""
298
299	count : int
300	"""
301		The count of the message (overall numeric id).
302	"""
303
304	msg: str|None = None
305	"""
306		An additional message.
307	"""
308
309	error: bool = False
310	"""
311		If an error occurred.
312	"""
313
314	error_msg: str|None = None
315	"""
316		Error message (if `error` )
317	"""
318
319class MessageDbRow(BaseModel):
320	"""
321		Object representing a database row.
322	"""
323
324	count : int
325	"""
326		The count (primary key) of the item.
327	"""
328
329	sender : str
330	"""
331		The sender of the message.
332	""" 
333
334	recipient : str
335	"""
336		The recipient of the message
337	"""
338
339	time : int
340	"""
341		The time (unix timestamp) the message was received/ sent.
342	"""
343
344	message : AgentMessage
345	"""
346		The message  received/ sent.
347	"""
348
349	processed : bool
350	"""
351		Did the management process the message, i.e., did the tasks necessary for this message (mostly only relevant for received messages).
352	"""
class RiddleInformation(pydantic.main.BaseModel):
104class RiddleInformation(BaseModel):
105	"""
106		This is the basic class used as superclass for all message and infos
107		about a riddle.
108	"""

This is the basic class used as superclass for all message and infos about a riddle.

Inherited Members
pydantic.main.BaseModel
BaseModel
model_extra
model_fields_set
model_construct
model_copy
model_dump
model_dump_json
model_json_schema
model_parametrized_name
model_post_init
model_rebuild
model_validate
model_validate_json
model_validate_strings
dict
json
parse_obj
parse_raw
parse_file
from_orm
construct
copy
schema
schema_json
validate
update_forward_refs
class RiddleDataType(enum.Enum):
110class RiddleDataType(Enum):
111	"""
112		Enum for the three types of data used in a riddle.
113	"""
114	
115	TEXT = "text"
116	IMAGE = "image"
117	AUDIO = "audio"

Enum for the three types of data used in a riddle.

TEXT = <RiddleDataType.TEXT: 'text'>
IMAGE = <RiddleDataType.IMAGE: 'image'>
AUDIO = <RiddleDataType.AUDIO: 'audio'>
Inherited Members
enum.Enum
name
value
class RiddleData(RiddleInformation):
131class RiddleData(RiddleInformation):
132	"""
133		A data item to be used to solve the riddle
134	"""
135
136	type: RiddleDataType
137	"""
138		The type of the data item.
139	"""
140
141	file_plain: Annotated[str, AfterValidator(_check_data_file)] 
142	"""
143		The plain file (as path to file system) without any processing.
144
145		The path will be validated and must start with `SHARE_PATH` (or be relative to `SHARE_PATH`).
146		The file must exist.
147	"""
148
149	file_extracted: Annotated[str, AfterValidator(_check_data_file)] | None = None
150	"""
151		The processed files (as path to file system), i.e., a schematic file containing all extracted informations.
152
153		The path will be validated and must start with `SHARE_PATH` (or be relative to `SHARE_PATH`).
154		The file must exist.
155	"""

A data item to be used to solve the riddle

The type of the data item.

file_plain: Annotated[str, AfterValidator(func=<function _check_data_file at 0x1067a8f40>)]

The plain file (as path to file system) without any processing.

The path will be validated and must start with SHARE_PATH (or be relative to SHARE_PATH). The file must exist.

file_extracted: Optional[Annotated[str, AfterValidator(func=<function _check_data_file at 0x1067a8f40>)]]

The processed files (as path to file system), i.e., a schematic file containing all extracted informations.

The path will be validated and must start with SHARE_PATH (or be relative to SHARE_PATH). The file must exist.

Inherited Members
pydantic.main.BaseModel
BaseModel
model_extra
model_fields_set
model_construct
model_copy
model_dump
model_dump_json
model_json_schema
model_parametrized_name
model_post_init
model_rebuild
model_validate
model_validate_json
model_validate_strings
dict
json
parse_obj
parse_raw
parse_file
from_orm
construct
copy
schema
schema_json
validate
update_forward_refs
class RiddleSolution(RiddleInformation):
157class RiddleSolution(RiddleInformation):
158	"""
159		A solution of a riddle.
160	"""
161
162	solution: str
163	"""
164		The textual value of the solution.
165	"""
166
167	explanation: str
168	"""
169		An explanation of the solution.
170	"""
171
172	used_data: List[RiddleData] = []
173	"""
174		The data items used to create the solution (optional).
175	"""
176
177	accepted : bool = False
178	"""
179		If the solution is accepted by validator/ gatekeeper.
180	"""
181
182	review: str | None = None
183	"""
184		A review of the solution (if None: not tried to validate)
185	"""

A solution of a riddle.

solution: str

The textual value of the solution.

explanation: str

An explanation of the solution.

used_data: List[RiddleData]

The data items used to create the solution (optional).

accepted: bool

If the solution is accepted by validator/ gatekeeper.

review: str | None

A review of the solution (if None: not tried to validate)

Inherited Members
pydantic.main.BaseModel
BaseModel
model_extra
model_fields_set
model_construct
model_copy
model_dump
model_dump_json
model_json_schema
model_parametrized_name
model_post_init
model_rebuild
model_validate
model_validate_json
model_validate_strings
dict
json
parse_obj
parse_raw
parse_file
from_orm
construct
copy
schema
schema_json
validate
update_forward_refs
class Riddle(RiddleInformation):
187class Riddle(RiddleInformation):
188	"""
189		The riddle (the task description and possibly a solution)
190	"""
191	
192	context: str
193	"""
194		The context of the riddle (as textual string).
195	"""
196
197	question: str
198	"""
199		The actual main question of the riddle (as textual string).
200	"""
201
202	solutions_before: List[RiddleSolution] = []
203	"""
204		If already tried to solve this riddle before, the (not accepted) solutions are stored here
205	"""

The riddle (the task description and possibly a solution)

context: str

The context of the riddle (as textual string).

question: str

The actual main question of the riddle (as textual string).

solutions_before: List[RiddleSolution]

If already tried to solve this riddle before, the (not accepted) solutions are stored here

Inherited Members
pydantic.main.BaseModel
BaseModel
model_extra
model_fields_set
model_construct
model_copy
model_dump
model_dump_json
model_json_schema
model_parametrized_name
model_post_init
model_rebuild
model_validate
model_validate_json
model_validate_strings
dict
json
parse_obj
parse_raw
parse_file
from_orm
construct
copy
schema
schema_json
validate
update_forward_refs
class RiddleSubStatus(RiddleInformation):
207class RiddleSubStatus(RiddleInformation):
208	"""
209		The sub status for each possible step a riddle may go though.
210	"""
211	
212	required: bool = True
213	"""
214		Is this step required (i.e., requested)
215	"""
216
217	finished: bool = False
218	"""
219		Was this step already executed.
220	"""

The sub status for each possible step a riddle may go though.

required: bool

Is this step required (i.e., requested)

finished: bool

Was this step already executed.

Inherited Members
pydantic.main.BaseModel
BaseModel
model_extra
model_fields_set
model_construct
model_copy
model_dump
model_dump_json
model_json_schema
model_parametrized_name
model_post_init
model_rebuild
model_validate
model_validate_json
model_validate_strings
dict
json
parse_obj
parse_raw
parse_file
from_orm
construct
copy
schema
schema_json
validate
update_forward_refs
class RiddleStatus(RiddleInformation):
222class RiddleStatus(RiddleInformation):
223	"""
224		The status of a riddle, will be mostly changed by Management when the riddle is sent to different agents while solving it.
225	"""
226	
227	extract: RiddleSubStatus = RiddleSubStatus()
228	"""
229		The first extract step (image, text, audio -> more sematic data)
230
231		The `RiddleData` items in `AgentMessage.data` shall have `file_extracted` afterwards. 
232	"""
233	
234	solve: RiddleSubStatus = RiddleSubStatus()
235	"""
236		The *main* solving step.
237
238		`AgentMessage.solution` shall be an `RiddleSolution` afterwards.
239	"""
240
241	validate: RiddleSubStatus = RiddleSubStatus()
242	"""
243		The validation step, i.e., does the gatekeeper accept the solution in `AgentMessage.solution`.
244	"""
245
246	trial: int = 0
247	"""
248		A counter for the number of trials.
249		Each time the gatekeeper does not accept a solution of this riddle, the value is incremented.
250	"""
251
252	solved: bool = False
253	"""
254		True, after the gatekeeper accepts the solution at `AgentMessage.solution`
255	"""

The status of a riddle, will be mostly changed by Management when the riddle is sent to different agents while solving it.

extract: RiddleSubStatus

The first extract step (image, text, audio -> more sematic data)

The RiddleData items in AgentMessage.data shall have file_extracted afterwards.

The main solving step.

AgentMessage.solution shall be an RiddleSolution afterwards.

@classmethod
@typing_extensions.deprecated('The `validate` method is deprecated; use `model_validate` instead.', category=None)
def validate(cls, value: Any) -> Self:
1383    @classmethod
1384    @typing_extensions.deprecated('The `validate` method is deprecated; use `model_validate` instead.', category=None)
1385    def validate(cls, value: Any) -> Self:  # noqa: D102
1386        warnings.warn(
1387            'The `validate` method is deprecated; use `model_validate` instead.', category=PydanticDeprecatedSince20
1388        )
1389        return cls.model_validate(value)

The validation step, i.e., does the gatekeeper accept the solution in AgentMessage.solution.

trial: int

A counter for the number of trials. Each time the gatekeeper does not accept a solution of this riddle, the value is incremented.

solved: bool

True, after the gatekeeper accepts the solution at AgentMessage.solution

Inherited Members
pydantic.main.BaseModel
BaseModel
model_extra
model_fields_set
model_construct
model_copy
model_dump
model_dump_json
model_json_schema
model_parametrized_name
model_post_init
model_rebuild
model_validate
model_validate_json
model_validate_strings
dict
json
parse_obj
parse_raw
parse_file
from_orm
construct
copy
schema
schema_json
update_forward_refs
class AgentMessage(RiddleInformation):
257class AgentMessage(RiddleInformation):
258	"""
259		The basic message, which is sent be the agent and the management.
260		The objects will be JSON en- and decoded.
261	"""
262
263	id: str
264	"""
265		The riddle id, e.g., ``ex1``
266		This is a unique string and identifies the riddle.
267	"""
268
269	sub_ids: List[str] = []
270	"""
271		There might be cases, when an agent decided to split in riddle in multiple *smaller* steps.
272		Each *sub* riddle will then get its own id (i.e., ``ex1-sub1``) while the sub id is added here as reference.
273	"""
274
275	riddle: Riddle
276	"""
277		The riddle to solve.
278	"""
279
280	solution: RiddleSolution | None = None
281	"""
282		The solution of the riddle (or empty if no solution available)
283	"""
284
285	data: List[RiddleData] = []
286	"""
287		The data to get the solution from.
288	"""
289
290	status: RiddleStatus = RiddleStatus()
291	"""
292		The status of the riddle.
293	"""

The basic message, which is sent be the agent and the management. The objects will be JSON en- and decoded.

id: str

The riddle id, e.g., ex1 This is a unique string and identifies the riddle.

sub_ids: List[str]

There might be cases, when an agent decided to split in riddle in multiple smaller steps. Each sub riddle will then get its own id (i.e., ex1-sub1) while the sub id is added here as reference.

riddle: Riddle

The riddle to solve.

solution: RiddleSolution | None

The solution of the riddle (or empty if no solution available)

data: List[RiddleData]

The data to get the solution from.

status: RiddleStatus

The status of the riddle.

Inherited Members
pydantic.main.BaseModel
BaseModel
model_extra
model_fields_set
model_construct
model_copy
model_dump
model_dump_json
model_json_schema
model_parametrized_name
model_post_init
model_rebuild
model_validate
model_validate_json
model_validate_strings
dict
json
parse_obj
parse_raw
parse_file
from_orm
construct
copy
schema
schema_json
validate
update_forward_refs
class AgentResponse(RiddleInformation):
295class AgentResponse(RiddleInformation):
296	"""
297		Returned by the management when receiving an `AgentMessage`.
298	"""
299
300	count : int
301	"""
302		The count of the message (overall numeric id).
303	"""
304
305	msg: str|None = None
306	"""
307		An additional message.
308	"""
309
310	error: bool = False
311	"""
312		If an error occurred.
313	"""
314
315	error_msg: str|None = None
316	"""
317		Error message (if `error` )
318	"""

Returned by the management when receiving an AgentMessage.

count: int

The count of the message (overall numeric id).

msg: str | None

An additional message.

error: bool

If an error occurred.

error_msg: str | None

Error message (if error )

Inherited Members
pydantic.main.BaseModel
BaseModel
model_extra
model_fields_set
model_construct
model_copy
model_dump
model_dump_json
model_json_schema
model_parametrized_name
model_post_init
model_rebuild
model_validate
model_validate_json
model_validate_strings
dict
json
parse_obj
parse_raw
parse_file
from_orm
construct
copy
schema
schema_json
validate
update_forward_refs
class MessageDbRow(pydantic.main.BaseModel):
320class MessageDbRow(BaseModel):
321	"""
322		Object representing a database row.
323	"""
324
325	count : int
326	"""
327		The count (primary key) of the item.
328	"""
329
330	sender : str
331	"""
332		The sender of the message.
333	""" 
334
335	recipient : str
336	"""
337		The recipient of the message
338	"""
339
340	time : int
341	"""
342		The time (unix timestamp) the message was received/ sent.
343	"""
344
345	message : AgentMessage
346	"""
347		The message  received/ sent.
348	"""
349
350	processed : bool
351	"""
352		Did the management process the message, i.e., did the tasks necessary for this message (mostly only relevant for received messages).
353	"""

Object representing a database row.

count: int

The count (primary key) of the item.

sender: str

The sender of the message.

recipient: str

The recipient of the message

time: int

The time (unix timestamp) the message was received/ sent.

message: AgentMessage

The message received/ sent.

processed: bool

Did the management process the message, i.e., did the tasks necessary for this message (mostly only relevant for received messages).

Inherited Members
pydantic.main.BaseModel
BaseModel
model_extra
model_fields_set
model_construct
model_copy
model_dump
model_dump_json
model_json_schema
model_parametrized_name
model_post_init
model_rebuild
model_validate
model_validate_json
model_validate_strings
dict
json
parse_obj
parse_raw
parse_file
from_orm
construct
copy
schema
schema_json
validate
update_forward_refs