Plugin API Reference

This is the reference for app.plugin_api — the versioned contract a plugin depends on (and which will publish separately as ciaren-plugin-api). It is still alpha and may change between releases until 1.0.0. A plugin imports only from this package, never from Ciaren's app, engine, or FastAPI internals.

New to plugins? Start with the Overview and the 10-minute tutorial; this page is the detailed contract.

The contract itself is versioned independently of the app: app.plugin_api.PLUGIN_API_VERSION (currently "0.1.0-alpha.1"). A plugin declares which contract it targets via its manifest's api_version; the loader rejects a plugin whose contract is incompatible with the running backend before importing it. Pre-1.0 (alpha) the contract makes no backward-compatibility promise — a plugin must target the exact major.minor the backend provides; from 1.0 on, minors become additive and only a major bump breaks. The backend's own value is exposed as plugin_api_version in GET /api/plugins/diagnostics. See Contract versioning for the full policy.

from app.plugin_api import (
    Plugin, PluginMetadata, ServiceRegistry,
    NodeProvider, NodeSpec, NodeRuntime, NodeContext, ModelStore, PortSpec, Permission,
    ConnectorProvider, ConnectorSpec, ConnectorRuntime, ConnectorTestResult,
    ModelProvider, ModelTypeSpec, ModelRef,
    ConfigFieldSpec, validate_config_schema,
    StorageProvider, StorageSpec,
    ExecutionProvider, ExecutionSpec, ExporterProvider, ExporterSpec,
    ValidatorProvider, ValidatorSpec, AIProvider, AICapabilitySpec,
    AuthProvider, AuthMethodSpec, LicenseProvider, LicenseStatus,
)

Plugin

The entry point a plugin package exposes. The loader instantiates it and calls register().

class GreetingPlugin(Plugin):
    def metadata(self) -> PluginMetadata: ...
    def register(self, registry: ServiceRegistry) -> None:
        registry.register_node_provider(_GreetingNodeProvider())

ServiceRegistry

Passed to Plugin.register(). Register each provider you implement:

Provider interfaces

Each provider is an ABC. Implement the ones you need; a single plugin can implement several. Providers return serializable specs (for the catalog) and, where relevant, opaque implementations (duck-typed by the engine).

A catalog-only NodeProvider may omit node_implementations() (the node appears but isn't executable); return a {node_id: NodeRuntime} map to make it run.

NodeRuntime

The runnable side of a plugin node. The contract is pandas-based and engine-agnostic: you receive and return pandas DataFrames keyed by handle, and Ciaren converts to/from the active engine (polars/pandas) around the call.

Override execute or execute_with_context — never neither. Handle conventions match the node's NodeSpec: a single-input node reads inputs["in"] and returns {"out": frame}.

class AddGreetingRuntime(NodeRuntime):
    def execute(self, inputs, config):
        df = inputs["in"].copy()
        df[config.get("column") or "greeting"] = "Hello!"
        return {"out": df}

NodeContext

Host services passed to execute_with_context:

Thin-client plugins

For a paid plugin whose logic you don't want to ship to the user's disk (or whose license must be unskippable), keep the work on your server and make the node a thin client. Forward context.license_token with each request and validate it server-side — signature, expiry, revocation, per-user rate limits and quotas — where the user can't patch the check out:

class PremiumRuntime(NodeRuntime):
    def execute_with_context(self, inputs, config, context):
        resp = httpx.post(
            config["endpoint"],                    # a secret (env-var) config field
            json={"token": context.license_token, "data": inputs["in"].to_json()},
            timeout=30,
        )
        if resp.status_code == 402:                # quota exhausted / not entitled
            raise ValueError(resp.json()["detail"])
        resp.raise_for_status()
        return {"out": pd.read_json(resp.text)}

The node needs the network permission, and endpoint should be a secret config_schema field (an env-var name). See Plugin Security for why this is the only robust way to protect plugin logic and enforce per-buyer limits.

ModelStore

The sanctioned persistence path for plugin-trained models — estimators become MLflow artifacts; only a typed ModelRef travels through the graph.

ModelRef

The typed payload of a model wire — a frozen dataclass with a one-row-frame round-trip. The core train nodes emit exactly this frame, and the core consumers (mlPredict, featureImportance, mlCrossValidate) read it, so plugin and core models interoperate in both directions.

ConnectorRuntime

The runnable side of a plugin connector — pandas-based like NodeRuntime. config is the saved connection flattened to a plain mapping (host, port, database, username, password resolved from the env var for the one call, options); options on read/write carries the flow node's config plus limit for bounded preview reads. Only read is required; unimplemented optional methods surface as a clear "not supported by this connector" error.

ModelTypeSpec

Describes a trainable model type contributed to the ML catalog; it appears in the matching core train node's picker and trains through the core pipeline.

The matching builder (from ModelProvider.model_builders()) is (hyperparameters: dict, seed: int | None) -> estimator and must return an sklearn-compatible estimator. Hyperparameters arrive sanitized to JSON-native values; inject the seed unless the user set one explicitly.

ConfigFieldSpec and config_schema

A deliberately small, UI-oriented form dialect (not full JSON Schema), shared by plugin node config forms (NodeSpec.config_schema), connector connection forms (ConnectorSpec.config_schema), and model hyperparameter forms (ModelTypeSpec.hyperparameter_schema). Shape: {"fields": [ … ]} where each field validates as:

A malformed schema fails at registration (validate_config_schema), never at render time.

Spec types

Specs are Pydantic models — JSON-serializable descriptions of what a plugin contributes. They carry no executable behavior.

NodeSpec

PortSpec

Other specs (shared shape)

ConnectorSpec, StorageSpec, ExecutionSpec, ExporterSpec, ValidatorSpec, AICapabilitySpec, and AuthMethodSpec all carry an id, a label, a provider, and capabilities, plus a few type-specific fields:

• ConnectorSpec — kind ("sql" / "mongo" / "storage" / "mlflow", or your own, e.g. "api" — sql-ish kinds back the SQL nodes, storage backs the storage nodes), available, driver_module, extra (pip extra for the install hint), permissions, metadata (form flags: host/port/auth/bucket/…), and config_schema (extra connector-specific form fields, stored in the connection's options).
• ExecutionSpec — available (an engine name the executor understands).
• ExporterSpec — format (e.g. "python") and file_extension.
• ValidatorSpec / AICapabilitySpec — a description.

PluginMetadata

id, name, version, publisher, description, capabilities, permissions.

LicenseStatus

Returned by LicenseProvider.validate_license(): plugin_id, valid, license_type, expires_at, reason.

Permission

Permissions a plugin may request in its manifest. They are a trust and UX boundary surfaced before a plugin is enabled — not a hard sandbox. Model-load is enforced by the host, and an opt-in audit-hook mode (CIAREN_PLUGIN_PERMISSION_ENFORCEMENT=warn|enforce) can log or block ungranted network/filesystem-write/subprocess/shell actions at runtime. See Plugin Security & Permissions.

filesystem_read · filesystem_write · network · credentials · subprocess · shell · docker · local_model_load · joblib_load · database_access · cloud_access · llm_access · telemetry

See also

• Plugins Overview — the extension-points map
• Build Your First Plugin — step-by-step tutorial
• Writing a Plugin — events, rules, and details
• Plugin Manifest · .flow Format