# auto-manager

**Measurement analysis for mechanical test engineers — load messy DAQ files, get answers in one command, and let your LLM drive the whole toolbox over MCP.**

You ran the test. Now you have a CSV from one rig, a TDMS file from another, semicolons and decimal commas from the German lab, and a manager who wants a report. `auto-manager` reads all of it, figures out what each channel *is* (accelerometer? load cell? thermocouple?), runs the right analysis for each, and writes a self-contained HTML report with plain-English findings:

> - **Accel_X**: dominant frequency 32.5 Hz, Q≈16, broadband RMS 0.84 g (further peaks: 120.0 Hz).
> - **Load**: 186 fatigue cycles counted (rainflow, ASTM E1049), max range 24.6 kN; damage-equivalent constant-amplitude range 14.4 kN (m=5).
> - **TC_Air**: 3 steady plateau(s) at 25.0, 85.1, −20.1; max transition overshoot 5.1.
> - **Force**: possible clipping: 608 samples pinned at the minimum.

No project files, no wiring diagrams, no license server.

## Install

```bash
pip install "auto-manager @ git+https://github.com/Maxpeng59/auto-manager"
# or, inside a clone:  pip install .
```

Python ≥ 3.10. MDF/MF4 support is an extra: `pip install "auto-manager[mdf] @ git+..."`.

## Try it in 60 seconds

```bash
automgr samples                                 # writes 3 realistic demo datasets
automgr info    samples/weld_fatigue_load.csv   # channels, units, detected kinds
automgr report  samples/bracket_vibration.csv --open   # full HTML report
automgr fatigue samples/weld_fatigue_load.csv -c Last
automgr thermal samples/thermal_chamber.csv
```

The demo files are deliberately awkward — a German export with semicolons, decimal
commas and a metadata preamble; a tab file with ISO timestamps — because that is
what real DAQ exports look like.

## What it does

| command | what you get |
|---|---|
| `automgr info FILE` | channels, units, auto-detected kinds, sample rate, duration, metadata |
| `automgr stats FILE [-c CH]` | min/max/mean/RMS/crest factor + data-quality flags (NaN gaps, clipping) |
| `automgr spectrum FILE -c CH` | Welch PSD: dominant peaks with Q estimates, broadband & band RMS |
| `automgr fatigue FILE -c CH` | rainflow cycle counting per **ASTM E1049** (validated against the standard's worked example), range histogram, damage-equivalent ranges, optional Miner damage with your S-N parameters |
| `automgr thermal FILE [-c CH]` | soak plateau detection, ramp rates, controller overshoot |
| `automgr report FILE` | everything above, chosen per channel automatically, as one shareable HTML file with charts, findings and a provenance footer (source hash, tool version) |
| `automgr mcp` | all of it as MCP tools for Claude / any MCP client |

Every command works with zero flags on a well-formed file; every error message says what to do next (`--rate` when a file has no time column, channel suggestions on typos, ...).

### File formats

- **CSV / TXT / TSV** — auto-detects delimiter (`,` `;` tab), decimal commas, metadata preambles, separate unit rows, units embedded in headers (`Load (kN)`, `Accel [g]`), datetime or elapsed-time columns, text status columns, NaN gaps.
- **TDMS** (NI LabVIEW/DIAdem) — via npTDMS, including waveform timing and units.
- **MDF / MF4** (CANape, INCA, ...) — via asammdf (`[mdf]` extra).

The loaders normalise everything into one channel model, so a future live-DAQ backend feeds the same analyses.

### Channel auto-classification

Units and names are strongly conventional in test data. `g`/`m/s²` → acceleration → PSD. `kN`/`µε`/`Nm` → load/strain/torque → rainflow. `°C`/`TC_1`/`PT100` → temperature → steady-state detection. You can always override by calling a specific analysis on any channel.

## Use it from an LLM (MCP)

`auto-manager` ships an MCP server so a model can be your natural-language front end — *"load bench_run_042.csv, tell me whether the 32 Hz mode shifted vs. Tuesday's baseline, and write me a report"* — while the numbers come from real signal processing, not from a model's imagination.

```bash
# Claude Code
claude mcp add automgr -- automgr mcp
```

```jsonc
// Claude Desktop (claude_desktop_config.json)
{ "mcpServers": { "automgr": { "command": "automgr", "args": ["mcp"] } } }
```

Exposed tools: `measurement_info`, `channel_stats`, `spectrum`, `fatigue_rainflow`, `thermal_steady_states`, `channel_segment` (inspect raw samples), `generate_report`, `supported_formats`. The model sees channel kinds and units, so it knows a `kN` channel gets rainflow, not an FFT.

## Python API

```python
import auto_manager as am

m = am.load("samples/bracket_vibration.csv")          # any supported format
psd = am.welch_psd(m.channel("Accel_X"), m.sample_rate)
print(psd["peaks"][0])        # {'freq_hz': 32.5, 'psd': ..., 'q_estimate': 16.2}

fat = am.rainflow(m.channel("Load"), sn_exponent=5, sn_ref_range=80.0, sn_ref_cycles=2e6)
soaks = am.steady_states(m.channel("TC_Air"), m.sample_rate)

from auto_manager.report import generate_report
generate_report(m)             # -> bracket_vibration.report.html
```

## Honest limitations (v0.1)

- File-based analysis only. Live DAQ (LabJack, VISA/SCPI instruments) is the next milestone — the channel model is already designed for it.
- Steady-state detection is a windowed heuristic; its parameters (`--slope-limit`, `--min-duration`) are exposed and echoed into results for reproducibility.
- Miner damage needs *your* S-N parameters; the reference slopes (m=3, m=5) shown by default are labelled as assumptions, not material data.
- No unit conversion (a `lbf` channel stays in lbf) and no mean-stress correction yet.
- Reports are generated automatically — review before you release them.

## Roadmap

This is module 1 of a four-module plan for an AI-native hardware+software test bench (see [research/2026-07-02-landscape-and-architecture.md](research/2026-07-02-landscape-and-architecture.md) for the full landscape study):

1. **Natural-language analysis over measurement files** ← *you are here*
2. Auto-control of external hardware (asyncio hardware-abstraction service as the LLM's tool surface; human approval on state-changing writes; simulation/dry-run backend)
3. LLM-generated firmware for a fixed companion dev-board kit (two-domain firmware: frozen safety kernel + MPU-restricted app partition; sim→HIL pipeline; A/B rollback)
4. Custom companion PCB (demand-gated)

## Development

```bash
uv venv && uv pip install -e ".[dev]"
uv run pytest            # 47 tests, incl. ASTM E1049 vector & MCP stdio handshake
python examples/generate_sample_data.py   # regenerate examples/data
```

## License

MIT