docs: add and improve numpy-style docstrings across entire codebase

src/litemind/agent/agent.py

@@ -1,3 +1,10 @@
+"""Main agent module providing the Agent class for agentic AI interactions.
+
+The Agent orchestrates conversation state, tool execution, augmentation-based
+retrieval (RAG), and LLM API calls. It automatically selects a suitable model
+based on requested features and maintains a conversation history.
+"""
+
 from typing import List, Optional, Sequence, Union
 
 from arbol import aprint, asection
@@ -343,12 +350,44 @@ def _add_context_to_conversation(
             aprint(str(augmentation_message))
 
     def __getitem__(self, item) -> Message:
+        """Retrieve a message from the conversation by index.
+
+        Parameters
+        ----------
+        item : int
+            The index of the message to retrieve.
+
+        Returns
+        -------
+        Message
+            The message at the specified index in the conversation.
+        """
         return self.conversation[item]
 
     def __len__(self):
+        """Return the number of messages in the conversation.
+
+        Returns
+        -------
+        int
+            The total number of messages (system and standard) in the
+            conversation.
+        """
         return len(self.conversation)
 
     def __iadd__(self, other: Message):
+        """Append a message to the agent's conversation using the ``+=`` operator.
+
+        Parameters
+        ----------
+        other : Message
+            The message to append.
+
+        Returns
+        -------
+        Agent
+            The agent itself, for chaining.
+        """
         self.conversation.append(other)
         return self
 
@@ -560,7 +599,21 @@ def _prepare_call(self, *args, **kwargs) -> List[Message]:
         return messages
 
     def __repr__(self):
+        """Return a concise string representation of the agent.
+
+        Returns
+        -------
+        str
+            A string in the form ``Name(model=..., api=...)``.
+        """
         return f"{self.name}(model={self.model}, api={self.api.__class__.__name__})"
 
     def __str__(self):
+        """Return the human-readable string representation of the agent.
+
+        Returns
+        -------
+        str
+            Same as ``__repr__``.
+        """
         return self.__repr__()

src/litemind/agent/augmentations/augmentation_base.py

@@ -1,3 +1,11 @@
+"""Abstract base class for augmentations in the litemind agentic framework.
+
+This module defines ``AugmentationBase``, the interface that all augmentation
+implementations must satisfy. Augmentations provide additional context to
+large language models by retrieving relevant pieces of information based on
+a query, enabling Retrieval-Augmented Generation (RAG) workflows.
+"""
+
 from abc import ABC, abstractmethod
 from typing import Iterator, List, Optional, Union
 
@@ -87,7 +95,21 @@ def get_relevant_informations_iterator(
         pass
 
     def __repr__(self):
+        """Return a detailed string representation of the augmentation.
+
+        Returns
+        -------
+        str
+            A string of the form ``ClassName(name='augmentation_name')``.
+        """
         return f"{self.__class__.__name__}(name='{self.name}')"
 
     def __str__(self):
+        """Return the name of the augmentation.
+
+        Returns
+        -------
+        str
+            The augmentation name.
+        """
         return self.name

src/litemind/agent/augmentations/augmentation_default.py

@@ -1,3 +1,12 @@
+"""Default partial implementation of the augmentation interface.
+
+This module provides ``AugmentationDefault``, a convenience base class that
+sits between ``AugmentationBase`` and concrete augmentation implementations.
+It normalizes heterogeneous query types (strings, Pydantic models, media
+objects, and ``Information`` instances) into ``MediaBase`` objects and
+supplies a default iterator-based retrieval method.
+"""
+
 from typing import Iterator, Optional, Union
 
 from pydantic import BaseModel

src/litemind/agent/augmentations/augmentation_set.py

@@ -1,3 +1,12 @@
+"""A managed collection of augmentations for Retrieval-Augmented Generation.
+
+This module defines ``AugmentationSet``, a container that holds multiple
+``AugmentationBase`` instances and provides methods to search them
+individually or to combine their results into a single ranked list.
+Each augmentation can have its own retrieval settings (``k`` and
+``threshold``).
+"""
+
 from typing import Dict, List, Optional, Union
 
 from arbol import aprint
@@ -256,21 +265,74 @@ def _search_raw(self, augmentation, k, query, threshold):
         return infos
 
     def __getitem__(self, item) -> AugmentationBase:
+        """Retrieve an augmentation by index.
+
+        Parameters
+        ----------
+        item : int
+            The index of the augmentation to retrieve.
+
+        Returns
+        -------
+        AugmentationBase
+            The augmentation at the given index.
+        """
         return self.augmentations[item]
 
     def __len__(self) -> int:
+        """Return the number of augmentations in the set.
+
+        Returns
+        -------
+        int
+            The number of augmentations.
+        """
         return len(self.augmentations)
 
     def __iter__(self):
+        """Iterate over the augmentations in the set.
+
+        Returns
+        -------
+        Iterator[AugmentationBase]
+            An iterator over the augmentations.
+        """
         return iter(self.augmentations)
 
     def __contains__(self, item: Union[AugmentationBase, str]) -> bool:
+        """Check whether an augmentation is in the set.
+
+        Parameters
+        ----------
+        item : Union[AugmentationBase, str]
+            An augmentation instance or a name string to search for.
+
+        Returns
+        -------
+        bool
+            True if the augmentation (or an augmentation with the given name)
+            is present in the set.
+        """
         if isinstance(item, str):
             return any(aug.name == item for aug in self.augmentations)
         return item in self.augmentations
 
     def __str__(self) -> str:
+        """Return a human-readable string listing the augmentation names.
+
+        Returns
+        -------
+        str
+            A string of the form ``AugmentationSet(['name1', 'name2', ...])``.
+        """
         return f"AugmentationSet({[aug.name for aug in self.augmentations]})"
 
     def __repr__(self) -> str:
+        """Return a detailed string representation of the augmentation set.
+
+        Returns
+        -------
+        str
+            Same as ``__str__``.
+        """
         return self.__str__()