scitex 2.14.0__py3-none-any.whl → 2.15.3__py3-none-any.whl

scitex/template/_templates/audio.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/template/_templates/audio.py
+# ----------------------------------------
+
+"""Template for stx.audio text-to-speech module usage."""
+
+TEMPLATE = {
+    "name": "Audio Module",
+    "description": "stx.audio usage for text-to-speech with multiple backends (pyttsx3, gTTS, ElevenLabs)",
+    "filename": "audio_script.py",
+    "priority": 5,
+    "content": '''#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: {timestamp}
+# File: {filepath}
+
+"""
+stx.audio - Text-to-Speech
+==========================
+
+stx.audio provides:
+- Multiple TTS backends (pyttsx3, gTTS, ElevenLabs)
+- Automatic fallback between backends
+- Local and relay playback modes
+- Audio generation and caching
+- Agent identification for multi-agent workflows
+
+Usage Patterns
+--------------
+1. MCP: audio_speak, audio_speak_local, audio_speak_relay
+2. Python API: stx.audio.speak()
+3. Environment: SCITEX_AUDIO_* variables
+
+Backends
+--------
+- pyttsx3: Offline, fast, robotic voice
+- gtts: Google TTS, natural voice, requires internet
+- elevenlabs: Premium quality, requires API key
+"""
+
+import scitex as stx
+
+# ============================================================
+# Pattern 1: Basic TTS (via MCP - Recommended)
+# ============================================================
+
+"""
+MCP Tools for Claude Code:
+--------------------------
+
+# Basic speech (auto-selects backend)
+audio_speak(text="Hello, I completed the task")
+
+# With specific backend
+audio_speak(text="Processing complete", backend="gtts")
+
+# With agent identification
+audio_speak(text="Analysis done", agent_id="analyzer-1")
+
+# Local playback (when MCP server is local)
+audio_speak_local(text="Local notification")
+
+# Relay playback (when MCP server is remote, audio plays on client)
+audio_speak_relay(text="Remote notification")
+
+# List available backends
+audio_list_backends()
+
+# Check audio status
+audio_check_audio_status()
+"""
+
+# ============================================================
+# Pattern 2: Python API Usage
+# ============================================================
+
+def python_api_example():
+    """Direct Python API for TTS."""
+    from scitex.audio import speak, list_backends, check_audio_status
+
+    # Basic speech
+    speak("Hello from SciTeX")
+
+    # With options
+    speak(
+        text="Processing completed successfully",
+        backend="gtts",      # or "pyttsx3", "elevenlabs"
+        speed=1.5,           # Playback speed multiplier
+        wait=True,           # Wait for completion
+        save=False,          # Don't save audio file
+    )
+
+    # With agent identification (for multi-agent workflows)
+    speak(
+        text="Agent Alpha reporting",
+        agent_id="alpha",
+        signature=True       # Add agent signature sound
+    )
+
+    # List available backends
+    backends = list_backends()
+    print(f"Available: {{backends}}")
+
+    # Check audio system status
+    status = check_audio_status()
+    print(f"Audio status: {{status}}")
+
+# ============================================================
+# Pattern 3: Audio Generation (Save to File)
+# ============================================================
+
+def generate_audio_example():
+    """Generate audio files without playing."""
+    from scitex.audio import generate_audio
+
+    # Generate audio file
+    result = generate_audio(
+        text="This is a test message",
+        output_path="notification.mp3",
+        backend="gtts"
+    )
+    print(f"Audio saved to: {{result['path']}}")
+
+    # Generate and get base64 (for embedding)
+    result_b64 = generate_audio(
+        text="Embedded audio",
+        return_base64=True
+    )
+    # result_b64['base64'] contains the audio data
+
+# ============================================================
+# Pattern 4: With @stx.session
+# ============================================================
+
+@stx.session
+def main(
+    message="Analysis complete",
+    CONFIG=stx.INJECTED,
+    logger=stx.INJECTED,
+):
+    """Session with audio notifications."""
+    from scitex.audio import speak
+
+    logger.info("Starting analysis...")
+
+    # Do some work
+    import time
+    time.sleep(1)
+
+    # Notify via audio when done
+    speak(
+        text=f"{{message}}. Results saved to {{CONFIG.SDIR_OUT}}",
+        speed=1.5,
+        wait=True
+    )
+
+    logger.info("Done")
+    return 0
+
+# ============================================================
+# Pattern 5: Environment Configuration
+# ============================================================
+
+"""
+Environment Variables:
+----------------------
+SCITEX_AUDIO_BACKEND=gtts           # Default backend
+SCITEX_AUDIO_SPEED=1.5              # Default playback speed
+SCITEX_AUDIO_VOICE=en               # Voice/language
+SCITEX_AUDIO_ELEVENLABS_KEY=xxx     # ElevenLabs API key
+SCITEX_AUDIO_RELAY_URL=http://...   # Relay server URL
+"""
+
+# ============================================================
+# Pattern 6: Multi-Agent Workflows
+# ============================================================
+
+"""
+Agent Identification:
+---------------------
+In multi-agent workflows, each agent can identify itself:
+
+# Agent 1 (Architect)
+audio_speak(text="Architecture plan ready", agent_id="architect")
+
+# Agent 2 (Developer)
+audio_speak(text="Implementation complete", agent_id="developer")
+
+# Agent 3 (Tester)
+audio_speak(text="All tests passing", agent_id="tester")
+
+The agent_id helps distinguish which agent is speaking,
+especially useful when running concurrent agents.
+"""
+
+# ============================================================
+# MCP Tools Reference
+# ============================================================
+
+"""
+MCP Tools:
+----------
+
+Speech:
+- audio_speak(text, backend, speed, agent_id)
+- audio_speak_local(text, ...)     # Play on server
+- audio_speak_relay(text, ...)     # Play on client via relay
+
+Generation:
+- audio_generate_audio(text, output_path, backend)
+- audio_play_audio(path)
+
+Management:
+- audio_list_backends()
+- audio_list_voices(backend)
+- audio_check_audio_status()
+- audio_speech_queue_status()
+- audio_list_audio_files(limit)
+- audio_clear_audio_cache(max_age_hours)
+
+Context:
+- audio_announce_context()         # Announce cwd and git branch
+"""
+
+if __name__ == "__main__":
+    main()
+''',
+}
+
+__all__ = ["TEMPLATE"]
+
+# EOF

scitex/template/_templates/canvas.py

@@ -0,0 +1,312 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/template/_templates/canvas.py
+# ----------------------------------------
+
+"""Template for stx.canvas figure composition module usage."""
+
+TEMPLATE = {
+    "name": "Canvas Module",
+    "description": "stx.canvas usage for composing multi-panel figures with panel labels",
+    "filename": "canvas_script.py",
+    "priority": 8,
+    "content": '''#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: {timestamp}
+# File: {filepath}
+
+"""
+stx.canvas - Figure Composition
+===============================
+
+stx.canvas provides:
+- Multi-panel figure composition
+- Automatic panel labels (A, B, C, ...)
+- Millimeter-based positioning
+- Export to PNG, PDF, SVG
+
+For single figures: use stx.plt
+For composed figures: use stx.canvas
+
+Usage Patterns
+--------------
+1. MCP: canvas_* tools for Claude Code integration
+2. Python API: stx.canvas.* functions
+3. Common for: paper figures with multiple panels
+"""
+
+import scitex as stx
+
+# ============================================================
+# Pattern 1: Basic Composition (via MCP)
+# ============================================================
+
+"""
+MCP Tools for Claude Code:
+--------------------------
+
+# Create a new canvas
+canvas_create_canvas(
+    parent_dir="/path/to/project",
+    canvas_name="figure1",
+    width_mm=180,    # Single column width
+    height_mm=120
+)
+
+# Add panels from images
+canvas_add_panel(
+    parent_dir="/path/to/project",
+    canvas_name="figure1",
+    panel_name="panel_a",
+    source="/path/to/plot1.png",
+    x_mm=0,
+    y_mm=0,
+    width_mm=85,
+    height_mm=60,
+    label="A"
+)
+
+canvas_add_panel(
+    parent_dir="/path/to/project",
+    canvas_name="figure1",
+    panel_name="panel_b",
+    source="/path/to/plot2.png",
+    x_mm=90,
+    y_mm=0,
+    width_mm=85,
+    height_mm=60,
+    label="B"
+)
+
+# List panels
+canvas_list_panels(
+    parent_dir="/path/to/project",
+    canvas_name="figure1"
+)
+
+# Export canvas
+canvas_export_canvas(
+    parent_dir="/path/to/project",
+    canvas_name="figure1",
+    format="png",    # png, pdf, svg
+    dpi=300
+)
+"""
+
+# ============================================================
+# Pattern 2: Common Paper Figure Layouts
+# ============================================================
+
+"""
+Journal-Specific Widths:
+------------------------
+Single column: 85-90 mm (Nature, Science)
+1.5 column:    114 mm
+Double column: 170-180 mm
+Full page:     210 mm (A4)
+
+Common Layouts:
+---------------
+
+# 2-panel horizontal (A | B)
+Panel A: x=0, y=0, w=85, h=60
+Panel B: x=90, y=0, w=85, h=60
+Canvas:  w=180, h=60
+
+# 2-panel vertical (A over B)
+Panel A: x=0, y=0, w=85, h=55
+Panel B: x=0, y=60, w=85, h=55
+Canvas:  w=85, h=120
+
+# 4-panel grid (2x2)
+Panel A: x=0, y=0, w=85, h=55
+Panel B: x=90, y=0, w=85, h=55
+Panel C: x=0, y=60, w=85, h=55
+Panel D: x=90, y=60, w=85, h=55
+Canvas:  w=180, h=120
+"""
+
+# ============================================================
+# Pattern 3: Python API Usage
+# ============================================================
+
+def python_api_example():
+    """Direct Python API for canvas."""
+    from scitex.canvas import (
+        create_canvas,
+        add_panel,
+        list_panels,
+        export_canvas,
+        remove_panel,
+    )
+
+    # Create canvas
+    create_canvas(
+        parent_dir="./figures",
+        canvas_name="fig1",
+        width_mm=180,
+        height_mm=120
+    )
+
+    # Add panels
+    add_panel(
+        parent_dir="./figures",
+        canvas_name="fig1",
+        panel_name="scatter",
+        source="./plots/scatter.png",
+        x_mm=0, y_mm=0,
+        width_mm=85, height_mm=55,
+        label="A"
+    )
+
+    add_panel(
+        parent_dir="./figures",
+        canvas_name="fig1",
+        panel_name="histogram",
+        source="./plots/histogram.png",
+        x_mm=90, y_mm=0,
+        width_mm=85, height_mm=55,
+        label="B"
+    )
+
+    # List current panels
+    panels = list_panels(
+        parent_dir="./figures",
+        canvas_name="fig1"
+    )
+    print(f"Panels: {{panels}}")
+
+    # Export
+    export_canvas(
+        parent_dir="./figures",
+        canvas_name="fig1",
+        format="png",
+        dpi=300
+    )
+
+# ============================================================
+# Pattern 4: With @stx.session
+# ============================================================
+
+@stx.session
+def main(
+    CONFIG=stx.INJECTED,
+    plt=stx.INJECTED,
+    logger=stx.INJECTED,
+):
+    """Create composed figure for paper."""
+    import numpy as np
+    from scitex.canvas import (
+        create_canvas,
+        add_panel,
+        export_canvas,
+    )
+
+    # Generate individual plots first
+    plots_dir = CONFIG.SDIR_OUT / "plots"
+    plots_dir.mkdir(exist_ok=True)
+
+    # Plot 1: Scatter
+    fig, ax = plt.subplots(figsize=(4, 3))
+    x = np.random.randn(100)
+    y = 2*x + np.random.randn(100)*0.5
+    ax.scatter(x, y, alpha=0.6)
+    ax.set_xyt("X", "Y", "Correlation")
+    stx.io.save(fig, plots_dir / "scatter.png")
+
+    # Plot 2: Histogram
+    fig, ax = plt.subplots(figsize=(4, 3))
+    ax.hist(np.random.randn(500), bins=30, edgecolor='black')
+    ax.set_xyt("Value", "Count", "Distribution")
+    stx.io.save(fig, plots_dir / "histogram.png")
+
+    # Plot 3: Time series
+    fig, ax = plt.subplots(figsize=(4, 3))
+    t = np.linspace(0, 10, 200)
+    ax.plot(t, np.sin(t) + np.random.randn(200)*0.1)
+    ax.set_xyt("Time (s)", "Amplitude", "Signal")
+    stx.io.save(fig, plots_dir / "timeseries.png")
+
+    # Create canvas and compose
+    canvas_dir = CONFIG.SDIR_OUT / "canvas"
+    canvas_dir.mkdir(exist_ok=True)
+
+    create_canvas(
+        parent_dir=str(canvas_dir),
+        canvas_name="figure1",
+        width_mm=180,
+        height_mm=120
+    )
+
+    # Add panels
+    add_panel(
+        parent_dir=str(canvas_dir),
+        canvas_name="figure1",
+        panel_name="scatter",
+        source=str(plots_dir / "scatter.png"),
+        x_mm=0, y_mm=0,
+        width_mm=85, height_mm=55,
+        label="A"
+    )
+
+    add_panel(
+        parent_dir=str(canvas_dir),
+        canvas_name="figure1",
+        panel_name="histogram",
+        source=str(plots_dir / "histogram.png"),
+        x_mm=90, y_mm=0,
+        width_mm=85, height_mm=55,
+        label="B"
+    )
+
+    add_panel(
+        parent_dir=str(canvas_dir),
+        canvas_name="figure1",
+        panel_name="timeseries",
+        source=str(plots_dir / "timeseries.png"),
+        x_mm=0, y_mm=60,
+        width_mm=180, height_mm=55,
+        label="C"
+    )
+
+    # Export final figure
+    export_canvas(
+        parent_dir=str(canvas_dir),
+        canvas_name="figure1",
+        format="png",
+        dpi=300
+    )
+
+    logger.info(f"Figure saved to {{canvas_dir}}/figure1.png")
+    return 0
+
+# ============================================================
+# MCP Tools Reference
+# ============================================================
+
+"""
+MCP Tools:
+----------
+
+Canvas Management:
+- canvas_create_canvas(parent_dir, canvas_name, width_mm, height_mm)
+- canvas_list_canvases(parent_dir)
+- canvas_canvas_exists(parent_dir, canvas_name)
+
+Panel Operations:
+- canvas_add_panel(parent_dir, canvas_name, panel_name, source, x_mm, y_mm, width_mm, height_mm, label)
+- canvas_list_panels(parent_dir, canvas_name)
+- canvas_remove_panel(parent_dir, canvas_name, panel_name)
+
+Export:
+- canvas_export_canvas(parent_dir, canvas_name, format, dpi, output_path)
+"""
+
+if __name__ == "__main__":
+    main()
+''',
+}
+
+__all__ = ["TEMPLATE"]
+
+# EOF