visionservex 0.3.0__py3-none-any.whl

visionservex/__init__.py

@@ -0,0 +1,29 @@
+"""VisionServeX: serve permissive-license computer vision models locally and over Cloudflare Tunnel."""
+
+from __future__ import annotations
+
+__version__ = "0.3.0"
+__author__ = "Arash Sajjadi"
+__email__ = "arash.sajjadi@usask.ca"
+__license__ = "Apache-2.0"
+
+from visionservex.core.model import VisionModel
+from visionservex.core.results import (
+    ClassificationResult,
+    DetectionResult,
+    OpenVocabularyResult,
+    OrientedDetectionResult,
+    PoseResult,
+    SegmentationResult,
+)
+
+__all__ = [
+    "VisionModel",
+    "DetectionResult",
+    "SegmentationResult",
+    "PoseResult",
+    "ClassificationResult",
+    "OrientedDetectionResult",
+    "OpenVocabularyResult",
+    "__version__",
+]

visionservex/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point so ``python -m visionservex`` works."""
+
+from visionservex.cli.main import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

visionservex/api/__init__.py

@@ -0,0 +1,24 @@
+"""HTTP API response/error schemas."""
+
+from visionservex.api.errors import ApiError, ErrorBody
+from visionservex.api.schemas import (
+    HealthResponse,
+    ModelListItem,
+    ModelListResponse,
+    PredictionResponse,
+    PromptRequest,
+    UrlInput,
+    VersionResponse,
+)
+
+__all__ = [
+    "ApiError",
+    "ErrorBody",
+    "HealthResponse",
+    "ModelListItem",
+    "ModelListResponse",
+    "PredictionResponse",
+    "PromptRequest",
+    "UrlInput",
+    "VersionResponse",
+]

visionservex/api/errors.py

@@ -0,0 +1,87 @@
+"""Stable API error envelope."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException, status
+from pydantic import BaseModel, Field
+
+
+class ErrorBody(BaseModel):
+    code: str
+    message: str
+    hint: str = ""
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class ApiError(HTTPException):
+    """HTTPException subclass that produces a stable error envelope.
+
+    Endpoints raise this; the server's exception handler renders it as
+    ``{"request_id": ..., "error": {...}}``.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        *,
+        hint: str = "",
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(status_code=status_code, detail=message)
+        self.error_code = code
+        self.error_message = message
+        self.error_hint = hint
+        self.error_details = details or {}
+
+
+# Common helpers
+def not_found(code: str, message: str, *, hint: str = "") -> ApiError:
+    return ApiError(status.HTTP_404_NOT_FOUND, code, message, hint=hint)
+
+
+def bad_request(code: str, message: str, *, hint: str = "") -> ApiError:
+    return ApiError(status.HTTP_400_BAD_REQUEST, code, message, hint=hint)
+
+
+def unauthorized(message: str = "authentication required", *, hint: str = "") -> ApiError:
+    return ApiError(
+        status.HTTP_401_UNAUTHORIZED,
+        "UNAUTHENTICATED",
+        message,
+        hint=hint or "send Authorization: Bearer <api-key>",
+    )
+
+
+def forbidden(message: str, *, hint: str = "") -> ApiError:
+    return ApiError(status.HTTP_403_FORBIDDEN, "FORBIDDEN", message, hint=hint)
+
+
+def too_large(message: str, *, hint: str = "") -> ApiError:
+    return ApiError(status.HTTP_413_REQUEST_ENTITY_TOO_LARGE, "REQUEST_TOO_LARGE", message, hint=hint)
+
+
+def unprocessable(code: str, message: str, *, hint: str = "") -> ApiError:
+    # 422; avoid touching the legacy ``HTTP_422_UNPROCESSABLE_ENTITY`` name
+    # unconditionally to suppress a Starlette deprecation warning.
+    return ApiError(422, code, message, hint=hint)
+
+
+def busy(message: str, *, hint: str = "") -> ApiError:
+    return ApiError(status.HTTP_503_SERVICE_UNAVAILABLE, "BUSY", message, hint=hint)
+
+
+__all__ = [
+    "ErrorBody",
+    "ApiError",
+    "not_found",
+    "bad_request",
+    "unauthorized",
+    "forbidden",
+    "too_large",
+    "unprocessable",
+    "busy",
+]

visionservex/api/schemas.py

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Arash Sajjadi
+"""Pydantic schemas for HTTP request and response bodies."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class HealthResponse(BaseModel):
+    status: str = "ok"
+    version: str
+    public_mode: bool
+    auth_enabled: bool
+
+
+class VersionResponse(BaseModel):
+    version: str
+    python: str
+    platform: str
+    author: str = "Arash Sajjadi"
+
+
+class ModelListItem(BaseModel):
+    id: str
+    display_name: str
+    task: str
+    family: str
+    license: str
+    status: str
+    implementation_status: str
+    engine: str
+    backend: str
+    difficulty: str
+    auto_download: bool
+    supported_devices: list[str]
+    minimum_vram_gb: float | None = None
+    recommended_vram_gb: float | None = None
+    warnings: list[str] = Field(default_factory=list)
+
+
+class ModelListResponse(BaseModel):
+    models: list[ModelListItem]
+
+
+class PromptRequest(BaseModel):
+    """JSON body for endpoints that accept prompts and a base64 image."""
+
+    image_b64: str | None = Field(
+        default=None,
+        description="Base64-encoded image bytes. Mutually exclusive with `image_url`.",
+    )
+    image_url: str | None = Field(
+        default=None,
+        description="HTTPS URL of an image. Requires inputs.allow_url_inputs=true.",
+    )
+    prompts: list[str] = Field(default_factory=list)
+    model_id: str
+    options: dict[str, Any] = Field(default_factory=dict)
+
+
+class UrlInput(BaseModel):
+    image_url: str
+    model_id: str
+    options: dict[str, Any] = Field(default_factory=dict)
+
+
+class PredictionResponse(BaseModel):
+    """Stable wire format for every prediction endpoint."""
+
+    model_config = ConfigDict(extra="forbid", protected_namespaces=())
+
+    request_id: str
+    status: Literal["completed", "downloading", "queued", "failed"] = "completed"
+    model_id: str
+    task: str
+    backend: str = ""
+    device: str
+    precision: str = "fp32"
+    latency_ms: float
+    model_loaded_from: str | None = None
+    cache_path: str | None = None
+    fallback_reason: str | None = None
+    results: list[dict[str, Any]] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class JobProgress(BaseModel):
+    downloaded_bytes: int = 0
+    total_bytes: int | None = None
+    percent: float = 0.0
+    speed_bytes_per_sec: int = 0
+
+
+class JobResponse(BaseModel):
+    model_config = ConfigDict(protected_namespaces=())
+    request_id: str | None = None
+    job_id: str
+    kind: str
+    model_id: str
+    status: str
+    message: str = ""
+    progress: dict[str, Any] = Field(default_factory=dict)
+    result: Any | None = None
+    error: dict[str, Any] | None = None
+    created_at: float
+    updated_at: float
+
+
+class DownloadingResponse(BaseModel):
+    """Returned when an auto-pull starts and the client opted out of waiting."""
+
+    model_config = ConfigDict(protected_namespaces=())
+    request_id: str
+    status: Literal["downloading"] = "downloading"
+    model_id: str
+    job_id: str
+    message: str
+    progress_url: str
+
+
+__all__ = [
+    "HealthResponse",
+    "VersionResponse",
+    "ModelListItem",
+    "ModelListResponse",
+    "PromptRequest",
+    "UrlInput",
+    "PredictionResponse",
+    "JobProgress",
+    "JobResponse",
+    "DownloadingResponse",
+]

visionservex/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface."""
+
+from visionservex.cli.main import app
+
+__all__ = ["app"]