sayou-visualizer 0.0.12__tar.gz → 0.1.0__tar.gz

{sayou_visualizer-0.0.12 → sayou_visualizer-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sayou-visualizer
-Version: 0.0.12
+Version: 0.1.0
 Summary: Visualizer components for the Sayou Data Platform
 Project-URL: Homepage, https://www.sayouzone.com/
 Project-URL: Documentation, https://sayouzone.github.io/sayou-fabric/
@@ -209,15 +209,15 @@ License:                                  Apache License
            limitations under the License.
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Requires-Dist: networkx==3.2.1
 Requires-Dist: pyvis==0.3.2
 Requires-Dist: rich==14.2.0
-Requires-Dist: sayou-core~=0.3.0
+Requires-Dist: sayou-core~=0.4.0
 Requires-Dist: websocket-client==1.9.0
 Description-Content-Type: text/markdown
 
@@ -228,67 +228,123 @@ Description-Content-Type: text/markdown
 
 **The Interactive Observability Engine for Sayou Fabric.**
 
-`sayou-visualizer` provides a transparent layer to monitor and visualize the execution flow of Sayou components. By attaching to any pipeline, it transforms invisible execution logs into intuitive, interactive **HTML Knowledge Graphs**.
+`sayou-visualizer` provides transparency to the "Black Box" of data pipelines. It transforms invisible execution logs and complex graph data structures into intuitive, interactive **3D Holographic Knowledge Graphs**.
 
-It separates the logic of **Observation** (Tracer) from **Presentation** (Renderer), allowing you to debug complex pipelines and visualize data lineage without modifying your core logic.
+It serves two distinct purposes: **Pipeline Telemetry** (Debugging flow) and **Knowledge Rendering** (Showcasing data topology).
 
-## 💡 Core Philosophy
+---
 
-**"Trace the Process, Render the Insight."**
+## 1. Architecture & Role
 
-Observability should not be an afterthought. We decouple the responsibility into two roles:
+The Visualizer operates as a separate layer that can attach to a running pipeline (Tracer) or read static data (Renderer) to generate HTML artifacts.
 
-1. **Tracer (Recorder)**: The "Camera". It silently observes events (`on_start`, `on_finish`) from the pipeline via the Callback system and builds an internal graph structure.
+```mermaid
+graph LR
+    Data[Pipeline / JSON] --> Pipeline[Visualizer Pipeline]
+    
+    subgraph Renderers
+        Tracer[DAG Tracer]
+        Analyst[Analyst KG View]
+        Showcase[Showcase 3D View]
+    end
+    
+    Pipeline --> Renderers
+    Renderers --> HTML[Interactive HTML]
+```
+
+### 1.1. Core Features
+* **Non-Intrusive Monitoring**: Attaches to any Sayou pipeline via the callback system to visualize execution flow without modifying code.
+* **Deterministic Layout**: Uses physics-based rendering (Cytoscape/Force-Graph) to reveal clusters and outliers in your data.
+* **Interactive Inspection**: Click on nodes to inspect raw attributes, source code, or relationships in real-time.
+
+---
 
-2. **Renderer (Painter)**: The "Canvas". It takes the recorded graph and generates human-readable artifacts (e.g., Interactive HTML, Static Images).
+## 2. Available Strategies
 
-This separation enables a Non-intrusive Monitoring experience, where visualization is just a plug-and-play feature.
+`sayou-visualizer` offers specialized views depending on who is looking at the data.
 
-## 📦 Installation
+| Strategy Key | Target Audience | Description |
+| :--- | :--- | :--- |
+| **`tracer`** | Data Engineer | Visualizes the **Pipeline Execution Flow** (DAG). Shows which components triggered which tasks. |
+| **`analyst`** | QA / Researcher | **2D Analytic View**. Focuses on strict schema validation, attribute inspection, and debugging specific relationships. |
+| **`showcase`** | Stakeholder | **3D Holographic View**. A visually stunning, high-performance renderer for presenting the scale and topology of the Knowledge Graph. |
+
+---
+
+## 3. Installation
 
 ```bash
 pip install sayou-visualizer
 ```
 
-## ⚡ Quick Start
+---
+
+## 4. Usage
 
-The `VisualizerPipeline` acts as a facade, easily attaching to other pipelines to generate reports.
+The `VisualizerPipeline` is the entry point. You can use it to render existing graph files or attach it to live pipelines.
+
+### Case A: Rendering a Knowledge Graph (3D Showcase)
+
+Visualizes the output of `sayou-assembler` as an interactive 3D galaxy.
 
 ```python
-from sayou.connector.pipeline import ConnectorPipeline
-from sayou.visualizer.pipeline import VisualizerPipeline
+from sayou.visualizer import VisualizerPipeline
+
+viz = VisualizerPipeline()
+
+kg_file_path = "./output/graph_data.json"
+
+viz.process(
+    source=kg_file_path,
+    destination="./output/report_showcase.html",
+    strategy="showcase"
+)
 
-def main():
-    connector = ConnectorPipeline()
+print("Report generated. Open 'report_showcase.html' in your browser.")
+```
+
+### Case B: Debugging Graph Data (2D Analyst)
+
+Generates a detailed 2D view for inspecting node attributes and edge types.
+
+```python
+viz.process(
+    source=kg_file_path,
+    destination="./output/report_analyst.html",
+    strategy="analyst"
+)
+```
+
+### Case C: Pipeline Tracing (Live Monitoring)
+
+Attaches to a running Connector pipeline to visualize the crawling process.
+
+```python
+from sayou.connector import ConnectorPipeline
+from sayou.visualizer import VisualizerPipeline
 
-    viz = VisualizerPipeline()
-    viz.attach_to(connector)
+connector = ConnectorPipeline()
 
-    print("🚀 Running Pipeline...")
-    iterator = connector.run("http://example.com")
-    for packet in iterator:
-        print(f"Processed: {packet.task.uri}")
+viz = VisualizerPipeline()
+viz.attach_to(connector)
 
-    print("🎨 Generating Report...")
-    viz.report("examples/pipeline_flow.html")
+connector.process(source="https://news.daum.net/tech", strategy="web")
 
-if __name__ == "__main__":
-    main()
+viz.report("pipeline_trace.html")
 ```
 
-## 🔑 Key Concepts
+---
 
-### Tracers
-* **`GraphTracer`**: Listens to pipeline events and constructs a `NetworkX` Directed Acyclic Graph (DAG) in real-time. It distinguishes between Components (Generator/Fetcher) and Data (Tasks).
+## 5. Configuration Keys
 
-### Renderers
-* **`PyVisRenderer`**: Converts the internal graph into an interactive HTML file powered by `Vis.js`. Features physics-based layout and modern dark UI.
-* **`RichRenderer`** (_Planned_): Displays a tree-structure summary directly in the console using the `Rich` library.
+Customize the visual appearance via the `config` dictionary.
 
-## 🤝 Contributing
+* **`showcase`**: `node_color_by` (e.g., class), `particle_speed`, `background_color`.
+* **`analyst`**: `layout_algorithm` (dagre/concentric), `show_attributes` (bool).
+* **`tracer`**: `include_data_payload` (bool), `max_events`.
 
-We welcome contributions for new Renderers (e.g., `MatplotlibRenderer`, `StreamlitRenderer`) or specialized Tracers for new components!
+---
 
-## 📜 License
+## 6. License
 
-Apache 2.0 License © 2025 Sayouzone
+Apache 2.0 License © 2026 **Sayouzone**

sayou_visualizer-0.1.0/README.md

@@ -0,0 +1,127 @@
+# sayou-visualizer
+
+[![PyPI version](https://img.shields.io/pypi/v/sayou-visualizer.svg?color=blue)](https://pypi.org/project/sayou-visualizer/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-red.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+**The Interactive Observability Engine for Sayou Fabric.**
+
+`sayou-visualizer` provides transparency to the "Black Box" of data pipelines. It transforms invisible execution logs and complex graph data structures into intuitive, interactive **3D Holographic Knowledge Graphs**.
+
+It serves two distinct purposes: **Pipeline Telemetry** (Debugging flow) and **Knowledge Rendering** (Showcasing data topology).
+
+---
+
+## 1. Architecture & Role
+
+The Visualizer operates as a separate layer that can attach to a running pipeline (Tracer) or read static data (Renderer) to generate HTML artifacts.
+
+```mermaid
+graph LR
+    Data[Pipeline / JSON] --> Pipeline[Visualizer Pipeline]
+    
+    subgraph Renderers
+        Tracer[DAG Tracer]
+        Analyst[Analyst KG View]
+        Showcase[Showcase 3D View]
+    end
+    
+    Pipeline --> Renderers
+    Renderers --> HTML[Interactive HTML]
+```
+
+### 1.1. Core Features
+* **Non-Intrusive Monitoring**: Attaches to any Sayou pipeline via the callback system to visualize execution flow without modifying code.
+* **Deterministic Layout**: Uses physics-based rendering (Cytoscape/Force-Graph) to reveal clusters and outliers in your data.
+* **Interactive Inspection**: Click on nodes to inspect raw attributes, source code, or relationships in real-time.
+
+---
+
+## 2. Available Strategies
+
+`sayou-visualizer` offers specialized views depending on who is looking at the data.
+
+| Strategy Key | Target Audience | Description |
+| :--- | :--- | :--- |
+| **`tracer`** | Data Engineer | Visualizes the **Pipeline Execution Flow** (DAG). Shows which components triggered which tasks. |
+| **`analyst`** | QA / Researcher | **2D Analytic View**. Focuses on strict schema validation, attribute inspection, and debugging specific relationships. |
+| **`showcase`** | Stakeholder | **3D Holographic View**. A visually stunning, high-performance renderer for presenting the scale and topology of the Knowledge Graph. |
+
+---
+
+## 3. Installation
+
+```bash
+pip install sayou-visualizer
+```
+
+---
+
+## 4. Usage
+
+The `VisualizerPipeline` is the entry point. You can use it to render existing graph files or attach it to live pipelines.
+
+### Case A: Rendering a Knowledge Graph (3D Showcase)
+
+Visualizes the output of `sayou-assembler` as an interactive 3D galaxy.
+
+```python
+from sayou.visualizer import VisualizerPipeline
+
+viz = VisualizerPipeline()
+
+kg_file_path = "./output/graph_data.json"
+
+viz.process(
+    source=kg_file_path,
+    destination="./output/report_showcase.html",
+    strategy="showcase"
+)
+
+print("Report generated. Open 'report_showcase.html' in your browser.")
+```
+
+### Case B: Debugging Graph Data (2D Analyst)
+
+Generates a detailed 2D view for inspecting node attributes and edge types.
+
+```python
+viz.process(
+    source=kg_file_path,
+    destination="./output/report_analyst.html",
+    strategy="analyst"
+)
+```
+
+### Case C: Pipeline Tracing (Live Monitoring)
+
+Attaches to a running Connector pipeline to visualize the crawling process.
+
+```python
+from sayou.connector import ConnectorPipeline
+from sayou.visualizer import VisualizerPipeline
+
+connector = ConnectorPipeline()
+
+viz = VisualizerPipeline()
+viz.attach_to(connector)
+
+connector.process(source="https://news.daum.net/tech", strategy="web")
+
+viz.report("pipeline_trace.html")
+```
+
+---
+
+## 5. Configuration Keys
+
+Customize the visual appearance via the `config` dictionary.
+
+* **`showcase`**: `node_color_by` (e.g., class), `particle_speed`, `background_color`.
+* **`analyst`**: `layout_algorithm` (dagre/concentric), `show_attributes` (bool).
+* **`tracer`**: `include_data_payload` (bool), `max_events`.
+
+---
+
+## 6. License
+
+Apache 2.0 License © 2026 **Sayouzone**

{sayou_visualizer-0.0.12 → sayou_visualizer-0.1.0}/pyproject.toml

@@ -7,24 +7,24 @@ build-backend = "hatchling.build"
 # -----------------
 [project]
 name = "sayou-visualizer"
-version = "0.0.12"
+version = "0.1.0"
 authors = [
     { name = "Sayouzone", email = "contact@sayouzone.com" },
 ]
 description = "Visualizer components for the Sayou Data Platform"
 readme = "README.md"
 license = { file = "../../LICENSE" }
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 classifiers = [
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
     "Topic :: Software Development :: Libraries :: Application Frameworks",
 ]
 dependencies = [
-    "sayou-core ~= 0.3.0",
+    "sayou-core ~= 0.4.0",
     "networkx == 3.2.1",
     "pyvis == 0.3.2",
     "rich == 14.2.0",

sayou_visualizer-0.0.12/README.md

@@ -1,71 +0,0 @@
-# sayou-visualizer
-
-[![PyPI version](https://img.shields.io/pypi/v/sayou-visualizer.svg?color=blue)](https://pypi.org/project/sayou-visualizer/)
-[![License](https://img.shields.io/badge/License-Apache%202.0-red.svg)](https://www.apache.org/licenses/LICENSE-2.0)
-
-**The Interactive Observability Engine for Sayou Fabric.**
-
-`sayou-visualizer` provides a transparent layer to monitor and visualize the execution flow of Sayou components. By attaching to any pipeline, it transforms invisible execution logs into intuitive, interactive **HTML Knowledge Graphs**.
-
-It separates the logic of **Observation** (Tracer) from **Presentation** (Renderer), allowing you to debug complex pipelines and visualize data lineage without modifying your core logic.
-
-## 💡 Core Philosophy
-
-**"Trace the Process, Render the Insight."**
-
-Observability should not be an afterthought. We decouple the responsibility into two roles:
-
-1. **Tracer (Recorder)**: The "Camera". It silently observes events (`on_start`, `on_finish`) from the pipeline via the Callback system and builds an internal graph structure.
-
-2. **Renderer (Painter)**: The "Canvas". It takes the recorded graph and generates human-readable artifacts (e.g., Interactive HTML, Static Images).
-
-This separation enables a Non-intrusive Monitoring experience, where visualization is just a plug-and-play feature.
-
-## 📦 Installation
-
-```bash
-pip install sayou-visualizer
-```
-
-## ⚡ Quick Start
-
-The `VisualizerPipeline` acts as a facade, easily attaching to other pipelines to generate reports.
-
-```python
-from sayou.connector.pipeline import ConnectorPipeline
-from sayou.visualizer.pipeline import VisualizerPipeline
-
-def main():
-    connector = ConnectorPipeline()
-
-    viz = VisualizerPipeline()
-    viz.attach_to(connector)
-
-    print("🚀 Running Pipeline...")
-    iterator = connector.run("http://example.com")
-    for packet in iterator:
-        print(f"Processed: {packet.task.uri}")
-
-    print("🎨 Generating Report...")
-    viz.report("examples/pipeline_flow.html")
-
-if __name__ == "__main__":
-    main()
-```
-
-## 🔑 Key Concepts
-
-### Tracers
-* **`GraphTracer`**: Listens to pipeline events and constructs a `NetworkX` Directed Acyclic Graph (DAG) in real-time. It distinguishes between Components (Generator/Fetcher) and Data (Tasks).
-
-### Renderers
-* **`PyVisRenderer`**: Converts the internal graph into an interactive HTML file powered by `Vis.js`. Features physics-based layout and modern dark UI.
-* **`RichRenderer`** (_Planned_): Displays a tree-structure summary directly in the console using the `Rich` library.
-
-## 🤝 Contributing
-
-We welcome contributions for new Renderers (e.g., `MatplotlibRenderer`, `StreamlitRenderer`) or specialized Tracers for new components!
-
-## 📜 License
-
-Apache 2.0 License © 2025 Sayouzone