amv-vision 2.0.0__py3-none-any.whl

amv_vision/__init__.py

@@ -0,0 +1,75 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""
+amv-vision: Lightweight On-Device Computer Vision & VLM Framework for Android Termux.
+Open-Source under Apache License 2.0.
+"""
+
+__version__ = "2.0.0"
+__author__ = "amv-vision contributors"
+__license__ = "Apache-2.0"
+
+from . import errors
+from . import io
+from . import transforms
+from . import cv
+from . import detect
+from . import models
+from . import bridge
+from . import csrc
+from . import vlm
+from . import cli
+
+from .detect.types import BoundingBox, Detection
+from .detect.haar import detect_faces
+from .models.embedding import Embedding, compute_similarity
+from .vlm.api import load
+from .hardware import HardwareProfile, detect_hardware, resolve_device
+from .downloader import list_models, download_model, resolve_model_path
+from . import cluster
+from .exceptions import (
+    AmevaTermuxError,
+    TermuxVisionError,
+    ClusterConnectionError,
+    ClusterConfigurationError,
+)
+from .cluster import (
+    parse_cluster_rpc_spec,
+    verify_rpc_cluster_nodes,
+    verify_rpc_cluster_health,
+)
+
+__all__ = [
+    "io",
+    "transforms",
+    "cv",
+    "detect",
+    "models",
+    "bridge",
+    "csrc",
+    "vlm",
+    "cluster",
+    "errors",
+    "cli",
+    "BoundingBox",
+    "Detection",
+    "detect_faces",
+    "Embedding",
+    "compute_similarity",
+    "load",
+    "HardwareProfile",
+    "detect_hardware",
+    "resolve_device",
+    "list_models",
+    "download_model",
+    "resolve_model_path",
+    "AmevaTermuxError",
+    "TermuxVisionError",
+    "ClusterConnectionError",
+    "ClusterConfigurationError",
+    "parse_cluster_rpc_spec",
+    "verify_rpc_cluster_nodes",
+    "verify_rpc_cluster_health",
+    "__version__"
+]
+

amv_vision/__main__.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+import sys
+from amv_vision.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

amv_vision/adapter.py

@@ -0,0 +1,201 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""
+amv_vision.adapter
+======================
+AMEVA Component Protocol v1 — Orchestrator Adapter (v0.8.1 호환)
+
+P0-2: infer() fallback yield _not_supported → raise OperationNotSupported
+P0-4: except Exception → retryable 분류, 원본 오류 코드 보존
+"""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator
+
+from ameva_component.adapter_base import BaseOrchestratorAdapter
+from ameva_component.exceptions import (
+    ComponentError,
+    OperationNotSupported,
+    redact_details,
+    redact_text,
+)
+from amv_vision.control.component import VisionControl
+
+
+class VisionOrchestratorAdapter(BaseOrchestratorAdapter):
+    """Vision Orchestrator Adapter.
+
+    이미지 분석 / VLM captioning은 파일 기반으로 수행됩니다.
+    infer(): image_path를 받아 분석 결과를 반환합니다.
+    Native backend 실패 시 fallback_used=True를 명시합니다.
+    """
+
+    COMPONENT_ID = "amv-vision"
+
+    _RETRYABLE_CODES: frozenset[str] = frozenset({
+        "REMOTE_TIMEOUT",
+        "MODEL_BUSY",
+        "BACKEND_OVERLOADED",
+    })
+    _NON_RETRYABLE_CODES: frozenset[str] = frozenset({
+        "IMAGE_PATH_FORBIDDEN",
+        "IMAGE_FORMAT_UNSUPPORTED",
+        "IMAGE_CORRUPT",
+        "MODEL_NOT_FOUND",
+        "HASH_MISMATCH",
+    })
+
+    def __init__(self, control: VisionControl | None = None) -> None:
+        self._control = control or VisionControl()
+
+    async def infer(self, request: dict[str, Any]) -> AsyncIterator[dict[str, Any]]:
+        """Vision inference: image_path → analysis result.
+
+        request 키:
+            image_path (str): 분석할 이미지 파일 경로 (필수)
+            task (str): "caption" | "vlm" | "detect" (선택, 기본: "caption")
+            prompt (str): VLM 프롬프트 (task="vlm"일 때)
+            model_id (str): 모델 ID (선택)
+
+        반환 프레임:
+            {"type": "vision_result", "task": str, "result": dict, ...}
+            {"type": "error", "ok": False, "error": {...}}
+        """
+        image_path = request.get("image_path", "").strip()
+        if not image_path:
+            yield {
+                "type": "error",
+                "ok": False,
+                "error": {
+                    "code": "IMAGE_PATH_MISSING",
+                    "message": "image_path is required for Vision infer",
+                    "operation": "infer",
+                    "component_id": self.COMPONENT_ID,
+                    "retryable": False,
+                },
+            }
+            return
+
+        if not hasattr(self._control, "analyze"):
+            # P0-2: fallback yield → raise
+            raise OperationNotSupported(operation="infer.analyze", component_id=self.COMPONENT_ID)
+
+        try:
+            result = await self._control.analyze(request)
+
+            if not isinstance(result, dict):
+                raise ValueError(f"analyze() must return dict, got {type(result).__name__}")
+
+            if result.get("ok") is not True:
+                err_payload = result.get("error") if isinstance(result.get("error"), dict) else {}
+                yield {
+                    "type": "error",
+                    "ok": False,
+                    "error": {
+                        "code": err_payload.get("code", "ADAPTER_RESULT_NOT_SUCCESS"),
+                        "message": err_payload.get("message", "analyze() did not return ok=True"),
+                        "operation": "infer",
+                        "component_id": self.COMPONENT_ID,
+                        "retryable": False,
+                        "details": {"result_keys": sorted(result.keys())},
+                    },
+                }
+                return
+
+            if "result" not in result:
+                raise ValueError("analyze() result missing required field 'result'")
+
+            yield {
+                "type": "vision_result",
+                "task": request.get("task", "caption"),
+                "result": result["result"],
+                "fallback_used": result.get("fallback_used", False),
+                "requested_backend": result.get("requested_backend"),
+                "executed_backend": result.get("executed_backend"),
+                "ok": True,
+            }
+
+        except ComponentError as component_err:
+            # HIGH 1: ComponentError public_message와 redact_details로 외부 노출 보안 격리
+            import logging
+            logging.getLogger(__name__).exception(
+                "Vision component operation failed",
+                extra={
+                    "component_id": self.COMPONENT_ID,
+                    "operation": "infer",
+                    "code": getattr(component_err, "code", "COMPONENT_ERROR"),
+                },
+            )
+            if hasattr(component_err, "to_public_dict"):
+                err_dict = component_err.to_public_dict()
+            else:
+                err_dict = {
+                    "code": getattr(component_err, "code", "COMPONENT_ERROR"),
+                    "message": redact_text(getattr(component_err, "public_message", "Component operation failed")),
+                    "retryable": getattr(component_err, "retryable", False),
+                    "details": redact_details(getattr(component_err, "details", {})),
+                }
+            yield {
+                "type": "error",
+                "ok": False,
+                "error": {
+                    **err_dict,
+                    "operation": "infer",
+                    "component_id": self.COMPONENT_ID,
+                    "retryable": self._classify_retryable(
+                        err_dict.get("code", ""), default=err_dict.get("retryable", False)
+                    ),
+                },
+            }
+
+        except (ValueError, TypeError) as contract_err:
+            # P0-3/4 & HIGH 1: 계약 위반 (str(contract_err) 직접 노출 금지, 내부 로그 격리)
+            import logging
+            logging.getLogger(__name__).exception("Vision contract validation error during infer: %s", contract_err)
+            yield {
+                "type": "error",
+                "ok": False,
+                "error": {
+                    "code": "ADAPTER_CONTRACT_ERROR",
+                    "message": "Adapter contract validation failed",
+                    "operation": "infer",
+                    "component_id": self.COMPONENT_ID,
+                    "retryable": False,
+                    "details": {
+                        "cause_type": type(contract_err).__name__,
+                        "operation": "infer",
+                    },
+                },
+            }
+
+        except Exception as unexpected_err:
+            import logging
+            logging.getLogger(__name__).exception("Vision adapter unexpected error during infer: %s", unexpected_err)
+            code = getattr(unexpected_err, "code", "ADAPTER_INTERNAL_ERROR")
+            yield {
+                "type": "error",
+                "ok": False,
+                "error": {
+                    "code": code if isinstance(code, str) else "ADAPTER_INTERNAL_ERROR",
+                    "message": "Unexpected adapter failure",
+                    "operation": "infer",
+                    "component_id": self.COMPONENT_ID,
+                    "retryable": False,
+                    "details": {
+                        "cause_type": type(unexpected_err).__name__,
+                        "operation": "infer",
+                    },
+                },
+            }
+
+    def _classify_retryable(self, code: str, *, default: bool = False) -> bool:
+        if code in self._RETRYABLE_CODES:
+            return True
+        if code in self._NON_RETRYABLE_CODES:
+            return False
+        return default
+
+
+def create_adapter() -> VisionOrchestratorAdapter:
+    """Entry Point Factory."""
+    return VisionOrchestratorAdapter()

amv_vision/bridge/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+from .amv_train_bridge import (
+    to_termux_tensor,
+    from_termux_tensor,
+    VisionPatchDataset
+)
+
+__all__ = [
+    "to_termux_tensor",
+    "from_termux_tensor",
+    "VisionPatchDataset"
+]

amv_vision/bridge/amv_train_bridge.py

@@ -0,0 +1,87 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+import numpy as np
+
+def to_termux_tensor(data, requires_grad: bool = False):
+    """
+    Convert a NumPy image array or patch matrix to amv_train.Tensor.
+    Gracefully imports amv_train or creates equivalent autograd structure.
+    """
+    try:
+        import amv_train as tt
+        if isinstance(data, np.ndarray):
+            # Direct flat C-buffer pass without .tolist() to eliminate 8x memory expansion and LMK kills
+            return tt.Tensor(data, dtype="float32", requires_grad=requires_grad)
+        elif isinstance(data, (list, tuple)):
+            return tt.Tensor(data, dtype="float32", requires_grad=requires_grad)
+        elif hasattr(data, "to_numpy"):
+            return tt.Tensor(data.to_numpy(), dtype="float32", requires_grad=requires_grad)
+        else:
+            return tt.Tensor(data, dtype="float32", requires_grad=requires_grad)
+    except ImportError:
+        # Fallback if amv-train is not installed in current environment
+        class StandaloneVisionTensor:
+            def __init__(self, arr, requires_grad=False):
+                self.data = np.array(arr, dtype=np.float32)
+                self.shape = self.data.shape
+                self.requires_grad = requires_grad
+                self.grad = None
+            def to_numpy(self):
+                return self.data
+            def __repr__(self):
+                return f"StandaloneVisionTensor(shape={self.shape}, dtype={self.data.dtype})"
+        return StandaloneVisionTensor(data, requires_grad=requires_grad)
+
+def from_termux_tensor(tensor) -> np.ndarray:
+    """
+    Convert a amv_train.Tensor or StandaloneVisionTensor back to NumPy array.
+    """
+    if hasattr(tensor, "to_numpy"):
+        return np.asarray(tensor.to_numpy(), dtype=np.float32)
+    elif hasattr(tensor, "numpy"):
+        return np.asarray(tensor.numpy(), dtype=np.float32)
+    elif hasattr(tensor, "tolist"):
+        return np.asarray(tensor.tolist(), dtype=np.float32)
+    elif hasattr(tensor, "_data"):
+        if hasattr(tensor._data, "to_list"):
+            return np.asarray(tensor._data.to_list(), dtype=np.float32)
+        return np.asarray(tensor._data, dtype=np.float32)
+    elif hasattr(tensor, "data"):
+        if isinstance(tensor.data, np.ndarray):
+            return np.asarray(tensor.data, dtype=np.float32)
+        return np.asarray(tensor.data, dtype=np.float32)
+    elif isinstance(tensor, np.ndarray):
+        return np.asarray(tensor, dtype=np.float32)
+    else:
+        return np.asarray(tensor, dtype=np.float32)
+
+class VisionPatchDataset:
+    """
+    On-Device Dataset for batching image patches for ViT or classifier training.
+    """
+    def __init__(self, patches: np.ndarray, labels: np.ndarray = None, batch_size: int = 32, shuffle: bool = True):
+        self.patches = np.asarray(patches, dtype=np.float32)
+        self.labels = np.asarray(labels, dtype=np.float32) if labels is not None else None
+        self.batch_size = batch_size
+        self.shuffle = shuffle
+        self.num_samples = len(self.patches)
+
+    def __len__(self):
+        return (self.num_samples + self.batch_size - 1) // self.batch_size
+
+    def __iter__(self):
+        indices = np.arange(self.num_samples)
+        if self.shuffle:
+            np.random.shuffle(indices)
+
+        for i in range(0, self.num_samples, self.batch_size):
+            batch_idx = indices[i:i + self.batch_size]
+            batch_x = self.patches[batch_idx]
+            batch_tensor_x = to_termux_tensor(batch_x)
+            
+            if self.labels is not None:
+                batch_y = self.labels[batch_idx]
+                batch_tensor_y = to_termux_tensor(batch_y)
+                yield batch_tensor_x, batch_tensor_y
+            else:
+                yield batch_tensor_x

amv_vision/cli/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+from .main import main
+
+__all__ = ["main"]

amv_vision/cli/doctor.py

@@ -0,0 +1,122 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+import os
+import sys
+import shutil
+import platform
+import subprocess
+import json
+import time
+from typing import Dict, Any, Optional
+from .. import __version__
+from .. import csrc
+from ..vlm.cache import ModelCacheManager
+from amv_vision.exceptions import RuntimeRequiredError
+
+def run_doctor(probe_vulkan: bool = False, full_check: bool = False) -> Dict[str, Any]:
+    """
+    Runs truthful diagnostic inspection of the Android Termux runtime environment.
+    - Default: Read-only environment inspection.
+    - probe_vulkan: Checks driver presence and reports execution capability (Zero-Hype / Ground Truth).
+    - full_check: Runs actual SHA-256 and byte-level integrity verification on installed models.
+    """
+    cache_mgr = ModelCacheManager()
+
+    report = {
+        "schema_version": 1,
+        "client_version": __version__,
+        "runtime_version": __version__,
+        "platform": {
+            "system": platform.system(),
+            "machine": platform.machine(),
+            "python_version": platform.python_version(),
+            "is_android": os.path.exists("/system/build.prop") or "ANDROID_ROOT" in os.environ
+        },
+        "hardware": {
+            "cpu_cores": os.cpu_count() or 1,
+            "total_ram_mb": None,
+            "available_ram_mb": None
+        },
+        "vulkan": {
+            "driver_dir": None,
+            "vulkan_loader_installed": shutil.which("vulkaninfo") is not None,
+            "loader_detected": shutil.which("vulkaninfo") is not None,
+            "driver_file_detected": False,
+            "compute_probe_executed": probe_vulkan,
+            "safe_for_vlm": None,
+            "status": "unverified"
+        },
+        "vlm_runtime": {
+            "llama_cli_available": shutil.which("llama-cli") is not None,
+            "multimodal_capable": False,
+            "multimodal_status": "unverified",
+            "installed_models_count": 0,
+            "cache_dir": cache_mgr.cache_root
+        },
+        "native_backends": {
+            "has_c_backend": csrc.has_c_backend(),
+            "has_vulkan_backend": csrc.has_vulkan_backend(),
+            "vulkan_device_name": csrc.get_vulkan_device_name(),
+            "c_backend_errors": csrc.get_c_backend_load_errors(),
+            "cpp_backend_errors": csrc.get_cpp_backend_load_errors()
+        },
+        "recommended_preset": "Tier M (smolvlm-500m / 4-Threads CPU Reference)",
+        "warnings": []
+    }
+
+    # Verify multimodal capability via installer gatekeeper
+    try:
+        from ..installer import verify_multimodal_support
+        mm_ok, mm_msg = verify_multimodal_support()
+        report["vlm_runtime"]["multimodal_capable"] = mm_ok
+        report["vlm_runtime"]["multimodal_status"] = mm_msg
+        if not mm_ok and report["vlm_runtime"]["llama_cli_available"]:
+            report["warnings"].append(f"llama-cli detected but lacks multimodal support: {mm_msg}")
+    except RuntimeRequiredError:
+        raise
+    except Exception as _mm_err:
+        report["vlm_runtime"]["multimodal_status"] = f"Check failed: {_mm_err}"
+
+    # RAM Inspection
+    try:
+        with open("/proc/meminfo", "r") as f:
+            for line in f:
+                if line.startswith("MemTotal:"):
+                    report["hardware"]["total_ram_mb"] = int(line.split()[1]) // 1024
+                elif line.startswith("MemAvailable:"):
+                    report["hardware"]["available_ram_mb"] = int(line.split()[1]) // 1024
+    except (OSError, ValueError, IndexError) as _mem_err:
+        report["warnings"].append(f"RAM inspection failed: {_mem_err}")
+
+    # Truthful Vulkan status via ameva-runtime integration
+    if probe_vulkan:
+        try:
+            from ameva_runtime.vulkan.adapters import find_system_vulkan_driver_dir
+            from ameva_runtime import vulkan as avr
+            driver_dir = find_system_vulkan_driver_dir()
+            is_avail = bool(driver_dir is not None)
+            report["vulkan"]["driver_dir"] = driver_dir
+            report["vulkan"]["driver_file_detected"] = is_avail
+            report["vulkan"]["loader_detected"] = bool(is_avail or report["vulkan"]["vulkan_loader_installed"])
+            report["vulkan"]["ameva_runtime_detected"] = True
+            report["vulkan"]["status"] = "driver_detected_experimental" if is_avail else "disabled"
+            dev_name = avr.get_device_name() if hasattr(avr, "get_device_name") and callable(avr.get_device_name) else "Vulkan GPU"
+            report["vulkan"]["device_name"] = dev_name
+            report["vulkan"]["note"] = "Hardware driver dynamically discovered via ameva-runtime."
+        except ImportError:
+            report["vulkan"]["ameva_runtime_detected"] = False
+            report["vulkan"]["status"] = "disabled"
+            report["vulkan"]["safe_for_vlm"] = False
+            report["vulkan"]["note"] = "Install ameva-runtime for optimized GPU compute shaders."
+
+    # Model count and Actual Full SHA-256 check
+    installed = cache_mgr.list_installed()
+    report["vlm_runtime"]["installed_models_count"] = len(installed)
+
+    if full_check:
+        report["vlm_runtime"]["models_integrity"] = {}
+        for m in installed:
+            mid = m["model_id"]
+            report["vlm_runtime"]["models_integrity"][mid] = cache_mgr.verify_integrity(mid)
+
+    return report