agno 2.2.13__py3-none-any.whl → 2.4.3__py3-none-any.whl

agno/knowledge/protocol.py

@@ -0,0 +1,134 @@
+"""
+Knowledge Protocol
+==================
+Defines the minimal interface that knowledge implementations must implement.
+
+This protocol enables:
+- Custom knowledge bases to be used with agents
+- Each implementation defines its own tools and context
+- Flexible tool naming (not forced to use 'search')
+- Type safety with Protocol typing
+"""
+
+from typing import Callable, List, Protocol, runtime_checkable
+
+from agno.knowledge.document import Document
+
+
+@runtime_checkable
+class KnowledgeProtocol(Protocol):
+    """Minimal protocol for knowledge implementations.
+
+    Enables custom knowledge bases to be used with agents.
+    Each implementation defines what tools it exposes and what
+    context/instructions it provides to the agent.
+
+    Required methods:
+    - build_context(): Return instructions for the agent's system prompt
+    - get_tools(): Return tools to expose to the agent
+    - aget_tools(): Async version of get_tools
+
+    Optional methods:
+    - retrieve(): Default retrieval for context injection (add_knowledge_to_context)
+    - aretrieve(): Async version of retrieve
+
+    Example:
+        ```python
+        from agno.knowledge.protocol import KnowledgeProtocol
+        from agno.knowledge.document import Document
+
+        class MyKnowledge:
+            def build_context(self, **kwargs) -> str:
+                return "Use search_docs to find information."
+
+            def get_tools(self, **kwargs) -> List[Callable]:
+                return [self.search_docs]
+
+            async def aget_tools(self, **kwargs) -> List[Callable]:
+                return [self.search_docs]
+
+            def search_docs(self, query: str) -> str:
+                # Your search implementation
+                return "Results for: " + query
+
+            # Optional: for add_knowledge_to_context feature
+            def retrieve(self, query: str, **kwargs) -> List[Document]:
+                results = self._internal_search(query)
+                return [Document(content=r) for r in results]
+
+        # MyKnowledge satisfies KnowledgeProtocol
+        agent = Agent(knowledge=MyKnowledge())
+        ```
+    """
+
+    def build_context(self, **kwargs) -> str:
+        """Build context string for the agent's system prompt.
+
+        Returns instructions about how to use this knowledge,
+        what tools are available, and any usage guidelines.
+
+        Args:
+            **kwargs: Context including enable_agentic_filters, etc.
+
+        Returns:
+            Formatted context string to inject into system prompt.
+        """
+        ...
+
+    def get_tools(self, **kwargs) -> List[Callable]:
+        """Get tools to expose to the agent.
+
+        Returns callable tools that the agent can use to interact
+        with this knowledge. Each implementation decides what
+        tools make sense (e.g., search, grep, list_files, query_db).
+
+        Args:
+            **kwargs: Context including run_response, run_context,
+                     async_mode, enable_agentic_filters, agent, etc.
+
+        Returns:
+            List of callable tools.
+        """
+        ...
+
+    async def aget_tools(self, **kwargs) -> List[Callable]:
+        """Async version of get_tools.
+
+        Args:
+            **kwargs: Same as get_tools.
+
+        Returns:
+            List of callable tools.
+        """
+        ...
+
+    # Optional methods - used by add_knowledge_to_context feature
+    # Implementations that don't support context injection can omit these
+
+    def retrieve(self, query: str, **kwargs) -> List[Document]:
+        """Retrieve documents for context injection.
+
+        Used by the add_knowledge_to_context feature to pre-fetch
+        relevant documents into the user message. This is optional;
+        if not implemented, add_knowledge_to_context will be skipped.
+
+        Args:
+            query: The query string.
+            **kwargs: Additional parameters (max_results, filters, etc.)
+
+        Returns:
+            List of Document objects.
+        """
+        ...
+
+    async def aretrieve(self, query: str, **kwargs) -> List[Document]:
+        """Async version of retrieve.
+
+        Args:
+            query: The query string.
+            **kwargs: Additional parameters.
+
+        Returns:
+            List of Document objects.
+        """
+        ...

agno/knowledge/reader/arxiv_reader.py

@@ -17,9 +17,10 @@ class ArxivReader(Reader):
     sort_by: arxiv.SortCriterion = arxiv.SortCriterion.Relevance
 
     @classmethod
-    def get_supported_chunking_strategies(self) -> List[ChunkingStrategyType]:
+    def get_supported_chunking_strategies(cls) -> List[ChunkingStrategyType]:
         """Get the list of supported chunking strategies for Arxiv readers."""
         return [
+            ChunkingStrategyType.CODE_CHUNKER,
             ChunkingStrategyType.FIXED_SIZE_CHUNKER,
             ChunkingStrategyType.AGENTIC_CHUNKER,
             ChunkingStrategyType.DOCUMENT_CHUNKER,
@@ -28,7 +29,7 @@ class ArxivReader(Reader):
         ]
 
     @classmethod
-    def get_supported_content_types(self) -> List[ContentType]:
+    def get_supported_content_types(cls) -> List[ContentType]:
         return [ContentType.TOPIC]
 
     def __init__(

agno/knowledge/reader/base.py

@@ -73,11 +73,17 @@ class Reader:
     def chunk_document(self, document: Document) -> List[Document]:
         if self.chunking_strategy is None:
             self.chunking_strategy = FixedSizeChunking(chunk_size=self.chunk_size)
-        return self.chunking_strategy.chunk(document)  # type: ignore
+        return self.chunking_strategy.chunk(document)
+
+    async def achunk_document(self, document: Document) -> List[Document]:
+        """Async version of chunk_document."""
+        if self.chunking_strategy is None:
+            self.chunking_strategy = FixedSizeChunking(chunk_size=self.chunk_size)
+        return await self.chunking_strategy.achunk(document)
 
     async def chunk_documents_async(self, documents: List[Document]) -> List[Document]:
         """
-        Asynchronously chunk a list of documents using the instance's chunk_document method.
+        Asynchronously chunk a list of documents.
 
         Args:
             documents: List of documents to be chunked.
@@ -85,11 +91,7 @@ class Reader:
         Returns:
             A flattened list of chunked documents.
         """
-
-        async def _chunk_document_async(doc: Document) -> List[Document]:
-            return await asyncio.to_thread(self.chunk_document, doc)
-
         # Process chunking in parallel for all documents
-        chunked_lists = await asyncio.gather(*[_chunk_document_async(doc) for doc in documents])
+        chunked_lists = await asyncio.gather(*[self.achunk_document(doc) for doc in documents])
         # Flatten the result
         return [chunk for sublist in chunked_lists for chunk in sublist]

agno/knowledge/reader/csv_reader.py

@@ -14,21 +14,42 @@ from agno.knowledge.chunking.row import RowChunking
 from agno.knowledge.chunking.strategy import ChunkingStrategy, ChunkingStrategyType
 from agno.knowledge.document.base import Document
 from agno.knowledge.reader.base import Reader
+from agno.knowledge.reader.utils import stringify_cell_value
 from agno.knowledge.types import ContentType
-from agno.utils.log import logger
+from agno.utils.log import log_debug, log_error
 
 
 class CSVReader(Reader):
-    """Reader for CSV files"""
+    """Reader for CSV files.
+
+    Converts CSV files to documents with optional chunking support.
+    For Excel files (.xlsx, .xls), use ExcelReader instead.
+
+    Args:
+        chunking_strategy: Strategy for chunking documents. Default is RowChunking.
+        **kwargs: Additional arguments passed to base Reader.
+
+    Example:
+        ```python
+        from agno.knowledge.reader.csv_reader import CSVReader
+
+        reader = CSVReader()
+        docs = reader.read("data.csv")
+
+        # Custom delimiter
+        docs = reader.read("data.tsv", delimiter="\\t")
+        ```
+    """
 
     def __init__(self, chunking_strategy: Optional[ChunkingStrategy] = RowChunking(), **kwargs):
         super().__init__(chunking_strategy=chunking_strategy, **kwargs)
 
     @classmethod
-    def get_supported_chunking_strategies(self) -> List[ChunkingStrategyType]:
+    def get_supported_chunking_strategies(cls) -> List[ChunkingStrategyType]:
         """Get the list of supported chunking strategies for CSV readers."""
         return [
             ChunkingStrategyType.ROW_CHUNKER,
+            ChunkingStrategyType.CODE_CHUNKER,
             ChunkingStrategyType.FIXED_SIZE_CHUNKER,
             ChunkingStrategyType.AGENTIC_CHUNKER,
             ChunkingStrategyType.DOCUMENT_CHUNKER,
@@ -36,39 +57,54 @@ class CSVReader(Reader):
         ]
 
     @classmethod
-    def get_supported_content_types(self) -> List[ContentType]:
-        return [ContentType.CSV, ContentType.XLSX, ContentType.XLS]
+    def get_supported_content_types(cls) -> List[ContentType]:
+        """Get the list of supported content types."""
+        return [ContentType.CSV]
 
     def read(
         self, file: Union[Path, IO[Any]], delimiter: str = ",", quotechar: str = '"', name: Optional[str] = None
     ) -> List[Document]:
+        """Read a CSV file and return a list of documents.
+
+        Args:
+            file: Path to CSV file or file-like object.
+            delimiter: CSV field delimiter. Default is comma.
+            quotechar: CSV quote character. Default is double quote.
+            name: Optional name override for the document.
+
+        Returns:
+            List of Document objects.
+
+        Raises:
+            FileNotFoundError: If the file path doesn't exist.
+        """
         try:
             if isinstance(file, Path):
                 if not file.exists():
                     raise FileNotFoundError(f"Could not find file: {file}")
-                logger.info(f"Reading: {file}")
-                file_content = file.open(newline="", mode="r", encoding=self.encoding or "utf-8")
+                log_debug(f"Reading: {file}")
+                csv_name = name or file.stem
+                file_content: Union[io.TextIOWrapper, io.StringIO] = file.open(
+                    newline="", mode="r", encoding=self.encoding or "utf-8"
+                )
             else:
-                logger.info(f"Reading retrieved file: {name or file.name}")
+                log_debug(f"Reading retrieved file: {getattr(file, 'name', 'BytesIO')}")
+                csv_name = name or getattr(file, "name", "csv_file").split(".")[0]
                 file.seek(0)
-                file_content = io.StringIO(file.read().decode("utf-8"))  # type: ignore
-
-            csv_name = name or (
-                Path(file.name).stem
-                if isinstance(file, Path)
-                else (getattr(file, "name", "csv_file").split(".")[0] if hasattr(file, "name") else "csv_file")
-            )
-            csv_content = ""
+                file_content = io.StringIO(file.read().decode(self.encoding or "utf-8"))
+
+            csv_lines: List[str] = []
             with file_content as csvfile:
                 csv_reader = csv.reader(csvfile, delimiter=delimiter, quotechar=quotechar)
                 for row in csv_reader:
-                    csv_content += ", ".join(row) + "\n"
+                    # Normalize line endings in CSV cells to preserve row integrity
+                    csv_lines.append(", ".join(stringify_cell_value(cell) for cell in row))
 
             documents = [
                 Document(
                     name=csv_name,
                     id=str(uuid4()),
-                    content=csv_content,
+                    content="\n".join(csv_lines),
                 )
             ]
             if self.chunk:
@@ -77,8 +113,15 @@ class CSVReader(Reader):
                     chunked_documents.extend(self.chunk_document(document))
                 return chunked_documents
             return documents
+        except FileNotFoundError:
+            raise
+        except UnicodeDecodeError as e:
+            file_desc = getattr(file, "name", str(file)) if isinstance(file, IO) else file
+            log_error(f"Encoding error reading {file_desc}: {e}. Try specifying a different encoding.")
+            return []
         except Exception as e:
-            logger.error(f"Error reading: {getattr(file, 'name', str(file)) if isinstance(file, IO) else file}: {e}")
+            file_desc = getattr(file, "name", str(file)) if isinstance(file, IO) else file
+            log_error(f"Error reading {file_desc}: {e}")
             return []
 
     async def async_read(
@@ -89,36 +132,35 @@ class CSVReader(Reader):
         page_size: int = 1000,
         name: Optional[str] = None,
     ) -> List[Document]:
-        """
-        Read a CSV file asynchronously, processing batches of rows concurrently.
+        """Read a CSV file asynchronously, processing batches of rows concurrently.
 
         Args:
-            file: Path or file-like object
-            delimiter: CSV delimiter
-            quotechar: CSV quote character
-            page_size: Number of rows per page
+            file: Path to CSV file or file-like object.
+            delimiter: CSV field delimiter. Default is comma.
+            quotechar: CSV quote character. Default is double quote.
+            page_size: Number of rows per page for large files.
+            name: Optional name override for the document.
 
         Returns:
-            List of Document objects
+            List of Document objects.
+
+        Raises:
+            FileNotFoundError: If the file path doesn't exist.
         """
         try:
             if isinstance(file, Path):
                 if not file.exists():
                     raise FileNotFoundError(f"Could not find file: {file}")
-                logger.info(f"Reading async: {file}")
-                async with aiofiles.open(file, mode="r", encoding="utf-8", newline="") as file_content:
+                log_debug(f"Reading async: {file}")
+                async with aiofiles.open(file, mode="r", encoding=self.encoding or "utf-8", newline="") as file_content:
                     content = await file_content.read()
                     file_content_io = io.StringIO(content)
+                csv_name = name or file.stem
             else:
-                logger.info(f"Reading retrieved file async: {file.name}")
+                log_debug(f"Reading retrieved file async: {getattr(file, 'name', 'BytesIO')}")
                 file.seek(0)
-                file_content_io = io.StringIO(file.read().decode("utf-8"))  # type: ignore
-
-            csv_name = name or (
-                Path(file.name).stem
-                if isinstance(file, Path)
-                else (getattr(file, "name", "csv_file").split(".")[0] if hasattr(file, "name") else "csv_file")
-            )
+                file_content_io = io.StringIO(file.read().decode(self.encoding or "utf-8"))
+                csv_name = name or getattr(file, "name", "csv_file").split(".")[0]
 
             file_content_io.seek(0)
             csv_reader = csv.reader(file_content_io, delimiter=delimiter, quotechar=quotechar)
@@ -126,7 +168,8 @@ class CSVReader(Reader):
             total_rows = len(rows)
 
             if total_rows <= 10:
-                csv_content = " ".join(", ".join(row) for row in rows)
+                # Small files: single document
+                csv_content = " ".join(", ".join(stringify_cell_value(cell) for cell in row) for row in rows)
                 documents = [
                     Document(
                         name=csv_name,
@@ -135,14 +178,15 @@ class CSVReader(Reader):
                     )
                 ]
             else:
+                # Large files: paginate and process in parallel
                 pages = []
                 for i in range(0, total_rows, page_size):
                     pages.append(rows[i : i + page_size])
 
                 async def _process_page(page_number: int, page_rows: List[List[str]]) -> Document:
-                    """Process a page of rows into a document"""
+                    """Process a page of rows into a document."""
                     start_row = (page_number - 1) * page_size + 1
-                    page_content = " ".join(", ".join(row) for row in page_rows)
+                    page_content = " ".join(", ".join(stringify_cell_value(cell) for cell in row) for row in page_rows)
 
                     return Document(
                         name=csv_name,
@@ -159,8 +203,13 @@ class CSVReader(Reader):
                 documents = await self.chunk_documents_async(documents)
 
             return documents
+        except FileNotFoundError:
+            raise
+        except UnicodeDecodeError as e:
+            file_desc = getattr(file, "name", str(file)) if isinstance(file, IO) else file
+            log_error(f"Encoding error reading {file_desc}: {e}. Try specifying a different encoding.")
+            return []
         except Exception as e:
-            logger.error(
-                f"Error reading async: {getattr(file, 'name', str(file)) if isinstance(file, IO) else file}: {e}"
-            )
+            file_desc = getattr(file, "name", str(file)) if isinstance(file, IO) else file
+            log_error(f"Error reading {file_desc}: {e}")
             return []

agno/knowledge/reader/docx_reader.py

@@ -8,7 +8,7 @@ from agno.knowledge.chunking.strategy import ChunkingStrategy, ChunkingStrategyT
 from agno.knowledge.document.base import Document
 from agno.knowledge.reader.base import Reader
 from agno.knowledge.types import ContentType
-from agno.utils.log import log_info, logger
+from agno.utils.log import log_debug, log_error
 
 try:
     from docx import Document as DocxDocument  # type: ignore
@@ -23,10 +23,11 @@ class DocxReader(Reader):
         super().__init__(chunking_strategy=chunking_strategy, **kwargs)
 
     @classmethod
-    def get_supported_chunking_strategies(self) -> List[ChunkingStrategyType]:
+    def get_supported_chunking_strategies(cls) -> List[ChunkingStrategyType]:
         """Get the list of supported chunking strategies for DOCX readers."""
         return [
             ChunkingStrategyType.DOCUMENT_CHUNKER,
+            ChunkingStrategyType.CODE_CHUNKER,
             ChunkingStrategyType.FIXED_SIZE_CHUNKER,
             ChunkingStrategyType.SEMANTIC_CHUNKER,
             ChunkingStrategyType.AGENTIC_CHUNKER,
@@ -34,7 +35,7 @@ class DocxReader(Reader):
         ]
 
     @classmethod
-    def get_supported_content_types(self) -> List[ContentType]:
+    def get_supported_content_types(cls) -> List[ContentType]:
         return [ContentType.DOCX, ContentType.DOC]
 
     def read(self, file: Union[Path, IO[Any]], name: Optional[str] = None) -> List[Document]:
@@ -43,15 +44,13 @@ class DocxReader(Reader):
             if isinstance(file, Path):
                 if not file.exists():
                     raise FileNotFoundError(f"Could not find file: {file}")
-                log_info(f"Reading: {file}")
+                log_debug(f"Reading: {file}")
                 docx_document = DocxDocument(str(file))
                 doc_name = name or file.stem
             else:
-                log_info(f"Reading uploaded file: {getattr(file, 'name', 'docx_file')}")
+                log_debug(f"Reading uploaded file: {getattr(file, 'name', 'BytesIO')}")
                 docx_document = DocxDocument(file)
-                doc_name = name or (
-                    getattr(file, "name", "docx_file").split(".")[0] if hasattr(file, "name") else "docx_file"
-                )
+                doc_name = name or getattr(file, "name", "docx_file").split(".")[0]
 
             doc_content = "\n\n".join([para.text for para in docx_document.paragraphs])
 
@@ -70,7 +69,7 @@ class DocxReader(Reader):
             return documents
 
         except Exception as e:
-            logger.error(f"Error reading file: {e}")
+            log_error(f"Error reading file: {e}")
             return []
 
     async def async_read(self, file: Union[Path, IO[Any]], name: Optional[str] = None) -> List[Document]:
@@ -78,5 +77,5 @@ class DocxReader(Reader):
         try:
             return await asyncio.to_thread(self.read, file, name)
         except Exception as e:
-            logger.error(f"Error reading file asynchronously: {e}")
+            log_error(f"Error reading file asynchronously: {e}")
             return []