Jm/init

.agents/skills/mblt-vision-readme/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: mblt-vision-readme
+description: >-
+  Write and maintain mblt-vision-python README documentation, API examples, model references,
+  and migration notes.
+---
+
+# Mobilint Vision README Writing
+
+## Documentation Ownership
+
+- Keep the root README concise: package purpose, installation, a minimal example, and a link to
+  mblt_vision/README.md.
+- Keep the detailed Vision API reference in mblt_vision/README.md. It owns Python construction,
+  framework selection, model discovery, model-family tables, output taxonomy, and migration notes.
+- Keep development-tool instructions in `benchmark/README.md` and `compile/README.md`; their
+  command scripts live directly in those directories.
+- Document Model Zoo compatibility as migration context only. Do not present Model Zoo CLI,
+  validation, dataset organization, or compilation commands as features of this package.
+
+## Accuracy Rules
+
+- Use the public mblt_vision namespace in every executable example.
+- Use model_path for new local-artifact examples. Mention mxq_path and onnx_path only as
+  compatibility aliases.
+- State that .mxq and .onnx paths select their framework automatically when framework is omitted.
+  Document the explicit-framework conflict error.
+- Describe file_cfg.filename as the MXQ source artifact and same-stem ONNX derivation. Mention
+  onnx_filename only for a genuinely different published artifact.
+- Keep post_cfg.dataset terminology precise: it identifies output taxonomy, not just a task.
+- Use obb as the only oriented-bounding-box name in standalone documentation.
+
+## Style and Validation
+
+- Use ATX headings, one blank line between blocks, hyphen lists, concise paragraphs, and
+  language-tagged code fences.
+- Prefer generated discovery examples such as list_tasks() and list_models() over manually
+  maintained exhaustive name lists.
+- When changing models, package metadata, dependencies, public APIs, or runtime behavior, update
+  the relevant README, `AGENTS.md`, and the canonical `mblt-vision` skill if the workflow changes.
+- For documentation-only updates, run git diff --check and verify relative links and headings.

.agents/skills/mblt-vision/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: mblt-vision
+description: >-
+  Work on the standalone Mobilint Vision Python API, model registry, preprocessing,
+  postprocessing, results, runtime integration, and package compatibility contracts.
+---
+
+# Mobilint Vision Python
+
+## Start Here
+
+1. Read AGENTS.md.
+2. Run git status --short before changing files.
+3. Read pyproject.toml, the affected package exports, matching model YAML, and relevant tests.
+4. For a compatibility migration, compare against
+   ../mblt-model-zoo/mblt_model_zoo/vision deliberately; do not make it a runtime dependency.
+
+## Public API and Model Registry
+
+- Use mblt_vision.MBLT_Engine and task subpackages as the public surface.
+- Keep mblt_vision as the sole intended import namespace. Use obb as the sole
+  oriented-bounding-box task name.
+- Update a task package, top-level lazy exports, and list_models() discovery together.
+- Preserve constructor arguments including model_path, mxq_path, onnx_path,
+  model_type, and core-selection options unless intentionally changing the API.
+- Keep .mxq/.onnx suffix routing and explicit-framework conflict errors intact.
+- Every model YAML must define stable file_cfg, pre_cfg, and post_cfg mappings.
+  Use file_cfg.filename for MXQ and derive the same-stem ONNX artifact unless
+  onnx_filename is required.
+- Every post_cfg declares dataset; resolve output taxonomy from the dataset/task pair.
+
+## Processing and Results
+
+- Reuse the shared letterbox geometry for both preprocessing and inverse coordinate restoration.
+- Detection requires pre_cfg.LetterBox. Keep semantic metadata (img0_shape and
+  ratio_pad) through postprocessing so logits restore to the original geometry before
+  argmax.
+- Preserve decoded-output layout provenance through NMS. For ambiguous tensors without
+  provenance, prioritize channels-first raw-output normalization.
+- Normalize dense depth and semantic outputs before inverse letterboxing. Validate baked semantic
+  maps are finite, integral, and in-range before converting them to integer class IDs.
+- Keep result shapes, ordering, coordinates, dtype, and empty-result behavior compatible with
+  the Model Zoo reference.
+
+## Runtime and Packaging
+
+- Route NPU runtime access through mblt-npu-python; do not copy backend classes into Vision.
+- Use the shared `ONNXBackend` for ONNX inference. Keep ONNX Runtime optional and lazy-imported;
+  raise a specific installation error when it is requested but unavailable.
+- Normalize legacy `aries` and `regulus` target values through mblt-npu-python. MXQ artifacts and
+  compilation metadata must resolve only from the selected board folder, never a core-mode path or
+  a fallback board folder.
+- Include model and dataset YAML files as package data. Build a wheel and inspect it after
+  changing metadata or assets.
+- Do not require native bindings, GStreamer, hardware, downloaded models, or caches for normal
+  imports and unit tests.
+
+## Tooling Layout and Documentation
+
+- Keep all executable benchmark scripts directly in `benchmark/`; reusable reporting helpers belong
+  in `mblt_vision.benchmark`.
+- Keep all executable compile scripts and the compile guide directly in `compile/`.
+- Use `~/.mblt_model_zoo` as the shared artifact and dataset cache root. Keep organizer defaults,
+  dataset registry YAMLs, compilation defaults, and documented commands aligned to it.
+- Keep imports free of cache-directory creation, write probes, downloads, and temporary-directory
+  allocation; resolve a writable cache only when an artifact or compilation output needs it.
+- Make fallback caches stable, private, and user-owned. Never use a new temporary directory per
+  process or trust a shared fallback cache without validating it.
+- For every significant package change (public API, CLI, runtime/dependency, artifact layout, or
+  tooling structure), update `AGENTS.md`, this canonical skill, the Claude skill entry point when
+  its workflow changes, and the relevant README in the same change.
+
+## Validate Proportionately
+
+- Begin with the smallest relevant test file or -k selection.
+- Add deterministic differential tests for Model Zoo compatibility, including invalid inputs,
+  empty detections, threshold boundaries, task discovery, and image geometry.
+- Run pre-commit run --files <touched files> when available. For docs, run
+  git diff --check.
+- Report unavailable hardware, downloads, or optional dependencies rather than weakening tests.

.claude/skills/mblt-vision-readme/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: mblt-vision-readme
+description: Write and maintain documentation for the standalone Mobilint Vision Python package.
+---
+
+# Mobilint Vision README Writing
+
+Read and follow the canonical skill at
+../../../.agents/skills/mblt-vision-readme/SKILL.md.

.claude/skills/mblt-vision/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: mblt-vision
+description: Work effectively on the standalone Mobilint Vision Python API and model registry.
+---
+
+# Mobilint Vision Python
+
+Read and follow the canonical skill at
+../../../.agents/skills/mblt-vision/SKILL.md.

.github/workflows/publish.yml

@@ -0,0 +1,80 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution 🛠️
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Validate distributions
+        run: python -m twine check dist/*
+
+      - name: Verify wheel package contents
+        run: |
+          python -c "from pathlib import Path; from zipfile import ZipFile; wheel, = Path('dist').glob('*.whl'); archive = ZipFile(wheel); assert 'mblt_vision/py.typed' in archive.namelist(), 'Wheel is missing mblt_vision/py.typed'"
+
+      - name: Upload built distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI 🧪
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-to-pypi:
+    name: Publish to PyPI 🚀
+    needs: [build, publish-to-testpypi]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+.venv/
+venv/
+env/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+*.egg-info/
+
+# C/C++ build artifacts
+build/
+cmake-build-*/
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+compile_commands.json
+*.o
+*.obj
+*.a
+*.lib
+*.so
+*.dylib
+*.dll
+*.exe
+*.out
+
+# IDE and OS files
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+*.zip
+*.tar.gz
+*.egg

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+