flukebase-sdk 0.1.0

SDK for developing FlukeBase plugins

FlukeBase SDK

SDK for developing FlukeBase plugins.

Installation

pip install flukebase-sdk

For development:

pip install flukebase-sdk[dev]

Quick Start

Create a plugin by extending BasePlugin:

from flukebase_sdk import (
    BasePlugin,
    PluginMetadata,
    PluginType,
    PluginMaturity,
    ToolDefinition,
    ToolAnnotations,
)


class MyPlugin(BasePlugin):
    @property
    def metadata(self) -> PluginMetadata:
        return PluginMetadata(
            name="my-awesome-plugin",
            version="1.0.0",
            description="Does awesome things",
            author="Your Name",
            plugin_type=PluginType.UTILITY,
            maturity=PluginMaturity.EXPERIMENTAL,
        )

    def get_tools(self) -> list[ToolDefinition]:
        return [
            ToolDefinition(
                name="do_awesome_thing",
                description="Performs an awesome operation",
                input_schema={
                    "type": "object",
                    "properties": {
                        "input": {"type": "string", "description": "Input value"}
                    },
                    "required": ["input"],
                },
                annotations=ToolAnnotations(
                    title="Do Awesome Thing",
                    read_only_hint=False,
                ),
            )
        ]

    async def initialize(self) -> None:
        # Set up your plugin
        pass

    async def shutdown(self) -> None:
        # Clean up resources
        pass

    async def handle_tool_call(self, tool_name: str, arguments: dict) -> any:
        if tool_name == "do_awesome_thing":
            return {"result": f"Processed: {arguments['input']}"}
        raise NotImplementedError(f"Unknown tool: {tool_name}")

API Reference

BasePlugin

Abstract base class that all plugins must inherit from.

Required Methods:

• metadata (property): Return PluginMetadata describing your plugin
• get_tools(): Return list of ToolDefinition objects
• initialize(): Async method called when plugin loads
• shutdown(): Async method called when plugin unloads

Optional Methods:

• handle_tool_call(tool_name, arguments): Handle tool invocations

PluginMetadata

Dataclass containing plugin information:

• name: Unique plugin identifier
• version: Semantic version string
• description: Brief description
• author: Plugin author
• plugin_type: One of PluginType enum values
• maturity: One of PluginMaturity enum values
• homepage: URL to plugin homepage
• documentation: URL to documentation
• tags: List of discovery tags
• min_sdk_version: Minimum required SDK version
• dependencies: List of plugin dependencies

ToolDefinition

Defines a tool provided by your plugin:

• name: Unique tool identifier
• description: What the tool does
• input_schema: JSON Schema for input validation
• annotations: ToolAnnotations with behavioral hints

ToolAnnotations

Hints for AI agents about tool behavior:

• title: Human-readable title
• read_only_hint: Tool doesn't modify state
• destructive_hint: Tool may cause irreversible changes
• idempotent_hint: Repeated calls have same effect
• open_world_hint: Tool interacts with external systems

ResourceDefinition

Defines a read-only resource:

• uri: Resource URI
• name: Human-readable name
• description: Resource description
• mime_type: Content MIME type

Testing

Use the MockPlugin for testing:

from flukebase_sdk.testing import MockPlugin

async def test_my_code():
    plugin = MockPlugin(name="test", version="1.0.0")
    await plugin.initialize()
    assert plugin.is_initialized

License

This SDK is released under the FlukeBase SDK License 1.0, a purpose-limited license designed to support plugin developers while protecting the FlukeBase ecosystem.

What You CAN Do

• Build plugins - Create plugins for the FlukeBase Platform for any purpose
• Sell your plugins - Distribute commercially through the Marketplace or independently
• Include SDK code - Use SDK components in your plugin as needed
• Modify for plugins - Adapt the SDK to fit your plugin's requirements

What You CANNOT Do

• Build competing platforms - Use the SDK to create alternatives to FlukeBase
• Extract interfaces - Copy protocols/interfaces for use in non-FlukeBase projects
• Redistribute standalone - Package the SDK as part of another SDK or framework
• Non-plugin use - Use the SDK for purposes other than FlukeBase plugin development

Your Plugin, Your Rights

You own your plugin code. The SDK license only covers SDK components - your business logic, integrations, and creative work remain entirely yours. You can license your plugins however you choose.

Why This License?

The SDK exposes internal architectural patterns and service contracts. This license ensures the SDK remains a tool for extending FlukeBase, not a blueprint for replicating it. Plugin developers get full commercial freedom; FlukeBase gets protection against clone platforms.

See the full LICENSE file for legal terms.