Journey 14 — Advanced Python surface

Advanced Python surface: inspect_model, EvidenceStore, RankSurrogate, MFBOConfig, and mfbo_search for custom orchestration beyond the CLI.

Prerequisites: Journeys 01–13 complete — full CLI and Session workflow internalized. Scenario: inspect_model · EvidenceStore · RankSurrogate · MFBOConfig

Key APIs

solvjump.inspect_model()
solvjump.EvidenceStore
solvjump.RankSurrogate
solvjump.MFBOConfig
solvjump.mfbo_search()
solvjump check-model examples/brusselator_model.py:make_rhs

Concepts to internalize

inspect_model — same checks as check-model for CI pipelines.
RankSurrogate / MFBO — build custom adaptive loops when YAML strategy is not enough.
EvidenceStore — programmatic access to calibration artifacts.
End of progression — return to APPLICATIONS.md and wire your proprietary model.py.

Important code

The guided tour script wraps this pattern. Copy the production shape into your pipeline:

from solvjump import inspect_model, EvidenceStore, RankSurrogate, MFBOConfig
 
report = inspect_model("examples/brusselator_model.py:make_rhs")
print(report.supports_ranking, report.make_rhs)

Act-by-act walkthrough

Act 1 — The rest of the public package

You have already used Session, run_study, propagate, golden, and verify_ranking. This tour names the remaining exports customers actually import. The product is CLI plus importable Python.

Act 2 — inspect_model

Same contract as solvjump check-model.

Field	Value	Notes
`model`	<product-root>\python\examples\brusselator_model.py:make_rhs
`make_rhs`	True
`terminal_metrics`	True
`supports_ranking`	True
`ok`	True

Act 3 — EvidenceStore

Family-keyed JSONL under ~/.solvjump/evidence (SOLVJUMP_EVIDENCE_DIR). SOLVJUMP_DISABLE_EVIDENCE=1 turns it off. Journey 08 writes records; this lists them.

Field	Value	Notes
`family_count`	1	8a384ff3f2c515e2: 19 observation(s)

Act 4 — RankSurrogate, MFBOConfig, mfbo_search

Adaptive search (Journey 08) calls these internally. You can fit a theta→score map yourself. head='poly2' is numpy-only; 'gbm' needs pip install solvjump[surrogate]. mfbo_search is the low-level loop Session.sweep_adaptive wraps. Surrogate ranking is still not a client claim until you verify against SolvSRK.

Field	Value	Notes
`mfbo_budget_frac`	0.2
`acquisition`	auto
`history_mode`	auto
`available_heads`	('poly2', 'gbm', 'rf')
`mfbo_search`	True
`poly2_predictions`	[0.337, 1.072]

Act 5 — Env and leftover knobs

SOLVJUMP_LICENSE_FILE, SOLVJUMP_C_LIB, SOLVJUMP_SESSION_DIR, SOLVJUMP_QUIET, SOLVJUMP_DISABLE_CACHE, SOLVJUMP_DEV_RECEIPTS=1 (keeps diagnostic fields in receipts). Session.recalibrate() refits an operator on an existing session. That is the full customer surface: CLI plus Python Session.

Guided tour output

Verified console capture from 14_advanced_python.py:

inspect_model · EvidenceStore · RankSurrogate · MFBOConfig

-- Act 1 - The rest of the public package --
  -> You have already used Session, run_study, propagate, golden, and verify_ranking. This tour names the remaining exports customers actually import. The product is CLI plus importable Python.

-- Act 2 - inspect_model --
  -> Same contract as solvjump check-model.
  model: <product-root>\python\examples\brusselator_model.py:make_rhs
  make_rhs: True
  terminal_metrics: True
  supports_ranking: True
  ok: True

-- Act 3 - EvidenceStore --
  -> Family-keyed JSONL under ~/.solvjump/evidence (SOLVJUMP_EVIDENCE_DIR). SOLVJUMP_DISABLE_EVIDENCE=1 turns it off. Journey 08 writes records; this lists them.
  family_count: 1
  -> 8a384ff3f2c515e2: 19 observation(s)

-- Act 4 - RankSurrogate, MFBOConfig, mfbo_search --
  -> Adaptive search (Journey 08) calls these internally. You can fit a theta→score map yourself. head='poly2' is numpy-only; 'gbm' needs pip install solvjump[surrogate]. mfbo_search is the low-level loop Session.sweep_adaptive wraps. Surrogate ranking is still not a client claim until you verify against SolvSRK.
  mfbo_budget_frac: 0.2
  acquisition: auto
  history_mode: auto
  available_heads: ('poly2', 'gbm', 'rf')
  mfbo_search: True
  poly2_predictions: [0.337, 1.072]

-- Act 5 - Env and leftover knobs --
  -> SOLVJUMP_LICENSE_FILE, SOLVJUMP_C_LIB, SOLVJUMP_SESSION_DIR, SOLVJUMP_QUIET, SOLVJUMP_DISABLE_CACHE, SOLVJUMP_DEV_RECEIPTS=1 (keeps diagnostic fields in receipts). Session.recalibrate() refits an operator on an existing session. That is the full customer surface: CLI plus Python Session.

-- Run complete --

Run it

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/14_advanced_python.py
 
# Production one-liner — same API call you ship:
solvjump check-model examples/brusselator_model.py:make_rhs

What comes next

Return to Integration and ship your model + study YAML in your pipeline.

Navigation

← Journey 13 — Scale and HPC gate

13 Scale and HPC gate Integration