agno 0.1.2__py3-none-any.whl → 2.3.13__py3-none-any.whl

agno/hooks/decorator.py

@@ -0,0 +1,164 @@
+from functools import wraps
+from typing import Any, Callable, TypeVar, Union, overload
+
+# Type variable for better type hints
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Attribute name used to mark hooks for background execution
+HOOK_RUN_IN_BACKGROUND_ATTR = "_agno_run_in_background"
+
+
+def _is_async_function(func: Callable) -> bool:
+    """
+    Check if a function is async, even when wrapped by decorators like @staticmethod.
+    Traverses the full wrapper chain to find the original function.
+    """
+    from inspect import iscoroutinefunction, unwrap
+
+    # First, try the standard inspect function on the wrapper
+    if iscoroutinefunction(func):
+        return True
+
+    # Use unwrap to traverse the full __wrapped__ chain to the original function
+    try:
+        original_func = unwrap(func)
+        if original_func is not func and iscoroutinefunction(original_func):
+            return True
+    except ValueError:
+        # unwrap raises ValueError if it hits a cycle
+        pass
+
+    # Check if the function has CO_COROUTINE flag in its code object
+    try:
+        if hasattr(func, "__code__") and func.__code__.co_flags & 0x80:  # CO_COROUTINE flag
+            return True
+    except (AttributeError, TypeError):
+        pass
+
+    return False
+
+
+@overload
+def hook() -> Callable[[F], F]: ...
+
+
+@overload
+def hook(
+    *,
+    run_in_background: bool = False,
+) -> Callable[[F], F]: ...
+
+
+@overload
+def hook(func: F) -> F: ...
+
+
+def hook(*args, **kwargs) -> Union[F, Callable[[F], F]]:
+    """Decorator to configure hook behavior.
+
+    Args:
+        run_in_background: If True, this hook will be scheduled as a FastAPI background task
+                          when background_tasks is available, regardless of the agent/team's
+                          run_hooks_in_background setting. This allows per-hook control over
+                          background execution.  This is only use-able when running with AgentOS.
+
+    Returns:
+        Union[F, Callable[[F], F]]: Decorated function or decorator
+
+    Examples:
+        @hook
+        def my_hook(run_output, agent):
+            # This runs normally (blocking)
+            process_output(run_output.content)
+
+        @hook()
+        def another_hook(run_output, agent):
+            # Same as above - runs normally
+            process_output(run_output.content)
+
+        @hook(run_in_background=True)
+        def my_background_hook(run_output, agent):
+            # This will run in the background when background_tasks is available
+            send_notification(run_output.content)
+
+        @hook(run_in_background=True)
+        async def my_async_background_hook(run_output, agent):
+            # Async hooks also supported
+            await send_async_notification(run_output.content)
+
+        agent = Agent(
+            model=OpenAIChat(id="gpt-4o"),
+            post_hooks=[my_hook, my_background_hook],
+        )
+    """
+    # Valid kwargs for the hook decorator
+    VALID_KWARGS = frozenset({"run_in_background"})
+
+    # Validate kwargs
+    invalid_kwargs = set(kwargs.keys()) - VALID_KWARGS
+    if invalid_kwargs:
+        raise ValueError(
+            f"Invalid hook configuration arguments: {invalid_kwargs}. Valid arguments are: {sorted(VALID_KWARGS)}"
+        )
+
+    def decorator(func: F) -> F:
+        run_in_background = kwargs.get("run_in_background", False)
+
+        # Preserve existing hook attributes from previously applied decorators
+        # Use OR logic: if any decorator sets run_in_background=True, it stays True
+        existing_run_in_background = should_run_in_background(func)
+        final_run_in_background = run_in_background or existing_run_in_background
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return func(*args, **kwargs)
+
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return await func(*args, **kwargs)
+
+        # Choose appropriate wrapper based on function type
+        if _is_async_function(func):
+            wrapper = async_wrapper
+        else:
+            wrapper = sync_wrapper
+
+        # Set the background execution attribute (combined from all decorators)
+        setattr(wrapper, HOOK_RUN_IN_BACKGROUND_ATTR, final_run_in_background)
+
+        return wrapper  # type: ignore
+
+    # Handle both @hook and @hook() cases
+    if len(args) == 1 and callable(args[0]) and not kwargs:
+        return decorator(args[0])
+
+    return decorator
+
+
+def should_run_in_background(hook_func: Callable) -> bool:
+    """
+    Check if a hook function is marked to run in background.
+    Traverses the wrapper chain to find the attribute when multiple decorators are stacked.
+
+    Args:
+        hook_func: The hook function to check
+
+    Returns:
+        True if the hook is decorated with @hook(run_in_background=True)
+    """
+    # Check the function directly first
+    if hasattr(hook_func, HOOK_RUN_IN_BACKGROUND_ATTR):
+        return getattr(hook_func, HOOK_RUN_IN_BACKGROUND_ATTR)
+
+    # Traverse the wrapper chain to find the attribute
+    current = hook_func
+    seen: set[int] = set()
+    while hasattr(current, "__wrapped__"):
+        if id(current) in seen:
+            break
+        seen.add(id(current))
+        current = current.__wrapped__
+        if hasattr(current, HOOK_RUN_IN_BACKGROUND_ATTR):
+            return getattr(current, HOOK_RUN_IN_BACKGROUND_ATTR)
+
+    return False

agno/integrations/discord/__init__.py

@@ -0,0 +1,3 @@
+from agno.integrations.discord.client import DiscordClient
+
+__all__ = ["DiscordClient"]

agno/integrations/discord/client.py

@@ -0,0 +1,203 @@
+from os import getenv
+from textwrap import dedent
+from typing import Optional, Union
+
+import requests
+
+from agno.agent.agent import Agent, RunOutput
+from agno.media import Audio, File, Image, Video
+from agno.team.team import Team, TeamRunOutput
+from agno.utils.log import log_info, log_warning
+from agno.utils.message import get_text_from_message
+
+try:
+    import discord
+
+except (ImportError, ModuleNotFoundError):
+    raise ImportError("`discord.py` not installed. Please install using `pip install discord.py`")
+
+
+class RequiresConfirmationView(discord.ui.View):
+    def __init__(self):
+        super().__init__()
+        self.value = None
+
+    @discord.ui.button(label="Confirm", style=discord.ButtonStyle.primary)
+    async def confirm(
+        self,
+        interaction: discord.Interaction,
+        button: discord.ui.Button,
+    ):
+        self.value = True
+        button.disabled = True
+        await interaction.response.edit_message(view=self)
+        self.clear_items()
+        self.stop()
+
+    @discord.ui.button(label="Cancel", style=discord.ButtonStyle.secondary)
+    async def cancel(
+        self,
+        interaction: discord.Interaction,
+        button: discord.ui.Button,
+    ):
+        self.value = False
+        button.disabled = True
+        await interaction.response.edit_message(view=self)
+        self.clear_items()
+        self.stop()
+
+    async def on_timeout(self):
+        log_warning("Agent Timeout Error")
+
+
+class DiscordClient:
+    def __init__(
+        self, agent: Optional[Agent] = None, team: Optional[Team] = None, client: Optional[discord.Client] = None
+    ):
+        self.agent = agent
+        self.team = team
+        if client is None:
+            self.intents = discord.Intents.all()
+            self.client = discord.Client(intents=self.intents)
+        else:
+            self.client = client
+        self._setup_events()
+
+    def _setup_events(self):
+        @self.client.event
+        async def on_message(message):
+            if message.author == self.client.user:
+                log_info(f"sent {message.content}")
+                return
+
+            message_image = None
+            message_video = None
+            message_audio = None
+            message_file = None
+            media_url = None
+            message_text = message.content
+            message_url = message.jump_url
+            message_user = message.author.name
+            message_user_id = message.author.id
+
+            if message.attachments:
+                media = message.attachments[0]
+                media_type = media.content_type
+                media_url = media.url
+                if media_type.startswith("image/"):
+                    message_image = media_url
+                elif media_type.startswith("video/"):
+                    req = requests.get(media_url)
+                    video = req.content
+                    message_video = video
+                elif media_type.startswith("application/"):
+                    req = requests.get(media_url)
+                    document = req.content
+                    message_file = document
+                elif media_type.startswith("audio/"):
+                    message_audio = media_url
+
+            log_info(f"processing message:{message_text} \n with media: {media_url} \n url:{message_url}")
+            if isinstance(message.channel, discord.Thread):
+                thread = message.channel
+            elif isinstance(message.channel, discord.channel.DMChannel):
+                thread = message.channel  # type: ignore
+            elif isinstance(message.channel, discord.TextChannel):
+                thread = await message.create_thread(name=f"{message_user}'s thread")
+            else:
+                log_info(f"received {message.content} but not in a supported channel")
+                return
+
+            async with thread.typing():
+                # TODO Unhappy with the duplication here but it keeps MyPy from complaining
+                additional_context = dedent(f"""
+                    Discord username: {message_user}
+                    Discord userid: {message_user_id} 
+                    Discord url: {message_url}
+                    """)
+                if self.agent:
+                    self.agent.additional_context = additional_context
+                    agent_response: RunOutput = await self.agent.arun(
+                        input=message_text,
+                        user_id=message_user_id,
+                        session_id=str(thread.id),
+                        images=[Image(url=message_image)] if message_image else None,
+                        videos=[Video(content=message_video)] if message_video else None,
+                        audio=[Audio(url=message_audio)] if message_audio else None,
+                        files=[File(content=message_file)] if message_file else None,
+                    )
+                    await self._handle_response_in_thread(agent_response, thread)
+                elif self.team:
+                    self.team.additional_context = additional_context
+                    team_response: TeamRunOutput = await self.team.arun(
+                        input=message_text,
+                        user_id=message_user_id,
+                        session_id=str(thread.id),
+                        images=[Image(url=message_image)] if message_image else None,
+                        videos=[Video(content=message_video)] if message_video else None,
+                        audio=[Audio(url=message_audio)] if message_audio else None,
+                        files=[File(content=message_file)] if message_file else None,
+                    )
+                    await self._handle_response_in_thread(team_response, thread)
+
+    async def handle_hitl(
+        self, run_response: RunOutput, thread: Union[discord.Thread, discord.TextChannel]
+    ) -> RunOutput:
+        """Handles optional Human-In-The-Loop interaction."""
+        if run_response.is_paused:
+            for tool in run_response.tools_requiring_confirmation:
+                view = RequiresConfirmationView()
+                await thread.send(f"Tool requiring confirmation: {tool.tool_name}", view=view)
+                await view.wait()
+                tool.confirmed = view.value if view.value is not None else False
+
+            if self.agent:
+                run_response = await self.agent.acontinue_run(
+                    run_response=run_response,
+                )
+
+        return run_response
+
+    async def _handle_response_in_thread(
+        self, response: Union[RunOutput, TeamRunOutput], thread: Union[discord.TextChannel, discord.Thread]
+    ):
+        if isinstance(response, RunOutput):
+            response = await self.handle_hitl(response, thread)
+
+        if response.reasoning_content:
+            await self._send_discord_messages(
+                thread=thread, message=f"Reasoning: \n{response.reasoning_content}", italics=True
+            )
+
+        # Handle structured outputs properly
+        content_message = get_text_from_message(response.content) if response.content is not None else ""
+
+        await self._send_discord_messages(thread=thread, message=content_message)
+
+    async def _send_discord_messages(self, thread: discord.channel, message: str, italics: bool = False):  # type: ignore
+        if len(message) < 1500:
+            if italics:
+                formatted_message = "\n".join([f"_{line}_" for line in message.split("\n")])
+                await thread.send(formatted_message)  # type: ignore
+            else:
+                await thread.send(message)  # type: ignore
+            return
+
+        message_batches = [message[i : i + 1500] for i in range(0, len(message), 1500)]
+
+        for i, batch in enumerate(message_batches, 1):
+            batch_message = f"[{i}/{len(message_batches)}] {batch}"
+            if italics:
+                formatted_batch = "\n".join([f"_{line}_" for line in batch_message.split("\n")])
+                await thread.send(formatted_batch)  # type: ignore
+            else:
+                await thread.send(batch_message)  # type: ignore
+
+    def serve(self):
+        try:
+            token = getenv("DISCORD_BOT_TOKEN")
+            if not token:
+                raise ValueError("DISCORD_BOT_TOKEN NOT SET")
+            return self.client.run(token)
+        except Exception as e:
+            raise ValueError(f"Failed to run Discord client: {str(e)}")

agno/knowledge/__init__.py

@@ -1 +1,5 @@
-from agno.knowledge.agent import AgentKnowledge
+from agno.knowledge.knowledge import Knowledge
+
+__all__ = [
+    "Knowledge",
+]

agno/{document → knowledge}/chunking/agentic.py

@@ -1,23 +1,31 @@
-from typing import List, Optional
+from typing import List, Optional, Union
 
-from agno.document.base import Document
-from agno.document.chunking.strategy import ChunkingStrategy
+from agno.knowledge.chunking.strategy import ChunkingStrategy
+from agno.knowledge.document.base import Document
 from agno.models.base import Model
 from agno.models.defaults import DEFAULT_OPENAI_MODEL_ID
 from agno.models.message import Message
-from agno.models.openai import OpenAIChat
+from agno.models.utils import get_model
 
 
 class AgenticChunking(ChunkingStrategy):
     """Chunking strategy that uses an LLM to determine natural breakpoints in the text"""
 
-    def __init__(self, model: Optional[Model] = None, max_chunk_size: int = 5000):
-        self.model = model or OpenAIChat(DEFAULT_OPENAI_MODEL_ID)
-        self.max_chunk_size = max_chunk_size
+    def __init__(self, model: Optional[Union[Model, str]] = None, max_chunk_size: int = 5000):
+        # Convert model string to Model instance
+        model = get_model(model)
+        if model is None:
+            try:
+                from agno.models.openai import OpenAIChat
+            except Exception:
+                raise ValueError("`openai` isn't installed. Please install it with `pip install openai`")
+            model = OpenAIChat(DEFAULT_OPENAI_MODEL_ID)
+        self.chunk_size = max_chunk_size
+        self.model = model
 
     def chunk(self, document: Document) -> List[Document]:
         """Split text into chunks using LLM to determine natural breakpoints based on context"""
-        if len(document.content) <= self.max_chunk_size:
+        if len(document.content) <= self.chunk_size:
             return [document]
 
         chunks: List[Document] = []
@@ -26,22 +34,22 @@ class AgenticChunking(ChunkingStrategy):
         chunk_number = 1
 
         while remaining_text:
-            # Ask model to find a good breakpoint within max_chunk_size
-            prompt = f"""Analyze this text and determine a natural breakpoint within the first {self.max_chunk_size} characters.
+            # Ask model to find a good breakpoint within chunk_size
+            prompt = f"""Analyze this text and determine a natural breakpoint within the first {self.chunk_size} characters.
             Consider semantic completeness, paragraph boundaries, and topic transitions.
             Return only the character position number of where to break the text:
 
-            {remaining_text[: self.max_chunk_size]}"""
+            {remaining_text[: self.chunk_size]}"""
 
             try:
                 response = self.model.response([Message(role="user", content=prompt)])
                 if response and response.content:
-                    break_point = min(int(response.content.strip()), self.max_chunk_size)
+                    break_point = min(int(response.content.strip()), self.chunk_size)
                 else:
-                    break_point = self.max_chunk_size
+                    break_point = self.chunk_size
             except Exception:
                 # Fallback to max size if model fails
-                break_point = self.max_chunk_size
+                break_point = self.chunk_size
 
             # Extract chunk and update remaining text
             chunk = remaining_text[:break_point].strip()

agno/{document → knowledge}/chunking/document.py

@@ -1,7 +1,7 @@
 from typing import List
 
-from agno.document.base import Document
-from agno.document.chunking.strategy import ChunkingStrategy
+from agno.knowledge.chunking.strategy import ChunkingStrategy
+from agno.knowledge.document.base import Document
 
 
 class DocumentChunking(ChunkingStrategy):

agno/{document → knowledge}/chunking/fixed.py

@@ -1,7 +1,7 @@
 from typing import List
 
-from agno.document.base import Document
-from agno.document.chunking.strategy import ChunkingStrategy
+from agno.knowledge.chunking.strategy import ChunkingStrategy
+from agno.knowledge.document.base import Document
 
 
 class FixedSizeChunking(ChunkingStrategy):
@@ -22,9 +22,8 @@ class FixedSizeChunking(ChunkingStrategy):
         chunked_documents: List[Document] = []
         chunk_number = 1
         chunk_meta_data = document.meta_data
-
         start = 0
-        while start < content_length:
+        while start + self.overlap < content_length:
             end = min(start + self.chunk_size, content_length)
 
             # Ensure we're not splitting a word in half
@@ -54,6 +53,8 @@ class FixedSizeChunking(ChunkingStrategy):
                 )
             )
             chunk_number += 1
-            start = end - self.overlap
-
+            # Ensure start always advances by at least 1 to prevent infinite loops
+            # when overlap is large relative to chunk_size
+            new_start = max(start + 1, end - self.overlap)
+            start = new_start
         return chunked_documents

agno/knowledge/chunking/markdown.py

@@ -0,0 +1,151 @@
+import os
+import tempfile
+from typing import List
+
+try:
+    from unstructured.chunking.title import chunk_by_title  # type: ignore
+    from unstructured.partition.md import partition_md  # type: ignore
+except ImportError:
+    raise ImportError("`unstructured` not installed. Please install it using `pip install unstructured markdown`")
+
+from agno.knowledge.chunking.strategy import ChunkingStrategy
+from agno.knowledge.document.base import Document
+
+
+class MarkdownChunking(ChunkingStrategy):
+    """A chunking strategy that splits markdown based on structure like headers, paragraphs and sections"""
+
+    def __init__(self, chunk_size: int = 5000, overlap: int = 0):
+        self.chunk_size = chunk_size
+        self.overlap = overlap
+
+    def _partition_markdown_content(self, content: str) -> List[str]:
+        """
+        Partition markdown content and return a list of text chunks.
+        Falls back to paragraph splitting if the markdown chunking fails.
+        """
+        try:
+            # Create a temporary file with the markdown content.
+            # This is the recommended usage of the unstructured library.
+            with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False, encoding="utf-8") as temp_file:
+                temp_file.write(content)
+                temp_file_path = temp_file.name
+
+            try:
+                elements = partition_md(filename=temp_file_path)
+
+                if not elements:
+                    return self.clean_text(content).split("\n\n")
+
+                # Chunk by title with some default values
+                chunked_elements = chunk_by_title(
+                    elements=elements,
+                    max_characters=self.chunk_size,
+                    new_after_n_chars=int(self.chunk_size * 0.8),
+                    combine_text_under_n_chars=self.chunk_size,
+                    overlap=0,
+                )
+
+                # Generate the final text chunks
+                text_chunks = []
+                for chunk_group in chunked_elements:
+                    if isinstance(chunk_group, list):
+                        chunk_text = "\n\n".join([elem.text for elem in chunk_group if hasattr(elem, "text")])
+                    else:
+                        chunk_text = chunk_group.text if hasattr(chunk_group, "text") else str(chunk_group)
+
+                    if chunk_text.strip():
+                        text_chunks.append(chunk_text.strip())
+
+                return text_chunks if text_chunks else self.clean_text(content).split("\n\n")
+
+            # Always clean up the temporary file
+            finally:
+                os.unlink(temp_file_path)
+
+        # Fallback to simple paragraph splitting if the markdown chunking fails
+        except Exception:
+            return self.clean_text(content).split("\n\n")
+
+    def chunk(self, document: Document) -> List[Document]:
+        """Split markdown document into chunks based on markdown structure"""
+        if not document.content or len(document.content) <= self.chunk_size:
+            return [document]
+
+        # Split using markdown chunking logic, or fallback to paragraphs
+        sections = self._partition_markdown_content(document.content)
+
+        chunks: List[Document] = []
+        current_chunk = []
+        current_size = 0
+        chunk_meta_data = document.meta_data
+        chunk_number = 1
+
+        for section in sections:
+            section = section.strip()
+            section_size = len(section)
+
+            if current_size + section_size <= self.chunk_size:
+                current_chunk.append(section)
+                current_size += section_size
+            else:
+                meta_data = chunk_meta_data.copy()
+                meta_data["chunk"] = chunk_number
+                chunk_id = None
+                if document.id:
+                    chunk_id = f"{document.id}_{chunk_number}"
+                elif document.name:
+                    chunk_id = f"{document.name}_{chunk_number}"
+                meta_data["chunk_size"] = len("\n\n".join(current_chunk))
+
+                if current_chunk:
+                    chunks.append(
+                        Document(
+                            id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk)
+                        )
+                    )
+                    chunk_number += 1
+
+                current_chunk = [section]
+                current_size = section_size
+
+        if current_chunk:
+            meta_data = chunk_meta_data.copy()
+            meta_data["chunk"] = chunk_number
+            chunk_id = None
+            if document.id:
+                chunk_id = f"{document.id}_{chunk_number}"
+            elif document.name:
+                chunk_id = f"{document.name}_{chunk_number}"
+            meta_data["chunk_size"] = len("\n\n".join(current_chunk))
+            chunks.append(
+                Document(id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk))
+            )
+
+        # Handle overlap if specified
+        if self.overlap > 0:
+            overlapped_chunks = []
+            for i in range(len(chunks)):
+                if i > 0:
+                    # Add overlap from previous chunk
+                    prev_text = chunks[i - 1].content[-self.overlap :]
+                    meta_data = chunk_meta_data.copy()
+                    meta_data["chunk"] = chunks[i].meta_data["chunk"]
+                    chunk_id = chunks[i].id
+                    meta_data["chunk_size"] = len(prev_text + chunks[i].content)
+
+                    if prev_text:
+                        overlapped_chunks.append(
+                            Document(
+                                id=chunk_id,
+                                name=document.name,
+                                meta_data=meta_data,
+                                content=prev_text + chunks[i].content,
+                            )
+                        )
+                    else:
+                        overlapped_chunks.append(chunks[i])
+                else:
+                    overlapped_chunks.append(chunks[i])
+            chunks = overlapped_chunks
+        return chunks

agno/{document → knowledge}/chunking/recursive.py

@@ -1,7 +1,8 @@
+import warnings
 from typing import List
 
-from agno.document.base import Document
-from agno.document.chunking.strategy import ChunkingStrategy
+from agno.knowledge.chunking.strategy import ChunkingStrategy
+from agno.knowledge.document.base import Document
 
 
 class RecursiveChunking(ChunkingStrategy):
@@ -12,6 +13,12 @@ class RecursiveChunking(ChunkingStrategy):
         if overlap >= chunk_size:
             raise ValueError(f"Invalid parameters: overlap ({overlap}) must be less than chunk size ({chunk_size}).")
 
+        if overlap > chunk_size * 0.15:
+            warnings.warn(
+                f"High overlap: {overlap} > 15% of chunk size ({chunk_size}). May cause slow processing.",
+                RuntimeWarning,
+            )
+
         self.chunk_size = chunk_size
         self.overlap = overlap
 
@@ -46,6 +53,11 @@ class RecursiveChunking(ChunkingStrategy):
             meta_data["chunk_size"] = len(chunk)
             chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk))
 
-            start = max(start, end - self.overlap)
+            new_start = end - self.overlap
+            if new_start <= start:  # Prevent infinite loop
+                new_start = min(
+                    len(content), start + max(1, self.chunk_size // 10)
+                )  # Move forward by at least 10% of chunk size
+            start = new_start
 
         return chunks