feat(media): add filename and readiness filters to shared listing (#126)

* Added Search filters,Added file names,Implemented CLI,MCP and HTTP projections

* Fixed the issue of import in the file named mcp.py

* Fixed the same import issue in the file named ports.py

* Fixes of media_service.py and test_frontend.py as proposed by the Reviewer

* Missed the service variable that was defined at the top of the function

* align workspace actions, cursor scope, and ready-only frontend listing

* Minor changes

* fix(media): preserve filtered pagination and matching

---------

Co-authored-by: Talha <tamjad91@gmail.com>

Author: FaiziNerd

src/vidxp/api_routes/media.py

@@ -26,6 +26,7 @@
 from vidxp.api_models import UploadIntentResponse
 from vidxp.composition import HttpApplicationContext
 from vidxp.core.identifiers import MediaId
+from vidxp.core.media import MediaState
 
 
 router = APIRouter(prefix="/media", tags=["media"])
@@ -176,9 +177,22 @@ def list_media(
         str | None,
         Query(min_length=1, max_length=512),
     ] = None,
+    filename: Annotated[
+        str | None,
+        Query(min_length=1),
+    ] = None,
+    state: Annotated[
+        MediaState | None,
+        Query(),
+    ] = None,
 ) -> MediaPage:
     return service.application.list_media(
-        ListMediaCommand(page_size=page_size, cursor=cursor)
+        ListMediaCommand(
+            page_size=page_size,
+            cursor=cursor,
+            filename=filename,
+            state=state,
+        )
     )
 
 

src/vidxp/api_routes/platform.py

@@ -11,6 +11,7 @@
     WorkspaceOverview,
 )
 from vidxp.composition import HttpApplicationContext
+from vidxp.core.media import MediaState
 
 
 router = APIRouter(
@@ -32,9 +33,22 @@ def workspace(
         str | None,
         Query(min_length=1, max_length=512),
     ] = None,
+    filename: Annotated[
+        str | None,
+        Query(min_length=1),
+    ] = None,
+    state: Annotated[
+        MediaState | None,
+        Query(),
+    ] = None,
 ) -> WorkspaceOverview:
     return service.application.workspace(
-        ListMediaCommand(page_size=page_size, cursor=cursor)
+        ListMediaCommand(
+            page_size=page_size,
+            cursor=cursor,
+            filename=filename,
+            state=state,
+        )
     )
 
 

src/vidxp/application_models.py

@@ -398,6 +398,15 @@ class ListMediaCommand(ApplicationModel):
         max_length=512,
         description="Opaque next_cursor from the previous list_media page.",
     )
+    filename: str | None = Field(
+        default=None,
+        min_length=1,
+        description="Filter media records by filename.",
+    )
+    state: MediaState | None = Field(
+        default=None,
+        description="Filter media records by readiness/state.",
+    )
 
 
 class MediaPage(Page[MediaAsset]):

src/vidxp/cli_commands/media.py

@@ -16,6 +16,7 @@
     require_media_runtime,
     state_from_context,
 )
+from vidxp.core.media import MediaState
 
 
 app = typer.Typer(no_args_is_help=True, help="Import and inspect local media.")
@@ -68,6 +69,14 @@ def list_media(
         str | None,
         typer.Option("--cursor", help="Cursor returned by the previous page."),
     ] = None,
+    filename: Annotated[
+        str | None,
+        typer.Option("--filename", help="Filter media by filename."),
+    ] = None,
+    media_state: Annotated[
+        MediaState | None,
+        typer.Option("--state", help="Filter media by readiness/state."),
+    ] = None,
     json_output: Annotated[
         bool,
         typer.Option("--json", help="Emit machine-readable JSON."),
@@ -77,7 +86,12 @@ def list_media(
 
     state = state_from_context(ctx)
     page = state.service.list_media(
-        ListMediaCommand(page_size=limit, cursor=cursor)
+        ListMediaCommand(
+            page_size=limit,
+            cursor=cursor,
+            filename=filename,
+            state=media_state,
+        )
     )
     assets = page.items
     payload = page.model_dump(mode="json")

src/vidxp/control_plane.py

@@ -117,6 +117,9 @@ def list_media(self, command: ListMediaCommand) -> MediaPage:
     @application_boundary
     def workspace(self, command: ListMediaCommand) -> WorkspaceOverview:
         page = self.list_media(command)
+        # Workspace actions are repository-level guidance, so compare against
+        # repository-wide totals rather than a potentially filtered page total.
+        repository_media_total = self.list_media(ListMediaCommand(page_size=1)).total
         index = self.index_status()
         snapshot = self._read_active_snapshot()
         capabilities = self.list_capabilities()
@@ -166,7 +169,7 @@ def workspace(self, command: ListMediaCommand) -> WorkspaceOverview:
         next_actions = []
         if page.total == 0:
             next_actions.append("register_media")
-        if page.total > len(indexed_media) or any(
+        if repository_media_total > len(indexed_media) or any(
             item.media_id not in indexed_media for item in page.items
         ):
             next_actions.append("index_media")

src/vidxp/frontend.py

@@ -754,7 +754,7 @@ def _select_video(busy, media_id, media_page):
     assets = tuple(
         asset
         for asset in (media_page.items if media_page is not None else ())
-        if asset.state == MediaState.ready
+        if getattr(asset, "state", None) == MediaState.ready
     )
     media_id = _default_media_id(media_id, assets)
     if media_id is not None:
@@ -998,7 +998,9 @@ def run():
             media_id = indexed_media[0]
             st.session_state[MEDIA_ID_KEY] = media_id
     try:
-        media_page = service.list_media(ListMediaCommand(page_size=100))
+        media_page = service.list_media(
+            ListMediaCommand(page_size=100, state=MediaState.ready)
+        )
     except ApplicationError:
         media_page = None
         st.warning(

src/vidxp/infrastructure/sql_catalog.py

@@ -68,6 +68,41 @@ def _record(model: Any, value: Any) -> Any:
     return model.model_validate(_payload(value), strict=False)
 
 
+def _escape_like_pattern(value: str) -> str:
+    escaped = (
+        value.replace("\\", "\\\\")
+        .replace("%", "\\%")
+        .replace("_", "\\_")
+    )
+    return f"%{escaped}%"
+
+
+def _media_payload_text(key: str):
+    return media.c.payload[key].as_string()
+
+
+def _media_list_conditions(
+    *,
+    dialect_name: str,
+    filename: str | None,
+    state: MediaState | None,
+) -> tuple[Any, ...]:
+    conditions: list[Any] = []
+    if state is not None:
+        conditions.append(_media_payload_text("state") == state.value)
+    if filename is not None:
+        filename_text = _media_payload_text("original_filename")
+        if dialect_name == "postgresql":
+            filename_text = filename_text.collate("pg_unicode_fast")
+        conditions.append(
+            func.casefold(filename_text).like(
+                _escape_like_pattern(filename.casefold()),
+                escape="\\",
+            )
+        )
+    return tuple(conditions)
+
+
 def _upload_record(row: Any) -> UploadIntentRecord:
     return UploadIntentRecord(
         intent_id=row.intent_id,
@@ -180,6 +215,12 @@ def transaction(self) -> Iterator[Connection]:
 
     @staticmethod
     def _configure_sqlite(dbapi_connection: Any, _record: Any) -> None:
+        dbapi_connection.create_function(
+            "casefold",
+            1,
+            str.casefold,
+            deterministic=True,
+        )
         cursor = dbapi_connection.cursor()
         try:
             cursor.execute("PRAGMA foreign_keys = ON")
@@ -316,28 +357,44 @@ def list_media(
         *,
         limit: int,
         offset: int = 0,
+        filename: str | None = None,
+        state: MediaState | None = None,
     ) -> tuple[MediaRecord, ...]:
         if limit <= 0 or offset < 0:
             raise ValueError("limit must be positive and offset nonnegative")
+        conditions = _media_list_conditions(
+            dialect_name=self.engine.dialect.name,
+            filename=filename,
+            state=state,
+        )
+        query = select(media.c.payload).order_by(media.c.created_at, media.c.media_id)
+        if conditions:
+            query = query.where(and_(*conditions))
         with self.engine.connect() as connection:
             payloads = connection.execute(
-                select(media.c.payload)
-                .order_by(media.c.created_at, media.c.media_id)
-                .limit(limit)
-                .offset(offset)
+                query.limit(limit).offset(offset)
             ).scalars()
             return tuple(
                 _record(MediaRecord, payload)
                 for payload in payloads
             )
 
-    def count_media(self) -> int:
+    def count_media(
+        self,
+        *,
+        filename: str | None = None,
+        state: MediaState | None = None,
+    ) -> int:
+        conditions = _media_list_conditions(
+            dialect_name=self.engine.dialect.name,
+            filename=filename,
+            state=state,
+        )
+        query = select(func.count()).select_from(media)
+        if conditions:
+            query = query.where(and_(*conditions))
         with self.engine.connect() as connection:
-            return int(
-                connection.execute(
-                    select(func.count()).select_from(media)
-                ).scalar_one()
-            )
+            return int(connection.execute(query).scalar_one())
 
     def reserve_media_import(
         self,

src/vidxp/mcp.py

@@ -109,6 +109,7 @@
     load_mcp_app_html,
 )
 from vidxp.core.identifiers import ArtifactId
+from vidxp.core.media import MediaState
 from vidxp.evidence_delivery import (
     EvidenceDeliveryService,
     require_completed_evidence_result,
@@ -1277,13 +1278,23 @@ async def get_workspace(
             str | None,
             Field(min_length=1, max_length=512),
         ] = None,
+        filename: Annotated[
+            str | None,
+            Field(min_length=1),
+        ] = None,
+        state: MediaState | None = None,
     ) -> WorkspaceOverview:
         return await _invoke_async(
             context,
             default_principal=default_principal,
             permission=RepositoryPermission.read,
             operation=lambda _actor: context.application.workspace(
-                ListMediaCommand(page_size=page_size, cursor=cursor)
+                ListMediaCommand(
+                    page_size=page_size,
+                    cursor=cursor,
+                    filename=filename,
+                    state=state,
+                )
             ),
         )
 
@@ -1349,13 +1360,23 @@ async def list_media(
             str | None,
             Field(min_length=1, max_length=512),
         ] = None,
+        filename: Annotated[
+            str | None,
+            Field(min_length=1),
+        ] = None,
+        state: MediaState | None = None,
     ) -> MediaPage:
         return await _invoke_async(
             context,
             default_principal=default_principal,
             permission=RepositoryPermission.read,
             operation=lambda _actor: context.application.list_media(
-                ListMediaCommand(page_size=page_size, cursor=cursor)
+                ListMediaCommand(
+                    page_size=page_size,
+                    cursor=cursor,
+                    filename=filename,
+                    state=state,
+                )
             ),
         )
 

src/vidxp/media_service.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
+import hashlib
 import json
 from pathlib import Path
-import hashlib
 from uuid import uuid4
 
 from vidxp.application_models import (
@@ -274,21 +274,38 @@ def get(self, media_id: str) -> MediaAsset:
         return media_asset(record)
 
     def list(self, command: ListMediaCommand) -> MediaPage:
-        scope = hashlib.sha256(
+        repository_scope = hashlib.sha256(
             str(self.settings.repository_root.resolve()).encode()
         ).hexdigest()
+        scope = repository_scope
+        if command.filename is not None or command.state is not None:
+            scope = hashlib.sha256(
+                json.dumps(
+                    [
+                        repository_scope,
+                        command.filename,
+                        command.state.value if command.state is not None else None,
+                    ],
+                    separators=(",", ":"),
+                ).encode()
+            ).hexdigest()
         try:
             offset = decode_offset_cursor(command.cursor, scope=scope)
         except CursorError as exc:
             raise ValueError("The media cursor is invalid.") from exc
-        total = self.catalog.count_media()
+        total = self.catalog.count_media(
+            filename=command.filename,
+            state=command.state,
+        )
         if offset > total:
             raise ValueError("The media cursor is outside the result set.")
         items = tuple(
             media_asset(record)
             for record in self.catalog.list_media(
                 limit=command.page_size,
                 offset=offset,
+                filename=command.filename,
+                state=command.state,
             )
         )
         next_offset = offset + len(items)