Metadata-Version: 2.4
Name: flukebase-sdk
Version: 0.1.0
Summary: SDK for developing FlukeBase plugins
Project-URL: Homepage, https://github.com/flukebase/flukebase-sdk
Project-URL: Documentation, https://docs.flukebase.com/sdk
Project-URL: Repository, https://github.com/flukebase/flukebase-sdk
Project-URL: Issues, https://github.com/flukebase/flukebase-sdk/issues
Project-URL: Changelog, https://github.com/flukebase/flukebase-sdk/blob/main/CHANGELOG.md
Author-email: FlukeBase <sdk@flukebase.com>
License: FlukeBase SDK License 1.0
License-File: LICENSE
Keywords: ai,flukebase,mcp,plugin,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: cli
Requires-Dist: rich>=13.0.0; extra == 'cli'
Requires-Dist: tomli>=2.0.0; extra == 'cli'
Requires-Dist: typer>=0.12.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: rich>=13.0.0; extra == 'dev'
Requires-Dist: ruff>=0.2.0; extra == 'dev'
Requires-Dist: tomli>=2.0.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Requires-Dist: typer>=0.12.0; extra == 'dev'
Description-Content-Type: text/markdown

# FlukeBase SDK

SDK for developing FlukeBase plugins.

## Installation

```bash
pip install flukebase-sdk
```

For development:

```bash
pip install flukebase-sdk[dev]
```

## Quick Start

Create a plugin by extending `BasePlugin`:

```python
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:

```python
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](LICENSE) file for legal terms.
