gemsmap 0.3.0__py3-none-any.whl

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.
@@ -0,0 +1,209 @@
1
+ """MetaNetX / MNXref client (SPARQL endpoint https://rdf.metanetx.org/sparql) with a local SQLite cache.
2
+
3
+ Only identifiers go to the ID mapper (an exact name lookup is a separate, explicitly weaker query).
4
+ Every answer — including "not found" — is cached, so a model is never queried twice and the analysis
5
+ keeps working offline for everything already seen. Standard library only.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import os
11
+ import sqlite3
12
+ import threading
13
+ import time
14
+ import urllib.error
15
+ import urllib.parse
16
+ import urllib.request
17
+ from concurrent.futures import ThreadPoolExecutor
18
+ from pathlib import Path
19
+ from typing import Callable, Iterable, Optional
20
+
21
+ ENDPOINT = os.environ.get("METANETX_SPARQL", "https://rdf.metanetx.org/sparql")
22
+ CHEM = "https://rdf.metanetx.org/chem/"
23
+ TTL_DAYS = 90
24
+ USER_AGENT = "GEMsMAP-COBRAGUI/0.2 (metabolite annotation curation)"
25
+
26
+ PREFIXES = """PREFIX mnx: <https://rdf.metanetx.org/schema/>
27
+ PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
28
+ """
29
+
30
+
31
+ class MetaNetXUnavailable(Exception):
32
+ pass
33
+
34
+
35
+ def _lit(s: str) -> str:
36
+ return '"' + s.replace("\\", "\\\\").replace('"', '\\"').replace("\n", " ") + '"'
37
+
38
+
39
+ class MetaNetX:
40
+ """Thread-safe client. `query` can be replaced in tests (no network)."""
41
+
42
+ def __init__(self, cache_path: Path, query: Optional[Callable[[str], list[dict]]] = None, workers: int = 4):
43
+ self.path = cache_path
44
+ self._db = sqlite3.connect(str(cache_path), check_same_thread=False)
45
+ self._lock = threading.Lock()
46
+ with self._lock:
47
+ self._db.executescript(
48
+ "CREATE TABLE IF NOT EXISTS xref (uri TEXT PRIMARY KEY, mnx TEXT NOT NULL, at REAL NOT NULL);"
49
+ "CREATE TABLE IF NOT EXISTS chem (mnx TEXT PRIMARY KEY, info TEXT NOT NULL, at REAL NOT NULL);"
50
+ "CREATE TABLE IF NOT EXISTS name (name TEXT PRIMARY KEY, mnx TEXT NOT NULL, at REAL NOT NULL);"
51
+ )
52
+ self._db.commit()
53
+ self.query = query or self._http_query
54
+ self.workers = workers
55
+ self.network_calls = 0
56
+
57
+ # ------------------------------------------------------------------ transport
58
+
59
+ def _http_query(self, q: str) -> list[dict]:
60
+ data = urllib.parse.urlencode({"query": PREFIXES + q}).encode()
61
+ req = urllib.request.Request(ENDPOINT, data=data, headers={
62
+ "Accept": "application/sparql-results+json", "User-Agent": USER_AGENT,
63
+ "Content-Type": "application/x-www-form-urlencoded"})
64
+ last: Exception | None = None
65
+ for attempt in range(3):
66
+ try:
67
+ with urllib.request.urlopen(req, timeout=90) as res:
68
+ self.network_calls += 1
69
+ body = json.loads(res.read().decode("utf-8"))
70
+ return [{k: v["value"] for k, v in b.items()} for b in body["results"]["bindings"]]
71
+ except (urllib.error.URLError, TimeoutError, OSError, ValueError) as e:
72
+ last = e
73
+ time.sleep(1.5 * (attempt + 1))
74
+ raise MetaNetXUnavailable(f"MetaNetX did not answer ({last})")
75
+
76
+ def _parallel(self, batches: list, fn: Callable, progress: Optional[Callable[[int], None]]) -> list:
77
+ out = []
78
+ with ThreadPoolExecutor(max_workers=self.workers) as pool:
79
+ for chunk, r in zip(batches, pool.map(fn, batches)):
80
+ out.append(r)
81
+ if progress:
82
+ progress(len(chunk))
83
+ return out
84
+
85
+ # ------------------------------------------------------------------ cache helpers
86
+
87
+ def _cached(self, table: str, key: str, keys: Iterable[str]) -> dict[str, str]:
88
+ keys = list(keys)
89
+ fresh = time.time() - TTL_DAYS * 86400
90
+ out: dict[str, str] = {}
91
+ with self._lock:
92
+ for i in range(0, len(keys), 500):
93
+ chunk = keys[i:i + 500]
94
+ q = f"SELECT {key}, {'mnx' if table != 'chem' else 'info'} FROM {table} WHERE at > ? AND {key} IN ({','.join('?' * len(chunk))})"
95
+ for k, v in self._db.execute(q, [fresh, *chunk]):
96
+ out[k] = v
97
+ return out
98
+
99
+ def _store(self, table: str, rows: list[tuple[str, str]]):
100
+ now = time.time()
101
+ with self._lock:
102
+ self._db.executemany(f"INSERT OR REPLACE INTO {table} VALUES (?, ?, ?)", [(k, v, now) for k, v in rows])
103
+ self._db.commit()
104
+
105
+ # ------------------------------------------------------------------ queries
106
+
107
+ def resolve_xrefs(self, uris: Iterable[str], progress=None, batch: int = 150) -> dict[str, list[str]]:
108
+ """identifiers.org URIs -> MNX chemical ids (several when MNXref splits an identifier)."""
109
+ uris = sorted(set(uris))
110
+ hit = self._cached("xref", "uri", uris)
111
+ todo = [u for u in uris if u not in hit]
112
+ if progress:
113
+ progress(len(uris) - len(todo))
114
+
115
+ def run(chunk: list[str]):
116
+ rows = self.query("SELECT ?ref ?mnx WHERE { VALUES ?ref { " + " ".join(f"<{u}>" for u in chunk) + " } ?mnx mnx:chemXref ?ref }")
117
+ found: dict[str, list[str]] = {u: [] for u in chunk}
118
+ for r in rows:
119
+ found.setdefault(r["ref"], []).append(r["mnx"].replace(CHEM, ""))
120
+ self._store("xref", [(u, ",".join(sorted(set(v)))) for u, v in found.items()])
121
+ return found
122
+
123
+ for found in self._parallel([todo[i:i + batch] for i in range(0, len(todo), batch)], run, progress):
124
+ for u, v in found.items():
125
+ hit[u] = ",".join(v)
126
+ return {u: [x for x in hit.get(u, "").split(",") if x] for u in uris}
127
+
128
+ def chem_info(self, mnx_ids: Iterable[str], progress=None, batch: int = 40) -> dict[str, dict]:
129
+ """name, formula, charge, InChIKey, cross-references and isomer links of MNX chemicals."""
130
+ ids = sorted(set(mnx_ids))
131
+ cached = self._cached("chem", "mnx", ids)
132
+ out = {k: json.loads(v) for k, v in cached.items()}
133
+ todo = [m for m in ids if m not in out]
134
+ if progress:
135
+ progress(len(ids) - len(todo))
136
+
137
+ def run(chunk: list[str]):
138
+ rows = self.query(
139
+ "SELECT ?mnx ?p ?o WHERE { VALUES ?mnx { " + " ".join(f"<{CHEM}{m}>" for m in chunk) + " } ?mnx ?p ?o . "
140
+ "FILTER(?p IN (rdfs:comment, mnx:formula, mnx:charge, mnx:inchikey, mnx:chemXref, mnx:chemIsom)) }")
141
+ info: dict[str, dict] = {m: {"mnx": m, "name": None, "formula": None, "charge": None, "inchikey": None, "xrefs": [], "isomers": [], "exists": False} for m in chunk}
142
+ for r in rows:
143
+ d = info.get(r["mnx"].replace(CHEM, ""))
144
+ if d is None:
145
+ continue
146
+ d["exists"] = True
147
+ p, o = r["p"].rsplit("/", 1)[-1].split("#")[-1], r["o"]
148
+ if p == "comment":
149
+ d["name"] = o
150
+ elif p == "formula":
151
+ d["formula"] = o
152
+ elif p == "charge":
153
+ try:
154
+ d["charge"] = int(float(o))
155
+ except ValueError:
156
+ pass
157
+ elif p == "inchikey":
158
+ d["inchikey"] = o
159
+ elif p == "chemXref":
160
+ d["xrefs"].append(o)
161
+ elif p == "chemIsom":
162
+ d["isomers"].append(o.replace(CHEM, ""))
163
+ self._store("chem", [(m, json.dumps(v)) for m, v in info.items()])
164
+ return info
165
+
166
+ for info in self._parallel([todo[i:i + batch] for i in range(0, len(todo), batch)], run, progress):
167
+ out.update(info)
168
+ return out
169
+
170
+ def lookup_names(self, names: Iterable[str], progress=None, batch: int = 80) -> dict[str, list[str]]:
171
+ """Exact (case-sensitive) MetaNetX name matches. Weak evidence: callers must treat hits as suggestions."""
172
+ names = sorted({n for n in names if n and len(n) < 200})
173
+ hit = self._cached("name", "name", names)
174
+ todo = [n for n in names if n not in hit]
175
+ if progress:
176
+ progress(len(names) - len(todo))
177
+
178
+ def run(chunk: list[str]):
179
+ rows = self.query("SELECT ?n ?mnx WHERE { VALUES ?n { " + " ".join(_lit(n) for n in chunk) + " } ?mnx rdfs:comment ?n }")
180
+ found: dict[str, list[str]] = {n: [] for n in chunk}
181
+ for r in rows:
182
+ found.setdefault(r["n"], []).append(r["mnx"].replace(CHEM, ""))
183
+ self._store("name", [(n, ",".join(sorted(set(v)))) for n, v in found.items()])
184
+ return found
185
+
186
+ for found in self._parallel([todo[i:i + batch] for i in range(0, len(todo), batch)], run, progress):
187
+ for n, v in found.items():
188
+ hit[n] = ",".join(v)
189
+ return {n: [x for x in hit.get(n, "").split(",") if x] for n in names}
190
+
191
+
192
+ _client: Optional[MetaNetX] = None
193
+ _client_lock = threading.Lock()
194
+
195
+
196
+ def client() -> MetaNetX:
197
+ global _client
198
+ with _client_lock:
199
+ if _client is None:
200
+ from ..registry import cache_dir
201
+ _client = MetaNetX(cache_dir().parent / "metanetx_cache.sqlite")
202
+ return _client
203
+
204
+
205
+ def set_client(c: Optional[MetaNetX]) -> None:
206
+ """Tests inject a client with a fake `query`."""
207
+ global _client
208
+ with _client_lock:
209
+ _client = c
@@ -0,0 +1,480 @@
1
+ """Model import, validation, catalog (UI-facing description of the model) and state application."""
2
+ import hashlib
3
+ import io
4
+ import json
5
+ import logging
6
+ import re
7
+ from contextlib import contextmanager
8
+ from pathlib import Path
9
+ from typing import Iterator, Optional
10
+
11
+ import cobra
12
+ from cobra.util.solver import linear_reaction_coefficients
13
+
14
+ from .. import registry
15
+ from ..errors import ScienceError, bound_in, num
16
+ from ..schemas import StateSpec
17
+ from . import bigg_service
18
+ from .search_service import SearchIndex
19
+
20
+ log = logging.getLogger("cobragui")
21
+
22
+ FORMAT_HINTS = ["SBML (.xml, .sbml)", "COBRA JSON (.json)", "MATLAB COBRA (.mat)"]
23
+
24
+
25
+ # ----------------------------------------------------------------------------- import
26
+
27
+ def detect_format(filename: str, data: bytes) -> str:
28
+ n = filename.lower()
29
+ if n.endswith((".xml", ".sbml")):
30
+ return "sbml"
31
+ if n.endswith(".mat"):
32
+ return "mat"
33
+ if n.endswith(".json"):
34
+ return "json"
35
+ head = data[:256].lstrip()
36
+ if head.startswith(b"<"):
37
+ return "sbml"
38
+ if head.startswith(b"{"):
39
+ return "json"
40
+ if head.startswith(b"MATLAB"):
41
+ return "mat"
42
+ raise ScienceError("Unsupported model format", f"Could not recognise '{filename}'.", hints=FORMAT_HINTS)
43
+
44
+
45
+ class _Capture(logging.Handler):
46
+ """Collect COBRApy/optlang log messages emitted while reading a model (shown as import notes)."""
47
+
48
+ def __init__(self):
49
+ super().__init__(logging.WARNING)
50
+ self.messages: list[str] = []
51
+
52
+ def emit(self, record):
53
+ self.messages.append(record.getMessage())
54
+
55
+
56
+ @contextmanager
57
+ def _captured_logs() -> Iterator[_Capture]:
58
+ h = _Capture()
59
+ loggers = [logging.getLogger(n) for n in ("cobra", "optlang")]
60
+ for lg in loggers:
61
+ lg.addHandler(h)
62
+ try:
63
+ yield h
64
+ finally:
65
+ for lg in loggers:
66
+ lg.removeHandler(h)
67
+
68
+
69
+ def _read_model(fmt: str, data: bytes, path: Path) -> tuple[cobra.Model, dict]:
70
+ validation: dict = {"format": fmt, "categories": {}, "loader": []}
71
+ with _captured_logs() as cap:
72
+ try:
73
+ if fmt == "sbml":
74
+ # Pass the document as a string: libSBML cannot open some non-ASCII Windows paths.
75
+ text = data.decode("utf-8", errors="replace")
76
+ model, errors = cobra.io.validate_sbml_model(text)
77
+ for cat, msgs in (errors or {}).items():
78
+ if msgs:
79
+ validation["categories"][cat] = {"count": len(msgs), "messages": [str(m) for m in msgs[:40]]}
80
+ if model is None:
81
+ fatal = [m for c in ("SBML_FATAL", "COBRA_FATAL", "SBML_ERROR", "COBRA_ERROR")
82
+ for m in (errors or {}).get(c, [])]
83
+ raise ScienceError("SBML model could not be read", str(fatal[0]) if fatal else "",
84
+ detail=validation["categories"])
85
+ elif fmt == "json":
86
+ model = cobra.io.load_json_model(io.StringIO(data.decode("utf-8", errors="replace")))
87
+ elif fmt == "mat":
88
+ model = cobra.io.load_matlab_model(str(path))
89
+ else:
90
+ raise ScienceError("Unsupported model format", fmt, hints=FORMAT_HINTS)
91
+ except ScienceError:
92
+ raise
93
+ except Exception as e: # noqa: BLE001 - surfaced to the user with the parser message
94
+ raise ScienceError(f"Could not read the {fmt.upper()} model", str(e), hints=FORMAT_HINTS,
95
+ detail=type(e).__name__) from e
96
+ validation["loader"] = cap.messages[:60]
97
+ return model, validation
98
+
99
+
100
+ def _safe_name(name: str) -> str:
101
+ return re.sub(r"[^A-Za-z0-9._-]+", "_", name)[:80] or "model"
102
+
103
+
104
+ def import_model(filename: str, data: bytes) -> registry.ModelEntry:
105
+ if not data:
106
+ raise ScienceError("Empty file", f"'{filename}' contains no data.")
107
+ checksum = hashlib.sha256(data).hexdigest()
108
+ mid = checksum[:16]
109
+ existing = registry.get(mid)
110
+ if existing:
111
+ return existing
112
+ fmt = detect_format(filename, data)
113
+ if fmt == "json":
114
+ # a model exported by BiGG: normalized IDs, annotations completed from the local BiGG tables
115
+ data, report = bigg_service.normalize_bigg_json(data)
116
+ if report:
117
+ log.info("BiGG export %s: %s", filename, report)
118
+ path = registry.cache_dir() / f"{mid}__{_safe_name(filename)}"
119
+ if not path.exists():
120
+ path.write_bytes(data)
121
+ model, validation = _read_model(fmt, data, path)
122
+ _write_fast_copy(mid, model, validation)
123
+ entry = _make_entry(mid, checksum, filename, fmt, model, validation)
124
+ registry.put(entry)
125
+ return entry
126
+
127
+
128
+ def _write_fast_copy(mid: str, model: cobra.Model, validation: dict) -> None:
129
+ """COBRA-JSON copy + validation notes: reloading after a backend restart skips SBML parsing."""
130
+ try:
131
+ d = registry.cache_dir()
132
+ cobra.io.save_json_model(model, str(d / f"{mid}.fast.json"))
133
+ (d / f"{mid}.validation.json").write_text(json.dumps(validation), encoding="utf-8")
134
+ except Exception as e: # noqa: BLE001 - only an optimization
135
+ log.warning("could not write fast cache for %s: %s", mid, e)
136
+
137
+
138
+ def _load_fast_copy(mid: str, checksum: str, filename: str, fmt: str) -> Optional[registry.ModelEntry]:
139
+ d = registry.cache_dir()
140
+ fast, val = d / f"{mid}.fast.json", d / f"{mid}.validation.json"
141
+ if not fast.exists():
142
+ return None
143
+ try:
144
+ model = cobra.io.load_json_model(str(fast))
145
+ validation = json.loads(val.read_text(encoding="utf-8")) if val.exists() else {}
146
+ except Exception: # noqa: BLE001 - fall back to the original file
147
+ return None
148
+ entry = _make_entry(mid, checksum, filename, fmt, model, validation)
149
+ registry.put(entry)
150
+ return entry
151
+
152
+
153
+ _example_ids: dict[str, str] = {}
154
+
155
+
156
+ def import_example(name: str) -> registry.ModelEntry:
157
+ """Models bundled with COBRApy (no download), e.g. 'textbook' = E. coli core."""
158
+ known = _example_ids.get(name)
159
+ if known and registry.get(known):
160
+ return registry.get(known)
161
+ try:
162
+ model = cobra.io.load_model(name)
163
+ except Exception as e: # noqa: BLE001
164
+ raise ScienceError("Example model unavailable", str(e)) from e
165
+ buf = io.StringIO()
166
+ cobra.io.save_json_model(model, buf)
167
+ entry = import_model(f"{name}.json", buf.getvalue().encode("utf-8"))
168
+ _example_ids[name] = entry.id
169
+ return entry
170
+
171
+
172
+ def get_entry(model_id: str) -> registry.ModelEntry:
173
+ entry = registry.get(model_id)
174
+ if entry:
175
+ return entry
176
+ path = registry.cached_file(model_id)
177
+ if not path:
178
+ raise ScienceError("Model not loaded", "The backend has no copy of this model.", status=404,
179
+ hints=["Import the model file again."])
180
+ data = path.read_bytes()
181
+ filename = path.name.split("__", 1)[1] if "__" in path.name else path.name
182
+ checksum = hashlib.sha256(data).hexdigest()
183
+ fast = _load_fast_copy(model_id, checksum, filename, detect_format(filename, data))
184
+ return fast or import_model(filename, data)
185
+
186
+
187
+ def _make_entry(mid, checksum, filename, fmt, model, validation) -> registry.ModelEntry:
188
+ # metabolite curation saved for this file (annotation analysis) is part of the working model
189
+ from . import annotation_service, edit_service
190
+ saved = annotation_service.load_json(mid, "curation")
191
+ if saved:
192
+ annotation_service.apply_curation_to_model(model, saved)
193
+ entry = registry.ModelEntry(
194
+ id=mid, checksum=checksum, filename=filename, fmt=fmt, model=model,
195
+ original_bounds={}, original_objective={}, original_direction="max", original_medium={},
196
+ validation=validation,
197
+ )
198
+ # structural edits saved for this file (reactions / metabolites added, changed or removed)
199
+ edit_service.replay(entry)
200
+ set_baseline(entry)
201
+ entry.search = SearchIndex(model)
202
+ entry.catalog = build_catalog(entry)
203
+ return entry
204
+
205
+
206
+ def set_baseline(entry: registry.ModelEntry) -> None:
207
+ """The working model's own bounds, objective and medium (the 'model file' that states modify)."""
208
+ m = entry.model
209
+ entry.original_bounds = {r.id: (r.lower_bound, r.upper_bound) for r in m.reactions}
210
+ entry.original_objective = objective_coefficients(m)
211
+ entry.original_direction = m.objective_direction
212
+ try:
213
+ entry.original_medium = {k: float(v) for k, v in m.medium.items()}
214
+ except Exception: # noqa: BLE001 - models without identifiable exchanges
215
+ entry.original_medium = {}
216
+
217
+
218
+ def load_base_model(mid: str, filename: str, fmt: str) -> cobra.Model:
219
+ """The imported file as read (fast copy when available) with the metabolite curation — no edits."""
220
+ from . import annotation_service
221
+ fast = registry.cache_dir() / f"{mid}.fast.json"
222
+ if fast.exists():
223
+ model = cobra.io.load_json_model(str(fast))
224
+ else:
225
+ path = registry.cached_file(mid)
226
+ if not path:
227
+ raise ScienceError("Model not loaded", "The backend has no copy of this model.", status=404)
228
+ model, _ = _read_model(fmt, path.read_bytes(), path)
229
+ saved = annotation_service.load_json(mid, "curation")
230
+ if saved:
231
+ annotation_service.apply_curation_to_model(model, saved)
232
+ return model
233
+
234
+
235
+ def search_index(entry: registry.ModelEntry) -> SearchIndex:
236
+ if entry.search is None: # dropped after a structural edit
237
+ entry.search = SearchIndex(entry.model)
238
+ return entry.search
239
+
240
+
241
+ def known_compartments(model: cobra.Model) -> dict[str, str]:
242
+ """Compartments with metabolites plus compartments only named in the model (created explicitly)."""
243
+ out = {k: (v or k) for k, v in (getattr(model, "_compartments", None) or {}).items()}
244
+ for k, v in model.compartments.items():
245
+ out[k] = v or out.get(k) or k
246
+ return out
247
+
248
+
249
+ # ----------------------------------------------------------------------------- helpers
250
+
251
+ def objective_coefficients(model: cobra.Model) -> dict[str, float]:
252
+ try:
253
+ return {r.id: float(c) for r, c in linear_reaction_coefficients(model).items() if c}
254
+ except Exception: # noqa: BLE001
255
+ return {}
256
+
257
+
258
+ def solver_name(model: cobra.Model) -> str:
259
+ name = model.solver.interface.__name__.split(".")[-1].replace("_interface", "")
260
+ return name.upper()
261
+
262
+
263
+ def boundary_kinds(model: cobra.Model) -> dict[str, str]:
264
+ """Reaction id -> 'exchange' | 'demand' | 'sink' for boundary reactions (COBRApy definitions)."""
265
+ out: dict[str, str] = {}
266
+ for attr, kind in (("sinks", "sink"), ("demands", "demand"), ("exchanges", "exchange")):
267
+ try:
268
+ for r in getattr(model, attr):
269
+ out[r.id] = kind
270
+ except Exception: # noqa: BLE001 - external compartment could not be identified
271
+ pass
272
+ for r in model.boundary:
273
+ out.setdefault(r.id, "exchange")
274
+ return out
275
+
276
+
277
+ def boundary_metabolite(rxn) -> tuple[Optional[str], float]:
278
+ """The single metabolite of a boundary reaction and its coefficient."""
279
+ for m, c in rxn.metabolites.items():
280
+ return m.id, float(c)
281
+ return None, 0.0
282
+
283
+
284
+ def _ec(annotation) -> list[str]:
285
+ v = (annotation or {}).get("ec-code") or []
286
+ return [str(x) for x in (v if isinstance(v, (list, tuple)) else [v])]
287
+
288
+
289
+ def _notes(notes) -> dict:
290
+ """Free-text notes as strings (shown and edited in the structural editor)."""
291
+ return {str(k): (", ".join(str(x) for x in v) if isinstance(v, (list, tuple)) else str(v)) for k, v in (notes or {}).items()}
292
+
293
+
294
+ def _ann(annotation) -> dict:
295
+ out = {}
296
+ for k, v in (annotation or {}).items():
297
+ out[str(k)] = [str(x) for x in v] if isinstance(v, (list, tuple)) else str(v)
298
+ return out
299
+
300
+
301
+ # ----------------------------------------------------------------------------- catalog
302
+
303
+ def build_catalog(entry: registry.ModelEntry) -> dict:
304
+ """Everything the UI needs to browse the model. Plain data — never COBRApy objects."""
305
+ m = entry.model
306
+ kinds = boundary_kinds(m)
307
+ obj = entry.original_objective
308
+ reactions = []
309
+ counts = {"exchange": 0, "demand": 0, "sink": 0, "transport": 0, "internal": 0}
310
+ reversible = blocked = 0
311
+ subsystems: set[str] = set()
312
+ for r in m.reactions:
313
+ comps = sorted({met.compartment for met in r.metabolites if met.compartment})
314
+ if r.id in kinds:
315
+ t = kinds[r.id]
316
+ elif len(comps) > 1:
317
+ t = "transport"
318
+ else:
319
+ t = "internal"
320
+ counts[t] += 1
321
+ reversible += 1 if r.reversibility else 0
322
+ blocked += 1 if r.lower_bound == 0 and r.upper_bound == 0 else 0
323
+ if r.subsystem:
324
+ subsystems.add(r.subsystem)
325
+ bmet, bcoef = boundary_metabolite(r) if r.id in kinds else (None, 0.0)
326
+ reactions.append({
327
+ "id": r.id,
328
+ "name": r.name or "",
329
+ "equation": r.build_reaction_string(),
330
+ "equationNames": r.build_reaction_string(use_metabolite_names=True),
331
+ "stoichiometry": {met.id: float(c) for met, c in r.metabolites.items()},
332
+ "lb": num(r.lower_bound), "ub": num(r.upper_bound),
333
+ "reversible": bool(r.reversibility),
334
+ "subsystem": r.subsystem or None,
335
+ "gpr": r.gene_reaction_rule or None,
336
+ "genes": [g.id for g in r.genes],
337
+ "ec": _ec(r.annotation),
338
+ "annotation": _ann(r.annotation), "notes": _notes(r.notes),
339
+ "type": t,
340
+ "compartments": comps,
341
+ "objectiveCoefficient": obj.get(r.id, 0.0),
342
+ "boundaryMetabolite": bmet,
343
+ "boundaryCoefficient": bcoef if bmet else None,
344
+ })
345
+ metabolites = [{
346
+ "id": met.id, "name": met.name or "", "formula": met.formula or None,
347
+ "charge": met.charge if isinstance(met.charge, (int, float)) else None,
348
+ "compartment": met.compartment or "", "annotation": _ann(met.annotation), "notes": _notes(met.notes),
349
+ "reactionCount": len(met.reactions),
350
+ } for met in m.metabolites]
351
+ genes = [{
352
+ "id": g.id, "name": g.name or "", "annotation": _ann(g.annotation),
353
+ "reactions": [r.id for r in g.reactions],
354
+ } for g in m.genes]
355
+ compartments = known_compartments(m)
356
+ summary = {
357
+ "reactions": len(m.reactions), "metabolites": len(m.metabolites), "genes": len(m.genes),
358
+ "compartments": len(compartments), "subsystems": len(subsystems),
359
+ **counts,
360
+ "reversible": reversible, "irreversible": len(m.reactions) - reversible, "blockedByBounds": blocked,
361
+ "objective": {"coefficients": obj, "direction": entry.original_direction},
362
+ "solver": solver_name(m), "cobraVersion": cobra.__version__,
363
+ "mediumSize": len(entry.original_medium),
364
+ }
365
+ return {
366
+ "id": entry.id, "checksum": entry.checksum, "filename": entry.filename, "format": entry.fmt,
367
+ "modelId": m.id or "", "name": m.name or m.id or entry.filename,
368
+ "summary": summary, "compartments": compartments,
369
+ "metabolites": metabolites, "reactions": reactions, "genes": genes,
370
+ "medium": entry.original_medium,
371
+ "warnings": model_warnings(entry, kinds),
372
+ "validation": entry.validation,
373
+ }
374
+
375
+
376
+ def model_warnings(entry: registry.ModelEntry, kinds: dict[str, str]) -> list[dict]:
377
+ """Non-blocking quality notes, each with the ids involved so the UI can make them inspectable."""
378
+ m = entry.model
379
+ out: list[dict] = []
380
+
381
+ def add(level, code, title, ids, detail=""):
382
+ if ids:
383
+ out.append({"level": level, "code": code, "title": title, "count": len(ids), "ids": ids[:5000], "detail": detail})
384
+
385
+ if not entry.original_objective:
386
+ out.append({"level": "error", "code": "no-objective", "title": "No objective defined in the model file",
387
+ "count": 1, "ids": [], "detail": "Choose an objective before running FBA-based methods."})
388
+ add("warning", "disconnected-metabolite", "metabolites are not used by any reaction",
389
+ [x.id for x in m.metabolites if not x.reactions])
390
+ can_prod: set[str] = set()
391
+ can_cons: set[str] = set()
392
+ for r in m.reactions:
393
+ for met, c in r.metabolites.items():
394
+ if (c > 0 and r.upper_bound > 0) or (c < 0 and r.lower_bound < 0):
395
+ can_prod.add(met.id)
396
+ if (c < 0 and r.upper_bound > 0) or (c > 0 and r.lower_bound < 0):
397
+ can_cons.add(met.id)
398
+ add("info", "dead-end", "dead-end metabolites (can only be produced or only consumed under current bounds)",
399
+ [x.id for x in m.metabolites if x.reactions and (x.id not in can_prod or x.id not in can_cons)])
400
+ add("info", "no-gpr", "non-boundary reactions have no gene association",
401
+ [r.id for r in m.reactions if r.id not in kinds and not r.gene_reaction_rule])
402
+ add("info", "blocked-bounds", "reactions are blocked by their bounds (lower = upper = 0)",
403
+ [r.id for r in m.reactions if r.lower_bound == 0 and r.upper_bound == 0])
404
+ add("info", "no-formula", "metabolites have no chemical formula", [x.id for x in m.metabolites if not x.formula])
405
+ unbalanced = []
406
+ for r in m.reactions:
407
+ if r.id in kinds or r.id in entry.original_objective:
408
+ continue
409
+ if not all(x.formula for x in r.metabolites):
410
+ continue
411
+ try:
412
+ bal = r.check_mass_balance()
413
+ except Exception: # noqa: BLE001 - unparsable formula
414
+ continue
415
+ if any(k != "charge" and abs(v) > 1e-6 for k, v in bal.items()):
416
+ unbalanced.append(r.id)
417
+ add("warning", "mass-unbalanced", "reactions are elementally unbalanced", unbalanced,
418
+ "Boundary and objective (biomass) reactions are excluded; metabolites without formula are skipped.")
419
+ cats = (entry.validation or {}).get("categories", {})
420
+ for cat, info in cats.items():
421
+ if cat in ("SBML_ERROR", "SBML_SCHEMA_ERROR", "COBRA_ERROR"):
422
+ level = "warning"
423
+ elif cat in ("SBML_FATAL", "COBRA_FATAL"):
424
+ level = "error"
425
+ else:
426
+ continue
427
+ out.append({"level": level, "code": f"sbml-{cat.lower()}", "title": f"{cat.replace('_', ' ').lower()} messages",
428
+ "count": info["count"], "ids": [], "detail": "\n".join(info["messages"][:15])})
429
+ return out
430
+
431
+
432
+ # ----------------------------------------------------------------------------- states
433
+
434
+ def apply_state(model: cobra.Model, state: StateSpec) -> None:
435
+ errors = []
436
+ for rid, (lb, ub) in (state.bounds or {}).items():
437
+ if rid not in model.reactions:
438
+ errors.append(f"unknown reaction '{rid}'")
439
+ continue
440
+ lo, hi = bound_in(lb, "lower"), bound_in(ub, "upper")
441
+ if lo > hi:
442
+ errors.append(f"{rid}: lower bound {lo:g} is greater than upper bound {hi:g}")
443
+ continue
444
+ model.reactions.get_by_id(rid).bounds = (lo, hi)
445
+ if state.objective is not None:
446
+ coefs = {}
447
+ for rid, c in state.objective.coefficients.items():
448
+ if rid not in model.reactions:
449
+ errors.append(f"objective reaction '{rid}' is not in the model")
450
+ elif c:
451
+ coefs[model.reactions.get_by_id(rid)] = float(c)
452
+ if not errors:
453
+ model.objective = coefs
454
+ model.objective_direction = state.objective.direction
455
+ if errors:
456
+ raise ScienceError("Invalid model state", "; ".join(errors[:6]), status=422,
457
+ hints=["Check edited bounds and the objective."], detail=errors)
458
+
459
+
460
+ @contextmanager
461
+ def applied(entry: registry.ModelEntry, state: Optional[StateSpec]) -> Iterator[cobra.Model]:
462
+ """Yield the model with a state applied; COBRApy reverts every change on exit."""
463
+ with entry.lock:
464
+ model = entry.model
465
+ with model:
466
+ if state is not None:
467
+ apply_state(model, state)
468
+ yield model
469
+
470
+
471
+ def bound_changes(entry: registry.ModelEntry, state: StateSpec) -> list[dict]:
472
+ out = []
473
+ for rid, (lb, ub) in (state.bounds or {}).items():
474
+ orig = entry.original_bounds.get(rid)
475
+ if orig is None:
476
+ continue
477
+ cur = (bound_in(lb, "lower"), bound_in(ub, "upper"))
478
+ if cur != orig:
479
+ out.append({"reaction": rid, "original": [num(orig[0]), num(orig[1])], "current": [num(cur[0]), num(cur[1])]})
480
+ return out