howso-engine 67.0.1__tar.gz → 67.2.0__tar.gz

{howso_engine-67.0.1 → howso_engine-67.2.0}/LICENSE-3RD-PARTY.txt

@@ -1,10 +1,10 @@
 Faker
-40.39.0
+40.41.0
 MIT License
 joke2k
 https://github.com/joke2k/faker
 Faker is a Python package that generates fake data for you.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/faker-40.39.0.dist-info/licenses/LICENSE.txt
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/faker-40.41.0.dist-info/licenses/LICENSE.txt
 Copyright (c) 2012 Daniele Faraglia
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -32,7 +32,7 @@ MIT License
 Kirill Simonov
 https://pyyaml.org/
 YAML parser and emitter for Python
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/pyyaml-6.0.3.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/pyyaml-6.0.3.dist-info/licenses/LICENSE
 Copyright (c) 2017-2021 Ingy döt Net
 Copyright (c) 2006-2016 Kirill Simonov
 
@@ -61,7 +61,7 @@ BSD-2-Clause
 Georg Brandl <georg@python.org>
 https://pygments.org
 Pygments is a syntax highlighting package written in Python.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/pygments-2.21.0.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/pygments-2.21.0.dist-info/licenses/LICENSE
 Copyright (c) 2006-2022 by the respective authors (see AUTHORS file).
 All rights reserved.
 
@@ -95,7 +95,7 @@ MIT
 Filipe Laíns <lains@riseup.net>, Bernát Gábor <gaborjbernat@gmail.com>, layday <layday@protonmail.com>, Henry Schreiner <henryschreineriii@gmail.com>
 https://build.pypa.io
 A simple, correct Python build frontend
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/build-1.6.1.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/build-1.6.1.dist-info/licenses/LICENSE
 Copyright © 2019 Filipe Laíns <filipe.lains@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a
@@ -124,7 +124,7 @@ Mozilla Public License 2.0 (MPL 2.0)
 Kenneth Reitz
 https://github.com/certifi/python-certifi
 Python package for providing Mozilla's CA Bundle.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/certifi-2026.7.22.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/certifi-2026.7.22.dist-info/licenses/LICENSE
 This package contains a modified version of ca-bundle.crt:
 
 ca-bundle.crt -- Bundle of CA Root Certificates
@@ -148,12 +148,12 @@ one at http://mozilla.org/MPL/2.0/.
 
 
 charset-normalizer
-3.5.1
+3.5.2
 MIT
 "Ahmed R. TAHRI" <tahri.ahmed@proton.me>
 https://github.com/jawah/charset_normalizer/blob/master/CHANGELOG.md
 The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/charset_normalizer-3.5.1.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/charset_normalizer-3.5.2.dist-info/licenses/LICENSE
 MIT License
 
 Copyright (c) 2025 TAHRI Ahmed R.
@@ -183,7 +183,7 @@ BSD-3-Clause
 UNKNOWN
 https://github.com/pallets/click/
 Composable command line interface toolkit
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/click-8.5.0.dist-info/licenses/LICENSE.txt
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/click-8.5.0.dist-info/licenses/LICENSE.txt
 Copyright 2014 Pallets
 
 Redistribution and use in source and binary forms, with or without
@@ -220,7 +220,7 @@ BSD License
 The cloudpickle developer team
 https://github.com/cloudpipe/cloudpickle
 Pickler class to extend the standard pickle.Pickler functionality
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/cloudpickle-3.1.2.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/cloudpickle-3.1.2.dist-info/licenses/LICENSE
 This module was extracted from the `cloud` package, developed by
 PiCloud, Inc.
 
@@ -261,7 +261,7 @@ MIT
 Jason Moiron <jmoiron@jmoiron.net>
 https://github.com/python-humanize/humanize
 Python humanize utilities
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/humanize-4.16.0.dist-info/licenses/LICENCE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/humanize-4.16.0.dist-info/licenses/LICENCE
 Copyright (c) 2010-2020 Jason Moiron and Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining
@@ -290,7 +290,7 @@ BSD-3-Clause
 Kim Davies <kim+pypi@gumleaf.org>
 https://github.com/kjd/idna
 Internationalized Domain Names in Applications (IDNA)
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/idna-3.20.dist-info/licenses/LICENSE.md
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/idna-3.20.dist-info/licenses/LICENSE.md
 BSD 3-Clause License
 
 Copyright (c) 2013-2026, Kim Davies and contributors.
@@ -330,7 +330,7 @@ BSD-3-Clause
 Gael Varoquaux <gael.varoquaux@normalesup.org>
 https://joblib.readthedocs.io
 Lightweight pipelining with Python functions
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/joblib-1.6.0.dist-info/licenses/LICENSE.txt
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/joblib-1.6.0.dist-info/licenses/LICENSE.txt
 BSD 3-Clause License
 
 Copyright (c) 2008-2021, The joblib developers.
@@ -368,7 +368,7 @@ MIT License
 Chris Sewell <chrisj_sewell@hotmail.com>
 https://github.com/executablebooks/markdown-it-py
 Python port of markdown-it. Markdown parsing, done right!
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/markdown_it_py-4.2.0.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/markdown_it_py-4.2.0.dist-info/licenses/LICENSE
 MIT License
 
 Copyright (c) 2020 ExecutableBookProject
@@ -398,7 +398,7 @@ MIT License
 Taneli Hukkinen <hukkin@users.noreply.github.com>
 https://github.com/executablebooks/mdurl
 Markdown URL utilities
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/mdurl-0.1.2.dist-info/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/mdurl-0.1.2.dist-info/LICENSE
 Copyright (c) 2015 Vitaly Puzrin, Alex Kocharin.
 Copyright (c) 2021 Taneli Hukkinen
 
@@ -448,12 +448,12 @@ IN THE SOFTWARE.
 
 
 mmh3
-5.3.0
+5.3.1
 MIT License
 Hajime Senuma <hajime.senuma@gmail.com>
 https://pypi.org/project/mmh3/
 Python extension for MurmurHash (MurmurHash3), a set of fast and robust hash functions.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/mmh3-5.3.0.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/mmh3-5.3.1.dist-info/licenses/LICENSE
 MIT License
 
 Copyright (c) 2011-2026 Hajime Senuma
@@ -482,7 +482,7 @@ BSD-3-Clause AND 0BSD AND MIT AND Zlib AND CC0-1.0
 Travis E. Oliphant et al.
 https://numpy.org
 Fundamental package for array computing in Python
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/numpy-2.4.6.dist-info/licenses/LICENSE.txt
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/numpy-2.4.6.dist-info/licenses/LICENSE.txt
 Copyright (c) 2005-2025, NumPy Developers.
 All rights reserved.
 
@@ -1426,7 +1426,7 @@ Apache-2.0 OR BSD-2-Clause
 Donald Stufft <donald@stufft.io>
 https://github.com/pypa/packaging
 Core utilities for Python packages
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/packaging-26.3.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/packaging-26.3.dist-info/licenses/LICENSE
 This software is made available under the terms of *either* of the licenses
 found in LICENSE.APACHE or LICENSE.BSD. Contributions to this software is made
 under the terms of *both* these licenses.
@@ -1438,7 +1438,7 @@ BSD License
 The Pandas Development Team <pandas-dev@python.org>
 https://pandas.pydata.org
 Powerful data structures for data analysis, time series, and statistics
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/pandas-2.3.3.dist-info/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/pandas-2.3.3.dist-info/LICENSE
 BSD 3-Clause License
 
 Copyright (c) 2008-2011, AQR Capital Management, LLC, Lambda Foundry, Inc. and PyData Development Team
@@ -2696,7 +2696,7 @@ BSD License
 Vincent Driessen <me@nvie.com>
 https://github.com/jazzband/pip-tools/
 pip-tools keeps your pinned dependencies fresh.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/pip_tools-7.4.1.dist-info/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/pip_tools-7.4.1.dist-info/LICENSE
 BSD 3-Clause License
 
 Copyright (c). All rights reserved.
@@ -2733,7 +2733,7 @@ BSD-3-Clause
 Giampaolo Rodola
 https://github.com/giampaolo/psutil
 Cross-platform lib for process and system monitoring.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/psutil-7.2.2.dist-info/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/psutil-7.2.2.dist-info/LICENSE
 BSD 3-Clause License
 
 Copyright (c) 2009, Jay Loden, Dave Daeschler, Giampaolo Rodola
@@ -2771,7 +2771,7 @@ MIT
 Thomas Kluyver <thomas@kluyver.me.uk>
 https://github.com/pypa/pyproject-hooks
 Wrappers to call pyproject.toml-based build backend hooks.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/pyproject_hooks-1.3.3.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/pyproject_hooks-1.3.3.dist-info/licenses/LICENSE
 The MIT License (MIT)
 
 Copyright (c) 2017 Thomas Kluyver
@@ -2801,7 +2801,7 @@ Apache Software License; BSD License
 Gustavo Niemeyer
 https://github.com/dateutil/dateutil
 Extensions to the standard Python datetime module
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/python_dateutil-2.9.0.post0.dist-info/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/python_dateutil-2.9.0.post0.dist-info/LICENSE
 Copyright 2017- Paul Ganssle <paul@ganssle.io>
 Copyright 2017- dateutil contributors (see AUTHORS file)
 
@@ -2858,12 +2858,12 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 The above BSD License Applies to all code, even that also covered by Apache 2.0.
 
 pytz
-2026.4
+2026.5
 MIT License
 Stuart Bishop
 http://pythonhosted.org/pytz
 World timezone definitions, modern and historical
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/pytz-2026.4.dist-info/LICENSE.txt
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/pytz-2026.5.dist-info/LICENSE.txt
 Copyright (c) 2003-2019 Stuart Bishop <stuart@stuartbishop.net>
 
 Permission is hereby granted, free of charge, to any person obtaining a
@@ -2886,12 +2886,12 @@ DEALINGS IN THE SOFTWARE.
 
 
 regex
-2026.9.10
+2026.9.29
 Apache-2.0 AND CNRI-Python
 Matthew Barnett <regex@mrabarnett.plus.com>
 https://github.com/mrabarnett/mrab-regex
 Alternative regular expression module, to replace re.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/regex-2026.9.10.dist-info/licenses/LICENSE.txt
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/regex-2026.9.29.dist-info/licenses/LICENSE.txt
 This work was derived from the 're' module of CPython 2.6 and CPython 3.1,
 copyright (c) 1998-2001 by Secret Labs AB and licensed under CNRI's Python 1.6
 license.
@@ -3108,7 +3108,7 @@ Apache Software License
 Kenneth Reitz <me@kennethreitz.org>
 https://github.com/psf/requests
 Python HTTP for Humans.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/requests-2.34.2.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/requests-2.34.2.dist-info/licenses/LICENSE
 
                                  Apache License
                            Version 2.0, January 2004
@@ -3292,7 +3292,7 @@ MIT License
 Will McGugan
 https://github.com/Textualize/rich
 Render rich text, tables, progress bars, syntax highlighting, markdown and more to the terminal
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/rich-15.0.0.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/rich-15.0.0.dist-info/licenses/LICENSE
 Copyright (c) 2020 Will McGugan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -3320,7 +3320,7 @@ MIT License
 UNKNOWN
 https://github.com/hplt-project/sacremoses
 SacreMoses
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/sacremoses-0.2.0.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/sacremoses-0.2.0.dist-info/licenses/LICENSE
 MIT License
 
 Copyright (c) 2020 alvations
@@ -3350,7 +3350,7 @@ BSD License
 Raphaël Barrois
 https://github.com/rbarrois/python-semanticversion
 A library implementing the 'SemVer' scheme.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/semantic_version-2.10.0.dist-info/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/semantic_version-2.10.0.dist-info/LICENSE
 Copyright (c) The python-semanticversion project
 All rights reserved.
 
@@ -3381,7 +3381,7 @@ MIT License
 Benjamin Peterson
 https://github.com/benjaminp/six
 Python 2 and 3 compatibility utilities
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/six-1.17.0.dist-info/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/six-1.17.0.dist-info/LICENSE
 Copyright (c) 2010-2024 Benjamin Peterson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
@@ -3408,7 +3408,7 @@ MPL-2.0 AND MIT
 UNKNOWN
 https://tqdm.github.io
 Fast, Extensible Progress Meter
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/tqdm-4.70.1.dist-info/licenses/LICENCE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/tqdm-4.70.1.dist-info/licenses/LICENCE
 `tqdm` is a product of collaborative work.
 Unless otherwise stated, all authors (see commit logs) retain copyright
 for their respective work, and release the work under the MIT licence
@@ -3466,7 +3466,7 @@ PSF-2.0
 "Guido van Rossum, Jukka Lehtosalo, Łukasz Langa, Michael Lee" <levkivskyi@gmail.com>
 https://github.com/python/typing_extensions
 Backported and Experimental Type Hints for Python 3.9+
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/typing_extensions-4.16.0.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/typing_extensions-4.16.0.dist-info/licenses/LICENSE
 A. HISTORY OF THE SOFTWARE
 ==========================
 
@@ -3749,12 +3749,12 @@ PERFORMANCE OF THIS SOFTWARE.
 
 
 tzdata
-2026.4
+2026.5
 Apache-2.0
 Python Software Foundation
 https://github.com/python/tzdata
 Provider of IANA time zone data
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/tzdata-2026.4.dist-info/licenses/LICENSE
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/tzdata-2026.5.dist-info/licenses/LICENSE
 Apache Software License 2.0
 
 Copyright (c) 2020, Paul Ganssle (Google)
@@ -3779,7 +3779,7 @@ MIT
 Andrey Petrov <andrey.petrov@shazow.net>
 https://github.com/urllib3/urllib3/blob/main/CHANGES.rst
 HTTP library with thread-safe connection pooling, file post, and more.
-/home/runner/.pyenv/versions/3.14.7/lib/python3.14/site-packages/urllib3-2.8.0.dist-info/licenses/LICENSE.txt
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/urllib3-2.8.0.dist-info/licenses/LICENSE.txt
 MIT License
 
 Copyright (c) 2008-2020 Andrey Petrov and contributors.

{howso_engine-67.0.1/howso_engine.egg-info → howso_engine-67.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howso-engine
-Version: 67.0.1
+Version: 67.2.0
 Summary: The Howso Engine™ is a natively and fully explainable ML engine, serving as an alternative to black box AI neural networks.
 Author: Howso Incorporated
 Author-email: support@howso.com
@@ -705,7 +705,7 @@ Requires-Dist: sacremoses
 Requires-Dist: semantic-version~=2.0
 Requires-Dist: typing-extensions~=4.9
 Requires-Dist: urllib3>=2.6.3
-Requires-Dist: amalgam-lang==35.0.1
+Requires-Dist: amalgam-lang==35.1.0
 Provides-Extra: dev
 Requires-Dist: dill~=0.0; extra == "dev"
 Requires-Dist: flake8-docstrings; extra == "dev"

{howso_engine-67.0.1 → howso_engine-67.2.0}/howso/client/base.py

@@ -164,15 +164,17 @@ class AbstractHowsoClient(ABC):
             The Trainee feature attributes.
         """
         cached = self.trainee_cache.get_item(trainee_id, None)
-        if cached:
+        if cached is None:
             # Trainee not yet cached, resolve it first
             trainee_id = self._resolve_trainee(trainee_id).id
             cached = self.trainee_cache.get_item(trainee_id)
 
-        if cached["feature_attributes"] is None:
+        feature_attributes = cached.get("feature_attributes")
+        if feature_attributes is None:
             # Feature attributes not yet cached, get them
-            cached["feature_attributes"] = self.get_feature_attributes(trainee_id)
-        return cached["feature_attributes"]
+            feature_attributes = self.get_feature_attributes(trainee_id)
+            cached["feature_attributes"] = feature_attributes
+        return feature_attributes
 
     @abstractmethod
     def _resolve_trainee(self, trainee_id: str, **kwargs) -> Trainee:
@@ -1863,6 +1865,10 @@ class AbstractHowsoClient(ABC):
         produces action_values for the specified action_features conditioned
         on the optionally provided contexts.
 
+        Large requests are split into batches (see ``batch_size``). When the
+        client runs batches concurrently, they do not report engine progress
+        under ``task_id``; ``progress_callback`` reports overall progress.
+
         Parameters
         ----------
         trainee_id : str
@@ -3022,6 +3028,10 @@ class AbstractHowsoClient(ABC):
         corresponding "action" where "action" is the completed 'matrix' for the
         corresponding `action_features` and `derived_action_features`.
 
+        Large requests are split into batches (see ``batch_size``). When the
+        client runs batches concurrently, they do not report engine progress
+        under ``task_id``; ``progress_callback`` reports overall progress.
+
         Parameters
         ----------
         trainee_id : str
@@ -3556,6 +3566,10 @@ class AbstractHowsoClient(ABC):
         r"""
         React to series data predicting stationary feature values.
 
+        Large requests are split into batches (see ``batch_size``). When the
+        client runs batches concurrently, they do not report engine progress
+        under ``task_id``; ``progress_callback`` reports overall progress.
+
         Parameters
         ----------
         trainee_id : str
@@ -4655,6 +4669,7 @@ class AbstractHowsoClient(ABC):
         num_deviation_samples: int | None = None,
         num_feature_probability_samples: int | None = None,
         p_values: Collection[float] | None = None,
+        rand_seed: int | str | None = None,
         rebalance_features: Collection[str] | None = None,
         reduce_only: bool = False,
         targeted_model: TargetedModel | None = None,
@@ -4721,6 +4736,9 @@ class AbstractHowsoClient(ABC):
             multiplied by :math:`10000 \\cdot \\left(1 - \\frac{1}{e}\\right)`.
         p_values : Collection of float, optional
             The p value data parameters to analyze with.
+        rand_seed : int or str, optional
+            A random seed to use for analysis, making the results reproducible.
+            When unspecified, the Trainee's current random state is used.
         rebalance_features : Collection[str], optional
             The list of features whose values to use to rebalance case
             weighting of the data and to store into weight_feature.
@@ -4790,6 +4808,7 @@ class AbstractHowsoClient(ABC):
             num_deviation_samples=num_deviation_samples,
             num_feature_probability_samples=num_feature_probability_samples,
             p_values=p_values,
+            rand_seed=rand_seed,
             rebalance_features=rebalance_features,
             reduce_only=reduce_only,
             targeted_model=targeted_model,

howso_engine-67.2.0/howso/client/cache.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from collections.abc import Collection, Iterator
+import threading
+import typing as t
+
+from semantic_version import Version
+from typing_extensions import NotRequired
+
+if t.TYPE_CHECKING:
+    from howso.client.schemas import Trainee
+
+_T = t.TypeVar("_T")
+
+
+class TraineeCacheItem(t.TypedDict):
+    """Type definition for trainee cache items."""
+
+    trainee: Trainee
+    """Trainee object."""
+
+    feature_attributes: dict[str, dict] | None
+    """Trainee's feature attributes."""
+
+    version: NotRequired[Version]
+    """Version of the Trainee."""
+
+
+class TraineeCache(Collection):
+    """
+    Thread-safe cache of trainee related information, keyed by trainee id.
+
+    A single cache may be shared by clients running on several threads. All
+    access to the cache's set of entries is serialized by a lock owned by the
+    cache.
+
+    The enumeration methods (``ids``, ``items``, ``trainees`` and iteration
+    over the cache) snapshot *which* entries exist, under that lock.
+    Concurrent ``set``, ``discard`` and ``clear`` calls never disturb an
+    enumeration in progress, and an enumeration does not reflect entries
+    added or removed after it was taken.
+
+    The entries themselves are not snapshotted. Each ``TraineeCacheItem``
+    returned by ``get_item`` or ``items`` is the cache's own live entry:
+    assigning to one of its keys updates the cache for every holder, and a
+    later ``set`` for the same trainee id updates a dictionary already handed
+    out. The lock does not cover reads or writes made through an entry.
+    """
+
+    __slots__ = ("_items", "_lock")
+
+    __marker = object()
+
+    def __init__(self) -> None:
+        """Initialize an empty cache."""
+        self._items: dict[str, TraineeCacheItem] = {}
+        self._lock = threading.Lock()
+
+    def set(self, trainee: Trainee, **kwargs) -> None:
+        """
+        Set trainee in cache.
+
+        A trainee id not yet in the cache gets a new entry whose
+        ``feature_attributes`` is ``None``. For an id already in the cache,
+        the entry's ``trainee`` is replaced and ``kwargs`` are merged into
+        the existing entry, keeping any keys not named in ``kwargs``.
+
+        Parameters
+        ----------
+        trainee : Trainee
+            The trainee to cache. Trainees without an id are ignored.
+        **kwargs
+            Additional entry keys to store alongside the trainee.
+        """
+        if trainee.id:
+            with self._lock:
+                item = self._items.setdefault(trainee.id, {"trainee": trainee, "feature_attributes": None})
+                item["trainee"] = trainee
+                # kwargs may carry keys TraineeCacheItem does not declare
+                # (for example a platform ``revision``), so they are assigned
+                # one at a time.
+                for key, value in kwargs.items():
+                    item[key] = value
+
+    def get(self, trainee_id: str, default=__marker) -> Trainee:
+        """Get trainee instance by id."""
+        with self._lock:
+            try:
+                return self._items[trainee_id]["trainee"]
+            except KeyError:
+                if default is self.__marker:
+                    raise
+                return default
+
+    @t.overload
+    def get_item(self, trainee_id: str) -> TraineeCacheItem: ...
+
+    @t.overload
+    def get_item(self, trainee_id: str, default: _T) -> TraineeCacheItem | _T: ...
+
+    def get_item(self, trainee_id: str, default: object = __marker) -> TraineeCacheItem | object:
+        """
+        Get the cache entry for a trainee, by id.
+
+        The returned dictionary is the cache's own live entry, not a copy.
+        Assigning to its keys (for example ``feature_attributes``) changes
+        what the cache holds for this trainee, and a later ``set`` call for
+        the same id changes this dictionary. Once the trainee is discarded,
+        the dictionary is detached from the cache: it keeps its contents, and
+        a subsequent ``set`` for that id creates a new entry.
+
+        Parameters
+        ----------
+        trainee_id : str
+            The id of the trainee.
+        default : optional
+            The value to return if the trainee is not in the cache. If not
+            provided, a missing trainee raises ``KeyError``.
+
+        Returns
+        -------
+        TraineeCacheItem or the type of ``default``
+            The trainee's live cache entry, or ``default``.
+
+        Raises
+        ------
+        KeyError
+            If the trainee is not in the cache and no ``default`` is given.
+        """
+        with self._lock:
+            try:
+                return self._items[trainee_id]
+            except KeyError:
+                if default is self.__marker:
+                    raise
+                return default
+
+    def discard(self, trainee_id: str) -> None:
+        """Remove trainee from cache if exists."""
+        with self._lock:
+            self._items.pop(trainee_id, None)
+
+    def ids(self) -> list[str]:
+        """Return a snapshot list of the ids in the cache."""
+        with self._lock:
+            return list(self._items)
+
+    def items(self) -> list[tuple[str, TraineeCacheItem]]:
+        """
+        Return a list of the ``(id, item)`` pairs in the cache.
+
+        The list is a snapshot of which trainees are cached, but each
+        ``item`` is the cache's own live entry, as returned by ``get_item``.
+        """
+        with self._lock:
+            return list(self._items.items())
+
+    def trainees(self) -> Iterator[tuple[str, Trainee]]:
+        """Return an iterator over a snapshot of the ``(id, trainee)`` pairs in the cache."""
+        with self._lock:
+            snapshot = [(key, item["trainee"]) for key, item in self._items.items()]
+        return iter(snapshot)
+
+    def clear(self) -> None:
+        """Clear the cache."""
+        with self._lock:
+            self._items.clear()
+
+    def __contains__(self, key: object) -> bool:
+        """Return if trainee id is in cache."""
+        with self._lock:
+            return key in self._items
+
+    def __iter__(self) -> Iterator[str]:
+        """Return an iterator over a snapshot of the cached trainee ids."""
+        with self._lock:
+            snapshot = list(self._items)
+        return iter(snapshot)
+
+    def __len__(self) -> int:
+        """Return length of the cache."""
+        with self._lock:
+            return len(self._items)
+
+    def __str__(self) -> str:
+        """Return string representation of the cache."""
+        with self._lock:
+            snapshot = dict(self._items)
+        return str(snapshot)