polycog-cognition 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.
cognition/__init__.py ADDED
@@ -0,0 +1,22 @@
1
+ """
2
+ Polycog cognition library
3
+ """
4
+
5
+ import logging
6
+
7
+ from .cogent import *
8
+ from .decision import *
9
+ from .knowledge import *
10
+ from .language import *
11
+ from .reasoning import *
12
+ from .util import *
13
+
14
+ # ===
15
+
16
+ logger = logging.getLogger(__name__)
17
+ logger.setLevel(logging.NOTSET)
18
+ logger.addHandler(logging.NullHandler())
19
+
20
+ # ===
21
+
22
+ __version__ = "1.0.0"
@@ -0,0 +1,44 @@
1
+ """
2
+ Cogent sub-module
3
+ """
4
+
5
+ from . import cogent, env
6
+ from .cogent import (
7
+ Cogent,
8
+ self_actuator,
9
+ self_sensor,
10
+ )
11
+ from .env import (
12
+ Actuator,
13
+ ActuatorInvoker,
14
+ BaseActuator,
15
+ BaseSensor,
16
+ Sensor,
17
+ SensorReader,
18
+ create_actuator,
19
+ create_sensor,
20
+ install,
21
+ invoke_actuator,
22
+ perceive,
23
+ read_sensor_data,
24
+ )
25
+
26
+ __all__ = [
27
+ "Actuator",
28
+ "ActuatorInvoker",
29
+ "BaseActuator",
30
+ "BaseSensor",
31
+ "Cogent",
32
+ "Sensor",
33
+ "SensorReader",
34
+ "cogent",
35
+ "create_actuator",
36
+ "create_sensor",
37
+ "env",
38
+ "install",
39
+ "invoke_actuator",
40
+ "perceive",
41
+ "read_sensor_data",
42
+ "self_actuator",
43
+ "self_sensor",
44
+ ]
@@ -0,0 +1,384 @@
1
+ """
2
+ (Cog)nitive ag(ents)
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import logging
8
+ from collections.abc import Mapping
9
+ from types import MappingProxyType
10
+ from typing import Any, Literal, Self
11
+
12
+ from ..decision.core import (
13
+ BaseDecisionProcess,
14
+ DecisionProcessErrorMessage,
15
+ DecisionProcessExecutionError,
16
+ )
17
+ from ..decision.dp import NamedObject, args_added, format_name_params
18
+ from ..util.functypes import BiFunction, BiPredicate, Function, Predicate, Supplier
19
+ from ..util.misc import stringify
20
+ from .env import (
21
+ BaseActuator,
22
+ BaseSensor,
23
+ create_actuator,
24
+ create_sensor,
25
+ install,
26
+ perceive,
27
+ )
28
+
29
+ # ===
30
+
31
+ _logger = logging.getLogger(__name__)
32
+
33
+ # ===
34
+
35
+
36
+ def self_sensor[C: Cogent[Any], T](m: Function[C, T]) -> Function[C, T]:
37
+ """
38
+ Decorator to mark a cogent method for use as a sensor upon instance init
39
+
40
+ :param m: method
41
+ :return: supplied method (tagged for later init)
42
+ """
43
+
44
+ # pylint: disable=protected-access
45
+ m._is_selfsensor = True # type: ignore[attr-defined]
46
+ return m
47
+
48
+
49
+ def self_actuator[C: Cogent[Any], P, F](
50
+ m: BiFunction[C, P, F],
51
+ ) -> BiFunction[C, P, F]:
52
+ """
53
+ Decorator to mark a cogent method for use as an actuator upon instance init
54
+
55
+ :param m: method
56
+ :return: supplied method (tagged for later init)
57
+ """
58
+
59
+ # pylint: disable=protected-access
60
+ m._is_selfactuator = True # type: ignore[attr-defined]
61
+ return m
62
+
63
+
64
+ class Cogent[DP: BaseDecisionProcess[Any]](NamedObject):
65
+ """
66
+ Base for a cognitive agent that uses type ``S``
67
+ for decision process state, and ``DP`` as the
68
+ type of decision process
69
+ """
70
+
71
+ DEFAULT_NAME: str = "cogent"
72
+
73
+ _self_sensors: dict[str, Function[Cogent[DP], Any]]
74
+ _self_actuators: dict[str, BiFunction[Cogent[DP], Any, Any]]
75
+
76
+ def __init_subclass__(cls, **kwargs: Any) -> None:
77
+ super().__init_subclass__(**kwargs)
78
+
79
+ cls._self_sensors = {
80
+ name: val
81
+ for name, val in vars(cls).items()
82
+ if callable(val) and getattr(val, "_is_selfsensor", False)
83
+ }
84
+
85
+ cls._self_actuators = {
86
+ name: val
87
+ for name, val in vars(cls).items()
88
+ if callable(val) and getattr(val, "_is_selfactuator", False)
89
+ }
90
+
91
+ def _add_self_tagged(self) -> None:
92
+
93
+ if hasattr(self, "_self_sensors"):
94
+ for s_n, s_m in self._self_sensors.items():
95
+
96
+ def _self_sensor[T](orig_method: Function[Cogent[DP], T] = s_m) -> T:
97
+ return orig_method(self)
98
+
99
+ self.add_sensor(create_sensor(s_n, _self_sensor))
100
+
101
+ if hasattr(self, "_self_actuators"):
102
+ for a_n, a_m in self._self_actuators.items():
103
+
104
+ def _self_actuator[P, F](
105
+ param: P, orig_method: BiFunction[Cogent[DP], P, F] = a_m
106
+ ) -> F:
107
+ return orig_method(self, param)
108
+
109
+ self.add_actuator(create_actuator(a_n, _self_actuator))
110
+
111
+ # ===
112
+
113
+ def __init__(
114
+ self, decision_process: DP, name: str = DEFAULT_NAME, **kwargs: Any
115
+ ) -> None:
116
+ """
117
+ :param decision_process: agent control
118
+ :param name: agent name
119
+ :param kwargs: optional parameters to describe the agent
120
+ """
121
+
122
+ self._dp = decision_process
123
+ self._sensors: set[BaseSensor[Any]] = set()
124
+
125
+ self._name = name
126
+ self._params = kwargs
127
+ self._str = format_name_params(name, **kwargs)
128
+
129
+ # ===
130
+
131
+ self._add_self_tagged()
132
+
133
+ _logger.info("Cogent (%s): initialized", self)
134
+
135
+ def __str__(self) -> str:
136
+ return self._str
137
+
138
+ @property
139
+ def dp(self) -> DP:
140
+ """
141
+ :return: decision process for this cogent
142
+ """
143
+
144
+ return self._dp
145
+
146
+ @property
147
+ def name(self) -> str:
148
+ """
149
+ :return: cogent's name
150
+ """
151
+
152
+ return self._name
153
+
154
+ @property
155
+ def params(self) -> Mapping[str, Any]:
156
+ """
157
+ :return: optional augmentations to the cogent
158
+ """
159
+
160
+ return MappingProxyType(self._params)
161
+
162
+ def add_sensor(self, sensor: BaseSensor[Any]) -> Self:
163
+ """
164
+ Add a sensor to the cogent
165
+
166
+ :param sensor: sensor to add
167
+ :return: this cogent (for chaining)
168
+ """
169
+
170
+ _logger.info("Cogent (%s): sensor (%s) added", self, sensor.name)
171
+
172
+ self._sensors.add(sensor)
173
+ return self
174
+
175
+ def sensor(
176
+ self,
177
+ **kwargs: Any,
178
+ ) -> Function[type[BaseSensor[Any]], type[BaseSensor[Any]]]:
179
+ """
180
+ Decorator version of :meth:`Cogent.add_sensor`
181
+
182
+ :param kwargs: instantiation argument(s)
183
+ :return: parameterized decorator
184
+ """
185
+
186
+ def cls_dec(cls: type[BaseSensor[Any]]) -> type[BaseSensor[Any]]:
187
+ """
188
+ Adds a sensor instance to this cogent.
189
+
190
+ :param cls: sensor to instantiate
191
+ :return: added class
192
+ """
193
+
194
+ self.add_sensor(cls(**kwargs))
195
+ return cls
196
+
197
+ return cls_dec
198
+
199
+ def as_sensor[T](self, name: str) -> Function[Supplier[T], Supplier[T]]:
200
+ """
201
+ Decorator version of :func:`.env.create_sensor`
202
+
203
+ :param name: name for the sensor instance
204
+ :return: parameterized decorator
205
+ """
206
+
207
+ def dec(f: Supplier[T]) -> Supplier[T]:
208
+ self.add_sensor(create_sensor(name, f))
209
+ return f
210
+
211
+ return dec
212
+
213
+ def add_actuator(self, actuator: BaseActuator[Any, Any]) -> Self:
214
+ """
215
+ Add an actuator to the cogent
216
+
217
+ :param actuator: actuator to add
218
+ :return: this cogent (for chaining)
219
+ """
220
+
221
+ _logger.info("Cogent (%s): actuator (%s) installed", self, actuator.name)
222
+
223
+ install(actuator, self._dp)
224
+ return self
225
+
226
+ def actuator(
227
+ self,
228
+ **kwargs: Any,
229
+ ) -> Function[type[BaseActuator[Any, Any]], type[BaseActuator[Any, Any]]]:
230
+ """
231
+ Decorator version of :meth:`Cogent.add_actuator`
232
+
233
+ :param kwargs: instantiation argument(s)
234
+ :return: parameterized decorator
235
+ """
236
+
237
+ def cls_dec(cls: type[BaseActuator[Any, Any]]) -> type[BaseActuator[Any, Any]]:
238
+ """
239
+ Adds a actuator instance to this cogent.
240
+
241
+ :param cls: actuator to instantiate
242
+ :return: added class
243
+ """
244
+
245
+ self.add_actuator(cls(**kwargs))
246
+ return cls
247
+
248
+ return cls_dec
249
+
250
+ def as_actuator[P, F](self, name: str) -> Function[Function[P, F], Function[P, F]]:
251
+ """
252
+ Decorator version of :func:`.env.create_actuator`
253
+
254
+ :param name: name for the actuator instance
255
+ :return: parameterized decorator
256
+ """
257
+
258
+ def dec(f: Function[P, F]) -> Function[P, F]:
259
+ self.add_actuator(create_actuator(name, f))
260
+ return f
261
+
262
+ return dec
263
+
264
+ def perception(self) -> None:
265
+ """
266
+ All added sensors are routed to the decision process IO container
267
+ """
268
+
269
+ _logger.info("Cogent (%s): all-sensor perception", self)
270
+
271
+ for s in self._sensors:
272
+ perceive(s, self._dp)
273
+
274
+ @stringify("run_once")
275
+ @staticmethod
276
+ def gate_run_once(_c: Cogent[Any]) -> Literal[False]:
277
+ """
278
+ Immediate end upon decision process termination
279
+ """
280
+
281
+ return False
282
+
283
+ @stringify("run_forever")
284
+ @staticmethod
285
+ def gate_run_forever(_c: Cogent[Any]) -> Literal[True]:
286
+ """
287
+ Restarts decision process upon termination
288
+ """
289
+
290
+ return True
291
+
292
+ def __call__(
293
+ self,
294
+ repeat_p: Predicate[Cogent[DP]] = gate_run_once,
295
+ max_cycles: int | None = None,
296
+ dp_err_p: BiPredicate[DecisionProcessErrorMessage, Self] | None = None,
297
+ other_err_p: BiPredicate[Exception, Self] | None = None,
298
+ **args: Any,
299
+ ) -> Self:
300
+ """
301
+ After initialization (dp.reinit, add arguments),
302
+ runs a cogent loop...
303
+
304
+ 1. Cache sensor(s) perception to IO
305
+ 2. Run the decision process
306
+ 3. Check the gating predicate
307
+ (reinitialize the decision process if not done)
308
+
309
+ until the supplied gating predicate returns ``False``
310
+
311
+ :param repeat_p: gating predicate (assuming no errors)
312
+ :param max_cycles: maximum dp cycles to run per loop;
313
+ ``None`` indicates no limit
314
+ :param dp_err_p: gating predicate to continue if a known
315
+ error type occurs (or raise if ``None``)
316
+ (see :class:`cognition.decision.core.DecisionProcessExecutionError`)
317
+ :param other_err_p: gating predicate to continue if an unknown
318
+ error type occurs (or raise if ``None``)
319
+ :param args: IO args to add (see :func:`cognition.decision.dp.args_added`)
320
+ :return: this cogent (for chaining)
321
+ """
322
+
323
+ _logger.info("Cogent (%s): run started", self)
324
+ _logger.debug(
325
+ "repeat_p=%s, max_cycles=%s, dp_err_p=%s, args=%s",
326
+ repeat_p,
327
+ max_cycles,
328
+ dp_err_p,
329
+ args,
330
+ )
331
+
332
+ proceed = True
333
+ self._dp.reinit()
334
+
335
+ with args_added(self._dp, **args):
336
+ while proceed:
337
+ _logger.debug("Cogent (%s): loop start", self)
338
+
339
+ try:
340
+ self.perception()
341
+ if max_cycles is None:
342
+ self._dp.run_until_done()
343
+ else:
344
+ self._dp.run_cycles(max_cycles)
345
+
346
+ _logger.debug("Cogent (%s): dp run complete", self)
347
+
348
+ proceed = repeat_p(self)
349
+ _logger.debug(
350
+ "Cogent (%s): gate checked (keep going: %s)", self, proceed
351
+ )
352
+ except DecisionProcessExecutionError as err_dp:
353
+ _logger.error(err_dp)
354
+
355
+ if dp_err_p is not None:
356
+ proceed = dp_err_p(err_dp.msg, self)
357
+
358
+ _logger.debug(
359
+ "Cogent (%s): known error gate checked (keep going: %s)",
360
+ self,
361
+ proceed,
362
+ )
363
+ else:
364
+ raise
365
+ except Exception as err_other: # pylint: disable=broad-exception-caught
366
+ _logger.error(err_other)
367
+
368
+ if other_err_p is not None:
369
+ proceed = other_err_p(err_other, self)
370
+
371
+ _logger.debug(
372
+ "Cogent (%s): unknown error gate checked (keep going: %s)",
373
+ self,
374
+ proceed,
375
+ )
376
+ else:
377
+ raise
378
+
379
+ if proceed:
380
+ self._dp.reinit()
381
+
382
+ _logger.info("Cogent (%s): run ended", self)
383
+
384
+ return self