lobster-transcriptomics 1.2.0__tar.gz → 1.2.2__tar.gz

{lobster_transcriptomics-1.2.0/lobster_transcriptomics.egg-info → lobster_transcriptomics-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lobster-transcriptomics
-Version: 1.2.0
+Version: 1.2.2
 Summary: Transcriptomics agents for Lobster AI - single-cell and bulk RNA-seq analysis
 Author-email: Omics-OS <info@omics-os.com>
 License-Expression: AGPL-3.0-or-later

{lobster_transcriptomics-1.2.0 → lobster_transcriptomics-1.2.2}/lobster/agents/transcriptomics/annotation_expert.py

@@ -54,6 +54,7 @@ from lobster.config.inference_context import (
 from lobster.config.llm_factory import create_llm
 from lobster.config.settings import get_settings
 from lobster.core.component_registry import component_registry
+from lobster.core.export_scope import WORKSPACE_EXPORT_MESSAGE, outside_workspace
 from lobster.core.figures.export_guard import MANAGED_EXPORT_MESSAGE, export_refused
 from lobster.core.runtime.data_manager import DataManagerV2
 from lobster.services.analysis.enhanced_singlecell_service import (
@@ -1067,12 +1068,17 @@ def annotation_expert(
             output_path = Path(output_filename)
             if not output_path.is_absolute():
                 output_path = data_manager.exports_dir / output_path
+            # The destination stays inside the workspace (or a listed export root).
+            if outside_workspace(data_manager.workspace_path, output_path):
+                return WORKSPACE_EXPORT_MESSAGE
             # Figures are saved only through the trusted save step: check the
             # caller's (unresolved) destination before anything is created.
             if export_refused(data_manager.workspace_path, output_path):
                 return MANAGED_EXPORT_MESSAGE
             output_path.parent.mkdir(parents=True, exist_ok=True)
             output_filename = str(output_path.resolve())
+            if outside_workspace(data_manager.workspace_path, output_filename):
+                return WORKSPACE_EXPORT_MESSAGE
             if export_refused(
                 data_manager.workspace_path, output_path, output_filename
             ):

{lobster_transcriptomics-1.2.0 → lobster_transcriptomics-1.2.2}/lobster/agents/transcriptomics/de_analysis_expert.py

@@ -53,6 +53,15 @@ from lobster.core import (
     InsufficientCellsError,
     PseudobulkError,
 )
+from lobster.core.export_scope import (
+    WORKSPACE_EXPORT_MESSAGE,
+    InvalidModalityNameError,
+    WorkspaceExportError,
+    assert_inside_workspace,
+    check_modality_name,
+    outside_workspace,
+    plain_name_part,
+)
 from lobster.core.figures.errors import ManagedPathError
 from lobster.core.figures.export_dirs import assert_dirs_allowed
 from lobster.core.figures.export_guard import (
@@ -89,6 +98,15 @@ _BULK_SERVICE_SETUP = (
 )
 
 
+def _de_result_name(modality_name: str, group1, group2) -> str:
+    """The DE result modality name: group labels are data values, so each is encoded
+    as part of one plain name (two labels never collide); refused (fixed reason)
+    before any analysis if the name is still not plain, for example too long."""
+    return check_modality_name(
+        f"{modality_name}_de_{plain_name_part(group1)}_vs_{plain_name_part(group2)}"
+    )
+
+
 def _is_pseudobulk(adata) -> bool:
     """True when the modality carries a pseudobulk or formula design (``uns`` only)."""
     return (
@@ -1091,7 +1109,9 @@ def de_analysis_expert(
                 status = (
                     "OK"
                     if count >= 4
-                    else "LOW POWER" if count >= 3 else "INSUFFICIENT"
+                    else "LOW POWER"
+                    if count >= 3
+                    else "INSUFFICIENT"
                 )
                 response += f"\n- {group}: {count} replicates ({status})"
             response += _replicate_summary_text(replicate_validation)
@@ -1174,21 +1194,26 @@ def de_analysis_expert(
             # Get the modality
             adata = data_manager.get_modality(modality_name)
 
+            # The result name carries the group labels (data values, which may hold
+            # '/'): encoded into one plain name, checked before any analysis.
+            de_modality_name = None
+            if not (_is_pseudobulk(adata) and method == "deseq2"):
+                de_modality_name = _de_result_name(modality_name, group1, group2)
+
             # Every save target of the branch that will run is checked before the
             # data changes or any analysis runs.
             if save_result:
                 if _is_pseudobulk(adata) and method == "deseq2":
-                    assert_export_allowed(
-                        data_manager.workspace_path,
-                        data_manager.exports_dir / f"{modality_name}_de_results.csv",
+                    results_csv = (
+                        data_manager.exports_dir / f"{modality_name}_de_results.csv"
                     )
+                    assert_inside_workspace(data_manager.workspace_path, results_csv)
+                    assert_export_allowed(data_manager.workspace_path, results_csv)
                     data_manager._assert_save_allowed(
                         f"{modality_name}_with_de_results.h5ad"
                     )
                 else:
-                    data_manager._assert_save_allowed(
-                        f"{modality_name}_de_{group1}_vs_{group2}.h5ad"
-                    )
+                    data_manager._assert_save_allowed(f"{de_modality_name}.h5ad")
 
             logger.info(
                 f"Running DE analysis on '{modality_name}': "
@@ -1404,8 +1429,7 @@ def de_analysis_expert(
                     de_stats["de_results_key"],
                     "adata_de" if internal_method == "deseq2_like" else "adata",
                 )
-                # Save as new modality
-                de_modality_name = f"{modality_name}_de_{group1}_vs_{group2}"
+                # Save as new modality (name derived and checked before the analysis)
                 data_manager.store_modality(
                     name=de_modality_name,
                     adata=adata_de,
@@ -1414,7 +1438,7 @@ def de_analysis_expert(
                 )
 
                 if save_result:
-                    save_path = f"{modality_name}_de_{group1}_vs_{group2}.h5ad"
+                    save_path = f"{de_modality_name}.h5ad"
                     data_manager.save_modality(de_modality_name, save_path)
 
                 data_manager.log_tool_usage(
@@ -1437,13 +1461,13 @@ def de_analysis_expert(
 
 **Analysis Results:**
 - Comparison: {group1} ({group1_count} samples) vs {group2} ({group2_count} samples)
-- Method: {de_stats['method']}
-- Genes tested: {de_stats['n_genes_tested']:,}
-- Significant genes (padj < {alpha}): {de_stats['n_significant_genes']:,}
+- Method: {de_stats["method"]}
+- Genes tested: {de_stats["n_genes_tested"]:,}
+- Significant genes (padj < {alpha}): {de_stats["n_significant_genes"]:,}
 
 **Differential Expression Summary:**
-- Upregulated in {group2}: {de_stats['n_upregulated']} genes
-- Downregulated in {group2}: {de_stats['n_downregulated']} genes
+- Upregulated in {group2}: {de_stats["n_upregulated"]} genes
+- Downregulated in {group2}: {de_stats["n_downregulated"]} genes
 
 **Top Upregulated Genes:**
 {chr(10).join([f"- {gene}" for gene in de_stats["top_upregulated"][:5]])}
@@ -1471,6 +1495,12 @@ def de_analysis_expert(
             analysis_results["details"]["differential_expression"] = response
             return response
 
+        except WorkspaceExportError:
+            # A save target is outside the workspace: nothing was saved.
+            return WORKSPACE_EXPORT_MESSAGE
+        except InvalidModalityNameError as e:
+            # The derived result name is not one plain name (fixed reason).
+            return f"Error: {e}"
         except ManagedPathError:
             # A save target is inside the managed figure folder: nothing was saved.
             return MANAGED_EXPORT_MESSAGE
@@ -1897,7 +1927,9 @@ def de_analysis_expert(
                 status = (
                     "OK"
                     if count >= 4
-                    else "LOW POWER" if count >= 3 else "INSUFFICIENT"
+                    else "LOW POWER"
+                    if count >= 3
+                    else "INSUFFICIENT"
                 )
                 response += f"- {group}: {count} replicates ({status})\n"
             response += _replicate_summary_text(replicate_validation)
@@ -1989,11 +2021,12 @@ def de_analysis_expert(
 
             # Both save targets are checked before any analysis or store.
             if save_results:
-                assert_export_allowed(
-                    data_manager.workspace_path,
+                formula_csv = (
                     data_manager.exports_dir
-                    / f"{pseudobulk_modality}_formula_de_results.csv",
+                    / f"{pseudobulk_modality}_formula_de_results.csv"
                 )
+                assert_inside_workspace(data_manager.workspace_path, formula_csv)
+                assert_export_allowed(data_manager.workspace_path, formula_csv)
                 data_manager._assert_save_allowed(
                     f"{pseudobulk_modality}_with_formula_results.h5ad"
                 )
@@ -2192,6 +2225,9 @@ def de_analysis_expert(
 
             return response
 
+        except WorkspaceExportError:
+            # A save target is outside the workspace: nothing was saved.
+            return WORKSPACE_EXPORT_MESSAGE
         except ManagedPathError:
             # A save target is inside the managed figure folder: nothing was saved.
             return MANAGED_EXPORT_MESSAGE
@@ -3034,6 +3070,9 @@ def de_analysis_expert(
             output_path_obj = Path(output_path)
             if not output_path_obj.is_absolute():
                 output_path_obj = data_manager.exports_dir / output_path_obj
+            # The destination stays inside the workspace (or a listed export root).
+            if outside_workspace(data_manager.workspace_path, output_path_obj):
+                return WORKSPACE_EXPORT_MESSAGE
             # Figures are saved only through the trusted save step: check the
             # caller's (unresolved) destination, and every folder its recursive
             # creation can make, before anything is created.
@@ -3045,6 +3084,8 @@ def de_analysis_expert(
                 return MANAGED_EXPORT_MESSAGE
             output_path_obj.parent.mkdir(parents=True, exist_ok=True)
             output_path = str(output_path_obj.resolve())
+            if outside_workspace(data_manager.workspace_path, output_path):
+                return WORKSPACE_EXPORT_MESSAGE
             if export_refused(
                 data_manager.workspace_path, output_path_obj, output_path
             ):
@@ -3080,7 +3121,7 @@ def de_analysis_expert(
                     "results_df = results_df.sort_values({{ sort_by | string | repr }})\n"
                     "results_df.to_{{ output_format }}({{ output_path | string | repr }}, index=True)"
                 ),
-                imports=["pandas"],
+                imports=["import pandas as pd"],
             )
 
             data_manager.log_tool_usage(
@@ -3107,8 +3148,8 @@ def de_analysis_expert(
 - Sorted by: {sort_by}
 - Output: {output_path}
 
-**Columns:** {', '.join(results_df.columns.tolist()[:8])}{'...' if len(results_df.columns) > 8 else ''}
-**Filtered only:** {'Yes' if filtered_only else 'No'}"""
+**Columns:** {", ".join(results_df.columns.tolist()[:8])}{"..." if len(results_df.columns) > 8 else ""}
+**Filtered only:** {"Yes" if filtered_only else "No"}"""
 
             return response
 
@@ -3189,6 +3230,9 @@ def de_analysis_expert(
             if group2 not in available_groups_str:
                 return f"Group '{group2}' not found in '{group_key}'. Available: {available_groups}"
 
+            # The result name carries the group labels: encoded and checked first.
+            de_modality_name = _de_result_name(modality_name, group1, group2)
+
             # Ensure string type matching
             if group1 not in available_groups:
                 adata.obs[group_key] = adata.obs[group_key].astype(str)
@@ -3223,8 +3267,7 @@ def de_analysis_expert(
             if refusal:
                 return refusal
             adata_de.uns["de_current_results_key"] = de_stats["de_results_key"]
-            # Store result modality
-            de_modality_name = f"{modality_name}_de_{group1}_vs_{group2}"
+            # Store result modality (name derived and checked before the analysis)
             data_manager.store_modality(
                 name=de_modality_name,
                 adata=adata_de,
@@ -3292,7 +3335,7 @@ def de_analysis_expert(
 **Method:** DESeq2-like bulk differential expression
 
 **Results:**
-- Genes tested: {de_stats.get('n_genes_tested', 'N/A'):,}
+- Genes tested: {de_stats.get("n_genes_tested", "N/A"):,}
 - Significant genes (padj < {alpha}): {n_sig:,}
 - Upregulated in {group2}: {n_up:,}
 - Downregulated in {group2}: {n_down:,}
@@ -3320,6 +3363,9 @@ def de_analysis_expert(
 
             return response
 
+        except InvalidModalityNameError as e:
+            # The derived result name is not one plain name (fixed reason).
+            return f"Error: {e}"
         except (BulkRNASeqError, ModalityNotFoundError) as e:
             logger.error(f"Error in bulk DE direct: {e}")
             return f"Error in bulk DE analysis: {str(e)}"
@@ -3498,7 +3544,7 @@ def de_analysis_expert(
 - DE results: {de_results_key}
 - Ranking metric: {ranking_metric}
 - Genes ranked: {len(ranked_df):,}
-- Databases: {', '.join(db_list)}
+- Databases: {", ".join(db_list)}
 - Organism: {organism}
 
 **Results:**
@@ -3688,12 +3734,19 @@ def de_analysis_expert(
             targets = [output_path_obj]
             if output_format == "xlsx":
                 targets.append(Path(str(output_path_obj).replace(".xlsx", ".csv")))
+            # Every target stays inside the workspace (or a listed export root).
+            if outside_workspace(data_manager.workspace_path, *targets):
+                return WORKSPACE_EXPORT_MESSAGE
             if export_refused(data_manager.workspace_path, *targets):
                 return MANAGED_EXPORT_MESSAGE
             if output_format == "xlsx":
                 # ...and the name exactly as the late fallback derives it; a path
                 # that cannot be resolved is refused with the same fixed message.
                 fallback = _resolved_csv_fallback(output_path_obj)
+                if fallback is not None and outside_workspace(
+                    data_manager.workspace_path, fallback
+                ):
+                    return WORKSPACE_EXPORT_MESSAGE
                 if fallback is None or export_refused(
                     data_manager.workspace_path, fallback
                 ):
@@ -3705,6 +3758,8 @@ def de_analysis_expert(
                 return MANAGED_EXPORT_MESSAGE
             output_path_obj.parent.mkdir(parents=True, exist_ok=True)
             output_path = str(output_path_obj.resolve())
+            if outside_workspace(data_manager.workspace_path, output_path):
+                return WORKSPACE_EXPORT_MESSAGE
             if export_refused(data_manager.workspace_path, *targets, output_path):
                 return MANAGED_EXPORT_MESSAGE
 
@@ -3714,6 +3769,8 @@ def de_analysis_expert(
                 except ImportError:
                     output_format = "csv"
                     output_path = output_path.replace(".xlsx", ".csv")
+                    if outside_workspace(data_manager.workspace_path, output_path):
+                        return WORKSPACE_EXPORT_MESSAGE
                     if export_refused(data_manager.workspace_path, output_path):
                         return MANAGED_EXPORT_MESSAGE
                     results_df.to_csv(output_path, index=True)
@@ -3748,7 +3805,7 @@ def de_analysis_expert(
                     "results_df = results_df.sort_values('padj')\n"
                     "results_df.to_{{ output_format }}({{ output_path | string | repr }}, index=True)"
                 ),
-                imports=["pandas"],
+                imports=["import pandas as pd"],
             )
 
             data_manager.log_tool_usage(
@@ -3780,10 +3837,10 @@ def de_analysis_expert(
 - Format: {output_format.upper()}
 - Output: {output_path}
 
-**LFC Shrinkage:** {'Applied' if shrinkage_applied else 'Not applied'}
-{f'- Note: {shrinkage_note}' if shrinkage_note else ''}
+**LFC Shrinkage:** {"Applied" if shrinkage_applied else "Not applied"}
+{f"- Note: {shrinkage_note}" if shrinkage_note else ""}
 
-**Publication Columns:** {', '.join(pub_cols)}
+**Publication Columns:** {", ".join(pub_cols)}
 
 **File ready for publication supplementary tables.**"""
 

{lobster_transcriptomics-1.2.0 → lobster_transcriptomics-1.2.2}/lobster/agents/transcriptomics/prompts.py

@@ -144,8 +144,8 @@ Do NOT describe delegation, do NOT ask permission -- execute the tool call.
 4. select_variable_features("modality_filtered_normalized") # HVG/deviance selection
 5. run_pca("modality_..._hvg_selected")                   # PCA reduction
 6. integrate_batches("modality_..._pca", batch_key="...")  # If multi-sample
-7. compute_neighbors_and_embed("modality_..._integrated")  # Neighbor graph + UMAP
-8. cluster_cells("modality_..._embedded", resolution=0.5)  # Leiden clustering (or algorithm="louvain" if specified)
+7. compute_neighbors_and_embed("chosen_prepared_modality", use_rep="actual_obsm_key") # Use returned representation key
+8. cluster_cells("chosen_prepared_modality", use_rep="actual_obsm_key", batch_correction=False, resolution=0.5) # Reuse; do not rerun upstream
 9. find_marker_genes("modality_clustered", groupby="leiden") # Cluster markers
 10. handoff_to_annotation_expert(...)                       # If annotation requested
 ```
@@ -153,6 +153,23 @@ Do NOT describe delegation, do NOT ask permission -- execute the tool call.
 NOTE: cluster_cells can also perform steps 4-9 automatically as a full pipeline.
 Use composable tools when user asks for specific steps; use cluster_cells for full pipeline.
 
+**Prepared clustering contract:** If the caller already prepared PCA, explicitly name
+that modality and use_rep='X_pca'; pass requested n_neighbors/n_pcs. Only the first
+n_pcs components are used. Do not repeat normalization, HVG selection, scaling or PCA.
+A modality name suffix is not evidence that an embedding exists or is scientifically
+fresh: inspect actual obsm keys. Missing/incompatible representations or unhonorable
+explicit dimensions require refusal, not a silent full-pipeline fallback or clamp.
+For **HVG-only** prepared data without PCA, call composable run_pca on the named
+selected modality first, then cluster its returned modality with use_rep='X_pca'.
+Disclose that PCA was computed, not reused. Unset clustering dimensions resolve the
+ordinary 15/30; dimension-driven implicit adjustments must be disclosed. Explicit
+values are never demo-capped. Read actual applied-parameter JSON and recorded IR,
+not schema/request values, when reporting what ran. Never fabricate an applied HVG
+feature count/flavor: full-pipeline exact HVG requests are unsupported; use the
+explicit selection/PCA/reuse workflow. Prepared reuse skips unrequested batch
+correction and says why; explicit batch correction AND a named prepared representation
+refuse together. If correction is needed, do it before preparing/naming the representation.
+
 ## Bulk Standard Workflow (6 steps)
 
 ```
@@ -210,6 +227,36 @@ Report: data_type, n_genes, n_cells/n_samples, mito_pct, n_filtered, cluster_siz
 If batch_silhouette > 0.3 or median_lisi < 1.5, flag for re-integration.
 </Response_Format>
 
+<Scientific_Reporting_Contract>
+- Report dataset-specific numbers only from tool output for the stated cohort. Never infer
+  medians, percentiles, exceedance counts or filtering impact from means/default pass counts.
+- If a requested value is absent, say NOT COMPUTED and offer to compute it; "~" is not evidence.
+- Pass requested thresholds unchanged. Report applied parameters from the tool's actual result,
+  not from the user's request, a standard workflow or an earlier modality's configuration.
+- Requested-but-unsupported parameters or extra operations: refuse or explicitly state NOT
+  SUPPORTED; never claim they were applied. Exact requests take precedence over default workflows.
+- Report every actually applied filter, including explicit optional-filter disabled states.
+  Criterion failures are independent on the original pre-filter cohort: do not sum them.
+  Report combined actual removals separately, and distinguish gene counts from observation counts.
+- State the real raw-count storage location returned by the tool. adata.raw is not a counts layer.
+- The supervisor must preserve these numeric/cohort/applied-parameter limitations when reformulating.
+- SC markers: original ranked genes, specificity-filtered candidates and FDR-significant genes
+  are different sets. Use the tool's explicit original/filtered/display keys, executed groups
+  and aligned counts; never label original rankings as filtered or automatically significant.
+- Disclose actual Scanpy specificity operators/units: positive log2FC > min_fold_change,
+  in-group fraction > min_pct, out-group fraction < max_out_pct, compare_abs=False.
+  The legacy 1.5 threshold is log2FC, not linear fold-change. No FDR criterion is applied there.
+- Supported adjusted p-values must be interpreted using an explicitly stated criterion.
+  Absent statistics are NOT COMPUTED, not zero discoveries; nonfinite values are separate flags.
+  Finite extreme abs(log2FC) flags use the tool's diagnostic threshold, without clipping,
+  reranking or a significance claim. Near-zero reference expression
+  can amplify Scanpy's approximate effect size; an extreme value alone proves neither a
+  statistical effect nor a computation error.
+- Cell-level cluster-versus-rest markers are exploratory. Single-donor cells are not independent
+  donor replicates and do not establish patient/condition effects; require a biological-unit
+  design before such claims. Do not infer uncomputed donor counts from the dataset name.
+</Scientific_Reporting_Contract>
+
 <Important_Rules>
 1. **ALWAYS call check_data_status() first** to understand data type and column names
 2. **NEVER assume column names** (leiden, batch, etc.) -- always verify via check_data_status
@@ -387,6 +434,12 @@ You report results back to the parent agent, not directly to users.
 - One donor per condition cannot support a statistical comparison (pseudoreplication): refuse the DE and explain why, even when that donor has several libraries
 - LFC shrinkage is recommended for publication (use extract_and_export_de_results with shrink_lfc=True)
 - GSEA requires sufficient DE genes; run after run_differential_expression, run_de_with_formula, or run_bulk_de_direct
+- Interpretation: ranked, specificity-filtered and FDR-significant genes are distinct sets.
+  Name the exact results key and actually applied adjusted-p criterion before claiming
+  significance; a large absolute log2FC alone is insufficient. Absent statistics are
+  NOT COMPUTED, not zero discoveries; flag nonfinite values separately without changing them.
+- Do not turn exploratory single-donor cell-level cluster markers into patient/condition
+  effects. Independent biological units and an appropriate design remain required.
 </Critical_Scientific_Requirements>
 
 <Available_Tools>