plexus-python-pulse-common 1.1.75__py3-none-any.whl

plexus/pulse/common/utils/tagutils.py

@@ -0,0 +1,1476 @@
+import contextlib
+import dataclasses
+import datetime
+import math
+import os
+import pathlib
+import textwrap
+import threading
+import typing
+from collections.abc import Generator, Mapping, Sequence
+from typing import Self
+
+import jinja2
+import jsonschema
+import pydantic as pdt
+import sqlalchemy as sa
+import sqlalchemy.dialects.sqlite as sa_sqlite
+import sqlalchemy.orm as sa_orm
+from plexus.common.utils.dbutils import ConnectionMaker
+from plexus.common.utils.dtutils import dt_from_ts_us, dt_to_ts_us
+from plexus.common.utils.funcutils import Chainable
+from plexus.common.utils.funcutils import chainable, memorized, singleton
+from plexus.common.utils.iterutils import batched, head_or_none
+from plexus.common.utils.iterutils import dicttree
+from plexus.common.utils.iterutils import dicttree_add, dicttree_remove
+from plexus.common.utils.iterutils import dicttree_children, dicttree_lineage, dicttree_subtree
+from plexus.common.utils.jsonutils import JsonObject, JsonType
+from plexus.common.utils.randutils import randomizer
+from plexus.common.utils.strutils import is_blank
+from sqlmodel import Field
+
+from plexus.pulse.common.resources.tags import predefined_tagset_specs
+from plexus.pulse.common.utils.datautils import validate_colon_tag, validate_snake_case, validate_vehicle_name
+from plexus.pulse.common.utils.datautils import validate_dt_timezone, validate_semver, validate_slash_tag
+from plexus.pulse.common.utils.jsonutils import json_datetime_encoder
+from plexus.pulse.common.utils.ormutils import SQLiteDateTime, SequenceModelMixinProtocol
+from plexus.pulse.common.utils.ormutils import clone_sequence_model_instance, make_base_model, make_sequence_model_mixin
+from plexus.pulse.common.utils.sqlutils import escape_sql_like
+
+__all__ = [
+    "versioned_identifier",
+    "split_versioned_identifier",
+    "RichDesc",
+    "Tag",
+    "BoundTag",
+    "Tagset",
+    "MutableTagset",
+    "populate_tagset",
+    "predefined_tagsets",
+    "render_tagset_markdown_readme",
+    "make_tag_target_model_mixin",
+    "make_tag_record_model_mixin",
+    "TagTarget",
+    "TagRecord",
+    "TagTargetTable",
+    "TagRecordTable",
+    "tag_cache_file_path",
+    "TagCache",
+    "tag_cache",
+    "standard_clip_duration_us",
+    "populate_clip_ranges",
+]
+
+
+def versioned_identifier(identifier: str | None, version: str | None) -> str | None:
+    if identifier is None or version is None:
+        return identifier
+    return f"{identifier}@{version}"
+
+
+def split_versioned_identifier(s: str | None) -> tuple[str | None, str | None]:
+    if s is None:
+        return None, None
+    if "@" not in s:
+        return s, None
+    identifier, version = s.rsplit("@", 1)
+    return identifier, version
+
+
+@dataclasses.dataclass(frozen=True, eq=True, order=True)
+class RichDesc(object):
+    type: str
+    text: str
+
+
+@dataclasses.dataclass(frozen=True, eq=True, order=True)
+class Tag(object):
+    name: str
+    desc: str | RichDesc | None
+    schema: JsonObject | None = None
+
+    @property
+    def tag_parts(self) -> list[str]:
+        return self.name.rsplit(":")
+
+    @property
+    def parent_tag_name(self) -> str | None:
+        name = head_or_none(self.name.rsplit(":", 1))
+        return None if is_blank(name) or name == self.name else name
+
+    def unbind(self) -> Self:
+        return self
+
+    def validate(self, features: JsonType | None, *, raise_on_error: bool = False) -> bool:
+        if self.schema is None or features is None:
+            return True
+        try:
+            jsonschema.Draft7Validator(self.schema).validate(features)
+            return True
+        except (jsonschema.ValidationError, jsonschema.SchemaError):
+            if raise_on_error:
+                raise
+            return False
+
+
+@dataclasses.dataclass(frozen=True, eq=True, order=True)
+class BoundTag(Tag):
+    namespace: str | None = None
+    version: str | None = None
+
+    def unbind(self) -> Tag:
+        return Tag(name=self.name, desc=self.desc, schema=self.schema)
+
+
+class Tagset(Sequence[Tag], Mapping[str, Tag]):
+    def __init__(self, namespace: str, version: str, desc: str | RichDesc) -> None:
+        super().__init__()
+        self.namespace = namespace
+        self.version = version
+        self.desc = desc
+        self.tags: list[Tag] = []
+        self.tags_dict: dict[str, Tag] = {}
+        self.tags_tree: dicttree[str, Tag] = {}
+
+    def __contains__(self, item: str | Tag | BoundTag | None) -> bool:
+        try:
+            return self.get(item) is not None
+        except ValueError:
+            return False
+
+    def __len__(self) -> int:
+        return len(self.tags)
+
+    def __getitem__(self, index: int) -> Tag:
+        return self.tags[index]
+
+    def keys(self):
+        return self.tags_dict.keys()
+
+    def values(self):
+        return self.tags_dict.values()
+
+    def items(self):
+        return self.tags_dict.items()
+
+    def get(self, item: str | Tag | BoundTag) -> Tag | None:
+        if item is None:
+            return None
+        if isinstance(item, BoundTag):
+            if item.namespace != self.namespace or item.version != self.version:
+                raise ValueError(f"tag bind '{item}' does not belong to this tagset")
+        tag_name = item.name if isinstance(item, Tag) else item
+        return self.tags_dict.get(tag_name)
+
+    def bind(self, tag: Tag) -> BoundTag:
+        return BoundTag(tag.name, tag.desc, tag.schema, self.namespace, self.version)
+
+    def get_bound(self, item: str | Tag | BoundTag) -> BoundTag | None:
+        tag = self.get(item)
+        return None if tag is None else self.bind(tag)
+
+    def clone(self) -> Self:
+        return clone_tagset(self)
+
+    def mutable(self):
+        return clone_mutable_tagset(self)
+
+    def frozen(self):
+        return self.clone()
+
+    @property
+    def tag_names(self) -> list[str]:
+        return list(self.tags_dict.keys())
+
+    def child_tags(self, parent: str | Tag | BoundTag) -> list[Tag]:
+        parent = self.get(parent)
+        if parent is None:
+            return []
+        subtree = dicttree_subtree(self.tags_tree, parent.tag_parts)
+        return list(dicttree_children(subtree)) if subtree else []
+
+    def parent_tags(self, child: str | Tag | BoundTag) -> list[Tag]:
+        child = self.get(child)
+        if child is None:
+            return []
+        return list(dicttree_lineage(self.tags_tree, child.tag_parts[:-1]))
+
+    def validate(self, tag_name: str, features: JsonType | None, *, raise_on_error: bool = False) -> bool:
+        tag = self.get(tag_name)
+        return False if tag is None else tag.validate(features, raise_on_error=raise_on_error)
+
+
+class MutableTagset(Tagset):
+
+    def clone(self) -> Self:
+        return clone_mutable_tagset(self)
+
+    def mutable(self):
+        return self.clone()
+
+    def frozen(self):
+        return clone_tagset(self)
+
+    def add(self, tag: Tag | BoundTag) -> Self:
+        if tag.name in self.tags_dict:
+            raise ValueError(f"duplicate tag name '{tag.name}'")
+        if isinstance(tag, BoundTag):
+            if tag.namespace != self.namespace or tag.version != self.version:
+                raise ValueError(f"tag bind '{tag}' does not belong to this tagset")
+
+        tag = tag.unbind()
+
+        self.tags.append(tag)
+        self.tags_dict[tag.name] = tag
+
+        dicttree_add(self.tags_tree, tag.tag_parts, tag, create_prefix=True)
+
+        return self
+
+    def remove(self, tag_name: str) -> Self:
+        tag = self.get(tag_name)
+        if tag is None:
+            raise ValueError(f"tag '{tag_name}' not found")
+
+        self.tags.remove(tag)
+        del self.tags_dict[tag_name]
+
+        dicttree_remove(self.tags_tree, tag.tag_parts, recursive=True)
+
+        return self
+
+
+def clone_tagset(tagset: Tagset) -> Tagset:
+    tagset = clone_mutable_tagset(tagset)
+    new_tagset = Tagset(namespace=tagset.namespace, version=tagset.version, desc=tagset.desc)
+    new_tagset.tags = tagset.tags
+    new_tagset.tags_dict = tagset.tags_dict
+    new_tagset.tags_tree = tagset.tags_tree
+    return new_tagset
+
+
+def clone_mutable_tagset(tagset: Tagset) -> MutableTagset:
+    new_tagset = MutableTagset(namespace=tagset.namespace, version=tagset.version, desc=tagset.desc)
+    for tag in tagset.tags:
+        new_tagset.add(tag)
+    return new_tagset
+
+
+def populate_tagset(tagset_spec: JsonObject) -> Tagset:
+    """
+    Collect tags from tagset spec JSON object, validate the format along the way.
+
+    :param tagset_spec: JSON object of tagset spec
+    :return: Populated Tagset instance
+    """
+
+    def validate_and_collect(name: str, tag_def: JsonObject) -> Generator[Tag, None, None]:
+        if not isinstance(tag_def, dict):
+            raise ValueError(f"tag '{name}' definition is not a dict")
+
+        if not is_blank(name):
+            desc = tag_def.get("$desc")
+            if isinstance(desc, dict):
+                desc = RichDesc(**desc)
+
+            schema = tag_def.get("$schema")
+            if schema is not None:
+                try:
+                    jsonschema.Draft7Validator.check_schema(schema)
+                except jsonschema.SchemaError as e:
+                    raise ValueError(f"invalid JSON schema for tag '{name}'") from e
+
+            yield Tag(name=name, desc=desc, schema=schema)
+
+        for child_name, child_tag_def in tag_def.items():
+            if child_name in ("$desc", "$schema"):
+                continue
+
+            if not isinstance(child_name, str):
+                raise ValueError(f"child '{child_name}' of tag '{name}' is not a string")
+            try:
+                validate_snake_case(child_name)
+            except ValueError as e:
+                raise ValueError(f"child '{child_name}' of tag '{name}' is not in snake case") from e
+
+            child_name = name + ":" + child_name if name else child_name
+
+            yield from validate_and_collect(child_name, child_tag_def)
+
+    namespace = tagset_spec.get("$namespace")
+    if namespace is None:
+        raise ValueError("missing '$namespace' in tagset spec")
+    try:
+        validate_snake_case(namespace)
+    except ValueError as e:
+        raise ValueError(f"tagset namespace '{namespace}' is not in snake case") from e
+
+    version = tagset_spec.get("$version")
+    if version is None:
+        raise ValueError("missing '$version' in tagset spec")
+    try:
+        validate_semver(version)
+    except ValueError as e:
+        raise ValueError(f"tagset version '{version}' is not a valid semantic version") from e
+
+    desc = tagset_spec.get("$desc")
+    if desc is None:
+        raise ValueError("missing '$desc' in tagset spec")
+    if isinstance(desc, dict):
+        desc = RichDesc(**desc)
+
+    tags = tagset_spec.get("$tags")
+    if tags is None:
+        raise ValueError("missing '$tags' in tagset spec")
+
+    tagset = MutableTagset(namespace=namespace, version=version, desc=desc)
+
+    for tag in validate_and_collect("", tags):
+        tagset.add(tag)
+
+    return tagset.frozen()
+
+
+@singleton
+def predefined_tagsets() -> dict[str, Tagset]:
+    from packaging.version import Version
+
+    tagsets: dict[str, Tagset] = {}
+    latest_targets: dict[str, tuple[Version, Tagset]] = {}
+
+    for _, tagset_spec in predefined_tagset_specs():
+        tagset = populate_tagset(tagset_spec)
+        version = Version(tagset.version)
+        if tagset.namespace in latest_targets:
+            latest_version, _ = latest_targets[tagset.namespace]
+            if version > latest_version:
+                latest_targets[tagset.namespace] = (version, tagset)
+        else:
+            latest_targets[tagset.namespace] = (version, tagset)
+
+        tagsets[versioned_identifier(tagset.namespace, tagset.version)] = tagset
+
+    for _, tagset in latest_targets.values():
+        tagsets[tagset.namespace] = tagset
+
+    return tagsets
+
+
+def render_tagset_markdown_readme(tagset: Tagset) -> str:
+    def render_desc(desc: str | RichDesc | None) -> str:
+        if desc is None:
+            return ""
+        if isinstance(desc, str):
+            return desc
+        if isinstance(desc, RichDesc):
+            return desc.text
+        raise ValueError(f"unsupported desc type '{type(desc)}'")
+
+    template_str = textwrap.dedent(
+        """
+        # Tagset {{ tagset.namespace }} (Version {{ tagset.version }})
+
+        {{ tagset.desc | render_desc }}
+
+        ## Contents
+
+        {% for tag in tagset.tags %}
+        - {{ tag.name }}
+        {% endfor %}
+
+        ## Tags
+
+        {% for tag in tagset.tags %}
+        ### {{ tag.name }}
+
+        {{ tag.desc | render_desc }}
+
+        {% endfor %}
+        """
+    )
+
+    env = jinja2.Environment(trim_blocks=True, lstrip_blocks=True)
+    env.filters["render_desc"] = render_desc
+
+    return env.from_string(template_str).render(tagset=tagset)
+
+
+def make_tag_target_model_mixin() -> type[pdt.BaseModel]:
+    class ModelMixin(pdt.BaseModel):
+        identifier: str = Field(
+            sa_column=sa.Column(sa_sqlite.VARCHAR(256), nullable=False, unique=True),
+            description="Identifier of the tag target",
+        )
+        tagger_name: str = Field(
+            sa_column=sa.Column(sa_sqlite.VARCHAR(128), nullable=False),
+            description="Name of the tagger that generates the tag records for the target",
+        )
+        tagger_version: str = Field(
+            sa_column=sa.Column(sa_sqlite.VARCHAR(32), nullable=False),
+            description="Version of the tagger that generates the tag records for the target",
+        )
+        vehicle_name: str = Field(
+            sa_column=sa.Column(sa_sqlite.VARCHAR(128), nullable=False),
+            description="Name of the tagger's applicability vehicle",
+        )
+        begin_dt: datetime.datetime = Field(
+            sa_column=sa.Column(SQLiteDateTime, nullable=False),
+            description="Beginning of the tagger's applicability time range",
+        )
+        end_dt: datetime.datetime = Field(
+            sa_column=sa.Column(SQLiteDateTime, nullable=False),
+            description="End of the tagger's applicability time range",
+        )
+        props: JsonType | None = Field(
+            sa_column=sa.Column(sa_sqlite.JSON, nullable=True),
+            default=None,
+            description="Additional properties of the tag target in JSON format",
+        )
+
+        @pdt.field_validator("identifier", mode="after")
+        @classmethod
+        def validate_identifier(cls, v: str) -> str:
+            validate_slash_tag(v)
+            return v
+
+        @pdt.field_validator("tagger_name", mode="after")
+        @classmethod
+        def validate_tagger_name(cls, v: str) -> str:
+            validate_slash_tag(v)
+            return v
+
+        @pdt.field_validator("tagger_version", mode="after")
+        @classmethod
+        def validate_tagger_version(cls, v: str) -> str:
+            validate_semver(v)
+            return v
+
+        @pdt.field_validator("vehicle_name", mode="after")
+        @classmethod
+        def validate_vehicle_name(cls, v: str) -> str:
+            validate_vehicle_name(v)
+            return v
+
+        @pdt.field_validator("begin_dt", mode="after")
+        @classmethod
+        def validate_begin_dt(cls, v: datetime.datetime) -> datetime.datetime:
+            validate_dt_timezone(v)
+            return v
+
+        @pdt.field_validator("end_dt", mode="after")
+        @classmethod
+        def validate_end_dt(cls, v: datetime.datetime) -> datetime.datetime:
+            validate_dt_timezone(v)
+            return v
+
+        @pdt.model_validator(mode="after")
+        def validate_begin_dt_end_dt(self) -> Self:
+            if self.begin_dt > self.end_dt:
+                raise ValueError(f"begin_dt '{self.begin_dt}' is greater than end_dt '{self.end_dt}'")
+            return self
+
+        @pdt.field_serializer("begin_dt", mode="plain")
+        def serialize_begin_dt(self, v: datetime.datetime) -> str:
+            return json_datetime_encoder(v)
+
+        @pdt.field_serializer("end_dt", mode="plain")
+        def serialize_end_dt(self, v: datetime.datetime) -> str:
+            return json_datetime_encoder(v)
+
+    return ModelMixin
+
+
+def make_tag_record_model_mixin() -> type[pdt.BaseModel]:
+    class ModelMixin(pdt.BaseModel):
+        target_sqn: int = Field(
+            sa_column=sa.Column(sa_sqlite.INTEGER, nullable=False),
+            description="Sequence number of the tag record's target",
+        )
+        begin_dt: datetime.datetime = Field(
+            sa_column=sa.Column(SQLiteDateTime, nullable=False),
+            description="Begin of the tag record time range",
+        )
+        end_dt: datetime.datetime = Field(
+            sa_column=sa.Column(SQLiteDateTime, nullable=False),
+            description="End of the tag record time range",
+        )
+        tagset_namespace: str | None = Field(
+            sa_column=sa.Column(sa_sqlite.VARCHAR(64), nullable=True),
+            default=None,
+            description="Namespace of the tagset that the tag in this record belongs to",
+        )
+        tagset_version: str | None = Field(
+            sa_column=sa.Column(sa_sqlite.VARCHAR(32), nullable=True),
+            default=None,
+            description="Version of the tagset that the tag in this record belongs to",
+        )
+        tag: str = Field(
+            sa_column=sa.Column(sa_sqlite.VARCHAR(256), nullable=False),
+            description="Tag name",
+        )
+        features: JsonType | None = Field(
+            sa_column=sa.Column(sa_sqlite.JSON, nullable=True),
+            default=None,
+            description="Tag features in JSON format, which can be used for storing preprocessed information of the tag record to facilitate querying and filtering",
+        )
+        props: JsonType | None = Field(
+            sa_column=sa.Column(sa_sqlite.JSON, nullable=True),
+            default=None,
+            description="Additional properties of the tag record in JSON format",
+        )
+        flags: int = Field(
+            sa_column=sa.Column(sa_sqlite.INTEGER),
+            default=0,
+            description="Integer bitmask storing status or metadata flags for this tag record",
+        )
+
+        @pdt.field_validator("begin_dt", mode="after")
+        @classmethod
+        def validate_begin_dt(cls, v: datetime.datetime) -> datetime.datetime:
+            validate_dt_timezone(v)
+            return v
+
+        @pdt.field_validator("end_dt", mode="after")
+        @classmethod
+        def validate_end_dt(cls, v: datetime.datetime) -> datetime.datetime:
+            validate_dt_timezone(v)
+            return v
+
+        @pdt.field_validator("tagset_namespace", mode="after")
+        @classmethod
+        def validate_tagset_namespace(cls, v: str | None) -> str | None:
+            if v is not None:
+                validate_snake_case(v)
+            return v
+
+        @pdt.field_validator("tagset_version", mode="after")
+        @classmethod
+        def validate_tagset_version(cls, v: str | None) -> str | None:
+            if v is not None:
+                validate_semver(v)
+            return v
+
+        @pdt.model_validator(mode="after")
+        def validate_begin_dt_end_dt(self) -> Self:
+            if self.begin_dt > self.end_dt:
+                raise ValueError(f"begin_dt '{self.begin_dt}' is greater than end_dt '{self.end_dt}'")
+            return self
+
+        @pdt.field_validator("tag", mode="after")
+        @classmethod
+        def validate_tag(cls, v: str) -> str:
+            validate_colon_tag(v)
+            return v
+
+        @pdt.field_serializer("begin_dt", mode="plain")
+        def serialize_begin_dt(self, v: datetime.datetime) -> str:
+            return json_datetime_encoder(v)
+
+        @pdt.field_serializer("end_dt", mode="plain")
+        def serialize_end_dt(self, v: datetime.datetime) -> str:
+            return json_datetime_encoder(v)
+
+    return ModelMixin
+
+
+BaseModel = make_base_model()
+
+
+class TagTarget(BaseModel, make_tag_target_model_mixin()):
+    pass
+
+
+class TagRecord(BaseModel, make_tag_record_model_mixin()):
+    pass
+
+
+class TagTargetTable(TagTarget, make_sequence_model_mixin("sqlite"), table=True):
+    __tablename__ = "tag_target"
+
+
+class TagRecordTable(TagRecord, make_sequence_model_mixin("sqlite"), table=True):
+    __tablename__ = "tag_record"
+
+
+if typing.TYPE_CHECKING:
+    class TagTarget(BaseModel):
+        identifier: sa_orm.Mapped[str] = ...
+        tagger_name: sa_orm.Mapped[str] = ...
+        tagger_version: sa_orm.Mapped[str] = ...
+        vehicle_name: sa_orm.Mapped[str] = ...
+        begin_dt: sa_orm.Mapped[datetime.datetime] = ...
+        end_dt: sa_orm.Mapped[datetime.datetime] = ...
+        props: sa_orm.Mapped[JsonType | None] = ...
+
+
+    class TagTargetTable(TagTarget, SequenceModelMixinProtocol):
+        pass
+
+
+    class TagRecord(BaseModel):
+        target_sqn: sa_orm.Mapped[int] = ...
+        begin_dt: sa_orm.Mapped[datetime.datetime] = ...
+        end_dt: sa_orm.Mapped[datetime.datetime] = ...
+        tagset_namespace: sa_orm.Mapped[str | None] = ...
+        tagset_version: sa_orm.Mapped[str | None] = ...
+        tag: sa_orm.Mapped[str] = ...
+        features: sa_orm.Mapped[JsonType | None] = ...
+        props: sa_orm.Mapped[JsonType | None] = ...
+        flags: sa_orm.Mapped[int] = ...
+
+
+    class TagRecordTable(TagRecord, SequenceModelMixinProtocol):
+        pass
+
+
+@singleton
+def tag_cache_file_path() -> pathlib.Path:
+    return pathlib.Path.home() / ".local" / "plexus" / "tag_cache" / f"{randomizer().random_alphanumeric(7)}.db"
+
+
+class TagCache(object):
+    def __init__(
+        self,
+        *,
+        file_path: str | os.PathLike[str] | None = None,
+        fail_if_exists: bool = False,
+    ):
+        self.file_path = pathlib.Path(file_path or tag_cache_file_path())
+        if fail_if_exists and self.file_path.exists():
+            raise FileExistsError(f"tag cache file '{str(self.file_path)}' already exists")
+        self.file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        self.conn_maker = ConnectionMaker.from_url(f"sqlite:///{str(self.file_path.absolute())}",
+                                                   engine_opts=dict(connect_args={"check_same_thread": False}))
+
+        self.thread_lock = threading.Lock()
+
+        BaseModel.metadata.create_all(self.conn_maker.engine)
+
+    @contextlib.contextmanager
+    def make_session(self) -> Generator[sa_orm.Session, None, None]:
+        with self.thread_lock, self.conn_maker.make_session(expire_on_commit=False) as session:
+            try:
+                yield session
+                session.commit()
+            except Exception:
+                session.rollback()
+                raise
+
+    def get_target(self, target: int | str) -> TagTargetTable | None:
+        with self.make_session() as session:
+            if isinstance(target, int):
+                return session.get(TagTargetTable, target)
+            else:
+                return session.query(TagTargetTable).filter(TagTargetTable.identifier == target).one_or_none()
+
+    def query_targets(
+        self,
+        identifier: str | None = None,
+        tagger_name: str | None = None,
+        tagger_version: str | None = None,
+        vehicle_name: str | None = None,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+    ) -> list[TagTargetTable]:
+        with self.make_session() as session:
+            query_stmt = session.query(TagTargetTable)
+            if identifier:
+                query_stmt = query_stmt.filter(TagTargetTable.identifier == identifier)
+            if tagger_name:
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_name == tagger_name)
+            if tagger_version:
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_version == tagger_version)
+            if vehicle_name:
+                query_stmt = query_stmt.filter(TagTargetTable.vehicle_name == vehicle_name)
+            if begin_dt:
+                query_stmt = query_stmt.filter(TagTargetTable.end_dt >= begin_dt)
+            if end_dt:
+                query_stmt = query_stmt.filter(TagTargetTable.begin_dt <= end_dt)
+
+            return query_stmt.all()
+
+    def add_target(
+        self,
+        identifier: str,
+        tagger_name: str,
+        tagger_version: str,
+        vehicle_name: str,
+        begin_dt: datetime.datetime,
+        end_dt: datetime.datetime,
+        props: JsonType | None = None,
+    ) -> Chainable[Self, TagTargetTable]:
+        """
+        Create a new tag target and add it to the cache.
+
+        :param identifier: Identifier of the tag target, which should be unique across the cache. It is recommended
+                           to use a slash tag (e.g. "dummy_name/dummy_name") to ensure uniqueness and facilitate
+                           organization, but other formats are also allowed as long as they are valid slash tags.
+        :param tagger_name: Name of the tagger creating the tag target.
+        :param tagger_version: Version of the tagger creating the tag target.
+        :param vehicle_name: Name of the vehicle associated with the tag target.
+        :param begin_dt: Start datetime for the tag target's validity period.
+        :param end_dt: End datetime for the tag target's validity period.
+        :param props: Additional properties for the tag target.
+        :return: Self instance for chaining along with the added ``TagTargetTable`` instance
+        """
+        with self.make_session() as session:
+            tag_target = TagTarget(
+                identifier=identifier,
+                tagger_name=tagger_name,
+                tagger_version=tagger_version,
+                vehicle_name=vehicle_name,
+                begin_dt=begin_dt,
+                end_dt=end_dt,
+                props=props,
+            )
+            db_tag_target = clone_sequence_model_instance(TagTargetTable, tag_target)
+            session.add(db_tag_target)
+            session.commit()
+
+        return chainable(self, db_tag_target)
+
+    def remove_targets(
+        self,
+        identifier: str | None = None,
+        tagger_name: str | None = None,
+        tagger_version: str | None = None,
+        vehicle_name: str | None = None,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        *,
+        cascade_records: bool = True,
+    ):
+        """
+        Remove tag targets from the cache that match the specified filters.
+
+        :param identifier: Filter by target identifier (exact match)
+        :param tagger_name: Filter by tagger name (exact match)
+        :param tagger_version: Filter by tagger version (exact match)
+        :param vehicle_name: Filter by vehicle name (exact match)
+        :param begin_dt: Filter by begin time (inclusive)
+        :param end_dt: Filter by end time (inclusive)
+        :param cascade_records: Whether to also remove tag records that are associated with the removed targets.
+                                If False, the tag records will be kept but become orphaned (i.e. their ``target_sqn``
+                                will not have a corresponding target in the cache).
+        :return: Self for chaining
+        """
+        with self.make_session() as session:
+            query_stmt = session.query(TagTargetTable)
+            if identifier:
+                query_stmt = query_stmt.filter(TagTargetTable.identifier == identifier)
+            if tagger_name:
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_name == tagger_name)
+            if tagger_version:
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_version == tagger_version)
+            if vehicle_name:
+                query_stmt = query_stmt.filter(TagTargetTable.vehicle_name == vehicle_name)
+            if begin_dt:
+                query_stmt = query_stmt.filter(TagTargetTable.end_dt >= begin_dt)
+            if end_dt:
+                query_stmt = query_stmt.filter(TagTargetTable.begin_dt <= end_dt)
+
+            query_stmt.delete()
+            session.commit()
+
+            if cascade_records:
+                (
+                    session
+                    .query(TagRecordTable)
+                    .filter(TagRecordTable.target_sqn.notin_(session.query(TagTargetTable.sqn)))
+                    .delete()
+                )
+                session.commit()
+
+            return self
+
+    def with_target(self, target: int | str) -> "TargetedTagCache":
+        db_tag_target = self.get_target(target)
+        if db_tag_target is None:
+            raise ValueError(f"tag target '{target}' not found in cache")
+        return TargetedTagCache(cache=self, tag_target=db_tag_target)
+
+    def count_records(self) -> int:
+        with self.make_session() as session:
+            return session.query(sa.func.count(TagRecordTable.sqn)).scalar()
+
+    def iter_records(
+        self,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
+        *,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+        skip: int | None = None,
+        limit: int | None = None,
+        batch_size: int = 1000,
+    ) -> Generator[TagRecordTable, None, None]:
+        """
+        Query tag records in the cache with optional filters.
+
+        :param begin_dt: Filter by begin time (inclusive)
+        :param end_dt: Filter by end time (inclusive)
+        :param tagset_namespace: Filter by tagset namespace (exact match)
+        :param tagset_version: Filter by tagset version (exact match)
+        :param tag_prefix: Filter by tag name prefix, e.g. "dummy_tag:" to match all tags starting with "dummy_tag:"
+        :param tagsets: Filter by tagsets (match tags that are in any of the specified tagsets)
+        :param tagset_inverted: Whether to invert the tagset filter (match tags that are NOT in any of the specified
+                                tagsets)
+        :param skip: Number of records to skip (for pagination)
+        :param limit: Maximum number of records to return (for pagination)
+        :param batch_size: Number of records to fetch per batch from the database (for memory efficiency)
+        :return: Generator of ``TagRecordTable`` instances that match the filters
+        """
+        with self.make_session() as session:
+            query_stmt = session.query(TagRecordTable)
+            if begin_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
+            if end_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
+            if tagset_namespace:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+            if tagsets:
+                if tagset_inverted:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+                else:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+            if skip is not None or limit is not None:
+                query_stmt = query_stmt.order_by(TagRecordTable.sqn.desc())
+                if skip is not None:
+                    query_stmt = query_stmt.offset(skip)
+                if limit is not None:
+                    query_stmt = query_stmt.limit(limit)
+
+            for result in query_stmt.yield_per(batch_size):
+                yield result
+
+    def iter_record_and_targets(
+        self,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
+        *,
+        target_identifier: str | None = None,
+        target_tagger_name: str | None = None,
+        target_tagger_version: str | None = None,
+        target_vehicle_name: str | None = None,
+        target_begin_dt: datetime.datetime | None = None,
+        target_end_dt: datetime.datetime | None = None,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+        skip: int | None = None,
+        limit: int | None = None,
+        batch_size: int = 1000,
+    ) -> Generator[tuple[TagRecordTable, TagTargetTable], None, None]:
+        """
+        Query tag records along with their target in the cache with optional filters.
+
+        :param begin_dt: Filter by begin time (inclusive)
+        :param end_dt: Filter by end time (inclusive)
+        :param tagset_namespace: Filter by tagset namespace (exact match)
+        :param tagset_version: Filter by tagset version (exact match)
+        :param tag_prefix: Filter by tag name prefix, e.g. "dummy_tag:" to match all tags starting with "dummy_tag:"
+        :param target_identifier: Filter by target identifier (exact match)
+        :param target_tagger_name: Filter by target tagger name (exact match)
+        :param target_tagger_version: Filter by target tagger version (exact match)
+        :param target_vehicle_name: Filter by target vehicle name (exact match)
+        :param target_begin_dt: Filter by target begin time (inclusive)
+        :param target_end_dt: Filter by target end time (inclusive)
+        :param tagsets: Filter by tagsets (match tags that are in any of the specified tagsets)
+        :param tagset_inverted: Whether to invert the tagset filter (match tags that are NOT in any of the specified
+                                tagsets)
+        :param skip: Number of records to skip (for pagination)
+        :param limit: Maximum number of records to return (for pagination)
+        :param batch_size: Number of records to fetch per batch from the database (for memory efficiency)
+        :return: Generator of ``TagRecordTable`` instances that match the filters
+        """
+        with self.make_session() as session:
+            query_stmt = (
+                session
+                .query(TagRecordTable, TagTargetTable)
+                .join(TagTargetTable, TagRecordTable.target_sqn == TagTargetTable.sqn)
+            )
+            if begin_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
+            if end_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
+            if tagset_namespace:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+            if target_identifier:
+                query_stmt = query_stmt.filter(TagTargetTable.identifier == target_identifier)
+            if target_tagger_name:
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_name == target_tagger_name)
+            if target_tagger_version:
+                query_stmt = query_stmt.filter(TagTargetTable.tagger_version == target_tagger_version)
+            if target_vehicle_name:
+                query_stmt = query_stmt.filter(TagTargetTable.vehicle_name == target_vehicle_name)
+            if target_begin_dt:
+                query_stmt = query_stmt.filter(TagTargetTable.end_dt >= target_begin_dt)
+            if target_end_dt:
+                query_stmt = query_stmt.filter(TagTargetTable.begin_dt <= target_end_dt)
+            if tagsets:
+                if tagset_inverted:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+                else:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+            if skip is not None or limit is not None:
+                query_stmt = query_stmt.order_by(TagRecordTable.sqn.desc())
+                if skip is not None:
+                    query_stmt = query_stmt.offset(skip)
+                if limit is not None:
+                    query_stmt = query_stmt.limit(limit)
+
+            for result in query_stmt.yield_per(batch_size):
+                yield result
+
+    def remove_records(
+        self,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
+        *,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+    ) -> Self:
+        """
+        Remove tag records from the cache that match the specified filters.
+
+        :param begin_dt: Filter by begin time (inclusive)
+        :param end_dt: Filter by end time (inclusive)
+        :param tagset_namespace: Filter by tagset namespace (exact match)
+        :param tagset_version: Filter by tagset version (exact match)
+        :param tag_prefix: Filter by tag name prefix, e.g. "dummy_tag:" to match all tags starting with "dummy_tag:"
+        :param tagsets: Filter by tagsets (match tags that are in any of the specified tagsets)
+        :param tagset_inverted: Whether to invert the tagset filter (match tags that are NOT in any of the specified
+                                tagsets)
+        :return: Self for chaining
+        """
+        with self.make_session() as session:
+            query_stmt = session.query(TagRecordTable)
+            if begin_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
+            if end_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
+            if tagset_namespace:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+            if tagsets:
+                if tagset_inverted:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+                else:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+
+            query_stmt.delete()
+            session.commit()
+
+        return self
+
+    def target_count_records(self, target_sqn: int) -> int:
+        with self.make_session() as session:
+            return (
+                session
+                .query(sa.func.count(TagRecordTable.sqn))
+                .filter(TagRecordTable.target_sqn == target_sqn)
+                .scalar()
+            )
+
+    def target_iter_records(
+        self,
+        target_sqn: int,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
+        *,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+        skip: int | None = None,
+        limit: int | None = None,
+        batch_size: int = 1000,
+    ) -> Generator[TagRecordTable, None, None]:
+        """
+        Query tag records in the cache with optional filters.
+
+        :param target_sqn: Filter by target sequence number (exact match)
+        :param begin_dt: Filter by begin time (inclusive)
+        :param end_dt: Filter by end time (inclusive)
+        :param tagset_namespace: Filter by tagset namespace (exact match)
+        :param tagset_version: Filter by tagset version (exact match)
+        :param tag_prefix: Filter by tag name prefix, e.g. "dummy_tag:" to match all tags starting with "dummy_tag:"
+        :param tagsets: Filter by tagsets (match tags that are in any of the specified tagsets)
+        :param tagset_inverted: Whether to invert the tagset filter (match tags that are NOT in any of the specified
+                                tagsets)
+        :param skip: Number of records to skip (for pagination)
+        :param limit: Maximum number of records to return (for pagination)
+        :param batch_size: Number of records to fetch per batch from the database (for memory efficiency)
+        :return: Generator of ``TagRecordTable`` instances that match the filters
+        """
+
+        with self.make_session() as session:
+            query_stmt = session.query(TagRecordTable).filter(TagRecordTable.target_sqn == target_sqn)
+            if begin_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
+            if end_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
+            if tagset_namespace:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+            if tagsets:
+                if tagset_inverted:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+                else:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+            if skip is not None or limit is not None:
+                query_stmt = query_stmt.order_by(TagRecordTable.sqn.desc())
+                if skip is not None:
+                    query_stmt = query_stmt.offset(skip)
+                if limit is not None:
+                    query_stmt = query_stmt.limit(limit)
+
+            for result in query_stmt.yield_per(batch_size):
+                yield result
+
+    def target_add_record(
+        self,
+        target_sqn: int,
+        begin_dt: datetime.datetime,
+        end_dt: datetime.datetime,
+        tag: str | Tag | BoundTag,
+        features: JsonType | None = None,
+        props: JsonType | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+    ) -> Chainable[Self, TagRecordTable]:
+        """
+        Add a tag record to the cache for the specified time range.
+
+        :param target_sqn: Sequence number of the tag record's target
+        :param begin_dt: Begin datetime of the tag record
+        :param end_dt: End datetime of the tag record
+        :param tag: Tag name or ``Tag``/``BoundTag`` instance to be added. If ``Tag``/``BoundTag`` instance is provided,
+                    its name will be used.
+        :param features: Additional tag features of the tag record in JSON format (optional), which can be used for
+                         storing preprocessed information of the tag record to facilitate querying and filtering.
+        :param props: Additional properties of the tag record in JSON format (optional)
+        :param tagset_namespace: Namespace of the tagset that the tag belongs to. If the ``tag`` parameter is a
+                                 ``BoundTag`` instance, this parameter will be ignored and the namespace from the
+                                 instance will be used.
+        :param tagset_version: Version of the tagset that the tag belongs to. If the ``tag`` parameter is a ``BoundTag``
+                               instance, this parameter will be ignored and the version from the instance will be used.
+        :return: Self instance for chaining along with the added ``TagRecordTable`` instance
+        """
+        with self.make_session() as session:
+            tag_record = TagRecord(
+                target_sqn=target_sqn,
+                begin_dt=begin_dt,
+                end_dt=end_dt,
+                tagset_namespace=tag.namespace if isinstance(tag, BoundTag) else tagset_namespace,
+                tagset_version=tag.version if isinstance(tag, BoundTag) else tagset_version,
+                tag=tag.name if isinstance(tag, Tag) else tag,
+                features=features,
+                props=props,
+            )
+            db_tag_record = clone_sequence_model_instance(TagRecordTable, tag_record)
+            session.add(db_tag_record)
+            session.commit()
+
+            return chainable(self, db_tag_record)
+
+    def target_update_record(
+        self,
+        target_sqn: int,
+        sqn: int,
+        *,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tag: str | Tag | BoundTag | None = None,
+        features: JsonType | None = None,
+        props: JsonType | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        flags: int | None = None,
+    ) -> Chainable[Self, TagRecordTable]:
+        """
+        Update a tag record in the cache by its sequence number.
+
+        :param target_sqn: Sequence number of the tag record's target
+        :param sqn: Sequence number of the tag record to be updated
+        :param begin_dt: New begin datetime of the tag record (optional)
+        :param end_dt: New end datetime of the tag record (optional)
+        :param tag: New tag name or ``Tag``/``BoundTag`` instance to be updated (optional). If ``Tag``/``BoundTag``
+                    instance is provided, its name will be used.
+        :param features: Additional tag features of the tag record in JSON format (optional), which can be used for
+                         storing preprocessed information of the tag record to facilitate querying and filtering.
+        :param props: New additional properties of the tag record in JSON format (optional)
+        :param tagset_namespace: New namespace of the tagset that the tag belongs to (optional). If the ``tag``
+                                 parameter is a ``BoundTag`` instance, this parameter will be ignored and the namespace
+                                 from the instance will be used.
+        :param tagset_version: New version of the tagset that the tag belongs to (optional). If the ``tag`` parameter
+                               is a ``BoundTag`` instance, this parameter will be ignored and the version from the
+                               instance will be used.
+        :param flags: New integer bitmask storing status or metadata flags for this tag record (optional)
+        :return: Self instance for chaining along with the updated ``TagRecordTable`` instance
+        """
+        with self.make_session() as session:
+            db_tag_record = (
+                session
+                .query(TagRecordTable)
+                .filter(TagRecordTable.target_sqn == target_sqn, TagRecordTable.sqn == sqn)
+                .one_or_none()
+            )
+            if not db_tag_record:
+                raise ValueError(f"tag record with sqn '{sqn}' not found in cache")
+
+            if begin_dt is not None:
+                db_tag_record.begin_dt = begin_dt
+            if end_dt is not None:
+                db_tag_record.end_dt = end_dt
+            if tagset_namespace is not None:
+                db_tag_record.tagset_namespace = tag.namespace if isinstance(tag, BoundTag) else tagset_namespace
+            if tagset_version is not None:
+                db_tag_record.tagset_version = tag.version if isinstance(tag, BoundTag) else tagset_version
+            if tag is not None:
+                db_tag_record.tag = tag.name if isinstance(tag, Tag) else tag
+            if features is not None:
+                db_tag_record.features = features
+            if props is not None:
+                db_tag_record.props = props
+            if flags is not None:
+                db_tag_record.flags = flags
+
+            session.commit()
+
+            return chainable(self, db_tag_record)
+
+    def target_remove_records(
+        self,
+        target_sqn: int,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
+        *,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+    ) -> Self:
+        """
+        Remove tag records from the cache that match the specified filters.
+
+        :param target_sqn: Filter by target sequence number (exact match)
+        :param begin_dt: Filter by begin time (inclusive)
+        :param end_dt: Filter by end time (inclusive)
+        :param tagset_namespace: Filter by tagset namespace (exact match)
+        :param tagset_version: Filter by tagset version (exact match)
+        :param tag_prefix: Filter by tag name prefix, e.g. "dummy_tag:" to match all tags starting with "dummy_tag:"
+        :param tagsets: Filter by tagsets (match tags that are in any of the specified tagsets)
+        :param tagset_inverted: Whether to invert the tagset filter (match tags that are NOT in any of the specified
+                                tagsets)
+        :return: Self instance for chaining
+        """
+        with self.make_session() as session:
+            query_stmt = session.query(TagRecordTable).filter(TagRecordTable.target_sqn == target_sqn)
+            if begin_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.end_dt >= begin_dt)
+            if end_dt:
+                query_stmt = query_stmt.filter(TagRecordTable.begin_dt <= end_dt)
+            if tagset_namespace:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_namespace == tagset_namespace)
+            if tagset_version:
+                query_stmt = query_stmt.filter(TagRecordTable.tagset_version == tagset_version)
+            if tag_prefix:
+                query_stmt = query_stmt.filter(TagRecordTable.tag.like(f"{escape_sql_like(tag_prefix)}%", escape="\\"))
+            if tagsets:
+                if tagset_inverted:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.notin_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+                else:
+                    query_stmt = query_stmt.filter(
+                        TagRecordTable.tag.in_([tag_name for tagset in tagsets for tag_name in tagset.tag_names]))
+
+            query_stmt.delete()
+            session.commit()
+
+        return self
+
+    def clear(self):
+        with self.make_session() as session:
+            session.execute(sa.delete(TagRecordTable))
+            session.execute(sa.delete(TagTargetTable))
+            session.commit()
+
+    def append_to(self, target_file_path: str, *, overwrite: bool = False):
+        target_tag_cache = TagCache(file_path=target_file_path)
+        if overwrite:
+            target_tag_cache.clear()
+        TagCache.copy_to(self, target_tag_cache)
+
+    def merge_from(self, source_file_path: str, *, overwrite: bool = False):
+        source_tag_cache = TagCache(file_path=source_file_path)
+        if overwrite:
+            self.clear()
+        TagCache.copy_to(source_tag_cache, self)
+
+    @staticmethod
+    def copy_to(src: "TagCache", dst: "TagCache"):
+        # If src and dst are the same instance or point to the same file path,
+        # do nothing to avoid accidentally clearing the cache
+        if src == dst or src.file_path == dst.file_path:
+            return
+
+        with src.make_session() as src_session, dst.make_session() as dst_session:
+            src_db_tag_targets = src_session.query(TagTargetTable).all()
+            dst_db_tag_targets = [
+                clone_sequence_model_instance(TagTargetTable, db_tag_target, clear_meta_fields=True)
+                for db_tag_target in src_db_tag_targets
+            ]
+            dst_session.add_all(dst_db_tag_targets)
+            dst_session.flush()  # ensure new sqn values are assigned
+
+            sqn_map = {src_db_tag_target.sqn: dst_db_tag_target.sqn
+                       for src_db_tag_target, dst_db_tag_target in zip(src_db_tag_targets, dst_db_tag_targets)}
+
+            for db_tag_records in batched(src_session.query(TagRecordTable).yield_per(1000), 1000):
+                cloned_db_tag_records = []
+                for db_tag_record in db_tag_records:
+                    cloned_db_tag_record = clone_sequence_model_instance(TagRecordTable,
+                                                                         db_tag_record,
+                                                                         clear_meta_fields=True)
+                    try:
+                        cloned_db_tag_record.target_sqn = sqn_map[db_tag_record.target_sqn]
+                    except KeyError as e:
+                        raise ValueError(f"no cloned tag target for target_sqn '{db_tag_record.target_sqn}'") from e
+                    cloned_db_tag_records.append(cloned_db_tag_record)
+                dst_session.add_all(cloned_db_tag_records)
+            dst_session.commit()
+
+
+class TargetedTagCache(object):
+    def __init__(self, cache: TagCache, tag_target: TagTargetTable):
+        self.cache = cache
+        self.tag_target = tag_target
+
+    def count_records(self) -> int:
+        return self.cache.target_count_records(self.tag_target.sqn)
+
+    def iter_records(
+        self,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
+        *,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+        skip: int | None = None,
+        limit: int | None = None,
+        batch_size: int = 1000,
+    ) -> Generator[TagRecordTable, None, None]:
+        return self.cache.target_iter_records(
+            target_sqn=self.tag_target.sqn,
+            begin_dt=begin_dt,
+            end_dt=end_dt,
+            tagset_namespace=tagset_namespace,
+            tagset_version=tagset_version,
+            tag_prefix=tag_prefix,
+            tagsets=tagsets,
+            tagset_inverted=tagset_inverted,
+            skip=skip,
+            limit=limit,
+            batch_size=batch_size,
+        )
+
+    def add_ranged_record(
+        self,
+        begin_dt: datetime.datetime | None,
+        end_dt: datetime.datetime | None,
+        tag: str | Tag | BoundTag,
+        features: JsonType | None = None,
+        props: JsonType | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+    ) -> Chainable[Self, TagRecordTable]:
+        result = self.cache.target_add_record(
+            target_sqn=self.tag_target.sqn,
+            begin_dt=begin_dt or self.tag_target.begin_dt,
+            end_dt=end_dt or self.tag_target.end_dt,
+            tag=tag,
+            features=features,
+            props=props,
+            tagset_namespace=tagset_namespace,
+            tagset_version=tagset_version,
+        )
+        return result.retarget(self)
+
+    def add_record(
+        self,
+        tag: str | Tag | BoundTag,
+        features: JsonType | None = None,
+        props: JsonType | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+    ) -> Chainable[Self, TagRecordTable]:
+        result = self.add_ranged_record(
+            begin_dt=self.tag_target.begin_dt,
+            end_dt=self.tag_target.end_dt,
+            tag=tag,
+            features=features,
+            tagset_namespace=tagset_namespace,
+            tagset_version=tagset_version,
+            props=props,
+        )
+        return result.retarget(self)
+
+    def update_record(
+        self,
+        sqn: int,
+        *,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tag: str | Tag | BoundTag | None = None,
+        features: JsonType | None = None,
+        props: JsonType | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        flags: int | None = None,
+    ) -> Chainable[Self, TagRecordTable]:
+        result = self.cache.target_update_record(
+            self.tag_target.sqn,
+            sqn,
+            begin_dt=begin_dt,
+            end_dt=end_dt,
+            tag=tag,
+            features=features,
+            props=props,
+            tagset_namespace=tagset_namespace,
+            tagset_version=tagset_version,
+            flags=flags,
+        )
+        return result.retarget(self)
+
+    def remove_records(
+        self,
+        begin_dt: datetime.datetime | None = None,
+        end_dt: datetime.datetime | None = None,
+        tagset_namespace: str | None = None,
+        tagset_version: str | None = None,
+        tag_prefix: str | None = None,
+        *,
+        tagsets: Sequence[Tagset] | None = None,
+        tagset_inverted: bool = False,
+    ) -> Self:
+        self.cache.target_remove_records(
+            self.tag_target.sqn,
+            begin_dt=begin_dt,
+            end_dt=end_dt,
+            tagset_namespace=tagset_namespace,
+            tagset_version=tagset_version,
+            tag_prefix=tag_prefix,
+            tagsets=tagsets,
+            tagset_inverted=tagset_inverted,
+        )
+        return self
+
+
+@memorized
+def tag_cache(*, identifier: str | None = None, file_path: str | os.PathLike[str] | None = None) -> TagCache:
+    """
+    Get a ``TagCache`` instance associated with the given identifier. If the identifier is ``None``, return a
+    ``TagCache`` instance associated with a default file path. Otherwise, validate the identifier as a snake case
+    string and return a ``TagCache`` instance associated with a file path derived from the identifier.
+
+    :param identifier: An optional string identifier for the tag cache. If provided, it must be in snake case format
+                       and will be used to derive the file path for the tag cache. If not provided, a default file path
+                       will be used.
+    :param file_path: An optional file path for the tag cache. If provided, it will be used directly. If not provided,
+                      the file path will be derived from the identifier if it is provided, or a default file path will
+                      be used if the identifier is not provided. Note that both ``identifier`` and ``file_path`` cannot
+                      be specified at the same time.
+    :return: A ``TagCache`` instance associated with the specified or default file path.
+    """
+    if identifier is not None and file_path is not None:
+        raise ValueError("cannot specify both 'identifier' and 'file_path'")
+    if identifier is not None:
+        validate_snake_case(identifier)
+        return TagCache(file_path=tag_cache_file_path().parent / f"{identifier}.db")
+    if file_path is not None:
+        return TagCache(file_path=file_path)
+    return TagCache(file_path=tag_cache_file_path())
+
+
+@singleton
+def standard_clip_duration_us() -> int:
+    """Duration of clips to split samples into, in microseconds, which is fixed to 20 seconds for now."""
+    return 20 * 1_000_000  # 20 seconds
+
+
+def populate_clip_ranges(
+    data_begin_dt: datetime.datetime,
+    data_end_dt: datetime.datetime,
+    *,
+    clip_duration_us: int = None
+) -> Generator[tuple[datetime.datetime, datetime.datetime, datetime.datetime, datetime.datetime]]:
+    """
+    Generate clip begin datetime, clip data begin datetime, and clip data end datetime for each clip slot that overlaps
+    with the given data begin and end datetimes.
+    The clip begin datetime is the beginning of the clip slot, the clip data begin datetime is the maximum of the clip
+    begin datetime and the data begin datetime, and the clip data end datetime is the minimum of the clip end datetime
+    and the data end datetime.
+
+    :param data_begin_dt: The beginning datetime of the data.
+    :param data_end_dt: The end datetime of the data.
+    :param clip_duration_us: The duration of each clip in microseconds. If not provided,
+                             the standard clip duration will be used.
+    :return: A generator of tuples containing the clip begin datetime, clip data begin datetime,
+             and clip data end datetime
+    """
+    clip_duration_us = clip_duration_us or standard_clip_duration_us()
+
+    if data_begin_dt == data_end_dt:
+        clip_slot = math.floor(dt_to_ts_us(data_begin_dt) / clip_duration_us)
+        clip_begin_dt = dt_from_ts_us(clip_slot * clip_duration_us)
+        clip_end_dt = dt_from_ts_us((clip_slot + 1) * clip_duration_us)
+        yield clip_begin_dt, clip_end_dt, data_begin_dt, data_end_dt
+        return
+
+    begin_clip_slot = math.floor(dt_to_ts_us(data_begin_dt) / clip_duration_us)
+    end_clip_slot = math.ceil(dt_to_ts_us(data_end_dt) / clip_duration_us)
+
+    for clip_slot in range(begin_clip_slot, end_clip_slot):
+        clip_begin_dt = dt_from_ts_us(clip_slot * clip_duration_us)
+        clip_end_dt = dt_from_ts_us((clip_slot + 1) * clip_duration_us)
+        clip_data_begin_dt = max(clip_begin_dt, data_begin_dt)
+        clip_data_end_dt = min(clip_end_dt, data_end_dt)
+
+        yield clip_begin_dt, clip_end_dt, clip_data_begin_dt, clip_data_end_dt