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

scitex/_mcp_resources/_modules.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/_mcp_resources/_modules.py
+"""Module-specific documentation resources for AI agents."""
+
+from __future__ import annotations
+
+__all__ = ["register_module_resources"]
+
+MODULE_IO = """\
+# stx.io - Universal File I/O
+==============================
+
+## Core API
+```python
+stx.io.save(obj, path, **kwargs)  # Save any object
+stx.io.load(path, **kwargs)       # Load any file
+```
+
+## Key Features
+
+### 1. Automatic Extension Handling
+```python
+stx.io.save(df, "data.csv")    # Uses CSV handler
+stx.io.save(df, "data.xlsx")   # Uses Excel handler
+stx.io.save(arr, "data.npy")   # Uses NumPy handler
+```
+
+### 2. Verbose Logging
+```python
+stx.io.save(df, "data.csv", verbose=True)
+# Output: SUCC: Saved to: ./script_out/data.csv (12.5 KiB)
+```
+
+### 3. Metadata Embedding (Images)
+```python
+stx.io.save(fig, "plot.png", metadata={"exp": "exp01"})
+img, meta = stx.io.load("plot.png")
+print(meta)  # {'exp': 'exp01', 'url': 'https://scitex.ai'}
+```
+
+### 4. Symlink Creation
+```python
+stx.io.save(results, "results.csv", symlink_to="./data")
+# Creates: ./data/results.csv -> ./script_out/results.csv
+```
+
+### 5. Auto CSV Export for Figures
+```python
+stx.io.save(fig, "plot.png")
+# Creates BOTH: plot.png AND plot.csv (with plotted data)
+```
+
+## Common Formats
+- `.csv`, `.xlsx`, `.parquet` - DataFrames
+- `.npy`, `.npz`, `.h5` - Arrays
+- `.pkl`, `.json`, `.yaml` - Objects
+- `.png`, `.jpg`, `.pdf`, `.svg` - Figures
+"""
+
+MODULE_PLT = """\
+# stx.plt - Publication-Ready Figures
+======================================
+
+## Basic Usage
+```python
+fig, ax = stx.plt.subplots()
+
+# Use stx_ prefixed methods for auto CSV export
+ax.stx_line(x, y, label="Signal")
+ax.stx_scatter(x, y)
+ax.stx_bar(categories, values)
+ax.stx_errorbar(x, y, yerr=err)
+
+# Set labels with convenience method
+ax.set_xyt("X axis", "Y axis", "Title")
+
+# Save -> creates BOTH image AND CSV
+stx.io.save(fig, "plot.png")
+fig.close()
+```
+
+## Tracked Plot Methods (stx_ prefix)
+```python
+ax.stx_line(x, y)           # Line plot
+ax.stx_scatter(x, y)        # Scatter plot
+ax.stx_bar(x, height)       # Bar chart
+ax.stx_errorbar(x, y, yerr) # Error bars
+ax.stx_hist(data, bins=30)  # Histogram
+ax.stx_boxplot(data)        # Box plot
+ax.stx_violinplot(data)     # Violin plot
+ax.stx_imshow(matrix)       # Image/heatmap
+```
+
+## Auto CSV Export
+When saving with `stx.io.save(fig, "plot.png")`, CSV is auto-created:
+```csv
+ax_00_stx_line_0_x,ax_00_stx_line_0_y
+0.0,0.0
+0.1,0.0998
+...
+```
+
+## Color Palette
+```python
+@stx.session
+def main(COLORS=stx.INJECTED):
+    ax.stx_line(x, y1, color=COLORS.blue)
+    ax.stx_line(x, y2, color=COLORS.red)
+    # Available: blue, red, green, orange, purple, navy, pink, brown, gray
+```
+"""
+
+MODULE_STATS = """\
+# stx.stats - Publication Statistics
+=====================================
+
+23 statistical tests with automatic assumption checking, effect sizes,
+confidence intervals, and multiple output formats.
+
+## Two-Sample Tests
+```python
+result = stx.stats.test_ttest_ind(group1, group2)
+result = stx.stats.test_mannwhitneyu(group1, group2)  # Non-parametric
+```
+
+## Paired Sample Tests
+```python
+result = stx.stats.test_ttest_rel(before, after)
+result = stx.stats.test_wilcoxon(before, after)
+```
+
+## Multiple Group Tests
+```python
+result = stx.stats.test_anova(g1, g2, g3, g4)
+result = stx.stats.test_kruskal(g1, g2, g3, g4)  # Non-parametric
+```
+
+## Correlation Tests
+```python
+result = stx.stats.test_pearsonr(x, y)
+result = stx.stats.test_spearmanr(x, y)
+```
+
+## Output Formats
+```python
+result = stx.stats.test_ttest_ind(g1, g2, return_as="dataframe")  # Default
+result = stx.stats.test_ttest_ind(g1, g2, return_as="latex")      # Papers
+result = stx.stats.test_ttest_ind(g1, g2, return_as="markdown")   # Docs
+```
+
+## Result Contents
+- `statistic`: Test statistic value
+- `p_value`: P-value
+- `effect_size`: Cohen's d, r, eta², etc.
+- `ci_low`, `ci_high`: 95% CI
+- `power`: Statistical power
+"""
+
+MODULE_SCHOLAR = """\
+# stx.scholar - Literature Management
+======================================
+
+BibTeX enrichment with abstracts for LLM context, DOI resolution,
+PDF download, and impact factors.
+
+## CLI Usage (Recommended)
+```bash
+scitex scholar bibtex papers.bib --project myresearch --num-workers 8
+```
+
+## BibTeX Enrichment
+
+Before:
+```bibtex
+@article{Smith2024,
+  title = {Neural Networks},
+  author = {Smith, John},
+  doi = {10.1038/s41586-024-00001-1}
+}
+```
+
+After:
+```bibtex
+@article{Smith2024,
+  title = {Neural Networks for Brain Signal Analysis},
+  author = {Smith, John and Lee, Alice},
+  doi = {10.1038/s41586-024-00001-1},
+  journal = {Nature},
+  year = {2024},
+  abstract = {We present a novel deep learning approach...},
+  impact_factor = {64.8}
+}
+```
+
+The abstract provides rich context for LLM-based literature review!
+
+## MCP Tools
+- `scholar_search_papers`: Search papers
+- `scholar_enrich_bibtex`: Add metadata
+- `scholar_download_pdf`: Download PDFs
+- `scholar_fetch_papers`: Async download
+- `scholar_parse_pdf_content`: Extract text
+
+## Tip: Get BibTeX from Scholar QA
+1. Go to https://scholarqa.allen.ai/chat/
+2. Ask research questions
+3. Export All Citations -> Save as .bib
+4. Enrich: `scitex scholar bibtex citations.bib`
+"""
+
+MODULE_SESSION = """\
+# stx.session - Reproducible Experiment Tracking
+=================================================
+
+## The @stx.session Decorator
+```python
+@stx.session
+def main(
+    input_file="data.csv",       # CLI args (auto-generated)
+    n_epochs=100,
+
+    CONFIG=stx.INJECTED,         # Session config
+    plt=stx.INJECTED,            # matplotlib
+    COLORS=stx.INJECTED,         # Color palette
+    rng=stx.INJECTED,            # Random generator
+    logger=stx.INJECTED,         # Logger
+):
+    \"\"\"Docstring becomes --help.\"\"\"
+    stx.io.save(results, "output.csv", symlink_to="./data")
+    return 0
+
+if __name__ == "__main__":
+    main()
+```
+
+## Injected Variables
+
+### CONFIG (DotDict)
+```python
+CONFIG.ID          # "2026Y-01M-20D-09h37m01s_boSr"
+CONFIG.FILE        # "/path/to/script.py"
+CONFIG.SDIR_OUT    # "/path/to/script_out"
+CONFIG.SDIR_RUN    # "/path/to/script_out/RUNNING/<session_id>"
+CONFIG.PID         # Process ID
+CONFIG.ARGS        # {"input_file": "data.csv", ...}
+```
+
+### COLORS
+```python
+COLORS.blue, COLORS.red, COLORS.green, COLORS.orange
+COLORS.purple, COLORS.navy, COLORS.pink, COLORS.brown
+```
+
+## YAML Config Loading
+Place YAML files in `./config/` directory - auto-loaded into CONFIG:
+```yaml
+# ./config/experiment.yaml
+model:
+  hidden_size: 256
+  num_layers: 3
+training:
+  batch_size: 32
+  learning_rate: 0.001
+```
+Access via dot notation:
+```python
+CONFIG.experiment.model.hidden_size    # 256
+CONFIG.experiment.training.batch_size  # 32
+```
+
+## Symlinks for Central Navigation
+```python
+stx.io.save(arr, "output.npy", symlink_to="./data")
+# Creates: ./data/output.npy -> ../script_out/output.npy
+```
+Use `./data` to accumulate outputs from multiple scripts.
+
+## Output Structure
+```
+script_out/
+├── output.npy           # Files at ROOT (not in session dir)
+└── FINISHED_SUCCESS/
+    └── <session_id>/
+        ├── CONFIGS/
+        │   ├── CONFIG.pkl    # Pickle snapshot
+        │   └── CONFIG.yaml   # Human-readable
+        └── logs/
+            ├── stdout.log    # print() captured
+            └── stderr.log    # errors captured
+```
+
+## Best Practices
+1. Always return exit status (0 for success)
+2. Use stx.io.save() with symlink_to="./data"
+3. Use stx.plt for figures (auto CSV export)
+"""
+
+MODULE_DOCS = {
+    "io": MODULE_IO,
+    "plt": MODULE_PLT,
+    "stats": MODULE_STATS,
+    "scholar": MODULE_SCHOLAR,
+    "session": MODULE_SESSION,
+}
+
+
+def register_module_resources(mcp) -> None:
+    """Register module documentation resources."""
+
+    @mcp.resource("scitex://module/io")
+    def module_io() -> str:
+        """stx.io module documentation - Universal File I/O."""
+        return MODULE_DOCS["io"]
+
+    @mcp.resource("scitex://module/plt")
+    def module_plt() -> str:
+        """stx.plt module documentation - Publication-ready figures."""
+        return MODULE_DOCS["plt"]
+
+    @mcp.resource("scitex://module/stats")
+    def module_stats() -> str:
+        """stx.stats module documentation - Statistical tests."""
+        return MODULE_DOCS["stats"]
+
+    @mcp.resource("scitex://module/scholar")
+    def module_scholar() -> str:
+        """stx.scholar module documentation - Literature management."""
+        return MODULE_DOCS["scholar"]
+
+    @mcp.resource("scitex://module/session")
+    def module_session() -> str:
+        """stx.session module documentation - Experiment tracking."""
+        return MODULE_DOCS["session"]
+
+
+# EOF

scitex/_mcp_resources/_session.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/_mcp_resources/_session.py
+"""Session output tree documentation resource."""
+
+from __future__ import annotations
+
+__all__ = ["register_session_resources"]
+
+SESSION_TREE = """\
+# @stx.session Output Directory Structure
+==========================================
+
+When you use @stx.session, outputs are automatically organized:
+
+```
+script.py                          # Your script
+script_out/                        # Output directory (auto-created)
+├── output.npy                     # Your saved files (ROOT level)
+├── results.json                   # All outputs here, NOT in session dir
+├── figure.png                     # Figures
+├── figure.csv                     # Auto-exported plot data
+├── RUNNING/                       # Currently running sessions
+│   └── 2025Y-01M-20D-09h30m00s_AbC1-main/
+│       ├── CONFIGS/
+│       │   ├── CONFIG.pkl         # Python config object (pickle)
+│       │   └── CONFIG.yaml        # Human-readable config snapshot
+│       └── logs/
+│           ├── stdout.log         # All print() output captured
+│           └── stderr.log         # All errors captured
+├── FINISHED_SUCCESS/              # Completed sessions (moved from RUNNING)
+│   └── <session_id>-main/
+│       ├── CONFIGS/...
+│       └── logs/...
+└── FINISHED_FAILED/               # Failed sessions (errors)
+    └── <session_id>-main/
+        └── ...
+data/                              # Central navigation via symlinks
+└── output.npy -> ../script_out/output.npy
+```
+
+## Key Points
+
+1. **Session ID Format**: `YYYY'Y'-MM'M'-DD'D'-HH'h'MM'm'SS's'_XXXX-funcname`
+   - Example: `2026Y-01M-20D-09h37m01s_boSr-main`
+
+2. **Output File Placement**:
+   - Files saved with `stx.io.save(obj, "filename")` go to `script_out/` ROOT
+   - NOT inside the session subdirectory (CONFIGS/logs only there)
+
+3. **Symlinks for Central Navigation**:
+   ```python
+   stx.io.save(arr, "output.npy", symlink_to="./data")
+   # Creates: ./data/output.npy -> ../script_out/output.npy
+   ```
+   - Use `./data` directory to accumulate outputs from multiple scripts
+   - Easy navigation without digging into individual script_out directories
+
+4. **CONFIG Object** (available as `CONFIG=stx.INJECTED`):
+   ```python
+   CONFIG.ID          # "2026Y-01M-20D-09h37m01s_boSr"
+   CONFIG.FILE        # "/path/to/script.py"
+   CONFIG.SDIR_OUT    # "/path/to/script_out"
+   CONFIG.SDIR_RUN    # "/path/to/script_out/RUNNING/<session_id>"
+   CONFIG.PID         # 12345
+   CONFIG.ARGS        # {"n_points": 100, ...}
+   ```
+
+5. **YAML Config Loading** (from `./config/*.yaml`):
+   ```yaml
+   # ./config/experiment.yaml
+   model:
+     hidden_size: 256
+     num_layers: 3
+   training:
+     batch_size: 32
+   ```
+   Access: `CONFIG.experiment.model.hidden_size  # 256`
+
+6. **Automatic Cleanup**:
+   - On success: RUNNING -> FINISHED_SUCCESS
+   - On error: RUNNING -> FINISHED_FAILED
+   - All print()/stderr captured in logs/
+
+## Example Script
+
+```python
+#!/usr/bin/env python3
+import scitex as stx
+import numpy as np
+
+@stx.session
+def main(n_points=100, CONFIG=stx.INJECTED, plt=stx.INJECTED):
+    \"\"\"Generate sample data and plot.\"\"\"
+
+    x = np.linspace(0, 10, n_points)
+    y = np.sin(x) * np.exp(-x/5)
+
+    fig, ax = stx.plt.subplots()
+    ax.stx_line(x, y)
+    ax.set_xyt("X", "Y", "Damped Sine")
+
+    # symlink_to for central navigation
+    stx.io.save(fig, "sine.png", symlink_to="./data")
+    fig.close()
+
+    return 0
+
+if __name__ == "__main__":
+    main()
+```
+
+Output:
+```
+SUCC: Saved to: ./script_out/sine.png (241.6 KiB)
+SUCC: Symlinked: /path/script_out/sine.png ->
+SUCC:            /path/data/sine.png
+```
+
+Tree after running:
+```
+script.py
+script_out/
+├── sine.png                       # Figure at ROOT level
+├── sine.csv                       # Auto-exported data
+└── FINISHED_SUCCESS/
+    └── 2026Y-01M-20D-09h37m01s_boSr-main/
+        ├── CONFIGS/
+        │   ├── CONFIG.pkl
+        │   └── CONFIG.yaml
+        └── logs/
+            ├── stdout.log
+            └── stderr.log
+data/
+└── sine.png -> ../script_out/sine.png
+```
+"""
+
+
+def register_session_resources(mcp) -> None:
+    """Register session tree resource."""
+
+    @mcp.resource("scitex://session-tree")
+    def session_tree() -> str:
+        """Explain the @stx.session output directory structure."""
+        return SESSION_TREE
+
+
+# EOF

scitex/_mcp_tools/__init__.py

@@ -9,8 +9,10 @@ from .audio import register_audio_tools
 from .canvas import register_canvas_tools
 from .capture import register_capture_tools
 from .diagram import register_diagram_tools
+from .introspect import register_introspect_tools
 from .plt import register_plt_tools
 from .scholar import register_scholar_tools
+from .social import register_social_tools
 from .stats import register_stats_tools
 from .template import register_template_tools
 from .ui import register_ui_tools
@@ -25,8 +27,10 @@ def register_all_tools(mcp) -> None:
     register_canvas_tools(mcp)
     register_capture_tools(mcp)
     register_diagram_tools(mcp)
+    register_introspect_tools(mcp)
     register_plt_tools(mcp)
     register_scholar_tools(mcp)
+    register_social_tools(mcp)
     register_stats_tools(mcp)
     register_template_tools(mcp)
     register_ui_tools(mcp)

scitex/_mcp_tools/audio.py

@@ -28,6 +28,7 @@ def register_audio_tools(mcp) -> None:
         fallback: bool = True,
         agent_id: Optional[str] = None,
         wait: bool = True,
+        signature: bool = False,
     ) -> str:
         """[audio] Convert text to speech with fallback (pyttsx3 -> gtts -> elevenlabs)."""
         from scitex.audio._mcp.handlers import speak_handler
@@ -43,6 +44,7 @@ def register_audio_tools(mcp) -> None:
             fallback=fallback,
             agent_id=agent_id,
             wait=wait,
+            signature=signature,
         )
         return _json(result)
 
@@ -130,5 +132,69 @@ def register_audio_tools(mcp) -> None:
         result = await announce_context_handler(include_full_path=include_full_path)
         return _json(result)
 
+    @mcp.tool()
+    async def audio_speak_local(
+        text: str,
+        backend: Optional[str] = None,
+        voice: Optional[str] = None,
+        rate: int = 150,
+        speed: float = 1.5,
+        play: bool = True,
+        save: bool = False,
+        fallback: bool = True,
+        agent_id: Optional[str] = None,
+    ) -> str:
+        """[audio] Convert text to speech on the LOCAL/SERVER machine.
+
+        Use when running Claude Code directly on your local machine.
+        Audio plays where MCP server runs.
+        """
+        from scitex.audio._mcp.speak_handlers import speak_local_handler
+
+        result = await speak_local_handler(
+            text=text,
+            backend=backend,
+            voice=voice,
+            rate=rate,
+            speed=speed,
+            play=play,
+            save=save,
+            fallback=fallback,
+            agent_id=agent_id,
+        )
+        return _json(result)
+
+    @mcp.tool()
+    async def audio_speak_relay(
+        text: str,
+        backend: Optional[str] = None,
+        voice: Optional[str] = None,
+        rate: int = 150,
+        speed: float = 1.5,
+        play: bool = True,
+        save: bool = False,
+        fallback: bool = True,
+        agent_id: Optional[str] = None,
+    ) -> str:
+        """[audio] Convert text to speech via RELAY server (remote playback).
+
+        Use when running on remote server (NAS) and want audio on your
+        local machine. Returns error with setup instructions if unavailable.
+        """
+        from scitex.audio._mcp.speak_handlers import speak_relay_handler
+
+        result = await speak_relay_handler(
+            text=text,
+            backend=backend,
+            voice=voice,
+            rate=rate,
+            speed=speed,
+            play=play,
+            save=save,
+            fallback=fallback,
+            agent_id=agent_id,
+        )
+        return _json(result)
+
 
 # EOF

scitex/_mcp_tools/diagram.py

@@ -1,106 +1,22 @@
 #!/usr/bin/env python3
-# Timestamp: 2026-01-15
+# Timestamp: 2026-01-24
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/_mcp_tools/diagram.py
-"""Diagram module tools for FastMCP unified server."""
-
-from __future__ import annotations
-
-import json
-from typing import Optional
+"""Diagram module tools for FastMCP unified server.
 
+Delegates entirely to figrecipe's diagram MCP tools.
+figrecipe is the single source of truth.
+"""
 
-def _json(data: dict) -> str:
-    return json.dumps(data, indent=2, default=str)
+from __future__ import annotations
 
 
 def register_diagram_tools(mcp) -> None:
-    """Register diagram tools with FastMCP server."""
-
-    @mcp.tool()
-    async def diagram_create_diagram(
-        spec_path: Optional[str] = None,
-        spec_dict: Optional[dict] = None,
-    ) -> str:
-        """[diagram] Create a diagram from a YAML specification file or dictionary."""
-        from scitex.diagram._mcp.handlers import create_diagram_handler
-
-        result = await create_diagram_handler(
-            spec_path=spec_path,
-            spec_dict=spec_dict,
-        )
-        return _json(result)
-
-    @mcp.tool()
-    async def diagram_compile_mermaid(
-        spec_path: Optional[str] = None,
-        output_path: Optional[str] = None,
-        spec_dict: Optional[dict] = None,
-    ) -> str:
-        """[diagram] Compile diagram specification to Mermaid format."""
-        from scitex.diagram._mcp.handlers import compile_mermaid_handler
-
-        result = await compile_mermaid_handler(
-            spec_path=spec_path,
-            output_path=output_path,
-            spec_dict=spec_dict,
-        )
-        return _json(result)
-
-    @mcp.tool()
-    async def diagram_compile_graphviz(
-        spec_path: Optional[str] = None,
-        output_path: Optional[str] = None,
-        spec_dict: Optional[dict] = None,
-    ) -> str:
-        """[diagram] Compile diagram specification to Graphviz DOT format."""
-        from scitex.diagram._mcp.handlers import compile_graphviz_handler
-
-        result = await compile_graphviz_handler(
-            spec_path=spec_path,
-            output_path=output_path,
-            spec_dict=spec_dict,
-        )
-        return _json(result)
-
-    @mcp.tool()
-    async def diagram_list_presets() -> str:
-        """[diagram] List available diagram presets (workflow, decision, pipeline)."""
-        from scitex.diagram._mcp.handlers import list_presets_handler
-
-        result = await list_presets_handler()
-        return _json(result)
-
-    @mcp.tool()
-    async def diagram_get_preset(preset_name: str) -> str:
-        """[diagram] Get a diagram preset configuration by name."""
-        from scitex.diagram._mcp.handlers import get_preset_handler
-
-        result = await get_preset_handler(preset_name=preset_name)
-        return _json(result)
-
-    @mcp.tool()
-    async def diagram_split_diagram(
-        spec_path: str,
-        strategy: str = "horizontal",
-        max_nodes_per_part: int = 10,
-    ) -> str:
-        """[diagram] Split a large diagram into smaller parts for multi-column layouts."""
-        from scitex.diagram._mcp.handlers import split_diagram_handler
-
-        result = await split_diagram_handler(
-            spec_path=spec_path,
-            strategy=strategy,
-            max_nodes_per_part=max_nodes_per_part,
-        )
-        return _json(result)
-
-    @mcp.tool()
-    async def diagram_get_paper_modes() -> str:
-        """[diagram] Get available paper layout modes and their constraints."""
-        from scitex.diagram._mcp.handlers import get_paper_modes_handler
+    """Register diagram tools by delegating to figrecipe."""
+    from figrecipe._mcp._diagram_tools import (
+        register_diagram_tools as register_figrecipe_diagram_tools,
+    )
 
-        result = await get_paper_modes_handler()
-        return _json(result)
+    register_figrecipe_diagram_tools(mcp)
 
 
 # EOF