clams-python 1.3.3__tar.gz → 1.5.0__tar.gz

{clams_python-1.3.3/clams_python.egg-info → clams_python-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clams-python
-Version: 1.3.3
+Version: 1.5.0
 Summary: A collection of APIs to develop CLAMS app for python
 Home-page: https://clams.ai
 Author: Brandeis Lab for Linguistics and Computation
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mmif-python==1.1.2
+Requires-Dist: mmif-python==1.3.1
 Requires-Dist: Flask>=2
 Requires-Dist: Flask-RESTful>=0.3.9
 Requires-Dist: gunicorn>=20

clams_python-1.5.0/VERSION

@@ -0,0 +1 @@
+1.5.0

{clams_python-1.3.3 → clams_python-1.5.0}/clams/app/__init__.py

@@ -13,14 +13,29 @@ __all__ = ['ClamsApp']
 from typing import Union, Any, Optional, Dict, List, Tuple
 
 from mmif import Mmif, Document, DocumentTypes, View
+from mmif.utils.video_document_helper import (
+    SamplingMode, SAMPLING_MODE_DESCRIPTIONS, SAMPLING_MODE_DEFAULT,
+    _sampling_mode,
+)
+from mmif.utils.workflow_helper import generate_param_hash  # pytype: disable=import-error
 from clams.appmetadata import AppMetadata, real_valued_primitives, python_type, map_param_kv_delimiter
 
 logging.basicConfig(
-    level=logging.WARNING,
+    level=getattr(logging, os.environ.get('CLAMS_LOGLEVEL', 'WARNING').upper(), logging.WARNING),
     format="%(asctime)s %(name)s %(levelname)-8s %(thread)d %(message)s",
     datefmt="%Y-%m-%d %H:%M:%S")
 
 
+_sampling_mode_choices = [m.value for m in SamplingMode]
+_sampling_mode_description = (
+    'Sampling mode for TimeFrame annotations. '
+    'Has no effect when the app does not process TimeFrames. '
+    + ' '.join(
+        f'"{m.value}" {SAMPLING_MODE_DESCRIPTIONS[m]}'
+        for m in SamplingMode
+    )
+)
+
 falsy_values = [
     'False', 
     'false', 
@@ -47,13 +62,26 @@ class ClamsApp(ABC):
             'description': 'The JSON body of the HTTP response will be re-formatted with 2-space indentation',
         },
         {
-            'name': 'runningTime', 'type': 'boolean', 'choices': None, 'default': False, 'multivalued': False,
+            'name': 'runningTime', 'type': 'boolean', 'choices': None, 'default': True, 'multivalued': False,
             'description': 'The running time of the app will be recorded in the view metadata',
         },
         {
             'name': 'hwFetch', 'type': 'boolean', 'choices': None, 'default': False, 'multivalued': False,
             'description': 'The hardware information (architecture, GPU and vRAM) will be recorded in the view metadata',
         },
+        # tfSamplingMode is universal (not per-app) because it controls
+        # how vdh.extract_frames_by_mode() selects frames from TimeFrames.
+        # The value is intercepted in annotate() and pushed into a
+        # contextvars.ContextVar so that any vdh call inside _annotate()
+        # picks it up automatically — app developers never need to handle
+        # this parameter themselves.
+        {
+            'name': 'tfSamplingMode', 'type': 'string',
+            'choices': _sampling_mode_choices,
+            'default': SAMPLING_MODE_DEFAULT.value,
+            'multivalued': False,
+            'description': _sampling_mode_description,
+        },
     ]
     
     # this key is used to store users' raw input params in the parameter dict 
@@ -76,7 +104,7 @@ class ClamsApp(ABC):
 
         self.metadata_param_caster = ParameterCaster(self.metadata_param_spec)
         self.annotate_param_caster = ParameterCaster(self.annotate_param_spec)
-        self.logger = logging.getLogger(self.metadata.identifier)
+        self.logger = logging.getLogger(str(self.metadata.identifier))
         
     def appmetadata(self, **kwargs: List[str]) -> str:
         """
@@ -137,6 +165,7 @@ class ClamsApp(ABC):
         """
         if not isinstance(mmif, Mmif):
             mmif = Mmif(mmif)
+        existing_view_ids = {view.id for view in mmif.views}
         issued_warnings = []
         for key in runtime_params:
             if key not in self.annotate_param_spec:
@@ -146,35 +175,52 @@ class ClamsApp(ABC):
         refined = self._refine_params(**runtime_params)
         self.logger.debug(f"Refined parameters: {refined}")
         pretty = refined.get('pretty', False)
+        sampling_mode_str = refined.pop('tfSamplingMode', None)
+        if sampling_mode_str is not None:
+            _sampling_mode.set(SamplingMode(sampling_mode_str))
         t = datetime.now()
         with warnings.catch_warnings(record=True) as ws:
-            annotated = self._annotate(mmif, **refined)
+            annotated, cuda_profiler = self._profile_cuda_memory(self._annotate)(mmif, **refined)
             if ws:
                 issued_warnings.extend(ws)
         if issued_warnings:
             warnings_view = annotated.new_view()
             self.sign_view(warnings_view, refined)
             warnings_view.metadata.warnings = issued_warnings
-        td = datetime.now() - t
+        run_id = datetime.now()
+        td = run_id - t
         runningTime = refined.get('runningTime', False)
         hwFetch = refined.get('hwFetch', False)
         runtime_recs = {}
         if hwFetch:
+            import multiprocessing
             import platform, shutil, subprocess
-            runtime_recs['architecture'] = platform.machine()
-            # runtime_recs['processor'] = platform.processor()  # this only works on Windows
+            runtime_recs['cpu'] = f"{platform.machine()}, {multiprocessing.cpu_count()} cores"
             runtime_recs['cuda'] = []
-            if shutil.which('nvidia-smi'):
+            # Use cuda_profiler data if available, otherwise fallback to nvidia-smi
+            if cuda_profiler:
+                for gpu_name, mem_info in cuda_profiler.items():
+                    total_str = self._cuda_memory_to_str(mem_info['total'])
+                    available_str = self._cuda_memory_to_str(mem_info['available_before'])
+                    peak_str = self._cuda_memory_to_str(mem_info['peak'])
+                    runtime_recs['cuda'].append(
+                        f"{gpu_name}, {total_str} total, {available_str} available, {peak_str} peak used"
+                    )
+            elif shutil.which('nvidia-smi'):
                 for gpu in subprocess.run(['nvidia-smi', '--query-gpu=name,memory.total', '--format=csv,noheader'], 
                                           stdout=subprocess.PIPE).stdout.decode('utf-8').strip().split('\n'):
                     name, mem = gpu.split(', ')
-                    runtime_recs['cuda'].append(f'{name} ({mem})')
+                    runtime_recs['cuda'].append(self._cuda_device_name_concat(name, mem))
         for annotated_view in annotated.views:
-            if annotated_view.metadata.app == self.metadata.identifier:
+            if annotated_view.id not in existing_view_ids and annotated_view.metadata.app == str(self.metadata.identifier):
+                annotated_view.metadata.timestamp = run_id
+                profiling_data = {}
                 if runningTime:
-                    annotated_view.metadata.set_additional_property('appRunningTime', str(td))
+                    profiling_data['runningTime'] = str(td)
                 if len(runtime_recs) > 0:
-                    annotated_view.metadata.set_additional_property('appRunningHardware', runtime_recs)
+                    profiling_data['hardware'] = runtime_recs
+                if profiling_data:
+                    annotated_view.metadata.set_additional_property('appProfiling', profiling_data)
                     
         return annotated.serialize(pretty=pretty, sanitize=True)
 
@@ -252,7 +298,7 @@ class ClamsApp(ABC):
         :param view: a view to sign
         :param runtime_conf: runtime configuration of the app as k-v pairs
         """
-        view.metadata.app = self.metadata.identifier
+        view.metadata.app = str(self.metadata.identifier)
         params_map = {p.name: p for p in self.metadata.parameters}
         if self._RAW_PARAMS_KEY in runtime_conf:
             for k, v in runtime_conf.items():
@@ -287,7 +333,7 @@ class ClamsApp(ABC):
             mmif = Mmif(mmif)
         error_view: Optional[View] = None
         for view in reversed(mmif.views):
-            if view.metadata.app == self.metadata.identifier:
+            if view.metadata.app == str(self.metadata.identifier):
                 error_view = view
                 break
         if error_view is None:
@@ -321,6 +367,237 @@ class ClamsApp(ABC):
                 #  (https://github.com/clamsproject/mmif/issues/150) , here is a good place for additional check for
                 #  file integrity
 
+    @staticmethod
+    def _cuda_memory_to_str(mem) -> str:
+        mib = mem / (1024 * 1024)
+        return f"{mib:.0f} MiB"  # No decimal places
+
+    @staticmethod
+    def _cuda_device_name_concat(name, mem):
+        if type(mem) in (bytes, int):
+            mem = ClamsApp._cuda_memory_to_str(mem)
+        return f"{name}, With {mem}"
+
+    def _get_profile_path(self, param_hash: str) -> pathlib.Path:
+        """
+        Get filesystem path for memory profile file.
+
+        Profile files are stored in a per-app directory under user's cache.
+
+        :param param_hash: Hash of parameters from :func:`mmif.utils.cli.describe.generate_param_hash`
+        :return: Path to the profile file
+        """
+        # Sanitize app identifier for filesystem use
+        app_id = str(self.metadata.identifier).replace('/', '-').replace(':', '-')
+        cache_base = pathlib.Path(os.environ.get('XDG_CACHE_HOME', pathlib.Path.home() / '.cache'))
+        cache_dir = cache_base / 'clams' / 'memory_profiles' / app_id
+        return cache_dir / f"memory_{param_hash}.json"
+
+    @staticmethod
+    def _get_available_vram() -> int:
+        """
+        Get currently available VRAM in bytes (GPU-wide, across all processes).
+
+        Uses nvidia-smi to get actual available memory, not just current process.
+
+        :return: Available VRAM in bytes, or 0 if unavailable
+        """
+        try:
+            import subprocess
+            import shutil
+            if shutil.which('nvidia-smi'):
+                # Get free memory from nvidia-smi (reports GPU-wide, not per-process)
+                result = subprocess.run(
+                    ['nvidia-smi', '--query-gpu=memory.free', '--format=csv,noheader,nounits', '-i', '0'],
+                    capture_output=True, text=True, timeout=5
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    free_mb = float(result.stdout.strip())
+                    return int(free_mb * 1024 * 1024)  # Convert MB to bytes
+        except Exception:
+            pass
+
+        # Fallback to torch (only sees current process memory)
+        try:
+            import torch  # pytype: disable=import-error
+            if not torch.cuda.is_available():
+                return 0
+
+            device = torch.cuda.current_device()
+            total = torch.cuda.get_device_properties(device).total_memory
+            used = max(torch.cuda.memory_allocated(device),
+                       torch.cuda.memory_reserved(device))
+            return total - used
+        except Exception:
+            return 0
+
+    def _record_vram_usage(self, parameters: dict, peak_bytes: int) -> None:
+        """
+        Record peak memory usage to profile file.
+
+        Uses atomic write (temp + rename) to avoid corruption from
+        concurrent writes. Only updates if new value is higher.
+
+        Profile files are JSON containing:
+        - peak_bytes: Peak VRAM usage by the torch process
+        - parameters: Original parameters for human readability
+
+        :param parameters: Request parameters (for hash and recording)
+        :param peak_bytes: Measured peak VRAM usage
+        """
+        import json
+
+        if peak_bytes <= 0:
+            return
+
+        param_hash = generate_param_hash(parameters)
+        profile_path = self._get_profile_path(param_hash)
+
+        try:
+            profile_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Check if we should update
+            should_write = True
+            if profile_path.exists():
+                try:
+                    existing_data = json.loads(profile_path.read_text())
+                    existing = existing_data.get('peak_bytes', 0)
+                    if peak_bytes <= existing:
+                        should_write = False  # Existing value is sufficient
+                    else:
+                        self.logger.debug(
+                            f"Updating peak memory for {param_hash}: "
+                            f"{self._cuda_memory_to_str(existing)} -> {self._cuda_memory_to_str(peak_bytes)}"
+                        )
+                except (ValueError, IOError, json.JSONDecodeError):
+                    pass  # Corrupted file, overwrite
+
+            if should_write:
+                # Prepare profile data with original parameters for readability
+                # Filter out internal keys and non-serializable values
+                clean_params = {
+                    k: v for k, v in parameters.items()
+                    if k != self._RAW_PARAMS_KEY and not k.startswith('#')
+                }
+                profile_data = {
+                    'peak_bytes': peak_bytes,
+                    'parameters': clean_params
+                }
+
+                # Atomic write: write to temp, then rename
+                temp_path = profile_path.with_suffix('.tmp')
+                temp_path.write_text(json.dumps(profile_data, indent=2))
+                temp_path.rename(profile_path)  # Atomic on POSIX
+
+                self.logger.info(
+                    f"Recorded peak memory for {param_hash}: "
+                    f"{self._cuda_memory_to_str(peak_bytes)}"
+                )
+        except Exception as e:
+            self.logger.warning(f"Failed to record memory profile: {e}")
+
+    @staticmethod
+    def _profile_cuda_memory(func):
+        """
+        Decorator for profiling CUDA memory usage and managing VRAM availability.
+
+        This decorator:
+        1. Checks VRAM requirements before execution (if conditions met)
+        2. Rejects requests if insufficient VRAM
+        3. Records peak memory usage after execution
+        4. Calls empty_cache() for cleanup
+
+        :param func: The function to wrap (typically _annotate)
+        :return: Decorated function that returns (result, cuda_profiler)
+                 where cuda_profiler is dict with "<GPU_NAME>, <GPU_TOTAL_MEMORY>" keys
+                 and dict values containing 'available_before' and 'peak' memory in bytes
+        """
+        def wrapper(*args, **kwargs):
+            # Get the ClamsApp instance from the bound method
+            app_instance = getattr(func, '__self__', None)
+
+            cuda_profiler = {}
+            torch_available = False
+            cuda_available = False
+            device_count = 0
+            available_before = {}
+
+            try:
+                import torch  # pytype: disable=import-error
+                torch_available = True
+                cuda_available = torch.cuda.is_available()
+                device_count = torch.cuda.device_count()
+            except ImportError:
+                pass
+
+            # Capture available VRAM before execution and reset stats
+            if torch_available and cuda_available:
+                for device_id in range(device_count):
+                    device_id_str = f'cuda:{device_id}'
+                    # Get GPU-wide available memory via nvidia-smi
+                    try:
+                        import subprocess
+                        import shutil
+                        if shutil.which('nvidia-smi'):
+                            result = subprocess.run(
+                                ['nvidia-smi', '--query-gpu=memory.free',
+                                 '--format=csv,noheader,nounits', '-i', str(device_id)],
+                                capture_output=True, text=True, timeout=5
+                            )
+                            if result.returncode == 0 and result.stdout.strip():
+                                free_mb = float(result.stdout.strip())
+                                available_before[device_id] = int(free_mb * 1024 * 1024)
+                            else:
+                                # Fallback to torch (process-specific)
+                                total = torch.cuda.get_device_properties(device_id_str).total_memory
+                                allocated = torch.cuda.memory_allocated(device_id_str)
+                                available_before[device_id] = total - allocated
+                        else:
+                            # Fallback to torch (process-specific)
+                            total = torch.cuda.get_device_properties(device_id_str).total_memory
+                            allocated = torch.cuda.memory_allocated(device_id_str)
+                            available_before[device_id] = total - allocated
+                    except Exception:
+                        # Fallback to torch (process-specific)
+                        total = torch.cuda.get_device_properties(device_id_str).total_memory
+                        allocated = torch.cuda.memory_allocated(device_id_str)
+                        available_before[device_id] = total - allocated
+                # Reset peak memory stats for all devices
+                torch.cuda.reset_peak_memory_stats('cuda')
+
+            try:
+                result = func(*args, **kwargs)
+
+                # Record peak memory usage
+                total_peak = 0
+                if torch_available and cuda_available and device_count > 0:
+                    for device_id in range(device_count):
+                        device_id_str = f'cuda:{device_id}'
+                        peak_memory = torch.cuda.max_memory_allocated(device_id_str)
+                        total_peak = max(total_peak, peak_memory)
+                        gpu_name = torch.cuda.get_device_name(device_id_str)
+                        gpu_total_memory = torch.cuda.get_device_properties(device_id_str).total_memory
+                        cuda_profiler[gpu_name] = {
+                            'total': gpu_total_memory,
+                            'available_before': available_before.get(device_id, 0),
+                            'peak': peak_memory
+                        }
+
+                    # Record peak memory for future requests (if GPU app)
+                    gpu_app = (
+                        hasattr(app_instance, 'metadata') and
+                        getattr(app_instance.metadata, 'est_gpu_mem_min', 0) > 0
+                    )
+                    if gpu_app and total_peak > 0:
+                        app_instance._record_vram_usage(kwargs, total_peak)
+
+                return result, cuda_profiler
+            finally:
+                if torch_available and cuda_available:
+                    torch.cuda.empty_cache()
+
+        return wrapper
+
     @staticmethod
     @contextmanager
     def open_document_location(document: Union[str, Document], opener: Any = open, **openerargs):

{clams_python-1.3.3 → clams_python-1.5.0}/clams/appmetadata/__init__.py

@@ -1,3 +1,4 @@
+import json
 import os
 import shutil
 import subprocess
@@ -131,11 +132,6 @@ class Output(_BaseModel):
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
         
-    @pydantic.field_validator('at_type', mode='after')  # because pydantic v2 doesn't auto-convert url to string
-    @classmethod
-    def stringify(cls, val):
-        return str(val)
-    
     @pydantic.field_validator('at_type', mode='before')
     @classmethod
     def at_type_must_be_str(cls, v):
@@ -295,6 +291,10 @@ class AppMetadata(pydantic.BaseModel):
         None, 
         description="(optional) Version of an analyzer software, if the app is working as a wrapper for one. "
     )
+    analyzer_versions: Optional[Dict[str, str]] = pydantic.Field(
+        None,
+        description="(optional) Map of analyzer IDs to their versions, for apps that wrap multiple models or families."
+    )
     app_license: str = pydantic.Field(
         ..., 
         description="License information of the app."
@@ -352,9 +352,20 @@ class AppMetadata(pydantic.BaseModel):
                     "a package name and its version in the string value at the minimum (e.g., ``clams-python==1.2.3``)."
     )
     more: Optional[Dict[str, str]] = pydantic.Field(
-        None, 
+        None,
         description="(optional) A string-to-string map that can be used to store any additional metadata of the app."
     )
+    est_gpu_mem_min: int = pydantic.Field(
+        0,
+        description="(optional) Minimum GPU memory required to run the app, in megabytes (MB). "
+                    "Set to 0 (default) if the app does not use GPU."
+    )
+    est_gpu_mem_typ: int = pydantic.Field(
+        0,
+        description="(optional) Typical GPU memory usage for default parameters, in megabytes (MB). "
+                    "Must be equal or larger than est_gpu_mem_min. "
+                    "Set to 0 (default) if the app does not use GPU."
+    )
 
     model_config = {
         'title': 'CLAMS AppMetadata',
@@ -364,13 +375,26 @@ class AppMetadata(pydantic.BaseModel):
     }
     
     @pydantic.model_validator(mode='after')
-    @classmethod
-    def assign_versions(cls, data):
-        if data.app_version == '':
-            data.app_version = generate_app_version()
-        if data.mmif_version == '':
-            data.mmif_version = get_mmif_specver()
-        return data
+    def assign_versions(self):
+        if self.app_version == '':
+            self.app_version = generate_app_version()
+        if self.mmif_version == '':
+            self.mmif_version = get_mmif_specver()
+        return self
+
+    @pydantic.model_validator(mode='after')
+    def validate_gpu_memory(self):
+        import warnings
+        if self.est_gpu_mem_typ > 0 and self.est_gpu_mem_min > 0:
+            if self.est_gpu_mem_typ < self.est_gpu_mem_min:
+                warnings.warn(
+                    f"est_gpu_mem_typ ({self.est_gpu_mem_typ} MB) is less than "
+                    f"est_gpu_mem_min ({self.est_gpu_mem_min} MB). "
+                    f"Setting est_gpu_mem_typ to {self.est_gpu_mem_min} MB.",
+                    UserWarning
+                )
+                self.est_gpu_mem_typ = self.est_gpu_mem_min
+        return self
 
     @pydantic.field_validator('identifier', mode='before')
     @classmethod
@@ -379,11 +403,7 @@ class AppMetadata(pydantic.BaseModel):
         suffix = generate_app_version()
         return '/'.join(map(lambda x: x.strip('/'), filter(None, (prefix, val, suffix))))
 
-    @pydantic.field_validator('url', 'identifier', mode='after')  # because pydantic v2 doesn't auto-convert url to string
-    @classmethod
-    def stringify(cls, val):
-        return str(val)
-    
+
     def _check_input_duplicate(self, a_input):
         for elem in self.input:
             if isinstance(elem, list):
@@ -504,4 +524,4 @@ class AppMetadata(pydantic.BaseModel):
 
 
 if __name__ == '__main__':
-    print(AppMetadata.schema_json(indent=2))
+    print(json.dumps(AppMetadata.model_json_schema(), indent=2))

{clams_python-1.3.3 → clams_python-1.5.0}/clams/develop/templates/app/metadata.py.template

@@ -39,6 +39,9 @@ def appmetadata() -> AppMetadata:
         # this trick can also be useful (replace ANALYZER_NAME with the pypi dist name)
         analyzer_version=[l.strip().rsplit('==')[-1] for l in open(pathlib.Path(__file__).parent / 'requirements.txt').readlines() if re.match(r'^ANALYZER_NAME==', l)][0],
         analyzer_license="",  # short name for a software license
+        # GPU memory estimates (in MB). Set to 0 if the app does not use GPU.
+        est_gpu_mem_min=0,  # estimated memory usage with minimal computation parameters
+        est_gpu_mem_typ=0,  # estimated memory usage with default parameters, must be >= est_gpu_mem_min
     )
     # and then add I/O specifications: an app must have at least one input and one output
     metadata.add_input(DocumentTypes.Document)

{clams_python-1.3.3 → clams_python-1.5.0}/clams/restify/__init__.py

@@ -42,14 +42,55 @@ class Restifier(object):
     def serve_production(self, **options):
         """
         Runs the CLAMS app as a flask webapp, using a production-ready web server (gunicorn, https://docs.gunicorn.org/en/stable/#).
-        
+
         :param options: any additional options to pass to the web server.
         """
         import gunicorn.app.base
         import multiprocessing
+        import os
 
         def number_of_workers():
-            return (multiprocessing.cpu_count() * 2) + 1  # +1 to make sure at least two workers are running
+            # Allow override via environment variable
+            if 'CLAMS_GUNICORN_WORKERS' in os.environ:
+                return int(os.environ['CLAMS_GUNICORN_WORKERS'])
+
+            cpu_workers = (multiprocessing.cpu_count() * 2) + 1
+
+            # Get GPU memory requirement from app metadata
+            # Use est_gpu_mem_typ (typical usage) for worker calculation
+            try:
+                metadata = self.cla.metadata
+                gpu_mem_mb = metadata.est_gpu_mem_typ  # typical usage determines how many workers fit
+            except Exception:
+                gpu_mem_mb = 0
+
+            if gpu_mem_mb <= 0:
+                return cpu_workers
+
+            # Calculate workers based on total VRAM of the first CUDA device (no other GPUs are considered for now)
+            # Use nvidia-smi instead of torch to avoid initializing CUDA in parent process before fork
+            try:
+                import subprocess
+                import shutil
+                if shutil.which('nvidia-smi'):
+                    result = subprocess.run(
+                        ['nvidia-smi', '--query-gpu=memory.total', '--format=csv,noheader,nounits', '-i', '0'],
+                        capture_output=True, text=True, timeout=5
+                    )
+                    if result.returncode == 0 and result.stdout.strip():
+                        total_vram_mb = float(result.stdout.strip())
+                        vram_workers = max(1, int(total_vram_mb // gpu_mem_mb))
+                        workers = min(vram_workers, cpu_workers)
+                        self.cla.logger.info(
+                            f"GPU detected: {total_vram_mb:.0f} MB VRAM, "
+                            f"app requires {gpu_mem_mb} MB, "
+                            f"using {workers} workers (max {vram_workers} by VRAM, {cpu_workers} by CPU)"
+                        )
+                        return workers
+            except Exception:
+                pass
+
+            return cpu_workers
         
         class ProductionApplication(gunicorn.app.base.BaseApplication):
 
@@ -58,9 +99,16 @@ class Restifier(object):
                     'bind': f'{host}:{port}',
                     'workers': number_of_workers(),
                     'threads': 2,
+                    # disable timeout for long-running GPU workloads (default 30s is too short)
+                    'timeout': 0,
                     # because the default is 'None'
                     'accesslog': '-',
                     # errorlog, however, is redirected to stderr by default since 19.2, so no need to set
+                    # log level is warning by default
+                    'loglevel': os.environ.get('CLAMS_LOGLEVEL', 'warning').lower(),
+                    # default to 1 to free GPU memory after each request
+                    # developers can override via serve_production(max_requests=N) for single-model apps
+                    'max_requests': 1,
                 }
                 self.options.update(options)
                 self.application = app
@@ -75,6 +123,13 @@ class Restifier(object):
             def load(self):
                 return self.application
 
+        # Log max_requests setting
+        max_req = options.get('max_requests', 1)  # default is 1, meaning workers are killed after each request
+        if max_req == 0:
+            self.cla.logger.info("Worker recycling: disabled (workers persist)")
+        else:
+            self.cla.logger.info(f"Worker recycling: after {max_req} request(s)")
+
         ProductionApplication(self.flask_app, self.host, self.port, **options).run()
 
     def serve_development(self, **options):

clams_python-1.5.0/clams/ver/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.5.0"

{clams_python-1.3.3 → clams_python-1.5.0/clams_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clams-python
-Version: 1.3.3
+Version: 1.5.0
 Summary: A collection of APIs to develop CLAMS app for python
 Home-page: https://clams.ai
 Author: Brandeis Lab for Linguistics and Computation
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mmif-python==1.1.2
+Requires-Dist: mmif-python==1.3.1
 Requires-Dist: Flask>=2
 Requires-Dist: Flask-RESTful>=0.3.9
 Requires-Dist: gunicorn>=20

{clams_python-1.3.3 → clams_python-1.5.0}/clams_python.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mmif-python==1.1.2
+mmif-python==1.3.1
 Flask>=2
 Flask-RESTful>=0.3.9
 gunicorn>=20

{clams_python-1.3.3 → clams_python-1.5.0}/requirements.txt

@@ -1,4 +1,4 @@
-mmif-python==1.1.2
+mmif-python==1.3.1
 
 Flask>=2
 Flask-RESTful>=0.3.9

{clams_python-1.3.3 → clams_python-1.5.0}/tests/test_clamsapp.py

@@ -85,7 +85,7 @@ class ExampleClamsApp(clams.app.ClamsApp):
 class TestClamsApp(unittest.TestCase):
     
     def setUp(self):
-        self.appmetadataschema = json.loads(AppMetadata.schema_json())
+        self.appmetadataschema = AppMetadata.model_json_schema()
         self.app = ExampleClamsApp()
         self.in_mmif = ExampleInputMMIF.get_mmif()
 
@@ -234,12 +234,12 @@ class TestClamsApp(unittest.TestCase):
         m = Mmif(self.in_mmif)
         v1 = m.new_view()
         self.app.sign_view(v1, {})
-        self.assertEqual(v1.metadata.app, self.app.metadata.identifier)
+        self.assertEqual(v1.metadata.app, str(self.app.metadata.identifier))
         self.assertEqual(len(v1.metadata.parameters), 0)
         v2 = m.new_view()
         args2 = {'undefined_param1': ['value1']}  # values are lists as our restifier uses `to_dict(flat=False)`
         self.app.sign_view(v2, self.app._refine_params(**args2))
-        self.assertEqual(v2.metadata.app, self.app.metadata.identifier)
+        self.assertEqual(v2.metadata.app, str(self.app.metadata.identifier))
         self.assertEqual(len(v2.metadata.parameters), 1)
         self.assertFalse(clams.ClamsApp._RAW_PARAMS_KEY in v2.metadata.appConfiguration)
         for param in self.app.metadata.parameters:
@@ -253,14 +253,14 @@ class TestClamsApp(unittest.TestCase):
         args3 = {'undefined_param1': ['value1']} 
         self.app.sign_view(v3, self.app._refine_params(**args3))
         self.assertEqual(len(v3.metadata.parameters), 1)
-        self.assertEqual(len(v3.metadata.appConfiguration), 5)  # universal (pretty, runningtime, hwfetch) + `raise_error` in metadata.py + `multivalued_param`
+        self.assertEqual(len(v3.metadata.appConfiguration), 6)  # universal (pretty, runningTime, hwFetch, tfSamplingMode) + `raise_error` in metadata.py + `multivalued_param`
         self.assertEqual(v3.metadata.appConfiguration['multivalued_param'], [])
         v4 = m.new_view()
         multiple_values = ['value1', 'value2']
         args4 = {'multivalued_param': multiple_values}
         self.app.sign_view(v4, self.app._refine_params(**args4))
         self.assertEqual(len(v4.metadata.parameters), 1)
-        self.assertEqual(len(v4.metadata.appConfiguration), 5)
+        self.assertEqual(len(v4.metadata.appConfiguration), 6)
         self.assertEqual(len(v4.metadata.parameters['multivalued_param']), len(str(multiple_values)))
 
     def test_annotate(self):
@@ -271,19 +271,41 @@ class TestClamsApp(unittest.TestCase):
         out_mmif = Mmif(out_mmif)
         self.assertEqual(len(out_mmif.views), 2)
         for v in out_mmif.views:
-            if v.metadata.app == self.app.metadata.identifier:
+            if v.metadata.app == str(self.app.metadata.identifier):
                 self.assertEqual(len(v.metadata.parameters), 0)  # no params were passed when `annotate()` was called
         out_mmif = self.app.annotate(self.in_mmif, pretty=[str(False)])
         out_mmif = Mmif(out_mmif)
         for v in out_mmif.views:
-            if v.metadata.app == self.app.metadata.identifier:
+            if v.metadata.app == str(self.app.metadata.identifier):
                 self.assertEqual(len(v.metadata.parameters), 1)  # 'pretty` parameter was passed 
         out_mmif = Mmif(self.app.annotate(out_mmif))
         self.assertEqual(len(out_mmif.views), 4)
         views = list(out_mmif.views)
         # insertion order is kept
-        self.assertTrue(views[0].metadata.timestamp < views[1].metadata.timestamp)
-    
+        self.assertEqual(views[0].metadata.timestamp, views[1].metadata.timestamp)
+        self.assertEqual(views[2].metadata.timestamp, views[3].metadata.timestamp)
+        self.assertTrue(views[1].metadata.timestamp < views[2].metadata.timestamp)
+
+    def test_run_id(self):
+        # first run
+        out_mmif = Mmif(self.app.annotate(self.in_mmif))
+        app_views = [v for v in out_mmif.views if v.metadata.app == str(self.app.metadata.identifier)]
+        self.assertTrue(len(app_views) > 0)
+        first_timestamp = app_views[0].metadata.timestamp
+        for view in app_views[1:]:
+            self.assertEqual(first_timestamp, view.metadata.timestamp)
+        # second run
+        out_mmif2 = Mmif(self.app.annotate(out_mmif))
+        app_views2 = [v for v in out_mmif2.views if v.metadata.app == str(self.app.metadata.identifier)]
+        self.assertEqual(len(app_views2), len(app_views) * 2)
+        second_timestamp = app_views2[-1].metadata.timestamp
+        self.assertNotEqual(first_timestamp, second_timestamp)
+        for view in app_views2:
+            if view.id in [v.id for v in app_views]:
+                self.assertEqual(first_timestamp, view.metadata.timestamp)
+            else:
+                self.assertEqual(second_timestamp, view.metadata.timestamp)
+
     def test_annotate_returns_invalid_mmif(self):
         m = Mmif(self.in_mmif)
         v = m.new_view()
@@ -297,13 +319,13 @@ class TestClamsApp(unittest.TestCase):
 
     def test_open_document_location(self):
         mmif = ExampleInputMMIF.get_rawmmif()
-        with self.app.open_document_location(mmif.documents['t1']) as f:
+        with self.app.open_document_location(mmif['t1']) as f:
             self.assertEqual(f.read(), ExampleInputMMIF.EXAMPLE_TEXT)
 
     def test_open_document_location_custom_opener(self):
         from PIL import Image
         mmif = ExampleInputMMIF.get_rawmmif()
-        with self.app.open_document_location(mmif.documents['i1'], Image.open) as f:
+        with self.app.open_document_location(mmif['i1'], Image.open) as f:
             self.assertEqual(f.size, (200, 71))
             
     def test_refine_parameters(self):
@@ -355,20 +377,89 @@ class TestClamsApp(unittest.TestCase):
     def test_error_handling(self):
         params = {'raise_error': ['true'], 'pretty': ['true']}
         in_mmif = Mmif(self.in_mmif)
-        try: 
+        try:
             out_mmif = self.app.annotate(in_mmif, **params)
         except Exception as e:
             out_mmif_from_str = self.app.set_error_view(self.in_mmif, **params)
             out_mmif_from_mmif = self.app.set_error_view(in_mmif, **params)
             self.assertEqual(
-                out_mmif_from_mmif.views.get_last(),
-                out_mmif_from_str.views.get_last())
+                out_mmif_from_mmif.views.get_last_contentful_view(),
+                out_mmif_from_str.views.get_last_contentful_view())
             out_mmif = out_mmif_from_str
         self.assertIsNotNone(out_mmif)
         last_view: View = next(reversed(out_mmif.views))
         self.assertEqual(len(last_view.metadata.contains), 0)
         self.assertEqual(len(last_view.metadata.error), 2)
 
+    def test_gpu_mem_fields_default_zero(self):
+        """GPU memory fields default to 0."""
+        metadata = AppMetadata(
+            name="Test App",
+            description="Test",
+            app_license="MIT",
+            identifier="test-app",
+            url="https://example.com",
+        )
+        metadata.add_input(DocumentTypes.TextDocument)
+        metadata.add_output(AnnotationTypes.TimeFrame)
+
+        self.assertEqual(metadata.est_gpu_mem_min, 0)
+        self.assertEqual(metadata.est_gpu_mem_typ, 0)
+
+    def test_est_gpu_mem_typ_validation(self):
+        """Warning issued when est_gpu_mem_typ < est_gpu_mem_min, autocorrected."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+
+            metadata = AppMetadata(
+                name="Test App",
+                description="Test",
+                app_license="MIT",
+                identifier="test-app",
+                url="https://example.com",
+                est_gpu_mem_min=4000,  # 4GB min
+                est_gpu_mem_typ=2000,  # 2GB typical (less than min!)
+            )
+            metadata.add_input(DocumentTypes.TextDocument)
+            metadata.add_output(AnnotationTypes.TimeFrame)
+
+            # Should have issued a warning
+            self.assertEqual(len(w), 1)
+            self.assertIn('est_gpu_mem_typ', str(w[0].message))
+            self.assertIn('est_gpu_mem_min', str(w[0].message))
+
+            # Should have auto-corrected
+            self.assertEqual(metadata.est_gpu_mem_typ, metadata.est_gpu_mem_min)
+
+        def test_analyzer_versions_default_none(self):
+            """analyzer_versions field defaults to None."""
+            metadata = AppMetadata(
+                name="Test App",
+                description="Test",
+                app_license="MIT",
+                identifier="test-app",
+                url="https://example.com",
+            )
+            metadata.add_input(DocumentTypes.TextDocument)
+            metadata.add_output(AnnotationTypes.TimeFrame)
+
+            self.assertIsNone(metadata.analyzer_versions)
+
+        def test_analyzer_versions_with_value(self):
+            """analyzer_versions can be set with a dictionary."""
+            test_versions = {"model_a": "1.0", "model_b": "2.1"}
+            metadata = AppMetadata(
+                name="Test App",
+                description="Test",
+                app_license="MIT",
+                identifier="test-app",
+                url="https://example.com",
+                analyzer_versions=test_versions,
+            )
+            metadata.add_input(DocumentTypes.TextDocument)
+            metadata.add_output(AnnotationTypes.TimeFrame)
+
+            self.assertEqual(metadata.analyzer_versions, test_versions)
 
 class TestRestifier(unittest.TestCase):
 

clams_python-1.3.3/VERSION

@@ -1 +0,0 @@
-1.3.3

clams_python-1.3.3/clams/ver/__init__.py

@@ -1 +0,0 @@
-__version__ = "1.3.3"