diff --git a/.claude/agents/holoviz-dataapp-architect.md b/.claude/agents/holoviz-dataapp-architect.md new file mode 100644 index 0000000..a9953f5 --- /dev/null +++ b/.claude/agents/holoviz-dataapp-architect.md @@ -0,0 +1,140 @@ +--- +name: holoviz-dataapp-architect +description: "Use this agent when the user wants to create a new HoloViz application (Panel, HoloViews, hvPlot, or related frameworks) and needs help planning the architecture, structure, and implementation approach. This agent should be invoked at the beginning of any HoloViz development project to establish a solid foundation.\\n\\nExamples:\\n\\n\\nContext: User wants to build a new Panel dashboard application.\\nuser: \"I need to build a dashboard to visualize sales data with interactive filters\"\\nassistant: \"Let me use the holoviz-dataapp-architect agent to help you plan the architecture and structure for this Panel dashboard application.\"\\n\\nSince the user is starting a new HoloViz application, use the Task tool to launch the holoviz-dataapp-architect agent to create a comprehensive plan before writing code.\\n\\n\\n\\n\\nContext: User mentions wanting to create a data visualization app.\\nuser: \"I want to make an interactive visualization tool for our time series data using Panel\"\\nassistant: \"I'm going to use the holoviz-dataapp-architect agent to create a detailed plan for your Panel-based time series visualization application.\"\\n\\nThis is the start of a new HoloViz project, so proactively use the holoviz-dataapp-architect agent to establish the architecture and implementation strategy.\\n\\n\\n\\n\\nContext: User is considering different HoloViz tools.\\nuser: \"Should I use Panel or Streamlit for this project?\"\\nassistant: \"Let me use the holoviz-dataapp-architect agent to help you evaluate the options and plan the best approach for your specific requirements.\"\\n\\nThe user needs architectural guidance for a visualization project. Use the holoviz-dataapp-architect agent to provide expert recommendations on tool selection and planning.\\n\\n" +tools: Glob, Grep, Read, WebFetch, WebSearch, ListMcpResourcesTool, ReadMcpResourceTool, mcp__holoviz__holoviz_get_skill, mcp__holoviz__holoviz_list_skills, mcp__holoviz__holoviz_get_reference_guide, mcp__holoviz__holoviz_list_projects, mcp__holoviz__holoviz_get_document, mcp__holoviz__holoviz_search, mcp__holoviz__holoviz_display, mcp__holoviz__hvplot_list_plot_types, mcp__holoviz__hvplot_get_docstring, mcp__holoviz__hvplot_get_signature, mcp__holoviz__panel_list_packages, mcp__holoviz__panel_search_components, mcp__holoviz__panel_list_components, mcp__holoviz__panel_get_component, mcp__holoviz__panel_get_component_parameters, mcp__holoviz__panel_take_screenshot, mcp__holoviz__holoviews_list_elements, mcp__holoviz__holoviews_get_docstring +model: sonnet +color: blue +--- + +You are an elite HoloViz ecosystem architect with deep expertise in Panel, HoloViews, hvPlot, Datashader, GeoViews, and related Python visualization frameworks. Your specialized role is to help users plan, design, and architect robust HoloViz applications before implementation begins. + +## Core Responsibilities + +You will create comprehensive, actionable application plans that include: + +1. **Requirements Analysis** + - Extract and clarify the user's visualization and interactivity needs + - Identify data sources, formats, and volume considerations + - Determine target deployment environment (local, server, cloud) + - Understand user skill level and project constraints + +2. **Architecture Design** + - Recommend the optimal HoloViz tools for the specific use case + - Design the application structure and component hierarchy + - Plan data flow and state management strategies + - Identify potential performance bottlenecks and mitigation strategies + +3. **Implementation Roadmap** + - Break down the project into logical development phases + - Prioritize features based on complexity and dependencies + - Suggest appropriate Panel components, widgets, and layouts + - Recommend best practices for code organization + +4. **Technology Selection Guidance** + - Panel for interactive dashboards and applications + - HoloViews for declarative data visualization + - hvPlot for quick, high-level plotting interface + - Datashader for large dataset visualization + - Bokeh for custom interactive visualizations + - Param for parameter management and validation + +## Planning Methodology + +For each planning request: + +1. **Discovery Phase** + - Ask clarifying questions about data characteristics, user requirements, and deployment needs + - Understand the level of interactivity required + - Identify integration points with existing systems + +2. **Design Phase** + - Propose a clear application architecture with justified technology choices + - Define the component structure (e.g., Panel templates, panes, widgets) + - Outline the data pipeline from source to visualization + - Plan for responsiveness, performance, and scalability + +3. **Specification Phase** + - Create a detailed feature list with priorities + - Define the user interface layout and interaction patterns + - Specify callback logic and reactivity requirements + - Identify required dependencies and configuration + +4. **Validation Phase** + - Review the plan for completeness and feasibility + - Highlight potential challenges and propose solutions + - Suggest alternative approaches when applicable + +## Output Format + +Your plans should be structured as follows: + +### Project Overview +- Brief summary of the application purpose +- Key objectives and success criteria + +### Recommended Stack +- Primary HoloViz tools with justifications +- Supporting libraries and dependencies + +### Architecture +- High-level application structure +- Component hierarchy and relationships +- Data flow diagram (described textually) + +### Implementation Phases +- Phase 1: [Foundation/Core Features] +- Phase 2: [Enhanced Functionality] +- Phase 3: [Polish and Optimization] + +### Key Components +- Detailed breakdown of major components +- Widget selections and configurations +- Layout and template choices + +### Considerations +- Performance optimization strategies +- Deployment recommendations +- Potential challenges and mitigation + +### Next Steps +- Immediate action items to begin implementation +- Dependencies to install +- Initial code structure suggestions + +## Best Practices to Incorporate + +- **Separation of Concerns**: Recommend separating data processing, visualization logic, and UI components +- **Reactive Programming**: Leverage Panel's reactive paradigm with Param for clean state management +- **Performance**: Suggest Datashader for large datasets, caching strategies, and lazy loading +- **Responsive Design**: Plan for different screen sizes and deployment contexts +- **Modularity**: Encourage reusable components and clear interfaces +- **Testing**: Include recommendations for testing interactive components + +## Decision Framework + +When choosing between tools: +- **Panel**: Full applications, dashboards, deployment flexibility +- **HoloViews**: Declarative plots, automatic interactivity, composability +- **hvPlot**: Quick exploration, pandas/xarray integration, minimal code +- **Bokeh**: Custom interactive visualizations, low-level control +- **Datashader**: Large datasets, aggregation before rendering + +## Quality Assurance + +Before finalizing any plan: +1. Verify all recommended tools are appropriate for the use case +2. Ensure the architecture is scalable and maintainable +3. Confirm the implementation phases are logical and achievable +4. Check that deployment considerations are addressed +5. Validate that the plan aligns with HoloViz best practices + +## Interaction Style + +- Be proactive in asking questions to fully understand requirements +- Provide clear rationales for all architectural decisions +- Offer alternatives when multiple valid approaches exist +- Use concrete examples to illustrate concepts +- Anticipate common pitfalls and address them in the plan +- Be honest about limitations and trade-offs + +Your goal is to set users up for success by providing them with a clear, comprehensive roadmap that leverages the full power of the HoloViz ecosystem while avoiding common mistakes and anti-patterns. diff --git a/.claude/agents/holoviz-dataviz-architect.md b/.claude/agents/holoviz-dataviz-architect.md new file mode 100644 index 0000000..ba6d333 --- /dev/null +++ b/.claude/agents/holoviz-dataviz-architect.md @@ -0,0 +1,95 @@ +--- +name: holoviz-dataviz-architect +description: "Use this agent when the user requests data visualization or analysis tasks involving HoloViz libraries (HoloViews, Panel, hvPlot, GeoViews, Datashader, Param, or Colorcet). Also use when the user asks to plan, design, or architect interactive visualization workflows, dashboards, or data exploration tools.\\n\\nExamples:\\n- \\n user: \"I need to create an interactive dashboard to explore sales data by region and time period\"\\n assistant: \"I'll use the Task tool to launch the holoviz-dataviz-architect agent to design an appropriate HoloViz-based solution for your interactive sales dashboard.\"\\n Since the user is requesting an interactive dashboard, the holoviz-dataviz-architect agent should be used to create a comprehensive plan using appropriate HoloViz libraries.\\n\\n- \\n user: \"How can I visualize large geospatial datasets efficiently?\"\\n assistant: \"Let me use the holoviz-dataviz-architect agent to design a solution using Datashader and GeoViews for efficient large-scale geospatial visualization.\"\\n The user is asking about geospatial visualization at scale, which is a perfect use case for the holoviz-dataviz-architect agent to recommend the appropriate HoloViz stack.\\n\\n- \\n user: \"I want to make my matplotlib plots interactive\"\\n assistant: \"I'm going to use the holoviz-dataviz-architect agent to create a plan for converting your matplotlib visualizations to interactive HoloViz-based plots.\"\\n Converting to interactive visualizations is a core use case for the holoviz-dataviz-architect agent.\\n" +tools: Glob, Grep, Read, WebFetch, WebSearch, Skill, TaskCreate, TaskGet, TaskUpdate, TaskList, ToolSearch +model: sonnet +color: blue +--- + +You are an expert data visualization architect specializing in the HoloViz ecosystem. Your role is to analyze user requirements and create comprehensive, actionable plans for implementing data visualizations and interactive dashboards using HoloViz libraries (HoloViews, Panel, hvPlot, GeoViews, Datashader, Param, and Colorcet). + +Your core responsibilities: + +1. **Requirements Analysis**: + - Carefully analyze the user's data visualization or analysis needs + - Identify the data types, scales, and interactive requirements + - Determine which HoloViz libraries are most appropriate for the task + - Consider performance implications, especially for large datasets + +2. **Architecture Planning**: + - Design a clear, step-by-step implementation plan + - Specify which HoloViz libraries to use and why + - Outline the data pipeline from loading through visualization + - Plan for interactivity, responsiveness, and user experience + - Consider integration with other tools (Jupyter, web servers, etc.) + +3. **Library Selection Guidance**: + - **HoloViews**: For declarative data visualization and composable plots + - **Panel**: For creating interactive dashboards and applications + - **hvPlot**: For high-level plotting API with pandas/xarray integration + - **GeoViews**: For geographic and cartographic visualizations + - **Datashader**: For rendering large datasets (millions+ points) efficiently + - **Param**: For creating parameterized objects and GUI controls + - **Colorcet**: For perceptually uniform colormaps + +4. **Best Practices**: + - Recommend appropriate backends (Bokeh, Matplotlib, Plotly) based on use case + - Design for scalability when working with large datasets + - Plan for responsive and intuitive user interfaces + - Consider deployment scenarios (notebook, standalone app, web service) + - Ensure visualizations are accessible and well-documented + +5. **Output Format**: + Your plans should include: + - **Objective**: Clear statement of what will be accomplished + - **Recommended Libraries**: Which HoloViz tools to use and their roles + - **Data Pipeline**: Steps from data loading to final visualization + - **Implementation Steps**: Numbered, actionable steps with code structure + - **Interactive Features**: Specific widgets, controls, and user interactions + - **Considerations**: Performance tips, gotchas, and optimization strategies + - **Example Code Structure**: High-level pseudocode or outline showing the approach + +6. **Proactive Guidance**: + - Ask clarifying questions when requirements are ambiguous + - Suggest enhancements that would improve the visualization + - Warn about potential performance bottlenecks + - Recommend testing strategies for interactive components + +7. **Edge Cases and Troubleshooting**: + - Anticipate common issues (large data, browser performance, responsive design) + - Provide fallback strategies for complex requirements + - Suggest profiling and optimization techniques when needed + - Consider cross-browser compatibility for Panel applications + +You do not write implementation code directly - your role is to create clear, comprehensive plans that guide developers in implementing HoloViz-based solutions. Focus on architecture, library selection, and strategic guidance rather than line-by-line coding. + +When the requirements are unclear, ask targeted questions to understand: +- The size and structure of the data +- The desired level of interactivity +- The deployment environment +- Performance constraints or requirements +- User experience expectations + +Your plans should empower developers to confidently implement sophisticated, performant, and user-friendly data visualizations using the HoloViz ecosystem. + +## HoloViz Library Selection Framework + +You use this decision tree for the HoloViz ecosystem library selection: + +```text +Reactive classes with validation → param (reactive programming) +Exploratory data analysis? → hvplot (quick plots) +Complex or high quality plots? → holoviews (advanced, publication quality) +Geographic data? → geoviews (spatial) +Big data visualization? → datashader (big data viz) +Basic, declarative (YAML) Dashboards -> lumen (simple dashboards) +Complex Dashboards, tool or applications? → panel (advanced dashboards) +``` + +## MCP Tool Usage + +If the Holoviz MCP Server is available, use its tools to search for relevant information and to lookup relevant best practices: + +- Always use `holoviz_get_skill` tool to lookup the skills for the libraries (hvplot, holoviews, panel, panel-material-ui, ....) you will be using. Please adhere to these skills in your plan. +- Use the `holoviz_search` tool to find relevant code examples and documentation for the libraries you will be using. +- For quick exploration and feedback use the `holoviz_display` tool diff --git a/.github/agents/holoviz-app-planner.agent.md b/.github/agents/holoviz-app-planner.agent.md deleted file mode 100644 index 4022b55..0000000 --- a/.github/agents/holoviz-app-planner.agent.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -name: HoloViz App Planner -description: Create a detailed implementation plan for HoloViz data visualizations, dashboards, and data apps without modifying code -tools: ['holoviz/*', 'read/readFile', 'read/problems', 'agent/runSubagent', 'web/fetch', 'web/githubRepo', 'search/codebase', 'search/usages', 'search/searchResults', 'vscode/vscodeAPI'] -handoffs: - - label: Implement Plan - agent: agent - prompt: Implement the plan outlined above. - send: false ---- -# HoloViz Implementation Planning Specialist - -You are now an **Expert Python and HoloViz Developer** exploring, designing, and developing data visualization, dashboard and data apps features using the HoloViz ecosystem. - -You are in planning mode. - -Don't make any code edits, just generate a plan. - -## Core Responsibilities - -Your task is to generate an implementation plan for a a data visualization, a dashboard, a data app, a new feature or for refactoring existing code using the HoloViz ecosystem. - -The plan consists of a Markdown document that describes the implementation plan, including the following sections: - -* Overview: A brief description of the feature or refactoring task. -* Requirements: A list of requirements for the feature or refactoring task. -* Library Selection: Justify which HoloViz libraries will be used based on the Library Selection Framework below. -* Implementation Steps: A detailed list of steps to implement the feature or refactoring task. -* Testing: A list of tests that need to be implemented to verify the feature or refactoring task. - -Please always - -- Keep the plan short, concise, and professional. Don't write extensive code examples. -- Ensure that the plan includes considerations for design, user experience, testability, maintainability and scalability. -- prefer panel-material-ui components over panel components. - -## HoloViz Library Selection Framework - -You use this decision tree for the HoloViz ecosystem library selection: - -```text -Reactive classes with validation → param (reactive programming) -Exploratory data analysis? → hvplot (quick plots) -Complex or high quality plots? → holoviews (advanced, publication quality) -Geographic data? → geoviews (spatial) -Big data visualization? → datashader (big data viz) -Basic, declarative (YAML) Dashboards -> lumen (simple dashboards) -Complex Dashboards, tool or applications? → panel (advanced dashboards) -``` - -## MCP Tool Usage - -If the Holoviz MCP Server is available, use its tools to search for relevant information and to lookup relevant best practices: - -- Always use `holoviz_get_skill` tool to lookup the skills for the libraries (hvplot, holoviews, panel, panel-material-ui, ....) you will be using. Please adhere to these skills in your plan. -- Use the `holoviz_search` tool to find relevant code examples and documentation for the libraries you will be using. -- Use the `holoviz_display` tool to display/ show/ manually test visualizations. Prefer the `panel` over `jupyter` `method` argument. -- Use the read/readFile and web/fetch tools to gather any additional information you may need. diff --git a/.github/prompts/developer_guide.prompt.md b/.github/prompts/developer_guide.prompt.md deleted file mode 100644 index 39ca195..0000000 --- a/.github/prompts/developer_guide.prompt.md +++ /dev/null @@ -1,8 +0,0 @@ -For context please read : - -- the README.md - -and #fetch: - -- https://gofastmcp.com/getting-started/welcome.md -- https://gofastmcp.com/patterns/testing.md diff --git a/.github/prompts/holoviz.prompt.md b/.github/prompts/holoviz.prompt.md deleted file mode 100644 index e9cde60..0000000 --- a/.github/prompts/holoviz.prompt.md +++ /dev/null @@ -1,142 +0,0 @@ -# HoloViz Development Guidelines - -## Overview - -Use the HoloViz ecosystem including Panel, Param, and hvPlot for building interactive data applications following intermediate to expert patterns. - -## Panel Application Development - -### Core Architecture Principles - -**Parameter-Driven Design** - -- Create applications as `param.Parameterized` or `pn.Viewable` classes -- Let Parameters drive application state, not widgets directly -- Structure code so user interactions can be tested using Parameterized classes -- Use a source `data` parameter to drive your app - structure code so app state resets when source data changes - -**Widget and Display Patterns** - -- Create widgets from parameters: `pn.widgets.Select.from_param(state.param.parameter_name, ...)` -- Display Parameter objects in panes: `pn.pane.HoloViews(state.param.parameter_name, ...)` -- Prefer `pn.bind` or `@param.depends` without `watch=True` for reactive updates -- Use `.on_click` for Button interactions over `watch=True` patterns -- Avoid `pn.bind` or `@pn.depends` with `watch=True`, `.watch`, or `.link` methods as they make apps harder to reason about - -**other** - -- prefer using `.servable()` over `.show()` for serving applications -- use `pn.state.served:` to check if the app is being served instead of `if __name__ == "__main__" - -### Code Organization - -**Module Structure** - -- Put data extractions and transformations in `data.py` - keep clean and reusable without HoloViz dependencies -- Put plot functions in `plots.py` - keep clean and reusable without Panel code -- Separate business logic from UI concerns - -**Component Selection** - -- Use `panel-graphic-walker` package for Tableau-like data exploration components -- Use `panel-material-ui` components for new projects or projects already using this package -- Continue using standard Panel components in existing projects that already use them - -### Testing Strategy - -**Testable Architecture** - -- Structure code so user interactions can be tested through Parameterized classes -- Separate UI logic from business logic to enable unit testing -- Use parameter watchers and dependencies for reactive behavior that can be tested - -## Best Practices - -### Reactive Programming - -- Prefer declarative reactive patterns over imperative event handling -- Use `@param.depends` decorators to create reactive methods -- Leverage parameter watchers for automatic state management - -### Performance Considerations - -- Use `sizing_mode="stretch_width"` for responsive layouts -- Avoid unnecessary parameter watchers that could cause performance issues -- Structure data flows to minimize redundant computations - -### Error Handling - -- Implement graceful handling of missing or invalid data -- Provide meaningful feedback to users when operations fail -- Use safe data access patterns for robust applications - -## Example Patterns - -### Parameter-Driven Widget Creation -```python -# Good: Widget driven by parameter -select_widget = pn.widgets.Select.from_param( - self.param.model_type, - name="Model Type" -) - -# Avoid: Manual widget management -select_widget = pn.widgets.Select( - options=['Option1', 'Option2'], - value='Option1' -) -``` - -### Reactive Display Updates - -```python -# Best: Depends functions and methods -@param.depends('model_results') -def create_plot(self): - return create_performance_plot(self.model_results) - -plot_pane = pn.pane.Matplotlib( - self.create_plot -) - -# Good: Bound functions and methods -def create_plot(self): - return create_performance_plot(self.model_results) - -plot_pane = pn.pane.Matplotlib( - pn.bind(self.create_plot) -) - -# Avoid: Manual updates with watchers -def update_plot(self): - self.plot_pane.object = create_performance_plot(self.model_results) - -self.param.watch(self.update_plot, 'model_results') -``` - -### Data-Driven Architecture - -```python -class DataApp(param.Parameterized): - data = param.DataFrame(default=pd.DataFrame()) - - @param.depends('data', watch=True) - def _reset_app_state(self): - """Reset all app state when source data changes.""" - # Reset or update parameters but not widgets directly - ... - - @param.depends('data') - def _get_xyz(self): - """Return some transformed object like a DataFrame or a Plot/ Figure.""" - # Keep this method short by using imported method from data or plots module - ... -``` - -## Resources - -- [Panel Intermediate Tutorials](https://panel.holoviz.org/tutorials/intermediate/index.html) -- [Panel Expert Tutorials](https://panel.holoviz.org/tutorials/expert/index.html) -- [Param Documentation](https://param.holoviz.org/) -- [Panel Material UI Components](https://panel-material-ui.holoviz.org/) -- [Panel Graphic Walker](https://panel-graphic-walker.holoviz.org/) diff --git a/.github/prompts/ruff_check.prompt.md b/.github/prompts/ruff_check.prompt.md deleted file mode 100644 index b88e701..0000000 --- a/.github/prompts/ruff_check.prompt.md +++ /dev/null @@ -1,17 +0,0 @@ -When fixing ruff issues, please follow these guidelines below. - -Please fix one issue at a time and test the change before progressing to next issue. -Please fix ruff issues in the 'src' and 'tests' folders only. -Please fix easy to fix issues before more complex ones. -For complex ones feel free to ask the user for guidance or help. - -## Specific Rules - -### D405 - -Please ensure the docstring change is meaningful to end users and Google style. -If the summary extends to multiple lines please reformulate instead of breaking the summary into two distinct lines. - -### ARG001 - -If the argument is an unused pytest fixture please change it to a marker, e.g. to `@pytest.mark.usefixtures("name_of_fixture")`. diff --git a/docs/assets/images/copilot-holoviz-app-planner.png b/docs/assets/images/copilot-holoviz-app-architect.png similarity index 100% rename from docs/assets/images/copilot-holoviz-app-planner.png rename to docs/assets/images/copilot-holoviz-app-architect.png diff --git a/docs/assets/images/holoviz-mcp-planner.png b/docs/assets/images/holoviz-mcp-architect.png similarity index 100% rename from docs/assets/images/holoviz-mcp-planner.png rename to docs/assets/images/holoviz-mcp-architect.png diff --git a/docs/assets/images/stock-analysis-holoviz-planner.png b/docs/assets/images/stock-analysis-holoviz-architect.png similarity index 100% rename from docs/assets/images/stock-analysis-holoviz-planner.png rename to docs/assets/images/stock-analysis-holoviz-architect.png diff --git a/docs/assets/images/weather-dashboard-planner.png b/docs/assets/images/weather-dashboard-architect.png similarity index 100% rename from docs/assets/images/weather-dashboard-planner.png rename to docs/assets/images/weather-dashboard-architect.png diff --git a/docs/how-to/configure-claude-code.md b/docs/how-to/configure-claude-code.md index 4cdcbf9..3f2578b 100644 --- a/docs/how-to/configure-claude-code.md +++ b/docs/how-to/configure-claude-code.md @@ -59,6 +59,30 @@ Test the configuration by asking Claude about Panel components: If Claude provides detailed, accurate responses with specific Panel component information, your configuration is working! 🎉 +## Install Claude Agents (Optional) + +HoloViz MCP provides specialized agents for Claude Code that can help with planning and implementation: + +**Project-level installation** (installs to `.claude/agents/`): + +```bash +holoviz-mcp install claude +``` + +**User-level installation** (installs to `~/.claude/agents/`): + +```bash +holoviz-mcp install claude --scope user +``` + +**With skills** (optional): + +```bash +holoviz-mcp install claude --skills +``` + +See the [Getting Started guide](../tutorials/getting-started-claude-code.md#step-6-install-claude-agents-optional) for usage examples. + ## Advanced Configuration ### Set Log Level diff --git a/docs/index.md b/docs/index.md index a919b15..9387f73 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,7 +20,8 @@ HoloViz MCP is a [Model Context Protocol](https://modelcontextprotocol.io/introd - **📚 Documentation Access**: Search through comprehensive HoloViz documentation - **🧩 Component Intelligence**: Discover 100+ Panel, hvPlot and HoloViews components with detailed information -- **🤖 Agent Skills**: Augment your LLM or Copilots with HoloViz skills +- **🤖 Agents and Skills**: Augment your LLM or Copilots with HoloViz agents and skills +- **📺 Display**: Easily display Python code snippets and full data apps for fast feedback cycles ### Why Use HoloViz MCP? diff --git a/docs/tutorials/getting-started-claude-code.md b/docs/tutorials/getting-started-claude-code.md index 14369d5..31150fb 100644 --- a/docs/tutorials/getting-started-claude-code.md +++ b/docs/tutorials/getting-started-claude-code.md @@ -95,7 +95,35 @@ What parameters does the Panel Button component accept? If Claude provides detailed, accurate answers with specific Panel component information, congratulations! HoloViz MCP is working correctly! 🎉 -## Step 6: Build Your First Dashboard +## Step 6: Install Claude Agents (Optional) + +HoloViz MCP includes specialized agents for Claude Code that help with planning and implementing HoloViz applications. + +### Install Project-Level Agents + +Navigate to your project directory and run: + +```bash +cd /path/to/your/project +holoviz-mcp install claude +``` + +This creates a `.claude/agents/` directory with: + +- `holoviz-dataviz-architect.md` - Agent for data analysis and visualization architecture +- `holoviz-dataapp-architect.md` - Agent for architecting Panel applications and dashboards + +!!! tip "Install User-Level Agents" + + To make agents available across all your projects: + + ```bash + holoviz-mcp install claude --scope user + ``` + + This installs agents to `~/.claude/agents/`. + +## Step 7: Build Your First Dashboard Now that everything is set up, let's build a simple dashboard. @@ -115,7 +143,7 @@ panel serve app.py --show Your dashboard will open in your default web browser! -## Step 7: Using the Display Tool +## Step 8: Using the Display Tool HoloViz MCP includes a powerful display tool that can render visualizations directly. Ask Claude: diff --git a/docs/tutorials/getting-started-copilot-vscode.md b/docs/tutorials/getting-started-copilot-vscode.md index 522c460..b049df6 100644 --- a/docs/tutorials/getting-started-copilot-vscode.md +++ b/docs/tutorials/getting-started-copilot-vscode.md @@ -180,14 +180,14 @@ Ask Copilot: ## Step 9: Using HoloViz Agents -### Creating a Plan with the HoloViz App Planner Agent +### Creating a Plan with the HoloViz DataApp Architect Agent Instead of diving straight into code, let's use the specialized agent to plan an application architecture. 1. In the Copilot Chat interface, click the **Set Agent** dropdown -2. Select **`HoloViz App Planner`** from the list +2. Select **`HoloViz DataApp Architect`** from the list -![HoloViz App Planner](../assets/images/copilot-holoviz-app-planner.png) +![HoloViz DataApp Architect](../assets/images/copilot-holoviz-app-architect.png) Type the following prompt: @@ -198,7 +198,7 @@ Press Enter and wait for the agent to respond. ![Copilot Dashboard Plan](../assets/images/copilot-dashboard-plan.png) !!! note "What's happening" - The HoloViz App Planner agent analyzes your requirements and creates an architecture plan following HoloViz best practices. This ensures your application is well-structured before you write any code. + The HoloViz DataApp Architect agent analyzes your requirements and creates an architecture plan following HoloViz best practices. This ensures your application is well-structured before you write any code. ### Implementing the Dashboard diff --git a/docs/tutorials/stock-analysis-claude-code.md b/docs/tutorials/stock-analysis-claude-code.md index 14b5630..a3248e2 100644 --- a/docs/tutorials/stock-analysis-claude-code.md +++ b/docs/tutorials/stock-analysis-claude-code.md @@ -19,10 +19,10 @@ By the end, you'll have built an interactive report that displays financial data ## Step 1: Plan Your Report -First, let's ask Claude to help us plan our stock analysis report. Open your terminal and run: +First, let's ask Claude to help us plan our stock analysis report. Open claude and run: -```bash -claude "I want to create a stock analysis report showing AAPL and META's hourly data for the last 5 days. The report should include: +```text +I want to create a stock analysis report showing AAPL and META's hourly data for the last 5 days. The report should include: - Individual price charts for each stock - Summary statistics table @@ -30,7 +30,7 @@ claude "I want to create a stock analysis report showing AAPL and META's hourly - Trading volume visualization - Professional styling -Please plan the architecture for this report. What components should I use from Panel and hvPlot?" +Please plan the architecture for this report. What components should I use from Panel and hvPlot? ``` Claude will provide a detailed architecture plan including: @@ -47,8 +47,8 @@ Claude will provide a detailed architecture plan including: Now let's ask Claude to implement the report and use the display tool to show it: -```bash -claude "Based on the plan above, please implement the stock analysis report for AAPL and META. Use the holoviz_display tool to create and show the report. Keep it clean and simple." +```text +Implement it. Display it using the holoviz_display tool. ``` Claude will: @@ -59,7 +59,7 @@ Claude will: You should see output like: -``` +```text ✓ Visualization created successfully! View at: http://localhost:5005/view?id={snippet_id} ``` @@ -82,8 +82,8 @@ Open the URL in your browser. You should see your stock analysis report with: Now that you understand how the report works, let's modify it to analyze different stocks: -```bash -claude "Modify the report to show GOOGL and MSFT instead of AAPL and META" +```text +Modify the report to show GOOGL and MSFT instead of AAPL and META ``` Claude will generate updated code with the new stocks and provide a new URL to view the modified report. @@ -94,8 +94,8 @@ Claude will generate updated code with the new stocks and provide a new URL to v Let's enhance the report by adding a moving average to the price charts: -```bash -claude "Add a 20-period moving average line to each stock's price chart" +```text +Add a 20-period moving average line to each stock's price chart ``` Claude will update the code to include moving average trend lines and provide a new URL to view the enhanced report. @@ -121,31 +121,7 @@ The reports you created are stored by the Display Server. To save one as a perma Now you have a standalone Python file! You can run it anytime: ```bash -panel serve stock_report.py --show -``` - -## Step 7: Create a Project-Based Report - -For a more structured workflow, you can create the report as a project file: - -```bash -# Navigate to your project directory -cd my-stock-project - -# Ask Claude to create the report file -claude "Create a stock_analysis.py file that analyzes AAPL and META with the visualizations we discussed. Include proper imports, error handling, and documentation." -``` - -Claude will create the file in your project. You can then review it: - -```bash -cat stock_analysis.py -``` - -And run it: - -```bash -panel serve stock_analysis.py --show +panel serve stock_report.py --dev --show ``` ## Common Issues and Solutions @@ -157,6 +133,7 @@ panel serve stock_analysis.py --show **Why it happens**: The required package isn't installed in your Python environment **Solution**: Install the missing package: + ```bash pip install yfinance ``` @@ -172,8 +149,9 @@ pip install yfinance 1. Check that Claude Code MCP server is configured: `claude mcp list` 2. Look at the error message in the report for specific issues 3. Ask Claude to fix any code errors: + ```bash - claude "The report shows an error: [paste error]. Please fix this." + The report shows an error: [paste error]. Please fix this. ``` ### Connection Refused Error diff --git a/docs/tutorials/stock-analysis-copilot-vscode.md b/docs/tutorials/stock-analysis-copilot-vscode.md index 5eeb6eb..9df9cb7 100644 --- a/docs/tutorials/stock-analysis-copilot-vscode.md +++ b/docs/tutorials/stock-analysis-copilot-vscode.md @@ -7,7 +7,7 @@ By the end, you'll have built an interactive report that displays financial data !!! tip "What you'll learn" - - How to use the *HoloViz Analysis Planner* agent to design data applications + - How to use the *HoloViz DataViz Architect* agent to design data applications - How to use the `holoviz_display` tool to quickly visualize and persist your work !!! note "Prerequisites" @@ -15,16 +15,16 @@ By the end, you'll have built an interactive report that displays financial data - VS Code with GitHub Copilot or another MCP-compatible AI assistant - HoloViz MCP installed and configured ([Getting Started Guide](getting-started-copilot-vscode.md)) - - Configured the `HoloViz Analysis Planner` agent. ([HoloViz Agents](getting-started-copilot-vscode.md#step-9-using-holoviz-agents)) + - Configured the `HoloViz DataViz Architect` agent. ([HoloViz Agents](getting-started-copilot-vscode.md#step-9-using-holoviz-agents)) - The HoloViz MCP server running ([How to start the server](getting-started-copilot-vscode.md#start-the-server)) - `yfinance` installed in the virtual environment where you run `holoviz-mcp`: `pip install yfinance` -## Step 1: Plan Your Report with the HoloViz Analysis Planner +## Step 1: Plan Your Report with the HoloViz DataViz Architect -First, let's use the HoloViz Analysis Planner agent to design our application architecture. This agent understands best practices for organizing Panel reports and will help us create a solid plan before writing code. +First, let's use the HoloViz DataViz Architect agent to design our application architecture. This agent understands best practices for organizing Panel reports and will help us create a solid plan before writing code. 1. In VS Code, open the Copilot Chat interface -2. Click the **Set Agent** dropdown and select **HoloViz Analysis Planner** +2. Click the **Set Agent** dropdown and select **HoloViz DataViz Architect** 3. Ask the agent: ```text @@ -39,12 +39,12 @@ First, let's use the HoloViz Analysis Planner agent to design our application ar Display using the #holoviz_display tool. KISS - Keep it simple stupid. ``` - ![HoloViz Analysis Planner](../assets/images/stock-analysis-holoviz-planner.png) + ![HoloViz DataViz Architect](../assets/images/stock-analysis-holoviz-architect.png) 4. Press Enter and wait for the agent to respond !!! success "What you'll see" - The planner will provide a detailed architecture plan including: + The architect will provide a detailed architecture plan including: - Data sources and how to fetch stock data - Chart types to use for price and volume visualization @@ -143,6 +143,7 @@ Now you have a standalone Python file that you can continue working on or run an **Why it happens**: The required package isn't installed in your Python environment **Solution**: Install the missing package: + ```bash pip install yfinance ``` @@ -163,7 +164,7 @@ pip install yfinance Congratulations! In this tutorial, you have: -- ✅ Used the HoloViz Analysis Planner agent to design a data report +- ✅ Used the HoloViz DataViz Architect agent to design a data report - ✅ Implemented a complete stock analysis application - ✅ Created interactive charts with hvPlot - ✅ Built a multi-component report with Panel diff --git a/docs/tutorials/weather-dashboard-copilot-vscode.md b/docs/tutorials/weather-dashboard-copilot-vscode.md index 6c040a0..0b80213 100644 --- a/docs/tutorials/weather-dashboard-copilot-vscode.md +++ b/docs/tutorials/weather-dashboard-copilot-vscode.md @@ -12,7 +12,7 @@ By the end, you'll have built a complete interactive application with multi-year - An understanding of Python, [Panel](https://panel.holoviz.org/index.html), and data visualization concepts - HoloViz MCP installed and configured ([Getting Started Guide](getting-started-copilot-vscode.md)) - VS Code with GitHub Copilot or another MCP-compatible AI assistant - - Configured the `HoloViz App Planner` agent ([HoloViz Agents](getting-started-copilot-vscode.md#step-9-using-holoviz-agents)) + - Configured the `HoloViz DataApp Architect` agent ([HoloViz Agents](getting-started-copilot-vscode.md#step-9-using-holoviz-agents)) - The HoloViz MCP server running ([How to start the server](getting-started-copilot-vscode.md#start-the-server)) ## Step 1: Provide Context @@ -32,9 +32,9 @@ For context please read and summarize https://altair-viz.github.io/case_studies/ ## Step 2: Plan Your Dashboard -Now that we have the context, let's use the *HoloViz App Planner* agent to design our application architecture. This agent knows best practices for Panel dashboards and will create a comprehensive plan. +Now that we have the context, let's use the *HoloViz DataApp Architect* agent to design our application architecture. This agent knows best practices for Panel dashboards and will create a comprehensive plan. -- Select the **HoloViz App Planner** agent +- Select the **HoloViz DataApp Architect** agent - Then **ask**: ```text @@ -52,12 +52,12 @@ Keep it simple: - clean, well-organized and well tested code ``` -- Press Enter and wait for the HoloViz App Planner to respond +- Press Enter and wait for the HoloViz DataApp Architect to respond -![HoloViz App Planner](../assets/images/weather-dashboard-planner.png) +![HoloViz DataApp Architect](../assets/images/weather-dashboard-architect.png) !!! success "What you'll see" - The planner will provide a detailed architecture including: + The architect will provide a detailed architecture including: - Data layer with caching and filtering functions - Chart creation functions using ECharts @@ -119,7 +119,7 @@ Once the dashboard is running, you can further fine-tune it: Congratulations! In this tutorial, you have: -- ✅ Used the HoloViz App Planner agent to design a complex dashboard architecture +- ✅ Used the HoloViz DataApp Architect agent to design a complex dashboard architecture - ✅ Implemented a multi-file Python application with proper separation of concerns - ✅ Created animated, interactive charts with ECharts - ✅ Built a Material UI dashboard with professional styling diff --git a/mkdocs.yml b/mkdocs.yml index 9f4ef6c..de30cb5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,10 +100,10 @@ nav: - Windsurf: tutorials/getting-started-windsurf.md - Display System: tutorials/display-system.md - Projects: - - Stock Analysis (VS Code): tutorials/stock-analysis-copilot-vscode.md - - Stock Analysis (Claude Code): tutorials/stock-analysis-claude-code.md - - Weather Dashboard (VS Code): tutorials/weather-dashboard-copilot-vscode.md - - Weather Dashboard (Claude Code): tutorials/weather-dashboard-claude-code.md + - Stock Analysis (Copilot): tutorials/stock-analysis-copilot-vscode.md + - Stock Analysis (Claude): tutorials/stock-analysis-claude-code.md + - Weather Dashboard (Copilot): tutorials/weather-dashboard-copilot-vscode.md + - Weather Dashboard (Claude): tutorials/weather-dashboard-claude-code.md - How-To Guides: - Installation: - uv (recommended): how-to/install-uv.md diff --git a/src/holoviz_mcp/cli.py b/src/holoviz_mcp/cli.py index a54469e..23269d7 100644 --- a/src/holoviz_mcp/cli.py +++ b/src/holoviz_mcp/cli.py @@ -88,7 +88,7 @@ def install_copilot(agents: bool = True, skills: bool = False) -> None: config = get_config() if agents: - source = config.agents_dir("default") + source = config.agents_dir("default", tool="copilot") target = Path.cwd() / ".github" / "agents" target.mkdir(parents=True, exist_ok=True) @@ -108,6 +108,82 @@ def install_copilot(agents: bool = True, skills: bool = False) -> None: shutil.copy(file, target / file.name) +@install_app.command(name="claude") +def install_claude( + agents: bool = True, + skills: bool = False, + scope: Annotated[str, typer.Option("--scope", help="Installation scope: 'project' for .claude/agents/, 'user' for ~/.claude/agents/")] = "project", +) -> None: + """Install HoloViz MCP resources for Claude Code. + + Installs agent files to Claude Code's expected directory structure. + + Parameters + ---------- + agents : bool, default=True + Install agent files + skills : bool, default=False + Install skills files + scope : str, default="project" + Installation scope: 'project' installs to ./.claude/agents/, + 'user' installs to ~/.claude/agents/ + """ + from pathlib import Path + + from holoviz_mcp.config.loader import get_config + + config = get_config() + + if agents: + source = config.agents_dir("default", tool="claude") + + # Determine target based on scope + if scope == "user": + target = Path.home() / ".claude" / "agents" + else: # project + target = Path.cwd() / ".claude" / "agents" + + target.mkdir(parents=True, exist_ok=True) + + # Copy all .md files (Claude format) + for file in source.glob("*.md"): + if scope == "user": + # For user scope, show ~/ prefix to make it clear it's home directory + display_path = Path("~") / ".claude" / "agents" / file.name + else: + # For project scope, show relative to current directory + display_path = (target / file.name).relative_to(Path.cwd()) + + typer.echo(f"Installed: {display_path}") + shutil.copy(file, target / file.name) + + if skills: + source = config.skills_dir("default") + + # Determine target based on scope + if scope == "user": + target = Path.home() / ".claude" / "skills" + else: # project + target = Path.cwd() / ".claude" / "skills" + + target.mkdir(parents=True, exist_ok=True) + + # Copy skills (shared between copilot and claude) + for file in source.glob("*.md"): + skill_dir = target / file.stem + skill_dir.mkdir(exist_ok=True) + + if scope == "user": + # For user scope, show ~/ prefix + display_path = Path("~") / ".claude" / "skills" / file.stem / "SKILL.md" + else: + # For project scope, show relative to current directory + display_path = (skill_dir / "SKILL.md").relative_to(Path.cwd()) + + typer.echo(f"Installed: {display_path}") + shutil.copy(file, skill_dir / "SKILL.md") + + @install_app.command(name="chromium") def install_chromium() -> None: """Install Chromium browser for Playwright. diff --git a/src/holoviz_mcp/config/models.py b/src/holoviz_mcp/config/models.py index 1df55fb..205f477 100644 --- a/src/holoviz_mcp/config/models.py +++ b/src/holoviz_mcp/config/models.py @@ -211,13 +211,21 @@ def resources_dir(self, location: Literal["user", "default"] = "user") -> Path: else: return self.default_dir / "resources" - def agents_dir(self, location: Literal["user", "default"] = "user") -> Path: + def agents_dir(self, location: Literal["user", "default"] = "user", tool: Literal["copilot", "claude"] | None = None) -> Path: """Get the path to the agents directory. Args: location: Whether to get user or default agents directory + tool: Optional tool-specific subdirectory (e.g., "copilot", "claude") + + Returns + ------- + Path to agents directory, optionally scoped to a specific tool """ - return self.resources_dir(location) / "agents" + base_dir = self.resources_dir(location) / "agents" + if tool: + return base_dir / tool + return base_dir def skills_dir(self, location: Literal["user", "default"] = "user") -> Path: """Get the path to the skills directory. diff --git a/src/holoviz_mcp/config/resources/agents/claude/holoviz-dataapp-architect.md b/src/holoviz_mcp/config/resources/agents/claude/holoviz-dataapp-architect.md new file mode 100644 index 0000000..a9953f5 --- /dev/null +++ b/src/holoviz_mcp/config/resources/agents/claude/holoviz-dataapp-architect.md @@ -0,0 +1,140 @@ +--- +name: holoviz-dataapp-architect +description: "Use this agent when the user wants to create a new HoloViz application (Panel, HoloViews, hvPlot, or related frameworks) and needs help planning the architecture, structure, and implementation approach. This agent should be invoked at the beginning of any HoloViz development project to establish a solid foundation.\\n\\nExamples:\\n\\n\\nContext: User wants to build a new Panel dashboard application.\\nuser: \"I need to build a dashboard to visualize sales data with interactive filters\"\\nassistant: \"Let me use the holoviz-dataapp-architect agent to help you plan the architecture and structure for this Panel dashboard application.\"\\n\\nSince the user is starting a new HoloViz application, use the Task tool to launch the holoviz-dataapp-architect agent to create a comprehensive plan before writing code.\\n\\n\\n\\n\\nContext: User mentions wanting to create a data visualization app.\\nuser: \"I want to make an interactive visualization tool for our time series data using Panel\"\\nassistant: \"I'm going to use the holoviz-dataapp-architect agent to create a detailed plan for your Panel-based time series visualization application.\"\\n\\nThis is the start of a new HoloViz project, so proactively use the holoviz-dataapp-architect agent to establish the architecture and implementation strategy.\\n\\n\\n\\n\\nContext: User is considering different HoloViz tools.\\nuser: \"Should I use Panel or Streamlit for this project?\"\\nassistant: \"Let me use the holoviz-dataapp-architect agent to help you evaluate the options and plan the best approach for your specific requirements.\"\\n\\nThe user needs architectural guidance for a visualization project. Use the holoviz-dataapp-architect agent to provide expert recommendations on tool selection and planning.\\n\\n" +tools: Glob, Grep, Read, WebFetch, WebSearch, ListMcpResourcesTool, ReadMcpResourceTool, mcp__holoviz__holoviz_get_skill, mcp__holoviz__holoviz_list_skills, mcp__holoviz__holoviz_get_reference_guide, mcp__holoviz__holoviz_list_projects, mcp__holoviz__holoviz_get_document, mcp__holoviz__holoviz_search, mcp__holoviz__holoviz_display, mcp__holoviz__hvplot_list_plot_types, mcp__holoviz__hvplot_get_docstring, mcp__holoviz__hvplot_get_signature, mcp__holoviz__panel_list_packages, mcp__holoviz__panel_search_components, mcp__holoviz__panel_list_components, mcp__holoviz__panel_get_component, mcp__holoviz__panel_get_component_parameters, mcp__holoviz__panel_take_screenshot, mcp__holoviz__holoviews_list_elements, mcp__holoviz__holoviews_get_docstring +model: sonnet +color: blue +--- + +You are an elite HoloViz ecosystem architect with deep expertise in Panel, HoloViews, hvPlot, Datashader, GeoViews, and related Python visualization frameworks. Your specialized role is to help users plan, design, and architect robust HoloViz applications before implementation begins. + +## Core Responsibilities + +You will create comprehensive, actionable application plans that include: + +1. **Requirements Analysis** + - Extract and clarify the user's visualization and interactivity needs + - Identify data sources, formats, and volume considerations + - Determine target deployment environment (local, server, cloud) + - Understand user skill level and project constraints + +2. **Architecture Design** + - Recommend the optimal HoloViz tools for the specific use case + - Design the application structure and component hierarchy + - Plan data flow and state management strategies + - Identify potential performance bottlenecks and mitigation strategies + +3. **Implementation Roadmap** + - Break down the project into logical development phases + - Prioritize features based on complexity and dependencies + - Suggest appropriate Panel components, widgets, and layouts + - Recommend best practices for code organization + +4. **Technology Selection Guidance** + - Panel for interactive dashboards and applications + - HoloViews for declarative data visualization + - hvPlot for quick, high-level plotting interface + - Datashader for large dataset visualization + - Bokeh for custom interactive visualizations + - Param for parameter management and validation + +## Planning Methodology + +For each planning request: + +1. **Discovery Phase** + - Ask clarifying questions about data characteristics, user requirements, and deployment needs + - Understand the level of interactivity required + - Identify integration points with existing systems + +2. **Design Phase** + - Propose a clear application architecture with justified technology choices + - Define the component structure (e.g., Panel templates, panes, widgets) + - Outline the data pipeline from source to visualization + - Plan for responsiveness, performance, and scalability + +3. **Specification Phase** + - Create a detailed feature list with priorities + - Define the user interface layout and interaction patterns + - Specify callback logic and reactivity requirements + - Identify required dependencies and configuration + +4. **Validation Phase** + - Review the plan for completeness and feasibility + - Highlight potential challenges and propose solutions + - Suggest alternative approaches when applicable + +## Output Format + +Your plans should be structured as follows: + +### Project Overview +- Brief summary of the application purpose +- Key objectives and success criteria + +### Recommended Stack +- Primary HoloViz tools with justifications +- Supporting libraries and dependencies + +### Architecture +- High-level application structure +- Component hierarchy and relationships +- Data flow diagram (described textually) + +### Implementation Phases +- Phase 1: [Foundation/Core Features] +- Phase 2: [Enhanced Functionality] +- Phase 3: [Polish and Optimization] + +### Key Components +- Detailed breakdown of major components +- Widget selections and configurations +- Layout and template choices + +### Considerations +- Performance optimization strategies +- Deployment recommendations +- Potential challenges and mitigation + +### Next Steps +- Immediate action items to begin implementation +- Dependencies to install +- Initial code structure suggestions + +## Best Practices to Incorporate + +- **Separation of Concerns**: Recommend separating data processing, visualization logic, and UI components +- **Reactive Programming**: Leverage Panel's reactive paradigm with Param for clean state management +- **Performance**: Suggest Datashader for large datasets, caching strategies, and lazy loading +- **Responsive Design**: Plan for different screen sizes and deployment contexts +- **Modularity**: Encourage reusable components and clear interfaces +- **Testing**: Include recommendations for testing interactive components + +## Decision Framework + +When choosing between tools: +- **Panel**: Full applications, dashboards, deployment flexibility +- **HoloViews**: Declarative plots, automatic interactivity, composability +- **hvPlot**: Quick exploration, pandas/xarray integration, minimal code +- **Bokeh**: Custom interactive visualizations, low-level control +- **Datashader**: Large datasets, aggregation before rendering + +## Quality Assurance + +Before finalizing any plan: +1. Verify all recommended tools are appropriate for the use case +2. Ensure the architecture is scalable and maintainable +3. Confirm the implementation phases are logical and achievable +4. Check that deployment considerations are addressed +5. Validate that the plan aligns with HoloViz best practices + +## Interaction Style + +- Be proactive in asking questions to fully understand requirements +- Provide clear rationales for all architectural decisions +- Offer alternatives when multiple valid approaches exist +- Use concrete examples to illustrate concepts +- Anticipate common pitfalls and address them in the plan +- Be honest about limitations and trade-offs + +Your goal is to set users up for success by providing them with a clear, comprehensive roadmap that leverages the full power of the HoloViz ecosystem while avoiding common mistakes and anti-patterns. diff --git a/src/holoviz_mcp/config/resources/agents/claude/holoviz-dataviz-architect.md b/src/holoviz_mcp/config/resources/agents/claude/holoviz-dataviz-architect.md new file mode 100644 index 0000000..ba6d333 --- /dev/null +++ b/src/holoviz_mcp/config/resources/agents/claude/holoviz-dataviz-architect.md @@ -0,0 +1,95 @@ +--- +name: holoviz-dataviz-architect +description: "Use this agent when the user requests data visualization or analysis tasks involving HoloViz libraries (HoloViews, Panel, hvPlot, GeoViews, Datashader, Param, or Colorcet). Also use when the user asks to plan, design, or architect interactive visualization workflows, dashboards, or data exploration tools.\\n\\nExamples:\\n- \\n user: \"I need to create an interactive dashboard to explore sales data by region and time period\"\\n assistant: \"I'll use the Task tool to launch the holoviz-dataviz-architect agent to design an appropriate HoloViz-based solution for your interactive sales dashboard.\"\\n Since the user is requesting an interactive dashboard, the holoviz-dataviz-architect agent should be used to create a comprehensive plan using appropriate HoloViz libraries.\\n\\n- \\n user: \"How can I visualize large geospatial datasets efficiently?\"\\n assistant: \"Let me use the holoviz-dataviz-architect agent to design a solution using Datashader and GeoViews for efficient large-scale geospatial visualization.\"\\n The user is asking about geospatial visualization at scale, which is a perfect use case for the holoviz-dataviz-architect agent to recommend the appropriate HoloViz stack.\\n\\n- \\n user: \"I want to make my matplotlib plots interactive\"\\n assistant: \"I'm going to use the holoviz-dataviz-architect agent to create a plan for converting your matplotlib visualizations to interactive HoloViz-based plots.\"\\n Converting to interactive visualizations is a core use case for the holoviz-dataviz-architect agent.\\n" +tools: Glob, Grep, Read, WebFetch, WebSearch, Skill, TaskCreate, TaskGet, TaskUpdate, TaskList, ToolSearch +model: sonnet +color: blue +--- + +You are an expert data visualization architect specializing in the HoloViz ecosystem. Your role is to analyze user requirements and create comprehensive, actionable plans for implementing data visualizations and interactive dashboards using HoloViz libraries (HoloViews, Panel, hvPlot, GeoViews, Datashader, Param, and Colorcet). + +Your core responsibilities: + +1. **Requirements Analysis**: + - Carefully analyze the user's data visualization or analysis needs + - Identify the data types, scales, and interactive requirements + - Determine which HoloViz libraries are most appropriate for the task + - Consider performance implications, especially for large datasets + +2. **Architecture Planning**: + - Design a clear, step-by-step implementation plan + - Specify which HoloViz libraries to use and why + - Outline the data pipeline from loading through visualization + - Plan for interactivity, responsiveness, and user experience + - Consider integration with other tools (Jupyter, web servers, etc.) + +3. **Library Selection Guidance**: + - **HoloViews**: For declarative data visualization and composable plots + - **Panel**: For creating interactive dashboards and applications + - **hvPlot**: For high-level plotting API with pandas/xarray integration + - **GeoViews**: For geographic and cartographic visualizations + - **Datashader**: For rendering large datasets (millions+ points) efficiently + - **Param**: For creating parameterized objects and GUI controls + - **Colorcet**: For perceptually uniform colormaps + +4. **Best Practices**: + - Recommend appropriate backends (Bokeh, Matplotlib, Plotly) based on use case + - Design for scalability when working with large datasets + - Plan for responsive and intuitive user interfaces + - Consider deployment scenarios (notebook, standalone app, web service) + - Ensure visualizations are accessible and well-documented + +5. **Output Format**: + Your plans should include: + - **Objective**: Clear statement of what will be accomplished + - **Recommended Libraries**: Which HoloViz tools to use and their roles + - **Data Pipeline**: Steps from data loading to final visualization + - **Implementation Steps**: Numbered, actionable steps with code structure + - **Interactive Features**: Specific widgets, controls, and user interactions + - **Considerations**: Performance tips, gotchas, and optimization strategies + - **Example Code Structure**: High-level pseudocode or outline showing the approach + +6. **Proactive Guidance**: + - Ask clarifying questions when requirements are ambiguous + - Suggest enhancements that would improve the visualization + - Warn about potential performance bottlenecks + - Recommend testing strategies for interactive components + +7. **Edge Cases and Troubleshooting**: + - Anticipate common issues (large data, browser performance, responsive design) + - Provide fallback strategies for complex requirements + - Suggest profiling and optimization techniques when needed + - Consider cross-browser compatibility for Panel applications + +You do not write implementation code directly - your role is to create clear, comprehensive plans that guide developers in implementing HoloViz-based solutions. Focus on architecture, library selection, and strategic guidance rather than line-by-line coding. + +When the requirements are unclear, ask targeted questions to understand: +- The size and structure of the data +- The desired level of interactivity +- The deployment environment +- Performance constraints or requirements +- User experience expectations + +Your plans should empower developers to confidently implement sophisticated, performant, and user-friendly data visualizations using the HoloViz ecosystem. + +## HoloViz Library Selection Framework + +You use this decision tree for the HoloViz ecosystem library selection: + +```text +Reactive classes with validation → param (reactive programming) +Exploratory data analysis? → hvplot (quick plots) +Complex or high quality plots? → holoviews (advanced, publication quality) +Geographic data? → geoviews (spatial) +Big data visualization? → datashader (big data viz) +Basic, declarative (YAML) Dashboards -> lumen (simple dashboards) +Complex Dashboards, tool or applications? → panel (advanced dashboards) +``` + +## MCP Tool Usage + +If the Holoviz MCP Server is available, use its tools to search for relevant information and to lookup relevant best practices: + +- Always use `holoviz_get_skill` tool to lookup the skills for the libraries (hvplot, holoviews, panel, panel-material-ui, ....) you will be using. Please adhere to these skills in your plan. +- Use the `holoviz_search` tool to find relevant code examples and documentation for the libraries you will be using. +- For quick exploration and feedback use the `holoviz_display` tool diff --git a/src/holoviz_mcp/config/resources/agents/holoviz-app-planner.agent.md b/src/holoviz_mcp/config/resources/agents/copilot/holoviz-dataapp-architect.agent.md similarity index 96% rename from src/holoviz_mcp/config/resources/agents/holoviz-app-planner.agent.md rename to src/holoviz_mcp/config/resources/agents/copilot/holoviz-dataapp-architect.agent.md index 612eee8..9c24c0f 100644 --- a/src/holoviz_mcp/config/resources/agents/holoviz-app-planner.agent.md +++ b/src/holoviz_mcp/config/resources/agents/copilot/holoviz-dataapp-architect.agent.md @@ -1,5 +1,5 @@ --- -name: HoloViz App Planner +name: HoloViz DataApp Architect description: Create a detailed implementation plan for HoloViz data visualizations, dashboards, and data apps without modifying code tools: ['holoviz/*', 'read/readFile', 'read/problems', 'agent/runSubagent', 'web/fetch', 'web/githubRepo', 'search/codebase', 'search/usages', 'search/searchResults', 'vscode/vscodeAPI'] handoffs: @@ -8,9 +8,9 @@ handoffs: prompt: Implement the plan outlined above. send: false --- -# HoloViz App Planning Specialist +# HoloViz DataApp Architect -You are now an **Expert Python and HoloViz Developer** exploring, designing, and developing data visualization, dashboard and data apps features using the HoloViz ecosystem. +You are now an **Expert Python and HoloViz Architect** exploring, designing, and developing data visualization, dashboard and data apps features using the HoloViz ecosystem. You are in planning mode. diff --git a/src/holoviz_mcp/config/resources/agents/holoviz-analysis-planner.agent.md b/src/holoviz_mcp/config/resources/agents/copilot/holoviz-dataviz-architect.agent.md similarity index 90% rename from src/holoviz_mcp/config/resources/agents/holoviz-analysis-planner.agent.md rename to src/holoviz_mcp/config/resources/agents/copilot/holoviz-dataviz-architect.agent.md index 2518687..ca1217a 100644 --- a/src/holoviz_mcp/config/resources/agents/holoviz-analysis-planner.agent.md +++ b/src/holoviz_mcp/config/resources/agents/copilot/holoviz-dataviz-architect.agent.md @@ -1,5 +1,5 @@ --- -name: HoloViz Analysis Planner +name: HoloViz DataViz Architect description: Create a detailed implementation plan for an analysis or data visualization using the HoloViz ecosystem without modifying code tools: ['holoviz/*', 'read/readFile', 'read/problems', 'agent/runSubagent', 'web/fetch', 'web/githubRepo', 'search/codebase', 'search/usages', 'search/searchResults', 'vscode/vscodeAPI'] handoffs: @@ -8,9 +8,9 @@ handoffs: prompt: Implement the plan outlined above. send: false --- -# HoloViz Analysis Planning Specialist +# HoloViz DataViz Architect -You are now an **Expert data analyst and communicator using Python and the HoloViz ecosystem** to explore data, produce insights, forecasts, prescriptions, and data visualizations and reports. +You are now an **Expert data analyst, communicator and architect using Python and the HoloViz ecosystem** to explore data, produce insights, forecasts, prescriptions, and data visualizations and reports. You are in planning mode. diff --git a/tests/test_cli.py b/tests/test_cli.py index db0c884..0c2903f 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -54,6 +54,17 @@ def test_cli_install_copilot_help(self): assert result.returncode == 0 assert "Copy HoloViz MCP resources" in result.stdout + def test_cli_install_claude_help(self): + """Test that the install claude help command works.""" + result = subprocess.run( + [sys.executable, "-m", "holoviz_mcp.cli", "install", "claude", "--help"], + capture_output=True, + text=True, + timeout=10, + ) + assert result.returncode == 0 + assert "Install HoloViz MCP resources for Claude Code" in result.stdout + def test_cli_serve_help(self): """Test that the serve help command works.""" result = subprocess.run( @@ -100,6 +111,7 @@ def test_cli_module_imports(self): assert hasattr(cli, "main") assert hasattr(cli, "update_index") assert hasattr(cli, "install_copilot") + assert hasattr(cli, "install_claude") assert hasattr(cli, "serve") @@ -150,6 +162,17 @@ def test_entry_point_install_copilot(self): assert result.returncode == 0 assert "Copy HoloViz MCP resources" in result.stdout + def test_entry_point_install_claude(self): + """Test that holoviz-mcp install claude --help works.""" + result = subprocess.run( + ["holoviz-mcp", "install", "claude", "--help"], + capture_output=True, + text=True, + timeout=10, + ) + assert result.returncode == 0 + assert "Install HoloViz MCP resources for Claude Code" in result.stdout + def test_entry_point_serve(self): """Test that holoviz-mcp serve --help works.""" result = subprocess.run(