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

scitex/__init__.py

@@ -196,6 +196,50 @@ config = _LazyModule("config")
 audio = _LazyModule("audio")
 msword = _LazyModule("msword")
 fts = _LazyModule("fts")  # Bundle schemas module
+social = _LazyModule("social")  # Social media integration (socialia wrapper)
+diagram = _LazyModule("diagram")  # Diagram creation (delegates to figrecipe)
+
+
+# Lazy Diagram class - delegates to figrecipe.Diagram
+class _LazyDiagram:
+    """Lazy loader for Diagram class from figrecipe."""
+
+    _class = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls._class is None:
+            try:
+                from figrecipe import Diagram as _FigrecipeDiagram
+
+                cls._class = _FigrecipeDiagram
+            except ImportError:
+                # Fallback to scitex's own implementation if figrecipe not available
+                from scitex.diagram._diagram import Diagram as _ScitexDiagram
+
+                cls._class = _ScitexDiagram
+        return cls._class(*args, **kwargs)
+
+    @classmethod
+    def from_yaml(cls, *args, **kwargs):
+        if cls._class is None:
+            cls.__new__(cls)  # Trigger lazy load
+        return cls._class.from_yaml(*args, **kwargs)
+
+    @classmethod
+    def from_mermaid(cls, *args, **kwargs):
+        if cls._class is None:
+            cls.__new__(cls)  # Trigger lazy load
+        return cls._class.from_mermaid(*args, **kwargs)
+
+    @classmethod
+    def from_dict(cls, *args, **kwargs):
+        if cls._class is None:
+            cls.__new__(cls)  # Trigger lazy load
+        return cls._class.from_dict(*args, **kwargs)
+
+
+Diagram = _LazyDiagram
+
 
 # Centralized path configuration - eager loaded for convenience
 # Usage: scitex.PATHS.logs, scitex.PATHS.cache, etc.
@@ -261,6 +305,9 @@ __all__ = [
     "msword",
     "fts",
     "fsb",  # Legacy alias
+    "social",  # Social media integration
+    "diagram",  # Diagram module (delegates to figrecipe)
+    "Diagram",  # Diagram class (from figrecipe)
     "PATHS",
     "INJECTED",
 ]

scitex/_env_loader.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-24
+# File: src/scitex/_env_loader.py
+
+"""
+Environment variable loader for SCITEX_ENV_SRC.
+
+Parses and loads bash-compatible .src files containing environment variable definitions.
+Supports both directory paths (all *.src files) and single file paths.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Dict, List
+
+logger = logging.getLogger(__name__)
+
+# Pattern to match: export VAR=value or VAR=value (with optional quotes)
+_ENV_PATTERN = re.compile(r"^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+
+
+def _parse_value(value: str) -> str:
+    """Parse a bash-style value, handling quotes and escapes."""
+    value = value.strip()
+
+    # Handle double-quoted strings
+    if value.startswith('"') and value.endswith('"'):
+        value = value[1:-1]
+        # Unescape common bash escapes
+        value = value.replace('\\"', '"')
+        value = value.replace("\\$", "$")
+        value = value.replace("\\\\", "\\")
+    # Handle single-quoted strings (no escaping in bash single quotes)
+    elif value.startswith("'") and value.endswith("'"):
+        value = value[1:-1]
+
+    # Expand $VAR and ${VAR} references
+    def expand_var(match):
+        var_name = match.group(1) or match.group(2)
+        return os.environ.get(var_name, "")
+
+    value = re.sub(r"\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)", expand_var, value)
+
+    return value
+
+
+def parse_src_file(filepath: Path) -> Dict[str, str]:
+    """
+    Parse a bash-compatible .src file and extract environment variables.
+
+    Parameters
+    ----------
+    filepath : Path
+        Path to the .src file.
+
+    Returns
+    -------
+    dict
+        Dictionary of variable names to values.
+    """
+    env_vars = {}
+
+    try:
+        with open(filepath) as f:
+            for line_num, line in enumerate(f, 1):
+                line = line.strip()
+
+                # Skip empty lines and comments
+                if not line or line.startswith("#"):
+                    continue
+
+                match = _ENV_PATTERN.match(line)
+                if match:
+                    name, value = match.groups()
+                    env_vars[name] = _parse_value(value)
+
+    except Exception as e:
+        logger.warning(f"Failed to parse {filepath}: {e}")
+
+    return env_vars
+
+
+def load_env_from_path(path: str) -> Dict[str, str]:
+    """
+    Load environment variables from a file or directory.
+
+    Parameters
+    ----------
+    path : str
+        Path to a .src file or directory containing .src files.
+
+    Returns
+    -------
+    dict
+        All loaded environment variables.
+    """
+    loaded = {}
+    path_obj = Path(path).expanduser()
+
+    if not path_obj.exists():
+        logger.warning(f"SCITEX_ENV_SRC path does not exist: {path}")
+        return loaded
+
+    files_to_load: List[Path] = []
+
+    if path_obj.is_dir():
+        # Load all .src files in directory
+        files_to_load = sorted(path_obj.glob("*.src"))
+    elif path_obj.is_file():
+        files_to_load = [path_obj]
+    else:
+        logger.warning(f"SCITEX_ENV_SRC is not a file or directory: {path}")
+        return loaded
+
+    for src_file in files_to_load:
+        env_vars = parse_src_file(src_file)
+        if env_vars:
+            logger.info(f"Loaded {len(env_vars)} vars from {src_file.name}")
+            loaded.update(env_vars)
+
+    return loaded
+
+
+def load_scitex_env() -> int:
+    """
+    Load environment variables from SCITEX_ENV_SRC if set.
+
+    This function should be called early in the MCP server startup.
+
+    Returns
+    -------
+    int
+        Number of environment variables loaded.
+    """
+    env_src = os.environ.get("SCITEX_ENV_SRC")
+
+    if not env_src:
+        return 0
+
+    loaded = load_env_from_path(env_src)
+
+    # Apply to current process environment
+    for name, value in loaded.items():
+        os.environ[name] = value
+
+    if loaded:
+        logger.info(f"SCITEX_ENV_SRC: Loaded {len(loaded)} environment variables")
+
+    return len(loaded)
+
+
+# EOF

scitex/_mcp_resources/__init__.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/_mcp_resources/__init__.py
+"""MCP Resources for SciTeX - Dynamic documentation for AI agents.
+
+This module provides MCP resources that expose SciTeX documentation,
+patterns, and examples to AI agents for code generation guidance.
+
+Resources:
+- scitex://cheatsheet - Quick reference for all core patterns
+- scitex://session-tree - Output directory structure explanation
+- scitex://module/{name} - Module-specific documentation (io, plt, stats, scholar, session)
+- scitex://io-formats - Supported file formats
+- scitex://figrecipe-spec - Figure recipe specification
+"""
+
+from __future__ import annotations
+
+from ._cheatsheet import register_cheatsheet_resources
+from ._figrecipe import register_figrecipe_resources
+from ._formats import register_format_resources
+from ._modules import register_module_resources
+from ._session import register_session_resources
+
+__all__ = ["register_resources"]
+
+
+def register_resources(mcp) -> None:
+    """Register all MCP resources with the FastMCP server."""
+    register_cheatsheet_resources(mcp)
+    register_session_resources(mcp)
+    register_module_resources(mcp)
+    register_format_resources(mcp)
+    register_figrecipe_resources(mcp)
+
+
+# EOF

scitex/_mcp_resources/_cheatsheet.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/_mcp_resources/_cheatsheet.py
+"""Core SciTeX cheatsheet resource for AI agents."""
+
+from __future__ import annotations
+
+__all__ = ["register_cheatsheet_resources"]
+
+CHEATSHEET = """\
+# SciTeX Cheatsheet for AI Agents
+=================================
+
+## Import Pattern (ALWAYS use this)
+```python
+import scitex as stx
+import numpy as np
+```
+
+## 1. @stx.session - Reproducible Experiment Tracking
+
+The MOST IMPORTANT pattern. Wrap your main function with @stx.session:
+
+```python
+@stx.session
+def main(
+    # User parameters (become CLI arguments automatically)
+    input_file="data.csv",       # --input-file (default: data.csv)
+    n_samples=100,               # --n-samples (default: 100)
+
+    # INJECTED parameters (auto-provided by session)
+    CONFIG=stx.INJECTED,         # Session config with ID, paths
+    plt=stx.INJECTED,            # Pre-configured matplotlib
+    COLORS=stx.INJECTED,         # Color palette
+    rng=stx.INJECTED,            # Seeded random generator
+    logger=stx.INJECTED,         # Session logger
+):
+    \"\"\"This docstring becomes --help description.\"\"\"
+
+    # Your analysis code here
+    data = stx.io.load(input_file)
+    results = process(data, n_samples)
+
+    # Save outputs (automatically to session directory)
+    stx.io.save(results, "results.csv")
+    stx.io.save(fig, "plot.png", symlink_to="./data")
+
+    return 0  # Exit status
+
+if __name__ == "__main__":
+    main()  # CLI mode when no args passed
+```
+
+## 2. stx.io - Universal File I/O (30+ formats)
+
+ALWAYS use stx.io.save() and stx.io.load() for file operations:
+
+```python
+# Saving - extension determines format automatically
+stx.io.save(df, "data.csv")           # DataFrame -> CSV
+stx.io.save(arr, "data.npy")          # NumPy array
+stx.io.save(obj, "data.pkl")          # Any Python object
+stx.io.save(fig, "plot.png")          # Figure + auto CSV
+
+# Loading - format auto-detected
+data = stx.io.load("data.csv")
+
+# With options
+stx.io.save(fig, "plot.png",
+    metadata={"exp": "exp01"},  # Embedded metadata
+    symlink_to="./data",        # Create symlink
+    verbose=True,               # Log messages
+)
+```
+
+IMPORTANT: stx.io.save shows logging messages:
+```
+SUCC: Saved to: ./script_out/results.csv (4.0 KiB)
+SUCC: Symlinked: ./script_out/results.csv -> ./data/results.csv
+```
+
+## 3. stx.plt - Publication-Ready Figures (Auto CSV Export)
+
+```python
+fig, ax = stx.plt.subplots()
+
+# Use stx_ prefixed methods for auto CSV export
+ax.stx_line(x, y, label="Signal")     # Tracked: exports to CSV
+ax.stx_scatter(x, y)                   # Tracked
+
+# Set labels with convenience method
+ax.set_xyt("X axis", "Y axis", "Title")
+
+# Save figure -> creates BOTH plot.png AND plot.csv
+stx.io.save(fig, "plot.png")
+fig.close()
+```
+
+## 4. stx.stats - Publication Statistics (23 tests)
+
+```python
+result = stx.stats.test_ttest_ind(group1, group2, return_as="dataframe")
+# Returns: p-value, Cohen's d, 95% CI, normality check, power analysis
+
+result = stx.stats.test_anova(*groups, return_as="latex")
+```
+
+## 5. stx.scholar - Literature Management
+
+```bash
+scitex scholar bibtex papers.bib --project myresearch --num-workers 8
+# Enriches BibTeX with abstracts, DOIs, impact factors, downloads PDFs
+```
+
+## Quick Tips
+
+1. ALWAYS use `import scitex as stx`
+2. ALWAYS wrap main functions with `@stx.session`
+3. ALWAYS use `stx.io.save()` and `stx.io.load()` for files
+4. ALWAYS use `stx.plt.subplots()` for figures
+5. ALWAYS use `ax.stx_*` methods for auto CSV export
+6. ALWAYS return exit status (0 for success) from main
+"""
+
+
+def register_cheatsheet_resources(mcp) -> None:
+    """Register cheatsheet resource."""
+
+    @mcp.resource("scitex://cheatsheet")
+    def cheatsheet() -> str:
+        """Complete SciTeX quick reference for AI code generation."""
+        return CHEATSHEET
+
+
+# EOF

scitex/_mcp_resources/_figrecipe.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/_mcp_resources/_figrecipe.py
+"""Figrecipe integration documentation for stx.plt MCP tools."""
+
+from __future__ import annotations
+
+__all__ = ["register_figrecipe_resources"]
+
+FIGRECIPE_INTEGRATION = """\
+# stx.plt - Powered by FigRecipe
+=================================
+
+stx.plt provides publication-ready figures with **automatic reproducibility**.
+It's built on FigRecipe, which records all matplotlib calls to YAML recipes.
+
+## Using stx.plt in @stx.session
+```python
+@stx.session
+def main(plt=stx.INJECTED, COLORS=stx.INJECTED):
+    fig, ax = stx.plt.subplots()
+
+    # Use stx_ prefixed methods for auto CSV export
+    ax.stx_line(x, y, color=COLORS.blue, label="data")
+    ax.set_xyt("X", "Y", "Title")
+
+    # Save creates: plot.png + plot.csv (data)
+    stx.io.save(fig, "plot.png", symlink_to="./data")
+    fig.close()
+    return 0
+```
+
+## Output Files from stx.io.save(fig, ...)
+```
+script_out/
+├── plot.png           # Image file
+├── plot.csv           # Extracted plot data (auto-generated)
+└── plot.yaml          # FigRecipe recipe (if using fr.save directly)
+```
+
+## Tracked Methods (stx_ prefix)
+These methods track data for automatic CSV export:
+- ax.stx_line(x, y)
+- ax.stx_scatter(x, y)
+- ax.stx_bar(x, height)
+- ax.stx_errorbar(x, y, yerr)
+- ax.stx_hist(data, bins)
+- ax.stx_boxplot(data)
+- ax.stx_violinplot(data)
+- ax.stx_imshow(matrix)
+
+## MCP Declarative Spec (via plt_plot tool)
+
+### RECOMMENDED: CSV Column Input
+Use CSV files - enables code to write data, MCP to visualize:
+```yaml
+plots:
+  - type: scatter
+    data_file: results.csv   # CSV from your analysis
+    x: time                   # Column name (string)
+    y: measurement            # Column name
+    color: blue
+```
+
+**Workflow**: Python writes CSV → MCP reads columns → Creates figure
+
+### Alternative: Inline Data (simple cases only)
+```yaml
+plots:
+  - type: line
+    x: [1, 2, 3, 4, 5]    # Inline array (less flexible)
+    y: [1, 4, 9, 16, 25]
+    color: blue
+```
+
+### Full Example
+```yaml
+figure:
+  width_mm: 85          # Nature single-column width
+  height_mm: 60
+plots:
+  - type: scatter
+    data_file: experiment.csv
+    x: time_hours
+    y: concentration_mm
+    color: blue
+    label: "Data"
+xlabel: "Time (h)"
+ylabel: "Concentration (mM)"
+title: "Enzyme Kinetics"
+legend: true
+stat_annotations:
+  - x1: 1
+    x2: 3
+    p_value: 0.01
+    style: stars
+```
+
+## Statistical Annotations
+```python
+# Method 1: Via stx.plt (Python API)
+ax.add_stat_annotation(x1=0, x2=1, p_value=0.01, style="stars")
+
+# Method 2: Via MCP spec (declarative)
+stat_annotations:
+  - x1: 0
+    x2: 1
+    p_value: 0.01  # Converts to ** automatically
+```
+
+## Color Palette (COLORS=stx.INJECTED)
+```python
+COLORS.blue, COLORS.red, COLORS.green, COLORS.orange
+COLORS.purple, COLORS.navy, COLORS.pink, COLORS.brown
+```
+
+## For Detailed FigRecipe Documentation
+See figrecipe MCP resources directly:
+- figrecipe://cheatsheet - Quick reference
+- figrecipe://api/core - Full API documentation
+- figrecipe://mcp-spec - Declarative spec format
+
+## Supported Plot Types
+line, scatter, bar, barh, hist, boxplot, violinplot, imshow, heatmap,
+errorbar, fill_between, contour, contourf, pie, stem
+"""
+
+
+def register_figrecipe_resources(mcp) -> None:
+    """Register figrecipe integration resource."""
+
+    @mcp.resource("scitex://plt-figrecipe")
+    def figrecipe_integration() -> str:
+        """stx.plt integration with FigRecipe for reproducible figures."""
+        return FIGRECIPE_INTEGRATION
+
+
+# EOF

scitex/_mcp_resources/_formats.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/_mcp_resources/_formats.py
+"""IO format documentation resource."""
+
+from __future__ import annotations
+
+__all__ = ["register_format_resources"]
+
+IO_FORMATS = """\
+# stx.io Supported Formats
+===========================
+
+## Data Formats
+
+| Extension | Type | Save | Load | Notes |
+|-----------|------|:----:|:----:|-------|
+| .csv | DataFrame/Array | ✓ | ✓ | Comma-separated |
+| .tsv | DataFrame/Array | ✓ | ✓ | Tab-separated |
+| .xlsx | DataFrame | ✓ | ✓ | Excel workbook |
+| .json | Dict/List | ✓ | ✓ | JSON format |
+| .yaml/.yml | Dict/List | ✓ | ✓ | YAML format |
+| .pkl/.pickle | Any | ✓ | ✓ | Python pickle |
+| .npy | Array | ✓ | ✓ | NumPy array |
+| .npz | Dict[Array] | ✓ | ✓ | Compressed NumPy |
+| .h5/.hdf5 | Array/Dict | ✓ | ✓ | HDF5 format |
+| .zarr | Array | ✓ | ✓ | Zarr array |
+| .parquet | DataFrame | ✓ | ✓ | Apache Parquet |
+| .feather | DataFrame | ✓ | ✓ | Feather format |
+
+## Image Formats
+
+| Extension | Type | Save | Load | Notes |
+|-----------|------|:----:|:----:|-------|
+| .png | Figure/Array | ✓ | ✓ | Lossless, metadata |
+| .jpg/.jpeg | Figure/Array | ✓ | ✓ | Lossy, metadata |
+| .tiff/.tif | Figure/Array | ✓ | ✓ | Scientific imaging |
+| .pdf | Figure | ✓ | ✓ | Vector format |
+| .svg | Figure | ✓ | - | Vector format |
+
+## Scientific Formats
+
+| Extension | Type | Load | Notes |
+|-----------|------|:----:|-------|
+| .edf | EEG | ✓ | European Data Format |
+| .fif | MNE | ✓ | MNE-Python |
+| .set | EEGLAB | ✓ | EEGLAB format |
+| .mat | MATLAB | ✓ | MATLAB files |
+
+## PyTorch Formats
+
+| Extension | Type | Save | Load |
+|-----------|------|:----:|:----:|
+| .pt | Tensor/Model | ✓ | ✓ |
+| .pth | Model | ✓ | ✓ |
+
+## Usage Notes
+
+1. **Extension determines handler**: `stx.io.save(df, "data.csv")` uses CSV
+2. **Metadata embedding**: PNG/JPEG support embedded metadata
+3. **Figure auto-CSV**: Saving figures also exports plotted data as CSV
+4. **Symlink support**: `symlink_to="./data"` creates symlinks
+
+## Examples
+
+```python
+import scitex as stx
+import pandas as pd
+import numpy as np
+
+# DataFrame
+df = pd.DataFrame({"x": [1, 2], "y": [3, 4]})
+stx.io.save(df, "data.csv")
+stx.io.save(df, "data.parquet")
+
+# NumPy
+arr = np.random.randn(100, 100)
+stx.io.save(arr, "array.npy")
+stx.io.save(arr, "array.npz")
+
+# Any Python object
+stx.io.save({"config": "value"}, "config.yaml")
+stx.io.save(complex_obj, "obj.pkl")
+
+# Figure with auto-CSV
+fig, ax = stx.plt.subplots()
+ax.stx_line([1, 2, 3], [4, 5, 6])
+stx.io.save(fig, "plot.png")  # Creates plot.png + plot.csv
+```
+"""
+
+
+def register_format_resources(mcp) -> None:
+    """Register IO formats resource."""
+
+    @mcp.resource("scitex://io-formats")
+    def io_formats() -> str:
+        """List all supported file formats for stx.io."""
+        return IO_FORMATS
+
+
+# EOF