visionservex 0.3.0__tar.gz

visionservex-0.3.0/.gitignore

@@ -0,0 +1,118 @@
+# =============================================================
+# Python
+# =============================================================
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*$py.class
+*.so
+
+# Packaging / build
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+MANIFEST
+pip-wheel-metadata/
+.installed.cfg
+
+# =============================================================
+# Virtual environments
+# =============================================================
+.venv/
+venv/
+env/
+ENV/
+.virtualenv/
+
+# =============================================================
+# Test & coverage
+# =============================================================
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+coverage.xml
+*.cover
+junit*.xml
+
+# =============================================================
+# Type checking & linting caches
+# =============================================================
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+
+# =============================================================
+# IDE
+# =============================================================
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# =============================================================
+# Logs
+# =============================================================
+*.log
+logs/
+
+# =============================================================
+# Model weight files — never commit model weights to git.
+# Download via `visionservex pull <model_id>` instead.
+# =============================================================
+*.pth
+*.pt
+*.bin
+*.ckpt
+*.safetensors
+*.onnx
+*.trt
+*.engine
+*.pkl
+
+# =============================================================
+# Model cache directories
+# =============================================================
+.cache/
+models_cache/
+.visionservex/
+model_weights/
+weights/
+checkpoints/
+
+# =============================================================
+# Inference outputs — generated at runtime
+# =============================================================
+outputs/
+
+# =============================================================
+# Secrets — never commit
+# =============================================================
+.env
+.env.local
+.env.*.local
+
+# =============================================================
+# OS
+# =============================================================
+.DS_Store
+.DS_Store?
+._*
+Thumbs.db
+ehthumbs.db
+desktop.ini
+
+# =============================================================
+# Cloudflare Tunnel credentials & generated configs
+# =============================================================
+cert.pem
+*.pem
+# cloudflared credential files (UUID-named)
+[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-*.json
+tunnel*.yaml

visionservex-0.3.0/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-05-15
+
+### Added (Pass 3 through Pass 7)
+- **RF-DETR real backend** (detection + segmentation) via the `rfdetr` PyPI
+  package. Model IDs: `rfdetr-nano`, `rfdetr-small`, `rfdetr-base`,
+  `rfdetr-medium`, `rfdetr-large`, `rfdetr-seg-nano`, `rfdetr-seg-small`,
+  `rfdetr-seg-medium`. Status: beta/wired.
+- **SwinV2 real classification backend** via HF Transformers
+  (`AutoModelForImageClassification`). Model IDs: `swinv2-tiny` through
+  `swinv2-large`. Status: beta/wired.
+- **SAM v1 real backend** via HF Transformers (`SamModel`, `SamProcessor`).
+  Model IDs: `sam-vit-base`, `sam-vit-large`, `sam-vit-huge`. Supports point
+  and box prompts. Status: beta/wired.
+- **Grounded SAM composed pipeline** (`grounded-sam`) combining Grounding
+  DINO Tiny + SAM v1 Base for text-prompted segmentation. Status: beta/wired.
+- **Grounding DINO fp16 fix**: cast float tensors to model dtype before
+  forward pass; integer token tensors are not cast. Fallback-to-fp32 on
+  dtype errors.
+- `package_managed` download type for models that manage their own cache
+  (RF-DETR). `is_downloadable()` includes this type.
+- New engine files: `engines/rfdetr.py`, `engines/swinv2.py`,
+  `engines/sam_hf.py`, `engines/grounded_sam.py`.
+- New registry entries: SAM v1 variants, Grounded SAM pipeline.
+- Tests: `test_rfdetr_engine.py`, `test_new_backends.py` with `@real_model`
+  and `@gpu` marks registered in `pyproject.toml`.
+- Version bumped to 0.3.0.
+
+### Changed
+- RF-DETR and RF-DETR-Seg registry entries updated to `download_type:
+  package_managed`, `implementation_status: wired`, `status: beta`.
+- SwinV2 registry entries updated to `engine: swinv2`, `implementation_status:
+  wired`, `status: beta`.
+- SAM 2 entries (`sam2-hiera-*`) remain `stub` / `experimental` with improved
+  warning: "Use `sam-vit-base` instead."
+- `grounded-sam` added as wired alternative to `grounded-sam2` (which needs
+  the sam2 package not on PyPI).
+
+## [0.2.0] - 2026-05-15
+
+### Added (Pass 2)
+- Grounding DINO real backend (wired via HF Transformers).
+- First-class downloader (HF, GitHub, direct URL, resume, SHA-256).
+- Job system for async model downloads.
+- Recommendation engine and `recommend` CLI command.
+- Beginner-friendly `doctor` command (system, devices, deps, recommendations).
+- `devices`, `pull-easy`, `pull-recommended`, `pull-all`, `cache verify/repair`
+  commands.
+- Auto-pull config, job-mode server prediction.
+- Expanded registry (63 models with difficulty/vram/download metadata).
+- Beginner examples (10 scripts), synthetic sample images.
+- Author attribution (Arash Sajjadi, University of Saskatchewan).
+- CITATION.cff, NOTICE.
+
+## [0.1.0] - 2026-05-15
+
+### Added
+- Initial public scaffold.
+- Model registry with permissive-license-first defaults.
+- `VisionModel` high-level Python API with stable result schemas.
+- FastAPI server with `/health`, `/ready`, `/version`, `/models`,
+  `/predict`, `/detect`, `/segment`, `/pose`, `/classify`,
+  `/open-vocab/detect`, `/grounded-segment`, and `/metrics`.
+- Typer CLI: `doctor`, `list-models`, `info`, `pull`, `cache`, `predict`,
+  `serve`, `tunnel`, `benchmark`, `export`, `config`.
+- Security middleware: API key auth, rate limit, body-size limit,
+  image validators, SSRF guard, log redaction.
+- Cloudflare Tunnel integration via external `cloudflared` binary, with a
+  safe ingress config generator that includes a catch-all 404.
+- `MockEngine` for tests and engine stubs for D-FINE, RF-DETR, SAM 2,
+  Grounding DINO with actionable install hints.
+- LRU model cache with VRAM-aware lazy loading.
+- Docker (CPU) image and `docker-compose.yml` with optional cloudflared
+  sidecar.
+- Documentation covering installation, quickstart, model zoo, tasks,
+  Cloudflare Tunnel, security, deployment, performance, troubleshooting,
+  model licenses, and an LLM-agent guide.

visionservex-0.3.0/CITATION.cff

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Arash Sajjadi
+cff-version: 1.2.0
+message: "If you use VisionServeX in academic work, please cite the project as follows."
+title: "VisionServeX: A permissive-license-aware framework for local computer vision model serving"
+authors:
+  - family-names: "Sajjadi"
+    given-names: "Arash"
+    affiliation: "University of Saskatchewan, Department of Computer Science"
+    email: "arash.sajjadi@usask.ca"
+date-released: "2026-05-15"
+version: "0.2.0"
+license: "Apache-2.0"
+repository-code: "https://github.com/example/visionservex"
+url: "https://github.com/example/visionservex"
+keywords:
+  - "computer vision"
+  - "object detection"
+  - "segmentation"
+  - "inference"
+  - "fastapi"
+  - "cloudflare tunnel"
+abstract: >-
+  VisionServeX is a Python framework for serving modern, permissively-licensed
+  computer vision models on local machines, workstations, and small servers.
+  It targets a beginner-friendly developer experience, predictable JSON
+  contracts for LLM agents, and secure-by-default operation, with first-class
+  support for Cloudflare Tunnel-based public exposure.
+preferred-citation:
+  type: software
+  title: "VisionServeX"
+  authors:
+    - family-names: "Sajjadi"
+      given-names: "Arash"
+  year: 2026
+  notes: >-
+    Developed under the supervision of Prof. Mark Eramian, Department of
+    Computer Science, University of Saskatchewan, Computer Vision Lab.

visionservex-0.3.0/LICENSE

@@ -0,0 +1,29 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright (c) 2026 Arash Sajjadi
+   Developed under the supervision of Prof. Mark Eramian, Department of
+   Computer Science, University of Saskatchewan, Computer Vision Lab.
+
+   SPDX-License-Identifier: Apache-2.0
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   ----------------------------------------------------------------------
+
+   Full Apache 2.0 license text is available at:
+       https://www.apache.org/licenses/LICENSE-2.0.txt
+
+   Each integrated upstream model retains its own license. Refer to
+   docs/model_licenses.md for per-model upstream license information.

visionservex-0.3.0/NOTICE

@@ -0,0 +1,19 @@
+VisionServeX
+Copyright (c) 2026 Arash Sajjadi
+
+This product includes software developed by Arash Sajjadi
+(arash.sajjadi@usask.ca, PhD Candidate, Department of Computer Science,
+University of Saskatchewan).
+
+Developed under the supervision of Prof. Mark Eramian, Department of
+Computer Science, University of Saskatchewan, Computer Vision Lab.
+This work is not an official product of the University of Saskatchewan
+and is not endorsed by the University unless stated otherwise in writing.
+
+----
+
+This project integrates and references third-party computer vision models.
+Each integrated upstream project retains its own copyright and license.
+Refer to docs/model_licenses.md for per-model upstream license information.
+Users are responsible for reviewing upstream model, dataset, and checkpoint
+licenses before commercial deployment.