bijux-proteomics-runtime 0.3.8__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.
- bijux_proteomics_runtime-0.3.8/.gitignore +62 -0
- bijux_proteomics_runtime-0.3.8/CHANGELOG.md +43 -0
- bijux_proteomics_runtime-0.3.8/LICENSE +1 -0
- bijux_proteomics_runtime-0.3.8/NOTICE +1 -0
- bijux_proteomics_runtime-0.3.8/PKG-INFO +440 -0
- bijux_proteomics_runtime-0.3.8/README.md +376 -0
- bijux_proteomics_runtime-0.3.8/pyproject.toml +106 -0
- bijux_proteomics_runtime-0.3.8/src/bijux_proteomics_runtime/py.typed +0 -0
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Bijux shared
|
|
2
|
+
.DS_Store
|
|
3
|
+
.idea/
|
|
4
|
+
.vscode/
|
|
5
|
+
.tox/
|
|
6
|
+
.tox
|
|
7
|
+
.venv/
|
|
8
|
+
.venv
|
|
9
|
+
.venv-esm/
|
|
10
|
+
.coverage
|
|
11
|
+
.coverage.*
|
|
12
|
+
**/.coverage
|
|
13
|
+
**/.coverage.*
|
|
14
|
+
.python-version
|
|
15
|
+
.mypy_cache/
|
|
16
|
+
.pytest_cache/
|
|
17
|
+
.ruff_cache/
|
|
18
|
+
.hypothesis/
|
|
19
|
+
.hypothesis
|
|
20
|
+
.benchmarks
|
|
21
|
+
.nox/
|
|
22
|
+
.cache/
|
|
23
|
+
.tmp/
|
|
24
|
+
.github/tmp/
|
|
25
|
+
site/
|
|
26
|
+
build/
|
|
27
|
+
dist/
|
|
28
|
+
htmlcov/
|
|
29
|
+
**/coverage.xml
|
|
30
|
+
node_modules/
|
|
31
|
+
*.egg-info/
|
|
32
|
+
pip-wheel-metadata/
|
|
33
|
+
|
|
34
|
+
artifacts/
|
|
35
|
+
artifacts
|
|
36
|
+
packages/*/artifacts/
|
|
37
|
+
packages/*/artifacts
|
|
38
|
+
|
|
39
|
+
**/__pycache__/
|
|
40
|
+
**/.pytest_cache/
|
|
41
|
+
**/.ruff_cache/
|
|
42
|
+
**/.mypy_cache/
|
|
43
|
+
**/.pytype/
|
|
44
|
+
**/.hypothesis/
|
|
45
|
+
**/.hypothesis
|
|
46
|
+
**/.benchmarks/
|
|
47
|
+
**/.benchmarks
|
|
48
|
+
**/.tox/
|
|
49
|
+
**/.tox
|
|
50
|
+
**/.venv/
|
|
51
|
+
**/.venv
|
|
52
|
+
**/.nox/
|
|
53
|
+
**/.cache/
|
|
54
|
+
**/site/
|
|
55
|
+
**/build/
|
|
56
|
+
**/dist/
|
|
57
|
+
**/htmlcov/
|
|
58
|
+
**/*.egg-info/
|
|
59
|
+
**/*.pyc
|
|
60
|
+
**/*.pyo
|
|
61
|
+
*.swp
|
|
62
|
+
*.swo
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes for `bijux-proteomics-runtime` are recorded here.
|
|
4
|
+
|
|
5
|
+
## Unreleased
|
|
6
|
+
|
|
7
|
+
## 0.3.8 - 2026-07-01
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- Added the canonical runtime package with typed CLI and API entrypoints,
|
|
12
|
+
provider binding, run management, reviewable sequence and import paths,
|
|
13
|
+
collaborator handoff archives, artifact checkpoint, rehydration, diff, and
|
|
14
|
+
comparison surfaces, and deterministic replay contracts.
|
|
15
|
+
- Added typed workflow DAG, step-type, semantic-cache, partial-rerun, and
|
|
16
|
+
workflow-failure contracts so runtime planning and stage reuse stay
|
|
17
|
+
machine-readable and auditable.
|
|
18
|
+
- Added advanced DIA-NN public workflows for dry-run planning, deterministic
|
|
19
|
+
run identity, resumable stage reuse, archived result bundles, runtime smoke
|
|
20
|
+
bundles, and architecture-demo routes.
|
|
21
|
+
- Added benchmark rerun kits, comparability ledgers, black-box benchmark
|
|
22
|
+
dashboards, runtime replay challenges, and migration-ledger routes so an
|
|
23
|
+
outsider can follow runtime proof from benchmark root to rerun artifact.
|
|
24
|
+
|
|
25
|
+
### Changed
|
|
26
|
+
|
|
27
|
+
- Rebuilt runtime around explicit `api`, `providers`, `runs`, `workflows`,
|
|
28
|
+
`state`, `support`, and `governance` owner families and tightened
|
|
29
|
+
dependency-light imports plus optional provider guards.
|
|
30
|
+
- Expanded executable README and package docs for runtime APIs, advanced
|
|
31
|
+
DIA-NN tutorials, archived workflow ownership, and black-box rerun trust
|
|
32
|
+
surfaces.
|
|
33
|
+
- Aligned dependency floors and fallback version with the `0.3.8` release
|
|
34
|
+
line.
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
|
|
38
|
+
- Hardened guarded route methods, multiplex import handling, bytecode hygiene,
|
|
39
|
+
security-sensitive asserts, and the governed local-folding dependency
|
|
40
|
+
policy.
|
|
41
|
+
- Tightened type coverage across archive, rehydrate, run-operation, advanced
|
|
42
|
+
DIA-NN resume, and workflow-plan boundaries so the canonical runtime surface
|
|
43
|
+
stays strict under review.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
../../LICENSE
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
../../NOTICE
|
|
@@ -0,0 +1,440 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: bijux-proteomics-runtime
|
|
3
|
+
Version: 0.3.8
|
|
4
|
+
Summary: Canonical execution runtime for orchestrating proteomics workflows through CLI, API, provider binding, and deterministic run control
|
|
5
|
+
Project-URL: Homepage, https://bijux.io/bijux-proteomics/
|
|
6
|
+
Project-URL: Documentation, https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/
|
|
7
|
+
Project-URL: Repository, https://github.com/bijux/bijux-proteomics
|
|
8
|
+
Project-URL: Issues, https://github.com/bijux/bijux-proteomics/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-runtime/CHANGELOG.md
|
|
10
|
+
Project-URL: Security, https://github.com/bijux/bijux-proteomics/blob/main/SECURITY.md
|
|
11
|
+
Author-email: Bijan Mousavi <bijan@bijux.io>
|
|
12
|
+
Maintainer-email: Bijan Mousavi <bijan@bijux.io>
|
|
13
|
+
License: Apache-2.0
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
License-File: NOTICE
|
|
16
|
+
Keywords: determinism,orchestration,proteomics,replay,runtime
|
|
17
|
+
Classifier: Development Status :: 3 - Alpha
|
|
18
|
+
Classifier: Intended Audience :: Developers
|
|
19
|
+
Classifier: Intended Audience :: Science/Research
|
|
20
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
21
|
+
Classifier: Operating System :: OS Independent
|
|
22
|
+
Classifier: Programming Language :: Python :: 3
|
|
23
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
28
|
+
Classifier: Typing :: Typed
|
|
29
|
+
Requires-Python: <4,>=3.11
|
|
30
|
+
Requires-Dist: bijux-proteomics-core>=0.3.8
|
|
31
|
+
Requires-Dist: bijux-proteomics-foundation>=0.3.8
|
|
32
|
+
Requires-Dist: bijux-proteomics-intelligence>=0.3.8
|
|
33
|
+
Requires-Dist: bijux-proteomics-knowledge>=0.3.8
|
|
34
|
+
Requires-Dist: bijux-proteomics-lab>=0.3.8
|
|
35
|
+
Requires-Dist: biopython>=1.83
|
|
36
|
+
Requires-Dist: click>=8.1
|
|
37
|
+
Requires-Dist: fastapi>=0.115
|
|
38
|
+
Requires-Dist: loguru>=0.7
|
|
39
|
+
Requires-Dist: pydantic>=2.0.2
|
|
40
|
+
Requires-Dist: requests>=2.31
|
|
41
|
+
Requires-Dist: slowapi>=0.1
|
|
42
|
+
Requires-Dist: starlette<2.0,>=1.3.1
|
|
43
|
+
Requires-Dist: uvicorn>=0.30
|
|
44
|
+
Provides-Extra: api
|
|
45
|
+
Requires-Dist: openprotein-python>=0.8.8; extra == 'api'
|
|
46
|
+
Provides-Extra: local-esmfold
|
|
47
|
+
Requires-Dist: einops>=0.7; extra == 'local-esmfold'
|
|
48
|
+
Requires-Dist: tokenizers>=0.14; extra == 'local-esmfold'
|
|
49
|
+
Requires-Dist: transformers>=5.0.0rc3; extra == 'local-esmfold'
|
|
50
|
+
Provides-Extra: local-rosettafold
|
|
51
|
+
Provides-Extra: nl
|
|
52
|
+
Requires-Dist: langchain-community>=0.3.27; extra == 'nl'
|
|
53
|
+
Requires-Dist: langchain-core>=1.3.3; extra == 'nl'
|
|
54
|
+
Requires-Dist: langchain-huggingface>=1.2.1; extra == 'nl'
|
|
55
|
+
Requires-Dist: langchain-text-splitters>=1.1.2; extra == 'nl'
|
|
56
|
+
Requires-Dist: langsmith>=0.8.0; extra == 'nl'
|
|
57
|
+
Provides-Extra: test
|
|
58
|
+
Requires-Dist: httpx<1.0,>=0.27.0; extra == 'test'
|
|
59
|
+
Requires-Dist: pytest-asyncio<2.0,>=1.0.0; extra == 'test'
|
|
60
|
+
Requires-Dist: pytest-benchmark<6.0,>=4.0.0; extra == 'test'
|
|
61
|
+
Requires-Dist: pytest-timeout<3.0,>=2.4.0; extra == 'test'
|
|
62
|
+
Requires-Dist: pytest<10.0,>=8.4.1; extra == 'test'
|
|
63
|
+
Description-Content-Type: text/markdown
|
|
64
|
+
|
|
65
|
+
# bijux-proteomics-runtime
|
|
66
|
+
|
|
67
|
+
<!-- bijux-proteomics-badges:generated:start -->
|
|
68
|
+
[](https://pypi.org/project/bijux-proteomics-runtime/)
|
|
69
|
+
[-0A7BBB)](https://pypi.org/project/bijux-proteomics-runtime/)
|
|
70
|
+
[](https://github.com/bijux/bijux-proteomics/blob/main/LICENSE)
|
|
71
|
+
[](https://github.com/bijux/bijux-proteomics/actions/workflows/verify.yml?query=branch%3Amain)
|
|
72
|
+
[](https://github.com/bijux/bijux-proteomics)
|
|
73
|
+
|
|
74
|
+
[](https://pypi.org/project/bijux-proteomics-runtime/)
|
|
75
|
+
[](https://pypi.org/project/agentic-proteins/)
|
|
76
|
+
[](https://pypi.org/project/bijux-proteomics-foundation/)
|
|
77
|
+
[](https://pypi.org/project/bijux-proteomics-core/)
|
|
78
|
+
[](https://pypi.org/project/bijux-proteomics-intelligence/)
|
|
79
|
+
[](https://pypi.org/project/bijux-proteomics-knowledge/)
|
|
80
|
+
[](https://pypi.org/project/bijux-proteomics-lab/)
|
|
81
|
+
|
|
82
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fagentic-proteins)
|
|
83
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-foundation)
|
|
84
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-core)
|
|
85
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-intelligence)
|
|
86
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-knowledge)
|
|
87
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-lab)
|
|
88
|
+
|
|
89
|
+
[](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/)
|
|
90
|
+
[](https://bijux.io/bijux-proteomics/02-agentic-proteins/)
|
|
91
|
+
[](https://bijux.io/bijux-proteomics/03-bijux-proteomics-foundation/)
|
|
92
|
+
[](https://bijux.io/bijux-proteomics/04-bijux-proteomics-core/)
|
|
93
|
+
[](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/)
|
|
94
|
+
[](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/)
|
|
95
|
+
[](https://bijux.io/bijux-proteomics/07-bijux-proteomics-lab/)
|
|
96
|
+
<!-- bijux-proteomics-badges:generated:end -->
|
|
97
|
+
|
|
98
|
+
`bijux-proteomics-runtime` is the execution owner for provider binding,
|
|
99
|
+
deterministic replay, and operator-facing orchestration surfaces in
|
|
100
|
+
`bijux-proteomics`.
|
|
101
|
+
|
|
102
|
+
Within the suite, runtime owns execution, provider binding, deterministic
|
|
103
|
+
replay, and operator entrypoints.
|
|
104
|
+
|
|
105
|
+
Use this package when you need supported CLI, HTTP API, provider wiring,
|
|
106
|
+
runtime state handling, and replay-safe orchestration for the bounded
|
|
107
|
+
flagship workflow chain.
|
|
108
|
+
|
|
109
|
+
Runtime owns execution control. It does not own the scientific workflow
|
|
110
|
+
blueprint, evidence truth, ranking semantics, or lab progression logic that the
|
|
111
|
+
wider proteomics engine still needs.
|
|
112
|
+
|
|
113
|
+
## At a glance
|
|
114
|
+
|
|
115
|
+
- Use runtime when the concern is executable workflow control, provider
|
|
116
|
+
binding, deterministic replay, or operator-facing handoff.
|
|
117
|
+
- Start with `bijux-proteomics-runtime --help` for the live CLI surface, then
|
|
118
|
+
open the
|
|
119
|
+
[runtime handbook](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/)
|
|
120
|
+
when you need the end-to-end run path.
|
|
121
|
+
- Route scientific truth to core, cited evidence memory to knowledge,
|
|
122
|
+
recommendation posture to intelligence, and assay follow-up authority to
|
|
123
|
+
lab.
|
|
124
|
+
|
|
125
|
+
## Why teams pick this package
|
|
126
|
+
|
|
127
|
+
- one canonical runtime surface for CLI, API, orchestration, and providers
|
|
128
|
+
- deterministic replay and artifact shaping for repeatable execution outcomes
|
|
129
|
+
- typed run context, artifact ledger, replay contract, and local/container/scheduler/import run bundle outputs
|
|
130
|
+
- runtime-owned CLI and API operations that avoid private helper glue
|
|
131
|
+
- reviewable run and import paths that publish canonical downstream-facing manifests
|
|
132
|
+
- partial rerun planning, cache claims, cleanup plans, and failure-recovery audits for operational safety
|
|
133
|
+
- preflight and failure reports that fail early on missing execution requirements
|
|
134
|
+
- import traces, human-review resume checkpoints, and artifact-integrity reports for safe reuse
|
|
135
|
+
- runtime-owned control surfaces that consume lower-layer contracts without re-exporting their domain semantics
|
|
136
|
+
- explicit migration target for `agentic-proteins` compatibility forwarding
|
|
137
|
+
|
|
138
|
+
## Typical use cases
|
|
139
|
+
|
|
140
|
+
- run the canonical proteomics workflow through CLI or HTTP entrypoints
|
|
141
|
+
- bind local or API-backed structure providers behind one orchestration layer
|
|
142
|
+
- enforce replay-safe runtime execution without moving domain semantics upward
|
|
143
|
+
- ingest third-party engine outputs while preserving external provenance honestly
|
|
144
|
+
- publish one useful run path from clean install to reviewable output
|
|
145
|
+
- publish one useful import-only path from third-party result to reviewable output
|
|
146
|
+
- integrate canonical runtime surfaces while legacy imports remain compat-only
|
|
147
|
+
|
|
148
|
+
## 0.3.8 Release Highlights
|
|
149
|
+
|
|
150
|
+
- Runtime now publishes advanced DIA-NN dry-run, resume, comparison, archive,
|
|
151
|
+
and architecture-demo workflows as public owner surfaces.
|
|
152
|
+
- Workflow DAG typing, semantic cache fingerprints, partial rerun plans,
|
|
153
|
+
workflow failure artifacts, and reviewable handoff archives now stay
|
|
154
|
+
machine-readable instead of living in ad hoc runtime glue.
|
|
155
|
+
- Black-box rerun and reviewable sequence/import paths are now explicit parts
|
|
156
|
+
of the runtime trust story rather than maintainer-only knowledge.
|
|
157
|
+
|
|
158
|
+
## Installation
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
pip install bijux-proteomics-runtime
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Quick start
|
|
165
|
+
|
|
166
|
+
Use the runtime CLI for end-to-end workflow execution, replay, and reviewable
|
|
167
|
+
run outputs:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
bijux-proteomics-runtime --help
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Use exact owner modules for Python integrations:
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
from bijux_proteomics_runtime.api.app import AppConfig, create_app
|
|
177
|
+
from bijux_proteomics_runtime.runs.manager import RunManager
|
|
178
|
+
from bijux_proteomics_runtime.workflows.paths import (
|
|
179
|
+
run_reviewable_import_path,
|
|
180
|
+
run_reviewable_sequence_path,
|
|
181
|
+
)
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
The package root remains a stable external entrypoint surface, but runtime
|
|
185
|
+
maintainers and in-repo consumers should import the exact owner modules above
|
|
186
|
+
instead of widening `bijux_proteomics_runtime` into a convenience bucket.
|
|
187
|
+
|
|
188
|
+
## Public APIs
|
|
189
|
+
|
|
190
|
+
The stable root API stays intentionally small:
|
|
191
|
+
|
|
192
|
+
- `AppConfig` for runtime app configuration
|
|
193
|
+
- `create_app(...)` for the canonical FastAPI assembly path
|
|
194
|
+
- `RunManager` for execution coordination
|
|
195
|
+
- `api.cli:cli` for the supported operator command surface
|
|
196
|
+
|
|
197
|
+
Minimal executable example:
|
|
198
|
+
|
|
199
|
+
```python
|
|
200
|
+
from pathlib import Path
|
|
201
|
+
|
|
202
|
+
from bijux_proteomics_runtime import AppConfig, create_app
|
|
203
|
+
|
|
204
|
+
base_dir = Path("artifacts/readme-runtime-app")
|
|
205
|
+
app = create_app(AppConfig(base_dir=base_dir, docs_enabled=False))
|
|
206
|
+
|
|
207
|
+
assert app.state.base_dir == base_dir
|
|
208
|
+
assert app.docs_url is None
|
|
209
|
+
assert any(route.path == "/health" for route in app.routes)
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## Package identity
|
|
213
|
+
|
|
214
|
+
- Distribution name: `bijux-proteomics-runtime`
|
|
215
|
+
- Import root: `bijux_proteomics_runtime`
|
|
216
|
+
- Flagship workflow CLI command: `bijux-proteomics-runtime`
|
|
217
|
+
- Stable entrypoints: `AppConfig`, `RunManager`, `create_app`, and `api.cli:cli`
|
|
218
|
+
- Execution charter: `src/bijux_proteomics_runtime/governance/charter.py`
|
|
219
|
+
- First-level owner families: `api/`, `execution/`, `governance/`, `providers/`, `runs/`, `state/`, `support/`, and `workflows/`
|
|
220
|
+
- Compatibility forwarding lives in `agentic-proteins`; the canonical runtime package keeps only owner paths
|
|
221
|
+
|
|
222
|
+
## Package boundaries
|
|
223
|
+
|
|
224
|
+
This package owns runtime execution behavior and orchestration interfaces.
|
|
225
|
+
|
|
226
|
+
Domain meaning, evidence semantics, scoring policy, and lab planning semantics
|
|
227
|
+
remain in their dedicated lower-layer packages.
|
|
228
|
+
|
|
229
|
+
## What this package must not do
|
|
230
|
+
|
|
231
|
+
- it must not redefine scientific workflow truth, evidence truth, or recommendation policy
|
|
232
|
+
- it must not absorb knowledge curation or lab execution semantics into runtime transport
|
|
233
|
+
- it must not pretend container orchestration, scheduler policy, or external-engine provenance are runtime-owned science
|
|
234
|
+
|
|
235
|
+
## Execution charter
|
|
236
|
+
|
|
237
|
+
- `governance/charter.py` defines the exact runtime-owned capability boundary and classifies every source module against it
|
|
238
|
+
- runtime only owns canonical entrypoints, provider binding, workflow execution, replay and recovery, and reviewable run outputs
|
|
239
|
+
- modules that cannot be defended against that charter should move out of runtime or be deleted rather than hardening into generic infrastructure
|
|
240
|
+
|
|
241
|
+
## Supported execution surfaces
|
|
242
|
+
|
|
243
|
+
Launch surfaces:
|
|
244
|
+
|
|
245
|
+
- `launch_surface="local"` runs through `runs/manager.py` inside the current workspace and persists canonical review artifacts
|
|
246
|
+
- `launch_surface="container"` emits container launch bundles and digest capture through `runs/launch_bundles.py`; runtime does not build images or define container fleet policy
|
|
247
|
+
- `launch_surface="scheduler"` emits scheduler submission bundles and replay-safe metadata through `runs/launch_bundles.py`; runtime does not own queue policy, job priority rules, or cluster provisioning
|
|
248
|
+
- `launch_surface="import"` normalizes third-party outputs through `runs/import_lineage.py`; runtime does not claim new scientific derivation for imported evidence
|
|
249
|
+
|
|
250
|
+
Execution modes:
|
|
251
|
+
|
|
252
|
+
- `execution_mode="auto"` lets provider capability checks choose an allowed mode; runtime may degrade to CPU when provider support or configured budgets require it
|
|
253
|
+
- `execution_mode="cpu"` forces CPU-compatible execution; runtime does not emulate GPU-only providers when a CPU path is unavailable
|
|
254
|
+
- `execution_mode="gpu"` requires GPU-capable providers and an execution environment that can honor that request; runtime does not provision GPUs or schedule cluster policy
|
|
255
|
+
|
|
256
|
+
Non-goals for these surfaces:
|
|
257
|
+
|
|
258
|
+
- runtime does not define workflow truth, evidence truth, scoring truth, or lab truth
|
|
259
|
+
- runtime does not promise every provider on every launch surface
|
|
260
|
+
- runtime does not replace container orchestration, scheduler administration, or external-engine provenance
|
|
261
|
+
|
|
262
|
+
## Canonical owner imports
|
|
263
|
+
|
|
264
|
+
- `bijux_proteomics_runtime.api.cli` for CLI contracts and operator-safe command output
|
|
265
|
+
- `bijux_proteomics_runtime.api.app` for `AppConfig`, FastAPI construction, and request-scoped runtime wiring
|
|
266
|
+
- `bijux_proteomics_runtime.api.routes.runtime_execution` for runtime execution HTTP routes
|
|
267
|
+
- `bijux_proteomics_runtime.runs.manager` for canonical execution coordination
|
|
268
|
+
- `bijux_proteomics_runtime.runs.preflight` for readiness and refusal reports
|
|
269
|
+
- `bijux_proteomics_runtime.runs.replay_decisions` and `runs.execution_decisions` for operator-visible reuse and degraded-mode reasoning
|
|
270
|
+
- `bijux_proteomics_runtime.runs.import_lineage` for import traces and derived-artifact separation
|
|
271
|
+
- `bijux_proteomics_runtime.workflows.paths` for reviewable runtime path manifests
|
|
272
|
+
- `bijux_proteomics_runtime.providers.selection` and `providers.capabilities` for provider binding and capability gates
|
|
273
|
+
|
|
274
|
+
## Operational review paths
|
|
275
|
+
|
|
276
|
+
- `run_reviewable_sequence_path` publishes a runtime-owned manifest from canonical execution to reviewable output
|
|
277
|
+
- `run_reviewable_import_path` publishes a runtime-owned manifest from third-party evidence import to reviewable output
|
|
278
|
+
- `build_runtime_smoke_workflows` declares the supported smoke paths for sequence-to-digest, DDA import, DIA import, quant review, PTM review, analytical review, and lab handoff
|
|
279
|
+
- `build_runtime_partial_rerun_plan` exposes dependency-graph rerun boundaries instead of leaving replay reuse implicit
|
|
280
|
+
- `build_runtime_preflight_report`, `verify_runtime_artifact_integrity`, and `write_runtime_failure_report` keep readiness, reuse safety, and failure classification on explicit run-owned support surfaces
|
|
281
|
+
|
|
282
|
+
## Contract checkpoints
|
|
283
|
+
|
|
284
|
+
- runtime entrypoints must remain canonical while compat imports forward to them
|
|
285
|
+
- lower-layer meaning must stay below runtime owner families rather than being redefined here
|
|
286
|
+
- replay, artifact, and provider contracts must remain explicit and testable
|
|
287
|
+
- run context, artifact ledger, replay/import bundles, checkpoint artifacts, and preflight outputs must remain machine-readable and reviewable
|
|
288
|
+
- changes to canonical ownership should land in runtime before compat forwarding expands
|
|
289
|
+
|
|
290
|
+
## Foundation-backed runtime contract examples
|
|
291
|
+
|
|
292
|
+
Runtime-owned examples that depend on shared foundation primitives stay here so
|
|
293
|
+
the foundation package does not read like a workflow product.
|
|
294
|
+
|
|
295
|
+
Document metadata:
|
|
296
|
+
|
|
297
|
+
```python
|
|
298
|
+
from bijux_proteomics_foundation import DocumentSchema
|
|
299
|
+
|
|
300
|
+
schema = DocumentSchema(
|
|
301
|
+
created_by="bijux-proteomics-runtime",
|
|
302
|
+
document_kind="artifact_bundle",
|
|
303
|
+
package_name="bijux-proteomics-runtime",
|
|
304
|
+
package_version="0.3.8",
|
|
305
|
+
)
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
Runtime refusal:
|
|
309
|
+
|
|
310
|
+
```python
|
|
311
|
+
from bijux_proteomics_foundation.outcomes.refusals import OperationRefusal, RefusalKind
|
|
312
|
+
from bijux_proteomics_foundation.support.states import SupportState
|
|
313
|
+
|
|
314
|
+
refusal = OperationRefusal(
|
|
315
|
+
operation="mzidentml_ingestion",
|
|
316
|
+
kind=RefusalKind.UNSUPPORTED,
|
|
317
|
+
code="unsupported_construct",
|
|
318
|
+
reason="the source export cannot be normalized honestly",
|
|
319
|
+
support_state=SupportState.REFUSED,
|
|
320
|
+
)
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Runtime error envelope:
|
|
324
|
+
|
|
325
|
+
```python
|
|
326
|
+
from bijux_proteomics_foundation.support.error_models import (
|
|
327
|
+
ErrorCategory,
|
|
328
|
+
ErrorEnvelope,
|
|
329
|
+
)
|
|
330
|
+
|
|
331
|
+
envelope = ErrorEnvelope(
|
|
332
|
+
category=ErrorCategory.RUNTIME,
|
|
333
|
+
code="engine_timeout",
|
|
334
|
+
message="external engine did not complete before timeout",
|
|
335
|
+
)
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
Runtime operation result:
|
|
339
|
+
|
|
340
|
+
```python
|
|
341
|
+
from bijux_proteomics_foundation.outcomes.results import OperationResult
|
|
342
|
+
|
|
343
|
+
result = OperationResult.success(
|
|
344
|
+
operation="hash_manifest",
|
|
345
|
+
summary="hash computed successfully",
|
|
346
|
+
output_fingerprint="a" * 64,
|
|
347
|
+
)
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
## Choose this package when
|
|
351
|
+
|
|
352
|
+
- you need canonical CLI, API, provider binding, or replay-safe orchestration
|
|
353
|
+
- the change affects how canonical execution runs rather than what lower layers mean
|
|
354
|
+
- operator-facing entrypoints or runtime control helpers need to evolve without pushing
|
|
355
|
+
runtime ownership downward
|
|
356
|
+
|
|
357
|
+
## Route elsewhere when
|
|
358
|
+
|
|
359
|
+
- the change defines schema, lifecycle, evidence, ranking, or lab semantics
|
|
360
|
+
- the helper only exists to preserve historical imports instead of canonical
|
|
361
|
+
runtime behavior
|
|
362
|
+
- the provider-specific rule would force lower packages to import runtime
|
|
363
|
+
|
|
364
|
+
## Verification route
|
|
365
|
+
|
|
366
|
+
- check `tests` for runtime surface, provider, replay, and migration proof
|
|
367
|
+
before treating a runtime change as safe
|
|
368
|
+
- review `docs/BOUNDARIES.md`, `docs/CONTRACTS.md`, and `docs/ARCHITECTURE.md`
|
|
369
|
+
when canonical ownership or adapter law is part of the change
|
|
370
|
+
- use `README.md`, `CHANGELOG.md`, and package `docs/*.md` when the change
|
|
371
|
+
affects package publication, metadata, or release-readiness expectations
|
|
372
|
+
|
|
373
|
+
## Review questions
|
|
374
|
+
|
|
375
|
+
- does the change preserve canonical operator entrypoints, provider binding, or
|
|
376
|
+
replay-safe orchestration rather than lower-layer domain semantics
|
|
377
|
+
- would compat or lower packages start carrying shadow execution transport or
|
|
378
|
+
adapter law if this behavior stayed outside runtime
|
|
379
|
+
- can the change be justified as runtime-local work instead of a missing lower
|
|
380
|
+
package contract or a compat-only bridge
|
|
381
|
+
|
|
382
|
+
## Escalation route
|
|
383
|
+
|
|
384
|
+
- route the change downward when the behavior actually defines schema,
|
|
385
|
+
lifecycle, evidence, ranking, or lab semantics
|
|
386
|
+
- stop and review `docs/BOUNDARIES.md` and `docs/ARCHITECTURE.md` when the
|
|
387
|
+
proposal starts looking like compatibility glue or provider-specific policy
|
|
388
|
+
rather than canonical runtime orchestration
|
|
389
|
+
- escalate before release when adopting the change would force lower packages or
|
|
390
|
+
compat surfaces to mirror new runtime-local exceptions
|
|
391
|
+
|
|
392
|
+
## Consumer impact signals
|
|
393
|
+
|
|
394
|
+
- expect cross-surface review when CLI, API, provider binding, replay behavior,
|
|
395
|
+
or migration expectations change because operators consume them directly
|
|
396
|
+
- treat changes that alter canonical entrypoints, runtime control helpers, or compat
|
|
397
|
+
expectations as high-impact even when import paths stay stable
|
|
398
|
+
- expect a narrower release burden when the change only improves internal
|
|
399
|
+
orchestration without changing runtime-facing behavior
|
|
400
|
+
|
|
401
|
+
## Explicit non-goals
|
|
402
|
+
|
|
403
|
+
- this package does not redefine schema, lifecycle, evidence, ranking, or lab
|
|
404
|
+
semantics owned by lower layers
|
|
405
|
+
- this package does not serve as a dumping ground for compat-only exceptions or
|
|
406
|
+
migration shims
|
|
407
|
+
- this package does not decide scientific truth, only how canonical execution
|
|
408
|
+
runs over lower-layer contracts
|
|
409
|
+
- this package does not substitute for an end-to-end scientific workflow model
|
|
410
|
+
across core, intelligence, knowledge, and lab
|
|
411
|
+
|
|
412
|
+
## Source guide
|
|
413
|
+
|
|
414
|
+
- [`src/bijux_proteomics_runtime/runs`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/runs) for typed run contracts, canonical run operations, and execution ownership
|
|
415
|
+
- [`src/bijux_proteomics_runtime/workflows`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/workflows) for workflow planning, reproducibility, reviewable path manifests, and execution assurance ledgers
|
|
416
|
+
- [`src/bijux_proteomics_runtime/governance/charter.py`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/governance/charter.py) for the machine-readable execution charter and module audit
|
|
417
|
+
- [`src/bijux_proteomics_runtime/api/cli.py`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/api/cli.py) for CLI contracts
|
|
418
|
+
- [`src/bijux_proteomics_runtime/api`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/api) for HTTP entrypoints
|
|
419
|
+
- [`src/bijux_proteomics_runtime/providers`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/providers) for provider cataloging, capability gates, selection, and execution environment contracts
|
|
420
|
+
- [`src/bijux_proteomics_runtime/support`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/support) for execution primitives, artifact format contracts, and workspace support
|
|
421
|
+
- [`artifacts/<run-id>`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime) for persisted runtime bundle, checkpoint, and integrity outputs at execution time
|
|
422
|
+
- [`tests`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/tests) for executable surface and migration expectations
|
|
423
|
+
|
|
424
|
+
## Documentation
|
|
425
|
+
|
|
426
|
+
- [Advanced DIA-NN Python API tutorial](docs/ADVANCED-DIANN-PYTHON-API.md)
|
|
427
|
+
- [Execution overview](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/execution-overview/)
|
|
428
|
+
- [Operator rerun journey](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/operator-rerun-journey/)
|
|
429
|
+
- [Product architecture](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/product-architecture/)
|
|
430
|
+
- [Cross-package ownership](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/cross-package-ownership/)
|
|
431
|
+
- [Public surfaces dossier](docs/PUBLIC-SURFACES.md)
|
|
432
|
+
- [Route ownership dossier](docs/ROUTE-OWNERSHIP.md)
|
|
433
|
+
- [Provider ownership dossier](docs/PROVIDER-OWNERSHIP.md)
|
|
434
|
+
- [Artifact lineage dossier](docs/ARTIFACT-LINEAGE.md)
|
|
435
|
+
- [Benchmark rerun kits](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/benchmark-rerun-kits/)
|
|
436
|
+
- [Package guide](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/)
|
|
437
|
+
- [Runtime execution boundary](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/runtime-execution-boundary/)
|
|
438
|
+
- [Runtime environment contracts](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/runtime-environment-contracts/)
|
|
439
|
+
- [Runtime artifact stability](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/runtime-artifact-stability/)
|
|
440
|
+
- [Repository release and versioning](https://bijux.io/bijux-proteomics/01-bijux-proteomics/operations/release-and-versioning/)
|
|
@@ -0,0 +1,376 @@
|
|
|
1
|
+
# bijux-proteomics-runtime
|
|
2
|
+
|
|
3
|
+
<!-- bijux-proteomics-badges:generated:start -->
|
|
4
|
+
[](https://pypi.org/project/bijux-proteomics-runtime/)
|
|
5
|
+
[-0A7BBB)](https://pypi.org/project/bijux-proteomics-runtime/)
|
|
6
|
+
[](https://github.com/bijux/bijux-proteomics/blob/main/LICENSE)
|
|
7
|
+
[](https://github.com/bijux/bijux-proteomics/actions/workflows/verify.yml?query=branch%3Amain)
|
|
8
|
+
[](https://github.com/bijux/bijux-proteomics)
|
|
9
|
+
|
|
10
|
+
[](https://pypi.org/project/bijux-proteomics-runtime/)
|
|
11
|
+
[](https://pypi.org/project/agentic-proteins/)
|
|
12
|
+
[](https://pypi.org/project/bijux-proteomics-foundation/)
|
|
13
|
+
[](https://pypi.org/project/bijux-proteomics-core/)
|
|
14
|
+
[](https://pypi.org/project/bijux-proteomics-intelligence/)
|
|
15
|
+
[](https://pypi.org/project/bijux-proteomics-knowledge/)
|
|
16
|
+
[](https://pypi.org/project/bijux-proteomics-lab/)
|
|
17
|
+
|
|
18
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fagentic-proteins)
|
|
19
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-foundation)
|
|
20
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-core)
|
|
21
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-intelligence)
|
|
22
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-knowledge)
|
|
23
|
+
[](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-lab)
|
|
24
|
+
|
|
25
|
+
[](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/)
|
|
26
|
+
[](https://bijux.io/bijux-proteomics/02-agentic-proteins/)
|
|
27
|
+
[](https://bijux.io/bijux-proteomics/03-bijux-proteomics-foundation/)
|
|
28
|
+
[](https://bijux.io/bijux-proteomics/04-bijux-proteomics-core/)
|
|
29
|
+
[](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/)
|
|
30
|
+
[](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/)
|
|
31
|
+
[](https://bijux.io/bijux-proteomics/07-bijux-proteomics-lab/)
|
|
32
|
+
<!-- bijux-proteomics-badges:generated:end -->
|
|
33
|
+
|
|
34
|
+
`bijux-proteomics-runtime` is the execution owner for provider binding,
|
|
35
|
+
deterministic replay, and operator-facing orchestration surfaces in
|
|
36
|
+
`bijux-proteomics`.
|
|
37
|
+
|
|
38
|
+
Within the suite, runtime owns execution, provider binding, deterministic
|
|
39
|
+
replay, and operator entrypoints.
|
|
40
|
+
|
|
41
|
+
Use this package when you need supported CLI, HTTP API, provider wiring,
|
|
42
|
+
runtime state handling, and replay-safe orchestration for the bounded
|
|
43
|
+
flagship workflow chain.
|
|
44
|
+
|
|
45
|
+
Runtime owns execution control. It does not own the scientific workflow
|
|
46
|
+
blueprint, evidence truth, ranking semantics, or lab progression logic that the
|
|
47
|
+
wider proteomics engine still needs.
|
|
48
|
+
|
|
49
|
+
## At a glance
|
|
50
|
+
|
|
51
|
+
- Use runtime when the concern is executable workflow control, provider
|
|
52
|
+
binding, deterministic replay, or operator-facing handoff.
|
|
53
|
+
- Start with `bijux-proteomics-runtime --help` for the live CLI surface, then
|
|
54
|
+
open the
|
|
55
|
+
[runtime handbook](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/)
|
|
56
|
+
when you need the end-to-end run path.
|
|
57
|
+
- Route scientific truth to core, cited evidence memory to knowledge,
|
|
58
|
+
recommendation posture to intelligence, and assay follow-up authority to
|
|
59
|
+
lab.
|
|
60
|
+
|
|
61
|
+
## Why teams pick this package
|
|
62
|
+
|
|
63
|
+
- one canonical runtime surface for CLI, API, orchestration, and providers
|
|
64
|
+
- deterministic replay and artifact shaping for repeatable execution outcomes
|
|
65
|
+
- typed run context, artifact ledger, replay contract, and local/container/scheduler/import run bundle outputs
|
|
66
|
+
- runtime-owned CLI and API operations that avoid private helper glue
|
|
67
|
+
- reviewable run and import paths that publish canonical downstream-facing manifests
|
|
68
|
+
- partial rerun planning, cache claims, cleanup plans, and failure-recovery audits for operational safety
|
|
69
|
+
- preflight and failure reports that fail early on missing execution requirements
|
|
70
|
+
- import traces, human-review resume checkpoints, and artifact-integrity reports for safe reuse
|
|
71
|
+
- runtime-owned control surfaces that consume lower-layer contracts without re-exporting their domain semantics
|
|
72
|
+
- explicit migration target for `agentic-proteins` compatibility forwarding
|
|
73
|
+
|
|
74
|
+
## Typical use cases
|
|
75
|
+
|
|
76
|
+
- run the canonical proteomics workflow through CLI or HTTP entrypoints
|
|
77
|
+
- bind local or API-backed structure providers behind one orchestration layer
|
|
78
|
+
- enforce replay-safe runtime execution without moving domain semantics upward
|
|
79
|
+
- ingest third-party engine outputs while preserving external provenance honestly
|
|
80
|
+
- publish one useful run path from clean install to reviewable output
|
|
81
|
+
- publish one useful import-only path from third-party result to reviewable output
|
|
82
|
+
- integrate canonical runtime surfaces while legacy imports remain compat-only
|
|
83
|
+
|
|
84
|
+
## 0.3.8 Release Highlights
|
|
85
|
+
|
|
86
|
+
- Runtime now publishes advanced DIA-NN dry-run, resume, comparison, archive,
|
|
87
|
+
and architecture-demo workflows as public owner surfaces.
|
|
88
|
+
- Workflow DAG typing, semantic cache fingerprints, partial rerun plans,
|
|
89
|
+
workflow failure artifacts, and reviewable handoff archives now stay
|
|
90
|
+
machine-readable instead of living in ad hoc runtime glue.
|
|
91
|
+
- Black-box rerun and reviewable sequence/import paths are now explicit parts
|
|
92
|
+
of the runtime trust story rather than maintainer-only knowledge.
|
|
93
|
+
|
|
94
|
+
## Installation
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
pip install bijux-proteomics-runtime
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Quick start
|
|
101
|
+
|
|
102
|
+
Use the runtime CLI for end-to-end workflow execution, replay, and reviewable
|
|
103
|
+
run outputs:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
bijux-proteomics-runtime --help
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Use exact owner modules for Python integrations:
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
from bijux_proteomics_runtime.api.app import AppConfig, create_app
|
|
113
|
+
from bijux_proteomics_runtime.runs.manager import RunManager
|
|
114
|
+
from bijux_proteomics_runtime.workflows.paths import (
|
|
115
|
+
run_reviewable_import_path,
|
|
116
|
+
run_reviewable_sequence_path,
|
|
117
|
+
)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
The package root remains a stable external entrypoint surface, but runtime
|
|
121
|
+
maintainers and in-repo consumers should import the exact owner modules above
|
|
122
|
+
instead of widening `bijux_proteomics_runtime` into a convenience bucket.
|
|
123
|
+
|
|
124
|
+
## Public APIs
|
|
125
|
+
|
|
126
|
+
The stable root API stays intentionally small:
|
|
127
|
+
|
|
128
|
+
- `AppConfig` for runtime app configuration
|
|
129
|
+
- `create_app(...)` for the canonical FastAPI assembly path
|
|
130
|
+
- `RunManager` for execution coordination
|
|
131
|
+
- `api.cli:cli` for the supported operator command surface
|
|
132
|
+
|
|
133
|
+
Minimal executable example:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from pathlib import Path
|
|
137
|
+
|
|
138
|
+
from bijux_proteomics_runtime import AppConfig, create_app
|
|
139
|
+
|
|
140
|
+
base_dir = Path("artifacts/readme-runtime-app")
|
|
141
|
+
app = create_app(AppConfig(base_dir=base_dir, docs_enabled=False))
|
|
142
|
+
|
|
143
|
+
assert app.state.base_dir == base_dir
|
|
144
|
+
assert app.docs_url is None
|
|
145
|
+
assert any(route.path == "/health" for route in app.routes)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Package identity
|
|
149
|
+
|
|
150
|
+
- Distribution name: `bijux-proteomics-runtime`
|
|
151
|
+
- Import root: `bijux_proteomics_runtime`
|
|
152
|
+
- Flagship workflow CLI command: `bijux-proteomics-runtime`
|
|
153
|
+
- Stable entrypoints: `AppConfig`, `RunManager`, `create_app`, and `api.cli:cli`
|
|
154
|
+
- Execution charter: `src/bijux_proteomics_runtime/governance/charter.py`
|
|
155
|
+
- First-level owner families: `api/`, `execution/`, `governance/`, `providers/`, `runs/`, `state/`, `support/`, and `workflows/`
|
|
156
|
+
- Compatibility forwarding lives in `agentic-proteins`; the canonical runtime package keeps only owner paths
|
|
157
|
+
|
|
158
|
+
## Package boundaries
|
|
159
|
+
|
|
160
|
+
This package owns runtime execution behavior and orchestration interfaces.
|
|
161
|
+
|
|
162
|
+
Domain meaning, evidence semantics, scoring policy, and lab planning semantics
|
|
163
|
+
remain in their dedicated lower-layer packages.
|
|
164
|
+
|
|
165
|
+
## What this package must not do
|
|
166
|
+
|
|
167
|
+
- it must not redefine scientific workflow truth, evidence truth, or recommendation policy
|
|
168
|
+
- it must not absorb knowledge curation or lab execution semantics into runtime transport
|
|
169
|
+
- it must not pretend container orchestration, scheduler policy, or external-engine provenance are runtime-owned science
|
|
170
|
+
|
|
171
|
+
## Execution charter
|
|
172
|
+
|
|
173
|
+
- `governance/charter.py` defines the exact runtime-owned capability boundary and classifies every source module against it
|
|
174
|
+
- runtime only owns canonical entrypoints, provider binding, workflow execution, replay and recovery, and reviewable run outputs
|
|
175
|
+
- modules that cannot be defended against that charter should move out of runtime or be deleted rather than hardening into generic infrastructure
|
|
176
|
+
|
|
177
|
+
## Supported execution surfaces
|
|
178
|
+
|
|
179
|
+
Launch surfaces:
|
|
180
|
+
|
|
181
|
+
- `launch_surface="local"` runs through `runs/manager.py` inside the current workspace and persists canonical review artifacts
|
|
182
|
+
- `launch_surface="container"` emits container launch bundles and digest capture through `runs/launch_bundles.py`; runtime does not build images or define container fleet policy
|
|
183
|
+
- `launch_surface="scheduler"` emits scheduler submission bundles and replay-safe metadata through `runs/launch_bundles.py`; runtime does not own queue policy, job priority rules, or cluster provisioning
|
|
184
|
+
- `launch_surface="import"` normalizes third-party outputs through `runs/import_lineage.py`; runtime does not claim new scientific derivation for imported evidence
|
|
185
|
+
|
|
186
|
+
Execution modes:
|
|
187
|
+
|
|
188
|
+
- `execution_mode="auto"` lets provider capability checks choose an allowed mode; runtime may degrade to CPU when provider support or configured budgets require it
|
|
189
|
+
- `execution_mode="cpu"` forces CPU-compatible execution; runtime does not emulate GPU-only providers when a CPU path is unavailable
|
|
190
|
+
- `execution_mode="gpu"` requires GPU-capable providers and an execution environment that can honor that request; runtime does not provision GPUs or schedule cluster policy
|
|
191
|
+
|
|
192
|
+
Non-goals for these surfaces:
|
|
193
|
+
|
|
194
|
+
- runtime does not define workflow truth, evidence truth, scoring truth, or lab truth
|
|
195
|
+
- runtime does not promise every provider on every launch surface
|
|
196
|
+
- runtime does not replace container orchestration, scheduler administration, or external-engine provenance
|
|
197
|
+
|
|
198
|
+
## Canonical owner imports
|
|
199
|
+
|
|
200
|
+
- `bijux_proteomics_runtime.api.cli` for CLI contracts and operator-safe command output
|
|
201
|
+
- `bijux_proteomics_runtime.api.app` for `AppConfig`, FastAPI construction, and request-scoped runtime wiring
|
|
202
|
+
- `bijux_proteomics_runtime.api.routes.runtime_execution` for runtime execution HTTP routes
|
|
203
|
+
- `bijux_proteomics_runtime.runs.manager` for canonical execution coordination
|
|
204
|
+
- `bijux_proteomics_runtime.runs.preflight` for readiness and refusal reports
|
|
205
|
+
- `bijux_proteomics_runtime.runs.replay_decisions` and `runs.execution_decisions` for operator-visible reuse and degraded-mode reasoning
|
|
206
|
+
- `bijux_proteomics_runtime.runs.import_lineage` for import traces and derived-artifact separation
|
|
207
|
+
- `bijux_proteomics_runtime.workflows.paths` for reviewable runtime path manifests
|
|
208
|
+
- `bijux_proteomics_runtime.providers.selection` and `providers.capabilities` for provider binding and capability gates
|
|
209
|
+
|
|
210
|
+
## Operational review paths
|
|
211
|
+
|
|
212
|
+
- `run_reviewable_sequence_path` publishes a runtime-owned manifest from canonical execution to reviewable output
|
|
213
|
+
- `run_reviewable_import_path` publishes a runtime-owned manifest from third-party evidence import to reviewable output
|
|
214
|
+
- `build_runtime_smoke_workflows` declares the supported smoke paths for sequence-to-digest, DDA import, DIA import, quant review, PTM review, analytical review, and lab handoff
|
|
215
|
+
- `build_runtime_partial_rerun_plan` exposes dependency-graph rerun boundaries instead of leaving replay reuse implicit
|
|
216
|
+
- `build_runtime_preflight_report`, `verify_runtime_artifact_integrity`, and `write_runtime_failure_report` keep readiness, reuse safety, and failure classification on explicit run-owned support surfaces
|
|
217
|
+
|
|
218
|
+
## Contract checkpoints
|
|
219
|
+
|
|
220
|
+
- runtime entrypoints must remain canonical while compat imports forward to them
|
|
221
|
+
- lower-layer meaning must stay below runtime owner families rather than being redefined here
|
|
222
|
+
- replay, artifact, and provider contracts must remain explicit and testable
|
|
223
|
+
- run context, artifact ledger, replay/import bundles, checkpoint artifacts, and preflight outputs must remain machine-readable and reviewable
|
|
224
|
+
- changes to canonical ownership should land in runtime before compat forwarding expands
|
|
225
|
+
|
|
226
|
+
## Foundation-backed runtime contract examples
|
|
227
|
+
|
|
228
|
+
Runtime-owned examples that depend on shared foundation primitives stay here so
|
|
229
|
+
the foundation package does not read like a workflow product.
|
|
230
|
+
|
|
231
|
+
Document metadata:
|
|
232
|
+
|
|
233
|
+
```python
|
|
234
|
+
from bijux_proteomics_foundation import DocumentSchema
|
|
235
|
+
|
|
236
|
+
schema = DocumentSchema(
|
|
237
|
+
created_by="bijux-proteomics-runtime",
|
|
238
|
+
document_kind="artifact_bundle",
|
|
239
|
+
package_name="bijux-proteomics-runtime",
|
|
240
|
+
package_version="0.3.8",
|
|
241
|
+
)
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Runtime refusal:
|
|
245
|
+
|
|
246
|
+
```python
|
|
247
|
+
from bijux_proteomics_foundation.outcomes.refusals import OperationRefusal, RefusalKind
|
|
248
|
+
from bijux_proteomics_foundation.support.states import SupportState
|
|
249
|
+
|
|
250
|
+
refusal = OperationRefusal(
|
|
251
|
+
operation="mzidentml_ingestion",
|
|
252
|
+
kind=RefusalKind.UNSUPPORTED,
|
|
253
|
+
code="unsupported_construct",
|
|
254
|
+
reason="the source export cannot be normalized honestly",
|
|
255
|
+
support_state=SupportState.REFUSED,
|
|
256
|
+
)
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Runtime error envelope:
|
|
260
|
+
|
|
261
|
+
```python
|
|
262
|
+
from bijux_proteomics_foundation.support.error_models import (
|
|
263
|
+
ErrorCategory,
|
|
264
|
+
ErrorEnvelope,
|
|
265
|
+
)
|
|
266
|
+
|
|
267
|
+
envelope = ErrorEnvelope(
|
|
268
|
+
category=ErrorCategory.RUNTIME,
|
|
269
|
+
code="engine_timeout",
|
|
270
|
+
message="external engine did not complete before timeout",
|
|
271
|
+
)
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Runtime operation result:
|
|
275
|
+
|
|
276
|
+
```python
|
|
277
|
+
from bijux_proteomics_foundation.outcomes.results import OperationResult
|
|
278
|
+
|
|
279
|
+
result = OperationResult.success(
|
|
280
|
+
operation="hash_manifest",
|
|
281
|
+
summary="hash computed successfully",
|
|
282
|
+
output_fingerprint="a" * 64,
|
|
283
|
+
)
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
## Choose this package when
|
|
287
|
+
|
|
288
|
+
- you need canonical CLI, API, provider binding, or replay-safe orchestration
|
|
289
|
+
- the change affects how canonical execution runs rather than what lower layers mean
|
|
290
|
+
- operator-facing entrypoints or runtime control helpers need to evolve without pushing
|
|
291
|
+
runtime ownership downward
|
|
292
|
+
|
|
293
|
+
## Route elsewhere when
|
|
294
|
+
|
|
295
|
+
- the change defines schema, lifecycle, evidence, ranking, or lab semantics
|
|
296
|
+
- the helper only exists to preserve historical imports instead of canonical
|
|
297
|
+
runtime behavior
|
|
298
|
+
- the provider-specific rule would force lower packages to import runtime
|
|
299
|
+
|
|
300
|
+
## Verification route
|
|
301
|
+
|
|
302
|
+
- check `tests` for runtime surface, provider, replay, and migration proof
|
|
303
|
+
before treating a runtime change as safe
|
|
304
|
+
- review `docs/BOUNDARIES.md`, `docs/CONTRACTS.md`, and `docs/ARCHITECTURE.md`
|
|
305
|
+
when canonical ownership or adapter law is part of the change
|
|
306
|
+
- use `README.md`, `CHANGELOG.md`, and package `docs/*.md` when the change
|
|
307
|
+
affects package publication, metadata, or release-readiness expectations
|
|
308
|
+
|
|
309
|
+
## Review questions
|
|
310
|
+
|
|
311
|
+
- does the change preserve canonical operator entrypoints, provider binding, or
|
|
312
|
+
replay-safe orchestration rather than lower-layer domain semantics
|
|
313
|
+
- would compat or lower packages start carrying shadow execution transport or
|
|
314
|
+
adapter law if this behavior stayed outside runtime
|
|
315
|
+
- can the change be justified as runtime-local work instead of a missing lower
|
|
316
|
+
package contract or a compat-only bridge
|
|
317
|
+
|
|
318
|
+
## Escalation route
|
|
319
|
+
|
|
320
|
+
- route the change downward when the behavior actually defines schema,
|
|
321
|
+
lifecycle, evidence, ranking, or lab semantics
|
|
322
|
+
- stop and review `docs/BOUNDARIES.md` and `docs/ARCHITECTURE.md` when the
|
|
323
|
+
proposal starts looking like compatibility glue or provider-specific policy
|
|
324
|
+
rather than canonical runtime orchestration
|
|
325
|
+
- escalate before release when adopting the change would force lower packages or
|
|
326
|
+
compat surfaces to mirror new runtime-local exceptions
|
|
327
|
+
|
|
328
|
+
## Consumer impact signals
|
|
329
|
+
|
|
330
|
+
- expect cross-surface review when CLI, API, provider binding, replay behavior,
|
|
331
|
+
or migration expectations change because operators consume them directly
|
|
332
|
+
- treat changes that alter canonical entrypoints, runtime control helpers, or compat
|
|
333
|
+
expectations as high-impact even when import paths stay stable
|
|
334
|
+
- expect a narrower release burden when the change only improves internal
|
|
335
|
+
orchestration without changing runtime-facing behavior
|
|
336
|
+
|
|
337
|
+
## Explicit non-goals
|
|
338
|
+
|
|
339
|
+
- this package does not redefine schema, lifecycle, evidence, ranking, or lab
|
|
340
|
+
semantics owned by lower layers
|
|
341
|
+
- this package does not serve as a dumping ground for compat-only exceptions or
|
|
342
|
+
migration shims
|
|
343
|
+
- this package does not decide scientific truth, only how canonical execution
|
|
344
|
+
runs over lower-layer contracts
|
|
345
|
+
- this package does not substitute for an end-to-end scientific workflow model
|
|
346
|
+
across core, intelligence, knowledge, and lab
|
|
347
|
+
|
|
348
|
+
## Source guide
|
|
349
|
+
|
|
350
|
+
- [`src/bijux_proteomics_runtime/runs`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/runs) for typed run contracts, canonical run operations, and execution ownership
|
|
351
|
+
- [`src/bijux_proteomics_runtime/workflows`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/workflows) for workflow planning, reproducibility, reviewable path manifests, and execution assurance ledgers
|
|
352
|
+
- [`src/bijux_proteomics_runtime/governance/charter.py`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/governance/charter.py) for the machine-readable execution charter and module audit
|
|
353
|
+
- [`src/bijux_proteomics_runtime/api/cli.py`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/api/cli.py) for CLI contracts
|
|
354
|
+
- [`src/bijux_proteomics_runtime/api`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/api) for HTTP entrypoints
|
|
355
|
+
- [`src/bijux_proteomics_runtime/providers`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/providers) for provider cataloging, capability gates, selection, and execution environment contracts
|
|
356
|
+
- [`src/bijux_proteomics_runtime/support`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/support) for execution primitives, artifact format contracts, and workspace support
|
|
357
|
+
- [`artifacts/<run-id>`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime) for persisted runtime bundle, checkpoint, and integrity outputs at execution time
|
|
358
|
+
- [`tests`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-runtime/tests) for executable surface and migration expectations
|
|
359
|
+
|
|
360
|
+
## Documentation
|
|
361
|
+
|
|
362
|
+
- [Advanced DIA-NN Python API tutorial](docs/ADVANCED-DIANN-PYTHON-API.md)
|
|
363
|
+
- [Execution overview](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/execution-overview/)
|
|
364
|
+
- [Operator rerun journey](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/operator-rerun-journey/)
|
|
365
|
+
- [Product architecture](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/product-architecture/)
|
|
366
|
+
- [Cross-package ownership](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/cross-package-ownership/)
|
|
367
|
+
- [Public surfaces dossier](docs/PUBLIC-SURFACES.md)
|
|
368
|
+
- [Route ownership dossier](docs/ROUTE-OWNERSHIP.md)
|
|
369
|
+
- [Provider ownership dossier](docs/PROVIDER-OWNERSHIP.md)
|
|
370
|
+
- [Artifact lineage dossier](docs/ARTIFACT-LINEAGE.md)
|
|
371
|
+
- [Benchmark rerun kits](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/benchmark-rerun-kits/)
|
|
372
|
+
- [Package guide](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/)
|
|
373
|
+
- [Runtime execution boundary](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/runtime-execution-boundary/)
|
|
374
|
+
- [Runtime environment contracts](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/runtime-environment-contracts/)
|
|
375
|
+
- [Runtime artifact stability](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/runtime-artifact-stability/)
|
|
376
|
+
- [Repository release and versioning](https://bijux.io/bijux-proteomics/01-bijux-proteomics/operations/release-and-versioning/)
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27.0,<1.31", "hatch-vcs>=0.4.0,<1.0"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "bijux-proteomics-runtime"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Canonical execution runtime for orchestrating proteomics workflows through CLI, API, provider binding, and deterministic run control"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "Apache-2.0" }
|
|
11
|
+
requires-python = ">=3.11,<4"
|
|
12
|
+
authors = [{ name = "Bijan Mousavi", email = "bijan@bijux.io" }]
|
|
13
|
+
maintainers = [{ name = "Bijan Mousavi", email = "bijan@bijux.io" }]
|
|
14
|
+
keywords = [
|
|
15
|
+
"proteomics",
|
|
16
|
+
"runtime",
|
|
17
|
+
"orchestration",
|
|
18
|
+
"determinism",
|
|
19
|
+
"replay",
|
|
20
|
+
]
|
|
21
|
+
classifiers = [
|
|
22
|
+
"Development Status :: 3 - Alpha",
|
|
23
|
+
"Intended Audience :: Science/Research",
|
|
24
|
+
"Intended Audience :: Developers",
|
|
25
|
+
"License :: OSI Approved :: Apache Software License",
|
|
26
|
+
"Operating System :: OS Independent",
|
|
27
|
+
"Programming Language :: Python :: 3",
|
|
28
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
29
|
+
"Programming Language :: Python :: 3.11",
|
|
30
|
+
"Programming Language :: Python :: 3.12",
|
|
31
|
+
"Programming Language :: Python :: 3.13",
|
|
32
|
+
"Programming Language :: Python :: 3.14",
|
|
33
|
+
"Typing :: Typed",
|
|
34
|
+
]
|
|
35
|
+
dependencies = [
|
|
36
|
+
"requests>=2.31",
|
|
37
|
+
"biopython>=1.83",
|
|
38
|
+
"click>=8.1",
|
|
39
|
+
"fastapi>=0.115",
|
|
40
|
+
"starlette>=1.3.1,<2.0",
|
|
41
|
+
"uvicorn>=0.30",
|
|
42
|
+
"pydantic>=2.0.2",
|
|
43
|
+
"loguru>=0.7",
|
|
44
|
+
"slowapi>=0.1",
|
|
45
|
+
"bijux-proteomics-foundation>=0.3.8",
|
|
46
|
+
"bijux-proteomics-core>=0.3.8",
|
|
47
|
+
"bijux-proteomics-knowledge>=0.3.8",
|
|
48
|
+
"bijux-proteomics-intelligence>=0.3.8",
|
|
49
|
+
"bijux-proteomics-lab>=0.3.8",
|
|
50
|
+
]
|
|
51
|
+
|
|
52
|
+
[project.urls]
|
|
53
|
+
Homepage = "https://bijux.io/bijux-proteomics/"
|
|
54
|
+
Documentation = "https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/"
|
|
55
|
+
Repository = "https://github.com/bijux/bijux-proteomics"
|
|
56
|
+
Issues = "https://github.com/bijux/bijux-proteomics/issues"
|
|
57
|
+
Changelog = "https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-runtime/CHANGELOG.md"
|
|
58
|
+
Security = "https://github.com/bijux/bijux-proteomics/blob/main/SECURITY.md"
|
|
59
|
+
|
|
60
|
+
[project.scripts]
|
|
61
|
+
bijux-proteomics-runtime = "bijux_proteomics_runtime.api.cli:cli"
|
|
62
|
+
|
|
63
|
+
[tool.hatch.version]
|
|
64
|
+
source = "vcs"
|
|
65
|
+
tag-pattern = "^v(?P<version>.*)$"
|
|
66
|
+
fallback-version = "0.3.8"
|
|
67
|
+
raw-options = { git_describe_command = "git describe --dirty --tags --long --match 'v*'", local_scheme = "dirty-tag", version_scheme = "guess-next-dev", root = "../..", search_parent_directories = true }
|
|
68
|
+
|
|
69
|
+
[tool.hatch.build]
|
|
70
|
+
include = [
|
|
71
|
+
"README.md",
|
|
72
|
+
"CHANGELOG.md",
|
|
73
|
+
"src/bijux_proteomics_runtime/py.typed",
|
|
74
|
+
]
|
|
75
|
+
force-include = { "LICENSE" = "LICENSE", "NOTICE" = "NOTICE" }
|
|
76
|
+
|
|
77
|
+
[tool.hatch.build.targets.wheel]
|
|
78
|
+
packages = ["src/bijux_proteomics_runtime"]
|
|
79
|
+
|
|
80
|
+
[tool.hatch.build.targets.wheel.package-data]
|
|
81
|
+
"bijux_proteomics_runtime" = ["py.typed"]
|
|
82
|
+
|
|
83
|
+
[project.optional-dependencies]
|
|
84
|
+
api = [
|
|
85
|
+
"openprotein-python>=0.8.8",
|
|
86
|
+
]
|
|
87
|
+
test = [
|
|
88
|
+
"pytest>=8.4.1,<10.0",
|
|
89
|
+
"pytest-asyncio>=1.0.0,<2.0",
|
|
90
|
+
"pytest-benchmark>=4.0.0,<6.0",
|
|
91
|
+
"pytest-timeout>=2.4.0,<3.0",
|
|
92
|
+
"httpx>=0.27.0,<1.0",
|
|
93
|
+
]
|
|
94
|
+
local-esmfold = [
|
|
95
|
+
"transformers>=5.0.0rc3",
|
|
96
|
+
"tokenizers>=0.14",
|
|
97
|
+
"einops>=0.7",
|
|
98
|
+
]
|
|
99
|
+
local-rosettafold = []
|
|
100
|
+
nl = [
|
|
101
|
+
"langchain-core>=1.3.3",
|
|
102
|
+
"langchain-community>=0.3.27",
|
|
103
|
+
"langchain-huggingface>=1.2.1",
|
|
104
|
+
"langchain-text-splitters>=1.1.2",
|
|
105
|
+
"langsmith>=0.8.0",
|
|
106
|
+
]
|
|
File without changes
|