More Optim.

ums/__init__.py

@@ -6,4 +6,28 @@
 # 	https://www.chai.uni-hamburg.de/~bender
 #  
 # source code released under the terms of GNU Public License Version 3
-# https://www.gnu.org/licenses/gpl-3.0.txt
+# https://www.gnu.org/licenses/gpl-3.0.txt
+
+"""
+The package `ums` contains the Agenten-Plattform, the implementations of the agents shall be created in the package `src`, see [Agent-Template](https://git.chai.uni-hamburg.de/UMS-Agenten/Agent-Template).
+
+> Side note: The classes with comments may be useful when implementing the agents.
+> The classes without comments may be safe to ignore and are (only) used internally.
+
+- `ums.agent`
+	- Contains the implementation of an agent for handling requests by the implementations in `src`.
+- `ums.example`
+	- Contains a very simple examples for all types of agents.
+	- See `ums.example.example`
+- `ums.management`
+	- Contains the implementation of the management.
+	- Take a look at the web gui of the management!
+- `ums.utils`
+	- Contains various utilities.
+	- `ums.utils.const.SHARE_PATH` The path for shared files between all agents
+	- `ums.utils.const.PERSIST_PATH` The path to store persistent data of an agent
+	- `ums.utils.request.ManagementRequest` Run request to the management (only necessary in special cases, most requests done automatically by platform)
+	- `ums.utils.schema` The schema (types) used in the files storing extracted data from plain data
+	- `ums.utils.types` The types used in the communication between agent and management
+
+"""

ums/management/db.py

@@ -144,7 +144,7 @@ class DB():
 				yield count['count']
 			else:
 				for row in self.db.execute(
-					"SELECT * FROM Messages {} ORDER BY time DESC LIMIT :lim OFFSET :off".format(where_clause),
+					"SELECT * FROM Messages {} ORDER BY time DESC, count DESC LIMIT :lim OFFSET :off".format(where_clause),
 					params
 				):
 					yield self._create_row_object(row, allow_lazy=True)

ums/management/process.py

@@ -20,6 +20,7 @@ from ums.utils import AgentMessage, AgentResponse, logger
 class MessageProcessor():
 
 	SOLUTION_MAX_TRIALS = int(os.environ.get('SOLUTION_MAX_TRIALS', 5))
+	MESSAGE_MAX_CONTACTS = int(os.environ.get('MESSAGE_MAX_CONTACTS', 100))
 
 	MANAGEMENT_URL = os.environ.get('MANAGEMENT_URL', 'http://127.0.0.1:80').strip().strip('/')
 	
@@ -78,6 +79,12 @@ class MessageProcessor():
 			# do not process processed messages again
 			return
 		
+		# increment contacts counter
+		db_message.message.contacts += 1
+		if db_message.message.contacts > self.MESSAGE_MAX_CONTACTS:
+			logger.warning(f"Message reached max number of contacts! {db_message.message.id}, {count}")
+			return
+		
 		# check which step/ state the message requires the management to do
 		if db_message.message.status.extract.required and not db_message.message.status.extract.finished:
 			# send to extract agents
@@ -136,6 +143,9 @@ class MessageProcessor():
 			# add the riddle as new to management
 			self._send_message(self.MANAGEMENT_URL, message)
 
+		else:
+			logger.info(f"Unsolved riddle after max number of trials: {message.id}")
+
 	def _send_messages(self, recipients:List[str], message:AgentMessage) -> bool:
 		ok  = True
 		for r in recipients:

ums/utils/schema.py

@@ -0,0 +1,27 @@
+# Agenten Plattform
+#
+# (c) 2024 Magnus Bender
+# 	Institute of Humanities-Centered Artificial Intelligence (CHAI)
+# 	Universitaet Hamburg
+# 	https://www.chai.uni-hamburg.de/~bender
+#  
+# source code released under the terms of GNU Public License Version 3
+# https://www.gnu.org/licenses/gpl-3.0.txt
+
+"""
+	This represents the basic types used for representing extracted information from the data.
+	The types are implemented using [pydantic](https://docs.pydantic.dev/).
+	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.
+
+"""
+
+from enum import Enum
+
+from typing import List, Any
+
+from pydantic import BaseModel
+
+class ExtractionSchema(BaseModel):
+	"""
+		This is the basic class used as superclass for all extracted information from data items.
+	"""

ums/utils/types.py

@@ -45,7 +45,8 @@
 				{
 					"type": "text",
 					"file_plain": "/ums-agenten/share/cv.txt",
-					"file_extracted": null
+					"file_extracted": null,
+					"prompt": null
 				}
 			],
 			"status": {
@@ -63,7 +64,8 @@
 				},
 				"trial": 0,
 				"solved": false
-			}
+			},
+			"contacts": 0
 		}
 	```
 	```python
@@ -103,6 +105,7 @@ from pydantic import (
 from pydantic.functional_validators import WrapValidator, AfterValidator
 
 from ums.utils.const import SHARE_PATH
+from ums.utils.schema import ExtractionSchema
 
 class RiddleInformation(BaseModel):
 	"""
@@ -172,6 +175,10 @@ class RiddleData(RiddleInformation):
 		The file must exist.
 	"""
 
+	prompt: str | ExtractionSchema | None = None 
+	"""
+		An optional prompt giving more details to the extraction agent, e.g., selecting a type of extraction/ task to do with the data.
+	"""
 
 
 class RiddleSolution(RiddleInformation):
@@ -312,6 +319,13 @@ class AgentMessage(RiddleInformation):
 		The status of the riddle.
 	"""
 
+	contacts : int = 0
+	"""
+		A counter representing the number of contacts the management had with this message.
+		Each time the management processes the message, this counter is incremented by 1.
+		Using this counter the management is able to detect cycles and stop them.
+	"""
+
 class AgentResponse(RiddleInformation):
 	"""
 		Returned by the management when receiving an `AgentMessage`.