diff --git a/.gitignore b/.gitignore
index 2a808bd..9a5b6c9 100755
--- a/.gitignore
+++ b/.gitignore
@@ -90,4 +90,5 @@ certs
 tmp
 *.tar.gz
 M*.json
-H*.json
\ No newline at end of file
+H*.json
+*.old
diff --git a/.gitmodules b/.gitmodules
new file mode 100644
index 0000000..5d457ab
--- /dev/null
+++ b/.gitmodules
@@ -0,0 +1,6 @@
+[submodule "python_magnetsetup"]
+	path = python_magnetsetup
+	url = git@github.com:MagnetDB/python_magnetsetup.git
+[submodule "python_magnetcooling"]
+	path = python_magnetcooling
+	url = git@github.com:MagnetDB/python_magnetcooling.git
diff --git a/README.md b/README.md
index ce31303..b13c7bc 100644
--- a/README.md
+++ b/README.md
@@ -1,69 +1,425 @@
-# Usage
+# Python MagnetAPI
 
-# Pre-requisites
+Python CLI and library for interacting with MagnetDB — a database for magnetic materials, parts, magnets, and sites.
 
-## MagnetDB
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Add the following machines in /etc/hosts with IP of MagnetDB
+## Overview
+
+`python_magnetapi` provides utilities to interact with MagnetDB, including:
+
+- Listing, viewing, creating, and deleting objects (materials, parts, magnets, sites, records, servers, simulations)
+- Setting up and running simulations
+- Computing derived quantities (inductances, flow parameters, hoop stress)
+- Post-processing simulation results
+
+## Installation
+
+### Requirements
+
+- Python >= 3.11
+- A running MagnetDB instance
+
+### Option 1: Install within a Python virtual environment (recommended for development)
+
+```bash
+git clone https://github.com/MagnetDB/python_magnetapi.git
+cd python_magnetapi
+
+# Create and activate a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+Alternatively, you can use the provided helper script:
+
+```bash
+./start-venv.sh
+source venv/bin/activate
+```
+
+This script creates a virtual environment with `--system-site-packages` enabled (useful when system-level dependencies like `python3-magnetsetup` are installed via apt) and installs the package in editable mode.
+
+To use `uv` instead of pip:
+
+```bash
+uv venv venv
+source venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+### Option 2: Debian packaging
+
+#### Installing from the LNCMI Debian repository
+
+If the package is available in the LNCMI Debian repository:
+
+```bash
+sudo apt update
+sudo apt install python3-magnetapi
+```
+
+#### Building the Debian package locally
+
+Install the required build tools:
+
+```bash
+sudo apt install debhelper dh-python python3-all python3-setuptools \
+                 devscripts build-essential
+```
+
+Install build dependencies listed in `debian/control`:
+
+```bash
+sudo apt install python3-magnetrun python3-magnetsetup python3-rich
+```
+
+Build the package:
+
+```bash
+# Using the archive script (recommended)
+./archive.sh -v 0.1.0 -d trixie
+
+# Or manually
+dpkg-buildpackage -us -uc -b
+```
+
+Install the resulting `.deb` file:
+
+```bash
+sudo dpkg -i ../python3-magnetapi_0.1.0-1_all.deb
+sudo apt install -f  # Fix any missing dependencies
+```
+
+### Option 3: Using a Docker container
+
+A DevContainer configuration is provided in `.devcontainer/` for use with VS Code or any OCI-compatible runtime.
+
+#### Building the Docker image
+
+```bash
+docker build -f .devcontainer/Dockerfile -t magnetapi:latest .
+```
+
+#### Running the container
+
+```bash
+docker run -it --net host \
+  -e MAGNETDB_API_KEY=${MAGNETDB_API_KEY} \
+  magnetapi:latest
+```
+
+For development with VS Code, simply open the project folder and select **"Reopen in Container"** when prompted. The DevContainer will automatically build the image, install all dependencies (including `python3-magnetrun`, `python3-magnetsetup`, and `python3-rich` from the LNCMI Debian repository), and configure Python tooling.
+
+#### Using a Singularity/Apptainer container
+
+You can convert the Docker image to a Singularity/Apptainer container, which is particularly useful for HPC environments:
+
+```bash
+# Build from the local Docker image
+singularity build magnetapi.sif docker-daemon://magnetapi:latest
+
+# Or with Apptainer
+apptainer build magnetapi.sif docker-daemon://magnetapi:latest
+```
+
+Run the container:
+
+```bash
+singularity exec magnetapi.sif python -m python_magnetapi.cli --help
+# or
+apptainer exec magnetapi.sif python -m python_magnetapi.cli --help
+```
+
+## Pre-requisites
+
+### MagnetDB client
+
+Ensure the MagnetDB server is accessible. Add the following entries to `/etc/hosts` with the appropriate IP address:
 
 ```
 aa.bb.xx.yy magnetdb.local
 aa.bb.xx.yy api.magnetdb.local
 aa.bb.xx.yy lemon.magnetdb.local
-aa.bb.xx.yy manager.lemon.magnetdb.local 
+aa.bb.xx.yy manager.lemon.magnetdb.local
 aa.bb.xx.yy auth.lemon.magnetdb.local
 aa.bb.xx.yy pgadmin.magnetdb.local
 aa.bb.xx.yy minio.magnetdb.local
 aa.bb.xx.yy traefik.magnetdb.local
 ```
 
-## Add CA cert
+### Add the CA certificate
 
-Get the server certificate
+Retrieve and install the server certificate:
 
 ```bash
 echo | openssl s_client -servername magnetdb.local -connect magnetdb.local:443 | cat > magnetdb.crt
+sudo cp magnetdb.crt /usr/local/share/ca-certificates/
+sudo update-ca-certificates
 ```
 
-Then
+### API key
+
+Obtain your API key from your profile page on `magnetdb.local` and export it:
 
 ```bash
-sudo cp magnetdb.crt /usr/local/share/ca-certificates/
-sudo update-ca-certificates
+export MAGNETDB_API_KEY=your_api_key_here
 ```
-   
-# Running
 
-## Examples
+## Usage
+
+### CLI
 
-You can find your API key in your profile page on magnetdb.local.
+The CLI is accessible either as a console script or via `python -m`:
 
 ```bash
-export MAGNETDB_API_KEY=xxx
+# Using the installed entry point
+python_magnetapi --help
+
+# Or using the module directly
 python -m python_magnetapi.cli --help
+```
+
+### Examples
+
+#### Listing objects
+
+List commands now display results as formatted tables:
+
+```bash
+# List all materials (displays as a formatted table)
 python -m python_magnetapi.cli --https list --mtype material
+
+# List all parts
+python -m python_magnetapi.cli --https list --mtype part
+
+# List all magnets
+python -m python_magnetapi.cli --https list --mtype magnet
+
+# List all sites
+python -m python_magnetapi.cli --https list --mtype site
+```
+
+**Example output:**
+```
+PART: found 53 items
+           Name  ID
+       HL-34_H1   1
+       HL-34_H2   2
+      Ring-H1H2   3
+           tore   4
+          tore1   5
+...
+```
+
+#### Filtering results
+
+Filter objects by their attributes using `--filter KEY=VALUE`. Multiple filters can be combined:
+
+```bash
+# Filter parts by a single attribute
+python -m python_magnetapi.cli --https list --mtype part --filter status=active
+
+# Filter with multiple attributes (all must match)
+python -m python_magnetapi.cli --https list --mtype part --filter status=active --filter type=helix
+
+# Filter magnets by site
+python -m python_magnetapi.cli --https list --mtype magnet --filter site=grenoble
+
+# Filter materials by property
+python -m python_magnetapi.cli --https list --mtype material --filter material_type=copper
+```
+
+#### Viewing and creating objects
+
+```bash
+# View a specific material
 python -m python_magnetapi.cli --https view --mtype material --name testmat2
+
+# Create a material from inline JSON
 python -m python_magnetapi.cli --https create --mtype material --data '{"name": "tutu"}'
+
+# Create a material from a JSON file
 python -m python_magnetapi.cli --https create --mtype material --file data.json
+
+# Delete a material
 python -m python_magnetapi.cli --https delete --mtype material --name testmat2
-python -m python_magnetapi.cli --https compute --mtype magnet  --name M19061901 --flow_params
-python -m python_magnetapi.cli --https compute  --mtype part --name H15101601--hoop_stress
+```
+
+#### Computing derived quantities
+
+```bash
+# Compute flow parameters for a magnet
+python -m python_magnetapi.cli --https compute --mtype magnet --name M19061901 --flow_params
+
+# Compute hoop stress for a part
+python -m python_magnetapi.cli --https compute --mtype part --name H15101601 --hoop_stress
+```
+
+#### Setting up and running simulations
+
+```bash
+# Setup a simulation
 python -m python_magnetapi.cli --https setup --mtype site --name M10_M19020601 \
-   --method cfpdes --static --geometry Axi --model thelec --cooling mean --current 31000 12000 100 \
-   [--wd path_to_store_setup]
-python -m python_magnetapi.cli --https run --simu_id id [--wd path_to_store_results]
+   --method cfpdes --static --geometry Axi --model thelec --cooling mean \
+   --current 31000 12000 100 \
+   --wd path_to_store_setup
+
+# Run a simulation
+python -m python_magnetapi.cli --https run --simu_id id --wd path_to_store_results
+```
+
+### As a library
+
+```python
+import requests
+from python_magnetapi import utils
+
+headers = {"Authorization": "your_api_key"}
+web = "https://api.magnetdb.local"
+
+with requests.Session() as s:
+    # List all magnets
+    ids = utils.get_list(s, web, headers=headers, mtype="magnet")
+    
+    # List with filters (single attribute)
+    active_parts = utils.get_list(
+        s, web, headers=headers, mtype="part",
+        filters={"status": "active"}
+    )
+    
+    # List with multiple filters (all must match)
+    filtered_magnets = utils.get_list(
+        s, web, headers=headers, mtype="magnet",
+        filters={"site": "grenoble", "status": "operational"}
+    )
+    
+    # Get a specific object
+    obj = utils.get_object(s, web, headers=headers, mtype="magnet", id=ids["M19061901"])
+```
+
+## Testing
+
+The test suite is split into two tiers:
+
+| Tier | Location | Requires live server? |
+|------|----------|-----------------------|
+| CLI unit/integration | `tests/cli/` | No — uses mocks |
+| API integration | `tests/test_list.py` | Yes |
+
+### CLI tests (no server required)
+
+```bash
+# Run only the CLI tests
+pytest tests/cli/ --verbose
+
+# Run with coverage
+pytest tests/cli/ --cov=python_magnetapi.cli --cov-report=term
 ```
 
-## Test suite
+### Full integration tests
+
+API integration tests require a running MagnetDB instance and a valid API key:
 
 ```bash
-export MAGNETDB_API_KEY=xxx
-pytest-3 --verbose
+export MAGNETDB_API_KEY=your_api_key_here
+
+# Run all tests
+pytest
+
+# Run with verbose output
+pytest --verbose
+
+# Run with coverage report
+pytest --cov=python_magnetapi --cov-report=html --cov-report=term
 ```
 
-## Test inside docker container
+### Testing inside a Docker container
+
+When testing against a local MagnetDB instance running in Docker:
 
 ```bash
-export MAGNETDB_API_KEY=test MAGNETDB_API_SERVER=http://localhost:8000
-poetry run pytest --verbose
+export MAGNETDB_API_KEY=test
+export MAGNETDB_API_SERVER=http://localhost:8000
+pytest --verbose
+```
+
+### Writing new tests
+
+Tests live in the `tests/` directory. Create files following the `test_*.py` naming convention.
+CLI command handlers can be tested without a live server by mocking `utils.get_list` and
+`utils.get_object`:
+
+```python
+import pytest
+from unittest.mock import patch, Mock
+from python_magnetapi.cli.commands.list import ListCommand
+from python_magnetapi.cli.context import CLIContext
+
+def test_list_command():
+    context = Mock(spec=CLIContext)
+    context.web = "http://test:8000"
+    context.headers = {"Authorization": "key"}
+    context.debug = False
+
+    with patch("python_magnetapi.utils.get_list", return_value={"M10": 1}):
+        cmd = ListCommand()
+        args = Mock(mtype="magnet", filters=None)
+        assert cmd.execute(args, context) == 0
+```
+
+Pytest configuration is defined in `pyproject.toml` under `[tool.pytest.ini_options]`.
+
+## Project structure
+
+```
+python_magnetapi/
+├── __init__.py          # Package metadata and version
+├── cli/                 # CLI package
+│   ├── __init__.py      # Entry point — main() function
+│   ├── base.py          # BaseCommand ABC and OBJECT_TYPES constant
+│   ├── context.py       # CLIContext dataclass (session, headers, URL)
+│   ├── parser.py        # Argument parser factory
+│   └── commands/        # One module per subcommand
+│       ├── list.py
+│       ├── view.py
+│       ├── create.py
+│       ├── delete.py
+│       ├── setup.py
+│       ├── run.py
+│       ├── compute.py
+│       └── process.py
+├── utils.py             # Core API interaction utilities
+├── material.py          # Material-specific operations
+├── part.py              # Part-specific operations
+├── magnet.py            # Magnet-specific operations
+├── site.py              # Site-specific operations
+└── ...
+tests/
+├── cli/                 # Unit/integration tests for the CLI (no server needed)
+│   ├── test_list_command.py
+│   └── test_cli_integration.py
+└── test_list.py         # Integration tests (require a running MagnetDB instance)
+debian/                  # Debian packaging files
+.devcontainer/           # Docker/DevContainer configuration
+pyproject.toml           # Project metadata and build configuration
+start-venv.sh            # Helper script for virtual environment setup
 ```
+
+## Authors
+
+- **Christophe Trophime** — <christophe.trophime@lncmi.cnrs.fr>
+- **Remi Caumette** — <remicaumette@icloud.com>
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Links
+
+- **Repository**: <https://github.com/MagnetDB/python_magnetapi>
+- **Bug Tracker**: <https://github.com/MagnetDB/python_magnetapi/issues>
diff --git a/archive.sh b/archive.sh
new file mode 100755
index 0000000..0ae50c1
--- /dev/null
+++ b/archive.sh
@@ -0,0 +1,84 @@
+#! /bin/bash
+
+# set -x # force debug
+set -eo pipefail # add flag to stop when command returns an error
+
+SRCDIR=python_magnetapi
+PACKAGE=python-magnetapi
+
+usage(){
+   echo ""
+   echo "Description:"
+   echo "               Builds a debian package"
+   echo ""
+   echo "Usage:"
+   echo "               archive.sh [ <option> ] ... ]"
+   echo ""
+   echo "Options:"
+   echo "-d             Specify the distribution to use"
+   echo "-v <x.y.z>     Specify version to build."
+   echo ""
+   exit 1
+}
+
+while getopts "hd:v:" option ; do
+   case $option in
+       h ) usage ;;
+       d ) DIST=$OPTARG ;;
+       v ) VERSION=$OPTARG ;;
+       ? ) usage ;;
+   esac
+done
+# shift to have the good number of other args
+shift $((OPTIND - 1))
+
+# add parameters
+: ${VERSION:="0.1.1"}
+: ${DIST:="trixie"}
+
+# cleanup source
+find . -type d -name __pycache__ | xargs rm -rf
+
+# create archive
+
+cd ..
+tar \
+    --exclude-vcs \
+    --exclude=feelppdb \
+    --exclude=tmp \
+    --exclude=data \
+    --exclude=debian \
+    --exclude=.pc \
+    --exclude=.devcontainer \
+    --exclude=.vscode \
+    --exclude=*.sif \
+    --exclude=*.crt \
+    --exclude=*.pem \
+    --exclude=*.log \
+    --exclude=*~ \
+    --exclude=python_magnetcooling \
+    --exclude=python_magnetsetup \
+    --exclude=poetry.lock \
+    -zcvf ${PACKAGE}_${VERSION}.orig.tar.gz ${SRCDIR}
+
+# build package
+# disable use of hooks in pbuilder
+mkdir -p tmp
+cd tmp
+cp ../${PACKAGE}_${VERSION}.orig.tar.gz .
+tar zxvf ./${PACKAGE}_$VERSION.orig.tar.gz
+cp -r ../${SRCDIR}/debian ${SRCDIR}
+cd ${SRCDIR}
+DIST=${DIST} pdebuild
+
+# clean up
+cd ..
+rm -rf ${PACKAGE}*
+rm -rf ${SRCDIR}
+
+# # upload new package to Lncmi package repository
+# cd /var/cache/pbuilder/$DIST-amd64/results
+# dupload -t euler_$DIST 
+
+# connect to Lncmi repository server
+# update server
diff --git a/debian/changelog b/debian/changelog
index 86a3e88..8b5d85c 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,22 +1,68 @@
-python-magnetapi (0.1.0-1) unstable; urgency=medium
+python-magnetapi (0.1.1-1) UNRELEASED; urgency=medium
 
-  * New upstream release (0.1.0)
-  * Modernize Debian packaging infrastructure:
-    - Update debhelper-compat from 12 to 13
-    - Add explicit pybuild-plugin-pyproject support
-    - Remove legacy dh-python and python3-setuptools dependencies
+  * rebuild for trixie
+  * Refactor CLI module into modular package structure:
+    - Replace monolithic cli.py (684 lines) with cli/ package
+    - Add cli/context.py: CLIContext dataclass managing HTTP session and config
+    - Add cli/base.py: BaseCommand ABC with shared helpers and OBJECT_TYPES
+      constant
+    - Add cli/parser.py: argument parser factory
+    - Add cli/commands/: individual handlers for list, view, create, delete,
+      setup, run, compute and process subcommands
+    - No breaking changes: CLI interface remains identical
+  * Add type hints and docstrings throughout cli/ package:
+    - All public methods now have full type annotations and docstrings
+    - configure_parser() methods document their parser argument
+    - CLIContext.__enter__/__exit__ have proper return type annotations
+  * Fix logic bug in setup command available_models validation
+  * Eliminate redundant API calls in view and compute commands
+  * Update pyproject.toml to declare cli/ sub-packages
+  * Modernize Debian packaging:
     - Update Standards-Version to 4.7.0
-    - Simplify debian/rules using modern pybuild
-    - Remove obsolete --with python3 flag
-  * Fix packaging metadata:
-    - Correct Homepage URL to python-magnetapi repository
-    - Add VCS fields (Vcs-Browser, Vcs-Git)
-    - Change Section from 'unknown' to 'python'
-    - Improve package descriptions
-  * Align version with pyproject.toml (0.1.0)
-  * Update to PEP 517/518 compliant build system
-
- -- Christophe Trophime <christophe.trophime@lncmi.cnrs.fr>  Wed, 28 Jan 2026 14:00:00 +0100
+    - Add full runtime dependencies to Build-Depends and Depends
+    - Uncomment Vcs-Browser and Vcs-Git fields
+    - Remove duplicate python3-rich entry from Build-Depends
+    - Update package descriptions
+  * Handle ForeignKey fields returned as nested dicts by API:
+    - Add utils.get_fk_id() to extract FK id from nested dict, int, or None
+    - Update part.create() to use id directly when material field is a dict
+  * Add get_parts_for_magnet() helper in utils.py for nested magnet/parts
+    endpoint; add demo_magnet_parts.py example script
+  * Fix --no-verify SSL flag: suppress InsecureRequestWarning only when
+    explicitly requested; add --no-verify to all demo scripts and CLIContext
+  * Fix get_parts_for_magnet to correctly resolve part objects from magnet
+  * Add type hints and docstrings to domain modules:
+    - utils.py: requests.Session type on all session params; return types on
+      all functions (dict|None, list|None, str|None, etc.); full Args/Returns/
+      Raises docstrings
+    - material.py, part.py, magnet.py, record.py, site.py, attachment.py:
+      requests.Session type on session param; return type annotations;
+      expanded docstrings with Args, Returns, and Raises sections
+
+ -- Christophe Trophime <christophe.trophime@lncmi.cnrs.fr>  Fri, 20 Mar 2026 14:00:00 +0100
+
+python-magnetapi (0.1.0-1) unstable; urgency=medium
+
+  * New upstream release 0.1.0
+  * Modernize Debian packaging:
+    - Upgrade to debhelper-compat 13
+    - Update Standards-Version to 4.6.2
+    - Change Section from unknown to python
+    - Update Homepage URL to correct repository
+    - Add all required runtime dependencies
+    - Remove obsolete python3-setuptools build dependency
+  * Major improvements in upstream:
+    - Complete Sphinx documentation (1500+ lines)
+    - Performance optimization of hoop_stress module
+    - Add parallel processing capability (hoop_stress_parallel)
+    - Modernize flow_params to use python3-magnetcooling
+    - Add comprehensive demo scripts
+    - Migrate to pure pyproject.toml (PEP 517/518)
+    - Expand README with detailed installation and usage
+    - Add python3-magnetcooling and python3-magnettools dependencies
+  * Update package description to reflect library+CLI nature
+
+ -- Christophe Trophime <christophe.trophime@lncmi.cnrs.fr>  Wed, 12 Mar 2026 14:00:00 +0100
 
 python-magnetapi (0.0.1-2) unstable; urgency=medium
 
diff --git a/debian/control b/debian/control
index bf517d6..4ebb167 100644
--- a/debian/control
+++ b/debian/control
@@ -4,32 +4,45 @@ Priority: optional
 Maintainer: Christophe Trophime <christophe.trophime@lncmi.cnrs.fr>
 Build-Depends: debhelper-compat (= 13),
  pybuild-plugin-pyproject,
- python3-setuptools,
  python3-all,
- python3-magnetrun,
+ python3-requests,
+ python3-pandas,
+ python3-numpy,
+ python3-scipy,
+ python3-param,
+ python3-rich,
  python3-magnetsetup,
- python3-rich
+ python3-magnetcooling,
+ python3-magnettools
 Standards-Version: 4.7.0
 Homepage: https://github.com/MagnetDB/python_magnetapi
-#Vcs-Browser: https://github.com/MagnetDB/python_magnetapi
-#Vcs-Git: https://github.com/MagnetDB/python_magnetapi.git
+Vcs-Browser: https://github.com/MagnetDB/python_magnetapi
+Vcs-Git: https://github.com/MagnetDB/python_magnetapi.git
 #Testsuite: autopkgtest-pkg-python
 Rules-Requires-Root: no
 
 Package: python3-magnetapi
 Architecture: all
-Depends: ${python3:Depends}, ${misc:Depends}
-Description: Python CLI for MagnetDB
- Python MagnetAPI provides utilities and a command-line interface to interact
- with MagnetDB, a database system for managing magnetic materials, parts,
- magnets, sites, and experimental records.
+Depends: ${python3:Depends}, ${misc:Depends},
+ python3-requests,
+ python3-pandas,
+ python3-numpy,
+ python3-scipy,
+ python3-param,
+ python3-rich,
+ python3-magnetsetup,
+ python3-magnetcooling,
+ python3-magnettools
+Suggests: python-magnetapi-doc
+Description: Python library and CLI for interacting with MagnetDB
+ Python MagnetAPI provides utilities to interact with MagnetDB, a database
+ for magnetic materials, parts, magnets, and sites.
  .
- This package includes:
-  - API utilities for MagnetDB operations (CRUD)
-  - CLI tools for materials, parts, magnets, sites, and records
-  - Simulation setup and execution support
-  - Flow parameter computation and analysis
-  - Hoop stress history calculation
+ Features include:
+  - Listing, viewing, creating, and deleting database objects
+  - Setting up and running simulations
+  - Computing derived quantities (inductances, flow parameters, hoop stress)
+  - Post-processing simulation results
  .
  This package installs the library for Python 3.
 
@@ -37,7 +50,9 @@ Package: python-magnetapi-doc
 Architecture: all
 Section: doc
 Depends: ${sphinxdoc:Depends}, ${misc:Depends}
-Description: Documentation for Python MagnetAPI
- Python MagnetAPI provides utilities to interact with MagnetDB.
+Description: Python library and CLI for MagnetDB (documentation)
+ Python MagnetAPI provides utilities to interact with MagnetDB, a database
+ for materials, parts, magnets, and sites.
  .
- This is the common documentation package.
+ This package provides the common documentation including Sphinx-generated
+ HTML documentation, API reference, and usage guides.
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d4bb2cb
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..fc3171d
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,82 @@
+# Documentation for python_magnetapi
+
+This directory contains the Sphinx documentation for the `python_magnetapi` package.
+
+## Building the Documentation
+
+### Prerequisites
+
+Install the documentation dependencies:
+
+```bash
+pip install -e ".[doc]"
+```
+
+This installs:
+- sphinx
+- sphinx-rtd-theme
+
+Optionally, for better type hint rendering:
+```bash
+pip install sphinx-autodoc-typehints
+```
+
+### Build HTML Documentation
+
+On Linux/macOS:
+
+```bash
+cd docs
+make html
+```
+
+On Windows:
+
+```bash
+cd docs
+make.bat html
+```
+
+The generated HTML documentation will be in `_build/html/`. Open `_build/html/index.html` in your browser.
+
+### Other Build Targets
+
+- `make clean` - Remove build artifacts
+- `make latexpdf` - Build PDF documentation (requires LaTeX)
+- `make linkcheck` - Check all external links
+
+## Documentation Structure
+
+```
+docs/
+├── conf.py              # Sphinx configuration
+├── index.rst            # Main documentation page
+├── installation.rst     # Installation instructions
+├── quickstart.rst       # Quick start guide
+├── configuration.rst    # Server & environment configuration
+├── cli.rst              # CLI reference
+├── usage.rst            # Advanced usage guide
+├── testing.rst          # Testing guide
+├── contributing.rst     # Contributing guide
+├── api/                 # API reference (autodoc)
+│   ├── index.rst
+│   ├── utils.rst
+│   ├── cli_module.rst
+│   ├── material.rst
+│   ├── part.rst
+│   ├── magnet.rst
+│   ├── site.rst
+│   ├── geometry.rst
+│   ├── record.rst
+│   ├── hoop_stress.rst
+│   └── flow_params.rst
+├── Makefile             # Unix build script
+├── make.bat             # Windows build script
+├── _static/             # Static files (CSS, images)
+└── _templates/          # Custom Sphinx templates
+```
+
+## Auto-documentation
+
+The API documentation is automatically generated from docstrings using Sphinx's
+autodoc extension. Docstrings should follow Google or NumPy style conventions.
diff --git a/docs/api/cli_module.rst b/docs/api/cli_module.rst
new file mode 100644
index 0000000..3f840b8
--- /dev/null
+++ b/docs/api/cli_module.rst
@@ -0,0 +1,11 @@
+cli
+===
+
+Command-line interface entry point. This module defines the argument parser,
+subcommands, and the ``main()`` function that dispatches to the appropriate
+handlers.
+
+.. automodule:: python_magnetapi.cli
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/flow_params.rst b/docs/api/flow_params.rst
new file mode 100644
index 0000000..d3267ee
--- /dev/null
+++ b/docs/api/flow_params.rst
@@ -0,0 +1,11 @@
+flow_params
+===========
+
+Compute flow parameters from experimental measurement records using curve
+fitting. This module extracts flow data from records attached to magnets and
+fits hydraulic models.
+
+.. automodule:: python_magnetapi.flow_params
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/geometry.rst b/docs/api/geometry.rst
new file mode 100644
index 0000000..0b0c18e
--- /dev/null
+++ b/docs/api/geometry.rst
@@ -0,0 +1,9 @@
+geometry
+========
+
+Functions for creating and managing geometry attachments for parts and magnets.
+
+.. automodule:: python_magnetapi.geometry
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/hoop_stress.rst b/docs/api/hoop_stress.rst
new file mode 100644
index 0000000..d912b47
--- /dev/null
+++ b/docs/api/hoop_stress.rst
@@ -0,0 +1,11 @@
+hoop_stress
+===========
+
+Compute hoop stress history for magnet parts across all sites where they have
+been installed. This module retrieves operational records, extracts current
+data, and calculates mechanical stress using MagnetTools.
+
+.. automodule:: python_magnetapi.hoop_stress
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/index.rst b/docs/api/index.rst
new file mode 100644
index 0000000..1c846a3
--- /dev/null
+++ b/docs/api/index.rst
@@ -0,0 +1,18 @@
+API Reference
+=============
+
+This section documents the Python modules in the ``python_magnetapi`` package.
+
+.. toctree::
+   :maxdepth: 2
+
+   utils
+   cli_module
+   material
+   part
+   magnet
+   site
+   geometry
+   record
+   hoop_stress
+   flow_params
diff --git a/docs/api/magnet.rst b/docs/api/magnet.rst
new file mode 100644
index 0000000..8f1f2f1
--- /dev/null
+++ b/docs/api/magnet.rst
@@ -0,0 +1,10 @@
+magnet
+======
+
+Functions for creating and managing magnet assemblies in MagnetDB. Magnets are
+composed of parts and can be installed at one or more sites.
+
+.. automodule:: python_magnetapi.magnet
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/material.rst b/docs/api/material.rst
new file mode 100644
index 0000000..236a0ec
--- /dev/null
+++ b/docs/api/material.rst
@@ -0,0 +1,9 @@
+material
+========
+
+Functions for creating and managing material objects in MagnetDB.
+
+.. automodule:: python_magnetapi.material
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/part.rst b/docs/api/part.rst
new file mode 100644
index 0000000..5ca9db9
--- /dev/null
+++ b/docs/api/part.rst
@@ -0,0 +1,11 @@
+part
+====
+
+Functions for creating and managing part objects (helices, bitter disks, supra
+coils) in MagnetDB. Parts are associated with a material and can belong to one
+or more magnets.
+
+.. automodule:: python_magnetapi.part
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/record.rst b/docs/api/record.rst
new file mode 100644
index 0000000..d12365b
--- /dev/null
+++ b/docs/api/record.rst
@@ -0,0 +1,9 @@
+record
+======
+
+Functions for creating and managing measurement records in MagnetDB.
+
+.. automodule:: python_magnetapi.record
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/site.rst b/docs/api/site.rst
new file mode 100644
index 0000000..57b4c50
--- /dev/null
+++ b/docs/api/site.rst
@@ -0,0 +1,11 @@
+site
+====
+
+Functions for creating and managing site objects in MagnetDB. Sites represent
+physical installations that contain one or more magnets and have associated
+measurement records.
+
+.. automodule:: python_magnetapi.site
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/cli.rst b/docs/cli.rst
new file mode 100644
index 0000000..bc0c63d
--- /dev/null
+++ b/docs/cli.rst
@@ -0,0 +1,159 @@
+CLI Reference
+=============
+
+``python_magnetapi`` provides a command-line interface for interacting with
+MagnetDB. The CLI supports listing, viewing, creating, deleting objects, as well
+as setting up and running simulations.
+
+General Options
+---------------
+
+.. code-block:: text
+
+   python_magnetapi [--server SERVER] [--port PORT] [--debug] [--https]
+                    {list,view,create,delete,setup,run,compute,process} ...
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Option
+     - Description
+   * - ``--server``
+     - MagnetDB API server hostname (default: ``MAGNETDB_API_SERVER`` env var or ``api.magnetdb-dev.local``)
+   * - ``--port``
+     - API server port (default: ``8000``, ignored with ``--https``)
+   * - ``--debug``
+     - Enable debug output
+   * - ``--https``
+     - Use HTTPS instead of HTTP
+
+
+Subcommands
+-----------
+
+list
+~~~~
+
+List objects of a given type.
+
+.. code-block:: bash
+
+   python_magnetapi --https list --mtype material
+
+Supported types: ``material``, ``part``, ``magnet``, ``site``, ``record``,
+``server``, ``simulation``.
+
+
+view
+~~~~
+
+View details of a specific object.
+
+.. code-block:: bash
+
+   python_magnetapi --https view --mtype material --name testmat2
+
+Options:
+
+- ``--mtype``: Object type
+- ``--name``: Object name
+
+
+create
+~~~~~~
+
+Create a new object from inline JSON data or from a JSON file.
+
+.. code-block:: bash
+
+   # From inline data
+   python_magnetapi --https create --mtype material --data '{"name": "tutu"}'
+
+   # From a file
+   python_magnetapi --https create --mtype material --file data.json
+
+Options:
+
+- ``--mtype``: Object type
+- ``--data``: JSON data as a string (mutually exclusive with ``--file``)
+- ``--file``: Path to a JSON file (mutually exclusive with ``--data``)
+
+
+delete
+~~~~~~
+
+Delete an object by name.
+
+.. code-block:: bash
+
+   python_magnetapi --https delete --mtype material --name testmat2
+
+
+setup
+~~~~~
+
+Set up a simulation for a magnet or site.
+
+.. code-block:: bash
+
+   python_magnetapi --https setup --mtype site --name M10_M19020601 \
+     --method cfpdes --static --geometry Axi --model thelec \
+     --cooling mean --current 31000 12000 100 \
+     --wd path_to_store_setup
+
+Options:
+
+- ``--mtype``: ``magnet`` or ``site``
+- ``--name``: Object name
+- ``--geometry``: Geometry type (``Axi`` or ``3D``)
+- ``--method``: Numerical method (e.g. ``cfpdes``)
+- ``--model``: Model name (e.g. ``thelec``, ``thmagel_hcurl``)
+- ``--cooling``: Cooling mode (``mean``, ``meanH``, ``grad``, ``gradH``, ``gradHZ``)
+- ``--current``: Requested current values
+- ``--static``: Enable static mode
+- ``--nonlinear``: Enable non-linear mode
+- ``--wd``: Working directory for output
+
+
+run
+~~~
+
+Run a previously set-up simulation.
+
+.. code-block:: bash
+
+   python_magnetapi --https run --simu_id 42 --wd path_to_store_results
+
+Options:
+
+- ``--simu_id``: Simulation ID (from the setup step)
+- ``--wd``: Working directory for results
+- ``--compute_server``: Compute node name (default: ``calcul22``)
+- ``--np``: Number of MPI processes (default: ``4``)
+
+
+compute
+~~~~~~~
+
+Compute derived quantities for an object.
+
+.. code-block:: bash
+
+   # Flow parameters for a magnet
+   python_magnetapi --https compute --mtype magnet --name M19061901 --flow_params
+
+   # Hoop stress history for a part
+   python_magnetapi --https compute --mtype part --name H15101601 --hoop_stress
+
+   # Self and mutual inductances
+   python_magnetapi --https compute --mtype magnet --name M19061901 --inductances
+
+Options:
+
+- ``--mtype``: ``part``, ``magnet``, ``site``, or ``record``
+- ``--name``: Object name
+- ``--flow_params``: Compute flow parameters (magnet only)
+- ``--hoop_stress``: Compute hoop stress history (part only)
+- ``--inductances``: Compute self and mutual inductances
+- ``--samples``: Number of samples to consider (default: ``20``)
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..8b3fa54
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,110 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+# Add the project root to the Python path so autodoc can find the package
+sys.path.insert(0, os.path.abspath(".."))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "python_magnetapi"
+copyright = "2026, Christophe Trophime, Remi Caumette"
+author = "Christophe Trophime"
+release = "0.1.0"
+version = "0.1.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+]
+
+# Try to load optional extensions
+try:
+    import sphinx_autodoc_typehints  # noqa: F401
+
+    extensions.append("sphinx_autodoc_typehints")
+except ImportError:
+    pass
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The master toctree document
+master_doc = "index"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+# Theme options for Read the Docs theme
+html_theme_options = {
+    "navigation_depth": 3,
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "titles_only": False,
+}
+
+# -- Extension configuration -------------------------------------------------
+
+# Napoleon settings for Google/NumPy style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+# Autodoc settings
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "exclude-members": "__weakref__",
+}
+autodoc_mock_imports = [
+    "requests",
+    "pandas",
+    "numpy",
+    "scipy",
+    "param",
+    "rich",
+    "python_magnetsetup",
+    "python_magnetrun",
+    "magnettools",
+]
+
+# Intersphinx mapping to external projects
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "requests": ("https://requests.readthedocs.io/en/latest/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+}
+
+# Todo extension settings
+todo_include_todos = True
+
+# Type hints settings (if sphinx_autodoc_typehints is available)
+typehints_fully_qualified = False
+always_document_param_types = True
+typehints_document_rtype = True
diff --git a/docs/configuration.rst b/docs/configuration.rst
new file mode 100644
index 0000000..3392f56
--- /dev/null
+++ b/docs/configuration.rst
@@ -0,0 +1,75 @@
+Configuration
+=============
+
+Before using ``python_magnetapi``, you need to configure access to a running
+MagnetDB instance.
+
+MagnetDB Server
+---------------
+
+Add the following entries to ``/etc/hosts`` with the IP address of your MagnetDB
+server:
+
+.. code-block:: text
+
+   aa.bb.xx.yy magnetdb.local
+   aa.bb.xx.yy api.magnetdb.local
+   aa.bb.xx.yy lemon.magnetdb.local
+   aa.bb.xx.yy manager.lemon.magnetdb.local
+   aa.bb.xx.yy auth.lemon.magnetdb.local
+   aa.bb.xx.yy pgadmin.magnetdb.local
+   aa.bb.xx.yy minio.magnetdb.local
+   aa.bb.xx.yy traefik.magnetdb.local
+
+Replace ``aa.bb.xx.yy`` with the actual IP address of the MagnetDB host.
+
+
+CA Certificate
+--------------
+
+If the MagnetDB server uses HTTPS with a self-signed certificate, retrieve and
+install the server certificate:
+
+.. code-block:: bash
+
+   # Retrieve the certificate
+   echo | openssl s_client -servername magnetdb.local \
+     -connect magnetdb.local:443 | cat > magnetdb.crt
+
+   # Install it system-wide
+   sudo cp magnetdb.crt /usr/local/share/ca-certificates/
+   sudo update-ca-certificates
+
+
+API Key
+-------
+
+Obtain your API key from your profile page on ``magnetdb.local`` and export it
+as an environment variable:
+
+.. code-block:: bash
+
+   export MAGNETDB_API_KEY=your_api_key_here
+
+You can also add this to your shell profile (e.g. ``~/.bashrc``) for
+persistence.
+
+
+Environment Variables
+---------------------
+
+The following environment variables are recognized:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 50 20
+
+   * - Variable
+     - Description
+     - Default
+   * - ``MAGNETDB_API_KEY``
+     - API key for authenticating with MagnetDB
+     - *(none)*
+   * - ``MAGNETDB_API_SERVER``
+     - API server hostname
+     - ``api.magnetdb-dev.local``
diff --git a/docs/contributing.rst b/docs/contributing.rst
new file mode 100644
index 0000000..e149df0
--- /dev/null
+++ b/docs/contributing.rst
@@ -0,0 +1,90 @@
+Contributing
+============
+
+Development Setup
+-----------------
+
+1. Clone the repository:
+
+   .. code-block:: bash
+
+      git clone https://github.com/Trophime/python_magnetapi.git
+      cd python_magnetapi
+
+2. Create a virtual environment and install in editable mode:
+
+   .. code-block:: bash
+
+      python -m venv venv
+      source venv/bin/activate
+      pip install -e ".[dev,doc]"
+
+3. Run the tests to make sure everything works:
+
+   .. code-block:: bash
+
+      export MAGNETDB_API_KEY=your_api_key_here
+      pytest --verbose
+
+
+Code Style
+----------
+
+The project uses `Black <https://black.readthedocs.io/>`_ for code formatting.
+Format your code before committing:
+
+.. code-block:: bash
+
+   black python_magnetapi/ tests/
+
+
+Building Documentation
+----------------------
+
+Build the HTML documentation locally:
+
+.. code-block:: bash
+
+   cd docs
+   make html
+
+The output will be in ``docs/_build/html/``. Open ``index.html`` in your
+browser to preview.
+
+To check for broken links:
+
+.. code-block:: bash
+
+   make linkcheck
+
+
+Adding New Modules
+------------------
+
+When adding a new module to ``python_magnetapi``:
+
+1. Create the module file in ``python_magnetapi/``
+2. Add docstrings following the Google or NumPy style
+3. Create a corresponding ``.rst`` file in ``docs/api/``
+4. Add the new ``.rst`` file to ``docs/api/index.rst``
+5. Write tests in ``tests/``
+6. Build the docs and verify the autodoc output
+
+
+Debian Packaging
+----------------
+
+When updating the package version:
+
+1. Update ``version`` in ``pyproject.toml``
+2. Update the Debian changelog:
+
+   .. code-block:: bash
+
+      dch -v 0.2.0-1 "New upstream release"
+
+3. Rebuild the package:
+
+   .. code-block:: bash
+
+      ./archive.sh -v 0.2.0 -d trixie
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..9d6a609
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,62 @@
+.. python_magnetapi documentation master file
+
+python_magnetapi
+================
+
+**Python CLI and library for interacting with MagnetDB** — a database for magnetic
+materials, parts, magnets, and sites used in high-field magnet research.
+
+``python_magnetapi`` provides utilities to:
+
+- List, view, create, and delete objects (materials, parts, magnets, sites, records, servers, simulations)
+- Set up and run simulations (cfpdes, CRB, HDG, etc.)
+- Compute derived quantities (inductances, flow parameters, hoop stress)
+- Post-process simulation results
+
+.. note::
+
+   This package requires a running `MagnetDB <https://github.com/Trophime/magnetdb>`_ instance
+   and a valid API key to operate.
+
+Getting Started
+---------------
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   quickstart
+   configuration
+
+User Guide
+----------
+
+.. toctree::
+   :maxdepth: 2
+
+   cli
+   usage
+
+API Reference
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
+   api/index
+
+Development
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   testing
+   contributing
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 0000000..b8f7ca2
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,162 @@
+Installation
+============
+
+Requirements
+------------
+
+- Python >= 3.11
+- A running MagnetDB instance
+
+The package depends on the following Python packages:
+
+- ``requests`` >= 2.32.3
+- ``pandas`` >= 2.2.1
+- ``numpy`` >= 2.2.1
+- ``scipy`` >= 1.14.1
+- ``param`` >= 1.12.0
+- ``rich`` >= 9.11.0
+- ``python-magnetsetup``
+
+Python Virtual Environment (recommended for development)
+---------------------------------------------------------
+
+Clone the repository and install in a virtual environment:
+
+.. code-block:: bash
+
+   git clone https://github.com/Trophime/python_magnetapi.git
+   cd python_magnetapi
+
+   # Create and activate a virtual environment
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+   # Install in editable mode with dev dependencies
+   pip install -e ".[dev]"
+
+A helper script ``start-venv.sh`` is also provided. It creates a virtual
+environment with ``--system-site-packages`` enabled (useful when system-level
+dependencies like ``python3-magnetsetup`` are installed via apt):
+
+.. code-block:: bash
+
+   ./start-venv.sh
+   source venv/bin/activate
+
+Using ``uv`` instead of pip:
+
+.. code-block:: bash
+
+   uv venv venv
+   source venv/bin/activate
+   uv pip install -e ".[dev]"
+
+
+Debian Packaging
+----------------
+
+Installing from the LNCMI Debian repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the package is available in the LNCMI Debian repository:
+
+.. code-block:: bash
+
+   sudo apt update
+   sudo apt install python3-magnetapi
+
+Building the Debian package locally
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Install required build tools and dependencies:
+
+.. code-block:: bash
+
+   sudo apt install debhelper dh-python python3-all python3-setuptools \
+                    devscripts build-essential
+   sudo apt install python3-magnetrun python3-magnetsetup python3-rich
+
+Build the package:
+
+.. code-block:: bash
+
+   # Using the archive script (recommended)
+   ./archive.sh -v 0.1.0 -d trixie
+
+   # Or manually
+   dpkg-buildpackage -us -uc -b
+
+Install the resulting ``.deb`` file:
+
+.. code-block:: bash
+
+   sudo dpkg -i ../python3-magnetapi_0.1.0-1_all.deb
+   sudo apt install -f  # Fix any missing dependencies
+
+
+Docker / DevContainer
+---------------------
+
+A DevContainer configuration is provided in ``.devcontainer/`` for use with
+VS Code or any OCI-compatible runtime.
+
+Building the Docker image:
+
+.. code-block:: bash
+
+   docker build -f .devcontainer/Dockerfile -t magnetapi:latest .
+
+Running the container:
+
+.. code-block:: bash
+
+   docker run -it --net host \
+     -e MAGNETDB_API_KEY=${MAGNETDB_API_KEY} \
+     magnetapi:latest
+
+For VS Code users, open the project folder and select **"Reopen in Container"**
+when prompted. The DevContainer automatically builds the image, installs all
+dependencies (including ``python3-magnetrun``, ``python3-magnetsetup``, and
+``python3-rich`` from the LNCMI Debian repository), and configures Python
+tooling.
+
+
+Singularity / Apptainer
+------------------------
+
+Convert the Docker image to a Singularity/Apptainer container (useful for HPC
+environments):
+
+.. code-block:: bash
+
+   # Build from the local Docker image
+   singularity build magnetapi.sif docker-daemon://magnetapi:latest
+
+   # Or with Apptainer
+   apptainer build magnetapi.sif docker-daemon://magnetapi:latest
+
+Run the container:
+
+.. code-block:: bash
+
+   singularity exec magnetapi.sif python -m python_magnetapi.cli --help
+
+
+Optional Dependencies
+---------------------
+
+For development and testing:
+
+.. code-block:: bash
+
+   pip install -e ".[dev]"
+
+This installs ``pytest`` and ``pytest-cov``.
+
+For building the documentation:
+
+.. code-block:: bash
+
+   pip install -e ".[doc]"
+
+This installs ``sphinx`` and ``sphinx-rtd-theme``.
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..954237b
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
new file mode 100644
index 0000000..5a03084
--- /dev/null
+++ b/docs/quickstart.rst
@@ -0,0 +1,93 @@
+Quick Start
+===========
+
+This guide walks you through the basic usage of ``python_magnetapi``.
+
+Prerequisites
+-------------
+
+Make sure you have:
+
+1. Installed the package (see :doc:`installation`)
+2. Configured access to MagnetDB (see :doc:`configuration`)
+3. Exported your API key:
+
+   .. code-block:: bash
+
+      export MAGNETDB_API_KEY=your_api_key_here
+
+
+Using the CLI
+-------------
+
+The CLI is accessible either as a console script or via ``python -m``:
+
+.. code-block:: bash
+
+   # Using the installed entry point
+   python_magnetapi --help
+
+   # Or using the module directly
+   python -m python_magnetapi.cli --help
+
+List all materials:
+
+.. code-block:: bash
+
+   python -m python_magnetapi.cli --https list --mtype material
+
+View a specific material:
+
+.. code-block:: bash
+
+   python -m python_magnetapi.cli --https view --mtype material --name testmat2
+
+Create a material from inline JSON:
+
+.. code-block:: bash
+
+   python -m python_magnetapi.cli --https create --mtype material \
+     --data '{"name": "tutu"}'
+
+
+Using the Library
+-----------------
+
+You can also use ``python_magnetapi`` as a Python library for programmatic
+access:
+
+.. code-block:: python
+
+   import os
+   import requests
+   from python_magnetapi import utils
+
+   api_server = os.getenv("MAGNETDB_API_SERVER", "api.magnetdb-dev.local")
+   headers = {"Authorization": os.getenv("MAGNETDB_API_KEY")}
+   web = f"https://{api_server}"
+
+   with requests.Session() as s:
+       # Verify connectivity
+       r = s.get(f"{web}/api/magnets", headers=headers, verify=True)
+       r.raise_for_status()
+
+       # List all magnets
+       ids = utils.get_list(s, web, headers=headers, mtype="magnet")
+       for name, obj_id in ids.items():
+           print(f"Magnet: {name} (id={obj_id})")
+
+       # Get a specific object
+       if "M19061901" in ids:
+           obj = utils.get_object(
+               s, web, headers=headers,
+               mtype="magnet", id=ids["M19061901"]
+           )
+           print(obj)
+
+
+Next Steps
+----------
+
+- See :doc:`cli` for the full CLI reference
+- See :doc:`usage` for advanced usage patterns
+- See the :doc:`api/index` for the complete Python API reference
diff --git a/docs/testing.rst b/docs/testing.rst
new file mode 100644
index 0000000..7c63fe7
--- /dev/null
+++ b/docs/testing.rst
@@ -0,0 +1,125 @@
+Testing
+=======
+
+``python_magnetapi`` includes a test suite that exercises the API interaction
+layer against a running MagnetDB instance.
+
+
+Prerequisites
+-------------
+
+Tests require:
+
+1. A running MagnetDB instance
+2. A valid API key exported as ``MAGNETDB_API_KEY``
+3. Development dependencies installed:
+
+.. code-block:: bash
+
+   pip install -e ".[dev]"
+
+
+Running Tests
+-------------
+
+.. code-block:: bash
+
+   export MAGNETDB_API_KEY=your_api_key_here
+
+   # Run all tests
+   pytest
+
+   # Run with verbose output
+   pytest --verbose
+
+   # Run a specific test file
+   pytest tests/test_list.py
+
+   # Run a specific test class or method
+   pytest tests/test_list.py::TestList::test_material
+
+   # Run with coverage
+   pytest --cov=python_magnetapi --cov-report=html --cov-report=term
+
+
+Testing Inside Docker
+---------------------
+
+When testing against a local MagnetDB instance running in Docker:
+
+.. code-block:: bash
+
+   export MAGNETDB_API_KEY=test
+   export MAGNETDB_API_SERVER=http://localhost:8000
+   pytest --verbose
+
+
+Test Structure
+--------------
+
+.. code-block:: text
+
+   tests/
+   ├── __init__.py
+   └── test_list.py        # List, CRUD, and integration tests
+
+The test suite covers:
+
+- **TestList**: Verifies that listing each object type returns results
+  (materials, parts, magnets, sites, records, simulations).
+- **TestCrud**: Tests create, read, update, and delete operations for each
+  object type using sample data files.
+
+
+Writing New Tests
+-----------------
+
+Create test files following the ``test_*.py`` naming convention in the
+``tests/`` directory:
+
+.. code-block:: python
+
+   import os
+   import pytest
+   import requests
+   from python_magnetapi import utils
+
+   api_server = os.getenv("MAGNETDB_API_SERVER", "api.magnetdb-dev.local")
+   headers = {"Authorization": os.getenv("MAGNETDB_API_KEY")}
+
+
+   class TestMyFeature:
+       def test_something(self):
+           with requests.Session() as s:
+               ids = utils.get_list(
+                   s, api_server, headers=headers,
+                   mtype="material"
+               )
+               assert len(ids) > 0
+
+Pytest configuration is defined in ``pyproject.toml`` under
+``[tool.pytest.ini_options]``:
+
+.. code-block:: toml
+
+   [tool.pytest.ini_options]
+   testpaths = ["tests"]
+   python_files = ["test_*.py"]
+   python_classes = ["Test*"]
+   python_functions = ["test_*"]
+   addopts = "-v --tb=short"
+
+
+Coverage
+--------
+
+Generate an HTML coverage report:
+
+.. code-block:: bash
+
+   pytest --cov=python_magnetapi --cov-report=html
+
+Open ``htmlcov/index.html`` in your browser to inspect the results.
+
+Coverage configuration is in ``pyproject.toml`` under ``[tool.coverage.run]``
+and ``[tool.coverage.report]``.
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000..b4cd0fa
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,156 @@
+Usage Guide
+===========
+
+This guide covers advanced usage patterns for ``python_magnetapi``.
+
+
+Object Types
+------------
+
+MagnetDB organizes data into the following object types:
+
+- **material**: Physical materials with properties (conductivity, density, etc.)
+- **part**: Individual components (helices, bitter disks, supra coils) made of a material
+- **magnet**: An assembly of parts
+- **site**: A physical installation containing one or more magnets
+- **record**: Experimental measurement data attached to a site
+- **server**: Compute servers for running simulations
+- **simulation**: Simulation configurations and results
+
+
+CRUD Operations
+---------------
+
+All object types support the basic CRUD (Create, Read, Update, Delete) workflow.
+
+Creating objects with dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When creating a **part**, you must specify its material. The material can be
+referenced by name (if it already exists in the database) or provided as a
+nested dictionary to be created on the fly:
+
+.. code-block:: python
+
+   from python_magnetapi.part import create as part_create
+
+   # Reference existing material by name
+   data = {
+       "name": "H22121601",
+       "type": "helix",
+       "material": "CuAg",
+   }
+   part_create(session, web, headers=headers, data=data)
+
+Similarly, **magnets** reference parts and **sites** reference magnets.
+
+
+Simulation Workflow
+-------------------
+
+A typical simulation workflow consists of three steps:
+
+1. **Setup**: Configure the simulation parameters
+2. **Run**: Execute the simulation on a compute server
+3. **Post-process**: Analyze and retrieve results
+
+.. code-block:: bash
+
+   # Step 1: Setup
+   python_magnetapi --https setup --mtype site --name M10_M19020601 \
+     --method cfpdes --geometry Axi --model thelec --cooling mean \
+     --current 31000 12000 100 --wd ./setup_output
+
+   # Step 2: Run (use the simulation ID from setup)
+   python_magnetapi --https run --simu_id 42 --wd ./run_output
+
+
+Computing Derived Quantities
+----------------------------
+
+Flow parameters
+~~~~~~~~~~~~~~~
+
+Compute flow parameters for a magnet by fitting experimental record data:
+
+.. code-block:: bash
+
+   python_magnetapi --https compute --mtype magnet \
+     --name M19061901 --flow_params --samples 20
+
+Hoop stress
+~~~~~~~~~~~
+
+Compute the hoop stress history for a part across all sites where it has
+been installed:
+
+.. code-block:: bash
+
+   python_magnetapi --https compute --mtype part \
+     --name H15101601 --hoop_stress
+
+This retrieves the operational history (records) for each site, extracts
+current data, and calculates the mechanical stress on the part.
+
+Inductances
+~~~~~~~~~~~
+
+Compute self and mutual inductances for a magnet:
+
+.. code-block:: bash
+
+   python_magnetapi --https compute --mtype magnet \
+     --name M19061901 --inductances
+
+
+Working with the Python API
+---------------------------
+
+Session management
+~~~~~~~~~~~~~~~~~~
+
+The library uses ``requests.Session`` objects for HTTP connection pooling:
+
+.. code-block:: python
+
+   import os
+   import requests
+   from python_magnetapi import utils
+
+   headers = {"Authorization": os.getenv("MAGNETDB_API_KEY")}
+   web = "https://api.magnetdb.local"
+
+   with requests.Session() as s:
+       # All API calls share the same session
+       ids = utils.get_list(s, web, headers=headers, mtype="magnet")
+       for name, oid in ids.items():
+           obj = utils.get_object(s, web, headers=headers, mtype="magnet", id=oid)
+           print(f"{name}: {obj}")
+
+Pagination
+~~~~~~~~~~
+
+The ``get_list`` function handles pagination automatically, iterating through
+all pages of results and returning a complete dictionary of ``{name: id}``
+pairs.
+
+File attachments
+~~~~~~~~~~~~~~~~
+
+Objects can have associated files (geometries, CAD files, records). Use the
+utility functions to manage attachments:
+
+.. code-block:: python
+
+   # Download an attachment
+   filename = utils.download(session, web, headers, attach_id, wd="./downloads")
+
+   # Add a geometry file to a part
+   utils.add_data_files_to_object(
+       session, web, headers,
+       id=part_id,
+       mtype="part",
+       dtype="geometrie",
+       data={"type": "default"},
+       files={"geometry": "H15101601.yaml"},
+   )
diff --git a/docs/utils.rst b/docs/utils.rst
new file mode 100644
index 0000000..2f75ff2
--- /dev/null
+++ b/docs/utils.rst
@@ -0,0 +1,11 @@
+utils
+=====
+
+Core utility functions for interacting with the MagnetDB REST API. This module
+provides low-level HTTP operations (listing, fetching, creating, updating,
+deleting objects) used by all other modules.
+
+.. automodule:: python_magnetapi.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/examples/README-demos.md b/examples/README-demos.md
new file mode 100644
index 0000000..9a51ada
--- /dev/null
+++ b/examples/README-demos.md
@@ -0,0 +1,210 @@
+# MagnetDB Part History — Demonstrators
+
+Two stand-alone scripts that query the MagnetDB REST API to trace the
+operational history of a magnet **part** (helix, bitter, or supra insert).
+
+Both scripts rely only on `python_magnetapi.utils` and the standard
+`requests` library; no simulation setup or `magnettools` bindings are
+required.
+
+---
+
+## Prerequisites
+
+| Variable | Description |
+|---|---|
+| `MAGNETDB_API_KEY` | Personal API token (copy from your profile page on MagnetDB) |
+| `MAGNETDB_API_SERVER` | Hostname of the API server — host only, no scheme (e.g. `api.magnetdb.local`) |
+
+```bash
+export MAGNETDB_API_KEY=xxxxxxxxxxxx
+export MAGNETDB_API_SERVER=api.magnetdb.local
+```
+
+Both scripts accept `--server` on the command line to override the environment
+variable without changing your shell.
+
+---
+
+## Demo 1 — `demo_part_history.py`
+
+### What it does
+
+Given a part name, retrieves and prints:
+
+1. **Part metadata** — name, type, status
+2. **Magnets** that have ever contained this part, sorted chronologically
+3. **Sites** (experimental stations) in which those magnets were used,
+   deduplicated and sorted chronologically
+
+The date used for sorting is `commissioned_at` when available, falling back
+to `created_at`.
+
+### API calls made
+
+```
+GET /api/parts            → resolve name → id
+GET /api/parts/{id}       → part metadata
+GET /api/parts/{id}/magnets  → join rows → magnet ids
+GET /api/magnets/{id}     → magnet metadata  (one call per magnet)
+GET /api/magnets/{id}/sites  → join rows → site ids
+GET /api/sites/{id}       → site metadata    (one call per site)
+```
+
+### Usage
+
+```bash
+python demo_part_history.py --part H22121601
+```
+
+### All flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--part` | *(required)* | Part name to inspect |
+| `--server` | `$MAGNETDB_API_SERVER` | API hostname (no scheme) |
+| `--port` | `8000` | Port (HTTP only) |
+| `--https` | off | Use HTTPS instead of HTTP |
+| `--debug` | off | Print raw JSON API responses |
+
+### Sample output
+
+```
+============================================================
+  Part history for: H22121601
+  Server          : http://api.magnetdb.local:8000
+============================================================
+
+Part details
+  name   : H22121601
+  type   : helix
+  status : in_stock
+
+Magnets containing this part  (3 found, sorted by date)
+  [2021-06-18]  HL-31  (id=12)
+  [2022-01-05]  HL-34  (id=47)
+  [2023-03-12]  HL-36  (id=61)
+
+Sites that used this part (via its magnets)  (2 found, sorted by date)
+  [2022-03-01]  M9_M18110501   (id=5)
+  [2023-01-20]  M10_M19020601  (id=9)
+```
+
+---
+
+## Demo 2 — `demo_part_site_records.py`
+
+### What it does
+
+Extends Demo 1 with richer information for every site:
+
+1. **Part metadata** — as in Demo 1
+2. **Magnets** — as in Demo 1
+3. **Sites** with full detail cards, each showing:
+   - Status, description
+   - Commission and decommission dates
+   - Which magnets (from the part's history) link to this site
+   - **All measurement records** attached to the site, sorted by creation date
+
+Optionally dumps the raw site JSON payloads with `--json`.
+
+### API calls made
+
+Same as Demo 1, plus:
+
+```
+GET /api/sites/{id}/records  → record list with names and dates
+```
+
+### Usage
+
+```bash
+python demo_part_site_records.py --part H22121601
+```
+
+With JSON dump:
+
+```bash
+python demo_part_site_records.py --part H22121601 --json
+```
+
+### All flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--part` | *(required)* | Part name to inspect |
+| `--server` | `$MAGNETDB_API_SERVER` | API hostname (no scheme) |
+| `--port` | `8000` | Port (HTTP only) |
+| `--https` | off | Use HTTPS instead of HTTP |
+| `--json` | off | Dump raw site JSON payloads at end of output |
+| `--debug` | off | Print raw JSON API responses |
+
+### Sample output
+
+```
+======================================================================
+  Part history + site details + records
+  Part  : H22121601
+  Server: http://api.magnetdb.local:8000
+======================================================================
+
+Part details
+  name     : H22121601
+  type     : helix
+  status   : in_stock
+  ref      : —
+  created  : 2021-06-18 10:32
+
+──────────────────────────────────────────────────────────────────────
+Magnets containing this part  (3, sorted by date)
+──────────────────────────────────────────────────────────────────────
+  [2021-06-18 10:32]  HL-31  (id=12)
+  [2022-01-05 09:15]  HL-34  (id=47)
+  [2023-03-12 14:00]  HL-36  (id=61)
+
+──────────────────────────────────────────────────────────────────────
+Sites that used this part (via its magnets)  (2, sorted by date)
+──────────────────────────────────────────────────────────────────────
+
+  ▶  M9_M18110501   (id=5)
+     status        : decommissioned
+     description   : 9 T insert magnet cell
+     commissioned  : 2022-03-01 08:00
+     decommissioned: 2023-11-15 17:30
+     magnets       : HL-31, HL-34
+     records (  42) :
+                    [2022-03-22 09:27]  M9_2022.03.22---09:27:56.txt
+                    [2022-04-01 14:05]  M9_2022.04.01---14:05:12.txt
+                    ...
+
+  ▶  M10_M19020601  (id=9)
+     status        : in_use
+     description   : 10 T insert magnet cell
+     commissioned  : 2023-01-20 11:00
+     decommissioned: —
+     magnets       : HL-36
+     records ( 118) :
+                    [2023-01-25 08:41]  M10_2023.01.25---08:41:03.txt
+                    ...
+```
+
+---
+
+## Relationship between the two demos
+
+```
+demo_part_history.py          demo_part_site_records.py
+─────────────────────         ──────────────────────────────────────
+part metadata          ──▶    part metadata
+magnets (sorted)       ──▶    magnets (sorted)
+sites (sorted)         ──▶    sites (sorted) + full card per site
+                                └── status, dates, description
+                                └── linked magnet names
+                                └── all record names (sorted)
+                       (opt)   raw JSON dump  (--json)
+```
+
+Demo 1 is useful for a quick chronological overview.
+Demo 2 is the starting point for further analysis such as hoop-stress
+history computation (`hoop_stress.py`), which consumes the record list
+exposed by each site card.
diff --git a/examples/calcul_DT_helices_from_api.py b/examples/calcul_DT_helices_from_api.py
new file mode 100644
index 0000000..3b08245
--- /dev/null
+++ b/examples/calcul_DT_helices_from_api.py
@@ -0,0 +1,771 @@
+#!/usr/bin/env python3
+"""
+calcul_DT_helices_from_api.py
+==============================
+Compute helix conductor temperature rise for a resistive magnet by fetching
+geometry and material data from MagnetDB, then applying the same physical
+model as calcul_DT_helices_HL31.py.
+
+Three geometry backends are supported (selected automatically by priority):
+
+  1. **magnettools** (preferred) — when ``--dfile PATH`` points to a pre-generated
+     ``.d`` input file.  ``mt.read_dfile`` populates ``VectorOfTubes`` and
+     ``VectorOfBitters``; all geometry (r_int, r_ext) and physical parameters
+     (Σ → ρ, k_thermal, T_water, h_conv) are read directly from those objects.
+     No network access required.
+
+  2. **JSON file** — when ``--jsonfile PATH`` points to a file produced by
+     ``utils.get_object(session, api_server, headers, mtype="magnet", id=…)``.
+     Geometry is read from the embedded ``part.geometry_config`` dict
+     (``r[mm]``, ``modelaxi.pitch[mm]``, ``modelaxi.turns``).
+     Material parameters (ρ, λ) come from ``part.material`` when present;
+     use ``--rho`` / ``--lam`` to supply them when absent.
+     No network access required.
+
+  3. **API + YAML** (fallback) — geometry is obtained by downloading the
+     per-helix YAML attachments from MagnetDB and parsing them with PyYAML;
+     material properties (ρ, λ) come from the ``material`` sub-object of each
+     part API response.  Requires ``MAGNETDB_API_KEY``.
+
+Physical model (identical to calcul_DT_helices_HL31.py)
+---------------------------------------------------------
+  j        [A/m²]   = I / (e · h_spire)
+  P_vol    [W/m³]   = ρ · j²
+  flux     [W/m²]   = P_vol · (Dext − Dint) / 4
+  DT_paroi [°C]     = flux / h_conv
+  DT_plane [°C]     = P_vol · e² / (8 · λ)
+  DT_cyl   [°C]     = DT_plane · [1 + (Dext−Dint)² / (16·Dint·Dext)]
+  Tmax     [°C]     = Teau + DT_paroi + DT_plane
+  Tmoy     [°C]     = Teau + DT_paroi + 2/3 · DT_plane
+
+Matthiessen consistency check uses ρ_IACS_20 = 1.7241×10⁻⁸ Ω·m, T0 = 219.33 °C.
+
+Usage
+-----
+  # magnettools .d file (no network needed):
+  python calcul_DT_helices_from_api.py M9 --current 31000 --dfile M9.d
+
+  # Local JSON export of utils.get_object (no network needed):
+  python calcul_DT_helices_from_api.py M9 --current 31000 --jsonfile M9.json
+
+  # API-only (YAML fallback):
+  python calcul_DT_helices_from_api.py M9 --current 31000
+
+  # Override cooling defaults:
+  python calcul_DT_helices_from_api.py M9 --current 31000 --h_conv 85000 --Teau 30
+
+  # Full server specification:
+  python calcul_DT_helices_from_api.py M9 --current 31000 \\
+      --server magnetdb.lncmi.local --https
+
+Authentication
+--------------
+  export MAGNETDB_API_KEY=<your_key>   # only required for the API backend
+"""
+
+from __future__ import annotations
+
+import argparse
+import enum
+import json
+import math
+import os
+import sys
+import warnings
+from dataclasses import dataclass
+from typing import Optional
+
+import pandas as pd
+import requests
+
+from python_magnetapi import utils
+from python_magnetapi.cli.parser import add_server_arguments
+
+# ── Optional magnettools import ──────────────────────────────────────────────
+try:
+    import magnettools as mt  # pybind11 bindings
+
+    HAS_MT = True
+except ImportError:
+    HAS_MT = False
+    warnings.warn(
+        "magnettools not importable — .d-file backend unavailable; "
+        "falling back to API/JSON geometry."
+    )
+
+# ---------------------------------------------------------------------------
+# Physical constants (shared with calcul_DT_helices_HL31.py)
+# ---------------------------------------------------------------------------
+RHO_IACS_20 = 1.7241e-8  # 100 % IACS resistivity at 20 °C  [Ω·m]
+T0_MATTHIESSEN = 219.33  # Matthiessen offset temperature  [°C]
+
+# Fallback cooling defaults (LNCMI resistive magnets)
+DEFAULT_H_CONV = 85_000.0  # W/(m²·°C)
+DEFAULT_TEAU = 30.0  # °C
+
+
+# ---------------------------------------------------------------------------
+# Part types
+# ---------------------------------------------------------------------------
+class PartType(str, enum.Enum):
+    """Part types as defined in MagnetDB."""
+
+    HELIX = "helix"
+    BITTER = "bitter"
+    SUPRA = "supra"
+    RING = "ring"
+    SCREEN = "screen"
+    LEAD = "lead"
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses (identical interface to calcul_DT_helices_HL31.py)
+# ---------------------------------------------------------------------------
+@dataclass
+class HelixInput:
+    name: str
+    rho: float  # Electrical resistivity [Ω·m] at operating temperature
+    Current: float  # Current [A]
+    h_conv: float  # Convective HTC [W/(m²·°C)]
+    Dint: float  # Inner diameter [m]
+    Dext: float  # Outer diameter [m]
+    lam: float  # Thermal conductivity [W/(m·°C)]
+    Teau: float  # Cooling water temperature [°C]
+    h_spire: float  # Coil pitch [m]
+    rapport: Optional[float] = None  # conductivity / IACS → T_moy_ro derived
+    T_moy_ro: Optional[float] = None  # mean temp from ρ → rapport derived
+
+
+@dataclass
+class HelixResult:
+    name: str
+    h_spire: float
+    j: float
+    P_vol: float
+    flux: float
+    DT_paroi: float
+    DT_plane: float
+    DT_cyl: float
+    Tmax: float
+    Tmoy: float
+    T_moy_ro: float
+    rapport: float
+
+
+# ---------------------------------------------------------------------------
+# Core computation
+# ---------------------------------------------------------------------------
+def compute_helix(inp: HelixInput) -> HelixResult:
+    e = (inp.Dext - inp.Dint) / 2.0
+    j = inp.I / (e * inp.h_spire)
+    P_vol = inp.rho * j**2
+    flux = P_vol * (inp.Dext - inp.Dint) / 4.0
+    DT_paroi = flux / inp.h_conv
+    DT_plane = P_vol * e**2 / (8.0 * inp.lam)
+    DT_cyl = DT_plane * (
+        1.0 + (inp.Dext - inp.Dint) ** 2 / (16.0 * inp.Dint * inp.Dext)
+    )
+    Tmax = inp.Teau + DT_paroi + DT_plane
+    Tmoy = inp.Teau + DT_paroi + (2.0 / 3.0) * DT_plane
+
+    if inp.rapport is not None:
+        T_moy_ro = _t_from_rapport(inp.rho, inp.rapport)
+        rapport = inp.rapport
+    elif inp.T_moy_ro is not None:
+        rapport = _rapport_from_T(inp.rho, inp.T_moy_ro)
+        T_moy_ro = inp.T_moy_ro
+    else:
+        T_moy_ro = math.nan
+        rapport = math.nan
+
+    return HelixResult(
+        name=inp.name,
+        h_spire=inp.h_spire,
+        j=j,
+        P_vol=P_vol,
+        flux=flux,
+        DT_paroi=DT_paroi,
+        DT_plane=DT_plane,
+        DT_cyl=DT_cyl,
+        Tmax=Tmax,
+        Tmoy=Tmoy,
+        T_moy_ro=T_moy_ro,
+        rapport=rapport,
+    )
+
+
+def _t_from_rapport(rho, rapport):
+    return (20.0 + T0_MATTHIESSEN) * (
+        rho / RHO_IACS_20 - 1.0 / rapport + 1.0
+    ) - T0_MATTHIESSEN
+
+
+def _rapport_from_T(rho, T_moy_ro):
+    denom = (
+        rho / RHO_IACS_20 - (T_moy_ro + T0_MATTHIESSEN) / (20.0 + T0_MATTHIESSEN) + 1.0
+    )
+    return 1.0 / denom
+
+
+def results_to_dataframe(results: list[HelixResult]) -> pd.DataFrame:
+    rows = [
+        {
+            "Helix": r.name,
+            "h_spire [m]": r.h_spire,
+            "j [A/m²]": r.j,
+            "P_vol [W/m³]": r.P_vol,
+            "Flux [W/m²]": r.flux,
+            "DT_paroi [°C]": r.DT_paroi,
+            "DT_plane [°C]": r.DT_plane,
+            "DT_cyl [°C]": r.DT_cyl,
+            "Tmax [°C]": r.Tmax,
+            "Tmoy [°C]": r.Tmoy,
+            "T_moy_ro [°C]": r.T_moy_ro,
+            "Rapport IACS": r.rapport,
+        }
+        for r in results
+    ]
+    return pd.DataFrame(rows).set_index("Helix")
+
+
+# ---------------------------------------------------------------------------
+# Backend A: magnettools .d-file
+# ---------------------------------------------------------------------------
+def _load_from_dfile(
+    dfile: str,
+    Current: float,
+    h_conv_override: Optional[float],
+    Teau_override: Optional[float],
+    debug: bool,
+) -> list[HelixInput]:
+    """
+    Load helix parameters from a magnettools .d input file.
+
+    Geometry  — ``BitterMagnet.get_R_int/ext()``  [m]
+    Pitch     — ``Tube.get_pitch(i)``              [mm] × ``get_nturn(i)`` turns
+    ρ         — 1 / ``Tube.get_physical_params(0)``  (Sigma [S/m])
+    λ         — ``Tube.get_physical_params(2)``       (k [W/m/°C])
+    Teau      — ``Tube.get_cooling_params(0)``         [°C]
+    h_conv    — ``Tube.get_cooling_params(1)``         [W/m²/°C]
+
+    The rapport / T_moy_ro consistency check is skipped here (NaN) because
+    the .d file does not carry IACS ratio metadata; supply it via --rapport if
+    needed.
+    """
+    Tubes = mt.VectorOfTubes()
+    Helices = mt.VectorOfBitters()
+    OHelices = mt.VectorOfBitters()
+    BMagnets = mt.VectorOfBitters()
+    UMagnets = mt.VectorOfUnifs()
+    Shims = mt.VectorOfShims()
+
+    mt.read_dfile(dfile, Tubes, Helices, OHelices, BMagnets, UMagnets, Shims)
+
+    if debug:
+        print(
+            f"[dfile] loaded {dfile}: #Tubes={Tubes.size()}, #Helices={Helices.size()}"
+        )
+
+    inputs: list[HelixInput] = []
+    for ti in range(Tubes.size()):
+        tube = Tubes[ti]
+        idx = tube.get_index()  # starting index into Helices vector
+        bm = Helices[idx]  # first (innermost) BitterMagnet section
+
+        # ── geometry ──
+        R_int = bm.get_R_int()  # [m]
+        R_ext = bm.get_R_ext()  # [m]
+        Dint = 2.0 * R_int
+        Dext = 2.0 * R_ext
+
+        # ── coil pitch (weighted average over sections) ──
+        n_sec = tube.get_n_pitch()
+        pitches = [tube.get_pitch(i) for i in range(n_sec)]
+        nturns = [tube.get_nturn(i) for i in range(n_sec)]
+        total_turns = sum(nturns)
+        total_height = sum(p * n for p, n in zip(pitches, nturns))
+        h_spire = (total_height / total_turns) * 1e-3  # mm → m
+
+        # ── material ──
+        sigma = tube.get_physical_params(0)  # [S/m]
+        rho = 1.0 / sigma if sigma > 0 else math.nan
+        lam = tube.get_physical_params(2)  # [W/m/°C]
+
+        # ── cooling ──
+        Teau = (
+            Teau_override if Teau_override is not None else tube.get_cooling_params(0)
+        )
+        h_conv = (
+            h_conv_override
+            if h_conv_override is not None
+            else tube.get_cooling_params(1)
+        )
+
+        if debug:
+            print(
+                f"  H{ti+1}: R_int={R_int*1e3:.2f} mm, R_ext={R_ext*1e3:.2f} mm, "
+                f"h_spire={h_spire*1e3:.3f} mm, rho={rho:.3e}, lam={lam:.1f}, "
+                f"Teau={Teau}, h_conv={h_conv}"
+            )
+
+        inputs.append(
+            HelixInput(
+                name=f"H{ti+1}",
+                rho=rho,
+                Current=Current,
+                h_conv=h_conv,
+                Dint=Dint,
+                Dext=Dext,
+                lam=lam,
+                Teau=Teau,
+                h_spire=h_spire,
+            )
+        )
+    return inputs
+
+
+# ---------------------------------------------------------------------------
+# Backend B: live MagnetDB API  /  Backend C: local JSON file
+# ---------------------------------------------------------------------------
+def _parse_geometry_config(gc: dict, part_name: str, debug: bool) -> Optional[dict]:
+    """
+    Extract Dint [m], Dext [m], and h_spire [m] from a ``geometry_config`` dict.
+
+    This is the embedded geometry block present in every helix part returned
+    by ``utils.get_object`` / ``utils.get_cache``::
+
+        "geometry_config": {
+            "r": [r_int_mm, r_ext_mm],
+            "modelaxi": {
+                "pitch": [...],   # mm per section
+                "turns": [...]    # fractional turns per section
+            }
+        }
+
+    ``h_spire`` is the turn-weighted average pitch:
+        h_spire = Σ(pitch_i × turns_i) / Σ(turns_i)  [mm → m]
+    """
+    r = gc.get("r", [])
+    if len(r) < 2:
+        warnings.warn(
+            f"  {part_name}: geometry_config.r missing or short ({r}) — skipped."
+        )
+        return None
+
+    modelaxi = gc.get("modelaxi", {})
+    pitches = modelaxi.get("pitch", [])
+    nturns = modelaxi.get("turns", [])
+
+    if not pitches or not nturns:
+        warnings.warn(
+            f"  {part_name}: geometry_config.modelaxi missing pitch/turns — skipped."
+        )
+        return None
+
+    total_turns = sum(nturns)
+    total_height = sum(p * n for p, n in zip(pitches, nturns))
+    h_spire = (total_height / total_turns) * 1e-3  # mm → m
+
+    if debug:
+        print(
+            f"  {part_name}: r={r} mm, {len(pitches)} sections, "
+            f"h_spire={h_spire * 1e3:.3f} mm"
+        )
+
+    return {
+        "Dint": 2.0 * r[0] * 1e-3,
+        "Dext": 2.0 * r[1] * 1e-3,
+        "h_spire": h_spire,
+    }
+
+
+def _extract_material_params(material: dict, debug: bool) -> dict:
+    """
+    Extract ρ [Ω·m], λ [W/(m·°C)], and rapport from a MagnetDB material object.
+
+    Field name candidates (tries each in order):
+      ρ      : rho, electrical_resistivity, rho20
+      λ      : thermal_conductivity, kappa, k, lam
+      rapport: alpha, conductivity_ratio, iacs_ratio, rapport
+
+    If a field is not found the returned value is None; the caller decides
+    whether to fall back to CLI overrides or raise an error.
+    """
+
+    def first(*keys):
+        for k in keys:
+            if k in material and material[k] is not None:
+                return float(material[k])
+        return None
+
+    rho = first("rho", "electrical_resistivity", "rho20")
+    lam = first("thermal_conductivity", "kappa", "k", "lam")
+    rapport = first("alpha", "conductivity_ratio", "iacs_ratio", "rapport")
+
+    if debug:
+        print(
+            f"  material '{material.get('name', '?')}': "
+            f"rho={rho}, lam={lam}, rapport={rapport}"
+        )
+        if rho is None or lam is None:
+            print(f"  available material keys: {list(material.keys())}")
+
+    return {"rho": rho, "lam": lam, "rapport": rapport}
+
+
+def _build_helix_inputs_from_api(
+    session,
+    api_server: str,
+    auth_headers: dict,
+    magnet_name: str,
+    Current: float,
+    h_conv_override: Optional[float],
+    Teau_override: Optional[float],
+    rho_override: Optional[float],
+    lam_override: Optional[float],
+    debug: bool,
+) -> list[HelixInput]:
+    """
+    Fetch a magnet from the live MagnetDB API and build helix inputs.
+
+    Geometry is read from ``part.geometry_config`` (embedded in the magnet
+    response); material parameters come from the ``material`` sub-dict when
+    present, overridden by CLI flags if supplied.
+
+    Uses ``utils.get_object`` to retrieve individual objects by ID.
+    """
+    # ── locate the magnet ─────────────────────────────────────────────────
+    all_magnets = utils.get_list(
+        session, api_server, auth_headers, mtype="magnet"
+    )
+    if magnet_name not in all_magnets:
+        raise ValueError(
+            f"Magnet '{magnet_name}' not found in MagnetDB. "
+            f"Available: {sorted(all_magnets.keys())}"
+        )
+    magnet = utils.get_object(
+        session,
+        api_server,
+        headers=auth_headers,
+        mtype="magnet",
+        id=all_magnets[magnet_name],
+    )
+    if debug:
+        print(
+            f"[API] magnet '{magnet_name}' id={all_magnets[magnet_name]}, "
+            f"parts={len(magnet.get('magnet_parts', []))}"
+        )
+
+    return _helix_inputs_from_magnet_dict(
+        magnet,
+        Current,
+        h_conv_override,
+        Teau_override,
+        rho_override,
+        lam_override,
+        debug,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Backend C: local JSON file  (output of utils.get_object for a magnet)
+# ---------------------------------------------------------------------------
+def _helix_inputs_from_magnet_dict(
+    magnet: dict,
+    Current: float,
+    h_conv_override: Optional[float],
+    Teau_override: Optional[float],
+    rho_override: Optional[float],
+    lam_override: Optional[float],
+    debug: bool,
+) -> list[HelixInput]:
+    """
+    Shared core used by both the JSON-file and the live-API backends.
+
+    Iterates ``magnet["magnet_parts"]``, skips non-helix parts, and builds a
+    ``HelixInput`` for each helix using:
+
+    * **Geometry** — ``part.geometry_config`` (``r[mm]`` and
+      ``modelaxi.{pitch,turns}[mm]``).
+    * **Material** — ``part.material`` sub-dict (best-effort field lookup via
+      ``_extract_material_params``), then overridden by *rho_override* /
+      *lam_override* when supplied.
+
+    A helix is skipped (with a warning) if geometry is missing or if
+    neither the material dict nor CLI overrides provide ρ and λ.
+    """
+    inputs: list[HelixInput] = []
+    helix_counter = 0
+
+    for part_stub in magnet.get("magnet_parts", []):
+        pobj = part_stub.get("part", part_stub)
+        ptype = pobj.get("type", "")
+        if ptype != PartType.HELIX:
+            continue
+
+        helix_counter += 1
+        label = f"H{helix_counter}"
+        pname = pobj.get("name", f"part_{part_stub.get('part_id', helix_counter)}")
+
+        # ── geometry ──────────────────────────────────────────────────────
+        gc = pobj.get("geometry_config", {})
+        geom_params = _parse_geometry_config(gc, label, debug=debug)
+        if geom_params is None:
+            continue  # warning already issued inside _parse_geometry_config
+
+        # ── material ──────────────────────────────────────────────────────
+        mat = pobj.get("material") or {}
+        mat_params = _extract_material_params(mat, debug=debug)
+
+        rho = rho_override if rho_override is not None else mat_params["rho"]
+        lam = lam_override if lam_override is not None else mat_params["lam"]
+        h_conv = h_conv_override if h_conv_override is not None else DEFAULT_H_CONV
+        Teau = Teau_override if Teau_override is not None else DEFAULT_TEAU
+
+        if rho is None:
+            warnings.warn(f"{label} ({pname}): ρ not found — provide --rho.")
+            continue
+        if lam is None:
+            warnings.warn(f"{label} ({pname}): λ not found — provide --lam.")
+            continue
+
+        inputs.append(
+            HelixInput(
+                name=label,
+                rho=rho,
+                Current=Current,
+                h_conv=h_conv,
+                Dint=geom_params["Dint"],
+                Dext=geom_params["Dext"],
+                lam=lam,
+                Teau=Teau,
+                h_spire=geom_params["h_spire"],
+                rapport=mat_params.get("rapport"),
+            )
+        )
+
+    return inputs
+
+
+def _build_helix_inputs_from_json(
+    jsonfile: str,
+    Current: float,
+    h_conv_override: Optional[float],
+    Teau_override: Optional[float],
+    rho_override: Optional[float],
+    lam_override: Optional[float],
+    debug: bool,
+) -> list[HelixInput]:
+    """
+    Build helix inputs from a local JSON file produced by
+    ``utils.get_object(session, api_server, headers, mtype="magnet", id=…)``.
+
+    Geometry is read from ``part.geometry_config`` (inline in the JSON).
+    Material parameters come from ``part.material`` when present, and are
+    overridden by *rho_override* / *lam_override* when supplied.
+    """
+    with open(jsonfile) as f:
+        magnet = json.load(f)
+
+    if debug:
+        mname = magnet.get("name", os.path.basename(jsonfile))
+        print(
+            f"[JSON] loaded '{mname}' from {jsonfile}, "
+            f"{len(magnet.get('magnet_parts', []))} magnet_parts"
+        )
+
+    return _helix_inputs_from_magnet_dict(
+        magnet, Current, h_conv_override, Teau_override, rho_override, lam_override, debug
+    )
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        description="Compute helix temperature rise for a MagnetDB magnet.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    p.add_argument("magnet", help="Magnet name (e.g. M9, HL31)")
+    p.add_argument(
+        "--current", "-I", type=float, required=True, help="Operating current [A]"
+    )
+
+    # ── magnettools backend ──
+    mt_grp = p.add_argument_group("magnettools backend (preferred, no network)")
+    mt_grp.add_argument(
+        "--dfile",
+        metavar="PATH",
+        help="Path to a pre-generated magnettools .d input file. "
+        "When supplied, geometry and material params are read from "
+        "Tube/BitterMagnet objects (magnettools bindings) instead of the API.",
+    )
+
+    # ── JSON file backend ──
+    json_grp = p.add_argument_group("JSON file backend (no network)")
+    json_grp.add_argument(
+        "--jsonfile",
+        metavar="PATH",
+        help="Path to a JSON file produced by utils.get_object(…, 'magnet', id). "
+        "Geometry is taken from inline Dint/Dext/h_spire fields or from "
+        "YAML attachment files located next to the JSON file. "
+        "Ignored when --dfile is also given.",
+    )
+
+    # ── server ──
+    add_server_arguments(p)
+
+    # ── cooling overrides ──
+    cool_grp = p.add_argument_group("cooling overrides (API fallback defaults)")
+    cool_grp.add_argument(
+        "--h_conv",
+        type=float,
+        default=None,
+        help=f"Heat-transfer coefficient [W/m²/°C] " f"(default {DEFAULT_H_CONV:.0f})",
+    )
+    cool_grp.add_argument(
+        "--Teau",
+        type=float,
+        default=None,
+        help=f"Cooling water temperature [°C] (default {DEFAULT_TEAU})",
+    )
+
+    # ── material overrides (API fallback) ──
+    mat_grp = p.add_argument_group("material overrides (API fallback)")
+    mat_grp.add_argument(
+        "--rho",
+        type=float,
+        default=None,
+        help="Override resistivity ρ [Ω·m] for all helices",
+    )
+    mat_grp.add_argument(
+        "--lam",
+        type=float,
+        default=None,
+        help="Override thermal conductivity λ [W/m/°C] for all helices",
+    )
+
+    p.add_argument("--verbose", action="store_true")
+    return p
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    needs_api = not args.dfile and not args.jsonfile
+
+    # ── build HelixInput list ─────────────────────────────────────────────
+    if args.dfile:
+        # ── Backend 1: magnettools .d file ────────────────────────────────
+        if not HAS_MT:
+            sys.exit(
+                "Error: magnettools is required for --dfile but could not be imported."
+            )
+        if not os.path.isfile(args.dfile):
+            sys.exit(f"Error: .d file not found: {args.dfile}")
+        print(f"[magnettools] Reading geometry from {args.dfile}")
+        helix_inputs = _load_from_dfile(
+            args.dfile,
+            args.current,
+            h_conv_override=args.h_conv,
+            Teau_override=args.Teau,
+            debug=args.debug,
+        )
+
+    elif args.jsonfile:
+        # ── Backend 2: local JSON export of utils.get_object ─────────────
+        if not os.path.isfile(args.jsonfile):
+            sys.exit(f"Error: JSON file not found: {args.jsonfile}")
+        print(f"[JSON] Reading magnet data from {args.jsonfile}")
+        helix_inputs = _build_helix_inputs_from_json(
+            args.jsonfile,
+            args.current,
+            h_conv_override=args.h_conv,
+            Teau_override=args.Teau,
+            rho_override=args.rho,
+            lam_override=args.lam,
+            debug=args.debug,
+        )
+
+    else:
+        # ── Backend 3: live MagnetDB API ──────────────────────────────────
+        api_key = os.getenv("MAGNETDB_API_KEY")
+        if not api_key:
+            sys.exit(
+                "Error: MAGNETDB_API_KEY environment variable not set.\n"
+                "Tip: use --dfile or --jsonfile to work offline."
+            )
+        auth_headers = {"Authorization": api_key}
+        protocol = "https" if args.https else "http"
+        api_server = (
+            f"{protocol}://{args.server}"
+            if args.port is None
+            else f"{protocol}://{args.server}:{args.port}"
+        )
+        verify = not args.no_verify
+
+        print(f"[API] Fetching geometry for magnet '{args.magnet}' from {api_server}")
+        with requests.Session() as session:
+            session.verify = verify
+            helix_inputs = _build_helix_inputs_from_api(
+                session,
+                api_server,
+                auth_headers,
+                magnet_name=args.magnet,
+                I=args.current,
+                h_conv_override=args.h_conv,
+                Teau_override=args.Teau,
+                rho_override=args.rho,
+                lam_override=args.lam,
+                debug=args.debug,
+            )
+
+    if not helix_inputs:
+        sys.exit(
+            f"No helix inputs assembled for magnet '{args.magnet}'. "
+            "Check input file or API data."
+        )
+
+    # ── compute ───────────────────────────────────────────────────────────
+    results = [compute_helix(h) for h in helix_inputs]
+    df = results_to_dataframe(results)
+
+    # ── display ───────────────────────────────────────────────────────────
+    pd.set_option("display.float_format", "{:.4g}".format)
+    pd.set_option("display.max_columns", None)
+    pd.set_option("display.width", 220)
+
+    sep = "=" * 100
+    print(f"\n{sep}")
+    print(f"Calcul températures hélices — {args.magnet}  (I = {args.current:.0f} A)")
+    print(sep)
+    if args.verbose:
+        print(df.T.to_string())
+    else:
+        summary = df[
+            [
+                "DT_paroi [°C]",
+                "DT_plane [°C]",
+                "DT_cyl [°C]",
+                "Tmax [°C]",
+                "Tmoy [°C]",
+                "T_moy_ro [°C]",
+                "Rapport IACS",
+            ]
+        ].copy()
+        for col in summary.columns:
+            if col == "Rapport IACS":
+                summary[col] = summary[col].map(lambda x: f"{x:.4f}" if x == x else "—")
+            else:
+                summary[col] = summary[col].map(lambda x: f"{x:.2f}" if x == x else "—")
+        print(summary.to_string())
+
+    print(f"\nTmax range: {df['Tmax [°C]'].min():.1f} … {df['Tmax [°C]'].max():.1f} °C")
+    print(f"Tmoy range: {df['Tmoy [°C]'].min():.1f} … {df['Tmoy [°C]'].max():.1f} °C")
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/demo_magnet_parts.py b/examples/demo_magnet_parts.py
new file mode 100644
index 0000000..05f86ac
--- /dev/null
+++ b/examples/demo_magnet_parts.py
@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+demo_magnet_parts.py — Parts of a magnet
+=========================================
+For a given magnet name, retrieve all associated parts and display their
+name, type, status, and material in a table.
+
+Requires GET /api/magnets/{id}/parts to be available in magnetdb.
+
+Usage
+-----
+    export MAGNETDB_API_SERVER=api.magnetdb-dev.local   # host only, no scheme
+    export MAGNETDB_API_KEY=<your-key>
+    python demo_magnet_parts.py --magnet M18110501
+
+Optional flags
+--------------
+    --server     override MAGNETDB_API_SERVER
+    --https      use HTTPS instead of HTTP (default: HTTP on port 8000)
+    --no-verify  skip TLS certificate verification (self-signed certs)
+    --debug      print raw API responses
+"""
+
+import os
+import sys
+import argparse
+import enum
+
+import requests
+import urllib3
+from rich.console import Console
+from rich.table import Table
+
+from python_magnetapi import utils
+from python_magnetapi.cli.parser import add_server_arguments
+
+
+class PartType(str, enum.Enum):
+    """Part types as defined in MagnetDB."""
+
+    HELIX = "helix"
+    BITTER = "bitter"
+    SUPRA = "supra"
+    RING = "ring"
+    SCREEN = "screen"
+    LEAD = "lead"
+
+
+def get_magnet_id(
+    session, web: str, headers: dict, magnet_name: str, debug: bool
+) -> int:
+    """Resolve a magnet name to its numeric id."""
+    ids = utils.get_list(session, web, headers=headers, mtype="magnet")
+    if magnet_name not in ids:
+        available = sorted(ids.keys())
+        print(
+            f"ERROR: magnet '{magnet_name}' not found.\n"
+            f"Available magnets ({len(available)}): {available}"
+        )
+        sys.exit(1)
+    return ids[magnet_name]
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Show parts of a magnet")
+    parser.add_argument("--magnet", required=True, help="Magnet name to inspect")
+    parser.add_argument(
+        "--type",
+        type=PartType,
+        choices=list(PartType),
+        default=None,
+        help="Filter parts by type (default: all types)",
+    )
+    add_server_arguments(parser)
+    args = parser.parse_args()
+
+    web = (
+        f"https://{args.server}" if args.https else f"http://{args.server}:{args.port}"
+    )
+    headers = {"Authorization": os.getenv("MAGNETDB_API_KEY", "")}
+
+    if args.no_verify:
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+    console = Console()
+
+    with requests.Session() as session:
+        session.verify = not args.no_verify
+        # health-check
+        r = session.get(f"{web}/api/magnets", headers=headers)
+        if r.status_code != 200:
+            console.print(
+                f"[red]ERROR:[/red] cannot reach {web} (status {r.status_code})"
+            )
+            sys.exit(1)
+
+        # resolve magnet name → id
+        magnet_id = get_magnet_id(session, web, headers, args.magnet, args.debug)
+        magnet = utils.get_object(
+            session, web, headers=headers, mtype="magnet", id=magnet_id
+        )
+
+        console.print(f"\n[bold]Magnet:[/bold] {magnet.get('name')}  (id={magnet_id})")
+        console.print()
+
+        # fetch parts via GET /api/magnets/{id}/parts
+        parts = utils.get_parts_for_magnet(session, web, headers, magnet_id)
+
+        if args.type is not None:
+            parts = [p for p in parts if p.get("type") == args.type.value]
+
+        if not parts:
+            console.print("[yellow]No parts found for this magnet.[/yellow]")
+            return
+
+        """
+        # an alternative way of doing things?
+        history = utils.get_history(
+            session, web, headers, magnet_id, mtype="magnet", otype="part"
+        )
+        for row in history:
+            print(f"raw magnet join-row: {row}")
+        print(f"history: {[row.get('part').get('id') for row in history]}")
+        """
+
+        title = f"Parts of magnet '{args.magnet}'"
+        if args.type is not None:
+            title += f" (type={args.type.value})"
+        table = Table(title=title)
+        table.add_column("Part name", style="cyan", no_wrap=True)
+        table.add_column("Type", style="white")
+        table.add_column("Status", style="white")
+        table.add_column("Material", style="green")
+
+        for part in parts:
+            # material_id is a direct FK column returned by model_serializer
+            material_id = utils.get_fk_id(part, "material")
+            if material_id is not None:
+                mat = utils.get_object(
+                    session,
+                    web,
+                    headers=headers,
+                    mtype="material",
+                    id=material_id,
+                )
+                material_name = (
+                    mat.get("name", str(material_id)) if mat else str(material_id)
+                )
+            else:
+                material_name = "—"
+
+            table.add_row(
+                part.get("name", "?"),
+                part.get("type", "?"),
+                part.get("status", "?"),
+                material_name,
+            )
+
+        console.print(table)
+        console.print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/demo_part_history.py b/examples/demo_part_history.py
new file mode 100644
index 0000000..c054370
--- /dev/null
+++ b/examples/demo_part_history.py
@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""
+Demonstrator 1 – Part history
+==============================
+For a given part name, retrieve:
+  • all magnets in which this part was ever installed
+  • all sites (experimental stations) in which those magnets were used
+Both lists are sorted chronologically by their commission date
+(``commissioned_at``) when available, falling back to ``created_at``.
+
+Usage
+-----
+    export MAGNETDB_API_SERVER=api.magnetdb-dev.local   # host only, no scheme
+    export MAGNETDB_API_KEY=<your-key>
+    python demo_part_history.py --part H22121601
+
+Optional flags
+--------------
+    --server  override MAGNETDB_API_SERVER
+    --https   use HTTPS instead of HTTP (default: HTTP on port 8000)
+    --debug   print raw API responses
+"""
+
+import os
+import sys
+import json
+import argparse
+from datetime import datetime
+
+import requests
+
+from python_magnetapi import utils
+from python_magnetapi.cli.parser import add_server_arguments
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_DATE_FIELDS = ("commissioned_at", "created_at", "updated_at")
+
+
+def _parse_date(obj: dict) -> datetime:
+    """Return the earliest parseable date from an API object dict."""
+    for field in _DATE_FIELDS:
+        raw = obj.get(field)
+        if raw:
+            try:
+                dt = datetime.fromisoformat(raw)
+                return dt.replace(tzinfo=None)
+            except ValueError:
+                continue
+    return datetime.min
+
+
+def _fmt(obj: dict) -> str:
+    """Human-readable one-liner for an object."""
+    dt = _parse_date(obj)
+    date_str = dt.strftime("%Y-%m-%d") if dt != datetime.min else "date unknown"
+    return f"  [{date_str}]  {obj.get('name', '?')}  (id={obj.get('id', '?')})"
+
+
+# ---------------------------------------------------------------------------
+# Core logic
+# ---------------------------------------------------------------------------
+
+
+def get_part_id(session, web: str, headers: dict, part_name: str, debug: bool) -> int:
+    """Resolve a part name to its numeric id."""
+    ids = utils.get_list(session, web, headers=headers, mtype="part")
+    if part_name not in ids:
+        available = sorted(ids.keys())
+        print(
+            f"ERROR: part '{part_name}' not found.\n"
+            f"Available parts ({len(available)}): {available}"
+        )
+        sys.exit(1)
+    return ids[part_name]
+
+
+def get_magnets_for_part(
+    session, web: str, headers: dict, part_id: int, debug: bool
+) -> list[dict]:
+    """
+    Return every magnet object that contains *part_id*.
+
+    The MagnetDB API exposes  GET /api/parts/{id}/magnets  which returns the
+    list of MagnetPart join-rows; each row carries ``magnet_id``.  We then
+    fetch the full magnet object to get its metadata (name, dates, …).
+    """
+    r = session.get(f"{web}/api/parts/{part_id}/magnets", headers=headers)
+    if r.status_code != 200:
+        print(f"WARNING: GET /api/parts/{part_id}/magnets → {r.status_code}")
+        if debug:
+            print(r.text)
+        return []
+
+    join_rows = r.json()
+    if debug:
+        print(
+            f"[debug] magnet join-rows: {json.dumps(join_rows, indent=2, default=str)}"
+        )
+
+    magnets = []
+    seen = set()
+    for row in join_rows["magnets"]:
+        mid = row.get("id")
+        if mid is None or mid in seen:
+            continue
+        seen.add(mid)
+        magnet = utils.get_object(session, web, headers=headers, mtype="magnet", id=mid)
+        if magnet:
+            magnets.append(magnet)
+
+    magnets.sort(key=_parse_date)
+    return magnets
+
+
+def get_sites_for_magnet(
+    session, web: str, headers: dict, magnet_id: int, debug: bool
+) -> list[dict]:
+    """
+    Return every site that hosted *magnet_id*, with full site objects.
+    """
+    join_rows = utils.get_history(
+        session, web, headers, magnet_id, mtype="magnet", otype="site"
+    )
+    if not join_rows:
+        return []
+
+    if debug:
+        print(f"[debug] site join-rows: {json.dumps(join_rows, indent=2, default=str)}")
+
+    sites = []
+    seen = set()
+    for row in join_rows:
+        # get_history returns raw rows; the site id may live under 'id' or 'site_id'
+        sid = row.get("site").get("id")  # or row.get("site_id")
+        if sid is None or sid in seen:
+            continue
+        seen.add(sid)
+        site = utils.get_object(session, web, headers=headers, mtype="site", id=sid)
+        if site:
+            sites.append(site)
+
+    sites.sort(key=_parse_date)
+    return sites
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Show part history (magnets & sites)")
+    parser.add_argument("--part", required=True, help="Part name to inspect")
+    add_server_arguments(parser)
+    args = parser.parse_args()
+
+    web = (
+        f"https://{args.server}" if args.https else f"http://{args.server}:{args.port}"
+    )
+    headers = {"Authorization": os.getenv("MAGNETDB_API_KEY", "")}
+
+    if args.no_verify:
+        import urllib3
+
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+    with requests.Session() as session:
+        session.verify = not args.no_verify
+        # --- health-check ---------------------------------------------------
+        r = session.get(f"{web}/api/magnets", headers=headers)
+        if r.status_code != 200:
+            print(f"ERROR: cannot reach {web} (status {r.status_code})")
+            sys.exit(1)
+
+        print(f"\n{'='*60}")
+        print(f"  Part history for: {args.part}")
+        print(f"  Server          : {web}")
+        print(f"{'='*60}\n")
+
+        # 1. Resolve part
+        part_id = get_part_id(session, web, headers, args.part, args.debug)
+        part = utils.get_object(session, web, headers=headers, mtype="part", id=part_id)
+        print(f"Part details")
+        print(f"  name   : {part.get('name')}")
+        print(f"  type   : {part.get('type')}")
+        print(f"  status : {part.get('status')}")
+        print()
+
+        # 2. Magnets that include this part
+        magnets = get_magnets_for_part(session, web, headers, part_id, args.debug)
+
+        print(f"Magnets containing this part  ({len(magnets)} found, sorted by date)")
+        print("-" * 60)
+        if magnets:
+            for m in magnets:
+                print(_fmt(m))
+        else:
+            print("  (none found)")
+        print()
+
+        # 3. Sites for each magnet (deduplicated, globally sorted)
+        all_sites: dict[int, dict] = {}
+        for m in magnets:
+            for site in get_sites_for_magnet(
+                session, web, headers, m["id"], args.debug
+            ):
+                all_sites[site["id"]] = site
+
+        sorted_sites = sorted(all_sites.values(), key=_parse_date)
+
+        print(
+            f"Sites that used this part (via its magnets)  ({len(sorted_sites)} found, sorted by date)"
+        )
+        print("-" * 60)
+        if sorted_sites:
+            for s in sorted_sites:
+                print(_fmt(s))
+        else:
+            print("  (none found)")
+        print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/demo_part_site_records.py b/examples/demo_part_site_records.py
new file mode 100644
index 0000000..8014f53
--- /dev/null
+++ b/examples/demo_part_site_records.py
@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""
+Demonstrator 2 – Part history with site details & records
+==========================================================
+Extends Demonstrator 1: for every site in which a part was used (via its
+magnets) also display:
+  • site metadata  (status, commission / decommission dates, description)
+  • names of every measurement record attached to that site
+
+All magnets and sites are sorted chronologically.
+
+Usage
+-----
+    export MAGNETDB_API_SERVER=api.magnetdb-dev.local
+    export MAGNETDB_API_KEY=<your-key>
+    python demo_part_site_records.py --part H22121601
+
+Optional flags
+--------------
+    --server   override MAGNETDB_API_SERVER
+    --https    use HTTPS (default: HTTP on port 8000)
+    --json     dump full site payloads as JSON at the end
+    --debug    print raw API responses
+"""
+
+import os
+import sys
+import json
+import argparse
+from datetime import datetime
+
+import requests
+
+from python_magnetapi import utils
+from python_magnetapi.cli.parser import add_server_arguments
+
+
+# ---------------------------------------------------------------------------
+# Date helpers  (shared with demo_part_history.py)
+# ---------------------------------------------------------------------------
+
+_DATE_FIELDS = ("commissioned_at", "decommissioned_at", "created_at", "updated_at")
+
+
+def _parse_date(obj: dict, field: str | None = None) -> datetime:
+    """Return a datetime parsed from *field* (or the first available date field)."""
+    fields = [field] if field else _DATE_FIELDS
+    for f in fields:
+        raw = obj.get(f)
+        if raw:
+            for fmt in ("%Y-%m-%dT%H:%M:%S.%f", "%Y-%m-%dT%H:%M:%S"):
+                try:
+                    return datetime.strptime(raw, fmt)
+                except ValueError:
+                    continue
+    return datetime.min
+
+
+def _date_str(obj: dict, field: str | None = None) -> str:
+    dt = _parse_date(obj, field)
+    return dt.strftime("%Y-%m-%d %H:%M") if dt != datetime.min else "—"
+
+
+# ---------------------------------------------------------------------------
+# Core helpers
+# ---------------------------------------------------------------------------
+
+def get_part_id(session, web, headers, part_name, debug) -> int:
+    ids = utils.get_list(session, web, headers=headers, mtype="part")
+    if part_name not in ids:
+        print(
+            f"ERROR: part '{part_name}' not found.\n"
+            f"Available: {sorted(ids.keys())}"
+        )
+        sys.exit(1)
+    return ids[part_name]
+
+
+def get_magnets_for_part(session, web, headers, part_id, debug) -> list[dict]:
+    r = session.get(f"{web}/api/parts/{part_id}/magnets", headers=headers)
+    if r.status_code != 200:
+        if debug:
+            print(f"[debug] GET /api/parts/{part_id}/magnets → {r.status_code}: {r.text}")
+        return []
+
+    join_rows = r.json()
+    magnets, seen = [], set()
+    for row in join_rows:
+        mid = row.get("magnet_id")
+        if mid and mid not in seen:
+            seen.add(mid)
+            obj = utils.get_object(
+                session, web, headers=headers, mtype="magnet", id=mid
+            )
+            if obj:
+                magnets.append(obj)
+
+    return sorted(magnets, key=_parse_date)
+
+
+def get_sites_for_magnet(session, web, headers, magnet_id, debug) -> list[dict]:
+    join_rows = utils.get_history(
+        session, web, headers, magnet_id, mtype="magnet", otype="site"
+    )
+    if not join_rows:
+        return []
+
+    sites, seen = [], set()
+    for row in join_rows:
+        sid = row.get("id") or row.get("site_id")
+        if sid and sid not in seen:
+            seen.add(sid)
+            obj = utils.get_object(
+                session, web, headers=headers, mtype="site", id=sid
+            )
+            if obj:
+                sites.append(obj)
+
+    return sorted(sites, key=_parse_date)
+
+
+def get_records_for_site(session, web, headers, site_id, debug) -> list[dict]:
+    """
+    Return all record objects attached to *site_id*.
+
+    The API exposes  GET /api/sites/{id}/records.
+    Each record has at minimum: id, name, created_at, attachment_id.
+    """
+    records = utils.get_history(
+        session, web, headers, site_id, mtype="site", otype="record"
+    )
+    if not records:
+        return []
+    return sorted(records, key=lambda r: _parse_date(r, "created_at"))
+
+
+# ---------------------------------------------------------------------------
+# Pretty printers
+# ---------------------------------------------------------------------------
+
+_SEP  = "─" * 70
+_SEP2 = "·" * 60
+
+def print_site_card(site: dict, records: list[dict], magnet_names: list[str]) -> None:
+    """Print a formatted card for one site with its records."""
+    print(f"\n  {'▶':>2}  {site.get('name', '?')}   (id={site.get('id', '?')})")
+    print(f"       status        : {site.get('status', '—')}")
+    print(f"       description   : {site.get('description') or '—'}")
+    print(f"       commissioned  : {_date_str(site, 'commissioned_at')}")
+    print(f"       decommissioned: {_date_str(site, 'decommissioned_at')}")
+    print(f"       created       : {_date_str(site, 'created_at')}")
+
+    if magnet_names:
+        print(f"       magnets       : {', '.join(magnet_names)}")
+
+    if records:
+        print(f"       records ({len(records):>3}) :")
+        for rec in records:
+            rdate = _date_str(rec, "created_at")
+            print(f"                        [{rdate}]  {rec.get('name', '?')}")
+    else:
+        print(f"       records       : (none)")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Show part history with full site data and associated records"
+    )
+    parser.add_argument("--part",   required=True, help="Part name to inspect")
+    parser.add_argument("--json",   action="store_true", help="Dump raw site JSON at end")
+    add_server_arguments(parser)
+    args = parser.parse_args()
+
+    web = (
+        f"https://{args.server}"
+        if args.https
+        else f"http://{args.server}:{args.port}"
+    )
+    headers = {"Authorization": os.getenv("MAGNETDB_API_KEY", "")}
+
+    if args.no_verify:
+        import urllib3
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+    with requests.Session() as session:
+        session.verify = not args.no_verify
+        # health-check
+        r = session.get(f"{web}/api/magnets", headers=headers)
+        if r.status_code != 200:
+            print(f"ERROR: cannot reach {web} (status {r.status_code})")
+            sys.exit(1)
+
+        # ── Banner ────────────────────────────────────────────────────────
+        print(f"\n{'='*70}")
+        print(f"  Part history + site details + records")
+        print(f"  Part  : {args.part}")
+        print(f"  Server: {web}")
+        print(f"{'='*70}")
+
+        # ── 1. Part ───────────────────────────────────────────────────────
+        part_id = get_part_id(session, web, headers, args.part, args.debug)
+        part = utils.get_object(
+            session, web, headers=headers, mtype="part", id=part_id
+        )
+        print(f"\nPart details")
+        print(f"  name     : {part.get('name')}")
+        print(f"  type     : {part.get('type')}")
+        print(f"  status   : {part.get('status')}")
+        print(f"  ref      : {part.get('design_office_reference', '—')}")
+        print(f"  created  : {_date_str(part, 'created_at')}")
+
+        # ── 2. Magnets ────────────────────────────────────────────────────
+        magnets = get_magnets_for_part(session, web, headers, part_id, args.debug)
+        print(f"\n{_SEP}")
+        print(f"Magnets containing this part  ({len(magnets)}, sorted by date)")
+        print(_SEP)
+        for m in magnets:
+            print(f"  [{_date_str(m, 'created_at')}]  {m.get('name')}  (id={m.get('id')})")
+        if not magnets:
+            print("  (none found)")
+
+        # ── 3. Sites (deduplicated) ───────────────────────────────────────
+        # Build: site_id → (site_obj, [magnet_names_that_link_to_it])
+        site_map: dict[int, tuple[dict, list[str]]] = {}
+        for m in magnets:
+            for site in get_sites_for_magnet(session, web, headers, m["id"], args.debug):
+                sid = site["id"]
+                if sid not in site_map:
+                    site_map[sid] = (site, [])
+                site_map[sid][1].append(m["name"])
+
+        sorted_sites = sorted(
+            site_map.values(),
+            key=lambda pair: _parse_date(pair[0]),
+        )
+
+        print(f"\n{_SEP}")
+        print(
+            f"Sites that used this part (via its magnets)  "
+            f"({len(sorted_sites)}, sorted by date)"
+        )
+        print(_SEP)
+
+        raw_sites = []
+        for site_obj, mnames in sorted_sites:
+            records = get_records_for_site(
+                session, web, headers, site_obj["id"], args.debug
+            )
+            print_site_card(site_obj, records, mnames)
+            raw_sites.append(site_obj)
+
+        if not sorted_sites:
+            print("  (none found)")
+
+        # ── 4. Optional JSON dump ─────────────────────────────────────────
+        if args.json and raw_sites:
+            print(f"\n{_SEP}")
+            print("Raw site JSON")
+            print(_SEP)
+            print(json.dumps(raw_sites, indent=2, default=str))
+
+        print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/demo_site_magnets.py b/examples/demo_site_magnets.py
new file mode 100644
index 0000000..eaa7fd2
--- /dev/null
+++ b/examples/demo_site_magnets.py
@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""
+demo_site_magnets.py — Magnets of a site
+=========================================
+For a given site name, retrieve all associated magnets and display their
+name, status, and number of parts in a table.
+
+Requires GET /api/sites/{id}/magnets to be available in magnetdb.
+
+Usage
+-----
+    export MAGNETDB_API_SERVER=api.magnetdb-dev.local   # host only, no scheme
+    export MAGNETDB_API_KEY=<your-key>
+    python demo_site_magnets.py --site M10_M19020601
+
+Optional flags
+--------------
+    --server     override MAGNETDB_API_SERVER
+    --https      use HTTPS instead of HTTP (default: HTTP on port 8000)
+    --no-verify  skip TLS certificate verification (self-signed certs)
+    --debug      print raw API responses
+"""
+
+import os
+import sys
+import argparse
+
+import requests
+import urllib3
+from rich.console import Console
+from rich.table import Table
+
+from python_magnetapi import utils
+from python_magnetapi.cli.parser import add_server_arguments
+
+
+def get_site_id(
+    session, web: str, headers: dict, site_name: str, debug: bool
+) -> int:
+    """Resolve a site name to its numeric id."""
+    ids = utils.get_list(session, web, headers=headers, mtype="site")
+    if site_name not in ids:
+        available = sorted(ids.keys())
+        print(
+            f"ERROR: site '{site_name}' not found.\n"
+            f"Available sites ({len(available)}): {available}"
+        )
+        sys.exit(1)
+    return ids[site_name]
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Show magnets of a site")
+    parser.add_argument("--site", required=True, help="Site name to inspect")
+    add_server_arguments(parser)
+    args = parser.parse_args()
+
+    web = (
+        f"https://{args.server}" if args.https else f"http://{args.server}:{args.port}"
+    )
+    headers = {"Authorization": os.getenv("MAGNETDB_API_KEY", "")}
+
+    if args.no_verify:
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+    console = Console()
+
+    with requests.Session() as session:
+        session.verify = not args.no_verify
+        # health-check
+        r = session.get(f"{web}/api/sites", headers=headers)
+        if r.status_code != 200:
+            console.print(
+                f"[red]ERROR:[/red] cannot reach {web} (status {r.status_code})"
+            )
+            sys.exit(1)
+
+        # resolve site name → id
+        site_id = get_site_id(session, web, headers, args.site, args.debug)
+        site = utils.get_object(
+            session, web, headers=headers, mtype="site", id=site_id
+        )
+
+        console.print(f"\n[bold]Site:[/bold] {site.get('name')}  (id={site_id})")
+        console.print()
+
+        # fetch magnets via GET /api/sites/{id}/magnets
+        magnets = utils.get_magnets_for_site(session, web, headers, site_id)
+
+        if args.debug:
+            history = utils.get_history(
+                session, web, headers, site_id, mtype="site", otype="magnet"
+            )
+            for row in history:
+                print(f"raw site join-row: {row}")
+
+        if not magnets:
+            console.print("[yellow]No magnets found for this site.[/yellow]")
+            return
+
+        table = Table(title=f"Magnets of site '{args.site}'")
+        table.add_column("Magnet name", style="cyan", no_wrap=True)
+        table.add_column("Status", style="white")
+        table.add_column("# Parts", style="green", justify="right")
+
+        for magnet in magnets:
+            parts = utils.get_parts_for_magnet(session, web, headers, magnet["id"])
+            table.add_row(
+                magnet.get("name", "?"),
+                magnet.get("status", "?"),
+                str(len(parts)),
+            )
+
+        console.print(table)
+        console.print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/prompts/CLI_REFACTORING_TASK_PROMPT.md b/prompts/CLI_REFACTORING_TASK_PROMPT.md
new file mode 100644
index 0000000..ac8306b
--- /dev/null
+++ b/prompts/CLI_REFACTORING_TASK_PROMPT.md
@@ -0,0 +1,1471 @@
+# CLI Module Refactoring
+
+## Task Overview
+
+**Priority**: Tier 2 (Code Quality & Maintainability)
+**Status**: ✅ COMPLETE (merged via PR #13)
+**Original Size**: 684 lines (single monolithic function)
+**Result**: Modular `python_magnetapi/cli/` package — context, base, parser, per-command handlers
+**Breaking Changes**: No (CLI interface unchanged; `python -m python_magnetapi.cli` also supported)
+
+
+## Current State Analysis
+
+### Problems Identified
+
+1. ❌ **Monolithic main() function** - 684 lines, all logic in one function
+2. ❌ **Mixed concerns** - Argument parsing, validation, business logic, error handling, output all mixed
+3. ❌ **Code duplication** - Similar patterns repeated for each command (get ids, validate name, handle errors)
+4. ❌ **Hard to test** - No way to test individual command handlers
+5. ❌ **Poor readability** - Long if/elif chains, deeply nested blocks
+6. ❌ **No separation of concerns** - HTTP setup, argument parsing, command execution all in one function
+7. ❌ **Difficult to extend** - Adding new commands requires modifying the massive main() function
+8. ❌ **No error context** - Generic RuntimeError scattered throughout
+
+### Current Structure
+
+```
+cli.py (684 lines)
+├── main()
+    ├── Argument parser setup (lines 21-234)
+    │   ├── Global args (server, port, debug, https)
+    │   ├── list subcommand args
+    │   ├── view subcommand args
+    │   ├── create subcommand args
+    │   ├── delete subcommand args
+    │   ├── setup subcommand args
+    │   ├── run subcommand args
+    │   └── compute subcommand args
+    │
+    ├── HTTP setup (lines 235-251)
+    │   ├── Build web URL
+    │   ├── Configure headers
+    │   └── Setup session/verify
+    │
+    └── Command execution (lines 252-682)
+        ├── if args.command == "list": (lines 268-273)
+        ├── if args.command == "view": (lines 274-291)
+        ├── if args.command == "create": (lines 292-330)
+        ├── if args.command == "delete": (lines 331-348)
+        ├── if args.command == "setup": (lines 349-505)
+        ├── if args.command == "run": (lines 506-577)
+        ├── if args.command == "compute": (lines 578-678)
+        └── if args.command == "post": (lines 679-680)
+```
+
+### Commands Implemented
+
+1. **list** - List objects of a given type
+2. **view** - View details of a specific object
+3. **create** - Create new object from JSON/file
+4. **delete** - Delete object by name
+5. **setup** - Setup simulation for magnet/site
+6. **run** - Run simulation
+7. **compute** - Compute derived quantities (inductances, flow_params, hoop_stress)
+8. **process** (post) - Not implemented
+
+### Code Duplication Examples
+
+**Pattern 1: Get object list and validate name**
+```python
+# Repeated ~8 times throughout the code
+ids = utils.get_list(s, web, headers=headers, mtype=otype, debug=args.debug)
+if args.name in ids:
+    # do something
+else:
+    raise RuntimeError(f"cannot found {args.name} in {args.mtype.upper()}")
+```
+
+**Pattern 2: Setup HTTP session**
+```python
+# Done inline at start of command execution
+with requests.Session() as s:
+    # verify setup logic
+    # command execution
+```
+
+**Pattern 3: Type checking for commands**
+```python
+# Repeated for many subcommands
+if otype not in ["magnet", "site"]:
+    raise RuntimeError(f"unexpected type {args.mtype} in {args.command} subcommand")
+```
+
+---
+
+## Implementation Plan
+
+### Design Goals
+
+1. **Separation of Concerns** - Split parsing, validation, execution, output
+2. **Testability** - Each command handler independently testable
+3. **Maintainability** - Easy to add new commands or modify existing ones
+4. **No Breaking Changes** - CLI interface remains identical
+5. **Type Safety** - Add type hints throughout
+6. **Error Handling** - Use custom exceptions (after exception framework is complete)
+7. **DRY Principle** - Eliminate code duplication
+
+### Target Architecture
+
+```
+python_magnetapi/
+├── cli.py                    # Main entry point (50-100 lines)
+├── cli/
+│   ├── __init__.py          # Export public API
+│   ├── parser.py            # Argument parser configuration (150 lines)
+│   ├── context.py           # CLI context and configuration (50 lines)
+│   ├── base.py              # Base command handler class (100 lines)
+│   └── commands/
+│       ├── __init__.py      # Command registry
+│       ├── list.py          # ListCommand handler (~50 lines)
+│       ├── view.py          # ViewCommand handler (~50 lines)
+│       ├── create.py        # CreateCommand handler (~80 lines)
+│       ├── delete.py        # DeleteCommand handler (~50 lines)
+│       ├── setup.py         # SetupCommand handler (~150 lines)
+│       ├── run.py           # RunCommand handler (~80 lines)
+│       ├── compute.py       # ComputeCommand handler (~150 lines)
+│       └── process.py       # ProcessCommand handler (~30 lines)
+```
+
+---
+
+## Phase 1: Foundation and Infrastructure
+
+### Step 1.1: Create CLI Context Class
+
+Create `python_magnetapi/cli/context.py`:
+
+```python
+"""CLI context and configuration."""
+
+from dataclasses import dataclass
+from typing import Optional
+import requests
+
+
+@dataclass
+class CLIContext:
+    """Context passed to all command handlers.
+    
+    Attributes:
+        server: API server hostname
+        port: API port number
+        api_key: API authentication key
+        debug: Debug mode flag
+        https: Use HTTPS flag
+        session: Requests session (initialized later)
+        headers: HTTP headers for API requests
+        web: Full API URL (computed)
+    """
+    
+    server: str
+    port: int
+    api_key: str
+    debug: bool = False
+    https: bool = False
+    session: Optional[requests.Session] = None
+    
+    @property
+    def headers(self) -> dict:
+        """HTTP headers for API authentication."""
+        return {"Authorization": self.api_key}
+    
+    @property
+    def web(self) -> str:
+        """Full API base URL."""
+        protocol = "https" if self.https else "http"
+        return f"{protocol}://{self.server}:{self.port}"
+    
+    @property
+    def verify_ssl(self) -> bool:
+        """Whether to verify SSL certificates."""
+        return not self.https  # Don't verify if using custom HTTPS
+    
+    def __enter__(self):
+        """Context manager entry - create session."""
+        self.session = requests.Session()
+        self.session.verify = self.verify_ssl
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - close session."""
+        if self.session:
+            self.session.close()
+```
+
+### Step 1.2: Create Base Command Handler
+
+Create `python_magnetapi/cli/base.py`:
+
+```python
+"""Base command handler class."""
+
+from abc import ABC, abstractmethod
+import argparse
+from typing import Optional, List, Dict
+from rich.console import Console
+
+from .context import CLIContext
+from .. import utils
+
+
+class BaseCommand(ABC):
+    """Base class for all CLI command handlers.
+    
+    Subclasses should implement:
+        - name: Command name
+        - help: Command help text
+        - configure_parser(): Add command-specific arguments
+        - execute(): Execute command logic
+    """
+    
+    name: str = ""
+    help: str = ""
+    
+    def __init__(self, console: Optional[Console] = None):
+        """Initialize command handler.
+        
+        Args:
+            console: Rich console for output (created if not provided)
+        """
+        self.console = console or Console()
+    
+    @abstractmethod
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure argument parser for this command.
+        
+        Args:
+            parser: Subparser for this command
+        """
+        pass
+    
+    @abstractmethod
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute the command.
+        
+        Args:
+            args: Parsed command-line arguments
+            context: CLI context with session and configuration
+            
+        Returns:
+            Exit code (0 for success, non-zero for error)
+        """
+        pass
+    
+    # Helper methods for common operations
+    
+    def get_object_list(
+        self,
+        context: CLIContext,
+        mtype: str
+    ) -> Dict[str, int]:
+        """Get list of objects by type.
+        
+        Args:
+            context: CLI context
+            mtype: Resource type (material, part, magnet, etc.)
+            
+        Returns:
+            Dictionary mapping names to IDs
+        """
+        return utils.get_list(
+            context.session,
+            context.web,
+            headers=context.headers,
+            mtype=mtype,
+            debug=context.debug
+        )
+    
+    def get_object_by_name(
+        self,
+        context: CLIContext,
+        mtype: str,
+        name: str
+    ) -> Optional[dict]:
+        """Get object by name.
+        
+        Args:
+            context: CLI context
+            mtype: Resource type
+            name: Object name
+            
+        Returns:
+            Object data dictionary, or None if not found
+            
+        Raises:
+            NotFoundError: If object doesn't exist
+        """
+        ids = self.get_object_list(context, mtype)
+        
+        if name not in ids:
+            raise NotFoundError(
+                f"{mtype} '{name}' not found",
+                resource_type=mtype,
+                resource_name=name,
+                available=list(ids.keys())
+            )
+        
+        return utils.get_object(
+            context.session,
+            context.web,
+            context.headers,
+            ids[name],
+            mtype,
+            debug=context.debug
+        )
+    
+    def validate_resource_type(
+        self,
+        mtype: str,
+        allowed_types: List[str],
+        command_name: Optional[str] = None
+    ) -> None:
+        """Validate that resource type is allowed for this command.
+        
+        Args:
+            mtype: Resource type to validate
+            allowed_types: List of allowed types
+            command_name: Command name for error message
+            
+        Raises:
+            InvalidDataError: If type is not allowed
+        """
+        if mtype not in allowed_types:
+            cmd = command_name or self.name
+            raise InvalidDataError(
+                f"Command '{cmd}' does not support resource type '{mtype}'",
+                field="mtype",
+                value=mtype,
+                allowed=allowed_types
+            )
+```
+
+### Step 1.3: Create Command Registry
+
+Create `python_magnetapi/cli/commands/__init__.py`:
+
+```python
+"""Command registry and imports."""
+
+from typing import Dict, Type
+from ..base import BaseCommand
+
+# Import all command handlers
+from .list import ListCommand
+from .view import ViewCommand
+from .create import CreateCommand
+from .delete import DeleteCommand
+from .setup import SetupCommand
+from .run import RunCommand
+from .compute import ComputeCommand
+from .process import ProcessCommand
+
+
+# Command registry
+COMMANDS: Dict[str, Type[BaseCommand]] = {
+    "list": ListCommand,
+    "view": ViewCommand,
+    "create": CreateCommand,
+    "delete": DeleteCommand,
+    "setup": SetupCommand,
+    "run": RunCommand,
+    "compute": ComputeCommand,
+    "process": ProcessCommand,
+}
+
+
+def get_command(name: str) -> Type[BaseCommand]:
+    """Get command class by name.
+    
+    Args:
+        name: Command name
+        
+    Returns:
+        Command class
+        
+    Raises:
+        KeyError: If command not found
+    """
+    return COMMANDS[name]
+```
+
+---
+
+## Phase 2: Implement Command Handlers
+
+### Step 2.1: ListCommand Handler
+
+Create `python_magnetapi/cli/commands/list.py`:
+
+```python
+"""List command handler."""
+
+import argparse
+from typing import Optional
+from rich.table import Table
+
+from ..base import BaseCommand
+from ..context import CLIContext
+
+
+class ListCommand(BaseCommand):
+    """List objects of a given type."""
+    
+    name = "list"
+    help = "List objects in MagnetDB"
+    
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure list command arguments."""
+        parser.add_argument(
+            "--mtype",
+            help="Object type to list",
+            type=str,
+            choices=[
+                "material",
+                "part",
+                "magnet",
+                "site",
+                "record",
+                "server",
+                "simulation",
+            ],
+            default="magnet",
+        )
+    
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute list command.
+        
+        Args:
+            args: Parsed arguments
+            context: CLI context
+            
+        Returns:
+            Exit code (0 for success)
+        """
+        # Get object list
+        ids = self.get_object_list(context, args.mtype)
+        
+        # Display results
+        self.console.print(
+            f"\n[bold]{args.mtype.upper()}:[/bold] found {len(ids)} items\n"
+        )
+        
+        # Create table
+        table = Table(show_header=True, header_style="bold magenta")
+        table.add_column("Name", style="cyan")
+        table.add_column("ID", style="green")
+        
+        for name, id in sorted(ids.items()):
+            table.add_row(name, str(id))
+        
+        self.console.print(table)
+        
+        return 0
+```
+
+### Step 2.2: ViewCommand Handler
+
+Create `python_magnetapi/cli/commands/view.py`:
+
+```python
+"""View command handler."""
+
+import argparse
+import json
+from rich.syntax import Syntax
+
+from ..base import BaseCommand
+from ..context import CLIContext
+
+
+class ViewCommand(BaseCommand):
+    """View details of a specific object."""
+    
+    name = "view"
+    help = "View object details"
+    
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure view command arguments."""
+        parser.add_argument(
+            "--mtype",
+            help="Object type to view",
+            type=str,
+            choices=[
+                "material",
+                "part",
+                "magnet",
+                "site",
+                "record",
+                "server",
+                "simulation",
+            ],
+            default="magnet",
+        )
+        parser.add_argument(
+            "--name",
+            help="Object name",
+            type=str,
+            required=True,
+        )
+    
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute view command.
+        
+        Args:
+            args: Parsed arguments
+            context: CLI context
+            
+        Returns:
+            Exit code (0 for success)
+        """
+        # Get object by name
+        obj = self.get_object_by_name(context, args.mtype, args.name)
+        
+        # Display as formatted JSON
+        json_str = json.dumps(obj, indent=2)
+        syntax = Syntax(json_str, "json", theme="monokai", line_numbers=True)
+        
+        self.console.print(f"\n[bold]{args.mtype.upper()}:[/bold] {args.name}\n")
+        self.console.print(syntax)
+        
+        return 0
+```
+
+### Step 2.3: CreateCommand Handler
+
+Create `python_magnetapi/cli/commands/create.py`:
+
+```python
+"""Create command handler."""
+
+import argparse
+import json
+from typing import Dict, Any
+
+from ..base import BaseCommand
+from ..context import CLIContext
+from ... import part, magnet, site, record, material
+
+
+class CreateCommand(BaseCommand):
+    """Create new object from JSON data or file."""
+    
+    name = "create"
+    help = "Create new object"
+    
+    # Map resource types to creation functions
+    CREATORS = {
+        "material": material.create,
+        "part": part.create,
+        "magnet": magnet.create,
+        "site": site.create,
+        "record": record.create,
+    }
+    
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure create command arguments."""
+        parser.add_argument(
+            "--mtype",
+            help="Object type to create",
+            type=str,
+            choices=[
+                "material",
+                "part",
+                "magnet",
+                "site",
+                "record",
+                "server",
+                "simulation",
+            ],
+            default="magnet",
+        )
+        
+        # Mutually exclusive data sources
+        data_group = parser.add_mutually_exclusive_group(required=True)
+        data_group.add_argument(
+            "--data",
+            help="JSON data",
+            type=json.loads,
+        )
+        data_group.add_argument(
+            "--file",
+            help="JSON file path",
+            type=str,
+        )
+    
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute create command.
+        
+        Args:
+            args: Parsed arguments
+            context: CLI context
+            
+        Returns:
+            Exit code (0 for success)
+        """
+        # Load data from file or command line
+        data: Dict[str, Any] = {}
+        if args.file:
+            with open(args.file, "r") as f:
+                data = json.load(f)
+        else:
+            data = args.data
+        
+        # Validate resource type
+        if args.mtype not in self.CREATORS:
+            self.console.print(
+                f"[yellow]Warning:[/yellow] No specialized creator for {args.mtype}, "
+                f"using generic creation"
+            )
+            # Use generic utils.create_object
+            from ... import utils
+            obj_id = utils.create_object(
+                context.session,
+                context.web,
+                context.headers,
+                mtype=args.mtype,
+                data=data,
+                debug=context.debug,
+            )
+        else:
+            # Use specialized creator
+            creator = self.CREATORS[args.mtype]
+            obj_id = creator(
+                context.session,
+                context.web,
+                context.headers,
+                data=data,
+                debug=context.debug,
+            )
+        
+        # Display success
+        self.console.print(
+            f"\n[green]✓[/green] Created {args.mtype} with ID: [bold]{obj_id}[/bold]"
+        )
+        
+        return 0
+```
+
+### Step 2.4: DeleteCommand Handler
+
+Create `python_magnetapi/cli/commands/delete.py`:
+
+```python
+"""Delete command handler."""
+
+import argparse
+
+from ..base import BaseCommand
+from ..context import CLIContext
+from ... import utils
+
+
+class DeleteCommand(BaseCommand):
+    """Delete object by name."""
+    
+    name = "delete"
+    help = "Delete object"
+    
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure delete command arguments."""
+        parser.add_argument(
+            "--mtype",
+            help="Object type to delete",
+            type=str,
+            choices=[
+                "material",
+                "part",
+                "magnet",
+                "site",
+                "record",
+                "server",
+                "simulation",
+            ],
+            default="magnet",
+        )
+        parser.add_argument(
+            "--name",
+            help="Object name",
+            type=str,
+            required=True,
+        )
+        parser.add_argument(
+            "--force",
+            help="Skip confirmation",
+            action="store_true",
+        )
+    
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute delete command.
+        
+        Args:
+            args: Parsed arguments
+            context: CLI context
+            
+        Returns:
+            Exit code (0 for success)
+        """
+        # Get object ID
+        ids = self.get_object_list(context, args.mtype)
+        
+        if args.name not in ids:
+            self.console.print(
+                f"[red]Error:[/red] {args.mtype} '{args.name}' not found"
+            )
+            return 1
+        
+        obj_id = ids[args.name]
+        
+        # Confirmation prompt (unless --force)
+        if not args.force:
+            response = self.console.input(
+                f"[yellow]Delete {args.mtype} '{args.name}' (ID: {obj_id})? [y/N]:[/yellow] "
+            )
+            if response.lower() not in ["y", "yes"]:
+                self.console.print("[dim]Cancelled[/dim]")
+                return 0
+        
+        # Delete object
+        utils.del_object(
+            context.session,
+            context.web,
+            context.headers,
+            obj_id,
+            args.mtype,
+            debug=context.debug,
+        )
+        
+        self.console.print(
+            f"[green]✓[/green] Deleted {args.mtype} '{args.name}' (ID: {obj_id})"
+        )
+        
+        return 0
+```
+
+### Step 2.5: SetupCommand Handler
+
+Create `python_magnetapi/cli/commands/setup.py`:
+
+```python
+"""Setup command handler."""
+
+import argparse
+from typing import List
+
+from ..base import BaseCommand
+from ..context import CLIContext
+
+
+class SetupCommand(BaseCommand):
+    """Setup simulation for magnet or site."""
+    
+    name = "setup"
+    help = "Setup simulation"
+    
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure setup command arguments."""
+        parser.add_argument(
+            "--mtype",
+            help="Object type",
+            type=str,
+            choices=["magnet", "site"],
+            default="magnet",
+        )
+        parser.add_argument(
+            "--name",
+            help="Object name",
+            type=str,
+            required=True,
+        )
+        parser.add_argument(
+            "--current",
+            help="Requested current (default: 31kA)",
+            nargs="+",
+            metavar="Current",
+            type=float,
+            default=[31.0e3],
+        )
+        parser.add_argument(
+            "--geometry",
+            help="Geometry type",
+            type=str,
+            choices=["Axi", "3D"],
+            default="Axi",
+        )
+        parser.add_argument(
+            "--static",
+            help="Enable static mode",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--nonlinear",
+            help="Enable nonlinear mode",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--method",
+            help="Method",
+            type=str,
+            default="cfpdes",
+        )
+        parser.add_argument(
+            "--model",
+            help="Model",
+            type=str,
+            default="thmagel_hcurl",
+        )
+        parser.add_argument(
+            "--cooling",
+            help="Cooling mode",
+            type=str,
+            choices=["mean", "meanH", "grad", "gradH", "gradHZ"],
+            default="meanH",
+        )
+        parser.add_argument(
+            "--wd",
+            help="Working directory",
+            type=str,
+            default=".",
+        )
+    
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute setup command.
+        
+        Args:
+            args: Parsed arguments
+            context: CLI context
+            
+        Returns:
+            Exit code (0 for success)
+        """
+        # Validate resource type
+        self.validate_resource_type(args.mtype, ["magnet", "site"])
+        
+        # Get object
+        obj = self.get_object_by_name(context, args.mtype, args.name)
+        
+        # Import appropriate setup module
+        if args.mtype == "magnet":
+            from ... import magnet
+            simulation_id = magnet.setup(
+                context.session,
+                context.web,
+                context.headers,
+                obj["id"],
+                currents=args.current,
+                geometry=args.geometry,
+                static=args.static,
+                nonlinear=args.nonlinear,
+                method=args.method,
+                model=args.model,
+                cooling=args.cooling,
+                workdir=args.wd,
+                debug=context.debug,
+            )
+        else:  # site
+            from ... import site
+            simulation_id = site.setup(
+                context.session,
+                context.web,
+                context.headers,
+                obj["id"],
+                currents=args.current,
+                geometry=args.geometry,
+                static=args.static,
+                nonlinear=args.nonlinear,
+                method=args.method,
+                model=args.model,
+                cooling=args.cooling,
+                workdir=args.wd,
+                debug=context.debug,
+            )
+        
+        self.console.print(
+            f"\n[green]✓[/green] Setup complete for {args.mtype} '{args.name}'"
+        )
+        self.console.print(f"  Simulation ID: [bold]{simulation_id}[/bold]")
+        self.console.print(f"  Working directory: {args.wd}")
+        
+        return 0
+```
+
+### Step 2.6: ComputeCommand Handler
+
+Create `python_magnetapi/cli/commands/compute.py`:
+
+```python
+"""Compute command handler."""
+
+import argparse
+
+from ..base import BaseCommand
+from ..context import CLIContext
+
+
+class ComputeCommand(BaseCommand):
+    """Compute derived quantities."""
+    
+    name = "compute"
+    help = "Compute inductances, flow parameters, or hoop stress"
+    
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure compute command arguments."""
+        parser.add_argument(
+            "--mtype",
+            help="Object type",
+            type=str,
+            choices=["part", "magnet", "site", "record"],
+            default="magnet",
+        )
+        parser.add_argument(
+            "--name",
+            help="Object name",
+            type=str,
+            required=True,
+        )
+        parser.add_argument(
+            "--inductances",
+            help="Compute self and mutual inductances",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--flow_params",
+            help="Compute flow parameters",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--hoop_stress",
+            help="Compute hoop stress history",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--samples",
+            help="Number of samples",
+            type=int,
+            default=20,
+        )
+    
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute compute command.
+        
+        Args:
+            args: Parsed arguments
+            context: CLI context
+            
+        Returns:
+            Exit code (0 for success)
+        """
+        # Get object
+        obj = self.get_object_by_name(context, args.mtype, args.name)
+        obj_id = obj["id"]
+        
+        # Compute inductances
+        if args.inductances:
+            self._compute_inductances(args, context, obj_id)
+        
+        # Compute flow parameters
+        if args.flow_params:
+            self._compute_flow_params(args, context, obj_id)
+        
+        # Compute hoop stress
+        if args.hoop_stress:
+            self._compute_hoop_stress(args, context, obj_id)
+        
+        # If no computation requested, show help
+        if not (args.inductances or args.flow_params or args.hoop_stress):
+            self.console.print(
+                "[yellow]No computation requested. Use --inductances, "
+                "--flow_params, or --hoop_stress[/yellow]"
+            )
+            return 1
+        
+        return 0
+    
+    def _compute_inductances(
+        self,
+        args: argparse.Namespace,
+        context: CLIContext,
+        obj_id: int
+    ) -> None:
+        """Compute inductances."""
+        from ... import inductances
+        
+        self.console.print(f"\n[bold]Computing inductances...[/bold]")
+        
+        inductances.compute(
+            context.session,
+            context.web,
+            context.headers,
+            oid=obj_id,
+            mtype=args.mtype,
+            debug=context.debug,
+        )
+        
+        self.console.print("[green]✓[/green] Inductances computed")
+    
+    def _compute_flow_params(
+        self,
+        args: argparse.Namespace,
+        context: CLIContext,
+        obj_id: int
+    ) -> None:
+        """Compute flow parameters."""
+        # Validate type
+        if args.mtype != "magnet":
+            raise InvalidDataError(
+                "Flow parameters can only be computed for magnets",
+                field="mtype",
+                value=args.mtype,
+                expected="magnet"
+            )
+        
+        from ... import flow_params
+        
+        self.console.print(f"\n[bold]Computing flow parameters...[/bold]")
+        
+        flow_params.compute(
+            context.session,
+            context.web,
+            context.headers,
+            oid=obj_id,
+            samples=args.samples,
+            debug=context.debug,
+        )
+        
+        self.console.print("[green]✓[/green] Flow parameters computed")
+    
+    def _compute_hoop_stress(
+        self,
+        args: argparse.Namespace,
+        context: CLIContext,
+        obj_id: int
+    ) -> None:
+        """Compute hoop stress."""
+        # Validate type
+        if args.mtype != "part":
+            raise InvalidDataError(
+                "Hoop stress can only be computed for parts",
+                field="mtype",
+                value=args.mtype,
+                expected="part"
+            )
+        
+        from ... import hoop_stress
+        
+        self.console.print(f"\n[bold]Computing hoop stress...[/bold]")
+        
+        hoop_stress.compute(
+            context.session,
+            context.web,
+            context.headers,
+            mtype=args.mtype,
+            oid=obj_id,
+            debug=context.debug,
+        )
+        
+        self.console.print("[green]✓[/green] Hoop stress computed")
+```
+
+---
+
+## Phase 3: Create Main CLI Entry Point
+
+### Step 3.1: Create Parser Configuration
+
+Create `python_magnetapi/cli/parser.py`:
+
+```python
+"""Argument parser configuration."""
+
+import argparse
+import os
+from typing import Dict, Type
+
+from .base import BaseCommand
+from .commands import COMMANDS
+
+
+def create_parser(commands: Dict[str, Type[BaseCommand]]) -> argparse.ArgumentParser:
+    """Create and configure the argument parser.
+    
+    Args:
+        commands: Dictionary of command name to command class
+        
+    Returns:
+        Configured ArgumentParser
+    """
+    # Main parser
+    parser = argparse.ArgumentParser(
+        prog="python_magnetapi",
+        description="CLI for interacting with MagnetDB",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    
+    # Global arguments
+    parser.add_argument(
+        "--server",
+        help="API server hostname",
+        type=str,
+        default=os.getenv("MAGNETDB_API_SERVER", "api.magnetdb-dev.local"),
+    )
+    parser.add_argument(
+        "--port",
+        help="API server port",
+        type=int,
+        default=8000,
+    )
+    parser.add_argument(
+        "--debug",
+        help="Enable debug mode",
+        action="store_true",
+    )
+    parser.add_argument(
+        "--https",
+        help="Use HTTPS",
+        action="store_true",
+    )
+    
+    # Subcommands
+    subparsers = parser.add_subparsers(
+        title="commands",
+        dest="command",
+        help="Available commands",
+        required=True,
+    )
+    
+    # Configure each command's parser
+    for cmd_name, cmd_class in commands.items():
+        cmd_instance = cmd_class()
+        cmd_parser = subparsers.add_parser(
+            cmd_name,
+            help=cmd_instance.help,
+        )
+        cmd_instance.configure_parser(cmd_parser)
+    
+    return parser
+```
+
+### Step 3.2: Refactor Main CLI Entry Point
+
+Update `python_magnetapi/cli.py`:
+
+```python
+#! /usr/bin/python3
+
+"""CLI for interacting with MagnetDB."""
+
+import os
+import sys
+from rich.console import Console
+
+from .cli.parser import create_parser
+from .cli.context import CLIContext
+from .cli.commands import COMMANDS
+from .exceptions import MagnetAPIException, AuthenticationError
+
+
+def main(argv=None) -> int:
+    """Main CLI entry point.
+    
+    Args:
+        argv: Command-line arguments (for testing)
+        
+    Returns:
+        Exit code (0 for success)
+    """
+    console = Console()
+    
+    try:
+        # Parse arguments
+        parser = create_parser(COMMANDS)
+        args = parser.parse_args(argv)
+        
+        if args.debug:
+            console.print(f"[dim]Arguments: {args}[/dim]")
+        
+        # Validate API key
+        api_key = os.getenv("MAGNETDB_API_KEY")
+        if not api_key:
+            console.print(
+                "[red]Error:[/red] MAGNETDB_API_KEY environment variable not set"
+            )
+            return 2
+        
+        # Create CLI context
+        context = CLIContext(
+            server=args.server,
+            port=args.port,
+            api_key=api_key,
+            debug=args.debug,
+            https=args.https,
+        )
+        
+        # Get command handler
+        command_class = COMMANDS[args.command]
+        command = command_class(console=console)
+        
+        # Execute command with context
+        with context:
+            return command.execute(args, context)
+    
+    except AuthenticationError as e:
+        console.print(f"[red]Authentication Error:[/red] {e.message}", style="bold")
+        if e.context:
+            console.print(f"[dim]{e.context}[/dim]")
+        console.print("\n[yellow]Tip:[/yellow] Check your MAGNETDB_API_KEY environment variable")
+        return 2
+    
+    except MagnetAPIException as e:
+        console.print(f"[red]Error:[/red] {e.message}", style="bold")
+        if e.context and args.debug:
+            console.print(f"[dim]Context: {e.context}[/dim]")
+        return 1
+    
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted by user[/yellow]")
+        return 130
+    
+    except Exception as e:
+        console.print(f"[red]Unexpected error:[/red] {e}", style="bold")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        return 99
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+---
+
+## Phase 4: Testing and Migration
+
+### Step 4.1: Create Command Handler Tests
+
+Create `tests/cli/test_list_command.py`:
+
+```python
+"""Tests for list command."""
+
+import pytest
+from unittest.mock import Mock, patch
+from python_magnetapi.cli.commands.list import ListCommand
+from python_magnetapi.cli.context import CLIContext
+
+
+def test_list_command_execution():
+    """Test list command executes correctly."""
+    # Mock context
+    context = Mock(spec=CLIContext)
+    context.session = Mock()
+    context.web = "http://test"
+    context.headers = {"Authorization": "test"}
+    context.debug = False
+    
+    # Mock utils.get_list
+    with patch("python_magnetapi.utils.get_list") as mock_get_list:
+        mock_get_list.return_value = {
+            "M10": 1,
+            "M11": 2,
+        }
+        
+        # Create command and execute
+        cmd = ListCommand()
+        args = Mock()
+        args.mtype = "magnet"
+        
+        exit_code = cmd.execute(args, context)
+        
+        # Verify
+        assert exit_code == 0
+        mock_get_list.assert_called_once()
+
+
+def test_list_command_parser_configuration():
+    """Test list command parser configuration."""
+    import argparse
+    
+    parser = argparse.ArgumentParser()
+    cmd = ListCommand()
+    cmd.configure_parser(parser)
+    
+    # Should have mtype argument
+    args = parser.parse_args(["--mtype", "part"])
+    assert args.mtype == "part"
+```
+
+### Step 4.2: Create Integration Tests
+
+Create `tests/cli/test_cli_integration.py`:
+
+```python
+"""Integration tests for CLI."""
+
+import pytest
+from unittest.mock import patch, Mock
+from python_magnetapi.cli import main
+
+
+def test_cli_list_command():
+    """Test CLI list command end-to-end."""
+    with patch("python_magnetapi.utils.get_list") as mock_list:
+        mock_list.return_value = {"M10": 1}
+        
+        exit_code = main(["--server", "test", "list", "--mtype", "magnet"])
+        
+        assert exit_code == 0
+
+
+def test_cli_missing_api_key():
+    """Test CLI fails gracefully without API key."""
+    import os
+    
+    # Temporarily remove API key
+    old_key = os.environ.pop("MAGNETDB_API_KEY", None)
+    
+    try:
+        exit_code = main(["list"])
+        assert exit_code == 2  # Authentication error
+    finally:
+        if old_key:
+            os.environ["MAGNETDB_API_KEY"] = old_key
+```
+
+### Step 4.3: Migration Strategy
+
+**Backwards Compatibility Testing:**
+
+1. Create test suite that calls old CLI interface
+2. Ensure all commands produce same output
+3. Test error cases match old behavior
+4. Verify exit codes are consistent
+
+**Gradual Migration:**
+
+1. Keep old cli.py as cli_old.py temporarily
+2. Run both implementations side-by-side in tests
+3. Compare outputs for all commands
+4. Once verified, remove old implementation
+
+**User Communication:**
+
+1. Update README with any CLI improvements
+2. Note that CLI interface is unchanged
+3. Mention any new features (better error messages, colored output)
+
+---
+
+## Success Criteria
+
+✅ **Implementation Complete When:**
+1. cli.py reduced from 684 to <100 lines
+2. All command handlers in separate modules
+3. Each command handler independently testable
+4. Base command class provides common functionality
+5. CLI context manages session and configuration
+6. Command registry allows easy extension
+7. All existing commands work identically
+8. Test coverage ≥ 80% for command handlers
+9. Rich console output with colors and formatting
+10. Better error messages with actionable hints
+
+✅ **Code Quality Metrics:**
+- Main cli.py: <100 lines
+- Each command handler: <150 lines
+- Cyclomatic complexity per function: <10
+- Zero code duplication (DRY principle)
+- All functions have type hints
+- All functions have docstrings
+
+✅ **Testing Coverage:**
+- Unit tests for each command handler
+- Integration tests for full CLI execution
+- Test all error cases
+- Test argument parsing
+- Test help messages
+
+---
+
+## Benefits of Refactoring
+
+### Maintainability
+- Easy to find and modify command logic
+- Clear separation of concerns
+- Easy to add new commands (just create new handler)
+
+### Testability
+- Each command independently testable
+- Mock-friendly architecture
+- Easy to test error cases
+
+### Readability
+- Small, focused modules
+- Clear naming conventions
+- Type hints throughout
+
+### Extensibility
+- Plugin-style architecture
+- Command registry makes adding commands trivial
+- Base class provides common functionality
+
+### User Experience
+- Better error messages with Rich formatting
+- Colored output for better readability
+- Consistent help messages
+
+---
+
+## Implementation Timeline
+
+**Week 1: Foundation**
+- Create CLI infrastructure (context, base, parser)
+- Create command registry
+- Set up testing framework
+
+**Week 2: Core Commands**
+- Implement list, view, create, delete commands
+- Write unit tests
+- Test backwards compatibility
+
+**Week 3: Advanced Commands**
+- Implement setup, run, compute commands
+- Write unit tests
+- Integration testing
+
+**Week 4: Polish & Migration**
+- Code review and cleanup
+- Complete documentation
+- Remove old CLI code
+- Update README and docs
+
+---
+
+## Notes for Implementation
+
+1. **Start with infrastructure** - Get context, base, and parser working first
+2. **One command at a time** - Implement and test each command handler individually
+3. **Test backwards compatibility** - Ensure CLI interface doesn't change
+4. **Use Rich for output** - Leverage tables, syntax highlighting, colors
+5. **Keep it simple** - Don't over-engineer, focus on clarity
+6. **Document as you go** - Update docstrings and docs continuously
+
+## Dependencies
+
+**Should be done after:**
+- Error Handling Framework (for proper exception handling)
+- Type Hints (for type safety)
+
+**Can be done in parallel with:**
+- Logging Framework (commands can add logging calls)
+
+---
+
+## Document Version
+
+**Version**: 1.0  
+**Created**: 2026-03-12  
+**Task**: CLI Module Refactoring  
+**Priority**: Tier 2 (Code Quality & Maintainability)  
+**Status**: Ready for implementation  
+**Dependencies**: Error Handling Framework (recommended)
diff --git a/prompts/CONFIGURATION_MANAGEMENT_TASK_PROMPT.md b/prompts/CONFIGURATION_MANAGEMENT_TASK_PROMPT.md
new file mode 100644
index 0000000..5ff3526
--- /dev/null
+++ b/prompts/CONFIGURATION_MANAGEMENT_TASK_PROMPT.md
@@ -0,0 +1,1425 @@
+# Configuration Management - Eliminate Hardcoded Values
+
+## Task Overview
+
+**Priority**: Tier 2 (Code Quality & Maintainability)  
+**Status**: Configuration scattered, hardcoded values throughout  
+**Estimated Effort**: Medium (centralized configuration system)  
+**Breaking Changes**: Minimal (backward compatible with environment variables)  
+
+## Current State Analysis
+
+### What Exists ✓
+- ✅ Environment variable support (MAGNETDB_API_SERVER, MAGNETDB_API_KEY)
+- ✅ CLI arguments for server/port/key
+- ✅ Basic configuration passing through function arguments
+
+### What's Missing ❌
+- ❌ **No centralized config** - Configuration scattered across modules
+- ❌ **No config files** - Can't use config.yaml or .env files
+- ❌ **No validation** - Invalid config values cause runtime errors
+- ❌ **No defaults management** - Defaults hardcoded in multiple places
+- ❌ **No configuration documentation** - Users don't know what's configurable
+- ❌ **No config precedence** - Unclear which source takes priority
+- ❌ **No type safety** - Config values are stringly-typed
+- ❌ **Hardcoded timeouts** - Network timeouts hardcoded in code
+- ❌ **Hardcoded paths** - File paths and URLs hardcoded
+- ❌ **No profile support** - Can't switch between dev/staging/prod configs
+
+### Current Configuration Approach
+
+**Problems identified:**
+```python
+# In CLI and various modules - configuration scattered everywhere:
+# 1. Hardcoded defaults in multiple places
+server = os.getenv("MAGNETDB_API_SERVER", "magnetdb.example.com")  # Default repeated
+port = int(os.getenv("MAGNETDB_API_PORT", "443"))  # Conversion scattered
+timeout = 30  # Hardcoded in various places
+
+# 2. No validation
+api_key = os.getenv("MAGNETDB_API_KEY")  # Could be None, causes runtime error later
+
+# 3. Configuration passed through 10+ function parameters
+def create_magnet(session, web, headers, api_key, timeout, debug, ...):
+    # Too many parameters!
+    pass
+
+# 4. Inconsistent configuration access
+# Some modules use env vars, some use passed parameters, some have defaults
+
+# 5. Hardcoded values throughout
+verify_ssl = True  # Hardcoded - can't disable for development
+retry_attempts = 3  # Hardcoded - can't configure
+chunk_size = 8192  # Hardcoded in attachment.py
+```
+
+### Configuration Scattered Across Files
+
+- `cli.py`: CLI argument defaults, environment variable access
+- `utils.py`: Function defaults for timeouts, debug flags
+- `attachment.py`: Hardcoded chunk sizes, file paths
+- `hoop_stress.py`: Hardcoded computation parameters
+- `flow_params.py`: Hardcoded sampling parameters
+- Each module: Repeated environment variable access
+
+---
+
+## Implementation Plan
+
+### Design Goals
+
+1. **Single source of truth** - One config class, all modules use it
+2. **Layered configuration** - Defaults < Config file < Environment vars < CLI args
+3. **Type-safe config** - Use dataclasses with type hints
+4. **Validated config** - Catch invalid values early
+5. **Backward compatible** - Existing env vars continue to work
+6. **Well documented** - Each config option documented
+7. **Environment profiles** - Support dev/staging/prod profiles
+8. **Security-aware** - Protect sensitive values (API keys, passwords)
+
+### Configuration Precedence (lowest to highest)
+
+```
+1. Hardcoded defaults (in Config class)
+2. System config file (/etc/magnetdb/config.yaml)
+3. User config file (~/.config/magnetdb/config.yaml)
+4. Project config file (./magnetdb.yaml or .magnetdb)
+5. Environment variables (MAGNETDB_*)
+6. Command-line arguments (--server, --api-key, etc.)
+```
+
+### Target Architecture
+
+```
+python_magnetapi/
+├── config.py                      # NEW: Core configuration module
+│   ├── Config (main config class)
+│   ├── APIConfig (API settings)
+│   ├── ComputationConfig (computation settings)
+│   ├── FileConfig (file/path settings)
+│   ├── LoggingConfig (logging settings)
+│   └── load_config() (config loader)
+├── config_schema.yaml             # NEW: Config schema/documentation
+├── magnetdb.yaml.example          # NEW: Example config file
+└── (existing modules updated to use Config)
+```
+
+---
+
+## Phase 1: Core Configuration Infrastructure
+
+### Step 1.1: Create Configuration Classes
+
+Create `python_magnetapi/config.py`:
+
+```python
+"""Centralized configuration management for python_magnetapi.
+
+Configuration precedence (lowest to highest):
+1. Hardcoded defaults
+2. System config file (/etc/magnetdb/config.yaml)
+3. User config file (~/.config/magnetdb/config.yaml)
+4. Project config file (./magnetdb.yaml or .magnetdb)
+5. Environment variables (MAGNETDB_*)
+6. Command-line arguments (passed to load_config)
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+import yaml
+from urllib.parse import urlparse
+
+
+# ============================================================================
+# Configuration Dataclasses
+# ============================================================================
+
+@dataclass
+class APIConfig:
+    """API connection configuration."""
+    
+    # Connection settings
+    server: str = "magnetdb.lncmi.cnrs.fr"
+    port: int = 443
+    api_key: Optional[str] = None
+    base_path: str = "/api"
+    
+    # Network settings
+    timeout: int = 30
+    verify_ssl: bool = True
+    retry_attempts: int = 3
+    retry_delay: float = 1.0
+    
+    # Request settings
+    max_concurrent: int = 10
+    rate_limit: Optional[int] = None  # requests per second
+    
+    def __post_init__(self):
+        """Validate configuration."""
+        if self.port < 1 or self.port > 65535:
+            raise ValueError(f"Invalid port: {self.port}. Must be 1-65535")
+        
+        if self.timeout < 0:
+            raise ValueError(f"Invalid timeout: {self.timeout}. Must be >= 0")
+        
+        if self.retry_attempts < 0:
+            raise ValueError(f"Invalid retry_attempts: {self.retry_attempts}")
+    
+    @property
+    def web(self) -> str:
+        """Construct full web URL."""
+        protocol = "https" if self.port == 443 else "http"
+        if (protocol == "https" and self.port == 443) or \
+           (protocol == "http" and self.port == 80):
+            return f"{protocol}://{self.server}"
+        return f"{protocol}://{self.server}:{self.port}"
+    
+    @property
+    def headers(self) -> Dict[str, str]:
+        """Construct request headers."""
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = self.api_key
+        return headers
+
+
+@dataclass
+class ComputationConfig:
+    """Computation module configuration."""
+    
+    # Hoop stress computation
+    hoop_stress_parallel: bool = True
+    hoop_stress_workers: Optional[int] = None  # None = auto
+    hoop_stress_chunk_size: int = 100
+    
+    # Flow parameters
+    flow_params_samples: int = 10
+    flow_params_tolerance: float = 1e-6
+    
+    # Inductance computation
+    inductance_method: str = "analytical"  # analytical, numerical
+    inductance_precision: float = 1e-9
+    
+    # General computation
+    numpy_threads: Optional[int] = None  # None = auto
+    cache_results: bool = True
+    
+    def __post_init__(self):
+        """Validate configuration."""
+        if self.hoop_stress_workers is not None and self.hoop_stress_workers < 1:
+            raise ValueError("hoop_stress_workers must be >= 1")
+        
+        if self.flow_params_samples < 1:
+            raise ValueError("flow_params_samples must be >= 1")
+        
+        if self.inductance_method not in ("analytical", "numerical"):
+            raise ValueError(f"Invalid inductance_method: {self.inductance_method}")
+
+
+@dataclass
+class FileConfig:
+    """File and path configuration."""
+    
+    # Upload/download settings
+    chunk_size: int = 8192  # bytes
+    max_file_size: int = 100 * 1024 * 1024  # 100 MB
+    
+    # Temporary files
+    temp_dir: Optional[Path] = None  # None = system temp
+    cleanup_temp: bool = True
+    
+    # Output settings
+    output_format: str = "json"  # json, yaml, csv
+    pretty_print: bool = True
+    
+    # Data directories
+    data_dir: Optional[Path] = None
+    cache_dir: Optional[Path] = None
+    
+    def __post_init__(self):
+        """Validate and normalize paths."""
+        if self.chunk_size < 1:
+            raise ValueError("chunk_size must be >= 1")
+        
+        if self.max_file_size < 1:
+            raise ValueError("max_file_size must be >= 1")
+        
+        if self.output_format not in ("json", "yaml", "csv"):
+            raise ValueError(f"Invalid output_format: {self.output_format}")
+        
+        # Expand paths
+        if self.temp_dir:
+            self.temp_dir = Path(self.temp_dir).expanduser().resolve()
+        if self.data_dir:
+            self.data_dir = Path(self.data_dir).expanduser().resolve()
+        if self.cache_dir:
+            self.cache_dir = Path(self.cache_dir).expanduser().resolve()
+
+
+@dataclass
+class LoggingConfig:
+    """Logging configuration."""
+    
+    level: str = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+    format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    
+    # Output targets
+    console: bool = True
+    file: Optional[Path] = None
+    syslog: bool = False
+    
+    # Filtering
+    debug_modules: List[str] = field(default_factory=list)
+    quiet_modules: List[str] = field(default_factory=list)
+    
+    def __post_init__(self):
+        """Validate configuration."""
+        valid_levels = ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+        if self.level.upper() not in valid_levels:
+            raise ValueError(f"Invalid level: {self.level}. Must be one of {valid_levels}")
+        
+        self.level = self.level.upper()
+        
+        if self.file:
+            self.file = Path(self.file).expanduser().resolve()
+
+
+@dataclass
+class Config:
+    """Main configuration class."""
+    
+    api: APIConfig = field(default_factory=APIConfig)
+    computation: ComputationConfig = field(default_factory=ComputationConfig)
+    files: FileConfig = field(default_factory=FileConfig)
+    logging: LoggingConfig = field(default_factory=LoggingConfig)
+    
+    # Global settings
+    debug: bool = False
+    profile: str = "default"  # default, dev, staging, prod
+    
+    def __post_init__(self):
+        """Apply profile-specific settings."""
+        if self.profile == "dev":
+            self.debug = True
+            self.api.verify_ssl = False
+            self.logging.level = "DEBUG"
+        elif self.profile == "staging":
+            self.api.server = "staging-magnetdb.lncmi.cnrs.fr"
+        # prod uses defaults
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary (for serialization)."""
+        return asdict(self)
+    
+    def validate(self) -> List[str]:
+        """Validate entire configuration.
+        
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        
+        # Check required fields
+        if not self.api.api_key:
+            errors.append("API key is required (set MAGNETDB_API_KEY or provide in config)")
+        
+        if not self.api.server:
+            errors.append("API server is required")
+        
+        # Additional cross-field validation
+        if self.files.cache_dir and not self.computation.cache_results:
+            errors.append("cache_dir set but cache_results is False")
+        
+        return errors
+
+
+# ============================================================================
+# Configuration Loading
+# ============================================================================
+
+def load_config_file(filepath: Path) -> Dict[str, Any]:
+    """Load configuration from YAML file.
+    
+    Args:
+        filepath: Path to config file
+        
+    Returns:
+        Configuration dictionary
+    """
+    if not filepath.exists():
+        return {}
+    
+    with open(filepath, "r") as f:
+        data = yaml.safe_load(f)
+        return data or {}
+
+
+def load_env_config() -> Dict[str, Any]:
+    """Load configuration from environment variables.
+    
+    Environment variables use MAGNETDB_ prefix:
+    - MAGNETDB_API_SERVER
+    - MAGNETDB_API_PORT
+    - MAGNETDB_API_KEY
+    - MAGNETDB_DEBUG
+    - etc.
+    
+    Returns:
+        Configuration dictionary
+    """
+    config: Dict[str, Any] = {}
+    
+    # API configuration
+    if os.getenv("MAGNETDB_API_SERVER"):
+        config.setdefault("api", {})["server"] = os.getenv("MAGNETDB_API_SERVER")
+    
+    if os.getenv("MAGNETDB_API_PORT"):
+        config.setdefault("api", {})["port"] = int(os.getenv("MAGNETDB_API_PORT"))
+    
+    if os.getenv("MAGNETDB_API_KEY"):
+        config.setdefault("api", {})["api_key"] = os.getenv("MAGNETDB_API_KEY")
+    
+    if os.getenv("MAGNETDB_TIMEOUT"):
+        config.setdefault("api", {})["timeout"] = int(os.getenv("MAGNETDB_TIMEOUT"))
+    
+    if os.getenv("MAGNETDB_VERIFY_SSL"):
+        value = os.getenv("MAGNETDB_VERIFY_SSL").lower()
+        config.setdefault("api", {})["verify_ssl"] = value in ("true", "1", "yes")
+    
+    # Computation configuration
+    if os.getenv("MAGNETDB_PARALLEL"):
+        value = os.getenv("MAGNETDB_PARALLEL").lower()
+        config.setdefault("computation", {})["hoop_stress_parallel"] = value in ("true", "1", "yes")
+    
+    # Logging configuration
+    if os.getenv("MAGNETDB_LOG_LEVEL"):
+        config.setdefault("logging", {})["level"] = os.getenv("MAGNETDB_LOG_LEVEL")
+    
+    # Global settings
+    if os.getenv("MAGNETDB_DEBUG"):
+        value = os.getenv("MAGNETDB_DEBUG").lower()
+        config["debug"] = value in ("true", "1", "yes")
+    
+    if os.getenv("MAGNETDB_PROFILE"):
+        config["profile"] = os.getenv("MAGNETDB_PROFILE")
+    
+    return config
+
+
+def merge_config(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    """Merge two configuration dictionaries (deep merge).
+    
+    Args:
+        base: Base configuration
+        override: Configuration to merge in (takes precedence)
+        
+    Returns:
+        Merged configuration
+    """
+    result = base.copy()
+    
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = merge_config(result[key], value)
+        else:
+            result[key] = value
+    
+    return result
+
+
+def load_config(
+    config_file: Optional[Path] = None,
+    profile: Optional[str] = None,
+    **overrides
+) -> Config:
+    """Load configuration from multiple sources.
+    
+    Configuration precedence (lowest to highest):
+    1. Hardcoded defaults (in Config class)
+    2. System config file (/etc/magnetdb/config.yaml)
+    3. User config file (~/.config/magnetdb/config.yaml)
+    4. Project config file (./magnetdb.yaml or .magnetdb)
+    5. Specified config file (config_file parameter)
+    6. Environment variables (MAGNETDB_*)
+    7. Function overrides (**overrides)
+    
+    Args:
+        config_file: Optional config file path (overrides search)
+        profile: Configuration profile (dev/staging/prod)
+        **overrides: Direct configuration overrides
+        
+    Returns:
+        Loaded and validated configuration
+        
+    Example:
+        >>> cfg = load_config(profile="dev", api={"timeout": 60})
+        >>> cfg = load_config(config_file=Path("my-config.yaml"))
+    """
+    config_data: Dict[str, Any] = {}
+    
+    # 1. Start with defaults (implicit in dataclass defaults)
+    
+    # 2. Load system config
+    system_config = Path("/etc/magnetdb/config.yaml")
+    if system_config.exists():
+        config_data = merge_config(config_data, load_config_file(system_config))
+    
+    # 3. Load user config
+    user_config = Path.home() / ".config" / "magnetdb" / "config.yaml"
+    if user_config.exists():
+        config_data = merge_config(config_data, load_config_file(user_config))
+    
+    # 4. Load project config
+    for project_config in [Path("magnetdb.yaml"), Path(".magnetdb")]:
+        if project_config.exists():
+            config_data = merge_config(config_data, load_config_file(project_config))
+            break
+    
+    # 5. Load specified config file
+    if config_file and config_file.exists():
+        config_data = merge_config(config_data, load_config_file(config_file))
+    
+    # 6. Load environment variables
+    config_data = merge_config(config_data, load_env_config())
+    
+    # 7. Apply direct overrides
+    if profile:
+        config_data["profile"] = profile
+    
+    if overrides:
+        config_data = merge_config(config_data, overrides)
+    
+    # Create Config object
+    cfg = Config(
+        api=APIConfig(**config_data.get("api", {})),
+        computation=ComputationConfig(**config_data.get("computation", {})),
+        files=FileConfig(**config_data.get("files", {})),
+        logging=LoggingConfig(**config_data.get("logging", {})),
+        debug=config_data.get("debug", False),
+        profile=config_data.get("profile", "default"),
+    )
+    
+    # Validate
+    errors = cfg.validate()
+    if errors:
+        raise ValueError(f"Configuration validation failed:\n" + "\n".join(f"  - {e}" for e in errors))
+    
+    return cfg
+
+
+def save_config(config: Config, filepath: Path) -> None:
+    """Save configuration to YAML file.
+    
+    Args:
+        config: Configuration to save
+        filepath: Output file path
+    """
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+    
+    with open(filepath, "w") as f:
+        yaml.dump(config.to_dict(), f, default_flow_style=False, sort_keys=False)
+
+
+# ============================================================================
+# Global configuration instance (optional, for convenience)
+# ============================================================================
+
+_global_config: Optional[Config] = None
+
+
+def get_config() -> Config:
+    """Get or initialize global configuration instance.
+    
+    Returns:
+        Global configuration
+        
+    Raises:
+        RuntimeError: If config not initialized
+    """
+    global _global_config
+    
+    if _global_config is None:
+        # Auto-initialize from environment on first access
+        _global_config = load_config()
+    
+    return _global_config
+
+
+def set_config(config: Config) -> None:
+    """Set global configuration instance.
+    
+    Args:
+        config: Configuration to set as global
+    """
+    global _global_config
+    _global_config = config
+```
+
+### Step 1.2: Create Example Configuration File
+
+Create `magnetdb.yaml.example`:
+
+```yaml
+# Python-MagnetAPI Configuration Example
+# Copy this file to:
+#   - /etc/magnetdb/config.yaml (system-wide)
+#   - ~/.config/magnetdb/config.yaml (user-specific)
+#   - ./magnetdb.yaml (project-specific)
+#
+# Or specify explicitly: python -m python_magnetapi --config config.yaml
+
+# API Connection Settings
+api:
+  server: "magnetdb.lncmi.cnrs.fr"
+  port: 443
+  api_key: "your-api-key-here"  # Or use MAGNETDB_API_KEY env var
+  base_path: "/api"
+  
+  # Network settings
+  timeout: 30  # seconds
+  verify_ssl: true
+  retry_attempts: 3
+  retry_delay: 1.0  # seconds
+  
+  # Concurrency settings
+  max_concurrent: 10
+  rate_limit: null  # null = no limit, or specify requests/second
+
+# Computation Settings
+computation:
+  # Hoop stress computation
+  hoop_stress_parallel: true
+  hoop_stress_workers: null  # null = auto-detect CPU count
+  hoop_stress_chunk_size: 100
+  
+  # Flow parameters
+  flow_params_samples: 10
+  flow_params_tolerance: 1e-6
+  
+  # Inductance computation
+  inductance_method: "analytical"  # analytical or numerical
+  inductance_precision: 1e-9
+  
+  # General
+  numpy_threads: null  # null = auto
+  cache_results: true
+
+# File and Path Settings
+files:
+  chunk_size: 8192  # bytes
+  max_file_size: 104857600  # 100 MB
+  
+  temp_dir: null  # null = system temp
+  cleanup_temp: true
+  
+  output_format: "json"  # json, yaml, csv
+  pretty_print: true
+  
+  data_dir: null
+  cache_dir: "~/.cache/magnetdb"
+
+# Logging Settings
+logging:
+  level: "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+  
+  console: true
+  file: null  # null = no file logging, or specify path
+  syslog: false
+  
+  debug_modules: []  # List of modules to debug
+  quiet_modules: []  # List of modules to silence
+
+# Global Settings
+debug: false
+profile: "default"  # default, dev, staging, prod
+
+# Profile-specific configurations
+# Uncomment and modify as needed:
+
+# profiles:
+#   dev:
+#     debug: true
+#     api:
+#       server: "localhost"
+#       port: 8000
+#       verify_ssl: false
+#     logging:
+#       level: "DEBUG"
+#   
+#   staging:
+#     api:
+#       server: "staging-magnetdb.lncmi.cnrs.fr"
+#       port: 443
+#   
+#   prod:
+#     api:
+#       server: "magnetdb.lncmi.cnrs.fr"
+#       port: 443
+#       verify_ssl: true
+#     computation:
+#       hoop_stress_parallel: true
+#       cache_results: true
+```
+
+### Step 1.3: Create Configuration Schema Documentation
+
+Create `python_magnetapi/config_schema.yaml`:
+
+```yaml
+# Configuration Schema Documentation
+# This file documents all available configuration options
+
+api:
+  description: "API connection and network settings"
+  
+  server:
+    type: string
+    required: false
+    default: "magnetdb.lncmi.cnrs.fr"
+    description: "API server hostname or IP address"
+    env: "MAGNETDB_API_SERVER"
+  
+  port:
+    type: integer
+    required: false
+    default: 443
+    description: "API server port"
+    env: "MAGNETDB_API_PORT"
+    validation: "1-65535"
+  
+  api_key:
+    type: string
+    required: true
+    default: null
+    description: "API authentication key"
+    env: "MAGNETDB_API_KEY"
+    sensitive: true
+  
+  timeout:
+    type: integer
+    required: false
+    default: 30
+    description: "Request timeout in seconds"
+    env: "MAGNETDB_TIMEOUT"
+  
+  verify_ssl:
+    type: boolean
+    required: false
+    default: true
+    description: "Verify SSL certificates"
+    env: "MAGNETDB_VERIFY_SSL"
+  
+  retry_attempts:
+    type: integer
+    required: false
+    default: 3
+    description: "Number of retry attempts for failed requests"
+  
+  retry_delay:
+    type: float
+    required: false
+    default: 1.0
+    description: "Delay between retry attempts in seconds"
+
+computation:
+  description: "Computation module settings"
+  
+  hoop_stress_parallel:
+    type: boolean
+    required: false
+    default: true
+    description: "Enable parallel computation for hoop stress"
+    env: "MAGNETDB_PARALLEL"
+  
+  hoop_stress_workers:
+    type: integer
+    required: false
+    default: null
+    description: "Number of parallel workers (null = auto-detect)"
+  
+  flow_params_samples:
+    type: integer
+    required: false
+    default: 10
+    description: "Number of samples for flow parameter computation"
+
+files:
+  description: "File handling settings"
+  
+  chunk_size:
+    type: integer
+    required: false
+    default: 8192
+    description: "Chunk size in bytes for file upload/download"
+  
+  max_file_size:
+    type: integer
+    required: false
+    default: 104857600
+    description: "Maximum file size in bytes (default: 100 MB)"
+  
+  output_format:
+    type: string
+    required: false
+    default: "json"
+    description: "Default output format"
+    validation: "json|yaml|csv"
+
+logging:
+  description: "Logging configuration"
+  
+  level:
+    type: string
+    required: false
+    default: "INFO"
+    description: "Logging level"
+    env: "MAGNETDB_LOG_LEVEL"
+    validation: "DEBUG|INFO|WARNING|ERROR|CRITICAL"
+  
+  console:
+    type: boolean
+    required: false
+    default: true
+    description: "Enable console logging"
+  
+  file:
+    type: string
+    required: false
+    default: null
+    description: "Log file path (null = no file logging)"
+
+debug:
+  type: boolean
+  required: false
+  default: false
+  description: "Enable debug mode"
+  env: "MAGNETDB_DEBUG"
+
+profile:
+  type: string
+  required: false
+  default: "default"
+  description: "Configuration profile to use"
+  env: "MAGNETDB_PROFILE"
+  validation: "default|dev|staging|prod"
+```
+
+---
+
+## Phase 2: Integrate Configuration into Existing Code
+
+### Step 2.1: Update utils.py to Use Config
+
+**Before:**
+```python
+def get_list(session, web, headers, mtype, debug=False):
+    """Get list with hardcoded behavior."""
+    # Configuration scattered and hardcoded
+    timeout = 30  # Hardcoded!
+    response = session.get(url, headers=headers, timeout=timeout)
+```
+
+**After:**
+```python
+from python_magnetapi.config import Config
+
+def get_list(
+    session,
+    web: str,
+    headers: Dict[str, str],
+    mtype: str,
+    config: Optional[Config] = None,
+    debug: Optional[bool] = None
+):
+    """Get list using centralized configuration.
+    
+    Args:
+        session: Requests session
+        web: Base web URL
+        headers: Request headers
+        mtype: Resource type
+        config: Configuration object (uses global if None)
+        debug: Debug override (uses config.debug if None)
+    """
+    from python_magnetapi.config import get_config
+    
+    if config is None:
+        config = get_config()
+    
+    if debug is None:
+        debug = config.debug
+    
+    # Use configuration values
+    timeout = config.api.timeout
+    
+    try:
+        response = session.get(
+            url,
+            headers=headers,
+            timeout=timeout,
+            verify=config.api.verify_ssl
+        )
+        # ... rest of implementation
+    except Exception as e:
+        if debug:
+            print(f"Request failed: {e}")
+        raise
+```
+
+### Step 2.2: Update CLI to Use Config
+
+**Update `cli.py` to load configuration:**
+
+```python
+from python_magnetapi.config import load_config, Config
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(description="MagnetDB API Client")
+    
+    # Add config file argument
+    parser.add_argument(
+        "--config",
+        type=Path,
+        help="Configuration file path"
+    )
+    
+    # Add profile argument
+    parser.add_argument(
+        "--profile",
+        choices=["default", "dev", "staging", "prod"],
+        help="Configuration profile"
+    )
+    
+    # Keep existing arguments for backward compatibility
+    parser.add_argument("--server", help="API server")
+    parser.add_argument("--port", type=int, help="API port")
+    parser.add_argument("--api-key", help="API key")
+    parser.add_argument("--debug", action="store_true", help="Debug mode")
+    
+    args = parser.parse_args()
+    
+    # Load configuration
+    overrides = {}
+    if args.server or args.port or args.api_key:
+        overrides["api"] = {}
+        if args.server:
+            overrides["api"]["server"] = args.server
+        if args.port:
+            overrides["api"]["port"] = args.port
+        if args.api_key:
+            overrides["api"]["api_key"] = args.api_key
+    
+    if args.debug:
+        overrides["debug"] = True
+    
+    try:
+        config = load_config(
+            config_file=args.config,
+            profile=args.profile,
+            **overrides
+        )
+    except ValueError as e:
+        print(f"Configuration error: {e}", file=sys.stderr)
+        return 1
+    
+    # Initialize session with config
+    from python_magnetapi.config import set_config
+    set_config(config)
+    
+    session = requests.Session()
+    
+    # Execute command with config
+    # ... rest of CLI logic
+```
+
+### Step 2.3: Update Domain Modules
+
+**Pattern for updating modules:**
+
+```python
+# At top of file
+from python_magnetapi.config import Config, get_config
+from typing import Optional
+
+# Update function signatures
+def create(
+    session,
+    web: str,
+    headers: Dict[str, str],
+    data: Dict,
+    config: Optional[Config] = None,
+    debug: Optional[bool] = None
+):
+    """Create object using configuration.
+    
+    Args:
+        ...
+        config: Configuration (uses global if None)
+        debug: Debug override (uses config.debug if None)
+    """
+    if config is None:
+        config = get_config()
+    
+    if debug is None:
+        debug = config.debug
+    
+    # Use config values instead of hardcoded
+    timeout = config.api.timeout
+    verify = config.api.verify_ssl
+    
+    # ... implementation
+```
+
+---
+
+## Phase 3: Configuration CLI Commands
+
+### Step 3.1: Add Config Subcommands
+
+Add to CLI:
+
+```python
+# magnetapi config show - Show current configuration
+# magnetapi config get api.timeout - Get specific value
+# magnetapi config set api.timeout 60 - Set value (in project config)
+# magnetapi config validate - Validate configuration
+# magnetapi config init - Initialize config file
+
+def cmd_config_show(args, config: Config):
+    """Show current configuration."""
+    import yaml
+    print(yaml.dump(config.to_dict(), default_flow_style=False))
+    return 0
+
+def cmd_config_get(args, config: Config):
+    """Get specific configuration value."""
+    keys = args.key.split(".")
+    value = config.to_dict()
+    
+    try:
+        for key in keys:
+            value = value[key]
+        print(value)
+        return 0
+    except KeyError:
+        print(f"Configuration key not found: {args.key}", file=sys.stderr)
+        return 1
+
+def cmd_config_set(args, config: Config):
+    """Set configuration value in project config."""
+    project_config = Path("magnetdb.yaml")
+    
+    # Load existing or create new
+    if project_config.exists():
+        with open(project_config) as f:
+            data = yaml.safe_load(f) or {}
+    else:
+        data = {}
+    
+    # Set value
+    keys = args.key.split(".")
+    current = data
+    for key in keys[:-1]:
+        current = current.setdefault(key, {})
+    current[keys[-1]] = args.value
+    
+    # Save
+    with open(project_config, "w") as f:
+        yaml.dump(data, f, default_flow_style=False)
+    
+    print(f"Set {args.key} = {args.value} in {project_config}")
+    return 0
+
+def cmd_config_init(args):
+    """Initialize configuration file from template."""
+    template = Path(__file__).parent / "magnetdb.yaml.example"
+    target = Path(args.output or "magnetdb.yaml")
+    
+    if target.exists() and not args.force:
+        print(f"Config file already exists: {target}", file=sys.stderr)
+        print("Use --force to overwrite", file=sys.stderr)
+        return 1
+    
+    # Copy template
+    import shutil
+    shutil.copy(template, target)
+    print(f"Created configuration file: {target}")
+    print(f"Edit the file and set your API key.")
+    return 0
+```
+
+---
+
+## Phase 4: Testing and Documentation
+
+### Step 4.1: Configuration Tests
+
+Create `tests/unit/test_config.py`:
+
+```python
+"""Tests for configuration management."""
+
+import pytest
+import os
+from pathlib import Path
+from python_magnetapi.config import (
+    Config,
+    APIConfig,
+    load_config,
+    load_env_config,
+    merge_config,
+)
+
+
+@pytest.mark.unit
+class TestAPIConfig:
+    """Test API configuration."""
+    
+    def test_default_config(self):
+        """Test default configuration values."""
+        cfg = APIConfig()
+        assert cfg.server == "magnetdb.lncmi.cnrs.fr"
+        assert cfg.port == 443
+        assert cfg.timeout == 30
+    
+    def test_web_property(self):
+        """Test web URL construction."""
+        cfg = APIConfig(server="test.local", port=443)
+        assert cfg.web == "https://test.local"
+        
+        cfg = APIConfig(server="test.local", port=8080)
+        assert cfg.web == "http://test.local:8080"
+    
+    def test_headers_property(self):
+        """Test headers construction."""
+        cfg = APIConfig(api_key="test-key-123")
+        assert cfg.headers == {"Authorization": "test-key-123"}
+        
+        cfg = APIConfig(api_key=None)
+        assert cfg.headers == {}
+    
+    def test_validation(self):
+        """Test configuration validation."""
+        with pytest.raises(ValueError, match="Invalid port"):
+            APIConfig(port=99999)
+        
+        with pytest.raises(ValueError, match="Invalid timeout"):
+            APIConfig(timeout=-1)
+
+
+@pytest.mark.unit
+class TestConfigLoading:
+    """Test configuration loading."""
+    
+    def test_load_env_config(self, monkeypatch):
+        """Test loading from environment variables."""
+        monkeypatch.setenv("MAGNETDB_API_SERVER", "test.local")
+        monkeypatch.setenv("MAGNETDB_API_PORT", "8080")
+        monkeypatch.setenv("MAGNETDB_API_KEY", "test-key")
+        monkeypatch.setenv("MAGNETDB_DEBUG", "true")
+        
+        env_config = load_env_config()
+        
+        assert env_config["api"]["server"] == "test.local"
+        assert env_config["api"]["port"] == 8080
+        assert env_config["api"]["api_key"] == "test-key"
+        assert env_config["debug"] is True
+    
+    def test_merge_config(self):
+        """Test configuration merging."""
+        base = {"api": {"server": "base", "port": 443}, "debug": False}
+        override = {"api": {"server": "override"}, "debug": True}
+        
+        merged = merge_config(base, override)
+        
+        assert merged["api"]["server"] == "override"
+        assert merged["api"]["port"] == 443  # Preserved from base
+        assert merged["debug"] is True
+    
+    def test_config_precedence(self, tmp_path, monkeypatch):
+        """Test configuration precedence."""
+        # Create config file
+        config_file = tmp_path / "test.yaml"
+        config_file.write_text("api:\n  timeout: 60\n")
+        
+        # Set environment variable
+        monkeypatch.setenv("MAGNETDB_TIMEOUT", "90")
+        
+        # Load with override
+        cfg = load_config(
+            config_file=config_file,
+            api={"timeout": 120}  # Highest precedence
+        )
+        
+        # Override should win
+        assert cfg.api.timeout == 120
+```
+
+### Step 4.2: Configuration Documentation
+
+Create `docs/configuration.md` (update existing):
+
+```markdown
+# Configuration Management
+
+## Overview
+
+Python-MagnetAPI uses a layered configuration system that supports:
+- Config files (YAML)
+- Environment variables
+- Command-line arguments
+- Programmatic configuration
+
+## Configuration Precedence
+
+Configuration is loaded from multiple sources with the following precedence (lowest to highest):
+
+1. **Hardcoded defaults** - Built-in default values
+2. **System config** - `/etc/magnetdb/config.yaml`
+3. **User config** - `~/.config/magnetdb/config.yaml`
+4. **Project config** - `./magnetdb.yaml` or `./.magnetdb`
+5. **Environment variables** - `MAGNETDB_*`
+6. **Command-line arguments** - `--server`, `--api-key`, etc.
+
+## Quick Start
+
+### Environment Variables
+
+```bash
+# Minimum required
+export MAGNETDB_API_KEY="your-api-key"
+
+# Optional
+export MAGNETDB_API_SERVER="magnetdb.lncmi.cnrs.fr"
+export MAGNETDB_API_PORT="443"
+export MAGNETDB_DEBUG="true"
+```
+
+### Config File
+
+Create `magnetdb.yaml` in your project:
+
+```yaml
+api:
+  server: "magnetdb.lncmi.cnrs.fr"
+  api_key: "your-api-key"
+  
+debug: false
+```
+
+Initialize from template:
+
+```bash
+magnetapi config init
+# Edit magnetdb.yaml with your settings
+```
+
+## Configuration Options
+
+See [Configuration Schema](config_schema.yaml) for all available options.
+
+### API Settings
+
+- `api.server` - API server hostname
+- `api.port` - API server port
+- `api.api_key` - Authentication key (**required**)
+- `api.timeout` - Request timeout in seconds
+- `api.verify_ssl` - Verify SSL certificates
+
+### Computation Settings
+
+- `computation.hoop_stress_parallel` - Enable parallel computation
+- `computation.flow_params_samples` - Number of computation samples
+
+### File Settings
+
+- `files.chunk_size` - Upload/download chunk size
+- `files.output_format` - Default output format (json/yaml/csv)
+
+### Logging Settings
+
+- `logging.level` - Log level (DEBUG/INFO/WARNING/ERROR)
+- `logging.file` - Log file path
+
+## Profiles
+
+Use profiles for different environments:
+
+```bash
+# Development (localhost, no SSL verification)
+magnetapi --profile dev list magnet
+
+# Staging
+magnetapi --profile staging list magnet
+
+# Production (default)
+magnetapi list magnet
+```
+
+## CLI Configuration Commands
+
+```bash
+# Show current configuration
+magnetapi config show
+
+# Get specific value
+magnetapi config get api.timeout
+
+# Set value (saves to ./magnetdb.yaml)
+magnetapi config set api.timeout 60
+
+# Validate configuration
+magnetapi config validate
+
+# Initialize config file
+magnetapi config init
+```
+
+## Programmatic Usage
+
+```python
+from python_magnetapi.config import load_config
+
+# Load from defaults + environment
+config = load_config()
+
+# Load with specific file
+config = load_config(config_file="my-config.yaml")
+
+# Load with overrides
+config = load_config(
+    profile="dev",
+    api={"timeout": 60}
+)
+
+# Access configuration
+print(config.api.web)
+print(config.api.timeout)
+
+# Use in API calls
+from python_magnetapi import utils
+result = utils.get_list(session, config.api.web, config.api.headers, "magnet", config=config)
+```
+```
+
+---
+
+## Success Criteria
+
+✅ **Implementation Complete When:**
+1. Core config.py module with dataclasses created
+2. All existing hardcoded values moved to config
+3. Configuration loading from files/env/CLI implemented
+4. Config validation with helpful error messages
+5. Example config file (magnetdb.yaml.example) provided
+6. Configuration documentation updated
+7. CLI config commands implemented (show/get/set/init)
+8. All modules updated to use Config
+9. Tests for configuration loading and validation
+10. Backward compatibility maintained (env vars still work)
+
+✅ **Quality Metrics:**
+- Zero hardcoded configuration values in code
+- All config options documented
+- Config validation catches errors early
+- Tests cover all config loading paths
+- Clear precedence order documented
+
+---
+
+## Migration Guide
+
+For users to update their code:
+
+```python
+# OLD - Hardcoded and scattered
+server = os.getenv("MAGNETDB_API_SERVER", "default")
+port = int(os.getenv("MAGNETDB_API_PORT", "443"))
+timeout = 30  # Hardcoded!
+
+session = requests.Session()
+web = f"https://{server}:{port}"
+headers = {"Authorization": os.getenv("MAGNETDB_API_KEY")}
+
+result = utils.get_list(session, web, headers, "magnet", debug=True)
+
+# NEW - Centralized configuration
+from python_magnetapi.config import load_config
+
+config = load_config()  # Loads from all sources automatically
+
+session = requests.Session()
+result = utils.get_list(
+    session,
+    config.api.web,
+    config.api.headers,
+    "magnet",
+    config=config
+)
+```
+
+---
+
+## Implementation Timeline
+
+**Week 1: Core Infrastructure**
+- Create config.py with all dataclasses
+- Implement load_config with precedence
+- Create example config file
+- Write configuration tests
+
+**Week 2: Integration**
+- Update utils.py to use Config
+- Update all domain modules (part, magnet, site, etc.)
+- Update CLI to load configuration
+- Maintain backward compatibility
+
+**Week 3: CLI Commands**
+- Implement config show/get/set/init commands
+- Add config validation
+- Update CLI help text
+
+**Week 4: Documentation & Testing**
+- Update configuration documentation
+- Add migration guide
+- Write integration tests
+- Test all configuration loading paths
+
+---
+
+## Notes for Implementation
+
+1. **Backward Compatibility** - Ensure existing env vars continue to work
+2. **Security** - Never log or print sensitive values (API keys)
+3. **Validation** - Validate early to catch errors before API calls
+4. **Type Safety** - Use dataclasses with type hints
+5. **Documentation** - Document every configuration option
+6. **Testing** - Test all precedence layers and merging logic
+7. **CLI Integration** - Update CLI to load and use config
+
+## Dependencies
+
+**Should be done after:**
+- Type Hints (for better config type safety)
+
+**Recommended before:**
+- Test Suite Enhancement (makes testing easier with config)
+
+**Required packages:**
+- PyYAML (for YAML config files)
+
+---
+
+## Document Version
+
+**Version**: 1.0  
+**Created**: 2026-03-12  
+**Task**: Configuration Management - Eliminate Hardcoded Values  
+**Priority**: Tier 2 (Code Quality & Maintainability)  
+**Status**: Ready for implementation
diff --git a/prompts/ERROR_HANDLING_TASK_PROMPT.md b/prompts/ERROR_HANDLING_TASK_PROMPT.md
new file mode 100644
index 0000000..8ef1da0
--- /dev/null
+++ b/prompts/ERROR_HANDLING_TASK_PROMPT.md
@@ -0,0 +1,771 @@
+# Error Handling and Exception Framework Implementation
+
+## Task Overview
+
+**Priority**: Tier 1 (High Impact, Foundation)
+**Status**: 🛠️ IN PROGRESS — Foundation complete, propagation remaining
+**Estimated Effort**: Medium (hierarchy done; ~10-15 files still need updating)
+**Breaking Changes**: Yes (functions returning `None` will raise exceptions)
+
+## Current State Analysis
+
+### What Exists ✅
+- ✅ `exceptions.py` created (121 lines) with `MagnetAPIException` base class and subclasses
+- ✅ CLI (`cli/` package) wired to catch `MagnetAPIException` and `AuthenticationError` with Rich output
+- ✅ Basic exception context via `**context` kwargs (status_code, url, response, etc.)
+
+### Problems Remaining ❌
+1. ❌ **Domain modules not updated** - `utils.py`, `part.py`, `magnet.py`, `site.py`, `record.py` still use `RuntimeError` / `print()`-based errors
+2. ❌ **Silent failures remain** - Some functions still return `None` on error instead of raising
+3. ❌ **Print-based errors** - `utils.py` and domain modules still use `print()` for error output
+4. ❌ **No error recovery** - No retry logic implemented
+5. ❌ **No error handling tests** - No tests for exception paths
+
+### Files Requiring Updates
+
+**High Priority:**
+- `python_magnetapi/utils.py` - Core API functions (~50+ print statements for errors)
+- `python_magnetapi/cli.py` - CLI error handling (~20+ generic RuntimeError instances)
+- New file: `python_magnetapi/exceptions.py` - Custom exception hierarchy
+
+**Medium Priority:**
+- `python_magnetapi/part.py` - Domain module error handling
+- `python_magnetapi/magnet.py` - Domain module error handling
+- `python_magnetapi/site.py` - Domain module error handling
+- `python_magnetapi/record.py` - Domain module error handling
+- `python_magnetapi/material.py` - Domain module error handling
+- `python_magnetapi/geometry.py` - Domain module error handling
+
+**Low Priority:**
+- `python_magnetapi/hoop_stress.py` - Computation error handling
+- `python_magnetapi/hoop_stress_parallel.py` - Computation error handling
+- `python_magnetapi/flow_params.py` - Computation error handling
+- `python_magnetapi/inductances.py` - Computation error handling
+
+**Testing:**
+- New file: `tests/test_exceptions.py` - Exception framework tests
+
+---
+
+## Implementation Plan
+
+### Phase 1: Foundation (Essential)
+
+#### Step 1.1: Create Exception Hierarchy
+
+Create `python_magnetapi/exceptions.py` with comprehensive exception classes:
+
+```python
+"""
+Custom exceptions for python-magnetapi.
+
+This module defines a hierarchy of exceptions used throughout the package
+to provide clear, structured error handling with context.
+"""
+
+
+class MagnetAPIException(Exception):
+    """Base exception for all python-magnetapi errors.
+    
+    All custom exceptions in this package inherit from this base class,
+    allowing users to catch any package-specific error.
+    
+    Attributes:
+        message (str): Human-readable error message
+        context (dict): Additional context information (status_code, url, etc.)
+    """
+    
+    def __init__(self, message, **context):
+        """Initialize exception with message and optional context.
+        
+        Args:
+            message: Human-readable error description
+            **context: Additional context (status_code, url, response, etc.)
+        """
+        super().__init__(message)
+        self.message = message
+        self.context = context
+    
+    def __str__(self):
+        """Format exception with context for display."""
+        if not self.context:
+            return self.message
+        ctx = ", ".join(f"{k}={v}" for k, v in self.context.items())
+        return f"{self.message} ({ctx})"
+
+
+# API-related exceptions
+class APIError(MagnetAPIException):
+    """Base exception for API communication errors."""
+    pass
+
+
+class AuthenticationError(APIError):
+    """Raised when API authentication fails.
+    
+    Typical causes:
+    - Invalid API key
+    - Missing credentials
+    - Expired token
+    """
+    pass
+
+
+class NotFoundError(APIError):
+    """Raised when requested resource is not found (HTTP 404).
+    
+    Context should include:
+        - resource_type: Type of resource (magnet, part, etc.)
+        - resource_id: ID that was not found
+    """
+    pass
+
+
+class APIRequestError(APIError):
+    """Raised when API request fails.
+    
+    Includes network errors, timeouts, connection issues.
+    """
+    pass
+
+
+class APIResponseError(APIError):
+    """Raised when API returns unexpected or invalid response.
+    
+    Context should include:
+        - status_code: HTTP status code
+        - response: Response body (if available)
+    """
+    pass
+
+
+class ForbiddenError(APIError):
+    """Raised when access to resource is forbidden (HTTP 403).
+    
+    User lacks permissions for the requested operation.
+    """
+    pass
+
+
+# Data validation exceptions
+class ValidationError(MagnetAPIException):
+    """Base exception for data validation errors."""
+    pass
+
+
+class InvalidDataError(ValidationError):
+    """Raised when input data is invalid or malformed.
+    
+    Context should include:
+        - field: Name of invalid field
+        - value: Invalid value provided
+        - expected: Expected format/type
+    """
+    pass
+
+
+class MissingFieldError(ValidationError):
+    """Raised when required field is missing.
+    
+    Context should include:
+        - field: Name of missing field
+        - resource_type: Type of resource being created/updated
+    """
+    pass
+
+
+# Resource operation exceptions
+class ResourceError(MagnetAPIException):
+    """Base exception for resource operation errors."""
+    pass
+
+
+class ResourceCreationError(ResourceError):
+    """Raised when resource creation fails."""
+    pass
+
+
+class ResourceUpdateError(ResourceError):
+    """Raised when resource update fails."""
+    pass
+
+
+class ResourceDeletionError(ResourceError):
+    """Raised when resource deletion fails."""
+    pass
+
+
+# Computation exceptions
+class ComputationError(MagnetAPIException):
+    """Base exception for computation/calculation errors."""
+    pass
+
+
+class InvalidParameterError(ComputationError):
+    """Raised when computation receives invalid parameters.
+    
+    Context should include:
+        - parameter: Name of invalid parameter
+        - value: Provided value
+        - constraint: Constraint that was violated
+    """
+    pass
+
+
+class ConvergenceError(ComputationError):
+    """Raised when numerical computation fails to converge."""
+    pass
+```
+
+**Update** `python_magnetapi/__init__.py` to export exceptions:
+```python
+from .exceptions import (
+    MagnetAPIException,
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    APIRequestError,
+    APIResponseError,
+    ForbiddenError,
+    ValidationError,
+    InvalidDataError,
+    MissingFieldError,
+    ResourceError,
+    ResourceCreationError,
+    ResourceUpdateError,
+    ResourceDeletionError,
+    ComputationError,
+    InvalidParameterError,
+    ConvergenceError,
+)
+
+__all__ = [
+    # ... existing exports ...
+    "MagnetAPIException",
+    "APIError",
+    "AuthenticationError",
+    # ... rest of exceptions ...
+]
+```
+
+#### Step 1.2: Refactor utils.py
+
+**Current pattern to replace:**
+```python
+# BEFORE:
+if r.status_code != 200:
+    print(response["detail"])
+    return None
+```
+
+**New pattern:**
+```python
+# AFTER:
+if r.status_code == 401 or r.status_code == 403:
+    raise AuthenticationError(
+        "Authentication failed - check MAGNETDB_API_KEY",
+        status_code=r.status_code,
+        url=r.url
+    )
+elif r.status_code == 404:
+    raise NotFoundError(
+        f"{mtype} with id {id} not found",
+        status_code=r.status_code,
+        url=r.url,
+        resource_type=mtype,
+        resource_id=id
+    )
+elif r.status_code != 200:
+    detail = response.get("detail", "Unknown error") if isinstance(response, dict) else "Unknown error"
+    raise APIResponseError(
+        f"API request failed: {detail}",
+        status_code=r.status_code,
+        url=r.url,
+        response=response
+    )
+```
+
+**Functions to update in utils.py:**
+- `get_list()` - Replace print + return None
+- `get_object()` - Replace print + return None
+- `create_object()` - Replace print + return None
+- `update_object()` - Replace print + return None
+- `del_object()` - Replace print statements
+- `add_data_to_object()` - Replace print + return None
+- `get_data()` - Replace print + return None
+- `post_data()` - Replace print + return None
+- All other utility functions with error handling
+
+**Optional: Add helper function for consistent API error handling:**
+```python
+def _handle_response_error(response, status_code, url, context_msg=""):
+    """Helper to handle API response errors consistently."""
+    if status_code == 401 or status_code == 403:
+        raise AuthenticationError(
+            f"Authentication failed{': ' + context_msg if context_msg else ''}",
+            status_code=status_code,
+            url=url
+        )
+    elif status_code == 404:
+        raise NotFoundError(
+            f"Resource not found{': ' + context_msg if context_msg else ''}",
+            status_code=status_code,
+            url=url
+        )
+    elif status_code != 200:
+        detail = response.get("detail", "Unknown error") if isinstance(response, dict) else "Unknown error"
+        raise APIResponseError(
+            f"API request failed: {detail}{': ' + context_msg if context_msg else ''}",
+            status_code=status_code,
+            url=url,
+            response=response
+        )
+```
+
+#### Step 1.3: Create Basic Tests
+
+Create `tests/test_exceptions.py`:
+
+```python
+"""Tests for custom exceptions."""
+
+import pytest
+from python_magnetapi.exceptions import (
+    MagnetAPIException,
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    InvalidParameterError,
+)
+
+
+def test_base_exception():
+    """Test base MagnetAPIException."""
+    exc = MagnetAPIException("Test error")
+    assert str(exc) == "Test error"
+    assert exc.message == "Test error"
+    assert exc.context == {}
+
+
+def test_exception_with_context():
+    """Test exception with context."""
+    exc = MagnetAPIException("Test error", status_code=404, url="http://example.com")
+    assert "Test error" in str(exc)
+    assert "status_code=404" in str(exc)
+    assert "url=http://example.com" in str(exc)
+    assert exc.context["status_code"] == 404
+
+
+def test_authentication_error():
+    """Test AuthenticationError is subclass of APIError."""
+    exc = AuthenticationError("Auth failed", status_code=401)
+    assert isinstance(exc, APIError)
+    assert isinstance(exc, MagnetAPIException)
+
+
+def test_not_found_error():
+    """Test NotFoundError with resource context."""
+    exc = NotFoundError(
+        "Magnet not found",
+        resource_type="magnet",
+        resource_id=123
+    )
+    assert "Magnet not found" in str(exc)
+    assert exc.context["resource_type"] == "magnet"
+
+
+def test_validation_error():
+    """Test ValidationError hierarchy."""
+    exc = InvalidParameterError(
+        "Invalid parameter",
+        parameter="current",
+        value=-100,
+        constraint="must be positive"
+    )
+    assert isinstance(exc, ValidationError)
+    assert exc.context["parameter"] == "current"
+
+
+def test_exception_catching():
+    """Test catching exceptions by hierarchy."""
+    # Can catch specific type
+    with pytest.raises(AuthenticationError):
+        raise AuthenticationError("Auth error")
+    
+    # Can catch by parent type
+    with pytest.raises(APIError):
+        raise AuthenticationError("Auth error")
+    
+    # Can catch by base type
+    with pytest.raises(MagnetAPIException):
+        raise AuthenticationError("Auth error")
+```
+
+---
+
+### Phase 2: Core Integration (Important)
+
+#### Step 2.1: Update CLI Error Handling
+
+Refactor `python_magnetapi/cli.py`:
+
+**Add top-level error handler in main():**
+```python
+def main():
+    """Main CLI entry point with comprehensive error handling."""
+    try:
+        # ... existing argument parsing ...
+        
+        # ... existing CLI logic ...
+        
+    except AuthenticationError as e:
+        console.print(f"[red]Authentication Error:[/red] {e.message}", style="bold")
+        if e.context:
+            console.print(f"[dim]{e.context}[/dim]")
+        console.print("\n[yellow]Tip:[/yellow] Check your MAGNETDB_API_KEY environment variable")
+        sys.exit(2)
+        
+    except NotFoundError as e:
+        console.print(f"[yellow]Not Found:[/yellow] {e.message}")
+        if "resource_type" in e.context and "resource_id" in e.context:
+            console.print(f"  Resource: {e.context['resource_type']} (ID: {e.context['resource_id']})")
+        sys.exit(3)
+        
+    except ForbiddenError as e:
+        console.print(f"[red]Access Forbidden:[/red] {e.message}")
+        console.print("[yellow]Tip:[/yellow] You may not have permission for this operation")
+        sys.exit(4)
+        
+    except APIError as e:
+        console.print(f"[red]API Error:[/red] {e.message}", style="bold")
+        if e.context:
+            console.print(f"[dim]Details: {e.context}[/dim]")
+        sys.exit(5)
+        
+    except ValidationError as e:
+        console.print(f"[yellow]Validation Error:[/yellow] {e.message}")
+        if "field" in e.context:
+            console.print(f"  Field: {e.context['field']}")
+        sys.exit(6)
+        
+    except ComputationError as e:
+        console.print(f"[red]Computation Error:[/red] {e.message}")
+        if e.context:
+            console.print(f"[dim]Details: {e.context}[/dim]")
+        sys.exit(7)
+        
+    except MagnetAPIException as e:
+        console.print(f"[red]Error:[/red] {e.message}", style="bold")
+        sys.exit(1)
+        
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted by user[/yellow]")
+        sys.exit(130)
+        
+    except Exception as e:
+        console.print(f"[red]Unexpected error:[/red] {e}", style="bold")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        sys.exit(99)
+```
+
+**Replace generic RuntimeError throughout cli.py:**
+```python
+# BEFORE:
+raise RuntimeError(f"{args.server} : wrong credentials - check MAGNETDB_API_KEY")
+
+# AFTER:
+raise AuthenticationError(
+    "Wrong credentials",
+    server=args.server,
+    hint="Check MAGNETDB_API_KEY environment variable"
+)
+```
+
+#### Step 2.2: Update Domain Modules
+
+For each domain module (`part.py`, `magnet.py`, `site.py`, `record.py`, `material.py`, `geometry.py`):
+
+**Replace generic RuntimeError:**
+```python
+# BEFORE:
+raise RuntimeError(
+    f"part/create: unexpected type for material (type={type(mat)})"
+)
+
+# AFTER:
+raise InvalidDataError(
+    "Unexpected type for material",
+    field="material",
+    expected="str or dict",
+    received=type(mat).__name__
+)
+```
+
+**Add validation for required fields:**
+```python
+# BEFORE: Silent assumption that field exists
+
+# AFTER:
+if "name" not in data:
+    raise MissingFieldError(
+        "Name is required",
+        field="name",
+        resource_type="part"
+    )
+```
+
+#### Step 2.3: Add Comprehensive Tests
+
+Expand `tests/test_exceptions.py` with integration tests:
+
+```python
+def test_utils_get_object_not_found(mocker):
+    """Test get_object raises NotFoundError for 404."""
+    # Mock requests to return 404
+    # Verify NotFoundError is raised with correct context
+    pass
+
+
+def test_utils_authentication_error(mocker):
+    """Test API functions raise AuthenticationError for 401/403."""
+    pass
+
+
+def test_cli_error_handling(capsys):
+    """Test CLI handles exceptions gracefully."""
+    pass
+```
+
+---
+
+### Phase 3: Polish & Advanced (Optional)
+
+#### Step 3.1: Update Computation Modules
+
+For `hoop_stress.py`, `hoop_stress_parallel.py`, `flow_params.py`, `inductances.py`:
+
+**Replace generic ValueError:**
+```python
+# BEFORE:
+raise ValueError("At least one current array must be provided.")
+
+# AFTER:
+raise InvalidParameterError(
+    "At least one current array must be provided",
+    parameter="currents",
+    constraint="must provide I, I_dict, or I2"
+)
+```
+
+**Don't silently catch exceptions:**
+```python
+# BEFORE:
+try:
+    result = compute_something()
+except:
+    pass  # Silent failure
+
+# AFTER:
+try:
+    result = compute_something()
+except Exception as e:
+    raise ComputationError(
+        f"Computation failed: {e}",
+        operation="compute_something"
+    ) from e
+```
+
+#### Step 3.2: Add Retry Logic (Optional)
+
+Add retry decorator for transient failures in utils.py:
+
+```python
+from functools import wraps
+import time
+
+
+def retry_on_transient_error(max_attempts=3, backoff=1.0):
+    """Decorator to retry API calls on transient errors.
+    
+    Args:
+        max_attempts: Maximum number of retry attempts
+        backoff: Backoff multiplier (exponential backoff)
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            attempt = 0
+            while attempt < max_attempts:
+                try:
+                    return func(*args, **kwargs)
+                except APIRequestError as e:
+                    # Only retry on network errors, not auth/validation
+                    attempt += 1
+                    if attempt >= max_attempts:
+                        raise
+                    time.sleep(backoff * (2 ** attempt))
+                except APIResponseError as e:
+                    # Retry on 5xx server errors
+                    if "status_code" in e.context and 500 <= e.context["status_code"] < 600:
+                        attempt += 1
+                        if attempt >= max_attempts:
+                            raise
+                        time.sleep(backoff * (2 ** attempt))
+                    else:
+                        raise
+            return None
+        return wrapper
+    return decorator
+
+
+# Usage:
+@retry_on_transient_error(max_attempts=3)
+def get_list(...):
+    # existing implementation
+    pass
+```
+
+#### Step 3.3: Documentation
+
+Add to docs:
+
+1. **docs/error_handling.rst** - New documentation file:
+```rst
+Error Handling
+==============
+
+Exception Hierarchy
+-------------------
+
+python-magnetapi uses a hierarchy of custom exceptions...
+
+[Document all exception types, when they're raised, how to catch them]
+
+Common Error Scenarios
+----------------------
+
+Authentication Errors
+~~~~~~~~~~~~~~~~~~~~~
+
+[How to handle auth errors, check credentials, etc.]
+
+Resource Not Found
+~~~~~~~~~~~~~~~~~~
+
+[How to handle 404s, verify IDs, etc.]
+
+Troubleshooting Guide
+---------------------
+
+[Common errors and solutions]
+```
+
+2. Update **docs/usage.rst** with error handling examples
+
+3. Update **docs/api/** module docs with "Raises" sections in docstrings
+
+---
+
+## Implementation Guidelines
+
+### Code Style
+- All exception classes should have comprehensive docstrings
+- Always include context in exceptions (status_code, url, resource info)
+- Use Rich console for CLI error display (colors, formatting)
+- Maintain backwards compatibility where possible
+
+### Testing Strategy
+- Unit tests for all exception classes
+- Integration tests for utils.py error handling
+- CLI error handler tests with mocked errors
+- Edge case tests (network failures, malformed responses)
+
+### Migration Considerations
+- **Breaking change**: Functions that returned `None` will now raise exceptions
+- Update all calling code to handle exceptions instead of checking for `None`
+- Consider adding deprecation warnings if backwards compatibility needed
+
+### Documentation Requirements
+- Update all docstrings with "Raises" sections
+- Add error handling example to README
+- Create troubleshooting guide
+- Add API reference for exceptions
+
+---
+
+## Success Criteria
+
+✅ **Implementation Complete When:**
+1. Custom exception hierarchy exists in `exceptions.py`
+2. All utils.py functions raise exceptions instead of print/return None
+3. CLI has comprehensive error handler with user-friendly messages
+4. All domain modules use appropriate exception types
+5. Test coverage for exceptions ≥ 90%
+6. Documentation includes error handling guide
+7. All existing tests pass with new error handling
+8. No more generic `RuntimeError` or `ValueError` in codebase
+
+✅ **Quality Metrics:**
+- Zero `print()` statements for errors (use exceptions/logging)
+- Zero `return None` on errors (raise exceptions)
+- All exceptions include context
+- User-friendly error messages in CLI
+- Proper exit codes for different error types
+
+---
+
+## Testing Checklist
+
+- [ ] All exception classes instantiate correctly
+- [ ] Exception context is preserved and formatted properly
+- [ ] utils.py raises correct exception types for different status codes
+- [ ] CLI error handler catches and displays all exception types
+- [ ] Domain modules raise appropriate exceptions
+- [ ] Computation modules raise InvalidParameterError for bad inputs
+- [ ] Integration test: Full CLI command with API error
+- [ ] Integration test: Full CLI command with auth error
+- [ ] Integration test: Full CLI command with not found error
+- [ ] Exception messages are clear and actionable
+- [ ] All docstrings updated with "Raises" sections
+
+---
+
+## References
+
+**Related Files:**
+- `python_magnetapi/exceptions.py` (new)
+- `python_magnetapi/__init__.py` (update exports)
+- `python_magnetapi/utils.py` (major refactor)
+- `python_magnetapi/cli.py` (add error handler)
+- `tests/test_exceptions.py` (new)
+
+**Python Best Practices:**
+- PEP 8: Exception naming conventions
+- Use exception chaining (`raise ... from e`)
+- Provide actionable error messages
+- Include context for debugging
+
+**Related Tasks:**
+- Logging framework (should use logging for debugging, exceptions for errors)
+- Type hints (exception raises should be in type hints when Python 3.11+)
+
+---
+
+## Notes for Implementation
+
+1. **Start with exceptions.py** - Get the foundation right first
+2. **Test each exception type** - Ensure hierarchy works correctly
+3. **Refactor utils.py incrementally** - One function at a time, test each
+4. **Update CLI last** - Requires utils.py refactor to be complete
+5. **Add retry logic separately** - Don't complicate initial implementation
+
+## Document Version
+
+**Version**: 1.0  
+**Created**: 2026-03-12  
+**Task**: Error Handling and Exception Framework  
+**Priority**: Tier 1 (High Impact, Foundation)  
+**Status**: Ready for implementation
diff --git a/prompts/PYTHON_MAGNETAPI_IMPROVEMENT_PROMPT.md b/prompts/PYTHON_MAGNETAPI_IMPROVEMENT_PROMPT.md
new file mode 100644
index 0000000..da001b5
--- /dev/null
+++ b/prompts/PYTHON_MAGNETAPI_IMPROVEMENT_PROMPT.md
@@ -0,0 +1,541 @@
+# Python-MagnetAPI Module Improvement Framework
+
+## Project Context
+
+**Project**: python-magnetapi  
+**Purpose**: Python library and CLI for interacting with MagnetDB (magnetic materials database)  
+**Current Version**: 0.1.0  
+**Python Support**: 3.11+  
+**Collaborators**: Christophe Trophime, Remi Caumette  
+**Active Branch**: claude/handle-foreignkey-fields-ZDujw
+**Status**: Active development with recent major improvements
+
+### Recent Major Achievements (March 2026)
+
+Multiple branches have seen significant progress across all improvement tiers:
+
+- **✅ Documentation Complete**: Full Sphinx documentation infrastructure with 1,500+ lines of comprehensive docs covering API, CLI, installation, testing, and contributing
+- **✅ Performance Optimized**: hoop_stress.py rewritten for better performance, plus parallel processing version
+- **✅ Modern Packaging**: Migrated to pure pyproject.toml (removed setup.py), proper PEP 517/518 compliance
+- **✅ Enhanced Dependencies**: Integrated python3-magnetcooling and python3-magnettools
+- **✅ Demo Scripts Added**: Three comprehensive demo scripts showcasing real-world usage (part history, part+site records, magnet parts)
+- **✅ README Expansion**: README expanded from ~50 to 314 lines with detailed installation and usage guides
+- **✅ Testing Framework**: pytest properly configured with test paths and coverage settings
+- **✅ CLI Refactoring Complete**: Monolithic 684-line cli.py split into modular cli/ package with command handlers, context, parser, and base class
+- **✅ Error Handling Foundation**: Custom exception hierarchy in exceptions.py (121 lines, MagnetAPIException base + subclasses)
+- **✅ Type Hints in CLI**: Full type hints and docstrings added to all cli/ modules
+- **✅ ForeignKey Handling**: `get_fk_id()` helper added to utils.py; `get_parts_for_magnet()` for nested API relations
+- **✅ SSL Verification**: `--no-verify` flag added to CLIContext and all demo scripts; InsecureRequestWarning suppressed when opted in
+
+### Core Characteristics
+- MagnetDB API client library with CLI tools
+- Domain-specific modules for magnetic materials, parts, magnets, sites, and records
+- Comprehensive CLI with multiple subcommands and computation capabilities
+- Modern packaging (pyproject.toml) with multi-package-manager support (pip, uv, Poetry)
+- Debian packaging integration
+- DevContainer development environment
+
+---
+
+## Improvement Methodology
+
+### Principle: Incremental, Prioritized Modernization
+
+We follow a systematic, step-by-step approach to improve the codebase:
+
+1. **Start with specific, bounded improvements** (e.g., single module or feature)
+2. **Maintain backward compatibility** unless explicitly modernizing packaging
+3. **Prioritize packaging infrastructure over API stability**
+4. **Document decisions and learnings** from each iteration
+5. **Test thoroughly** before and after changes
+
+### Priority Tiers
+
+**Tier 1 (High Impact, Foundation)** - ✅ COMPLETE
+- ✅ Version consistency across all configuration files
+- ✅ Test suite setup (pytest configuration)
+- ✅ Modern packaging (pyproject.toml migration)
+- ✅ Error handling and exception framework (exceptions.py created)
+- ⏳ Debian packaging modernization (debhelper, pybuild) - REMAINING
+- ⏳ Type hints - full coverage and mypy config - PARTIAL (CLI complete, other modules pending)
+
+**Tier 2 (Code Quality & Maintainability)** - 🛠️ MAJOR PROGRESS
+- ✅ Performance optimization (hoop_stress.py rewritten)
+- ✅ Parallel processing capability added
+- ✅ Modern library integration (python3-magnetcooling)
+- ✅ CLI module refactoring (modular cli/ package, complete)
+- ✅ ForeignKey field handling in utils.py (get_fk_id, get_parts_for_magnet)
+- ⏳ Test suite enhancement and fixture population - REMAINING
+- ⏳ Logging implementation (replace remaining print statements) - REMAINING
+- ⏳ Configuration management (move hardcoded values) - REMAINING
+
+**Tier 3 (Documentation & Developer Experience)** - ✅ COMPLETE
+- ✅ Sphinx documentation generation
+- ✅ API reference documentation
+- ✅ Architecture and design documentation
+- ✅ Contributing guidelines
+- ✅ Demo scripts and examples
+
+**Tier 4 (Polish & Advanced Features)** - 📅 FUTURE
+- Performance optimization (further improvements)
+- Advanced error recovery
+- Interactive CLI improvements
+- Plugin/extension system
+
+---
+
+## How to Use This Framework
+
+### For Each Improvement Task
+
+**1. Problem Definition**
+```
+When discussing an improvement, clearly state:
+- What specific component/file is being improved?
+- What is the current limitation or issue?
+- What is the desired outcome?
+- What is the scope (single file, module, cross-cutting)?
+```
+
+**2. Assessment**
+```
+Ask Claude to:
+- Review current implementation
+- Identify dependencies and side effects
+- Suggest backward compatibility approach
+- Assess test impact
+```
+
+**3. Implementation Planning**
+```
+Request Claude to:
+- Show the modified code
+- Explain changes and rationale
+- Identify files to create/modify/remove
+- Propose testing strategy
+```
+
+**4. Implementation**
+```
+Have Claude:
+- Create/modify files
+- Provide code with inline comments
+- Generate tests or test fixtures
+- Create summary of changes
+```
+
+**5. Verification**
+```
+Verify:
+- No syntax errors
+- Files are in correct locations
+- Changes align with project structure
+- Ready for integration/review
+```
+
+---
+
+## Key Project Knowledge
+
+### Project Structure
+```
+python-magnetapi/
+├── pyproject.toml              # Build config (PEP 517/518 compliant)
+├── debian/                      # Debian packaging
+│   ├── control                  # Package metadata
+│   ├── rules                    # Build rules
+│   ├── changelog                # Version history
+│   └── watch                    # Upstream version tracking
+├── .devcontainer/               # Development environment
+├── python_magnetapi/            # Main package
+│   ├── __init__.py              # Package version management
+│   ├── cli.py                   # Legacy CLI shim (kept for compatibility)
+│   ├── cli/                     # Modular CLI package (REFACTORED ✅)
+│   │   ├── __init__.py          # Exports main()
+│   │   ├── __main__.py          # python -m python_magnetapi.cli support
+│   │   ├── parser.py            # Argument parser configuration
+│   │   ├── context.py           # CLIContext dataclass (session, headers, --no-verify)
+│   │   ├── base.py              # BaseCommand ABC with shared helpers
+│   │   └── commands/            # Per-command handler modules
+│   │       ├── list.py          # list command
+│   │       ├── view.py          # view command
+│   │       ├── create.py        # create command
+│   │       ├── delete.py        # delete command
+│   │       ├── setup.py         # setup command
+│   │       ├── run.py           # run command
+│   │       ├── compute.py       # compute command
+│   │       └── process.py       # process command
+│   ├── exceptions.py            # Custom exception hierarchy (MagnetAPIException + subclasses)
+│   ├── utils.py                 # API utility functions (incl. get_fk_id, get_parts_for_magnet)
+│   ├── material.py              # Material domain module
+│   ├── part.py                  # Part domain module
+│   ├── magnet.py                # Magnet domain module
+│   ├── site.py                  # Site domain module
+│   ├── record.py                # Record domain module
+│   ├── attachment.py            # Attachment handling
+│   ├── geometry.py              # Geometry management
+│   ├── inductances.py           # Computation module
+│   ├── hoop_stress.py           # Computation module (optimized)
+│   ├── hoop_stress_parallel.py  # Parallel computation module
+│   └── flow_params.py           # Computation module (uses python3-magnetcooling)
+├── tests/                       # Test suite
+│   ├── test_list.py             # Comprehensive test class
+│   ├── cli/                     # CLI-specific tests
+│   │   ├── test_cli_integration.py
+│   │   └── test_list_command.py
+│   └── *.dat, *.json            # Test fixtures
+├── examples/                    # Demo scripts
+│   ├── demo_part_history.py     # Part hoop stress history demo
+│   ├── demo_part_site_records.py # Part site records demo
+│   ├── demo_magnet_parts.py     # Magnet parts listing demo (NEW)
+│   └── README-demos.md          # Demo documentation
+├── docs/                        # Sphinx documentation (COMPLETE)
+│   ├── conf.py                  # Sphinx configuration
+│   ├── index.rst                # Documentation index
+│   ├── cli.rst, usage.rst       # User guides
+│   ├── installation.rst         # Installation guide
+│   ├── testing.rst              # Testing guide
+│   ├── contributing.rst         # Contributor guide
+│   └── api/                     # API reference docs
+├── old/                         # Legacy examples (informational)
+└── README.md                    # Usage documentation (EXPANDED)
+```
+
+### Key Dependencies
+- **Core**: requests, pandas, numpy, scipy, param, rich
+- **Domain-specific**: python3-magnetsetup, python3-magnetcooling, python3-magnettools
+- **Dev**: pytest, pytest-cov
+- **Doc**: sphinx, sphinx-rtd-theme
+
+### Version Management
+- Single source of truth: `pyproject.toml` [project] → version
+- `python_magnetapi/__init__.py` reads version from package metadata
+- Debian changelog tracks releases
+- setup.py removed (now uses modern PEP 517/518 build system)
+
+---
+
+## Common Improvement Scenarios
+
+### Scenario A: Refactoring a Module
+```
+When improving a module like cli.py:
+1. Request detailed review of current structure
+2. Propose modular reorganization
+3. Create new module structure
+4. Migrate functionality piece by piece
+5. Update imports and tests
+6. Remove old files
+```
+
+### Scenario B: Adding Modern Python Features
+```
+When modernizing Python code:
+1. Review Python 3.11+ features
+2. Identify deprecations or opportunities
+3. Implement type hints gradually
+4. Add mypy configuration
+5. Test with multiple Python versions
+6. Update CI/CD if applicable
+```
+
+### Scenario C: Fixing Debian Packaging
+```
+When updating Debian packaging:
+1. Review current standards (debhelper, etc.)
+2. Check compatibility with target distros
+3. Update debian/control and debian/rules
+4. Test package building
+5. Verify installation
+6. Document changes in debian/changelog
+```
+
+### Scenario D: Enhancing Error Handling
+```
+When improving error handling:
+1. Map current error scenarios
+2. Define custom exceptions
+3. Create exception hierarchy
+4. Add error context and logging
+5. Update CLI error messages
+6. Add error handling tests
+```
+
+---
+
+## Communication Pattern
+
+### When Starting a Discussion
+
+Include in your request to Claude:
+
+```
+IMPROVEMENT FOCUS: [Component/Feature Name]
+PRIORITY TIER: [1-4]
+SCOPE: [single file / module / cross-module]
+
+CURRENT STATE:
+- [What exists now]
+- [Why it's problematic]
+
+DESIRED STATE:
+- [What should be achieved]
+- [Success criteria]
+
+CONSTRAINTS:
+- [Backward compatibility needs]
+- [Dependencies to consider]
+- [Testing requirements]
+
+NEXT STEPS:
+- [What should Claude do first?]
+```
+
+### Example
+
+```
+IMPROVEMENT FOCUS: CLI Module Refactoring
+PRIORITY TIER: 2
+SCOPE: python_magnetapi/cli.py (module split)
+
+CURRENT STATE:
+- 900+ line monolithic cli.py
+- Mixed argument parsing, business logic, and output
+- Hard to test individual command handlers
+
+DESIRED STATE:
+- Modular CLI structure with handlers per subcommand
+- Clear separation of concerns
+- Each handler independently testable
+
+CONSTRAINTS:
+- Maintain exact same CLI interface for users
+- No breaking changes to existing scripts
+- Must work with current argument structure
+
+NEXT STEPS:
+- Analyze current cli.py structure
+- Propose modular architecture
+- Show what handlers structure would look like
+```
+
+---
+
+## Tracking Progress
+
+### Completed Improvements
+
+#### Tier 1 (Foundation) - ✅ COMPLETED
+- ✅ Version consistency modernization (pyproject.toml updates, improved __init__.py)
+- ✅ Packaging modernization (removed setup.py, clean pyproject.toml with proper dependencies)
+- ✅ Test framework setup (pytest configuration in pyproject.toml)
+- ✅ Error handling foundation: exceptions.py with MagnetAPIException hierarchy
+
+#### Tier 2 (Code Quality) - ✅ MAJOR PROGRESS
+- ✅ Performance optimization of hoop_stress.py (rewritten: +760 lines improvements)
+- ✅ Parallel processing capability added (hoop_stress_parallel.py with 484 lines)
+- ✅ flow_params.py modernized to use python3-magnetcooling library
+- ✅ CLI refactored into modular cli/ package (context, base, parser, per-command handlers)
+- ✅ `__main__.py` added for `python -m python_magnetapi.cli` support
+- ✅ ForeignKey handling: `get_fk_id()` and `get_parts_for_magnet()` added to utils.py
+- ✅ `--no-verify` SSL flag added to CLIContext and all demo scripts
+
+#### Tier 3 (Documentation) - ✅ COMPLETED
+- ✅ Full Sphinx documentation structure created
+- ✅ Comprehensive documentation added:
+  - API reference documentation for all modules
+  - CLI documentation (cli.rst)
+  - Usage guide (usage.rst)
+  - Installation guide (installation.rst)
+  - Testing guide (testing.rst)
+  - Contributing guide (contributing.rst)
+  - Configuration guide (configuration.rst)
+- ✅ README significantly expanded (from ~50 to 314 lines)
+- ✅ Demo scripts added with documentation:
+  - demo_part_history.py (225 lines)
+  - demo_part_site_records.py (269 lines)
+  - README-demos.md (210 lines)
+
+#### Dependencies Updated - ✅ COMPLETED
+- ✅ Added python3-magnetcooling
+- ✅ Added python3-magnettools
+- ✅ Updated numpy, scipy, and other core dependencies
+
+### In-Progress Improvements
+- Type hints and static analysis (CLI complete, other modules pending)
+- Error handling (exceptions.py created, not yet systematically applied across all modules)
+
+### Next Planned Improvements
+
+#### Priority: Tier 1 Remaining
+1. Debian packaging modernization (debhelper, pybuild)
+2. Propagate exception hierarchy across all modules (replace RuntimeError / print-based errors)
+3. Type hints completion for domain modules (utils, part, magnet, site, etc.) and mypy configuration
+
+#### Priority: Tier 2 Remaining
+4. Test suite enhancement and fixture population (CLI unit tests scaffolded, need expansion)
+5. Logging implementation (replace remaining print statements in utils.py, domain modules)
+6. Configuration management (move hardcoded values)
+
+#### Priority: Tier 4 (Future)
+8. Interactive CLI improvements
+9. Plugin/extension system
+
+---
+
+## Focus Areas for Next Phase
+
+Based on the completed work, here are the recommended focus areas:
+
+### High Priority (Tier 1 Completion)
+1. **Debian Packaging Modernization**
+   - Update debian/rules to use dh-python and pybuild
+   - Ensure compatibility with modern Debian/Ubuntu standards
+   - Test package building and installation
+
+2. **Error Handling Propagation**
+   - exceptions.py already defines the hierarchy (MagnetAPIException + subclasses)
+   - Replace RuntimeError / print-based errors in utils.py, domain modules
+   - Wire CLI error handlers to the custom exception types
+   - Add error handling tests
+
+3. **Type Hints Completion**
+   - CLI modules fully typed — extend to utils.py, domain modules (part, magnet, site, record, material)
+   - Configure mypy for static analysis
+   - Add py.typed marker
+   - Gradually improve type coverage
+
+### Medium Priority (Tier 2 Focus)
+4. **Test Suite Enhancement** *(CLI unit tests scaffolded — expand coverage)*
+   - Populate unit tests for domain modules
+   - Add integration test fixtures
+   - Target ≥ 80% coverage
+
+3. **Logging Framework**
+   - Replace print statements with proper logging
+   - Add configurable log levels
+   - Support log file output
+   - Add request/response logging for API calls
+
+6. **Configuration Management**
+   - Extract hardcoded values to configuration
+   - Support environment variables
+   - Add configuration file support
+   - Document all configuration options
+
+---
+
+## Reference Documents
+
+### Style & Quality Standards
+- **Python Version**: 3.11+ (use modern syntax)
+- **Type Hints**: Gradually add to all new/modified functions
+- **Docstrings**: NumPy/Google style with type information
+- **Testing**: pytest with descriptive test names
+- **Linting**: Follow black formatting, flake8 compliance
+
+### Configuration Files to Consider
+- `pyproject.toml` [tool.pytest], [tool.coverage], [tool.mypy]
+- `.pre-commit-config.yaml` (for automated checks)
+- `.github/workflows/` (for CI/CD)
+
+### Documentation Standards
+- Inline comments for why, not what
+- Docstrings for public APIs
+- README sections for features
+- CHANGELOG entries for releases
+
+---
+
+## Questions to Ask Claude
+
+Use these types of questions systematically:
+
+### Discovery
+- "What are all the places this module is imported?"
+- "What functions depend on this implementation?"
+- "What would break if we changed this?"
+
+### Design
+- "What's the cleanest way to structure this?"
+- "Are there design patterns that fit?"
+- "How do we maintain backward compatibility?"
+
+### Implementation
+- "Can you implement this change?"
+- "Where should this code live?"
+- "How do we test this thoroughly?"
+
+### Quality
+- "What are potential edge cases?"
+- "How could this fail in production?"
+- "What error handling is needed?"
+
+---
+
+## Success Metrics
+
+For each improvement cycle:
+
+✅ **Code Quality**
+- Type hints added or extended
+- Cyclomatic complexity reduced
+- Test coverage maintained or improved
+
+✅ **Functionality**
+- No breaking changes (or documented)
+- All tests pass
+- Backwards compatibility maintained
+
+✅ **Documentation**
+- Changes documented
+- Usage examples updated if needed
+- Architecture implications noted
+
+✅ **Maintainability**
+- Code is easier to understand
+- Changes are easier to make
+- Testing is easier to write
+
+---
+
+## Anti-Patterns to Avoid
+
+❌ **Scope Creep**: Stay focused on one component per discussion  
+❌ **Premature Optimization**: Fix clarity before performance  
+❌ **Breaking Changes**: Maintain compatibility unless explicitly modernizing  
+❌ **Incomplete Testing**: All changes need test coverage  
+❌ **Undocumented Decisions**: Explain the "why" in comments/docstrings  
+
+---
+
+## Getting Started
+
+**For the next discussion**, use this prompt as context and specify:
+
+1. **What component** you want to improve (reference the structure above)
+2. **What the current issue is** (reference the review findings)
+3. **What success looks like** (be specific)
+4. **Any constraints** I should know about
+
+Example:
+
+> "I want to improve error handling in the utils.py module. Currently, API errors are just printed. I want custom exceptions and better error context. This should maintain backward compatibility at the CLI level but can change internal APIs. Let's start by reviewing current error scenarios."
+
+---
+
+## Document Version
+
+**Version**: 2.1
+**Created**: 2025-01-28
+**Last Updated**: 2026-03-20
+**Scope**: python-magnetapi package improvements
+**Major Changes**: Documented CLI refactoring completion (modular cli/ package); exceptions.py; get_fk_id/get_parts_for_magnet helpers; --no-verify flag; demo_magnet_parts.py; updated project structure, tier status, and next-steps roadmap
+
+---
+
+## Footer
+
+This framework guides iterative, systematic improvements to python-magnetapi while maintaining code quality, backward compatibility, and clear communication. Each improvement builds on previous work, creating a cohesive modernization path.
+
+**Next steps**: Reference this prompt in future discussions with Claude to ensure consistent methodology and context across all improvements.
diff --git a/prompts/TEST_SUITE_ENHANCEMENT_TASK_PROMPT.md b/prompts/TEST_SUITE_ENHANCEMENT_TASK_PROMPT.md
new file mode 100644
index 0000000..d80ce3e
--- /dev/null
+++ b/prompts/TEST_SUITE_ENHANCEMENT_TASK_PROMPT.md
@@ -0,0 +1,1634 @@
+# Test Suite Enhancement and Fixture Population
+
+## Task Overview
+
+**Priority**: Tier 2 (Code Quality & Maintainability)  
+**Status**: Minimal testing (210 lines, integration tests only)  
+**Estimated Effort**: Large (comprehensive test suite from scratch)  
+**Breaking Changes**: No (tests only)  
+
+## Current State Analysis
+
+### What Exists ✓
+- ✅ Basic test file: `test_list.py` (210 lines)
+- ✅ Test data files: 12 fixture files (.dat, .json, .yaml)
+- ✅ Two test classes: `TestList`, `TestCrud`
+- ✅ Integration tests (hit real API)
+- ✅ Basic pytest configuration in pyproject.toml
+
+### What's Missing ❌
+- ❌ **No unit tests** - All tests are integration tests
+- ❌ **No mocking** - Tests depend on real API server
+- ❌ **No conftest.py** - Fixture organization missing
+- ❌ **No test factories** - Fixture data created manually
+- ❌ **No parametrized tests** - Lots of code duplication
+- ❌ **Low coverage** - Only basic list/create/delete tested
+- ❌ **No test database setup** - Manual database required
+- ❌ **No CI/CD tests** - Can't run without external API
+- ❌ **No test documentation** - No guide for running tests
+- ❌ **No performance tests** - No benchmarks
+
+### Current Test Structure
+
+```
+tests/
+├── test_list.py (210 lines)
+│   ├── TestList - Integration tests for list operations
+│   └── TestCrud - Integration tests for CRUD operations
+├── Fixture data (12 files)
+│   ├── *.dat - Legacy format fixture data
+│   ├── *.json - JSON fixture data
+│   └── *.yaml - YAML fixture data
+├── conftest.py.old - Inactive fixture configuration
+└── __init__.py (empty)
+```
+
+### Issues with Current Tests
+
+1. **Integration-only** - Can't run without API server
+2. **No isolation** - Tests create/delete real data
+3. **Order-dependent** - Tests must run in specific order
+4. **Slow** - Network calls for every test
+5. **Brittle** - Break if API structure changes
+6. **Hard to debug** - No clear separation of concerns
+7. **No mocking** - Can't test error cases easily
+
+---
+
+## Implementation Plan
+
+### Design Goals
+
+1. **Two-tier testing** - Unit tests (mocked) + Integration tests (real DB)
+2. **Fast unit tests** - Run without external services (<5 seconds)
+3. **Reliable integration tests** - Docker-compose test environment
+4. **Fixture factories** - Generate test data programmatically
+5. **High coverage** - Target ≥80% code coverage
+6. **Parametrized tests** - Reduce code duplication
+7. **CI/CD ready** - Run in GitHub Actions
+8. **Well documented** - Clear setup and usage instructions
+
+### Target Architecture
+
+```
+tests/
+├── conftest.py                    # Pytest fixtures and configuration
+├── fixtures/
+│   ├── __init__.py
+│   ├── factories.py              # Test data factories
+│   ├── mock_responses.py         # Mock API responses
+│   └── sample_data.py            # Sample test data
+├── unit/                         # Unit tests (mocked, fast)
+│   ├── __init__.py
+│   ├── test_utils.py             # Test utils.py with mocking
+│   ├── test_part.py              # Test part.py with mocking
+│   ├── test_magnet.py            # Test magnet.py with mocking
+│   ├── test_site.py              # Test site.py with mocking
+│   ├── test_material.py          # Test material.py with mocking
+│   ├── test_geometry.py          # Test geometry.py with mocking
+│   ├── test_flow_params.py       # Test flow_params.py
+│   ├── test_hoop_stress.py       # Test hoop_stress.py
+│   └── test_inductances.py       # Test inductances.py
+├── integration/                  # Integration tests (real DB)
+│   ├── __init__.py
+│   ├── test_api_crud.py          # Test full CRUD operations
+│   ├── test_api_list.py          # Test list operations
+│   ├── test_simulation.py        # Test simulation workflows
+│   └── test_computation.py       # Test computation workflows
+├── cli/                          # CLI tests
+│   ├── __init__.py
+│   ├── test_commands.py          # Test CLI commands
+│   └── test_cli_integration.py   # Test full CLI workflows
+├── data/                         # Test data files
+│   ├── materials/                # Material test data
+│   ├── parts/                    # Part test data
+│   ├── magnets/                  # Magnet test data
+│   └── sites/                    # Site test data
+├── docker-compose.test.yml       # Test database setup
+└── README.md                     # Test documentation
+```
+
+---
+
+## Phase 1: Test Infrastructure Setup
+
+### Step 1.1: Create conftest.py with Fixtures
+
+Create `tests/conftest.py`:
+
+```python
+"""Pytest configuration and shared fixtures."""
+
+import os
+import pytest
+from unittest.mock import Mock, MagicMock
+import requests
+import json
+from pathlib import Path
+
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+def pytest_configure(config):
+    """Register custom markers."""
+    config.addinivalue_line(
+        "markers",
+        "unit: Unit tests with mocking (fast)",
+    )
+    config.addinivalue_line(
+        "markers",
+        "integration: Integration tests with real database (slow)",
+    )
+    config.addinivalue_line(
+        "markers",
+        "slow: Slow tests (skip by default)",
+    )
+
+
+# ============================================================================
+# Mock Fixtures (for unit tests)
+# ============================================================================
+
+@pytest.fixture
+def mock_session():
+    """Mock requests.Session for unit tests."""
+    session = MagicMock(spec=requests.Session)
+    session.verify = True
+    return session
+
+
+@pytest.fixture
+def mock_response():
+    """Factory fixture for mock responses."""
+    def _make_response(status_code=200, json_data=None, text="OK"):
+        response = Mock()
+        response.status_code = status_code
+        response.json.return_value = json_data or {}
+        response.text = text
+        response.url = "http://test-api/endpoint"
+        return response
+    return _make_response
+
+
+@pytest.fixture
+def api_config():
+    """API configuration for tests."""
+    return {
+        "server": "test-api.local",
+        "port": 8000,
+        "api_key": "test-key-123",
+        "headers": {"Authorization": "test-key-123"},
+        "web": "http://test-api.local:8000",
+    }
+
+
+@pytest.fixture
+def mock_api_success(mock_session, mock_response, api_config):
+    """Mock successful API responses."""
+    mock_session.get.return_value = mock_response(
+        status_code=200,
+        json_data={"id": 1, "name": "test"}
+    )
+    mock_session.post.return_value = mock_response(
+        status_code=200,
+        json_data={"id": 1}
+    )
+    mock_session.put.return_value = mock_response(status_code=200)
+    mock_session.delete.return_value = mock_response(status_code=200)
+    
+    return {
+        "session": mock_session,
+        "config": api_config,
+    }
+
+
+# ============================================================================
+# Real Database Fixtures (for integration tests)
+# ============================================================================
+
+@pytest.fixture(scope="session")
+def test_db_config():
+    """Configuration for test database.
+    
+    Reads from environment or uses defaults for docker-compose setup.
+    """
+    return {
+        "server": os.getenv("TEST_MAGNETDB_API_SERVER", "localhost"),
+        "port": int(os.getenv("TEST_MAGNETDB_API_PORT", "8001")),
+        "api_key": os.getenv("TEST_MAGNETDB_API_KEY", "test-key"),
+        "timeout": 30,
+    }
+
+
+@pytest.fixture(scope="session")
+def test_db_session(test_db_config):
+    """Real session for integration tests.
+    
+    Creates a session that connects to test database.
+    Only use with @pytest.mark.integration tests.
+    """
+    import time
+    
+    # Wait for database to be ready (in case of docker-compose)
+    max_retries = 10
+    for i in range(max_retries):
+        try:
+            session = requests.Session()
+            web = f"http://{test_db_config['server']}:{test_db_config['port']}"
+            headers = {"Authorization": test_db_config['api_key']}
+            
+            # Test connection
+            response = session.get(f"{web}/api/health", headers=headers, timeout=5)
+            if response.status_code == 200:
+                break
+        except requests.exceptions.RequestException:
+            if i == max_retries - 1:
+                pytest.skip("Test database not available")
+            time.sleep(2)
+    
+    yield {
+        "session": session,
+        "config": test_db_config,
+        "headers": headers,
+        "web": web,
+    }
+    
+    session.close()
+
+
+@pytest.fixture
+def clean_test_db(test_db_session):
+    """Clean test database before/after test.
+    
+    Use with integration tests that create data.
+    Automatically cleans up test objects by prefix.
+    """
+    test_prefix = "test_"
+    created_objects = []
+    
+    def register_object(mtype: str, obj_id: int):
+        """Register object for cleanup."""
+        created_objects.append((mtype, obj_id))
+    
+    # Provide registration function
+    yield register_object
+    
+    # Cleanup after test
+    from python_magnetapi import utils
+    for mtype, obj_id in reversed(created_objects):
+        try:
+            utils.del_object(
+                test_db_session["session"],
+                test_db_session["web"],
+                test_db_session["headers"],
+                obj_id,
+                mtype,
+                debug=False,
+            )
+        except Exception as e:
+            print(f"Cleanup failed for {mtype} {obj_id}: {e}")
+
+
+# ============================================================================
+# Data Fixtures
+# ============================================================================
+
+@pytest.fixture
+def test_data_dir():
+    """Path to test data directory."""
+    return Path(__file__).parent / "data"
+
+
+@pytest.fixture
+def load_test_data(test_data_dir):
+    """Factory to load test data files."""
+    def _load(category: str, filename: str):
+        """Load JSON test data file.
+        
+        Args:
+            category: Subdirectory (materials, parts, etc.)
+            filename: File name
+            
+        Returns:
+            Parsed JSON data
+        """
+        filepath = test_data_dir / category / filename
+        with open(filepath, "r") as f:
+            return json.load(f)
+    return _load
+
+
+# ============================================================================
+# Parametrization Helpers
+# ============================================================================
+
+RESOURCE_TYPES = ["material", "part", "magnet", "site", "record", "simulation"]
+
+
+@pytest.fixture(params=RESOURCE_TYPES)
+def resource_type(request):
+    """Parametrize over all resource types."""
+    return request.param
+```
+
+### Step 1.2: Create Test Data Factories
+
+Create `tests/fixtures/factories.py`:
+
+```python
+"""Test data factories using factory pattern."""
+
+from typing import Dict, Any, Optional
+from datetime import datetime
+import random
+
+
+class MaterialFactory:
+    """Factory for creating test material data."""
+    
+    @staticmethod
+    def create(
+        name: Optional[str] = None,
+        nuance: str = "test-nuance",
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Create material test data.
+        
+        Args:
+            name: Material name (auto-generated if not provided)
+            nuance: Material nuance
+            **kwargs: Additional fields
+            
+        Returns:
+            Material data dictionary
+        """
+        if name is None:
+            name = f"test_material_{random.randint(1000, 9999)}"
+        
+        data = {
+            "name": name,
+            "nuance": nuance,
+            "type": "conductor",
+            "properties": {
+                "rho": 1.8e-8,
+                "E": 120e9,
+                "nu": 0.3,
+                "alpha": 3.9e-3,
+            }
+        }
+        data.update(kwargs)
+        return data
+    
+    @staticmethod
+    def batch(count: int = 3) -> list:
+        """Create multiple materials."""
+        return [MaterialFactory.create() for _ in range(count)]
+
+
+class PartFactory:
+    """Factory for creating test part data."""
+    
+    @staticmethod
+    def create(
+        name: Optional[str] = None,
+        material_id: Optional[int] = None,
+        part_type: str = "helix",
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Create part test data.
+        
+        Args:
+            name: Part name (auto-generated if not provided)
+            material_id: Material ID
+            part_type: Part type (helix, ring, etc.)
+            **kwargs: Additional fields
+            
+        Returns:
+            Part data dictionary
+        """
+        if name is None:
+            name = f"test_part_{random.randint(1000, 9999)}"
+        
+        data = {
+            "name": name,
+            "type": part_type,
+            "status": "in_stock",
+        }
+        
+        if material_id is not None:
+            data["material_id"] = material_id
+        
+        data.update(kwargs)
+        return data
+    
+    @staticmethod
+    def batch(count: int = 3, material_id: Optional[int] = None) -> list:
+        """Create multiple parts."""
+        return [
+            PartFactory.create(material_id=material_id)
+            for _ in range(count)
+        ]
+
+
+class MagnetFactory:
+    """Factory for creating test magnet data."""
+    
+    @staticmethod
+    def create(
+        name: Optional[str] = None,
+        be: str = "Bitter",
+        part_ids: Optional[list] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Create magnet test data.
+        
+        Args:
+            name: Magnet name (auto-generated if not provided)
+            be: Magnet BE type
+            part_ids: List of part IDs
+            **kwargs: Additional fields
+            
+        Returns:
+            Magnet data dictionary
+        """
+        if name is None:
+            name = f"test_magnet_{random.randint(1000, 9999)}"
+        
+        data = {
+            "name": name,
+            "be": be,
+        }
+        
+        if part_ids is not None:
+            data["parts"] = part_ids
+        
+        data.update(kwargs)
+        return data
+
+
+class SiteFactory:
+    """Factory for creating test site data."""
+    
+    @staticmethod
+    def create(
+        name: Optional[str] = None,
+        magnet_ids: Optional[list] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Create site test data.
+        
+        Args:
+            name: Site name (auto-generated if not provided)
+            magnet_ids: List of magnet IDs
+            **kwargs: Additional fields
+            
+        Returns:
+            Site data dictionary
+        """
+        if name is None:
+            name = f"test_site_{random.randint(1000, 9999)}"
+        
+        data = {
+            "name": name,
+            "status": "in_stock",
+        }
+        
+        if magnet_ids is not None:
+            data["magnets"] = magnet_ids
+        
+        data.update(kwargs)
+        return data
+
+
+class RecordFactory:
+    """Factory for creating test record data."""
+    
+    @staticmethod
+    def create(
+        name: Optional[str] = None,
+        site_id: Optional[int] = None,
+        date: Optional[str] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Create record test data.
+        
+        Args:
+            name: Record name (auto-generated if not provided)
+            site_id: Site ID
+            date: Record date
+            **kwargs: Additional fields
+            
+        Returns:
+            Record data dictionary
+        """
+        if name is None:
+            name = f"test_record_{random.randint(1000, 9999)}"
+        
+        if date is None:
+            date = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        
+        data = {
+            "name": name,
+            "date": date,
+            "data": {
+                "current": 31000,
+                "voltage": 220,
+                "temperature": 25.0,
+            }
+        }
+        
+        if site_id is not None:
+            data["site_id"] = site_id
+        
+        data.update(kwargs)
+        return data
+
+
+# Export all factories
+__all__ = [
+    "MaterialFactory",
+    "PartFactory",
+    "MagnetFactory",
+    "SiteFactory",
+    "RecordFactory",
+]
+```
+
+### Step 1.3: Create Mock Response Library
+
+Create `tests/fixtures/mock_responses.py`:
+
+```python
+"""Mock API responses for unit testing."""
+
+from typing import Dict, Any, List
+
+
+class MockResponses:
+    """Collection of mock API responses."""
+    
+    # Successful responses
+    
+    @staticmethod
+    def list_success(items: List[Dict], page: int = 1, total: int = None) -> Dict:
+        """Mock successful list response."""
+        if total is None:
+            total = len(items)
+        
+        return {
+            "current_page": page,
+            "last_page": (total + 9) // 10,  # 10 items per page
+            "total": total,
+            "items": items,
+        }
+    
+    @staticmethod
+    def get_success(resource_type: str = "magnet", **fields) -> Dict:
+        """Mock successful get response."""
+        defaults = {
+            "id": 1,
+            "name": f"test_{resource_type}",
+            "created_at": "2026-01-01T00:00:00Z",
+            "updated_at": "2026-01-01T00:00:00Z",
+        }
+        defaults.update(fields)
+        return defaults
+    
+    @staticmethod
+    def create_success(resource_id: int = 1) -> Dict:
+        """Mock successful create response."""
+        return {"id": resource_id}
+    
+    @staticmethod
+    def update_success() -> Dict:
+        """Mock successful update response."""
+        return {"message": "Updated successfully"}
+    
+    @staticmethod
+    def delete_success() -> Dict:
+        """Mock successful delete response."""
+        return {"message": "Deleted successfully"}
+    
+    # Error responses
+    
+    @staticmethod
+    def error_not_found(resource_type: str = "resource", resource_id: int = 1) -> Dict:
+        """Mock 404 not found response."""
+        return {
+            "detail": f"{resource_type} with id {resource_id} not found",
+            "status_code": 404,
+        }
+    
+    @staticmethod
+    def error_unauthorized() -> Dict:
+        """Mock 401 unauthorized response."""
+        return {
+            "detail": "Unauthorized. Invalid API key.",
+            "status_code": 401,
+        }
+    
+    @staticmethod
+    def error_forbidden() -> Dict:
+        """Mock 403 forbidden response."""
+        return {
+            "detail": "Forbidden. Insufficient permissions.",
+            "status_code": 403,
+        }
+    
+    @staticmethod
+    def error_validation(field: str = "name", message: str = "Required field") -> Dict:
+        """Mock 422 validation error response."""
+        return {
+            "detail": [
+                {
+                    "loc": ["body", field],
+                    "msg": message,
+                    "type": "value_error",
+                }
+            ],
+            "status_code": 422,
+        }
+    
+    @staticmethod
+    def error_server() -> Dict:
+        """Mock 500 server error response."""
+        return {
+            "detail": "Internal server error",
+            "status_code": 500,
+        }
+    
+    # Sample data
+    
+    @staticmethod
+    def sample_material() -> Dict:
+        """Sample material data."""
+        return {
+            "id": 1,
+            "name": "CuAg0.1",
+            "nuance": "test",
+            "type": "conductor",
+            "properties": {
+                "rho": 1.8e-8,
+                "E": 120e9,
+                "nu": 0.3,
+            }
+        }
+    
+    @staticmethod
+    def sample_part() -> Dict:
+        """Sample part data."""
+        return {
+            "id": 1,
+            "name": "H1",
+            "type": "helix",
+            "material_id": 1,
+            "status": "in_stock",
+        }
+    
+    @staticmethod
+    def sample_magnet() -> Dict:
+        """Sample magnet data."""
+        return {
+            "id": 1,
+            "name": "M10",
+            "be": "Bitter",
+            "parts": [1, 2, 3],
+        }
+    
+    @staticmethod
+    def sample_site() -> Dict:
+        """Sample site data."""
+        return {
+            "id": 1,
+            "name": "M9_M10",
+            "magnets": [1],
+            "status": "in_stock",
+        }
+```
+
+---
+
+## Phase 2: Unit Tests with Mocking
+
+### Step 2.1: Unit Tests for utils.py
+
+Create `tests/unit/test_utils.py`:
+
+```python
+"""Unit tests for utils.py with mocking."""
+
+import pytest
+from unittest.mock import Mock, patch, call
+from python_magnetapi import utils
+from tests.fixtures.mock_responses import MockResponses
+
+
+@pytest.mark.unit
+class TestGetList:
+    """Test get_list function."""
+    
+    def test_get_list_single_page(self, mock_session, api_config, mock_response):
+        """Test get_list with single page of results."""
+        # Setup mock response
+        items = [
+            {"id": 1, "name": "M10"},
+            {"id": 2, "name": "M11"},
+        ]
+        mock_session.get.return_value = mock_response(
+            status_code=200,
+            json_data=MockResponses.list_success(items)
+        )
+        
+        # Execute
+        result = utils.get_list(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            "magnet"
+        )
+        
+        # Verify
+        assert result == {"M10": 1, "M11": 2}
+        mock_session.get.assert_called_once()
+    
+    def test_get_list_multiple_pages(self, mock_session, api_config, mock_response):
+        """Test get_list paginating through multiple pages."""
+        # Setup mock responses for 2 pages
+        page1_items = [{"id": i, "name": f"M{i}"} for i in range(1, 11)]
+        page2_items = [{"id": i, "name": f"M{i}"} for i in range(11, 15)]
+        
+        mock_session.get.side_effect = [
+            mock_response(200, MockResponses.list_success(page1_items, page=1, total=14)),
+            mock_response(200, MockResponses.list_success(page2_items, page=2, total=14)),
+        ]
+        
+        # Execute
+        result = utils.get_list(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            "magnet"
+        )
+        
+        # Verify
+        assert len(result) == 14
+        assert mock_session.get.call_count == 2
+    
+    def test_get_list_auth_error(self, mock_session, api_config, mock_response):
+        """Test get_list handles authentication error."""
+        mock_session.get.return_value = mock_response(
+            status_code=401,
+            json_data=MockResponses.error_unauthorized()
+        )
+        
+        # Should handle error gracefully (current implementation prints)
+        result = utils.get_list(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            "magnet"
+        )
+        
+        # With error handling framework, this would raise AuthenticationError
+        # For now, check it returns empty dict or handles error
+        assert result == {}
+
+
+@pytest.mark.unit
+class TestGetObject:
+    """Test get_object function."""
+    
+    def test_get_object_success(self, mock_session, api_config, mock_response):
+        """Test get_object retrieves object successfully."""
+        expected = MockResponses.sample_magnet()
+        mock_session.get.return_value = mock_response(200, expected)
+        
+        result = utils.get_object(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            1,
+            "magnet"
+        )
+        
+        assert result == expected
+        mock_session.get.assert_called_with(
+            f"{api_config['web']}/api/magnets/1",
+            headers=api_config["headers"]
+        )
+    
+    def test_get_object_not_found(self, mock_session, api_config, mock_response):
+        """Test get_object handles not found."""
+        mock_session.get.return_value = mock_response(
+            404,
+            MockResponses.error_not_found("magnet", 999)
+        )
+        
+        result = utils.get_object(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            999,
+            "magnet"
+        )
+        
+        # Currently returns None, with error framework would raise NotFoundError
+        assert result is None
+
+
+@pytest.mark.unit
+class TestCreateObject:
+    """Test create_object function."""
+    
+    def test_create_object_success(self, mock_session, api_config, mock_response):
+        """Test create_object creates successfully."""
+        mock_session.post.return_value = mock_response(
+            200,
+            MockResponses.create_success(42)
+        )
+        
+        data = {"name": "test_magnet", "be": "Bitter"}
+        result = utils.create_object(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            "magnet",
+            data
+        )
+        
+        assert result == 42
+        mock_session.post.assert_called_once()
+    
+    def test_create_object_validation_error(self, mock_session, api_config, mock_response):
+        """Test create_object handles validation error."""
+        mock_session.post.return_value = mock_response(
+            422,
+            MockResponses.error_validation("name", "Field required")
+        )
+        
+        data = {"be": "Bitter"}  # Missing name
+        result = utils.create_object(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            "magnet",
+            data
+        )
+        
+        # With error framework, would raise ValidationError
+        assert result is None
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("mtype", ["material", "part", "magnet", "site", "record"])
+def test_get_list_all_types(mock_session, api_config, mock_response, mtype):
+    """Test get_list works for all resource types."""
+    items = [{"id": 1, "name": f"test_{mtype}"}]
+    mock_session.get.return_value = mock_response(
+        200,
+        MockResponses.list_success(items)
+    )
+    
+    result = utils.get_list(
+        mock_session,
+        api_config["web"],
+        api_config["headers"],
+        mtype
+    )
+    
+    assert f"test_{mtype}" in result
+```
+
+### Step 2.2: Unit Tests for Domain Modules
+
+Create `tests/unit/test_part.py`:
+
+```python
+"""Unit tests for part.py with mocking."""
+
+import pytest
+from unittest.mock import patch
+from python_magnetapi import part
+from tests.fixtures.factories import PartFactory, MaterialFactory
+from tests.fixtures.mock_responses import MockResponses
+
+
+@pytest.mark.unit
+class TestPartCreate:
+    """Test part creation."""
+    
+    @patch('python_magnetapi.part.utils.create_object')
+    @patch('python_magnetapi.part.utils.get_list')
+    def test_create_with_material_name(
+        self,
+        mock_get_list,
+        mock_create,
+        mock_session,
+        api_config
+    ):
+        """Test creating part with material name (string)."""
+        # Setup mocks
+        mock_get_list.return_value = {"test_material": 5}
+        mock_create.return_value = 42
+        
+        # Create part with material name
+        data = PartFactory.create(material="test_material")
+        
+        result = part.create(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            data
+        )
+        
+        # Verify material was looked up and part was created
+        assert result == 42
+        mock_get_list.assert_called_with(
+            mock_session,
+            api_config["web"],
+            headers=api_config["headers"],
+            mtype="material",
+            debug=False
+        )
+    
+    @patch('python_magnetapi.part.utils.create_object')
+    def test_create_with_material_id(
+        self,
+        mock_create,
+        mock_session,
+        api_config
+    ):
+        """Test creating part with material ID (int)."""
+        mock_create.return_value = 42
+        
+        data = PartFactory.create(material_id=5)
+        
+        result = part.create(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            data
+        )
+        
+        assert result == 42
+    
+    @patch('python_magnetapi.part.geometry.create')
+    @patch('python_magnetapi.part.utils.create_object')
+    def test_create_with_geometry(
+        self,
+        mock_create_part,
+        mock_create_geometry,
+        mock_session,
+        api_config
+    ):
+        """Test creating part with geometry."""
+        mock_create_part.return_value = 42
+        mock_create_geometry.return_value = 100
+        
+        data = PartFactory.create(
+            material_id=5,
+            geometry=[{"file": "geometry.json"}]
+        )
+        
+        result = part.create(
+            mock_session,
+            api_config["web"],
+            api_config["headers"],
+            data
+        )
+        
+        # Verify both part and geometry were created
+        assert result == 42
+        mock_create_part.assert_called_once()
+        mock_create_geometry.assert_called_once()
+```
+
+---
+
+## Phase 3: Integration Tests with Real Database
+
+### Step 3.1: Docker Compose Test Database
+
+Create `tests/docker-compose.test.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  test-db:
+    image: postgres:15
+    environment:
+      POSTGRES_DB: magnetdb_test
+      POSTGRES_USER: test_user
+      POSTGRES_PASSWORD: test_password
+    ports:
+      - "5433:5432"
+    volumes:
+      - test-db-data:/var/lib/postgresql/data
+      - ./test-db-init.sql:/docker-entrypoint-initdb.d/init.sql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U test_user"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+  
+  test-api:
+    image: magnetdb/api:latest  # Replace with actual MagnetDB API image
+    environment:
+      DATABASE_URL: postgresql://test_user:test_password@test-db:5432/magnetdb_test
+      API_KEY: test-integration-key-12345
+      LOG_LEVEL: DEBUG
+    ports:
+      - "8001:8000"
+    depends_on:
+      test-db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/api/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  test-db-data:
+```
+
+### Step 3.2: Integration Test for CRUD Operations
+
+Create `tests/integration/test_api_crud.py`:
+
+```python
+"""Integration tests for CRUD operations against real test database."""
+
+import pytest
+from tests.fixtures.factories import (
+    MaterialFactory,
+    PartFactory,
+    MagnetFactory,
+    SiteFactory,
+)
+from python_magnetapi import utils, material, part, magnet, site
+
+
+@pytest.mark.integration
+class TestMaterialCRUD:
+    """Integration tests for material CRUD."""
+    
+    def test_create_list_get_delete_material(self, test_db_session, clean_test_db):
+        """Test full material lifecycle."""
+        session = test_db_session["session"]
+        web = test_db_session["web"]
+        headers = test_db_session["headers"]
+        
+        # Create material
+        data = MaterialFactory.create()
+        mat_id = material.create(session, web, headers, data)
+        assert mat_id is not None
+        clean_test_db("material", mat_id)
+        
+        # List materials - verify it appears
+        materials = utils.get_list(session, web, headers, "material")
+        assert data["name"] in materials
+        assert materials[data["name"]] == mat_id
+        
+        # Get material - verify data
+        retrieved = utils.get_object(session, web, headers, mat_id, "material")
+        assert retrieved["name"] == data["name"]
+        assert retrieved["nuance"] == data["nuance"]
+        
+        # Delete material
+        utils.del_object(session, web, headers, mat_id, "material")
+        
+        # Verify deleted
+        materials = utils.get_list(session, web, headers, "material")
+        assert data["name"] not in materials
+
+
+@pytest.mark.integration
+class TestHierarchicalCreation:
+    """Integration tests for creating hierarchical objects."""
+    
+    def test_create_full_site_hierarchy(self, test_db_session, clean_test_db):
+        """Test creating material -> part -> magnet -> site."""
+        session = test_db_session["session"]
+        web = test_db_session["web"]
+        headers = test_db_session["headers"]
+        
+        # Create material
+        mat_data = MaterialFactory.create()
+        mat_id = material.create(session, web, headers, mat_data)
+        clean_test_db("material", mat_id)
+        
+        # Create parts
+        part_ids = []
+        for i in range(3):
+            part_data = PartFactory.create(material_id=mat_id)
+            part_id = part.create(session, web, headers, part_data)
+            part_ids.append(part_id)
+            clean_test_db("part", part_id)
+        
+        # Create magnet with parts
+        mag_data = MagnetFactory.create(part_ids=part_ids)
+        mag_id = magnet.create(session, web, headers, mag_data)
+        clean_test_db("magnet", mag_id)
+        
+        # Create site with magnet
+        site_data = SiteFactory.create(magnet_ids=[mag_id])
+        site_id = site.create(session, web, headers, site_data)
+        clean_test_db("site", site_id)
+        
+        # Verify hierarchy
+        site_obj = utils.get_object(session, web, headers, site_id, "site")
+        assert mag_id in site_obj["magnets"]
+        
+        mag_obj = utils.get_object(session, web, headers, mag_id, "magnet")
+        for part_id in part_ids:
+            assert part_id in mag_obj["parts"]
+
+
+@pytest.mark.integration
+@pytest.mark.parametrize("count", [1, 5, 10])
+def test_bulk_creation(test_db_session, clean_test_db, count):
+    """Test creating multiple objects efficiently."""
+    session = test_db_session["session"]
+    web = test_db_session["web"]
+    headers = test_db_session["headers"]
+    
+    created_ids = []
+    
+    # Create multiple materials
+    for mat_data in MaterialFactory.batch(count):
+        mat_id = material.create(session, web, headers, mat_data)
+        created_ids.append(mat_id)
+        clean_test_db("material", mat_id)
+    
+    # Verify all created
+    assert len(created_ids) == count
+    materials = utils.get_list(session, web, headers, "material")
+    for mat_id in created_ids:
+        assert mat_id in materials.values()
+```
+
+### Step 3.3: Integration Test for Computation
+
+Create `tests/integration/test_computation.py`:
+
+```python
+"""Integration tests for computation modules."""
+
+import pytest
+from tests.fixtures.factories import MagnetFactory, PartFactory
+from python_magnetapi import inductances, flow_params, hoop_stress
+
+
+@pytest.mark.integration
+@pytest.mark.slow
+class TestInductanceComputation:
+    """Integration tests for inductance computation."""
+    
+    def test_compute_inductances_magnet(self, test_db_session, clean_test_db):
+        """Test inductance computation for magnet."""
+        session = test_db_session["session"]
+        web = test_db_session["web"]
+        headers = test_db_session["headers"]
+        
+        # Create test magnet (simplified)
+        # In practice, would need full hierarchy with geometry
+        mag_id = 1  # Use existing test magnet
+        
+        # Compute inductances
+        result = inductances.compute(
+            session,
+            web,
+            headers,
+            oid=mag_id,
+            mtype="magnet"
+        )
+        
+        # Verify result structure
+        assert result is not None
+        # Add more specific assertions based on expected output
+
+
+@pytest.mark.integration
+@pytest.mark.slow
+class TestFlowParamsComputation:
+    """Integration tests for flow parameters computation."""
+    
+    def test_compute_flow_params(self, test_db_session):
+        """Test flow parameters computation."""
+        session = test_db_session["session"]
+        web = test_db_session["web"]
+        headers = test_db_session["headers"]
+        
+        # Use existing test magnet
+        mag_id = 1
+        
+        # Compute flow parameters
+        result = flow_params.compute(
+            session,
+            web,
+            headers,
+            oid=mag_id,
+            samples=5,  # Small sample for faster testing
+        )
+        
+        assert result is not None
+```
+
+---
+
+## Phase 4: CLI Testing
+
+### Step 4.1: CLI Command Tests
+
+Create `tests/cli/test_commands.py`:
+
+```python
+"""Tests for CLI command handlers."""
+
+import pytest
+from unittest.mock import Mock, patch
+from python_magnetapi.cli.commands.list import ListCommand
+from python_magnetapi.cli.commands.view import ViewCommand
+from python_magnetapi.cli.context import CLIContext
+
+
+@pytest.mark.unit
+class TestListCommand:
+    """Test list command handler."""
+    
+    @patch('python_magnetapi.cli.commands.list.utils.get_list')
+    def test_list_magnets(self, mock_get_list):
+        """Test listing magnets."""
+        # Setup
+        mock_get_list.return_value = {"M10": 1, "M11": 2}
+        
+        cmd = ListCommand()
+        args = Mock()
+        args.mtype = "magnet"
+        
+        context = Mock(spec=CLIContext)
+        context.session = Mock()
+        context.web = "http://test"
+        context.headers = {}
+        context.debug = False
+        
+        # Execute
+        exit_code = cmd.execute(args, context)
+        
+        # Verify
+        assert exit_code == 0
+        mock_get_list.assert_called_once()
+
+
+@pytest.mark.integration
+class TestListCommandIntegration:
+    """Integration tests for list command."""
+    
+    def test_list_real_api(self, test_db_session):
+        """Test list command against real API."""
+        from python_magnetapi.cli.commands.list import ListCommand
+        from python_magnetapi.cli.context import CLIContext
+        
+        # Create context from test DB session
+        context = CLIContext(
+            server=test_db_session["config"]["server"],
+            port=test_db_session["config"]["port"],
+            api_key=test_db_session["config"]["api_key"],
+            debug=True,
+        )
+        
+        with context:
+            cmd = ListCommand()
+            args = Mock()
+            args.mtype = "material"
+            
+            exit_code = cmd.execute(args, context)
+            assert exit_code == 0
+```
+
+---
+
+## Phase 5: Testing Documentation and CI/CD
+
+### Step 5.1: Test Documentation
+
+Create `tests/README.md`:
+
+```markdown
+# Python-MagnetAPI Test Suite
+
+## Overview
+
+The test suite consists of two tiers:
+- **Unit tests** (fast, mocked) - Test individual functions in isolation
+- **Integration tests** (slow, real DB) - Test against actual test database
+
+## Running Tests
+
+### Quick Start (Unit Tests Only)
+
+```bash
+# Run all unit tests (fast, no external dependencies)
+pytest -m unit
+
+# Run with coverage
+pytest -m unit --cov=python_magnetapi --cov-report=html
+```
+
+### Full Test Suite (Unit + Integration)
+
+**Prerequisites:**
+- Docker and docker-compose installed
+- Test database running
+
+**Start test database:**
+
+```bash
+cd tests/
+docker-compose -f docker-compose.test.yml up -d
+
+# Wait for services to be ready
+docker-compose -f docker-compose.test.yml ps
+```
+
+**Run tests:**
+
+```bash
+# Run all tests (unit + integration)
+pytest
+
+# Run only integration tests
+pytest -m integration
+
+# Run with verbose output
+pytest -v -m integration
+```
+
+**Stop test database:**
+
+```bash
+cd tests/
+docker-compose -f docker-compose.test.yml down
+```
+
+## Test Organization
+
+```
+tests/
+├── unit/              # Unit tests (mocked, fast)
+├── integration/       # Integration tests (real DB, slow)
+├── cli/              # CLI tests
+├── fixtures/         # Test data factories and mocks
+└── data/             # Test data files
+```
+
+## Writing Tests
+
+### Unit Tests
+
+Use mocking for external dependencies:
+
+```python
+import pytest
+from unittest.mock import Mock
+
+@pytest.mark.unit
+def test_my_function(mock_session, api_config):
+    # Setup mock
+    mock_session.get.return_value = Mock(status_code=200)
+    
+    # Test function
+    result = my_function(mock_session)
+    
+    # Assert
+    assert result is not None
+```
+
+### Integration Tests
+
+Use real test database:
+
+```python
+import pytest
+
+@pytest.mark.integration
+def test_full_workflow(test_db_session, clean_test_db):
+    # Create test data
+    obj_id = create_object(test_db_session)
+    clean_test_db("object_type", obj_id)  # Register for cleanup
+    
+    # Test workflow
+    result = process_object(test_db_session, obj_id)
+    
+    # Assert
+    assert result is not None
+```
+
+## Environment Variables
+
+```bash
+# For integration tests
+export TEST_MAGNETDB_API_SERVER=localhost
+export TEST_MAGNETDB_API_PORT=8001
+export TEST_MAGNETDB_API_KEY=test-integration-key-12345
+```
+
+## Coverage
+
+Generate coverage report:
+
+```bash
+pytest --cov=python_magnetapi --cov-report=html --cov-report=term
+open htmlcov/index.html
+```
+
+## CI/CD
+
+Tests run automatically in GitHub Actions on push/PR.
+
+See `.github/workflows/test.yml` for configuration.
+```
+
+### Step 5.2: GitHub Actions Workflow
+
+Create `.github/workflows/test.yml`:
+
+```yaml
+name: Test Suite
+
+on:
+  push:
+    branches: [ main, refactor-* ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+      
+      - name: Run unit tests with coverage
+        run: |
+          pytest -m unit --cov=python_magnetapi --cov-report=xml --cov-report=term
+      
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-${{ matrix.python-version }}
+  
+  integration-tests:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    
+    services:
+      test-db:
+        image: postgres:15
+        env:
+          POSTGRES_DB: magnetdb_test
+          POSTGRES_USER: test_user
+          POSTGRES_PASSWORD: test_password
+        ports:
+          - 5433:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+      
+      - name: Wait for test API
+        run: |
+          # Add logic to start test API or wait for it
+          sleep 10
+      
+      - name: Run integration tests
+        env:
+          TEST_MAGNETDB_API_SERVER: localhost
+          TEST_MAGNETDB_API_PORT: 8001
+          TEST_MAGNETDB_API_KEY: test-integration-key
+        run: |
+          pytest -m integration -v
+```
+
+---
+
+## Success Criteria
+
+✅ **Implementation Complete When:**
+1. Comprehensive conftest.py with fixtures for both mock and real DB
+2. Test data factories for all resource types
+3. Mock response library for unit tests
+4. Unit tests for all modules (≥80% coverage)
+5. Integration tests with docker-compose test database
+6. CLI tests (unit + integration)
+7. Documentation for running tests
+8. CI/CD integration (GitHub Actions)
+9. Performance/slow tests marked and skippable
+10. Test coverage reporting integrated
+
+✅ **Quality Metrics:**
+- Test coverage ≥ 80%
+- Unit tests run in < 10 seconds
+- Integration tests run in < 2 minutes
+- All tests pass in CI/CD
+- Zero flaky tests
+- Clear test organization and naming
+
+✅ **Test Categories:**
+- Unit tests: ≥ 100 tests
+- Integration tests: ≥ 30 tests
+- CLI tests: ≥ 20 tests
+- Computation tests: ≥ 10 tests
+
+---
+
+## Implementation Timeline
+
+**Week 1: Foundation**
+- Create conftest.py with fixtures
+- Create factories and mock responses
+- Setup docker-compose for test DB
+- Write test documentation
+
+**Week 2: Unit Tests**
+- Unit tests for utils.py
+- Unit tests for domain modules
+- Unit tests for computation modules
+- Achieve 60% coverage
+
+**Week 3: Integration Tests**
+- Integration tests for CRUD
+- Integration tests for computation
+- Integration tests for CLI
+- Achieve 80% coverage
+
+**Week 4: CI/CD & Polish**
+- GitHub Actions workflow
+- Coverage reporting
+- Performance optimization
+- Documentation finalization
+
+---
+
+## Notes for Implementation
+
+1. **Start with infrastructure** - Get conftest.py and factories working first
+2. **Mock early, mock often** - Unit tests should be fast and isolated
+3. **Use parametrize** - Reduce code duplication with parametrized tests
+4. **Clean up after integration tests** - Always use clean_test_db fixture
+5. **Mark slow tests** - Use @pytest.mark.slow for tests > 5 seconds
+6. **Document test data** - Explain what each fixture file represents
+
+## Dependencies
+
+**Should be done after:**
+- Error Handling Framework (for proper exception testing)
+- Type Hints (for better test type safety)
+
+**Recommended tools:**
+- pytest-cov (coverage)
+- pytest-xdist (parallel testing)
+- pytest-mock (mocking utilities)
+- responses (HTTP mocking)
+
+---
+
+## Document Version
+
+**Version**: 1.0  
+**Created**: 2026-03-12  
+**Task**: Test Suite Enhancement and Fixture Population  
+**Priority**: Tier 2 (Code Quality & Maintainability)  
+**Status**: Ready for implementation
diff --git a/prompts/TIER1_DEBIAN_PACKAGING_PROMPT.md b/prompts/TIER1_DEBIAN_PACKAGING_PROMPT.md
new file mode 100644
index 0000000..64ddadc
--- /dev/null
+++ b/prompts/TIER1_DEBIAN_PACKAGING_PROMPT.md
@@ -0,0 +1,336 @@
+# Tier 1 Debian Packaging Modernization Prompt
+
+## IMPROVEMENT FOCUS: Debian Packaging Modernization
+**PRIORITY TIER**: 1 (Foundation)
+**SCOPE**: Debian packaging configuration files (debian/ directory)
+**ESTIMATED COMPLEXITY**: Low — most modernization already done, cleanup remaining
+**STATUS**: 🛠️ IN PROGRESS — foundation complete, cleanup needed
+
+---
+
+## CURRENT STATE (as of 2026-03-20)
+
+### What Has Been Done ✅
+
+- **debhelper-compat 13** — upgraded (was 12)
+- **Standards-Version 4.7.0** — updated (was 4.5.1)
+- **pybuild-plugin-pyproject** — explicitly declared in Build-Depends
+- **`--with python3` removed** from debian/rules (no longer needed)
+- **`override_dh_auto_test`** — skips tests with informative message
+- **Runtime dependencies expanded** — requests, pandas, numpy, scipy, param, rich, magnetsetup, magnetcooling, magnettools all declared
+- **Homepage field** — added to debian/control
+- **Version 0.1.1-1** — debian/changelog up to date (CLI refactoring + packaging update documented)
+
+### Current debian/control (actual file)
+
+```
+Source: python-magnetapi
+Section: python
+Priority: optional
+Maintainer: Christophe Trophime <christophe.trophime@lncmi.cnrs.fr>
+Build-Depends: debhelper-compat (= 13),
+ dh-python,
+ pybuild-plugin-pyproject,
+ python3-setuptools,
+ python3-all,
+ pybuild-plugin-pyproject,          ← DUPLICATE
+ python3-requests,
+ python3-pandas,
+ python3-numpy,
+ python3-scipy,
+ python3-param,
+ python3-rich,
+ python3-magnetsetup,
+ python3-magnetcooling,
+ python3-magnettools                ← MISSING TRAILING COMMA
+ python3-rich                       ← DUPLICATE (no comma separator)
+Standards-Version: 4.7.0
+Homepage: https://github.com/MagnetDB/python_magnetapi
+#Vcs-Browser: https://github.com/MagnetDB/python_magnetapi
+#Vcs-Git: https://github.com/MagnetDB/python_magnetapi.git
+#Testsuite: autopkgtest-pkg-python
+Rules-Requires-Root: no
+```
+
+### Current debian/rules (actual file)
+
+```makefile
+#!/usr/bin/make -f
+
+export PYBUILD_NAME=magnetapi
+
+%:
+	dh $@ --buildsystem=pybuild
+
+# Sphinx build commented out (kept for reference)
+#override_dh_auto_build: ...
+
+override_dh_auto_test:
+	@echo "Skipping tests - requires external MagnetDB API server"
+	@echo "Set MAGNETDB_API_SERVER and MAGNETDB_API_KEY environment variables to run tests"
+```
+
+### Current debian/changelog (latest entry)
+
+```
+python-magnetapi (0.1.1-1) UNRELEASED; urgency=medium
+
+  * rebuild for trixie
+  * Refactor CLI module into modular package structure
+  * Add type hints and docstrings throughout cli/ package
+  * Fix logic bug in setup command available_models validation
+  * Eliminate redundant API calls in view and compute commands
+  * Update pyproject.toml to declare cli/ sub-packages
+  * Modernize Debian packaging:
+    - Update Standards-Version to 4.7.0
+
+ -- Christophe Trophime <christophe.trophime@lncmi.cnrs.fr>  Thu, 20 Mar 2026 00:00:00 +0100
+```
+
+---
+
+## REMAINING ISSUES
+
+### 1. Duplicate and broken entries in debian/control Build-Depends
+
+The current Build-Depends has two bugs that will cause `dpkg-buildpackage` to either warn or fail:
+
+- `pybuild-plugin-pyproject` listed **twice**
+- `python3-rich` listed **twice** (once inside the block with a comma, once at the end without a comma separator after `python3-magnettools`)
+- Missing comma after `python3-magnettools` line (syntax error)
+
+**Fix**: Clean up to a single, correctly comma-separated list.
+
+### 2. `dh-python` still in Build-Depends
+
+With `pybuild-plugin-pyproject` explicit and `--with python3` removed from rules, `dh-python` is no longer needed as a Build-Depends. It can be dropped.
+
+### 3. `python3-setuptools` still in Build-Depends
+
+`setup.py` was removed; the project is pure pyproject.toml. `python3-setuptools` is not needed at build time with `pybuild-plugin-pyproject`.
+
+### 4. `Vcs-Browser` and `Vcs-Git` still commented out
+
+These fields should be uncommented — the GitHub repository is public and the URL is known.
+
+### 5. debian/changelog entry timestamp
+
+The current entry has a placeholder timestamp (`00:00:00`). Should be set to the actual release time when releasing.
+
+---
+
+## DESIRED STATE
+
+### Clean debian/control Build-Depends
+
+```
+Build-Depends: debhelper-compat (= 13),
+ pybuild-plugin-pyproject,
+ python3-all,
+ python3-requests,
+ python3-pandas,
+ python3-numpy,
+ python3-scipy,
+ python3-param,
+ python3-rich,
+ python3-magnetsetup,
+ python3-magnetcooling,
+ python3-magnettools
+```
+
+Removed: `dh-python`, `python3-setuptools`, duplicates.
+
+### Uncommented Vcs fields
+
+```
+Vcs-Browser: https://github.com/MagnetDB/python_magnetapi
+Vcs-Git: https://github.com/MagnetDB/python_magnetapi.git
+```
+
+### debian/rules — no changes needed
+
+The current rules file is correct and clean. `PYBUILD_NAME=magnetapi` is still needed so pybuild installs the package under the right name.
+
+---
+
+## CONSTRAINTS
+
+### Must Maintain
+
+- **Target distros**: Debian 12 (bookworm) and 13 (trixie)
+- **Package naming**: `python3-magnetapi`
+- **Runtime Depends**: All entries in the `Depends:` stanza are correct — do not remove
+- **`override_dh_auto_test`**: Keep — tests need external API server
+
+### Safe to Change
+
+- Build-Depends (build-time only)
+- Vcs fields (informational)
+- Duplicate/broken entries cleanup
+
+---
+
+## IMPLEMENTATION STEPS
+
+### Step 1: Fix debian/control
+
+Remove duplicates, drop unneeded build-time deps, uncomment Vcs fields.
+
+**Target debian/control:**
+
+```
+Source: python-magnetapi
+Section: python
+Priority: optional
+Maintainer: Christophe Trophime <christophe.trophime@lncmi.cnrs.fr>
+Build-Depends: debhelper-compat (= 13),
+ pybuild-plugin-pyproject,
+ python3-all,
+ python3-requests,
+ python3-pandas,
+ python3-numpy,
+ python3-scipy,
+ python3-param,
+ python3-rich,
+ python3-magnetsetup,
+ python3-magnetcooling,
+ python3-magnettools
+Standards-Version: 4.7.0
+Homepage: https://github.com/MagnetDB/python_magnetapi
+Vcs-Browser: https://github.com/MagnetDB/python_magnetapi
+Vcs-Git: https://github.com/MagnetDB/python_magnetapi.git
+Rules-Requires-Root: no
+
+Package: python3-magnetapi
+Architecture: all
+Depends: ${python3:Depends}, ${misc:Depends},
+ python3-requests,
+ python3-pandas,
+ python3-numpy,
+ python3-scipy,
+ python3-param,
+ python3-rich,
+ python3-magnetsetup,
+ python3-magnetcooling,
+ python3-magnettools
+Suggests: python-magnetapi-doc
+Description: Python library and CLI for interacting with MagnetDB
+ Python MagnetAPI provides utilities to interact with MagnetDB, a database
+ for magnetic materials, parts, magnets, and sites.
+ .
+ Features include:
+  - Listing, viewing, creating, and deleting database objects
+  - Setting up and running simulations
+  - Computing derived quantities (inductances, flow parameters, hoop stress)
+  - Post-processing simulation results
+ .
+ This package installs the library for Python 3.
+
+Package: python-magnetapi-doc
+Architecture: all
+Section: doc
+Depends: ${sphinxdoc:Depends}, ${misc:Depends}
+Description: Python library and CLI for MagnetDB (documentation)
+ Python MagnetAPI provides utilities to interact with MagnetDB, a database
+ for materials, parts, magnets, and sites.
+ .
+ This package provides the common documentation including Sphinx-generated
+ HTML documentation, API reference, and usage guides.
+```
+
+### Step 2: Update debian/changelog
+
+Add new entry for the cleanup:
+
+```
+python-magnetapi (0.1.1-2) UNRELEASED; urgency=low
+
+  * Fix Build-Depends: remove duplicate pybuild-plugin-pyproject and
+    python3-rich entries; remove unused dh-python and python3-setuptools
+  * Uncomment Vcs-Browser and Vcs-Git fields
+
+ -- Christophe Trophime <christophe.trophime@lncmi.cnrs.fr>  DATE
+```
+
+Or fold into the existing `0.1.1-1 UNRELEASED` entry since it hasn't been released yet.
+
+### Step 3: Verify Build
+
+```bash
+dpkg-buildpackage -F --no-sign
+lintian -i ../*.deb
+dpkg -c ../*.deb
+python3 -m python_magnetapi.cli --help
+```
+
+---
+
+## SUCCESS CRITERIA
+
+- [x] debhelper-compat 13
+- [x] pybuild-plugin-pyproject declared
+- [x] Standards-Version 4.7.0
+- [x] `--with python3` removed from rules
+- [x] override_dh_auto_test skips with clear message
+- [x] Version 0.1.1-1 in changelog
+- [ ] Duplicate Build-Depends entries removed
+- [ ] `dh-python` removed from Build-Depends
+- [ ] `python3-setuptools` removed from Build-Depends
+- [ ] Vcs-Browser / Vcs-Git uncommented
+- [ ] Package builds without lintian errors
+- [ ] `python -m python_magnetapi.cli --help` works after install
+
+---
+
+## DEBIAN COMPATIBILITY MATRIX
+
+| Aspect | Debian 11 (bullseye) | Debian 12 (bookworm) | Debian 13 (trixie) |
+|--------|----------------------|----------------------|-------------------|
+| Python 3.11 | Backports only | Yes (default) | Yes |
+| debhelper 13 | Yes | Yes | Yes |
+| pybuild-plugin-pyproject | Yes | Yes | Yes |
+| python3-magnetcooling | From repo | From repo | From repo |
+
+**Primary target**: Debian 13 (trixie) — `UNRELEASED` in changelog reflects this.
+
+---
+
+## REFERENCE: CURRENT debian/ DIRECTORY STATE
+
+```
+debian/
+├── control              # Needs duplicate/syntax cleanup
+├── rules                # OK — clean and correct
+├── changelog            # 0.1.1-1 UNRELEASED, needs timestamp fix on release
+├── copyright            # OK
+├── watch                # OK
+├── patches/series       # OK (empty)
+├── source/
+│   ├── format           # "3.0 (quilt)" — OK
+│   └── options          # egg-info ignore — OK
+├── python-magnetapi-docs.docs  # Doc package — OK
+├── README.Debian        # Informational — OK
+└── README.source        # OK
+```
+
+---
+
+## FOLLOW-UP ACTIONS (After This Cleanup)
+
+Once debian/control is clean:
+- Propagate custom exception hierarchy across domain modules (error handling)
+- Complete type hints for utils.py, part.py, magnet.py, site.py, record.py
+- Consider enabling `Testsuite: autopkgtest-pkg-python` once unit tests don't need external API
+
+---
+
+## Document Information
+
+**Prompt Type**: Actionable Tier 1 Improvement
+**Component**: Debian Packaging (debian/ directory)
+**Scope**: Build configuration cleanup
+**Estimated Time**: 30 minutes (cleanup + verify)
+**Difficulty**: Low (configuration cleanup only)
+**Risk Level**: Low
+**Last Updated**: 2026-03-20
+**Version**: 2.0
diff --git a/prompts/TYPE_HINTS_TASK_PROMPT.md b/prompts/TYPE_HINTS_TASK_PROMPT.md
new file mode 100644
index 0000000..a76128c
--- /dev/null
+++ b/prompts/TYPE_HINTS_TASK_PROMPT.md
@@ -0,0 +1,1122 @@
+# Type Hints and Static Analysis Setup
+
+## Task Overview
+
+**Priority**: Tier 1 (High Impact, Foundation) - Partial
+**Status**: 🛠️ IN PROGRESS — CLI fully typed; domain modules pending
+**Estimated Effort**: Medium (CLI done; ~10 domain/utility modules remaining)
+**Breaking Changes**: No (type hints are optional at runtime)
+
+## Current State Analysis
+
+### What Exists ✅
+- ✅ Full type hints and docstrings in all `python_magnetapi/cli/` modules (context, base, parser, all commands)
+- ✅ `get_fk_id()` in `utils.py` uses modern `int | None` union syntax
+- ✅ Basic type hints in some function signatures (`api_server: str`, `verbose: bool`, etc.)
+- ✅ Minimal typing imports in `hoop_stress.py` and `hoop_stress_parallel.py` (`from typing import Sequence`)
+- ✅ Python 3.11+ support (modern type hint syntax available)
+
+### What's Missing ❌
+- ❌ **Domain modules not typed** — `utils.py` (763 lines), `part.py`, `magnet.py`, `site.py`, `record.py`, `material.py` lack return annotations
+- ❌ **No py.typed marker** - Package not recognized as typed by type checkers
+- ❌ **No mypy configuration** - No static type checking setup
+- ❌ **Inconsistent type hints** - Some functions have partial hints, others have none
+- ❌ **No complex type annotations** - No Union, Optional, List, Dict annotations
+- ❌ **No TypedDict** for structured data (API responses, configuration)
+- ❌ **No Protocol definitions** for duck-typed interfaces
+- ❌ **No type narrowing** with isinstance checks
+- ❌ **No integration in CI/CD** - Type checking not automated
+
+### Files Requiring Updates
+
+**All modules need type hints:**
+- `python_magnetapi/utils.py` - API utility functions (~15 functions)
+- `python_magnetapi/cli.py` - CLI functions (~900 lines, many functions)
+- `python_magnetapi/part.py` - Part operations (~10 functions)
+- `python_magnetapi/magnet.py` - Magnet operations (~10 functions)
+- `python_magnetapi/site.py` - Site operations (~8 functions)
+- `python_magnetapi/record.py` - Record operations (~8 functions)
+- `python_magnetapi/material.py` - Material operations (~8 functions)
+- `python_magnetapi/geometry.py` - Geometry operations (~5 functions)
+- `python_magnetapi/attachment.py` - Attachment operations (~5 functions)
+- `python_magnetapi/flow_params.py` - Flow computations (~10 functions)
+- `python_magnetapi/hoop_stress.py` - Hoop stress computations (~12 functions)
+- `python_magnetapi/hoop_stress_parallel.py` - Parallel computations (~10 functions)
+- `python_magnetapi/inductances.py` - Inductance computations (~5 functions)
+- `python_magnetapi/__init__.py` - Package exports
+
+---
+
+## Implementation Plan
+
+### Phase 1: Foundation and Configuration
+
+#### Step 1.1: Create py.typed Marker
+
+Create empty `python_magnetapi/py.typed` file to indicate package supports type hints:
+
+```bash
+touch python_magnetapi/py.typed
+```
+
+This signals to type checkers that the package provides type information (PEP 561).
+
+**Update pyproject.toml** to include py.typed in package data:
+
+```toml
+[tool.setuptools.package-data]
+python_magnetapi = ["py.typed"]
+```
+
+#### Step 1.2: Configure mypy
+
+Add mypy configuration to `pyproject.toml`:
+
+```toml
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false  # Start lenient, tighten later
+disallow_incomplete_defs = false
+check_untyped_defs = true
+disallow_untyped_calls = false
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+show_error_codes = true
+show_column_numbers = true
+pretty = true
+
+# Gradually increase strictness
+[[tool.mypy.overrides]]
+module = "python_magnetapi.utils"
+disallow_untyped_defs = true  # Enforce for completed modules
+
+[[tool.mypy.overrides]]
+module = "python_magnetapi.exceptions"
+disallow_untyped_defs = true
+
+# Third-party libraries without stubs
+[[tool.mypy.overrides]]
+module = [
+    "python_magnetsetup.*",
+    "python_magnetcooling.*",
+    "python_magnettools.*",
+    "python_magnetrun.*",
+    "magnettools.*",
+    "param.*",
+]
+ignore_missing_imports = true
+```
+
+#### Step 1.3: Add mypy to dev dependencies
+
+Update `pyproject.toml`:
+
+```toml
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.2.0",
+    "pytest-cov",
+    "mypy>=1.8.0",
+    "types-requests",  # Type stubs for requests
+]
+```
+
+#### Step 1.4: Create Type Aliases File
+
+Create `python_magnetapi/types.py` for common type aliases:
+
+```python
+"""Type aliases and TypedDict definitions for python-magnetapi."""
+
+from typing import TypedDict, Union, Optional, Dict, Any, List
+import requests
+
+# Type aliases
+SessionType = requests.Session
+HeadersDict = Dict[str, str]
+JSONDict = Dict[str, Any]
+
+# API Response types (based on actual API structure)
+class PagedResponse(TypedDict):
+    """Structure of paginated API responses."""
+    current_page: int
+    last_page: int
+    items: List[JSONDict]
+    total: int
+
+
+class MaterialData(TypedDict, total=False):
+    """Material data structure (total=False means all fields optional)."""
+    name: str
+    id: int
+    nuance: Optional[str]
+    type: str
+    properties: Dict[str, Any]
+
+
+class PartData(TypedDict, total=False):
+    """Part data structure."""
+    name: str
+    id: int
+    material_id: int
+    type: str
+    status: Optional[str]
+    geometry: Optional[List[int]]
+
+
+class MagnetData(TypedDict, total=False):
+    """Magnet data structure."""
+    name: str
+    id: int
+    be: str
+    parts: List[int]
+
+
+class SiteData(TypedDict, total=False):
+    """Site data structure."""
+    name: str
+    id: int
+    magnets: List[int]
+    records: List[int]
+
+
+class RecordData(TypedDict, total=False):
+    """Record data structure."""
+    name: str
+    id: int
+    date: str
+    data: Dict[str, Any]
+
+
+class SimulationData(TypedDict, total=False):
+    """Simulation data structure."""
+    name: str
+    id: int
+    resource_type: str
+    resource_id: int
+    method: str
+    geometry: str
+    model: str
+    cooling: str
+
+
+# Type for resource types
+ResourceType = Union[
+    "material", "part", "magnet", "site", "record", "simulation", "attachment"
+]
+
+# ID type
+ResourceID = int
+```
+
+---
+
+### Phase 2: Add Type Hints to Core Modules
+
+#### Step 2.1: Type Hints for utils.py (High Priority)
+
+This is the most critical module - all API interactions go through it.
+
+**Pattern for get_list():**
+```python
+from typing import Dict, Optional
+from .types import SessionType, HeadersDict, ResourceType
+
+def get_list(
+    session: SessionType,
+    api_server: str,
+    headers: HeadersDict,
+    mtype: ResourceType = "magnets",
+    verbose: bool = False,
+    debug: bool = False,
+) -> Dict[str, int]:
+    """
+    Return list of ids for selected type.
+    
+    Args:
+        session: Requests session object
+        api_server: Base URL of MagnetDB API
+        headers: HTTP headers for authentication
+        mtype: Resource type to list
+        verbose: Enable verbose output
+        debug: Enable debug output
+        
+    Returns:
+        Dictionary mapping resource names to their IDs
+        
+    Raises:
+        APIError: If API request fails
+        AuthenticationError: If authentication fails
+    """
+    # ... implementation ...
+```
+
+**Pattern for get_object():**
+```python
+from typing import Optional
+from .types import SessionType, HeadersDict, ResourceType, ResourceID, JSONDict
+
+def get_object(
+    session: SessionType,
+    api_server: str,
+    headers: HeadersDict,
+    id: ResourceID,
+    mtype: ResourceType = "magnet",
+    verbose: bool = False,
+    debug: bool = False,
+) -> Optional[JSONDict]:
+    """
+    Return object data by ID.
+    
+    Args:
+        session: Requests session object
+        api_server: Base URL of MagnetDB API
+        headers: HTTP headers for authentication
+        id: Resource ID to retrieve
+        mtype: Resource type
+        verbose: Enable verbose output
+        debug: Enable debug output
+        
+    Returns:
+        Resource data dictionary, or None if not found
+        
+    Raises:
+        NotFoundError: If resource doesn't exist
+        APIError: If API request fails
+    """
+    # ... implementation ...
+```
+
+**Pattern for create_object():**
+```python
+from typing import Dict, Any, Optional
+
+def create_object(
+    session: SessionType,
+    api_server: str,
+    headers: HeadersDict,
+    mtype: ResourceType = "magnet",
+    data: Dict[str, Any] = {},
+    verbose: bool = False,
+    debug: bool = False,
+) -> ResourceID:
+    """
+    Create an object and return its ID.
+    
+    Args:
+        session: Requests session object
+        api_server: Base URL of MagnetDB API
+        headers: HTTP headers for authentication
+        mtype: Resource type to create
+        data: Resource data
+        verbose: Enable verbose output
+        debug: Enable debug output
+        
+    Returns:
+        ID of created resource
+        
+    Raises:
+        ResourceCreationError: If creation fails
+        ValidationError: If data is invalid
+        APIError: If API request fails
+    """
+    # ... implementation ...
+```
+
+**Apply same pattern to all utils.py functions:**
+- `update_object()` → returns `ResourceID`
+- `del_object()` → returns `None`
+- `add_data_to_object()` → returns `bool`
+- `get_data()` → returns `Optional[JSONDict]`
+- `post_data()` → returns `ResourceID`
+- etc.
+
+#### Step 2.2: Type Hints for Domain Modules
+
+**Pattern for part.py create():**
+```python
+from typing import Dict, Any, List, Optional, Union
+from .types import SessionType, HeadersDict, ResourceID, PartData
+
+def create(
+    session: SessionType,
+    api_server: str,
+    headers: HeadersDict,
+    data: PartData,
+    verbose: bool = False,
+    debug: bool = False,
+) -> ResourceID:
+    """
+    Create a part in MagnetDB.
+    
+    Args:
+        session: Requests session object
+        api_server: Base URL of MagnetDB API
+        headers: HTTP headers for authentication
+        data: Part data including name, material, type, etc.
+        verbose: Enable verbose output
+        debug: Enable debug output
+        
+    Returns:
+        ID of created part
+        
+    Raises:
+        InvalidDataError: If part data is invalid
+        ResourceCreationError: If creation fails
+    """
+    # ... implementation ...
+```
+
+**Apply to all domain modules:**
+- `magnet.py` - Use `MagnetData`
+- `site.py` - Use `SiteData`
+- `record.py` - Use `RecordData`
+- `material.py` - Use `MaterialData`
+- `geometry.py` - Add specific geometry types
+- `attachment.py` - Add file-related types
+
+#### Step 2.3: Type Hints for Computation Modules
+
+**Pattern for hoop_stress.py:**
+```python
+from typing import Optional, Union, Dict, List, Tuple
+import numpy as np
+import pandas as pd
+from numpy.typing import NDArray
+
+# Type aliases for arrays
+FloatArray = NDArray[np.float64]
+IntArray = NDArray[np.int32]
+
+def compute_hoop_stress(
+    geometry: Dict[str, Any],
+    material_properties: Dict[str, float],
+    current: Union[float, FloatArray],
+    temperature: Optional[FloatArray] = None,
+    verbose: bool = False,
+) -> pd.DataFrame:
+    """
+    Compute hoop stress for given geometry and conditions.
+    
+    Args:
+        geometry: Geometry definition with r, z coordinates
+        material_properties: Material properties (E, nu, alpha, etc.)
+        current: Current value(s) in Amperes
+        temperature: Temperature distribution (optional)
+        verbose: Enable verbose output
+        
+    Returns:
+        DataFrame with hoop stress results
+        
+    Raises:
+        InvalidParameterError: If parameters are invalid
+        ComputationError: If computation fails
+    """
+    # ... implementation ...
+```
+
+**Apply to all computation modules:**
+- `flow_params.py` - Add physics parameter types
+- `inductances.py` - Add electrical parameter types
+- `hoop_stress_parallel.py` - Reuse types from hoop_stress.py
+
+#### Step 2.4: Type Hints for CLI Module
+
+The CLI module is large (900+ lines) but type hints are still valuable:
+
+```python
+from typing import Optional, List
+import argparse
+
+def parse_args() -> argparse.Namespace:
+    """Parse command-line arguments."""
+    # ... implementation ...
+    return parser.parse_args()
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """
+    Main CLI entry point.
+    
+    Args:
+        argv: Command-line arguments (for testing)
+        
+    Returns:
+        Exit code (0 for success, non-zero for error)
+    """
+    try:
+        args = parse_args()
+        # ... implementation ...
+        return 0
+    except Exception as e:
+        # ... error handling ...
+        return 1
+```
+
+---
+
+### Phase 3: Advanced Type Hints
+
+#### Step 3.1: Add Protocol Definitions
+
+For duck-typed interfaces, use Protocol (Python 3.8+):
+
+```python
+from typing import Protocol, runtime_checkable
+
+@runtime_checkable
+class GeometryProvider(Protocol):
+    """Protocol for objects that provide geometry data."""
+    
+    def get_coordinates(self) -> Tuple[FloatArray, FloatArray]:
+        """Return (r, z) coordinate arrays."""
+        ...
+    
+    def get_volumes(self) -> FloatArray:
+        """Return volume array."""
+        ...
+
+# Usage:
+def compute_field(geometry: GeometryProvider) -> FloatArray:
+    r, z = geometry.get_coordinates()
+    # ... computation ...
+```
+
+#### Step 3.2: Add Generic Types
+
+For reusable components:
+
+```python
+from typing import TypeVar, Generic, Callable
+
+T = TypeVar('T')
+R = TypeVar('R')
+
+class APICache(Generic[T]):
+    """Generic cache for API responses."""
+    
+    def get(self, key: str) -> Optional[T]:
+        """Get cached value."""
+        ...
+    
+    def set(self, key: str, value: T) -> None:
+        """Set cached value."""
+        ...
+
+# Usage:
+magnet_cache: APICache[MagnetData] = APICache()
+```
+
+#### Step 3.3: Add Type Narrowing
+
+Use isinstance checks to narrow types:
+
+```python
+def process_material(material: Union[str, MaterialData, int]) -> MaterialData:
+    """Process material specification."""
+    if isinstance(material, str):
+        # Type narrowed to str
+        return fetch_material_by_name(material)
+    elif isinstance(material, int):
+        # Type narrowed to int
+        return fetch_material_by_id(material)
+    else:
+        # Type narrowed to MaterialData
+        return material
+```
+
+#### Step 3.4: Add Literal Types
+
+For string enums:
+
+```python
+from typing import Literal
+
+ResourceType = Literal[
+    "material", "part", "magnet", "site", "record", "simulation", "attachment"
+]
+
+def get_resource(
+    resource_type: ResourceType,
+    resource_id: int
+) -> JSONDict:
+    """Get resource by type and ID."""
+    # Type checker ensures only valid types are passed
+    ...
+```
+
+---
+
+### Phase 4: Integration and Validation
+
+#### Step 4.1: Run mypy Locally
+
+```bash
+# Install mypy and type stubs
+pip install mypy types-requests
+
+# Run mypy on entire package
+mypy python_magnetapi/
+
+# Run mypy with strict mode on specific modules
+mypy --strict python_magnetapi/utils.py
+
+# Generate HTML report
+mypy --html-report mypy-report python_magnetapi/
+```
+
+#### Step 4.2: Fix Type Errors Incrementally
+
+**Common patterns and fixes:**
+
+**1. Any type errors:**
+```python
+# Before:
+def process_data(data):  # Implicit Any
+    ...
+
+# After:
+def process_data(data: Dict[str, Any]) -> None:
+    ...
+```
+
+**2. Optional return values:**
+```python
+# Before:
+def find_item(name: str):
+    # Sometimes returns None
+    ...
+
+# After:
+def find_item(name: str) -> Optional[ItemData]:
+    ...
+```
+
+**3. Union types:**
+```python
+# Before:
+def handle_id(id):
+    # Can be str or int
+    ...
+
+# After:
+def handle_id(id: Union[str, int]) -> None:
+    ...
+```
+
+**4. Missing return statements:**
+```python
+# Before:
+def get_value() -> str:
+    if condition:
+        return "value"
+    # mypy error: Missing return statement
+
+# After:
+def get_value() -> str:
+    if condition:
+        return "value"
+    return "default"  # or raise exception
+```
+
+#### Step 4.3: Add Type Checking to CI/CD
+
+Create `.github/workflows/type-check.yml`:
+
+```yaml
+name: Type Check
+
+on: [push, pull_request]
+
+jobs:
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+      
+      - name: Run mypy
+        run: |
+          mypy python_magnetapi/ --no-error-summary
+      
+      - name: Upload report
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: mypy-report
+          path: mypy-report/
+```
+
+#### Step 4.4: Configure IDE Integration
+
+**VS Code settings.json:**
+```json
+{
+  "python.linting.mypyEnabled": true,
+  "python.linting.mypyArgs": [
+    "--config-file=pyproject.toml"
+  ],
+  "python.analysis.typeCheckingMode": "basic"
+}
+```
+
+**PyCharm:**
+- Enable mypy plugin from marketplace
+- Configure External Tools → mypy with `--config-file pyproject.toml`
+
+---
+
+### Phase 5: Documentation and Best Practices
+
+#### Step 5.1: Update Docstrings
+
+Add type information to docstrings (NumPy/Google style):
+
+```python
+def create_magnet(
+    session: SessionType,
+    data: MagnetData,
+    verbose: bool = False,
+) -> ResourceID:
+    """
+    Create a magnet in MagnetDB.
+    
+    Parameters
+    ----------
+    session : requests.Session
+        Active requests session with authentication
+    data : MagnetData
+        Magnet configuration including name, BE, parts list
+    verbose : bool, default=False
+        Enable verbose output
+        
+    Returns
+    -------
+    int
+        ID of created magnet
+        
+    Raises
+    ------
+    InvalidDataError
+        If magnet data is invalid or incomplete
+    ResourceCreationError
+        If creation fails on the server
+    APIError
+        If API request fails
+        
+    Examples
+    --------
+    >>> magnet_data = {"name": "M10", "be": "Bitter", "parts": [1, 2, 3]}
+    >>> magnet_id = create_magnet(session, magnet_data)
+    >>> print(f"Created magnet {magnet_id}")
+    """
+    # ... implementation ...
+```
+
+#### Step 5.2: Create Type Hints Documentation
+
+Add `docs/type_hints.rst`:
+
+```rst
+Type Hints Guide
+================
+
+python-magnetapi is fully typed using Python type hints (PEP 484).
+
+Type Stubs
+----------
+
+The package includes a ``py.typed`` marker, making it compatible with
+type checkers like mypy, pyright, and Pyre.
+
+Common Types
+------------
+
+The package defines common types in ``python_magnetapi.types``:
+
+.. code-block:: python
+
+    from python_magnetapi.types import (
+        MagnetData,
+        PartData,
+        SiteData,
+        ResourceID,
+    )
+
+Type Checking Your Code
+-----------------------
+
+To type-check code using python-magnetapi:
+
+.. code-block:: bash
+
+    pip install mypy types-requests
+    mypy your_script.py
+
+Using Type Hints
+----------------
+
+All public API functions include type hints:
+
+.. code-block:: python
+
+    from python_magnetapi import utils
+    from python_magnetapi.types import SessionType, HeadersDict
+    
+    def my_function(session: SessionType, headers: HeadersDict) -> None:
+        magnets = utils.get_list(session, "http://api", headers, "magnet")
+        # Type checker knows magnets is Dict[str, int]
+        for name, id in magnets.items():
+            print(f"{name}: {id}")
+
+Type Narrowing
+--------------
+
+Use isinstance() for type narrowing:
+
+.. code-block:: python
+
+    from typing import Union
+    
+    def process_input(value: Union[str, int, dict]) -> str:
+        if isinstance(value, str):
+            return value  # Type narrowed to str
+        elif isinstance(value, int):
+            return str(value)  # Type narrowed to int
+        else:
+            return value["name"]  # Type narrowed to dict
+```
+
+#### Step 5.3: Add Type Checking to Development Workflow
+
+Update `README.md`:
+
+```markdown
+## Development
+
+### Type Checking
+
+This project uses type hints and mypy for static type checking:
+
+```bash
+# Run type checker
+mypy python_magnetapi/
+
+# Run type checker on specific module
+mypy python_magnetapi/utils.py --strict
+
+# Generate HTML report
+mypy --html-report mypy-report python_magnetapi/
+```
+
+### Pre-commit Hooks
+
+Install pre-commit hooks for automatic type checking:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+```
+
+#### Step 5.4: Create Type Hints Best Practices Guide
+
+Add to `docs/contributing.rst`:
+
+```rst
+Type Hints Guidelines
+---------------------
+
+When adding new code:
+
+1. **Always add type hints** to function signatures
+2. **Use specific types** over ``Any`` when possible
+3. **Document types** in docstrings
+4. **Run mypy** before committing
+5. **Add type stubs** for external libraries if needed
+
+Examples:
+
+Good:
+    .. code-block:: python
+    
+        def fetch_data(id: int, timeout: float = 30.0) -> Optional[dict]:
+            \"\"\"Fetch data by ID.\"\"\"
+            ...
+
+Bad:
+    .. code-block:: python
+    
+        def fetch_data(id, timeout=30.0):  # No type hints
+            ...
+```
+
+---
+
+## Implementation Guidelines
+
+### Incremental Approach
+
+1. **Start with types.py** - Define all TypedDict classes first
+2. **Complete utils.py** - Core module, type everything
+3. **One domain module at a time** - part.py, then magnet.py, etc.
+4. **Computation modules** - More complex types, numpy arrays
+5. **CLI module last** - Large but straightforward
+6. **Enable strict mode gradually** - Per module in mypy config
+
+### Type Hint Priorities
+
+**High Priority (Must Have):**
+- Function parameters and return types
+- Public API functions
+- TypedDict for structured data
+
+**Medium Priority (Should Have):**
+- Class attributes
+- Instance variables
+- Local variables in complex functions
+
+**Low Priority (Nice to Have):**
+- Private functions (can use `# type: ignore` sparingly)
+- Very dynamic code (use `Any` if necessary)
+
+### Dealing with Untyped Dependencies
+
+For dependencies without type stubs:
+
+```toml
+[[tool.mypy.overrides]]
+module = "untyped_library.*"
+ignore_missing_imports = true
+```
+
+Or create stub files in `stubs/` directory.
+
+### Common Type Patterns
+
+**Optional values:**
+```python
+from typing import Optional
+
+def find_by_name(name: str) -> Optional[dict]:
+    # Returns dict or None
+    ...
+```
+
+**Union types:**
+```python
+from typing import Union
+
+def process(value: Union[str, int, dict]) -> str:
+    ...
+```
+
+**Lists and Dicts:**
+```python
+from typing import List, Dict
+
+def get_names() -> List[str]:
+    ...
+
+def get_mapping() -> Dict[str, int]:
+    ...
+```
+
+**Callbacks:**
+```python
+from typing import Callable
+
+def apply(func: Callable[[int], str]) -> str:
+    return func(42)
+```
+
+---
+
+## Testing Type Hints
+
+### Create Type Checker Tests
+
+Create `tests/test_types.py`:
+
+```python
+"""Tests for type hints (these test the types, not runtime behavior)."""
+
+from python_magnetapi import utils
+from python_magnetapi.types import MagnetData, PartData
+
+# Type checker tests (use mypy to validate)
+def test_magnet_data_structure() -> None:
+    """Test MagnetData structure."""
+    magnet: MagnetData = {
+        "name": "M10",
+        "id": 1,
+        "be": "Bitter",
+        "parts": [1, 2, 3],
+    }
+    assert magnet["name"] == "M10"
+
+
+def test_utils_get_list_types() -> None:
+    """Test get_list type signature."""
+    # This tests that the types are correct
+    from unittest.mock import Mock
+    session = Mock()
+    headers = {"Authorization": "Bearer token"}
+    
+    # Type checker verifies these calls are valid
+    result = utils.get_list(session, "http://api", headers, "magnet")
+    reveal_type(result)  # Should be Dict[str, int]
+```
+
+### Use reveal_type for Debugging
+
+```python
+from typing import reveal_type
+
+def test_function() -> None:
+    result = some_function()
+    reveal_type(result)  # mypy will print the inferred type
+```
+
+---
+
+## Success Criteria
+
+✅ **Implementation Complete When:**
+1. All public functions have full type hints (parameters + return)
+2. `py.typed` marker file exists and is included in package
+3. mypy configuration in pyproject.toml
+4. All modules pass mypy with `check_untyped_defs = true`
+5. At least core modules (utils, exceptions) pass with `--strict`
+6. TypedDict definitions for all structured data
+7. Type checking integrated in CI/CD
+8. Documentation includes type hints guide
+9. IDE integration configured (VS Code, PyCharm)
+10. Zero critical type errors in mypy output
+
+✅ **Quality Metrics:**
+- mypy success rate ≥ 95% (some `# type: ignore` acceptable)
+- All public APIs fully typed
+- Type coverage ≥ 80% (use mypy --html-report to track)
+- Zero untyped function definitions in core modules
+- Documentation includes type information
+
+---
+
+## Troubleshooting Common Issues
+
+### Issue 1: Third-party Library Without Stubs
+
+**Solution:** Add to mypy overrides:
+```toml
+[[tool.mypy.overrides]]
+module = "problematic_library.*"
+ignore_missing_imports = true
+```
+
+### Issue 2: Complex Type that mypy Can't Infer
+
+**Solution:** Use explicit type cast:
+```python
+from typing import cast, Dict
+
+data = get_complex_data()
+typed_data = cast(Dict[str, Any], data)
+```
+
+### Issue 3: Dynamic Attribute Access
+
+**Solution:** Use TypedDict or define `__getattr__`:
+```python
+def __getattr__(self, name: str) -> Any:
+    ...
+```
+
+### Issue 4: Too Many Type Errors
+
+**Solution:** Start with lenient config, tighten gradually:
+```toml
+[tool.mypy]
+disallow_untyped_defs = false  # Initially
+check_untyped_defs = true      # Check even untyped
+```
+
+---
+
+## References
+
+**PEP References:**
+- PEP 484: Type Hints
+- PEP 526: Syntax for Variable Annotations
+- PEP 544: Protocols
+- PEP 561: Distributing and Packaging Type Information
+- PEP 585: Type Hinting Generics In Standard Collections (Python 3.9+)
+- PEP 604: Union Type as `X | Y` (Python 3.10+)
+
+**Tools:**
+- mypy: http://mypy-lang.org/
+- typing module docs: https://docs.python.org/3/library/typing.html
+- mypy cheat sheet: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
+
+**Related Files:**
+- `python_magnetapi/types.py` (new)
+- `python_magnetapi/py.typed` (new)
+- `pyproject.toml` (update [tool.mypy])
+- All `.py` files in python_magnetapi/
+- `tests/test_types.py` (new)
+- `docs/type_hints.rst` (new)
+
+---
+
+## Notes for Implementation
+
+1. **Start small** - Complete one module end-to-end before moving to next
+2. **Test frequently** - Run mypy after each function is typed
+3. **Use reveal_type()** - Debug type inference issues
+4. **Don't overuse Any** - Try to use specific types, but `Any` is better than no hints
+5. **TypedDict is powerful** - Use for structured API responses
+6. **Protocol for duck typing** - Better than structural subtyping
+7. **Consider backwards compatibility** - Type hints don't break runtime (Python 3.7+)
+
+## Gradual Typing Strategy
+
+**Week 1:** Foundation
+- Create types.py, py.typed, mypy config
+- Type hints for utils.py
+- Basic CI integration
+
+**Week 2:** Domain modules
+- Type hints for all domain modules
+- TypedDict for all data structures  
+- Documentation updates
+
+**Week 3:** Computation & CLI
+- Type hints for computation modules
+- Type hints for CLI
+- Comprehensive tests
+
+**Week 4:** Polish & Strict mode
+- Enable strict mode for core modules
+- Fix all remaining type errors
+- Complete documentation
+
+## Document Version
+
+**Version**: 1.0  
+**Created**: 2026-03-12  
+**Task**: Type Hints and Static Analysis Setup  
+**Priority**: Tier 1 (High Impact, Foundation) - Partial  
+**Status**: Ready for implementation  
+**Dependencies**: Should be done after or in parallel with Error Handling Framework
diff --git a/pyproject.toml b/pyproject.toml
index aab9df6..c9a92a1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,30 +1,92 @@
-[tool.poetry]
-name = "python_magnetapi"
-version = "0.1.0"
-description = ""
-authors = ["Christophe Trophime <christophe.trophime@lncmi.cnrs.fr>",
-           "Remi Caumette <remicaumette@icloud.com>"
-          ]
-
-[tool.poetry.dependencies]
-python = "^3.11"
-requests = "^2.32.3"
-pandas = "^2.2.1"
-numpy = "^2.2.1"
-scipy = "^1.14.1"
-param = "^1.12.0"
-#magnettools = {path = "/home/feelpp/magnettools-1.1.0/build/Python/dist/MagnetTools-1.0.7-py3-none-any.whl"}
-#magnettools = "^1.1.0)
-#python-magnetgeo = {path = "python_magnetsgeo"}
-python-magnetsetup = {path = "../python_magnetsetup", develop = true }
-#python-magnetrun = {path = "../python_magnetrun"}
-rich = "^9.11.0"
-
-
-
-[tool.poetry.dev-dependencies]
-pytest = "^8.2.0"
-
 [build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-magnetapi"
+version = "0.1.1"
+description = "Python CLI for magnetDB - utilities to interact with MagnetDB"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Christophe Trophime", email = "christophe.trophime@lncmi.cnrs.fr"},
+    {name = "Remi Caumette", email = "remicaumette@icloud.com"}
+]
+maintainers = [
+    {name = "Christophe Trophime", email = "christophe.trophime@lncmi.cnrs.fr"}
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "requests>=2.32.3",
+    "pandas>=2.2.1",
+    "numpy>=2.2.1",
+    "scipy>=1.14.1",
+    "param>=1.12.0",
+    "rich>=9.11.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.2.0",
+    "pytest-cov",
+]
+doc = [
+    "sphinx>=5.0.0",
+    "sphinx-rtd-theme",
+]
+full = [
+    "python-magnetsetup",
+    "python-magnetcooling",
+    "magnettools"
+]
+
+[project.scripts]
+python_magnetapi = "python_magnetapi.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/MagnetDB/python_magnetapi"
+Repository = "https://github.com/MagnetDB/python_magnetapi"
+Documentation = "https://github.com/MagnetDB/python_magnetapi"
+"Bug Tracker" = "https://github.com/MagnetDB/python_magnetapi/issues"
+
+[tool.setuptools]
+packages = [
+    "python_magnetapi",
+    "python_magnetapi.cli",
+    "python_magnetapi.cli.commands",
+]
+
+[tool.setuptools.package-data]
+python_magnetapi = ["py.typed"]
+
+# Pytest configuration
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+# Coverage configuration
+[tool.coverage.run]
+source = ["python_magnetapi"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
\ No newline at end of file
diff --git a/python_magnetapi/__init__.py b/python_magnetapi/__init__.py
index 4f91bd8..5767765 100755
--- a/python_magnetapi/__init__.py
+++ b/python_magnetapi/__init__.py
@@ -2,4 +2,19 @@
 
 __author__ = """Christophe Trophime"""
 __email__ = 'christophe.trophime@lncmi.cnrs.fr'
-__version__ = '0.0.1'
+
+
+# Version is read from package metadata (defined in pyproject.toml)
+# This ensures a single source of truth for the version number
+try:
+    from importlib.metadata import version, PackageNotFoundError
+except ImportError:
+    # Fallback for Python < 3.8 (though we require 3.11+)
+    from importlib_metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("python-magnetapi")
+except PackageNotFoundError:
+    # Package not installed (e.g., running from source without install)
+    # This is expected during development before running `pip install -e .`
+    __version__ = "0.0.0+unknown"
diff --git a/python_magnetapi/attachment.py b/python_magnetapi/attachment.py
index ee5675e..d2b2e14 100644
--- a/python_magnetapi/attachment.py
+++ b/python_magnetapi/attachment.py
@@ -3,19 +3,31 @@
 """
 
 import os
+import requests
+
 from . import utils
 
 
 def create(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: str,
     verbose: bool = False,
     debug: bool = False,
-):
-    """
-    create an attachment from a data dictionnary
+) -> int | None:
+    """Upload a local file and create an attachment record.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: local file path to upload
+        verbose: enable verbose output
+        debug: enable debug output
+
+    Returns:
+        ID of the newly created attachment, or None if upload failed.
     """
     print(f"attachment/create: data={data}")
 
@@ -28,7 +40,7 @@ def create(
 
     # create an attachment
     response = utils.post_file(
-        session, api_server, headers, files, "attachment", verbose, debug
+        session, api_server, headers, files, "attachment"
     )
     if response is None:
         print(f"{data['name']} failed to create attachment {data}")
diff --git a/python_magnetapi/cli.py b/python_magnetapi/cli.py
deleted file mode 100644
index 2b6641a..0000000
--- a/python_magnetapi/cli.py
+++ /dev/null
@@ -1,684 +0,0 @@
-#! /usr/bin/python3
-
-"""
-Connect to MagnetDB site
-"""
-
-import os
-import sys
-import json
-import argparse
-from time import sleep
-import requests
-import requests.exceptions
-
-from . import utils
-
-api_server = os.getenv("MAGNETDB_API_SERVER") or "api.magnetdb-dev.local"
-api_key = os.getenv("MAGNETDB_API_KEY")
-
-
-def main():
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--server", help="specify server", type=str, default=api_server)
-    parser.add_argument("--port", help="specify port", type=int, default=8000)
-    parser.add_argument("--debug", help="activate debug mode", action="store_true")
-    parser.add_argument("--https", help="activate https mode", action="store_true")
-
-    subparsers = parser.add_subparsers(
-        title="commands", dest="command", help="sub-command help"
-    )
-    parser_list = subparsers.add_parser("list", help="list help")
-    parser_view = subparsers.add_parser("view", help="view help")
-    parser_create = subparsers.add_parser("create", help="create help")
-    parser_delete = subparsers.add_parser("delete", help="create help")
-
-    parser_setup = subparsers.add_parser("setup", help="setup help")
-    parser_run = subparsers.add_parser("run", help="run help")
-    parser_compute = subparsers.add_parser("compute", help="compute help")
-    parser_post = subparsers.add_parser("process", help="process help")
-    # pull data from srv data
-    # push data to srv data
-    # get object as json???
-
-    # list subcommand
-    parser_list.add_argument(
-        "--mtype",
-        help="select object type",
-        type=str,
-        choices=[
-            "material",
-            "part",
-            "magnet",
-            "site",
-            "record",
-            "server",
-            "simulation",
-        ],
-        default="magnet",
-    )
-
-    # view subcommand
-    parser_view.add_argument(
-        "--mtype",
-        help="select object type",
-        type=str,
-        choices=[
-            "material",
-            "part",
-            "magnet",
-            "site",
-            "record",
-            "server",
-            "simulation",
-        ],
-        default="magnet",
-    )
-    parser_view.add_argument(
-        "--name", help="specify an object name", type=str, default="None"
-    )
-
-    # create subcommand
-    parser_create.add_argument(
-        "--mtype",
-        help="select object type",
-        type=str,
-        choices=[
-            "material",
-            "part",
-            "magnet",
-            "site",
-            "record",
-            "server",
-            "simulation",
-        ],
-        default="magnet",
-    )
-    # parser_create.add_argument("--data", help="specify data as dict", type=json.loads)
-    # parser_create.add_argument("--file", help="specify data as file", type=str)
-    command_group = parser_create.add_mutually_exclusive_group()
-    command_group.add_argument(
-        "--data", help="load data from dict", type=json.loads, nargs="?"
-    )
-    command_group.add_argument(
-        "--file", help="load data from file", type=str, nargs="?"
-    )
-
-    # delete subcommand
-    parser_delete.add_argument(
-        "--mtype",
-        help="select object type",
-        type=str,
-        choices=[
-            "material",
-            "part",
-            "magnet",
-            "site",
-            "record",
-            "server",
-            "simulation",
-        ],
-        default="magnet",
-    )
-    parser_delete.add_argument(
-        "--name", help="specify an object name", type=str, default="None"
-    )
-
-    # setup subcommand
-    parser_setup.add_argument(
-        "--mtype",
-        help="select object type",
-        type=str,
-        choices=[
-            "magnet",
-            "site",
-        ],
-        default="magnet",
-    )
-    parser_setup.add_argument(
-        "--name", help="specify an object name", type=str, default="None"
-    )
-    parser_setup.add_argument(
-        "--current",
-        help="specify requested current (default: 31kA)",
-        nargs="+",
-        metavar="Current",
-        type=float,
-        default=[31.0e3],
-    )
-
-    parser_setup.add_argument(
-        "--geometry",
-        help="select a method",
-        type=str,
-        choices=["Axi", "3D"],
-        default="Axi",
-    )
-    parser_setup.add_argument(
-        "--static", help="activate static mode", action="store_true"
-    )
-    parser_setup.add_argument(
-        "--nonlinear", help="activate non_linear", action="store_true"
-    )
-    parser_setup.add_argument(
-        "--method", help="select a method", type=str, default="cfpdes"
-    )
-    parser_setup.add_argument(
-        "--model", help="select a model", type=str, default="thmagel_hcurl"
-    )
-    parser_setup.add_argument(
-        "--cooling",
-        help="select a cooling mode",
-        type=str,
-        choices=["mean", "meanH", "grad", "gradH", "gradHZ"],
-        default="meanH",
-    )
-    parser_setup.add_argument(
-        "--wd",
-        help="select directory to store setup/simulation results",
-        type=str,
-        default=".",
-    )
-
-    # run subcommand
-    parser_run.add_argument(
-        "--mtype",
-        help="select object type",
-        type=str,
-        choices=[
-            "magnet",
-            "site",
-        ],
-        default="magnet",
-    )
-    parser_run.add_argument(
-        "--simu_id", help="select simulation id", type=int, default=-1
-    )
-    parser_run.add_argument(
-        "--wd",
-        help="select directory to store setup/simulation results",
-        type=str,
-        default=".",
-    )
-
-    parser_run.add_argument(
-        "--compute_server", help="choose compute node", type=str, default="calcul22"
-    )
-    parser_run.add_argument("--np", help="choose number of procs", type=int, default=4)
-
-    # stats subcommand
-    # compute
-    parser_compute.add_argument(
-        "--mtype",
-        help="select object type",
-        type=str,
-        choices=[
-            "part",
-            "magnet",
-            "site",
-            "record",
-        ],
-        default="magnet",
-    )
-    parser_compute.add_argument(
-        "--name", help="specify an object name", type=str, default="None"
-    )
-    parser_compute.add_argument(
-        "--inductances",
-        help="activate self and mutual inductances",
-        action="store_true",
-    )
-    parser_compute.add_argument(
-        "--flow_params", help="activate flow params", action="store_true"
-    )
-    parser_compute.add_argument(
-        "--hoop_stress", help="activate hoop stress history", action="store_true"
-    )
-    parser_compute.add_argument(
-        "--samples", help="specify number of samples to consider", type=int, default=20
-    )
-
-    # get args
-    args = parser.parse_args()
-    print(f"args: {args}")
-
-    # main
-    otype = args.mtype
-    headers = {"Authorization": os.getenv("MAGNETDB_API_KEY")}
-    web = f"http://{args.server}:{args.port}"
-    verify = True
-    if args.https:
-        web = f"https://{args.server}"
-        verify = "/etc/ssl/certs"
-
-    print(f"server: {web}, verify={verify}")
-    with requests.Session() as s:
-        # print("requests")
-        r = s.get(f"{web}/api/{otype}s", headers=headers, verify=True)
-        # print(f"done (r={r}, isOk={r.status_code == requests.codes.ok}", flush=True)
-        if not r.status_code == requests.codes.ok:
-            response = r.json()
-            if "detail" in response and response["detail"] == "Forbidden.":
-                raise RuntimeError(
-                    f"{args.server} : wrong credentials - check MAGNETDB_API_KEY"
-                )
-            raise RuntimeError(f"{args.server} : unknown reason")
-        # print(f"s.verify={s.verify}")
-
-        if args.command == "list":
-            ids = utils.get_list(s, web, headers=headers, mtype=otype, debug=args.debug)
-            print(f"{args.mtype.upper()}: found {len([*ids])} items")
-            for obj in ids:
-                print(f"{args.mtype.upper()}: {obj}, id={ids[obj]}")
-
-        if args.command == "view":
-            # add a filter for view
-            ids = utils.get_list(s, web, headers=headers, mtype=otype, debug=args.debug)
-            print(f"view: ids={ids}")
-            if args.name in ids:
-                response = utils.get_object(
-                    web,
-                    headers=headers,
-                    mtype=otype,
-                    id=ids[args.name],
-                    debug=args.debug,
-                )
-                print(f"{args.name}:\n{json.dumps(response, indent=4)}")
-            else:
-                raise RuntimeError(
-                    f"{args.server} : cannot found {args.name} in {args.mtype.upper()} objects"
-                )
-
-        if args.command == "create":
-            # if server, try to guess some values by running appropriate commands on the server
-            # if part|magnet|site need to attach some extra files and upload then to minio
-            # if part|magnet|site update associative tables
-            # if record upload file to minio
-
-            data = {}
-            if args.data:
-                print(f"create: data={json.dumps(args.data, indent=4, default=str)}")
-                data = args.data
-                # how to validate data
-            if args.file:
-                print(f"create: file={args.file}")
-                with open(args.file, "r") as f:
-                    data = json.loads(f.read())
-                    print(f"data: {data}")
-
-            from .material import create as mat_create
-            from .site import create as site_create
-            from .magnet import create as magnet_create
-            from .part import create as part_create
-            from .record import create as record_create
-
-            ocreate = {
-                "material": mat_create,
-                "site": site_create,
-                "magnet": magnet_create,
-                "part": part_create,
-                "record": record_create,
-            }
-
-            id = ocreate[otype](
-                s, web, headers=headers, data=data, verbose=True, debug=args.debug
-            )
-
-            # create material if not already done then part
-            if id is None:
-                print(f"create: type={otype}, name={data['name']} not implemented")
-
-        if args.command == "delete":
-            ids = utils.get_list(s, web, headers=headers, mtype=otype, debug=args.debug)
-            if args.name in ids:
-                print(f"{args.name}: id={ids[args.name]}")
-                response = utils.del_object(
-                    s,
-                    web,
-                    headers=headers,
-                    mtype=otype,
-                    id=ids[args.name],
-                    verbose=True,
-                    debug=args.debug,
-                )
-            else:
-                raise RuntimeError(
-                    f"{args.server} : cannot found {args.name} in {args.mtype.upper()} objects"
-                )
-
-        if args.command == "setup":
-            if otype not in ["site", "magnet"]:
-                raise RuntimeError(
-                    f"unexpected type {args.mtype} in run subcommand - expect mtype=site|magnet"
-                )
-
-            # Check consistant method and model
-            r = s.get(f"{web}/api/simulations/models", headers=headers)
-            response = r.json()
-            if r.status_code != 200:
-                raise RuntimeError(
-                    f'setup: cannot get models dict {response["detail"]}'
-                )
-
-            available_methods = [
-                data["method"] for data in response if data["geometry"] == args.geometry
-            ]
-            available_methods = list(set(available_methods))
-            # print(f"available methods={available_methods}")
-            if args.method not in available_methods:
-                raise RuntimeError(
-                    f"{args.method}: unknown method for {args.geometry} geometry - supported values are {available_methods}"
-                )
-
-            available_models = {}
-            for method in available_methods:
-                available_models[method] = [
-                    data["model"]
-                    for data in response
-                    if data["method"] == args.method
-                    and data["geometry"] == args.geometry
-                ]
-            # print(f"available models={available_models}")
-            if args.model not in available_models[args.method]:
-                raise RuntimeError(
-                    f"{args.model}: unknown model for {args.method} and {args.geometry} geometry - supported values are {available_models[args.method]}"
-                )
-            ids = utils.get_list(s, web, headers=headers, mtype=otype, debug=args.debug)
-            if args.name in ids:
-                response = utils.get_object(
-                    s,
-                    web,
-                    headers=headers,
-                    mtype=otype,
-                    id=ids[args.name],
-                    debug=args.debug,
-                )
-            else:
-                raise RuntimeError(
-                    f"run: cannot found {args.name} in {args.mtype.upper()} objects"
-                )
-
-            # TODO: add flow_params
-            # use flow_params from magnetsetup if no records attached to object id
-            # otherwise try to get flow_params from db or create it
-            # TODO:  add current_data
-            # currents: List[CreatePayloadCurrent]
-            # with CreatePayloadCurrent(BaseModel): magnet_id: int, value: float
-            object = utils.get_object(
-                s,
-                web,
-                headers,
-                ids[args.name],
-                mtype=otype,
-                verbose=True,
-                debug=args.debug,
-            )
-
-            currents = []
-            if otype == "site":
-                if len(args.current) != len(object["site_magnets"]):
-                    raise RuntimeError(
-                        f"args.current contains {len(args.current)} values - should have {len(object['site_magnets'])} values"
-                    )
-
-                for i, magnet in enumerate(object["site_magnets"]):
-                    print(f"current[{i}]: magnet={magnet}")
-                    current_data = {
-                        "magnet_id": magnet["magnet_id"],
-                        "value": args.current[i],
-                    }
-                    currents.append(current_data)
-            else:
-                if len(args.current) != 1:
-                    raise RuntimeError(
-                        f"args.current contains {len(args.current)} values - should have 1 value"
-                    )
-
-                current_data = {
-                    "magnet_id": ids[args.name],
-                    "value": args.current[0],
-                }
-                currents.append(current_data)
-            print(f"currents: {currents}")
-
-            sim_data = {
-                "resource_type": args.mtype,
-                "resource_id": ids[args.name],
-                "method": args.method,
-                "model": args.model,
-                "geometry": args.geometry,
-                "cooling": args.cooling,
-                "static": args.static,
-                "non_linear": args.nonlinear,
-                "currents": currents,
-            }
-
-            # check parameters consistency: see allowed_methods in
-            # create simu
-            simu_id = utils.create_object(
-                s,
-                web,
-                headers=headers,
-                mtype="simulation",
-                data=sim_data,
-                verbose=True,
-                debug=args.debug,
-            )
-            if simu_id is None:
-                raise RuntimeError(
-                    f"failed to create simulation for {args.mtype} {args.name} in run subcommand"
-                )
-
-            # run setup
-            print("Starting setup...")
-            r = s.post(f"{web}/api/simulations/{simu_id}/run_setup", headers=headers)
-
-            while True:
-                simulation = utils.get_object(
-                    s,
-                    web,
-                    headers=headers,
-                    mtype="simulation",
-                    id=simu_id,
-                    debug=args.debug,
-                )
-                if simulation["setup_status"] in ["failed", "done"]:
-                    break
-                sleep(10)
-
-            print(f"Setup done: simulation={simulation}")
-            print(f'Setup done: status={simulation["setup_status"]}')
-            if simulation["setup_status"] == "failed":
-                sys.exit(1)
-
-            setup_arch_id = simulation["setup_output_attachment"]["id"]
-            setup_filename = utils.download(
-                s,
-                web,
-                headers=headers,
-                attach=setup_arch_id,
-                wd=args.wd,
-                debug=args.debug,
-            )
-            print(f"{setup_filename} downloaded")
-            print(f'simulation {simulation["id"]} setup done')
-
-        if args.command == "run":
-            # find simu_id
-            simu = utils.get_object(
-                s,
-                web,
-                headers=headers,
-                id=args.simu_id,
-                mtype="simulation",
-                debug=args.debug,
-            )
-            if simu is None:
-                raise RuntimeError(
-                    f"run : cannot find {args.simu_id} simulation - please check simulations list"
-                )
-
-            # Run simu with ssh
-            ids = utils.get_list(
-                s, web, headers=headers, mtype="server", debug=args.debug
-            )
-            if args.compute_server in ids:
-                server_id = ids[args.compute_server]
-            else:
-                raise RuntimeError(
-                    f"{args.server} : cannot found {args.name} in server objects"
-                )
-
-            # TODO get server data - aka np
-            server_data = utils.get_object(
-                s,
-                web,
-                headers=headers,
-                mtype="server",
-                id=server_id,
-                debug=args.debug,
-            )
-
-            print("Starting simulation...")
-            r = s.post(
-                f"{web}/api/simulations/{args.simu_id}/run",
-                data={"server_id": server_id},
-                headers=headers,
-            )
-            while True:
-                simulation = utils.get_object(
-                    s,
-                    web,
-                    headers=headers,
-                    mtype="simulation",
-                    id=simu_id,
-                    debug=args.debug,
-                )
-                if simulation["status"] in ["failed", "done"]:
-                    break
-                sleep(10)
-            print(f'Simulation done: status={simulation["status"]}')
-
-            if simulation["status"] == "failed":
-                sys.exit(1)
-
-            print(f"simulation={simulation}")
-            simu_arch_id = simulation["output_attachment"]["id"]
-            simu_filename = utils.download(
-                s,
-                web,
-                headers=headers,
-                attach=simu_arch_id,
-                wd=args.wd,
-                debug=args.debug,
-            )
-            print(f"{simu_filename} downloaded")
-            print(f'simulation {simulation["id"]} done')
-
-        if args.command == "compute":
-            if args.inductances:
-                if otype in ["part"]:
-                    raise RuntimeError(
-                        f"unexpected type {args.mtype} in compute subcommand inductances"
-                    )
-
-                ids = utils.get_list(
-                    s, web, headers=headers, mtype=otype, debug=args.debug
-                )
-                if args.name in ids:
-                    response = utils.get_object(
-                        s,
-                        web,
-                        headers=headers,
-                        mtype=otype,
-                        id=ids[args.name],
-                        debug=args.debug,
-                    )
-                    from . import inductances
-
-                    print("Compute Self/Mutual inductances")
-                    inductances.compute(
-                        s,
-                        api_server,
-                        headers,
-                        oid=ids[args.name],
-                        mtype=otype,
-                        debug=args.debug,
-                    )
-                else:
-                    raise RuntimeError(
-                        f"unexpected name {args.name}: no such object found in {otype} list: {ids.keys()}"
-                    )
-
-            if args.flow_params:
-                if otype != "magnet":
-                    raise RuntimeError(
-                        f"unexpected type {args.mtype} in compute subcommand flow_params - should be magnet"
-                    )
-
-                ids = utils.get_list(
-                    s, web, headers=headers, mtype=otype, debug=args.debug
-                )
-                if args.name in ids:
-                    response = utils.get_object(
-                        s,
-                        web,
-                        headers=headers,
-                        mtype=otype,
-                        id=ids[args.name],
-                        debug=args.debug,
-                    )
-                    from . import flow_params
-
-                    flow_params.compute(
-                        s,
-                        web,
-                        headers=headers,
-                        oid=ids[args.name],
-                        samples = args.samples,
-                        debug=args.debug,
-                    )
-                else:
-                    raise RuntimeError(
-                        f"{args.server} : cannot found {args.name} in {args.mtype.upper()} objects"
-                    )
-
-            if args.hoop_stress:
-                if otype not in ["part"]:
-                    raise RuntimeError(
-                        f"unexpected type {args.mtype} in compute subcommand hoop_stress"
-                    )
-
-                ids = utils.get_list(
-                    s, web, headers=headers, mtype=otype, debug=args.debug
-                )
-                if args.name in ids:
-                    response = utils.get_object(
-                        s,
-                        web,
-                        headers=headers,
-                        mtype=otype,
-                        id=ids[args.name],
-                        debug=args.debug,
-                    )
-                    from . import hoop_stress
-
-                    hoop_stress.compute(
-                        s,
-                        web,
-                        headers=headers,
-                        mtype=otype,
-                        oid=ids[args.name],
-                        debug=args.debug,
-                    )
-                else:
-                    raise RuntimeError(
-                        f"{args.server} : cannot found {args.name} in {args.mtype.upper()} objects"
-                    )
-
-        if args.command == "post":
-            print("post: not implemented")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/python_magnetapi/cli/__init__.py b/python_magnetapi/cli/__init__.py
new file mode 100644
index 0000000..35b2ea8
--- /dev/null
+++ b/python_magnetapi/cli/__init__.py
@@ -0,0 +1,57 @@
+#! /usr/bin/python3
+
+"""CLI for interacting with MagnetDB."""
+
+import os
+import sys
+from typing import List, Optional
+
+from .parser import create_parser
+from .context import CLIContext
+from .commands import COMMANDS
+from ..exceptions import MagnetAPIException, AuthenticationError
+from ..utils import setup_logging
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Main CLI entry point.
+
+    Args:
+        argv: Command-line arguments (for testing); uses sys.argv if None
+
+    Returns:
+        Exit code (0 for success)
+    """
+    parser = create_parser(COMMANDS)
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 1
+
+    log_level = "DEBUG" if args.debug else args.log_level
+    setup_logging(level=log_level, log_file=args.log_file)
+
+    api_key = os.getenv("MAGNETDB_API_KEY")
+    if not api_key:
+        raise AuthenticationError(
+            "API key not found. Please set the MAGNETDB_API_KEY environment variable. "
+            "You can obtain your API key from your profile page on MagnetDB."
+        )
+
+    context = CLIContext(
+        server=args.server,
+        port=args.port,
+        api_key=api_key,
+        debug=args.debug,
+        https=args.https,
+    )
+
+    command = COMMANDS[args.command]()
+
+    with context:
+        return command.execute(args, context)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/python_magnetapi/cli/__main__.py b/python_magnetapi/cli/__main__.py
new file mode 100644
index 0000000..794c82d
--- /dev/null
+++ b/python_magnetapi/cli/__main__.py
@@ -0,0 +1,6 @@
+"""Allow python -m python_magnetapi.cli execution."""
+
+from . import main
+import sys
+
+sys.exit(main())
diff --git a/python_magnetapi/cli/base.py b/python_magnetapi/cli/base.py
new file mode 100644
index 0000000..4113893
--- /dev/null
+++ b/python_magnetapi/cli/base.py
@@ -0,0 +1,131 @@
+"""Base command handler class."""
+
+from abc import ABC, abstractmethod
+import argparse
+from typing import Optional, List, Dict
+
+from .context import CLIContext
+from .. import utils
+from ..exceptions import ResourceNotFoundError, ValidationError
+
+# All resource types supported by MagnetDB
+OBJECT_TYPES: List[str] = [
+    "material",
+    "part",
+    "magnet",
+    "site",
+    "record",
+    "server",
+    "simulation",
+]
+
+
+class BaseCommand(ABC):
+    """Base class for all CLI command handlers.
+
+    Subclasses should implement:
+        - name: Command name
+        - help: Command help text
+        - configure_parser(): Add command-specific arguments
+        - execute(): Execute command logic
+    """
+
+    name: str = ""
+    help: str = ""
+
+    @abstractmethod
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure argument parser for this command.
+
+        Args:
+            parser: Subparser for this command
+        """
+        pass
+
+    @abstractmethod
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute the command.
+
+        Args:
+            args: Parsed command-line arguments
+            context: CLI context with session and configuration
+
+        Returns:
+            Exit code (0 for success, non-zero for error)
+        """
+        pass
+
+    def get_object_list(self, context: CLIContext, mtype: str) -> Dict[str, int]:
+        """Get list of objects by type.
+
+        Args:
+            context: CLI context
+            mtype: Resource type (material, part, magnet, etc.)
+
+        Returns:
+            Dictionary mapping names to IDs
+        """
+        return utils.get_list(
+            context.session,
+            context.web,
+            headers=context.headers,
+            mtype=mtype,
+        )
+
+    def get_object_by_name(
+        self, context: CLIContext, mtype: str, name: str
+    ) -> dict:
+        """Get object by name.
+
+        Args:
+            context: CLI context
+            mtype: Resource type
+            name: Object name
+
+        Returns:
+            Object data dictionary
+
+        Raises:
+            ResourceNotFoundError: If object doesn't exist
+        """
+        ids = self.get_object_list(context, mtype)
+
+        if name not in ids:
+            raise ResourceNotFoundError(
+                f"{mtype} '{name}' not found",
+                object_name=name,
+                object_type=mtype,
+            )
+
+        return utils.get_object(
+            context.session,
+            context.web,
+            context.headers,
+            ids[name],
+            mtype,
+        )
+
+    def validate_resource_type(
+        self,
+        mtype: str,
+        allowed_types: List[str],
+        command_name: Optional[str] = None,
+    ) -> None:
+        """Validate that resource type is allowed for this command.
+
+        Args:
+            mtype: Resource type to validate
+            allowed_types: List of allowed types
+            command_name: Command name for error message
+
+        Raises:
+            ValidationError: If type is not allowed
+        """
+        if mtype not in allowed_types:
+            cmd = command_name or self.name
+            raise ValidationError(
+                f"Command '{cmd}' does not support resource type '{mtype}'. "
+                f"Expected one of: {allowed_types}",
+                provided_type=mtype,
+                expected_types=allowed_types,
+            )
diff --git a/python_magnetapi/cli/commands/__init__.py b/python_magnetapi/cli/commands/__init__.py
new file mode 100644
index 0000000..efe6723
--- /dev/null
+++ b/python_magnetapi/cli/commands/__init__.py
@@ -0,0 +1,27 @@
+"""Command registry and imports."""
+
+from typing import Dict, Type
+
+from ..base import BaseCommand
+from .list import ListCommand
+from .view import ViewCommand
+from .create import CreateCommand
+from .delete import DeleteCommand
+from .setup import SetupCommand
+from .run import RunCommand
+from .compute import ComputeCommand
+from .process import ProcessCommand
+
+
+COMMANDS: Dict[str, Type[BaseCommand]] = {
+    "list": ListCommand,
+    "view": ViewCommand,
+    "create": CreateCommand,
+    "delete": DeleteCommand,
+    "setup": SetupCommand,
+    "run": RunCommand,
+    "compute": ComputeCommand,
+    "process": ProcessCommand,
+}
+
+__all__ = ["COMMANDS"]
diff --git a/python_magnetapi/cli/commands/compute.py b/python_magnetapi/cli/commands/compute.py
new file mode 100644
index 0000000..fd3a689
--- /dev/null
+++ b/python_magnetapi/cli/commands/compute.py
@@ -0,0 +1,146 @@
+"""Compute command handler."""
+
+import argparse
+from typing import Any, Dict
+
+from ..base import BaseCommand
+from ..context import CLIContext
+
+
+class ComputeCommand(BaseCommand):
+    """Compute derived quantities."""
+
+    name = "compute"
+    help = "Compute inductances, flow parameters, or hoop stress"
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure compute command arguments.
+
+        Args:
+            parser: Subparser for this command
+        """
+        parser.add_argument(
+            "--mtype",
+            help="select object type",
+            type=str,
+            choices=["part", "magnet", "site", "record"],
+            default="magnet",
+        )
+        parser.add_argument(
+            "--name",
+            help="specify an object name",
+            type=str,
+            default="None",
+        )
+        parser.add_argument(
+            "--inductances",
+            help="activate self and mutual inductances",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--flow_params",
+            help="activate flow params",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--hoop_stress",
+            help="activate hoop stress history",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--samples",
+            help="specify number of samples to consider",
+            type=int,
+            default=20,
+        )
+
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute compute command.
+
+        Args:
+            args: Parsed arguments
+            context: CLI context
+
+        Returns:
+            Exit code (0 for success)
+        """
+        if args.inductances:
+            self._compute_inductances(args, context)
+
+        if args.flow_params:
+            self._compute_flow_params(args, context)
+
+        if args.hoop_stress:
+            self._compute_hoop_stress(args, context)
+
+        return 0
+
+    def _compute_inductances(
+        self, args: argparse.Namespace, context: CLIContext
+    ) -> None:
+        """Compute self and mutual inductances.
+
+        Args:
+            args: Parsed arguments (requires mtype, name)
+            context: CLI context
+        """
+        self.validate_resource_type(args.mtype, ["magnet", "site", "record"])
+
+        obj: Dict[str, Any] = self.get_object_by_name(context, args.mtype, args.name)
+
+        from ... import inductances
+
+        print("Compute Self/Mutual inductances")
+        inductances.compute(
+            context.session,
+            context.web,
+            context.headers,
+            oid=obj["id"],
+            mtype=args.mtype,
+        )
+
+    def _compute_flow_params(
+        self, args: argparse.Namespace, context: CLIContext
+    ) -> None:
+        """Compute flow parameters.
+
+        Args:
+            args: Parsed arguments (requires mtype=magnet, name, samples)
+            context: CLI context
+        """
+        self.validate_resource_type(args.mtype, ["magnet"])
+
+        obj: Dict[str, Any] = self.get_object_by_name(context, args.mtype, args.name)
+
+        from ... import flow_params
+
+        flow_params.compute(
+            context.session,
+            context.web,
+            headers=context.headers,
+            oid=obj["id"],
+            samples=args.samples,
+        )
+
+    def _compute_hoop_stress(
+        self, args: argparse.Namespace, context: CLIContext
+    ) -> None:
+        """Compute hoop stress.
+
+        Args:
+            args: Parsed arguments (requires mtype=part, name)
+            context: CLI context
+        """
+        self.validate_resource_type(args.mtype, ["part"])
+
+        obj: Dict[str, Any] = self.get_object_by_name(context, args.mtype, args.name)
+
+        from ... import hoop_stress
+
+        hoop_stress.compute(
+            context.session,
+            context.web,
+            headers=context.headers,
+            mtype=args.mtype,
+            oid=obj["id"],
+        )
diff --git a/python_magnetapi/cli/commands/create.py b/python_magnetapi/cli/commands/create.py
new file mode 100644
index 0000000..0b462a3
--- /dev/null
+++ b/python_magnetapi/cli/commands/create.py
@@ -0,0 +1,89 @@
+"""Create command handler."""
+
+import argparse
+import json
+from typing import Any, Callable, Dict
+
+from ..base import BaseCommand, OBJECT_TYPES
+from ..context import CLIContext
+from ...material import create as mat_create
+from ...site import create as site_create
+from ...magnet import create as magnet_create
+from ...part import create as part_create
+from ...record import create as record_create
+
+# Map resource types to their creation functions
+_CREATORS: Dict[str, Callable[..., Any]] = {
+    "material": mat_create,
+    "site": site_create,
+    "magnet": magnet_create,
+    "part": part_create,
+    "record": record_create,
+}
+
+
+class CreateCommand(BaseCommand):
+    """Create new object from JSON data or file."""
+
+    name = "create"
+    help = "Create new object"
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure create command arguments.
+
+        Args:
+            parser: Subparser for this command
+        """
+        parser.add_argument(
+            "--mtype",
+            help="select object type",
+            type=str,
+            choices=OBJECT_TYPES,
+            default="magnet",
+        )
+        command_group = parser.add_mutually_exclusive_group()
+        command_group.add_argument(
+            "--data",
+            help="load data from dict",
+            type=json.loads,
+            nargs="?",
+        )
+        command_group.add_argument(
+            "--file",
+            help="load data from file",
+            type=str,
+            nargs="?",
+        )
+
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute create command.
+
+        Args:
+            args: Parsed arguments
+            context: CLI context
+
+        Returns:
+            Exit code (0 for success)
+        """
+        data: Dict[str, Any] = {}
+        if args.data:
+            print(f"create: data={json.dumps(args.data, indent=4, default=str)}")
+            data = args.data
+        if args.file:
+            print(f"create: file={args.file}")
+            with open(args.file, "r") as f:
+                data = json.loads(f.read())
+                print(f"data: {data}")
+
+        creator = _CREATORS[args.mtype]
+        obj_id = creator(
+            context.session,
+            context.web,
+            headers=context.headers,
+            data=data,
+        )
+
+        if obj_id is None:
+            print(f"create: type={args.mtype}, name={data.get('name')} not implemented")
+
+        return 0
diff --git a/python_magnetapi/cli/commands/delete.py b/python_magnetapi/cli/commands/delete.py
new file mode 100644
index 0000000..e570c4e
--- /dev/null
+++ b/python_magnetapi/cli/commands/delete.py
@@ -0,0 +1,65 @@
+"""Delete command handler."""
+
+import argparse
+
+from ..base import BaseCommand, OBJECT_TYPES
+from ..context import CLIContext
+from ... import utils
+from ...exceptions import ResourceNotFoundError
+
+
+class DeleteCommand(BaseCommand):
+    """Delete object by name."""
+
+    name = "delete"
+    help = "Delete object"
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure delete command arguments.
+
+        Args:
+            parser: Subparser for this command
+        """
+        parser.add_argument(
+            "--mtype",
+            help="select object type",
+            type=str,
+            choices=OBJECT_TYPES,
+            default="magnet",
+        )
+        parser.add_argument(
+            "--name",
+            help="specify an object name",
+            type=str,
+            default="None",
+        )
+
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute delete command.
+
+        Args:
+            args: Parsed arguments
+            context: CLI context
+
+        Returns:
+            Exit code (0 for success)
+        """
+        ids = self.get_object_list(context, args.mtype)
+
+        if args.name not in ids:
+            raise ResourceNotFoundError(
+                f"Object '{args.name}' not found in {args.mtype} collection",
+                object_name=args.name,
+                object_type=args.mtype,
+            )
+
+        print(f"{args.name}: id={ids[args.name]}")
+        utils.del_object(
+            context.session,
+            context.web,
+            headers=context.headers,
+            mtype=args.mtype,
+            id=ids[args.name],
+        )
+
+        return 0
diff --git a/python_magnetapi/cli/commands/list.py b/python_magnetapi/cli/commands/list.py
new file mode 100644
index 0000000..2545051
--- /dev/null
+++ b/python_magnetapi/cli/commands/list.py
@@ -0,0 +1,74 @@
+"""List command handler."""
+
+import argparse
+from typing import Dict, Optional
+
+from ..base import BaseCommand, OBJECT_TYPES
+from ..context import CLIContext
+from ... import utils
+
+
+class ListCommand(BaseCommand):
+    """List objects of a given type."""
+
+    name = "list"
+    help = "List objects in MagnetDB"
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure list command arguments.
+
+        Args:
+            parser: Subparser for this command
+        """
+        parser.add_argument(
+            "--mtype",
+            help="select object type",
+            type=str,
+            choices=OBJECT_TYPES,
+            default="magnet",
+        )
+        parser.add_argument(
+            "--filter",
+            help="filter results by attribute (format: key=value). Can be used multiple times.",
+            action="append",
+            dest="filters",
+            metavar="KEY=VALUE",
+        )
+
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute list command.
+
+        Args:
+            args: Parsed arguments
+            context: CLI context
+
+        Returns:
+            Exit code (0 for success)
+        """
+        filter_dict: Dict[str, str] = {}
+        if args.filters:
+            for filter_str in args.filters:
+                if "=" in filter_str:
+                    key, value = filter_str.split("=", 1)
+                    filter_dict[key.strip()] = value.strip()
+                else:
+                    print(
+                        f"Warning: Invalid filter format '{filter_str}'. Expected KEY=VALUE"
+                    )
+
+        ids = utils.get_list(
+            context.session,
+            context.web,
+            headers=context.headers,
+            mtype=args.mtype,
+            filters=filter_dict if filter_dict else None,
+        )
+        print(f"{args.mtype.upper()}: found {len(ids)} items")
+
+        import pandas as pd
+
+        data = [{"Name": name, "ID": id_value} for name, id_value in ids.items()]
+        df = pd.DataFrame(data)
+        print(df.to_string(index=False))
+
+        return 0
diff --git a/python_magnetapi/cli/commands/process.py b/python_magnetapi/cli/commands/process.py
new file mode 100644
index 0000000..e7ca32a
--- /dev/null
+++ b/python_magnetapi/cli/commands/process.py
@@ -0,0 +1,34 @@
+"""Process command handler."""
+
+import argparse
+
+from ..base import BaseCommand
+from ..context import CLIContext
+
+
+class ProcessCommand(BaseCommand):
+    """Process/post-process simulation results."""
+
+    name = "process"
+    help = "Process simulation results (not yet implemented)"
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure process command arguments.
+
+        Args:
+            parser: Subparser for this command
+        """
+        pass
+
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute process command.
+
+        Args:
+            args: Parsed arguments
+            context: CLI context
+
+        Returns:
+            Exit code
+        """
+        print("process: not implemented")
+        return 0
diff --git a/python_magnetapi/cli/commands/run.py b/python_magnetapi/cli/commands/run.py
new file mode 100644
index 0000000..92c5431
--- /dev/null
+++ b/python_magnetapi/cli/commands/run.py
@@ -0,0 +1,127 @@
+"""Run command handler."""
+
+import argparse
+import sys
+from time import sleep
+from typing import Any, Dict, Optional
+
+from ..base import BaseCommand
+from ..context import CLIContext
+from ... import utils
+
+
+class RunCommand(BaseCommand):
+    """Run a simulation."""
+
+    name = "run"
+    help = "Run simulation"
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure run command arguments.
+
+        Args:
+            parser: Subparser for this command
+        """
+        parser.add_argument(
+            "--mtype",
+            help="select object type",
+            type=str,
+            choices=["magnet", "site"],
+            default="magnet",
+        )
+        parser.add_argument(
+            "--simu_id",
+            help="select simulation id",
+            type=int,
+            default=-1,
+        )
+        parser.add_argument(
+            "--wd",
+            help="select directory to store setup/simulation results",
+            type=str,
+            default=".",
+        )
+        parser.add_argument(
+            "--compute_server",
+            help="choose compute node",
+            type=str,
+            default="calcul22",
+        )
+        parser.add_argument(
+            "--np",
+            help="choose number of procs",
+            type=int,
+            default=4,
+        )
+
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute run command.
+
+        Args:
+            args: Parsed arguments
+            context: CLI context
+
+        Returns:
+            Exit code (0 for success)
+        """
+        simu: Optional[Dict[str, Any]] = utils.get_object(
+            context.session,
+            context.web,
+            context.headers,
+            args.simu_id,
+            mtype="simulation",
+        )
+        if simu is None:
+            raise RuntimeError(
+                f"run: cannot find {args.simu_id} simulation"
+                " - please check simulations list"
+            )
+
+        server_ids: Dict[str, int] = utils.get_list(
+            context.session,
+            context.web,
+            headers=context.headers,
+            mtype="server",
+        )
+        if args.compute_server not in server_ids:
+            raise RuntimeError(
+                f"{args.compute_server}: cannot found {args.compute_server} in server objects"
+            )
+        server_id: int = server_ids[args.compute_server]
+
+        print("Starting simulation...")
+        context.session.post(
+            f"{context.web}/api/simulations/{args.simu_id}/run",
+            data={"server_id": server_id},
+            headers=context.headers,
+        )
+
+        while True:
+            simulation = utils.get_object(
+                context.session,
+                context.web,
+                context.headers,
+                args.simu_id,
+                mtype="simulation",
+            )
+            if simulation["status"] in ["failed", "done"]:
+                break
+            sleep(10)
+
+        print(f'Simulation done: status={simulation["status"]}')
+        if simulation["status"] == "failed":
+            sys.exit(1)
+
+        print(f"simulation={simulation}")
+        simu_arch_id = simulation["output_attachment"]["id"]
+        simu_filename = utils.download(
+            context.session,
+            context.web,
+            headers=context.headers,
+            attach=simu_arch_id,
+            wd=args.wd,
+        )
+        print(f"{simu_filename} downloaded")
+        print(f'simulation {simulation["id"]} done')
+
+        return 0
diff --git a/python_magnetapi/cli/commands/setup.py b/python_magnetapi/cli/commands/setup.py
new file mode 100644
index 0000000..23dad54
--- /dev/null
+++ b/python_magnetapi/cli/commands/setup.py
@@ -0,0 +1,215 @@
+"""Setup command handler."""
+
+import argparse
+import sys
+from time import sleep
+
+from typing import Any, Dict, List
+
+from ..base import BaseCommand
+from ..context import CLIContext
+from ... import utils
+
+
+class SetupCommand(BaseCommand):
+    """Setup simulation for magnet or site."""
+
+    name = "setup"
+    help = "Setup simulation"
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure setup command arguments.
+
+        Args:
+            parser: Subparser for this command
+        """
+        parser.add_argument(
+            "--mtype",
+            help="select object type",
+            type=str,
+            choices=["magnet", "site"],
+            default="magnet",
+        )
+        parser.add_argument(
+            "--name",
+            help="specify an object name",
+            type=str,
+            default="None",
+        )
+        parser.add_argument(
+            "--current",
+            help="specify requested current (default: 31kA)",
+            nargs="+",
+            metavar="Current",
+            type=float,
+            default=[31.0e3],
+        )
+        parser.add_argument(
+            "--geometry",
+            help="select a method",
+            type=str,
+            choices=["Axi", "3D"],
+            default="Axi",
+        )
+        parser.add_argument(
+            "--static",
+            help="activate static mode",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--nonlinear",
+            help="activate non_linear",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--method",
+            help="select a method",
+            type=str,
+            default="cfpdes",
+        )
+        parser.add_argument(
+            "--model",
+            help="select a model",
+            type=str,
+            default="thmagel_hcurl",
+        )
+        parser.add_argument(
+            "--cooling",
+            help="select a cooling mode",
+            type=str,
+            choices=["mean", "meanH", "grad", "gradH", "gradHZ"],
+            default="meanH",
+        )
+        parser.add_argument(
+            "--wd",
+            help="select directory to store setup/simulation results",
+            type=str,
+            default=".",
+        )
+
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute setup command.
+
+        Args:
+            args: Parsed arguments
+            context: CLI context
+
+        Returns:
+            Exit code (0 for success)
+        """
+        self.validate_resource_type(args.mtype, ["magnet", "site"])
+
+        # Check consistent method and model
+        r = context.session.get(
+            f"{context.web}/api/simulations/models", headers=context.headers
+        )
+        response = r.json()
+        if r.status_code != 200:
+            raise RuntimeError(
+                f"setup: cannot get models dict {response['detail']}"
+            )
+
+        available_methods = [
+            data["method"]
+            for data in response
+            if data["geometry"] == args.geometry
+        ]
+        available_methods = list(set(available_methods))
+        if args.method not in available_methods:
+            raise RuntimeError(
+                f"{args.method}: unknown method for {args.geometry} geometry"
+                f" - supported values are {available_methods}"
+            )
+
+        available_models = [
+            data["model"]
+            for data in response
+            if data["method"] == args.method and data["geometry"] == args.geometry
+        ]
+        if args.model not in available_models:
+            raise RuntimeError(
+                f"{args.model}: unknown model for {args.method} and {args.geometry}"
+                f" geometry - supported values are {available_models}"
+            )
+
+        obj: Dict[str, Any] = self.get_object_by_name(context, args.mtype, args.name)
+
+        currents: List[Dict[str, Any]] = []
+        if args.mtype == "site":
+            if len(args.current) != len(obj["site_magnets"]):
+                raise RuntimeError(
+                    f"args.current contains {len(args.current)} values"
+                    f" - should have {len(obj['site_magnets'])} values"
+                )
+            for i, magnet in enumerate(obj["site_magnets"]):
+                print(f"current[{i}]: magnet={magnet}")
+                currents.append(
+                    {"magnet_id": magnet["magnet_id"], "value": args.current[i]}
+                )
+        else:
+            if len(args.current) != 1:
+                raise RuntimeError(
+                    f"args.current contains {len(args.current)} values - should have 1 value"
+                )
+            currents.append({"magnet_id": obj["id"], "value": args.current[0]})
+        print(f"currents: {currents}")
+
+        sim_data = {
+            "resource_type": args.mtype,
+            "resource_id": obj["id"],
+            "method": args.method,
+            "model": args.model,
+            "geometry": args.geometry,
+            "cooling": args.cooling,
+            "static": args.static,
+            "non_linear": args.nonlinear,
+            "currents": currents,
+        }
+
+        simu_id = utils.create_object(
+            context.session,
+            context.web,
+            headers=context.headers,
+            mtype="simulation",
+            data=sim_data,
+        )
+        if simu_id is None:
+            raise RuntimeError(
+                f"failed to create simulation for {args.mtype} {args.name} in run subcommand"
+            )
+
+        print("Starting setup...")
+        context.session.post(
+            f"{context.web}/api/simulations/{simu_id}/run_setup",
+            headers=context.headers,
+        )
+
+        while True:
+            simulation = utils.get_object(
+                context.session,
+                context.web,
+                context.headers,
+                simu_id,
+                mtype="simulation",
+            )
+            if simulation["setup_status"] in ["failed", "done"]:
+                break
+            sleep(10)
+
+        print(f"Setup done: simulation={simulation}")
+        print(f'Setup done: status={simulation["setup_status"]}')
+        if simulation["setup_status"] == "failed":
+            sys.exit(1)
+
+        setup_arch_id = simulation["setup_output_attachment"]["id"]
+        setup_filename = utils.download(
+            context.session,
+            context.web,
+            headers=context.headers,
+            attach=setup_arch_id,
+            wd=args.wd,
+        )
+        print(f"{setup_filename} downloaded")
+        print(f'simulation {simulation["id"]} setup done')
+
+        return 0
diff --git a/python_magnetapi/cli/commands/view.py b/python_magnetapi/cli/commands/view.py
new file mode 100644
index 0000000..a3f07e5
--- /dev/null
+++ b/python_magnetapi/cli/commands/view.py
@@ -0,0 +1,50 @@
+"""View command handler."""
+
+import argparse
+import json
+from typing import Any, Dict
+
+from ..base import BaseCommand, OBJECT_TYPES
+from ..context import CLIContext
+
+
+class ViewCommand(BaseCommand):
+    """View details of a specific object."""
+
+    name = "view"
+    help = "View object details"
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Configure view command arguments.
+
+        Args:
+            parser: Subparser for this command
+        """
+        parser.add_argument(
+            "--mtype",
+            help="select object type",
+            type=str,
+            choices=OBJECT_TYPES,
+            default="magnet",
+        )
+        parser.add_argument(
+            "--name",
+            help="specify an object name",
+            type=str,
+            default="None",
+        )
+
+    def execute(self, args: argparse.Namespace, context: CLIContext) -> int:
+        """Execute view command.
+
+        Args:
+            args: Parsed arguments
+            context: CLI context
+
+        Returns:
+            Exit code (0 for success)
+        """
+        obj: Dict[str, Any] = self.get_object_by_name(context, args.mtype, args.name)
+        print(f"{args.name}:\n{json.dumps(obj, indent=4)}")
+
+        return 0
diff --git a/python_magnetapi/cli/context.py b/python_magnetapi/cli/context.py
new file mode 100644
index 0000000..f84768e
--- /dev/null
+++ b/python_magnetapi/cli/context.py
@@ -0,0 +1,61 @@
+"""CLI context and configuration."""
+
+from __future__ import annotations
+
+import urllib3
+from dataclasses import dataclass, field
+from typing import Optional
+import requests
+
+
+@dataclass
+class CLIContext:
+    """Context passed to all command handlers.
+
+    Attributes:
+        server: API server hostname
+        port: API port number
+        api_key: API authentication key
+        debug: Debug mode flag
+        https: Use HTTPS flag
+        no_verify: Skip TLS certificate verification (self-signed certs)
+        session: Requests session (initialized later)
+    """
+
+    server: str
+    port: int
+    api_key: str
+    debug: bool = False
+    https: bool = False
+    no_verify: bool = False
+    session: Optional[requests.Session] = field(default=None, repr=False)
+
+    @property
+    def headers(self) -> dict:
+        """HTTP headers for API authentication."""
+        return {"Authorization": self.api_key}
+
+    @property
+    def web(self) -> str:
+        """Full API base URL."""
+        if self.https:
+            return f"https://{self.server}"
+        return f"http://{self.server}:{self.port}"
+
+    def __enter__(self) -> CLIContext:
+        """Context manager entry - create session."""
+        if self.no_verify:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+        self.session = requests.Session()
+        self.session.verify = not self.no_verify
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[BaseException],
+        exc_tb: object,
+    ) -> None:
+        """Context manager exit - close session."""
+        if self.session:
+            self.session.close()
diff --git a/python_magnetapi/cli/parser.py b/python_magnetapi/cli/parser.py
new file mode 100644
index 0000000..3af9d86
--- /dev/null
+++ b/python_magnetapi/cli/parser.py
@@ -0,0 +1,97 @@
+"""Argument parser configuration."""
+
+import argparse
+import os
+from typing import Dict, Type
+
+from .base import BaseCommand
+
+
+def add_server_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add standard server/connection arguments to any parser.
+
+    Args:
+        parser: ArgumentParser (or subparser) to augment
+    """
+    parser.add_argument(
+        "--server",
+        help="API server hostname",
+        type=str,
+        default=os.getenv("MAGNETDB_API_SERVER", "api.magnetdb-dev.local"),
+    )
+    parser.add_argument(
+        "--port",
+        help="API server port",
+        type=int,
+        default=8000,
+    )
+    parser.add_argument(
+        "--https",
+        help="Use HTTPS",
+        action="store_true",
+    )
+    parser.add_argument(
+        "--no-verify",
+        help="Skip TLS certificate verification (self-signed certs)",
+        action="store_true",
+    )
+    parser.add_argument(
+        "--debug",
+        help="Enable debug mode",
+        action="store_true",
+    )
+
+
+def add_logging_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add logging-related arguments to any parser.
+
+    Args:
+        parser: ArgumentParser (or subparser) to augment
+    """
+    parser.add_argument(
+        "--log-level",
+        help="Logging level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        default="WARNING",
+    )
+    parser.add_argument(
+        "--log-file",
+        help="Optional file path to write logs to",
+        type=str,
+        default=None,
+    )
+
+
+def create_parser(commands: Dict[str, Type[BaseCommand]]) -> argparse.ArgumentParser:
+    """Create and configure the argument parser.
+
+    Args:
+        commands: Dictionary of command name to command class
+
+    Returns:
+        Configured ArgumentParser
+    """
+    parser = argparse.ArgumentParser(
+        prog="python_magnetapi",
+        description="CLI for interacting with MagnetDB",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    add_server_arguments(parser)
+    add_logging_arguments(parser)
+
+    subparsers = parser.add_subparsers(
+        title="commands",
+        dest="command",
+        help="Available commands",
+    )
+
+    for cmd_name, cmd_class in commands.items():
+        cmd_instance = cmd_class()
+        cmd_parser = subparsers.add_parser(
+            cmd_name,
+            help=cmd_instance.help,
+        )
+        cmd_instance.configure_parser(cmd_parser)
+
+    return parser
diff --git a/python_magnetapi/exceptions.py b/python_magnetapi/exceptions.py
new file mode 100644
index 0000000..bc4e093
--- /dev/null
+++ b/python_magnetapi/exceptions.py
@@ -0,0 +1,121 @@
+"""
+Custom exceptions for python-magnetapi.
+
+This module defines a hierarchy of exceptions used throughout the package
+to provide clear, structured error handling with context.
+"""
+
+
+class MagnetAPIException(Exception):
+    """Base exception for all python-magnetapi errors.
+
+    All custom exceptions in this package inherit from this base class,
+    allowing users to catch any package-specific error.
+
+    Attributes:
+        message (str): Human-readable error message
+        context (dict): Additional context information (status_code, url, etc.)
+    """
+
+    def __init__(self, message, **context):
+        """Initialize exception with message and optional context.
+
+        Args:
+            message: Human-readable error description
+            **context: Additional context (status_code, url, response, etc.)
+        """
+        super().__init__(message)
+        self.message = message
+        self.context = context
+
+    def __str__(self):
+        """Format exception with context for display."""
+        if not self.context:
+            return self.message
+        ctx = ", ".join(f"{k}={v}" for k, v in self.context.items())
+        return f"{self.message} ({ctx})"
+
+
+# API-related exceptions
+class APIError(MagnetAPIException):
+    """Base exception for API communication errors."""
+
+    pass
+
+
+class AuthenticationError(APIError):
+    """Raised when API authentication fails.
+
+    This typically occurs when:
+    - MAGNETDB_API_KEY is not set
+    - API key is invalid or expired
+    - API returns 401 Unauthorized
+    """
+
+    pass
+
+
+class AuthorizationError(APIError):
+    """Raised when user lacks permission for an operation.
+
+    This occurs when:
+    - User is authenticated but doesn't have permission
+    - API returns 403 Forbidden
+    """
+
+    pass
+
+
+class ResourceNotFoundError(APIError):
+    """Raised when a requested resource doesn't exist.
+
+    This occurs when:
+    - Specified object name/ID doesn't exist
+    - API returns 404 Not Found
+    """
+
+    pass
+
+
+class ResourceConflictError(APIError):
+    """Raised when a resource already exists or conflicts.
+
+    This occurs when:
+    - Trying to create an object with duplicate name
+    - API returns 409 Conflict
+    """
+
+    pass
+
+
+class ValidationError(MagnetAPIException):
+    """Raised when input data validation fails.
+
+    This occurs when:
+    - Required fields are missing
+    - Data format is invalid
+    - Business logic validation fails
+    """
+
+    pass
+
+
+class NetworkError(APIError):
+    """Raised when network communication fails.
+
+    This occurs when:
+    - Connection timeout
+    - Server unreachable
+    - DNS resolution fails
+    """
+
+    pass
+
+
+class ServerError(APIError):
+    """Raised when server returns 5xx error.
+
+    This indicates a server-side problem that the client cannot fix.
+    """
+
+    pass
diff --git a/python_magnetapi/flow_params.py b/python_magnetapi/flow_params.py
index 79adbfd..5265f02 100644
--- a/python_magnetapi/flow_params.py
+++ b/python_magnetapi/flow_params.py
@@ -1,161 +1,289 @@
 """
-Extract flow params from records using a fit
-"""
+Extract flow params from records using a fit.
 
+This module handles data acquisition from the MagnetDB API and delegates
+curve fitting to python_magnetcooling.fitting. The separation of concerns is:
+  - Data acquisition & record management: this module (python_magnetapi)
+  - Curve fitting & hydraulic calculations: python_magnetcooling.fitting
+  - WaterFlow object creation: python_magnetcooling.waterflow_factory / fitting.build_waterflow
+"""
 
 import tempfile
 import os
 import re
+import datetime
+import json
+import logging
 
-import numpy as np
-from scipy import optimize
 from math import floor
 
-import datetime
-
-import json
+import numpy as np
 import pandas as pd
 from rich.progress import track
+
 from . import utils
 
-# from txt2csv import load_files
 from python_magnetrun.utils.files import concat_files
 from python_magnetrun.utils.plots import plot_files
 from python_magnetrun.magnetdata import MagnetData
 from python_magnetrun.processing.stats import nplateaus
 
+from python_magnetcooling.fitting import (
+    fit_hydraulic_system,
+    build_waterflow,
+)
+from python_magnetcooling.waterflow_factory import from_flow_params
+
+logger = logging.getLogger(__name__)
+
 
-def stats(
+def _extract_arrays_from_files(
+    files: list,
     Ikey: str,
-    Okey: str,
-    Ostring: str,
+    rpm_key: str,
+    flow_key: str,
+    pin_key: str,
+    pout_key: str,
     threshold: float,
-    files: list,
-    wd: str,
-    filename: str,
     debug: bool = False,
-):
-    df = concat_files(files, keys=[Ikey, Okey], debug=debug)
+) -> dict:
+    """
+    Extract numpy arrays from record files for fitting.
+
+    Concatenates data from multiple record files, cleans NaN/Inf values,
+    and filters by current threshold.
+
+    Parameters
+    ----------
+    files : list
+        List of record file paths.
+    Ikey : str
+        Column name for current.
+    rpm_key, flow_key, pin_key, pout_key : str
+        Column names for pump speed, flow rate, inlet pressure, and back pressure.
+    threshold : float
+        Maximum current value (Imax) for filtering.
+    debug : bool
+        Enable debug output.
+
+    Returns
+    -------
+    dict
+        Dictionary with numpy arrays: 'current', 'pump_speed', 'flow_rate',
+        'pressure', 'back_pressure'.
+    """
+    all_keys = [Ikey, rpm_key, flow_key, pin_key, pout_key]
+
+    df = concat_files(files, keys=all_keys, debug=debug)
     df.replace([np.inf, -np.inf], np.nan, inplace=True)
     df.dropna(inplace=True)
 
-    # # drop values for Icoil1 > Imax
-    result = df.query(f"{Ikey} <= {threshold}")  # , inplace=True)
+    # Filter by current threshold
+    result = df.query(f"{Ikey} <= {threshold}")
     if result is not None and debug:
         print(f"df: nrows={df.shape[0]}, results: nrows={result.shape[0]}")
         print(f"result max: {result[Ikey].max()}")
 
-    plot_files(
-        filename,
-        files,
-        key1=Ikey,
-        key2=Okey,
-        fit=None,
-        show=debug,
-        debug=debug,
-        wd=wd,
-    )
+    return {
+        "current": result[Ikey].to_numpy(),
+        "pump_speed": result[rpm_key].to_numpy(),
+        "flow_rate": result[flow_key].to_numpy(),
+        "pressure": result[pin_key].to_numpy(),
+        "back_pressure": result[pout_key].to_numpy(),
+    }
 
-    if debug:
-        stats = result[Okey].describe(include="all")
-        print(f"{Okey}: stats")
-    return (result[Okey].mean(), result[Okey].std())
 
+def _build_flow_params_dict(pump_fit, flow_pressure_fit) -> dict:
+    """
+    Build the standard flow_params dictionary from fit results.
+
+    This preserves backward compatibility with code that expects
+    the legacy dict format (e.g. for JSON serialization).
+
+    Parameters
+    ----------
+    pump_fit : PumpSpeedFit
+        Pump speed fit results.
+    flow_pressure_fit : FlowPressureFit
+        Flow rate and pressure fit results.
+
+    Returns
+    -------
+    dict
+        Flow parameters in the standard format with value/unit pairs.
+    """
+    return {
+        "Vp0": {"value": pump_fit.vp0, "unit": "rpm"},
+        "Vpmax": {"value": pump_fit.vpmax, "unit": "rpm"},
+        "F0": {"value": flow_pressure_fit.f0, "unit": "l/s"},
+        "Fmax": {"value": flow_pressure_fit.fmax, "unit": "l/s"},
+        "Pmax": {"value": flow_pressure_fit.pmax, "unit": "bar"},
+        "Pmin": {"value": flow_pressure_fit.pmin, "unit": "bar"},
+        "Pout": {"value": flow_pressure_fit.back_pressure, "unit": "bar"},
+        "Imax": {"value": pump_fit.imax, "unit": "A"},
+    }
 
-def fit(
-    Ikey: str,
-    Okey: str,
-    Ostring: str,
-    threshold: float,
-    fit_function,
+
+def _detect_imax_from_files(
     files: list,
-    wd: str,
-    filename: str,
+    Ikey: str,
+    rpm_key: str,
+    housing: str,
+    fit_data: dict,
+    Imax: float,
     debug: bool = False,
-):
+) -> tuple:
     """
-    perform fit
+    Detect Imax from plateau regions in record files.
+
+    Examines each record file for plateau regions in pump speed
+    to determine the actual maximum operating current.
+
+    Parameters
+    ----------
+    files : list
+        List of record file paths.
+    Ikey : str
+        Column name for current.
+    rpm_key : str
+        Column name for pump speed.
+    housing : str
+        Housing identifier (e.g. 'M9', 'M10').
+    fit_data : dict
+        Fit data configuration per housing.
+    Imax : float
+        Current Imax estimate.
+    debug : bool
+        Enable debug output.
+
+    Returns
+    -------
+    tuple
+        (new_Imax, dropped_files) where new_Imax is the detected Imax
+        (or original if no plateau found) and dropped_files is the list
+        of files to exclude from fitting.
     """
+    new_Imax_values = []
+    dropped_files = []
+
+    for file in files:
+        _df = pd.read_csv(file, sep=r"\s+", engine="python", skiprows=1)
+        if Ikey not in _df.columns.values.tolist():
+            print(f"{Ikey}: no such key in {file} - ignore {file}")
+            dropped_files.append(file)
+        else:
+            # Compute duration and drop short records
+            if (
+                "Date" in _df.columns.values.tolist()
+                and "Time" in _df.columns.values.tolist()
+            ):
+                tformat = "%Y.%m.%d %H:%M:%S"
+                t0 = datetime.datetime.strptime(
+                    f"{_df['Date'].iloc[0]} {_df['Time'].iloc[0]}", tformat
+                )
+                _df["t"] = _df.apply(
+                    lambda row: (
+                        datetime.datetime.strptime(
+                            f"{row.Date} {row.Time}", tformat
+                        )
+                        - t0
+                    ).total_seconds(),
+                    axis=1,
+                )
+            duration = _df["t"].iloc[-1] - _df["t"][0]
+            if duration <= 15 * 60:
+                dropped_files.append(file)
+            else:
+                # Detect plateau in pump speed
+                _Rpmmax = _df[fit_data[housing]["Rpm"]].max()
+                threshold = _Rpmmax * (1 - 0.1 / 100.0)
+                result = _df.query(
+                    f'{fit_data[housing]["Rpm"]} >= {threshold}'
+                )
+                if not result.empty:
+                    if (
+                        result[Ikey].std() >= 10
+                        and result[Ikey].count() >= 100
+                        and result["Field"].max() >= 0.5
+                    ):
+                        if debug:
+                            _Istats = result[Ikey].describe(include="all")
+                            print(
+                                f'Rpmmax={_Rpmmax}, threshold={threshold} '
+                                f'{Ikey}: {_Istats}, Field: {result["Field"].max()}'
+                            )
+                        new_Imax_values.append(result[Ikey].min())
 
-    df = concat_files(files, keys=[Ikey, Okey], debug=debug)
-    df.replace([np.inf, -np.inf], np.nan, inplace=True)
-    df.dropna(inplace=True)
-
-    # # drop values for Icoil1 > Imax
-    result = df.query(f"{Ikey} <= {threshold}")  # , inplace=True)
-    if result is not None and debug:
-        print(f"df: nrows={df.shape[0]}, results: nrows={result.shape[0]}")
-        print(f"result max: {result[Ikey].max()}")
-
-    x_data = result[f"{Ikey}"].to_numpy()
-    y_data = result[Okey].to_numpy()
-    params, params_covariance = optimize.curve_fit(fit_function, x_data, y_data)
-
-    print(f"{Ostring} Fit:")
-    print(f"\tparams: {params}")
-    # print(f"\tcovariance: {params_covariance}")
-    print(f"\tstderr: {np.sqrt(np.diag(params_covariance))}")
-
-    # TODO update interface with name=f'{sname}_{mname}'
-    plot_files(
-        filename,
-        files,
-        key1=Ikey,
-        key2=Okey,
-        fit=(x_data, [fit_function(x, params[0], params[1]) for x in x_data]),
-        show=debug,
-        debug=debug,
-        wd=wd,
-    )
+    # Update Imax if plateaus were detected
+    detected_Imax = Imax
+    if new_Imax_values:
+        new_Imax_mean = sum(new_Imax_values) / len(new_Imax_values)
+        if Imax != new_Imax_mean:
+            print(f"new_Imax = {new_Imax_mean} raw={new_Imax_values}")
+            detected_Imax = new_Imax_mean
 
-    return params
+    return detected_Imax, dropped_files
 
 
-def compute(session, api_server: str, headers: dict, oid: int, samples: int=20, debug: bool = False):
+def compute(
+    session,
+    api_server: str,
+    headers: dict,
+    oid: int,
+    samples: int = 20,
+    debug: bool = False,
+):
     """
-    compute flow_params for a given magnet
+    Compute flow_params for a given magnet.
+
+    Fetches record data from MagnetDB API, downloads and processes record files,
+    detects Imax from plateau regions, and delegates curve fitting to
+    python_magnetcooling.fitting.fit_hydraulic_system().
+
+    The fitted parameters are saved as JSON and a WaterFlow object is returned.
+
+    Parameters
+    ----------
+    session : requests.Session
+        Active HTTP session for API calls.
+    api_server : str
+        MagnetDB API server URL.
+    headers : dict
+        HTTP headers (including authorization).
+    oid : int
+        Magnet object ID in the database.
+    samples : int
+        Maximum number of records to sample per site (default 20).
+    debug : bool
+        Enable debug output and plots.
+
+    Returns
+    -------
+    WaterFlow or None
+        Fitted WaterFlow object, or None if no data was available.
     """
     print(f"flow_params.compute: api_server={api_server}, id={oid}")
     cwd = os.getcwd()
     print(f"cwd={cwd}")
 
-    # default value
-    # set Imax to 40 kA to enable real Imax detection
-    flow_params = {
-        "Vp0": {"value": 1000, "unit": "rpm"},
-        "Vpmax": {"value": 2840, "unit": "rpm"},
-        "F0": {"value": 0, "unit": "l/s"},
-        "Fmax": {"value": 61.71612272405876, "unit": "l/s"},
-        "Pmax": {"value": 22, "unit": "bar"},
-        "Pmin": {"value": 4, "unit": "bar"},
-        "Pout": {"value": 4, "unit": "bar"},
-        "Imax": {"value": 28000, "unit": "A"},
-    }
-
-    Imax = flow_params["Imax"]["value"]  # 28000
+    # Default flow parameters (used as initial Imax estimate)
+    default_Imax = 28000  # A
 
-    # get magnet type: aka bitter|helix|supra ??
+    # Get magnet type to determine channel mapping
     odata = utils.get_object(
         session,
         api_server,
         headers=headers,
         mtype="magnet",
         id=oid,
-        debug=debug,
     )
     if debug:
         print(f"magnet data: {json.dumps(odata, indent=2, default=str)}")
     mname = odata["name"]
     mpart = odata["magnet_parts"][0]
     otype = mpart["part"]["type"]
-    # print(f"magnet type: {otype}")
-
-    # TODO: change according to magnet type
-    # or better store data with RpmH and RpmB
-    # similarely keep only Ih, Ib instead of Icoil
-    # and Ih_ref, Ib_ref instead of of Iddcct1
-    # Iddct are values of measured current
-    # Icoil  are actually referenced values required by the user
+
+    # Channel mapping depends on magnet type (helix vs bitter)
     # on M9: FlowH = Flow1, FlowB = Flow2
     # on M8,M10: FlowH = Flow2, FlowB = Flow1
     fit_data = {
@@ -186,14 +314,17 @@ def compute(session, api_server: str, headers: dict, oid: int, samples: int=20,
             },
         }
 
+    # Get sites associated with the magnet
     sites = utils.get_history(
-        session, api_server, headers, oid, mtype="magnet", otype="site", debug=debug
+        session, api_server, headers, oid, mtype="magnet", otype="site"
     )
     if debug:
         print(f"sites: {json.dumps(sites, indent=2, default=str)}")
         for i, site in enumerate(sites):
             print(f"site[{i}/{len(sites)}]: {json.dumps(site, indent=2, default=str)}")
 
+    waterflow = None
+
     with tempfile.TemporaryDirectory() as tempdir:
         os.chdir(tempdir)
         if debug:
@@ -208,19 +339,16 @@ def compute(session, api_server: str, headers: dict, oid: int, samples: int=20,
                 site["site_id"],
                 mtype="site",
                 otype="record",
-                verbose=debug,
-                debug=debug,
             )
 
-            # download files
+            # Download record files (random sampling if many records)
             files = []
-            total = 0
             nrecords = len(records)
             ithreshold = nrecords
             if nrecords > samples:
                 ithreshold = min(samples, floor(nrecords * 0.80))
             if debug:
-                print(f"site[{site['site']['name']}]: nrecords={nrecords}")
+                print(f"site[{sname}]: nrecords={nrecords}")
 
             housing = None
             import random
@@ -230,28 +358,25 @@ def compute(session, api_server: str, headers: dict, oid: int, samples: int=20,
                 random.seed()
                 num_records = random.sample(range(0, nrecords), ithreshold)
             print(f"randomly selected records ({ithreshold}): {num_records}")
+
             for i in track(
                 range(ithreshold),
-                description=f"Processing records for site {site['site']['name']} (pick {ithreshold}/ {nrecords})",
+                description=f"Processing records for site {sname} (pick {ithreshold}/{nrecords})",
             ):
                 f = records[num_records[i]]
-                # print(f'f={f}')
                 attach = f["attachment_id"]
                 filename = utils.download(
-                    session, api_server, headers, attach, verbose=debug, debug=debug
+                    session, api_server, headers, attach
                 )
                 housing = filename.split("_")[0]
                 files.append(filename)
-                """
-                if i >= ithreshold:
-                    break
-                """
 
             if files:
-                # get keys to be extracted
-                df = pd.read_csv(files[0], sep=r"\s+", engine="python", skiprows=1)
-
-                df_emptycolumns = df.mask(df != 0).dropna(axis=1)
+                # Detect the current column key
+                df_sample = pd.read_csv(
+                    files[0], sep=r"\s+", engine="python", skiprows=1
+                )
+                df_emptycolumns = df_sample.mask(df_sample != 0).dropna(axis=1)
                 keys_emptycolumns = [
                     _key
                     for _key in df_emptycolumns.columns.values.tolist()
@@ -262,14 +387,11 @@ def compute(session, api_server: str, headers: dict, oid: int, samples: int=20,
                         keys_emptycolumns.remove(_key)
                     except ValueError:
                         pass
-                # print(f"keys_emptycolumns={keys_emptycolumns}")
 
-                # get first Icoil column (not necessary Icoil1)
-                keys = df.columns.values.tolist()
+                keys = df_sample.columns.values.tolist()
                 if debug:
                     print(f"{files[0]}: keys={keys}")
 
-                # key first or latest header that match Icoil\d+ depending on mtype
                 Ikeys = []
                 for _key in keys:
                     _found = re.match(r"(Icoil\d+)", _key)
@@ -279,178 +401,85 @@ def compute(session, api_server: str, headers: dict, oid: int, samples: int=20,
                 if otype == "bitter":
                     Ikey = Ikeys[-1]
                 print(f"Ikey={Ikey}")
-                df = pd.DataFrame()
-
-                dropped_files = []
-
-                # Imax detection
-                new_Imax = []
-                for file in files:
-                    _df = pd.read_csv(file, sep=r"\s+", engine="python", skiprows=1)
-                    if Ikey not in _df.columns.values.tolist():
-                        print(f"{Ikey}: no such key in {file} - ignore {file}")
-                        dropped_files.append(file)
-                    else:
-                        # drop if duration is less than threshold ??
-                        if (
-                            "Date" in _df.columns.values.tolist()
-                            and "Time" in _df.columns.values.tolist()
-                        ):
-                            tformat = "%Y.%m.%d %H:%M:%S"
-                            t0 = datetime.datetime.strptime(
-                                _df["Date"].iloc[0] + " " + _df["Time"].iloc[0], tformat
-                            )
-                            _df["t"] = _df.apply(
-                                lambda row: (
-                                    datetime.datetime.strptime(
-                                        row.Date + " " + row.Time, tformat
-                                    )
-                                    - t0
-                                ).total_seconds(),
-                                axis=1,
-                            )
-                        duration = _df["t"].iloc[-1] - _df["t"][0]
-                        if duration <= 15 * 60:
-                            dropped_files.append(file)
-
-                        else:
-                            _Rpmmax = _df[fit_data[housing]["Rpm"]].max()
-                            threshold = _Rpmmax * (1 - 0.1 / 100.0)
-                            result = _df.query(
-                                f'{fit_data[housing]["Rpm"]} >= {threshold}'
-                            )
-                            if not result.empty:
-                                if (
-                                    result[Ikey].std() >= 10
-                                    and result[Ikey].count() >= 100
-                                    and result["Field"].max() >= 0.5
-                                ):
-                                    if debug:
-                                        _Istats = result[Ikey].describe(include="all")
-                                        print(
-                                            f'Rpmmax={_Rpmmax}, thresold={threshold} {Ikey}: {_Istats}, Field: {result["Field"].max()}'
-                                        )
-                                        """ """
-                                        import matplotlib.pyplot as plt
-
-                                        result.plot.scatter(
-                                            x=Ikey,
-                                            y=fit_data[housing]["Rpm"],
-                                            grid=True,
-                                        )
-                                        lname = file.replace("_", "-")
-                                        lname = lname.replace(".txt", "")
-                                        lname = lname.split("/")
-                                        plt.title(lname[-1])
-                                        plt.show()
-                                        plt.close()
-                                        """ """
-
-                                    new_Imax.append(result[Ikey].min())
-
-                    """
-                    # xField = (Ikey, "A")
-                    # yField = (fit_data[housing]["Rpm"], "rpm")
-                    # threshold = 2.0e-2
-                    # num_points_threshold = 600
-                    Data = MagnetData.fromtxt(file)
-                    plateaus = nplateaus(
-                        Data, xField, yField, threshold, num_points_threshold, show=True
-                    )
-                    if plateaus:
-                        new_Imax = {min(plateaus[0]["start"], Imax)}
-                        print(f"new_Imax = {new_Imax}")
-                    """
-
-                if new_Imax:
-                    new_Imax_mean = sum(new_Imax) / len(new_Imax)
-                    if Imax != new_Imax_mean:
-                        print(f"new_Imax = {new_Imax_mean} raw={new_Imax}")
-                        flow_params["Imax"]["value"] = new_Imax_mean
-                        Imax = new_Imax_mean
+
+                # Detect Imax from plateau regions and filter bad files
+                Imax, dropped_files = _detect_imax_from_files(
+                    files, Ikey, fit_data[housing]["Rpm"],
+                    housing, fit_data, default_Imax, debug
+                )
 
                 for file in dropped_files:
                     files.remove(file)
 
-                def vpump_func(x, a: float, b: float):
-                    return a * (x / Imax) ** 2 + b
+                if not files:
+                    print(f"No valid files remaining for site {sname}, skipping")
+                    continue
 
-                params = fit(
-                    Ikey,
-                    fit_data[housing]["Rpm"],
-                    "Rpm",
-                    Imax,
-                    vpump_func,
-                    files,
-                    cwd,
-                    f"{sname}-{mname}",
-                    debug,
-                )
-                flow_params["Vp0"]["value"] = params[1]
-                flow_params["Vpmax"]["value"] = params[0]
-                vp0 = flow_params["Vp0"]["value"]
-                vpmax = flow_params["Vpmax"]["value"]
-                params = []
-
-                # Fit for Flow
-                def flow_func(x, a: float, b: float):
-                    return a + b * vpump_func(x, vpmax, vp0) / (vpmax + vp0)
-
-                params = fit(
-                    Ikey,
-                    fit_data[housing]["Flow"],
-                    "Flow",
-                    Imax,
-                    flow_func,
+                # Extract arrays from record files
+                arrays = _extract_arrays_from_files(
                     files,
-                    cwd,
-                    f"{sname}-{mname}",
-                    debug,
+                    Ikey=Ikey,
+                    rpm_key=fit_data[housing]["Rpm"],
+                    flow_key=fit_data[housing]["Flow"],
+                    pin_key=fit_data[housing]["Pin"],
+                    pout_key=fit_data[housing]["Pout"],
+                    threshold=Imax,
+                    debug=debug,
                 )
-                flow_params["F0"]["value"] = params[0]
-                flow_params["Fmax"]["value"] = params[1]
-                params = []
-
-                # Fit for Pressure
-                def pressure_func(x, a: float, b: float):
-                    return a + b * (vpump_func(x, vpmax, vp0) / (vpmax + vp0)) ** 2
-
-                params = fit(
-                    Ikey,
-                    fit_data[housing]["Pin"],
-                    "Pin",
-                    Imax,
-                    pressure_func,
-                    files,
-                    cwd,
-                    f"{sname}-{mname}",
-                    debug,
-                )
-                flow_params["Pmin"]["value"] = params[0]
-                flow_params["Pmax"]["value"] = params[1]
-                P0 = flow_params["Pmin"]["value"]
-                Pmax = flow_params["Pmax"]["value"]
-                params = []
-
-                # correlation Pout
-                params = stats(
-                    Ikey,
-                    fit_data[housing]["Pout"],
-                    "Pout",
-                    Imax,
-                    files,
-                    cwd,
-                    f"{sname}-{mname}",
-                    debug,
+
+                # Delegate fitting to python_magnetcooling
+                pump_fit, flow_pressure_fit = fit_hydraulic_system(
+                    current=arrays["current"],
+                    pump_speed=arrays["pump_speed"],
+                    flow_rate=arrays["flow_rate"],
+                    pressure=arrays["pressure"],
+                    back_pressure=arrays["back_pressure"],
+                    imax=Imax,
+                    method="simple",
+                    current_threshold=0.0,  # Already filtered in _extract_arrays_from_files
                 )
-                print(f"Pout(mean, std): {params}")
-                Pout = params[0]
-                flow_params["Pout"]["value"] = Pout
 
-                # save flow_params
+                # Build WaterFlow object from fit results
+                waterflow = build_waterflow(pump_fit, flow_pressure_fit)
+
+                # Build and save flow_params dict (backward compatible JSON format)
+                flow_params = _build_flow_params_dict(pump_fit, flow_pressure_fit)
                 print(f"flow_params: {json.dumps(flow_params, indent=4)}")
+
                 filename = f"{cwd}/{sname}_{mname}-flow_params.json"
                 with open(filename, "w") as f:
                     f.write(json.dumps(flow_params, indent=4))
 
+                # Generate diagnostic plots if debug is enabled
+                if debug:
+                    plot_files(
+                        f"{sname}-{mname}",
+                        files,
+                        key1=Ikey,
+                        key2=fit_data[housing]["Rpm"],
+                        fit=None,
+                        show=debug,
+                        debug=debug,
+                        wd=cwd,
+                    )
+
+                # Log fit quality
+                print(
+                    f"Fit results for {sname}/{mname}:\n"
+                    f"  Pump speed: Vpmax={pump_fit.vpmax:.2f} rpm, "
+                    f"Vp0={pump_fit.vp0:.2f} rpm, "
+                    f"R²={pump_fit.fit_result.r_squared:.6f}\n"
+                    f"  Flow rate: F0={flow_pressure_fit.f0:.2f} l/s, "
+                    f"Fmax={flow_pressure_fit.fmax:.2f} l/s, "
+                    f"R²={flow_pressure_fit.flow_fit.r_squared:.6f}\n"
+                    f"  Pressure: Pmin={flow_pressure_fit.pmin:.2f} bar, "
+                    f"Pmax={flow_pressure_fit.pmax:.2f} bar, "
+                    f"R²={flow_pressure_fit.pressure_fit.r_squared:.6f}\n"
+                    f"  Back pressure: {flow_pressure_fit.back_pressure:.2f} "
+                    f"± {flow_pressure_fit.back_pressure_std:.2f} bar\n"
+                    f"  Imax={pump_fit.imax:.0f} A"
+                )
+
         os.chdir(cwd)
+
+    return waterflow
diff --git a/python_magnetapi/hoop_stress.py b/python_magnetapi/hoop_stress.py
index da698fc..78896fa 100644
--- a/python_magnetapi/hoop_stress.py
+++ b/python_magnetapi/hoop_stress.py
@@ -1,289 +1,814 @@
 """
-Extract flow params from records using a fit
+Hoop stress history for a magnet part
+======================================
+Computes, across the full operational lifetime of a ``part``, the hoop stress
+at every timestamp stored in every measurement record, then provides statistics
+and plotting helpers.
+
+Public API
+----------
+compute(session, api_server, auth_headers, oid, mtype="part", ...)
+    → pd.DataFrame   (full time-series, one column per sub-component)
+
+hoop_stats(df, quantiles=(0.25, 0.50, 0.75, 0.90, 0.95, 0.99))
+    → pd.DataFrame   (min / mean / max / quantiles per hoop column)
+
+plot_hoop_history(df, part_name, ...)
+    → matplotlib Figure
+
+plot_hoop_stats(stats_df, part_name, ...)
+    → matplotlib Figure
+
+
+Speedup: precomputed coefficient matrix (linearity argument)
+------------------------------------------------------------
+Hoop stress for component k is:
+
+    σ_k = r_k · j_θ,k · B_total(r_k)
+
+Both j_θ and B are **linear** in the currents:
+
+    j_θ,k      =  j̃_k · I_own_k
+    B_total(r_k) =  Σ_i  B̃_i(r_k) · I_i       (sum over current sources H, B, S)
+
+so σ_k is quadratic in the currents but factors as:
+
+    σ_k(I_H, I_B, …)  =  I_own_k · Σ_i  C[k, i] · I_i
+
+where the **coefficient matrix** C[k, i] = r_k · j̃_k · B̃_i(r_k) depends only
+on the site geometry and is precomputed with n_sources calls to ``getHoop``
+(one per basis current: set I_i = 1 A, all others = 0).
+
+``getHoop`` already returns ``r[m]``, ``j[A/m²]``, ``Bz[T]`` as separate
+columns, so all ingredients are available even when j = 0 (e.g. helix row
+during a bitter-only basis call still provides the Bz contribution from the
+bitters at the helix radius).
+
+The inner loop over every timestamp row then reduces to:
+
+    σ_vec = I_own_vec * (C @ I_vec)     # pure numpy, zero C++ calls
+
+This replaces O(N_rows × N_sources) C++ round-trips with a single matrix–
+vector multiply per row, giving a speedup of ~N_rows (typically 1000–10000×
+for a 30-minute run at 1 Hz).
+
+
+Notes on thread / process safety
+---------------------------------
+``mt.set_currents`` **mutates** the shared C++ objects (Tubes, Helices, …) in
+place.  With the precomputed-coefficient approach, ``set_currents`` and
+``getHoop`` are only called during the *precomputation* phase (n_sources times,
+sequentially).  The hot inner loop is pure numpy and trivially thread-safe.
+
+If the precomputation itself needs to be parallelised across sites, use
+``ProcessPoolExecutor`` where every worker re-initialises its own magnettools
+objects by calling ``msite_setup`` independently (fork-safety of pybind11
+objects is not guaranteed; passing live C++ objects across process boundaries
+is unsafe).
 """
 
+from __future__ import annotations
 
-import tempfile
-import sys
 import os
-import re
+import sys
+import tempfile
+import warnings
+from typing import Sequence
 
 import numpy as np
-from scipy import optimize
-
-import json
 import pandas as pd
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+from matplotlib.gridspec import GridSpec
 from rich.progress import track
-from . import utils
 
+from . import utils
 from python_magnetsetup.ana import msite_setup
 from python_magnetsetup.config import appenv
-
-# from txt2csv import load_files
 from python_magnetrun.MagnetRun import MagnetRun
-
 import magnettools.Bmap as bmap
 import magnettools.magnettools as mt
 
 
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+class _ObjectCache:
+    """Simple request-level cache for API objects (avoids redundant HTTP calls)."""
+
+    def __init__(self):
+        self._store: dict[tuple, dict] = {}
+
+    def get_object(self, session, api_server, auth_headers, mtype, obj_id) -> dict:
+        key = (mtype, obj_id)
+        if key not in self._store:
+            self._store[key] = utils.get_object(
+                session, api_server, headers=auth_headers,
+                mtype=mtype, id=obj_id,
+            )
+        return self._store[key]
+
+
+
+
+class HoopBasis:
+    """
+    Precomputed coefficient matrix for fast hoop-stress evaluation.
+
+    Builds the matrix C[k, i] = r_k · j̃_k · B̃_i(r_k) by making exactly
+    n_sources calls to ``getHoop`` at unit currents (one per current source).
+
+    After construction, ``eval(I_vec)`` returns the hoop stress vector for
+    an arbitrary operating point using only numpy operations — no further
+    C++ calls are needed.
+
+    Parameters
+    ----------
+    Tubes, Helices, OHelices, BMagnets, UMagnets
+        Magnettools objects for the site, already loaded by ``msite_setup``.
+    icurrents_template : list[float]
+        Nominal current vector (used to determine source ordering).
+
+    Attributes
+    ----------
+    comp_names : list[str]
+        Output column names, e.g. ``["H0", "H1", "B0"]``.
+    source_names : list[str]
+        Current source labels in the order expected by ``eval``,
+        e.g. ``["IH_ref", "IB_ref"]``.
+    C : np.ndarray, shape (n_components, n_sources)
+        Coefficient matrix in Pa / A²  (converted to MPa inside ``eval``).
+    I_own_idx : np.ndarray, shape (n_components,)
+        Index into the source vector for the component's own current.
+    """
+
+    def __init__(
+        self,
+        Tubes, Helices, OHelices, BMagnets, UMagnets,
+        icurrents_template: list[float],
+    ):
+        # ── which component types are present? ─────────────────────────────
+        mdata: dict[str, object] = {}
+        if len(Tubes) != 0:
+            mdata["H"] = Tubes
+        if len(BMagnets) != 0:
+            mdata["B"] = BMagnets
+        if len(UMagnets) != 0:
+            mdata["S"] = UMagnets
+
+        # ── source ordering mirrors set_currents argument order ─────────────
+        source_labels: list[str] = []
+        if len(Tubes) != 0:
+            source_labels.append("IH_ref")
+        if len(BMagnets) != 0:
+            source_labels.append("IB_ref")
+        if len(UMagnets) != 0:
+            source_labels.append("IS_ref")
+
+        n_sources = len(source_labels)
+
+        # ── probe call at [1,0,…] to discover component layout ─────────────
+        # (all currents = 0 gives j = 0 for every type, so we need I_H=1 or
+        #  I_B=1 depending on type; we always get r and Bz regardless of j)
+        #
+        # Strategy: for each component type T we need j̃_T (= j at I_own=1 A).
+        # We read j̃_T from the basis call where source_T = 1.
+        # We read B̃_i at each component position from every basis call.
+
+        # First pass: collect component names and own-source index
+        comp_names: list[str] = []
+        comp_own_src: list[int] = []     # index into source_labels
+        comp_r:       list[float] = []
+        comp_j_unit:  list[float] = []   # j at own source = 1 A
+
+        # own-source index for each type
+        type_to_src_idx = {"H": 0, "B": source_labels.index("IB_ref") if "IB_ref" in source_labels else -1,
+                           "S": source_labels.index("IS_ref") if "IS_ref" in source_labels else -1}
+
+        # Perform n_sources basis calls; collect Bz[T] per component
+        # basis_Bz[src_idx][comp_name] = B̃_src at component radius (in T/A)
+        basis_Bz: list[dict[str, float]] = [{} for _ in range(n_sources)]
+
+        n0 = list(icurrents_template)
+
+        for src_idx, src_label in enumerate(source_labels):
+            # unit current vector: 1 A in source src_idx, 0 elsewhere
+            v = [0.0] * n_sources
+            v[src_idx] = 1.0
+            cvec = mt.DoubleVector(v)
+            mt.set_currents(Tubes, Helices, BMagnets, UMagnets, OHelices, cvec)
+
+            for mtype, Magnets in mdata.items():
+                hoop_cols, hoop_vals = bmap.getHoop(
+                    Magnets, Tubes, Helices, BMagnets, UMagnets, mtype
+                )
+                _df = pd.DataFrame.from_records(hoop_vals)
+                _df.columns = hoop_cols
+
+                for _, row in _df.iterrows():
+                    cname = f"{mtype}{row['num']}"
+                    basis_Bz[src_idx][cname] = float(row["Bz[T]"])
+
+                    # on own-source call: harvest r and j̃
+                    if src_idx == type_to_src_idx[mtype]:
+                        if cname not in comp_names:
+                            comp_names.append(cname)
+                            comp_own_src.append(src_idx)
+                            comp_r.append(float(row["r[m]"]))
+                            comp_j_unit.append(float(row["j[A/m\u00b2]"]))
+
+        # ── build coefficient matrix C ─────────────────────────────────────
+        # C[k, i] = r_k · j̃_k · B̃_i(r_k)
+        # Units: m · (A/m²) · (T/A) = m · A/m² · kg/(A·s²)
+        #      = kg/(m·s²) = Pa   (at I²)
+        # We convert to MPa inside eval by multiplying by 1e-6.
+
+        n_comp = len(comp_names)
+        C = np.zeros((n_comp, n_sources), dtype=np.float64)
+        for k, cname in enumerate(comp_names):
+            r_k = comp_r[k]
+            j_k = comp_j_unit[k]     # j at own source = 1 A
+            for i in range(n_sources):
+                C[k, i] = r_k * j_k * basis_Bz[i].get(cname, 0.0)
+
+        self.comp_names: list[str]  = comp_names
+        self.source_names: list[str] = source_labels
+        self.C: np.ndarray           = C                      # (n_comp, n_src)
+        self.I_own_idx: np.ndarray   = np.array(comp_own_src, dtype=np.intp)
+
+        # restore nominal currents so the caller's objects are undisturbed
+        mt.set_currents(
+            Tubes, Helices, BMagnets, UMagnets, OHelices,
+            mt.DoubleVector(n0),
+        )
+
+    def eval(self, I_vec: np.ndarray) -> np.ndarray:
+        """
+        Evaluate hoop stress [MPa] for a 1-D current vector ``I_vec``
+        (length = n_sources, order = self.source_names).
+
+        Returns a 1-D array of length n_components (order = self.comp_names).
+        """
+        # σ_k = I_own_k · Σ_i C[k,i] · I_i   (in Pa)
+        # converted to MPa via 1e-6
+        I_own = I_vec[self.I_own_idx]
+        return I_own * (self.C @ I_vec) * 1e-6
+
+    def eval_dataframe(
+        self,
+        ih_arr:  np.ndarray | None,
+        ib_arr:  np.ndarray | None,
+        is_arr:  np.ndarray | None,
+    ) -> pd.DataFrame:
+        """
+        Vectorised evaluation over arrays of current values.
+
+        Parameters
+        ----------
+        ih_arr, ib_arr, is_arr
+            1-D arrays of current values (or ``None`` if source absent).
+            All present arrays must have the same length N.
+
+        Returns
+        -------
+        pd.DataFrame, shape (N, n_components), columns = self.comp_names.
+        """
+        # Build current matrix  I_mat: shape (N, n_sources)
+        n = None
+        parts: dict[str, np.ndarray] = {}
+        for arr, label in zip(
+            [ih_arr, ib_arr, is_arr], ["IH_ref", "IB_ref", "IS_ref"]
+        ):
+            if arr is not None and label in self.source_names:
+                parts[label] = arr
+                n = len(arr)
+
+        if n is None:
+            raise ValueError("At least one current array must be provided.")
+
+        I_mat = np.zeros((n, len(self.source_names)), dtype=np.float64)
+        for i, label in enumerate(self.source_names):
+            if label in parts:
+                I_mat[:, i] = parts[label]
+
+        # σ_mat[row, k] = I_own[k] · Σ_i C[k,i]·I[row,i]
+        # = (I_mat @ C.T) elementwise * I_own_mat
+        # I_own_mat[row, k] = I_mat[row, I_own_idx[k]]
+        CIt    = (I_mat @ self.C.T)                  # (N, n_comp)  in Pa·A
+        I_own_mat = I_mat[:, self.I_own_idx]         # (N, n_comp)
+        sigma_MPa = CIt * I_own_mat * 1e-6           # (N, n_comp)  in MPa
+
+        return pd.DataFrame(sigma_MPa, columns=self.comp_names)
+
+
+
+# ---------------------------------------------------------------------------
+# Main compute function
+# ---------------------------------------------------------------------------
+
 def compute(
     session,
     api_server: str,
-    headers: dict,
+    auth_headers: dict,
     oid: int,
     mtype: str = "part",
     verbose: bool = False,
     debug: bool = False,
-):
+) -> pd.DataFrame | None:
     """
-    compute hoop stress for a given part
+    Compute the full hoop-stress history for *oid* (a part id).
+
+    Returns
+    -------
+    pd.DataFrame
+        Columns: ``timestamp``, ``site``, ``record``, current columns
+        (``IH_ref``, ``IB_ref``, ``IS_ref`` when present), then one
+        ``{type}{num}`` column per sub-component (e.g. ``H0``, ``H1``,
+        ``B0``).  The DataFrame is sorted by ``timestamp``.
+
+    Returns ``None`` if the part type is unsupported or no data is found.
     """
     if mtype != "part":
-        print(f"hoop_stress.compute: expect a part - got a {mtype}")
+        print(f"hoop_stress.compute: expected a part – got '{mtype}'")
         return None
 
-    part = utils.get_object(
-        session,
-        f"{api_server}",
-        headers=headers,
-        mtype="part",
-        id=oid,
-        verbose=verbose,
-        debug=debug,
+    cache = _ObjectCache()
+
+    part = cache.get_object(
+        session, api_server, auth_headers, "part", oid
     )
     if debug:
         print(f"part: {part}")
-    part_type = part["type"]
-    if part["type"] == "helix":
-        mpart = "H"
-    elif part["type"] == "bitter":
-        mpart = "B"
-    elif part["type"] == "supra":
-        mpart = "S"
-    else:
+
+    part_type = part.get("type", "")
+    if part_type not in ("helix", "bitter", "supra"):
         print(
-            f"hoop_stress.compute: expect a part of type (helix|bitter|supra) - got a {part_type} for part={part['name']}"
+            f"hoop_stress.compute: unsupported part type '{part_type}' "
+            f"for part '{part['name']}'"
         )
         return None
 
     print(
-        f"hoop_stress.compute: api_server={api_server}, mtype={mtype}, otype='site', id={oid}, name={part['name']}"
+        f"\nhoop_stress.compute: part='{part['name']}' (type={part_type})"
+        f"  api={api_server}"
     )
-    cwd = os.getcwd()
-    print(f"cwd={cwd}")
 
     sites = utils.get_history(
-        session, api_server, headers, oid, mtype=mtype, otype="site", debug=debug
+        session, api_server, auth_headers, oid,
+        mtype=mtype, otype="site",
     )
+    if not sites:
+        print("  No sites found – nothing to process.")
+        return None
+
     if debug:
-        print(f"sites: {sites}")
+        print(f"sites ({len(sites)}): {[s.get('name', s.get('id')) for s in sites]}")
+
+    cwd = os.getcwd()
+    all_frames: list[pd.DataFrame] = []
+    # pnames_by_site[site_name] = {part_api_name: positional_label}
+    # preserved in result.attrs for downstream label mapping
+    pnames_by_site: dict[str, dict[str, str]] = {}
 
     with tempfile.TemporaryDirectory() as tempdir:
         os.chdir(tempdir)
-        data_dir = f"{tempdir}/data"
-        os.mkdir(f"{tempdir}/data")
-        os.mkdir(f"{tempdir}/data/geometries")
-        print(f"moving to {tempdir}")
-
-        nsites = len(sites)
-        print(f"Processing sites for part {part['name']}...")
-        for i in range(
-            nsites
-        ):  # track(range(nsites), description=f"Processing sites for part {part['name']}..."):
-            # get site with records
-            site = utils.get_object(
-                session,
-                f"{api_server}",
-                headers=headers,
-                mtype="site",
-                id=sites[i]["id"],
-                verbose=verbose,
-                debug=debug,
+        data_dir = os.path.join(tempdir, "data")
+        os.makedirs(os.path.join(data_dir, "geometries"), exist_ok=True)
+
+        for site_stub in track(sites, description="Sites"):
+            site = cache.get_object(
+                session, api_server, auth_headers, "site", site_stub["id"],
             )
-            # print(f"site[{i}]: {sites[i]['name']}")
+            site_name = site.get("name", str(site["id"]))
 
-            # add route to get data in visualisation
+            # ── geometry setup ──────────────────────────────────────────────
             config_data = utils.get_data(
-                session, api_server, headers, oid=site["id"], mtype="site", debug=debug
+                session, api_server, auth_headers,
+                oid=site["id"], mtype="site",
             )
 
-            # create datastruct for Hoop calc
-            # pname: dict to hold partname <-> Hn or Bn or Sn
-            pnames = dict()
-            for magnet in site["site_magnets"]:
-                _id = magnet["magnet_id"]
-                _object = utils.get_object(
-                    session,
-                    f"{api_server}",
-                    headers=headers,
-                    mtype="magnet",
-                    id=_id,
-                    verbose=verbose,
-                    debug=debug,
-                )
-                # print(f"magnet: {_object}")
-                geom_data = _object["geometry"]
-                yamlfile = geom_data["filename"]
-                attach = geom_data["id"]
-                filename = utils.download(
-                    session,
-                    api_server,
-                    headers,
-                    attach,
-                    wd=f"{tempdir}/data/geometries",
-                    debug=debug,
+            # pnames: part_name → positional label (H1, B2, …) — local to this site
+            pnames: dict[str, str] = {}
+            num_by_type: dict[str, int] = {"H": 0, "B": 0, "S": 0}
+            for magnet_stub in site.get("site_magnets", []):
+                magnet_id = magnet_stub["magnet_id"]
+                magnet = cache.get_object(
+                    session, api_server, auth_headers, "magnet", magnet_id,
                 )
-                # print(f"magnet: {_object['name']} {yamlfile}")
-                num = 0
-                for part in _object["magnet_parts"]:
-                    _pid = part["part_id"]
-                    _ptype = part["part"]["type"]
-                    if _ptype in ["helix", "bitter", "supra"]:
-                        _pobject = utils.get_object(
-                            session,
-                            f"{api_server}",
-                            headers=headers,
-                            mtype="part",
-                            id=_pid,
-                            verbose=verbose,
-                            debug=debug,
-                        )
-                        # print(f"part: {_pobject}")
-                        geom_data = _pobject["geometries"][0]
-                        yamlfile = geom_data["attachment"]["filename"]
-                        attach = geom_data["attachment"]["id"]
-                        filename = utils.download(
-                            session,
-                            api_server,
-                            headers,
-                            attach,
-                            wd=f"{tempdir}/data/geometries",
-                            debug=debug,
-                        )
-                        print(
-                            f"part: {_pobject['name']} {yamlfile} {_ptype.upper()[0]}{num+1}"
-                        )
-                        pnames[_pobject["name"]] = f"{_ptype.upper()[0]}{num+1}"
-                        num += 1
+
+                # download magnet geometry yaml
+                geom_data = magnet.get("geometry", {})
+                if geom_data:
+                    utils.download(
+                        session, api_server, auth_headers,
+                        geom_data["id"],
+                        wd=os.path.join(data_dir, "geometries"),
+                    )
+
+                # download part geometries and build pnames
+                for part_stub in magnet.get("magnet_parts", []):
+                    _pid = part_stub["part_id"]
+                    _ptype = part_stub["part"].get("type", "")
+                    if _ptype not in ("helix", "bitter", "supra"):
+                        continue
+                    _pobj = cache.get_object(
+                        session, api_server, auth_headers, "part", _pid,
+                    )
+                    for geom in _pobj.get("geometries", []):
+                        attach = geom.get("attachment", {})
+                        if attach:
+                            utils.download(
+                                session, api_server, auth_headers,
+                                attach["id"],
+                                wd=os.path.join(data_dir, "geometries"),
+                            )
+                    type_key = _ptype.upper()[0]  # H / B / S
+                    num_by_type[type_key] += 1
+                    pnames[_pobj["name"]] = f"{type_key}{num_by_type[type_key]}"
+
+            # record the site-local name mapping for later reference
+            pnames_by_site[site_name] = pnames
 
             env = appenv(
                 envfile=None,
                 url_api=data_dir,
-                yaml_repo=f"{data_dir}/geometries",
-                cad_repo=f"{data_dir}/cad",
+                yaml_repo=os.path.join(data_dir, "geometries"),
+                cad_repo=os.path.join(data_dir, "cad"),
                 mesh_repo=data_dir,
                 simage_repo=data_dir,
                 mrecord_repo=data_dir,
                 optim_repo=data_dir,
             )
-            site_data = msite_setup(env, config_data["results"], debug)
-            (Tubes, Helices, OHelices, BMagnets, UMagnets, Shims) = site_data
-            icurrents = mt.get_currents(Tubes, Helices, BMagnets, UMagnets)
-
-            mdata = {"H": Helices, "B": BMagnets}
-            if len(icurrents) == 3:
-                mdata["S"] = UMagnets
-
-            # get record data
-            total = 0
-            # records = utils.get_history(session, api_server, headers, site['site_id'], mtype='site', otype='record', verbose=debug, debug=debug) #site_obj['records']
-            nrecords = len(site["records"])
-            for j in track(
-                range(nrecords),
-                description=f"Processing records for site id={site['name']}...",
+            try:
+                site_data = msite_setup(env, config_data["results"], debug)
+            except Exception as exc:
+                warnings.warn(
+                    f"msite_setup failed for site '{site_name}': {exc} – skipping"
+                )
+                continue
+
+            Tubes, Helices, OHelices, BMagnets, UMagnets, Shims = site_data
+            icurrents_template = list(mt.get_currents(Tubes, Helices, BMagnets, UMagnets))
+
+            # ── precompute coefficient matrix (n_sources getHoop calls only) ─
+            try:
+                basis = HoopBasis(
+                    Tubes, Helices, OHelices, BMagnets, UMagnets,
+                    icurrents_template,
+                )
+            except Exception as exc:
+                warnings.warn(
+                    f"HoopBasis precomputation failed for site '{site_name}': {exc} – skipping"
+                )
+                continue
+
+            if debug:
+                print(
+                    f"  [{site_name}] basis: {len(basis.comp_names)} components, "
+                    f"{len(basis.source_names)} sources\n"
+                    f"  C =\n{basis.C}"
+                )
+
+            # ── records loop  (no C++ calls inside) ─────────────────────────
+            records = site.get("records", [])
+            for rec in track(
+                records,
+                description=f"  Records [{site_name}]",
+                transient=True,
             ):
-                f = site["records"][j]
-                # print(f'f={f}')
-                attach = f["attachment_id"]
-                filename = utils.download(session, api_server, headers, attach, debug)
-                housing = filename.split("_")[0]
-                if filename.endswith(".txt"):
-                    rundata = MagnetRun.fromtxt(housing, site["name"], filename)
-                else:
-                    rundata = MagnetRun.fromcsv(housing, site["name"], filename)
-                total += 1
-
-                # extract timestamp, currents from rundata
-                df = rundata.MagnetData.Data[["timestamp", "Field", "IH_ref", "IB_ref"]]
-                # print(f'df: {df}')
-
-                """
-                def Hoopstress(row):
-                    # update Ih, Ib, Is range
-                    vcurrents = list(icurrents)
-                    num = 0
-                    if len(Tubes) != 0: vcurrents[num] = row.IH_ref; num += 1
-                    if len(BMagnets) != 0: vcurrents[num] = row.IB_ref; num += 1
-                    if len(UMagnets) != 0: vcurrents[num] = 0; num += 1
-
-                    currents = mt.DoubleVector(vcurrents)
-                    mt.set_currents(Tubes, Helices, BMagnets, UMagnets, OHelices, currents)
-
-                    for magnet_type in mdata:
-                        Magnets = mdata[magnet_type]
-                        (headers, values) = bmap.getHoop(Magnets, Tubes, Helices, BMagnets, UMagnets, magnet_type)
-                        _df = pd.DataFrame.from_records(values)
-                        _df.columns = headers
-                        vheaders = _df['num'].tolist()
-                        values = _df['Hoop[MPa]'].to_numpy()
-                        print(f"_df = {vheaders}, {values}")
-                        for k,vheader in enumerate(vheaders):
-                            row.vheader = values[k]
-
-                df.apply(lambda row: Hoopstress(row), axis=1)
-                print(f'df: {df}')
-                """
-
-                data = dict()
-                for magnet_type in mdata:
-                    Magnets = mdata[magnet_type]
-                    (headers, values) = bmap.getHoop(
-                        Magnets, Tubes, Helices, BMagnets, UMagnets, magnet_type
-                    )
-                    _df = pd.DataFrame.from_records(values)
-                    _df.columns = headers
-                    vheaders = _df["num"].tolist()
-                    for k, vheader in enumerate(vheaders):
-                        data[vheader] = []
-
-                for _ih, _ib in zip(df["IH_ref"].to_numpy(), df["IB_ref"].to_numpy()):
-                    # print(f"Ih={_ih}, Ib={_ib}")
-                    # update Ih, Ib, Is range
-                    vcurrents = list(icurrents)
-                    num = 0
-                    if len(Tubes) != 0:
-                        vcurrents[num] = _ih
-                        num += 1
-                    if len(BMagnets) != 0:
-                        vcurrents[num] = _ib
-                        num += 1
-                    if len(UMagnets) != 0:
-                        vcurrents[num] = 0
-                        num += 1
-
-                    currents = mt.DoubleVector(vcurrents)
-                    mt.set_currents(
-                        Tubes, Helices, BMagnets, UMagnets, OHelices, currents
+                attach = rec.get("attachment_id")
+                if attach is None:
+                    continue
+
+                filename = utils.download(
+                    session, api_server, auth_headers,
+                    attach,
+                    wd=tempdir,
+                )
+                if filename is None:
+                    continue
+
+                housing = os.path.basename(filename).split("_")[0]
+                try:
+                    if filename.endswith(".txt"):
+                        rundata = MagnetRun.fromtxt(housing, site_name, filename)
+                    else:
+                        rundata = MagnetRun.fromcsv(housing, site_name, filename)
+                except Exception as exc:
+                    warnings.warn(f"Cannot parse record '{rec.get('name')}': {exc}")
+                    continue
+
+                raw_df = rundata.MagnetData.Data
+
+                # select available, relevant columns
+                base_cols = ["timestamp", "Field"]
+                current_cols = [c for c in basis.source_names if c in raw_df.columns]
+                available = [c for c in base_cols + current_cols if c in raw_df.columns]
+                if not current_cols:
+                    warnings.warn(
+                        f"Record '{rec.get('name')}': no matching current columns "
+                        f"(need {basis.source_names}) – skipping"
                     )
+                    continue
+                df_run = raw_df[available].copy()
+
+                # ── vectorised hoop stress (pure numpy, no C++ in hot path) ──
+                ih_arr = df_run["IH_ref"].to_numpy() if "IH_ref" in df_run.columns else None
+                ib_arr = df_run["IB_ref"].to_numpy() if "IB_ref" in df_run.columns else None
+                is_arr = df_run["IS_ref"].to_numpy() if "IS_ref" in df_run.columns else None
+
+                hoop_df = basis.eval_dataframe(ih_arr, ib_arr, is_arr)
+                # hoop_df: shape (N, n_components), columns = basis.comp_names
+
+                # attach metadata columns
+                hoop_df.insert(0, "timestamp", df_run["timestamp"].to_numpy())
+                hoop_df.insert(1, "site",      site_name)
+                hoop_df.insert(2, "record",    rec.get("name", str(rec.get("id"))))
+                if "Field" in df_run.columns:
+                    hoop_df.insert(3, "Field[T]", df_run["Field"].to_numpy())
+                for col in current_cols:
+                    hoop_df[col] = df_run[col].to_numpy()
+
+                all_frames.append(hoop_df)
 
-                    for magnet_type in mdata:
-                        Magnets = mdata[magnet_type]
-                        (headers, values) = bmap.getHoop(
-                            Magnets, Tubes, Helices, BMagnets, UMagnets, magnet_type
-                        )
-                        _df = pd.DataFrame.from_records(values)
-                        _df.columns = headers
-                        vheaders = _df["num"].tolist()
-                        values = _df["Hoop[MPa]"].to_numpy()
-                        # print(f"_df = {vheaders}, {values}")
-                        for k, vheader in enumerate(vheaders):
-                            data[vheader].append(values[i])
-
-                for key in data:
-                    df.insert(2, key, data[vheader], True)
-                print(f"df: {df}")
-
-                # add plot
-                sys.exit(1)
-            print(f"Processed {total} records for {site['name']}.")
         os.chdir(cwd)
+
+    if not all_frames:
+        print("No data collected.")
+        return None
+
+    result = pd.concat(all_frames, ignore_index=True)
+    result.sort_values("timestamp", inplace=True)
+    result.reset_index(drop=True, inplace=True)
+
+    # Attach metadata as DataFrame attrs for downstream use
+    result.attrs["part_name"] = part["name"]
+    result.attrs["part_type"] = part_type
+    result.attrs["pnames_by_site"] = pnames_by_site  # {site_name: {api_name: label}}
+
+    print(
+        f"\nDone – {len(result):,} rows across "
+        f"{result['site'].nunique()} site(s) / "
+        f"{result['record'].nunique()} record(s)."
+    )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Statistics
+# ---------------------------------------------------------------------------
+
+def hoop_columns(df: pd.DataFrame) -> list[str]:
+    """Return the hoop-stress column names (H*, B*, S*) from the result DataFrame."""
+    return [c for c in df.columns if len(c) >= 2 and c[0] in "HBS" and c[1:].isdigit()]
+
+
+def hoop_stats(
+    df: pd.DataFrame,
+    quantiles: Sequence[float] = (0.25, 0.50, 0.75, 0.90, 0.95, 0.99),
+) -> pd.DataFrame:
+    """
+    Compute statistics for every hoop-stress column.
+
+    Returns
+    -------
+    pd.DataFrame
+        Index = column name (e.g. H0, H1, B0).
+        Columns = count, min, mean, max, std, then one per quantile.
+    """
+    hcols = hoop_columns(df)
+    if not hcols:
+        raise ValueError("No hoop-stress columns found in DataFrame.")
+
+    rows = []
+    for col in hcols:
+        series = df[col].dropna()
+        row = {
+            "component": col,
+            "count": len(series),
+            "min [MPa]": series.min(),
+            "mean [MPa]": series.mean(),
+            "max [MPa]": series.max(),
+            "std [MPa]": series.std(),
+        }
+        for q in quantiles:
+            row[f"q{int(q * 100):02d} [MPa]"] = series.quantile(q)
+        rows.append(row)
+
+    stats_df = pd.DataFrame(rows).set_index("component")
+    return stats_df
+
+
+# ---------------------------------------------------------------------------
+# Plots
+# ---------------------------------------------------------------------------
+
+_PALETTE = [
+    "#2563EB", "#DC2626", "#16A34A", "#D97706",
+    "#7C3AED", "#0891B2", "#DB2777", "#65A30D",
+]
+
+
+def plot_hoop_history(
+    df: pd.DataFrame,
+    part_name: str | None = None,
+    figsize: tuple[int, int] = (14, 5),
+    show: bool = True,
+    savepath: str | None = None,
+) -> plt.Figure:
+    """
+    Time-series plot of hoop stress for every sub-component.
+
+    Light vertical bands mark site boundaries.
+    """
+    hcols = hoop_columns(df)
+    if not hcols:
+        raise ValueError("No hoop-stress columns found.")
+
+    pname = part_name or df.attrs.get("part_name", "part")
+
+    fig, ax = plt.subplots(figsize=figsize)
+    ax.set_facecolor("#F8FAFC")
+    fig.patch.set_facecolor("#FFFFFF")
+
+    # shade site bands
+    sites = df["site"].unique()
+    site_colors = ["#EFF6FF", "#F0FDF4", "#FFF7ED", "#FDF4FF"]
+    site_df = df.sort_values("timestamp")
+    for k, sname in enumerate(sites):
+        mask = site_df["site"] == sname
+        t_min = site_df.loc[mask, "timestamp"].min()
+        t_max = site_df.loc[mask, "timestamp"].max()
+        ax.axvspan(t_min, t_max, color=site_colors[k % len(site_colors)], alpha=0.6,
+                   label=f"site: {sname}" if k < 4 else None)
+
+    # hoop stress lines
+    for i, col in enumerate(hcols):
+        color = _PALETTE[i % len(_PALETTE)]
+        ax.plot(
+            df["timestamp"], df[col],
+            color=color, linewidth=0.8, alpha=0.85,
+            label=col,
+        )
+
+    ax.set_xlabel("Time", fontsize=11)
+    ax.set_ylabel("Hoop stress [MPa]", fontsize=11)
+    ax.set_title(f"Hoop stress history — {pname}", fontsize=13, fontweight="bold")
+    ax.grid(True, linestyle="--", linewidth=0.5, alpha=0.6)
+    ax.legend(loc="upper left", fontsize=9, framealpha=0.9)
+
+    # Format x-axis as dates if timestamps are datetime-like
+    try:
+        ax.xaxis.set_major_formatter(mdates.DateFormatter("%Y-%m"))
+        fig.autofmt_xdate()
+    except Exception:
+        pass
+
+    fig.tight_layout()
+    if savepath:
+        fig.savefig(savepath, dpi=150, bbox_inches="tight")
+    if show:
+        plt.show()
+    return fig
+
+
+def plot_hoop_stats(
+    stats_df: pd.DataFrame,
+    part_name: str | None = None,
+    quantiles_to_show: Sequence[str] | None = None,
+    figsize: tuple[int, int] = (14, 8),
+    show: bool = True,
+    savepath: str | None = None,
+) -> plt.Figure:
+    """
+    Two-panel figure:
+      • Left  – bar chart: min / mean / max per component, with std error bars
+      • Right – CDF-style quantile heatmap (components × quantile levels)
+
+    Also prints a formatted stats table to stdout.
+    """
+    import matplotlib.cm as cm
+    from matplotlib.colors import Normalize
+
+    pname = part_name or "part"
+
+    # identify quantile columns
+    q_cols = [c for c in stats_df.columns if c.startswith("q") and "[MPa]" in c]
+    if quantiles_to_show:
+        q_cols = [c for c in q_cols if c in quantiles_to_show]
+
+    fig = plt.figure(figsize=figsize, facecolor="white")
+    gs = GridSpec(1, 2, figure=fig, width_ratios=[1.4, 1], wspace=0.35)
+    ax_bar  = fig.add_subplot(gs[0])
+    ax_heat = fig.add_subplot(gs[1])
+
+    # ── bar chart ────────────────────────────────────────────────────────────
+    components = stats_df.index.tolist()
+    x = np.arange(len(components))
+    width = 0.25
+
+    ax_bar.bar(x - width, stats_df["min [MPa]"],  width, label="min",  color="#93C5FD", zorder=3)
+    ax_bar.bar(x,          stats_df["mean [MPa]"], width, label="mean", color="#2563EB",
+               yerr=stats_df["std [MPa]"], capsize=4, zorder=3)
+    ax_bar.bar(x + width,  stats_df["max [MPa]"],  width, label="max",  color="#1E3A5F", zorder=3)
+
+    ax_bar.set_xticks(x)
+    ax_bar.set_xticklabels(components, fontsize=10)
+    ax_bar.set_ylabel("Hoop stress [MPa]", fontsize=11)
+    ax_bar.set_title(f"Min / Mean / Max — {pname}", fontsize=12, fontweight="bold")
+    ax_bar.legend(fontsize=9)
+    ax_bar.set_facecolor("#F8FAFC")
+    ax_bar.grid(axis="y", linestyle="--", linewidth=0.5, alpha=0.6, zorder=0)
+
+    # ── quantile heatmap ─────────────────────────────────────────────────────
+    if q_cols:
+        heat_data = stats_df[q_cols].values
+        norm = Normalize(vmin=heat_data.min(), vmax=heat_data.max())
+        im = ax_heat.imshow(heat_data, aspect="auto", cmap="YlOrRd", norm=norm)
+
+        ax_heat.set_xticks(np.arange(len(q_cols)))
+        ax_heat.set_xticklabels(
+            [c.replace(" [MPa]", "") for c in q_cols], rotation=45, ha="right", fontsize=9
+        )
+        ax_heat.set_yticks(np.arange(len(components)))
+        ax_heat.set_yticklabels(components, fontsize=10)
+        ax_heat.set_title("Quantiles [MPa]", fontsize=12, fontweight="bold")
+
+        # annotate cells
+        for r in range(heat_data.shape[0]):
+            for c in range(heat_data.shape[1]):
+                ax_heat.text(
+                    c, r, f"{heat_data[r, c]:.1f}",
+                    ha="center", va="center", fontsize=8,
+                    color="white" if norm(heat_data[r, c]) > 0.6 else "black",
+                )
+
+        fig.colorbar(im, ax=ax_heat, shrink=0.8, label="MPa")
+    else:
+        ax_heat.axis("off")
+
+    fig.suptitle(
+        f"Hoop stress statistics — {pname}",
+        fontsize=14, fontweight="bold", y=1.01,
+    )
+    fig.tight_layout()
+
+    # ── stdout table ─────────────────────────────────────────────────────────
+    try:
+        from tabulate import tabulate
+        print(f"\n{tabulate(stats_df.round(2), headers='keys', tablefmt='rounded_outline')}")
+    except ImportError:
+        print(f"\n{stats_df.round(2).to_string()}")
+
+    if savepath:
+        fig.savefig(savepath, dpi=150, bbox_inches="tight")
+    if show:
+        plt.show()
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Convenience: run everything in one call
+# ---------------------------------------------------------------------------
+
+def run(
+    session,
+    api_server: str,
+    auth_headers: dict,
+    oid: int,
+    quantiles: Sequence[float] = (0.25, 0.50, 0.75, 0.90, 0.95, 0.99),
+    verbose: bool = False,
+    debug: bool = False,
+    show_plots: bool = True,
+    output_prefix: str | None = None,
+) -> tuple[pd.DataFrame | None, pd.DataFrame | None]:
+    """
+    Full pipeline: compute → stats → plots.
+
+    Returns ``(history_df, stats_df)``.
+    If *output_prefix* is given, saves CSV and PNG files.
+    """
+    df = compute(session, api_server, auth_headers, oid,
+                 mtype="part", verbose=verbose, debug=debug)
+    if df is None:
+        return None, None
+
+    stats_df = hoop_stats(df, quantiles=quantiles)
+    pname = df.attrs.get("part_name", str(oid))
+
+    history_savepath = f"{output_prefix}_history.png" if output_prefix else None
+    stats_savepath   = f"{output_prefix}_stats.png"   if output_prefix else None
+
+    plot_hoop_history(df, part_name=pname, show=show_plots, savepath=history_savepath)
+    plot_hoop_stats(stats_df, part_name=pname, show=show_plots, savepath=stats_savepath)
+
+    if output_prefix:
+        df.to_csv(f"{output_prefix}_history.csv", index=False)
+        stats_df.to_csv(f"{output_prefix}_stats.csv")
+        print(f"Saved CSV  → {output_prefix}_history.csv")
+        print(f"Saved CSV  → {output_prefix}_stats.csv")
+        print(f"Saved PNG  → {history_savepath}")
+        print(f"Saved PNG  → {stats_savepath}")
+
+    return df, stats_df
diff --git a/python_magnetapi/hoop_stress_parallel.py b/python_magnetapi/hoop_stress_parallel.py
new file mode 100644
index 0000000..3e6781a
--- /dev/null
+++ b/python_magnetapi/hoop_stress_parallel.py
@@ -0,0 +1,477 @@
+"""
+Hoop stress history — parallelised version
+==========================================
+Drop-in replacement for ``hoop_stress.compute``.  All statistics and plotting
+helpers are re-exported from the sequential module unchanged.
+
+Parallelisation strategy
+------------------------
+The computation splits into two phases:
+
+Phase 1 — sequential, main process
+    For each site:
+      • download geometry files  (network I/O)
+      • ``msite_setup``          (disk I/O + lightweight C++)
+      • ``HoopBasis(...)``       (n_sources C++ calls, typically 2–3)
+      • download all record files (network I/O)
+      • enqueue one Task per record
+
+Phase 2 — parallel, ProcessPoolExecutor
+    Each worker receives a ``_RecordTask`` (fully picklable):
+      site_name, record_name, housing, filepath, HoopBasis
+
+    The worker:
+      1. parses the record file with MagnetRun
+      2. calls basis.eval_dataframe(...)  — pure numpy, no C++
+      3. returns a partial DataFrame
+
+Phase 3 — sequential, main process
+    pd.concat(partial frames) → sort by timestamp → attach attrs
+
+Why ProcessPoolExecutor, not ThreadPoolExecutor?
+    Phase 2 workers do real CPU work (numpy matrix multiply) and file I/O.
+    The GIL would prevent true CPU parallelism with threads.  Processes give
+    genuine concurrency.
+
+Why HoopBasis is safely picklable
+    Its attributes are: comp_names (list[str]), source_names (list[str]),
+    C (np.ndarray), I_own_idx (np.ndarray).  No C++ objects, no file handles.
+    pickle serialises these without issue across process boundaries.
+
+Why C++ objects are NOT passed to workers
+    pybind11-wrapped objects (Tubes, Helices, …) do not implement ``__reduce__``
+    and are not pickle-serialisable.  Even if they were, ``set_currents``
+    mutates them in place, which is unsafe across a shared-memory fork.
+    Keeping C++ entirely in Phase 1 sidesteps both issues.
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+import tempfile
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from dataclasses import dataclass
+from typing import Sequence
+
+import numpy as np
+import pandas as pd
+from rich.progress import Progress, SpinnerColumn, BarColumn, TextColumn, TimeElapsedColumn
+
+# Re-export stats and plot helpers unchanged — no need to duplicate them
+from .hoop_stress import (          # noqa: F401  (re-exported for callers)
+    HoopBasis,
+    _ObjectCache,
+    hoop_columns,
+    hoop_stats,
+    plot_hoop_history,
+    plot_hoop_stats,
+)
+from . import utils
+from python_magnetsetup.ana import msite_setup
+from python_magnetsetup.config import appenv
+from python_magnetrun.MagnetRun import MagnetRun
+import magnettools.magnettools as mt
+
+
+# ---------------------------------------------------------------------------
+# Worker task descriptor  (must be picklable → plain dataclass, no C++ refs)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class _RecordTask:
+    """All data a worker needs to process one record file."""
+    site_name:   str
+    record_name: str
+    housing:     str
+    filepath:    str
+    basis:       HoopBasis   # picklable: only numpy arrays + lists
+
+
+# ---------------------------------------------------------------------------
+# Worker function  (module-level so ProcessPoolExecutor can pickle it)
+# ---------------------------------------------------------------------------
+
+def _process_record(task: _RecordTask) -> pd.DataFrame | None:
+    """
+    Parse one record file and evaluate hoop stress via the precomputed basis.
+
+    Runs entirely in a worker process.  No C++ calls.
+
+    Returns
+    -------
+    pd.DataFrame or None
+        Columns: timestamp, site, record, Field[T] (if present),
+        current columns, then one hoop column per component.
+        Returns ``None`` on any unrecoverable error (warning already issued).
+    """
+    try:
+        if task.filepath.endswith(".txt"):
+            rundata = MagnetRun.fromtxt(task.housing, task.site_name, task.filepath)
+        else:
+            rundata = MagnetRun.fromcsv(task.housing, task.site_name, task.filepath)
+    except Exception as exc:
+        warnings.warn(f"[{task.record_name}] cannot parse: {exc}")
+        return None
+
+    raw_df = rundata.MagnetData.Data
+
+    current_cols = [c for c in task.basis.source_names if c in raw_df.columns]
+    if not current_cols:
+        warnings.warn(
+            f"[{task.record_name}] no matching current columns "
+            f"(need {task.basis.source_names}) – skipped"
+        )
+        return None
+
+    ih_arr = raw_df["IH_ref"].to_numpy() if "IH_ref" in raw_df.columns else None
+    ib_arr = raw_df["IB_ref"].to_numpy() if "IB_ref" in raw_df.columns else None
+    is_arr = raw_df["IS_ref"].to_numpy() if "IS_ref" in raw_df.columns else None
+
+    try:
+        hoop_df = task.basis.eval_dataframe(ih_arr, ib_arr, is_arr)
+    except Exception as exc:
+        warnings.warn(f"[{task.record_name}] eval_dataframe failed: {exc}")
+        return None
+
+    # Prepend metadata columns
+    n = len(hoop_df)
+    hoop_df.insert(0, "timestamp", raw_df["timestamp"].to_numpy() if "timestamp" in raw_df.columns else np.arange(n))
+    hoop_df.insert(1, "site",      task.site_name)
+    hoop_df.insert(2, "record",    task.record_name)
+    if "Field" in raw_df.columns:
+        hoop_df.insert(3, "Field[T]", raw_df["Field"].to_numpy())
+    for col in current_cols:
+        hoop_df[col] = raw_df[col].to_numpy()
+
+    return hoop_df
+
+
+# ---------------------------------------------------------------------------
+# Main parallel compute function
+# ---------------------------------------------------------------------------
+
+def compute(
+    session,
+    api_server: str,
+    auth_headers: dict,
+    oid: int,
+    mtype: str = "part",
+    max_workers: int | None = None,
+    verbose: bool = False,
+    debug: bool = False,
+) -> pd.DataFrame | None:
+    """
+    Parallel version of ``hoop_stress.compute``.
+
+    Phase 1 (this process): geometry downloads + ``HoopBasis`` precomputation
+    per site, then record file downloads.
+
+    Phase 2 (worker pool): one task per record, evaluated with pure numpy.
+
+    Parameters
+    ----------
+    max_workers : int or None
+        Number of worker processes.  ``None`` lets Python choose
+        (typically ``os.cpu_count()``).  A value of 1 effectively runs
+        sequentially but still exercises the multiprocessing path.
+
+    All other parameters identical to ``hoop_stress.compute``.
+
+    Returns
+    -------
+    pd.DataFrame or None
+        Identical schema to the sequential version.
+    """
+    if mtype != "part":
+        print(f"hoop_stress_parallel.compute: expected a part – got '{mtype}'")
+        return None
+
+    cache = _ObjectCache()
+
+    part = cache.get_object(
+        session, api_server, auth_headers, "part", oid,
+    )
+    part_type = part.get("type", "")
+    if part_type not in ("helix", "bitter", "supra"):
+        print(
+            f"hoop_stress_parallel.compute: unsupported part type '{part_type}' "
+            f"for part '{part['name']}'"
+        )
+        return None
+
+    print(
+        f"\nhoop_stress_parallel.compute: part='{part['name']}' (type={part_type})"
+        f"  api={api_server}  max_workers={max_workers or 'auto'}"
+    )
+
+    sites = utils.get_history(
+        session, api_server, auth_headers, oid,
+        mtype=mtype, otype="site",
+    )
+    if not sites:
+        print("  No sites found – nothing to process.")
+        return None
+
+    cwd = os.getcwd()
+    tasks:          list[_RecordTask]         = []
+    pnames_by_site: dict[str, dict[str, str]] = {}
+
+    # =========================================================================
+    # Phase 1 — sequential: geometry + basis precomputation, file downloads
+    # =========================================================================
+    with tempfile.TemporaryDirectory() as tempdir:
+        os.chdir(tempdir)
+        data_dir = os.path.join(tempdir, "data")
+        os.makedirs(os.path.join(data_dir, "geometries"), exist_ok=True)
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[bold blue]{task.description}"),
+            BarColumn(),
+            TextColumn("{task.completed}/{task.total}"),
+            TimeElapsedColumn(),
+        ) as progress:
+
+            site_bar = progress.add_task("Phase 1 – sites", total=len(sites))
+
+            for site_stub in sites:
+                site = cache.get_object(
+                    session, api_server, auth_headers, "site", site_stub["id"],
+                )
+                site_name = site.get("name", str(site["id"]))
+                progress.update(site_bar, description=f"Phase 1 – {site_name}")
+
+                # ── geometry files ──────────────────────────────────────────
+                config_data = utils.get_data(
+                    session, api_server, auth_headers,
+                    oid=site["id"], mtype="site",
+                )
+
+                pnames: dict[str, str] = {}
+                num_by_type: dict[str, int] = {"H": 0, "B": 0, "S": 0}
+
+                for magnet_stub in site.get("site_magnets", []):
+                    magnet = cache.get_object(
+                        session, api_server, auth_headers,
+                        "magnet", magnet_stub["magnet_id"],
+                    )
+                    geom_data = magnet.get("geometry", {})
+                    if geom_data:
+                        utils.download(
+                            session, api_server, auth_headers,
+                            geom_data["id"],
+                            wd=os.path.join(data_dir, "geometries"),
+                        )
+                    for part_stub in magnet.get("magnet_parts", []):
+                        _pid   = part_stub["part_id"]
+                        _ptype = part_stub["part"].get("type", "")
+                        if _ptype not in ("helix", "bitter", "supra"):
+                            continue
+                        _pobj = cache.get_object(
+                            session, api_server, auth_headers, "part", _pid,
+                        )
+                        for geom in _pobj.get("geometries", []):
+                            attach = geom.get("attachment", {})
+                            if attach:
+                                utils.download(
+                                    session, api_server, auth_headers,
+                                    attach["id"],
+                                    wd=os.path.join(data_dir, "geometries"),
+                                )
+                        type_key = _ptype.upper()[0]
+                        num_by_type[type_key] += 1
+                        pnames[_pobj["name"]] = f"{type_key}{num_by_type[type_key]}"
+
+                pnames_by_site[site_name] = pnames
+
+                # ── magnettools setup ───────────────────────────────────────
+                env = appenv(
+                    envfile=None,
+                    url_api=data_dir,
+                    yaml_repo=os.path.join(data_dir, "geometries"),
+                    cad_repo=os.path.join(data_dir, "cad"),
+                    mesh_repo=data_dir,
+                    simage_repo=data_dir,
+                    mrecord_repo=data_dir,
+                    optim_repo=data_dir,
+                )
+                try:
+                    site_data = msite_setup(env, config_data["results"], debug)
+                except Exception as exc:
+                    warnings.warn(f"msite_setup failed for '{site_name}': {exc} – skipping")
+                    progress.advance(site_bar)
+                    continue
+
+                Tubes, Helices, OHelices, BMagnets, UMagnets, Shims = site_data
+                icurrents = list(mt.get_currents(Tubes, Helices, BMagnets, UMagnets))
+
+                # ── HoopBasis precomputation  (C++ calls happen here, once) ─
+                try:
+                    basis = HoopBasis(
+                        Tubes, Helices, OHelices, BMagnets, UMagnets, icurrents
+                    )
+                except Exception as exc:
+                    warnings.warn(f"HoopBasis failed for '{site_name}': {exc} – skipping")
+                    progress.advance(site_bar)
+                    continue
+
+                if debug:
+                    print(
+                        f"\n  [{site_name}] basis: "
+                        f"{len(basis.comp_names)} components × "
+                        f"{len(basis.source_names)} sources"
+                        f"\n  C =\n{basis.C}"
+                    )
+
+                # ── download record files + build tasks ─────────────────────
+                records = site.get("records", [])
+                rec_bar = progress.add_task(
+                    f"  ↳ downloading records [{site_name}]",
+                    total=len(records),
+                )
+                for rec in records:
+                    attach = rec.get("attachment_id")
+                    if attach is None:
+                        progress.advance(rec_bar)
+                        continue
+                    filepath = utils.download(
+                        session, api_server, auth_headers,
+                        attach,
+                        wd=tempdir,
+                    )
+                    if filepath is None:
+                        progress.advance(rec_bar)
+                        continue
+                    housing = os.path.basename(filepath).split("_")[0]
+                    tasks.append(_RecordTask(
+                        site_name=site_name,
+                        record_name=rec.get("name", str(rec.get("id"))),
+                        housing=housing,
+                        filepath=filepath,
+                        basis=basis,   # picklable numpy struct
+                    ))
+                    progress.advance(rec_bar)
+
+                progress.advance(site_bar)
+
+            # ── summary ──────────────────────────────────────────────────────
+            n_sites   = len(pnames_by_site)
+            n_records = len(tasks)
+            print(
+                f"\nPhase 1 complete: {n_sites} site(s), "
+                f"{n_records} record task(s) queued."
+            )
+
+        if not tasks:
+            print("No record tasks – nothing to process.")
+            os.chdir(cwd)
+            return None
+
+        # =====================================================================
+        # Phase 2 — parallel: one worker process per record task
+        # =====================================================================
+        all_frames: list[pd.DataFrame] = []
+
+        print(f"\nPhase 2 – parallel evaluation  ({max_workers or 'auto'} workers) …")
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[bold green]Phase 2"),
+            BarColumn(),
+            TextColumn("{task.completed}/{task.total} records"),
+            TimeElapsedColumn(),
+        ) as progress:
+            eval_bar = progress.add_task("evaluating", total=len(tasks))
+
+            with ProcessPoolExecutor(max_workers=max_workers) as pool:
+                futures = {pool.submit(_process_record, t): t for t in tasks}
+
+                for future in as_completed(futures):
+                    task_desc = futures[future]
+                    try:
+                        result_df = future.result()
+                    except Exception as exc:
+                        warnings.warn(
+                            f"Worker error for record '{task_desc.record_name}' "
+                            f"in site '{task_desc.site_name}': {exc}"
+                        )
+                        result_df = None
+
+                    if result_df is not None:
+                        all_frames.append(result_df)
+
+                    progress.advance(eval_bar)
+
+        os.chdir(cwd)
+
+    # =========================================================================
+    # Phase 3 — assemble final DataFrame
+    # =========================================================================
+    if not all_frames:
+        print("No data collected.")
+        return None
+
+    result = pd.concat(all_frames, ignore_index=True)
+    result.sort_values("timestamp", inplace=True)
+    result.reset_index(drop=True, inplace=True)
+
+    result.attrs["part_name"]     = part["name"]
+    result.attrs["part_type"]     = part_type
+    result.attrs["pnames_by_site"] = pnames_by_site
+
+    print(
+        f"\nDone – {len(result):,} rows across "
+        f"{result['site'].nunique()} site(s) / "
+        f"{result['record'].nunique()} record(s)."
+    )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Convenience: run full pipeline
+# ---------------------------------------------------------------------------
+
+def run(
+    session,
+    api_server: str,
+    auth_headers: dict,
+    oid: int,
+    quantiles: Sequence[float] = (0.25, 0.50, 0.75, 0.90, 0.95, 0.99),
+    max_workers: int | None = None,
+    verbose: bool = False,
+    debug: bool = False,
+    show_plots: bool = True,
+    output_prefix: str | None = None,
+) -> tuple[pd.DataFrame | None, pd.DataFrame | None]:
+    """
+    Full pipeline with parallel compute: compute → stats → plots.
+
+    Returns ``(history_df, stats_df)``.
+    """
+    df = compute(
+        session, api_server, auth_headers, oid,
+        mtype="part", max_workers=max_workers,
+        verbose=verbose, debug=debug,
+    )
+    if df is None:
+        return None, None
+
+    stats_df = hoop_stats(df, quantiles=quantiles)
+    pname    = df.attrs.get("part_name", str(oid))
+
+    history_savepath = f"{output_prefix}_history.png" if output_prefix else None
+    stats_savepath   = f"{output_prefix}_stats.png"   if output_prefix else None
+
+    plot_hoop_history(df, part_name=pname, show=show_plots, savepath=history_savepath)
+    plot_hoop_stats(stats_df, part_name=pname, show=show_plots, savepath=stats_savepath)
+
+    if output_prefix:
+        df.to_csv(f"{output_prefix}_history.csv", index=False)
+        stats_df.to_csv(f"{output_prefix}_stats.csv")
+        print(f"Saved CSV  → {output_prefix}_history.csv")
+        print(f"Saved CSV  → {output_prefix}_stats.csv")
+        print(f"Saved PNG  → {history_savepath}")
+        print(f"Saved PNG  → {stats_savepath}")
+
+    return df, stats_df
diff --git a/python_magnetapi/inductances.py b/python_magnetapi/inductances.py
index 9ad832f..30f9f04 100644
--- a/python_magnetapi/inductances.py
+++ b/python_magnetapi/inductances.py
@@ -32,8 +32,6 @@ def compute(
     headers: dict,
     oid: int,
     mtype: str = "magnet",
-    verbose: bool = False,
-    debug: bool = False,
 ):
     """
     compute inductances for a given magnet or site
@@ -46,14 +44,12 @@ def compute(
             headers=headers,
             mtype="site",
             id=oid,
-            verbose=verbose,
-            debug=debug,
         )
         # print(f"site[{i}]: {sites[i]['name']}")
 
         # add route to get data in visualisation
         config_data = utils.get_data(
-            session, api_server, headers, oid=site["id"], mtype="site", debug=debug
+            session, api_server, headers, oid=site["id"], mtype="site"
         )
 
         # create datastruct for Hoop calc
@@ -83,8 +79,6 @@ def compute(
             headers=headers,
             mtype="magnet",
             id=oid,
-            verbose=verbose,
-            debug=debug,
         )
 
         data = magnet_setup(env, config_data["results"], debug)
diff --git a/python_magnetapi/magnet.py b/python_magnetapi/magnet.py
index e090e57..0ba7e78 100644
--- a/python_magnetapi/magnet.py
+++ b/python_magnetapi/magnet.py
@@ -2,175 +2,191 @@
 create magnet
 """
 
+import requests
+
 from . import utils
+from .exceptions import ResourceConflictError
 
 # from . import part
 # from . import site
 
 
 def create(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: dict,
     verbose: bool = False,
     debug: bool = False,
-):
-    """
-    create a magnet from a data dictionnary
+) -> int | None:
+    """Create a magnet from a data dictionary.
+
+    Parts and sites listed in *data* are linked after the magnet is created.
+    Geometry files, if provided, are uploaded to the geometry endpoint.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: magnet fields (must include "name"); may contain "parts", "sites",
+              and "geometry" lists which are processed separately
+        verbose: enable verbose output
+        debug: enable debug output
+
+    Returns:
+        ID of the newly created magnet, or None if creation failed.
+
+    Raises:
+        ResourceConflictError: if a magnet with the same name already exists.
+        RuntimeError: if a part or site entry has an unexpected type.
     """
 
     ids = utils.get_list(
-        session, api_server, headers=headers, mtype="magnet", debug=debug
+        session, api_server, headers=headers, mtype="magnet"
     )
     if data["name"] in ids:
-        print(f"magnet with name={data['name']} already exists")
-        return None
-
-    else:
-        parts = []
-        if "parts" in data:
-            parts = data["parts"].copy()
-            del data["parts"]
-
-        sites = []
-        if "sites" in data:
-            sites = data["sites"].copy()
-            del data["sites"]
-
-        geometries = []
-        if "geometry" in data:
-            geometries = data["geometry"].copy()
-            del data["geometry"]
-
-        status = ""
-        if "status" in data:
-            status = data["status"]
-            del data["status"]
-
-        # data: extract only necessary data for creation
-        print(f"create:magnet data={data}")
-        response = utils.post_data(
-            session, api_server, headers, data, "magnet", verbose, debug
+        raise ResourceConflictError(
+            f"Magnet '{data['name']}' already exists",
+            object_name=data['name'],
+            object_type='magnet',
+            existing_id=ids[data['name']]
         )
-        print(f"create:magnet response={response}")
-        if response is None:
-            print(f"create:magnet {data['name']} failed to be created")
-            return None
-        else:
-            print(f"create:magnet {data['name']} created with id={response['id']}")
 
-        # loop over parts
-        magnet_id = response["id"]
-        for part in parts:
-            _ids = utils.get_list(
-                session, api_server, headers=headers, mtype="part", debug=debug
-            )
-            if isinstance(part, str):
-                # TODO if part is a string use procedure bellow,
-                # otherwise if part is a dict simple call create method from part.py
-                if part in _ids:
-                    pdata = {"part_id": _ids[part]}
-                    # how to create MagnetPart: use /api/magnets/{magnet_id}/parts
-                    # create(magnet_id: int, user=Depends(get_user('create')), part_id: int = Form(...))
-                    print(
-                        f"create:magnet  {data['name']} attach part id={pdata['part_id']} name={part}"
-                    )
-                    utils.add_data_to_object(
-                        session,
-                        api_server,
-                        headers,
-                        magnet_id,
-                        data=pdata,
-                        mtype="magnet",
-                        dtype="part",
-                        verbose=verbose,
-                        debug=debug,
-                    )
-                else:
-                    print(
-                        f"create:magnet {data['name']} failed to add part {part} - no such part"
-                    )
-
-            elif isinstance(part, dict):
-                pname = part["name"]
-                _id = -1
-                if pname in _ids:
-                    _id = pdata = {"part_id": _ids[part]}
-                else:
-                    _id = part.create(
-                        api_server, headers, part, verbose=verbose, debug=debug
-                    )
+    parts = []
+    if "parts" in data:
+        parts = data["parts"].copy()
+        del data["parts"]
+
+    sites = []
+    if "sites" in data:
+        sites = data["sites"].copy()
+        del data["sites"]
+
+    geometries = []
+    if "geometry" in data:
+        geometries = data["geometry"].copy()
+        del data["geometry"]
+
+    status = ""
+    if "status" in data:
+        status = data["status"]
+        del data["status"]
+
+    # data: extract only necessary data for creation
+    print(f"create:magnet data={data}")
+    response = utils.post_data(
+        session, api_server, headers, data, "magnet"
+    )
+    print(f"create:magnet response={response}")
+    if response is None:
+        print(f"create:magnet {data['name']} failed to be created")
+        return None
+    else:
+        print(f"create:magnet {data['name']} created with id={response['id']}")
 
+    # loop over parts
+    magnet_id = response["id"]
+    for part in parts:
+        _ids = utils.get_list(
+            session, api_server, headers=headers, mtype="part"
+        )
+        if isinstance(part, str):
+            # TODO if part is a string use procedure bellow,
+            # otherwise if part is a dict simple call create method from part.py
+            if part in _ids:
+                pdata = {"part_id": _ids[part]}
+                # how to create MagnetPart: use /api/magnets/{magnet_id}/parts
+                # create(magnet_id: int, user=Depends(get_user('create')), part_id: int = Form(...))
                 print(
-                    f"create:magnet {data['name']}  attach part id={_id} name={pname}"
+                    f"create:magnet  {data['name']} attach part id={pdata['part_id']} name={part}"
                 )
                 utils.add_data_to_object(
                     session,
                     api_server,
                     headers,
                     magnet_id,
-                    data={"part_id": _id},
+                    data=pdata,
                     mtype="magnet",
                     dtype="part",
-                    verbose=verbose,
-                    debug=debug,
                 )
             else:
-                raise RuntimeError(
-                    f"create:magnet  {data['name']} unexpected type for part (type={type(part)}) - should be str or dict"
+                print(
+                    f"create:magnet {data['name']} failed to add part {part} - no such part"
                 )
 
-        for site in sites:
-            _ids = utils.get_list(
-                session, api_server, headers=headers, mtype="site", debug=debug
-            )
-            if isinstance(site, str):
-                if site in _ids:
-                    site_id = _ids[site]
-
-                    print(
-                        f"create:magnet {data['name']}  attach site id={_id} name={site}"
-                    )
-                    utils.add_data_to_object(
-                        session,
-                        api_server,
-                        headers,
-                        site_id,
-                        data={"magnet_id": magnet_id},
-                        mtype="site",
-                        dtype="magnet",
-                        verbose=verbose,
-                        debug=debug,
-                    )
-
-                else:
-                    print(
-                        f"create:magnet {data['name']} failed to attach to site {site} - no such site"
-                    )
-
+        elif isinstance(part, dict):
+            pname = part["name"]
+            _id = -1
+            if pname in _ids:
+                _id = pdata = {"part_id": _ids[part]}
             else:
-                raise RuntimeError(
-                    f"magnet {data['name']} failed to attach to site {site} - unexpected type ({type(site)}"
+                _id = part.create(
+                    api_server, headers, part
                 )
 
-        # add magnet geometry
-        if geometries:
-            geomfile = f"{geometries[0]}.yaml"
-            utils.add_data_files_to_object(
+            print(
+                f"create:magnet {data['name']}  attach part id={_id} name={pname}"
+            )
+            utils.add_data_to_object(
                 session,
                 api_server,
                 headers,
-                response["id"],
-                "magnet",
-                "geometrie",
-                data={"type": "default"},
-                files={"geometry": geomfile},
-                verbose=verbose,
-                debug=debug,
+                magnet_id,
+                data={"part_id": _id},
+                mtype="magnet",
+                dtype="part",
+            )
+        else:
+            raise RuntimeError(
+                f"create:magnet  {data['name']} unexpected type for part (type={type(part)}) - should be str or dict"
+            )
+
+    for site in sites:
+        _ids = utils.get_list(
+            session, api_server, headers=headers, mtype="site"
+        )
+        if isinstance(site, str):
+            if site in _ids:
+                site_id = _ids[site]
+
+                print(
+                    f"create:magnet {data['name']}  attach site id={_id} name={site}"
+                )
+                utils.add_data_to_object(
+                    session,
+                    api_server,
+                    headers,
+                    site_id,
+                    data={"magnet_id": magnet_id},
+                    mtype="site",
+                    dtype="magnet",
+                )
+
+            else:
+                print(
+                    f"create:magnet {data['name']} failed to attach to site {site} - no such site"
+                )
+
+        else:
+            raise RuntimeError(
+                f"magnet {data['name']} failed to attach to site {site} - unexpected type ({type(site)}"
             )
 
-        # add cad
-        # add status
+    # add magnet geometry
+    if geometries:
+        geomfile = f"{geometries[0]}.yaml"
+        utils.add_data_files_to_object(
+            session,
+            api_server,
+            headers,
+            response["id"],
+            "magnet",
+            "geometrie",
+            data={"type": "default"},
+            files={"geometry": geomfile},
+        )
+
+    # add cad
+    # add status
 
-        return response["id"]
+    return response["id"]
diff --git a/python_magnetapi/material.py b/python_magnetapi/material.py
index f439530..b1d56ab 100644
--- a/python_magnetapi/material.py
+++ b/python_magnetapi/material.py
@@ -2,34 +2,50 @@
 create material
 """
 
+import requests
+
 from . import utils
+from .exceptions import ResourceConflictError
 
 
 def create(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: dict,
     verbose: bool = False,
     debug: bool = False,
-):
-    """
-    create a material from a data dictionnary
+) -> int:
+    """Create a material from a data dictionary.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: material fields (must include "name")
+        verbose: enable verbose output
+        debug: enable debug output
+
+    Returns:
+        ID of the newly created material.
+
+    Raises:
+        ResourceConflictError: if a material with the same name already exists.
     """
 
     ids = utils.get_list(
-        session, api_server, headers=headers, mtype="material", debug=debug
+        session, api_server, headers=headers, mtype="material"
     )
     if data["name"] in ids:
-        print(f"material with name={data['name']} already exists")
-        return None
-
-    else:
-        response = utils.post_json(
-            session, api_server, headers, data, "material", verbose, debug
+        raise ResourceConflictError(
+            f"Material '{data['name']}' already exists",
+            object_name=data["name"],
+            object_type="material",
+            existing_id=ids[data["name"]],
         )
-        if response is None:
-            print(f"material {data['name']} failed to be created")
-            return None
-        print(f"material {data['name']} created with id={response['id']}")
-        return response["id"]
+
+    response = utils.post_json(
+        session, api_server, headers, data, "material"
+    )
+    print(f"material {data['name']} created with id={response['id']}")
+    return response["id"]
diff --git a/python_magnetapi/part.py b/python_magnetapi/part.py
index ab1b3ff..fb50a65 100644
--- a/python_magnetapi/part.py
+++ b/python_magnetapi/part.py
@@ -2,134 +2,166 @@
 create part
 """
 
+import requests
+
 from . import utils
 from . import material
+from .exceptions import ResourceConflictError, ResourceNotFoundError, ValidationError
 
 
 def create(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: dict,
     verbose: bool = False,
     debug: bool = False,
-):
-    """
-    create a part from a data dictionnary
+) -> int | None:
+    """Create a part from a data dictionary.
+
+    The "material" field may be a string (name lookup), a dict with an "id"
+    (API response object used directly), or a dict without "id" (create-or-lookup
+    by name).  Associated magnets and geometry files are linked after creation.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: part fields (must include "name" and "material")
+        verbose: enable verbose output
+        debug: enable debug output
+
+    Returns:
+        ID of the newly created part, or None if creation failed.
+
+    Raises:
+        ResourceConflictError: if a part with the same name already exists.
+        ResourceNotFoundError: if the referenced material name is not found.
+        ValidationError: if the "material" field type is invalid.
     """
 
     ids = utils.get_list(
-        session, api_server, headers=headers, mtype="part", debug=debug
+        session, api_server, headers=headers, mtype="part"
     )
     if data["name"] in ids:
-        print(f"part with name={data['name']} already exists")
-        return None
-
-    else:
-        # search or create material in db
-        mat_ids = utils.get_list(
-            session, api_server, headers=headers, mtype="material", debug=debug
+        raise ResourceConflictError(
+            f"Part '{data['name']}' already exists",
+            object_name=data["name"],
+            object_type="part",
+            existing_id=ids[data["name"]],
         )
-        mat = data["material"]
-        if isinstance(mat, str):
-            if mat in mat_ids:
-                data["material_id"] = mat_ids[mat]
-                del data["material"]
-            else:
-                print(f"part {data['name']} failed to be created: no material {mat}")
-                return None
-        elif isinstance(mat, dict):
+
+    # search or create material in db
+    mat_ids = utils.get_list(
+        session, api_server, headers=headers, mtype="material"
+    )
+    mat = data["material"]
+    if isinstance(mat, str):
+        if mat in mat_ids:
+            data["material_id"] = mat_ids[mat]
+            del data["material"]
+        else:
+            raise ResourceNotFoundError(
+                f"Material '{mat}' not found. Create the material before creating part '{data['name']}'",
+                object_name=mat,
+                object_type="material",
+                required_by=data["name"],
+            )
+    elif isinstance(mat, dict):
+        # If the dict already has an "id" key it is an API response object —
+        # use the id directly without an extra lookup.
+        if "id" in mat:
+            data["material_id"] = mat["id"]
+        else:
             mname = mat["name"]
             _id = -1
             if mname in mat_ids:
                 _id = mat_ids[mname]
             else:
                 _id = material.create(
-                    session, api_server, headers, mat, verbose=verbose, debug=debug
+                    session, api_server, headers, mat
                 )
-
             data["material_id"] = _id
-            del data["material"]
-        else:
-            raise RuntimeError(
-                f"part/create: unexpected type for material (type={type(mat)}) - should be str or dict"
-            )
-
-        # extract magnets list
-        magnets = []
-        if "magnets" in data:
-            magnets = data["magnets"].copy()
-            del data["magnets"]
-
-        geometries = []
-        if "geometry" in data:
-            geometries = data["geometry"].copy()
-            del data["geometry"]
-
-        status = ""
-        if "status" in data:
-            status = data["status"]
-            del data["status"]
-
-        # get material id, and set data accordingly
-        print(f"part/create: data={data}")
-        response = utils.post_data(
-            session, api_server, headers, data, "part", verbose, debug
+        del data["material"]
+    else:
+        raise ValidationError(
+            f"Invalid material type for part '{data['name']}'. Expected string or dict, got {type(mat).__name__}",
+            field="material",
+            value_type=type(mat).__name__,
+            expected_types=["str", "dict"],
         )
-        if response is None:
-            print(f"part {data['name']} failed to be created")
-            return None
-        print(f"part {data['name']} created with id={response['id']}")
-
-        # add magnets
-        part_id = response["id"]
-        for magnet in magnets:
-            _ids = utils.get_list(
-                session, api_server, headers=headers, mtype="magnet", debug=debug
-            )
-            if magnet in _ids:
-                _id = _ids[magnet]
-                # how to create MagnetPart: use /api/magnets/{magnet_id}/parts
-                # create(magnet_id: int, user=Depends(get_user('create')), part_id: int = Form(...))
-                utils.add_data_to_object(
-                    session,
-                    api_server,
-                    headers,
-                    _id,
-                    data={"part_id": part_id},
-                    mtype="magnet",
-                    dtype="part",
-                    verbose=verbose,
-                    debug=debug,
-                )
-            else:
-                print(
-                    f"part {data['name']} failed to be created MagnetPart: no magnet {magnet}"
-                )
 
-        # TODO better to have a dict for this part
-        # data['geometry'] = {'default':} with additionnal from part type
-        # see valid_geometry_types in geometry.py
-        # add geometry: see geometry.create
-        # for geometry: files: {'attachment': }
-        # for cad (/api/cad_attachments) : files:{'file': }
-        if geometries:
-            geomfile = f"{geometries[0]}.yaml"
-            utils.add_data_files_to_object(
+    # extract magnets list
+    magnets = []
+    if "magnets" in data:
+        magnets = data["magnets"].copy()
+        del data["magnets"]
+
+    geometries = []
+    if "geometry" in data:
+        geometries = data["geometry"].copy()
+        del data["geometry"]
+
+    status = ""
+    if "status" in data:
+        status = data["status"]
+        del data["status"]
+
+    # get material id, and set data accordingly
+    print(f"part/create: data={data}")
+    response = utils.post_data(
+        session, api_server, headers, data, "part"
+    )
+    if response is None:
+        print(f"part {data['name']} failed to be created")
+        return None
+    print(f"part {data['name']} created with id={response['id']}")
+
+    # add magnets
+    part_id = response["id"]
+    for magnet in magnets:
+        _ids = utils.get_list(
+            session, api_server, headers=headers, mtype="magnet"
+        )
+        if magnet in _ids:
+            _id = _ids[magnet]
+            # how to create MagnetPart: use /api/magnets/{magnet_id}/parts
+            # create(magnet_id: int, user=Depends(get_user('create')), part_id: int = Form(...))
+            utils.add_data_to_object(
                 session,
                 api_server,
                 headers,
-                response["id"],
-                "part",
-                "geometrie",
-                data={"type": "default"},
-                files={"geometry": geomfile},
-                verbose=verbose,
-                debug=debug,
+                _id,
+                data={"part_id": part_id},
+                mtype="magnet",
+                dtype="part",
             )
+        else:
+            print(
+                f"part {data['name']} failed to be created MagnetPart: no magnet {magnet}"
+            )
+
+    # TODO better to have a dict for this part
+    # data['geometry'] = {'default':} with additionnal from part type
+    # see valid_geometry_types in geometry.py
+    # add geometry: see geometry.create
+    # for geometry: files: {'attachment': }
+    # for cad (/api/cad_attachments) : files:{'file': }
+    if geometries:
+        geomfile = f"{geometries[0]}.yaml"
+        utils.add_data_files_to_object(
+            session,
+            api_server,
+            headers,
+            response["id"],
+            "part",
+            "geometrie",
+            data={"type": "default"},
+            files={"geometry": geomfile},
+        )
 
-        # add cad, ...
-        # see also status in python_magnetdb/models/status.py
-        # how to change timestamps
+    # add cad, ...
+    # see also status in python_magnetdb/models/status.py
+    # how to change timestamps
 
-        return response["id"]
+    return response["id"]
diff --git a/python_magnetapi/record.py b/python_magnetapi/record.py
index 907bd39..1192765 100644
--- a/python_magnetapi/record.py
+++ b/python_magnetapi/record.py
@@ -2,57 +2,78 @@
 create record
 """
 
+import requests
+
 from . import utils
+from .exceptions import ResourceConflictError, ResourceNotFoundError
 from .attachment import create as attach_create
 
 
 def create(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: dict,
     verbose: bool = False,
     debug: bool = False,
-):
-    """
-    create a record from a data dictionnary
+) -> int:
+    """Create a record from a data dictionary.
+
+    The referenced site must already exist.  The "file" field is uploaded as an
+    attachment first; the resulting attachment ID is stored as "attachment_id".
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: record fields (must include "name", "site", and "file")
+        verbose: enable verbose output
+        debug: enable debug output
+
+    Returns:
+        ID of the newly created record.
+
+    Raises:
+        ResourceConflictError: if a record with the same name already exists.
+        ResourceNotFoundError: if the referenced site name is not found.
     """
 
     _ids = utils.get_list(
-        session, api_server, headers=headers, mtype="record", debug=debug
+        session, api_server, headers=headers, mtype="record"
     )
     if data["name"] in _ids:
-        print(f"record with name={data['name']} already exists")
-        return None
+        raise ResourceConflictError(
+            f"Record '{data['name']}' already exists",
+            object_name=data['name'],
+            object_type='record',
+            existing_id=_ids[data['name']]
+        )
 
-    else:
-        # look for site
-        _ids = utils.get_list(
-            session, api_server, headers=headers, mtype="site", debug=debug
+    # look for site
+    _ids = utils.get_list(
+        session, api_server, headers=headers, mtype="site"
+    )
+    if data["site"] not in _ids:
+        raise ResourceNotFoundError(
+            f"Site '{data['site']}' not found. Create the site before creating record '{data['name']}'",
+            object_name=data['site'],
+            object_type='site',
+            required_by=data['name']
         )
-        if data["site"] not in _ids:
-            print(
-                f"create(record, name={data['name']}): site with name={data['site']} does not exist - must be created first"
-            )
-            return None
-        else:
-            _id = _ids[data["site"]]
-            data["site_id"] = _id
-            del data["site"]
-
-            data["attachment_id"] = attach_create(
-                session, api_server, headers, data["file"], verbose, debug
-            )
-            del data["file"]
-            print(f"data:{data}")
-
-            # process record data: remove empty columns, rename columns, add Hoopstress data
-            response = utils.post_json(
-                session, api_server, headers, data, "clirecord", verbose, debug=True
-            )
-            if response is None:
-                print(f"record {data['name']} failed to be created")
-                return None
-
-            print(f"record {data['name']} created with id={response['id']}")
-            return response["id"]
+    
+    _id = _ids[data["site"]]
+    data["site_id"] = _id
+    del data["site"]
+
+    data["attachment_id"] = attach_create(
+        session, api_server, headers, data["file"]
+    )
+    del data["file"]
+    print(f"data:{data}")
+
+    # process record data: remove empty columns, rename columns, add Hoopstress data
+    response = utils.post_json(
+        session, api_server, headers, data, "clirecord"
+    )
+    print(f"record {data['name']} created with id={response['id']}")
+    return response["id"]
diff --git a/python_magnetapi/site.py b/python_magnetapi/site.py
index cc9c885..8bde62c 100644
--- a/python_magnetapi/site.py
+++ b/python_magnetapi/site.py
@@ -2,7 +2,10 @@
 create site
 """
 
+import requests
+
 from . import utils
+from .exceptions import ResourceConflictError
 from datetime import datetime
 
 # from . import magnet
@@ -10,103 +13,84 @@
 
 
 def create(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: dict,
     verbose: bool = False,
     debug: bool = False,
-) -> int:
-    """
-    create a site from a data dictionnary
+) -> int | None:
+    """Create a site from a data dictionary.
+
+    Magnets and records listed in *data* are linked after the site is created.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: site fields (must include "name"); may contain "magnets" and
+              "records" lists which are processed separately
+        verbose: enable verbose output
+        debug: enable debug output
+
+    Returns:
+        ID of the newly created site, or None if creation failed.
+
+    Raises:
+        ResourceConflictError: if a site with the same name already exists.
+        RuntimeError: if a magnet or record entry has an unexpected type.
     """
 
     ids = utils.get_list(
-        session, api_server, headers=headers, mtype="site", debug=debug
+        session, api_server, headers=headers, mtype="site"
     )
     if data["name"] in ids:
-        print(f"site with name={data['name']} already exists")
-        return None
-
-    else:
-        # data: extract only necessary data for creation
-        magnets = []
-        if "magnets" in data:
-            magnets = data["magnets"].copy()
-            del data["magnets"]
-
-        if "status" in data:
-            del data["status"]
+        raise ResourceConflictError(
+            f"Site '{data['name']}' already exists",
+            object_name=data["name"],
+            object_type="site",
+            existing_id=ids[data["name"]],
+        )
 
-        records = []
-        if "records" in data:
-            records = data["records"].copy()
-            del data["records"]
+    # data: extract only necessary data for creation
+    magnets = []
+    if "magnets" in data:
+        magnets = data["magnets"].copy()
+        del data["magnets"]
 
-        if "status" in data:
-            del data["status"]
+    if "status" in data:
+        del data["status"]
 
-        response = utils.post_data(
-            session, api_server, headers, data, "site", verbose, debug
-        )
-        if response is None:
-            print(f"site {data['name']} failed to be created")
-            return None
-        print(f"site {data['name']} created with id={response['id']}")
+    records = []
+    if "records" in data:
+        records = data["records"].copy()
+        del data["records"]
 
-        # loop over magnets
-        site_id = response["id"]
+    if "status" in data:
+        del data["status"]
 
-        for magnet in magnets:
-            _ids = utils.get_list(
-                session, api_server, headers=headers, mtype="magnet", debug=debug
-            )
+    response = utils.post_data(
+        session, api_server, headers, data, "site"
+    )
+    if response is None:
+        print(f"site {data['name']} failed to be created")
+        return None
+    print(f"site {data['name']} created with id={response['id']}")
 
-            _id = None
-            mname = None
-            if isinstance(magnet, str):
-                mname = magnet
-                if magnet in _ids:
-                    _id = _ids[magnet]
-                    utils.add_data_to_object(
-                        session,
-                        api_server,
-                        headers,
-                        site_id,
-                        mtype="site",
-                        dtype="magnet",
-                        data={"magnet_id": _id},
-                        verbose=verbose,
-                        debug=debug,
-                    )
-                else:
-                    print(
-                        f"site {data['name']} failed to add magnet {magnet} - no such magnet"
-                    )
-
-            elif isinstance(magnet, dict):
-                mname = magnet["name"]
-                _id = -1
-                if mname in _ids:
-                    _id = _ids[magnet["name"]]
-                else:
-                    _id = magnet.create(
-                        session,
-                        api_server,
-                        headers,
-                        magnet,
-                        verbose=verbose,
-                        debug=debug,
-                    )
+    # loop over magnets
+    site_id = response["id"]
 
-            else:
-                raise RuntimeError(
-                    f"site/create: unexpected type for magnet (type={type(magnet)}) - should be str or dict"
-                )
+    for magnet in magnets:
+        _ids = utils.get_list(
+            session, api_server, headers=headers, mtype="magnet"
+        )
 
-            # call to api/sites/{site_id}/magnets with magnetid = _id
-            if _id is not None:
-                print(f"create:site attach magnet id={_id} name={mname}")
+        _id = None
+        mname = None
+        if isinstance(magnet, str):
+            mname = magnet
+            if magnet in _ids:
+                _id = _ids[magnet]
                 utils.add_data_to_object(
                     session,
                     api_server,
@@ -115,54 +99,88 @@ def create(
                     mtype="site",
                     dtype="magnet",
                     data={"magnet_id": _id},
-                    verbose=verbose,
-                    debug=debug,
+                )
+            else:
+                print(
+                    f"site {data['name']} failed to add magnet {magnet} - no such magnet"
                 )
 
-        for record in records:
-            if not isinstance(record, dict):
-                raise RuntimeError(
-                    f"site/create: unexpected type for record (type={type(record)}) - should be dict"
+        elif isinstance(magnet, dict):
+            mname = magnet["name"]
+            _id = -1
+            if mname in _ids:
+                _id = _ids[magnet["name"]]
+            else:
+                _id = magnet.create(
+                    session,
+                    api_server,
+                    headers,
+                    magnet,
                 )
-            _id = record.create(
-                session, api_server, headers, record, verbose=verbose, debug=debug
+
+        else:
+            raise RuntimeError(
+                f"site/create: unexpected type for magnet (type={type(magnet)}) - should be str or dict"
+            )
+
+        # call to api/sites/{site_id}/magnets with magnetid = _id
+        if _id is not None:
+            print(f"create:site attach magnet id={_id} name={mname}")
+            utils.add_data_to_object(
+                session,
+                api_server,
+                headers,
+                site_id,
+                mtype="site",
+                dtype="magnet",
+                data={"magnet_id": _id},
             )
 
-        # update site description
-        # update status
-        # putinoperation: patch /api/sites/{id}/put_in_operation
-        # shutdown: patch "/api/sites/{id}/shutdown
-        return response["id"]
+    for record in records:
+        if not isinstance(record, dict):
+            raise RuntimeError(
+                f"site/create: unexpected type for record (type={type(record)}) - should be dict"
+            )
+        _id = record.create(
+            session, api_server, headers, record
+        )
+
+    # update site description
+    # update status
+    # putinoperation: patch /api/sites/{id}/put_in_operation
+    # shutdown: patch "/api/sites/{id}/shutdown
+    return response["id"]
 
 
 def status(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: dict,
     verbose: bool = False,
     debug: bool = False,
 ) -> bool:
-    """
-    set site status
-
-    /api/sites/{id}/put_in_operation
-    /api/sites/{id}/shutdown
-
-    from magnetdb.models.status.py:
-    class Status:
-
-    data:
-    name: of site
-    id:
-    status:
-    date:
-
-    see python_magnetdb.models.status.py:
-    IN_STUDY = "in_study"
-    IN_STOCK = "in_stock"
-    IN_OPERATION = "in_operation"
-    DEFUNCT = "defunct"
+    """Set the operational status of a site.
+
+    Calls PUT /api/sites/{id}/put_in_operation or /api/sites/{id}/shutdown
+    depending on the requested status.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: dict with keys:
+            - "name" or "id": site identifier
+            - "status": one of "in_study", "in_stock", "in_operation"
+            - "date": timestamp string in "%Y.%m.%d %H:%M:%S" format
+        verbose: enable verbose output
+        debug: enable debug output
+
+    Returns:
+        True on success, False if the site is not found or the request failed.
+
+    Raises:
+        RuntimeError: if "name"/"id" is missing or status value is unknown.
     """
     print(f"site.status: data={data}", flush=True)
 
@@ -173,7 +191,7 @@ class Status:
             )
 
         ids = utils.get_list(
-            session, api_server, headers=headers, mtype="site", debug=debug
+            session, api_server, headers=headers, mtype="site"
         )
         if data["name"] not in ids:
             print(f"site with name={data['name']} does not exist")
@@ -187,7 +205,6 @@ class Status:
                 headers=headers,
                 mtype="site",
                 id=data["id"],
-                debug=debug,
             )
             data["name"] = sdata["name"]
 
diff --git a/python_magnetapi/utils.py b/python_magnetapi/utils.py
index 029a21a..c2a9ea4 100644
--- a/python_magnetapi/utils.py
+++ b/python_magnetapi/utils.py
@@ -3,22 +3,65 @@
 """
 
 import json
+import logging
 import re
 
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ResourceConflictError,
+    ServerError,
+    MagnetAPIException,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def setup_logging(level: str = "WARNING", log_file: str = None) -> None:
+    """Configure the root logger for python_magnetapi.
+
+    Args:
+        level: Logging level name (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        log_file: Optional file path to write logs to in addition to stderr.
+    """
+    numeric_level = getattr(logging, f"{level.upper()}", logging.WARNING)
+    handlers = [logging.StreamHandler()]
+    if log_file:
+        handlers.append(logging.FileHandler(log_file))
+
+    logging.basicConfig(
+        level=numeric_level,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+        handlers=handlers,
+    )
+
 
 def get_list(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     mtype: str = "magnets",
-    verbose: bool = False,
-    debug: bool = False,
+    filters: dict = None,
 ) -> dict:
     """
-    return list of ids for selected tpye
+    return list of ids for selected type
+
+    Args:
+        session: requests session
+        api_server: API server URL
+        headers: request headers
+        mtype: object type (magnet, part, site, etc.)
+        filters: dict of attribute:value pairs to filter results
+                 e.g., {"status": "active", "type": "helix"}
+
+    Returns:
+        dict: mapping of object names to IDs (filtered if filters provided)
     """
-    if verbose:
-        print(f"get_list: api_server={api_server}, mtype={mtype}")
+    logger.info(f"get_list: api_server={api_server}, mtype={mtype}")
+    if filters:
+        logger.info(f"get_list: filters={filters}")
 
     # loop over pages
     objects = dict()
@@ -29,12 +72,11 @@ def get_list(
         r = session.get(f"{api_server}/api/{mtype}s?page={n}", headers=headers)
         response = r.json()
         if r.status_code != 200:
-            print(response["detail"])
+            logger.error(response["detail"])
             break
-        if debug:
-            print(
-                f"get_list: {api_server}/api/{mtype}s?page={n}, headers={headers}, res={r.text}"
-            )
+        logger.debug(
+            f"get_list: {api_server}/api/{mtype}s?page={n}, headers={headers}, res={r.text}"
+        )
 
         # check r.json() pages max
         current_page = response["current_page"]
@@ -42,11 +84,10 @@ def get_list(
 
         # get object list per page
         _page_dict = response["items"]
-        if debug:
-            print(f"_page_dict={_page_dict}")
+        logger.debug(f"_page_dict={_page_dict}")
         for object in _page_dict:
             if mtype == "simulation":
-                print(f"object: {object}")
+                logger.debug(f"object: {object}")
                 resource_type = object["resource_type"][:-1]
                 resource_id = object["resource_id"]
                 resource = get_object(
@@ -55,8 +96,6 @@ def get_list(
                     headers,
                     resource_id,
                     resource_type,
-                    verbose,
-                    debug,
                 )
                 object["name"] = (
                     f"{resource['name']}: {object['method']}/{object['geometry']}/{object['model']}/{object['cooling']}"
@@ -71,55 +110,223 @@ def get_list(
             break
 
     for object in objects:
-        if debug:
-            print(
-                f"{mtype.upper()}: {objects[object]['name']} (id:{objects[object]['id']})"
-            )
+        # Apply filters if provided
+        if filters:
+            matches = True
+            for attr, value in filters.items():
+                # Check if attribute exists and matches the filter value
+                if attr not in objects[object] or str(objects[object][attr]) != str(
+                    value
+                ):
+                    matches = False
+                    break
+            if not matches:
+                continue
+
+        logger.debug(
+            f"{mtype.upper()}: {objects[object]['name']} (id:{objects[object]['id']})"
+        )
         ids[objects[object]["name"]] = objects[object]["id"]
 
     return ids
 
 
 def get_object(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     id: int,
     mtype: str = "magnet",
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    return id of an object with name == name
+) -> dict | None:
+    """Return the API response dict for a single object.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        id: object ID
+        mtype: resource type (magnet, part, site, etc.)
+
+    Returns:
+        Object data dict, or None if the request failed.
     """
-    if verbose:
-        print(f"get_object: api_server={api_server}, mtype={mtype}, id={id}")
+    logger.info(f"get_object: api_server={api_server}, mtype={mtype}, id={id}")
 
     r = session.get(f"{api_server}/api/{mtype}s/{id}", headers=headers)
     response = r.json()
 
     if r.status_code != 200:
-        print(f"get_object: {api_server}/api/{mtype}s/{id}")
-        print(response["detail"])
+        logger.error(f"get_object: {api_server}/api/{mtype}s/{id}: {response['detail']}")
         return None
     else:
         return response
 
 
+def get_fk_id(obj: dict, field: str) -> int | None:
+    """
+    Extract the integer ID for a direct/forward ForeignKey field from a
+    MagnetDB API response dict (as returned by get_object).
+
+    Django serializes a ForeignKey named `material` as the column `material_id`
+    (an integer), not as a nested object.  Checks in order:
+      1. "{field}_id" key  — standard Django column name (primary form)
+      2. "{field}" key holding an int
+      3. "{field}" key holding a dict with "id" (defensive fallback)
+
+    For reverse FK / many-to-many relations (e.g. parts on a magnet) the
+    related objects are NOT in the get_object response.
+    Use get_parts_for_magnet() or an equivalent nested-endpoint helper instead.
+    """
+    fk_col = f"{field}_id"
+    if fk_col in obj:
+        return obj[fk_col]
+    value = obj.get(field)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, dict):
+        return value.get("id")
+    return None
+
+
+def get_parts_for_magnet(
+    session: requests.Session,
+    api_server: str,
+    headers: dict,
+    magnet_id: int,
+) -> list[dict]:
+    """
+    Return the full Part objects associated with a magnet.
+
+    Calls GET /api/magnets/{magnet_id}/parts (must exist in magnetdb).
+    The endpoint may return either:
+    - a bare array of Part objects directly, or
+    - a bare array of MagnetPart join rows each containing a `part_id` field.
+
+    In the join-row case each part is fetched individually via get_object.
+    Returns a list of Part dicts (same structure as get_object(mtype="part")).
+    """
+    logger.info(f"get_parts_for_magnet: api_server={api_server}, magnet_id={magnet_id}")
+
+    r = session.get(f"{api_server}/api/magnets/{magnet_id}/parts", headers=headers)
+    if r.status_code != 200:
+        logger.error(f"get_parts_for_magnet: {r.status_code} for magnet {magnet_id}")
+        return []
+
+    rows = r.json()
+    logger.debug(f"get_parts_for_magnet: rows={rows}")
+
+    if not rows:
+        return []
+
+    logger.info(
+        f"get_parts_for_magnet: {len(rows['parts'])} parts found for magnet {magnet_id}"
+    )
+    logger.debug(
+        f"get_parts_for_magnet: {[magnet_part.get('part').get('id') for magnet_part in rows['parts']]} parts found for magnet {magnet_id}"
+    )
+
+    parts = []
+
+    seen = set()
+    for i, magnet_part in enumerate(rows["parts"]):
+        part_id = magnet_part.get("part").get("id")
+        if part_id is None or part_id in seen:
+            continue
+        try:
+            logger.debug(f"get_parts_for_magnet: part[{i}] = id={part_id}")
+            seen.add(part_id)
+            part = get_object(
+                session,
+                api_server,
+                headers,
+                part_id,
+                mtype="part",
+            )
+            logger.debug(
+                f"name={part.get('name')}, type={part.get('type')}, material={part.get('material').get('name') if part.get('material') else None}"
+            )
+            if part:
+                parts.append(part)
+        except Exception as e:
+            logger.error(f"Error fetching part with id {part_id}: {e}")
+
+    return parts
+
+
+def get_magnets_for_site(
+    session: requests.Session,
+    api_server: str,
+    headers: dict,
+    site_id: int,
+) -> list[dict]:
+    """
+    Return the full Magnet objects associated with a site.
+
+    Calls GET /api/sites/{site_id}/magnets (must exist in magnetdb).
+    The endpoint returns a dict with a `site_magnets` key, each entry
+    containing a `magnet_id` field and a nested `magnet` object.
+
+    Each magnet is fetched individually via get_object to obtain the full
+    representation.
+    Returns a list of Magnet dicts (same structure as get_object(mtype="magnet")).
+    """
+    logger.info(f"get_magnets_for_site: api_server={api_server}, site_id={site_id}")
+
+    r = session.get(f"{api_server}/api/sites/{site_id}/magnets", headers=headers)
+    if r.status_code != 200:
+        logger.error(f"get_magnets_for_site: {r.status_code} for site {site_id}")
+        return []
+
+    rows = r.json()
+    logger.debug(f"get_magnets_for_site: rows={rows}")
+
+    if not rows:
+        return []
+
+    site_magnets = rows.get("site_magnets", [])
+    logger.info(
+        f"get_magnets_for_site: {len(site_magnets)} magnets found for site {site_id}"
+    )
+    logger.debug(
+        f"get_magnets_for_site: {[sm.get('magnet', {}).get('id') for sm in site_magnets]} magnets found for site {site_id}"
+    )
+
+    magnets = []
+    seen = set()
+    for i, site_magnet in enumerate(site_magnets):
+        magnet_id = site_magnet.get("magnet", {}).get("id") or site_magnet.get("magnet_id")
+        if magnet_id is None or magnet_id in seen:
+            continue
+        try:
+            logger.debug(f"get_magnets_for_site: magnet[{i}] = id={magnet_id}")
+            seen.add(magnet_id)
+            magnet = get_object(
+                session,
+                api_server,
+                headers,
+                magnet_id,
+                mtype="magnet",
+            )
+            logger.debug(f"name={magnet.get('name') if magnet else None}")
+            if magnet:
+                magnets.append(magnet)
+        except Exception as e:
+            logger.error(f"Error fetching magnet with id {magnet_id}: {e}")
+
+    return magnets
+
+
 def create_object(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     mtype: str = "magnet",
     data: dict = {},
-    verbose: bool = False,
-    debug: bool = False,
 ) -> int:
     """
     create an object and return its id
     """
-    if verbose:
-        print(f"create_object: api_server={api_server}, mtype={mtype}, data={data}")
+    logger.info(f"create_object: api_server={api_server}, mtype={mtype}, data={data}")
 
     web = f"{api_server}/api/{mtype}s"
     r = None
@@ -132,56 +339,85 @@ def create_object(
 
     response = r.json()
     if r.status_code != 200:
-        print(
-            f"create_object: api_server={web}, mtype={mtype}, response={response['detail']}"
-        )
-        return None
+        detail = response.get("detail", "Unknown error")
+        if r.status_code == 401:
+            raise AuthenticationError(
+                f"Authentication failed while creating {mtype}",
+                status_code=401,
+                url=web,
+            )
+        elif r.status_code == 403:
+            raise AuthorizationError(
+                f"Not authorized to create {mtype} objects", status_code=403, url=web
+            )
+        elif r.status_code == 409:
+            raise ResourceConflictError(
+                f"Conflict while creating {mtype}: {detail}", status_code=409, url=web
+            )
+        elif r.status_code >= 500:
+            raise ServerError(
+                f"Server error while creating {mtype}: {detail}",
+                status_code=r.status_code,
+                url=web,
+            )
+        else:
+            raise MagnetAPIException(
+                f"Failed to create {mtype}: {detail}",
+                status_code=r.status_code,
+                url=web,
+            )
 
-    if debug:
-        print(
-            f"create_object: {web}, {mtype.upper()} created: \n{json.dumps(response, indent=4)}"
-        )
+    logger.debug(
+        f"create_object: {web}, {mtype.upper()} created: \n{json.dumps(response, indent=4)}"
+    )
 
     return response["id"]
 
 
 def update_object(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     id: int,
     mtype: str = "magnet",
     data: dict = {},
     files: dict = {},
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    update an object
+) -> dict | None:
+    """Update an existing object via PATCH.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        id: object ID to update
+        mtype: resource type (magnet, part, site, etc.)
+        data: fields to update
+        files: files to attach (unused by the current endpoint)
+
+    Returns:
+        Updated object data dict, or None on error.
     """
-    if verbose:
-        print(f"update_object: api_server={api_server}, mtype={mtype}, data={data}")
+    logger.info(f"update_object: api_server={api_server}, mtype={mtype}, data={data}")
 
     web = f"{api_server}/api/{mtype}s/{id}"
     r = session.patch(web, data=data, headers=headers)
 
     response = r.json()
     if r.status_code != 200:
-        print(
+        logger.error(
             f"update_object: api_server={web}, mtype={mtype}, response={response['detail']}"
         )
         return None
 
-    if debug:
-        print(
-            f"update_object: {web}, {mtype.upper()} created: \n{json.dumps(response, indent=4)}"
-        )
+    logger.debug(
+        f"update_object: {web}, {mtype.upper()} created: \n{json.dumps(response, indent=4)}"
+    )
 
     return response
 
 
 def update_associative_object(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     id: int,
@@ -189,113 +425,137 @@ def update_associative_object(
     dtype: str = "part",
     data: dict = {},
     files: dict = {},
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    update an object in associative table
-    """
-    if verbose:
-        print(
-            f"update_associative_object: api_server={api_server}, mtype={mtype}, data={data}"
-        )
+) -> dict | None:
+    """Update an associative (join-table) object via PATCH.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        id: parent object ID
+        mtype: parent resource type (e.g. "magnet")
+        dtype: related resource type (e.g. "part")
+        data: fields to update on the join row
+        files: files to attach (unused by the current endpoint)
+
+    Returns:
+        Updated join-row data dict, or None on error.
+    """
+    logger.info(
+        f"update_associative_object: api_server={api_server}, mtype={mtype}, data={data}"
+    )
 
     web = f"{api_server}/api/{mtype}s/{id}/{dtype}s"
     r = session.patch(web, data=data, headers=headers)
 
     response = r.json()
     if r.status_code != 200:
-        print(
+        logger.error(
             f"update_associative_object: api_server={web}, mtype={mtype}, response={response['detail']}"
         )
         return None
 
-    if debug:
-        print(
-            f"update_associative_object: {web}, {mtype.upper()} created: \n{json.dumps(response, indent=4)}"
-        )
+    logger.debug(
+        f"update_associative_object: {web}, {mtype.upper()} created: \n{json.dumps(response, indent=4)}"
+    )
 
     return response
 
 
 def del_object(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     mtype: str = "magnet",
-    id: int = None,
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    delete an object given its id
+    id: int | None = None,
+) -> dict | None:
+    """Delete an object by ID.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        mtype: resource type (magnet, part, site, etc.)
+        id: object ID to delete
+
+    Returns:
+        API response dict, or None on error.
     """
-    if verbose:
-        print(f"del_object: api_server={api_server}, mtype={mtype}, id={id}")
+    logger.info(f"del_object: api_server={api_server}, mtype={mtype}, id={id}")
     r = session.delete(
         f"{api_server}/api/{mtype}s/{id}", data={"id": id}, headers=headers
     )
     response = r.json()
     if r.status_code != 200:
-        print(response["detail"])
+        logger.error(response["detail"])
         return None
 
-    print(response)
+    logger.info(f"{response}")
     return response
 
 
 def add_data_to_object(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     id: int,
     data: dict,
     mtype: str = "magnet",
     dtype: str = "part",
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    add data to an object
-    """
-    if verbose:
-        print(
-            f"add_data_to_object: api_server={api_server}, mtype={mtype}, id={id}, dtype={dtype}, data={data}"
-        )
+) -> None:
+    """Post form data to a nested resource endpoint (e.g. /api/magnets/{id}/parts).
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        id: parent object ID
+        data: form data to post (e.g. {"part_id": 5})
+        mtype: parent resource type (e.g. "magnet")
+        dtype: nested resource type (e.g. "part")
+    """
+    logger.info(
+        f"add_data_to_object: api_server={api_server}, mtype={mtype}, id={id}, dtype={dtype}, data={data}"
+    )
 
-    print(f"add_data_to_object: {api_server}/api/{mtype}s/{id}/{dtype}s")
+    logger.info(f"add_data_to_object: {api_server}/api/{mtype}s/{id}/{dtype}s")
     r = session.post(
         f"{api_server}/api/{mtype}s/{id}/{dtype}s",
         data=data,
         headers=headers,
     )
-    print(f"add_data_to_object: r={r}")
+    logger.debug(f"add_data_to_object: r={r}")
     response = r.json()
-    print(f"add_data_to_object: response={response}")
+    logger.debug(f"add_data_to_object: response={response}")
     if r.status_code != 200:
-        print(response["detail"])
+        logger.error(response["detail"])
         return None
     pass
 
 
 def add_files_to_object(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     id: int,
     mtype: str = "part",
     dtype: str = "geometrie",
     files: dict = {},
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    add files to an object
-    """
-    if verbose:
-        print(
-            f"add_files_to_object: api_server={api_server}, mtype={mtype}, id={id}, dtype={dtype}, files={files}"
-        )
+) -> None:
+    """Upload files to a nested resource endpoint (e.g. /api/parts/{id}/geometries).
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        id: parent object ID
+        mtype: parent resource type (e.g. "part")
+        dtype: nested resource type (e.g. "geometrie")
+        files: multipart file dict accepted by requests
+    """
+    logger.info(
+        f"add_files_to_object: api_server={api_server}, mtype={mtype}, id={id}, dtype={dtype}, files={files}"
+    )
 
     r = session.post(
         f"{api_server}/api/{mtype}s/{id}/{dtype}s",
@@ -304,13 +564,13 @@ def add_files_to_object(
     )
     response = r.json()
     if r.status_code != 200:
-        print(response["detail"])
+        logger.error(response["detail"])
         return None
     pass
 
 
 def add_data_files_to_object(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     id: int,
@@ -318,16 +578,22 @@ def add_data_files_to_object(
     dtype: str = "geometrie",
     data: dict = {},
     files: dict = {},
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    add data and files to an object
-    """
-    if verbose:
-        print(
-            f"add_files_to_object: api_server={api_server}, mtype={mtype}, id={id}, dtype={dtype}, files={files}"
-        )
+) -> None:
+    """Post both form data and files to a nested resource endpoint.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        id: parent object ID
+        mtype: parent resource type (e.g. "part")
+        dtype: nested resource type (e.g. "geometrie")
+        data: form data fields (e.g. {"type": "default"})
+        files: multipart file dict accepted by requests
+    """
+    logger.info(
+        f"add_data_files_to_object: api_server={api_server}, mtype={mtype}, id={id}, dtype={dtype}, files={files}"
+    )
 
     r = session.post(
         f"{api_server}/api/{mtype}s/{id}/{dtype}s",
@@ -337,35 +603,41 @@ def add_data_files_to_object(
     )
     response = r.json()
     if r.status_code != 200:
-        print(response["detail"])
+        logger.error(response["detail"])
         return None
     pass
 
 
 def get_history(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     id: int,
     mtype: str = "magnet",
-    otype="record",
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    return list of otype ids attached to object id
-
-    otype = site|record
-    """
-    if verbose:
-        print(
-            f"get_history: api_server={api_server}, mtype={mtype}, otype={otype}, id={id}"
-        )
+    otype: str = "record",
+) -> list | None:
+    """Return the list of related objects (records or sites) attached to an object.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        id: parent object ID
+        mtype: parent resource type (part, magnet, or site)
+        otype: related object type — "record" or "site"
+
+    Returns:
+        List of related object dicts, empty list if mtype not supported,
+        or None on HTTP error.
+    """
+    logger.info(
+        f"get_history: api_server={api_server}, mtype={mtype}, otype={otype}, id={id}"
+    )
 
     r = session.get(f"{api_server}/api/{mtype}s/{id}", headers=headers)
     response = r.json()
     if r.status_code != 200:
-        print(
+        logger.error(
             f"get_history: api_server={api_server}, mtype={mtype}, otype={otype}, id={id} response={response['detail']}"
         )
         return None
@@ -374,9 +646,8 @@ def get_history(
         r = session.get(f"{api_server}/api/{mtype}s/{id}/{otype}s", headers=headers)
         response = r.json()
         if r.status_code != 200:
-            print(f"{api_server}/api/{mtype}s/{id}/{otype}s")
-            print(
-                f"get_history: api_server={api_server}, mtype={mtype}, otype={otype}, id={id} response={response['detail']}"
+            logger.error(
+                f"get_history: {api_server}/api/{mtype}s/{id}/{otype}s response={response['detail']}"
             )
             return None
         return response[f"{otype}s"]
@@ -385,143 +656,223 @@ def get_history(
 
 
 def get_data(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     oid: int,
     mtype: str = "magnet",
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    return data attached to mtype object with oid
+) -> dict | None:
+    """Return the mdata payload attached to an object.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        oid: object ID
+        mtype: resource type (magnet, part, etc.)
 
+    Returns:
+        mdata dict, or None on HTTP error.
     """
-    if verbose:
-        print(f"get_data: api_server={api_server}, mtype={mtype}, id={oid}")
+    logger.info(f"get_data: api_server={api_server}, mtype={mtype}, id={oid}")
 
     r = session.get(f"{api_server}/api/{mtype}s/{oid}/mdata", headers=headers)
     response = r.json()
     if r.status_code != 200:
-        print(
+        logger.error(
             f"get_data: api_server={api_server}/api/{mtype}s/{oid}/mdata, mtype={mtype}, id={oid} response={response['detail']}"
         )
         return None
 
-    if debug:
-        print(f"get_data: response={response}")
+    logger.debug(f"get_data: response={response}")
     return response
 
 
 def post_data(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: dict,
     mtype: str = "magnet",
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    send data to create mtype object
+) -> dict | None:
+    """Create an object by POSTing form data.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: form data dict
+        mtype: resource type to create (magnet, part, site, etc.)
 
+    Returns:
+        Created object data dict, or None on HTTP error.
     """
-    if verbose:
-        print(f"post_data: api_server={api_server}, mtype={mtype}, data={data}")
+    logger.info(f"post_data: api_server={api_server}, mtype={mtype}, data={data}")
 
     r = session.post(f"{api_server}/api/{mtype}s", data=data, headers=headers)
     response = r.json()
     if r.status_code != 200:
-        print(
+        logger.error(
             f"post_data: api_server={api_server}/api/{mtype}s, mtype={mtype}, response={response['detail']}"
         )
         return None
 
-    if debug:
-        print(f"post_data: response={response}")
+    logger.debug(f"post_data: response={response}")
     return response
 
 
 def post_json(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: dict,
     mtype: str = "magnet",
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    send json to create mtype object
+) -> dict:
+    """Create an object by POSTing a JSON body.
 
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: JSON-serialisable dict
+        mtype: resource type to create (material, record, simulation, etc.)
+
+    Returns:
+        Created object data dict.
+
+    Raises:
+        AuthenticationError: HTTP 401
+        AuthorizationError: HTTP 403
+        ResourceConflictError: HTTP 409
+        ServerError: HTTP 5xx
+        MagnetAPIException: any other non-200 response
     """
-    if verbose:
-        print(f"post_json: api_server={api_server}, mtype={mtype}, data={data}")
+    logger.info(f"post_json: api_server={api_server}, mtype={mtype}, data={data}")
 
     r = session.post(f"{api_server}/api/{mtype}s", json=data, headers=headers)
     response = r.json()
     if r.status_code != 200:
-        print(
-            f"post_json: api_server={api_server}/api/{mtype}s, mtype={mtype}, response={response['detail']}"
-        )
-        return None
+        detail = response.get("detail", "Unknown error")
+        if r.status_code == 401:
+            raise AuthenticationError(
+                f"Authentication failed while creating {mtype}",
+                status_code=401,
+                url=f"{api_server}/api/{mtype}s",
+            )
+        elif r.status_code == 403:
+            raise AuthorizationError(
+                f"Not authorized to create {mtype} objects",
+                status_code=403,
+                url=f"{api_server}/api/{mtype}s",
+            )
+        elif r.status_code == 409:
+            raise ResourceConflictError(
+                f"Conflict while creating {mtype}: {detail}",
+                status_code=409,
+                url=f"{api_server}/api/{mtype}s",
+            )
+        elif r.status_code >= 500:
+            raise ServerError(
+                f"Server error while creating {mtype}: {detail}",
+                status_code=r.status_code,
+                url=f"{api_server}/api/{mtype}s",
+            )
+        else:
+            raise MagnetAPIException(
+                f"Failed to create {mtype}: {detail}",
+                status_code=r.status_code,
+                url=f"{api_server}/api/{mtype}s",
+            )
 
-    if debug:
-        print(f"post_json: response={response}")
+    logger.debug(f"post_json: response={response}")
     return response
 
 
 def post_file(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     data: dict,
     mtype: str = "magnet",
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    send data to upload
+) -> dict:
+    """Upload a file by POSTing multipart form data.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        data: multipart file dict accepted by requests (e.g. {"file": <file object>})
+        mtype: resource type (typically "attachment")
 
+    Returns:
+        Created object data dict (contains "id" of the new attachment).
+
+    Raises:
+        AuthenticationError: HTTP 401
+        AuthorizationError: HTTP 403
+        ServerError: HTTP 5xx
+        MagnetAPIException: any other non-200 response
     """
-    if verbose:
-        print(f"post_file: api_server={api_server}, mtype={mtype}, files={data}")
+    logger.info(f"post_file: api_server={api_server}, mtype={mtype}, files={data}")
 
-    print(f"post_file: files={data}")
     r = session.post(f"{api_server}/api/{mtype}s", files=data, headers=headers)
     response = r.json()
-    print(f"post_file: response={response}")
+    logger.debug(f"post_file: response={response}")
     if r.status_code != 200:
-        print(
-            f"post_file: api_server={api_server}/api/{mtype}s, mtype={mtype}, response={response['detail']}"
-        )
-        return None
+        detail = response.get("detail", "Unknown error")
+        if r.status_code == 401:
+            raise AuthenticationError(
+                f"Authentication failed while uploading file for {mtype}",
+                status_code=401,
+                url=f"{api_server}/api/{mtype}s",
+            )
+        elif r.status_code == 403:
+            raise AuthorizationError(
+                f"Not authorized to upload files for {mtype} objects",
+                status_code=403,
+                url=f"{api_server}/api/{mtype}s",
+            )
+        elif r.status_code >= 500:
+            raise ServerError(
+                f"Server error while uploading file for {mtype}: {detail}",
+                status_code=r.status_code,
+                url=f"{api_server}/api/{mtype}s",
+            )
+        else:
+            raise MagnetAPIException(
+                f"Failed to upload file for {mtype}: {detail}",
+                status_code=r.status_code,
+                url=f"{api_server}/api/{mtype}s",
+            )
 
-    if debug:
-        print(f"post_file: response={response}")
     return response
 
 
 def download(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     attach: str,
     wd: str = "",
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    download file
+) -> str | None:
+    """Download an attachment by ID and write it to disk.
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        attach: attachment ID (as string)
+        wd: working directory to write the file into (uses cwd if empty)
+
+    Returns:
+        Filename of the downloaded file, or None if the download failed.
     """
     import os
 
-    if verbose:
-        print(f"download: api_server={api_server}, attach={attach}")
+    logger.info(f"download: api_server={api_server}, attach={attach}")
 
     r = session.get(f"{api_server}/api/attachments/{attach}/download", headers=headers)
     if r.status_code != 200:
-        # print(f"download: api_server={api_server}, attach={attach} response={r.status_code}")
         return None
 
     cwd = os.getcwd()
@@ -541,16 +892,18 @@ def download(
 
 
 def upload(
-    session,
+    session: requests.Session,
     api_server: str,
     headers: dict,
     attach: str,
-    verbose: bool = False,
-    debug: bool = False,
-):
-    """
-    upload file
+) -> None:
+    """Upload a file (stub — not yet implemented).
+
+    Args:
+        session: requests session
+        api_server: API server base URL
+        headers: HTTP request headers
+        attach: local file path to upload
     """
-    if verbose:
-        print(f"upload: api_server={api_server}, attach={attach}")
+    logger.info(f"upload: api_server={api_server}, attach={attach}")
     pass
diff --git a/python_magnetcooling b/python_magnetcooling
new file mode 160000
index 0000000..a94c4f8
--- /dev/null
+++ b/python_magnetcooling
@@ -0,0 +1 @@
+Subproject commit a94c4f839cc7df7058afe5e40184d505c60f6c82
diff --git a/python_magnetsetup b/python_magnetsetup
new file mode 160000
index 0000000..96221aa
--- /dev/null
+++ b/python_magnetsetup
@@ -0,0 +1 @@
+Subproject commit 96221aa3223f036ac83ac600306e088f9b822b01
diff --git a/requirements.txt b/requirements.txt.old
similarity index 100%
rename from requirements.txt
rename to requirements.txt.old
diff --git a/start-venv.sh b/start-venv.sh
new file mode 100755
index 0000000..866c5c9
--- /dev/null
+++ b/start-venv.sh
@@ -0,0 +1,25 @@
+#! /bin/bash
+
+set +x
+
+# pwd shall contains requirements.txt
+
+VENVDIR=./venv
+USE_SYSTEM_PACKAGES=1
+
+if [ ! -d $VENVDIR ]; then
+   echo "create Python Virtualenv: VENVDIR=${VENVDIR}"
+   if [ "$USE_SYSTEM_PACKAGES" == "1" ]; then
+      python -m venv --system-site-packages $VENVDIR
+   else
+      python -m venv $VENVDIR
+   fi
+   . $VENVDIR/bin/activate
+   # Install local dependencies
+   python -m pip install -e ./python_magnetsetup
+   python -m pip install -e ./python_magnetcooling
+   python -m pip install -e .
+   deactivate
+fi
+
+# add option to properly quit python_magnetapi-venv using deactivate
diff --git a/tests/cli/__init__.py b/tests/cli/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/cli/test_cli_integration.py b/tests/cli/test_cli_integration.py
new file mode 100644
index 0000000..7f3947b
--- /dev/null
+++ b/tests/cli/test_cli_integration.py
@@ -0,0 +1,71 @@
+"""Integration tests for CLI."""
+
+import os
+import pytest
+from unittest.mock import patch, Mock
+
+from python_magnetapi.cli import main
+
+
+def test_cli_missing_api_key():
+    """Test CLI raises AuthenticationError without API key."""
+    from python_magnetapi.exceptions import AuthenticationError
+
+    env = {k: v for k, v in os.environ.items() if k != "MAGNETDB_API_KEY"}
+    with patch.dict(os.environ, env, clear=True):
+        with pytest.raises(AuthenticationError):
+            main(["list"])
+
+
+def test_cli_no_command_returns_nonzero():
+    """Test CLI returns non-zero exit code when no command given."""
+    with patch.dict(os.environ, {"MAGNETDB_API_KEY": "test-key"}):
+        exit_code = main([])
+        assert exit_code != 0
+
+
+def test_list_command_runs():
+    """Test list command runs end-to-end with mocked HTTP."""
+    with patch.dict(os.environ, {"MAGNETDB_API_KEY": "test-key"}):
+        with patch("requests.Session") as mock_session_cls:
+            mock_session = Mock()
+            mock_session_cls.return_value.__enter__ = Mock(return_value=mock_session)
+            mock_session_cls.return_value.__exit__ = Mock(return_value=False)
+
+            with patch("python_magnetapi.utils.get_list") as mock_get_list:
+                mock_get_list.return_value = {"M10": 1}
+
+                exit_code = main(["--server", "localhost", "list", "--mtype", "magnet"])
+                assert exit_code == 0
+                mock_get_list.assert_called_once()
+
+
+def test_process_command_runs():
+    """Test process command returns 0 (not implemented stub)."""
+    with patch.dict(os.environ, {"MAGNETDB_API_KEY": "test-key"}):
+        with patch("requests.Session") as mock_session_cls:
+            mock_session = Mock()
+            mock_session.__enter__ = Mock(return_value=mock_session)
+            mock_session.__exit__ = Mock(return_value=False)
+            mock_session_cls.return_value = mock_session
+
+            exit_code = main(["--server", "localhost", "process"])
+            assert exit_code == 0
+
+
+def test_view_command_not_found():
+    """Test view command raises ResourceNotFoundError when object missing."""
+    from python_magnetapi.exceptions import ResourceNotFoundError
+
+    with patch.dict(os.environ, {"MAGNETDB_API_KEY": "test-key"}):
+        with patch("requests.Session") as mock_session_cls:
+            mock_session = Mock()
+            mock_session.__enter__ = Mock(return_value=mock_session)
+            mock_session.__exit__ = Mock(return_value=False)
+            mock_session_cls.return_value = mock_session
+
+            with patch("python_magnetapi.utils.get_list") as mock_get_list:
+                mock_get_list.return_value = {}
+
+                with pytest.raises(ResourceNotFoundError):
+                    main(["--server", "localhost", "view", "--name", "nonexistent"])
diff --git a/tests/cli/test_list_command.py b/tests/cli/test_list_command.py
new file mode 100644
index 0000000..a9755ad
--- /dev/null
+++ b/tests/cli/test_list_command.py
@@ -0,0 +1,72 @@
+"""Tests for list command."""
+
+import argparse
+import pytest
+from unittest.mock import Mock, patch
+
+from python_magnetapi.cli.commands.list import ListCommand
+from python_magnetapi.cli.context import CLIContext
+
+
+def make_context():
+    ctx = Mock(spec=CLIContext)
+    ctx.session = Mock()
+    ctx.web = "http://test:8000"
+    ctx.headers = {"Authorization": "test-key"}
+    ctx.debug = False
+    return ctx
+
+
+def test_list_command_execution():
+    """Test list command executes correctly."""
+    context = make_context()
+
+    with patch("python_magnetapi.utils.get_list") as mock_get_list:
+        mock_get_list.return_value = {"M10": 1, "M11": 2}
+
+        cmd = ListCommand()
+        args = Mock()
+        args.mtype = "magnet"
+        args.filters = None
+
+        exit_code = cmd.execute(args, context)
+
+        assert exit_code == 0
+        mock_get_list.assert_called_once()
+
+
+def test_list_command_parser_configuration():
+    """Test list command parser configuration."""
+    parser = argparse.ArgumentParser()
+    cmd = ListCommand()
+    cmd.configure_parser(parser)
+
+    args = parser.parse_args(["--mtype", "part"])
+    assert args.mtype == "part"
+
+
+def test_list_command_default_mtype():
+    """Test list command defaults to magnet."""
+    parser = argparse.ArgumentParser()
+    cmd = ListCommand()
+    cmd.configure_parser(parser)
+
+    args = parser.parse_args([])
+    assert args.mtype == "magnet"
+
+
+def test_list_command_with_filter():
+    """Test list command parses filter arguments."""
+    parser = argparse.ArgumentParser()
+    cmd = ListCommand()
+    cmd.configure_parser(parser)
+
+    args = parser.parse_args(["--filter", "status=active"])
+    assert args.filters == ["status=active"]
+
+
+def test_list_command_name_and_help():
+    """Test list command metadata."""
+    cmd = ListCommand()
+    assert cmd.name == "list"
+    assert cmd.help
diff --git a/tests/test_list.py b/tests/test_list.py
index d4acc9c..e0cb9b8 100644
--- a/tests/test_list.py
+++ b/tests/test_list.py
@@ -4,7 +4,7 @@
 
 # add  @pytest.fixture to declare context
 
-api_server = os.getenv("MAGNETDB_API_SERVER") or "api.magnetdb-dev.local"
+api_server = os.getenv("MAGNETDB_API_SERVER") or "https://api.magnetdb-dev.local"
 api_key = os.getenv("MAGNETDB_API_KEY")
 
 headers = {"Authorization": os.getenv("MAGNETDB_API_KEY")}
@@ -43,7 +43,14 @@ class TestList:
     def list_type(self, mtype: str):
         from python_magnetapi import utils
 
-        return utils.get_list(session, api_server, headers=headers, mtype=mtype, debug=False, verbose=False)
+        return utils.get_list(
+            session,
+            api_server,
+            headers=headers,
+            mtype=mtype,
+            debug=False,
+            verbose=False,
+        )
 
     def test_material(self):
         _ids = self.list_type("material")
@@ -127,7 +134,9 @@ def create(self, mtype: str):
     def delete(self, mtype: str, name: str):
         from python_magnetapi import utils
 
-        ids = utils.get_list(session, api_server, headers=headers, mtype=mtype, debug=False)
+        ids = utils.get_list(
+            session, api_server, headers=headers, mtype=mtype, debug=False
+        )
         print(f"id={ids[name]}")
 
         response = utils.del_object(
@@ -140,7 +149,9 @@ def delete(self, mtype: str, name: str):
             debug=False,
         )
 
-        ids = utils.get_list(session, api_server, headers=headers, mtype=mtype, debug=False)
+        ids = utils.get_list(
+            session, api_server, headers=headers, mtype=mtype, debug=False
+        )
         return name in ids
 
     def up(self, mtype: str):