featm 0.5.7__tar.gz

featm-0.5.7/.gitattributes

@@ -0,0 +1,9 @@
+# Preserve audited product/test bytes, including existing line endings.
+* -text
+*.md text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+LICENSE text eol=lf
+src/featm/** -text
+tests/** -text

featm-0.5.7/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: A minimal reproducer and environment details
+title: ""
+labels: ""
+assignees: ""
+---
+
+## Expected and actual behavior
+
+Describe the selected feature/operation and its expected output.
+
+## Minimal reproducer
+
+Include executable code with synthetic input, explicit features and
+`errors="raise"`. For `warn`/`skip`, also include the execution report and shape.
+
+## Environment
+
+FEATM version; Python version; OS/architecture; installed extras;
+relevant dependency versions; input shape/dtypes; CPU/GPU/Dask configuration.
+
+## Evidence
+
+Paste the exception/traceback or report. Do not include tokens, personal data,
+model weights or large datasets. A checkpoint issue may need a redacted manifest
+and the steps that created it, not a binary artifact from an untrusted source.

featm-0.5.7/.github/scripts/check_release.py

@@ -0,0 +1,26 @@
+"""Check built artifacts without importing the development package."""
+import email,hashlib,json,sys,tarfile,tomllib,zipfile
+from pathlib import Path
+
+root=Path(__file__).resolve().parents[2]
+dist=Path(sys.argv[1]).resolve()
+p=tomllib.loads((root/'pyproject.toml').read_text(encoding='utf-8'))['project']
+assert p['name']=='featm' and p['version']=='0.5.7'
+expected={'featm-0.5.7-py3-none-any.whl','featm-0.5.7.tar.gz'}
+assert {f.name for f in dist.iterdir()}==expected
+with zipfile.ZipFile(dist/'featm-0.5.7-py3-none-any.whl') as w,tarfile.open(dist/'featm-0.5.7.tar.gz') as t:
+ m=email.message_from_string(w.read('featm-0.5.7.dist-info/METADATA').decode('utf-8'))
+ s=email.message_from_string(t.extractfile('featm-0.5.7/PKG-INFO').read().decode('utf-8'))
+ assert m['Name']==s['Name']=='featm' and m['Version']==s['Version']=='0.5.7'
+ assert m.get_all('Requires-Dist')==s.get_all('Requires-Dist')
+ assert m['Requires-Python']==s['Requires-Python']==p['requires-python']
+ assert m.get_payload().replace('\r\n','\n').strip()==(root/'README.md').read_text(encoding='utf-8').strip()
+ licenses=[n for n in w.namelist() if n.endswith('/LICENSE')]
+ assert len(licenses)==1 and w.read(licenses[0])==(root/'LICENSE').read_bytes()
+ assert t.extractfile('featm-0.5.7/LICENSE').read()==(root/'LICENSE').read_bytes()
+ names={x.relative_to(root/'src').as_posix() for x in (root/'src/featm').rglob('*.py')}
+ assert len(names)==77 and names=={n for n in w.namelist() if n.startswith('featm/') and n.endswith('.py')}
+ for n in names:
+  assert w.read(n)==t.extractfile('featm-0.5.7/src/'+n).read()==(root/'src'/n).read_bytes()
+print('PASS: version, metadata, README, license and 77 product files')
+(root/'release-artifact-hashes.json').write_text(json.dumps({f.name:{'sha256':hashlib.sha256(f.read_bytes()).hexdigest(),'bytes':f.stat().st_size} for f in sorted(dist.iterdir())},indent=2))

featm-0.5.7/.github/scripts/test_wheel.py

@@ -0,0 +1,18 @@
+"""Exercise an installed wheel in a fresh environment, never an editable install."""
+import os,subprocess,sys,tempfile,venv
+from pathlib import Path
+
+root=Path(__file__).resolve().parents[2]
+wheel=next(Path(sys.argv[1]).resolve().glob('*.whl'))
+env=os.environ.copy();env.pop('PYTHONPATH',None);env.update(PYTHONNOUSERSITE='1',PYTHONDONTWRITEBYTECODE='1',PYTHONUTF8='1')
+with tempfile.TemporaryDirectory() as tmp:
+ base=Path(tmp);v=base/'env';venv.create(v,with_pip=True)
+ py=v/('Scripts/python.exe' if os.name=='nt' else 'bin/python')
+ def run(*args):subprocess.run([str(py),*map(str,args)],cwd=base,env=env,check=True)
+ # These are test dependencies, not changes to the package's runtime metadata.
+ run('-m','pip','install',wheel,'pytest','networkx','scipy','pyarrow')
+ run('-m','pip','check')
+ run('-c',"import featm,importlib.metadata as m,numpy as np,sys; from pathlib import Path; package_path=Path(featm.__file__).resolve(); environment_path=Path(sys.prefix).resolve(); print('INSTALLED_WHEEL',package_path,'ENVIRONMENT',environment_path); assert package_path.is_relative_to(environment_path), (package_path,environment_path); s=featm.REGISTRY.all(); assert featm.__version__==m.version('featm')=='0.5.7'; assert [len(s),len({x.modality for x in s}),len({(x.modality,x.family) for x in s}),sum(x.stateful for x in s),sum(x.gpu_available for x in s)]==[552,18,182,7,22]; np.testing.assert_allclose(featm.extract(np.array([[1.,2.,3.,4.],[10.,20.,30.,40.]]),features=['timeseries.statistical.mean'],errors='raise').to_numpy().ravel(),[2.5,25.])")
+ cfg=base/'pytest.ini';cfg.write_text('[pytest]\n')
+ runner=base/'runner.py';runner.write_text("import os,sys\nfrom pathlib import Path\nroot=Path(sys.argv.pop(1)); sys.path.insert(0,str(root)); os.chdir(root)\nimport featm,pytest\nassert not Path(featm.__file__).resolve().is_relative_to(root)\nraise SystemExit(pytest.main(sys.argv[1:]))\n")
+ run(runner,root,'-c',cfg,'tests/test_core.py','tests/test_state.py','tests/test_matrix.py','tests/test_v057_checkpoint_root.py','-q','-p','no:cacheprovider')

featm-0.5.7/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: Distribution CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  wheel:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.11']
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Build and inspect distributions
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+          python .github/scripts/check_release.py dist
+      - name: Install wheel into a fresh environment and test
+        run: python .github/scripts/test_wheel.py dist

featm-0.5.7/.github/workflows/publish-pypi.yml

@@ -0,0 +1,69 @@
+name: Publish reviewed release to PyPI
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+concurrency:
+  group: featm-pypi-v0.5.7
+  cancel-in-progress: false
+jobs:
+  build:
+    if: >-
+      github.repository == 'Harish-K22/featm' &&
+      github.repository_id == '1409483295' &&
+      github.event.repository.private == true &&
+      github.actor == 'Harish-K22' &&
+      github.event.release.draft == false &&
+      github.event.release.prerelease == false &&
+      github.event.release.tag_name == 'v0.5.7' &&
+      github.event.release.author.login == 'Harish-K22'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: refs/tags/v0.5.7
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.11'
+      - name: Verify owner-approved release commit
+        env:
+          APPROVED_RELEASE_COMMIT: ${{ vars.FEATM_APPROVED_RELEASE_COMMIT }}
+        run: |
+          python -c "import os,re,subprocess; expected=os.environ['APPROVED_RELEASE_COMMIT']; actual=subprocess.check_output(['git','rev-parse','HEAD'],text=True).strip(); assert re.fullmatch('[0-9a-f]{40}',expected), 'Set the repository variable FEATM_APPROVED_RELEASE_COMMIT to the reviewed full SHA'; assert actual==expected, 'Release tag does not point to the approved commit'; print('Approved source commit:',actual)"
+      - name: Validate exact source version and build
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python -m pip install build twine
+          python -c "import os,tomllib; p=tomllib.load(open('pyproject.toml','rb'))['project']; assert p['name']=='featm' and p['version']=='0.5.7' and os.environ['RELEASE_TAG']=='v'+p['version']"
+          python -m build
+          python -m twine check dist/*
+          python .github/scripts/check_release.py dist
+          python .github/scripts/test_wheel.py dist
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: pypi-distributions
+          path: dist/
+          if-no-files-found: error
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: reviewed-distribution-hashes
+          path: release-artifact-hashes.json
+          if-no-files-found: error
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      actions: read
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: pypi-distributions
+          path: dist/
+      - name: Publish using OIDC
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist/

featm-0.5.7/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+.DS_Store
+Thumbs.db
+.env
+.env.*
+datasets/
+models/
+checkpoints/
+step5_final_results/
+*_AUDIT_HANDOFF.zip

featm-0.5.7/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Release notes
+
+## 0.5.7 — initial public release
+
+FEATM offers a searchable registry for explicit, named feature extraction
+across time series, tabular data and other modalities. Discover names with
+`list_features`, create a callable with `create_feature`, and extract a selected
+set with `extract`. Reuse training-only fitted transformations with `fit`,
+`transform`, `save` and `load_fitted`.
+
+The package includes bounded source execution, disk-backed results, compatible
+checkpoint resume, Dask partition execution and a scoped 22-method CuPy GPU
+surface. Backends and external models are optional; the beginner example uses
+only base dependencies. The supporting catalogue retains 552 entries across
+18 modalities, not a claim of universal predictive improvement.
+
+v0.5.7 rejects non-object checkpoint JSON roots without overwriting invalid
+manifests, while preserving missing-file creation and valid resume behavior.
+The documentation explains time-series shapes, error/report access,
+training-only state, optional installation and execution limits.
+
+Base certification is Windows/Ubuntu-WSL x86-64 CPython 3.10–3.14. Node2vec,
+gensim/text and actual Windows CUDA support have narrower scopes; macOS, ARM
+and Python 3.15 are unvalidated. Short harmonic/tonnetz inputs retain an
+upstream librosa numerical limitation. See [compatibility](docs/COMPATIBILITY.md).
+

featm-0.5.7/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Use explicit named methods, and include a small reproducer when reporting a
+problem. A report should contain the FEATM/Python versions, OS and architecture,
+installed extras and dependency versions, input shape/dtypes, exact feature
+names and parameters, error policy, actual exception/report and expected result.
+For CUDA/Dask, include device/runtime or worker configuration. Remove credentials
+and personal data; prefer synthetic inputs over private datasets.
+
+The owner-confirmed repository is [https://github.com/Harish-K22/featm](https://github.com/Harish-K22/featm).
+Use its [issue tracker](https://github.com/Harish-K22/featm/issues) when available; no private contact
+address or repository visibility is assumed by these instructions.
+
+## Development setup
+
+Once repository access is available, obtain a checkout from `https://github.com/Harish-K22/featm`.
+The package lives in `src/featm/`; method definitions live in `src/featm/features/`
+and stateful encoders in `src/featm/state.py`. From a checkout, in a virtual environment:
+
+```bash
+python -m pip install -e ".[dev,io,distributed,scientific]"
+python -m pytest -q -ra
+```
+
+These are actual extras. Tests for optional backends/models may skip when their
+dependencies are absent; include skip reasons. CUDA tests need the certified
+GPU setup, not merely the development extra. A minimal CI job can use the above
+CPU setup on the tested Windows/Ubuntu x86-64 Python scope; do not add unvalidated
+platform badges or infer optional-wide support from a green base job.
+
+Feature authoring contracts are in [docs/FEATURE_AUTHORING.md](docs/FEATURE_AUTHORING.md).
+Changes should explain inputs, named outputs, dependencies, batch/stateful
+semantics and relevant numerical verification. Avoid committing environments,
+datasets, model weights, checkpoints or private audit material. Product/API
+changes require their own review; this staged release preserves the audited implementation.

featm-0.5.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harish K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

featm-0.5.7/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md LICENSE CONTRIBUTING.md THIRD_PARTY_NOTICES.md CHANGELOG.md
+include .gitignore .gitattributes
+recursive-include docs *.md
+recursive-include examples *.py *.md
+recursive-include tests *.py *.json
+recursive-include benchmarks *.py *.json *.csv
+recursive-include scripts *.py
+recursive-include .github *.md *.yml *.py *.ini
+global-exclude *.pyc *.pyo .DS_Store Thumbs.db
+prune .git
+prune .venv
+prune build
+prune dist

featm-0.5.7/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: featm
+Version: 0.5.7
+Summary: One searchable API for explicit, named feature extraction across data modalities.
+Author: featm contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Harish-K22/featm
+Project-URL: Repository, https://github.com/Harish-K22/featm
+Project-URL: Issues, https://github.com/Harish-K22/featm/issues
+Keywords: feature-engineering,feature-extraction,machine-learning,time-series,signal-processing,computational-geometry,graphs
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: psutil>=5.9
+Provides-Extra: io
+Requires-Dist: pyarrow>=14; extra == "io"
+Requires-Dist: polars>=1.0; extra == "io"
+Provides-Extra: distributed
+Requires-Dist: dask[distributed]>=2024.1; extra == "distributed"
+Provides-Extra: scientific
+Requires-Dist: scipy>=1.10; extra == "scientific"
+Requires-Dist: scikit-learn>=1.3; extra == "scientific"
+Requires-Dist: statsmodels>=0.14; extra == "scientific"
+Provides-Extra: geometry
+Requires-Dist: scipy>=1.10; extra == "geometry"
+Requires-Dist: scikit-learn>=1.3; extra == "geometry"
+Provides-Extra: graph
+Requires-Dist: networkx>=3.0; extra == "graph"
+Requires-Dist: scipy>=1.10; extra == "graph"
+Requires-Dist: python-igraph>=0.11; extra == "graph"
+Requires-Dist: leidenalg>=0.10; extra == "graph"
+Requires-Dist: gensim>=4.4; python_version < "3.14" and extra == "graph"
+Provides-Extra: graph-node2vec
+Requires-Dist: networkx>=3.0; python_version < "3.13" and extra == "graph-node2vec"
+Requires-Dist: gensim>=4.4; python_version < "3.13" and extra == "graph-node2vec"
+Requires-Dist: node2vec>=0.5; python_version < "3.13" and extra == "graph-node2vec"
+Provides-Extra: audio
+Requires-Dist: librosa<1.0,>=0.11; python_version < "3.12" and extra == "audio"
+Requires-Dist: librosa>=1.0; python_version >= "3.12" and extra == "audio"
+Requires-Dist: scipy>=1.10; extra == "audio"
+Provides-Extra: vision
+Requires-Dist: opencv-python>=4.8; extra == "vision"
+Requires-Dist: scikit-image>=0.22; extra == "vision"
+Requires-Dist: scipy>=1.10; extra == "vision"
+Provides-Extra: signal
+Requires-Dist: scipy>=1.10; extra == "signal"
+Requires-Dist: statsmodels>=0.14; extra == "signal"
+Requires-Dist: EMD-signal>=1.6; extra == "signal"
+Requires-Dist: vmdpy>=0.2; extra == "signal"
+Provides-Extra: topology
+Requires-Dist: gudhi>=3.9; extra == "topology"
+Requires-Dist: scipy>=1.10; extra == "topology"
+Provides-Extra: pointcloud
+Requires-Dist: open3d>=0.18; extra == "pointcloud"
+Requires-Dist: scipy>=1.10; extra == "pointcloud"
+Provides-Extra: text
+Requires-Dist: scikit-learn>=1.3; extra == "text"
+Requires-Dist: gensim>=4.4; extra == "text"
+Requires-Dist: spacy>=3.7; extra == "text"
+Provides-Extra: embeddings
+Requires-Dist: torch>=2.2; extra == "embeddings"
+Requires-Dist: timm>=1.0; extra == "embeddings"
+Requires-Dist: transformers>=4.40; extra == "embeddings"
+Requires-Dist: sentence-transformers>=3.0; extra == "embeddings"
+Requires-Dist: Pillow>=10; extra == "embeddings"
+Provides-Extra: calendar
+Requires-Dist: holidays>=0.50; extra == "calendar"
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x[ctk]>=14.0; sys_platform != "darwin" and extra == "gpu"
+Provides-Extra: gpu-cupy
+Requires-Dist: cupy-cuda12x[ctk]>=14.0; sys_platform != "darwin" and extra == "gpu-cupy"
+Provides-Extra: gpu-torch
+Requires-Dist: torch>=2.2; extra == "gpu-torch"
+Provides-Extra: gpu-rapids
+Provides-Extra: full
+Requires-Dist: scipy>=1.10; extra == "full"
+Requires-Dist: scikit-learn>=1.3; extra == "full"
+Requires-Dist: statsmodels>=0.14; extra == "full"
+Requires-Dist: networkx>=3.0; extra == "full"
+Requires-Dist: python-igraph>=0.11; extra == "full"
+Requires-Dist: leidenalg>=0.10; extra == "full"
+Requires-Dist: librosa<1.0,>=0.11; python_version < "3.12" and extra == "full"
+Requires-Dist: librosa>=1.0; python_version >= "3.12" and extra == "full"
+Requires-Dist: opencv-python>=4.8; extra == "full"
+Requires-Dist: scikit-image>=0.22; extra == "full"
+Requires-Dist: EMD-signal>=1.6; extra == "full"
+Requires-Dist: vmdpy>=0.2; extra == "full"
+Requires-Dist: gudhi>=3.9; extra == "full"
+Requires-Dist: open3d>=0.18; extra == "full"
+Requires-Dist: gensim>=4.4; extra == "full"
+Requires-Dist: spacy>=3.7; extra == "full"
+Requires-Dist: holidays>=0.50; extra == "full"
+Requires-Dist: torch>=2.2; extra == "full"
+Requires-Dist: timm>=1.0; extra == "full"
+Requires-Dist: transformers>=4.40; extra == "full"
+Requires-Dist: sentence-transformers>=3.0; extra == "full"
+Requires-Dist: Pillow>=10; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# FEATM
+
+[Repository](https://github.com/Harish-K22/featm) · [Release notes](CHANGELOG.md)
+
+**One searchable API for explicit, named feature extraction across data modalities.**
+
+Use FEATM to discover an existing feature method by name, compute a small feature
+set, and reuse fitted transformations on new data. You choose the methods;
+FEATM does not select features automatically or promise better model accuracy.
+
+## Quickstart
+
+```python
+import numpy as np
+import featm
+
+# Two samples, each with four time steps.
+X = np.array([
+    [1.0, 2.0, 3.0, 4.0],
+    [10.0, 20.0, 30.0, 40.0],
+])
+result = featm.extract(
+    X,
+    features=["timeseries.statistical.mean", "timeseries.statistical.std"],
+    errors="raise",
+)
+print(result)
+```
+
+The mean column contains `2.5` and `25.0`: one output row per input sample.
+For time-series features, `(n_steps,)` means one series, and
+`(n_samples, n_steps)` means a batch. An `(8, 1)` array means eight one-step
+series, **not** one eight-step series. Other modalities use different inputs;
+see [input conventions](docs/GETTING_STARTED.md#input-conventions).
+
+## Installation
+
+Install FEATM from PyPI:
+
+```bash
+pip install featm
+```
+
+During initial release testing, GitHub remains private; see the
+[repository-access note](docs/INSTALLATION.md#initial-publication-period).
+
+The quickstart needs only base dependencies: NumPy, pandas and psutil.
+For checkpoints, Parquet, Arrow or disk-backed output, install the IO extra:
+
+```bash
+python -m pip install "featm[io]"
+```
+
+Quoted requirements work in PowerShell and POSIX shells. See the full
+[installation table](docs/INSTALLATION.md) for minimal optional backends.
+
+## Find a feature
+
+```python
+import numpy as np
+import featm
+
+print(featm.list_features("timeseries.fractal.*"))
+print(featm.list_features("*entropy*"))
+print(featm.list_features("*mean*"))
+
+spec = featm.feature_info("timeseries.statistical.mean")
+print(spec.input_types, spec.requires, spec.default_params)
+mean = featm.create_feature("timeseries.statistical.mean")
+print(mean(np.array([1.0, 2.0, 3.0, 4.0])))
+```
+
+Names follow `modality.family.feature_name`. Narrow a broad search such as
+`timeseries.*` by family. `list_modalities()`, `list_families()` and `search()`
+also help with discovery. Parameters and input types vary by feature;
+[API guidance](docs/API.md) explains what metadata is available.
+Some features, including MFCC, HOG and LBP, expand into multiple named columns.
+There is intentionally no `features="all"` mode.
+
+## Modalities and inputs
+
+The registry covers time series, tabular, graph, image, audio, text, geometry,
+point clouds, signal, video, information, sequence, matrix, topology, manifold,
+spatial, event and multimodal data. Each family has its own input contract.
+For example, text features typically accept an iterable of documents, while
+graph features accept graph objects; do not reshape them using the time-series
+convention.
+
+The supporting inventory is 552 registered entries, 18 modalities and 182
+modality/family groups. The [feature catalogue](docs/FEATURE_UNIVERSE.md) lists
+names and dependencies. An entry's availability does not imply that its
+optional backend or external model is installed.
+
+## Reuse state learned from training data
+
+```python
+from pathlib import Path
+from tempfile import TemporaryDirectory
+import numpy as np
+import pandas as pd
+import featm
+
+name = "tabular.encoding.category_frequency"
+train = pd.DataFrame({"category": ["A", "A", "B", "B", "B", "C"]})
+test = pd.DataFrame({"category": ["A", "B", "C", "D"]})
+fitted = featm.fit(
+    train, features=[name], columns={name: "category"}, errors="raise"
+)
+result = fitted.transform(test)
+print(result.to_pandas())
+np.testing.assert_allclose(result.to_numpy().ravel(), [2/6, 3/6, 1/6, 0])
+
+with TemporaryDirectory() as directory:
+    path = Path(directory) / "categories.pkl"
+    fitted.save(path)
+    restored = featm.load_fitted(path)
+    np.testing.assert_array_equal(
+        result.to_numpy(), restored.transform(test).to_numpy()
+    )
+```
+
+Only `train` supplies fitted statistics. Unseen category `D` maps to zero;
+transforming `test` does not refit the encoder. `extract()` fits and transforms
+its own input, so use `fit()` followed by `transform()` for a train/test split.
+There are seven stateful entries, including scaling and corpus-statistic text
+features. See [stateful workflows](docs/GETTING_STARTED.md#stateful-workflows).
+
+## Errors and return types
+
+Start with `errors="raise"` so a shape, parameter or dependency error is visible.
+The default `errors="skip"` isolates feature failures and can return an empty
+result if none succeeds. `errors="warn"` also emits warnings. An empty result
+is not proof that every requested feature ran.
+
+For a simple in-memory `pandas.DataFrame` result, inspect
+`result.attrs.get("execution_report", {})`. The report is present when this
+path records failures. Out-of-core extraction and fitted transformations use
+`FeatureMatrix`: inspect `result.report` and convert with `result.to_pandas()`.
+For large results, iterate batches rather than materializing everything.
+See [tested error examples](docs/GETTING_STARTED.md#error-policy-and-reports).
+
+## Larger data, checkpointing and execution backends
+
+File-backed extraction can read bounded batches, save disk-backed results and
+resume a compatible checkpoint. IO is required for checkpoints even when the
+input is already in memory. Existing incompatible or structurally invalid
+checkpoints fail closed; choose a fresh directory when you want a new run.
+Memory budgets guide execution; they are not a hard cap on total process RSS.
+
+CPU is the default. Optional CuPy kernels cover 22 features; strict GPU mode
+raises when a requested GPU implementation is unavailable, while fallback mode
+reports a CPU fallback. Dask distributes eligible features according to their
+batch semantics. Start with [scaling and checkpoints](docs/SCALING.md),
+[GPU setup](docs/INSTALLATION.md#gpu) or [Dask](docs/DISTRIBUTED.md).
+
+## Examples and documentation
+
+- [Getting started](docs/GETTING_STARTED.md): shapes, multiple families,
+  reports and fitted state.
+- [Installation](docs/INSTALLATION.md) and [compatibility](docs/COMPATIBILITY.md).
+- [Small executable examples](examples/README.md), including audio, images
+  and dataset-loading recipes without model-performance claims.
+- [Evidence and benchmark interpretation](docs/BENCHMARKS.md).
+- [Feature authoring](docs/FEATURE_AUTHORING.md) and
+  [architecture](docs/ARCHITECTURE.md) for contributors.
+
+## Compatibility and known limits
+
+Base certification covers Windows x86-64 and Ubuntu/WSL Linux x86-64 with
+CPython 3.10–3.14. Optional extras have narrower scopes: node2vec is certified
+on 3.10–3.12, and gensim-backed text/DeepWalk paths through 3.13.
+`full` is not a universal recommendation across all base Python versions.
+Real GPU evidence is limited to the tested Windows/CUDA-12/CuPy-14 configuration.
+macOS, ARM and Python 3.15 are **not validated**, rather than proven incompatible.
+
+Certain short harmonic/tonnetz inputs can yield non-finite values inside
+librosa. This was reproduced upstream without importing FEATM. No minimum
+safe duration, universal sample-rate claim or upstream fix is asserted.
+See [compatibility details](docs/COMPATIBILITY.md).
+
+FEATM is explicit extraction, not AutoML, relational DFS or automatic feature
+selection. New windowing infrastructure and sklearn Pipeline integration are
+outside v0.5.7. A legacy `AutoFeatures` planner remains for compatibility; it
+is not the recommended discovery or extraction workflow.
+
+## Contributing and license
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and reproducible bug reports.
+The owner-confirmed project address is [GitHub](https://github.com/Harish-K22/featm); report reproducible
+problems using the [issue tracker](https://github.com/Harish-K22/featm/issues) once the repository is available.
+
+FEATM's own code is distributed under the [MIT License](LICENSE),
+Copyright (c) 2026 Harish K. Optional dependencies, datasets and external models
+retain their own terms. See [third-party scope](THIRD_PARTY_NOTICES.md).