agno 2.1.8__py3-none-any.whl → 2.1.10__py3-none-any.whl

agno/db/surrealdb/surrealdb.py

@@ -7,6 +7,7 @@ from agno.db.postgres.utils import (
     get_dates_to_calculate_metrics_for,
 )
 from agno.db.schemas import UserMemory
+from agno.db.schemas.culture import CulturalKnowledge
 from agno.db.schemas.evals import EvalFilterType, EvalRunRecord, EvalType
 from agno.db.schemas.knowledge import KnowledgeRow
 from agno.db.surrealdb import utils
@@ -19,6 +20,7 @@ from agno.db.surrealdb.metrics import (
 )
 from agno.db.surrealdb.models import (
     TableType,
+    deserialize_cultural_knowledge,
     deserialize_eval_run_record,
     deserialize_knowledge_row,
     deserialize_session,
@@ -30,6 +32,7 @@ from agno.db.surrealdb.models import (
     desurrealize_user_memory,
     get_schema,
     get_session_type,
+    serialize_cultural_knowledge,
     serialize_eval_run_record,
     serialize_knowledge_row,
     serialize_session,
@@ -60,6 +63,7 @@ class SurrealDb(BaseDb):
         metrics_table: Optional[str] = None,
         eval_table: Optional[str] = None,
         knowledge_table: Optional[str] = None,
+        culture_table: Optional[str] = None,
         id: Optional[str] = None,
     ):
         """
@@ -80,6 +84,7 @@ class SurrealDb(BaseDb):
             metrics_table=metrics_table,
             eval_table=eval_table,
             knowledge_table=knowledge_table,
+            culture_table=culture_table,
         )
         self._client = client
         self._db_url = db_url
@@ -101,6 +106,7 @@ class SurrealDb(BaseDb):
     def table_names(self) -> dict[TableType, str]:
         return {
             "agents": self._agents_table_name,
+            "culture": self.culture_table_name,
             "evals": self.eval_table_name,
             "knowledge": self.knowledge_table_name,
             "memories": self.memory_table_name,
@@ -127,6 +133,8 @@ class SurrealDb(BaseDb):
             table_name = self.memory_table_name
         elif table_type == "knowledge":
             table_name = self.knowledge_table_name
+        elif table_type == "culture":
+            table_name = self.culture_table_name
         elif table_type == "users":
             table_name = self._users_table_name
         elif table_type == "agents":
@@ -463,6 +471,152 @@ class SurrealDb(BaseDb):
         table = self._get_table("memories")
         _ = self.client.delete(table)
 
+    # -- Cultural Knowledge methods --
+    def clear_cultural_knowledge(self) -> None:
+        """Delete all cultural knowledge from the database.
+
+        Raises:
+            Exception: If an error occurs during deletion.
+        """
+        table = self._get_table("culture")
+        _ = self.client.delete(table)
+
+    def delete_cultural_knowledge(self, id: str) -> None:
+        """Delete cultural knowledge by ID.
+
+        Args:
+            id (str): The ID of the cultural knowledge to delete.
+
+        Raises:
+            Exception: If an error occurs during deletion.
+        """
+        table = self._get_table("culture")
+        rec_id = RecordID(table, id)
+        self.client.delete(rec_id)
+
+    def get_cultural_knowledge(
+        self, id: str, deserialize: Optional[bool] = True
+    ) -> Optional[Union[CulturalKnowledge, Dict[str, Any]]]:
+        """Get cultural knowledge by ID.
+
+        Args:
+            id (str): The ID of the cultural knowledge to retrieve.
+            deserialize (Optional[bool]): Whether to deserialize to CulturalKnowledge object. Defaults to True.
+
+        Returns:
+            Optional[Union[CulturalKnowledge, Dict[str, Any]]]: The cultural knowledge if found, None otherwise.
+
+        Raises:
+            Exception: If an error occurs during retrieval.
+        """
+        table = self._get_table("culture")
+        rec_id = RecordID(table, id)
+        result = self.client.select(rec_id)
+
+        if result is None:
+            return None
+
+        if not deserialize:
+            return result  # type: ignore
+
+        return deserialize_cultural_knowledge(result)  # type: ignore
+
+    def get_all_cultural_knowledge(
+        self,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+        name: Optional[str] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        sort_by: Optional[str] = None,
+        sort_order: Optional[str] = None,
+        deserialize: Optional[bool] = True,
+    ) -> Union[List[CulturalKnowledge], Tuple[List[Dict[str, Any]], int]]:
+        """Get all cultural knowledge with filtering and pagination.
+
+        Args:
+            agent_id (Optional[str]): Filter by agent ID.
+            team_id (Optional[str]): Filter by team ID.
+            name (Optional[str]): Filter by name (case-insensitive partial match).
+            limit (Optional[int]): Maximum number of results to return.
+            page (Optional[int]): Page number for pagination.
+            sort_by (Optional[str]): Field to sort by.
+            sort_order (Optional[str]): Sort order ('asc' or 'desc').
+            deserialize (Optional[bool]): Whether to deserialize to CulturalKnowledge objects. Defaults to True.
+
+        Returns:
+            Union[List[CulturalKnowledge], Tuple[List[Dict[str, Any]], int]]:
+                - When deserialize=True: List of CulturalKnowledge objects
+                - When deserialize=False: Tuple with list of dictionaries and total count
+
+        Raises:
+            Exception: If an error occurs during retrieval.
+        """
+        table = self._get_table("culture")
+
+        # Build where clauses
+        where_clauses: List[WhereClause] = []
+        if agent_id is not None:
+            agent_rec_id = RecordID(self._get_table("agents"), agent_id)
+            where_clauses.append(("agent", "=", agent_rec_id))  # type: ignore
+        if team_id is not None:
+            team_rec_id = RecordID(self._get_table("teams"), team_id)
+            where_clauses.append(("team", "=", team_rec_id))  # type: ignore
+        if name is not None:
+            where_clauses.append(("string::lowercase(name)", "CONTAINS", name.lower()))  # type: ignore
+
+        # Build query for total count
+        count_query = COUNT_QUERY.format(
+            table=table,
+            where=""
+            if not where_clauses
+            else f"WHERE {' AND '.join(f'{w[0]} {w[1]} ${chr(97 + i)}' for i, w in enumerate(where_clauses))}",  # type: ignore
+        )
+        params = {chr(97 + i): w[2] for i, w in enumerate(where_clauses)}  # type: ignore
+        total_count = self._query_one(count_query, params, int) or 0
+
+        # Build main query
+        order_limit = order_limit_start(sort_by, sort_order, limit, page)
+        query = f"SELECT * FROM {table}"
+        if where_clauses:
+            query += f" WHERE {' AND '.join(f'{w[0]} {w[1]} ${chr(97 + i)}' for i, w in enumerate(where_clauses))}"  # type: ignore
+        query += order_limit
+
+        results = self._query(query, params, list) or []
+
+        if not deserialize:
+            return results, total_count  # type: ignore
+
+        return [deserialize_cultural_knowledge(r) for r in results]  # type: ignore
+
+    def upsert_cultural_knowledge(
+        self, cultural_knowledge: CulturalKnowledge, deserialize: Optional[bool] = True
+    ) -> Optional[Union[CulturalKnowledge, Dict[str, Any]]]:
+        """Upsert cultural knowledge in SurrealDB.
+
+        Args:
+            cultural_knowledge (CulturalKnowledge): The cultural knowledge to upsert.
+            deserialize (Optional[bool]): Whether to deserialize the result. Defaults to True.
+
+        Returns:
+            Optional[Union[CulturalKnowledge, Dict[str, Any]]]: The upserted cultural knowledge.
+
+        Raises:
+            Exception: If an error occurs during upsert.
+        """
+        table = self._get_table("culture", create_table_if_not_found=True)
+        serialized = serialize_cultural_knowledge(cultural_knowledge, table)
+
+        result = self.client.upsert(serialized["id"], serialized)
+
+        if result is None:
+            return None
+
+        if not deserialize:
+            return result  # type: ignore
+
+        return deserialize_cultural_knowledge(result)  # type: ignore
+
     def delete_user_memory(self, memory_id: str, user_id: Optional[str] = None) -> None:
         """Delete a user memory from the database.
 

agno/db/surrealdb/utils.py

@@ -1,8 +1,9 @@
 import dataclasses
-from typing import Any, Optional, Sequence, TypeVar, Union, cast
+from typing import Any, Dict, Optional, Sequence, TypeVar, Union, cast
 
 from surrealdb import BlockingHttpSurrealConnection, BlockingWsSurrealConnection, Surreal
 
+from agno.db.schemas.culture import CulturalKnowledge
 from agno.utils.log import logger
 
 RecordType = TypeVar("RecordType")
@@ -85,3 +86,62 @@ def query_one(
             raise ValueError(f"Expected single record, got {len(response)} records: {response}")
     else:
         raise ValueError(f"Unexpected response type: {type(response)}")
+
+
+# -- Cultural Knowledge util methods --
+
+
+def serialize_cultural_knowledge_for_db(cultural_knowledge: CulturalKnowledge) -> Dict[str, Any]:
+    """Serialize a CulturalKnowledge object for database storage.
+
+    Converts the model's separate content, categories, and notes fields
+    into a single dict for the database content field.
+
+    Args:
+        cultural_knowledge (CulturalKnowledge): The cultural knowledge object to serialize.
+
+    Returns:
+        Dict[str, Any]: A dictionary with content, categories, and notes.
+    """
+    content_dict: Dict[str, Any] = {}
+    if cultural_knowledge.content is not None:
+        content_dict["content"] = cultural_knowledge.content
+    if cultural_knowledge.categories is not None:
+        content_dict["categories"] = cultural_knowledge.categories
+    if cultural_knowledge.notes is not None:
+        content_dict["notes"] = cultural_knowledge.notes
+
+    return content_dict if content_dict else {}
+
+
+def deserialize_cultural_knowledge_from_db(db_row: Dict[str, Any]) -> CulturalKnowledge:
+    """Deserialize a database row to a CulturalKnowledge object.
+
+    The database stores content as a dict containing content, categories, and notes.
+    This method extracts those fields and converts them back to the model format.
+
+    Args:
+        db_row (Dict[str, Any]): The database row as a dictionary.
+
+    Returns:
+        CulturalKnowledge: The cultural knowledge object.
+    """
+    # Extract content, categories, and notes from the content field
+    content_json = db_row.get("content", {}) or {}
+
+    return CulturalKnowledge.from_dict(
+        {
+            "id": db_row.get("id"),
+            "name": db_row.get("name"),
+            "summary": db_row.get("summary"),
+            "content": content_json.get("content"),
+            "categories": content_json.get("categories"),
+            "notes": content_json.get("notes"),
+            "metadata": db_row.get("metadata"),
+            "input": db_row.get("input"),
+            "created_at": db_row.get("created_at"),
+            "updated_at": db_row.get("updated_at"),
+            "agent_id": db_row.get("agent_id"),
+            "team_id": db_row.get("team_id"),
+        }
+    )

agno/knowledge/knowledge.py

@@ -122,6 +122,7 @@ class Knowledge:
                     exclude=exclude,
                     upsert=upsert,
                     skip_if_exists=skip_if_exists,
+                    reader=reader,
                 )
             for url in urls:
                 await self.add_content_async(
@@ -133,6 +134,7 @@ class Knowledge:
                     exclude=exclude,
                     upsert=upsert,
                     skip_if_exists=skip_if_exists,
+                    reader=reader,
                 )
             for i, text_content in enumerate(text_contents):
                 content_name = f"{name}_{i}" if name else f"text_content_{i}"
@@ -146,6 +148,7 @@ class Knowledge:
                     exclude=exclude,
                     upsert=upsert,
                     skip_if_exists=skip_if_exists,
+                    reader=reader,
                 )
             if topics:
                 await self.add_content_async(
@@ -168,6 +171,7 @@ class Knowledge:
                     remote_content=remote_content,
                     upsert=upsert,
                     skip_if_exists=skip_if_exists,
+                    reader=reader,
                 )
 
         else:

agno/knowledge/reader/field_labeled_csv_reader.py

@@ -33,8 +33,6 @@ class FieldLabeledCSVReader(Reader):
         self.format_headers = format_headers
         self.skip_empty_fields = skip_empty_fields
 
-        logger.info(f"FieldLabeledCSVReader initialized - chunk_title: {chunk_title}, field_names: {self.field_names}")
-
     @classmethod
     def get_supported_chunking_strategies(cls) -> List[ChunkingStrategyType]:
         """Chunking is not supported - each row is already a logical document unit."""

agno/memory/manager.py

@@ -12,7 +12,13 @@ from agno.db.schemas import UserMemory
 from agno.models.base import Model
 from agno.models.message import Message
 from agno.tools.function import Function
-from agno.utils.log import log_debug, log_error, log_warning, set_log_level_to_debug, set_log_level_to_info
+from agno.utils.log import (
+    log_debug,
+    log_error,
+    log_warning,
+    set_log_level_to_debug,
+    set_log_level_to_info,
+)
 from agno.utils.prompts import get_json_output_prompt
 from agno.utils.string import parse_response_model_str
 
@@ -21,7 +27,8 @@ class MemorySearchResponse(BaseModel):
     """Model for Memory Search Response."""
 
     memory_ids: List[str] = Field(
-        ..., description="The IDs of the memories that are most semantically similar to the query."
+        ...,
+        description="The IDs of the memories that are most semantically similar to the query.",
     )
 
 
@@ -32,11 +39,11 @@ class MemoryManager:
     # Model used for memory management
     model: Optional[Model] = None
 
-    # Provide the system message for the manager as a string. If not provided, a default prompt will be used.
+    # Provide the system message for the manager as a string. If not provided, the default system message will be used.
     system_message: Optional[str] = None
-    # Provide the memory capture instructions for the manager as a string. If not provided, a default prompt will be used.
+    # Provide the memory capture instructions for the manager as a string. If not provided, the default memory capture instructions will be used.
     memory_capture_instructions: Optional[str] = None
-    # Additional instructions for the manager. These instructions are appended to the default system prompt.
+    # Additional instructions for the manager. These instructions are appended to the default system message.
     additional_instructions: Optional[str] = None
 
     # Whether memories were created in the last run
@@ -731,14 +738,16 @@ class MemoryManager:
         if self.system_message is not None:
             return Message(role="system", content=self.system_message)
 
-        memory_capture_instructions = self.memory_capture_instructions or dedent("""\
+        memory_capture_instructions = self.memory_capture_instructions or dedent(
+            """\
             Memories should capture personal information about the user that is relevant to the current conversation, such as:
             - Personal facts: name, age, occupation, location, interests, and preferences
             - Opinions and preferences: what the user likes, dislikes, enjoys, or finds frustrating
             - Significant life events or experiences shared by the user
             - Important context about the user's current situation, challenges, or goals
             - Any other details that offer meaningful insight into the user's personality, perspective, or needs
-        """)
+        """
+        )
 
         # -*- Return a system message for the memory manager
         system_prompt_lines = [
@@ -852,7 +861,9 @@ class MemoryManager:
 
         # Generate a response from the Model (includes running function calls)
         response = model_copy.response(
-            messages=messages_for_model, tools=self._tools_for_model, functions=self._functions_for_model
+            messages=messages_for_model,
+            tools=self._tools_for_model,
+            functions=self._functions_for_model,
         )
 
         if response.tool_calls is not None and len(response.tool_calls) > 0:
@@ -928,7 +939,9 @@ class MemoryManager:
 
         # Generate a response from the Model (includes running function calls)
         response = await model_copy.aresponse(
-            messages=messages_for_model, tools=self._tools_for_model, functions=self._functions_for_model
+            messages=messages_for_model,
+            tools=self._tools_for_model,
+            functions=self._functions_for_model,
         )
 
         if response.tool_calls is not None and len(response.tool_calls) > 0:
@@ -983,7 +996,9 @@ class MemoryManager:
 
         # Generate a response from the Model (includes running function calls)
         response = model_copy.response(
-            messages=messages_for_model, tools=self._tools_for_model, functions=self._functions_for_model
+            messages=messages_for_model,
+            tools=self._tools_for_model,
+            functions=self._functions_for_model,
         )
 
         if response.tool_calls is not None and len(response.tool_calls) > 0:
@@ -1051,7 +1066,9 @@ class MemoryManager:
 
         # Generate a response from the Model (includes running function calls)
         response = await model_copy.aresponse(
-            messages=messages_for_model, tools=self._tools_for_model, functions=self._functions_for_model
+            messages=messages_for_model,
+            tools=self._tools_for_model,
+            functions=self._functions_for_model,
         )
 
         if response.tool_calls is not None and len(response.tool_calls) > 0:

agno/models/message.py

@@ -1,6 +1,7 @@
 import json
 from time import time
 from typing import Any, Dict, List, Optional, Sequence, Union
+from uuid import uuid4
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -51,6 +52,8 @@ class Citations(BaseModel):
 class Message(BaseModel):
     """Message sent to the Model"""
 
+    id: str = Field(default_factory=lambda: str(uuid4()))
+
     # The role of the message author.
     # One of system, user, assistant, or tool.
     role: str
@@ -259,6 +262,7 @@ class Message(BaseModel):
     def to_dict(self) -> Dict[str, Any]:
         """Returns the message as a dictionary."""
         message_dict = {
+            "id": self.id,
             "content": self.content,
             "reasoning_content": self.reasoning_content,
             "from_history": self.from_history,

agno/os/app.py

@@ -13,6 +13,7 @@ from starlette.requests import Request
 
 from agno.agent.agent import Agent
 from agno.db.base import AsyncBaseDb, BaseDb
+from agno.knowledge.knowledge import Knowledge
 from agno.os.config import (
     AgentOSConfig,
     DatabaseConfig,
@@ -98,6 +99,7 @@ class AgentOS:
         agents: Optional[List[Agent]] = None,
         teams: Optional[List[Team]] = None,
         workflows: Optional[List[Workflow]] = None,
+        knowledge: Optional[List[Knowledge]] = None,
         interfaces: Optional[List[BaseInterface]] = None,
         a2a_interface: bool = False,
         config: Optional[Union[str, AgentOSConfig]] = None,
@@ -122,6 +124,7 @@ class AgentOS:
             agents: List of agents to include in the OS
             teams: List of teams to include in the OS
             workflows: List of workflows to include in the OS
+            knowledge: List of knowledge bases to include in the OS
             interfaces: List of interfaces to include in the OS
             a2a_interface: Whether to expose the OS agents and teams in an A2A server
             config: Configuration file path or AgentOSConfig instance
@@ -133,8 +136,8 @@ class AgentOS:
             telemetry: Whether to enable telemetry
 
         """
-        if not agents and not workflows and not teams:
-            raise ValueError("Either agents, teams or workflows must be provided.")
+        if not agents and not workflows and not teams and not knowledge:
+            raise ValueError("Either agents, teams, workflows or knowledge bases must be provided.")
 
         self.config = load_yaml_config(config) if isinstance(config, str) else config
 
@@ -143,7 +146,7 @@ class AgentOS:
         self.teams: Optional[List[Team]] = teams
         self.interfaces = interfaces or []
         self.a2a_interface = a2a_interface
-
+        self.knowledge = knowledge
         self.settings: AgnoAPISettings = settings or AgnoAPISettings()
 
         self._app_set = False
@@ -480,6 +483,10 @@ class AgentOS:
             if workflow.db:
                 self._register_db_with_validation(dbs, workflow.db)
 
+        for knowledge_base in self.knowledge or []:
+            if knowledge_base.contents_db:
+                self._register_db_with_validation(knowledge_dbs, knowledge_base.contents_db)
+
         for interface in self.interfaces or []:
             if interface.agent and interface.agent.db:
                 self._register_db_with_validation(dbs, interface.agent.db)
@@ -534,14 +541,29 @@ class AgentOS:
 
     def _auto_discover_knowledge_instances(self) -> None:
         """Auto-discover the knowledge instances used by all contextual agents, teams and workflows."""
-        knowledge_instances = []
+        seen_ids = set()
+        knowledge_instances: List[Knowledge] = []
+
+        def _add_knowledge_if_not_duplicate(knowledge: "Knowledge") -> None:
+            """Add knowledge instance if it's not already in the list (by object identity or db_id)."""
+            # Use database ID if available, otherwise use object ID as fallback
+            if not knowledge.contents_db:
+                return
+            if knowledge.contents_db.id in seen_ids:
+                return
+            seen_ids.add(knowledge.contents_db.id)
+            knowledge_instances.append(knowledge)
+
         for agent in self.agents or []:
             if agent.knowledge:
-                knowledge_instances.append(agent.knowledge)
+                _add_knowledge_if_not_duplicate(agent.knowledge)
 
         for team in self.teams or []:
             if team.knowledge:
-                knowledge_instances.append(team.knowledge)
+                _add_knowledge_if_not_duplicate(team.knowledge)
+
+        for knowledge_base in self.knowledge or []:
+            _add_knowledge_if_not_duplicate(knowledge_base)
 
         self.knowledge_instances = knowledge_instances
 

agno/team/team.py

@@ -1674,11 +1674,11 @@ class Team:
         )
         self.model = cast(Model, self.model)
 
-        if metadata is not None:
-            if self.metadata is not None:
-                merge_dictionaries(metadata, self.metadata)
-            else:
+        if self.metadata is not None:
+            if metadata is None:
                 metadata = self.metadata
+            else:
+                merge_dictionaries(metadata, self.metadata)
 
         # Create a new run_response for this attempt
         run_response = TeamRunOutput(
@@ -2201,7 +2201,7 @@ class Team:
 
             # Execute post-hooks after output is generated but before response is returned
             if self.post_hooks is not None:
-                self._execute_post_hooks(
+                await self._aexecute_post_hooks(
                     hooks=self.post_hooks,  # type: ignore
                     run_output=run_response,
                     session_state=session_state,
@@ -2428,11 +2428,11 @@ class Team:
 
         self.model = cast(Model, self.model)
 
-        if metadata is not None:
-            if self.metadata is not None:
-                merge_dictionaries(metadata, self.metadata)
-            else:
+        if self.metadata is not None:
+            if metadata is None:
                 metadata = self.metadata
+            else:
+                merge_dictionaries(metadata, self.metadata)
 
         #  Get knowledge filters
         effective_filters = knowledge_filters

agno/tools/gmail.py

@@ -124,20 +124,6 @@ class GmailTools(Toolkit):
         self.scopes = scopes or self.DEFAULT_SCOPES
         self.port = port
 
-        """ tools functions:
-         enable_get_latest_emails (bool): Enable getting latest emails.
-         enable_get_emails_from_user (bool): Enable getting emails from specific user.
-         enable_get_unread_emails (bool): Enable getting unread emails.
-         enable_get_starred_emails (bool): Enable getting starred emails.
-         enable_get_emails_by_context (bool): Enable getting emails by context.
-         enable_get_emails_by_date (bool): Enable getting emails by date.
-         enable_get_emails_by_thread (bool): Enable getting emails by thread.
-         enable_create_draft_email (bool): Enable creating draft emails.
-         enable_send_email (bool): Enable sending emails.
-         enable_send_email_reply (bool): Enable sending email replies.
-         all (bool): Enable all tools.
-        """
-
         tools: List[Any] = [
             # Reading emails
             self.get_latest_emails,
@@ -148,6 +134,9 @@ class GmailTools(Toolkit):
             self.get_emails_by_date,
             self.get_emails_by_thread,
             self.search_emails,
+            # Email management
+            self.mark_email_as_read,
+            self.mark_email_as_unread,
             # Composing emails
             self.create_draft_email,
             self.send_email,
@@ -173,12 +162,18 @@ class GmailTools(Toolkit):
             "get_emails_by_thread",
             "search_emails",
         ]
+        modify_operations = ["mark_email_as_read", "mark_email_as_unread"]
         if any(read_operation in self.functions for read_operation in read_operations):
             read_scope = "https://www.googleapis.com/auth/gmail.readonly"
             write_scope = "https://www.googleapis.com/auth/gmail.modify"
             if read_scope not in self.scopes and write_scope not in self.scopes:
                 raise ValueError(f"The scope {read_scope} is required for email reading operations")
 
+        if any(modify_operation in self.functions for modify_operation in modify_operations):
+            modify_scope = "https://www.googleapis.com/auth/gmail.modify"
+            if modify_scope not in self.scopes:
+                raise ValueError(f"The scope {modify_scope} is required for email modification operations")
+
     def _auth(self) -> None:
         """Authenticate with Gmail API"""
         token_file = Path(self.token_path or "token.json")
@@ -555,6 +550,56 @@ class GmailTools(Toolkit):
         except Exception as error:
             return f"Unexpected error retrieving emails with query '{query}': {type(error).__name__}: {error}"
 
+    @authenticate
+    def mark_email_as_read(self, message_id: str) -> str:
+        """
+        Mark a specific email as read by removing the 'UNREAD' label.
+        This is crucial for long polling scenarios to prevent processing the same email multiple times.
+
+        Args:
+            message_id (str): The ID of the message to mark as read
+
+        Returns:
+            str: Success message or error description
+        """
+        try:
+            # Remove the UNREAD label to mark the email as read
+            modify_request = {"removeLabelIds": ["UNREAD"]}
+
+            self.service.users().messages().modify(userId="me", id=message_id, body=modify_request).execute()  # type: ignore
+
+            return f"Successfully marked email {message_id} as read. Labels removed: UNREAD"
+
+        except HttpError as error:
+            return f"HTTP Error marking email {message_id} as read: {error}"
+        except Exception as error:
+            return f"Error marking email {message_id} as read: {type(error).__name__}: {error}"
+
+    @authenticate
+    def mark_email_as_unread(self, message_id: str) -> str:
+        """
+        Mark a specific email as unread by adding the 'UNREAD' label.
+        This is useful for flagging emails that need attention or re-processing.
+
+        Args:
+            message_id (str): The ID of the message to mark as unread
+
+        Returns:
+            str: Success message or error description
+        """
+        try:
+            # Add the UNREAD label to mark the email as unread
+            modify_request = {"addLabelIds": ["UNREAD"]}
+
+            self.service.users().messages().modify(userId="me", id=message_id, body=modify_request).execute()  # type: ignore
+
+            return f"Successfully marked email {message_id} as unread. Labels added: UNREAD"
+
+        except HttpError as error:
+            return f"HTTP Error marking email {message_id} as unread: {error}"
+        except Exception as error:
+            return f"Error marking email {message_id} as unread: {type(error).__name__}: {error}"
+
     def _validate_email_params(self, to: str, subject: str, body: str) -> None:
         """Validate email parameters."""
         if not to: