tensorflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# TensorFlow / Keras

Rules and patterns for TensorFlow / Keras model development.
General Python form follows `python-style.instructions.md`.

## Load Patterns and Solutions

Read the following files for named, ready-to-use implementations with when/replaces/gotchas:

- `../../catalogs/tensorflow-patterns.md`
- `../../catalogs/tensorflow-solutions.md`

---

## Baseline

Latest stable metadata-compatible reference assessed on **2026-10-12**:

| CPython | TensorFlow | pandas | NumPy |
| --- | --- | --- | --- |
| 3.12 or 3.13 | 2.21.0 | 3.0.6 | 2.5.4 |
| 3.11 fallback | 2.21.0 | 3.0.6 | 2.4.6 |

Use Keras 3 on the TensorFlow backend. TensorFlow 2.21.0 declares NumPy >= 1.26.0
and Keras >= 3.12.0; pandas 3.0.6 requires Python >= 3.11 and NumPy >= 1.26.0
on these interpreters. NumPy 2.5.4 requires Python >= 3.12; 2.4.6 retains 3.11.
The pack's general Python style remains 3.11+.

- Evidence covers package metadata and wheel availability, not a tested full
  dependency lock or integrated runtime compatibility. Resolve and test the
  destination project's dependencies, including managed runtimes and accelerators.
- TensorFlow 2.21.0 wheels cover macOS 12+ ARM64, glibc 2.27+ Linux
  x86_64/AArch64, and Windows x86_64. No CPython 3.14, Intel macOS, musl Linux,
  or Windows ARM64 wheel is available in this release.
- Native Windows GPU support ended after TF 2.10; newer GPU use needs a supported
  Linux/WSL2 setup. Official macOS GPU support and third-party Metal plugins are
  not established by this reference.

Sources: exact PyPI metadata for [TensorFlow 2.21.0](https://pypi.org/pypi/tensorflow/2.21.0/json),
[pandas 3.0.6](https://pypi.org/pypi/pandas/3.0.6/json),
[NumPy 2.5.4](https://pypi.org/pypi/numpy/2.5.4/json),
[NumPy 2.4.6](https://pypi.org/pypi/numpy/2.4.6/json), and the
[TensorFlow 2.21.0 release](https://github.com/tensorflow/tensorflow/releases/tag/v2.21.0).
These bounds are dated evidence, not open-ended future compatibility guarantees.

Historical migration only: in TF 2.16+, `tf.keras` resolves to Keras 3. Legacy
Keras 2 uses a version-matched `tf-keras` package plus `TF_USE_LEGACY_KERAS=1`
set before importing TensorFlow (catalog entry `tf-keras-compat-shim`). This is
not the reference baseline; retain it only for unmigrated Keras 2 dependencies.

---

## Import Convention

```python
import keras
import numpy as np
import tensorflow as tf

L = keras.layers
```

- Use `keras.*` for models, layers, callbacks, optimizers, losses, metrics, and saving.
- Use `tf.*` only for `tf.data`, `tf.config`, `tf.saved_model`, `tf.signal`, `tf.strings`,
  and eager tensor ops outside a model.
- Why `import keras` over `tf.keras` / `from tensorflow.keras ...`: one explicit Keras 3
  source; `tf.keras` is a lazy alias that silently switches to Keras 2 under
  `TF_USE_LEGACY_KERAS=1`, and static analysis resolves it poorly.
- Inside Functional models use `keras.ops.*` or layers — raw `tf.*` ops on a symbolic
  `KerasTensor` raise in Keras 3.
- Prefer string dtypes in Keras code (`dtype="int32"`).

---

## Legacy → Current

Apply when generating new code or refactoring existing code.

| Legacy | Current |
| --- | --- |
| `from tensorflow.keras.x import Y`, `tf.keras.x.Y` | `import keras`; `keras.x.Y` |
| `model.save("m.h5")`, `save_format="tf"` / `"h5"` | `model.save("m.keras")`; `keras.saving.load_model("m.keras")` |
| SavedModel via `model.save(dir)` or `tf.compat.v1.saved_model.simple_save` | `model.export(dir)`; reload in Keras via `L.TFSMLayer` |
| `ModelCheckpoint("m.h5", save_weights_only=True)` | `"m.weights.h5"` (suffix required); full model → `"m.keras"` |
| `fit_generator` / `evaluate_generator` / `predict_generator` | `fit` / `evaluate` / `predict` with a `tf.data.Dataset`, generator, or `keras.utils.PyDataset` |
| `model.predict_classes(x)` | `np.argmax(model.predict(x), axis=-1)`; sigmoid output: `model.predict(x) > 0.5` |
| `Adam(lr=...)`, `optimizer.lr`, `K.set_value(optimizer.lr, v)` | `Adam(learning_rate=...)`; `optimizer.learning_rate = v`; or a `LearningRateSchedule` |
| `keras.preprocessing.text.Tokenizer` | `L.TextVectorization`, adapted on training text |
| `keras.preprocessing.sequence.pad_sequences` | `keras.utils.pad_sequences`, or `TextVectorization(output_sequence_length=...)` |
| `ImageDataGenerator`, `keras.preprocessing.image.*` | `keras.utils.image_dataset_from_directory` + `L.Rescaling` / `L.RandomFlip` / `L.RandomRotation`; `keras.utils.load_img` / `img_to_array` |
| `tf.data.experimental.AUTOTUNE` | `tf.data.AUTOTUNE` |
| `tf.data` pipeline without `cache` / `prefetch` | `.cache()` (if it fits) → `.shuffle()` → `.batch()` → `.prefetch(tf.data.AUTOTUNE)` |
| `tf.compat.v1`, `Session`, `placeholder`, `tf.estimator` | eager TF2 + Keras `Model.fit`; `@tf.function` for graph compilation |
| `tf.random.set_seed` + `np.random.seed` + `random.seed` | `keras.utils.set_random_seed(seed)` |
| `L.Lambda(fn)` holding custom logic | subclassed `L.Layer` with `get_config` + `@keras.saving.register_keras_serializable()` |
| `tf.*` op or `K.*` backend fn applied to a Functional `KerasTensor` | `keras.ops.*` or a custom layer |
| `keras.utils.to_categorical` + `categorical_crossentropy` | integer labels + `sparse_categorical_crossentropy`; one-hot only for soft labels |
| per-layer or `experimental` mixed-precision policies | `keras.mixed_precision.set_global_policy("mixed_float16")`; output layer `dtype="float32"` |

---

## Training Rules

- Prefer `model.fit` with callbacks. In a custom loop, wrap the step in `@tf.function`
  and compute gradients with `tf.GradientTape`; keep `.numpy()` and Python side effects
  out of the step.
- Call `keras.backend.clear_session()` only between model builds in one long-lived
  process, then re-seed.
- String metrics (`"accuracy"`, `"mae"`) are fine; their names become log keys verbatim.
  Use metric objects when a callback `monitor` key must be predictable.
- Omit `steps_per_epoch` for finite datasets. Set it only for repeated (infinite)
  datasets, as `math.ceil(n_samples / batch_size)`.

From mabrosim/aet-content-pack, MIT.

More from mabrosim/aet-content-pack