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

mozo/server.py

@@ -0,0 +1,294 @@
+import io
+import cv2
+import json
+import numpy as np
+from pathlib import Path
+from fastapi import FastAPI, UploadFile, File, HTTPException
+from fastapi.responses import JSONResponse, StreamingResponse, FileResponse
+
+# Import model manager and registry utilities
+from .manager import ModelManager
+from .registry import get_available_families, get_available_variants, get_model_info
+
+import os
+os.environ['PYTORCH_ENABLE_MPS_FALLBACK'] = '1'
+
+# --- FastAPI App ---
+app = FastAPI(
+    title="Mozo Model Server",
+    description="Dynamic model serving API with lazy loading and lifecycle management.",
+    version="0.2.0"
+)
+
+# --- Model Manager Setup ---
+@app.on_event("startup")
+def setup_manager():
+    """
+    Initialize model manager (no models loaded yet - they load on-demand).
+
+    This is much faster than the old approach which loaded all models at startup.
+    Models will be loaded automatically when first requested.
+    """
+    print("[Server] Initializing model manager...")
+    app.state.model_manager = ModelManager()
+    print("[Server] Model manager ready. Models will be loaded on-demand.")
+
+# --- API Endpoints ---
+@app.get("/", summary="Health Check", description="Check if the API server is ready.")
+def health_check():
+    """
+    Health check endpoint.
+
+    Note: Models are loaded on-demand, so this just checks if the manager is initialized.
+    """
+    manager_ready = hasattr(app.state, "model_manager")
+    if not manager_ready:
+        return {"status": "error", "message": "Server is starting up, model manager not yet initialized."}
+    return {
+        "status": "ok",
+        "message": "Server is running with dynamic model management.",
+        "loaded_models": app.state.model_manager.list_loaded_models()
+    }
+
+
+# --- Test UI ---
+
+@app.get("/test-ui", summary="Test UI", description="Serve interactive testing interface.")
+def serve_test_ui():
+    """
+    Serve the interactive test UI for model testing.
+
+    This provides a user-friendly web interface to:
+    - Upload images
+    - Select models dynamically
+    - View prediction results
+    """
+    html_path = Path(__file__).parent / "static" / "test_ui.html"
+    return FileResponse(html_path, media_type="text/html")
+
+
+@app.get("/static/example.jpg", summary="Example Image", description="Serve example test image.")
+def serve_example_image():
+    """Serve the default example image for testing."""
+    image_path = Path(__file__).parent.parent / "vision" / "example.jpg"
+
+    if not image_path.exists():
+        raise HTTPException(status_code=404, detail="Example image not found at vision/example.jpg")
+
+    return FileResponse(image_path, media_type="image/jpeg")
+
+
+# --- Prediction Endpoints ---
+
+@app.post("/predict/{family}/{variant}",
+          summary="Run Model Prediction",
+          description="Upload an image and get predictions from any available model variant.")
+async def predict(
+    family: str,
+    variant: str,
+    file: UploadFile = File(..., description="Image file to process."),
+    prompt: str = "Describe this image in detail."
+):
+    """
+    Universal prediction endpoint supporting all model families and variants.
+
+    Args:
+        family: Model family (e.g., 'detectron2', 'depth_anything', 'qwen2.5_vl')
+        variant: Model variant (e.g., 'mask_rcnn_R_50_FPN_3x', 'small', '7b-instruct')
+        file: Image file to process
+        prompt: Text prompt for vision-language models (used by qwen2.5_vl)
+
+    Returns:
+        JSON response with predictions (format depends on model type)
+
+    Examples:
+        POST /predict/detectron2/mask_rcnn_R_50_FPN_3x
+        POST /predict/detectron2/faster_rcnn_X_101_32x8d_FPN_3x
+        POST /predict/depth_anything/small
+        POST /predict/depth_anything/large
+        POST /predict/qwen2.5_vl/7b-instruct?prompt=What objects are in this image?
+    """
+    if not hasattr(app.state, "model_manager"):
+        raise HTTPException(status_code=503, detail="Server is starting up, model manager not initialized.")
+
+    # Read and decode image
+    try:
+        contents = await file.read()
+        image = cv2.imdecode(np.frombuffer(contents, np.uint8), cv2.IMREAD_COLOR)
+        if image is None:
+            raise HTTPException(status_code=400, detail="Invalid image file.")
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Could not read or decode the image file: {e}")
+
+    # Get or load model (lazy loading happens here)
+    try:
+        model = app.state.model_manager.get_model(family, variant)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to load model: {e}")
+
+    # Run prediction
+    try:
+        # Vision-language models need prompt parameter
+        if family == 'qwen2.5_vl':
+            results = model.predict(image, prompt=prompt)
+        else:
+            results = model.predict(image)
+
+        # Handle different return types
+        if hasattr(results, 'save'):  # It's a PIL Image (depth map)
+            buffer = io.BytesIO()
+            results.save(buffer, format="PNG")
+            buffer.seek(0)
+            return StreamingResponse(buffer, media_type="image/png")
+
+        elif hasattr(results, 'to_dict'):  # It's a PixelFlow Detections object
+            # PixelFlow's to_dict() now properly serializes numpy arrays to base64/lists
+            return JSONResponse(content=results.to_dict())
+
+        else:  # It's a dict (VLM results)
+            return JSONResponse(content=results)
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Prediction failed: {e}")
+
+
+# --- Model Management Endpoints ---
+
+@app.get("/models",
+         summary="List Available Models",
+         description="Get all available model families and their variants.")
+def list_available_models():
+    """
+    List all available model families and their variants.
+
+    Returns:
+        dict: Available models organized by family, with variant lists and descriptions
+    """
+    families = get_available_families()
+    result = {}
+
+    for family in families:
+        variants = get_available_variants(family)
+        info = get_model_info(family)
+        result[family] = {
+            'task_type': info['task_type'],
+            'description': info['description'],
+            'num_variants': len(variants),
+            'variants': variants
+        }
+
+    return result
+
+
+@app.get("/models/loaded",
+         summary="List Loaded Models",
+         description="Get currently loaded models in memory.")
+def list_loaded_models():
+    """
+    List currently loaded models.
+
+    Returns:
+        dict: Loaded model IDs and their usage information
+    """
+    if not hasattr(app.state, "model_manager"):
+        raise HTTPException(status_code=503, detail="Model manager not initialized.")
+
+    loaded = app.state.model_manager.list_loaded_models()
+    info = app.state.model_manager.get_model_info()
+
+    return {
+        "loaded_count": len(loaded),
+        "models": info
+    }
+
+
+@app.get("/models/{family}/{variant}/info",
+         summary="Get Model Info",
+         description="Get detailed information about a specific model variant.")
+def get_model_details(family: str, variant: str):
+    """
+    Get detailed information about a specific model variant.
+
+    Args:
+        family: Model family name
+        variant: Model variant name
+
+    Returns:
+        dict: Model information including parameters and load status
+    """
+    try:
+        info = get_model_info(family, variant)
+
+        # Add load status
+        if hasattr(app.state, "model_manager"):
+            model_id = f"{family}/{variant}"
+            load_info = app.state.model_manager.get_model_info(model_id)
+            info['load_status'] = load_info
+        else:
+            info['load_status'] = {'loaded': False}
+
+        return info
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+
+@app.post("/models/{family}/{variant}/unload",
+          summary="Unload Model",
+          description="Manually unload a model to free memory.")
+def unload_model(family: str, variant: str):
+    """
+    Manually unload a specific model to free memory.
+
+    Args:
+        family: Model family name
+        variant: Model variant name
+
+    Returns:
+        dict: Unload status
+    """
+    if not hasattr(app.state, "model_manager"):
+        raise HTTPException(status_code=503, detail="Model manager not initialized.")
+
+    success = app.state.model_manager.unload_model(family, variant)
+
+    if success:
+        return {
+            "status": "unloaded",
+            "family": family,
+            "variant": variant,
+            "model_id": f"{family}/{variant}"
+        }
+    else:
+        return {
+            "status": "not_loaded",
+            "family": family,
+            "variant": variant,
+            "message": "Model was not loaded, nothing to unload."
+        }
+
+
+@app.post("/models/cleanup",
+          summary="Cleanup Inactive Models",
+          description="Unload models that haven't been used recently.")
+def cleanup_inactive_models(inactive_seconds: int = 600):
+    """
+    Cleanup models that haven't been used in the specified time period.
+
+    Args:
+        inactive_seconds: Time threshold in seconds (default: 600 = 10 minutes)
+
+    Returns:
+        dict: Cleanup results
+    """
+    if not hasattr(app.state, "model_manager"):
+        raise HTTPException(status_code=503, detail="Model manager not initialized.")
+
+    count = app.state.model_manager.cleanup_inactive_models(inactive_seconds)
+
+    return {
+        "status": "completed",
+        "models_unloaded": count,
+        "inactive_threshold_seconds": inactive_seconds
+    }

mozo-0.2.0.dist-info/METADATA

@@ -0,0 +1,343 @@
+Metadata-Version: 2.4
+Name: mozo
+Version: 0.2.0
+Summary: Universal computer vision model serving library with dynamic model management and PixelFlow integration
+Home-page: https://github.com/datamarkin/mozo
+Author: Emrah NAZIF
+Author-email: Emrah NAZIF <emrah@datamarkin.com>, Datamarkin <support@datamarkin.com>
+License: MIT
+Project-URL: Homepage, https://github.com/datamarkin/mozo
+Project-URL: Bug Tracker, https://github.com/datamarkin/mozo/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: requests
+Requires-Dist: opencv-python
+Requires-Dist: transformers
+Requires-Dist: torch
+Requires-Dist: torchvision
+Requires-Dist: Pillow
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pixelflow
+Requires-Dist: click
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Mozo
+
+Universal computer vision model server with automatic memory management and multi-framework support.
+
+Mozo provides HTTP access to 25+ pre-configured models from Detectron2, HuggingFace Transformers, and other frameworks. Models load on-demand and clean up automatically.
+
+## Quick Start
+
+```bash
+pip install mozo
+mozo start
+```
+
+Server starts on `http://localhost:8000` with all models available via REST API.
+
+### Examples
+
+Object detection:
+```bash
+curl -X POST "http://localhost:8000/predict/detectron2/mask_rcnn_R_50_FPN_3x" \
+  -F "file=@image.jpg"
+```
+
+Depth estimation:
+```bash
+curl -X POST "http://localhost:8000/predict/depth_anything/small" \
+  -F "file=@image.jpg" --output depth.png
+```
+
+Vision-language Q&A:
+```bash
+curl -X POST "http://localhost:8000/predict/qwen2.5_vl/7b-instruct?prompt=What%20is%20in%20this%20image" \
+  -F "file=@image.jpg"
+```
+
+List available models:
+```bash
+curl http://localhost:8000/models
+```
+
+## Features
+
+- **25+ Pre-configured Models** - Detectron2, HuggingFace Transformers, custom adapters
+- **Automatic Memory Management** - Lazy loading, usage tracking, automatic cleanup
+- **Multi-Framework Support** - Unified API across different ML frameworks
+- **PixelFlow Integration** - Detection models return unified format for filtering and annotation
+- **Thread-Safe** - Concurrent request handling with per-model locks
+- **Production Ready** - Multiple workers, configurable timeouts, health checks
+
+## Installation
+
+```bash
+# Basic installation
+pip install mozo
+
+# Framework dependencies (install as needed)
+pip install transformers torch torchvision
+pip install 'git+https://github.com/facebookresearch/detectron2.git'
+```
+
+## Available Models
+
+### Detectron2 (22 variants)
+Object detection, instance segmentation, keypoint detection trained on COCO dataset.
+
+Popular variants:
+- `mask_rcnn_R_50_FPN_3x` - Instance segmentation
+- `faster_rcnn_R_50_FPN_3x` - Object detection
+- `faster_rcnn_X_101_32x8d_FPN_3x` - High-accuracy detection
+- `keypoint_rcnn_R_50_FPN_3x` - Keypoint detection
+- `retinanet_R_50_FPN_3x` - Single-stage detector
+
+Output: JSON with bounding boxes, class names, confidence scores (80 COCO classes)
+
+### Depth Anything (3 variants)
+Monocular depth estimation.
+
+- `small` - Fastest, lowest memory
+- `base` - Balanced performance
+- `large` - Best accuracy
+
+Output: PNG grayscale depth map
+
+### Qwen2.5-VL (1 variant)
+Vision-language understanding for VQA, captioning, and image analysis.
+
+- `7b-instruct` - 7B parameter model (requires 16GB+ RAM)
+
+Output: JSON with text response
+
+## Server
+
+```bash
+# Start with defaults (0.0.0.0:8000, auto-reload enabled)
+mozo start
+
+# Custom port
+mozo start --port 8080
+
+# Production mode with multiple workers
+mozo start --workers 4
+
+# Check version
+mozo version
+```
+
+## API Reference
+
+### Run Prediction
+```http
+POST /predict/{family}/{variant}
+Content-Type: multipart/form-data
+```
+
+Parameters:
+- `family` - Model family (e.g., `detectron2`, `depth_anything`, `qwen2.5_vl`)
+- `variant` - Model variant (e.g., `mask_rcnn_R_50_FPN_3x`, `small`, `7b-instruct`)
+- `file` - Image file
+- `prompt` - Text prompt (VLM models only)
+
+### Health Check
+```http
+GET /
+```
+
+Returns server status and loaded models.
+
+### List Models
+```http
+GET /models
+```
+
+Returns all available model families and variants.
+
+### List Loaded Models
+```http
+GET /models/loaded
+```
+
+Returns currently loaded models with usage information.
+
+### Get Model Info
+```http
+GET /models/{family}/{variant}/info
+```
+
+Returns detailed information about a specific model variant.
+
+### Unload Model
+```http
+POST /models/{family}/{variant}/unload
+```
+
+Manually unload a model to free memory.
+
+### Cleanup Inactive Models
+```http
+POST /models/cleanup?inactive_seconds=600
+```
+
+Unload models inactive for specified duration (default: 600 seconds).
+
+## How It Works
+
+**Lazy Loading**
+Models load on first request, not at server startup. This keeps startup time instant regardless of available models.
+
+**Smart Caching**
+Loaded models stay in memory and are reused across requests. First request is slower (model download + load), subsequent requests are fast.
+
+**Usage Tracking**
+Each model access updates a timestamp. Models inactive for 10+ minutes are automatically unloaded.
+
+**Thread Safety**
+Per-model locks ensure only one thread loads a given model. Other threads wait and reuse the loaded instance.
+
+Example flow:
+```bash
+# Server starts instantly (no models loaded)
+mozo start
+
+# First request loads model
+curl -X POST "http://localhost:8000/predict/detectron2/faster_rcnn_R_50_FPN_3x" -F "file=@test.jpg"
+# Output: [ModelManager] Loading model: detectron2/faster_rcnn_R_50_FPN_3x...
+
+# Subsequent requests reuse loaded model
+curl -X POST "http://localhost:8000/predict/detectron2/faster_rcnn_R_50_FPN_3x" -F "file=@test2.jpg"
+# Output: [ModelManager] Model already loaded, reusing existing instance.
+
+# After 10 minutes of inactivity, model auto-unloads
+# Output: [ModelManager] Cleanup: Unloaded 1 inactive model(s).
+```
+
+## Python SDK
+
+For direct integration in Python applications:
+
+```python
+from mozo import ModelManager
+import cv2
+
+manager = ModelManager()
+model = manager.get_model('detectron2', 'mask_rcnn_R_50_FPN_3x')
+
+image = cv2.imread('image.jpg')
+detections = model.predict(image)
+
+# Filter results
+high_confidence = detections.filter_by_confidence(0.8)
+
+# Manual memory management
+manager.unload_model('detectron2', 'mask_rcnn_R_50_FPN_3x')
+manager.cleanup_inactive_models(inactive_seconds=300)
+```
+
+### PixelFlow Integration
+
+Detection models return PixelFlow Detections objects - a unified format across all ML frameworks:
+
+```python
+# Works the same for Detectron2, YOLO, or custom models
+detections = model.predict(image)
+
+# Filter and annotate
+import pixelflow as pf
+filtered = detections.filter_by_confidence(0.8).filter_by_class_id([0, 2])
+annotated = pf.annotate.box(image, filtered)
+annotated = pf.annotate.label(annotated, filtered)
+
+# Export
+json_output = filtered.to_json()
+```
+
+Learn more: [PixelFlow](https://github.com/datamarkin/pixelflow)
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Enable MPS fallback for macOS (Apple Silicon)
+export PYTORCH_ENABLE_MPS_FALLBACK=1
+
+# Configure HuggingFace cache location
+export HF_HOME=~/.cache/huggingface
+```
+
+### Memory Management
+
+Models automatically unload after 10 minutes of inactivity. Adjust this:
+
+```bash
+curl -X POST "http://localhost:8000/models/cleanup?inactive_seconds=300"
+```
+
+Or in Python:
+```python
+manager.cleanup_inactive_models(inactive_seconds=300)
+```
+
+## Extending Mozo
+
+Add new models in 3 steps:
+
+1. Create adapter in `mozo/adapters/your_model.py`
+2. Register in `mozo/registry.py`
+3. Use via HTTP or Python API
+
+See [CLAUDE.md](CLAUDE.md) for detailed implementation guide.
+
+## Architecture
+
+```
+HTTP Request → FastAPI Server → ModelManager → ModelFactory → Adapter → Framework
+                                      ↓
+                               Thread-safe cache
+                               Usage tracking
+                               Auto cleanup
+```
+
+Components:
+- **Server** - FastAPI REST API
+- **Manager** - Lifecycle management, caching, cleanup
+- **Factory** - Dynamic adapter instantiation
+- **Registry** - Central catalog of models
+- **Adapters** - Framework-specific implementations
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Start server with auto-reload
+mozo start
+```
+
+## Documentation
+
+- [Repository](https://github.com/datamarkin/mozo)
+- [Issues](https://github.com/datamarkin/mozo/issues)
+
+## License
+
+MIT License

mozo-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+mozo/__init__.py,sha256=g5eQJP-xx0SvxMd0uQ1HAI4b4KRCmeo2P31rDc-5YjE,1490
+mozo/__main__.py,sha256=aGVemo--o10oQnIqOW2-tsUR0KGyMzvrJgz3aBzdDos,460
+mozo/cli.py,sha256=nymMNcCdTVvNoQJSy8YoHRexCEdcxpmhHeR4YuzAAuc,1211
+mozo/factory.py,sha256=HB9OG2shfo6Gxn6Odc9ZiBKWuiYJlUhBNwfHbtN6heA,4826
+mozo/manager.py,sha256=NPID5QxieAeL8zAWorlvk2QXWiSNYmJmHWRHDRGd0hs,9681
+mozo/registry.py,sha256=RKU4LPyNgivS13PAwxJTSa9zit4v7dxMIFUO2xioErk,7744
+mozo/server.py,sha256=RkFfbGBquqplBABY8b7oIiybXfdv-naamKQKdwzq7sQ,9712
+mozo/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mozo/adapters/depth_anything.py,sha256=SsmNrU5d2t0KukbSn8PMDliyaya8AUo6xHoMsjvw4k4,2632
+mozo/adapters/detectron2.py,sha256=zUH3VxwMKQ-3L6SBMeDckojpc5mvaymkSDpkQktqe00,5798
+mozo/adapters/qwen2_5_vl.py,sha256=8UK_pXfdbprw-OHbDT8gFdfUMEeRG3rC_obXlHlZo00,5801
+mozo-0.2.0.dist-info/licenses/LICENSE,sha256=QsFuCag5g1YSVKk3WUlv4Nc6TaQwNjyO53Rl0N60CB0,1067
+mozo-0.2.0.dist-info/METADATA,sha256=dGHns-S0LzSZ-x0vlAvmw06zrWn9v8MKfUJ265rFgb4,8861
+mozo-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mozo-0.2.0.dist-info/entry_points.txt,sha256=4KCJ-IL4STq1ib_M5Ny9Yd0dJ9QSUayoY5Cc2XSDU6w,38
+mozo-0.2.0.dist-info/top_level.txt,sha256=tvn0MKjQnyc1gIlKPjBmrhF3xVUXuM0TGUrdsv2XHgI,5
+mozo-0.2.0.dist-info/RECORD,,

mozo-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mozo = mozo.cli:cli

{mozo-0.1.0.dist-info → mozo-0.2.0.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025
+Copyright (c) 2025 Datamarkin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.