# Developing VIPR Plugins

## Start from the Example

The best way to create a plugin is to copy and adapt the example plugin in `example-plugin/`.

## Minimal Plugin - Step by Step

This follows the structure of `example-plugin/`.

### 1. Project Configuration (pyproject.toml)

```toml
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "vipr-log-file"  # PyPI package name
version = "0.1.0"
dependencies = ["vipr"]

[project.entry-points."vipr.plugins"]
log_file = "vipr_log_file:load"  # entry_point_name = "package:function"

[tool.setuptools.packages.find]
where = ["."]
include = ["vipr_log_file*"]
```

### 2. Package Structure

```
vipr_log_file/          # Package name (matches entry point target)
└── __init__.py         # Contains load(app) function
```

### 3. Implementation (__init__.py)

```python
def load(app):
    """Plugin initialization - called by VIPR"""
    app.log.info("Loading log_file plugin")
    
    # Register hook
    def write_logs_to_file(app):
        # Your plugin logic here
        pass
    
    # Register with weight to control execution order
    # Hooks are executed from lowest to highest weight value
    app.hook.register('INFERENCE_COMPLETE_HOOK', write_logs_to_file, weight=250)
```

**Note on weights:** The `weight` parameter controls execution order for hooks. Hooks are executed from lowest to highest weight value, regardless of registration order. This allows plugins to ensure their hooks run at the right time in relation to other plugins.

## Installation

```bash
cd example-plugin/
pip install -e .  # Development mode
```

Plugin is automatically discovered via entry points.

## Optional: Plugin Control

Create `vipr-plugins.yaml` in your working directory to disable a plugin:

```yaml
plugin.log_file:
  enabled: false
```

**Note:** `log_file` matches the entry point name in pyproject.toml, NOT the package name.

## Complete Working Example

See `example-plugin/` for the full implementation that:
- Registers a hook
- Writes logs to a file after inference
- Shows proper project structure

Copy it and adapt for your needs.