octantis-plugin-sdk

Plugin SDK for Octantis — the open-core, OTLP-native incident investigator.

This package defines the stable public contract between Octantis and plugin authors: six Protocol interfaces, shared data types, and the lifecycle they guarantee.

Octantis uses "Ingester" for its event-source Protocol, distinct from the OpenTelemetry Collector's "receiver" pipeline stage. An Ingester plugin lives inside the Octantis process and produces SDK Event instances.

• License: Apache-2.0 (permissive — your plugin is NOT obligated to be AGPL just because Octantis core is)
• Stability: semantic versioning. Breaking changes require a major bump.
• No runtime deps on Octantis core: depend on this SDK only.

Install

pip install octantis-plugin-sdk

Protocols

Octantis discovers plugins via six Python entry-point groups. Implement the matching Protocol and register under the matching group.

Minimal plugin example

# my_notifier/plugin.py
from octantis_plugin_sdk import Notifier, InvestigationResult

class MyNotifier:
    name = "my-notifier"
    version = "0.1.0"

    def setup(self, config: dict) -> None:
        self._url = config["webhook_url"]

    def teardown(self) -> None:
        pass

    async def send(self, result: InvestigationResult) -> None:
        ...

Register in your pyproject.toml:

[project.entry-points."octantis.notifiers"]
my-notifier = "my_notifier.plugin:MyNotifier"

Shared types

• Event — the canonical event passed through the pipeline.
• InvestigationResult — the output of an investigation workflow.
• Tool — an MCP tool exposed to the investigator.
• PluginMetadata — optional structured metadata a plugin may expose.

See the Protocol source files for the full contracts.

Tier limits

Octantis enforces plugin-count limits by license tier at load time:

Plugin installation is never blocked — only loading beyond your tier's limits is.