# EZ-Input Backend Plugin System

A minimal, FastAPI-friendly plugin architecture for the ZenMirage / admin-panel ecosystem.

## What it does

- **Plugin base class**: every plugin inherits from `Plugin`, declares metadata (`name`, `version`, `description`, `dependencies`), and implements `register(app)` to add routes.
- **Plugin registry**: `PluginRegistry` discovers plugin modules in a `plugins/` directory, resolves dependencies, and registers them with a FastAPI app.
- **Lifecycle hooks**: plugins can implement `activate()` for post-registration setup, and `health()` for status reporting.
- **Shared context**: `set_context(ctx)` binds a shared dict to every plugin.
- **FastAPI integration**: `create_app(plugin_dir)` wires everything together in one line.

## Files

| File | Purpose |
|------|---------|
| `plugin.py` | `Plugin` abstract base class. |
| `registry.py` | `PluginRegistry` discovery, dependency resolution, and mounting. |
| `plugins/health_check_plugin.py` | Example plugin that adds `/plugin/health`. |
| `fastapi_integration.py` | Example FastAPI service that loads plugins. |
| `tests/` | Pytest suite covering registry, health plugin, and FastAPI integration. |
| `requirements.txt` | Python dependencies. |

## Quick start

```bash
cd /root/ez-input-plugins/backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python fastapi_integration.py
```

Then visit:

- `http://127.0.0.1:8900/health` — host health
- `http://127.0.0.1:8900/plugin/health` — health-check endpoint added by the example plugin
- `http://127.0.0.1:8900/plugin/status` — aggregated plugin health
- `http://127.0.0.1:8900/plugins` — loaded plugin metadata and route list

## Writing a plugin

Create a Python file under `plugins/` (or any scanned directory) with a class that extends `Plugin`:

```python
from fastapi import APIRouter, FastAPI
from plugin import Plugin

class MyPlugin(Plugin):
    name = "my_plugin"
    version = "1.0.0"
    description = "Does something useful."
    dependencies = []

    def register(self, app: FastAPI) -> None:
        router = APIRouter(prefix="/my-plugin", tags=["plugins"])

        @router.get("/hello")
        async def hello():
            return {"message": "Hello from my plugin"}

        app.include_router(router)
```

The registry auto-discovers and mounts the plugin.

## Running tests

```bash
cd /root/ez-input-plugins/backend
source .venv/bin/activate
pytest tests/ -v
```

## Integration with admin-panel / ZenMirage

Import `create_app()` (or use `PluginRegistry` directly) in your service entrypoint:

```python
from fastapi_integration import create_app

app = create_app("/root/ez-input-plugins/backend/plugins")
```

Plugins are mounted during app construction, so they appear alongside your existing routes.