nv-ingest 2025.5.21.dev20250521__py3-none-any.whl

nv_ingest/framework/util/flow_control/filter_by_task.py

@@ -0,0 +1,227 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+import functools
+import logging
+import re
+from typing import Dict, List, Any, Union, Tuple, Optional, Callable
+
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+
+def filter_by_task(
+    required_tasks: List[Union[str, Tuple[Any, ...]]],
+    forward_func: Optional[Callable[[Any], Any]] = None,
+) -> Callable:
+    """
+    Decorator that checks whether an IngestControlMessage contains any of the required tasks.
+    Supports both synchronous and asynchronous functions as well as class methods (with 'self').
+    If no required task is found, the original message is returned (or forward_func is called if provided).
+
+    Parameters
+    ----------
+    required_tasks : list[Union[str, Tuple[Any, ...]]]
+        A list of required tasks. Each element is either a string representing a task name
+        or a tuple/list where the first element is the task name and the remaining elements
+        specify required task properties.
+    forward_func : Optional[Callable[[Any], Any]]
+        A function to be called with the IngestControlMessage if no required task is found.
+
+    Returns
+    -------
+    Callable
+        A decorator wrapping a function that expects an IngestControlMessage as one of its first arguments.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        # Helper to extract the IngestControlMessage from the arguments.
+        def extract_message(args: Tuple) -> Any:
+            if args and hasattr(args[0], "get_tasks"):
+                return args[0]
+            elif len(args) > 1 and hasattr(args[1], "get_tasks"):
+                return args[1]
+            else:
+                raise ValueError(
+                    "The first or second argument must be an IngestControlMessage with task handling capabilities."
+                )
+
+        if asyncio.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                message = extract_message(args)
+                tasks: Dict[str, List[Any]] = {}
+                for task in message.get_tasks():
+                    tasks.setdefault(task.type, []).append(task.properties)
+                for required_task in required_tasks:
+                    # Case 1: required task is a simple string.
+                    if isinstance(required_task, str):
+                        if required_task in tasks:
+                            logger.debug(
+                                "Task '%s' found. Proceeding with async function '%s'.",
+                                required_task,
+                                func.__name__,
+                            )
+                            return await func(*args, **kwargs)
+                        else:
+                            logger.debug("Required task '%s' not found.", required_task)
+                    # Case 2: required task is a tuple/list with properties.
+                    elif isinstance(required_task, (tuple, list)):
+                        required_task_name, *required_task_props_list = required_task
+                        if required_task_name not in tasks:
+                            continue
+                        for task_props in tasks.get(required_task_name, []):
+                            orig_task_props = task_props
+                            if isinstance(task_props, BaseModel):
+                                task_props = task_props.model_dump()
+                            all_match = True
+                            for required_props in required_task_props_list:
+                                if not _is_subset(task_props, required_props):
+                                    logger.debug(
+                                        "For task '%s', task properties %s do not match required subset %s.",
+                                        required_task_name,
+                                        orig_task_props,
+                                        required_props,
+                                    )
+                                    all_match = False
+                                    break
+                            if all_match:
+                                logger.debug(
+                                    "Task '%s' with properties %s matched for function '%s'.",
+                                    required_task_name,
+                                    orig_task_props,
+                                    func.__name__,
+                                )
+                                return await func(*args, **kwargs)
+                    else:
+                        logger.debug("Invalid required task type: %s", type(required_task))
+                logger.debug("No required task matched for function '%s'.", func.__name__)
+                if forward_func:
+                    logger.debug("Calling forward function for IngestControlMessage.")
+                    return await forward_func(message)
+                else:
+                    logger.debug("Returning original IngestControlMessage without processing.")
+                    return message
+
+            return async_wrapper
+        else:
+
+            @functools.wraps(func)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                message = extract_message(args)
+                tasks: Dict[str, List[Any]] = {}
+                for task in message.get_tasks():
+                    tasks.setdefault(task.type, []).append(task.properties)
+                for required_task in required_tasks:
+                    if isinstance(required_task, str):
+                        if required_task in tasks:
+                            logger.debug(
+                                "Task '%s' found. Proceeding with function '%s'.", required_task, func.__name__
+                            )
+                            return func(*args, **kwargs)
+                        else:
+                            logger.debug("Required task '%s' not found.", required_task)
+                    elif isinstance(required_task, (tuple, list)):
+                        required_task_name, *required_task_props_list = required_task
+                        if required_task_name not in tasks:
+                            continue
+                        for task_props in tasks.get(required_task_name, []):
+                            orig_task_props = task_props
+                            if isinstance(task_props, BaseModel):
+                                task_props = task_props.model_dump()
+                            all_match = True
+                            for required_props in required_task_props_list:
+                                if not _is_subset(task_props, required_props):
+                                    logger.debug(
+                                        "For task '%s', task properties %s do not match required subset %s.",
+                                        required_task_name,
+                                        orig_task_props,
+                                        required_props,
+                                    )
+                                    all_match = False
+                                    break
+                            if all_match:
+                                logger.debug(
+                                    "Task '%s' with properties %s matched for function '%s'.",
+                                    required_task_name,
+                                    orig_task_props,
+                                    func.__name__,
+                                )
+                                return func(*args, **kwargs)
+                    else:
+                        logger.debug("Invalid required task type: %s", type(required_task))
+                logger.debug("No required task matched for function '%s'.", func.__name__)
+                if forward_func:
+                    logger.debug("Calling forward function for IngestControlMessage.")
+                    return forward_func(message)
+                else:
+                    logger.debug("Returning original IngestControlMessage without processing.")
+                    return message
+
+            return sync_wrapper
+
+    return decorator
+
+
+def _is_subset(superset: Any, subset: Any) -> bool:
+    """
+    Recursively checks whether 'subset' is contained within 'superset'. Supports dictionaries,
+    lists, strings (including regex patterns), and basic types.
+
+    Parameters
+    ----------
+    superset : Any
+        The data structure (or value) that is expected to contain the subset.
+    subset : Any
+        The data structure (or value) to be checked for being a subset of 'superset'. A special
+        value "*" matches any value, and strings prefixed with "regex:" are treated as regular
+        expression patterns.
+
+    Returns
+    -------
+    bool
+        True if 'subset' is contained within 'superset', False otherwise.
+    """
+    if subset == "*":
+        return True
+    if isinstance(superset, dict) and isinstance(subset, dict):
+        for key, val in subset.items():
+            if key not in superset:
+                logger.debug("Key '%s' not found in superset dictionary: %s", key, superset)
+                return False
+            if not _is_subset(superset[key], val):
+                logger.debug("Value for key '%s' (%s) does not match expected subset (%s).", key, superset[key], val)
+                return False
+        return True
+    if isinstance(subset, str) and subset.startswith("regex:"):
+        pattern = subset[len("regex:") :]
+        if isinstance(superset, list):
+            for sup_item in superset:
+                if re.match(pattern, sup_item):
+                    return True
+            logger.debug("No items in list %s match regex pattern '%s'.", superset, pattern)
+            return False
+        else:
+            if re.match(pattern, superset) is None:
+                logger.debug("Value '%s' does not match regex pattern '%s'.", superset, pattern)
+                return False
+            return True
+    if isinstance(superset, list) and not isinstance(subset, list):
+        for sup_item in superset:
+            if _is_subset(sup_item, subset):
+                return True
+        logger.debug("None of the items in list %s match the value '%s'.", superset, subset)
+        return False
+    if isinstance(superset, (list, set)) and isinstance(subset, list):
+        for sub_item in subset:
+            if not any(_is_subset(sup_item, sub_item) for sup_item in superset):
+                logger.debug("No element in %s matches subset element '%s'.", superset, sub_item)
+                return False
+        return True
+    if superset != subset:
+        logger.debug("Direct comparison failed: %s != %s", superset, subset)
+    return superset == subset

nv_ingest/framework/util/service/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0

nv_ingest/framework/util/service/impl/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0

nv_ingest/framework/util/service/impl/ingest/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0

nv_ingest/framework/util/service/impl/ingest/redis_ingest_service.py

@@ -0,0 +1,395 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+import json
+import logging
+import os
+from json import JSONDecodeError
+from typing import Optional, Dict, Any
+
+from typing import List
+
+import redis
+
+from nv_ingest.framework.schemas.framework_message_wrapper_schema import MessageWrapper
+from nv_ingest.framework.schemas.framework_processing_job_schema import ProcessingJob
+from nv_ingest.framework.util.service.meta.ingest.ingest_service_meta import IngestServiceMeta
+from nv_ingest_api.internal.schemas.meta.ingest_job_schema import validate_ingest_job
+from nv_ingest_api.util.service_clients.client_base import FetchMode
+from nv_ingest_api.util.service_clients.redis.redis_client import RedisClient
+
+logger = logging.getLogger("uvicorn")
+
+
+def get_fetch_mode_from_env() -> "FetchMode":
+    """
+    Retrieves the fetch mode from the environment variable FETCH_MODE.
+
+    Returns
+    -------
+    FetchMode
+        The fetch mode as specified by the environment variable, or NON_DESTRUCTIVE by default.
+    """
+    mode_str: str = os.getenv("FETCH_MODE", "NON_DESTRUCTIVE").upper()
+    try:
+        return FetchMode[mode_str]
+    except KeyError:
+        logger.warning(f"Invalid FETCH_MODE '{mode_str}' in environment. Defaulting to DESTRUCTIVE.")
+        return FetchMode.DESTRUCTIVE
+
+
+class RedisIngestService(IngestServiceMeta):
+    """
+    Submits jobs and fetches results via Redis, supporting multiple fetch modes
+    and state management with TTLs. Operates asynchronously using asyncio.to_thread
+    for synchronous Redis client operations.
+    """
+
+    _concurrency_level: int = int(os.getenv("CONCURRENCY_LEVEL", "10"))
+    __shared_instance: Optional["RedisIngestService"] = None
+
+    @staticmethod
+    def get_instance() -> "RedisIngestService":
+        """
+        Static access method implementing the Singleton pattern.
+
+        Returns
+        -------
+        RedisIngestService
+            The singleton instance of the RedisIngestService.
+        """
+        if RedisIngestService.__shared_instance is None:
+            redis_host: str = os.getenv("MESSAGE_CLIENT_HOST", "localhost")
+            redis_port: int = int(os.getenv("MESSAGE_CLIENT_PORT", "6379"))
+            redis_task_queue: str = os.getenv("REDIS_INGEST_TASK_QUEUE", "ingest_task_queue")
+
+            fetch_mode: "FetchMode" = get_fetch_mode_from_env()
+            result_data_ttl: int = int(os.getenv("RESULT_DATA_TTL_SECONDS", "3600"))
+            state_ttl: int = int(os.getenv("STATE_TTL_SECONDS", "7200"))
+
+            cache_config: Dict[str, Any] = {
+                "directory": os.getenv("FETCH_CACHE_DIR", "./.fetch_cache"),
+                "ttl": int(os.getenv("FETCH_CACHE_TTL_SECONDS", "3600")),
+            }
+            use_ssl: bool = os.getenv("REDIS_USE_SSL", "false").lower() == "true"
+
+            RedisIngestService.__shared_instance = RedisIngestService(
+                redis_hostname=redis_host,
+                redis_port=redis_port,
+                redis_task_queue=redis_task_queue,
+                fetch_mode=fetch_mode,
+                result_data_ttl_seconds=result_data_ttl if result_data_ttl > 0 else None,
+                state_ttl_seconds=state_ttl if state_ttl > 0 else None,
+                cache_config=cache_config,
+                use_ssl=use_ssl,
+            )
+            logger.debug(f"RedisIngestService configured with FetchMode: {fetch_mode.name}")
+        else:
+            logger.debug("Returning existing RedisIngestService Singleton instance.")
+        return RedisIngestService.__shared_instance
+
+    def __init__(
+        self,
+        redis_hostname: str,
+        redis_port: int,
+        redis_task_queue: str,
+        fetch_mode: "FetchMode",
+        result_data_ttl_seconds: Optional[int],
+        state_ttl_seconds: Optional[int],
+        cache_config: Optional[Dict[str, Any]],
+        use_ssl: bool,
+    ) -> None:
+        """
+        Initializes the service and the underlying RedisClient.
+
+        Parameters
+        ----------
+        redis_hostname : str
+            Redis server hostname.
+        redis_port : int
+            Redis server port.
+        redis_task_queue : str
+            The Redis queue name for tasks.
+        fetch_mode : FetchMode
+            The fetch mode configuration.
+        result_data_ttl_seconds : int or None
+            TTL for result data in seconds, or None to disable.
+        state_ttl_seconds : int or None
+            TTL for the job state record, or None to disable.
+        cache_config : dict or None
+            Configuration for caching.
+        use_ssl : bool
+            Whether to use SSL for the Redis connection.
+        """
+        self._redis_hostname: str = redis_hostname
+        self._redis_port: int = redis_port
+        self._redis_task_queue: str = redis_task_queue
+        self._fetch_mode: "FetchMode" = fetch_mode
+        self._result_data_ttl_seconds: Optional[int] = result_data_ttl_seconds
+        self._state_ttl_seconds: Optional[int] = state_ttl_seconds
+
+        self._bulk_vdb_cache_prefix: str = "vdb_bulk_upload_cache:"
+        self._cache_prefix: str = "processing_cache:"
+        self._state_prefix: str = "job_state:"
+
+        self._ingest_client = RedisClient(
+            host=self._redis_hostname,
+            port=self._redis_port,
+            max_pool_size=self._concurrency_level,
+            fetch_mode=self._fetch_mode,
+            cache_config=cache_config,
+            message_ttl_seconds=self._result_data_ttl_seconds,
+            use_ssl=use_ssl,
+            max_retries=int(os.getenv("REDIS_MAX_RETRIES", "3")),
+            max_backoff=int(os.getenv("REDIS_MAX_BACKOFF", "32")),
+            connection_timeout=int(os.getenv("REDIS_CONNECTION_TIMEOUT", "300")),
+        )
+        logger.debug(
+            f"RedisClient initialized for service. Host: {redis_hostname}:{redis_port}, "
+            f"FetchMode: {fetch_mode.name}, ResultTTL: {result_data_ttl_seconds}, StateTTL: {state_ttl_seconds}"
+        )
+
+    async def submit_job(self, job_spec_wrapper: "MessageWrapper", trace_id: str) -> str:
+        """
+        Validates, prepares, and submits a job specification to the Redis task queue.
+        Sets result data TTL if configured for NON_DESTRUCTIVE mode.
+
+        Parameters
+        ----------
+        job_spec_wrapper : MessageWrapper
+            A wrapper containing the job specification payload.
+        trace_id : str
+            A unique identifier for the job.
+
+        Returns
+        -------
+        str
+            The job trace_id.
+
+        Raises
+        ------
+        ValueError
+            If the payload is missing or invalid.
+        JSONDecodeError, TypeError
+            For payload parsing errors.
+        RedisError, ConnectionError
+            For Redis-related errors.
+        """
+        try:
+            json_data = job_spec_wrapper.model_dump(mode="json").get("payload")
+            if not json_data:
+                raise ValueError("MessageWrapper payload is missing or empty.")
+            if isinstance(json_data, str):
+                job_spec = json.loads(json_data)
+            elif isinstance(json_data, dict):
+                job_spec = json_data
+            else:
+                raise TypeError(f"Unexpected payload type: {type(json_data)}")
+
+            validate_ingest_job(job_spec)
+            job_spec["job_id"] = trace_id
+            tasks = job_spec.get("tasks", [])
+            updated_tasks = []
+            for task in tasks:
+                task_prop = task.get("task_properties", {})
+                if hasattr(task_prop, "model_dump") and callable(task_prop.model_dump):
+                    task["task_properties"] = task_prop.model_dump(mode="json")
+                elif not isinstance(task_prop, dict):
+                    try:
+                        task["task_properties"] = dict(task_prop)
+                    except (TypeError, ValueError):
+                        logger.error(f"Cannot convert task_properties to dict: {task_prop}. Skipping properties.")
+                        task["task_properties"] = {}
+                updated_tasks.append(task)
+            job_spec["tasks"] = updated_tasks
+            job_spec_json = json.dumps(job_spec)
+            ttl_for_result: Optional[int] = (
+                self._result_data_ttl_seconds if self._fetch_mode == FetchMode.NON_DESTRUCTIVE else None
+            )
+            logger.debug(
+                f"Submitting job {trace_id} to queue '{self._redis_task_queue}' with result TTL: {ttl_for_result}"
+            )
+            await asyncio.to_thread(
+                self._ingest_client.submit_message,
+                channel_name=self._redis_task_queue,
+                message=job_spec_json,
+                ttl_seconds=ttl_for_result,
+            )
+            logger.debug(f"Successfully submitted job {trace_id}")
+            return trace_id
+        except (JSONDecodeError, TypeError, ValueError) as err:
+            logger.exception(f"Data validation or parsing error for job {trace_id}: {err}")
+            raise ValueError(f"Invalid job specification: {err}") from err
+        except (redis.RedisError, ConnectionError) as err:
+            logger.exception(f"Redis error submitting job {trace_id}: {err}")
+            raise err
+        except Exception as err:
+            logger.exception(f"Unexpected error submitting job {trace_id}: {err}")
+            raise
+
+    async def fetch_job(self, job_id: str) -> Optional[Dict]:
+        """
+        Fetches the job result using the configured RedisClient fetch mode and timeout.
+        Executes the synchronous client call asynchronously.
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job.
+
+        Returns
+        -------
+        dict or None
+            The job result message.
+
+        Raises
+        ------
+        TimeoutError, RedisError, ConnectionError, ValueError, RuntimeError
+            If the fetch operation fails.
+        """
+        try:
+            result_channel: str = f"{job_id}"
+            logger.debug(f"Attempting to fetch job result for {job_id} using mode {self._fetch_mode.name}")
+            message = await asyncio.to_thread(
+                self._ingest_client.fetch_message,
+                channel_name=result_channel,
+                timeout=10,
+            )
+            if message is not None:
+                logger.debug(f"Successfully fetched result for job {job_id}.")
+                return message
+            else:
+                logger.warning(f"fetch_message for {job_id} returned None unexpectedly.")
+                raise TimeoutError("No data found (unexpected None response).")
+        except (TimeoutError, redis.RedisError, ConnectionError, ValueError, RuntimeError) as e:
+            logger.info(f"Fetch operation for job {job_id} did not complete: ({type(e).__name__}) {e}")
+            raise e
+        except Exception as e:
+            logger.exception(f"Unexpected error during async fetch_job for {job_id}: {e}")
+            raise RuntimeError(f"Unexpected error fetching job {job_id}") from e
+
+    async def set_job_state(self, job_id: str, state: str) -> None:
+        """
+        Sets the explicit state of a job and refreshes its TTL.
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job.
+        state : str
+            The state to be assigned to the job.
+
+        Returns
+        -------
+        None
+        """
+        state_key: str = f"{self._state_prefix}{job_id}"
+        ttl_to_set: Optional[int] = self._state_ttl_seconds
+        try:
+            logger.debug(f"Setting state for {job_id} to {state} with TTL {ttl_to_set}")
+            await asyncio.to_thread(
+                self._ingest_client.get_client().set,
+                state_key,
+                state,
+                ex=ttl_to_set,
+            )
+            logger.debug(f"Successfully set state for {job_id}.")
+        except (redis.RedisError, ConnectionError) as err:
+            logger.error(f"Failed to set state for {state_key}: {err}")
+        except Exception as err:
+            logger.exception(f"Unexpected error setting state for {state_key}: {err}")
+
+    async def get_job_state(self, job_id: str) -> Optional[str]:
+        """
+        Retrieves the explicit state of a job.
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job.
+
+        Returns
+        -------
+        str or None
+            The state of the job, or None if not found or upon error.
+        """
+        state_key: str = f"{self._state_prefix}{job_id}"
+        try:
+            data_bytes: Optional[bytes] = await asyncio.to_thread(self._ingest_client.get_client().get, state_key)
+            if data_bytes:
+                state: str = data_bytes.decode("utf-8")
+                logger.debug(f"Retrieved state for {job_id}: {state}")
+                return state
+            else:
+                logger.debug(f"No state found for {job_id} (key: {state_key})")
+                return None
+        except (redis.RedisError, ConnectionError) as err:
+            logger.error(f"Redis error getting state for {state_key}: {err}")
+            return None
+        except Exception as err:
+            logger.exception(f"Unexpected error getting state for {state_key}: {err}")
+            return None
+
+    async def set_processing_cache(self, job_id: str, jobs_data: List["ProcessingJob"]) -> None:
+        """
+        Stores processing jobs data in a simple key-value cache.
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job.
+        jobs_data : list of ProcessingJob
+            The processing job data to be cached.
+
+        Returns
+        -------
+        None
+        """
+        cache_key: str = f"{self._cache_prefix}{job_id}"
+        try:
+            data_to_store: str = json.dumps([job.model_dump(mode="json") for job in jobs_data])
+            await asyncio.to_thread(
+                self._ingest_client.get_client().set,
+                cache_key,
+                data_to_store,
+                ex=3600,
+            )
+        except Exception as err:
+            logger.exception(f"Error setting cache for {cache_key}: {err}")
+
+    async def get_processing_cache(self, job_id: str) -> List["ProcessingJob"]:
+        """
+        Retrieves processing jobs data from the simple key-value cache.
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job.
+
+        Returns
+        -------
+        list of ProcessingJob
+            A list of processing jobs, or an empty list if not found or upon error.
+        """
+        cache_key: str = f"{self._cache_prefix}{job_id}"
+        try:
+            data_bytes: Optional[bytes] = await asyncio.to_thread(self._ingest_client.get_client().get, cache_key)
+            if data_bytes is None:
+                return []
+            return [ProcessingJob(**job) for job in json.loads(data_bytes)]
+        except Exception as err:
+            logger.exception(f"Error getting cache for {cache_key}: {err}")
+            return []
+
+    async def get_fetch_mode(self) -> "FetchMode":
+        """
+        Returns the configured fetch mode for the service.
+
+        Returns
+        -------
+        FetchMode
+            The current fetch mode.
+        """
+        return self._fetch_mode

nv_ingest/framework/util/service/meta/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0

nv_ingest/framework/util/service/meta/ingest/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0

nv_ingest/framework/util/service/meta/ingest/ingest_service_meta.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from abc import ABC
+from abc import abstractmethod
+from typing import List, Optional
+
+from nv_ingest.framework.schemas.framework_message_wrapper_schema import MessageWrapper
+from nv_ingest.framework.schemas.framework_processing_job_schema import ProcessingJob
+from nv_ingest_api.util.service_clients.client_base import FetchMode
+
+
+class IngestServiceMeta(ABC):
+    @abstractmethod
+    async def submit_job(self, job_spec: MessageWrapper, trace_id: str) -> str:
+        """Abstract method for submitting one or more jobs to the ingestion pipeline"""
+
+    @abstractmethod
+    async def fetch_job(self, job_id: str):
+        """Abstract method for fetching job from ingestion service based on job_id"""
+
+    @abstractmethod
+    async def set_processing_cache(self, job_id: str, jobs_data: List[ProcessingJob]) -> None:
+        """Abstract method for setting processing cache"""
+
+    @abstractmethod
+    async def get_processing_cache(self, job_id: str) -> List[ProcessingJob]:
+        """Abstract method for getting processing cache"""
+
+    @abstractmethod
+    async def set_job_state(self, job_id: str, state: str, ttl: int = 86400):
+        """Abstract method for setting job state"""
+
+    @abstractmethod
+    async def get_job_state(self, job_id: str) -> Optional[str]:
+        """Abstract method for getting job state"""
+
+    @abstractmethod
+    async def get_fetch_mode(self) -> FetchMode:
+        """Abstract method for getting fetch mode"""