karcytics-sdk 2.0.0__tar.gz

karcytics_sdk-2.0.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: karcytics-sdk
+Version: 2.0.0
+Summary: Software Development Kit and CLI for Karcytics.
+Author: Kalaimaran Balasothy
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: PyQt6>=6.5.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: scikit-image>=0.26.0
+Requires-Dist: scipy
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+
+# 🔌 Karcytics SDK
+
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blueviolet?style=flat-square)](https://KalaimaranB.github.io/Karcytics-SDK/)
+[![CI Build Status](https://img.shields.io/github/actions/workflow/status/KalaimaranB/Karcytics-SDK/test_and_lint.yml?branch=main&style=flat-square&label=CI%20build)](https://github.com/KalaimaranB/Karcytics-SDK/actions)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/KalaimaranB/Karcytics-SDK/blob/main/LICENSE)
+
+The Software Development Kit (SDK) and Command-Line Interface (CLI) for building, validating, and signing plugins for the **Karcytics** desktop scientific suite.
+
+---
+
+## 🚀 Key Features
+
+- **Decoupled Architecture**: Build and test PyQt6-based scientific plugins independently of the main desktop app.
+- **Fail-Safe Dynamic Theme Fallbacks**: Visual components automatically load custom HSL-tailored colors when running standalone inside CI/CD test gates or external visualizers.
+- **Merkle-Tree Cryptographic Integrity**: Built-in Ed25519 signing and verification tools to secure user environments against remote execution and tampering.
+- **PyPI-Ready Packaging**: Complete declarative `pyproject.toml` config, built to publish natively under the `karcytics-sdk` package.
+
+---
+
+## 🛠️ Installation
+
+Install the SDK directly into your plugin's virtual environment:
+
+```bash
+pip install karcytics-sdk
+```
+
+*(Or during development, install in editable mode):*
+```bash
+git clone https://github.com/KalaimaranB/Karcytics-SDK.git
+cd Karcytics-SDK
+pip install -e .
+```
+
+---
+
+## 📦 Creating a Custom Karcytics Plugin
+
+To build a valid plugin, implement the `KarcyticsPlugin` interface and declare your entrypoints.
+
+### 1. `manifest.json`
+Every plugin must include a manifest file in its root directory:
+```json
+{
+  "id": "my_custom_plugin",
+  "name": "My Custom Plugin",
+  "version": "1.0.0",
+  "author": "Dr. Kalaimaran",
+  "description": "High-performance scientific analysis plugin.",
+  "category": "analysis",
+  "min_core_version": "1.0.0",
+  "entrypoint": "plugin:MyPluginClass"
+}
+```
+
+### 2. `plugin.py`
+```python
+from PyQt6.QtWidgets import QWidget, QVBoxLayout, QLabel
+from karcytics_sdk.core.interfaces import KarcyticsPlugin
+from karcytics_sdk.ui import PrimaryButton
+
+class MyPluginClass(KarcyticsPlugin):
+    """A professional-grade Karcytics plugin."""
+
+    def initialize(self) -> None:
+        self.logger.info("Initializing custom plugin...")
+
+    def create_panel(self, parent=None) -> QWidget:
+        panel = QWidget(parent)
+        layout = QVBoxLayout(panel)
+
+        title = QLabel("Welcome to Custom Analysis Panel")
+        btn = PrimaryButton("Execute Step")
+
+        layout.addWidget(title)
+        layout.addWidget(btn)
+        return panel
+```
+
+---
+
+## 🛡️ Cryptographic Trust Architecture
+
+Karcytics implements a professional-grade **Chain of Trust** to protect laboratory environments:
+
+```
+[ Root Authority ] (Hardcoded Core Key)
+       │
+       ▼ (signs)
+[ Developer Key ] (Dev Certificate)
+       │
+       ▼ (signs)
+[ Plugin Manifest ] (Ed25519 Signature + Merkle-Tree Hashes)
+```
+
+### 1. Generate Your Cryptographic Identity
+```bash
+karcytics-sdk setup-identity
+```
+- Local Private Key: `~/.karcytics/dev_private_key.pem`
+- Developer Certificate: `~/.karcytics/dev_cert.bin`
+
+### 2. Sign Your Plugin payload
+Calculates Merkle-hashes for all your files recursively, excludes development directories automatically, updates `manifest.json`, and writes `signature.bin`:
+```bash
+karcytics-sdk sign <path/to/plugin>
+```
+
+### 3. Modularity Compliance Check
+Verify your plugin matches QA and security standards:
+```bash
+karcytics-sdk evaluate <path/to/plugin>
+```
+
+---
+
+## 📘 Standalone Preview Support
+Since the SDK decouples all theme components from the desktop core using robust try-except fallbacks, you can instantiate and preview components standalone in development:
+
+```python
+import sys
+from PyQt6.QtWidgets import QApplication
+from karcytics_sdk.ui import PrimaryButton, WizardPanel
+
+app = QApplication(sys.argv)
+widget = WizardPanel()  # Renders beautifully even without the main app!
+widget.show()
+sys.exit(app.exec())
+```
+
+---
+
+## 📄 License
+This project is licensed under the MIT License.

karcytics_sdk-2.0.0/README.md

@@ -0,0 +1,134 @@
+# 🔌 Karcytics SDK
+
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blueviolet?style=flat-square)](https://KalaimaranB.github.io/Karcytics-SDK/)
+[![CI Build Status](https://img.shields.io/github/actions/workflow/status/KalaimaranB/Karcytics-SDK/test_and_lint.yml?branch=main&style=flat-square&label=CI%20build)](https://github.com/KalaimaranB/Karcytics-SDK/actions)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/KalaimaranB/Karcytics-SDK/blob/main/LICENSE)
+
+The Software Development Kit (SDK) and Command-Line Interface (CLI) for building, validating, and signing plugins for the **Karcytics** desktop scientific suite.
+
+---
+
+## 🚀 Key Features
+
+- **Decoupled Architecture**: Build and test PyQt6-based scientific plugins independently of the main desktop app.
+- **Fail-Safe Dynamic Theme Fallbacks**: Visual components automatically load custom HSL-tailored colors when running standalone inside CI/CD test gates or external visualizers.
+- **Merkle-Tree Cryptographic Integrity**: Built-in Ed25519 signing and verification tools to secure user environments against remote execution and tampering.
+- **PyPI-Ready Packaging**: Complete declarative `pyproject.toml` config, built to publish natively under the `karcytics-sdk` package.
+
+---
+
+## 🛠️ Installation
+
+Install the SDK directly into your plugin's virtual environment:
+
+```bash
+pip install karcytics-sdk
+```
+
+*(Or during development, install in editable mode):*
+```bash
+git clone https://github.com/KalaimaranB/Karcytics-SDK.git
+cd Karcytics-SDK
+pip install -e .
+```
+
+---
+
+## 📦 Creating a Custom Karcytics Plugin
+
+To build a valid plugin, implement the `KarcyticsPlugin` interface and declare your entrypoints.
+
+### 1. `manifest.json`
+Every plugin must include a manifest file in its root directory:
+```json
+{
+  "id": "my_custom_plugin",
+  "name": "My Custom Plugin",
+  "version": "1.0.0",
+  "author": "Dr. Kalaimaran",
+  "description": "High-performance scientific analysis plugin.",
+  "category": "analysis",
+  "min_core_version": "1.0.0",
+  "entrypoint": "plugin:MyPluginClass"
+}
+```
+
+### 2. `plugin.py`
+```python
+from PyQt6.QtWidgets import QWidget, QVBoxLayout, QLabel
+from karcytics_sdk.core.interfaces import KarcyticsPlugin
+from karcytics_sdk.ui import PrimaryButton
+
+class MyPluginClass(KarcyticsPlugin):
+    """A professional-grade Karcytics plugin."""
+
+    def initialize(self) -> None:
+        self.logger.info("Initializing custom plugin...")
+
+    def create_panel(self, parent=None) -> QWidget:
+        panel = QWidget(parent)
+        layout = QVBoxLayout(panel)
+
+        title = QLabel("Welcome to Custom Analysis Panel")
+        btn = PrimaryButton("Execute Step")
+
+        layout.addWidget(title)
+        layout.addWidget(btn)
+        return panel
+```
+
+---
+
+## 🛡️ Cryptographic Trust Architecture
+
+Karcytics implements a professional-grade **Chain of Trust** to protect laboratory environments:
+
+```
+[ Root Authority ] (Hardcoded Core Key)
+       │
+       ▼ (signs)
+[ Developer Key ] (Dev Certificate)
+       │
+       ▼ (signs)
+[ Plugin Manifest ] (Ed25519 Signature + Merkle-Tree Hashes)
+```
+
+### 1. Generate Your Cryptographic Identity
+```bash
+karcytics-sdk setup-identity
+```
+- Local Private Key: `~/.karcytics/dev_private_key.pem`
+- Developer Certificate: `~/.karcytics/dev_cert.bin`
+
+### 2. Sign Your Plugin payload
+Calculates Merkle-hashes for all your files recursively, excludes development directories automatically, updates `manifest.json`, and writes `signature.bin`:
+```bash
+karcytics-sdk sign <path/to/plugin>
+```
+
+### 3. Modularity Compliance Check
+Verify your plugin matches QA and security standards:
+```bash
+karcytics-sdk evaluate <path/to/plugin>
+```
+
+---
+
+## 📘 Standalone Preview Support
+Since the SDK decouples all theme components from the desktop core using robust try-except fallbacks, you can instantiate and preview components standalone in development:
+
+```python
+import sys
+from PyQt6.QtWidgets import QApplication
+from karcytics_sdk.ui import PrimaryButton, WizardPanel
+
+app = QApplication(sys.argv)
+widget = WizardPanel()  # Renders beautifully even without the main app!
+widget.show()
+sys.exit(app.exec())
+```
+
+---
+
+## 📄 License
+This project is licensed under the MIT License.

karcytics_sdk-2.0.0/pyproject.toml

@@ -0,0 +1,112 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "karcytics-sdk"
+version = "2.0.0"
+description = "Software Development Kit and CLI for Karcytics."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "Kalaimaran Balasothy" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "cryptography>=41.0.0",
+    "msgpack>=1.0.0",
+    "numpy",
+    "pandas",
+    "pillow>=12.3.0",
+    "PyQt6>=6.5.0",
+    "requests>=2.28.0",
+    "scikit-image>=0.26.0",
+    "scipy",
+]
+
+[project.optional-dependencies]
+docs = [
+    "mkdocs-material",
+    "mkdocstrings[python]",
+]
+
+[project.scripts]
+karcytics-sdk = "karcytics_sdk.cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+karcytics_sdk = ["py.typed"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --tb=short --cov=src/karcytics_sdk --cov-report=term-missing --cov-report=html --cov-fail-under=45"
+testpaths = ["tests"]
+pythonpath = ["src"]
+filterwarnings = [
+    "ignore:.*PyQt6.*:DeprecationWarning",
+]
+
+[tool.coverage.run]
+source = ["src/karcytics_sdk"]
+omit = [
+    "*/__init__.py",
+]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W",  # Pyflakes & pycodestyle
+    "I",            # isort (import sorting)
+    "UP",           # pyupgrade
+    "B",            # flake8-bugbear
+    "D",            # pydocstyle
+    "C90",          # mccabe complexity
+    "PLR",          # pylint refactoring (complexity)
+]
+ignore = [
+    "E501",  # Line too long (handled by formatting standards)
+    "E722",  # Bare excepts (utilised in AI connection retry fallbacks)
+    "D100",  # Missing docstring in public module
+    "D101",  # Missing docstring in public class (redundant for UI colors/fallback classes)
+    "D102",  # Missing docstring in public method (redundant for standard UI properties/callbacks)
+    "D103",  # Missing docstring in public function
+    "D104",  # Missing docstring in public package
+    "D105",  # Missing docstring in magic method (redundant by standard definition)
+    "D106",  # Missing docstring in public nested class
+    "D107",  # Missing docstring in __init__ (covered by class docstring)
+    "D205",  # 1 blank line between summary and description
+    "B024",  # ABC with no abstract methods (perfectly valid for base data/state models)
+    "B027",  # Empty hooks in ABCs without abstract decorator (standard custom override hook pattern)
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PLR2004", "PLR0913", "PLR0915", "PLR0917"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = false
+check_untyped_defs = false
+ignore_missing_imports = true
+disable_error_code = ["assignment", "union-attr", "call-arg", "no-any-return", "method-assign", "misc", "no-redef"]
+files = "src"

karcytics_sdk-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

karcytics_sdk-2.0.0/src/karcytics_sdk/__init__.py

@@ -0,0 +1,10 @@
+"""Karcytics SDK — Software Development Kit for Karcytics desktop plugins.
+
+Provides two main namespaces:
+    - plugin: Clean API for plugin development with zero unnecessary dependencies.
+    - host: Host-facing APIs for the Core application and SDK signing CLI.
+"""
+
+from . import host, interfaces, plugin
+
+__all__ = ["plugin", "host", "interfaces"]

karcytics_sdk-2.0.0/src/karcytics_sdk/cli/commands/diagnostics.py

@@ -0,0 +1,81 @@
+def setup_diagnostics_parser(subparsers):
+    # Command: sbom
+    sbom_parser = subparsers.add_parser("sbom", help="Generates and prints the SBOM in the specified format.")
+    sbom_parser.add_argument(
+        "--format", type=str, choices=["--json", "--markdown"], default="--markdown", help="Output format"
+    )
+    sbom_parser.set_defaults(func=generate_sbom)
+
+    # Command: evaluate
+    eval_parser = subparsers.add_parser("evaluate", help="Perform comprehensive CLI evaluation of a plugin.")
+    eval_parser.add_argument("plugin_dir", type=str, help="Path to the plugin directory.")
+    eval_parser.set_defaults(func=evaluate_plugin)
+
+    # Command: doctor
+    doctor_parser = subparsers.add_parser("doctor", help="Evaluate a plugin against new SDK architecture.")
+    doctor_parser.add_argument("plugin_dir", type=str, help="Path to the plugin directory.")
+    doctor_parser.set_defaults(func=doctor_plugin)
+
+
+def generate_sbom(args) -> bool:
+    """Generates and prints the SBOM in the specified format."""
+    try:
+        import importlib
+
+        karcytics_core_sbom = importlib.import_module("karcytics.core.sbom")
+        generator = karcytics_core_sbom.SBOMGenerator()
+
+        if args.format == "--json":
+            print(generator.to_json())
+        else:
+            print(generator.to_markdown())
+        return True
+    except ImportError:
+        print("ERROR: SBOM generation is only supported when running inside the Karcytics main application.")
+        return False
+
+
+def evaluate_plugin(args) -> bool:
+    """Perform comprehensive CLI evaluation of a plugin."""
+    import logging
+    import sys
+    from pathlib import Path
+
+    from PyQt6.QtWidgets import QApplication
+
+    from karcytics_sdk.plugin.manifest_parser import ManifestParser
+
+    print("Running Plugin Diagnostics Evaluator (evaluate)...")
+    _app = QApplication.instance() or QApplication(sys.argv)
+    logging.basicConfig(level=logging.INFO)
+
+    try:
+        parser = ManifestParser()
+        manifest = parser.parse_file(str(Path(args.plugin_dir) / "pyproject.toml"))
+        print(f"Manifest parsed successfully: {manifest.get('id')} v{manifest.get('version')}")
+
+        dependencies = manifest.get("python_dependencies") or manifest.get("dependencies", {})
+        if dependencies:
+            print("Auditing Plugin Dependencies...")
+            all_pinned = True
+            for dep, version in dependencies.items():
+                if any(c in version for c in (">", "<", "*", "^", "~")):
+                    print(f"WARNING: Dependency '{dep}' is not pinned. Recommend exact pinning.")
+                    all_pinned = False
+                else:
+                    print(f"Dependency '{dep}' is pinned to version '{version}'")
+
+            if all_pinned:
+                print("All declared dependencies are securely pinned.")
+
+        return True
+    except Exception as e:
+        print(f"Evaluation failed: {e}")
+        return False
+
+
+def doctor_plugin(args) -> bool:
+    """Evaluate a plugin against new SDK architecture (plugin.toml, strict imports)."""
+    print(f"Running Plugin Conformance Evaluator (doctor) on {args.plugin_dir}...")
+    print("Note: Scaffolded for Phase 1. Full static/runtime checks to be implemented.")
+    return True

karcytics_sdk-2.0.0/src/karcytics_sdk/cli/commands/migrate.py

@@ -0,0 +1,112 @@
+import json
+from pathlib import Path
+
+
+def setup_migrate_parser(subparsers):
+    # Command: migrate
+    migrate_parser = subparsers.add_parser("migrate", help="Migrate a legacy plugin to the new architecture.")
+    migrate_parser.add_argument("plugin_dir", type=str, help="Path to the plugin directory.")
+    migrate_parser.set_defaults(func=migrate_plugin)
+
+
+def migrate_plugin(args) -> bool:  # noqa: C901
+    """Migrate a legacy plugin to the new architecture (pyproject.toml, src/ layout)."""
+    print(f"Migrating legacy plugin at {args.plugin_dir} to new SDK architecture...")
+
+    p_dir = Path(args.plugin_dir)
+    manifest_path = p_dir / "manifest.json"
+
+    if not manifest_path.exists():
+        print("ERROR: manifest.json not found. This doesn't look like a valid legacy plugin.")
+        return False
+
+    with open(manifest_path, encoding="utf-8") as f:
+        manifest_data = json.load(f)
+
+    plugin_id = manifest_data.get("id", p_dir.name.lower().replace("-", "_").replace(" ", "_"))
+
+    # 1. Generate pyproject.toml
+    print("1. Creating pyproject.toml and deprecating manifest.json...")
+
+    toml_path = p_dir / "pyproject.toml"
+
+    # Extract dependencies
+    dependencies_str = ""
+    if "python_dependencies" in manifest_data:
+        for dep, ver in manifest_data["python_dependencies"].items():
+            dependencies_str += f'    "{dep}{ver}",\n'
+
+    # Build authors block for project
+    project_authors = ""
+    if "authors" in manifest_data:
+        for author in manifest_data["authors"]:
+            name = author.get("name", "Unknown")
+            project_authors += f'    {{ name = "{name}" }},\n'
+
+    # Build authors block for plugin
+    plugin_authors = ""
+    if "authors" in manifest_data:
+        for author in manifest_data["authors"]:
+            name = author.get("name", "Unknown")
+            role = author.get("role", "Developer")
+            perms_str = json.dumps(author.get("permissions", []))
+            plugin_authors += f'    {{ name = "{name}", role = "{role}", permissions = {perms_str} }},\n'
+
+    clean_project_authors = project_authors.rstrip(",\\n")
+    clean_deps = dependencies_str.rstrip(",\\n")
+    clean_plugin_authors = plugin_authors.rstrip(",\\n")
+    reqs_json = json.dumps(manifest_data.get("requires", ["task_scheduler", "logger", "event_bus"]))
+
+    toml_content = f'''[project]
+name = "{manifest_data.get("name", p_dir.name.title())}"
+version = "{manifest_data.get("version", "1.0.0")}"
+description = "{manifest_data.get("description", "")}"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+{clean_project_authors}
+]
+dependencies = [
+{clean_deps}
+]
+
+[tool.biopro.plugin]
+id = "{plugin_id}"
+min_core_version = "{manifest_data.get("min_core_version", "1.4.9")}"
+entry_point = "biopro_plugins.{plugin_id}:initialize"
+requires = {reqs_json}
+authors = [
+{clean_plugin_authors}
+]
+'''
+    with open(toml_path, "w", encoding="utf-8") as f:
+        f.write(toml_content)
+
+    print(
+        "   -> Renaming manifest.json to manifest.json.deprecated (DO NOT DELETE yet, the core still uses it internally!)"
+    )
+    manifest_path.rename(p_dir / "manifest.json.deprecated")
+
+    # 2. Setup src structure
+    print("2. Restructuring python files into src/...")
+    src_dir = p_dir / "src"
+    src_dir.mkdir(exist_ok=True)
+
+    plugin_pkg_dir = src_dir / "biopro_plugins" / plugin_id
+    plugin_pkg_dir.mkdir(parents=True, exist_ok=True)
+
+    # Move all .py files except setup.py to the new package directory
+    py_files_moved = 0
+    for file in p_dir.glob("*.py"):
+        if file.name not in {"setup.py", "conftest.py"}:
+            print(f"   -> Moving {file.name} to {plugin_pkg_dir.relative_to(p_dir)}")
+            file.rename(plugin_pkg_dir / file.name)
+            py_files_moved += 1
+
+    if py_files_moved == 0:
+        # Create an empty __init__.py if no files were moved
+        (plugin_pkg_dir / "__init__.py").touch()
+
+    print("\n✅ Migration complete! Please verify your imports in the new src/biopro_plugins/ folder.")
+    print("Run 'karcytics-sdk sign .' to sign the new structure.")
+    return True