graphcontainer 0.1.0__py3-none-any.whl

graphcontainer/__init__.py

@@ -0,0 +1,123 @@
+from .base import BaseGraphContainer
+from .core import SearchableGraphContainer, SimpleGraphContainer
+from .index import BaseIndexer
+from .indexers import ChromaCollectionIndexer, InMemoryVectorIndexer, PGVectorIndexer
+from .types import EdgeRecord, NodeRecord
+from .adapters import (
+    FastInsightAdapter,
+    GraphAdapter,
+    GraphAdapterError,
+    LightRAGAdapter,
+    UnsupportedSourceError,
+    import_graph_from_attribute_bundle_graph,
+    import_graph_from_component_graph,
+    import_graph_from_fastinsight,
+    import_graph_from_lightrag,
+    import_graph_from_subgraph_union_graph,
+    import_graph_from_topology_semantic_graph,
+)
+from .visualizer import (
+    LiveGraphVisualizer,
+    LiveVisualizerClient,
+    VisualizerHTTPError,
+    clear_session,
+    create_session,
+    delete_session,
+    get_config,
+    get_session_snapshot,
+    get_session_subgraph,
+    health,
+    list_sessions,
+    set_progress,
+    serve_attribute_bundle_graph,
+    serve_component_graph,
+    serve_fastinsight,
+    serve_g_retriever,
+    serve_graph,
+    serve_hipporag,
+    serve_lightrag,
+    serve_multi,
+    serve_subgraph_union_graph,
+    serve_topology_semantic_graph,
+    serve_tog,
+    update_session,
+)
+from .rag import (
+    BaseRetriever,
+    ChatMessage,
+    ChatRequest,
+    ChatResponse,
+    GraphRAGPipeline,
+    GraphRAGService,
+    FastInsightRetriever,
+    HybridRetriever,
+    OneHopRetriever,
+    OpenAIChatGenerator,
+    OpenAIEmbedder,
+    RetrievedNode,
+    RetrievalResult,
+    VectorRetriever,
+)
+
+__all__ = [
+    "BaseGraphContainer",
+    "SearchableGraphContainer",
+    "SimpleGraphContainer",
+    "BaseIndexer",
+    "EdgeRecord",
+    "NodeRecord",
+    "GraphAdapter",
+    "GraphAdapterError",
+    "UnsupportedSourceError",
+    "FastInsightAdapter",
+    "LightRAGAdapter",
+    "InMemoryVectorIndexer",
+    "ChromaCollectionIndexer",
+    "PGVectorIndexer",
+    "import_graph_from_component_graph",
+    "import_graph_from_attribute_bundle_graph",
+    "import_graph_from_topology_semantic_graph",
+    "import_graph_from_subgraph_union_graph",
+    "import_graph_from_fastinsight",
+    "import_graph_from_lightrag",
+    "render_graph_html",
+    "render_fastinsight_html",
+    "LiveGraphVisualizer",
+    "serve_graph",
+    "serve_component_graph",
+    "serve_attribute_bundle_graph",
+    "serve_topology_semantic_graph",
+    "serve_subgraph_union_graph",
+    "serve_fastinsight",
+    "serve_lightrag",
+    "serve_hipporag",
+    "serve_g_retriever",
+    "serve_tog",
+    "serve_multi",
+    "VisualizerHTTPError",
+    "LiveVisualizerClient",
+    "health",
+    "get_config",
+    "list_sessions",
+    "create_session",
+    "get_session_snapshot",
+    "get_session_subgraph",
+    "update_session",
+    "set_progress",
+    "clear_session",
+    "delete_session",
+    "ChatMessage",
+    "ChatRequest",
+    "ChatResponse",
+    "RetrievedNode",
+    "RetrievalResult",
+    "OpenAIEmbedder",
+    "OpenAIChatGenerator",
+    "BaseRetriever",
+    "OneHopRetriever",
+    "VectorRetriever",
+    "HybridRetriever",
+    "FastInsightRetriever",
+    "GraphRAGPipeline",
+    "GraphRAGService",
+]

graphcontainer/adapters/__init__.py

@@ -0,0 +1,35 @@
+# src/GraphContainer/adapters/__init__.py
+from .base import GraphAdapter, GraphAdapterError, UnsupportedSourceError
+from .fastinsight import FastInsightAdapter, import_graph_from_fastinsight
+from .expla_graphs import ExplaGraphsAdapter, import_graph_from_expla_graphs
+from .freebasekg import FreebaseKGAdapter, import_graph_from_freebasekg
+from .g_retriever import GRetrieverAdapter, import_graph_from_g_retriever
+from .lightrag import LightRAGAdapter, import_graph_from_lightrag
+from .hipporag import HippoRAGAdapter, import_graph_from_hipporag
+
+import_graph_from_component_graph = import_graph_from_fastinsight
+import_graph_from_attribute_bundle_graph = import_graph_from_lightrag
+import_graph_from_topology_semantic_graph = import_graph_from_hipporag
+import_graph_from_subgraph_union_graph = import_graph_from_g_retriever
+
+__all__ = [
+    "GraphAdapter",
+    "GraphAdapterError",
+    "UnsupportedSourceError",
+    "FastInsightAdapter",
+    "ExplaGraphsAdapter",
+    "FreebaseKGAdapter",
+    "GRetrieverAdapter",
+    "LightRAGAdapter",
+    "HippoRAGAdapter",
+    "import_graph_from_component_graph",
+    "import_graph_from_attribute_bundle_graph",
+    "import_graph_from_topology_semantic_graph",
+    "import_graph_from_subgraph_union_graph",
+    "import_graph_from_fastinsight",
+    "import_graph_from_expla_graphs",
+    "import_graph_from_freebasekg",
+    "import_graph_from_lightrag",
+    "import_graph_from_hipporag",
+    "import_graph_from_g_retriever",
+]

graphcontainer/adapters/base.py

@@ -0,0 +1,50 @@
+# src/GraphContainer/adapters/base.py
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+from ..core import SimpleGraphContainer
+
+
+class GraphAdapterError(RuntimeError):
+    """Base error for adapter-level failures."""
+
+
+class UnsupportedSourceError(GraphAdapterError):
+    """Raised when an adapter cannot import the given source."""
+
+
+class GraphAdapter(ABC):
+    """Base interface for importing / exporting graphs."""
+
+    def __init__(self, *, name: str, version: str = "0.1.0"):
+        self.name = name
+        self.version = version
+
+    @abstractmethod
+    def can_import(self, source: Any) -> bool:
+        """Return True if this adapter can import the given source."""
+
+    @abstractmethod
+    def import_graph(
+        self,
+        source: Any,
+        container: Optional[SimpleGraphContainer] = None,
+        *,
+        keep_source_reference: bool = False,
+    ) -> SimpleGraphContainer:
+        """Load a graph from source into a container.
+
+        keep_source_reference is adapter-defined optional metadata.
+        """
+
+    @abstractmethod
+    def export_graph(
+        self,
+        container: SimpleGraphContainer,
+        destination: Any,
+        *,
+        overwrite: bool = False,
+    ) -> Dict[str, Any]:
+        """Serialize container into destination format and return result metadata."""

graphcontainer/adapters/expla_graphs.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import csv
+import json
+import re
+from hashlib import md5
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, Optional, Tuple
+
+from ..core import SearchableGraphContainer, SimpleGraphContainer
+from ..types import EdgeRecord, NodeRecord
+from ..utils import container_or_new
+from .base import GraphAdapter, GraphAdapterError, UnsupportedSourceError
+
+
+_TRIPLE_RE = re.compile(r"\((.*?)\)")
+
+
+def _normalize_source(source: Any) -> Path:
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        if path.is_dir():
+            return path / "train_dev.tsv"
+        return path
+    raise UnsupportedSourceError(f"Unsupported source type: {type(source)}")
+
+
+def _iter_tsv_rows(path: Path) -> Iterable[Dict[str, Any]]:
+    if not path.exists():
+        raise UnsupportedSourceError(f"Required file not found: {path}")
+
+    with path.open("r", encoding="utf-8", newline="") as f:
+        reader = csv.DictReader(f, delimiter="\t")
+        for row in reader:
+            if row:
+                yield row
+
+
+def _normalize_text(value: Any) -> str:
+    if value is None:
+        return ""
+    return " ".join(str(value).strip().lower().split())
+
+
+def _parse_triplets(graph_text: str) -> Iterator[Tuple[str, str, str]]:
+    for chunk in _TRIPLE_RE.findall(graph_text or ""):
+        parts = [p.strip() for p in chunk.split(";", maxsplit=2)]
+        if len(parts) != 3:
+            continue
+        src, rel, dst = parts
+        if not src or not dst:
+            continue
+        yield src, rel, dst
+
+
+class ExplaGraphsAdapter(GraphAdapter):
+    """Adapter for Expla_graphs train_dev.tsv format."""
+
+    def __init__(self):
+        super().__init__(name="expla_graphs", version="0.1.0")
+
+    def can_import(self, source: Any) -> bool:
+        try:
+            src = _normalize_source(source)
+            return src.is_file() and src.suffix.lower() in {".tsv", ".txt"}
+        except Exception:
+            return False
+
+    def import_graph(
+        self,
+        source: Any,
+        container: Optional[SimpleGraphContainer] = None,
+        *,
+        keep_source_reference: bool = False,
+        **kwargs: Any,
+    ) -> SearchableGraphContainer:
+        src_path = _normalize_source(source)
+
+        graph = container_or_new(container)
+
+        # Deduplicate nodes/edges across rows by default.
+        node_key_to_id: Dict[Tuple[str, str], str] = {}
+        edge_key_to_idx: Dict[Tuple[str, str, str], int] = {}
+
+        for row_idx, row in enumerate(_iter_tsv_rows(src_path)):
+            graph_text = row.get("graph")
+            if not graph_text:
+                continue
+
+            for src, rel, dst in _parse_triplets(graph_text):
+                src_text = _normalize_text(src)
+                dst_text = _normalize_text(dst)
+                rel_text = _normalize_text(rel) or "related"
+
+                src_key = ("entity", src_text)
+                dst_key = ("entity", dst_text)
+
+                src_id = node_key_to_id.get(src_key)
+                if src_id is None:
+                    src_id = f"node-{md5(f'{src_key[0]}|{src_key[1]}'.encode()).hexdigest()}"
+                    node_key_to_id[src_key] = src_id
+                    metadata: Dict[str, Any] = {
+                        "original_label": src_id,
+                    }
+                    if keep_source_reference:
+                        metadata.setdefault("_source_path", str(src_path))
+                        metadata.setdefault("_source_style", "expla_graphs")
+                    graph.add_node(
+                        NodeRecord(
+                            id=src_id,
+                            type="Entity",
+                            text=src,
+                            metadata=metadata,
+                        )
+                    )
+
+                dst_id = node_key_to_id.get(dst_key)
+                if dst_id is None:
+                    dst_id = f"node-{md5(f'{dst_key[0]}|{dst_key[1]}'.encode()).hexdigest()}"
+                    node_key_to_id[dst_key] = dst_id
+                    metadata = {
+                        "original_label": dst_id,
+                    }
+                    if keep_source_reference:
+                        metadata.setdefault("_source_path", str(src_path))
+                        metadata.setdefault("_source_style", "expla_graphs")
+                    graph.add_node(
+                        NodeRecord(
+                            id=dst_id,
+                            type="Entity",
+                            text=dst,
+                            metadata=metadata,
+                        )
+                    )
+
+                edge_key = (src_id, rel_text, dst_id)
+                if edge_key in edge_key_to_idx:
+                    continue
+
+                metadata = {}
+                if keep_source_reference:
+                    metadata.setdefault("_source_path", str(src_path))
+                    metadata.setdefault("_source_style", "expla_graphs")
+
+                graph.add_edge(
+                    EdgeRecord(
+                        source=src_id,
+                        target=dst_id,
+                        relation=rel_text,
+                        weight=1.0,
+                        metadata=metadata,
+                    )
+                )
+                edge_key_to_idx[edge_key] = len(graph.edges) - 1
+
+        return graph
+
+    def export_graph(
+        self,
+        container: SimpleGraphContainer,
+        destination: Any,
+        *,
+        overwrite: bool = False,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        dest = Path(destination)
+        if dest.exists() and not overwrite and any(dest.iterdir()):
+            raise GraphAdapterError(f"Destination is not empty: {dest}")
+        dest.mkdir(parents=True, exist_ok=True)
+
+        node_path = dest / "nodes.jsonl"
+        edge_path = dest / "edges.jsonl"
+
+        with node_path.open("w", encoding="utf-8") as f:
+            for node in container.nodes.values():
+                payload = {
+                    "id": node.id,
+                    "text": node.text,
+                    "type": node.type,
+                    **node.metadata,
+                }
+                if node.embedding is not None:
+                    payload["embedding"] = (
+                        node.embedding.tolist()
+                        if hasattr(node.embedding, "tolist")
+                        else list(node.embedding)
+                    )
+                f.write(json.dumps(payload, ensure_ascii=False) + "\n")
+
+        with edge_path.open("w", encoding="utf-8") as f:
+            for edge in container.edges:
+                payload = {
+                    "source": edge.source,
+                    "target": edge.target,
+                    "relation": edge.relation,
+                    "weight": edge.weight,
+                    **edge.metadata,
+                }
+                f.write(json.dumps(payload, ensure_ascii=False) + "\n")
+
+        return {
+            "destination": str(dest),
+            "node_file": str(node_path),
+            "edge_file": str(edge_path),
+            "nodes": len(container.nodes),
+            "edges": len(container.edges),
+        }
+
+
+def import_graph_from_expla_graphs(
+    source: Any,
+    *,
+    container: Optional[SimpleGraphContainer] = None,
+    keep_source_reference: bool = False,
+    **kwargs: Any,
+) -> SearchableGraphContainer:
+    return ExplaGraphsAdapter().import_graph(
+        source=source,
+        container=container,
+        keep_source_reference=keep_source_reference,
+        **kwargs,
+    )

graphcontainer/adapters/fastinsight.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterator, Optional, Tuple
+
+from ..core import SearchableGraphContainer, SimpleGraphContainer
+from ..types import EdgeRecord, NodeRecord
+from ..utils import container_or_new
+from .base import GraphAdapter, GraphAdapterError, UnsupportedSourceError
+from ..indexers import ChromaCollectionIndexer
+
+
+def _normalize_source(source: Any) -> Path:
+    if isinstance(source, (str, Path)):
+        return Path(source)
+    raise UnsupportedSourceError(f"Unsupported source type: {type(source)}")
+
+
+def _iter_jsonl(path: Path) -> Iterator[Dict[str, Any]]:
+    if not path.exists():
+        raise UnsupportedSourceError(f"Required file not found: {path}")
+
+    with path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            item = json.loads(line)
+            if isinstance(item, dict):
+                yield item
+            elif isinstance(item, list):
+                # edges.jsonl may use list rows.
+                yield {"_list": item}
+
+
+def _parse_edge(raw: Dict[str, Any]) -> Optional[Tuple[str, str]]:
+    if "_list" in raw:
+        row = raw["_list"]
+        if isinstance(row, list) and len(row) >= 2:
+            return str(row[0]), str(row[1])
+        return None
+
+    source = raw.get("src", raw.get("source"))
+    target = raw.get("tgt", raw.get("target"))
+    if source is None or target is None:
+        return None
+    return str(source), str(target)
+
+
+class FastInsightAdapter(GraphAdapter):
+    def __init__(self):
+        super().__init__(name="component_graph", version="0.1.0")
+
+    def can_import(self, source: Any) -> bool:
+        try:
+            src = _normalize_source(source)
+            return (src / "nodes.jsonl").exists() and (src / "edges.jsonl").exists()
+        except Exception:
+            return False
+
+    def _get_manifest(self, path: Path) -> Dict[str, Any]:
+        for name in ("manifest.json", "menifest.json"):
+            p = path / name
+            if p.exists():
+                return json.loads(p.read_text(encoding="utf-8"))
+        return {}
+
+    def import_graph(
+        self,
+        source: Any,
+        container: Optional[SimpleGraphContainer] = None,
+        *,
+        keep_source_reference: bool = False,
+        **kwargs: Any,
+    ) -> SearchableGraphContainer:
+        src_path = _normalize_source(source)
+        manifest = self._get_manifest(src_path)
+        v_cfg = manifest.get("vector_store", {})
+
+        # Priority: kwargs > manifest > default
+        col_name = kwargs.get("collection_name") or v_cfg.get("collection_name")
+        db_path = kwargs.get("vector_store_path") or v_cfg.get("path")
+        distance_metric = str(kwargs.get("distance_metric", v_cfg.get("distance_metric", "cosine")))
+
+        graph = container_or_new(container)
+
+        for raw in _iter_jsonl(src_path / "nodes.jsonl"):
+            node_id = raw.get("id")
+            if node_id is None:
+                continue
+            metadata = {k: v for k, v in raw.items() if k not in {"id", "text", "type"}}
+            if keep_source_reference:
+                metadata.setdefault("_source_path", str(src_path))
+                metadata.setdefault("_source_style", "component_graph")
+            graph.add_node(
+                NodeRecord(
+                    id=str(node_id),
+                    type=str(raw.get("type", "Chunk")),
+                    text=raw.get("text"),
+                    metadata=metadata,
+                )
+            )
+
+        for raw in _iter_jsonl(src_path / "edges.jsonl"):
+            endpoints = _parse_edge(raw)
+            if endpoints is None:
+                continue
+            source_id, target_id = endpoints
+            graph.add_edge(EdgeRecord(source=source_id, target=target_id))
+
+        if col_name:
+            import chromadb
+
+            if not db_path:
+                db_path = f"./data/database/chroma_db/{col_name}"
+            client = chromadb.PersistentClient(path=str(Path(str(db_path)).resolve()))
+            col = client.get_or_create_collection(name=str(col_name))
+            indexer = ChromaCollectionIndexer(
+                col,
+                persist_path=str(db_path),
+                distance_metric=distance_metric,
+            )
+            graph.attach_index(str(col_name), indexer)
+            graph.attach_index("node_vector", indexer)
+
+        return graph
+
+    def export_graph(
+        self,
+        container: SimpleGraphContainer,
+        destination: Any,
+        *,
+        overwrite: bool = False,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        dest = Path(destination)
+        if dest.exists() and not overwrite and any(dest.iterdir()):
+            raise GraphAdapterError(f"Destination is not empty: {dest}")
+        dest.mkdir(parents=True, exist_ok=True)
+
+        node_path = dest / "nodes.jsonl"
+        edge_path = dest / "edges.jsonl"
+
+        with node_path.open("w", encoding="utf-8") as f:
+            for n in container.nodes.values():
+                payload = {"id": n.id, "text": n.text, "type": n.type, **n.metadata}
+                f.write(json.dumps(payload, ensure_ascii=False) + "\n")
+
+        with edge_path.open("w", encoding="utf-8") as f:
+            for e in container.edges:
+                f.write(json.dumps([e.source, e.target], ensure_ascii=False) + "\n")
+
+        store_info = None
+        if isinstance(container, SearchableGraphContainer):
+            idx = container.get_index("node_vector")
+            if idx is not None and hasattr(idx, "describe_store"):
+                store_info = idx.describe_store()
+
+        col_name = kwargs.get("collection_name", dest.name)
+        vector_path = kwargs.get("vector_store_path", f"./chroma_db/{col_name}")
+        manifest = {
+            "vector_store": store_info
+            or {
+                "library": "chromadb",
+                "path": vector_path,
+                "collection_name": col_name,
+                "distance_metric": kwargs.get("distance_metric", "cosine"),
+            }
+        }
+        (dest / "manifest.json").write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+
+        return {
+            "destination": str(dest),
+            "node_file": str(node_path),
+            "edge_file": str(edge_path),
+            "nodes": len(container.nodes),
+            "edges": len(container.edges),
+        }
+
+
+def import_graph_from_fastinsight(
+    source: Any,
+    *,
+    container: Optional[SimpleGraphContainer] = None,
+    keep_source_reference: bool = False,
+    **kwargs: Any,
+) -> SearchableGraphContainer:
+    return FastInsightAdapter().import_graph(
+        source=source,
+        container=container,
+        keep_source_reference=keep_source_reference,
+        **kwargs,
+    )