besser-agentic-framework 4.4.1__tar.gz → 4.4.2__tar.gz

{besser_agentic_framework-4.4.1/besser_agentic_framework.egg-info → besser_agentic_framework-4.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: besser-agentic-framework
-Version: 4.4.1
+Version: 4.4.2
 Summary: BESSER Agentic Framework (BAF)
 Author: Luxembourg Institute of Science and Technology
 License: MIT
@@ -51,6 +51,7 @@ Requires-Dist: langchain-community==0.2.7; python_version < "3.13" and extra ==
 Requires-Dist: langchain==0.3.10; python_version >= "3.13" and extra == "extras"
 Requires-Dist: langchain-community==0.3.10; python_version >= "3.13" and extra == "extras"
 Requires-Dist: pypdf==4.3.1; extra == "extras"
+Requires-Dist: python-docx==1.2.0; extra == "extras"
 Requires-Dist: tiktoken==0.9.0; extra == "extras"
 Provides-Extra: llms
 Requires-Dist: openai==1.93.0; extra == "llms"
@@ -83,6 +84,7 @@ Requires-Dist: langchain-community==0.2.7; python_version < "3.13" and extra ==
 Requires-Dist: langchain==0.3.10; python_version >= "3.13" and extra == "all"
 Requires-Dist: langchain-community==0.3.10; python_version >= "3.13" and extra == "all"
 Requires-Dist: pypdf==4.3.1; extra == "all"
+Requires-Dist: python-docx==1.2.0; extra == "all"
 Requires-Dist: tiktoken==0.9.0; extra == "all"
 Requires-Dist: openai==1.93.0; extra == "all"
 Requires-Dist: replicate==0.23.1; extra == "all"

{besser_agentic_framework-4.4.1 → besser_agentic_framework-4.4.2}/baf/core/session.py

@@ -18,7 +18,7 @@ from baf.library.transition.events.base_events import ReceiveMessageEvent, Recei
 from baf.core.message import Message, get_message_type
 from baf.exceptions.logger import logger
 from baf.db import DB_MONITORING
-from baf.nlp.rag.rag import RAGMessage
+from baf.nlp.rag.rag import RAGMessage, RAG
 from baf.platforms.payload import PayloadEncoder, Payload, PayloadAction
 
 if TYPE_CHECKING:
@@ -27,6 +27,8 @@ if TYPE_CHECKING:
     from baf.core.state import State
     from baf.platforms.platform import Platform
 
+_SESSION_RAG_KEY = '__session_rag__'
+
 
 class Session:
     """A user session in an agent execution.
@@ -400,3 +402,40 @@ class Session:
         if self._agent.nlp_engine._rag is None:
             raise ValueError('Attempting to run RAG in an agent with no RAG engine.')
         return self._agent.nlp_engine._rag.run(message, self, llm_prompt, llm_name, k, num_previous_messages)
+
+    @property
+    def session_rag(self) -> RAG:
+        """RAG: The session-scoped RAG for this session, or ``None`` if not configured."""
+        return self.__dict__.get(_SESSION_RAG_KEY)
+
+    @session_rag.setter
+    def session_rag(self, rag: RAG) -> None:
+        """Set the session-scoped RAG for this session.
+
+        Args:
+            rag (RAG): a :class:`~baf.nlp.rag.rag.RAG` instance created with ``session_scoped=True``
+        """
+        # Stored as a plain instance attribute, not in _dictionary, so it is
+        # never picked up by get_dictionary() / JSON serialization to monitoring DB.
+        # RAG holds live in-memory objects (Chroma client, embeddings) that cannot
+        # be meaningfully serialized or restored from JSON.
+        self.__dict__[_SESSION_RAG_KEY] = rag
+
+    def run_session_rag(self, message: str, llm_prompt: str = None, llm_name: str = None, k: int = None) -> RAGMessage:
+        """Run RAG over this session's isolated corpus.
+
+        Args:
+            message (str): the input query
+            llm_prompt (str): override the LLM prompt for this call
+            llm_name (str): override the LLM name for this call
+            k (int): override the number of chunks to retrieve for this call
+
+        Returns:
+            RAGMessage: the answer generated by the session-scoped RAG engine
+
+        Raises:
+            RuntimeError: if no session-scoped RAG has been assigned to this session
+        """
+        if self.session_rag is None:
+            raise RuntimeError('No session-scoped RAG configured. Assign one via session.session_rag = RAG(..., session_scoped=True).')
+        return self.session_rag.run(message, self, llm_prompt, llm_name, k)

{besser_agentic_framework-4.4.1 → besser_agentic_framework-4.4.2}/baf/nlp/rag/rag.py

@@ -1,14 +1,17 @@
 from __future__ import annotations
 
 from baf.exceptions.logger import logger
+import base64
 import os
-from typing import TYPE_CHECKING
+import tempfile
+from typing import TYPE_CHECKING, Callable
 
 from baf.core.message import Message, MessageType
 from baf.nlp.llm.llm import LLM
 
 if TYPE_CHECKING:
     from baf.core.agent import Agent
+    from baf.core.file import File
     from baf.core.session import Session
     from baf.nlp.nlp_engine import NLPEngine
 
@@ -70,7 +73,9 @@ class RAG:
 
     Args:
         agent (Agent): the agent the RAG engine belongs to
-        vector_store (langchain_core.vectorstores.base.VectorStore): the vector store of the RAG engine
+        vector_store (langchain_core.vectorstores.base.VectorStore | Callable[[], VectorStore]): the vector store of the RAG engine, , or
+            a zero-arg factory that produces one. A factory is recommended when ``session_scoped=True`` so that each
+            session's RAG receives its own isolated store
         splitter (langchain_text_splitters.base.TextSplitter): the text splitter of the RAG engine
         llm_name (str): the name of the LLM of the RAG engine. It must have been previously created and assigned to the
             agent
@@ -79,6 +84,7 @@ class RAG:
         k (int): number of chunks to retrieve from the vector store
         num_previous_messages (int): number of previous messages of the conversation to add to the LLM prompt context.
             Necessary a connection to :class:`~baf.db.monitoring_db.MonitoringDB`.
+        session_scoped (bool): True if each session should have its own RAG engine and vector store.
 
     Attributes:
         _nlp_engine (NLPEngine): the NLPEngine that handles the NLP processes of the agent the RAG engine belongs to
@@ -94,18 +100,22 @@ class RAG:
     """
 
     DEFAULT_LLM_PROMPT = "You are an assistant for question-answering tasks. Based on the previous messages in the conversation (if provided), and additional context retrieved from a database (if provided), answer the user question. If you don't know the answer, just say that you don't know. Note that if the question refers to a previous message, you may have to ignore the context since it is retrieved from the database based only on the question (the retrieval does not take into account the previous messages). Use three sentences maximum and keep the answer concise"
+    SUPPORTED_FORMATS = ('pdf', 'docx', 'txt', 'md')
 
     def __init__(
             self,
             agent: 'Agent',
-            vector_store: VectorStore,
+            vector_store: VectorStore | Callable[[], VectorStore],
             splitter: TextSplitter,
             llm_name: str,
             llm_prompt: str = None,
             k: int = 4,
-            num_previous_messages: int = 0
+            num_previous_messages: int = 0,
+            session_scoped: bool = False
     ):
         self._nlp_engine: 'NLPEngine' = agent.nlp_engine
+        if callable(vector_store) and not hasattr(vector_store, 'add_documents'):
+            vector_store = vector_store()
         self.vector_store: VectorStore = vector_store
         self.splitter: TextSplitter = splitter
         self.llm_name: str = llm_name
@@ -114,7 +124,43 @@ class RAG:
         self.llm_prompt = llm_prompt
         self.k: int = k
         self.num_previous_messages: int = num_previous_messages
-        self._nlp_engine._rag = self
+        if not session_scoped:
+            self._nlp_engine._rag = self
+    
+    def load_documents_from_path(path: str, fmt: str) -> list['Document']:
+        """Load raw (un-chunked) LangChain Documents from a file path.
+
+        Dispatches to the appropriate loader based on ``fmt``. Used internally by
+        :meth:`RAG.load_documents` and :meth:`RAG.add_file`.
+
+        Args:
+            path (str): path to the file on disk
+            fmt (str): lowercase file format
+
+        Returns:
+            list[Document]: raw LangChain Documents (not yet chunked)
+
+        Raises:
+            ValueError: if ``fmt`` is not in `RAG.SUPPORTED_FORMATS`
+            ImportError: if ``fmt`` is ``'docx'`` and python-docx is not installed
+        """
+        
+        if fmt not in RAG.SUPPORTED_FORMATS:
+            raise ValueError(f"Unsupported format '{fmt}'. Supported formats: {RAG.SUPPORTED_FORMATS}")
+        if fmt == 'pdf':
+            return PyPDFLoader(path).load()
+        elif fmt == 'docx':
+            try:
+                from docx import Document as DocxDocument
+            except ImportError:
+                raise ImportError('python-docx is required for DOCX support. Install with: pip install python-docx')
+            docx_doc = DocxDocument(path)
+            text = '\n'.join(p.text for p in docx_doc.paragraphs if p.text.strip())
+            return [Document(page_content=text, metadata={'source': os.path.basename(path)})]
+        elif fmt in ('txt', 'md'):
+            with open(path, 'r', encoding='utf-8') as f:
+                text = f.read()
+            return [Document(page_content=text, metadata={'source': os.path.basename(path)})]
 
     def load_pdfs(self, path: str) -> int:
         """Load PDF files from a given location into the RAG's vector store.
@@ -136,6 +182,92 @@ class RAG:
         self.vector_store.add_documents(chunked_documents)
         logger.info(f'[RAG] Added {n_chunks} chunks to RAG\'s vector store. Total: {len(self.vector_store.get()["documents"])}')
         return n_chunks
+    
+    def is_empty(self) -> bool:
+        """Return ``True`` if the vector store contains no documents.
+
+        Returns:
+            bool: ``True`` if the corpus is empty
+        """
+        return len(self.vector_store.get()['ids']) == 0
+
+    def clear(self) -> None:
+        """Remove all documents from the vector store."""
+        ids = self.vector_store.get()['ids']
+        if ids:
+            self.vector_store.delete(ids)
+        logger.info('[RAG] Vector store cleared')
+
+    def load_documents(self, path: str, formats: list[str] = None) -> int:
+        """Load documents from a directory into the RAG's vector store.
+
+        Supports multiple file formats. Use :meth:`load_pdfs` if only PDF loading is needed.
+
+        Args:
+            path (str): path to the directory containing the files
+            formats (list[str]): restrict loading to a subset of formats, e.g. ``['pdf', 'docx']``.
+                If ``None``, all `RAG.SUPPORTED_FORMATS` are loaded.
+
+        Returns:
+            int: the number of chunks added to the vector store
+        """
+        allowed = set(formats) if formats else set(RAG.SUPPORTED_FORMATS)
+        documents = []
+        for fname in os.listdir(path):
+            fmt = os.path.splitext(fname)[1].lower().lstrip('.')
+            if fmt in allowed:
+                documents.extend(RAG.load_documents_from_path(os.path.join(path, fname), fmt))
+        chunked_documents = self.splitter.split_documents(documents)
+        n_chunks = len(chunked_documents)
+        self.vector_store.add_documents(chunked_documents)
+        logger.info(f'[RAG] Added {n_chunks} chunks to RAG\'s vector store. Total: {len(self.vector_store.get()["documents"])}')
+        return n_chunks
+
+    def add_file(self, file: 'File') -> int:
+        """Extract text from a BAF :class:`~baf.core.file.File` object and add it to the RAG's vector store at runtime.
+
+        Args:
+            file (File): the BAF File object to load
+
+        Returns:
+            int: the number of chunks added to the vector store
+
+        Raises:
+            ValueError: if the file type is not in RAG.SUPPORTED_FORMATS`
+        """
+        fmt = (file.type or '').lower().lstrip('.')
+        if not fmt or '/' in fmt:  # MIME type (e.g. "application/pdf") — derive from filename
+            fmt = os.path.splitext(file.name or '')[1].lower().lstrip('.')
+        file_bytes = base64.b64decode(file.base64)
+        with tempfile.NamedTemporaryFile(suffix=f'.{fmt}', delete=False) as tmp:
+            tmp.write(file_bytes)
+            tmp_path = tmp.name
+        try:
+            documents = RAG.load_documents_from_path(tmp_path, fmt)
+        finally:
+            os.unlink(tmp_path)
+        chunked_documents = self.splitter.split_documents(documents)
+        n_chunks = len(chunked_documents)
+        self.vector_store.add_documents(chunked_documents)
+        logger.info(f'[RAG] Added {n_chunks} chunks from \'{file.name}\' to RAG\'s vector store.')
+        return n_chunks
+
+    def add_text(self, text: str, metadata: dict = None) -> int:
+        """Chunk a raw text string and add it to the RAG's vector store at runtime.
+
+        Args:
+            text (str): the raw text to add
+            metadata (dict): optional metadata to attach to each chunk
+
+        Returns:
+            int: the number of chunks added to the vector store
+        """
+        doc = Document(page_content=text, metadata=metadata or {})
+        chunked_documents = self.splitter.split_documents([doc])
+        n_chunks = len(chunked_documents)
+        self.vector_store.add_documents(chunked_documents)
+        logger.info(f'[RAG] Added {n_chunks} text chunks to RAG\'s vector store.')
+        return n_chunks
 
     def run_retrieval(self, question: str, k: int = None) -> list[Document]:
         """Run retrieval. Given a query, return the `k` most relevant documents (i.e., chunks) from the RAG's vector store.

{besser_agentic_framework-4.4.1 → besser_agentic_framework-4.4.2}/baf/platforms/websocket/streamlit_ui/chat.py

@@ -134,7 +134,7 @@ def write_message(message: Message, key_count: int, stream: bool = False):
                     for i, doc in enumerate(message.content['docs']):
                         st.write(f'**Document {i + 1}/{len(message.content["docs"])}**')
                         st.write(f'- **Source:** {doc["metadata"]["source"]}')
-                        st.write(f'- **Page:** {doc["metadata"]["page"]}')
+                        st.write(f'- **Page:** {doc["metadata"].get("page", "N/A")}')
                         st.write(f'- **Content:** {doc["content"]}')
 
         elif message.type == MessageType.REASONING_TRACE:

{besser_agentic_framework-4.4.1 → besser_agentic_framework-4.4.2}/baf/test/examples/rag_agent.py

@@ -3,7 +3,9 @@
 # sys.path.append("/Path/to/directory/agentic-framework") # Replace with your directory path
 
 import logging
+import uuid
 
+from chromadb import EphemeralClient
 from langchain_community.embeddings import OpenAIEmbeddings
 from langchain_community.vectorstores import Chroma
 from langchain_text_splitters import RecursiveCharacterTextSplitter
@@ -12,10 +14,12 @@ from baf import nlp
 from baf.core.agent import Agent
 from baf.core.session import Session
 from baf.exceptions.logger import logger
+from baf.library.transition.events.base_events import ReceiveFileEvent
 from baf.nlp.llm.llm_huggingface_api import LLMHuggingFaceAPI
 from baf.nlp.llm.llm_openai_api import LLMOpenAI
 from baf.nlp.llm.llm_replicate_api import LLMReplicate
 from baf.nlp.rag.rag import RAGMessage, RAG
+from baf.library.transition.events.base_events import ReceiveTextEvent, ReceiveMessageEvent, ReceiveFileEvent
 
 # Configure the logging module (optional)
 logger.setLevel(logging.INFO)
@@ -27,11 +31,10 @@ agent.load_properties('config.yaml')
 # Define the platform your agent will use
 websocket_platform = agent.use_websocket_platform(use_ui=True)
 
-# Create Vector Store (RAG's DB)
-vector_store: Chroma = Chroma(
-    embedding_function=OpenAIEmbeddings(openai_api_key=agent.get_property(nlp.OPENAI_API_KEY)),
-    persist_directory='vector_store'
-)
+#To keep RAG as session scoped or not
+SESSION_SCOPED=True
+
+
 # Create text splitter (RAG creates a vector for each chunk)
 splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=100)
 # Create the LLM (for the answer generation)
@@ -57,33 +60,43 @@ rag = RAG(
     k=4,
     num_previous_messages=0
 )
-# Uncomment to fill the DB
-# rag.load_pdfs('./pdfs')
+# Uncomment the relevant line to directly provide text to RAG instead of uploading at runtime
+# rag.load_documents('C:/Users/chidambaram/Downloads/example', formats=['docx'])   # read all the files of the given format in the directory
+# rag.add_text('raw text to index and base your RAG on.') # add a text string directly
+
+# If not uploading at runtime, comment the following function, L84, L87 and L88, and uncomment L85. 
+def upload_file_body(session: Session):
+    rag.add_file(session.event.file)
+
 
 # STATES
 
 initial_state = agent.new_state('initial_state', initial=True)
-rag_state = agent.new_state('rag_state')
+upload_file_state = agent.new_state('upload_file_state')
+ask_question_state = agent.new_state('ask_question_state')
 
 
 # STATES BODIES' DEFINITION + TRANSITIONS
 
 def initial_body(session: Session):
-    session.reply('Hi!')
+    session.reply('Hi!, upload a file to use as RAG context. If already done, ask your question.')
 
 
 initial_state.set_body(initial_body)
-# TODO : fix no_intent_matched
-initial_state.when_no_intent_matched().go_to(rag_state)
+initial_state.when_event(ReceiveFileEvent()).go_to(upload_file_state)
+# initial_state.when_no_intent_matched().go_to(ask_question_state)
+
+upload_file_state.set_body(upload_file_body)
+upload_file_state.when_no_intent_matched().go_to(ask_question_state)
 
 
-def rag_body(session: Session):
+def ask_question_body(session: Session):
     rag_message: RAGMessage = session.run_rag(session.event.message)
     websocket_platform.reply_rag(session, rag_message)
 
 
-rag_state.set_body(rag_body)
-rag_state.go_to(initial_state)
+ask_question_state.set_body(ask_question_body)
+ask_question_state.go_to(initial_state)
 
 
 # RUN APPLICATION

{besser_agentic_framework-4.4.1 → besser_agentic_framework-4.4.2/besser_agentic_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: besser-agentic-framework
-Version: 4.4.1
+Version: 4.4.2
 Summary: BESSER Agentic Framework (BAF)
 Author: Luxembourg Institute of Science and Technology
 License: MIT
@@ -51,6 +51,7 @@ Requires-Dist: langchain-community==0.2.7; python_version < "3.13" and extra ==
 Requires-Dist: langchain==0.3.10; python_version >= "3.13" and extra == "extras"
 Requires-Dist: langchain-community==0.3.10; python_version >= "3.13" and extra == "extras"
 Requires-Dist: pypdf==4.3.1; extra == "extras"
+Requires-Dist: python-docx==1.2.0; extra == "extras"
 Requires-Dist: tiktoken==0.9.0; extra == "extras"
 Provides-Extra: llms
 Requires-Dist: openai==1.93.0; extra == "llms"
@@ -83,6 +84,7 @@ Requires-Dist: langchain-community==0.2.7; python_version < "3.13" and extra ==
 Requires-Dist: langchain==0.3.10; python_version >= "3.13" and extra == "all"
 Requires-Dist: langchain-community==0.3.10; python_version >= "3.13" and extra == "all"
 Requires-Dist: pypdf==4.3.1; extra == "all"
+Requires-Dist: python-docx==1.2.0; extra == "all"
 Requires-Dist: tiktoken==0.9.0; extra == "all"
 Requires-Dist: openai==1.93.0; extra == "all"
 Requires-Dist: replicate==0.23.1; extra == "all"

{besser_agentic_framework-4.4.1 → besser_agentic_framework-4.4.2}/besser_agentic_framework.egg-info/requires.txt

@@ -37,6 +37,7 @@ soundfile==0.13.1
 opencv-python==4.10.0.84
 plotly==5.18.0
 pypdf==4.3.1
+python-docx==1.2.0
 tiktoken==0.9.0
 openai==1.93.0
 replicate==0.23.1
@@ -71,6 +72,7 @@ soundfile==0.13.1
 opencv-python==4.10.0.84
 plotly==5.18.0
 pypdf==4.3.1
+python-docx==1.2.0
 tiktoken==0.9.0
 
 [extras:python_version < "3.13"]

{besser_agentic_framework-4.4.1 → besser_agentic_framework-4.4.2}/requirements/requirements-extras.txt

@@ -24,4 +24,5 @@ langchain-community==0.2.7; python_version < "3.13"
 langchain==0.3.10; python_version >= "3.13"
 langchain-community==0.3.10; python_version >= "3.13"
 pypdf==4.3.1
+python-docx==1.2.0
 tiktoken==0.9.0

{besser_agentic_framework-4.4.1 → besser_agentic_framework-4.4.2}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = besser-agentic-framework
-version = 4.4.1
+version = 4.4.2
 author = Luxembourg Institute of Science and Technology
 description = BESSER Agentic Framework (BAF)
 long_description = file: README.md