stat-agent 0.1.0__tar.gz

stat_agent-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Yihang Chen
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

stat_agent-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: stat-agent
+Version: 0.1.0
+Summary: STAT: Spatial Transcriptomics Analytical agenT - AI-powered platform for spatial omics analysis
+Author-email: Yihang Chen <ychenlp@connect.ust.hk>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/chenyhvvvv/STAT-agent
+Project-URL: Repository, https://github.com/chenyhvvvv/STAT-agent
+Project-URL: Bug Tracker, https://github.com/chenyhvvvv/STAT-agent/issues
+Keywords: spatial transcriptomics,single-cell,agent,AI,bioinformatics,anndata,scanpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: anndata>=0.9
+Requires-Dist: scipy>=1.7
+Requires-Dist: scanpy>=1.9
+Requires-Dist: geopandas>=0.10
+Requires-Dist: shapely>=2.0
+Requires-Dist: pillow>=9.0
+Requires-Dist: tifffile>=2021.0
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: seaborn>=0.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.18; extra == "llm"
+Requires-Dist: openai>=1.12; extra == "llm"
+Requires-Dist: google-generativeai>=0.3; extra == "llm"
+Provides-Extra: web
+Requires-Dist: flask>=3.0; extra == "web"
+Provides-Extra: skills
+Requires-Dist: squidpy>=1.2; extra == "skills"
+Requires-Dist: gseapy>=1.0; extra == "skills"
+Requires-Dist: scvi-tools>=1.0; extra == "skills"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Provides-Extra: all
+Requires-Dist: stat-agent[dev,llm,skills,web]; extra == "all"
+Dynamic: license-file
+
+# STAT
+
+**Spatial Transcriptomics Analytical agenT**
+
+An AI-powered platform for spatial omics analysis with multi-format support, interactive visualization, and intelligent code generation.
+
+## Features
+
+- **AI Agent**: Natural language interface for spatial transcriptomics analysis — ask questions, get results
+- **Multi-format support**: Single-slice, multi-slice, and multi-omics (gene + protein) datasets
+- **Interactive viewer**: Canvas-based spatial visualization with zoom/pan, ROI drawing, and cell overlays
+- **Skill system**: Extensible analysis skills (cell type annotation, deconvolution, spatial domains, etc.)
+- **Code execution**: Agent generates and runs analysis code in a sandboxed environment
+- **Multi-provider LLM**: Works with OpenAI, Anthropic, Google, Deepseek, and Poe
+
+## Installation
+
+```bash
+pip install stat-agent
+```
+
+With all optional dependencies:
+
+```bash
+pip install "stat-agent[all]"
+```
+
+Or install specific extras:
+
+```bash
+pip install "stat-agent[web]"      # Flask web interface
+pip install "stat-agent[llm]"      # LLM providers
+pip install "stat-agent[skills]"   # Analysis skill dependencies
+```
+
+## Quick Start
+
+### Web Interface
+
+```bash
+stat-web
+# Open http://localhost:8889
+```
+
+Or with the startup script (includes Jupyter Lab):
+
+```bash
+./start_web.sh
+```
+
+### In the web UI:
+
+1. Enter path to your dataset directory
+2. Configure LLM (API key, model)
+3. Click "Load Dataset"
+4. Ask questions in the chat panel: *"Annotate cell types"*, *"Find spatially variable genes"*, *"Show BRCA1 expression"*
+
+## Data Format
+
+STAT auto-detects your data layout. Place files in a single directory:
+
+**Single-slice:**
+```
+dataset/
+├── tissue.h5ad          # Required: AnnData with x, y coordinates in obs
+└── he.tif               # Optional: H&E image (pixel coords = cell coords)
+```
+
+**Multi-slice:**
+```
+dataset/
+├── tissue_slice_0.h5ad
+├── he_slice_0.tif
+├── tissue_slice_1.h5ad
+└── he_slice_1.tif
+```
+
+**Multi-omics:**
+```
+dataset/
+├── tissue.h5ad          # Gene expression
+├── tissue_protein.h5ad  # Protein expression
+├── he.tif
+└── protein_CD3.tif
+```
+
+**Key**: Cell coordinates `(x, y)` in `adata.obs` map directly to image pixels `(x, y)`. No coordinate transformation needed.
+
+## Built-in Skills
+
+| Skill | Description |
+|-------|-------------|
+| Cell Type Annotation (GPT) | Unsupervised clustering + LLM-based annotation |
+| Cell Type Annotation (scANVI) | Transfer learning from scRNA-seq reference |
+| Deconvolution (RCTD) | Spot-level cell type deconvolution |
+| Spatial Domains (SpaGCN) | Graph-based spatial domain identification |
+| SVG (SpatialDE) | Spatially variable gene detection |
+| Neighborhood Enrichment | Cell type co-localization analysis |
+| Cell Communication (LIANA+) | Ligand-receptor interaction analysis |
+| Cell Communication (CellPhoneDB) | Permutation-based interaction testing |
+| GO Enrichment | Gene Ontology pathway analysis |
+| Niche Detection (Harmonics) | Spatial niche identification |
+| Integration (Harmony) | Multi-slice batch correction |
+| Alignment (STalign) | Spatial slice alignment |
+
+## Architecture
+
+```
+User Query → QueryPlanner → SkillFilter → LLM Matching → SkillVerifier → Code Generation → Execution
+```
+
+- **QueryPlanner**: Determines target slices, breaks complex queries into steps
+- **SkillFilter**: Programmatic filtering by modality, data level, number of slices
+- **SkillVerifier**: Checks prerequisites, requests missing information
+- **SpatialAgent**: Generates analysis code using skill instructions + session context
+- **CodeExecutor**: Sandboxed execution with state change detection
+
+## Project Structure
+
+```
+stat_agent/
+├── core/                  # Data layer
+│   ├── session.py         # Multi-slice/multi-omics session
+│   ├── data_slice.py      # Single data slice wrapper
+│   └── roi_manager.py     # ROI geometry management
+├── agent/                 # Agent pipeline
+│   ├── spatial_agent_core.py
+│   ├── conversation_orchestrator.py
+│   ├── pipeline_executor.py
+│   ├── query_planner.py
+│   ├── skill_registry.py
+│   ├── skill_filter.py
+│   ├── skill_verifier.py
+│   ├── llm_backend.py
+│   └── memory.py
+└── functions/
+    └── io.py              # Data loading
+.claude/skills/            # Skill definitions (SKILL.md + helper libs)
+web_interface.py           # Flask backend + API endpoints
+static/                    # Frontend (JS + CSS)
+templates/                 # HTML templates
+```
+
+## License
+
+BSD-3-Clause

stat_agent-0.1.0/README.md

@@ -0,0 +1,146 @@
+# STAT
+
+**Spatial Transcriptomics Analytical agenT**
+
+An AI-powered platform for spatial omics analysis with multi-format support, interactive visualization, and intelligent code generation.
+
+## Features
+
+- **AI Agent**: Natural language interface for spatial transcriptomics analysis — ask questions, get results
+- **Multi-format support**: Single-slice, multi-slice, and multi-omics (gene + protein) datasets
+- **Interactive viewer**: Canvas-based spatial visualization with zoom/pan, ROI drawing, and cell overlays
+- **Skill system**: Extensible analysis skills (cell type annotation, deconvolution, spatial domains, etc.)
+- **Code execution**: Agent generates and runs analysis code in a sandboxed environment
+- **Multi-provider LLM**: Works with OpenAI, Anthropic, Google, Deepseek, and Poe
+
+## Installation
+
+```bash
+pip install stat-agent
+```
+
+With all optional dependencies:
+
+```bash
+pip install "stat-agent[all]"
+```
+
+Or install specific extras:
+
+```bash
+pip install "stat-agent[web]"      # Flask web interface
+pip install "stat-agent[llm]"      # LLM providers
+pip install "stat-agent[skills]"   # Analysis skill dependencies
+```
+
+## Quick Start
+
+### Web Interface
+
+```bash
+stat-web
+# Open http://localhost:8889
+```
+
+Or with the startup script (includes Jupyter Lab):
+
+```bash
+./start_web.sh
+```
+
+### In the web UI:
+
+1. Enter path to your dataset directory
+2. Configure LLM (API key, model)
+3. Click "Load Dataset"
+4. Ask questions in the chat panel: *"Annotate cell types"*, *"Find spatially variable genes"*, *"Show BRCA1 expression"*
+
+## Data Format
+
+STAT auto-detects your data layout. Place files in a single directory:
+
+**Single-slice:**
+```
+dataset/
+├── tissue.h5ad          # Required: AnnData with x, y coordinates in obs
+└── he.tif               # Optional: H&E image (pixel coords = cell coords)
+```
+
+**Multi-slice:**
+```
+dataset/
+├── tissue_slice_0.h5ad
+├── he_slice_0.tif
+├── tissue_slice_1.h5ad
+└── he_slice_1.tif
+```
+
+**Multi-omics:**
+```
+dataset/
+├── tissue.h5ad          # Gene expression
+├── tissue_protein.h5ad  # Protein expression
+├── he.tif
+└── protein_CD3.tif
+```
+
+**Key**: Cell coordinates `(x, y)` in `adata.obs` map directly to image pixels `(x, y)`. No coordinate transformation needed.
+
+## Built-in Skills
+
+| Skill | Description |
+|-------|-------------|
+| Cell Type Annotation (GPT) | Unsupervised clustering + LLM-based annotation |
+| Cell Type Annotation (scANVI) | Transfer learning from scRNA-seq reference |
+| Deconvolution (RCTD) | Spot-level cell type deconvolution |
+| Spatial Domains (SpaGCN) | Graph-based spatial domain identification |
+| SVG (SpatialDE) | Spatially variable gene detection |
+| Neighborhood Enrichment | Cell type co-localization analysis |
+| Cell Communication (LIANA+) | Ligand-receptor interaction analysis |
+| Cell Communication (CellPhoneDB) | Permutation-based interaction testing |
+| GO Enrichment | Gene Ontology pathway analysis |
+| Niche Detection (Harmonics) | Spatial niche identification |
+| Integration (Harmony) | Multi-slice batch correction |
+| Alignment (STalign) | Spatial slice alignment |
+
+## Architecture
+
+```
+User Query → QueryPlanner → SkillFilter → LLM Matching → SkillVerifier → Code Generation → Execution
+```
+
+- **QueryPlanner**: Determines target slices, breaks complex queries into steps
+- **SkillFilter**: Programmatic filtering by modality, data level, number of slices
+- **SkillVerifier**: Checks prerequisites, requests missing information
+- **SpatialAgent**: Generates analysis code using skill instructions + session context
+- **CodeExecutor**: Sandboxed execution with state change detection
+
+## Project Structure
+
+```
+stat_agent/
+├── core/                  # Data layer
+│   ├── session.py         # Multi-slice/multi-omics session
+│   ├── data_slice.py      # Single data slice wrapper
+│   └── roi_manager.py     # ROI geometry management
+├── agent/                 # Agent pipeline
+│   ├── spatial_agent_core.py
+│   ├── conversation_orchestrator.py
+│   ├── pipeline_executor.py
+│   ├── query_planner.py
+│   ├── skill_registry.py
+│   ├── skill_filter.py
+│   ├── skill_verifier.py
+│   ├── llm_backend.py
+│   └── memory.py
+└── functions/
+    └── io.py              # Data loading
+.claude/skills/            # Skill definitions (SKILL.md + helper libs)
+web_interface.py           # Flask backend + API endpoints
+static/                    # Frontend (JS + CSS)
+templates/                 # HTML templates
+```
+
+## License
+
+BSD-3-Clause

stat_agent-0.1.0/pyproject.toml

@@ -0,0 +1,121 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stat-agent"
+version = "0.1.0"
+description = "STAT: Spatial Transcriptomics Analytical agenT - AI-powered platform for spatial omics analysis"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "BSD-3-Clause"
+authors = [
+    {name = "Yihang Chen", email = "ychenlp@connect.ust.hk"},
+]
+keywords = [
+    "spatial transcriptomics",
+    "single-cell",
+    "agent",
+    "AI",
+    "bioinformatics",
+    "anndata",
+    "scanpy",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+
+dependencies = [
+    # Core data
+    "numpy>=1.21",
+    "pandas>=1.3",
+    "anndata>=0.9",
+    "scipy>=1.7",
+    "scanpy>=1.9",
+
+    # Spatial geometry
+    "geopandas>=0.10",
+    "shapely>=2.0",
+
+    # Imaging
+    "pillow>=9.0",
+    "tifffile>=2021.0",
+
+    # Visualization
+    "matplotlib>=3.5",
+    "seaborn>=0.11",
+
+    # Config
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+# LLM providers
+llm = [
+    "anthropic>=0.18",
+    "openai>=1.12",
+    "google-generativeai>=0.3",
+]
+
+# Web interface
+web = [
+    "flask>=3.0",
+]
+
+# Skill dependencies (for specific analysis skills)
+skills = [
+    "squidpy>=1.2",
+    "gseapy>=1.0",
+    "scvi-tools>=1.0",
+]
+
+# Development
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.1",
+]
+
+# All optional dependencies
+all = [
+    "stat-agent[llm,web,skills,dev]",
+]
+
+[project.scripts]
+stat-web = "web_interface:main"
+
+[project.urls]
+Homepage = "https://github.com/chenyhvvvv/STAT-agent"
+Repository = "https://github.com/chenyhvvvv/STAT-agent"
+"Bug Tracker" = "https://github.com/chenyhvvvv/STAT-agent/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stat_agent*"]
+exclude = ["tests*", "docs*", "external*", "paper*", "examples*"]
+
+[tool.setuptools.package-data]
+"*" = ["*.md", "*.yaml", "*.yml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]
+ignore = ["E501"]

stat_agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stat_agent-0.1.0/stat_agent/__init__.py

@@ -0,0 +1,47 @@
+"""
+STAT
+
+Spatial Transcriptomics Analytical agenT
+
+Your AI Laboratory for Spatial Transcriptomics Analysis.
+An AI-powered platform for spatial omics analysis with multi-format support,
+interactive visualization, and intelligent code generation.
+"""
+
+__version__ = "0.1.0"
+
+from stat_agent.core.session import SimpleSession
+from stat_agent.core.roi_manager import ROIManager, ROI
+
+# Import and expose IO functions
+from stat_agent.functions.io import (
+    load_anndata,
+    load_image,
+    load_data,
+)
+
+__all__ = [
+    "SimpleSession",
+    "ROIManager",
+    "ROI",
+    "load_anndata",
+    "load_image",
+    "load_data",
+]
+
+
+def create_session(name="session"):
+    """
+    Create a new simplified spatial analysis session.
+
+    Parameters
+    ----------
+    name : str
+        Session name
+
+    Returns
+    -------
+    SimpleSession
+        Initialized session object
+    """
+    return SimpleSession(name=name)

stat_agent-0.1.0/stat_agent/agent/__init__.py

@@ -0,0 +1,5 @@
+"""Spatial transcriptomics agent module."""
+
+from stat_agent.agent.spatial_agent_core import SpatialAgent
+
+__all__ = ["SpatialAgent"]