royalsolution-ontosight 0.2.0__py3-none-any.whl

ontosight/__init__.py

@@ -0,0 +1,42 @@
+"""OnToSight - Interactive visualization library for knowledge graphs and structured data.
+
+A simple, powerful library for creating interactive visualizations of graphs,
+trees, lists, and other structured data with Python.
+
+Logging Configuration:
+    OnToSight provides automatic logging configuration. By default, it uses a
+    user-friendly log format that minimizes output for end users.
+
+    Environment Variables:
+        ONTOSIGHT_LOG_LEVEL: Log level (DEBUG, INFO, WARNING, ERROR)
+        ONTOSIGHT_LOG_FORMAT: Log format ("user_friendly" or "detailed")
+        ONTOSIGHT_QUIET: Set to "true" to disable all log output
+
+    Example:
+        import os
+        os.environ["ONTOSIGHT_LOG_LEVEL"] = "DEBUG"
+        os.environ["ONTOSIGHT_LOG_FORMAT"] = "detailed"
+
+        from ontosight import view_graph
+        # Now view_graph will output detailed debug logs
+"""
+
+# 导入日志配置（在任何其他导入之前）
+from ontosight import logging_config
+
+from ontosight.core import (
+    view_graph,
+    view_hypergraph,
+    view_nodes,
+)
+
+__version__ = "0.2.0"
+__author__ = "Yifan Feng"
+__email__ = "evanfeng97@gmail.com"
+
+__all__ = [
+    "view_graph",
+    "view_hypergraph",
+    "view_nodes",
+    "logging_config",
+]

ontosight/core/__init__.py

@@ -0,0 +1,30 @@
+"""OntoSight Core - High-level API for visualization management.
+
+This module provides simple, intuitive functions for creating and managing
+interactive visualizations of knowledge graphs and structured data.
+
+Example:
+    >>> from ontosight.core import view_graph, view_hypergraph
+    >>>
+    >>> # Create a graph visualization
+    >>> nodes = [{"name": "Node 1"}, {"name": "Node 2"}]
+    >>> edges = [{"source": nodes[0], "target": nodes[1]}]
+    >>> view_graph(node_list=nodes, edge_list=edges)
+"""
+
+from ontosight.core.views import (
+    view_nodes,
+    view_graph,
+    view_hypergraph,
+)
+
+from .storage import BaseStorage, GraphStorage, HypergraphStorage
+
+__all__ = [
+    "view_nodes",
+    "view_graph",
+    "view_hypergraph",
+    "BaseStorage",
+    "GraphStorage",
+    "HypergraphStorage",
+]

ontosight/core/storage/__init__.py

@@ -0,0 +1,13 @@
+"""Storage engines for graph, hypergraph, and node-only visualizations."""
+
+from .base import BaseStorage
+from .graph import GraphStorage
+from .hypergraph import HypergraphStorage
+from .node import NodeStorage
+
+__all__ = [
+    "BaseStorage",
+    "GraphStorage",
+    "HypergraphStorage",
+    "NodeStorage",
+]

ontosight/core/storage/base.py

@@ -0,0 +1,55 @@
+"""Base storage class for all storage engines."""
+
+from typing import Any, Dict, List, Optional
+
+
+class BaseStorage:
+    """Abstract base class for storage engines."""
+
+    def get_element(self, element_id: str) -> Optional[Dict[str, Any]]:
+        """Get a single element by ID."""
+        raise NotImplementedError
+
+    def get_details(self, element_id: str) -> Optional[Dict[str, Any]]:
+        """Get full details of an element."""
+        raise NotImplementedError
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get statistics about the storage."""
+        raise NotImplementedError
+
+    def get_sample(
+        self,
+        center_ids: Optional[List[str]] = None,
+        hops: int = 2,
+        highlight_center: bool = False,
+        min_nodes: int = 10,
+        max_attempts: int = 5,
+    ) -> Dict[str, Any]:
+        """Get sample around given nodes.
+
+        Args:
+            center_ids: List of center node/element IDs
+            hops: Number of hops to expand (graph/hypergraph specific)
+            highlight_center: If True, mark center elements with highlighted=True
+            min_nodes: Minimum number of nodes to include in the sample
+            max_attempts: Maximum number of attempts to find a suitable center
+        """
+        raise NotImplementedError
+
+    def get_sample_from_data(self, *args, highlight_center: bool = False, **kwargs) -> Dict[str, Any]:
+        """Get sample based on raw data objects (ItemSchema/NodeSchema/EdgeSchema).
+        
+        For list visualization: get_sample_from_data(item_list, highlight_center=False)
+        For graph visualization: get_sample_from_data(node_list, edge_list, highlight_center=False)
+        For hypergraph visualization: get_sample_from_data(node_list, hyperedge_list, highlight_center=False)
+        
+        Args:
+            *args: Raw data objects to extract IDs from
+            highlight_center: If True, mark matching elements with highlighted=True
+            **kwargs: Additional keyword arguments
+            
+        Returns:
+            Sample data around the provided elements
+        """
+        raise NotImplementedError

ontosight/core/storage/graph.py

@@ -0,0 +1,386 @@
+"""Storage engine for graph visualization."""
+
+from typing import Any, Dict, List, Optional, Set, Tuple, Callable, TypeVar
+from pydantic import BaseModel
+import random
+import logging
+
+from ontosight.utils import get_model_id, default_label_formatter
+from .base import BaseStorage
+
+logger = logging.getLogger(__name__)
+
+NodeSchema = TypeVar("NodeSchema", bound=BaseModel)
+EdgeSchema = TypeVar("EdgeSchema", bound=BaseModel)
+
+_MIN_NODE_SIZE = 20
+_MAX_NODE_SIZE = 48
+
+
+def _node_size_from_importance(importance: float) -> int:
+    clamped = max(0.0, min(1.0, float(importance)))
+    return int(_MIN_NODE_SIZE + round(clamped * (_MAX_NODE_SIZE - _MIN_NODE_SIZE)))
+
+
+def _apply_topology_to_node(
+    node_entry: Dict[str, Any],
+    *,
+    degree: int,
+    ranking: Optional[Dict[str, Any]],
+    highlight: bool,
+) -> None:
+    """Enrich a node dict with topology metrics for the viewer."""
+    data = node_entry.setdefault("data", {})
+    data["degree"] = degree
+    if ranking:
+        data["importance"] = ranking.get("importance", 0)
+        data["betweenness"] = ranking.get("betweenness", 0)
+        data["tier"] = ranking.get("tier", "low")
+        node_entry["size"] = _node_size_from_importance(ranking.get("importance", 0))
+    else:
+        data["importance"] = min(1.0, degree / 10.0) if degree else 0.0
+        node_entry["size"] = _node_size_from_importance(data["importance"])
+    if highlight:
+        node_entry["highlighted"] = True
+
+
+class GraphStorage(BaseStorage):
+    """Storage engine for graph visualization."""
+
+    def __init__(
+        self,
+        node_list: List[NodeSchema],
+        edge_list: List[EdgeSchema],
+        node_id_extractor: Callable[[NodeSchema], str],
+        node_ids_in_edge_extractor: Callable[[EdgeSchema], Tuple[str, str]],
+        edge_label_extractor: Callable[[EdgeSchema], str],
+        node_label_extractor: Optional[Callable[[NodeSchema], str]] = None,
+        node_rankings: Optional[List[Dict[str, Any]]] = None,
+        critical_node_ids: Optional[List[str]] = None,
+    ):
+        """Initialize graph storage from raw schema items.
+
+        Args:
+            node_list: List of node schema objects
+            edge_list: List of edge schema objects
+            node_id_extractor: Function to extract unique ID from node
+            node_ids_in_edge_extractor: Function to extract (source_id, target_id) from edge
+            edge_label_extractor: Function to extract display label from edge
+            node_label_extractor: Optional function to extract display label from node
+        """
+        node_label_extractor = (
+            node_label_extractor
+            if node_label_extractor
+            else lambda n: default_label_formatter(node_id_extractor(n))
+        )
+        edge_id_extractor = get_model_id
+        # Store extractors as class variables for later use
+        self.node_id_extractor = node_id_extractor
+        self.edge_id_extractor = edge_id_extractor
+        self.node_label_extractor = node_label_extractor
+        self.edge_label_extractor = edge_label_extractor
+        self.node_ids_in_edge_extractor = node_ids_in_edge_extractor
+
+        rankings_map = {r["node_id"]: r for r in (node_rankings or []) if r.get("node_id")}
+        critical_set = set(critical_node_ids or [])
+
+        self.nodes = {}  # {id: {"id": id, "data": {"label": label, "raw": raw_data}}}
+        self.deg_node = {}
+
+        for node in node_list:
+            node_id = node_id_extractor(node)
+            label = node_label_extractor(node)
+            raw_data = node.model_dump() if hasattr(node, "model_dump") else dict(node)
+            self.nodes[node_id] = {"id": node_id, "data": {"label": label, "raw": raw_data}}
+            self.deg_node[node_id] = 0
+
+        # Build edges with formatted structure
+        self.edges = {}  # {id: {"id": id, "source": src_id, "target": tgt_id, "data": {...}}}
+        self.adjacency: Dict[str, Set[str]] = {node_id: set() for node_id in self.nodes}
+        self.incident_edges: Dict[str, List[str]] = {node_id: [] for node_id in self.nodes}
+
+        for i, edge in enumerate(edge_list):
+            edge_label = edge_label_extractor(edge)
+            source_id, target_id = node_ids_in_edge_extractor(edge)
+
+            if source_id not in self.nodes or target_id not in self.nodes:
+                logger.warning(f"Edge references missing node IDs: {source_id} -> {target_id}")
+                continue
+
+            edge_id = edge_id_extractor(edge)
+
+            if source_id != target_id:
+                self.deg_node[source_id] += 1
+                self.deg_node[target_id] += 1
+
+            raw_data = edge.model_dump() if hasattr(edge, "model_dump") else dict(edge)
+            self.edges[edge_id] = {
+                "id": edge_id,
+                "source": source_id,
+                "target": target_id,
+                "data": {"label": edge_label, "raw": raw_data},
+            }
+
+            # Build adjacency
+            self.adjacency[source_id].add(target_id)
+            self.adjacency[target_id].add(source_id)
+            self.incident_edges[source_id].append(edge_id)
+            self.incident_edges[target_id].append(edge_id)
+
+        for node_id, node_entry in self.nodes.items():
+            _apply_topology_to_node(
+                node_entry,
+                degree=self.deg_node.get(node_id, 0),
+                ranking=rankings_map.get(node_id),
+                highlight=node_id in critical_set,
+            )
+
+        self.stats = self._compute_stats()
+        logger.debug(f"GraphStorage initialized: {len(self.nodes)} nodes, {len(self.edges)} edges")
+
+    def _compute_stats(self) -> Dict[str, Any]:
+        """Compute graph statistics."""
+        if not self.nodes:
+            return {"total_nodes": 0, "total_edges": 0, "avg_degree": 0}
+
+        total_degree = sum(self.deg_node.values())
+        return {
+            "total_nodes": len(self.nodes),
+            "total_edges": len(self.edges),
+            "avg_degree": total_degree / len(self.nodes) if self.nodes else 0,
+        }
+
+    def get_element(self, element_id: str) -> Optional[Dict[str, Any]]:
+        """Get node or edge by ID."""
+        if element_id in self.nodes:
+            return self.nodes[element_id]
+        elif element_id in self.edges:
+            return self.edges[element_id]
+        return None
+
+    def get_details(self, element_id: str) -> Optional[Dict[str, Any]]:
+        """Get full details of a node or edge."""
+        return self.get_element(element_id)
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get graph statistics."""
+        return self.stats
+
+    def export_full_graph(self) -> Dict[str, Any]:
+        """Export all nodes and edges for API / client-side filtering."""
+        return {
+            "nodes": [dict(node) for node in self.nodes.values()],
+            "edges": [dict(edge) for edge in self.edges.values()],
+        }
+
+    def get_sample(
+        self,
+        center_ids: Optional[List[str]] = None,
+        hops: int = 2,
+        highlight_center: bool = False,
+        min_nodes: int = 10,
+        max_attempts: int = 5,
+    ) -> Dict[str, Any]:
+        """Get a subgraph around given center nodes/edges (or random if not provided).
+
+        Args:
+            center_ids: List of node or edge IDs to use as starting points
+            hops: Number of hops to expand
+            highlight_center: If True, mark center nodes/edges with highlighted=True
+            min_nodes: Minimum number of nodes to include in the sample
+            max_attempts: Maximum number of attempts to find a suitable center
+
+        Returns:
+            Dict with 'nodes' and 'edges' keys containing the subgraph
+        """
+        if not center_ids:
+            all_nodes = list(self.nodes.keys())
+            if not all_nodes:
+                return {"nodes": [], "edges": []}
+
+            all_node_ids = set()
+            all_edge_ids = set()
+            result_nodes = []
+            result_edges = []
+
+            for _ in range(max_attempts):
+                current_center = [random.choice(all_nodes)]
+
+                sample = self._get_sample_with_center(current_center, hops, highlight_center)
+
+                for node in sample["nodes"]:
+                    if node["id"] not in all_node_ids:
+                        all_node_ids.add(node["id"])
+                        result_nodes.append(node)
+
+                for edge in sample["edges"]:
+                    if edge["id"] not in all_edge_ids:
+                        all_edge_ids.add(edge["id"])
+                        result_edges.append(edge)
+
+                if len(result_nodes) >= min_nodes:
+                    return {"nodes": result_nodes, "edges": result_edges}
+
+            return {"nodes": result_nodes, "edges": result_edges}
+
+        return self._get_sample_with_center(center_ids, hops, highlight_center)
+
+    def _get_sample_with_center(
+        self,
+        center_ids: List[str],
+        hops: int,
+        highlight_center: bool,
+    ) -> Dict[str, Any]:
+        """Internal method to get sample with given center IDs."""
+        if not center_ids:
+            return {"nodes": [], "edges": []}
+
+        visited_nodes = set()
+        visited_edges = set()
+        center_node_ids = set()
+        center_edge_ids = set()
+
+        for element_id in center_ids:
+            if element_id in self.nodes:
+                visited_nodes.add(element_id)
+                if highlight_center:
+                    center_node_ids.add(element_id)
+            elif element_id in self.edges:
+                visited_edges.add(element_id)
+                if highlight_center:
+                    center_edge_ids.add(element_id)
+                edge_data = self.edges[element_id]
+                visited_nodes.add(edge_data["source"])
+                visited_nodes.add(edge_data["target"])
+
+        if not visited_nodes:
+            return {"nodes": [], "edges": []}
+
+        current_layer = set(visited_nodes)
+
+        for _ in range(hops):
+            next_layer = set()
+            for node_id in current_layer:
+                for edge_id in self.incident_edges.get(node_id, []):
+                    if edge_id not in visited_edges:
+                        visited_edges.add(edge_id)
+                        edge_data = self.edges[edge_id]
+                        other_node = (
+                            edge_data["target"]
+                            if edge_data["source"] == node_id
+                            else edge_data["source"]
+                        )
+                        if other_node not in visited_nodes:
+                            next_layer.add(other_node)
+                            visited_nodes.add(other_node)
+            current_layer = next_layer
+
+        sub_nodes = []
+        for node_id in visited_nodes:
+            node_data = dict(self.nodes[node_id])
+            if highlight_center and node_id in center_node_ids:
+                node_data["highlighted"] = True
+            sub_nodes.append(node_data)
+
+        sub_edges = []
+        for edge_id in visited_edges:
+            edge_data = dict(self.edges[edge_id])
+            if highlight_center and edge_id in center_edge_ids:
+                edge_data["highlighted"] = True
+            sub_edges.append(edge_data)
+
+        logger.debug(f"[GraphStorage] get_sample: {len(sub_nodes)} nodes, {len(sub_edges)} edges")
+        return {"nodes": sub_nodes, "edges": sub_edges}
+
+    def get_all_nodes_paginated(self, page: int = 0, page_size: int = 30) -> Dict[str, Any]:
+        """Get paginated list of all nodes."""
+        # Use values directly to keep the nested {id, data} structure
+        node_items = list(self.nodes.values())
+
+        total = len(node_items)
+        start = page * page_size
+        end = start + page_size
+
+        # For list view, we ensure 'label' and 'type' are at root
+        items = []
+        for node in node_items[start:end]:
+            item = dict(node)
+            item["label"] = node.get("data", {}).get("label", node.get("id"))
+            item["type"] = "node"
+            items.append(item)
+
+        return {
+            "items": items,
+            "page": page,
+            "page_size": page_size,
+            "total": total,
+            "has_next": end < total,
+        }
+
+    def get_all_edges_paginated(self, page: int = 0, page_size: int = 30) -> Dict[str, Any]:
+        """Get paginated list of all edges."""
+        edge_items = list(self.edges.values())
+
+        total = len(edge_items)
+        start = page * page_size
+        end = start + page_size
+
+        items = []
+        for edge in edge_items[start:end]:
+            item = dict(edge)
+            item["label"] = edge.get("data", {}).get("label", edge.get("id"))
+            item["type"] = "edge"
+            items.append(item)
+
+        return {
+            "items": items,
+            "page": page,
+            "page_size": page_size,
+            "total": total,
+            "has_next": end < total,
+        }
+
+    def get_sample_from_data(
+        self,
+        node_list: List[NodeSchema],
+        edge_list: List[EdgeSchema],
+        hops: int = 2,
+        highlight_center: bool = False,
+    ) -> Dict[str, Any]:
+        """Get sample based on raw node and edge data objects.
+
+        Extracts IDs from the provided raw data using extractors and label_to_id mapping.
+
+        Args:
+            node_list: List of NodeSchema objects to extract IDs from
+            edge_list: List of EdgeSchema objects to extract IDs from
+            hops: Number of hops for neighborhood expansion
+            highlight_center: If True, mark extracted nodes and edges with highlighted=True
+
+        Returns:
+            Dict with 'nodes' and 'edges' keys containing the subgraph
+        """
+        # Extract node IDs
+        node_ids = []
+        for node in node_list:
+            node_id = self.node_id_extractor(node)
+            if node_id in self.nodes:
+                node_ids.append(node_id)
+            else:
+                logger.debug(f"Node {self.node_label_extractor(node)} not found in graph")
+
+        # Extract edge IDs
+        edge_ids = []
+        for edge in edge_list:
+            edge_id = self.edge_id_extractor(edge)
+            if edge_id in self.edges:
+                edge_ids.append(edge_id)
+            else:
+                logger.debug(f"Edge {self.edge_label_extractor(edge)} not found in graph")
+
+        # Combine node and edge IDs and call get_sample with highlight_center
+        all_ids = node_ids + edge_ids
+        if all_ids:
+            return self.get_sample(center_ids=all_ids, hops=hops, highlight_center=highlight_center)
+        else:
+            return {"nodes": [], "edges": []}