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-agent/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-agent/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 """
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
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.
Inherited Members
- enum.Enum
- name
- value
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 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.
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
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.
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
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)
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
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.
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
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.
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.
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
.
A counter for the number of trials. Each time the gatekeeper does not accept a solution of this riddle, the value is incremented.
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
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.
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.
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