mozo 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

mozo/__init__.py

@@ -1,9 +1,54 @@
 """
-mozo - A dummy Python library
+Mozo - Universal Computer Vision Model Server
+
+25+ pre-configured models ready to use. No deployment, no configuration.
+Just `mozo start` and make HTTP requests.
+
+Quick Start:
+    >>> # From terminal:
+    >>> mozo start
+    >>>
+    >>> # Then use any model via HTTP:
+    >>> curl -X POST "http://localhost:8000/predict/detectron2/mask_rcnn_R_50_FPN_3x" \\
+    >>>   -F "file=@image.jpg"
+
+Advanced Usage (Python SDK):
+    >>> from mozo import ModelManager
+    >>> import cv2
+    >>>
+    >>> manager = ModelManager()
+    >>> model = manager.get_model('detectron2', 'mask_rcnn_R_50_FPN_3x')
+    >>> image = cv2.imread('example.jpg')
+    >>> detections = model.predict(image)  # Returns PixelFlow Detections
+    >>> print(f"Found {len(detections)} objects")
+
+Features:
+    - 25+ models from Detectron2, HuggingFace Transformers
+    - Zero deployment - no Docker, Kubernetes, or cloud needed
+    - Automatic memory management with lazy loading
+    - PixelFlow integration for unified detection format
+    - Thread-safe concurrent access
+
+For more information, see:
+    - Documentation: https://github.com/datamarkin/mozo
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
+
+# Public API exports
+from mozo.manager import ModelManager
+from mozo.registry import (
+    MODEL_REGISTRY,
+    get_available_families,
+    get_available_variants,
+    get_model_info,
+)
 
-def hello():
-    """Simple hello function"""
-    return "Hello from mozo library!"
+__all__ = [
+    "ModelManager",
+    "MODEL_REGISTRY",
+    "get_available_families",
+    "get_available_variants",
+    "get_model_info",
+    "__version__",
+]

mozo/__main__.py

@@ -0,0 +1,24 @@
+"""
+Entry point for running `python -m mozo`.
+
+This delegates to the CLI start command for consistency.
+"""
+
+from mozo.cli import cli
+import sys
+
+
+def main():
+    """
+    Entry point when running `python -m mozo`.
+    Defaults to the start command for backward compatibility.
+    """
+    # If no arguments, default to 'start --reload'
+    if len(sys.argv) == 1:
+        sys.argv.extend(['start', '--reload'])
+
+    cli()
+
+
+if __name__ == "__main__":
+    main()

mozo/adapters/depth_anything.py

@@ -0,0 +1,75 @@
+from PIL import Image
+import numpy as np
+import cv2
+
+try:
+    from transformers import pipeline
+except ImportError:
+    print("="*50)
+    print("ERROR: `transformers` is not installed.")
+    print("Please install it with: `pip install transformers`")
+    print("="*50)
+    raise
+
+class DepthAnythingPredictor:
+    """
+    Universal Depth Anything adapter - handles all model size variants.
+    Supports small, base, and large variants of Depth Anything V2.
+    """
+
+    # Registry of all supported Depth Anything model variants
+    SUPPORTED_VARIANTS = {
+        'small': 'depth-anything/Depth-Anything-V2-Small-hf',
+        'base': 'depth-anything/Depth-Anything-V2-Base-hf',
+        'large': 'depth-anything/Depth-Anything-V2-Large-hf',
+    }
+
+    def __init__(self, variant="small"):
+        """
+        Initialize Depth Anything predictor with specific model size variant.
+
+        Args:
+            variant: Model size variant - 'small', 'base', or 'large'
+                    small:  Fastest, lowest memory, good for real-time applications
+                    base:   Balanced speed and accuracy
+                    large:  Best accuracy, slower, higher memory usage
+
+        Raises:
+            ValueError: If variant is not supported
+        """
+        if variant not in self.SUPPORTED_VARIANTS:
+            raise ValueError(
+                f"Unsupported variant: '{variant}'. "
+                f"Choose from: {list(self.SUPPORTED_VARIANTS.keys())}"
+            )
+
+        self.variant = variant
+        model_name = self.SUPPORTED_VARIANTS[variant]
+
+        print(f"Loading Depth Anything model (variant: {variant}, model: {model_name})...")
+        self.pipe = pipeline(task="depth-estimation", model=model_name)
+        print(f"Depth Anything model loaded successfully (variant: {variant}).")
+
+    def predict(self, image: np.ndarray) -> Image.Image:
+        """
+        Runs depth estimation on an image.
+
+        Args:
+            image: A numpy array representing the input image in BGR format (from cv2).
+
+        Returns:
+            A PIL.Image object representing the depth map.
+        """
+        print("Running depth estimation...")
+        # The pipeline expects a PIL Image in RGB format.
+        # cv2 reads images as BGR, so we need to convert it.
+        image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+        pil_image = Image.fromarray(image_rgb)
+        
+        result = self.pipe(pil_image)
+        
+        # The pipeline returns a dictionary, the depth map is in the "depth" key
+        depth_map = result["depth"]
+        
+        print("Depth estimation complete.")
+        return depth_map

mozo/adapters/detectron2.py

@@ -0,0 +1,128 @@
+import cv2
+import numpy as np
+
+try:
+    from detectron2.engine import DefaultPredictor
+    from detectron2.config import get_cfg
+    from detectron2 import model_zoo
+    from detectron2.data import MetadataCatalog
+except ImportError:
+    print("="*50)
+    print("ERROR: Detectron2 is not installed.")
+    print("Please install it following the instructions at:")
+    print("https://detectron2.readthedocs.io/en/latest/tutorials/install.html")
+    print("="*50)
+    raise
+
+try:
+    import pixelflow as pf
+except ImportError:
+    print("="*50)
+    print("ERROR: PixelFlow is not installed.")
+    print("Please install it with: pip install pixelflow")
+    print("="*50)
+    raise
+
+class Detectron2Predictor:
+    """
+    Universal Detectron2 adapter - handles ALL detectron2 model variants.
+    Supports multiple model families: Mask R-CNN, Faster R-CNN, RetinaNet, Keypoint R-CNN, etc.
+    """
+
+    # Registry of all supported detectron2 model variants
+    SUPPORTED_CONFIGS = {
+        # Mask R-CNN (Instance Segmentation)
+        'mask_rcnn_R_50_FPN_3x': 'COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml',
+        'mask_rcnn_R_50_C4_1x': 'COCO-InstanceSegmentation/mask_rcnn_R_50_C4_1x.yaml',
+        'mask_rcnn_R_50_C4_3x': 'COCO-InstanceSegmentation/mask_rcnn_R_50_C4_3x.yaml',
+        'mask_rcnn_R_50_DC5_1x': 'COCO-InstanceSegmentation/mask_rcnn_R_50_DC5_1x.yaml',
+        'mask_rcnn_R_50_DC5_3x': 'COCO-InstanceSegmentation/mask_rcnn_R_50_DC5_3x.yaml',
+        'mask_rcnn_R_50_FPN_1x': 'COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml',
+        'mask_rcnn_R_101_C4_3x': 'COCO-InstanceSegmentation/mask_rcnn_R_101_C4_3x.yaml',
+        'mask_rcnn_R_101_DC5_3x': 'COCO-InstanceSegmentation/mask_rcnn_R_101_DC5_3x.yaml',
+        'mask_rcnn_R_101_FPN_3x': 'COCO-InstanceSegmentation/mask_rcnn_R_101_FPN_3x.yaml',
+        'mask_rcnn_X_101_32x8d_FPN_3x': 'COCO-InstanceSegmentation/mask_rcnn_X_101_32x8d_FPN_3x.yaml',
+
+        # Faster R-CNN (Object Detection)
+        'faster_rcnn_R_50_C4_1x': 'COCO-Detection/faster_rcnn_R_50_C4_1x.yaml',
+        'faster_rcnn_R_50_C4_3x': 'COCO-Detection/faster_rcnn_R_50_C4_3x.yaml',
+        'faster_rcnn_R_50_DC5_1x': 'COCO-Detection/faster_rcnn_R_50_DC5_1x.yaml',
+        'faster_rcnn_R_50_DC5_3x': 'COCO-Detection/faster_rcnn_R_50_DC5_3x.yaml',
+        'faster_rcnn_R_50_FPN_1x': 'COCO-Detection/faster_rcnn_R_50_FPN_1x.yaml',
+        'faster_rcnn_R_50_FPN_3x': 'COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml',
+        'faster_rcnn_R_101_C4_3x': 'COCO-Detection/faster_rcnn_R_101_C4_3x.yaml',
+        'faster_rcnn_R_101_DC5_3x': 'COCO-Detection/faster_rcnn_R_101_DC5_3x.yaml',
+        'faster_rcnn_R_101_FPN_3x': 'COCO-Detection/faster_rcnn_R_101_FPN_3x.yaml',
+        'faster_rcnn_X_101_32x8d_FPN_3x': 'COCO-Detection/faster_rcnn_X_101_32x8d_FPN_3x.yaml',
+
+        # RetinaNet (Object Detection)
+        'retinanet_R_50_FPN_1x': 'COCO-Detection/retinanet_R_50_FPN_1x.yaml',
+        'retinanet_R_50_FPN_3x': 'COCO-Detection/retinanet_R_50_FPN_3x.yaml',
+        'retinanet_R_101_FPN_3x': 'COCO-Detection/retinanet_R_101_FPN_3x.yaml',
+
+        # Keypoint R-CNN (Keypoint Detection)
+        'keypoint_rcnn_R_50_FPN_1x': 'COCO-Keypoints/keypoint_rcnn_R_50_FPN_1x.yaml',
+        'keypoint_rcnn_R_50_FPN_3x': 'COCO-Keypoints/keypoint_rcnn_R_50_FPN_3x.yaml',
+        'keypoint_rcnn_R_101_FPN_3x': 'COCO-Keypoints/keypoint_rcnn_R_101_FPN_3x.yaml',
+        'keypoint_rcnn_X_101_32x8d_FPN_3x': 'COCO-Keypoints/keypoint_rcnn_X_101_32x8d_FPN_3x.yaml',
+
+        # RPN (Region Proposal Network)
+        'rpn_R_50_C4_1x': 'COCO-Detection/rpn_R_50_C4_1x.yaml',
+        'rpn_R_50_FPN_1x': 'COCO-Detection/rpn_R_50_FPN_1x.yaml',
+
+        # Fast R-CNN
+        'fast_rcnn_R_50_FPN_1x': 'COCO-Detection/fast_rcnn_R_50_FPN_1x.yaml',
+    }
+
+    def __init__(self, variant="mask_rcnn_R_50_FPN_3x", confidence_threshold=0.5, device="cpu"):
+        """
+        Initialize Detectron2 predictor with specific model variant.
+
+        Args:
+            variant: Model variant name (e.g., 'mask_rcnn_R_50_FPN_3x', 'faster_rcnn_X_101_32x8d_FPN_3x')
+            confidence_threshold: Detection confidence threshold (0.0-1.0)
+            device: Device to run on - 'cpu' or 'cuda'
+
+        Raises:
+            ValueError: If variant is not supported
+        """
+        if variant not in self.SUPPORTED_CONFIGS:
+            raise ValueError(
+                f"Unsupported variant: '{variant}'. "
+                f"Choose from: {list(self.SUPPORTED_CONFIGS.keys())}"
+            )
+
+        self.variant = variant
+        config_file = self.SUPPORTED_CONFIGS[variant]
+
+        print(f"Loading Detectron2 model (variant: {variant})...")
+        cfg = get_cfg()
+        cfg.merge_from_file(model_zoo.get_config_file(config_file))
+        cfg.MODEL.WEIGHTS = model_zoo.get_checkpoint_url(config_file)
+        cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST = confidence_threshold
+        cfg.MODEL.DEVICE = device
+
+        self.predictor = DefaultPredictor(cfg)
+
+        # Get class names from metadata
+        dataset_name = cfg.DATASETS.TRAIN[0] if cfg.DATASETS.TRAIN else "coco_2017_val"
+        metadata = MetadataCatalog.get(dataset_name)
+        self.class_names = metadata.thing_classes
+
+        print(f"Detectron2 model loaded successfully (variant: {variant}).")
+
+    def predict(self, image: np.ndarray):
+        """
+        Runs inference on an image and returns PixelFlow Detections.
+
+        Returns:
+            pf.detections.Detections: PixelFlow Detections object containing all detected objects
+        """
+        print("Running prediction...")
+        outputs = self.predictor(image)
+
+        # Use PixelFlow's existing converter for Detectron2
+        detections = pf.detections.from_detectron2(outputs)
+
+        print(f"Found {len(detections)} objects.")
+        return detections

mozo/adapters/qwen2_5_vl.py

@@ -0,0 +1,170 @@
+from PIL import Image
+import numpy as np
+import cv2
+
+try:
+    from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessor
+    from qwen_vl_utils import process_vision_info
+except ImportError:
+    print("="*50)
+    print("ERROR: Qwen2.5-VL dependencies not installed.")
+    print("Install with:")
+    print("  pip install git+https://github.com/huggingface/transformers")
+    print("  pip install qwen-vl-utils")
+    print("="*50)
+    raise
+
+class Qwen2_5VLPredictor:
+    """
+    Universal Qwen2.5-VL adapter for vision-language understanding.
+
+    Supports:
+    - Image understanding and description
+    - Visual question answering (VQA)
+    - Object recognition and counting
+    - Text extraction (OCR)
+    - Chart and diagram analysis
+    - Visual reasoning
+    """
+
+    # Registry of all supported Qwen2.5-VL model variants
+    SUPPORTED_VARIANTS = {
+        '7b-instruct': 'Qwen/Qwen2.5-VL-7B-Instruct',
+        # Future variants can be added here:
+        # '2b-instruct': 'Qwen/Qwen2.5-VL-2B-Instruct',
+        # '72b-instruct': 'Qwen/Qwen2.5-VL-72B-Instruct',
+    }
+
+    def __init__(self, variant="7b-instruct", device="auto", torch_dtype="auto"):
+        """
+        Initialize Qwen2.5-VL predictor with specific model variant.
+
+        Args:
+            variant: Model size variant - '7b-instruct'
+                    7b-instruct: 7 billion parameters, balanced performance
+            device: Device placement - 'auto', 'cpu', 'cuda', 'mps'
+                   'auto' will automatically use best available device
+            torch_dtype: Precision - 'auto', 'float16', 'bfloat16', 'float32'
+                        'auto' will choose based on device capabilities
+
+        Raises:
+            ValueError: If variant is not supported
+
+        Note:
+            This is a large model (7B parameters). First load will download ~7-14GB.
+            Recommended: 16GB+ RAM and GPU/MPS for reasonable performance.
+        """
+        if variant not in self.SUPPORTED_VARIANTS:
+            raise ValueError(
+                f"Unsupported variant: '{variant}'. "
+                f"Choose from: {list(self.SUPPORTED_VARIANTS.keys())}"
+            )
+
+        self.variant = variant
+        model_name = self.SUPPORTED_VARIANTS[variant]
+
+        print(f"Loading Qwen2.5-VL model (variant: {variant}, model: {model_name})...")
+        print("Note: This is a 7B model and may take time to load on first run...")
+
+        # Load model and processor
+        self.model = Qwen2_5_VLForConditionalGeneration.from_pretrained(
+            model_name,
+            torch_dtype=torch_dtype,
+            device_map=device
+        )
+        self.processor = AutoProcessor.from_pretrained(model_name)
+
+        print(f"Qwen2.5-VL model loaded successfully (variant: {variant}).")
+        print(f"Model device: {self.model.device}")
+
+    def predict(self, image: np.ndarray, prompt: str = "Describe this image in detail.") -> dict:
+        """
+        Run vision-language understanding on an image.
+
+        Args:
+            image: Input image as numpy array (BGR format from cv2)
+            prompt: Text prompt/question about the image
+                   Examples:
+                   - "Describe this image in detail."
+                   - "What objects are in this image?"
+                   - "How many people are visible?"
+                   - "What is the text in this image?"
+                   - "Analyze this chart."
+
+        Returns:
+            dict: {
+                'text': str,      # Generated text response
+                'prompt': str,    # Original prompt used
+                'variant': str    # Model variant used
+            }
+
+        Example:
+            >>> predictor = Qwen2_5VLPredictor()
+            >>> result = predictor.predict(image, "What is in this image?")
+            >>> print(result['text'])
+        """
+        print(f"Running Qwen2.5-VL inference with prompt: '{prompt[:50]}...'")
+
+        # Convert BGR (OpenCV format) to RGB (PIL format)
+        image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+        pil_image = Image.fromarray(image_rgb)
+
+        # Prepare conversation in Qwen format
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": pil_image},
+                    {"type": "text", "text": prompt},
+                ],
+            }
+        ]
+
+        # Apply chat template
+        text = self.processor.apply_chat_template(
+            messages,
+            tokenize=False,
+            add_generation_prompt=True
+        )
+
+        # Process vision information
+        image_inputs, video_inputs = process_vision_info(messages)
+
+        # Prepare inputs for model
+        inputs = self.processor(
+            text=[text],
+            images=image_inputs,
+            videos=video_inputs,
+            padding=True,
+            return_tensors="pt",
+        )
+
+        # Move inputs to model device
+        inputs = inputs.to(self.model.device)
+
+        # Generate response
+        generated_ids = self.model.generate(
+            **inputs,
+            max_new_tokens=512  # Adjust based on expected response length
+        )
+
+        # Trim input tokens from generated output
+        generated_ids_trimmed = [
+            out_ids[len(in_ids):]
+            for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
+        ]
+
+        # Decode generated text
+        output_text = self.processor.batch_decode(
+            generated_ids_trimmed,
+            skip_special_tokens=True,
+            clean_up_tokenization_spaces=False
+        )[0]
+
+        print(f"Qwen2.5-VL inference complete. Generated {len(output_text)} characters.")
+
+        return {
+            'text': output_text,
+            'prompt': prompt,
+            'variant': self.variant
+        }

mozo/cli.py

@@ -0,0 +1,47 @@
+"""
+Command-line interface for Mozo.
+
+Provides simple commands for starting the server and checking version.
+"""
+
+import click
+import uvicorn
+
+
+@click.group()
+def cli():
+    """Mozo - Universal CV Model Server"""
+    pass
+
+
+@cli.command()
+@click.option('--host', default='0.0.0.0', help='Host to bind to')
+@click.option('--port', default=8000, type=int, help='Port to bind to')
+@click.option('--reload', is_flag=True, help='Enable auto-reload on code changes')
+@click.option('--workers', default=1, type=int, help='Number of worker processes')
+def start(host, port, reload, workers):
+    """Start the Mozo model server"""
+    click.echo(f"Starting Mozo server on {host}:{port}...")
+    if reload:
+        click.echo("Auto-reload enabled (development mode)")
+    if workers > 1:
+        click.echo(f"Running with {workers} worker processes")
+
+    uvicorn.run(
+        "mozo.server:app",
+        host=host,
+        port=port,
+        reload=reload,
+        workers=workers if not reload else 1  # reload only works with 1 worker
+    )
+
+
+@cli.command()
+def version():
+    """Show Mozo version"""
+    from mozo import __version__
+    click.echo(f"Mozo version {__version__}")
+
+
+if __name__ == '__main__':
+    cli()

mozo/factory.py

@@ -0,0 +1,150 @@
+"""
+Model Factory for Mozo
+
+Factory pattern implementation for dynamic model instantiation.
+Handles loading adapter classes and creating model instances from registry configurations.
+"""
+
+import importlib
+from .registry import MODEL_REGISTRY
+
+
+class ModelFactory:
+    """
+    Factory class for creating model instances dynamically.
+
+    The factory reads from MODEL_REGISTRY to instantiate the correct adapter class
+    with the appropriate parameters for the requested model variant.
+    """
+
+    def __init__(self):
+        """Initialize the model factory."""
+        self._adapter_cache = {}  # Cache for loaded adapter classes
+
+    def _get_adapter_class(self, module_path, class_name):
+        """
+        Dynamically import and return an adapter class.
+
+        Args:
+            module_path: Python module path (e.g., 'mozo.adapters.detectron2')
+            class_name: Class name to import (e.g., 'Detectron2Predictor')
+
+        Returns:
+            The adapter class
+
+        Raises:
+            ImportError: If module or class cannot be loaded
+        """
+        cache_key = f"{module_path}.{class_name}"
+
+        # Return cached class if available
+        if cache_key in self._adapter_cache:
+            return self._adapter_cache[cache_key]
+
+        try:
+            # Dynamically import the module
+            module = importlib.import_module(module_path)
+
+            # Get the class from the module
+            adapter_class = getattr(module, class_name)
+
+            # Cache for future use
+            self._adapter_cache[cache_key] = adapter_class
+
+            return adapter_class
+
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import module '{module_path}': {e}"
+            ) from e
+        except AttributeError as e:
+            raise ImportError(
+                f"Module '{module_path}' does not have class '{class_name}': {e}"
+            ) from e
+
+    def create_model(self, family, variant):
+        """
+        Create a model instance from family and variant identifiers.
+
+        Args:
+            family: Model family name (e.g., 'detectron2', 'depth_anything')
+            variant: Model variant name (e.g., 'mask_rcnn_R_50_FPN_3x', 'small')
+
+        Returns:
+            Instantiated model predictor object
+
+        Raises:
+            ValueError: If family or variant is not found in registry
+            ImportError: If adapter class cannot be loaded
+
+        Example:
+            >>> factory = ModelFactory()
+            >>> model = factory.create_model('detectron2', 'mask_rcnn_R_50_FPN_3x')
+            >>> predictions = model.predict(image)
+        """
+        # Validate family exists
+        if family not in MODEL_REGISTRY:
+            available_families = list(MODEL_REGISTRY.keys())
+            raise ValueError(
+                f"Unknown model family: '{family}'. "
+                f"Available families: {available_families}"
+            )
+
+        family_config = MODEL_REGISTRY[family]
+
+        # Validate variant exists for this family
+        if variant not in family_config['variants']:
+            available_variants = list(family_config['variants'].keys())
+            raise ValueError(
+                f"Unknown variant '{variant}' for family '{family}'. "
+                f"Available variants: {available_variants}"
+            )
+
+        # Get adapter class information
+        module_path = family_config['module']
+        class_name = family_config['adapter_class']
+
+        # Get variant-specific parameters
+        variant_params = family_config['variants'][variant]
+
+        # Load the adapter class
+        adapter_class = self._get_adapter_class(module_path, class_name)
+
+        # Instantiate the adapter with variant parameters
+        try:
+            model_instance = adapter_class(**variant_params)
+            return model_instance
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to instantiate {class_name} with parameters {variant_params}: {e}"
+            ) from e
+
+    def get_available_families(self):
+        """
+        Get list of all available model families.
+
+        Returns:
+            list: Model family names
+        """
+        return list(MODEL_REGISTRY.keys())
+
+    def get_available_variants(self, family):
+        """
+        Get list of all available variants for a model family.
+
+        Args:
+            family: Model family name
+
+        Returns:
+            list: Variant names for the family
+
+        Raises:
+            ValueError: If family not found
+        """
+        if family not in MODEL_REGISTRY:
+            raise ValueError(f"Unknown model family: '{family}'")
+        return list(MODEL_REGISTRY[family]['variants'].keys())
+
+    def clear_cache(self):
+        """Clear the adapter class cache."""
+        self._adapter_cache.clear()