scitex 2.8.1__py3-none-any.whl → 2.10.2__py3-none-any.whl

scitex/scholar/docs/to_claude/guidelines/examples/mgmt/ARCHITECTURE_EXAMPLE.md

@@ -1,905 +0,0 @@
-# Agreed Architecture v06 - Graph Visualization Enhancement
-
-## Executive Summary
-
-``` yaml
-project_context:
-  current_state:
-    test_success_rate: 99.1% (1474 passed, 13 failed, 24 skipped)
-    graph_infrastructure: "Comprehensive NetworkX-based KnowledgeGraphManager"
-    node_types: ["document", "chunk", "entity"]
-    relationship_extraction: "Sophisticated patterns for cross-references"
-    persistence: "Pickle-based graph serialization"
-    mcp_integration: "FastMCP 2.0 compliant server"
-
-  enhancement_scope:
-    purpose: "Add powerful visualization capabilities to existing graph infrastructure"
-    key_features:
-      - Document connectivity visualization (Connected Papers-style)
-      - Interactive exploration with filtering and clustering
-      - Multiple output formats (PNG, SVG, HTML)
-      - CLI command integration
-      - MCP server tools for AI assistant integration
-    scale_support: "100-10K+ documents with performance optimization"
-
-  architectural_approach:
-    strategy: "Extension-based enhancement preserving existing infrastructure"
-    principles:
-      - Leverage existing KnowledgeGraphManager without modification
-      - Follow established naming conventions (_private files, public classes)
-      - Maintain test-driven development with >90% coverage
-      - Ensure backward compatibility
-      - Support both library and MCP usage modes
-```
-
-## Current Infrastructure Analysis
-
-### Graph Foundation Assessment
-
-``` yaml
-existing_capabilities:
-  knowledge_graph_manager:
-    location: "src/semantic_graph/graph/_KnowledgeGraphManager.py"
-    features:
-      - NetworkX MultiDiGraph for directed relationships
-      - Node types: document, chunk, entity
-      - Comprehensive metadata tracking
-      - Cross-reference pattern extraction
-      - Graph persistence and loading
-      - Multiple search strategies (semantic, keyword, hybrid, graph)
-      - Centrality-based ranking
-      - Graph statistics and metrics
-
-  data_structures:
-    GraphNodeContainer:
-      fields: [node_id, node_type, title, file_path, content, metadata]
-      methods: [to_dict()]
-
-    GraphEdgeContainer:
-      fields: [source_id, target_id, relationship_type, weight, metadata]
-      methods: [to_dict()]
-
-  reference_patterns:
-    file_reference: "File path mentions"
-    section_reference: "Chapter/section numbers"
-    function_reference: "Function calls and mentions"
-    class_reference: "Class definitions and usage"
-    variable_reference: "Variable references"
-
-  strengths:
-    - Rich metadata for visualization
-    - Multiple relationship types
-    - File path tracking for document grouping
-    - Entity and relationship indices
-    - Graph traversal capabilities
-
-  opportunities:
-    - No visualization methods currently
-    - Graph statistics could feed visualization
-    - Relationship patterns perfect for edge styling
-    - Node metadata ideal for clustering
-```
-
-## Visualization Architecture Design
-
-### Core Components Structure
-
-``` text
-src/semantic_graph/
-├── visualization/                    # NEW: Graph visualization module
-│   ├── __init__.py
-│   │   └── from ._GraphVisualizer import GraphVisualizer
-│   │
-│   ├── _GraphVisualizer.py         # Main visualization orchestrator
-│   │   └── class GraphVisualizer:
-│   │       ├── __init__(self, graph_manager: KnowledgeGraphManager) -> None
-│   │       ├── visualize_document_graph(self, output_path: str, **kwargs) -> str
-│   │       ├── visualize_entity_graph(self, output_path: str, **kwargs) -> str
-│   │       ├── visualize_relationship_network(self, output_path: str, **kwargs) -> str
-│   │       ├── generate_interactive_html(self, output_path: str, **kwargs) -> str
-│   │       ├── export_to_format(self, format: str, output_path: str) -> str
-│   │       └── get_visualization_metrics(self) -> Dict[str, Any]
-│   │
-│   ├── _LayoutEngine.py             # Graph layout algorithms
-│   │   └── class LayoutEngine:
-│   │       ├── __init__(self, algorithm: str = "force_directed") -> None
-│   │       ├── compute_layout(self, graph: nx.Graph, **kwargs) -> Dict[str, Tuple[float, float]]
-│   │       ├── force_directed_layout(self, graph: nx.Graph) -> Dict[str, Tuple[float, float]]
-│   │       ├── hierarchical_layout(self, graph: nx.Graph) -> Dict[str, Tuple[float, float]]
-│   │       ├── circular_layout(self, graph: nx.Graph) -> Dict[str, Tuple[float, float]]
-│   │       └── clustered_layout(self, graph: nx.Graph, clusters: Dict) -> Dict[str, Tuple[float, float]]
-│   │
-│   ├── _NodeRenderer.py             # Node visualization and styling
-│   │   └── class NodeRenderer:
-│   │       ├── __init__(self, style_config: Optional[Dict] = None) -> None
-│   │       ├── render_node(self, node: GraphNodeContainer, position: Tuple[float, float]) -> Any
-│   │       ├── get_node_color(self, node_type: str) -> str
-│   │       ├── get_node_size(self, node: GraphNodeContainer) -> float
-│   │       ├── get_node_shape(self, node_type: str) -> str
-│   │       └── apply_clustering_colors(self, nodes: List, clusters: Dict) -> Dict[str, str]
-│   │
-│   ├── _EdgeRenderer.py             # Edge visualization and styling
-│   │   └── class EdgeRenderer:
-│   │       ├── __init__(self, style_config: Optional[Dict] = None) -> None
-│   │       ├── render_edge(self, edge: GraphEdgeContainer, positions: Dict) -> Any
-│   │       ├── get_edge_color(self, relationship_type: str) -> str
-│   │       ├── get_edge_width(self, weight: float) -> float
-│   │       ├── get_edge_style(self, relationship_type: str) -> str
-│   │       └── calculate_edge_curvature(self, source: str, target: str) -> float
-│   │
-│   ├── _FilterManager.py            # Graph filtering and subgraph extraction
-│   │   └── class FilterManager:
-│   │       ├── __init__(self) -> None
-│   │       ├── filter_by_node_type(self, graph: nx.Graph, node_types: List[str]) -> nx.Graph
-│   │       ├── filter_by_relationship_type(self, graph: nx.Graph, rel_types: List[str]) -> nx.Graph
-│   │       ├── filter_by_centrality(self, graph: nx.Graph, threshold: float) -> nx.Graph
-│   │       ├── extract_subgraph(self, graph: nx.Graph, center_nodes: List[str], depth: int) -> nx.Graph
-│   │       └── filter_by_metadata(self, graph: nx.Graph, conditions: Dict) -> nx.Graph
-│   │
-│   ├── _ClusteringEngine.py         # Graph clustering algorithms
-│   │   └── class ClusteringEngine:
-│   │       ├── __init__(self) -> None
-│   │       ├── detect_communities(self, graph: nx.Graph) -> Dict[str, int]
-│   │       ├── cluster_by_file_path(self, graph: nx.Graph) -> Dict[str, int]
-│   │       ├── cluster_by_similarity(self, graph: nx.Graph, threshold: float) -> Dict[str, int]
-│   │       ├── hierarchical_clustering(self, graph: nx.Graph) -> Dict[str, int]
-│   │       └── get_cluster_statistics(self, clusters: Dict) -> Dict[str, Any]
-│   │
-│   ├── _InteractiveExporter.py      # Interactive HTML/JS visualization
-│   │   └── class InteractiveExporter:
-│   │       ├── __init__(self, template_path: Optional[str] = None) -> None
-│   │       ├── export_to_html(self, graph_data: Dict, output_path: str) -> str
-│   │       ├── generate_d3_json(self, graph: nx.Graph) -> str
-│   │       ├── generate_vis_js_data(self, graph: nx.Graph) -> Dict
-│   │       ├── embed_interactivity(self, html_content: str, interactions: Dict) -> str
-│   │       └── add_search_interface(self, html_content: str) -> str
-│   │
-│   ├── _StaticExporter.py           # Static image export (PNG, SVG, PDF)
-│   │   └── class StaticExporter:
-│   │       ├── __init__(self) -> None
-│   │       ├── export_to_png(self, figure: Any, output_path: str, dpi: int = 300) -> str
-│   │       ├── export_to_svg(self, figure: Any, output_path: str) -> str
-│   │       ├── export_to_pdf(self, figure: Any, output_path: str) -> str
-│   │       ├── create_matplotlib_figure(self, graph: nx.Graph, layout: Dict) -> Any
-│   │       └── optimize_for_print(self, figure: Any) -> Any
-│   │
-│   └── types/                       # Visualization-specific types
-│       ├── __init__.py
-│       ├── _VisualizationConfig.py
-│       │   └── @dataclass class VisualizationConfig:
-│       │       ├── output_format: str = "html"
-│       │       ├── width: int = 1200
-│       │       ├── height: int = 800
-│       │       ├── layout_algorithm: str = "force_directed"
-│       │       ├── show_labels: bool = True
-│       │       ├── node_size_metric: str = "centrality"
-│       │       ├── edge_width_metric: str = "weight"
-│       │       ├── color_scheme: str = "default"
-│       │       └── interactive: bool = True
-│       │
-│       └── _VisualizationMetrics.py
-│           └── @dataclass class VisualizationMetrics:
-│               ├── node_count: int
-│               ├── edge_count: int
-│               ├── clusters_detected: int
-│               ├── max_degree: int
-│               ├── avg_degree: float
-│               ├── density: float
-│               ├── connected_components: int
-│               └── rendering_time: float
-```
-
-### CLI Integration
-
-``` text
-src/semantic_graph/cli/
-├── visualize_graph.py               # NEW: CLI command for graph visualization
-│   ├── create_parser() -> ArgumentParser
-│   │   ├── --input-path: "Path to indexed documents or graph file"
-│   │   ├── --output-path: "Output path for visualization"
-│   │   ├── --format: choices=["html", "png", "svg", "pdf"]
-│   │   ├── --layout: choices=["force", "hierarchical", "circular", "clustered"]
-│   │   ├── --filter-node-types: "Node types to include"
-│   │   ├── --filter-relationships: "Relationship types to include"
-│   │   ├── --max-nodes: "Maximum nodes to display"
-│   │   ├── --clustering: "Enable clustering analysis"
-│   │   ├── --interactive: "Generate interactive visualization"
-│   │   └── --style-config: "Path to style configuration file"
-│   │
-│   └── main(args: Optional[List[str]] = None) -> int
-│       ├── Load or build knowledge graph
-│       ├── Apply filters and clustering
-│       ├── Generate visualization
-│       └── Export to specified format
-```
-
-### MCP Server Tools Integration
-
-``` python
-# Extension to _SemanticSearchMcpServer.py
-
-@self.server.tool(
-    name="visualize_knowledge_graph",
-    description="Generate visualization of the knowledge graph"
-)
-async def visualize_knowledge_graph(
-    output_format: str = "html",
-    layout: str = "force_directed", 
-    max_nodes: Optional[int] = None,
-    filter_node_types: Optional[List[str]] = None,
-    filter_relationships: Optional[List[str]] = None,
-    clustering: bool = False
-) -> Dict[str, Any]:
-    """Generate and return knowledge graph visualization."""
-
-@self.server.tool(
-    name="get_graph_metrics",
-    description="Get comprehensive graph metrics and statistics"
-)
-async def get_graph_metrics() -> Dict[str, Any]:
-    """Return graph statistics for visualization planning."""
-
-@self.server.tool(
-    name="explore_document_connections",
-    description="Explore connections between specific documents"
-)
-async def explore_document_connections(
-    document_paths: List[str],
-    max_depth: int = 2,
-    include_entities: bool = True
-) -> Dict[str, Any]:
-    """Explore and visualize connections between documents."""
-```
-
-## API Design and Integration Points
-
-### Public API Interface
-
-``` yaml
-graph_visualizer_api:
-  initialization:
-    - GraphVisualizer(graph_manager: KnowledgeGraphManager)
-    - GraphVisualizer.from_documents(documents: List[ChunkContainer])
-    - GraphVisualizer.from_pickle(pickle_path: str)
-
-  core_methods:
-    visualize:
-      signature: "visualize(config: VisualizationConfig) -> str"
-      returns: "Path to generated visualization"
-
-    visualize_subset:
-      signature: "visualize_subset(node_ids: List[str], config: VisualizationConfig) -> str"
-      returns: "Path to visualization of subgraph"
-
-    generate_interactive:
-      signature: "generate_interactive(output_path: str, **options) -> str"
-      returns: "Path to interactive HTML visualization"
-
-    export:
-      signature: "export(format: str, output_path: str, **options) -> str"
-      returns: "Path to exported visualization"
-
-  analysis_methods:
-    analyze_clusters:
-      signature: "analyze_clusters() -> Dict[str, List[str]]"
-      returns: "Cluster assignments for all nodes"
-
-    find_central_documents:
-      signature: "find_central_documents(top_k: int = 10) -> List[str]"
-      returns: "Most central documents by various metrics"
-
-    detect_communities:
-      signature: "detect_communities() -> Dict[str, int]"
-      returns: "Community detection results"
-
-  filtering_methods:
-    filter_by_importance:
-      signature: "filter_by_importance(threshold: float) -> GraphVisualizer"
-      returns: "New visualizer with filtered graph"
-
-    focus_on_documents:
-      signature: "focus_on_documents(paths: List[str], depth: int = 2) -> GraphVisualizer"
-      returns: "Visualizer focused on specific documents"
-```
-
-### Integration with Existing Components
-
-``` yaml
-integration_points:
-  knowledge_graph_manager:
-    access_pattern: "Composition via dependency injection"
-    methods_used:
-      - graph (NetworkX graph access)
-      - node_index (Node metadata)
-      - entity_index (Entity information)
-      - relationship_index (Relationship details)
-      - get_graph_statistics() (Metrics)
-
-  search_engine:
-    enhancement: "Visualize search results as subgraph"
-    new_method: "SearchEngine.visualize_results(results: List[SearchResultContainer])"
-
-  cli_module:
-    registration: "Add visualize_graph to CLI command discovery"
-    integration: "GlobalArgumentParser auto-discovers new command"
-
-  mcp_server:
-    tool_addition: "Register visualization tools in _setup_tools()"
-    resource_addition: "Add graph visualization as MCP resource"
-
-  chunkers:
-    metadata_usage: "Use chunk metadata for node styling"
-    type_awareness: "Different visualization for different chunk types"
-```
-
-## Implementation Phases
-
-### Phase 1: Core Visualization Foundation (Week 1)
-
-``` yaml
-phase_1_foundation:
-  objectives:
-    - Establish visualization module structure
-    - Implement basic graph rendering
-    - Create static export capabilities
-
-  deliverables:
-    files_to_create:
-      - src/semantic_graph/visualization/__init__.py
-      - src/semantic_graph/visualization/_GraphVisualizer.py
-      - src/semantic_graph/visualization/_LayoutEngine.py
-      - src/semantic_graph/visualization/_StaticExporter.py
-      - tests/semantic_graph/visualization/test_GraphVisualizer.py
-      - tests/semantic_graph/visualization/test_LayoutEngine.py
-
-    features:
-      - Basic force-directed layout
-      - PNG/SVG export
-      - Node type coloring
-      - Edge weight visualization
-
-  success_criteria:
-    - Render simple graphs with 100-1000 nodes
-    - Export to PNG with matplotlib
-    - All tests passing
-    - Coverage > 90%
-```
-
-### Phase 2: Advanced Layout and Filtering (Week 2)
-
-``` yaml
-phase_2_advanced:
-  objectives:
-    - Implement multiple layout algorithms
-    - Add filtering capabilities
-    - Implement clustering
-
-  deliverables:
-    files_to_create:
-      - src/semantic_graph/visualization/_NodeRenderer.py
-      - src/semantic_graph/visualization/_EdgeRenderer.py
-      - src/semantic_graph/visualization/_FilterManager.py
-      - src/semantic_graph/visualization/_ClusteringEngine.py
-      - tests/semantic_graph/visualization/test_FilterManager.py
-      - tests/semantic_graph/visualization/test_ClusteringEngine.py
-
-    features:
-      - Hierarchical and circular layouts
-      - Community detection
-      - Centrality-based filtering
-      - File-based clustering
-
-  success_criteria:
-    - Handle graphs with 1000-5000 nodes
-    - Clustering accuracy > 85%
-    - Performance < 5s for typical graphs
-```
-
-### Phase 3: Interactive Visualization (Week 3)
-
-``` yaml
-phase_3_interactive:
-  objectives:
-    - Create interactive HTML visualizations
-    - Implement search and exploration
-    - Add zoom and pan capabilities
-
-  deliverables:
-    files_to_create:
-      - src/semantic_graph/visualization/_InteractiveExporter.py
-      - src/semantic_graph/visualization/templates/graph_template.html
-      - src/semantic_graph/visualization/static/graph_viewer.js
-      - src/semantic_graph/visualization/static/graph_viewer.css
-      - tests/semantic_graph/visualization/test_InteractiveExporter.py
-
-    features:
-      - D3.js or vis.js integration
-      - Interactive node exploration
-      - Dynamic filtering
-      - Search interface
-      - Tooltip information
-
-  success_criteria:
-    - Smooth interaction up to 2000 nodes
-    - Search response < 100ms
-    - Cross-browser compatibility
-```
-
-### Phase 4: CLI and MCP Integration (Week 4)
-
-``` yaml
-phase_4_integration:
-  objectives:
-    - Integrate with CLI commands
-    - Add MCP server tools
-    - Create example scripts
-
-  deliverables:
-    files_to_create:
-      - src/semantic_graph/cli/visualize_graph.py
-      - examples/visualize_knowledge_graph.py
-      - examples/visualize_search_results.py
-      - tests/semantic_graph/cli/test_visualize_graph.py
-      - tests/semantic_graph/mcp_servers/test_visualization_tools.py
-
-    features:
-      - CLI command with full options
-      - MCP tools for AI assistants
-      - Batch visualization scripts
-      - Configuration file support
-
-  success_criteria:
-    - CLI command fully functional
-    - MCP tools tested with Claude
-    - Examples cover common use cases
-```
-
-### Phase 5: Performance and Polish (Week 5)
-
-``` yaml
-phase_5_optimization:
-  objectives:
-    - Optimize for large graphs (10K+ nodes)
-    - Add advanced styling options
-    - Complete documentation
-
-  deliverables:
-    files_to_create:
-      - src/semantic_graph/visualization/types/_VisualizationConfig.py
-      - src/semantic_graph/visualization/types/_VisualizationMetrics.py
-      - docs/visualization_guide.md
-      - docs/api/visualization.md
-      - benchmarks/visualization_performance.py
-
-    features:
-      - Graph simplification for large datasets
-      - Custom style configurations
-      - Performance monitoring
-      - Caching for repeated visualizations
-
-  success_criteria:
-    - Handle 10K+ nodes with sampling
-    - Render time < 10s for large graphs
-    - Documentation complete
-    - All integration tests passing
-```
-
-## Testing Strategy
-
-### Test Coverage Plan
-
-``` yaml
-test_organization:
-  unit_tests:
-    visualization_core:
-      - test_GraphVisualizer.py: Core visualization logic
-      - test_LayoutEngine.py: Layout algorithms
-      - test_NodeRenderer.py: Node rendering
-      - test_EdgeRenderer.py: Edge rendering
-
-    filtering_clustering:
-      - test_FilterManager.py: Filtering operations
-      - test_ClusteringEngine.py: Clustering algorithms
-
-    exporters:
-      - test_StaticExporter.py: Image exports
-      - test_InteractiveExporter.py: HTML generation
-
-  integration_tests:
-    - test_visualization_integration.py: End-to-end workflows
-    - test_cli_visualization.py: CLI command testing
-    - test_mcp_visualization_tools.py: MCP server tools
-
-  performance_tests:
-    - test_visualization_performance.py: Large graph handling
-    - test_layout_performance.py: Algorithm efficiency
-
-  fixtures:
-    - fixtures/sample_graphs.py: Test graph generators
-    - fixtures/visualization_configs.py: Configuration templates
-```
-
-### Quality Assurance
-
-``` yaml
-quality_gates:
-  code_quality:
-    - Ruff linting: No errors
-    - Type checking: mypy strict mode
-    - Docstring coverage: 100%
-    - Naming conventions: Followed
-
-  test_quality:
-    - Unit test coverage: > 90%
-    - Integration test coverage: > 85%
-    - Performance benchmarks: Defined and met
-    - Edge cases: Explicitly tested
-
-  visualization_quality:
-    - Visual regression tests
-    - Cross-browser testing for HTML
-    - Accessibility compliance
-    - Print quality for static exports
-```
-
-## Performance Considerations
-
-### Scalability Strategy
-
-``` yaml
-performance_targets:
-  small_graphs: # < 100 nodes
-    rendering_time: < 0.5s
-    interaction_fps: 60
-    memory_usage: < 50MB
-
-  medium_graphs: # 100-1000 nodes
-    rendering_time: < 2s
-    interaction_fps: 30
-    memory_usage: < 200MB
-
-  large_graphs: # 1000-10000 nodes
-    rendering_time: < 10s
-    interaction_fps: 15
-    memory_usage: < 1GB
-    optimization: "Progressive rendering, node aggregation"
-
-  massive_graphs: # 10000+ nodes
-    approach: "Sampling and summarization"
-    rendering_time: < 30s
-    techniques:
-      - Importance sampling
-      - Hierarchical aggregation
-      - Level-of-detail rendering
-      - Viewport culling
-```
-
-### Optimization Techniques
-
-``` yaml
-optimizations:
-  graph_simplification:
-    - Edge bundling for dense connections
-    - Node aggregation by clusters
-    - Importance-based filtering
-    - Progressive detail loading
-
-  rendering_optimization:
-    - Canvas rendering for large graphs
-    - WebGL for 3D visualization
-    - Virtualization for node lists
-    - Lazy loading of node details
-
-  caching_strategy:
-    - Layout computation caching
-    - Rendered image caching
-    - Cluster analysis caching
-    - Metric calculation caching
-
-  memory_management:
-    - Streaming graph processing
-    - Garbage collection optimization
-    - Memory-mapped file support
-    - Graph compression techniques
-```
-
-## Configuration Management
-
-### Visualization Configuration
-
-``` yaml
-config_structure:
-  visualization_config:
-    location: "config/visualization.yaml"
-    sections:
-      defaults:
-        layout_algorithm: "force_directed"
-        output_format: "html"
-        width: 1200
-        height: 800
-
-      node_styles:
-        document:
-          color: "#4CAF50"
-          shape: "circle"
-          size: "centrality"
-
-        chunk:
-          color: "#2196F3"
-          shape: "square"
-          size: "fixed"
-
-        entity:
-          color: "#FF9800"
-          shape: "diamond"
-          size: "degree"
-
-      edge_styles:
-        references:
-          color: "#666666"
-          style: "solid"
-          width: "weight"
-
-        contains:
-          color: "#999999"
-          style: "dashed"
-          width: "fixed"
-
-      performance:
-        max_nodes_interactive: 2000
-        max_nodes_static: 10000
-        simplification_threshold: 5000
-        cache_enabled: true
-        cache_ttl: 3600
-```
-
-## Example Usage Patterns
-
-### Library Usage
-
-``` python
-# Example 1: Basic visualization
-from semantic_graph.graph import KnowledgeGraphManager
-from semantic_graph.visualization import GraphVisualizer
-
-# Load existing graph
-kg_manager = KnowledgeGraphManager(persist_path="./knowledge_graph.pkl")
-kg_manager.load_graph()
-
-# Create visualizer
-visualizer = GraphVisualizer(kg_manager)
-
-# Generate visualization
-output_path = visualizer.visualize_document_graph(
-    output_path="./graph_output.html",
-    layout="force_directed",
-    max_nodes=500,
-    clustering=True
-)
-
-# Example 2: Filtered visualization
-filtered_viz = visualizer.filter_by_importance(threshold=0.7)
-filtered_viz.focus_on_documents(
-    paths=["main.py", "config.yaml"],
-    depth=2
-).generate_interactive("focused_graph.html")
-
-# Example 3: Search result visualization
-from semantic_graph.search import SearchEngine
-
-search_engine = SearchEngine()
-results = search_engine.search("machine learning")
-
-# Visualize search results as subgraph
-search_viz = GraphVisualizer.from_search_results(results)
-search_viz.export("svg", "search_results.svg")
-```
-
-### CLI Usage
-
-``` bash
-# Basic visualization
-semantic-graph visualize-graph \
-    --input-path ./indexed_docs \
-    --output-path ./visualizations/graph.html \
-    --format html \
-    --layout force \
-    --clustering
-
-# Filtered visualization with custom styling
-semantic-graph visualize-graph \
-    --input-path ./knowledge_graph.pkl \
-    --output-path ./viz/filtered.png \
-    --format png \
-    --filter-node-types document entity \
-    --max-nodes 1000 \
-    --style-config ./config/custom_style.yaml
-
-# Export multiple formats
-semantic-graph visualize-graph \
-    --input-path ./indexed_docs \
-    --output-path ./exports/graph \
-    --format html png svg \
-    --interactive \
-    --clustering
-```
-
-### MCP Server Usage
-
-``` python
-# AI Assistant Integration Example
-{
-    "tool": "visualize_knowledge_graph",
-    "parameters": {
-        "output_format": "html",
-        "layout": "hierarchical",
-        "max_nodes": 500,
-        "filter_node_types": ["document", "entity"],
-        "clustering": true
-    }
-}
-
-# Response
-{
-    "success": true,
-    "visualization_path": "/tmp/graph_20250831_073000.html",
-    "metrics": {
-        "nodes_rendered": 487,
-        "edges_rendered": 1243,
-        "clusters_detected": 12,
-        "rendering_time": 2.3
-    },
-    "preview_url": "http://localhost:8080/preview/graph_20250831_073000.html"
-}
-```
-
-## Acceptance Criteria
-
-\### Feature Acceptance Criteria
-
-``` yaml
-acceptance_criteria:
-  core_functionality:
-    - Visualize existing KnowledgeGraphManager graphs
-    - Support document, chunk, and entity nodes
-    - Display all relationship types
-    - Export to PNG, SVG, PDF, HTML
-
-  interactivity:
-    - Zoom and pan in HTML visualizations
-    - Click nodes for details
-    - Search and filter dynamically
-    - Highlight connections on hover
-
-  performance:
-    - Handle 100 documents in < 1s
-    - Handle 1000 documents in < 5s
-    - Handle 10000 documents with sampling
-    - Smooth interaction up to 2000 nodes
-
-  integration:
-    - CLI command fully functional
-    - MCP tools accessible to AI assistants
-    - Python API intuitive and documented
-    - Backward compatible with existing code
-
-  quality:
-    - Test coverage > 90%
-    - All linting checks pass
-    - Type checking complete
-    - Documentation comprehensive
-```
-
-## Risk Assessment and Mitigation
-
-``` yaml
-identified_risks:
-  technical_risks:
-    dependency_management:
-      risk: "Matplotlib/D3.js version conflicts"
-      mitigation: "Pin versions, provide fallbacks"
-
-    performance_degradation:
-      risk: "Large graphs cause browser crashes"
-      mitigation: "Implement progressive rendering, node limits"
-
-    cross_platform_issues:
-      risk: "Visualization differences across OS"
-      mitigation: "Extensive testing, use web standards"
-
-  implementation_risks:
-    scope_creep:
-      risk: "Feature requests beyond initial scope"
-      mitigation: "Strict phase boundaries, defer to v07"
-
-    integration_complexity:
-      risk: "Difficult integration with existing code"
-      mitigation: "Composition pattern, minimal coupling"
-
-    testing_complexity:
-      risk: "Visual testing is subjective"
-      mitigation: "Automated metrics, regression tests"
-```
-
-## Migration Path from v05
-
-``` yaml
-migration_notes:
-  from_v05_to_v06:
-    preserved:
-      - All existing graph infrastructure
-      - Current test success rate (99.1%)
-      - API compatibility
-      - MCP server structure
-
-    additions:
-      - New visualization module
-      - CLI visualize-graph command
-      - MCP visualization tools
-      - Interactive HTML exports
-
-    no_breaking_changes:
-      - Existing code continues to work
-      - New features are additive only
-      - Optional dependencies for visualization
-
-    testing_impact:
-      - New test files for visualization
-      - No changes to existing tests
-      - Separate test suite for visualization
-```
-
-## Communication and Coordination
-
-``` yaml
-agent_coordination:
-  ArchitectAgent:
-    responsibilities:
-      - Architecture definition and agreement
-      - Phase planning and acceptance criteria
-      - Integration point specification
-
-  SourceDeveloperAgent:
-    responsibilities:
-      - Implement visualization module
-      - Create GraphVisualizer and supporting classes
-      - Ensure code quality and conventions
-
-  TestDeveloperAgent:
-    responsibilities:
-      - Create comprehensive test suite
-      - Visual regression testing
-      - Performance benchmarks
-
-  IntegrationAgent:
-    responsibilities:
-      - CLI command integration
-      - MCP server tool addition
-      - Example script creation
-
-  bulletin_board_updates:
-    - Phase completion announcements
-    - Blocking issues identification
-    - Integration readiness signals
-    - Performance metrics sharing
-```
-
-## Conclusion
-
-Architecture v06 introduces powerful graph visualization capabilities to the semantic search engine through a well-structured, extensible module that leverages the existing comprehensive KnowledgeGraphManager infrastructure. The design follows established patterns, maintains backward compatibility, and provides multiple integration points for CLI, MCP server, and library usage.
-
-The phased implementation approach ensures systematic development with clear milestones, comprehensive testing, and performance optimization for graphs ranging from 100 to 10,000+ documents. The architecture emphasizes both static and interactive visualizations, supporting research-style document connectivity exploration similar to Connected Papers.
-
-This enhancement will significantly improve the user\'s ability to understand document relationships, explore knowledge structures, and gain insights from their semantic search corpus through intuitive visual representations.
-
-## Next Steps
-
-1.  ****Architecture Review and Agreement****: Obtain user approval for v06 architecture
-2.  ****Environment Setup****: Install visualization dependencies (matplotlib, plotly/d3.js)
-3.  ****Phase 1 Implementation****: Begin with core GraphVisualizer and basic layouts
-4.  ****Incremental Development****: Follow 5-week phase plan with regular testing
-5.  ****Integration Testing****: Ensure seamless CLI and MCP server integration
-6.  ****Documentation****: Create comprehensive user and developer documentation
-7.  ****Performance Optimization****: Implement caching and simplification for large graphs
-
-The architecture is designed to be implemented incrementally while maintaining the stability of the existing codebase and its 99.1% test success rate.