deeptutor-visualize 1.7.0__py3-none-any.whl

deeptutor/visualizers/protocol.py

@@ -0,0 +1,225 @@
+"""Stable contracts shared by visualizer generators, validators and canvases."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import re
+from typing import Any, Callable, Literal
+
+from jsonschema.exceptions import SchemaError, ValidationError
+from jsonschema.validators import validator_for
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+VISUALIZE_MODE_KEY = "_visualizer_mode"
+VISUALIZATION_RESULT_KEY = "_visualizer_result"
+REQUESTED_VISUALIZER_KEY = "_requested_visualizer"
+
+_VISUALIZER_ID_RE = re.compile(r"^[a-z][a-z0-9_.-]{1,63}$")
+MAX_PAYLOAD_CHARS = 200_000
+MAX_MANIFEST_SCHEMA_CHARS = 32_000
+
+
+class VisualizerManifest(BaseModel):
+    """Static, serializable description of one visualization type."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    version: str = Field(default="1.0.0", min_length=1, max_length=32)
+    display_name: str = Field(min_length=1, max_length=80)
+    description: str = Field(min_length=1, max_length=1_000)
+    author: str = Field(default="DeepTutor", min_length=1, max_length=120)
+    subjects: list[str] = Field(default_factory=list, max_length=32)
+    intents: list[str] = Field(default_factory=list, max_length=32)
+    render_target: Literal["native", "iframe", "artifact"] = "native"
+    native_renderer: str = Field(default="", max_length=80)
+    renderer_entry: str = Field(default="", max_length=240)
+    payload_format: str = Field(min_length=1, max_length=160)
+    payload_kind: Literal["text", "json"] = "text"
+    payload_schema: dict[str, Any] = Field(default_factory=dict)
+    language_tag: str = Field(default="text", min_length=1, max_length=40)
+    prompt: str = Field(min_length=1, max_length=12_000)
+    agentic: bool = True
+    core: bool = False
+    default_installed: bool = True
+    priority: int = 100
+
+    @field_validator("id")
+    @classmethod
+    def _valid_id(cls, value: str) -> str:
+        value = value.strip().lower()
+        if not _VISUALIZER_ID_RE.fullmatch(value):
+            raise ValueError("visualizer id must match [a-z][a-z0-9_.-]{1,63}")
+        return value
+
+    @field_validator("renderer_entry")
+    @classmethod
+    def _safe_renderer_entry(cls, value: str) -> str:
+        value = value.strip().replace("\\", "/")
+        if not value:
+            return ""
+        parts = value.split("/")
+        if value.startswith("/") or ".." in parts:
+            raise ValueError("renderer_entry must be a safe relative path")
+        return value
+
+    @model_validator(mode="after")
+    def _renderer_contract(self) -> "VisualizerManifest":
+        if self.render_target == "native" and not self.native_renderer:
+            raise ValueError("native visualizers require native_renderer")
+        if self.render_target == "iframe" and not self.renderer_entry:
+            raise ValueError("iframe visualizers require renderer_entry")
+        if len(json.dumps(self.payload_schema, ensure_ascii=False)) > MAX_MANIFEST_SCHEMA_CHARS:
+            raise ValueError(f"payload_schema exceeds {MAX_MANIFEST_SCHEMA_CHARS} characters")
+        if self.payload_schema:
+            remote_ref = _find_remote_schema_ref(self.payload_schema)
+            if remote_ref:
+                raise ValueError(
+                    f"payload_schema may only use local # references, found: {remote_ref}"
+                )
+            try:
+                validator_for(self.payload_schema).check_schema(self.payload_schema)
+            except SchemaError as exc:
+                raise ValueError(f"payload_schema is invalid: {exc.message}") from exc
+        return self
+
+
+class RendererRef(BaseModel):
+    id: str
+    version: str
+    target: Literal["native", "iframe", "artifact"]
+    native_renderer: str = ""
+    entry_url: str = ""
+
+
+class VisualizationPayload(BaseModel):
+    format: str
+    data: Any
+
+
+class VisualizationPresentation(BaseModel):
+    title: str = ""
+    description: str = ""
+    alt_text: str = ""
+    aspect_ratio: str = ""
+
+
+class VisualizationInteraction(BaseModel):
+    events: list[str] = Field(default_factory=list)
+
+
+class VisualizationEnvelope(BaseModel):
+    """Versioned result understood by the generic frontend canvas."""
+
+    schema_version: str = "deeptutor.visualization/v1"
+    render_type: str
+    renderer: RendererRef
+    payload: VisualizationPayload
+    presentation: VisualizationPresentation = Field(default_factory=VisualizationPresentation)
+    interaction: VisualizationInteraction = Field(default_factory=VisualizationInteraction)
+    fallback: dict[str, Any] = Field(default_factory=dict)
+
+
+PayloadValidator = Callable[[str], tuple[bool, Any, str]]
+
+
+@dataclass(frozen=True)
+class VisualizerPlugin:
+    """Runtime wrapper around a manifest and its trusted validator."""
+
+    manifest: VisualizerManifest
+    origin: Literal["core", "bundled", "user"]
+    root: str = ""
+    validator: PayloadValidator | None = None
+
+    def validate_payload(self, raw_payload: str) -> tuple[bool, Any, str]:
+        raw = str(raw_payload or "").strip()
+        if not raw:
+            return False, None, "payload is empty"
+        if len(raw) > MAX_PAYLOAD_CHARS:
+            return False, None, f"payload exceeds {MAX_PAYLOAD_CHARS} characters"
+        if self.validator is not None:
+            return self.validator(raw)
+        if self.manifest.payload_kind == "json":
+            try:
+                data = json.loads(raw)
+            except json.JSONDecodeError as exc:
+                return False, None, f"payload is not valid JSON: {exc}"
+            if self.manifest.payload_schema:
+                validator_type = validator_for(self.manifest.payload_schema)
+                try:
+                    validator_type(self.manifest.payload_schema).validate(data)
+                except ValidationError as exc:
+                    location = "$"
+                    if exc.absolute_path:
+                        location += "".join(
+                            f"[{part}]" if isinstance(part, int) else f".{part}"
+                            for part in exc.absolute_path
+                        )
+                    return (
+                        False,
+                        None,
+                        f"payload schema violation at {location}: {exc.message}",
+                    )
+            return True, data, ""
+        return True, raw, ""
+
+    def serialize_payload(self, data: Any) -> str:
+        if isinstance(data, str):
+            return data
+        return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def manifest_public_dict(
+    plugin: VisualizerPlugin,
+    *,
+    installed: bool,
+    enabled: bool,
+) -> dict[str, Any]:
+    result = plugin.manifest.model_dump()
+    # Prompt rules are runtime implementation detail and can be very large.
+    result.pop("prompt", None)
+    result.update(
+        {
+            "origin": plugin.origin,
+            "installed": installed,
+            "enabled": enabled,
+            "uninstallable": not plugin.manifest.core,
+        }
+    )
+    return result
+
+
+def _find_remote_schema_ref(value: Any) -> str:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if key in {"$ref", "$dynamicRef"} and isinstance(item, str):
+                if not item.startswith("#"):
+                    return item
+            found = _find_remote_schema_ref(item)
+            if found:
+                return found
+    elif isinstance(value, list):
+        for item in value:
+            found = _find_remote_schema_ref(item)
+            if found:
+                return found
+    return ""
+
+
+__all__ = [
+    "MAX_PAYLOAD_CHARS",
+    "MAX_MANIFEST_SCHEMA_CHARS",
+    "REQUESTED_VISUALIZER_KEY",
+    "VISUALIZATION_RESULT_KEY",
+    "VISUALIZE_MODE_KEY",
+    "RendererRef",
+    "VisualizationEnvelope",
+    "VisualizationInteraction",
+    "VisualizationPayload",
+    "VisualizationPresentation",
+    "VisualizerManifest",
+    "VisualizerPlugin",
+    "manifest_public_dict",
+]

deeptutor/visualizers/registry.py

@@ -0,0 +1,155 @@
+"""Registry composition for core, bundled and per-user visualizer types."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .builtin import bundled_visualizers, core_visualizers
+from .protocol import VisualizerPlugin, manifest_public_dict
+from .store import VisualizerStore, VisualizerStoreError
+
+
+class VisualizerRegistry:
+    def __init__(self, *, store: VisualizerStore | None = None) -> None:
+        self.store = store or VisualizerStore()
+        self._catalog: dict[str, VisualizerPlugin] = {}
+        self._installed: set[str] = set()
+        self._enabled: set[str] = set()
+        self.reload()
+
+    def reload(self) -> None:
+        state = self.store.state()
+        explicitly_installed = set(state["installed"])
+        disabled = set(state["disabled"])
+        uninstalled = set(state["uninstalled"])
+        catalog: dict[str, VisualizerPlugin] = {}
+        installed: set[str] = set()
+
+        for plugin in core_visualizers():
+            catalog.setdefault(plugin.manifest.id, plugin)
+            installed.add(plugin.manifest.id)
+        for plugin in bundled_visualizers():
+            catalog.setdefault(plugin.manifest.id, plugin)
+            if plugin.manifest.id in explicitly_installed or (
+                plugin.manifest.default_installed and plugin.manifest.id not in uninstalled
+            ):
+                installed.add(plugin.manifest.id)
+        for manifest, root in self.store.user_packages():
+            if manifest.id in catalog:
+                continue
+            catalog[manifest.id] = VisualizerPlugin(
+                manifest=manifest,
+                origin="user",
+                root=str(root),
+            )
+            installed.add(manifest.id)
+
+        self._catalog = catalog
+        self._installed = installed
+        self._enabled = installed - disabled
+
+    def catalog(self) -> list[VisualizerPlugin]:
+        return sorted(self._catalog.values(), key=lambda item: item.manifest.priority)
+
+    def installed(self, *, include_disabled: bool = False) -> list[VisualizerPlugin]:
+        ids = self._installed if include_disabled else self._enabled
+        return [plugin for plugin in self.catalog() if plugin.manifest.id in ids]
+
+    def agentic(self) -> list[VisualizerPlugin]:
+        return [plugin for plugin in self.installed() if plugin.manifest.agentic]
+
+    def get(self, visualizer_id: str, *, require_enabled: bool = True) -> VisualizerPlugin | None:
+        plugin = self._catalog.get(str(visualizer_id or "").strip().lower())
+        if plugin is None:
+            return None
+        if plugin.manifest.id not in self._installed:
+            return None
+        if require_enabled and plugin.manifest.id not in self._enabled:
+            return None
+        return plugin
+
+    def public_catalog(self) -> list[dict[str, object]]:
+        return [
+            manifest_public_dict(
+                plugin,
+                installed=plugin.manifest.id in self._installed,
+                enabled=plugin.manifest.id in self._enabled,
+            )
+            for plugin in self.catalog()
+        ]
+
+    def set_enabled(self, visualizer_id: str, enabled: bool) -> None:
+        plugin = self._catalog.get(visualizer_id)
+        if plugin is None or plugin.manifest.id not in self._installed:
+            raise VisualizerStoreError(f"visualizer is not installed: {visualizer_id}")
+        self.store.set_enabled(visualizer_id, enabled)
+        self.reload()
+
+    def install_bundled(self, visualizer_id: str) -> None:
+        plugin = self._catalog.get(visualizer_id)
+        if plugin is None or plugin.origin != "bundled":
+            raise VisualizerStoreError(f"bundled visualizer not found: {visualizer_id}")
+        self.store.set_bundled_installed(visualizer_id, True)
+        self.reload()
+
+    def uninstall(self, visualizer_id: str) -> None:
+        plugin = self._catalog.get(visualizer_id)
+        if plugin is None:
+            raise VisualizerStoreError(f"visualizer not found: {visualizer_id}")
+        if plugin.manifest.core:
+            raise VisualizerStoreError("core visualizers cannot be uninstalled; disable them")
+        if plugin.origin == "bundled":
+            self.store.set_bundled_installed(visualizer_id, False)
+        elif plugin.origin == "user":
+            self.store.uninstall_user(visualizer_id)
+        self.reload()
+
+    def install_archive(self, archive_path: Path) -> VisualizerPlugin:
+        manifest = self.store.install_archive(
+            archive_path,
+            reserved_ids=set(self._catalog),
+        )
+        self.reload()
+        plugin = self.get(manifest.id)
+        if plugin is None:  # pragma: no cover - defensive
+            raise VisualizerStoreError("installed visualizer was not discoverable")
+        return plugin
+
+    def asset_path(self, visualizer_id: str, relative_path: str) -> Path:
+        plugin = self.get(visualizer_id)
+        if plugin is None or plugin.origin != "user":
+            raise VisualizerStoreError("visualizer asset not found")
+        return self.store.asset_path(visualizer_id, relative_path)
+
+    def prompt_catalog(self, requested: str = "auto") -> str:
+        plugins = self.agentic()
+        if requested != "auto":
+            selected = self.get(requested)
+            if selected is None or not selected.manifest.agentic:
+                raise VisualizerStoreError(f"visualizer is unavailable: {requested}")
+            plugins = [selected]
+        blocks: list[str] = []
+        for plugin in plugins:
+            manifest = plugin.manifest
+            schema = ""
+            if manifest.payload_schema:
+                schema = "\nPayload JSON Schema:\n" + json.dumps(
+                    manifest.payload_schema, ensure_ascii=False, indent=2
+                )
+            blocks.append(
+                f"### {manifest.id} — {manifest.display_name}\n"
+                f"Use for: {manifest.description}\n"
+                f"Payload format: {manifest.payload_format}{schema}\n"
+                f"Rules:\n{manifest.prompt.strip()}"
+            )
+        return "\n\n".join(blocks)
+
+
+def get_visualizer_registry() -> VisualizerRegistry:
+    # Per-user paths are resolved by PathService/current-user context, so a
+    # process singleton would leak one user's installed set into another's.
+    return VisualizerRegistry()
+
+
+__all__ = ["VisualizerRegistry", "get_visualizer_registry"]

deeptutor/visualizers/store.py

@@ -0,0 +1,260 @@
+"""Per-user installation state and safe declarative visualizer imports."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import shutil
+import tempfile
+import zipfile
+
+from .protocol import VisualizerManifest
+
+_MAX_ARCHIVE_BYTES = 25 * 1024 * 1024
+_MAX_ENTRY_BYTES = 10 * 1024 * 1024
+_MAX_MANIFEST_BYTES = 128 * 1024
+_MAX_ENTRIES = 200
+_MAX_RATIO = 100.0
+_ALLOWED_SUFFIXES = {
+    ".json",
+    ".html",
+    ".js",
+    ".mjs",
+    ".css",
+    ".svg",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".woff2",
+    ".wasm",
+}
+
+
+class VisualizerStoreError(ValueError):
+    pass
+
+
+class VisualizerStore:
+    """Owns the mutable layer; registry composition remains read-only."""
+
+    def __init__(
+        self,
+        *,
+        root: Path | None = None,
+        state_file: Path | None = None,
+    ) -> None:
+        from deeptutor.services.path_service import get_path_service
+
+        service = get_path_service()
+        self.root = (root or (service.get_user_root() / "visualizers")).resolve()
+        self.state_file = (state_file or service.get_settings_file("visualizers.json")).resolve()
+
+    def state(self) -> dict[str, list[str]]:
+        try:
+            raw = json.loads(self.state_file.read_text(encoding="utf-8"))
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            raw = {}
+        return {
+            "installed": _string_list(raw.get("installed")),
+            "disabled": _string_list(raw.get("disabled")),
+            "uninstalled": _string_list(raw.get("uninstalled")),
+        }
+
+    def save_state(self, state: dict[str, list[str]]) -> None:
+        normalized = {
+            "installed": sorted(set(_string_list(state.get("installed")))),
+            "disabled": sorted(set(_string_list(state.get("disabled")))),
+            "uninstalled": sorted(set(_string_list(state.get("uninstalled")))),
+        }
+        self.state_file.parent.mkdir(parents=True, exist_ok=True)
+        temp = self.state_file.with_suffix(self.state_file.suffix + ".tmp")
+        temp.write_text(
+            json.dumps(normalized, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        temp.replace(self.state_file)
+
+    def set_enabled(self, visualizer_id: str, enabled: bool) -> None:
+        state = self.state()
+        disabled = set(state["disabled"])
+        if enabled:
+            disabled.discard(visualizer_id)
+        else:
+            disabled.add(visualizer_id)
+        state["disabled"] = sorted(disabled)
+        self.save_state(state)
+
+    def set_bundled_installed(self, visualizer_id: str, installed: bool) -> None:
+        state = self.state()
+        explicitly_installed = set(state["installed"])
+        uninstalled = set(state["uninstalled"])
+        disabled = set(state["disabled"])
+        if installed:
+            explicitly_installed.add(visualizer_id)
+            uninstalled.discard(visualizer_id)
+            disabled.discard(visualizer_id)
+        else:
+            explicitly_installed.discard(visualizer_id)
+            uninstalled.add(visualizer_id)
+            disabled.discard(visualizer_id)
+        state["installed"] = sorted(explicitly_installed)
+        state["uninstalled"] = sorted(uninstalled)
+        state["disabled"] = sorted(disabled)
+        self.save_state(state)
+
+    def user_packages(self) -> list[tuple[VisualizerManifest, Path]]:
+        if not self.root.is_dir():
+            return []
+        packages: list[tuple[VisualizerManifest, Path]] = []
+        for child in sorted(self.root.iterdir()):
+            manifest_file = child / "visualizer.json"
+            if not child.is_dir() or not manifest_file.is_file():
+                continue
+            try:
+                if manifest_file.stat().st_size > _MAX_MANIFEST_BYTES:
+                    continue
+                manifest = VisualizerManifest.model_validate_json(
+                    manifest_file.read_text(encoding="utf-8")
+                )
+                self._validate_imported_manifest(manifest, child)
+            except Exception:
+                # A broken package is ignored by discovery. The API installer
+                # validates eagerly, so this is primarily crash recovery.
+                continue
+            packages.append((manifest, child.resolve()))
+        return packages
+
+    def install_archive(
+        self,
+        archive_path: Path,
+        *,
+        reserved_ids: set[str] | None = None,
+    ) -> VisualizerManifest:
+        self.root.mkdir(parents=True, exist_ok=True)
+        if archive_path.stat().st_size > _MAX_ARCHIVE_BYTES:
+            raise VisualizerStoreError("visualizer package exceeds 25 MB")
+        with tempfile.TemporaryDirectory(prefix="dtviz-") as tmp_name:
+            extracted = Path(tmp_name)
+            self._extract_archive(archive_path, extracted)
+            package_root = self._locate_package_root(extracted)
+            manifest_path = package_root / "visualizer.json"
+            try:
+                if manifest_path.stat().st_size > _MAX_MANIFEST_BYTES:
+                    raise VisualizerStoreError("visualizer.json exceeds 128 KB")
+                manifest = VisualizerManifest.model_validate_json(
+                    manifest_path.read_text(encoding="utf-8")
+                )
+            except Exception as exc:
+                raise VisualizerStoreError(f"invalid visualizer.json: {exc}") from exc
+            self._validate_imported_manifest(manifest, package_root)
+            if manifest.id in (reserved_ids or set()):
+                raise VisualizerStoreError(f"visualizer id is reserved by the host: {manifest.id}")
+            destination = (self.root / manifest.id).resolve()
+            if not destination.is_relative_to(self.root):
+                raise VisualizerStoreError("visualizer id escapes the installation root")
+            if destination.exists():
+                raise VisualizerStoreError(f"visualizer already installed: {manifest.id}")
+            staging = Path(tempfile.mkdtemp(prefix=f".{manifest.id}-", dir=self.root))
+            try:
+                for item in package_root.iterdir():
+                    target = staging / item.name
+                    if item.is_dir():
+                        shutil.copytree(item, target)
+                    else:
+                        shutil.copy2(item, target)
+                staging.replace(destination)
+            finally:
+                if staging.exists():
+                    shutil.rmtree(staging, ignore_errors=True)
+        self.set_enabled(manifest.id, True)
+        return manifest
+
+    def uninstall_user(self, visualizer_id: str) -> None:
+        target = (self.root / visualizer_id).resolve()
+        if not target.is_relative_to(self.root) or target == self.root:
+            raise VisualizerStoreError("invalid visualizer id")
+        if not (target / "visualizer.json").is_file():
+            raise VisualizerStoreError(f"user visualizer not found: {visualizer_id}")
+        shutil.rmtree(target)
+        state = self.state()
+        state["disabled"] = [item for item in state["disabled"] if item != visualizer_id]
+        state["installed"] = [item for item in state["installed"] if item != visualizer_id]
+        self.save_state(state)
+
+    def asset_path(self, visualizer_id: str, relative_path: str) -> Path:
+        package = (self.root / visualizer_id).resolve()
+        candidate = (package / relative_path).resolve()
+        if not package.is_dir() or not candidate.is_relative_to(package) or not candidate.is_file():
+            raise VisualizerStoreError("visualizer asset not found")
+        return candidate
+
+    @staticmethod
+    def _validate_imported_manifest(manifest: VisualizerManifest, root: Path) -> None:
+        if manifest.core or manifest.default_installed:
+            # Installation policy is host-owned. Imported packages cannot make
+            # themselves immutable or silently default-enabled for other users.
+            manifest.core = False
+            manifest.default_installed = False
+        if manifest.render_target != "iframe":
+            raise VisualizerStoreError(
+                "imported visualizers must use the sandboxed iframe render target"
+            )
+        entry = (root / manifest.renderer_entry).resolve()
+        if not entry.is_relative_to(root.resolve()) or not entry.is_file():
+            raise VisualizerStoreError("renderer_entry does not exist in the package")
+        if entry.suffix.lower() != ".html":
+            raise VisualizerStoreError("renderer_entry must be an HTML file")
+
+    @staticmethod
+    def _locate_package_root(extracted: Path) -> Path:
+        if (extracted / "visualizer.json").is_file():
+            return extracted
+        subdirs = [item for item in extracted.iterdir() if item.is_dir()]
+        if len(subdirs) == 1 and (subdirs[0] / "visualizer.json").is_file():
+            return subdirs[0]
+        raise VisualizerStoreError("package must contain visualizer.json at its root")
+
+    @staticmethod
+    def _extract_archive(archive_path: Path, destination: Path) -> None:
+        total = 0
+        try:
+            archive = zipfile.ZipFile(archive_path)
+        except zipfile.BadZipFile as exc:
+            raise VisualizerStoreError("package is not a valid zip archive") from exc
+        with archive:
+            members = [item for item in archive.infolist() if not item.is_dir()]
+            if len(members) > _MAX_ENTRIES:
+                raise VisualizerStoreError("package contains too many files")
+            root = destination.resolve()
+            for info in members:
+                raw = info.filename.replace("\\", "/")
+                rel = Path(raw)
+                if rel.is_absolute() or ".." in rel.parts:
+                    raise VisualizerStoreError(f"illegal package path: {raw}")
+                if raw.startswith("__MACOSX/") or rel.name.startswith("."):
+                    continue
+                if rel.suffix.lower() not in _ALLOWED_SUFFIXES:
+                    raise VisualizerStoreError(f"unsupported package file type: {raw}")
+                if info.file_size > _MAX_ENTRY_BYTES:
+                    raise VisualizerStoreError(f"package entry is too large: {raw}")
+                if info.compress_size and info.file_size / info.compress_size > _MAX_RATIO:
+                    raise VisualizerStoreError(f"suspicious compression ratio: {raw}")
+                total += info.file_size
+                if total > _MAX_ARCHIVE_BYTES:
+                    raise VisualizerStoreError("expanded package exceeds 25 MB")
+                target = (root / rel).resolve()
+                if not target.is_relative_to(root):
+                    raise VisualizerStoreError(f"illegal package path: {raw}")
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with archive.open(info) as source, open(target, "wb") as sink:
+                    shutil.copyfileobj(source, sink, length=1 << 16)
+
+
+def _string_list(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in value if str(item).strip()]
+
+
+__all__ = ["VisualizerStore", "VisualizerStoreError"]