Skip to content

Release 1.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 13 Jan 08:03
· 3 commits to main since this release
1.0.0
adbb696

Quality Gates & Modular Runtimes

Capybara v1.0.0 marks the first “production-ready” baseline for the project: packaging is refactored to be lightweight by default, inference backends are moved to opt-in extras, and CI now enforces a strict quality gate (ruff + pyright + pytest + coverage gate). This release also reshapes the public API surface (capybara.__init__) to be explicit and stable.

Highlights

1) Lightweight default install + opt-in inference backends

Capybara now installs core-only dependencies by default (vision / structures / utils). Heavy inference stacks are explicitly opt-in via extras.

Core install

pip install capybara-docsaid

Inference backends (optional)

# ONNX Runtime (CPU)
pip install "capybara-docsaid[onnxruntime]"

# ONNX Runtime (GPU)
pip install "capybara-docsaid[onnxruntime-gpu]"

# OpenVINO runtime
pip install "capybara-docsaid[openvino]"

# TorchScript runtime
pip install "capybara-docsaid[torchscript]"

# Install all runtimes
pip install "capybara-docsaid[all]"

Feature extras (optional)

pip install "capybara-docsaid[visualization]"  # matplotlib/pillow
pip install "capybara-docsaid[ipcam]"          # flask
pip install "capybara-docsaid[system]"         # psutil

2) New runtime registry for backend selection (capybara.runtime)

A new Runtime / Backend registry unifies backend naming and adds auto backend selection utilities.

from capybara.runtime import Runtime

print(Runtime.onnx.auto_backend_name())      # Priority: cuda -> tensorrt_rtx -> tensorrt -> cpu
print(Runtime.openvino.auto_backend_name())  # Priority: gpu -> npu -> cpu
print(Runtime.pt.auto_backend_name())        # Priority: cuda -> cpu

This removes duplicated, backend-specific heuristics and provides a single place to reason about execution targets.

3) ONNXEngine rewritten: ergonomic config, IO binding, benchmark, and better metadata

capybara.onnxengine is refactored into a clearer surface:

  • EngineConfig defines high-level session/provider/run options.
  • Optional IO binding (enable_io_binding=True) for performance.
  • benchmark(...) returns throughput + latency stats.
  • Metadata parsing now attempts JSON decoding for custom metadata values.
  • Provider chains follow capybara.runtime.Backend provider specs.

Example

import numpy as np
from capybara.onnxengine import EngineConfig, ONNXEngine

engine = ONNXEngine(
    "model.onnx",
    backend="cpu",
    config=EngineConfig(enable_io_binding=False),
)

outputs = engine.run({"input": np.ones((1, 3, 224, 224), dtype=np.float32)})
print(outputs.keys())
print(engine.summary())
print(engine.benchmark({"input": np.ones((1, 3, 224, 224), dtype=np.float32)}, repeat=50, warmup=5))

Note: onnxruntime is now an optional dependency. Importing capybara.onnxengine without installing the corresponding extra will raise a clear ImportError.

4) New OpenVINOEngine + async queue abstraction

A brand-new capybara.openvinoengine module is introduced, with a stable synchronous API and an async queue wrapper that returns Futures.

Synchronous

import numpy as np
from capybara.openvinoengine import OpenVINOConfig, OpenVINODevice, OpenVINOEngine

engine = OpenVINOEngine(
    "model.xml",
    device=OpenVINODevice.cpu,
    config=OpenVINOConfig(num_requests=2),
)

outputs = engine.run({"input": np.ones((1, 3), dtype=np.float32)})
print(outputs.keys())
print(engine.summary())
print(engine.benchmark({"input": np.ones((1, 3), dtype=np.float32)}, repeat=50, warmup=5))

Async (queue + Future)

import numpy as np
from capybara.openvinoengine import OpenVINOEngine

engine = OpenVINOEngine("model.xml", device="CPU")

with engine.create_async_queue(num_requests=2) as q:
    fut = q.submit({"input": np.ones((1, 3), dtype=np.float32)}, request_id="req-1")
    raw_outputs = fut.result()
    print(fut.request_id, raw_outputs.keys())

5) New TorchEngine for TorchScript runtime

capybara.torchengine provides a small, consistent wrapper around TorchScript:

  • Handles dtype inference (fp16 naming + CUDA) and dtype normalization.
  • benchmark(...) includes optional CUDA synchronization to avoid misleading timings.
  • Outputs are normalized into dict[str, np.ndarray].
import numpy as np
from capybara.torchengine import TorchEngine

engine = TorchEngine("model.pt", device="cpu")
outputs = engine.run({"image": np.zeros((1, 3, 224, 224), dtype=np.float32)})
print(outputs.keys())
print(engine.summary())

Public API changes

1) capybara.__init__ is now explicit and curated

Instead of wildcard exports (from .xxx import *), v1.0.0 exports a curated stable API set and defines __all__. This improves:

  • import speed,
  • static analysis quality (pyright),
  • backwards predictability.
import capybara as cb

print(cb.__version__)  # 1.0.0
from capybara import Box, Boxes, Polygon, Polygons, imread, imwrite

2) Backend moved to capybara.runtime

The old capybara.onnxengine.enum.Backend is removed; use:

from capybara.runtime import Backend

Quality Gates: CI is now enforced

What CI runs

A new GitHub Actions workflow Capybara CI is introduced:

  • ruff check capybara tests
  • ruff format --check capybara tests
  • pyright
  • pytest --cov=capybara ...
  • coverage gate enforced

Coverage gate thresholds in CI:

  • Line coverage: 0.99 (99%)
  • Branch coverage: 0.00
  • Enforced: 1 (hard fail)

Coverage config

.coveragerc is added to omit unstable / vendored / environment-dependent files from the gate, keeping CI reproducible.

CI reporting

CI generates and uploads an artifact containing:

  • pytest.xml, pytest.html, coverage.xml, htmlcov/
  • summary markdown + top slow tests
  • coverage missing report
  • logs for ruff/pyright/pytest

Packaging & tooling modernization

1) pyproject.toml becomes the single source of truth

  • Removed legacy setup.py.
  • Raised build requirements: setuptools>=68.
  • Declared Python classifiers up to 3.14.
  • Added optional dependencies groups (onnxruntime, onnxruntime-gpu, openvino, torchscript, system, ipcam, visualization, all).

2) pyrightconfig.json added

Basic type checking is enabled for capybara and tests, with pragmatic stub handling:

{
  "include": ["capybara", "tests"],
  "exclude": ["tmp", "capybara/cpuinfo.py"],
  "pythonVersion": "3.10",
  "typeCheckingMode": "basic",
  "reportMissingTypeStubs": false
}

3) Ruff config added and standardized formatting

ruff and ruff format are now first-class. The repo enforces:

  • py310 target
  • line-length=80
  • lint selections (E/F/W/B/UP/N/I/C4/SIM/RUF)
  • formatting normalization (double quotes, docstring code format, etc.)

Notable implementation hardening (bug fixes / behavioral improvements)

This release includes a large set of defensive fixes and API correctness improvements. A non-exhaustive set of high-impact ones:

  • imwrite() no longer pollutes cwd with tmp.jpg; uses a safe temp file when path is omitted.
  • pad() and imrotate() correctly handle RGBA channel counts and validate pad_value/bordervalue.
  • Visualization no longer auto-downloads fonts; it falls back gracefully when font files are missing.
  • Keypoints no longer hard-depends on matplotlib; it falls back to a pure-python colormap.
  • PowerDict semantics tightened: proper AttributeError, safer update/pop, clear freeze/melt errors.
  • get_files() no longer returns directories when suffix=None.
  • video2frames / video2frames_v2 now validate edge cases (fps=0, n_threads, empty segments) and behave deterministically.

Upgrade notes

Install name change in README badges/links

PyPI package naming is standardized to capybara-docsaid in documentation.

If you previously relied on implicit heavy deps

v1.0.0 will require you to install extras explicitly. For example, ONNX users must install:

pip install "capybara-docsaid[onnxruntime]"        # or [onnxruntime-gpu]

New Contributors

  • @Copilot made their first contribution in #30

Full Changelog: 0.12.0...1.0.0

Assets 3
Loading