omicstra 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- omicstra-1.0.0/.gitignore +99 -0
- omicstra-1.0.0/LICENSE +21 -0
- omicstra-1.0.0/PKG-INFO +397 -0
- omicstra-1.0.0/README.md +353 -0
- omicstra-1.0.0/pyproject.toml +90 -0
- omicstra-1.0.0/server.json +74 -0
- omicstra-1.0.0/src/omicstra/__init__.py +3 -0
- omicstra-1.0.0/src/omicstra/adapters/__init__.py +5 -0
- omicstra-1.0.0/src/omicstra/adapters/wang_st.py +147 -0
- omicstra-1.0.0/src/omicstra/agents/__init__.py +6 -0
- omicstra-1.0.0/src/omicstra/agents/modality.py +202 -0
- omicstra-1.0.0/src/omicstra/artifacts.py +30 -0
- omicstra-1.0.0/src/omicstra/cli.py +431 -0
- omicstra-1.0.0/src/omicstra/configs/compute_contract.json +122 -0
- omicstra-1.0.0/src/omicstra/configs/data_contract.json +517 -0
- omicstra-1.0.0/src/omicstra/configs/eda_contract.json +199 -0
- omicstra-1.0.0/src/omicstra/configs/routing_contract.json +154 -0
- omicstra-1.0.0/src/omicstra/contracts/__init__.py +16 -0
- omicstra-1.0.0/src/omicstra/contracts/eda.py +71 -0
- omicstra-1.0.0/src/omicstra/contracts/project.py +116 -0
- omicstra-1.0.0/src/omicstra/contracts/routing.py +49 -0
- omicstra-1.0.0/src/omicstra/eda.py +284 -0
- omicstra-1.0.0/src/omicstra/figures.py +136 -0
- omicstra-1.0.0/src/omicstra/graph.py +187 -0
- omicstra-1.0.0/src/omicstra/graphs/__init__.py +10 -0
- omicstra-1.0.0/src/omicstra/graphs/eda.py +202 -0
- omicstra-1.0.0/src/omicstra/graphs/route.py +151 -0
- omicstra-1.0.0/src/omicstra/mcp/__init__.py +1 -0
- omicstra-1.0.0/src/omicstra/mcp/server.py +426 -0
- omicstra-1.0.0/src/omicstra/measures/__init__.py +402 -0
- omicstra-1.0.0/src/omicstra/protocols/__init__.py +159 -0
- omicstra-1.0.0/src/omicstra/protocols/align.py +336 -0
- omicstra-1.0.0/src/omicstra/protocols/eda.py +181 -0
- omicstra-1.0.0/src/omicstra/protocols/evaluate.py +48 -0
- omicstra-1.0.0/src/omicstra/protocols/inventory.py +314 -0
- omicstra-1.0.0/src/omicstra/records.py +260 -0
- omicstra-1.0.0/src/omicstra/routing.py +281 -0
- omicstra-1.0.0/src/omicstra/settings.py +132 -0
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# os
|
|
2
|
+
.DS_Store
|
|
3
|
+
.DS_Store?
|
|
4
|
+
._*
|
|
5
|
+
.Spotlight-V100
|
|
6
|
+
.Trashes
|
|
7
|
+
Thumbs.db
|
|
8
|
+
|
|
9
|
+
# python
|
|
10
|
+
__pycache__/
|
|
11
|
+
*.py[cod]
|
|
12
|
+
*.egg-info/
|
|
13
|
+
dist/
|
|
14
|
+
build/
|
|
15
|
+
.eggs/
|
|
16
|
+
*.egg
|
|
17
|
+
.venv/
|
|
18
|
+
venv/
|
|
19
|
+
env/
|
|
20
|
+
|
|
21
|
+
# jupyter
|
|
22
|
+
.ipynb_checkpoints/
|
|
23
|
+
*.ipynb_checkpoints
|
|
24
|
+
|
|
25
|
+
# env
|
|
26
|
+
.env
|
|
27
|
+
.env.*
|
|
28
|
+
!.env.example
|
|
29
|
+
|
|
30
|
+
# data - large files never committed
|
|
31
|
+
data/inputs/
|
|
32
|
+
data/embeddings/
|
|
33
|
+
data/outputs/
|
|
34
|
+
runs/
|
|
35
|
+
|
|
36
|
+
# ml artifacts
|
|
37
|
+
*.pt
|
|
38
|
+
*.pth
|
|
39
|
+
*.ckpt
|
|
40
|
+
*.npy
|
|
41
|
+
*.zarr
|
|
42
|
+
*.h5
|
|
43
|
+
*.h5ad
|
|
44
|
+
*.parquet
|
|
45
|
+
|
|
46
|
+
# ide
|
|
47
|
+
.vscode/
|
|
48
|
+
.idea/
|
|
49
|
+
*.swp
|
|
50
|
+
*.swo
|
|
51
|
+
|
|
52
|
+
# langsmith / api logs
|
|
53
|
+
*.log
|
|
54
|
+
langsmith_traces/
|
|
55
|
+
docs/papers/
|
|
56
|
+
knowledge/
|
|
57
|
+
notebooks/embeddings/*.html
|
|
58
|
+
notebooks/embeddings/*.png
|
|
59
|
+
docs/TODO*
|
|
60
|
+
|
|
61
|
+
docs/tnbc92_summary.pdf
|
|
62
|
+
docs/tnbc92_three_hypotheses.pdf
|
|
63
|
+
|
|
64
|
+
.claude/
|
|
65
|
+
notebooks/final/*.html
|
|
66
|
+
|
|
67
|
+
# scratch workspaces - superseded / one-off work, kept locally as record
|
|
68
|
+
design/_scratch
|
|
69
|
+
scripts/_scratch/
|
|
70
|
+
|
|
71
|
+
# manuscript drafts - local until deliberately published
|
|
72
|
+
docs/reports/**/discussion.md
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
design/omicstra-deck-presenter.pdf
|
|
76
|
+
design/omicstra-deck.pdf
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
demo/
|
|
80
|
+
docs/deck_v3_plan.md
|
|
81
|
+
docs/deck_v4_plan.md
|
|
82
|
+
docs/deck_v5_qa.md
|
|
83
|
+
docs/talk_content.md
|
|
84
|
+
docs/deck_v4_outline.md
|
|
85
|
+
|
|
86
|
+
scripts/slurm/
|
|
87
|
+
projects/tnbc-92/talk/
|
|
88
|
+
docs/media/slides_omicstra_2026-08-18.zip
|
|
89
|
+
docs/talk_speaker_notes_2026-08-18.md
|
|
90
|
+
|
|
91
|
+
design/pseudocode/
|
|
92
|
+
# site - deployment notes for one institution. never committed.
|
|
93
|
+
# the package is site-agnostic by design; anything naming a cluster, a quota,
|
|
94
|
+
# an approval or an account belongs here, not in docs/.
|
|
95
|
+
site/
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
# a second venv that was being packaged into the sdist
|
|
99
|
+
venv_test/
|
omicstra-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nasim Sanati
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
omicstra-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,397 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: omicstra
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: multi-agent MCP server for cross-modal embedding alignment and evidence-based routing in spatial biology
|
|
5
|
+
Project-URL: Repository, https://github.com/teslajoy/omicstra
|
|
6
|
+
Project-URL: Documentation, https://teslajoy.github.io/omicstra/
|
|
7
|
+
Project-URL: DOI, https://doi.org/10.5281/zenodo.22666752
|
|
8
|
+
Project-URL: Funding, https://doi.org/10.55277/researchhub.6ou1w3h3
|
|
9
|
+
Author-email: Nasim Sanati <nasim@plenary.org>
|
|
10
|
+
License: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: bioinformatics,histopathology,mcp,model-context-protocol,multimodal,spatial-transcriptomics
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Requires-Dist: click>=8
|
|
22
|
+
Requires-Dist: langchain-core>=0.3
|
|
23
|
+
Requires-Dist: langgraph-checkpoint-sqlite>=2
|
|
24
|
+
Requires-Dist: langgraph>=1
|
|
25
|
+
Requires-Dist: mcp>=2
|
|
26
|
+
Requires-Dist: pydantic-settings>=2
|
|
27
|
+
Requires-Dist: pydantic>=2
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: build; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest; extra == 'dev'
|
|
31
|
+
Requires-Dist: ruff; extra == 'dev'
|
|
32
|
+
Provides-Extra: encode
|
|
33
|
+
Requires-Dist: novae>=1.0; extra == 'encode'
|
|
34
|
+
Requires-Dist: scanpy>=1.10; extra == 'encode'
|
|
35
|
+
Requires-Dist: timm>=1.0; extra == 'encode'
|
|
36
|
+
Requires-Dist: torch>=2.2; extra == 'encode'
|
|
37
|
+
Provides-Extra: measure
|
|
38
|
+
Requires-Dist: anndata>=0.10; extra == 'measure'
|
|
39
|
+
Requires-Dist: numpy>=1.26; extra == 'measure'
|
|
40
|
+
Requires-Dist: pandas>=2; extra == 'measure'
|
|
41
|
+
Requires-Dist: scikit-learn>=1.3; extra == 'measure'
|
|
42
|
+
Requires-Dist: scipy>=1.11; extra == 'measure'
|
|
43
|
+
Description-Content-Type: text/markdown
|
|
44
|
+
|
|
45
|
+
# omic<span style="color:#5DCAA5">stra</span>
|
|
46
|
+
|
|
47
|
+
a multi-agent MCP server for cross-modal embedding alignment and evidence-based routing in spatial biology. it exposes fixed scientific protocols as tools and returns evidence; the client holds the model. alignments are evaluated against declared metrics, and questions are routed from a cohort's own recorded evidence, refusing when that evidence is absent. foundation model encoders are pluggable; integration strategy is a configurable experimental dimension, not a fixed pipeline choice.
|
|
48
|
+
|
|
49
|
+
the seed implementation evaluates 92 TNBC patients from [Wang et al. 2024](https://www.nature.com/articles/s41467-024-54145-w) using H&E morphology (Virchow2 primary, UNI2 swap) and spatial transcriptomics (Novae GNN).
|
|
50
|
+
|
|
51
|
+
[](https://doi.org/10.5281/zenodo.22666752)
|
|
52
|
+
|
|
53
|
+
`v1.0` `ResearchHub Foundation grant` `Brenden-Colson Center / Sears Lab, OHSU` `MIT`
|
|
54
|
+
|
|
55
|
+
**v1.0** ships the read path (inventory, EDA, admissibility gate, routing) over
|
|
56
|
+
stdio and HTTP, the alignment and evaluation stages verified bit-identical
|
|
57
|
+
against the published grid, and the seed cohort's evidence pack in the repo, so a
|
|
58
|
+
fresh clone can route without training anything. The package itself ships no
|
|
59
|
+
cohort: `pip install omicstra` gets the contracts, and you point it at a cohort
|
|
60
|
+
directory.
|
|
61
|
+
|
|
62
|
+
**v1.1** is `omicstra run`: embeddings extracted here rather than resolved, the
|
|
63
|
+
niche join, H1/H2/H3 as a chain, and a promotion step where a person approves the
|
|
64
|
+
pack, with the report rendered from a cohort-agnostic template. Laptop-only for
|
|
65
|
+
both.
|
|
66
|
+
|
|
67
|
+
That report is a **template, not this cohort's report**. The renderer takes a
|
|
68
|
+
pack and a record ledger and knows nothing about tnbc-92 - sections appear
|
|
69
|
+
because a record exists, so a cohort that never ran H3 has no H3 section and says
|
|
70
|
+
why. That is what makes a second cohort's report free: same code, different
|
|
71
|
+
declarations. See `design/v1_1_scope.md`.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## hypotheses
|
|
76
|
+
|
|
77
|
+
| | | metrics |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| H1 | aligned embeddings retrieve better cross-modal matches than any unaligned baseline | Recall@K - MRR - CKA |
|
|
80
|
+
| H2 | manifold alignment preserves biological structure better than either modality alone | ARI - silhouette - UMAP |
|
|
81
|
+
| H3 | shared space encodes interpretable biological pathway signals | CCA - spatial maps |
|
|
82
|
+
|
|
83
|
+
early vs late fusion is an experimental variable, not an assumption.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## seed cohort results (v3, 10-run grid)
|
|
88
|
+
|
|
89
|
+
live report: **[teslajoy.github.io/omicstra/reports/internal/tnbc-92/](https://teslajoy.github.io/omicstra/reports/internal/tnbc-92/)**
|
|
90
|
+
|
|
91
|
+
evaluated on **35,594 niches across 14 held-out TNBC patients** (zero patient leakage across train / val / test). 6 contrastive runs (R1-R6) + 4 classical baselines (B1-B4):
|
|
92
|
+
|
|
93
|
+
- **H1 (cross-modal retrieval).** R4 wins. AUC 0.859 (95% CI 0.855-0.862). R4 is the only run using cross-attention - the other 5 contrastive runs use late fusion (mean-pooled H&E + independent MLPs).
|
|
94
|
+
- **H2 (biology preservation).** Split outcome. Late-fusion contrastive (R1, R6) wins K-means MC ARI; R4 still encodes MC biology at linear-probe parity. KMeans-ARI is geometry-biased - load-bearing diagnostic is the linear probe.
|
|
95
|
+
- **H3 (pathway transfer).** R4 wins again. 15/15 cells BH-FDR < 0.05 cross-patient (Welch z 3.8-5.7). At DAG resolution, R4 stays best (78% sig nodes) on clinically interpretable hits: BTLA checkpoint, IL signaling, IFN regulation, ECM collagen biology.
|
|
96
|
+
|
|
97
|
+
**R4 = the only non-late-fusion run** (cross-attention between the niche's 7 Virchow2 tile tokens and the 576-d ST vector). H1 + H3 both reward keeping local morphological heterogeneity un-pooled. See report for the full proposal-alignment matrix and 95% CIs.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## the loop
|
|
102
|
+
|
|
103
|
+
a **level** is what code is allowed to do (LEVEL 0/1/2 in the tree below); the
|
|
104
|
+
**loop** is the order a cohort goes through. they are different axes and the
|
|
105
|
+
words are easy to confuse:
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
layer 0: EDA (gate)
|
|
109
|
+
is data usable? quality? signal? modalities alignable?
|
|
110
|
+
-> proceed / proceed with caution / stop
|
|
111
|
+
|
|
112
|
+
layer 1: pipeline (execution)
|
|
113
|
+
embed -> align -> eval
|
|
114
|
+
fixed protocol, deterministic with seed
|
|
115
|
+
|
|
116
|
+
layer 2: karpathy loop (outer optimization)
|
|
117
|
+
editable asset: alignment_config.json
|
|
118
|
+
scalar metric: Recall@K or MRR (fixed)
|
|
119
|
+
proposes config -> runs pipeline -> scores -> keeps or discards
|
|
120
|
+
output: git log of validated decisions + winner.json
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
program.md defines search space, constraints, stopping criteria.
|
|
124
|
+
|
|
125
|
+
embedding dimensions: Virchow2 1280d (primary) / UNI2 1536d (alternative) - Novae GNN 64d (novae_latent) -> shared 512d
|
|
126
|
+
|
|
127
|
+
alignment strategies (experimental variable):
|
|
128
|
+
```
|
|
129
|
+
late interaction - tiles aggregated per spot (mean/max),
|
|
130
|
+
then independent MLPs -> shared 512d (InfoNCE)
|
|
131
|
+
early interaction - tile-level cross-attention between H&E tokens
|
|
132
|
+
and ST spot before projection (~4M params, local K tiles)
|
|
133
|
+
comparison: does tile-level morphological detail lost at aggregation
|
|
134
|
+
matter for cross-modal alignment quality?
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## repo structure
|
|
140
|
+
|
|
141
|
+
audited against the filesystem 2026-09-09. `·` is built, `○` is named in the design and **not yet built** - kept here because the name is referenced elsewhere, not because it exists.
|
|
142
|
+
|
|
143
|
+
```
|
|
144
|
+
omicstra/
|
|
145
|
+
│
|
|
146
|
+
· CLAUDE.md # north star for Claude Code
|
|
147
|
+
· EDA.md # gate - data quality checks before pipeline
|
|
148
|
+
· PLAN_RULES.md # constraints - no alignment until EDA passes
|
|
149
|
+
· MODELS.md # training provenance + tissue compatibility per model
|
|
150
|
+
· MODALITY_TEMPLATE.md # the contract a new modality generates against
|
|
151
|
+
· CITATION.cff server.json # citation metadata - MCP registry entry
|
|
152
|
+
· .mcp.json .env.example # MCP server entry - optional tracing only
|
|
153
|
+
│
|
|
154
|
+
· design/ # the planning tree - tracked, this is where "what next" lives
|
|
155
|
+
│ · v1_1_scope.md # the NEXT release's boundary. read before adding
|
|
156
|
+
│ · mcp_plan.md workflow.md # engineering plan - the executable graph
|
|
157
|
+
│ · decisions.md # what is decided, and by whom
|
|
158
|
+
│ · progress.md status.md # build log - repo snapshot
|
|
159
|
+
│
|
|
160
|
+
· src/omicstra/ # the pip-installable package - src layout
|
|
161
|
+
│ · graph.py # LEVEL 0 - the only entry, the only checkpointer
|
|
162
|
+
│ · graphs/ # LEVEL 1 - one per gate, each can interrupt()
|
|
163
|
+
│ │ · eda.py # inventory -> profile -> gate -> escalate
|
|
164
|
+
│ │ · route.py # orchestrator -> 3 agents -> judge -> ask_human
|
|
165
|
+
│ │ ○ encode.py promote.py # v1.1 - compute, and the reviewed evidence step
|
|
166
|
+
│ · protocols/ # LEVEL 2 - order, applicability, authority. no maths
|
|
167
|
+
│ │ · inventory.py # 8 steps: files .. bind - "what is this data"
|
|
168
|
+
│ │ · eda.py # 10 checks registered - "is it usable"
|
|
169
|
+
│ │ · align.py # 4 stages. resolve-only; compute is v1.1
|
|
170
|
+
│ │ · evaluate.py # 6 guards - becomes a chain in v1.1
|
|
171
|
+
│ · measures/__init__.py # the MATHS. pure functions, no ctx, no order,
|
|
172
|
+
│ │ # no authority. callable from a notebook
|
|
173
|
+
│ · contracts/ # READS a declaration, decides nothing
|
|
174
|
+
│ │ · project.py # a cohort's project.json
|
|
175
|
+
│ │ · routing.py eda.py # contract + evidence · contract + calibration
|
|
176
|
+
│ · configs/ # the CONTRACTS, inside the wheel so an
|
|
177
|
+
│ │ · data_contract.json # installed server can find them. 8 declared
|
|
178
|
+
│ │ · eda_contract.json # roles · which checks, which criteria
|
|
179
|
+
│ │ · routing_contract.json # task taxonomy, outcome vocabulary, rules
|
|
180
|
+
│ │ · compute_contract.json # 6 gates: 5 preflight, 1 mid-run
|
|
181
|
+
│ · adapters/wang_st.py # a cohort's files -> AnnData conforming to raw_counts
|
|
182
|
+
│ · agents/modality.py # he / st / pathway agents - read recorded evidence
|
|
183
|
+
│ · mcp/server.py # 8 tools, 3 resources, stdio + http. zero model calls
|
|
184
|
+
│ · records.py artifacts.py # the record contract - inventory/eda_summary io
|
|
185
|
+
│ · settings.py cli.py # 8 commands. settings imports nothing from omicstra
|
|
186
|
+
│ · routing.py eda.py figures.py # resolve + ledger · gate · plots
|
|
187
|
+
│
|
|
188
|
+
│ the rule: a thing gets its own graph only if it can ask a human;
|
|
189
|
+
│ everything else is a protocol. a new .py never lands in src/omicstra/ directly.
|
|
190
|
+
│
|
|
191
|
+
· configs/v3/ # R1_v3 .. R6_v3 run configs (cohort runs, not contracts)
|
|
192
|
+
│
|
|
193
|
+
· projects/ # committed - one directory per cohort
|
|
194
|
+
│ · {project_id}/
|
|
195
|
+
│ · project.json program.md # encoders, runs, metric · search space + constraints
|
|
196
|
+
│ · cohort.json # DECLARED: subject_id_column, classification,
|
|
197
|
+
│ │ # compute_backend, client_model_backend - fail closed
|
|
198
|
+
│ · platform.json # DECLARED per sample: platform, position_columns, pitch
|
|
199
|
+
│ · inventory.json # inventory protocol output - conformance report
|
|
200
|
+
│ · eda_summary.json # EDA gate output
|
|
201
|
+
│ · routing_evidence.json # this cohort's measured evaluation - never inherited
|
|
202
|
+
│
|
|
203
|
+
· site/{institution}/ [ignored] # compute.md governance.md - served as MCP resources
|
|
204
|
+
· scripts/ # the chain behind the published results
|
|
205
|
+
· tests/ # 114 - conformance, routing, eda authority
|
|
206
|
+
│ · fixtures/ # the pinned H1 summary, sha-guarded
|
|
207
|
+
· knowledge/reactome/ # shared domain assets - committed
|
|
208
|
+
· docs/ # -> teslajoy.github.io/omicstra
|
|
209
|
+
· notebooks/ # exploration - embeddings - experiments - final
|
|
210
|
+
· runs/ data/ demo/ [ignored] # traces - inputs + embeddings - talk assets
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
## extending to a new modality
|
|
216
|
+
|
|
217
|
+
`MODALITY_TEMPLATE.md` is the contract a new modality agent (single-cell, protein, electron microscopy, etc.) must satisfy: a frozen foundation-model encoder, a niche-aggregation step, a clean ST/H&E-equivalent feature parquet shape, and the construct-validity guards the eval agent enforces. each modality adds one row to the alignment grid and one entry to the routing contract.
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## seed cohort
|
|
222
|
+
|
|
223
|
+
[Wang et al. 2024](https://www.nature.com/articles/s41467-024-54145-w) - 92 TNBC patients, co-registered ST + H&E WSI. platform: original Spatial Transcriptomics (Stahl et al. 2016, KTH/Spatial Transcriptomics AB, acquired by 10x Genomics 2018) - 1934 spots/array, 100um diameter, 150um center-to-center. not 10x Visium.
|
|
224
|
+
|
|
225
|
+
> corrected 2026-08-12: previously read 200um center-to-center. Wang 2024 Methods states 150um and the lattice measures to it - nearest neighbour 161.6 px with the (+2,0)/(0,+2) offsets at 216/240 px, i.e. NN x sqrt(2), so NN is centre-to-centre. at 150um that is 0.93 um/px and the array spans 6.5 x 6.9 mm, matching the stated capture area; at 200um it would span 8.7 x 9.2 mm, which no ST array is.
|
|
226
|
+
|
|
227
|
+
| resource | url |
|
|
228
|
+
|---|---|
|
|
229
|
+
| processed data | [doi:10.5281/zenodo.14204217](https://doi.org/10.5281/zenodo.14204217) (mc-labels release also at [doi:10.5281/zenodo.8135721](https://doi.org/10.5281/zenodo.8135721)) |
|
|
230
|
+
| original analysis code | [BCTL-Bordet/ST](https://github.com/BCTL-Bordet/ST) |
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## quick start
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
pip install omicstra # serves, routes, gates - no numpy, no tensor libraries
|
|
238
|
+
pip install "omicstra[measure]" # + the numerics, for computing inventory and EDA steps
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
omicstra ships no model and no client: any MCP client supplies the model. OHSU
|
|
242
|
+
runs it behind a pydantic-ai front on ARC with Bedrock, and that front is a
|
|
243
|
+
separate package. the server holds no key and makes no outbound call.
|
|
244
|
+
|
|
245
|
+
the package ships its contracts and no cohort. point it at one:
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
export OMICSTRA_PROJECT_DIR=/path/to/projects/tnbc-92
|
|
249
|
+
omicstra selftest # start here: asserts the routing rules hold on this cohort
|
|
250
|
+
omicstra describe # what the cohort declares - platform, encoders, roles
|
|
251
|
+
omicstra families # which questions it can answer, and which it cannot yet
|
|
252
|
+
omicstra route cross_modal_retrieval
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
`omicstra --help` lists all eight: `selftest`, `describe`, `families`, `route`,
|
|
256
|
+
`gate`, `eda`, `decisions`, `init`. **`selftest` first** - it tells a new cohort
|
|
257
|
+
owner whether their declarations and evidence hang together before they spend
|
|
258
|
+
time on anything else.
|
|
259
|
+
|
|
260
|
+
**stdio** - the usual client config:
|
|
261
|
+
|
|
262
|
+
```json
|
|
263
|
+
{ "mcpServers": { "omicstra": {
|
|
264
|
+
"command": "python", "args": ["-c", "from omicstra.mcp.server import serve; serve()"],
|
|
265
|
+
"env": { "OMICSTRA_PROJECT_DIR": "/path/to/projects/tnbc-92" } } } }
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
**streamable-http** - `serve(mode="http")`, then note the envelope:
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
curl -s -X POST http://127.0.0.1:8000/mcp \
|
|
272
|
+
-H 'Content-Type: application/json' \
|
|
273
|
+
-H 'Accept: application/json, text/event-stream' \
|
|
274
|
+
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
|
|
275
|
+
"io.modelcontextprotocol/protocolVersion":"2026-07-28",
|
|
276
|
+
"io.modelcontextprotocol/clientCapabilities":{}}}}'
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
the `_meta` block is not optional and is the first thing a new http caller gets
|
|
280
|
+
wrong. protocol revision 2026-07-28 removed the initialize handshake, so the
|
|
281
|
+
version travels on **every** request rather than being negotiated once. a call
|
|
282
|
+
without it is refused with `-32602`, naming the two keys it wants.
|
|
283
|
+
|
|
284
|
+
a cohort with no evidence pack is **not routable**, and the compute path refuses
|
|
285
|
+
rather than improvising: `route` declines instead of inheriting another cohort's
|
|
286
|
+
winner, and `run_align` raises `ComputeUnavailable` naming the missing artifact
|
|
287
|
+
and the script that builds it. that refusal is the expected first response on a
|
|
288
|
+
fresh install, not a failure.
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
## stack
|
|
293
|
+
|
|
294
|
+
| layer | tool |
|
|
295
|
+
|---|---|
|
|
296
|
+
| orchestration | LangGraph StateGraph |
|
|
297
|
+
| model | supplied by the MCP client; the server ships none |
|
|
298
|
+
| tracing | OpenTelemetry-ready; LangSmith optional via env, not a dependency |
|
|
299
|
+
| resources | `omicstra://eda-contract`, `routing-contract`, `project/{id}/routing-evidence` |
|
|
300
|
+
| H&E foundation model | Virchow2 (primary, 1280-d) - UNI2 as swap (1536-d) |
|
|
301
|
+
| ST foundation model | Novae GNN |
|
|
302
|
+
| pathway | gpath2vec + biological pathway embeddings |
|
|
303
|
+
| alignment | contrastive MLP + cross-attention bridge |
|
|
304
|
+
| compute | laptop (v1.0); SLURM planned |
|
|
305
|
+
| interface | Model Context Protocol |
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## reproducibility
|
|
310
|
+
|
|
311
|
+
every run writes `runs/{project_id}/{run_id}/` - config, QC, embeddings, alignment, evaluation, synthesis. `notebooks/final/` contains the best run as a notebook, drafted with a model from the run trace and reviewed by hand; reruns go top-to-bottom with a fixed seed.
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
## deliverables
|
|
316
|
+
|
|
317
|
+
- [x] v3 10-run alignment grid on TNBC-92 ([live report](https://teslajoy.github.io/omicstra/reports/internal/tnbc-92/))
|
|
318
|
+
- [x] pip-installable MCP server (MIT) - verified on python 3.11 / 3.12 / 3.14
|
|
319
|
+
- [ ] alignment checkpoint + model card (Hugging Face)
|
|
320
|
+
- [ ] embeddings and niche join deposited (Zenodo)
|
|
321
|
+
- [ ] second-modality plug-in via `MODALITY_TEMPLATE.md` (target: CODA or CyCIF)
|
|
322
|
+
|
|
323
|
+
---
|
|
324
|
+
|
|
325
|
+
## how the evidence pack is produced
|
|
326
|
+
|
|
327
|
+
The router reads `projects/{id}/routing_evidence.json`. **No script writes it.**
|
|
328
|
+
|
|
329
|
+
```
|
|
330
|
+
eval summaries ──▶ proposed evidence deterministic: winners, margins, refusals
|
|
331
|
+
──▶ a person reviews, edits the notes, approves
|
|
332
|
+
──▶ routing_evidence.json
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
Deciding which metric answers which task family, what the floors are, and which
|
|
336
|
+
caveat attaches to which candidate is editorial work - the file's own notes
|
|
337
|
+
argue with the report in places. Generating it would invent the judgements it
|
|
338
|
+
records, so `run_eval` scores the grid and **resolves** the pack; it never
|
|
339
|
+
produces one.
|
|
340
|
+
|
|
341
|
+
**In v1.0 that promotion step is manual and recorded in `docs/`. In v1.1 it is
|
|
342
|
+
`omicstra promote`** - a gate, not a protocol, because it asks a person.
|
|
343
|
+
|
|
344
|
+
The acceptance test for the port is pinned in `tests/fixtures/`: a full-grid
|
|
345
|
+
rerun with one retrained baseline reproduced every numeric field of the H1
|
|
346
|
+
summary, and the fixture is checked against the evidence pack so the router can
|
|
347
|
+
never quote a number nothing produced.
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## declared deviation from the proposal
|
|
352
|
+
|
|
353
|
+
The registered report put a model **inside** the orchestration: one model for
|
|
354
|
+
intent classification and routing, another for hypothesis evaluation, with
|
|
355
|
+
conditional routing in the graph.
|
|
356
|
+
|
|
357
|
+
**The build moved the model to the client and made routing a deterministic rule
|
|
358
|
+
over evidence.** The server holds no model, generates no code, and executes
|
|
359
|
+
nothing a model wrote. A model has three narrow jobs, all on the client side:
|
|
360
|
+
classify a question into a closed task set, choose among enumerated options at a
|
|
361
|
+
gate, and write the "why". Everything downstream resolves from lookup tables.
|
|
362
|
+
|
|
363
|
+
The reason is reviewability. A server with no model is portable across clients,
|
|
364
|
+
has no second router to reason about, and can be reviewed for what it does rather
|
|
365
|
+
than what it might decide. It also means swapping the model cannot change a route
|
|
366
|
+
- the same question reaches the same method, because the method came from
|
|
367
|
+
recorded evidence rather than from inference.
|
|
368
|
+
|
|
369
|
+
**Deliverables, metrics and hypotheses are unchanged.**
|
|
370
|
+
|
|
371
|
+
---
|
|
372
|
+
|
|
373
|
+
## team
|
|
374
|
+
|
|
375
|
+
**Nasim Sanati, M.S.** - AI/ML systems - MCP server - agent orchestration - embedding pipelines
|
|
376
|
+
|
|
377
|
+
Brenden-Colson Center for Pancreatic Care / Sears Lab, OHSU
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
381
|
+
## citation
|
|
382
|
+
|
|
383
|
+
```bibtex
|
|
384
|
+
@software{sanati2026omicstra,
|
|
385
|
+
author = {Sanati, Nasim},
|
|
386
|
+
title = {omicstra: a multi-agent MCP server for cross-modal embedding alignment
|
|
387
|
+
and evidence-based routing in spatial biology},
|
|
388
|
+
year = {2026},
|
|
389
|
+
doi = {10.5281/zenodo.22666752},
|
|
390
|
+
url = {https://github.com/teslajoy/omicstra},
|
|
391
|
+
license = {MIT}
|
|
392
|
+
}
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
*funded by ResearchHub Foundation ([doi:10.55277/researchhub.6ou1w3h3](https://doi.org/10.55277/researchhub.6ou1w3h3))*
|
|
396
|
+
*nonprofit recipient: OHSU Foundation - EIN 23-7083114*
|
|
397
|
+
*seed cohort: Wang et al. 2024, Nat. Commun. 15:10232*
|