silco 0.1.0__tar.gz

silco-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: silco
+Version: 0.1.0
+Summary: Microkernel-based Python toolkit for system diagrams, SVG rendering, and plugin-driven exports
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: diagrams>=0.25.1
+Requires-Dist: graphviz>=0.20.3
+Requires-Dist: pydantic>=2.13.3
+Provides-Extra: notebook
+Requires-Dist: ipython>=8; extra == "notebook"
+Provides-Extra: pdf
+Requires-Dist: cairosvg>=2.7; extra == "pdf"
+
+# SILCO (**S**ystem **I**llustration & **L**ayout **Co**mposer)
+
+Silco is a Python-first diagram toolkit built around a small microkernel. The core owns the document model, layout contracts, and plugin registry; renderers, styles, and presenters plug into that kernel. The default SVG renderer now uses the `diagrams` package with C4-flavored Graphviz output so the generated diagrams read like real system design documentation instead of custom-drawn boxes.
+
+```python
+from silco import diagram
+
+d = (
+    diagram("Checkout")
+    .node("user", "User", kind="actor")
+    .node("api", "API", kind="service", group="app")
+    .node("db", "Orders DB", kind="database", group="data")
+    .connect("user", "api", "HTTPS")
+    .connect("api", "db", "SQL")
+)
+
+svg = d.to_svg(style="modern")
+```
+
+Runtime requirement: Graphviz must be installed and `dot` must be on `PATH`.
+
+Built-ins are registered through the kernel on import. Styles, layouts, and optional renderers stay discoverable:
+
+```python
+from silco import kernel
+
+kernel.names("layouts")      # ("dag", "grid")
+kernel.names("renderers")    # ("svg", "mermaid", ...)
+kernel.names("styles")       # ("modern", "uml")
+kernel.discover()            # optional plugin discovery
+```
+
+Render the same diagram in different ways:
+
+```python
+svg = d.to_svg(style="uml", layout="dag", title=True)
+mermaid = d.to_mermaid()
+```
+
+In IPython/Jupyter:
+
+```python
+%load_ext silco.plugins.ipython
+d
+```
+
+Export as PDF with the optional CairoSVG-backed renderer plugin:
+
+```bash
+pip install "silco[pdf]"
+```
+
+```python
+d.save_pdf("checkout.pdf")
+pdf_bytes = d.to_pdf()
+```
+
+Plugin categories:
+
+```python
+kernel.categories()
+kernel.names("renderers")
+kernel.names("presenters")
+```

silco-0.1.0/README.md

@@ -0,0 +1,64 @@
+# SILCO (**S**ystem **I**llustration & **L**ayout **Co**mposer)
+
+Silco is a Python-first diagram toolkit built around a small microkernel. The core owns the document model, layout contracts, and plugin registry; renderers, styles, and presenters plug into that kernel. The default SVG renderer now uses the `diagrams` package with C4-flavored Graphviz output so the generated diagrams read like real system design documentation instead of custom-drawn boxes.
+
+```python
+from silco import diagram
+
+d = (
+    diagram("Checkout")
+    .node("user", "User", kind="actor")
+    .node("api", "API", kind="service", group="app")
+    .node("db", "Orders DB", kind="database", group="data")
+    .connect("user", "api", "HTTPS")
+    .connect("api", "db", "SQL")
+)
+
+svg = d.to_svg(style="modern")
+```
+
+Runtime requirement: Graphviz must be installed and `dot` must be on `PATH`.
+
+Built-ins are registered through the kernel on import. Styles, layouts, and optional renderers stay discoverable:
+
+```python
+from silco import kernel
+
+kernel.names("layouts")      # ("dag", "grid")
+kernel.names("renderers")    # ("svg", "mermaid", ...)
+kernel.names("styles")       # ("modern", "uml")
+kernel.discover()            # optional plugin discovery
+```
+
+Render the same diagram in different ways:
+
+```python
+svg = d.to_svg(style="uml", layout="dag", title=True)
+mermaid = d.to_mermaid()
+```
+
+In IPython/Jupyter:
+
+```python
+%load_ext silco.plugins.ipython
+d
+```
+
+Export as PDF with the optional CairoSVG-backed renderer plugin:
+
+```bash
+pip install "silco[pdf]"
+```
+
+```python
+d.save_pdf("checkout.pdf")
+pdf_bytes = d.to_pdf()
+```
+
+Plugin categories:
+
+```python
+kernel.categories()
+kernel.names("renderers")
+kernel.names("presenters")
+```

silco-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "silco"
+version = "0.1.0"
+description = "Microkernel-based Python toolkit for system diagrams, SVG rendering, and plugin-driven exports"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "diagrams>=0.25.1",
+    "graphviz>=0.20.3",
+    "pydantic>=2.13.3",
+]
+
+[project.optional-dependencies]
+notebook = [
+    "ipython>=8",
+]
+pdf = [
+    "cairosvg>=2.7",
+]
+
+[project.entry-points."silco.plugins"]
+ipython = "silco.plugins.ipython"
+pdf = "silco.plugins.pdf"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["silco*"]
+
+[tool.setuptools.package-data]
+silco = [
+    "core/templates/shapes/*.svg",
+    "core/templates/shapes/*.png",
+]

silco-0.1.0/setup.cfg

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

silco-0.1.0/silco/__init__.py

@@ -0,0 +1,15 @@
+from silco.core import Canvas, Diagram, Edge, Element, Flow, Group, Node, PluginInfo, RenderConfig, diagram, kernel
+
+__all__ = [
+    "Canvas",
+    "Diagram",
+    "Edge",
+    "Element",
+    "Flow",
+    "Group",
+    "Node",
+    "PluginInfo",
+    "RenderConfig",
+    "diagram",
+    "kernel",
+]

silco-0.1.0/silco/core/__init__.py

@@ -0,0 +1,31 @@
+from silco.core.renderers.base.config import RenderConfig
+from silco.core.renderers.base.diagram import Diagram, diagram
+from silco.core.renderers.base.layout import Layout
+from silco.core.renderers.base.positioned_node import PositionedNode
+from silco.core.renderers.base.graphics import Canvas, Element
+from silco.core.kernel import PLUGIN_CATEGORIES, PluginCategory, PluginInfo, SilcoKernel, kernel
+from silco.core.models import Edge, Flow, Group, Node, NodeKind
+
+__all__ = [
+    "Canvas",
+    "Diagram",
+    "Edge",
+    "Element",
+    "Flow",
+    "Group",
+    "Layout",
+    "Node",
+    "NodeKind",
+    "PLUGIN_CATEGORIES",
+    "PluginCategory",
+    "PluginInfo",
+    "PositionedNode",
+    "RenderConfig",
+    "SilcoKernel",
+    "diagram",
+    "kernel",
+]
+
+# Register built-in layouts/renderers on import.
+# This keeps `Diagram.to_svg()` working out of the box.
+from silco.core import renderers as _renderers  # noqa: F401, E402

silco-0.1.0/silco/core/kernel.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import importlib
+import inspect
+import pkgutil
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from importlib import metadata
+from types import ModuleType
+from typing import Any, Literal
+
+PluginCategory = Literal["shapes", "renderers", "layouts", "presenters", "styles"]
+PluginType = PluginCategory
+PLUGIN_CATEGORIES: tuple[PluginCategory, ...] = ("shapes", "renderers", "layouts", "presenters", "styles")
+_CATEGORY_ALIASES = {
+    "shape": "shapes",
+    "shapes": "shapes",
+    "renderer": "renderers",
+    "renderers": "renderers",
+    "style": "styles",
+    "styles": "styles",
+    "layout": "layouts",
+    "layouts": "layouts",
+    "presenter": "presenters",
+    "presenters": "presenters",
+    "representation": "presenters",
+    "representations": "presenters",
+}
+
+
+@dataclass(frozen=True)
+class PluginInfo:
+    """Metadata describing a registered plugin."""
+
+    category: PluginCategory
+    name: str
+    plugin: Any
+    description: str | None = None
+    module: str | None = None
+    tags: tuple[str, ...] = field(default_factory=tuple)
+    auto_discovered: bool = False
+
+
+class SilcoKernel:
+    """Registry and discovery hub for core and optional plugins."""
+
+    def __init__(self) -> None:
+        self.plugins: dict[PluginCategory, dict[str, Any]] = {category: {} for category in PLUGIN_CATEGORIES}
+        self._plugin_info: dict[PluginCategory, dict[str, PluginInfo]] = {category: {} for category in PLUGIN_CATEGORIES}
+        self._discovered_modules: set[str] = set()
+        self._discovered_entry_points: set[str] = set()
+
+    def register(
+        self,
+        plugin_type: str,
+        name: str,
+        plugin: Any,
+        *,
+        description: str | None = None,
+        module: str | None = None,
+        tags: Iterable[str] = (),
+        auto_discovered: bool = False,
+    ) -> Any:
+        category = self.normalize_category(plugin_type)
+        if not name.strip():
+            raise ValueError("plugin name cannot be empty")
+        plugin_name = name.strip()
+        self.plugins[category][plugin_name] = plugin
+        self._plugin_info[category][plugin_name] = PluginInfo(
+            category=category,
+            name=plugin_name,
+            plugin=plugin,
+            description=description,
+            module=module or getattr(plugin, "__module__", None),
+            tags=tuple(tags),
+            auto_discovered=auto_discovered,
+        )
+        return plugin
+
+    def decorator(
+        self,
+        plugin_type: str,
+        name: str,
+        *,
+        description: str | None = None,
+        tags: Iterable[str] = (),
+    ) -> Callable[[Any], Any]:
+        def register_plugin(plugin: Any) -> Any:
+            return self.register(plugin_type, name, plugin, description=description, tags=tags)
+
+        return register_plugin
+
+    def get(self, plugin_type: str, name: str, default: Any = None) -> Any:
+        category = self.normalize_category(plugin_type)
+        if default is None:
+            return self.plugins[category][name]
+        return self.plugins[category].get(name, default)
+
+    def info(self, plugin_type: str, name: str) -> PluginInfo:
+        category = self.normalize_category(plugin_type)
+        return self._plugin_info[category][name]
+
+    def list(self, plugin_type: str | None = None) -> dict[PluginCategory, tuple[PluginInfo, ...]] | tuple[PluginInfo, ...]:
+        if plugin_type is not None:
+            category = self.normalize_category(plugin_type)
+            return tuple(self._plugin_info[category].values())
+        return {category: tuple(self._plugin_info[category].values()) for category in PLUGIN_CATEGORIES}
+
+    def names(self, plugin_type: str) -> tuple[str, ...]:
+        category = self.normalize_category(plugin_type)
+        return tuple(self.plugins[category])
+
+    def categories(self) -> tuple[PluginCategory, ...]:
+        return PLUGIN_CATEGORIES
+
+    def normalize_category(self, plugin_type: str) -> PluginCategory:
+        try:
+            return _CATEGORY_ALIASES[plugin_type]
+        except KeyError as exc:
+            valid = ", ".join(PLUGIN_CATEGORIES)
+            raise ValueError(f"Unknown plugin category: {plugin_type}. Expected one of: {valid}") from exc
+
+    def discover(
+        self,
+        *,
+        namespace: str = "silco.plugins",
+        entry_point_group: str = "silco.plugins",
+    ) -> tuple[PluginInfo, ...]:
+        """Import plugin modules and entry points, returning newly registered plugins."""
+
+        before = self._snapshot()
+        self.discover_namespace(namespace)
+        self.discover_entry_points(entry_point_group)
+        return self._new_plugins_since(before)
+
+    def discover_namespace(self, namespace: str = "silco.plugins") -> tuple[ModuleType, ...]:
+        package = importlib.import_module(namespace)
+        modules: list[ModuleType] = []
+        package_path = getattr(package, "__path__", None)
+        if package_path is None:
+            return tuple(modules)
+        for module_info in pkgutil.iter_modules(package_path, f"{namespace}."):
+            if module_info.name in self._discovered_modules:
+                continue
+            module = importlib.import_module(module_info.name)
+            self._discovered_modules.add(module_info.name)
+            self._register_from_module(module)
+            modules.append(module)
+        return tuple(modules)
+
+    def discover_entry_points(self, group: str = "silco.plugins") -> tuple[Any, ...]:
+        loaded: list[Any] = []
+        entry_points = metadata.entry_points()
+        if hasattr(entry_points, "select"):
+            selected = entry_points.select(group=group)
+        else:  # pragma: no cover - compatibility with old importlib.metadata
+            selected = entry_points.get(group, ())
+        for entry_point in selected:
+            key = f"{entry_point.group}:{entry_point.name}"
+            if key in self._discovered_entry_points:
+                continue
+            plugin = entry_point.load()
+            self._discovered_entry_points.add(key)
+            self._register_loaded_plugin(entry_point.name, plugin)
+            loaded.append(plugin)
+        return tuple(loaded)
+
+    def _register_from_module(self, module: ModuleType) -> None:
+        register = getattr(module, "register_plugins", None)
+        if callable(register):
+            register(self)
+
+    def _register_loaded_plugin(self, name: str, plugin: Any) -> None:
+        if inspect.ismodule(plugin):
+            self._register_from_module(plugin)
+            return
+        register = getattr(plugin, "register_plugins", None)
+        if callable(register):
+            register(self)
+            return
+        category = getattr(plugin, "silco_plugin_category", None)
+        plugin_name = getattr(plugin, "silco_plugin_name", name)
+        if category is None and callable(plugin):
+            plugin(self)
+            return
+        if category is None:
+            raise ValueError(f"Discovered plugin {name!r} does not declare a Silco category")
+        self.register(
+            category,
+            plugin_name,
+            plugin,
+            description=getattr(plugin, "silco_plugin_description", None),
+            tags=getattr(plugin, "silco_plugin_tags", ()),
+            auto_discovered=True,
+        )
+
+    def _snapshot(self) -> set[tuple[PluginCategory, str]]:
+        return {(category, name) for category, plugins in self.plugins.items() for name in plugins}
+
+    def _new_plugins_since(self, snapshot: set[tuple[PluginCategory, str]]) -> tuple[PluginInfo, ...]:
+        new_plugins: list[PluginInfo] = []
+        for category, infos in self._plugin_info.items():
+            for name, info in infos.items():
+                if (category, name) not in snapshot:
+                    new_plugins.append(info)
+        return tuple(new_plugins)
+
+
+kernel = SilcoKernel()

silco-0.1.0/silco/core/models/__init__.py

@@ -0,0 +1,12 @@
+from silco.core.models.edge import Edge
+from silco.core.models.flow import Flow
+from silco.core.models.group import Group
+from silco.core.models.node import Node, NodeKind
+
+__all__ = [
+    "Edge",
+    "Flow",
+    "Group",
+    "Node",
+    "NodeKind",
+]

silco-0.1.0/silco/core/models/edge.py

@@ -0,0 +1,30 @@
+from typing import Any
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class Edge(BaseModel):
+    """A directed relationship between two nodes."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    source: str = Field(min_length=1)
+    target: str = Field(min_length=1)
+    label: str | None = None
+    protocol: str | None = None
+    bidirectional: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("source", "target")
+    @classmethod
+    def normalize_endpoint(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("edge endpoint cannot be empty")
+        return value
+
+    @property
+    def display_label(self) -> str | None:
+        if self.label and self.protocol:
+            return f"{self.label} ({self.protocol})"
+        return self.label or self.protocol
+

silco-0.1.0/silco/core/models/flow.py

@@ -0,0 +1,6 @@
+from silco.core.models.edge import Edge
+
+
+class Flow(Edge):
+    """A directed flow between two nodes."""
+

silco-0.1.0/silco/core/models/group.py

@@ -0,0 +1,24 @@
+from typing import Any
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class Group(BaseModel):
+    """A visual boundary for a set of related nodes."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(min_length=1)
+    label: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("id")
+    @classmethod
+    def normalize_identifier(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("group id cannot be empty")
+        return value
+
+    @property
+    def display_label(self) -> str:
+        return self.label or self.id

silco-0.1.0/silco/core/models/node.py

@@ -0,0 +1,42 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+NodeKind = Literal[
+    "actor",
+    "service",
+    "database",
+    "queue",
+    "cache",
+    "storage",
+    "external",
+    "component",
+]
+
+
+class Node(BaseModel):
+    """A system component that can be rendered in a diagram."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(min_length=1)
+    label: str | None = None
+    kind: NodeKind = "component"
+    description: str | None = None
+    group: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("id", "group")
+    @classmethod
+    def normalize_identifier(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        value = value.strip()
+        if not value:
+            raise ValueError("identifier cannot be empty")
+        return value
+
+    @property
+    def display_label(self) -> str:
+        return self.label or self.id
+

silco-0.1.0/silco/core/renderers/__init__.py

@@ -0,0 +1,35 @@
+from silco.core.renderers.exporter.svg import svg_renderer
+from silco.core.kernel import kernel
+from silco.core.renderers.base.layout import dag_layout, grid_layout
+from silco.core.renderers.svg_common import render_mermaid
+
+kernel.register(
+    "layouts",
+    "dag",
+    dag_layout,
+    description="Layered directed-acyclic-graph layout for left-to-right system flows.",
+    tags=("builtin", "layout"),
+)
+kernel.register(
+    "layouts",
+    "grid",
+    grid_layout,
+    description="Simple grid layout for unordered component maps.",
+    tags=("builtin", "layout"),
+)
+kernel.register(
+    "renderers",
+    "svg",
+    svg_renderer,
+    description="Standalone SVG renderer for notebooks, docs, and exports.",
+    tags=("builtin", "renderer", "vector"),
+)
+kernel.register(
+    "renderers",
+    "mermaid",
+    render_mermaid,
+    description="Mermaid flowchart text renderer.",
+    tags=("builtin", "renderer", "text"),
+)
+
+__all__ = ["render_mermaid", "svg_renderer"]

silco-0.1.0/silco/core/renderers/base/config.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RenderConfig(BaseModel):
+    """Rendering knobs shared by built-in renderers."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    direction: str = "LR"
+    width: int = Field(default=960, ge=320)
+    node_width: int = Field(default=168, ge=80)
+    node_height: int = Field(default=84, ge=48)
+    rank_gap: int = Field(default=72, ge=40)
+    node_gap: int = Field(default=48, ge=20)
+    margin: int = Field(default=32, ge=0)
+    style: str = Field(default="modern", min_length=1)
+    font_family: str = "ui-sans-serif, Segoe UI, sans-serif"
+    title: bool = True