Strong typing (#83)

* Refactor model configuration to use frozen dataclasses instead of dicts

Introduce strongly-typed dataclasses for model configuration:
- Dimensions, Labels, Anchoring, EstimationOptions, TransitionInfo
- FactorEndogenousInfo, EndogenousFactorsInfo

This improves type safety and enables IDE autocompletion while keeping
user-facing model_dict as a plain dictionary.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Use frozendict for immutable dict fields in dataclasses

Replace dict fields with frozendict in frozen dataclasses to ensure
true immutability:
- Labels.aug_periods_to_periods
- Labels.aug_stages_to_stages
- Anchoring.outcomes
- TransitionInfo.param_names, individual_functions, function_names
- EndogenousFactorsInfo.aug_periods_to_aug_period_meas_types, factor_info

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Ignore ty false positive.

* Return ProcessedModel dataclass from process_model() instead of dict

Update process_model() to return a ProcessedModel frozen dataclass
and update all consumers to use attribute access instead of dict access.

This provides:
- Better type safety with explicit typed fields
- Immutability via frozen dataclass
- IDE autocomplete support
- Clear documentation of the model structure

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Rename FactorEndogenousInfo to FactorInfo

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Ensure complete typing in src/skillmodels.

* Require Python 3.14 before fixing type annotations.

* Move TESTS_DIR -> TEST_DATA_DIR, which points to a subdirectory of src so that config.TEST_DATA_DIR is valid also for skillmodels the package (as opposed to the project).

* Fix more linting issues.

* Make ruff rules much stricter.

* Further tighten type annotations. Fix a missing run-time annotation of NDArray.

* Move unsafe_fixes = false from .pre-commit config to pyproject.

* Fix query in data simulation.

* More fixes to imports, add test.

* Use more tuples in place of lists to prevent errors.

* Fix typing.

* Dataclasses for user input.

* Simplify.

* Use modern rng everywhere.

* Update CLAUDE.md

* Get rid of if TYPE_CHECKING blocks

* Update hooks and clean up

* Call by name throughout.

* Autogenerated docs, harmonised hooks / project configuration.

* Get rid of model_dict.

* Replace yaml model specifications by ModelSpec-s.

* Next shot at fixing pickling.

* Review comments 1: single EstimationOptions; improved dataclasses with all defaults set right there; get rid of remaining mutable types being passed around.

* Review comments on docs; tighten typing of Mapping to MappingProxyType where we could do so.

* Back to general implementation of ensure_containers_are_immutable.

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: hmgaudecker

.gitignore

@@ -1,124 +1,52 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
 # Distribution / packaging
-.Python
+*.egg
+*.egg-info/
+*.manifest
+*.spec
+.eggs/
+.installed.cfg
 build/
-develop-eggs/
 dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
+MANIFEST
 sdist/
-var/
 wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-*build/
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-*.sublime-workspace
-*.sublime-project
 
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-.hypothesis/
-.pytest_cache/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
+# Documentation
 docs/_build/
+_build/
 
-# PyBuilder
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# pyenv
-.python-version
-
-# celery beat schedule file
-celerybeat-schedule
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
+# IDE
+.idea/
+.vscode/
 
-# mypy
-.mypy_cache/
+# Jupyter
+.ipynb_checkpoints/
 
-*notes/
+# macOS
+.DS_Store
 
-.idea/
+# pixi
+.pixi/
 
-*.bak
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*$py.class
 
+# Ruff
+.ruff_cache/
 
-*.db
+# Testing
+.cache/
+.coverage
+.coverage.*
+.hypothesis/
+.pytest_cache/
+coverage.xml
+htmlcov/
 
+# Version file (generated by hatch-vcs)
+src/*/_version.py
 
-mixed_documents/
-src/skillmodels/_version.py
-.pixi
-.vscode
-*.py.*.bin
-*.py.*.html
+.claude

.pre-commit-config.yaml

@@ -4,7 +4,10 @@ repos:
     hooks:
       - id: check-hooks-apply
       - id: check-useless-excludes
-      # - id: identity  # Prints all files passed to pre-commits. Debugging.
+  - repo: https://github.com/tox-dev/tox-toml-fmt
+    rev: v1.2.2
+    hooks:
+      - id: tox-toml-fmt
   - repo: https://github.com/lyz-code/yamlfix
     rev: 1.19.1
     hooks:
@@ -15,53 +18,51 @@ repos:
       - id: check-added-large-files
         args:
           - --maxkb=50000
+      - id: check-ast
       - id: check-case-conflict
+      - id: check-docstring-first
       - id: check-merge-conflict
+      - id: check-toml
       - id: check-vcs-permalinks
       - id: check-yaml
-      - id: check-toml
       - id: debug-statements
       - id: end-of-file-fixer
       - id: fix-byte-order-marker
         types:
           - text
-      - id: forbid-submodules
       - id: mixed-line-ending
         args:
           - --fix=lf
         description: Forces to replace line ending by the UNIX 'lf' character.
+      - id: name-tests-test
+        args:
+          - --pytest-test-first
       - id: no-commit-to-branch
         args:
           - --branch
           - main
-      - id: name-tests-test
-        args:
-          - --pytest-test-first
       - id: trailing-whitespace
-      - id: check-ast
-      - id: check-docstring-first
   - repo: https://github.com/adrienverge/yamllint.git
-    rev: v1.37.1
+    rev: v1.38.0
     hooks:
       - id: yamllint
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.10
+    rev: v0.14.14
     hooks:
       - id: ruff-check
-        types_or:
-          - python
-          - pyi
-          - jupyter
         args:
           - --fix
-          # - --unsafe-fixes
-      - id: ruff-format
         types_or:
-          - python
+          - jupyter
           - pyi
+          - python
+      - id: ruff-format
+        types_or:
           - jupyter
+          - pyi
+          - python
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.8.2
+    rev: 0.9.0
     hooks:
       - id: nbstripout
         args:
@@ -72,10 +73,12 @@ repos:
     hooks:
       - id: mdformat
         additional_dependencies:
-          - mdformat-myst
+          - mdformat-gfm
+          - mdformat-gfm-alerts
           - mdformat-ruff
         args:
           - --wrap
           - '88'
+        files: (CLAUDE\.md|README\.md)
 ci:
   autoupdate_schedule: monthly

.readthedocs.yaml

@@ -0,0 +1,20 @@
+---
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: '3.14'
+    nodejs: '22'
+  jobs:
+    create_environment:
+      - asdf plugin add pixi
+      - asdf install pixi latest
+      - asdf global pixi latest
+    install:
+      - pixi install -e docs
+    post_build:
+      # Jupyter Book 2.0 builds site content to _build/html.
+      # For ReadTheDocs, we build and then copy to the expected output location.
+      - mkdir --parents $READTHEDOCS_OUTPUT/html/
+      - BASE_URL="/$READTHEDOCS_LANGUAGE/$READTHEDOCS_VERSION" pixi run -e docs docs
+      - cp -a docs/_build/html/. "$READTHEDOCS_OUTPUT/html" && rm -r docs/_build

.yamllint.yml

@@ -1,8 +1,4 @@
 ---
-yaml-files:
-  - '*.yaml'
-  - '*.yml'
-  - .yamllint
 rules:
   braces: enable
   brackets: enable
@@ -23,14 +19,21 @@ rules:
   key-duplicates: enable
   key-ordering: disable
   line-length:
-    max: 88
+    allow-non-breakable-inline-mappings: true
     allow-non-breakable-words: true
-    allow-non-breakable-inline-mappings: false
+    max: 88
   new-line-at-end-of-file: enable
   new-lines:
     type: unix
   octal-values: disable
   quoted-strings: disable
   trailing-spaces: enable
   truthy:
+    check-keys: false
     level: warning
+yaml-files:
+  - '*.yaml'
+  - '*.yml'
+  - .yamllint
+ignore:
+  - src/skillmodels/test_data/simplest_augmented_model.yaml

CLAUDE.md

@@ -27,13 +27,29 @@ pixi run -e test-cpu pytest tests/test_kalman_filters.py::test_function_name
 # Type checking
 pixi run ty
 
-# Install pre-commit hooks (required before committing)
-pre-commit install
+# Quality checks (linting, formatting)
+prek run --all-files
 
 # Build documentation (from docs/ directory)
 make html
 ```
 
+## Command Rules
+
+Always use these command mappings:
+
+- **Python**: Use `pixi run python` instead of `python` or `python3`
+- **Type checker**: Use `pixi run ty` instead of running ty/mypy/pyright directly
+- **Tests**: Use `pixi run tests` instead of `pytest` directly
+- **Linting/formatting**: Use `prek run --all-files` instead of `ruff` directly
+- **All quality checks**: Use `prek run --all-files`
+
+Before finishing any task that modifies code, always run:
+
+1. `pixi run ty` (type checker)
+1. `pixi run tests` (tests)
+1. `prek run --all-files` (quality checks)
+
 ## Architecture
 
 ### Core Pipeline Flow
@@ -82,14 +98,19 @@ The main package exports three functions:
 
 - `get_maximization_inputs()`: Prepare optimization problem for parameter estimation
 - `get_filtered_states()`: Extract filtered latent factor estimates
-- `simulate_dataset()`: Generate synthetic data from model specification
+- `simulate_dataset()`: Generate synthetic data from model specification (accepts
+  optional `seed` parameter for reproducibility)
 
 ## Code Style
 
-- Uses Ruff for linting (target: Python 3.13, line length: 88)
+- Require Python 3.14
+- Uses Ruff for linting (target: Python 3.14, line length: 88)
 - Google-style docstrings
 - Pre-commit hooks enforce formatting and linting
 - Type checking via `ty` with strict rules
+- Do not use `from __future__ import annotations`
+- Use modern numpy random API: `rng = np.random.default_rng(seed)` instead of
+  `np.random.seed()` or legacy functions like `np.random.randn()`
 
 ## Testing