luvmagiToolKits

luvmagiToolKits is a modular Python toolkit.

The current public release includes:

• json_diff: compare two JSON-serializable documents and write JSON or Markdown reports
• decotextual: a decorator-driven helper layer for building small Textual-based tool panels quickly
• wbs: WBS-oriented helpers that depend on the wbs extra

Installation

Install the lightweight base package:

pip install luvmagitoolkits

The base install is intended for dependency-light modules such as json_diff.

Install the Textual TUI helpers:

pip install "luvmagitoolkits[tui]"

Install the WBS helpers:

pip install "luvmagitoolkits[wbs]"

Install every optional dependency:

pip install "luvmagitoolkits[all]"

Upgrade the package:

pip install -U luvmagitoolkits

What json_diff Provides

• Structured diffs for dictionaries, lists, and nested JSON-like payloads.
• Configurable array matching by key, inferred key, hash, or index.
• JSON and Markdown output writers with explicit encoding parameters.

What decotextual Provides

• A class decorator to register tools into a navigable tree.
• A method decorator to define labels, descriptions, and placeholders.
• A simple Linear(...) helper for select-style choices.
• A ready-to-run Textual application launcher with run_tui().

run_tui() requires the tui extra.

Quick Start

from pathlib import Path

from luvmagitoolkits.decotextual import Linear, register_tool, run_tui, tool_method


@register_tool(category="File Tools", tool_name="File Utilities")
class FileTool:
    @tool_method(
        name="Read File",
        description="Read a file and return the first N lines",
        placeholders={
            "file_path": "Full path, e.g. ./demo.txt",
            "tags": "One tag per line, or comma-separated",
        },
    )
    def read_file(self, file_path: Path, line_count: int = 20, tags: list | None = None):
        print(f"Reading {file_path} - first {line_count} lines")
        if tags:
            print(f"Tags: {tags}")
        return "Done"

    @tool_method(
        name="Batch Rename",
        description="Batch rename files in a directory",
        placeholders={"directory": "Target directory path"},
    )
    def batch_rename(
        self,
        directory: Path,
        prefix: str = "file_",
        mode: Linear = Linear("Sequential", "Timestamp", "MD5"),
    ):
        print(f"Scanning: {directory}")
        print(f"Prefix: {prefix}, Mode: {mode}")
        return "Rename complete"


if __name__ == "__main__":
    run_tui()

Release Status

• Package version: 0.1.1
• Stability: alpha
• Recommended audience: early adopters and internal experimentation

Roadmap

• Expand the decotextual examples and tests.
• Add module-specific documentation under docs/.
• Gradually fill in the database, dataframe, excel, image, and utils modules.

Project Links

• Repository: https://github.com/luvmagi/luvmagiToolKits
• Issues: https://github.com/luvmagi/luvmagiToolKits/issues
• Release guide: docs/pypi-release.md