Core code documentation

src/cst_python/core/entities/coalition.py

@@ -1,4 +1,11 @@
 class Coalition:
+    '''
+    A Coalition is a group of Codelets which are gathered in order to perform a
+    task by summing up their abilities or to form a specific context.
+
+    In CST, two codelets belong to the same coalition when they share information
+    - pragmatically, when they write in and read from the same memory object.
+    '''
 
     def __init__(self) -> None:
         raise NotImplementedError()

src/cst_python/core/entities/code_rack.py

@@ -7,12 +7,22 @@
 
 
 class CodeRack:
+    '''
+    Following Hofstadter and Mitchell
+    "The copycat project: A model of mental fluidity and analogy-making". Pool of
+    all alive codelets in the system. The whole arena in the Baars-Franklin
+    metaphor.
+    '''
+
     def __init__(self) -> None:
         self._all_codelets :List[Codelet] = []
 
     #@alias.alias("getAllCodelets", "get_all_codelets")
     @property
     def all_codelets(self) -> List[Codelet]:
+        '''
+        List of all alive codelets in the system
+        '''
         return self._all_codelets
 
     #@alias.alias("setAllCodelets", "set_all_codelets")
@@ -22,10 +32,26 @@ def all_codelets(self, value:List[Codelet]) -> None:
 
     #@alias.alias("add_codelet")
     def add_codelet(self, codelet:Codelet) -> None:
+        '''
+        Adds a new Codelet to the Coderack
+
+        Args:
+            codelet (Codelet): codelet to be added.
+        '''
         self._all_codelets.append(codelet)
 
     #@alias.alias("insertCodelet")
     def insert_codelet(self, codelet:Codelet) -> Codelet:
+        '''
+        Creates a codelet and adds it to this coderack.
+
+        Args:
+            codelet (Codelet): codelet to be created.
+
+        Returns:
+            Codelet: the own codelet inserted, if it is needed to concatenate to
+                further methods calls.
+        '''
         self.add_codelet(codelet)
 
         return codelet
@@ -34,6 +60,20 @@ def insert_codelet(self, codelet:Codelet) -> Codelet:
     def create_codelet(self, activation:float, broadcast:List[Memory],
                        inputs:List[Memory], outputs:List[Memory],
                        codelet:Codelet) -> Codelet:
+        '''
+        Creates a codelet and adds it to this coderack.
+
+        Args:
+            activation (float): codelet's activation.
+            broadcast (List[Memory]): list of memory objects which were broadcast lately (treated as
+                input memories).
+            inputs (List[Memory]): list of input memories.
+            outputs (List[Memory]): list o output memories.
+            codelet (Codelet): codelet to be created.
+
+        Returns:
+            Codelet: the codelet created.
+        '''
 
         try:
             codelet.activation = activation
@@ -50,18 +90,33 @@ def create_codelet(self, activation:float, broadcast:List[Memory],
 
     #@alias.alias("destroyCodelet")
     def destroy_codelet(self, codelet:Codelet) -> None:
+        '''
+        Removes a codelet from coderack.
+
+        Args:
+            codelet (Codelet): the codelet to be destroyed.
+        '''
         codelet.stop()
         self._all_codelets.remove(codelet)
 
     #@alias.alias("shutDown", "shut_down")
     def shutdow(self):
+        '''
+        Destroys all codelets. Stops CodeRack's thread.
+        '''
         self.stop()
         self._all_codelets.clear()
 
     def start(self) -> None:
+        '''
+        Starts all codelets in coderack.
+        '''
         for codelet in self._all_codelets:
             codelet.start()
 
     def stop(self) -> None:
+        '''
+        Stops all codelets within CodeRack.
+        '''        
         for codelet in self._all_codelets:
             codelet.stop()

src/cst_python/core/entities/memory.py

@@ -5,65 +5,153 @@
 from.memory_observer import MemoryObserver
 
 class Memory(abc.ABC):
+    '''
+    This class represents the interface for all kinds of memories that exist in
+    CST. In order to be recognized as a Memory, an entity must implement this
+    interface. Currently, there are to kinds of Memory: MemoryObject and
+    MemoryContainer. However, other forms of Memory might come up as CST
+    develops.
+    '''
 
     #@alias.alias("getI", "get_I")
     @abc.abstractmethod
     def get_info(self) -> Any:
+        '''
+        Gets the info inside this memory.
+
+        Returns:
+            Any: the info in memory.
+        '''
         ...
 
     #@alias.alias("setT", "set_I")
     @abc.abstractmethod
     def set_info(self, value:Any) -> int:
+        '''
+        Sets the info inside this Memory.
+
+        Args:
+            value (Any): the updated info to set in memory.
+
+        Returns:
+            int: index of the memory inside the container or -1 if not a
+                container.
+        '''
         ...
 
     #@alias.alias("getEvaluation")
     @abc.abstractmethod
     def get_evaluation(self) -> float:
+        '''
+        Gets the evaluation of this memory.
+
+        Returns:
+            float: the evaluation of this memory.
+        '''
         ...
 
     #@alias.alias("getName")
     @abc.abstractmethod
     def get_name(self) -> str:
+        '''
+        Gets the type of this memory.
+
+        Returns:
+            str: the type of the memory.
+        '''
         ...
 
     #@alias.alias("setName")
     @abc.abstractmethod
     def set_name(self, name:str) -> None:
+        '''
+        Sets the name of this memory.
+
+        Args:
+            name (str): the value to be set as name.
+        '''
         ...
 
     #@alias.alias("setEvaluation")
     @abc.abstractmethod
     def set_evaluation(self, evaluation:float) -> None:
+        '''
+        Sets the evaluation of this memory.
+
+        Args:
+            evaluation (float): the value to be set as evaluation.
+        '''
         ...
 
     #@alias.alias("getTimestamp")
     @abc.abstractmethod
     def get_timestamp(self) -> int:
+        '''
+        Gets the timestamp of this Memory.
+
+        Returns:
+            int: the timestamp of this Memory.
+        '''
         ...
 
     #@alias.alias("addMemoryObserver")
     @abc.abstractmethod
     def add_memory_observer(self, observer:MemoryObserver) -> None:
+        '''
+        Add a memory observer to its list.
+
+        Args:
+            observer (MemoryObserver): MemoryObserver to be added.
+        '''
         ...
 
     #@alias.alias("removeMemoryObserver")
     @abc.abstractmethod
     def remove_memory_observer(self, observer:MemoryObserver) -> None:
+        '''
+        Remove a memory observer from its list.
+
+        Args:
+            observer (MemoryObserver): MemoryObserver to be removed.
+        '''
         ...
 
     #@alias.alias("getId")
     @abc.abstractmethod
     def get_id(self) -> int:
+        '''
+        Gets the id of the Memory.
+
+        Returns:
+            int: the id of the Memory.
+        '''
         ...
 
     #@alias.alias("setId")
     @abc.abstractmethod
     def set_id(self, memory_id:int) -> None:
+        '''
+        Sets the id of the Memory.
+
+        Args:
+            memory_id (int): the id of the Memory to set.
+        '''
         ...
 
 
 
     def compare_name(self, other_name:str) -> bool:
+        '''
+        Compares tha name of this memory with another.
+
+        Comparation is case insensitive.
+
+        Args:
+            other_name (str): name of the other memory.
+
+        Returns:
+            bool: True if is the same name.
+        '''
         if self._name is None:
             return False
 

src/cst_python/core/entities/memory_buffer.py

@@ -1,3 +1,8 @@
 class MemoryBuffer:
+    '''
+    MemoryBuffer is a generic holder for memory objects. It may be used to
+    produce sensory buffers, action buffers or other very short term memory
+    structures.
+    '''
     def __init__(self) -> None:
         raise NotImplementedError()

src/cst_python/core/entities/memory_container.py

@@ -1,6 +1,18 @@
 from .memory import Memory
 
 class MemoryContainer(Memory):
+    '''
+    This class represents a Memory Container. The Memory Container is responsible
+    for implementing an important element in the Dynamic Subsumption mechanism
+    used in CST. All the Memory Objects in a Container are of the same type, and
+    hold the same parameters. The only differences among them are that they were
+    generated by a different codelet, and they might have different evaluations.
+    An evaluation is an inner parameter from any Memory Object, which holds a
+    value (usually a real value between 0 and 1) that measures a relative
+    importance given by the codelet, and which is used by the Evaluation codelet
+    within the Container to decide which from all input Memory Objects will be
+    sent to the output.
+    '''
 
     def __init__(self) -> None:
         super().__init__()

src/cst_python/core/entities/memory_object.py

@@ -8,8 +8,31 @@
 from .memory_observer import MemoryObserver
 
 class MemoryObject(Memory):
+    '''
+    A Memory Object is a generic information holder, acting as a sign or an
+    internal representation, which is responsible to store any auxiliary or
+    perennial information necessary for the cognitive architecture to perform its
+    behavior. Codelets and Memory Objects are intrinsically coupled to each
+    other, in the sense that Memory Objects hold the information necessary for
+    the Codelets to run, and are also the placeholders of any new information
+    generated by the codelet. The main property being hold by a Memory Object is
+    its Information (I). This information can be simply a number, or hold complex
+    structures like lists, trees, graphs or whole networks. In our computational
+    implementation, the information I is a generic Java Object, which can be used
+    to represent virtually anything. A Memory Object also has two extra kinds of
+    meta-information: a time stamp (T), which tags the Memory Object with a
+    marker indicating its last update, and an evaluation (E), which has many
+    different uses within CST. This evaluation is simply a number, which can be
+    used, e.g. as an appraisal factor in an emotional module, or simply as a
+    discriminator to differentiate among two or more Memory Objects of the same
+    type. These meta-information can be simply ignored by simpler codelets, or be
+    useful while implementing more sophisticated cognitive models.
+    '''
 
     def __init__(self) -> None:
+        '''
+        Creates a MemoryObject.
+        '''
         self._id = 0
         self._timestamp = 0
         self._evaluation = 0.0
@@ -44,14 +67,25 @@ def _notify_memory_observers(self) -> None:
         for observer in self._memory_observers:
             observer.notify_codelet()
 
+
     def update_info(self, info:Any) -> None:
+        '''
+        Args:
+            info (Any): the info in memory object to set.
+
+        .. deprecated::
+            Use set_info() instead
+        '''
         self.set_info(info)
 
     def get_timestamp(self) -> int:
         return self._timestamp
 
     @property
     def timestamp(self) -> int:
+        '''
+        Date when the data was "created" in milliseconds.
+        '''
         return self._timestamp
 
     #@alias.alias("setTimestamp")