Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add tags support to blocks (#8474)
cthomasab4ccfca3184
diff --git a/alembic/versions/cf3c4d025dbc_add_blocks_tags_table.py b/alembic/versions/cf3c4d025dbc_add_blocks_tags_table.pynew file mode 100644index 000000000..f2be82a74--- /dev/null+++ b/alembic/versions/cf3c4d025dbc_add_blocks_tags_table.py@@ -0,0 +1,58 @@+"""Add blocks tags table++Revision ID: cf3c4d025dbc+Revises: 27de0f58e076+Create Date: 2026-01-08 23:36:00.000000++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op+from letta.settings import settings++# revision identifiers, used by Alembic.+revision: str = "cf3c4d025dbc"+down_revision: Union[str, None] = "27de0f58e076"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ # Skip this migration for SQLite+ if not settings.letta_pg_uri_no_default:+ return++ # Create blocks_tags table with timestamps and org scoping for filtering+ # Note: Matches agents_tags structure but follows SQLite baseline pattern (no separate id column)+ op.create_table(+ "blocks_tags",+ sa.Column("block_id", sa.String(), nullable=False),+ sa.Column("tag", sa.String(), nullable=False),+ sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=True),+ sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=True),+ sa.Column("is_deleted", sa.Boolean(), server_default=sa.text("FALSE"), nullable=False),+ sa.Column("_created_by_id", sa.String(), nullable=True),+ sa.Column("_last_updated_by_id", sa.String(), nullable=True),+ sa.Column("organization_id", sa.String(), nullable=False),+ sa.ForeignKeyConstraint(+ ["block_id"],+ ["block.id"],+ ),+ sa.ForeignKeyConstraint(+ ["organization_id"],+ ["organizations.id"],+ ),+ sa.PrimaryKeyConstraint("block_id", "tag"),+ sa.UniqueConstraint("block_id", "tag", name="unique_block_tag"),+ )+++def downgrade() -> None:+ # Skip this migration for SQLite+ if not settings.letta_pg_uri_no_default:+ return++ op.drop_table("blocks_tags")diff --git a/letta/orm/__init__.py b/letta/orm/__init__.pyindex c44ae3bd2..47fe5b1d9 100644--- a/letta/orm/__init__.py+++ b/letta/orm/__init__.py@@ -6,6 +6,7 @@ from letta.orm.base import Basefrom letta.orm.block import Blockfrom letta.orm.block_history import BlockHistoryfrom letta.orm.blocks_agents import BlocksAgents+from letta.orm.blocks_tags import BlocksTagsfrom letta.orm.conversation import Conversationfrom letta.orm.conversation_messages import ConversationMessagefrom letta.orm.file import FileMetadatadiff --git a/letta/orm/block.py b/letta/orm/block.pyindex 6ac486556..08f5fb282 100644--- a/letta/orm/block.py+++ b/letta/orm/block.py@@ -12,6 +12,7 @@ from letta.schemas.block import Block as PydanticBlock, Human, Personaif TYPE_CHECKING:from letta.orm import Organization+ from letta.orm.blocks_tags import BlocksTagsfrom letta.orm.identity import Identity@@ -82,6 +83,12 @@ class Block(OrganizationMixin, SqlalchemyBase, ProjectMixin, TemplateEntityMixinback_populates="shared_blocks",passive_deletes=True,)+ tags: Mapped[List["BlocksTags"]] = relationship(+ "BlocksTags",+ back_populates="block",+ cascade="all, delete-orphan",+ lazy="raise",+ )def to_pydantic(self) -> Type:match self.label:diff --git a/letta/orm/blocks_tags.py b/letta/orm/blocks_tags.pynew file mode 100644index 000000000..23412df8c--- /dev/null+++ b/letta/orm/blocks_tags.py@@ -0,0 +1,37 @@+from datetime import datetime+from typing import Optional++from sqlalchemy import Boolean, DateTime, ForeignKey, Index, String, UniqueConstraint, func, text+from sqlalchemy.orm import Mapped, mapped_column, relationship++from letta.orm.base import Base+++class BlocksTags(Base):+ __tablename__ = "blocks_tags"+ __table_args__ = (+ UniqueConstraint("block_id", "tag", name="unique_block_tag"),+ Index("ix_blocks_tags_block_id_tag", "block_id", "tag"),+ Index("ix_blocks_tags_tag_block_id", "tag", "block_id"),+ )++ # Primary key columns+ block_id: Mapped[String] = mapped_column(String, ForeignKey("block.id"), primary_key=True)+ tag: Mapped[str] = mapped_column(String, doc="The name of the tag associated with the block.", primary_key=True)++ # Organization scoping for filtering+ organization_id: Mapped[str] = mapped_column(String, ForeignKey("organizations.id"), nullable=False)++ # Timestamps for filtering by date+ created_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), server_default=func.now())+ updated_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), server_default=func.now())++ # Soft delete support+ is_deleted: Mapped[bool] = mapped_column(Boolean, server_default=text("FALSE"))++ # Audit fields+ _created_by_id: Mapped[Optional[str]] = mapped_column(String, nullable=True)+ _last_updated_by_id: Mapped[Optional[str]] = mapped_column(String, nullable=True)++ # Relationships+ block: Mapped["Block"] = relationship("Block", back_populates="tags")diff --git a/letta/schemas/block.py b/letta/schemas/block.pyindex cec7c3c23..3103c1a95 100644--- a/letta/schemas/block.py+++ b/letta/schemas/block.py@@ -1,5 +1,5 @@from datetime import datetime-from typing import Any, Optional+from typing import Any, List, Optionalfrom pydantic import ConfigDict, Field, model_validator@@ -88,6 +88,17 @@ class Block(BaseBlock):created_by_id: Optional[str] = Field(None, description="The id of the user that made this Block.")last_updated_by_id: Optional[str] = Field(None, description="The id of the user that last updated this Block.")+ # tags - using Optional with default [] to allow None input to become empty list+ tags: Optional[List[str]] = Field(default=[], description="The tags associated with the block.")++ @model_validator(mode="before")+ @classmethod+ def normalize_tags(cls, data: dict) -> dict:+ """Convert None tags to empty list."""+ if isinstance(data, dict) and data.get("tags") is None:+ data["tags"] = []+ return data+class BlockResponse(Block):id: str = Field(@@ -142,6 +153,9 @@ class BlockUpdate(BaseBlock):value: Optional[str] = Field(None, description="Value of the block.")project_id: Optional[str] = Field(None, description="The associated project id.")+ # tags+ tags: Optional[List[str]] = Field(None, description="The tags to associate with the block.")+model_config = ConfigDict(extra="ignore") # Ignores extra fields@@ -157,6 +171,9 @@ class CreateBlock(BaseBlock):is_template: bool = Falsetemplate_name: Optional[str] = Field(None, description="Name of the block if it is a template.")+ # tags+ tags: Optional[List[str]] = Field(None, description="The tags to associate with the block.")+@model_validator(mode="before")@classmethoddef ensure_value_is_string(cls, data):diff --git a/letta/server/rest_api/routers/v1/blocks.py b/letta/server/rest_api/routers/v1/blocks.pyindex 536e243d9..d297ab7a3 100644--- a/letta/server/rest_api/routers/v1/blocks.py+++ b/letta/server/rest_api/routers/v1/blocks.py@@ -33,6 +33,11 @@ async def list_blocks(identity_id: IdentityIdQuery = None,identifier_keys: Optional[List[str]] = Query(None, description="Search agents by identifier keys"),project_id: Optional[str] = Query(None, description="Search blocks by project id"),+ tags: Optional[List[str]] = Query(None, description="List of tags to filter blocks by"),+ match_all_tags: bool = Query(+ False,+ description="If True, only returns blocks that match ALL given tags. Otherwise, return blocks that have ANY of the passed-in tags.",+ ),limit: Optional[int] = Query(50, description="Number of blocks to return"),before: Optional[str] = Query(None,@@ -98,19 +103,44 @@ async def list_blocks(after=after,ascending=(order == "asc"),show_hidden_blocks=show_hidden_blocks,+ tags=tags,+ match_all_tags=match_all_tags,)@router.get("/count", response_model=int, operation_id="count_blocks")async def count_blocks(+ label: BlockLabelQuery = None,+ templates_only: bool = Query(False, description="Whether to include only templates"),+ name: BlockNameQuery = None,+ tags: Optional[List[str]] = Query(None, description="List of tags to filter blocks by"),+ match_all_tags: bool = Query(+ False,+ description="If True, only counts blocks that match ALL given tags. Otherwise, counts blocks that have ANY of the passed-in tags.",+ ),+ project_id: Optional[str] = Query(None, description="Search blocks by project id"),server: SyncServer = Depends(get_letta_server),headers: HeaderParams = Depends(get_headers),):"""- Count all blocks created by a user.+ Count all blocks with optional filtering.+ Supports the same filters as list_blocks for consistent querying."""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)- return await server.block_manager.size_async(actor=actor)++ # If no filters are provided, use the simpler size_async method+ if all(param is None or param is False for param in [label, templates_only, name, tags, project_id]):+ return await server.block_manager.size_async(actor=actor)++ return await server.block_manager.count_blocks_async(+ actor=actor,+ label=label,+ is_template=templates_only,+ template_name=name,+ tags=tags,+ match_all_tags=match_all_tags,+ project_id=project_id,+ )@router.post("/", response_model=BlockResponse, operation_id="create_block")diff --git a/letta/server/rest_api/routers/v1/tags.py b/letta/server/rest_api/routers/v1/tags.pyindex 52f2c75f1..5ed147593 100644--- a/letta/server/rest_api/routers/v1/tags.py+++ b/letta/server/rest_api/routers/v1/tags.py@@ -32,11 +32,34 @@ async def list_tags(headers: HeaderParams = Depends(get_headers),):"""- Get the list of all agent tags that have been created.+ Get the list of all tags (from agents and blocks) that have been created."""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)text_filter = name or query_text- tags = await server.agent_manager.list_tags_async(++ # Get tags from both agents and blocks+ agent_tags = await server.agent_manager.list_tags_async(actor=actor, before=before, after=after, limit=limit, query_text=text_filter, ascending=(order == "asc"))- return tags+ block_tags = await server.block_manager.list_tags_async(actor=actor, query_text=text_filter)++ # Merge and deduplicate, then sort and apply pagination+ all_tags = sorted(set(agent_tags) | set(block_tags), reverse=(order == "desc"))++ # Apply cursor-based pagination on merged results+ if after:+ if order == "asc":+ all_tags = [t for t in all_tags if t > after]+ else:+ all_tags = [t for t in all_tags if t < after]+ if before:+ if order == "asc":+ all_tags = [t for t in all_tags if t < before]+ else:+ all_tags = [t for t in all_tags if t > before]++ # Apply limit+ if limit:+ all_tags = all_tags[:limit]++ return all_tagsdiff --git a/letta/services/agent_manager.py b/letta/services/agent_manager.pyindex 9f17a4f82..da2f59138 100644--- a/letta/services/agent_manager.py+++ b/letta/services/agent_manager.py@@ -36,6 +36,7 @@ from letta.orm import (ArchivalPassage,Block as BlockModel,BlocksAgents,+ BlocksTags,Group as GroupModel,GroupsAgents,IdentitiesAgents,@@ -1929,7 +1930,10 @@ class AgentManager:agent = await AgentModel.read_async(db_session=session, identifier=agent_id, actor=actor)for block in agent.core_memory:if block.label == block_label:- return block.to_pydantic()+ pydantic_block = block.to_pydantic()+ tags_result = await session.execute(select(BlocksTags.tag).where(BlocksTags.block_id == block.id))+ pydantic_block.tags = [row[0] for row in tags_result.fetchall()]+ return pydantic_blockraise NoResultFound(f"No block with label '{block_label}' found for agent '{agent_id}'")@enforce_types@@ -1941,7 +1945,7 @@ class AgentManager:block_update: BlockUpdate,actor: PydanticUser,) -> PydanticBlock:- """Gets a block attached to an agent by its label."""+ """Modifies a block attached to an agent by its label."""async with db_registry.async_session() as session:matched_block = Noneagent = await AgentModel.read_async(db_session=session, identifier=agent_id, actor=actor)@@ -1954,6 +1958,9 @@ class AgentManager:update_data = block_update.model_dump(to_orm=True, exclude_unset=True, exclude_none=True)+ # Extract tags from update data (it's not a column on the block table)+ new_tags = update_data.pop("tags", None)+# Validate limit constraints before updatingvalidate_block_limit_constraint(update_data, matched_block)@@ -1961,7 +1968,23 @@ class AgentManager:setattr(matched_block, key, value)await matched_block.update_async(session, actor=actor)- return matched_block.to_pydantic()++ if new_tags is not None:+ await BlockManager._replace_block_pivot_rows_async(+ session,+ BlocksTags.__table__,+ matched_block.id,+ [{"block_id": matched_block.id, "tag": tag} for tag in new_tags],+ )++ pydantic_block = matched_block.to_pydantic()+ if new_tags is not None:+ pydantic_block.tags = new_tags+ else:+ tags_result = await session.execute(select(BlocksTags.tag).where(BlocksTags.block_id == matched_block.id))+ pydantic_block.tags = [row[0] for row in tags_result.fetchall()]++ return pydantic_block@enforce_types@raise_on_invalid_id(param_name="agent_id", expected_prefix=PrimitiveType.AGENT)@@ -3015,7 +3038,25 @@ class AgentManager:result = await session.execute(query)blocks = result.scalars().all()- return [block.to_pydantic() for block in blocks]+ if not blocks:+ return []++ block_ids = [block.id for block in blocks]+ tags_result = await session.execute(select(BlocksTags.block_id, BlocksTags.tag).where(BlocksTags.block_id.in_(block_ids)))+ tags_by_block: Dict[str, List[str]] = {}+ for row in tags_result.fetchall():+ block_id, tag = row+ if block_id not in tags_by_block:+ tags_by_block[block_id] = []+ tags_by_block[block_id].append(tag)++ pydantic_blocks = []+ for block in blocks:+ pydantic_block = block.to_pydantic()+ pydantic_block.tags = tags_by_block.get(block.id, [])+ pydantic_blocks.append(pydantic_block)++ return pydantic_blocks@enforce_types@trace_methoddiff --git a/letta/services/block_manager.py b/letta/services/block_manager.pyindex 5229ba1e6..3876bc406 100644--- a/letta/services/block_manager.py+++ b/letta/services/block_manager.py@@ -2,8 +2,12 @@ import asynciofrom datetime import datetimefrom typing import Dict, List, Optional-from sqlalchemy import and_, delete, func, or_, select+import sqlalchemy as sa+from sqlalchemy import and_, delete, exists, func, literal, or_, select+from sqlalchemy.dialects.postgresql import insert as pg_insertfrom sqlalchemy.ext.asyncio import AsyncSession+from sqlalchemy.orm import noload+from sqlalchemy.sql.expression import tuple_from letta.errors import LettaInvalidArgumentErrorfrom letta.log import get_logger@@ -11,7 +15,9 @@ from letta.orm.agent import Agent as AgentModelfrom letta.orm.block import Block as BlockModelfrom letta.orm.block_history import BlockHistoryfrom letta.orm.blocks_agents import BlocksAgents+from letta.orm.blocks_tags import BlocksTagsfrom letta.orm.errors import NoResultFound+from letta.orm.sqlalchemy_base import AccessTypefrom letta.otel.tracing import trace_methodfrom letta.schemas.agent import AgentState as PydanticAgentStatefrom letta.schemas.block import Block as PydanticBlock, BlockUpdate@@ -84,6 +90,68 @@ def validate_block_creation(block_data: dict) -> None:class BlockManager:"""Manager class to handle business logic related to Blocks."""+ # ======================================================================================================================+ # Helper methods for pivot tables+ # ======================================================================================================================++ @staticmethod+ async def _bulk_insert_block_pivot_async(session, table, rows: list[dict]):+ """Bulk insert rows into a pivot table, ignoring conflicts."""+ if not rows:+ return++ dialect = session.bind.dialect.name+ if dialect == "postgresql":+ stmt = pg_insert(table).values(rows).on_conflict_do_nothing()+ elif dialect == "sqlite":+ stmt = sa.insert(table).values(rows).prefix_with("OR IGNORE")+ else:+ # fallback: filter out exact-duplicate dicts in Python+ seen = set()+ filtered = []+ for row in rows:+ key = tuple(sorted(row.items()))+ if key not in seen:+ seen.add(key)+ filtered.append(row)+ stmt = sa.insert(table).values(filtered)++ await session.execute(stmt)++ @staticmethod+ async def _replace_block_pivot_rows_async(session, table, block_id: str, rows: list[dict]):+ """+ Replace all pivot rows for a block atomically using MERGE pattern.+ Only supports PostgreSQL (blocks_tags table not supported on SQLite).+ """+ dialect = session.bind.dialect.name++ if dialect == "postgresql":+ if rows:+ # separate upsert and delete operations+ stmt = pg_insert(table).values(rows)+ stmt = stmt.on_conflict_do_nothing()+ await session.execute(stmt)++ # delete rows not in new set+ pk_names = [c.name for c in table.primary_key.columns]+ new_keys = [tuple(r[c] for c in pk_names) for r in rows]+ await session.execute(+ delete(table).where(table.c.block_id == block_id, ~tuple_(*[table.c[c] for c in pk_names]).in_(new_keys))+ )+ else:+ # if no rows to insert, just delete all+ await session.execute(delete(table).where(table.c.block_id == block_id))+ else:+ # fallback: use original DELETE + INSERT pattern+ await session.execute(delete(table).where(table.c.block_id == block_id))+ if rows:+ await BlockManager._bulk_insert_block_pivot_async(session, table, rows)++ # ======================================================================================================================+ # Basic CRUD operations+ # ======================================================================================================================+@enforce_types@trace_methodasync def create_or_update_block_async(self, block: PydanticBlock, actor: PydanticUser) -> PydanticBlock:@@ -95,11 +163,23 @@ class BlockManager:else:async with db_registry.async_session() as session:data = block.model_dump(to_orm=True, exclude_none=True)+ # Extract tags before creating the ORM model (tags is not a column)+ tags = data.pop("tags", None) or []+# Validate block creation constraintsvalidate_block_creation(data)- block = BlockModel(**data, organization_id=actor.organization_id)- await block.create_async(session, actor=actor, no_commit=True, no_refresh=True)- pydantic_block = block.to_pydantic()+ block_model = BlockModel(**data, organization_id=actor.organization_id)+ await block_model.create_async(session, actor=actor, no_commit=True, no_refresh=True)++ if tags:+ await self._bulk_insert_block_pivot_async(+ session,+ BlocksTags.__table__,+ [{"block_id": block_model.id, "tag": tag, "organization_id": actor.organization_id} for tag in tags],+ )++ pydantic_block = block_model.to_pydantic()+ pydantic_block.tags = tags# context manager now handles commits# await session.commit()return pydantic_block@@ -119,10 +199,13 @@ class BlockManager:return []async with db_registry.async_session() as session:- # Validate all blocks before creating anyvalidated_data = []- for block in blocks:+ tags_by_index: Dict[int, List[str]] = {}+ for i, block in enumerate(blocks):block_data = block.model_dump(to_orm=True, exclude_none=True)+ tags = block_data.pop("tags", None) or []+ if tags:+ tags_by_index[i] = tagsvalidate_block_creation(block_data)validated_data.append(block_data)@@ -130,9 +213,22 @@ class BlockManager:created_models = await BlockModel.batch_create_async(items=block_models, db_session=session, actor=actor, no_commit=True, no_refresh=True)- result = [m.to_pydantic() for m in created_models]- # context manager now handles commits- # await session.commit()++ all_tag_rows = []+ for i, model in enumerate(created_models):+ if i in tags_by_index:+ for tag in tags_by_index[i]:+ all_tag_rows.append({"block_id": model.id, "tag": tag, "organization_id": actor.organization_id})++ if all_tag_rows:+ await self._bulk_insert_block_pivot_async(session, BlocksTags.__table__, all_tag_rows)++ result = []+ for i, model in enumerate(created_models):+ pydantic_block = model.to_pydantic()+ pydantic_block.tags = tags_by_index.get(i, [])+ result.append(pydantic_block)+return result@enforce_types@@ -144,6 +240,9 @@ class BlockManager:block = await BlockModel.read_async(db_session=session, identifier=block_id, actor=actor)update_data = block_update.model_dump(to_orm=True, exclude_unset=True, exclude_none=True)+ # Extract tags from update data (it's not a column on the block table)+ new_tags = update_data.pop("tags", None)+# Validate limit constraints before updatingvalidate_block_limit_constraint(update_data, block)@@ -151,7 +250,22 @@ class BlockManager:setattr(block, key, value)await block.update_async(db_session=session, actor=actor, no_commit=True, no_refresh=True)++ if new_tags is not None:+ await self._replace_block_pivot_rows_async(+ session,+ BlocksTags.__table__,+ block_id,+ [{"block_id": block_id, "tag": tag, "organization_id": block.organization_id} for tag in new_tags],+ )+pydantic_block = block.to_pydantic()+ if new_tags is not None:+ pydantic_block.tags = new_tags+ else:+ result = await session.execute(select(BlocksTags.tag).where(BlocksTags.block_id == block_id))+ pydantic_block.tags = [row[0] for row in result.fetchall()]+# context manager now handles commits# await session.commit()return pydantic_block@@ -164,6 +278,8 @@ class BlockManager:async with db_registry.async_session() as session:# First, delete all references in blocks_agents tableawait session.execute(delete(BlocksAgents).where(BlocksAgents.block_id == block_id))+ # Also delete all tags associated with this block+ await session.execute(delete(BlocksTags).where(BlocksTags.block_id == block_id))await session.flush()# Then delete the block itself@@ -192,19 +308,18 @@ class BlockManager:connected_to_agents_count_eq: Optional[List[int]] = None,ascending: bool = True,show_hidden_blocks: Optional[bool] = None,+ tags: Optional[List[str]] = None,+ match_all_tags: bool = False,) -> List[PydanticBlock]:"""Async version of get_blocks method. Retrieve blocks based on various optional filters."""- from sqlalchemy import select- from sqlalchemy.orm import noload-- from letta.orm.sqlalchemy_base import AccessType-async with db_registry.async_session() as session:# Start with a basic queryquery = select(BlockModel)# Explicitly avoid loading relationships- query = query.options(noload(BlockModel.agents), noload(BlockModel.identities), noload(BlockModel.groups))+ query = query.options(+ noload(BlockModel.agents), noload(BlockModel.identities), noload(BlockModel.groups), noload(BlockModel.tags)+ )# Apply access controlquery = BlockModel.apply_access_predicate(query, actor, ["read"], AccessType.ORGANIZATION)@@ -295,6 +410,20 @@ class BlockManager:query = query.join(BlockModel.identities).filter(BlockModel.identities.property.mapper.class_.id == identity_id)needs_distinct = True+ if tags:+ if match_all_tags:+ # Must match ALL tags - use subquery with having count+ tag_subquery = (+ select(BlocksTags.block_id)+ .where(BlocksTags.tag.in_(tags))+ .group_by(BlocksTags.block_id)+ .having(func.count(BlocksTags.tag) == literal(len(tags)))+ )+ query = query.where(BlockModel.id.in_(tag_subquery))+ else:+ # Must match ANY tag+ query = query.where(exists().where((BlocksTags.block_id == BlockModel.id) & (BlocksTags.tag.in_(tags))))+if after:result = (await session.execute(select(BlockModel.created_at, BlockModel.id).where(BlockModel.id == after))).first()if result:@@ -353,17 +482,39 @@ class BlockManager:result = await session.execute(query)blocks = result.scalars().all()- return [block.to_pydantic() for block in blocks]+ if not blocks:+ return []++ block_ids = [block.id for block in blocks]+ tags_result = await session.execute(select(BlocksTags.block_id, BlocksTags.tag).where(BlocksTags.block_id.in_(block_ids)))+ tags_by_block: Dict[str, List[str]] = {}+ for row in tags_result.fetchall():+ block_id, tag = row+ if block_id not in tags_by_block:+ tags_by_block[block_id] = []+ tags_by_block[block_id].append(tag)++ pydantic_blocks = []+ for block in blocks:+ pydantic_block = block.to_pydantic()+ pydantic_block.tags = tags_by_block.get(block.id, [])+ pydantic_blocks.append(pydantic_block)++ return pydantic_blocks@enforce_types@raise_on_invalid_id(param_name="block_id", expected_prefix=PrimitiveType.BLOCK)@trace_methodasync def get_block_by_id_async(self, block_id: str, actor: Optional[PydanticUser] = None) -> Optional[PydanticBlock]:- """Retrieve a block by its name."""+ """Retrieve a block by its ID, including tags."""async with db_registry.async_session() as session:try:block = await BlockModel.read_async(db_session=session, identifier=block_id, actor=actor)- return block.to_pydantic()+ pydantic_block = block.to_pydantic()+ tags_result = await session.execute(select(BlocksTags.tag).where(BlocksTags.block_id == block_id))+ pydantic_block.tags = [row[0] for row in tags_result.fetchall()]++ return pydantic_blockexcept NoResultFound:return None@@ -371,11 +522,6 @@ class BlockManager:@trace_methodasync def get_all_blocks_by_ids_async(self, block_ids: List[str], actor: Optional[PydanticUser] = None) -> List[PydanticBlock]:"""Retrieve blocks by their ids without loading unnecessary relationships. Async implementation."""- from sqlalchemy import select- from sqlalchemy.orm import noload-- from letta.orm.sqlalchemy_base import AccessType-if not block_ids:return []@@ -387,7 +533,9 @@ class BlockManager:query = query.where(BlockModel.id.in_(block_ids))# Explicitly avoid loading relationships- query = query.options(noload(BlockModel.agents), noload(BlockModel.identities), noload(BlockModel.groups))+ query = query.options(+ noload(BlockModel.agents), noload(BlockModel.identities), noload(BlockModel.groups), noload(BlockModel.tags)+ )# Apply access control if actor is providedif actor:@@ -522,6 +670,88 @@ class BlockManager:async with db_registry.async_session() as session:return await BlockModel.size_async(db_session=session, actor=actor)+ @enforce_types+ @trace_method+ async def count_blocks_async(+ self,+ actor: PydanticUser,+ label: Optional[str] = None,+ is_template: Optional[bool] = None,+ template_name: Optional[str] = None,+ project_id: Optional[str] = None,+ tags: Optional[List[str]] = None,+ match_all_tags: bool = False,+ ) -> int:+ """+ Count blocks with optional filtering. Supports same filters as get_blocks_async.+ """+ async with db_registry.async_session() as session:+ query = select(func.count(BlockModel.id))++ # Apply access control+ query = BlockModel.apply_access_predicate(query, actor, ["read"], AccessType.ORGANIZATION)+ query = query.where(BlockModel.organization_id == actor.organization_id)++ # Apply filters+ if label:+ query = query.where(BlockModel.label == label)+ if is_template is not None:+ query = query.where(BlockModel.is_template == is_template)+ if template_name:+ query = query.where(BlockModel.template_name == template_name)+ if project_id:+ query = query.where(BlockModel.project_id == project_id)++ # Apply tag filtering+ if tags:+ if match_all_tags:+ tag_subquery = (+ select(BlocksTags.block_id)+ .where(BlocksTags.tag.in_(tags))+ .group_by(BlocksTags.block_id)+ .having(func.count(BlocksTags.tag) == literal(len(tags)))+ )+ query = query.where(BlockModel.id.in_(tag_subquery))+ else:+ query = query.where(exists().where((BlocksTags.block_id == BlockModel.id) & (BlocksTags.tag.in_(tags))))++ result = await session.execute(query)+ return result.scalar() or 0++ @enforce_types+ @trace_method+ async def list_tags_async(+ self,+ actor: PydanticUser,+ query_text: Optional[str] = None,+ ) -> List[str]:+ """+ Get all unique block tags for the actor's organization.++ Args:+ actor: User performing the action.+ query_text: Filter tags by text search.++ Returns:+ List[str]: List of unique block tags.+ """+ async with db_registry.async_session() as session:+ query = (+ select(BlocksTags.tag)+ .join(BlockModel, BlocksTags.block_id == BlockModel.id)+ .where(BlockModel.organization_id == actor.organization_id)+ .distinct()+ )++ if query_text:+ if settings.database_engine is DatabaseChoice.POSTGRES:+ query = query.where(BlocksTags.tag.ilike(f"%{query_text}%"))+ else:+ query = query.where(func.lower(BlocksTags.tag).like(func.lower(f"%{query_text}%")))++ result = await session.execute(query)+ return [row[0] for row in result.fetchall()]+# Block History Functions@enforce_typesdiff --git a/tests/managers/test_agent_manager.py b/tests/managers/test_agent_manager.pyindex 72bcd2fe2..157671144 100644--- a/tests/managers/test_agent_manager.py+++ b/tests/managers/test_agent_manager.py@@ -1766,6 +1766,7 @@ async def test_agent_state_schema_unchanged(server: SyncServer):"hidden","created_by_id","last_updated_by_id",+ "tags",}actual_block_fields = set(block_fields.keys())if actual_block_fields != expected_block_fields:diff --git a/tests/managers/test_block_manager.py b/tests/managers/test_block_manager.pyindex f4007f24b..65f6d3ba7 100644--- a/tests/managers/test_block_manager.py+++ b/tests/managers/test_block_manager.py@@ -1282,3 +1282,141 @@ async def test_redo_concurrency_stale(server: SyncServer, default_user):# an out-of-date version of the blockwith pytest.raises(StaleDataError):await block_manager.redo_checkpoint_block(block_id=block.id, actor=default_user, use_preloaded_block=block_s2)+++# ======================================================================================================================+# Block Tags Tests+# ======================================================================================================================+++async def test_block_tags_create_and_update(server: SyncServer, default_user):+ """Test creating a block with tags and updating tags"""+ block_manager = BlockManager()++ # Create a block with tags+ block = PydanticBlock(+ label="test_tags",+ value="Block with tags",+ tags=["tag1", "tag2", "important"],+ )+ created_block = await block_manager.create_or_update_block_async(block, actor=default_user)++ # Verify tags were saved+ assert set(created_block.tags) == {"tag1", "tag2", "important"}++ # Update the block with new tags+ from letta.schemas.block import BlockUpdate++ updated_block = await block_manager.update_block_async(+ block_id=created_block.id,+ block_update=BlockUpdate(tags=["tag1", "new_tag"]),+ actor=default_user,+ )++ # Verify tags were updated+ assert set(updated_block.tags) == {"tag1", "new_tag"}++ # Clear all tags+ cleared_block = await block_manager.update_block_async(+ block_id=created_block.id,+ block_update=BlockUpdate(tags=[]),+ actor=default_user,+ )+ assert cleared_block.tags == []+++async def test_block_tags_filter_any(server: SyncServer, default_user):+ """Test filtering blocks by tags (match ANY)"""+ block_manager = BlockManager()++ # Create blocks with different tags+ block1 = await block_manager.create_or_update_block_async(+ PydanticBlock(label="b1", value="v1", tags=["alpha", "beta"]),+ actor=default_user,+ )+ block2 = await block_manager.create_or_update_block_async(+ PydanticBlock(label="b2", value="v2", tags=["beta", "gamma"]),+ actor=default_user,+ )+ block3 = await block_manager.create_or_update_block_async(+ PydanticBlock(label="b3", value="v3", tags=["delta"]),+ actor=default_user,+ )++ # Filter by tag "beta" (match ANY)+ results = await block_manager.get_blocks_async(actor=default_user, tags=["beta"], match_all_tags=False)+ result_ids = {b.id for b in results}+ assert block1.id in result_ids+ assert block2.id in result_ids+ assert block3.id not in result_ids++ # Filter by tag "alpha" or "delta" (match ANY)+ results = await block_manager.get_blocks_async(actor=default_user, tags=["alpha", "delta"], match_all_tags=False)+ result_ids = {b.id for b in results}+ assert block1.id in result_ids+ assert block2.id not in result_ids+ assert block3.id in result_ids+++async def test_block_tags_filter_all(server: SyncServer, default_user):+ """Test filtering blocks by tags (match ALL)"""+ block_manager = BlockManager()++ # Create blocks with different tags+ block1 = await block_manager.create_or_update_block_async(+ PydanticBlock(label="b1", value="v1", tags=["x", "y", "z"]),+ actor=default_user,+ )+ block2 = await block_manager.create_or_update_block_async(+ PydanticBlock(label="b2", value="v2", tags=["x", "y"]),+ actor=default_user,+ )+ block3 = await block_manager.create_or_update_block_async(+ PydanticBlock(label="b3", value="v3", tags=["x"]),+ actor=default_user,+ )++ # Filter by tags "x" AND "y" (match ALL)+ results = await block_manager.get_blocks_async(actor=default_user, tags=["x", "y"], match_all_tags=True)+ result_ids = {b.id for b in results}+ assert block1.id in result_ids+ assert block2.id in result_ids+ assert block3.id not in result_ids++ # Filter by tags "x", "y", AND "z" (match ALL)+ results = await block_manager.get_blocks_async(actor=default_user, tags=["x", "y", "z"], match_all_tags=True)+ result_ids = {b.id for b in results}+ assert block1.id in result_ids+ assert block2.id not in result_ids+ assert block3.id not in result_ids+++async def test_block_tags_count(server: SyncServer, default_user):+ """Test counting blocks with tag filters"""+ block_manager = BlockManager()++ # Create blocks with different tags+ await block_manager.create_or_update_block_async(+ PydanticBlock(label="c1", value="v1", tags=["count_test", "a"]),+ actor=default_user,+ )+ await block_manager.create_or_update_block_async(+ PydanticBlock(label="c2", value="v2", tags=["count_test", "b"]),+ actor=default_user,+ )+ await block_manager.create_or_update_block_async(+ PydanticBlock(label="c3", value="v3", tags=["other"]),+ actor=default_user,+ )++ # Count blocks with tag "count_test"+ count = await block_manager.count_blocks_async(actor=default_user, tags=["count_test"], match_all_tags=False)+ assert count == 2++ # Count blocks with tags "count_test" AND "a"+ count = await block_manager.count_blocks_async(actor=default_user, tags=["count_test", "a"], match_all_tags=True)+ assert count == 1