Repository navigation
Tool API: write down and test the contract (PR 1 of the 0.34 plan; no behaviour change) - #278
Merged
Merged
Conversation
A design, not code. modelx-bridge, modelx-mcp and spyder-modelx need 62 facts from modelx. By the owner's rule that underscore members of modelx objects are the API for tools, 22 already come from the tool API, 28 reach into internals (_impl, modelx.core imports, class-name checks, undocumented behaviour) and 12 cannot be had today. The document proposes the tool-API members, fixes and written contract that close those gaps, and unblocks a Space's inheritance roll-up and a Reference's "used by" links. Section 2 lists the 13 decisions for the owner, each with a recommendation. Every element cites modelx 0.33.0 by file:line. Measured facts name the probe that measured them; those probes were run while the design was written and are not committed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
…re.errors The owner decided where the new exception and warning classes live. They are defined in modelx/core/errors.py beside FormulaError and are not re-exported at the top level; modelx.core.errors is a supported import path for tools and the "API for tools" page lists it. That is where errors come from today (modelx's own tests import them there, tracebacks name modelx.core.errors.FormulaError, and modelx.FormulaError does not exist), and it adds no top-level name that could hide a model of the same name. Updated to match: summary, decision 2 (ToolAPIDeprecationWarning's home), decision 3, the classification (the bridge's FormulaError import is tool API: totals 23/27/12), T12, coverage row 20, the frozen tier and detection idioms, PR 4's files, the bridge's mxcompat helper, the CI audit hook and risk 6. The audit hook's new lookup was re-checked on CPython 3.10-3.14 against a stand-in package. The top-level functions in T13/T14 remain a recommendation for the owner to confirm. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
The owner confirmed that Space classes have no "derived" concept: since 0.24 a base Space's child Spaces are not copied into a sub Space, so no Space is inherited. The draft's BaseSpace._is_derived() (returning _is_dynamic()) and Model._is_derived() are dropped. T3 is now _is_derived() on Cells and References only; a dynamic copy is told by _is_dynamic(). The two needs that asked a Space for a derived flag are N/A: #10 (the bridge's _derived() on a Space) and the Space rows of #47 (spyder's "Is Derived" column, which already leaves them blank). Totals become 23/27/11 plus 1 N/A. The summary also records that the overrides badge for Cells is computable on 0.33 from Cells._is_derived() and the public bases (measured on a three-level chain), and that tree.get's Space entries drop `derived`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
The owner accepted the draft as the plan and approves each design decision when the PR that implements it is ready. The status line says so, and §2 gains a tracker: each decision, the PR that settles it, and its status (3 and 4 decided on 2026-10-09; the rest open). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
Decision 1 was approved with one change: PR 1's reference page covers only the tool API that exists today, and each later PR adds its own section. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
Work in progress on the feature branch, pushed so it is not held only in the session's container. A corrections pass is still running; the reviewed state will follow in a later commit. PR 1 changes no executable code: docs, docstrings and new tests only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
…ange) Decisions 1 and 2 of devnotes/ToolAPIDesign.md, approved by the owner on 2026-10-10: the API for tools is documented and its listed members are frozen, changing only after two minor releases of deprecation warnings. - doc/source/reference/toolapi.rst, "API for tools": the underscore convention, the two tiers (frozen members and other tool API), the deprecation rule, detection idioms, and the existing members tools use for identity and addressing, inheritance and dynamic objects, the snapshot wire, and errors (modelx.core.errors). Only what exists in 0.33; later PRs add their sections. Behaviour that is a defect, or that a later PR changes, is boxed as a Known limitation: documented, not frozen, not pinned by any test. - doc/source/reference/formula.rst (new), and additions to cells.rst (value operations, clearing a formula), model.rst (what tracegraph counts), reference.rst (proxy identity, refmode), userspace.rst (inheritance); api_tutorial.rst no longer says a Space formula is inherited. - Docstrings: get_object, read_model, write_model and zip_model in api.py now describe what they do; the listed members that had none (_idstr, _idtuple, _evalrepr, _get_repr, _is_valid, Cells._is_derived and _is_defined, and the _get_attrdict overrides) have one; _is_root and refmode are corrected; serializer versions "4-7" read "4-8". - Tests: test_tool_api_surface.py pins the signature of every listed member and the listed error classes against a golden; test_tool_contracts.py tests the documented behaviour against tables written by hand, reading no internals; test_spyder_requests.py snapshots what spyder-modelx actually requests. Checked: the full suite passes as before plus 72 new tests (1558 passed, 8 skipped; the one failure, export/test_lifelib.py::test_assets, needs QuantLib, which this environment lacks). The docs build adds no warning or error. Every changed .py file outside the tests has the same AST as before with docstrings removed, so no executable code changed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
Records that PR 1 is implemented (7a12fc2) and awaiting review, and lists the twelve defects of 0.33.0 that implementing it measured, each assigned to the PR that should take it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
The new tool-API tests now tear each model down with _impl._check_sanity() before close(), as the rest of the suite does (.github/copilot-instructions.md). It checks modelx's own invariants, not a tool-API result, so the tests still read no internals to check what they assert. All 72 tests in the three modules pass with it. devnotes/ToolAPIDesign.md records that the owner approved the five choices made inside PR 1 on 2026-10-11. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
This was referenced Oct 12, 2026
fumitoh
pushed a commit
that referenced
this pull request
Oct 17, 2026
The owner decided on 2026-10-17 that tools tell modelx objects apart by
class name, after checking that the class is modelx's own
(type(v).__module__.startswith("modelx.")), and that no _kind class
attribute is added. The names of the ten classes T1 lists become frozen
tool API, with the promise that each lives in the modelx package; the
module paths stay internal. The module check is part of the recipe
because a Reference can hold a user's own class named Model or Cells
(fix-bridge-adoption/b01b).
T1 is rewritten as that recipe, re-measured on main at 1b90682: right for
every kind, nested items, a DynamicSpace, deleted objects and a closed
model's objects, None for user classes, views, nodes and plain values,
at 0.13-0.20 us. A frozen class name cannot be deprecated with a warning,
so a rename is a breaking change with a release note. The decision
moves one line of PR 1's toolapi.rst, which PR 2 changes.
Everything that read _kind follows: T5, T10's is_ref, F11's example, the
C3 wire table, the coverage table, section 5, the PR 2 plan and tests, and
the bridge and spyder adoption notes. The progress line records
#278 and #281 as merged and #282 and #283 as filed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The first of nine PRs in
devnotes/ToolAPIDesign.md(§6), the plan for the tool-API additions in 0.34. It writes down the contract that other software (spyder-modelx, modelx-bridge, modelx-mcp) relies on today, and tests it. No executable code changes: outside the tests, every Python edit is to a docstring.The "API for tools" page
doc/source/reference/toolapi.rst, linked from the reference index:_impl, a view's_impls, an IOSpec's_ioand_manager, Python's special names, and the attributes a class gets fromcollections.abcandtypingbases (such as_abc_impl) are internal.mx.<name>model lookup:getattr(type(obj), name, None),vars(modelx).get(name),modelx.VERSION, andgetattr(modelx.core.errors, name, None)for exception classes.modelx.core.errors. 115 members in 23 tables, each with a description.Other docs and docstrings
get_object,read_model,write_modelandzip_model.Tests
modelx/tests/core/api/test_tool_api_surface.pywithtestdata/tool_api_surface.json: a golden of every listed member's kind and signature, and of the error classes with their bases. It fails when a frozen member disappears, changes kind or changes signature.--writeregenerates it.modelx/tests/core/api/test_tool_contracts.py: the documented behaviour, checked against tables written out by hand. It reads no internals to check a result, and pins no Known limitation, so a fix of one does not fail it. Model teardowns call_impl._check_sanity()beforeclose(), as elsewhere in the suite.modelx/tests/core/base/test_spyder_requests.pywithtestdata/spyder_requests_snapshot.json: a snapshot of what spyder-modelx actually requests.The design notes
devnotes/ToolAPIDesign.mdcarries the plan, the decisions settled so far, and a tracker:modelx.core.errors, not the top level) and 4 (Spaces have no "derived").The other decisions are put to the owner with the PR that implements each.
Writing the page turned up 12 defects in 0.33 that the design had not listed, for example
UserSpace.renameaccepting'','1x'and'class', and_is_valid()staying True afterModel.close(). They are in §9, "Found while implementing PR 1", each assigned to the later PR that should fix it. The page documents each as a Known limitation.Checked
modelx/tests/export/test_lifelib.py::test_assets, which needs QuantLib; it fails the same way onmainin that environment.maintoo:_static, intersphinx SSL, a duplicate "spyder" label at installation.rst:164, and eval_formulas.rst not in a toctree.mainonce docstrings are removed.feature_version=(3, 9). The golden's 60 signatures carry no annotations or object defaults, so they should not differ across the CI matrix. CI here is the first run on 3.9, 3.10 and 3.12–3.14, and on macOS and Windows.🤖 Generated with Claude Code
https://claude.ai/code/session_01LMVwDKYrkyW1zAbzKSK8Zc
Generated by Claude Code