Skip to content

Tool API: write down and test the contract (PR 1 of the 0.34 plan; no behaviour change) - #278

Merged
fumitoh merged 9 commits into
mainfrom
claude/stoic-bardeen-qpv3a0
Oct 12, 2026
Merged

fumitoh merged 9 commits into
mainfrom
claude/stoic-bardeen-qpv3a0

Conversation

@fumitoh

@fumitoh fumitoh commented Oct 11, 2026

Copy link
Copy Markdown
Owner

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:

  • The underscore convention. Underscore members of Model, the Space classes, Cells, Macro, ReferenceProxy, the views, the nodes, Formula and the IOSpec classes are public, for tools rather than end users. _impl, a view's _impls, an IOSpec's _io and _manager, Python's special names, and the attributes a class gets from collections.abc and typing bases (such as _abc_impl) are internal.
  • Two tiers. Members listed on the page are frozen from 0.34.0. The rest of the tool API may change or be removed in any release, with a note in the release notes.
  • The deprecation rule. A frozen member warns for at least two minor releases before it changes or goes, and is removed only when the released modelx-bridge and modelx-mcp pass without it. A new optional keyword or a new dict key is not a change, and a fix that makes a member match the page is a bug fix.
  • How a tool checks what modelx provides, without tripping mx.<name> model lookup: getattr(type(obj), name, None), vars(modelx).get(name), modelx.VERSION, and getattr(modelx.core.errors, name, None) for exception classes.
  • The members, grouped by use: identity and addressing, inheritance and dynamic copies, the snapshot wire format spyder-modelx reads, and errors in modelx.core.errors. 115 members in 23 tables, each with a description.
  • About 20 "Known limitation" boxes. Each marks a defect or behaviour a later PR changes. That behaviour is not frozen, may change without deprecation, and no test pins it.

Other docs and docstrings

  • A new Formula reference page. Additions to the Cells, Model, Reference and UserSpace pages.
  • The API tutorial no longer says a Space formula is inherited.
  • Docstrings added or corrected for the listed members, and for get_object, read_model, write_model and zip_model.

Tests

  • modelx/tests/core/api/test_tool_api_surface.py with testdata/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. --write regenerates 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() before close(), as elsewhere in the suite.
  • modelx/tests/core/base/test_spyder_requests.py with testdata/spyder_requests_snapshot.json: a snapshot of what spyder-modelx actually requests.

The design notes

devnotes/ToolAPIDesign.md carries the plan, the decisions settled so far, and a tracker:

  • Decided: 3 (new error classes go in modelx.core.errors, not the top level) and 4 (Spaces have no "derived").
  • Approved: 1 (the contract page and the signature golden) and 2 (the deprecation rule), and the five choices made inside this PR: which objects have a tool API, Known limitations, additions are not changes, the unfrozen tier, and freezing from 0.34.0.

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.rename accepting '', '1x' and 'class', and _is_valid() staying True after Model.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

  • Full test suite, Python 3.11, Linux: 1,558 passed, 8 skipped, 1 failed. The one failure is modelx/tests/export/test_lifelib.py::test_assets, which needs QuantLib; it fails the same way on main in that environment.
  • The three new modules alone: 72 passed, BasicTerm_S included.
  • Sphinx build: no new warnings. The 4 that remain are on main too: _static, intersphinx SSL, a duplicate "spyder" label at installation.rst:164, and eval_formulas.rst not in a toctree.
  • No behaviour change: all 11 non-test Python files have the same AST as on main once docstrings are removed.
  • Python 3.9 syntax: the new test modules parse with 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

claude added 9 commits October 7, 2026 20:29
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
@fumitoh
fumitoh merged commit 1e5e3c4 into main Oct 12, 2026
19 checks passed
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants