# VIPR Core

**VIPR** (Versatile Inverse Problem Software Framework) is a lightweight, plugin-based Python framework for building composable machine-learning workflows. Built on the [Cement CLI framework](https://builtoncement.com/), VIPR enables research groups to develop domain-specific plugins that can be configured and adapted via YAML—without requiring code modifications.

## Key Features

- **Built-in Inference Workflow**: 6-step ML pipeline with type-safe extension points
- **Plugin Architecture**: Extend via handlers, filters, and hooks
- **YAML Configuration**: Declarative workflow composition
- **Type Safety**: Runtime type checking ensures predictable data flow
- **CLI & API Ready**: Execute via command line or programmatically

## Installation

```bash
pip install git+https://codebase.helmholtz.cloud/vipr/vipr-core.git
```

For local development:
```bash
cd vipr-core
pip install -e .
```

## Quick Start

VIPR Core provides the framework. Domain-specific functionality comes from plugins.

Example using the [reflectometry plugin](https://codebase.helmholtz.cloud/vipr/vipr-reflectometry-plugin):

```bash
# Install reflectometry plugin
pip install git+https://codebase.helmholtz.cloud/vipr/vipr-reflectometry-plugin.git

# Run inference with bundled example
vipr --config @vipr_reflectometry/reflectorch/examples/configs/PTCDI-C3.yaml inference run
```

See the [reflectometry plugin repository](https://codebase.helmholtz.cloud/vipr/vipr-reflectometry-plugin) for more examples and usage instructions.

## Architecture

VIPR uses a layered approach:

1. **Framework Core**: Plugin system, built-in inference workflow (load data → load model → preprocess → predict → postprocess)
2. **Domain Plugins**: Domain-specific implementations (handlers, filters, hooks)
3. **YAML Configuration**: Workflow composition by selecting components and parameters

## Example Configuration

```yaml
vipr:
  inference:
    load_data:
      handler: your_data_loader
      parameters:
        file_path: data/input.csv
    
    load_model:
      handler: your_model_loader
      parameters:
        model_path: models/trained_model.pt
    
    filters:
      INFERENCE_PREPROCESS_PRE_FILTER:
        - class: your_plugin.YourPreprocessor
          enabled: true
          method: preprocess_data
```

## Documentation

- **Architecture Principles**: [architecture_principles.md](architecture_principles.md)
- **Plugin Development**: See documentation for handlers, filters, and hooks

## Available Plugins

- **vipr-reflectometry**: X-ray and neutron reflectometry analysis
- More domain plugins can be developed following the plugin architecture

## Acknowledgments

VIPR Framework builds upon [NF4IP](https://github.com/Photon-AI-Research/NF4IP) (Normalising Flows for Inverse Problems). We gratefully acknowledge the foundational work of:

- **Photon AI Research**
- **HZDR's AI Consultant Team for MATTER research**  
- **[Helm & Walter IT Solutions](https://www.helmundwalter.de/)**
- **Maintainer**: Nico Hoffmann (PAIR)

See [NOTICE.txt](NOTICE.txt) for complete third-party component information.

## License

This library is licensed under the **GNU Lesser General Public License v3.0** (LGPL-3.0).

### What this means for you:

**You CAN:**
- Use this library in commercial applications
- Use this library in proprietary/closed-source applications
- Modify the library for your needs

**You MUST:**
- Keep this library as a separate component (dynamic linking)
- Provide the source code of the library (including your modifications)
- Allow users to replace the library with a modified version
- Include the LGPL license text and copyright notices

**You CANNOT:**
- Statically link this library without releasing your entire application as LGPL
- Remove copyright notices
- Hold us liable for damages

### For proprietary applications:

You can use this library in your closed-source application by:
1. Linking dynamically (as a `.dll`, `.so`, or `.dylib`)
2. Providing a copy of this library's source code
3. Allowing users to replace the library version

See [LICENSE](LICENSE.txt) for the full license text.
