ptgp 0.1.0__tar.gz

ptgp-0.1.0/.gitignore

@@ -0,0 +1,190 @@
+# Don't check in hatch-vcs generated version file
+ptgp/_version.py
+
+# Local working notes
+FUTURE.md
+
+# Archived prototypes / old notebooks (not part of the package)
+archive/
+
+# Per-user Claude Code settings (personal permission caches, not project config)
+.claude/settings.json
+.claude/settings.local.json
+
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+comparison_libraries/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# 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
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# 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
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+.idea/

ptgp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+ci:
+  autofix_prs: false
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.6.0
+  hooks:
+    -   id: check-merge-conflict
+    -   id: check-toml
+    -   id: check-yaml
+    -   id: debug-statements
+    -   id: end-of-file-fixer
+    -   id: no-commit-to-branch
+        args: [--branch, main]
+    -   id: trailing-whitespace
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.5.5
+  hooks:
+    - id: ruff
+      args: [ --fix, --unsafe-fixes, --exit-non-zero-on-fix ]
+    - id: ruff-format
+      types_or: [ python, pyi, jupyter ]
+
+- repo: https://github.com/MarcoGorelli/madforhooks
+  rev: 0.4.1
+  hooks:
+    - id: no-print-statements
+      files: ^ptgp/
+      exclude: ^ptgp/_cli\.py$

ptgp-0.1.0/AGENTS.md

@@ -0,0 +1,219 @@
+# AGENTS.md
+
+Guidance for AI coding assistants (Claude Code, Codex, Cursor, Aider, …)
+working in this repository. Follows the [AGENTS.md](https://agents.md/)
+convention.
+
+## Mental model
+
+PTGP is a Gaussian process library whose central bet is: **write naive
+linear algebra, let PyTensor's rewrite system pick efficient algorithms
+based on declared matrix structure**. Three pieces hold this up:
+
+1. **Naive linalg in source.** Always write `pt.linalg.inv(K)`,
+   `pt.linalg.slogdet(K)`, `pt.linalg.solve(K, b)` — never hand-roll a
+   Cholesky + solve_triangular chain. The rewrite system picks the
+   algorithm.
+2. **Assumption annotations.** When a kernel evaluates `K(X, X)`, wrap
+   the result with `pta.assume(K, symmetric=True, positive_definite=True)`
+   (where `pta` is `pytensor.assumptions`) so the rewrite system can prove
+   it's PSD and lower it to Cholesky. Cross-covariance `K(X, Y)` is left
+   **unannotated**. This happens automatically in `Kernel.__call__` —
+   don't duplicate it in kernel subclasses.
+3. **Cubic-op floor.** `tests/test_cubic_floor.py` asserts each model's
+   joint (loss + all grads) graph compiles to the *minimum* count of
+   O(N³) factorizations: 1 for `Unapproximated`, 2 for `VFE`, 1 for
+   `SVGP`. This test is the canary for the whole rewrite story — run it
+   after any change to `ptgp/rewrites.py`, `ptgp/objectives.py`, or kernel
+   evaluation. When it fails, `scripts/joint_graph_analysis.py` prints the
+   full per-model op breakdown for diagnosis.
+
+`ptgp/rewrites.py` and `ptgp/linalg/rewrites.py` register assumption rules
+and structural rewrites into PyTensor's global registries at import time
+(both are imported for side-effects in `ptgp/__init__.py` —
+**don't remove those imports**). `ptgp/rewrites.py` also monkey-patches
+`pta.assume` to accept `positive=True` for scalar positivity.
+
+**PyMC is a prior container only.** `pm.Model()` holds priors on
+hyperparameters; `model.logp()` is added to the objective for MAP
+training. **Never call `pm.sample()`, `pm.find_MAP()`, or any PyMC
+inference routine** — PTGP's training paths in `ptgp/optim/` are the
+inference layer.
+
+## Running things
+
+All commands assume the project's `ptgp` conda env is active (Python
+3.14, PyTensor installed from `pymc-devs/pytensor@main`). The env path
+varies by machine — if no `ptgp` env is found, ask the user where their
+env lives rather than guessing.
+
+```bash
+# tests (pyproject sets -v and --doctest-modules, so docstrings run too)
+python -m pytest tests/
+python -m pytest tests/test_vfe.py                          # single file
+python -m pytest tests/test_vfe.py::test_name               # single test
+python -m pytest -k vfe                                     # by keyword
+python -m pytest tests/test_cubic_floor.py                  # the rewrite-floor canary
+
+# lint / format (also enforced by pre-commit; line-length 100)
+ruff check ptgp/ tests/
+ruff format ptgp/ tests/
+
+# diagnostic scripts — not in the test suite, run by hand when needed
+python scripts/joint_graph_analysis.py        # op-count tables per model, with/without ptgp rewrites
+python scripts/inplace_audit.py               # which linalg ops are inplace and why others aren't
+
+# execute the demo notebook in place
+python -m jupyter nbconvert --to notebook --execute --inplace \
+    notebooks/demo.ipynb --ExecutePreprocessor.kernel_name=ptgp
+
+# install the bundled agent-skill docs into a Claude Code skill dir (optional)
+python scripts/install_claude_skills.py --project .   # ./.claude/skills/
+python scripts/install_claude_skills.py --user        # ~/.claude/skills/
+```
+
+The reference usage example for all three models is
+[`notebooks/demo.ipynb`](notebooks/demo.ipynb).
+
+## Where things live
+
+- **Models** — `ptgp/gp/`. `Unapproximated`, `VFE`, `SVGP`. Each exposes
+  `predict_marginal` / `predict_joint`; `SVGP` adds `predict_f_samples`
+  and `prior_kl`. `VariationalParams` + `init_variational_params(M)` build
+  the symbolic `q_mu`, `q_sqrt`, plus the underlying trainable
+  `extra_vars` / `extra_init` needed by the compile helpers.
+- **Objectives** — `ptgp/objectives.py`. Standalone functions, **not**
+  methods on models, each returning a named tuple whose first field is
+  the scalar loss: `marginal_log_likelihood` → `MLLTerms`, `elbo` →
+  `ELBOTerms`, `collapsed_elbo` → `CollapsedELBOTerms`,
+  `fitc_log_marginal_likelihood` → `FITCTerms`, plus `vfe_diagnostics`
+  and `dpp_regularizer`.
+- **Kernels** — `ptgp/kernels/`. `Kernel` base class; subclasses
+  implement `_eval(X, Y)` and (optionally) `diag(X)`. Stationary
+  (`ExpQuad`, `Matern12/32/52`), nonstationary (`Gibbs`, `RandomWalk`,
+  `WarpedInput`), categorical (`Overlap`, `LowRankCategorical`),
+  combination (`SumKernel`, `ProductKernel`, via `+` / `*`). `active_dims`
+  selects input columns.
+- **Likelihoods** — `ptgp/likelihoods/`. `Gaussian`, `Bernoulli`,
+  `Poisson`, `NegativeBinomial`, `StudentT`. Non-Gaussian variants
+  implement `variational_expectation` for SVGP.
+- **Inducing variables** — `ptgp/inducing.py` (`Points`,
+  `random_subsample_init`, `kmeans_init`, `greedy_variance_init`),
+  `ptgp/inducing_fourier.py` (`FourierFeatures1D` — 1D Matern VFF with
+  `M = 2 * num_frequencies + 1`). Init routines return rich diagnostics
+  (`GreedyVarianceDiagnostics`, `KernelHealthDiagnostics`, …).
+- **Optim** — `ptgp/optim/`. Two training paths and a prediction
+  compiler:
+  - `compile_training_step` — Adam/SGD via `pytensor.shared` for SVGP /
+    minibatch. Auto-discovers PyMC free RVs as trainable; pass
+    `extra_vars` (e.g. `q_mu`, `q_sqrt`, trainable `Z`), optional
+    `frozen_vars` for staged training, `param_groups` for per-group
+    learning rates. Returns `(train_step, shared_params, shared_extras)`.
+  - `compile_scipy_objective` — L-BFGS-B path. Pair with
+    `tracked_minimize` (one phase, per-iteration diagnostics) or
+    `minimize_staged_vfe` (multi-phase VFE with per-phase diagnostic
+    capture). `compile_scipy_diagnostics` builds a sibling callable that
+    returns `VFEDiagnostics` for the same parameter vector.
+  - `compile_predict` — reads the same `shared_params` produced by
+    training, so prediction picks up the trained values automatically
+    (no model reconstruction).
+- **Conditionals / KL** — `ptgp/conditionals.py`, `ptgp/kl.py`. Whitened
+  vs unwhitened SVGP posterior pieces; `gauss_kl` / `gauss_kl_structured`.
+- **Linalg** — `ptgp/linalg/`. `LinearOperator` abstraction (matvec /
+  solve / logdet ops) + structural rewrites. Powers the Fourier-features
+  path.
+- **Utils** — `ptgp/utils.py`. `check_init` (NaN/inf + grad-norm sanity
+  check at initialisation — call this before training), `get_initial_params`
+  (prior-median / prior-draw / unconstrained-zero), `save_fit` / `load_fit`.
+- **Rewrites** — `ptgp/rewrites.py` + `ptgp/linalg/rewrites.py`. The
+  cubic-floor enablers; see the mental-model section.
+
+`comparison_libraries/` is **gitignored** — it's a local-only directory
+where some users keep checked-out reference repos (GPJax, GPflow,
+GPyTorch, CoLA, linear_operator, PyTensor, PyMC). GPJax is the primary
+reference for correctness; GPflow has the cleanest VFE/SVGP architecture.
+If `comparison_libraries/` isn't present on this machine, fetch from the
+upstream repos when reference code is needed.
+
+## Conventions
+
+Things that aren't self-evident from reading the code:
+
+- **Action-first names.** `minimize_staged_vfe`, not
+  `staged_vfe_minimize`. `compile_scipy_objective`, not
+  `objective_scipy_compile`.
+- **Kernel scale = `eta`, lengthscale = `ls`.** Kernels are written
+  `eta**2 * ExpQuad(ls=ls)` — `eta` is **always squared**. Multiple of
+  either get numeric suffixes: `eta1`, `ls2`.
+- **Shape-annotate every symbolic var.** Pass `shape=(...)` whenever a
+  dimension is known at construction time. Use `None` only for axes that
+  genuinely vary across calls. Standard letters:
+  - `N` — data points (almost always `None`)
+  - `M` — inducing points (concrete int)
+  - `D` — input dimension (concrete int)
+  - `K` — number of outputs (concrete int)
+
+  ```python
+  X    = pt.matrix("X",    shape=(None, D))
+  Z    = pt.matrix("Z",    shape=(M, D))
+  q_mu = pt.vector("q_mu", shape=(M,))
+  ```
+
+  Shape info lets rewrites specialize on known relationships (e.g. gating
+  on `M < N`) and catches mismatches at compile time. Even single-axis
+  annotations (`shape=(None, 1)`) are worth it.
+- **Internal symbolic var names start with `_`.** Anything named inside
+  library code (e.g. `pt.matrix("_X")` in `greedy_variance_init`) gets
+  the underscore prefix so it's distinguishable from user-named vars in
+  error messages and graph dumps.
+- **Name vars in complex examples.** When symbolic vars become dict keys
+  (`param_groups`, multi-phase training), pass `name="..."` — unnamed
+  vars render as opaque addresses in error text via
+  `var.name or repr(var)`.
+- **Error messages: two short sentences.** First names the problem,
+  second names the reason or fix. Example: `"Variables appear in both
+  extra_vars and frozen_vars: [...]. They cannot be both trainable and
+  frozen."`
+- **Tests use float64; GPJax uses float32.** For cross-library
+  correctness comparisons, use `atol=1e-5`.
+- **Notebooks** are stored as `.ipynb` and edited directly — no Jupytext
+  pairing or markdown mirror.
+
+## Stage and scope
+
+Prototype. Keep code and tests brief; the goal is a working prototype,
+not completeness. Don't add features, abstractions, or backwards-compat
+shims beyond what the task requires.
+
+## Skill docs (`docs/agents/`)
+
+The repo ships a backend-agnostic agent-skill doc at
+`docs/agents/ptgp-vfe/` covering VFE training diagnosis (pitfalls,
+escalation workflow, interpretation of `VFEDiagnostics` /
+`GreedyVarianceDiagnostics`). `scripts/install_claude_skills.py` is a
+Claude-specific convenience that symlinks it into a Claude Code skill
+directory (`~/.claude/skills/` or a project-local `.claude/skills/`);
+other AI tools can read `docs/agents/` directly.
+
+**When you change any of the following, check whether the skill needs
+updating:**
+
+| File                  | Skill files to scan                                            |
+| --------------------- | -------------------------------------------------------------- |
+| `ptgp/objectives.py`  | `reference/api.md`, `reference/interpretation.md`              |
+| `ptgp/optim/training.py` | `reference/api.md`, `pitfalls/lbfgsb_abnormal.md`, `pitfalls/slow_convergence.md` |
+| `ptgp/inducing.py`    | `reference/interpretation.md`, `pitfalls/inducing_*.md`        |
+| `ptgp/utils.py`       | `pitfalls/non_finite_at_init.md`, `pitfalls/large_grad_at_init.md` |
+
+The skill's pitfall pages reference fields on `VFEDiagnostics`,
+`CollapsedELBOTerms`, and `GreedyVarianceDiagnostics` by name — any
+change to those namedtuples needs a sweep through the skill.
+
+## Commits
+
+- One-sentence subject for small changes. Add a multi-line body for
+  multi-file refactors, non-obvious design decisions, or behavior changes
+  that need context.
+- After finishing a feature or plan, **prompt the user** about staging
+  and committing. Don't auto-commit.
+- Never add a `Co-Authored-By: …` trailer or any AI-attribution footer.

ptgp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bill Engels and the PyMC Developers
+
+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.

ptgp-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: ptgp
+Version: 0.1.0
+Summary: A practitioner's toolbox for estimating large-scale Gaussian Process models with PyMC and PyTensor
+Project-URL: Repository, https://github.com/pymc-devs/ptgp.git
+Project-URL: Issues, https://github.com/pymc-devs/ptgp/issues
+Author-email: Bill Engels <w.j.engels@gmail.com>, PyMC Developers <pymc.devs@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Bill Engels and the PyMC Developers
+        
+        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.
+License-File: LICENSE
+Keywords: bayesian,gaussian processes,probabilistic programming,pymc,pytensor,variational inference
+Requires-Python: >=3.12
+Requires-Dist: jax
+Requires-Dist: numpy
+Requires-Dist: optax
+Requires-Dist: pymc>=6.0.0
+Requires-Dist: pytensor>=3.0.2
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: polars; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PTGP
+
+A Gaussian process library for building GP models that solve real-world problems.
+
+## Who this is for
+
+PTGP is for practitioners who need flexible, well-supported GP modeling. The goal of PTGP is to be fully batteries-included and ready to work on real-world problems:
+
+- **Practical GP algorithms:** exact GP, VFE with collapsed bound, SVGP with minibatch training, VFF (Variational Fourier Features)
+- **Full kernel library:** ExpQuad, Matern52/32/12, RandomWalk, Gibbs, WarpedInput, categorical kernels for multi-class or categorical input variables, composition via `+` and `*`, `active_dims` for dimension selection
+- **Non-Gaussian likelihoods:** Bernoulli, Poisson, NegativeBinomial, StudentT
+- **PyMC priors:** set priors on any hyperparameter; use PyMC distributions for mean functions and noise models; MAP training by default
+- **Training tools:** L-BFGS-B and Adam optimizers, per-parameter learning rates, staged optimization, frozen variables, inducing point initialization strategies, diagnostic-guided workflows; more are being added, such as carefully monitored training to help diagnose issues early
+- **Agent-readable docs:** `docs/agents/` ships LLM-readable guides for debugging training issues and folk wisdom (VFE training covered). See the [Working with AI coding assistants](#working-with-ai-coding-assistants) section below.
+- **More coming:** see the [issues](https://github.com/pymc-devs/ptgp/issues)
+
+Researchers benefit from the underlying design: PTGP is built on PyTensor's symbolic graph and rewrite system, so you write GP math directly (`pt.linalg.inv(K)`, `pt.linalg.slogdet(K)`) and the compiler chooses efficient algorithms based on declared matrix structure. This makes it straightforward to implement new GP approximations and create custom models, and will eventually allow matrix structure like Kronecker, Toeplitz, and sparse to be taken advantage of automatically.
+
+## Models
+
+| Model | Scale | Best for |
+|-------|-------|----------|
+| `gp.Unapproximated` | N < ~2,000 | Exact inference, model comparison |
+| `gp.VFE` | N < ~50,000 | Medium-scale data with inducing points |
+| `gp.SVGP` | N up to ~500,000 | Large data, non-Gaussian likelihoods, minibatch training |
+| `FourierFeatures1D` | 1D Matern kernels | Structured Kuu via Fourier basis; no inducing point placement |
+
+## Quick start
+
+```python
+import numpy as np
+import pymc as pm
+import pytensor.tensor as pt
+import ptgp as pg
+
+X = np.random.randn(200, 1)
+y = np.sin(X.ravel()) + 0.1 * np.random.randn(200)
+Z_init = np.linspace(-2, 2, 20)[:, None]
+Z_var = pt.matrix("Z", shape=(20, 1))
+
+with pm.Model() as model:
+    ls = pm.InverseGamma("ls", alpha=2.0, beta=1.0)
+    eta = pm.Exponential("eta", lam=1.0)
+    kernel = eta**2 * pg.kernels.Matern52(input_dim=1, ls=ls)
+
+    svgp = pg.gp.SVGP(
+        kernel=kernel,
+        likelihood=pg.likelihoods.Gaussian(sigma=0.1),
+        inducing_variable=pg.inducing.Points(Z_var, Z_init=Z_init),
+        variational_params=pg.gp.init_variational_params(M=20),
+    )
+    fit = pg.fit(svgp, X, y, method="L-BFGS-B")
+
+mean, var = pg.predict(svgp, np.linspace(-3, 3, 100)[:, None], fit)
+```
+
+`pg.fit` picks a default objective from the gp type (`Unapproximated` → `marginal_log_likelihood`, `VFE` → `collapsed_elbo`, `SVGP` → `elbo`) and returns a `FitResult` that `pg.predict` consumes. For stochastic mini-batch training, staged VFE, or per-group learning rates, drop down to `pg.optim.compile_training_step` / `pg.optim.compile_scipy_objective` — see [`notebooks/demo.ipynb`](notebooks/demo.ipynb):
+
+```python
+X_var = pt.matrix("X")
+y_var = pt.vector("y")
+
+step, shared_params, shared_extras = pg.optim.compile_training_step(
+    pg.objectives.elbo, svgp, X_var, y_var, model, learning_rate=1e-2
+)
+
+for i in range(500):
+    loss = step(X, y)
+
+predict_fn = pg.optim.compile_predict(
+    svgp, pt.matrix("X_new"), model, shared_params, shared_extras=shared_extras
+)
+mean, var = predict_fn(np.linspace(-3, 3, 100)[:, None])
+```
+
+Training uses MAP by default: the PyMC log-prior is added to the objective. Pass `include_prior=False` for pure ELBO. For exact GPs and VFE, use `compile_scipy_objective` with L-BFGS-B instead. See [`notebooks/demo.ipynb`](notebooks/demo.ipynb) for end-to-end examples covering all three models.
+
+## How it works
+
+PTGP is built on PyTensor's symbolic graph. Kernels, likelihoods, and GP models return symbolic tensors with naive linear algebra like `pt.linalg.inv(K)` that PyTensor's rewrite system automatically lowers to efficient Cholesky-based code using declared matrix properties. All models compile their full forward+gradient step down to the minimum number of cubic factorizations.
+
+PTGP tries to distill some of the approaches of existing GP libraries and make them more accessible, mainly [GPJax](https://github.com/JaxGaussianProcesses/GPJax), [GPflow](https://github.com/GPflow/GPflow), and [GPyTorch](https://github.com/cornellius-gp/gpytorch).
+
+## Working with AI coding assistants
+
+PTGP is set up to work nicely with AI coding assistants:
+
+- **[`AGENTS.md`](AGENTS.md)** — project-level instructions for AI coding assistants (architecture, conventions, where things live, how to run tests). Follows the [AGENTS.md](https://agents.md/) cross-tool convention used by Codex, Cursor, Aider, and others.
+- **[`docs/agents/`](docs/agents/)** — backend-agnostic agent-skill docs covering folk wisdom and training-debug recipes. Currently includes [`ptgp-vfe`](docs/agents/ptgp-vfe/) (VFE diagnostic skill: pitfalls, escalation workflow, interpretation of `VFEDiagnostics` and `GreedyVarianceDiagnostics`).
+
+### Claude Code users
+
+Claude Code reads `CLAUDE.md`, not `AGENTS.md`. Symlink so they stay in sync:
+
+```bash
+ln -s AGENTS.md CLAUDE.md
+```
+
+To install the VFE skill into a Claude Code skill directory (so Claude auto-discovers it when you mention VFE), run:
+
+```bash
+python scripts/install_claude_skills.py --project .   # ./.claude/skills/
+python scripts/install_claude_skills.py --user        # ~/.claude/skills/
+```
+
+## Install
+
+```bash
+pip install git+https://github.com/pymc-devs/ptgp.git
+```
+
+To hack on PTGP itself, clone and install in editable mode:
+
+```bash
+git clone https://github.com/pymc-devs/ptgp.git
+cd ptgp
+pip install -e .
+```
+
+## Contributing
+
+See the [issues](https://github.com/pymc-devs/ptgp/issues) for what's being worked on. Feel free to propose issues, feature requests, or use cases you've been hoping could be made easier. PRs always welcome.