Extensibility

Open-Core Model

Kavach OSS is the immutable, authoritative core. An extension package depends on a released Kavach version and contributes behavior only through contracts that OSS owns. The dependency direction is always extension to Kavach; core code does not import, detect, or branch on a particular enterprise distribution.

Public Surface

Extensions import only the supported public packages:

• kavach.spi for provider contracts such as search and evaluation.
• kavach.plugins for metadata, lifecycle, providers, and routes.
• kavach.hooks for ordered workflow interception points.
• kavach.events for versioned domain-event subscriptions.

These contracts receive tenant context explicitly. Plugin code must not reconstruct tenancy from environment variables or process-wide state.

Plugin Package

Register an installed plugin with standard Python package metadata. Pin the compatible OSS range so upgrades are intentional and testable.

# kavach-enterprise/pyproject.toml
[project]
dependencies = ["kavach>=1.2,<1.3"]

[project.entry-points."kavach.plugins"]
enterprise-quality = "kavach_enterprise.plugins.quality:QualityPlugin"

At application creation, Kavach discovers registered entry points, checks their compatibility and declared capabilities, then validates and registers their contributions before serving traffic.

Extension Modes

• Add — add a new provider, API route, connector, or event subscriber.
• Replace — explicitly replace an OSS-declared provider contract.
• Decorate — wrap a selected provider through composition for authorization, metering, ranking, or audit behavior.
• Subscribe — react to a versioned domain event without changing its producer.

from kavach.plugins import PluginMetadata
from kavach.spi.search import SearchProvider

class QualityPlugin:
    metadata = PluginMetadata(
        name="quality-plugin",
        version="1.0.0",
        required_kavach_version=">=1.2,<1.3",
        capabilities=("search.read",),
    )

    def register(self, context):
        context.providers.register(SearchProvider, EnterpriseSearch(), replace=True)

Lifecycle and Safety

A plugin declares immutable metadata, validates its own configuration, registers contributions, starts after the application is composed, and stops in reverse registration order during shutdown. Duplicate plugin names, unsupported capabilities, incompatible versions, ambiguous provider ownership, and conflicting routes fail startup.

Hooks and event subscriptions execute deterministically by declared order and registration order. Hooks declare failure policy, timeout, and retries. A failed FAIL_CLOSED hook stops the producer; isolated subscribers can record a failure without destabilizing core execution.

Runtime Diagnostics

Operators with settings-read access can inspect the resolved runtime at GET /api/v1/runtime/extensions. The endpoint reports registered plugins, compatibility and lifecycle status, selected provider owners, decorators, hook order, event subscriptions, route claims, and recent outcomes. It deliberately excludes concrete implementation objects, credentials, and plugin-private configuration.