@caddis/cli 0.0.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/word-cloud/references/python.md

@@ -0,0 +1,249 @@
+# Python / Streamlit Word Cloud — Implementation Reference
+
+Two approaches:
+1. **Server-side PNG** — Python `wordcloud` lib, matplotlib, Pillow
+2. **Embedded HTML** — render the HTML template (references/html.md) inside `st.components.v1.html()`
+
+Use approach 2 for full interactivity, animations, and theming. Use approach 1 for static image export or simpler use cases.
+
+---
+
+## Approach 1: Server-side PNG (wordcloud lib)
+
+### Install
+```bash
+pip install wordcloud matplotlib pillow nltk numpy
+```
+
+### Full Example
+```python
+import streamlit as st
+from wordcloud import WordCloud, STOPWORDS
+import matplotlib.pyplot as plt
+from PIL import Image
+import numpy as np
+import re
+from collections import Counter
+
+# ── Optional: Sentiment coloring ──
+try:
+    from nltk.sentiment import SentimentIntensityAnalyzer
+    import nltk
+    nltk.download('vader_lexicon', quiet=True)
+    sia = SentimentIntensityAnalyzer()
+    HAS_SENTIMENT = True
+except Exception:
+    HAS_SENTIMENT = False
+
+POSITIVE_COLOR = '#4ade80'
+NEGATIVE_COLOR = '#f87171'
+VERB_COLOR     = '#c4b5fd'
+NOUN_COLOR     = '#7dd3fc'
+NEUTRAL_COLOR  = '#94a3b8'
+
+def compute_word_frequencies(text: str, max_words: int = 120) -> dict[str, int]:
+    stops = STOPWORDS | {'the','a','an','and','or','but','in','on','at','to','for','of'}
+    words = re.findall(r"[a-zA-Z']{3,}", text.lower())
+    counts = Counter(w for w in words if w not in stops)
+    return dict(counts.most_common(max_words))
+
+def sentiment_color_func(word, font_size, position, orientation, random_state=None, **kwargs):
+    """Color words by sentiment."""
+    if not HAS_SENTIMENT:
+        return NOUN_COLOR
+    score = sia.polarity_scores(word)['compound']
+    if score >= 0.3:  return POSITIVE_COLOR
+    if score <= -0.3: return NEGATIVE_COLOR
+    return NEUTRAL_COLOR
+
+def create_wordcloud_image(
+    text: str,
+    width: int = 900,
+    height: int = 520,
+    max_words: int = 120,
+    background_color: str = '#0c0a09',
+    font_path: str | None = None,
+    mask_path: str | None = None,
+    use_sentiment_colors: bool = True,
+) -> plt.Figure:
+    freqs = compute_word_frequencies(text, max_words)
+
+    mask = None
+    if mask_path:
+        mask = np.array(Image.open(mask_path).convert('L'))
+        mask = np.where(mask > 128, 255, 0).astype(np.uint8)
+
+    wc = WordCloud(
+        width=width,
+        height=height,
+        max_words=max_words,
+        background_color=background_color,
+        colormap=None if use_sentiment_colors else 'cool',
+        color_func=sentiment_color_func if use_sentiment_colors else None,
+        font_path=font_path,
+        mask=mask,
+        mode='RGBA' if mask is not None else 'RGB',
+        prefer_horizontal=0.7,
+        relative_scaling=0.55,
+        min_font_size=10,
+        max_font_size=None,
+        collocations=False,
+    ).generate_from_frequencies(freqs)
+
+    fig, ax = plt.subplots(figsize=(width / 100, height / 100), dpi=100)
+    ax.imshow(wc, interpolation='bilinear')
+    ax.axis('off')
+    fig.patch.set_facecolor(background_color)
+    plt.tight_layout(pad=0)
+    return fig
+
+# ── Streamlit App ──
+st.set_page_config(page_title='Word Cloud', layout='wide')
+st.markdown("""
+<style>
+  .stApp { background: #0c0a09; }
+  h1 { color: #7dd3fc !important; font-family: serif; }
+</style>
+""", unsafe_allow_html=True)
+
+st.title('✦ Word Cloud Generator')
+
+col1, col2 = st.columns([3, 1])
+with col2:
+    max_words = st.slider('Max words', 30, 200, 100)
+    theme = st.radio('Theme', ['Dark', 'Light'])
+    use_sentiment = st.checkbox('Sentiment colors', value=True)
+
+with col1:
+    source = st.radio('Input source', ['Text input', 'Upload file'], horizontal=True)
+
+    text = ''
+    if source == 'Text input':
+        text = st.text_area('Paste your text here', height=200)
+    else:
+        f = st.file_uploader('Upload PDF, DOCX, XLSX, PPTX, TXT...', 
+                              type=['pdf','docx','xlsx','pptx','txt','csv'])
+        if f:
+            text = extract_text_from_file(f)  # see extraction section below
+            st.success(f'Extracted {len(text):,} characters')
+
+    if text.strip():
+        bg = '#0c0a09' if theme == 'Dark' else '#fafaf9'
+        fig = create_wordcloud_image(
+            text, max_words=max_words,
+            background_color=bg,
+            use_sentiment_colors=use_sentiment,
+        )
+        st.pyplot(fig, use_container_width=True)
+        
+        # Download button
+        import io
+        buf = io.BytesIO()
+        fig.savefig(buf, format='png', dpi=150, bbox_inches='tight', facecolor=bg)
+        st.download_button('Download PNG', buf.getvalue(), 'wordcloud.png', 'image/png')
+```
+
+---
+
+## Approach 2: Interactive HTML Component in Streamlit
+
+Embed the full interactive HTML word cloud inside Streamlit:
+
+```python
+import streamlit.components.v1 as components
+
+def render_interactive_cloud(word_data: list[dict], theme: str = 'dark'):
+    """
+    word_data: [{'word': str, 'count': int, 'category': str}, ...]
+    """
+    js_data = str([[d['word'], d['count'], d['category']] for d in word_data])
+    
+    html_content = f"""
+    <!DOCTYPE html>
+    <html data-theme="{theme}">
+    <!-- Insert full template from references/html.md here -->
+    <!-- Replace WORD_DATA = [...] with: -->
+    <script>
+    const WORD_DATA = {js_data};
+    </script>
+    <!-- rest of template... -->
+    </html>
+    """
+    
+    components.html(html_content, height=600, scrolling=False)
+```
+
+---
+
+## File Extraction Utilities
+
+```python
+def extract_text_from_file(uploaded_file) -> str:
+    """Extract text from any uploaded file type."""
+    import io
+    name = uploaded_file.name.lower()
+    data = uploaded_file.read()
+    
+    if name.endswith('.txt') or name.endswith('.csv'):
+        return data.decode('utf-8', errors='replace')
+    
+    elif name.endswith('.pdf'):
+        import pdfplumber
+        text = []
+        with pdfplumber.open(io.BytesIO(data)) as pdf:
+            for page in pdf.pages:
+                t = page.extract_text()
+                if t: text.append(t)
+        return '\n'.join(text)
+    
+    elif name.endswith('.docx'):
+        from docx import Document
+        doc = Document(io.BytesIO(data))
+        return '\n'.join(p.text for p in doc.paragraphs if p.text.strip())
+    
+    elif name.endswith('.xlsx') or name.endswith('.xls'):
+        import openpyxl
+        wb = openpyxl.load_workbook(io.BytesIO(data), read_only=True, data_only=True)
+        text = []
+        for ws in wb.worksheets:
+            for row in ws.iter_rows(values_only=True):
+                text.extend(str(c) for c in row if c is not None)
+        return ' '.join(text)
+    
+    elif name.endswith('.pptx'):
+        from pptx import Presentation
+        prs = Presentation(io.BytesIO(data))
+        text = []
+        for slide in prs.slides:
+            for shape in slide.shapes:
+                if hasattr(shape, 'text'):
+                    text.append(shape.text)
+        return '\n'.join(text)
+    
+    elif name.endswith('.html') or name.endswith('.htm'):
+        from html.parser import HTMLParser
+        class P(HTMLParser):
+            def __init__(self): super().__init__(); self.parts = []
+            def handle_data(self, d): self.parts.append(d)
+        p = P(); p.feed(data.decode('utf-8', errors='replace'))
+        return ' '.join(p.parts)
+    
+    return ''
+```
+
+---
+
+## Install Requirements (requirements.txt)
+
+```
+streamlit>=1.32
+wordcloud>=1.9
+matplotlib>=3.8
+Pillow>=10.0
+pdfplumber>=0.10
+python-docx>=1.1
+openpyxl>=3.1
+python-pptx>=0.6
+nltk>=3.8
+numpy>=1.26
+```

package/bundles/antigravity-plugin-extras/skills/word-cloud/references/react.md

@@ -0,0 +1,427 @@
+# React Word Cloud — Implementation Reference
+
+## Dependencies
+
+```bash
+npm install d3-cloud d3 compromise sentiment
+# or with yarn:
+yarn add d3-cloud d3 compromise sentiment
+```
+
+For font loading (optional but recommended):
+```html
+<!-- In index.html or _document.tsx -->
+<link href="https://fonts.googleapis.com/css2?family=Syne:wght@400;700;800&family=DM+Serif+Display&display=swap" rel="stylesheet">
+```
+
+---
+
+## Core Component: `WordCloud.tsx`
+
+```tsx
+'use client'; // Next.js: client-only
+import React, { useEffect, useRef, useState, useCallback } from 'react';
+import cloud from 'd3-cloud';
+import * as d3 from 'd3';
+
+interface WordData {
+  text: string;
+  value: number;           // raw frequency
+  category?: 'positive' | 'negative' | 'verb' | 'noun' | 'neutral';
+  size?: number;           // computed by d3-cloud
+  x?: number;
+  y?: number;
+  rotate?: number;
+}
+
+interface WordCloudProps {
+  words: WordData[];
+  width?: number;
+  height?: number;
+  fontFamily?: string;
+  theme?: 'light' | 'dark' | 'auto';
+  palette?: string;
+  animation?: 'none' | 'entrance' | 'float' | 'cinematic';
+  shape?: 'circle' | 'star' | 'speech_bubble' | 'none';
+  maxWords?: number;
+  onWordClick?: (word: WordData) => void;
+}
+
+const CATEGORY_COLORS: Record<string, string> = {
+  positive: 'var(--cloud-positive)',
+  negative: 'var(--cloud-negative)',
+  verb:     'var(--cloud-verb)',
+  noun:     'var(--cloud-noun)',
+  neutral:  'var(--cloud-neutral)',
+};
+
+export const WordCloud: React.FC<WordCloudProps> = ({
+  words,
+  width = 800,
+  height = 500,
+  fontFamily = 'Syne, sans-serif',
+  theme = 'auto',
+  palette = 'obsidian',
+  animation = 'entrance',
+  maxWords = 100,
+  onWordClick,
+}) => {
+  const svgRef = useRef<SVGSVGElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [layoutWords, setLayoutWords] = useState<WordData[]>([]);
+  const [tooltip, setTooltip] = useState<{ word: WordData; x: number; y: number } | null>(null);
+  const [dims, setDims] = useState({ width, height });
+
+  // Responsive resize
+  useEffect(() => {
+    if (!containerRef.current) return;
+    const ro = new ResizeObserver(([entry]) => {
+      const w = entry.contentRect.width;
+      setDims({ width: w, height: Math.round(w * (height / width)) });
+    });
+    ro.observe(containerRef.current);
+    return () => ro.disconnect();
+  }, [width, height]);
+
+  // D3-cloud layout
+  useEffect(() => {
+    const top = words
+      .sort((a, b) => b.value - a.value)
+      .slice(0, maxWords);
+
+    const maxVal = Math.max(...top.map(w => w.value));
+    const minVal = Math.min(...top.map(w => w.value));
+    const sizeScale = d3.scalePow()
+      .exponent(0.6)
+      .domain([minVal, maxVal])
+      .range([12, Math.min(dims.width, dims.height) / 5]);
+
+    cloud<WordData>()
+      .size([dims.width, dims.height])
+      .words(top.map(w => ({ ...w, size: sizeScale(w.value) })))
+      .padding(5)
+      .rotate(() => {
+        const r = Math.random();
+        if (r < 0.6) return 0;
+        if (r < 0.8) return 90;
+        return Math.round((Math.random() - 0.5) * 30);
+      })
+      .font(fontFamily)
+      .fontSize(d => d.size ?? 12)
+      .on('end', (computed) => setLayoutWords(computed as WordData[]))
+      .start();
+  }, [words, dims, fontFamily, maxWords]);
+
+  const getColor = (w: WordData) =>
+    w.category ? CATEGORY_COLORS[w.category] : 'var(--cloud-noun)';
+
+  const getAnimStyle = (i: number): React.CSSProperties => {
+    if (animation === 'none') return {};
+    if (animation === 'entrance' || animation === 'cinematic') {
+      return {
+        animation: `wordEntrance 0.6s ease-out both`,
+        animationDelay: `${i * 30}ms`,
+        '--r': `${layoutWords[i]?.rotate ?? 0}deg`,
+      } as React.CSSProperties;
+    }
+    if (animation === 'float') {
+      return {
+        animation: `wordFloat ${3 + (i % 5) * 0.4}s ease-in-out infinite`,
+        animationDelay: `${(i * 137) % 2000}ms`,
+        '--r': `${layoutWords[i]?.rotate ?? 0}deg`,
+      } as React.CSSProperties;
+    }
+    return {};
+  };
+
+  return (
+    <div
+      ref={containerRef}
+      data-theme={theme}
+      className={`word-cloud-wrapper ${palette}`}
+      style={{ width: '100%', position: 'relative' }}
+    >
+      <style>{CLOUD_STYLES}</style>
+
+      {/* Accessible fallback */}
+      <ul className="sr-only" aria-label="Word cloud words">
+        {layoutWords.map(w => (
+          <li key={w.text}>{w.text} ({w.value})</li>
+        ))}
+      </ul>
+
+      <svg
+        ref={svgRef}
+        viewBox={`0 0 ${dims.width} ${dims.height}`}
+        aria-label="Word cloud visualization"
+        role="img"
+        style={{ width: '100%', height: 'auto', display: 'block' }}
+      >
+        {/* Background */}
+        <rect width={dims.width} height={dims.height} fill="var(--cloud-bg)" rx={16} />
+        <radialGradient id="bgGlow" cx="50%" cy="50%" r="60%">
+          <stop offset="0%" stopColor="var(--cloud-glow)" stopOpacity="0.15" />
+          <stop offset="100%" stopColor="transparent" stopOpacity="0" />
+        </radialGradient>
+        <rect width={dims.width} height={dims.height} fill="url(#bgGlow)" rx={16} />
+
+        <g transform={`translate(${dims.width / 2},${dims.height / 2})`}>
+          {layoutWords.map((w, i) => (
+            <text
+              key={w.text}
+              className="cloud-word"
+              style={{
+                ...getAnimStyle(i),
+                fontSize: w.size,
+                fontFamily,
+                fontWeight: (w.size ?? 12) > 40 ? 800 : (w.size ?? 12) > 24 ? 700 : 400,
+                fill: getColor(w),
+                cursor: 'pointer',
+                userSelect: 'none',
+              }}
+              textAnchor="middle"
+              transform={`translate(${w.x},${w.y}) rotate(${w.rotate})`}
+              onClick={() => onWordClick?.(w)}
+              onMouseEnter={(e) => {
+                const rect = (e.target as SVGTextElement).getBoundingClientRect();
+                setTooltip({ word: w, x: rect.left + rect.width / 2, y: rect.top - 8 });
+              }}
+              onMouseLeave={() => setTooltip(null)}
+            >
+              {w.text}
+            </text>
+          ))}
+        </g>
+      </svg>
+
+      {/* Tooltip */}
+      {tooltip && (
+        <div
+          className="cloud-tooltip"
+          style={{ left: tooltip.x, top: tooltip.y }}
+        >
+          <span className="tooltip-word">{tooltip.word.text}</span>
+          <span className="tooltip-count">{tooltip.word.value}×</span>
+          {tooltip.word.category && (
+            <span className={`tooltip-cat ${tooltip.word.category}`}>
+              {tooltip.word.category}
+            </span>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+---
+
+## CSS (inject as string or in your .css file)
+
+```css
+const CLOUD_STYLES = `
+  /* ── Themes ── */
+  .word-cloud-wrapper {
+    --cloud-bg:       #fafaf9;
+    --cloud-noun:     #1c6499;
+    --cloud-positive: #16a34a;
+    --cloud-negative: #dc2626;
+    --cloud-verb:     #7c3aed;
+    --cloud-neutral:  #a8a29e;
+    --cloud-glow:     #7c3aed;
+  }
+  .word-cloud-wrapper[data-theme="dark"],
+  .dark .word-cloud-wrapper {
+    --cloud-bg:       #0c0a09;
+    --cloud-noun:     #7dd3fc;
+    --cloud-positive: #4ade80;
+    --cloud-negative: #f87171;
+    --cloud-verb:     #c4b5fd;
+    --cloud-neutral:  #78716c;
+    --cloud-glow:     #a78bfa;
+  }
+  @media (prefers-color-scheme: dark) {
+    .word-cloud-wrapper[data-theme="auto"] {
+      --cloud-bg:       #0c0a09;
+      --cloud-noun:     #7dd3fc;
+      --cloud-positive: #4ade80;
+      --cloud-negative: #f87171;
+      --cloud-verb:     #c4b5fd;
+      --cloud-neutral:  #78716c;
+      --cloud-glow:     #a78bfa;
+    }
+  }
+
+  /* ── Palette overrides ── */
+  .word-cloud-wrapper.aurora {
+    --cloud-bg: #050510;
+    --cloud-noun: #38bdf8;
+    --cloud-verb: #e879f9;
+    --cloud-positive: #34d399;
+    --cloud-negative: #fb923c;
+    --cloud-glow: #818cf8;
+  }
+  .word-cloud-wrapper.parchment {
+    --cloud-bg: #f5f0e8;
+    --cloud-noun: #92400e;
+    --cloud-verb: #9a3412;
+    --cloud-positive: #365314;
+    --cloud-negative: #7f1d1d;
+    --cloud-glow: #b45309;
+  }
+
+  /* ── Word interactions ── */
+  .cloud-word {
+    transition: opacity 0.2s, filter 0.2s, transform 0.2s;
+  }
+  .cloud-word:hover {
+    filter: brightness(1.3) drop-shadow(0 0 8px currentColor);
+    transform-origin: center;
+  }
+
+  /* ── Animations ── */
+  @keyframes wordEntrance {
+    from { opacity: 0; transform: scale(0.3) rotate(var(--r, 0deg)); }
+    to   { opacity: 1; transform: scale(1)   rotate(var(--r, 0deg)); }
+  }
+  @keyframes wordFloat {
+    0%, 100% { transform: translateY(0)    rotate(var(--r, 0deg)); }
+    50%       { transform: translateY(-5px) rotate(var(--r, 0deg)); }
+  }
+
+  /* ── Tooltip ── */
+  .cloud-tooltip {
+    position: fixed;
+    transform: translate(-50%, -100%);
+    background: var(--cloud-bg);
+    border: 1px solid var(--cloud-noun);
+    border-radius: 8px;
+    padding: 6px 12px;
+    font-family: inherit;
+    font-size: 13px;
+    display: flex;
+    gap: 8px;
+    align-items: center;
+    pointer-events: none;
+    z-index: 1000;
+    box-shadow: 0 8px 24px rgba(0,0,0,0.2);
+  }
+  .tooltip-word { font-weight: 700; }
+  .tooltip-count { opacity: 0.6; }
+  .tooltip-cat { font-size: 11px; padding: 2px 6px; border-radius: 4px; background: var(--cloud-noun); color: #fff; }
+  .tooltip-cat.positive { background: var(--cloud-positive); }
+  .tooltip-cat.negative { background: var(--cloud-negative); }
+  .tooltip-cat.verb     { background: var(--cloud-verb); }
+
+  /* ── Accessibility ── */
+  .sr-only {
+    position: absolute; width: 1px; height: 1px;
+    padding: 0; margin: -1px; overflow: hidden;
+    clip: rect(0,0,0,0); border: 0;
+  }
+`;
+```
+
+---
+
+## Word Frequency Utility
+
+```ts
+// utils/wordFrequency.ts
+const DEFAULT_STOPWORDS = new Set([
+  'the','a','an','and','or','but','in','on','at','to','for','of','with',
+  'is','are','was','were','be','been','have','has','had','do','does','did',
+  'will','would','could','should','may','might','shall','this','that','these',
+  'those','it','its','i','we','you','he','she','they','my','your','our',
+  'their','what','which','who','when','where','how','all','each','both',
+  'more','also','just','not','no','so','if','as','by','from','up','about',
+  'into','through','then','than','very','even','any','one','two','three',
+]);
+
+export function computeFrequencies(
+  text: string,
+  customStopwords: string[] = [],
+  minLength = 3
+): Array<{ text: string; value: number }> {
+  const stops = new Set([...DEFAULT_STOPWORDS, ...customStopwords.map(w => w.toLowerCase())]);
+  const counts: Record<string, number> = {};
+
+  text
+    .toLowerCase()
+    .replace(/[^a-z\s'-]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length >= minLength && !stops.has(w) && !/^\d+$/.test(w))
+    .forEach(w => { counts[w] = (counts[w] ?? 0) + 1; });
+
+  return Object.entries(counts)
+    .map(([text, value]) => ({ text, value }))
+    .sort((a, b) => b.value - a.value);
+}
+```
+
+---
+
+## Shape Masking (D3-cloud)
+
+For non-rectangular shapes, provide a pixel mask:
+
+```ts
+function buildCircleMask(width: number, height: number): boolean[][] {
+  const cx = width / 2, cy = height / 2;
+  const r = Math.min(cx, cy) * 0.92;
+  return Array.from({ length: height }, (_, y) =>
+    Array.from({ length: width }, (_, x) =>
+      (x - cx) ** 2 + (y - cy) ** 2 <= r ** 2
+    )
+  );
+}
+
+// Pass to d3-cloud via custom spiral:
+// d3-cloud doesn't natively support pixel masks but you can approximate
+// by using a bounded region and clipping with SVG clipPath:
+```
+
+```tsx
+// SVG ClipPath approach (simpler, works great):
+<defs>
+  <clipPath id="cloudShape">
+    <circle cx={dims.width/2} cy={dims.height/2} r={Math.min(dims.width, dims.height)/2 - 10} />
+    {/* or use <path d={STAR_PATH} /> from references/shapes.md */}
+  </clipPath>
+</defs>
+<g clipPath="url(#cloudShape)" transform={`translate(${dims.width/2},${dims.height/2})`}>
+  {/* words */}
+</g>
+```
+
+---
+
+## Full Usage Example
+
+```tsx
+import { WordCloud } from './WordCloud';
+import { computeFrequencies } from './utils/wordFrequency';
+import { applySentiment } from './utils/nlp'; // optional
+
+const text = `...extracted text from PDF/DOCX/XLSX...`;
+const freqs = computeFrequencies(text);
+const words = applySentiment(freqs); // adds .category field
+
+export default function MyPage() {
+  return (
+    <div style={{ padding: 32, background: 'var(--cloud-bg)' }}>
+      <WordCloud
+        words={words}
+        width={900}
+        height={550}
+        theme="auto"
+        palette="obsidian"
+        animation="cinematic"
+        fontFamily="Syne, sans-serif"
+        maxWords={120}
+        onWordClick={w => console.log('clicked', w)}
+      />
+    </div>
+  );
+}
+```