ums.utils.request

  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	Access to the management, e.g., get the list of messages and single messages.
 13	Manually send messages (if necessary, the platforms should do this). 
 14
 15	### Example
 16	```python
 17
 18		m_request = ManagementRequest()
 19		
 20		m_request.get_message(count=12)
 21		# MessageDbRow(count=12 sender='from' recipient='to' ...
 22
 23		m_request.list_messages(id="test", limit=2)
 24		# [
 25		#	MessageDbRow(count=7256, sender='management', ...),
 26		#	MessageDbRow(count=7255, sender='management', ...),
 27		# ]
 28
 29		m_request.total_messages(id="test")
 30		# 31
 31
 32	```
 33
 34	See also `ums.example.__main__` and run in Docker via ``docker compose exec management python -m ums.example``
 35"""
 36
 37import os
 38from typing import List, Dict, Any
 39
 40import requests
 41from pydantic import validate_call
 42
 43from ums.utils.types import AgentMessage, AgentResponse, MessageDbRow
 44
 45
 46class RequestException(Exception):
 47	"""
 48		Raised on http and similar errors.
 49	"""
 50	pass
 51
 52class ManagementRequest():
 53
 54	MANAGEMENT_URL = os.environ.get('MANAGEMENT_URL', 'http://127.0.0.1:80').strip().strip('/')
 55
 56	@validate_call
 57	def __init__(self, allow_lazy:bool=True):
 58		"""
 59			If `allow_lazy` is active, the type checking (by pydantic) is less strict. 
 60			E.g. it does not require that all files in the data section of messages must exist on the file system.
 61		"""
 62		self._allow_lazy = allow_lazy
 63		self._pydantic_context = {
 64			"require_file_exists": not self._allow_lazy
 65		}
 66
 67	@validate_call
 68	def get_message(self, count:int) -> MessageDbRow:
 69		"""
 70			Get a message (like a table row) from the management by using the `count`.
 71
 72			May raise `RequestException`.
 73		"""
 74		row = self._get_request(
 75			'list/single',
 76			{"count": count}
 77		)
 78		return MessageDbRow.model_validate(
 79			row, context=self._pydantic_context
 80		)
 81
 82	@validate_call
 83	def list_messages(self,
 84			id:str|None=None, sender:str|None=None, recipient:str|None=None,
 85			processed:bool|None=None, solution:bool|None=None,
 86			time_after:int|None=None, time_before:int|None=None,
 87			limit:int=10, offset:int=0
 88		) -> List[MessageDbRow]:
 89		"""
 90			Get the rows in the tables as list of messages.
 91			The arguments are used for filtering.
 92
 93			May raise `RequestException`.
 94		"""
 95
 96		kwargs = locals().copy()
 97		params = {}
 98
 99		for k,v in kwargs.items():
100			if k not in ('self',) and not v is None:
101				params[k] = v
102
103		rows = self._get_request('list', params)
104
105		return [
106				MessageDbRow.model_validate(
107					row, context=self._pydantic_context
108				) for row in rows
109			]
110
111	@validate_call
112	def total_messages(self,
113			id:str|None=None, sender:str|None=None, recipient:str|None=None,
114			processed:bool|None=None, solution:bool|None=None,
115			time_after:int|None=None, time_before:int|None=None
116		) -> int:
117		"""
118			Get the total number of rows in the tables matching the filters.
119
120			May raise `RequestException`.
121		"""
122		
123		kwargs = locals().copy()
124		params = {}
125
126		for k,v in kwargs.items():
127			if k not in ('self',) and not v is None:
128				params[k] = v
129
130		return int(self._get_request('app/table/total', params))
131
132	def _get_request(self, endpoint:str, params:Dict[str, Any]):
133		r = requests.get(
134			"{}/{}".format(self.MANAGEMENT_URL, endpoint),
135			params=params
136		)
137
138		if r.status_code == 200:
139			return r.json()
140		else:
141			raise RequestException(str(r.text)+"\n"+str(r.headers))
142
143	@validate_call
144	def send_message(self, message:AgentMessage) -> AgentResponse:
145		"""
146			Send the `message` to the management and return the management's agent response.
147			(On error an agent response with error message).
148		"""
149		try:
150			return AgentResponse.model_validate(
151				self._post_request(
152					"message",
153					message.model_dump_json()
154				)
155			)
156		except RequestException as e:
157			return AgentResponse(
158				count=-1,
159				error=True,
160				error_msg=str(e) 
161			)
162			
163	def _post_request(self, endpoint:str, data:Dict[str, Any]):
164		r = requests.post(
165			"{}/{}".format(self.MANAGEMENT_URL, endpoint),
166			data=data,
167			headers={"accept" : "application/json", "content-type" : "application/json"}
168		)
169
170		if r.status_code == 200:
171			return r.json()
172		else:
173			return RequestException(str(r.text)+"\n"+str(r.headers))