silco 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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/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/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/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

silco/core/renderers/base/diagram.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import importlib
+from os import PathLike
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator, model_validator
+
+from silco.core.kernel import kernel
+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
+
+if TYPE_CHECKING:
+    from silco.core.renderers.base.layout import Layout
+
+Direction = Literal["LR", "RL", "TB", "BT"]
+
+
+class Diagram(BaseModel):
+    """Mutable system-design diagram model with kernel-backed rendering."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    title: str | None = None
+    direction: Direction = "LR"
+    nodes: dict[str, Node] = Field(default_factory=dict)
+    edges: list[Edge] = Field(default_factory=list)
+    flows: list[Flow] = Field(default_factory=list)
+    groups: dict[str, Group] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    _default_renderer: str = PrivateAttr(default="svg")
+
+    @field_validator("direction")
+    @classmethod
+    def validate_direction(cls, value: str) -> str:
+        if value not in {"LR", "RL", "TB", "BT"}:
+            raise ValueError("direction must be one of LR, RL, TB, BT")
+        return value
+
+    @model_validator(mode="after")
+    def validate_relations(self) -> "Diagram":
+        for collection_name, relations in (("edges", self.edges), ("flows", self.flows)):
+            missing = [f"{relation.source}->{relation.target}" for relation in relations if relation.source not in self.nodes or relation.target not in self.nodes]
+            if missing:
+                joined = ", ".join(missing)
+                raise ValueError(f"{collection_name} reference unknown nodes: {joined}")
+        return self
+
+    def add_node(
+        self,
+        id: str,
+        label: str | None = None,
+        *,
+        kind: str = "component",
+        group: str | None = None,
+        description: str | None = None,
+        **metadata: Any,
+    ) -> "Diagram":
+        node = Node(id=id, label=label, kind=kind, group=group, description=description, metadata=metadata)
+        if node.id in self.nodes:
+            raise ValueError(f"node already exists: {node.id}")
+        self.nodes[node.id] = node
+        if node.group and node.group not in self.groups:
+            self.add_group(node.group)
+        return self
+
+    node = add_node
+
+    def add_group(self, id: str, label: str | None = None, **metadata: Any) -> "Diagram":
+        group = Group(id=id, label=label, metadata=metadata)
+        current = self.groups.get(group.id)
+        if current is None:
+            self.groups[group.id] = group
+            return self
+        if label is not None:
+            current.label = label
+        current.metadata.update(metadata)
+        return self
+
+    group = add_group
+
+    def _append_relation(
+        self,
+        relation_type: type[Edge] | type[Flow],
+        source: str,
+        target: str,
+        label: str | None = None,
+        *,
+        protocol: str | None = None,
+        bidirectional: bool = False,
+        **metadata: Any,
+    ) -> "Diagram":
+        if source not in self.nodes:
+            raise ValueError(f"unknown source node: {source}")
+        if target not in self.nodes:
+            raise ValueError(f"unknown target node: {target}")
+        relation = relation_type(
+            source=source,
+            target=target,
+            label=label,
+            protocol=protocol,
+            bidirectional=bidirectional,
+            metadata=metadata,
+        )
+        target_collection = self.flows if relation_type is Flow else self.edges
+        target_collection.append(relation)
+        return self
+
+    def add_edge(
+        self,
+        source: str,
+        target: str,
+        label: str | None = None,
+        *,
+        protocol: str | None = None,
+        bidirectional: bool = False,
+        **metadata: Any,
+    ) -> "Diagram":
+        return self._append_relation(Edge, source, target, label, protocol=protocol, bidirectional=bidirectional, **metadata)
+
+    connect = add_edge
+
+    def add_flow(
+        self,
+        source: str,
+        target: str,
+        label: str | None = None,
+        *,
+        protocol: str | None = None,
+        bidirectional: bool = False,
+        **metadata: Any,
+    ) -> "Diagram":
+        return self._append_relation(Flow, source, target, label, protocol=protocol, bidirectional=bidirectional, **metadata)
+
+    flow = add_flow
+
+    def render(self, renderer: str | None = None, **options: Any) -> Any:
+        render_name = renderer or self._default_renderer
+        return kernel.get("renderers", render_name)(self, **options)
+
+    def layout(self, layout: str = "dag", **options: Any) -> Layout:
+        return kernel.get("layouts", layout)(self, **options)
+
+    def to_svg(self, **options: Any) -> str:
+        return self.render("svg", **options)
+
+    def to_mermaid(self, **options: Any) -> str:
+        return self.render("mermaid", **options)
+
+    def to_html(self, **options: Any) -> str:
+        return f'<div class="silco-diagram">{self.to_svg(**options)}</div>'
+
+    def to_pdf(self, **options: Any) -> bytes:
+        if "pdf" not in kernel.names("renderers"):
+            importlib.import_module("silco.plugins.pdf")
+        return self.render("pdf", **options)
+
+    def save_pdf(self, path: str | PathLike[str], **options: Any) -> Path:
+        pdf = importlib.import_module("silco.plugins.pdf")
+        return pdf.save_pdf(self, path, **options)
+
+    def _repr_svg_(self) -> str:
+        return self.to_svg()
+
+    def _repr_html_(self) -> str:
+        return self.to_html()
+
+    def __str__(self) -> str:
+        name = f" {self.title!r}" if self.title else ""
+        return f"<Diagram{name}: {len(self.nodes)} nodes, {len(self.edges) + len(self.flows)} relations>"
+
+    __repr__ = __str__
+
+
+def diagram(title: str | None = None, *, direction: Direction = "LR") -> Diagram:
+    return Diagram(title=title, direction=direction)