Plugin architecture

A .soaiplugin is a versioned ZIP package that adds an inference backend, provider, or media capability through the public plugin_sdk contract. The host inspects and reconciles the package without importing it, then loads its Plugin class in a dedicated worker process. Host code communicates with that worker through an authenticated proxy boundary.

Package admission and SDK boundary

.soaiplugin archive
      |
      +-- archive structure and path inspection
      +-- Python syntax and import audit
      +-- literal manifest extraction
      +-- dependency and compatibility assessment
      `-- capability contract validation
                  |
                  v
       reconciled catalog record
                  |
                  v
       hash-addressed package cache
                  |
                  v
      plugin-specific Python environment
                  |
                  v
         dedicated worker process
                  |
                  v
       authenticated IPC and host proxy
                  |
                  v
       models, routing, tasks, and state

Inspection, reconciliation, preparation, and execution are separate stages, so a valid archive can be incompatible with the current host, a compatible catalog record can be disabled, and an enabled plugin can have no active worker. Keeping those states separate lets SoAI report the exact boundary that prevents dispatch.

Archive admission and identity

The archive must be a valid ZIP with safe member paths and exactly one regular root __init__.py. Python members must decode as UTF-8 and parse as Python. The root entrypoint must define exactly one direct class named Plugin derived from plugin_sdk.BasePlugin. Package-local modules, data, licenses, and an optional root model_parameters.json can accompany it.

Package identity and manifest data are extracted from literal class assignments before the package runs. The manifest declares the plugin ID, version, SoAI compatibility requirement, dependencies, persistence and model behavior, capabilities, and compatible API feature flags. There is no separate JSON manifest. Values that require executing package code cannot establish admission identity.

The archive's SHA-256 hash identifies its prepared package cache, so changing archive bytes creates a separate cache entry. The Python environment belongs to the plugin ID and can be reused when its runtime baseline, declared dependencies, and installed packages still match. A different package hash does not by itself require rebuilding that environment.

SDK and dependency boundary

Plugin code can import the standard library, package-local modules, declared third-party dependencies, and public names from the top-level plugin_sdk package. It must not import Core implementation packages or plugin_sdk submodules. The top-level SDK is intentionally the complete public contract.

Declared dependencies are assessed against third-party imports before preparation. SoAI builds a plugin-specific Python environment rather than installing plugin dependencies into the host runtime. With PLUGINS.SECURITY.SAFETY_VALIDATION enabled, the source audit rejects direct Core imports and other prohibited import shapes before a worker starts.

Capabilities, catalog, and worker runtime

A plugin declares the capabilities it can provide, such as conversation inference, embeddings, speech, image work, or another supported media path. Its OpenAI-compatible feature flags describe the request fields and modalities implemented for that capability. Catalog models add their own capability and availability state. Dispatch therefore requires both a compatible plugin contract and a model that satisfies the requested operation.

The host owns request validation, catalog identity, routing, task state, public error projection, and protocol streaming. The worker owns plugin implementation and backend interaction. A plugin response crosses the proxy contract before it can become a public response or stream.

Catalog reconciliation

Reconciliation scans the configured package directory, compares on-disk packages with catalog records, inspects manifests and dependencies, evaluates host and version compatibility, resolves plugin dependency order, and reconciles configuration and model-parameter schemas. The reconciled catalog is authoritative for what can proceed to loading.

Package upload, download, deletion, cloning, configuration, and backend operations use task and transaction boundaries around their filesystem and database state. Startup recovery resolves interrupted owned operations before those artifacts are published as available. Partial archive or backend state is not treated as a successful installation.

Worker and IPC boundary

SoAI host process
      |
      | authenticated IPC
      v
plugin worker process
      |
      +-- optional local inference backend process
      `-- remote provider API

The worker and a local backend are separate roles. A plugin can manage an additional inference process, perform work in its worker, or connect to a remote provider, according to its capabilities. The host keeps scheduling and public API ownership across those arrangements.

Preparation leases the hash-addressed package cache and ensures the plugin environment is ready. The worker starts from an explicit bootstrap payload, imports the prepared package, validates the runtime class surface, and reports its callable contract. The host retains a proxy and validated static surface rather than the plugin object.

IPC authenticates the host-worker relationship and validates request and response payloads at both sides. Host services exposed to a worker are explicit IPC operations, not imports into application internals. A worker exit invalidates the proxy and releases runtime ownership without deleting the package or its catalog record.

State, trust, and source ownership

These axes can change independently: compatibility does not mean the backend is running, and a stopped worker does not mean the package is incompatible. Quarantine and an open circuit are different recovery mechanisms, which the public state projection combines without collapsing them into one generic plugin status.

Trust and failure boundary

Archive inspection, literal extraction, dependency checks, process separation, and authenticated IPC reduce the host surface and contain ordinary runtime failure. They do not turn third-party code into safely sandboxed code. The worker and any managed backend run with permissions available to the operating-system account that runs SoAI.

A worker crash, timeout, or provider failure is contained to the owning runtime and reported through plugin, task, and request state. A package integrity, schema, identity, or authorization failure blocks the affected operation before publication. Operators must treat a third-party plugin as host code and obtain it from a trusted source.

Runtime ownership map

• Archive inspection and package-audit services own archive structure, source inspection, and import validation.
• Manifest services own literal extraction, normalization, and dependency assessment.
• Package-preparation services own cache and plugin environments.
• Registry services own filesystem and catalog reconciliation.
• Loader and manager services own compatible loading, lifecycle, and public plugin state.
• Worker services own bootstrap, IPC, proxy validation, host services, and exit handling.
• Guardian services own health observation and recovery decisions.

Related documentation

• SoAI Core runtime architecture
• Plugins overview
• Creating a new plugin
• Plugin SDK reference
• Install and manage plugins
• Resilience and self-healing
• Security hardening