Skip to content

State & Config

karcytics_sdk.plugin.state

Plugin state management for Karcytics SDK.

Provides base class for plugin state that integrates with Karcytics's undo/redo history system. Enables serialization and deserialization of plugin states for workflow persistence.

PluginState dataclass

Bases: ABC

Base state class for plugin analysis state.

Subclass this in your plugin and use @dataclass for automatic serialization. Enables undo/redo integration via Karcytics's HistoryManager.

All fields in your state should be simple types (str, int, float, list, dict) to ensure proper serialization. Complex objects should be stored as paths or serializable representations.

This class strictly prevents dynamic attribute assignment. All attributes must be declared as fields in the subclass dataclass.

Source code in src/karcytics_sdk/plugin/state.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
@dataclass
class PluginState(ABC):
    """Base state class for plugin analysis state.

    Subclass this in your plugin and use @dataclass for automatic serialization.
    Enables undo/redo integration via Karcytics's HistoryManager.

    All fields in your state should be simple types (str, int, float, list, dict)
    to ensure proper serialization. Complex objects should be stored as paths
    or serializable representations.

    This class strictly prevents dynamic attribute assignment. All attributes
    must be declared as fields in the subclass dataclass.
    """

    def __setattr__(self, name: str, value: Any) -> None:
        fields = getattr(type(self), "__dataclass_fields__", {})
        if name not in fields and not hasattr(self, name):
            raise AttributeError(
                f"'{type(self).__name__}' object has no attribute '{name}'. "
                "Dynamic attribute assignment is strictly prohibited on PluginState objects."
            )
        super().__setattr__(name, value)

    def to_dict(self) -> dict[str, Any]:
        """Convert state to dictionary for serialization.

        Returns:
            Dictionary representation of the state
        """
        return asdict(self)

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> PluginState:
        """Reconstruct state from dictionary.

        Args:
            data: Dictionary previously produced by to_dict()

        Returns:
            New instance of this state class
        """
        return cls(**data)

from_dict(data) classmethod

Reconstruct state from dictionary.

Parameters:

Name Type Description Default
data dict[str, Any]

Dictionary previously produced by to_dict()

 required

Returns:

Type Description
PluginState

New instance of this state class
Source code in src/karcytics_sdk/plugin/state.py 
47
48
49
50
51
52
53
54
55
56
57
@classmethod
def from_dict(cls, data: dict[str, Any]) -> PluginState:
    """Reconstruct state from dictionary.

    Args:
        data: Dictionary previously produced by to_dict()

    Returns:
        New instance of this state class
    """
    return cls(**data)

to_dict()

Convert state to dictionary for serialization.

Returns:

Type Description
dict[str, Any]

Dictionary representation of the state
Source code in src/karcytics_sdk/plugin/state.py 
39
40
41
42
43
44
45
def to_dict(self) -> dict[str, Any]:
    """Convert state to dictionary for serialization.

    Returns:
        Dictionary representation of the state
    """
    return asdict(self)

karcytics_sdk.plugin.io

File I/O utilities for Karcytics SDK.

Provides convenient wrappers for JSON serialization and configuration management for plugins.

PluginConfig

Bases: PreferenceManagerProtocol

Simple configuration management for plugins.

Stores settings in JSON in ~/.karcytics/plugin_configs/{plugin_id}.json

This is useful for persisting user settings across sessions, like the last used parameters or paths.

One instance per plugin_id per process (see __new__): two independent PluginConfig objects for the same plugin would each cache their own snapshot of the JSON file in .data, and whichever calls .save() last would silently overwrite the other's unsaved changes with its own stale snapshot. A plugin's own config wrapper (e.g. a FlowConfig holding PluginConfig("flow_cytometry")) and any SDK feature that also reaches for PluginConfig(same_plugin_id) — the workflow-autosave preference, for instance — now always share the exact same object and .data dict.

Example

config = PluginConfig('my_plugin') config.set('threshold', 0.5) config.set('last_image_dir', '/path/to/images') threshold = config.get('threshold', default=0.0) config.save()

Source code in src/karcytics_sdk/plugin/io.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
class PluginConfig(PreferenceManagerProtocol):
    """Simple configuration management for plugins.

    Stores settings in JSON in ~/.karcytics/plugin_configs/{plugin_id}.json

    This is useful for persisting user settings across sessions, like
    the last used parameters or paths.

    One instance per `plugin_id` per process (see `__new__`): two independent
    `PluginConfig` objects for the same plugin would each cache their own
    snapshot of the JSON file in `.data`, and whichever calls `.save()` last
    would silently overwrite the other's unsaved changes with its own stale
    snapshot. A plugin's own config wrapper (e.g. a `FlowConfig` holding
    `PluginConfig("flow_cytometry")`) and any SDK feature that also reaches
    for `PluginConfig(same_plugin_id)` — the workflow-autosave preference,
    for instance — now always share the exact same object and `.data` dict.

    Example:
        >>> config = PluginConfig('my_plugin')
        >>> config.set('threshold', 0.5)
        >>> config.set('last_image_dir', '/path/to/images')
        >>> threshold = config.get('threshold', default=0.0)
        >>> config.save()
    """

    _instances: dict[str, "PluginConfig"] = {}

    def __new__(cls, plugin_id: str) -> "PluginConfig":
        instance = cls._instances.get(plugin_id)
        if instance is None:
            instance = super().__new__(cls)
            cls._instances[plugin_id] = instance
        return instance

    def __init__(self, plugin_id: str):
        """Initialize config manager.

        Args:
            plugin_id: Unique plugin identifier (used for filename)
        """
        if getattr(self, "_initialized", False):
            return
        self.plugin_id = plugin_id
        self.config_dir = Path.home() / ".karcytics" / "plugin_configs"
        self.config_file = self.config_dir / f"{plugin_id}.json"
        self.data: dict[str, Any] = {}
        self.load()
        self._initialized = True

    def load(self) -> None:
        """Load config from disk.

        Called automatically in __init__. Call again to reload from disk.
        """
        if self.config_file.exists():
            try:
                self.data = load_json(str(self.config_file))
            except Exception as e:
                logger.warning(f"Failed to load config for {self.plugin_id}: {e}")
                self.data = {}
        else:
            self.data = {}

    def save(self) -> None:
        """Save config to disk.

        Raises:
            IOError: If file cannot be written
        """
        try:
            save_json(str(self.config_file), self.data)
        except Exception as e:
            logger.error(f"Failed to save config for {self.plugin_id}: {e}")

    def set(self, key: str, value: Any) -> None:
        """Set a configuration value.

        Args:
            key: Configuration key
            value: Configuration value (should be JSON-serializable)
        """
        self.data[key] = value

    def get(self, key: str, default: Any = None) -> Any:
        """Get a configuration value.

        Args:
            key: Configuration key
            default: Value to return if key doesn't exist

        Returns:
            Configuration value or default
        """
        return self.data.get(key, default)

    def has(self, key: str) -> bool:
        """Check if a key exists.

        Args:
            key: Configuration key

        Returns:
            True if key exists
        """
        return key in self.data

    def clear(self) -> None:
        """Clear all config values (does not delete file until save())."""
        self.data.clear()

    def __getitem__(self, key: str):
        """Get value using dictionary syntax."""
        return self.data[key]

    def __setitem__(self, key: str, value: Any):
        """Set value using dictionary syntax."""
        self.data[key] = value

__getitem__(key)

Get value using dictionary syntax.

Source code in src/karcytics_sdk/plugin/io.py 
180
181
182
def __getitem__(self, key: str):
    """Get value using dictionary syntax."""
    return self.data[key]

__init__(plugin_id)

Initialize config manager.

Parameters:

Name Type Description Default
plugin_id str

Unique plugin identifier (used for filename)

 required
Source code in src/karcytics_sdk/plugin/io.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def __init__(self, plugin_id: str):
    """Initialize config manager.

    Args:
        plugin_id: Unique plugin identifier (used for filename)
    """
    if getattr(self, "_initialized", False):
        return
    self.plugin_id = plugin_id
    self.config_dir = Path.home() / ".karcytics" / "plugin_configs"
    self.config_file = self.config_dir / f"{plugin_id}.json"
    self.data: dict[str, Any] = {}
    self.load()
    self._initialized = True

__setitem__(key, value)

Set value using dictionary syntax.

Source code in src/karcytics_sdk/plugin/io.py 
184
185
186
def __setitem__(self, key: str, value: Any):
    """Set value using dictionary syntax."""
    self.data[key] = value

clear()

Clear all config values (does not delete file until save()).

Source code in src/karcytics_sdk/plugin/io.py 
176
177
178
def clear(self) -> None:
    """Clear all config values (does not delete file until save())."""
    self.data.clear()

get(key, default=None)

Get a configuration value.

Parameters:

Name Type Description Default
key str

Configuration key

 required
default Any

Value to return if key doesn't exist

 None

Returns:

Type Description
Any

Configuration value or default
Source code in src/karcytics_sdk/plugin/io.py 
153
154
155
156
157
158
159
160
161
162
163
def get(self, key: str, default: Any = None) -> Any:
    """Get a configuration value.

    Args:
        key: Configuration key
        default: Value to return if key doesn't exist

    Returns:
        Configuration value or default
    """
    return self.data.get(key, default)

has(key)

Check if a key exists.

Parameters:

Name Type Description Default
key str

Configuration key

 required

Returns:

Type Description
bool

True if key exists
Source code in src/karcytics_sdk/plugin/io.py 
165
166
167
168
169
170
171
172
173
174
def has(self, key: str) -> bool:
    """Check if a key exists.

    Args:
        key: Configuration key

    Returns:
        True if key exists
    """
    return key in self.data

load()

Load config from disk.

Called automatically in init. Call again to reload from disk.

Source code in src/karcytics_sdk/plugin/io.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
def load(self) -> None:
    """Load config from disk.

    Called automatically in __init__. Call again to reload from disk.
    """
    if self.config_file.exists():
        try:
            self.data = load_json(str(self.config_file))
        except Exception as e:
            logger.warning(f"Failed to load config for {self.plugin_id}: {e}")
            self.data = {}
    else:
        self.data = {}

save()

Save config to disk.

Raises:

Type Description
IOError

If file cannot be written
Source code in src/karcytics_sdk/plugin/io.py 
133
134
135
136
137
138
139
140
141
142
def save(self) -> None:
    """Save config to disk.

    Raises:
        IOError: If file cannot be written
    """
    try:
        save_json(str(self.config_file), self.data)
    except Exception as e:
        logger.error(f"Failed to save config for {self.plugin_id}: {e}")

set(key, value)

Set a configuration value.

Parameters:

Name Type Description Default
key str

Configuration key

 required
value Any

Configuration value (should be JSON-serializable)

 required
Source code in src/karcytics_sdk/plugin/io.py 
144
145
146
147
148
149
150
151
def set(self, key: str, value: Any) -> None:
    """Set a configuration value.

    Args:
        key: Configuration key
        value: Configuration value (should be JSON-serializable)
    """
    self.data[key] = value

get_plugin_logger(plugin_id)

Get a logger for a plugin.

Parameters:

Name Type Description Default
plugin_id str

Plugin identifier

 required

Returns:

Type Description
Logger

Configured logger with plugin name prefixed to 'karcytics.plugins'
Example

logger = get_plugin_logger("my_plugin") logger.info("Plugin initialized") # Logs to "karcytics.plugins.my_plugin"

Source code in src/karcytics_sdk/plugin/io.py 
197
198
199
200
201
202
203
204
205
206
207
208
209
210
def get_plugin_logger(plugin_id: str) -> logging.Logger:
    """Get a logger for a plugin.

    Args:
        plugin_id: Plugin identifier

    Returns:
        Configured logger with plugin name prefixed to 'karcytics.plugins'

    Example:
        >>> logger = get_plugin_logger("my_plugin")
        >>> logger.info("Plugin initialized")  # Logs to "karcytics.plugins.my_plugin"
    """
    return logging.getLogger(f"karcytics.plugins.{plugin_id}")

load_json(path)

Load JSON from file.

Parameters:

Name Type Description Default
path str

File path

 required

Returns:

Type Description
dict[str, Any]

Parsed JSON dictionary

Raises:

Type Description
FileNotFoundError

If file doesn't exist
JSONDecodeError

If JSON is invalid
Source code in src/karcytics_sdk/plugin/io.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
def load_json(path: str) -> dict[str, Any]:
    """Load JSON from file.

    Args:
        path: File path

    Returns:
        Parsed JSON dictionary

    Raises:
        FileNotFoundError: If file doesn't exist
        json.JSONDecodeError: If JSON is invalid
    """
    with open(path) as f:
        return json.load(f)

read_binary(path)

Read binary data from a file.

Source code in src/karcytics_sdk/plugin/io.py 
52
53
54
55
def read_binary(path: Path | str) -> bytes:
    """Read binary data from a file."""
    with open(path, "rb") as f:
        return f.read()

save_json(path, data, pretty=True)

Save JSON to file.

Parameters:

Name Type Description Default
path str

File path

 required
data dict[str, Any]

Dictionary to save

 required
pretty bool

If True, indent for readability (2 spaces)

 True
Source code in src/karcytics_sdk/plugin/io.py 
39
40
41
42
43
44
45
46
47
48
49
def save_json(path: str, data: dict[str, Any], pretty: bool = True) -> None:
    """Save JSON to file.

    Args:
        path: File path
        data: Dictionary to save
        pretty: If True, indent for readability (2 spaces)
    """
    Path(path).parent.mkdir(parents=True, exist_ok=True)
    with open(path, "w") as f:
        json.dump(data, f, indent=2 if pretty else None)

write_binary(path, data)

Write binary data to a file.

Source code in src/karcytics_sdk/plugin/io.py 
58
59
60
61
62
def write_binary(path: Path | str, data: bytes) -> None:
    """Write binary data to a file."""
    Path(path).parent.mkdir(parents=True, exist_ok=True)
    with open(path, "wb") as f:
        f.write(data)

karcytics_sdk.plugin.preferences

Preference Manager Interface for Karcytics SDK.

PreferenceManagerProtocol

Bases: Protocol

Standardized interface for preference management.

This interface ensures that both the Core application and SDK plugins have a unified way to interact with preferences, adhering to the Dependency Inversion Principle (DIP).

Source code in src/karcytics_sdk/plugin/preferences.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
@runtime_checkable
class PreferenceManagerProtocol(Protocol):
    """Standardized interface for preference management.

    This interface ensures that both the Core application and SDK plugins
    have a unified way to interact with preferences, adhering to the
    Dependency Inversion Principle (DIP).
    """

    def load(self) -> None:
        """Load preferences from storage."""
        ...

    def save(self) -> None:
        """Save preferences to storage."""
        ...

    def set(self, key: str, value: Any) -> None:
        """Set a configuration value."""
        ...

    def get(self, key: str, default: Any = None) -> Any:
        """Get a configuration value."""
        ...

    def has(self, key: str) -> bool:
        """Check if a key exists."""
        ...

    def clear(self) -> None:
        """Clear all preference values."""
        ...

clear()

Clear all preference values.

Source code in src/karcytics_sdk/plugin/preferences.py 
35
36
37
def clear(self) -> None:
    """Clear all preference values."""
    ...

get(key, default=None)

Get a configuration value.

Source code in src/karcytics_sdk/plugin/preferences.py 
27
28
29
def get(self, key: str, default: Any = None) -> Any:
    """Get a configuration value."""
    ...

has(key)

Check if a key exists.

Source code in src/karcytics_sdk/plugin/preferences.py 
31
32
33
def has(self, key: str) -> bool:
    """Check if a key exists."""
    ...

load()

Load preferences from storage.

Source code in src/karcytics_sdk/plugin/preferences.py 
15
16
17
def load(self) -> None:
    """Load preferences from storage."""
    ...

save()

Save preferences to storage.

Source code in src/karcytics_sdk/plugin/preferences.py 
19
20
21
def save(self) -> None:
    """Save preferences to storage."""
    ...

set(key, value)

Set a configuration value.

Source code in src/karcytics_sdk/plugin/preferences.py 
23
24
25
def set(self, key: str, value: Any) -> None:
    """Set a configuration value."""
    ...