Metadata-Version: 2.4
Name: cuvis-ai-core
Version: 0.3.4
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.12,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cuvis>=3.5.0
Requires-Dist: cuvis-ai-schemas>=0.3.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 Framework



![image](https://raw.githubusercontent.com/cubert-hyperspectral/cuvis.sdk/main/branding/logo/banner.png)

[![PyPI version](https://img.shields.io/pypi/v/cuvis-ai-core.svg)](https://pypi.org/project/cuvis-ai-core/)
[![CI Status](https://github.com/cubert-hyperspectral/cuvis-ai-core/actions/workflows/ci.yml/badge.svg)](https://github.com/cubert-hyperspectral/cuvis-ai-core/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/cubert-hyperspectral/cuvis-ai-core/branch/main/graph/badge.svg)](https://codecov.io/gh/cubert-hyperspectral/cuvis-ai-core)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/)



## Overview

**cuvis-ai-core** is the foundational framework that powers the [cuvis-ai](https://github.com/cubert-hyperspectral/cuvis-ai) machine learning pipeline for hyperspectral image analysis. This repository provides the core infrastructure and building blocks that enable flexible, extensible AI workflows for hyperspectral measurements.

While the [cuvis-ai](https://github.com/cubert-hyperspectral/cuvis-ai) repository contains domain-specific nodes and pre-built models for tasks like anomaly detection and classification, **cuvis-ai-core** provides the essential framework components:

- **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.
