Metadata-Version: 2.4
Name: cuvis-ai-core
Version: 0.5.0
Summary: Cuvis.AI Core Framework
Author-email: Cubert GmbH <cuvis.ai@cubert-gmbh.com>
License: Apache-2.0
Project-URL: Homepage, https://www.cubert-hyperspectral.com/
Project-URL: Repository, https://github.com/cubert-hyperspectral/cuvis-ai-core
Project-URL: Documentation, https://github.com/cubert-hyperspectral/cuvis-ai-core/tree/main/docs
Project-URL: Issues, https://github.com/cubert-hyperspectral/cuvis-ai-core/issues
Project-URL: Changelog, https://github.com/cubert-hyperspectral/cuvis-ai-core/blob/main/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: Pydantic
Classifier: Framework :: Pydantic :: 2
Classifier: Typing :: Typed
Classifier: Operating System :: OS Independent
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cuvis>=3.5.0
Requires-Dist: cuvis-ai-schemas[proto]>=0.4.0
Requires-Dist: torch>=2.9.1
Requires-Dist: torchvision
Requires-Dist: pytorch-lightning>=2.6.0
Requires-Dist: hydra-core>=1.3.0
Requires-Dist: omegaconf>=2.3.0
Requires-Dist: grpcio>=1.56.0
Requires-Dist: protobuf>=6.33.4
Requires-Dist: grpcio-health-checking>=1.56.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: opencv-python-headless>=4.5.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: gitpython>=3.1.40
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: dataclass-wizard
Requires-Dist: dotenv>=0.9.9
Requires-Dist: ruff>=0.14.11
Requires-Dist: scikit-image>=0.25.2
Requires-Dist: pycocotools>=2.0.11
Requires-Dist: graphviz>=0.21
Requires-Dist: scikit-learn>=1.8.0
Provides-Extra: hf
Requires-Dist: huggingface-hub>=0.20.0; extra == "hf"
Provides-Extra: dev
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: jupyterlab; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: types-protobuf>=5.29.2; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ipympl>=0.9.8; extra == "dev"
Requires-Dist: ipdb>=0.13.13; extra == "dev"
Requires-Dist: psutil; extra == "dev"
Requires-Dist: twine>=6.2.0; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"
Requires-Dist: bandit[toml]>=1.7.0; extra == "dev"
Requires-Dist: detect-secrets>=1.4.0; extra == "dev"
Requires-Dist: pip-licenses>=4.0.0; extra == "dev"
Requires-Dist: cyclonedx-bom>=4.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Dynamic: license-file

# Cuvis.AI Core



![image](https://github.com/cubert-hyperspectral/cuvis.sdk/blob/main/branding/logo/banner.png?raw=true)

[![PyPI][pypi-badge]][pypi-link]
[![CI][ci-badge]][ci-link]
[![codecov][cov-badge]][cov-link]
[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](LICENSE)

[pypi-badge]: https://img.shields.io/pypi/v/cuvis-ai-core?style=flat-square&logo=pypi&logoColor=white
[pypi-link]: https://pypi.org/project/cuvis-ai-core/
[ci-badge]: https://img.shields.io/github/actions/workflow/status/cubert-hyperspectral/cuvis-ai-core/ci.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI
[ci-link]: https://github.com/cubert-hyperspectral/cuvis-ai-core/actions/workflows/ci.yml
[cov-badge]: https://img.shields.io/codecov/c/github/cubert-hyperspectral/cuvis-ai-core?style=flat-square&logo=codecov&logoColor=white
[cov-link]: https://codecov.io/gh/cubert-hyperspectral/cuvis-ai-core



## Overview

Cuvis.AI is an opensource and extensible framework for building AI powered processing pipelines for hyperspectral video data.

It allows you to process and structure spectral data, train and apply machine learning models, visualize and interpret results, and deploy applications in real time environments.

Pipelines are built from reusable modular nodes and can be extended with custom plugins or external integrations.

Cuvis.AI bridges the gap between hyperspectral hardware and real world applications and enables faster development, testing, and deployment of new solutions.

**cuvis-ai-core** is the foundational framework underneath Cuvis.AI. While the [cuvis-ai](https://github.com/cubert-hyperspectral/cuvis-ai) repository contains the catalog of domain-specific nodes and pre-built models, **cuvis-ai-core** provides the essential infrastructure that makes those modular pipelines work:

- **Node System**: Base classes for creating processing nodes with typed input/output ports
- **Pipeline Infrastructure**: Graph-based pipeline orchestration, execution, and visualization
- **Plugin System**: Dynamic node loading from Git repositories or local filesystem paths
- **Serialization & Restoration**: Save and restore complete pipeline states and configurations
- **Type Safety**: Strongly-typed port system with runtime validation
- **gRPC Services**: Remote pipeline management, training, and inference APIs
- **Training Framework**: Integration with PyTorch Lightning for model training workflows

This separation allows the core framework to evolve independently while the catalog of domain-specific nodes grows through a plugin architecture.

- **Website:** https://www.cubert-hyperspectral.com/
- **Support:** http://support.cubert-hyperspectral.com/

## Installation

### Prerequisites

If you want to directly work with cubert session files (.cu3s), you need to install cuvis C SDK from 
[here](https://cloud.cubert-gmbh.de/s/qpxkyWkycrmBK9m).

Local development now relies on [uv](https://docs.astral.sh/uv/) for Python and dependency management.
If `uv` is not already available on your system you can install it following their installation instructions.

### Install from PyPI (Recommended)

```bash
# Install cuvis-ai-core from PyPI
uv add cuvis-ai-core
```

PyTorch will be installed automatically with CUDA support if available on your system.

### Local development with uv

Create or refresh a development environment at the repository root with:

```bash
uv sync --all-extras --dev
```

This installs the runtime dependencies declared in `pyproject.toml`. `uv` automatically provisions the Python version declared in the project metadata, so no manual interpreter management is required.

#### Enable Git Hooks (Required)

After cloning the repository, enable the git hooks for code quality enforcement:

```bash
git config core.hooksPath .githooks
```

This configures Git to use the version-controlled hooks in `.githooks/` which automatically enforce code formatting, linting, and testing standards before commits and pushes. See [docs/development/git-hooks.md](docs/development/git-hooks.md) for details.

#### Advanced environment setup

When you need the reproducible development toolchain (JupyterLab, TensorBoard, etc.) from the lock file, run:

```bash
uv sync --locked --extra dev
```

Use `uv run` to execute project tooling without manually activating virtual environments, for example:

```bash
uv run pytest
```

Collect coverage details (the `dev` extra installs `pytest-cov`) with:

```bash
uv run pytest --cov=cuvis_ai --cov-report=term-missing
```

Ruff handles both formatting and linting. Format sources and check style with:

```bash
uv run ruff format .
uv run ruff check .
```

The configuration enforces import ordering, newline hygiene, modern string formatting, safe exception chaining, and practical return type annotations while avoiding noisy `Any` policing.

Validate packaging metadata and build artifacts before publishing:

```bash
uv build
```


To build the documentation, add the `docs` extra:

```bash
uv sync --locked --extra docs
```

Combine extras as needed (e.g. `uv sync --locked --extra dev --extra docs`). Whenever the `pyproject.toml` or `uv.lock` changes, rerun `uv sync --locked` with the extras you need to stay up to date.
