Skip to content

Export a formal HistoryProvider Protocol from op_system's public API #183

Description

@jc-macdonald

Motivation

op_system's convolve_history/history_eval_fn machinery has a real, enforced runtime contract: callers pass a history_provider object whose .query(signal_id, body, **options) method gets forwarded as __hist_query inside the compiled history-aware closure (compile.py:1279-1318). This is documented today only as README prose ("Runtime contract from lowering: __hist_query(signal_id, body, **options)") and typed as bare history_provider: object on every public signature that accepts one (CompiledRhs.history_eval_fn, PytreeEvalFn-adjacent wrappers, etc.) — there is no actual Protocol class in the public API to type-check an implementation against.

This matters concretely now: ACCIDDA/op_engine#67 (revised) needs to port ACCIDDA/COVID19_USA's _history.py — a ~400-line fixed-cadence ring-buffer DDE/history provider — into op_engine as the backing implementation for diffrax-based adaptive methods. Without a formal HistoryProvider Protocol exported from op_system, that port has nothing concrete to implement against beyond README prose, and there's no structural protection if the implicit contract drifts as op_system's lowering evolves (e.g. if query's keyword-only options shape changes, nothing would catch a mismatch until a downstream runtime failure).

Scope

  • Define class HistoryProvider(Protocol): def query(self, signal_id: int, body: Array, **options: object) -> Array: ... (exact signature to be confirmed against the real call site at compile.py:1289) in _typing.py (alongside the existing Array protocol) or a new small module.
  • Export HistoryProvider from op_system.__init__'s public __all__.
  • Update CompiledRhs.history_eval_fn and any other history_provider: object-typed signatures to use the new Protocol instead of bare object.
  • Update the README's runnable convolve_history example (ZeroHistoryProvider class) to reference/type-annotate against the new Protocol.

Acceptance criteria

  • HistoryProvider importable from op_system.
  • history_provider parameters across the public API use the Protocol type instead of object (narrows an instance of the broad-object-typing pattern already tracked generally by Tighten backend typing in compile API (replace broad object usage) #78, specifically for this one parameter).
  • mypy --strict passes for touched modules.
  • Existing history/convolve_history tests unaffected (this is a typing-only change, no runtime behavior change).

Relationship to other issues / repos

Directly motivated by ACCIDDA/op_engine#67 (diffrax/lineax-backed adaptive methods, needs to port a HistoryProvider implementation) and ACCIDDA/op_engine#26 (tracking). Narrower, protocol-specific instance of the broader typing cleanup tracked by #78.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions