diff --git a/.github/ISSUE_TEMPLATE/report-issue.yml b/.github/ISSUE_TEMPLATE/report-issue.yml new file mode 100644 index 0000000000..a862b5ae83 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/report-issue.yml @@ -0,0 +1,85 @@ +name: Report Issue +description: Report an issue with an existing plot spec or implementation +title: "Report: " +labels: ["report-pending"] +body: + - type: markdown + attributes: + value: | + ## Report an Issue + + Found a problem with an existing plot? Let us know! + + Our AI will validate and structure your report, then queue it for maintainer review. + + - type: input + id: spec_id + attributes: + label: Specification ID + description: "The spec ID of the affected plot" + placeholder: "e.g., scatter-basic, qrcode-basic, heatmap-correlation" + validations: + required: true + + - type: dropdown + id: target + attributes: + label: What has the issue? + description: "Is this an issue with the specification itself or a specific library implementation?" + options: + - Specification (affects all libraries) + - Implementation (specific library) + validations: + required: true + + - type: dropdown + id: library + attributes: + label: Library (only for implementation issues) + description: "Which library implementation has the issue? Select N/A for spec issues." + options: + - N/A (spec issue) + - matplotlib + - seaborn + - plotly + - bokeh + - altair + - plotnine + - pygal + - highcharts + - letsplot + validations: + required: false + + - type: dropdown + id: category + attributes: + label: Issue Category + description: "What type of issue is this?" + options: + - Visual (ugly, unclear, hard to read) + - Data (unrealistic values, inappropriate context) + - Functional (doesn't work as expected, e.g., QR code not scannable) + - Other + validations: + required: true + + - type: textarea + id: description + attributes: + label: Issue Description + description: "Describe the issue. What's wrong? What should it look like instead?" + placeholder: | + Example: The QR code generated looks like a QR code but cannot be scanned by any QR reader app. + + Expected: The QR code should be a valid, scannable code that links to the specified URL. + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Additional Context (optional) + description: "Screenshots, comparison images, or other helpful information" + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/plot-request.yml b/.github/ISSUE_TEMPLATE/spec-request.yml similarity index 98% rename from .github/ISSUE_TEMPLATE/plot-request.yml rename to .github/ISSUE_TEMPLATE/spec-request.yml index 6df991d71d..b738bfd497 100644 --- a/.github/ISSUE_TEMPLATE/plot-request.yml +++ b/.github/ISSUE_TEMPLATE/spec-request.yml @@ -1,6 +1,6 @@ name: Plot Request description: Propose a new plot type for pyplots -labels: ["plot-request"] +labels: ["spec-request"] body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/plot-update.yml b/.github/ISSUE_TEMPLATE/spec-update.yml similarity index 98% rename from .github/ISSUE_TEMPLATE/plot-update.yml rename to .github/ISSUE_TEMPLATE/spec-update.yml index e04524702b..74f30d2ff8 100644 --- a/.github/ISSUE_TEMPLATE/plot-update.yml +++ b/.github/ISSUE_TEMPLATE/spec-update.yml @@ -1,7 +1,7 @@ name: Plot Update description: Request updates or regeneration of an existing plot title: "[SPEC-ID] [update] " -labels: ["plot-request", "update"] +labels: ["spec-update"] body: - type: markdown attributes: diff --git a/.github/workflows/report-validate.yml b/.github/workflows/report-validate.yml new file mode 100644 index 0000000000..fa34f405fd --- /dev/null +++ b/.github/workflows/report-validate.yml @@ -0,0 +1,164 @@ +name: "Report: Validate" +run-name: "Validate Report: ${{ github.event.issue.title }}" + +# Validates and structures user-submitted issue reports +# Flow: +# 1. User submits report → report-pending label auto-added +# 2. AI validates spec/impl exists, analyzes issue, posts structured comment +# 3. Labels updated: report-validated + category + report:spec/impl + +on: + issues: + types: [labeled] + +concurrency: + group: report-validate-${{ github.event.issue.number }} + cancel-in-progress: false + +jobs: + validate: + if: github.event.label.name == 'report-pending' + runs-on: ubuntu-latest + permissions: + contents: read + issues: write + + steps: + - name: Check if already validated + id: check + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # Check if already has report-validated label + LABELS=$(gh issue view ${{ github.event.issue.number }} --json labels -q '.labels[].name' | tr '\n' ' ') + if echo "$LABELS" | grep -q "report-validated"; then + echo "::notice::Skipping: Issue already validated" + echo "should_run=false" >> $GITHUB_OUTPUT + exit 0 + fi + echo "should_run=true" >> $GITHUB_OUTPUT + + - name: Checkout repository + if: steps.check.outputs.should_run == 'true' + uses: actions/checkout@v6 + + - name: React with eyes emoji + if: steps.check.outputs.should_run == 'true' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh api repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/reactions \ + -f content=eyes + + - name: Validate with Claude + if: steps.check.outputs.should_run == 'true' + id: validate + continue-on-error: true + timeout-minutes: 10 + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + claude_args: "--model sonnet" + prompt: | + ## Task: Validate Issue Report + + You are validating a user-submitted issue report for pyplots. + + ### Issue Details + - **Title:** ${{ github.event.issue.title }} + - **Number:** #${{ github.event.issue.number }} + - **Author:** ${{ github.event.issue.user.login }} + - **Body:** + ``` + ${{ github.event.issue.body }} + ``` + + --- + + ## Instructions + + 1. **Read the prompt:** `prompts/workflow-prompts/report-analysis.md` + + 2. **Parse the issue body** to extract: + - spec_id (from "Specification ID" field) + - target (Specification or Implementation) + - library (if implementation) + - category (Visual/Data/Functional/Other) + - description + + 3. **Validate the spec exists:** + ```bash + ls plots/{spec_id}/ + ``` + If NOT found: + - Post comment: "Spec `{spec_id}` not found. Please check the ID." + - Remove `report-pending` label + - Close issue + - STOP + + 4. **If implementation issue, validate the library exists:** + ```bash + ls plots/{spec_id}/implementations/{library}.py + ``` + If NOT found: + - Post comment: "Implementation `{library}` not found for `{spec_id}`." + - Remove `report-pending` label + - Close issue + - STOP + + 5. **Read relevant files:** + - `plots/{spec_id}/specification.md` + - `plots/{spec_id}/metadata/{library}.yaml` (if impl issue) + + 6. **Post structured analysis comment** following the format in the prompt file. + + 7. **Update issue title:** + ```bash + gh issue edit ${{ github.event.issue.number }} --title "[{spec_id}] {brief description}" + ``` + + 8. **Update labels:** + ```bash + # Remove pending, add validated + gh issue edit ${{ github.event.issue.number }} --remove-label "report-pending" --add-label "report-validated" + + # Add target label + gh issue edit ${{ github.event.issue.number }} --add-label "report:spec" + # OR for impl: + gh issue edit ${{ github.event.issue.number }} --add-label "report:impl" --add-label "report:impl:{library}" + + # Add category label (map from dropdown value) + # Visual → category:visual + # Data → category:data + # Functional → category:functional + # Other → category:other + gh issue edit ${{ github.event.issue.number }} --add-label "category:{category}" + ``` + + ### Important + - Do NOT add the `approved` label + - Do NOT trigger any fixes + - Keep the analysis comment concise but informative + + - name: Add reaction on success + if: steps.check.outputs.should_run == 'true' && steps.validate.outcome == 'success' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh api repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/reactions \ + -f content=rocket + + - name: Handle failure + if: steps.check.outputs.should_run == 'true' && steps.validate.outcome == 'failure' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh issue comment ${{ github.event.issue.number }} --body "## :x: Validation Failed + + The AI validation workflow encountered an error. A maintainer will review this manually. + + --- + :robot: *[report-validate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*" + + gh api repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/reactions \ + -f content=confused diff --git a/CLAUDE.md b/CLAUDE.md index 62f9151916..0422d373e6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -618,6 +618,12 @@ Located in `.github/workflows/`: | **impl-merge.yml** | `ai-approved` label OR workflow_dispatch | Merges approved PR, creates metadata/{library}.yaml | | **bulk-generate.yml** | workflow_dispatch only | Dispatches multiple implementations (max 3 parallel) | +### Report Workflows (`report-*.yml`) + +| Workflow | Trigger | Purpose | +|----------|---------|---------| +| **report-validate.yml** | `report-pending` label | Validates and structures user-submitted issue reports | + ### Workflow Data Flow **Flow A: New Specification (with approval gate)** @@ -674,6 +680,29 @@ impl-review.yml └── Re-triggers impl-review.yml ``` +**Flow C: Report Issue** + +``` +User submits report issue (from pyplots.ai or GitHub) + │ + ▼ (report-pending label auto-added) + │ +report-validate.yml + ├── Validates spec/impl exists + ├── Reads specification and metadata + ├── AI analyzes the issue + ├── Posts structured analysis comment + ├── Updates title: [{spec-id}] {brief description} + └── Updates labels: report-validated + category:* + report:spec/impl + │ + ▼ +Issue ready for maintainer review + │ + ▼ (maintainer adds `approved` label) + │ +(Fix workflow - future implementation) +``` + ### Supporting Workflows | Workflow | Purpose | @@ -757,6 +786,20 @@ These are set automatically by `impl-review.yml` after AI evaluation and used by - **`documentation`** - Documentation improvements - **`enhancement`** - New feature or improvement +### Report Labels + +| Label | Purpose | +|-------|---------| +| `report:spec` | Issue with the specification (affects all libraries) | +| `report:impl` | Issue with a specific implementation | +| `report:impl:{library}` | Specific library affected (e.g., `report:impl:matplotlib`) | +| `category:visual` | Design/visual issues | +| `category:data` | Data quality issues | +| `category:functional` | Non-functional elements | +| `category:other` | Other issues | +| `report-pending` | Report submitted, awaiting AI validation | +| `report-validated` | AI validated, ready for maintainer review | + ### New Specification Workflow 1. User creates issue with descriptive title (e.g., "3D scatter plot with rotation animation") diff --git a/README.md b/README.md index 80515b6617..8ff49727b5 100644 --- a/README.md +++ b/README.md @@ -118,24 +118,23 @@ pyplots/ We welcome contributions! **All code is AI-generated** - you propose ideas, AI implements them. -**How to contribute**: +**Three ways to contribute** (from [pyplots.ai](https://pyplots.ai) or GitHub): -1. **Propose plot ideas** - Create GitHub Issue with plot description (what you want to visualize) -2. **Improve specs** - Suggest better descriptions for existing plots -3. **Report issues** - Found bugs or quality problems? Open an Issue -4. **Improve docs** - Help others understand the project +| Action | When to Use | From pyplots.ai | +|--------|-------------|-----------------| +| **Suggest Spec** | Propose a new plot type | "suggest spec" link in catalog | +| **Report Spec Issue** | Problem with a specification | "report issue" link on spec page | +| **Report Impl Issue** | Problem with a library implementation | "report issue" link on impl page | -**The workflow**: +**How it works**: -1. You create Issue with plot idea + add `spec-request` label -2. AI generates spec, creates feature branch -3. Maintainer reviews and adds `approved` label -4. 9 library implementations generate in parallel (tracked via live status table) -5. AI quality review per library (≥ 90 instant, < 90 repair loop, ≥ 50 final threshold) -6. Auto-merge to feature branch, then to main +1. You create Issue (or click link on pyplots.ai) +2. AI validates and processes your input +3. Maintainer reviews and approves +4. AI generates/fixes the code +5. Automated quality review ensures excellence -**Important**: Don't submit code directly! If a plot has quality issues, it means the spec needs improvement, not the -code. +**Important**: Don't submit code directly! If a plot has quality issues, it means the spec needs improvement, not the code. See [contributing.md](docs/contributing.md) for details. @@ -167,6 +166,6 @@ MIT License - see [LICENSE](LICENSE) file for details. **Built by [Markus Neusinger](https://linkedin.com/in/markus-neusinger/)** -[⭐ Star us on GitHub](https://github.com/MarkusNeusinger/pyplots) • [🐛 Report Bug](https://github.com/MarkusNeusinger/pyplots/issues) • [💡 Request Feature](https://github.com/MarkusNeusinger/pyplots/issues) +[⭐ Star us on GitHub](https://github.com/MarkusNeusinger/pyplots) • [💡 Suggest Spec](https://github.com/MarkusNeusinger/pyplots/issues/new?template=spec-request.yml) • [🐛 Report Issue](https://github.com/MarkusNeusinger/pyplots/issues/new?template=report-issue.yml) diff --git a/app/src/pages/CatalogPage.tsx b/app/src/pages/CatalogPage.tsx index 1724369fac..e81c36c3f5 100644 --- a/app/src/pages/CatalogPage.tsx +++ b/app/src/pages/CatalogPage.tsx @@ -7,7 +7,7 @@ import Skeleton from '@mui/material/Skeleton'; import Fab from '@mui/material/Fab'; import KeyboardArrowUpIcon from '@mui/icons-material/KeyboardArrowUp'; -import { API_URL } from '../constants'; +import { API_URL, GITHUB_URL } from '../constants'; import { useAnalytics } from '../hooks'; import { useAppData, useHomeState } from '../components/Layout'; import { Footer } from '../components'; @@ -156,6 +156,7 @@ export function CatalogPage() { + {/* Breadcrumb links */} + + + pyplots.ai + + › + + catalog + + + + {/* Suggest spec link */} - pyplots.ai - - › - - catalog + suggest spec diff --git a/app/src/pages/SpecPage.tsx b/app/src/pages/SpecPage.tsx index 03997abc98..f68d269ee0 100644 --- a/app/src/pages/SpecPage.tsx +++ b/app/src/pages/SpecPage.tsx @@ -8,6 +8,7 @@ import IconButton from '@mui/material/IconButton'; import Tooltip from '@mui/material/Tooltip'; import Skeleton from '@mui/material/Skeleton'; import ArrowBackIcon from '@mui/icons-material/ArrowBack'; +import BugReportIcon from '@mui/icons-material/BugReport'; import DownloadIcon from '@mui/icons-material/Download'; import OpenInNewIcon from '@mui/icons-material/OpenInNew'; import ContentCopyIcon from '@mui/icons-material/ContentCopy'; @@ -16,7 +17,7 @@ import CheckIcon from '@mui/icons-material/Check'; import MuiLink from '@mui/material/Link'; import ClickAwayListener from '@mui/material/ClickAwayListener'; -import { API_URL } from '../constants'; +import { API_URL, GITHUB_URL } from '../constants'; import { useAnalytics } from '../hooks'; import { useAppData } from '../components/Layout'; import { LibraryPills } from '../components/LibraryPills'; @@ -179,6 +180,23 @@ export function SpecPage() { [specId, trackEvent, isOverviewMode] ); + // Build report issue URL + const buildReportUrl = useCallback(() => { + const params = new URLSearchParams({ + template: 'report-issue.yml', + spec_id: specId || '', + }); + + if (selectedLibrary) { + params.set('target', 'Implementation (specific library)'); + params.set('library', selectedLibrary); + } else { + params.set('target', 'Specification (affects all libraries)'); + } + + return `${GITHUB_URL}/issues/new?${params.toString()}`; + }, [specId, selectedLibrary]); + // Track page view useEffect(() => { if (specData) { @@ -235,6 +253,7 @@ export function SpecPage() { - - pyplots.ai - - › - - catalog - - › - {isOverviewMode ? ( - - {specId} + {/* Breadcrumb links */} + + + pyplots.ai - ) : ( - <> + › + + catalog + + › + {isOverviewMode ? ( + + {specId} + + ) : ( + <> + + {specId} + + › + + {selectedLibrary} + + + )} + + + {/* Report issue link - responsive */} + + + {/* Icon for mobile (xs, sm) */} + + {/* Text for desktop (md+) */} - {specId} - - › - - {selectedLibrary} + report issue - - )} + + {/* Title */} diff --git a/app/src/types/index.ts b/app/src/types/index.ts index 2ea68db8b7..d1956dab1f 100644 --- a/app/src/types/index.ts +++ b/app/src/types/index.ts @@ -29,7 +29,7 @@ export type FilterCategory = export const FILTER_LABELS: Record = { // Spec-level lib: 'library', - spec: 'example', + spec: 'spec', plot: 'type', data: 'data', dom: 'field', @@ -46,7 +46,7 @@ export const FILTER_LABELS: Record = { export const FILTER_TOOLTIPS: Record = { // Spec-level: WHAT is visualized lib: 'python plotting library', - spec: 'specific plot example by identifier', + spec: 'plot specification by identifier', plot: 'type of visualization or chart', data: 'structure of the input data', dom: 'application domain or field', diff --git a/docs/contributing.md b/docs/contributing.md index 7531fcb781..054702a397 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,7 +6,19 @@ pyplots is a specification-driven platform where **AI generates all plot impleme --- -## How to Propose a New Plot Type +## Three Ways to Contribute + +| Action | When to Use | From pyplots.ai | +|--------|-------------|-----------------| +| **[Suggest Spec](#suggest-a-new-plot-type)** | Propose a new plot type | Click "suggest spec" in catalog | +| **[Report Spec Issue](#report-a-spec-issue)** | Problem with a specification | Click "report issue" on spec page | +| **[Report Impl Issue](#report-an-impl-issue)** | Problem with a library implementation | Click "report issue" on impl page | + +All contributions go through GitHub Issues with AI-powered validation and processing. + +--- + +## Suggest a New Plot Type 1. **Create a GitHub Issue** with a descriptive title (e.g., "Radar Chart with Multiple Series") - Do NOT include spec-id in the title @@ -21,7 +33,36 @@ pyplots is a specification-driven platform where **AI generates all plot impleme --- -## How to Improve an Existing Spec +## Report a Spec Issue + +Found a problem with a specification (affects all libraries)? + +1. **From pyplots.ai**: Navigate to the spec page (e.g., `/scatter-basic`) and click "report issue" +2. **From GitHub**: Create issue using the [Report Issue](https://github.com/MarkusNeusinger/pyplots/issues/new?template=report-issue.yml) template +3. **Select "Specification"** as the target +4. **Choose a category**: Visual, Data, Functional, or Other +5. **Describe the issue** + +AI validates your report and adds structured analysis. Maintainers review and approve fixes. + +--- + +## Report an Impl Issue + +Found a problem with a specific library implementation? + +1. **From pyplots.ai**: Navigate to the impl page (e.g., `/scatter-basic/matplotlib`) and click "report issue" +2. **From GitHub**: Create issue using the [Report Issue](https://github.com/MarkusNeusinger/pyplots/issues/new?template=report-issue.yml) template +3. **Select "Implementation"** as the target +4. **Select the library** (matplotlib, seaborn, etc.) +5. **Choose a category**: Visual, Data, Functional, or Other +6. **Describe the issue** + +AI validates your report and adds structured analysis. Maintainers review and approve fixes. + +--- + +## Update an Existing Spec 1. **Create a GitHub Issue** referencing the spec to update 2. **Add the `spec-update` label** @@ -30,7 +71,7 @@ pyplots is a specification-driven platform where **AI generates all plot impleme --- -## How to Trigger Implementation Generation +## Trigger Implementation Generation After a spec has the `spec-ready` label: diff --git a/docs/plot-types-catalog.md b/docs/plot-types-catalog.md index f001561b3d..8f48efbc26 100644 --- a/docs/plot-types-catalog.md +++ b/docs/plot-types-catalog.md @@ -72,7 +72,7 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### line-annotated-events ✅ **Description:** A line plot with annotations marking significant events or milestones along the time series. -### line-interactive 📋 +### line-interactive ✅ **Description:** Line plot with hover tooltips and zoom capability. ### line-loss-training ✅ @@ -81,6 +81,9 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### line-timeseries-rolling ✅ **Description:** Time series plot with rolling average overlay for trend smoothing. +### line-animated-progressive ✅ +**Description:** Animated line plot that progressively draws over time. + --- ## 3. Bar Charts @@ -115,7 +118,7 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### lollipop-basic ✅ **Description:** A lollipop chart displays categorical data with thin lines (stems) extending from a baseline to circular markers (dots) at each data point. -### bar-interactive 📋 +### bar-interactive ✅ **Description:** Bar chart with hover details and click interactions. ### bar-feature-importance ✅ @@ -128,9 +131,6 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### histogram-basic ✅ **Description:** A histogram displays the distribution of a single continuous variable by dividing the data range into bins and showing the frequency of observations in each bin. -### histogram-normalized ✅ -**Description:** Histogram normalized to show density instead of count. - ### histogram-overlapping ✅ **Description:** Multiple overlapping histograms for comparison. @@ -293,9 +293,6 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### regression-linear 📋 **Description:** Scatter with linear regression fit and confidence band. -### regression-polynomial ✅ -**Description:** Non-linear regression curve fit. - ### regression-lowess 📋 **Description:** Locally weighted regression smoothing. @@ -305,18 +302,12 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### qq-basic ✅ **Description:** A Q-Q (Quantile-Quantile) plot compares the distribution of a dataset against a theoretical distribution. Points along a diagonal reference line indicate perfect distribution match. -### bland-altman ✅ -**Description:** Agreement plot between two measurements with limits of agreement. - ### bland-altman-basic ✅ **Description:** Bland-Altman agreement plot comparing two measurement methods with mean difference and limits of agreement. ### errorbar-basic ✅ **Description:** An error bar plot displays data points with associated uncertainty or variability represented by bars extending above and below each point. -### error-asymmetric ✅ -**Description:** Error bars with different upper/lower bounds. - ### errorbar-asymmetric ✅ **Description:** Asymmetric error bars plot with different upper and lower error values for each data point. @@ -368,17 +359,14 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### timeseries-decomposition ✅ **Description:** A time series decomposition plot showing the original series broken down into trend, seasonal, and residual components. -### timeseries-rolling ✅ -**Description:** Time series with rolling average overlay. - ### candlestick-basic ✅ **Description:** A candlestick chart displays open, high, low, and close (OHLC) price data for financial instruments over time. ### timeseries-ohlc 📋 **Description:** Open-high-low-close bar chart. -### timeseries-forecast 📋 -**Description:** Historical data with forecast and uncertainty. +### timeseries-forecast-uncertainty ✅ +**Description:** Time series plot with forecast line and uncertainty/confidence band. ### sparkline-basic ✅ **Description:** A sparkline is a small, condensed line chart designed to be embedded inline with text or in dashboard cells. Pure data visualization in minimal space. @@ -415,14 +403,14 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### wireframe-3d-basic ✅ **Description:** A 3D wireframe plot displays a mathematical surface as a mesh of lines connecting grid points, creating a see-through visualization. -### contour-3d 📋 +### contour-3d ✅ **Description:** 3D contour plot. ### bar-3d ✅ **Description:** 3D bar chart. -### line-3d 📋 -**Description:** 3D line plot or trajectory. +### line-3d-trajectory ✅ +**Description:** 3D line plot or trajectory visualization in three-dimensional space. --- @@ -447,7 +435,7 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### network-basic ✅ **Description:** A network graph (node-link diagram) visualizes relationships between entities as nodes connected by edges. -### network-directed 📋 +### network-directed ✅ **Description:** Directed graph with arrows. ### network-weighted 📋 @@ -487,9 +475,6 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### icicle-basic ✅ **Description:** Rectangular hierarchy visualization with stacked rectangles. -### circle-packing ✅ -**Description:** Nested circles showing hierarchy. - ### circlepacking-basic ✅ **Description:** Circle packing chart displaying hierarchical data as nested circles. @@ -516,9 +501,6 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ## 20. Animation & Interactive -### animation-line 📋 -**Description:** Animated line plot building over time. - ### scatter-animated-controls ✅ **Description:** An animated scatter plot with play/pause controls, showing data evolution over time with smooth transitions. @@ -575,9 +557,6 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### wordcloud-basic ✅ **Description:** A word cloud displays text data where word size represents frequency or importance. -### annotated-scatter ✅ -**Description:** Scatter plot with text labels on points. - ### annotated-line 📋 **Description:** Line plot with annotations at key points. @@ -588,9 +567,6 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### parallel-basic ✅ **Description:** A parallel coordinates plot visualizes multivariate data by representing each variable as a vertical axis and each observation as a line connecting values across all axes. -### parallel-categories ✅ -**Description:** Parallel coordinates for categorical data. - ### parallel-categories-basic ✅ **Description:** Basic parallel categories plot for visualizing flows between categorical variables. @@ -619,13 +595,13 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### stock-volume 📋 **Description:** Stock price with volume bars in synchronized panes. -### indicator-macd 📋 +### indicator-macd ✅ **Description:** MACD technical indicator chart. -### indicator-rsi 📋 +### indicator-rsi ✅ **Description:** Relative Strength Index indicator. -### indicator-bollinger 📋 +### indicator-bollinger ✅ **Description:** Bollinger Bands overlay on price chart. ### indicator-sma 📋 @@ -749,15 +725,9 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### precision-recall ✅ **Description:** Precision-Recall curve for evaluating classification models, especially useful for imbalanced datasets. -### learning-curve ✅ -**Description:** Learning curve showing model performance (training and validation scores) vs training set size for bias-variance diagnosis. - ### learning-curve-basic ✅ **Description:** Model learning curve showing training and validation performance across different training set sizes. -### feature-importance ✅ -**Description:** Horizontal bar chart showing feature importances from machine learning models, sorted by importance value. - ### calibration-curve ✅ **Description:** Calibration curve (reliability diagram) visualizing how well predicted probabilities match actual outcomes for probability calibration. @@ -767,12 +737,9 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### gain-curve ✅ **Description:** Cumulative gains chart for evaluating classification model effectiveness. -### shap-summary 📋 +### shap-summary ✅ **Description:** SHAP (SHapley Additive exPlanations) summary plot showing feature impact on model predictions. -### partial-dependence ✅ -**Description:** Partial dependence plot showing marginal effect of features on predicted outcome. - ### pdp-basic ✅ **Description:** Partial dependence plot showing the marginal effect of a feature on model predictions. @@ -788,9 +755,6 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### residual-plot ✅ **Description:** Residual plot displaying difference between observed and predicted values for regression model diagnostics. -### decision-boundary ✅ -**Description:** Decision boundary visualization showing classifier regions in 2D feature space. - ### contour-decision-boundary ✅ **Description:** Decision boundary classifier visualization using contour plot to show classification regions. @@ -801,15 +765,9 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ## 29. Scientific & Domain-Specific -### spectrum-plot ✅ -**Description:** Frequency spectrum visualization. - ### spectrum-basic ✅ **Description:** Frequency spectrum plot showing signal power or amplitude across frequencies. -### spectrogram ✅ -**Description:** Time-frequency heatmap for audio/signals. - ### spectrogram-basic ✅ **Description:** Spectrogram time-frequency heatmap showing signal intensity over time and frequency. @@ -819,7 +777,7 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### quiver-basic ✅ **Description:** A quiver plot displays vector fields using arrows positioned at grid points. Each arrow represents a vector at that location, with direction indicating the vector's angle and length proportional to its magnitude. -### streamline-basic 📋 +### streamline-basic ✅ **Description:** Streamlines of a vector field as smooth curves. ### stem-basic ✅ @@ -834,24 +792,15 @@ A comprehensive catalog of plot types for the pyplots platform. Each plot is imp ### skewt-basic 📋 **Description:** A Skew-T Log-P diagram displays atmospheric thermodynamic profiles with logarithmic pressure axis and 45-degree skewed temperature isotherms. -### survival-curve ✅ -**Description:** Kaplan-Meier survival analysis plot. - ### survival-kaplan-meier ✅ **Description:** Kaplan-Meier survival plot showing probability of survival over time with censored data. ### forest-basic ✅ **Description:** Meta-analysis effect sizes with confidence intervals. -### volcano-plot ✅ -**Description:** Statistical significance vs fold change. - ### volcano-basic ✅ **Description:** Volcano plot for statistical significance showing -log10(p-value) vs fold change. -### manhattan-plot ✅ -**Description:** Genome-wide association study visualization. - ### manhattan-gwas ✅ **Description:** Manhattan plot for genome-wide association studies showing chromosomal positions vs -log10(p-values). @@ -881,8 +830,8 @@ Printable templates and playful visualizations. ### sudoku-filled 📋 **Description:** Sudoku-Rätsel mit vorgegebenen Zahlen und eindeutiger Lösung. Vorgegebene Zahlen optisch hervorgehoben. -### maze-basic 📋 -**Description:** Rechteckiges Labyrinth mit Start und Ziel. Algorithmisch generiert mit genau einem Lösungsweg. Schwarz-weiß zum Ausdrucken. +### maze-printable ✅ +**Description:** Rectangular maze puzzle with start and goal, algorithmically generated with exactly one solution path. ### maze-circular 📋 **Description:** Rundes Labyrinth aus konzentrischen Ringen. Eingang außen, Ziel im Zentrum. @@ -895,8 +844,8 @@ Printable templates and playful visualizations. ### Codes & Identification -### qr-code 📋 -**Description:** QR-Code generiert aus Text oder URL. Quadratisches Muster mit Positionsmarkierungen, scanbar mit Smartphone. +### qrcode-basic ✅ +**Description:** QR code generated from text or URL, scannable with smartphone. ### barcode-ean 📋 **Description:** EAN-13 Barcode (europäischer Produktcode). Vertikale Striche mit 13 Ziffern darunter, scanbar im Einzelhandel. @@ -911,9 +860,9 @@ Printable templates and playful visualizations. ## Statistics -- **Total Plot Types:** 245+ -- **Implemented:** 191 ✅ -- **Planned:** 54+ 📋 +- **Total Plot Types:** 242 +- **Implemented:** 181 ✅ +- **Planned:** 61 📋 - **Categories:** 30 --- diff --git a/docs/workflows/overview.md b/docs/workflows/overview.md index 517c78b9ed..0fa6e86bd1 100644 --- a/docs/workflows/overview.md +++ b/docs/workflows/overview.md @@ -28,7 +28,26 @@ spec-create.yml (merge job) |-- Triggers sync-postgres.yml ``` -### 2. Implementation Pipeline +### 2. Report Pipeline + +See [Report Issues](report-issue.md) for details. + +``` +User reports issue (from pyplots.ai or GitHub) + | + v (report-pending label auto-added) + | +report-validate.yml + |-- Validates spec/impl exists + |-- AI analyzes the issue + |-- Posts structured analysis comment + |-- Updates labels: report-validated + category:* + | + v +Ready for maintainer review +``` + +### 3. Implementation Pipeline ``` Issue + [generate:{library}] label OR workflow_dispatch @@ -98,6 +117,20 @@ impl-review.yml | `approved` | Human approved specification | Maintainer | | `rejected` | Human rejected | Maintainer | +### Report Labels (on Issues) + +| Label | Meaning | Set By | +|-------|---------|--------| +| `report-pending` | Report submitted, awaiting validation | Auto (template) | +| `report-validated` | AI validated, ready for review | Workflow | +| `report:spec` | Issue with specification | Workflow | +| `report:impl` | Issue with implementation | Workflow | +| `report:impl:{library}` | Specific library affected | Workflow | +| `category:visual` | Design/visual issues | Workflow | +| `category:data` | Data quality issues | Workflow | +| `category:functional` | Non-functional elements | Workflow | +| `category:other` | Other issues | Workflow | + --- ## Quality Workflow @@ -134,6 +167,7 @@ Located in `.github/workflows/`: | `impl-merge.yml` | Merges approved PRs | | `bulk-generate.yml` | Batch implementation generation | | `sync-postgres.yml` | Syncs plots/ to database | +| `report-validate.yml` | Validates user-submitted issue reports | --- diff --git a/docs/workflows/report-issue.md b/docs/workflows/report-issue.md new file mode 100644 index 0000000000..6df4fe62a2 --- /dev/null +++ b/docs/workflows/report-issue.md @@ -0,0 +1,118 @@ +# Report Issues + +Report issues with existing plot specifications or implementations. + +## Overview + +Found a problem with an existing plot? The report system helps you: +1. Submit structured issue reports +2. Get AI-powered analysis and validation +3. Queue issues for maintainer review and fix + +Reports are validated by AI and structured for efficient review. + +--- + +## How to Report + +### From pyplots.ai (Recommended) + +1. Navigate to the plot page (e.g., `pyplots.ai/scatter-basic`) +2. Click **"report issue"** in the breadcrumb bar (top right) +3. Complete the form on GitHub +4. Wait for AI validation + +**Spec issues:** Report from the overview page (e.g., `/scatter-basic`) +**Impl issues:** Report from the detail page (e.g., `/scatter-basic/matplotlib`) + +The form will be pre-filled with the spec ID and library based on your current page. + +### From GitHub + +1. Go to [New Issue](https://github.com/MarkusNeusinger/pyplots/issues/new/choose) +2. Select **"Report Issue"** template +3. Fill in the spec ID, target, library, category, and description +4. Submit + +--- + +## Issue Categories + +| Category | Description | Examples | +|----------|-------------|----------| +| **Visual** | Design/display issues | Overlapping labels, ugly colors, hard to read | +| **Data** | Data quality issues | Unrealistic values, inappropriate context | +| **Functional** | Doesn't work as expected | QR code not scannable, broken interactivity | +| **Other** | Other issues | Unclear spec, missing features | + +--- + +## Labels + +### Report Type + +| Label | Purpose | +|-------|---------| +| `report:spec` | Issue with the specification (affects all libraries) | +| `report:impl` | Issue with a specific implementation | +| `report:impl:{library}` | Specific library affected (e.g., `report:impl:matplotlib`) | + +### Categories + +| Label | Purpose | +|-------|---------| +| `category:visual` | Design/visual issues | +| `category:data` | Data quality issues | +| `category:functional` | Non-functional elements | +| `category:other` | Other issues | + +### Status + +| Label | Purpose | +|-------|---------| +| `report-pending` | Report submitted, awaiting AI validation | +| `report-validated` | AI validated, ready for maintainer review | +| `approved` | Maintainer approved, ready for fix (future) | + +--- + +## Workflow + +``` +User submits report + │ + ▼ (report-pending label auto-added) + │ +report-validate.yml runs: + ├── Validates spec/impl exists + ├── Reads specification and metadata + ├── AI analyzes the issue + ├── Posts structured analysis comment + └── Updates labels (report-validated + category + target) + │ + ▼ +Issue ready for maintainer review + │ + ▼ +Maintainer adds "approved" label + │ + ▼ +(Fix workflow - future implementation) +``` + +--- + +## Tips for Good Reports + +1. **Be specific:** Describe exactly what's wrong +2. **Include context:** What did you expect vs. what happened? +3. **Use screenshots:** Especially for visual issues +4. **Check the spec:** Make sure the spec ID is correct +5. **One issue per report:** Don't combine multiple issues + +--- + +## Related + +- [Workflow Overview](overview.md) +- [Contributing](../contributing.md) diff --git a/prompts/workflow-prompts/report-analysis.md b/prompts/workflow-prompts/report-analysis.md new file mode 100644 index 0000000000..b2b768ea42 --- /dev/null +++ b/prompts/workflow-prompts/report-analysis.md @@ -0,0 +1,107 @@ +# Report Analysis Prompt + +Analyzes user-submitted issue reports and provides structured feedback. + +## Task + +Validate and structure a user-submitted issue report for an existing plot specification or implementation. + +## Input + +From the issue body, extract: +- **spec_id**: The specification ID (e.g., `scatter-basic`, `qrcode-basic`) +- **target**: "Specification" or "Implementation" +- **library**: The library name (if implementation issue) +- **category**: Visual, Data, Functional, or Other +- **description**: User's description of the issue + +## Input Validation (Security) + +**CRITICAL:** Before using any user-supplied values in commands, validate them: + +1. **spec_id** must match pattern `^[a-z0-9-]+$` (lowercase letters, numbers, hyphens only) +2. **library** must be one of: `matplotlib`, `seaborn`, `plotly`, `bokeh`, `altair`, `plotnine`, `pygal`, `highcharts`, `letsplot` + +If validation fails → post comment explaining invalid input, close issue, STOP. + +## Validation Steps + +1. **Validate spec_id format:** + - Must match `^[a-z0-9-]+$` + - If invalid → post comment, close issue, STOP + +2. **Verify spec exists:** + - Check if directory `plots/{spec_id}/` exists + - If not found → post comment, close issue, STOP + +3. **If implementation issue, verify library exists:** + - Check if file `plots/{spec_id}/implementations/{library}.py` exists + - If not found → post comment, close issue, STOP + +4. **Read relevant files:** + - `plots/{spec_id}/specification.md` + - `plots/{spec_id}/metadata/{library}.yaml` (if impl) + +5. **Analyze the issue:** + - Is this a legitimate issue or misunderstanding? + - Does the described problem match what's in the spec/metadata? + - What might be the root cause? + +## Output Format + +Post a comment with this structure: + +```markdown +## Report Analysis + +**Specification:** `{spec_id}` +**Target:** {Specification / Implementation ({library})} +**Category:** {Visual / Data / Functional / Other} + +### Problem Summary +{AI-structured version of the user's description - clear, concise, 2-3 sentences} + +### Analysis +{Assessment of the issue: +- Is this a valid issue? +- What might be causing it? +- Brief technical insight if applicable} + +### Recommended Action +- **Spec update needed:** {Yes/No} - {brief reason} +- **Regeneration needed:** {Yes/No} - {which libraries if yes} + +--- +**Next:** Add `approved` label when ready to fix. +``` + +## Label Updates + +After posting the comment, update labels: + +1. **Remove:** `report-pending` +2. **Add:** `report-validated` +3. **Add target label:** + - For spec issues: `report:spec` + - For impl issues: `report:impl` AND `report:impl:{library}` +4. **Add category label:** + - Visual → `category:visual` + - Data → `category:data` + - Functional → `category:functional` + - Other → `category:other` + +## Title Update + +Update the issue title to format: `[{spec_id}] {brief description}` + +Example: `[qrcode-basic] QR code not scannable` + +Keep the description under 60 characters. Only use the validated spec_id. + +## Important Notes + +- Do NOT add the `approved` label +- Do NOT trigger any fix workflows +- Keep analysis concise but informative +- Be objective - some reports may be user misunderstandings +- If the issue is unclear, ask for clarification instead of closing