DEV Community: Aman Singh

Four tools for seismic data

Aman Singh — Thu, 22 Oct 2026 07:36:20 +0000

Originally published at amansinghnp.com.

Over 2025 and 2026 I built four small open-source tools that sit at different points of a seismic data pipeline. Each solves a different problem, so start with the one you need:

Tool	What it does	Reach for it if you	Code
`torch-friction`	Rate-and-state friction as a differentiable PyTorch layer, so friction parameters can be fitted by gradient descent	want to recover a, b and Dc from friction data, or put exact friction physics inside a larger network	GitHub
`Basalt`	C++ frequency-wavenumber (f-k) filtering, built around memory-mapped SEG-Y, aligned memory, tiled FFTs and AVX2/AVX-512 kernels	need to remove ground roll from active-source shot gathers	GitHub
`fast-trigger`	Recursive STA/LTA event detection in C++23 with a NumPy-friendly Python API	need to flag events in single traces or batches of traces from Python	GitHub
`seismic-linter`	A static analyser (on PyPI) that flags temporal data leakage in ML code before training runs	train models on earthquake catalogues or other time series and want leaky code blocked at commit time	GitHub

Each tool's section opens with a short entry: the clearest result, the main limitation and how it was tested. The physics, numerics and full test results follow. Every chart below was produced by running the published code (or, where noted, a line-for-line NumPy port of it) on the data listed in section 6. Some of the results are flattering and some are not. I've kept both. The earthquake-severity model that led to seismic-linter is on the Projects page as South Asia Earthquake Severity.

< 0.05% friction parameter error after inversion

−20.7 dB ground roll removed by the f-k mute

≈ 2 dB less signal needed by x² STA/LTA at a 1% false-alarm rate

1. Why build a toolchain

Machine learning in seismology has moved fast. Deep networks now pick phases and detect events at scale (Mousavi & Beroza, 2022), and physics-informed neural networks (PINNs) put governing equations into the loss function (Raissi et al., 2019; Karniadakis et al., 2021). Two problems keep coming up anyway. The first is that the physics is often bolted on after the fact, instead of living inside the computational graph where gradients can reach it. The second is that evaluation is fragile: time-series leakage has inflated reported results across many fields (Kapoor & Narayanan, 2023), and earthquake forecasting has its own history of complex models that turn out no better than simple baselines (Mignan & Broccardo, 2019, 2020).

The four tools line up against those two problems. torch-friction and Basalt handle the physics and signal-processing side. fast-trigger handles detection. seismic-linter guards the evaluation.

2. torch-friction: differentiable rate-and-state friction

torch-friction in brief

Result. In a teacher–student test at a lab-scale Dc of 10 µm (Setup B, section 2.5), gradient descent through the solver recovered a, b and Dc to within 0.05% from starting guesses that were 33–100% wrong, and the loss levelled off at the noise variance.
Main limitation. Recovery depends on the experiment, not the optimiser. With only 8% of Dc of slip after a single step (Setup A), b and Dc can't be separated and b moved further from the truth. The layer also solves only the zero-dimensional friction ODE, not the elastodynamic problem around a fault.
How it was tested. Synthetic velocity-step data from a teacher layer with hidden parameters and Gaussian noise (σ = 10⁻⁴), fitted by a student layer with Adam; RK4 checked against the exact aging-law relaxation at seven step sizes (error falls 19.7× then 16.8× per halving of Δt). Run with torch-friction from PyPI in float64 on CPU.

2.1 The friction law

Laboratory rock friction isn't a constant. It depends on how fast the surfaces slide and on how long the contacts have had to age. Dieterich (1979) and Ruina (1983) captured this with a friction coefficient that depends on slip velocity V and a state variable θ, which you can read as the average lifetime of the asperity contacts:

μ(V, θ) = μ0 + a ln(V / V0) + b ln(V0θ / Dc)

The a term is the direct effect: friction jumps immediately when velocity changes. The b term is the evolution effect: as the contact population turns over across a characteristic slip distance Dc, friction relaxes to a new steady state. At steady state, θ = Dc/V and μss = μ0 + (a − b) ln(V/V0). When a − b < 0 the fault is velocity-weakening: sliding faster makes it weaker, which is the precondition for earthquake nucleation (Marone, 1998; Scholz, 1998).

Whether that weakening actually produces an earthquake depends on the surroundings. In the classic spring-slider model, a block dragged through a spring of stiffness k slides stably if k is above a critical stiffness kc = σ(b − a)/Dc, and stick-slips below it (Ruina, 1983; Rice & Ruina, 1983).

Figure 1. The spring-slider model. The load point moves at a constant rate, stress builds in the spring while the block sticks, then drops when the block slips. With velocity-weakening friction and k < kc, this cycle repeats indefinitely: the laboratory analogue of the seismic cycle.

2.2 Two ways the state can evolve

The friction equation says nothing about how θ changes over time. There are two standard choices, and torch-friction implements both as law='aging' and law='slip':

Law	dθ/dt	Behaviour	Source
Aging (Dieterich)	1 − Vθ/Dc	State grows with time even at rest, so contacts heal while stationary	Dieterich (1979)
Slip (Ruina)	−(Vθ/Dc) ln(Vθ/Dc)	State only evolves with slip; symmetric response to velocity steps up and down	Ruina (1983)

The standard lab test is a velocity step. Figure 2 runs one through FrictionLayer.forward_trajectory with a = 0.015, b = 0.020 and Dc = 10 µm, stepping from 1 to 10 µm/s and back.

Figure 2. Velocity step up at t = 2 s and back down at t = 8 s, computed with torch-friction (Δt = 2 ms, RK4). The jump of a·ln10 ≈ 0.035 is the direct effect; the settling to (a − b)·ln10 ≈ −0.012 below the starting level is the evolution effect. The two laws agree on the peak and the steady state but differ on the path between them.

The two laws only differ in the transient, but the difference isn't small: up to Δμ = 0.012 about one second after the step up, which is a third of the whole direct effect. The asymmetry is easy to see from the equations. After a tenfold step up, Vθ/Dc = 10, so the aging law evolves at a rate of 1 − 10 = −9 while the slip law evolves at −10 ln 10 ≈ −23. The slip law weakens faster. After the step down (Vθ/Dc = 0.1) it's reversed: 0.9 for aging against 0.23 for slip, so the aging law heals faster. Six seconds after the step down, the aging curve has recovered to μ = 0.586 while the slip curve is still at 0.575. Lab experiments with large velocity steps tend to favour the slip law (Bhattacharya et al., 2015), which is why the library keeps both.

2.3 Integrating the state equation

Each call to the layer advances θ by one classical fourth-order Runge-Kutta (RK4) step, then evaluates the friction equation at the new state. The core is short:

torch_friction/layers.py

def rk4_step(self, t, theta, v, dt, Dc):
    k1 = self.physics(t, theta, v, Dc)
    k2 = self.physics(t + dt/2, theta + k1*dt/2, v, Dc)
    k3 = self.physics(t + dt/2, theta + k2*dt/2, v, Dc)
    k4 = self.physics(t + dt, theta + k3*dt, v, Dc)
    return theta + (dt/6.0)*(k1 + 2*k2 + 2*k3 + k4)

The state equation is stiff when Dc is small relative to V·Δt. Linearising the aging law about steady state gives an eigenvalue of −V/Dc, and RK4's stability interval on the negative real axis ends near −2.79 (Hairer & Wanner, 1996), so explicit integration needs Δt < 2.79 Dc/V. The layer warns once Δt goes past 0.5 Dc/Vmax, which leaves a margin of about 5.6× below the stability limit. That margin is sensible, because the accuracy limit arrives well before the stability limit does.

To check the accuracy, Figure 3 relaxes the aging law from θ0 = 10 s at constant V, where the exact solution is θ(t) = Dc/V + (θ0 − Dc/V)e^−Vt/Dc, and compares it with the library's RK4 at seven step sizes.

Figure 3. Error in θ after 2 s of relaxation against step size. Halving Δt cuts the error by 19.7× and then 16.8×, close to the 2⁴ = 16 of a fourth-order method. Below Δt ≈ 0.06 s the error stops falling at about 3 × 10⁻⁷ s.

The floor isn't RK4's fault. The layer guards its logarithms and divisions with a 10⁻¹² epsilon and a smooth soft_clamp, and with Dc = 10⁻⁵ m those guards shift the steady state by about one part in 10⁷. That's a deliberate trade: gradients that never hit NaN in exchange for a relative bias far below lab measurement noise. If you're working at very small Dc, scale the epsilon with it.

2.4 Backpropagating through the solver

Because every operation in the RK4 step is a PyTorch tensor op, autograd records the whole integration. forward_trajectory unrolls the step T times into preallocated output tensors, and loss.backward() replays that graph in reverse to get ∂L/∂a, ∂L/∂b, ∂L/∂Dc and ∂L/∂μ0 (Paszke et al., 2019). This is "discretise-then-optimise": the gradients are exact for the discrete solver, at the cost of memory that grows linearly with T. The alternative is the adjoint method used by neural ODEs, which solves a second ODE backwards in time and uses constant memory, but its gradients are only as accurate as that backward solve (Chen et al., 2018). For sequences of a few thousand steps, exact gradients are the better deal.

Figure 4. One cell of the unrolled graph. Black arrows are the forward pass; green arrows are gradients flowing back through all four RK4 stages to the parameters. Parameters are stored in unconstrained form and passed through softplus, so a, b and Dc stay positive whatever the optimiser does.

Three other details matter for training. Parameters default to float64, because the evolution term takes logs of quantities that span many orders of magnitude. Negative velocities raise an error instead of being silently clamped. And freeze_parameters(['a', 'Dc']) lets you fix quantities you've measured independently, which matters a great deal for the next section.

2.5 The inverse problem, and when it's solvable

The test is to generate noisy friction data from a "teacher" layer with hidden parameters, then train a "student" layer, started from wrong values, to recover them. I ran two versions.

Setup A is the demo in the repository's examples/ folder: one step from 1 to 10 µm/s, Dc = 10 mm, Δt = 0.1 s, 1,000 samples, Adam at a learning rate of 10⁻³ for 150 epochs. Setup B uses a lab-scale Dc = 10 µm, a sequence of three steps (up ×10, down ×10, up ×3) over 12 s at Δt = 2 ms, and Adam at 10⁻² for 600 epochs. Both add Gaussian noise with σ = 10⁻⁴.

Figure 5. Setup B: relative error of each recovered parameter against epoch, starting from guesses that were 33–100% wrong. All three are within 1% by epoch 166 and within 0.05% at the end. The loss levels off at 9.9 × 10⁻⁹, which is the noise variance (10⁻⁸): the student is fitting everything except the noise.

Parameter	True	Start	Setup A (150 epochs)	Setup B (600 epochs)
a	0.015	0.010	0.0110	0.01500
b	0.020	0.010	0.0092	0.02000
Dc	10 mm / 10 µm	2× true	21.7 mm	9.996 µm
μ0	0.600	0.600	0.607	0.60000

Setup A doesn't recover the parameters, and b actually moves further from the truth. Part of the reason is optimisation (the loss is still 1,000× the noise floor after 150 epochs), but the main reason is identifiability. After the step, the block slides at 10 µm/s for 80 s, which is 0.8 mm, only 8% of Dc. The evolution effect has barely started, so the data mostly constrain the direct effect plus a linearised evolution term in which b and Dc appear together as roughly b/Dc. Many (b, Dc) pairs fit equally well. Setup B slides many times Dc after each step and steps in both directions, so the two parameters leave separate fingerprints.

Design rule

For rate-and-state inversion, design the experiment before the optimiser. Record at least several Dc of slip after each step, include steps up and down, and freeze any parameter you've measured some other way. A differentiable solver finds the minimum; it can't create information the data don't contain.

2.6 Where this sits in the literature

torch-friction is deliberately narrow. It solves the zero-dimensional friction ODE, not the elastodynamic problem around a fault. Rucker and Erickson (2024) go further and train PINNs for the wave equation with a rate-and-state fault boundary in 1D and 2D, recovering depth-varying friction parameters. Borate et al. (2024) show a PINN can recover rate-and-state parameters from acoustic monitoring of lab stick-slip experiments. A differentiable friction layer is a building block for that kind of model: a component whose physics is exact, placed inside a larger network that learns everything else.

3. Basalt: f-k filtering at the metal

Basalt in brief

Result. On a synthetic shot gather, the sigmoid mask with vcut = 1,500 m/s kept 99.97% of the reflection energy and 0.85% of the ground-roll energy, a 20.7 dB reduction (section 3.1).
Main limitation. There are no throughput numbers yet: every results cell in PERFORMANCE.md is marked TBD, and the C++ AVX2 kernels weren't run for this post. The kernel also reads only mute_vel_max, so the reject cone is always symmetric in ±k.
How it was tested. A NumPy port of Basalt's mask applied to a synthetic gather with separately known reflection and ground-roll components, with energy measured on each component. In the repository's CI, a golden checksum for single-thread AVX2 output and a bit-for-bit match between multi-threaded batch and single-threaded output.

3.1 What an f-k filter does

In an active-source shot gather, the reflections geologists care about arrive with high apparent velocities across the receiver spread. Ground roll, the surface waves travelling along the ground, is slow (typically a few hundred m/s), low-frequency and much stronger. A 2D Fourier transform maps each linear event with apparent velocity v to a line f = v·k in the frequency-wavenumber plane, so the two separate by slope. Muting the slow wedge and transforming back is the "pie-slice" filter (Embree et al., 1963; Yilmaz, 2001).

Basalt's mute is a smooth sigmoid rather than a hard cut, because a hard edge in the f-k plane rings in the time domain:

w(f, k) = sigmoid( 10 · ( |f / (k + ε)| − vcut ) / taper )

Figure 6. (a) A synthetic gather: 128 traces at 5 m spacing, 4 ms sampling, four reflectors (2,000–3,600 m/s, 30 Hz Ricker) and two ground-roll modes (320 m/s at 8 Hz, 450 m/s at 12 Hz). (b) Its f-k spectrum; the shaded region, |f/k| < 1,500 m/s, is muted. (c) The result, using a NumPy port of Basalt's mask with vcut = 1,500 m/s and taper = 100 m/s.

Measured on each component separately (the filter is linear), the mask keeps 99.97% of the reflection energy and 0.85% of the ground-roll energy, a 20.7 dB reduction. The panel also shows the two classic f-k artefacts. The small residue at the top centre is the ground-roll apex at zero offset, where the event is locally flat, so its energy sits near k = 0 inside the pass region. The faint smears at the edges near 1.0 s are wrap-around: the FFT treats the gather as periodic in offset, so energy that gets cut at one edge leaks back in at the other. Production workflows handle these with spatial tapering and padding before the transform.

3.2 Pipeline and memory

Figure 7. Basalt's path from disk to filtered data. The lower strip shows the mask kernel sweeping one frequency row eight wavenumbers at a time, one AVX2 register per iteration.

Most of the engineering is about not moving data. SEG-Y files are memory-mapped rather than read into buffers, and the parser decodes the EBCDIC textual header and legacy IBM-360 floating-point samples in place (SEG Technical Standards Committee, 2017). All working memory comes from a MemoryArena, a bump allocator with 64-byte alignment, so one gather's scratch space is a single allocation and reset() frees it in O(1). Complex spectra are stored as a structure of arrays (separate real and imag planes), so that eight consecutive real parts load into one 256-bit register without shuffling.

A 2D FFT is a set of 1D FFTs along rows, a transpose, then 1D FFTs along what used to be columns (Cooley & Tukey, 1965). The transpose is where naive code falls apart: striding down columns of a large matrix misses the cache on nearly every access. Basalt tiles the transpose so each block fits in cache, the approach cache-oblivious algorithms formalise (Frigo et al., 1999), and picks the 2D FFT schedule automatically by problem size, in the same spirit as FFTW's planner (Frigo & Johnson, 2005).

3.3 The SIMD mask kernel

The filter itself is embarrassingly parallel: every f-k bin gets multiplied by its own weight. The AVX2 path tiles the spectrum (32×64 bins for small gathers, 64×128 by default, 32×96 above 2,048), prefetches 8 to 24 elements ahead, and handles eight bins per instruction:

src/filter/fk_filter.cpp (AVX2 path, abridged)

const __m256 vk     = _mm256_load_ps(k_vals.data());
const __m256 vel    = _mm256_div_ps(vf, _mm256_add_ps(vk, v_eps));
__m256 x            = _mm256_sub_ps(absolute_ps(vel), v_cut);
x                   = _mm256_mul_ps(x, v_steep);
const __m256 weight = fast_sigmoid_avx(x);
real = _mm256_mul_ps(real, weight);
imag = _mm256_mul_ps(imag, weight);

There are no branches in the inner loop: the "mute or keep" decision is a multiplication by a weight between 0 and 1, so no lane waits on a mispredicted branch. At runtime, the library uses the AVX-512 path if the CPU reports avx512f, vl, bw and dq, and otherwise falls back to AVX2. One detail worth knowing: the kernel reads only mute_vel_max, so the reject cone is always symmetric in ±k. mute_vel_min is currently unused.

3.4 Performance: what's measured and what isn't

I'm not quoting throughput numbers here, because the repository hasn't published any yet. PERFORMANCE.md lays out the method: pinned CPU governors, the basalt_bench sweep across size, threads, SIMD mode, NUMA mode and memory policy, and PMU counters on self-hosted Linux. Every results cell is still marked TBD, because shared CI runners are fine for correctness testing but no good for performance claims. What is in CI is correctness: a golden checksum for single-thread AVX2 output, and a check that multi-threaded batch output matches single-threaded output bit for bit.

4. fast-trigger: STA/LTA in C++23

fast-trigger in brief

Result. The detector triggers on both P and S in a synthetic seismogram. The sharper finding is about the characteristic function: at a fixed 1% false-trigger rate, ObsPy's x² version reaches 50% detection at about 1.8σ against about 2.25σ for the |x| that fast-trigger uses, roughly 2 dB less signal, and picks earlier (a median 0.26 s after onset at 3σ, against 0.39 s). See section 4.3.
Main limitation. The characteristic function is fixed at |x|, which the test above shows is the weaker detector for this signal and noise model. It hasn't yet been benchmarked on real waveforms, and the package isn't on PyPI yet.
How it was tested. An exact NumPy port of the recursion, compared with ObsPy 1.5.1's recursive_sta_lta on synthetic 100 Hz seismograms with known P and S onsets. Thresholds were calibrated on 300 noise-only traces, with 150 trials per P-wave amplitude and fixed seeds. The repository adds Hypothesis property-based tests and an AddressSanitizer and UBSan build.

4.1 Classic and recursive STA/LTA

The short-term-average over long-term-average ratio is still the most widely used automatic event detector (Allen, 1978; Trnkoczy, 2012). A short window tracks the signal's recent energy, a long window tracks the background, and a trigger fires when their ratio crosses a threshold. The recursive form replaces the sliding windows with exponential moving averages:

STAi = cs|xi| + (1 − cs)STAi−1, cs = 1/Nsta

	Classic (sliding window)	Recursive (exponential)
Work per sample	O(1) with running sums	O(1): two multiply-adds
State per trace	Ring buffer of Nlta samples	Two floats
Memory of the past	Hard cut-off at Nlta	Exponential decay, time constant Nlta
Streaming	Needs the buffer carried between chunks	Needs only the two averages carried over

Withers et al. (1998) compare these and other trigger algorithms in detail. fast-trigger implements the recursive form in C++23, starts both averages at the first sample's magnitude, and exposes compute_sta_lta for a single trace and compute_sta_lta_batch for a 2D array of traces, the latter parallelised over traces with OpenMP. Inputs are validated at the boundary: empty arrays, zero windows, STA ≥ LTA and windows longer than the trace all raise ValueError in Python.

4.2 A worked example

Figure 8 applies it to a synthetic 100 Hz seismogram: Gaussian noise plus a 0.2 Hz microseism, a 6 Hz P arrival at 30 s and a stronger 3 Hz S arrival at 40 s. STA is 0.5 s and LTA is 10 s. For comparison, it also shows ObsPy's recursive_sta_lta (Beyreuther et al., 2010), which uses the same recursion on x² instead of |x|.

Figure 8. Top: the seismogram (min/max envelope). Bottom: STA/LTA from both characteristic functions, with each one's threshold set for a 1% false-trigger rate on noise alone (dashed). Both trigger on P and S; the |x| ratio triggers at 30.23 s and the x² ratio at 30.16 s. The green line sweeps the trace the way a real-time detector would.

4.3 The characteristic function matters more than the language

Squaring the signal doubles its dynamic range in decibels. Where an arrival lifts the |x| ratio to about 3.4, it lifts the x² ratio to about 7.7. The noise-only ratio gets peakier too, though, so the only fair comparison is at an equal false-alarm rate. I calibrated both thresholds on 300 noise-only traces (1.50 for |x|, 1.92 for x²), then measured how often each detects a P wave of known amplitude over 150 trials per level.

Figure 9. Detection probability against P-wave amplitude at a fixed 1% false-trigger rate. The x² function reaches 50% detection at about 1.8σ; |x| needs about 2.25σ, roughly 2 dB more signal. The x² function also picks earlier: a median 0.26 s after onset at 3σ, against 0.39 s.

For this signal and noise model, the energy function is simply the better detector, and no amount of C++ speed makes up for missing an event. Making the characteristic function a parameter (|x|, x², or Allen's (1978) function, which adds a weighted derivative term) is the most useful next change to fast-trigger. It's also a reminder to benchmark detectors at a fixed false-alarm rate, not at a fixed threshold.

4.4 Engineering notes

The C++ core takes std::span inputs and uses an mdspan-style view for batches, with __restrict pointers so the compiler can vectorise. Release builds on Linux and macOS use -ffast-math by default, which is fine for a detector but not for bit-reproducible research, so FAST_TRIGGER_STRICT_FLOAT=ON restores strict IEEE behaviour. There are Hypothesis property-based tests, and an AddressSanitizer and UBSan build. One practical caveat: because the batch function already uses OpenMP internally, calling it from many Python threads at once oversubscribes the CPU. Use one batch call at a time, or set OMP_NUM_THREADS.

5. seismic-linter: catching leakage before training

seismic-linter in brief

Result. Version 0.2.0 flagged all three leakage mistakes in an eight-line script (four violations across rules T001, T002 and T003) and exited with code 1, which is what lets it block a merge from a pre-commit hook or a GitHub Action (section 5.2).
Main limitation. The rules are heuristics over syntax, not data flow. T002 judges by variable names, so a leaky fit on train_df gets through; T001 doesn't yet treat ewm or custom wrappers as safe; T003 only accepts a literal shuffle=False.
How it was tested. Shown here on one deliberately leaky script, with the real output reproduced in section 5.2. Two runtime checks, @verify_monotonicity and validate_split_integrity, cover what static analysis can't see.

5.1 Three ways the future leaks into the past

Kaufman et al. (2012) define leakage as information in the training data that wouldn't be available at prediction time. In time series it usually comes from ordinary-looking code. Normalising with a global mean includes test-period statistics in every training row. Fitting a scaler before splitting does the same thing. And a shuffled train/test split lets the model train on 2023 and be tested on 2019. Standard k-fold cross-validation carries the same risk for time series unless it's done with care (Bergmeir & Benítez, 2012). Across 17 fields, Kapoor and Narayanan (2023) found leakage affecting 294 published papers.

Figure 10. Top: a shuffled split scatters test years (red) through the record, so the model trains on years that come after the ones it's tested on. Bottom: the temporal split used in the South Asia earthquake severity project, where every validation and test event is later than every training event.

5.2 How the analysis works

Figure 11. seismic-linter's pipeline. Notebooks are flattened to code cells, each file is parsed once and cached by content hash, and files are analysed in parallel processes.

The linter walks Python's abstract syntax tree and reasons about context. A call to .mean() is fine if it follows groupby, rolling, expanding or resample in the same chain, because those carry temporal boundaries; on a bare DataFrame, it gets flagged.

Rule	Severity	Flags	Fix
T001	Warning	Global mean / std / min / max without a temporal predecessor	Rolling or expanding statistics, or statistics fitted on train only
T002	Info	`.fit()` on generic names such as `df`, `data`, `X`	Split first, fit on `X_train`
T003	Error	`train_test_split` without a literal `shuffle=False`	`shuffle=False` or a time-based split

Here's the real output of version 0.2.0 on an eight-line script that makes all three mistakes:

$ seismic-linter lintdemo/
File: lintdemo/train.py
  ❌ [Line 6] T001: Global mean() may cause temporal leakage.
  ❌ [Line 6] T001: Global std() may cause temporal leakage.
  ℹ️ [Line 7] T002: Model fit() called on potential non-training data 'df'.
  ❌ [Line 8] T003: train_test_split used with shuffle=True on time series

Found 4 potential violation(s).        # exit code 1

A non-zero exit code is what turns this into a gate: it can run as a pre-commit hook or a GitHub Action, and fail-on / ignore in pyproject.toml control which rules block a merge. Deliberate exceptions get an inline # seismic-linter: ignore T001.

5.3 Runtime guards and limits

Static analysis can't see data, so the package also ships two runtime checks: a @verify_monotonicity(time_column="time") decorator that rejects unsorted catalogues, and validate_split_integrity(train, test, time_column="time"), which raises TemporalCausalityError if any test timestamp is earlier than a training timestamp.

The static rules are heuristics, and they have limits. T002 decides from variable names, so a leaky fit on a variable called train_df gets through. T001 doesn't yet recognise ewm or custom wrappers as safe, so those produce false positives. T003 only accepts a literal shuffle=False, so a variable holding False still gets reported. A proper fix would be data-flow analysis that follows which rows reach each fit call. For a linter whose job is to be run on every commit, false positives you can suppress are a better failure mode than silent misses.

6. Datasets

Dataset	Provider	Used here for	Access
Synthetic velocity steps	Generated with torch-friction	Figures 2, 3, 5 (known ground truth, σ = 10⁻⁴ noise)	This post
Synthetic seismograms	Generated with NumPy	Figures 8–9 (known P and S onsets)	This post
Synthetic shot gather	Generated with NumPy	Figure 6 (known reflection and ground-roll components)	This post
Laboratory stick-slip (biaxial shear, Penn State)	Rouet-Leduc et al. (2017); LANL Earthquake Prediction on Kaggle	Not used yet: the natural real-data target for torch-friction inversion	doi.org/10.1002/2017GL074677
STanford EArthquake Dataset (STEAD)	Mousavi et al. (2019)	Not used yet: labelled P/S picks for benchmarking fast-trigger on real waveforms	doi.org/10.1109/ACCESS.2019.2947848

I've used synthetics wherever the point was to test an algorithm, because only synthetic data come with exact ground truth. The two "not used yet" rows are where each tool should go next.

7. Reproducibility notes

Friction figures use torch-friction from PyPI (PyTorch 2.14, float64, CPU). The Setup A and B scripts follow examples/inverse_problem_demo.py, with the changes described in section 2.5.
STA/LTA figures use an exact NumPy port of fast-trigger's recursion (same coefficients, same first-sample initialisation), because the package isn't on PyPI yet, and ObsPy 1.5.1 for the x² comparison. Seeds are fixed.
The f-k figure uses a NumPy port of Basalt's sigmoid mask. The C++ kernels need x86-64 with AVX2, so they weren't run for this post.

You can backpropagate through physics. A friction law can be a layer in a neural network.

References

Allen, R. V. (1978). Automatic earthquake recognition and timing from single traces. Bulletin of the Seismological Society of America, 68(5), 1521–1532. https://doi.org/10.1785/BSSA0680051521
Bergmeir, C., & Benítez, J. M. (2012). On the use of cross-validation for time series predictor evaluation. Information Sciences, 191, 192–213. https://doi.org/10.1016/j.ins.2011.12.028
Beyreuther, M., Barsch, R., Krischer, L., Megies, T., Behr, Y., & Wassermann, J. (2010). ObsPy: A Python toolbox for seismology. Seismological Research Letters, 81(3), 530–533. https://doi.org/10.1785/gssrl.81.3.530
Bhattacharya, P., Rubin, A. M., Bayart, E., Savage, H. M., & Marone, C. (2015). Critical evaluation of state evolution laws in rate and state friction: Fitting large velocity steps in simulated fault gouge with time-dependent healing. Journal of Geophysical Research: Solid Earth, 120(9), 6365–6385. https://doi.org/10.1002/2015JB012437
Borate, P., Rivière, J., Marty, S., Marone, C., Kifer, D., & Shokouhi, P. (2024). Physics informed neural network can retrieve rate and state friction parameters from acoustic monitoring of laboratory stick-slip experiments. Scientific Reports, 14, Article 24624. https://doi.org/10.1038/s41598-024-75826-y
Chen, R. T. Q., Rubanova, Y., Bettencourt, J., & Duvenaud, D. (2018). Neural ordinary differential equations. In Advances in Neural Information Processing Systems 31. https://arxiv.org/abs/1806.07366
Cooley, J. W., & Tukey, J. W. (1965). An algorithm for the machine calculation of complex Fourier series. Mathematics of Computation, 19(90), 297–301. https://doi.org/10.1090/S0025-5718-1965-0178586-1
Dieterich, J. H. (1979). Modeling of rock friction: 1. Experimental results and constitutive equations. Journal of Geophysical Research: Solid Earth, 84(B5), 2161–2168. https://doi.org/10.1029/JB084iB05p02161
Embree, P., Burg, J. P., & Backus, M. M. (1963). Wide-band velocity filtering: The pie-slice process. Geophysics, 28(6), 948–974. https://doi.org/10.1190/1.1439310
Frigo, M., & Johnson, S. G. (2005). The design and implementation of FFTW3. Proceedings of the IEEE, 93(2), 216–231. https://doi.org/10.1109/JPROC.2004.840301
Frigo, M., Leiserson, C. E., Prokop, H., & Ramachandran, S. (1999). Cache-oblivious algorithms. In 40th Annual Symposium on Foundations of Computer Science (pp. 285–297). IEEE. https://doi.org/10.1109/SFFCS.1999.814600
Hairer, E., & Wanner, G. (1996). Solving ordinary differential equations II: Stiff and differential-algebraic problems (2nd ed.). Springer. https://doi.org/10.1007/978-3-642-05221-7
Kapoor, S., & Narayanan, A. (2023). Leakage and the reproducibility crisis in machine-learning-based science. Patterns, 4(9), Article 100804. https://doi.org/10.1016/j.patter.2023.100804
Karniadakis, G. E., Kevrekidis, I. G., Lu, L., Perdikaris, P., Wang, S., & Yang, L. (2021). Physics-informed machine learning. Nature Reviews Physics, 3(6), 422–440. https://doi.org/10.1038/s42254-021-00314-5
Kaufman, S., Rosset, S., Perlich, C., & Stitelman, O. (2012). Leakage in data mining: Formulation, detection, and avoidance. ACM Transactions on Knowledge Discovery from Data, 6(4), Article 15. https://doi.org/10.1145/2382577.2382579
Marone, C. (1998). Laboratory-derived friction laws and their application to seismic faulting. Annual Review of Earth and Planetary Sciences, 26, 643–696. https://doi.org/10.1146/annurev.earth.26.1.643
Mignan, A., & Broccardo, M. (2019). One neuron versus deep learning in aftershock prediction. Nature, 574(7776), E1–E3. https://doi.org/10.1038/s41586-019-1582-8
Mignan, A., & Broccardo, M. (2020). Neural network applications in earthquake prediction (1994–2019): Meta-analytic and statistical insights on their limitations. Seismological Research Letters, 91(4), 2330–2342. https://doi.org/10.1785/0220200021
Mousavi, S. M., & Beroza, G. C. (2022). Deep-learning seismology. Science, 377(6607), Article eabm4470. https://doi.org/10.1126/science.abm4470
Mousavi, S. M., Sheng, Y., Zhu, W., & Beroza, G. C. (2019). STanford EArthquake Dataset (STEAD): A global data set of seismic signals for AI. IEEE Access, 7, 179464–179476. https://doi.org/10.1109/ACCESS.2019.2947848
Paszke, A., Gross, S., Massa, F., Lerer, A., Bradbury, J., Chanan, G., Killeen, T., Lin, Z., Gimelshein, N., Antiga, L., Desmaison, A., Köpf, A., Yang, E., DeVito, Z., Raison, M., Tejani, A., Chilamkurthy, S., Steiner, B., Fang, L., … Chintala, S. (2019). PyTorch: An imperative style, high-performance deep learning library. In Advances in Neural Information Processing Systems 32 (pp. 8024–8035). https://arxiv.org/abs/1912.01703
Raissi, M., Perdikaris, P., & Karniadakis, G. E. (2019). Physics-informed neural networks: A deep learning framework for solving forward and inverse problems involving nonlinear partial differential equations. Journal of Computational Physics, 378, 686–707. https://doi.org/10.1016/j.jcp.2018.10.045
Rice, J. R., & Ruina, A. L. (1983). Stability of steady frictional slipping. Journal of Applied Mechanics, 50(2), 343–349. https://doi.org/10.1115/1.3167042
Rouet-Leduc, B., Hulbert, C., Lubbers, N., Barros, K., Humphreys, C. J., & Johnson, P. A. (2017). Machine learning predicts laboratory earthquakes. Geophysical Research Letters, 44(18), 9276–9282. https://doi.org/10.1002/2017GL074677
Rucker, C., & Erickson, B. A. (2024). Physics-informed deep learning of rate-and-state fault friction. Computer Methods in Applied Mechanics and Engineering, 430, Article 117211. https://doi.org/10.1016/j.cma.2024.117211
Ruina, A. (1983). Slip instability and state variable friction laws. Journal of Geophysical Research: Solid Earth, 88(B12), 10359–10370. https://doi.org/10.1029/JB088iB12p10359
Scholz, C. H. (1998). Earthquakes and friction laws. Nature, 391(6662), 37–42. https://doi.org/10.1038/34097
SEG Technical Standards Committee. (2017). SEG-Y_r2.0: SEG-Y revision 2.0 data exchange format (R. Hagelund & S. A. Levin, Eds.). Society of Exploration Geophysicists. https://seg.org/wp-content/uploads/2025/11/seg_y_rev2_0_mar2017.pdf
Singh, A. (2026). torch-friction (Version 0.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.18366445
Trnkoczy, A. (2012). Understanding and parameter setting of STA/LTA trigger algorithm. In P. Bormann (Ed.), New manual of seismological observatory practice 2 (NMSOP-2). Deutsches GeoForschungsZentrum GFZ. https://doi.org/10.2312/GFZ.NMSOP-2_IS_8.1
Withers, M., Aster, R., Young, C., Beiriger, J., Harris, M., Moore, S., & Trujillo, J. (1998). A comparison of select trigger algorithms for automated global seismic phase and event detection. Bulletin of the Seismological Society of America, 88(1), 95–106. https://doi.org/10.1785/BSSA0880010095
Yilmaz, Ö. (2001). Seismic data analysis: Processing, inversion, and interpretation of seismic data (2nd ed.). Society of Exploration Geophysicists. https://doi.org/10.1190/1.9781560801580

Code & archives

• torch-friction (Zenodo DOI)

• Basalt (Zenodo DOI)

• fast-trigger

• seismic-linter (PyPI)

This article was first published at amansinghnp.com.

The model had memorised the map

Aman Singh — Thu, 22 Oct 2026 07:36:04 +0000

Originally published at amansinghnp.com.

The depth classifier in my Kaggle notebook looked accurate. It tells deep earthquakes from shallow ones using only where and when they happened, and on a random 80/20 split it scored 0.856 accuracy and an AUC of 0.909. When I tested it on regions it had never seen, holding out whole 10° cells, the AUC fell to 0.695, towards the 0.5 of chance. Accuracy dropped to 0.801, level with always answering "shallow", and it found one deep event in six. It had learned where deep earthquakes have already happened, not how to find a subduction zone.

The notebook covers 23,409 significant earthquakes (magnitude 5.5 and above) from 1965 to 2016 [1] and runs in 47 seconds. Its summary made three claims. This report keeps two things apart: Part 1 is what the original notebook did and showed, and Part 2 is the 2026 re-check, where I rebuilt the event table from the notebook's own output and tested each claim. The three results, each linked to its section:

The notebook claimed	The re-check found	Key number
Events above M8.0 release "the vast majority" of the energy	Holds, but loosely. Sixteen events released half the energy; the 40 events of M8.0 or more released 60.2%.	16 events, 50%
Aftershocks decay "consistent with Omori's Law"	Never tested: the notebook plots the Sumatra sequence and fits nothing. An Omori–Utsu fit I ran afterwards gives ordinary decay exponents.	p = 0.90 and 1.16
The classifier can "accurately distinguish" deep from shallow	It memorised the map. On regions it had never seen, it falls towards chance.	AUC 0.909 → 0.695

Part 1: the original notebook

This part is what the notebook did and printed. The only thing I've added is the region names in the hotspot table.

The data is the USGS "Significant Earthquakes, 1965–2016" file on Kaggle. Cleaning joins the date and time columns into a timestamp, coerces coordinates, depth and magnitude to numbers, and drops rows missing any of them, leaving 23,409 events. Each event also gets an energy estimate. The rest of the notebook is six sections:

an animated Plotly map, one frame per year, with bubble size set to magnitude cubed;
cumulative energy over time, with the three largest events annotated;
the aftershock timeline of the largest event, 2004 Sumatra (M9.1), within 500 km and 30 days;
a 5° × 5° grid ranked by an intensity score, drawn as a density map with the PB2002 plate boundaries on top [2];
an explorer filtered by minimum magnitude and a deep-focus switch (below 300 km);
a random forest that classifies events as deep (70 km or more) or shallow from latitude, longitude, year and month.

Energy over time

Energy comes from the Gutenberg–Richter energy–magnitude relation [3]:

log10 E = 1.5 M + 4.8 (E in joules)

Each step of one magnitude unit is about 32 times the energy, so a catalogue that is mostly M5.5 to M6 will have its energy budget set by a handful of great earthquakes. The cumulative curve shows it: a slow ramp for 40 years, then three steps.

Figure 1, from the notebook. Cumulative energy release. The 2004, 2010 and 2011 earthquakes together account for a third of the 52-year total.

The notebook's markdown says the top 20 events account for "a disproportionate share" but never prints the share. Its summary goes further and says events above M8.0 account for "the vast majority" of the energy.

The Sumatra aftershocks

The notebook plots the Sumatra sequence within 500 km and 30 days of the mainshock and stops there. Its summary says aftershock sequences "exhibit predictable decay patterns consistent with Omori's Law".

Hotspots

Events are binned into 5° cells, and each cell gets a score of ln(1 + count) × maximum magnitude. The top ten:

Cell (lat, lon)	Region	Events	Max M	Mean depth (km)
35, 140	Japan Trench, Honshu	587	9.1	33
−10, 150	New Britain, Papua New Guinea	654	8.0	48
−15, 165	Vanuatu	594	8.0	67
−20, −175	Tonga	534	8.1	52
−25, −180	Fiji deep zone	583	7.8	328
40, 145	Off Hokkaido	388	8.3	43
0, 125	Molucca Sea	558	7.7	58
0, 95	Northern Sumatra	193	9.1	39
−30, −180	Kermadec	366	8.0	63
45, 150	Kuril Islands	275	8.3	45

All ten are subduction zones on the western Pacific or in Indonesia. The notebook printed only coordinates; the region names are mine. The Fiji cell's mean depth of 328 km is the one place in the top ten where deep-focus earthquakes dominate.

The depth classifier

The label is deep if the focal depth is 70 km or more (the markdown says "greater than 70"; the code uses ≥). 20.3% of events are deep. Features are latitude, longitude, year and month, with depth and magnitude deliberately left out. The model is a scikit-learn random forest [6] with 100 trees capped at depth 10, trained on a random 80/20 split. The hypothesis in the notebook was that deep earthquakes only happen at subduction zones, so location alone should predict depth, and the model would act as "a proxy for identifying tectonic boundaries without explicit plate data". This is what it reported:

Class	Precision	Recall	F1	Support
Shallow	0.852	0.990	0.916	3,709
Deep	0.901	0.346	0.500	973
Accuracy	0.856	4,682

On that basis the notebook's summary says the classifier can "accurately distinguish" the two regimes.

Figure 2, from the notebook. Feature importance. Year and month together take 8%, which should be close to zero for a question about plate geometry.

Part 2: the 2026 re-check

For the re-check I rebuilt the event table from the notebook's own output and tested each claim against it. Every table and chart from here on is mine, not the notebook's.

The first thing I found was a missing cleaning step. The source file has a Type column that separates earthquakes from nuclear explosions, and the notebook never reads it. At least 125 events sit on the Semipalatinsk, Novaya Zemlya and Nevada test sites at depths of 0 to 6 km. They barely move the energy totals, but they are in the hotspot counts and the classifier's shallow class.

Energy: the claim holds, loosely

Here is the share the notebook never printed:

Largest events	Share of total energy
1 (Sumatra, 2004)	14.1%
3	33.1%
5	39.1%
16	50.0%
20	53.0%
100	70.6%

By magnitude band the imbalance is plainer still. Half the energy came from 0.07% of the events.

Figure 3, from the re-check. Where the energy is. Six events of M8.5 or above, 0.03% of the catalogue, radiated 41.6% of the energy. The 16,054 events below M6.0 radiated 1.7%.

So the claim that events above M8.0 account for "the vast majority" of the energy is directionally right but loose: 40 events, 0.17% of the catalogue, released 60.2%. That is a majority, not a vast one, because the M7.5 to M7.9 band alone adds another 20%.

The notebook's animated map works against this finding. Bubble area is set to magnitude cubed, so an M9.1 is drawn about 4.5 times the size of an M5.5, when it released roughly 250,000 times the energy. On the map, the Sumatra earthquake looks like a slightly larger dot.

Aftershocks: the claim was never tested

Within the notebook's window of 500 km and 30 days there are 45 aftershocks of M5.5 or more, the largest M6.7, and 22 of them fall in the first day. That is what Omori decay looks like, but a scatter plot is not a test.

The window is also small for this earthquake. The Sumatra–Andaman rupture ran roughly 1,300 km north from the epicentre [4], so a 500 km circle around the epicentre misses much of it. Widening to 1,500 km roughly doubles the count, to 95.

I fitted the Omori–Utsu law, n(t) = K / (t + c)^p [5], by maximum likelihood over a grid, to both M9.1 events in the catalogue, using 90 days and 1,000 km:

Mainshock	Aftershocks (M5.5+)	In first day	p	c (days)
Sumatra, 26 Dec 2004	114	40	0.90	0.035
Tohoku, 11 Mar 2011	220	134	1.16	0.041

Both exponents sit in the usual range of roughly 0.9 to 1.5 [5], so the claim survives. The caveats are real, though. With only M5.5+ events, the counts are small. Catalogues miss many aftershocks in the first hours, when waveforms overlap, which inflates c. And I report no uncertainty on p. This is a check, not a result.

Hotspots: what the score rewards

Two things about the notebook's score are worth knowing. Maximum magnitude carries as much weight as frequency, which is how northern Sumatra gets into the top ten with 193 events. And the grid splits single systems: Tonga–Kermadec takes three cells and Japan–Kuril three more, so the table understates how concentrated seismicity is.

The classifier: it memorised the map

Start with the numbers the notebook reported. Always answering "shallow" scores 0.792 on the same test set, so the model adds six points. It caught 337 of 973 deep events and missed 636. When it does say deep it is usually right (37 false alarms), which means the default 0.5 threshold is the main problem. The ranking is decent: AUC 0.909. Lowering the threshold to 0.3 gives recall 0.66 at precision 0.74; at 0.2, recall 0.88 at precision 0.50. Letting the trees grow past depth 10, on latitude and longitude alone, lifts the AUC to 0.945 and recall at 0.5 to 0.73.

The bigger problem is the split. A random split scatters every cluster across training and test sets. Aftershocks of the same mainshock, and the hundreds of events on the same slab, end up on both sides, so to label a test event the forest only has to remember what happened a few kilometres away. That tests interpolation within known seismic zones. It does not test the hypothesis, which is about recognising tectonic structure.

To test that, I grouped events into 10° cells and ran 5-fold cross-validation with whole cells held out, so every test event comes from a region the model has not seen [7]. I also ran a time split, training on 1965–2005 and testing on 2006–2016.

Figure 4, from the re-check. The same model, three ways of testing it. It holds up when tested on later years and falls towards chance when tested on places it has never seen.

Evaluation	AUC	Deep recall at 0.5	Accuracy	All-shallow baseline
Random 80/20 (notebook)	0.909	0.346	0.856	0.792
Time split, test 2006–2016	0.906	0.316	0.877	0.827
Unseen 10° cells, 5-fold	0.695 ± 0.082	0.168	0.801	≈ 0.80

The time split barely moves anything, because subduction zones do not move in fifty years. Held-out regions are different: accuracy falls to the baseline and the model finds one deep event in six. What it learned is a lookup table of where deep earthquakes have already happened. That is a fair thing to know, but it is not a way to find plate boundaries without plate data, and a random split could not have told me so.

What I would change

Filter to Type == "Earthquake" before anything else.
Print the energy shares instead of describing them, and say "majority" where the number is 60%.
Scale map bubbles by energy, or state on the chart that they are not.
Fit Omori–Utsu with a completeness cut and confidence intervals, or drop the claim from the summary.
Evaluate the classifier with spatially grouped folds, report recall and AUC next to a baseline, and drop year and month.
Recast the classifier's goal: predict depth for new events in known zones, which it can do, rather than find boundaries, which it cannot.
Use one magnitude type for energy. The catalogue mixes Mw, Ms and mb, and body-wave magnitudes saturate for large events.

A model can look accurate just by memorising where things happen. Test it somewhere it hasn't seen.

References

U.S. Geological Survey. Significant Earthquakes, 1965–2016. Kaggle dataset.
Bird, P. (2003). An updated digital model of plate boundaries. Geochemistry, Geophysics, Geosystems, 4(3), 1027. doi:10.1029/2001GC000252.
Gutenberg, B. and Richter, C. F. (1956). Magnitude and energy of earthquakes. Annali di Geofisica, 9, 1–15.
Lay, T. et al. (2005). The great Sumatra–Andaman earthquake of 26 December 2004. Science, 308(5725), 1127–1133. doi:10.1126/science.1112250.
Utsu, T., Ogata, Y. and Matsu'ura, R. S. (1995). The centenary of the Omori formula for a decay law of aftershock activity. Journal of Physics of the Earth, 43(1), 1–33. doi:10.4294/jpe1952.43.1.
Pedregosa, F. et al. (2011). Scikit-learn: Machine Learning in Python. Journal of Machine Learning Research, 12, 2825–2830.
Roberts, D. R. et al. (2017). Cross-validation strategies for data with temporal, spatial, hierarchical, or phylogenetic structure. Ecography, 40(8), 913–929. doi:10.1111/ecog.02881.

Code & data

• Spatiotemporal Analysis of Global Seismicity (Kaggle notebook, Apache 2.0)

• Significant Earthquakes, 1965–2016 (USGS, via Kaggle)

This article was first published at amansinghnp.com.

Reading handwritten postcodes

Aman Singh — Thu, 22 Oct 2026 07:35:49 +0000

Originally published at amansinghnp.com.

LiPi is a web app that reads the postcode on a handwritten postcard. You upload a photo or hold a card up to a webcam, and LiPi straightens the image, works out which way up it is, finds the ten regions of a postcard with a fine-tuned YOLO11s detector, reads the postcode with OCR and looks up the matching NSW suburb. We connected it to a robotic arm, so the card can go from photograph to tray.

Real mail is full of personal details, so we didn't train on it. The training set is 1,200 synthetic postcards generated in Python, plus 110 real handwritten ones written by volunteers.

1. A handwritten card photographed through the app's camera tab.

2. The same card found, straightened and boxed region by region, with the postcode read as 2450.

3. With the arm connected, the postcode decides which tray the card goes in (section 9).

On validation, the detector reached an mAP50 of 0.995 and an mAP50-95 of about 0.88. Both numbers are for region detection: finding and labelling the ten postcard regions on the 124-image validation split (the dataset splits 1,066 / 124 / 120). They don't tell you how often LiPi reads the postcode correctly. We haven't measured end-to-end postcode reading accuracy.

1,310 postcard images, 110 of them real

10 annotated classes

0.995 validation mAP50, region detection (124 images)

0.88 validation mAP50-95, region detection (124 images)

~8 min training on one T4 GPU

19.2 MB model size

Two teammates and I built it, then showed it at the AI Showcase at UTS Tech Festival 2026, where it won the People's Choice Award. The app is live on Hugging Face Spaces if you'd like to try it with your own postcard.

Our showcase video, published on the UTS AI Showcase 2026 channel.

1. Introduction

1.1 The problem

Automated mail sorting already exists, but it's built for large postal operators with industrial sorting lines. Smaller organisations that receive mail still sort it by hand.

Reading a handwritten postcode from a photo is much harder than recognising digits in a clean dataset. The postcode sits inside a full handwritten address block. People photograph cards at an angle or in poor light, the card may be tilted or partly covered [1], and handwriting varies widely from writer to writer [2]. Our goal was a lightweight system that can take an ordinary photo of a postcard, find the postcode and read the correct four-digit NSW postcode despite all of that.

Finding where the postcode sits is a problem in its own right: earlier work used a deep CNN to detect the pincode for postal automation [5]. LiPi does the same detection step with YOLO11s before it reads the digits.

1.2 Motivation

We had two reasons. The practical one: university campuses, apartment complexes and community organisations handle a lot of mail but can't justify sorting infrastructure, so we wanted something that runs on a standard laptop and cuts down manual effort and sorting mistakes. The research one: could a model trained almost entirely on synthetic postcards hold up on messy real-world photos? Using real public mail as a dataset was never an option because of privacy, so the whole project depended on synthetic data being good enough.

1.3 Where it fits

In the app, you upload a photo or snap one with your camera and get back the detected postcode, its NSW suburb and the location of every other region on the card, in seconds. The obvious next step is a mailroom workflow where a camera scans incoming postcards and routes each one to the right tray, which is the job of the robotic arm we built (see section 9).

2. Dataset

The dataset was built in three stages and holds 1,310 postcard images: 1,200 synthetic and 110 real. Prior work shows that combining synthetic and real data improves generalisation in handwritten document recognition [3], and that's the approach we followed. It gave us a large, varied, labelled set without collecting hundreds of real home addresses.

1,310 postcard images in total.

2.1 Postcard templates

We visited several Australia Post branches and photographed blank NSW Air Mail postcards under different conditions. Eight real templates became the base for everything we generated.

2.2 Synthetic generation

Following the approach of synthetic OCR dataset generators [4], we built a generation pipeline in Python with Pillow that produced 1,200 postcards. Each one has handwritten-style content: a recipient address, a message and a date, rendered in handwriting fonts with random variation in character size, baseline and rotation. Stamps and postmarks are generated procedurally with varying placement and appearance, and the ink changes between blue ballpoint, black ink, dark grey pencil, green ink, dark red-brown ink and marker-style strokes.

Getting there took a lot of experimenting. Before settling on the final Pillow compositor, we tried compositing and overlaying augmented real postcard photos, and generating images with Nano Banana 2 and GPT-5.

A contact sheet of synthetic postcards with their annotations.

2.3 Real handwritten postcards

To cover genuine handwriting, eight people first wrote 84 postcards, which were photographed and annotated by hand in CVAT.ai using the YOLO format. We later wrote and labelled 26 more, bringing the real set to 110. The real samples went into the training and validation splits, while the original test set stayed unchanged so results remained comparable.

A real handwritten postcard with its YOLO annotations.

2.4 Classes and splits

Every postcard is annotated with ten classes: brand_logo, barcode, service_title, stamp_imprint, publisher_imprint, date_note, message_block, address_block, postcode_line and postmark. The final split is 1,066 training, 124 validation and 120 test images, roughly 80/10/10.

3. System design

3.1 Pipeline overview

LiPi runs every image through the same seven stages.

The seven stages every postcard goes through.

The app has two modes. Default uses fixed, recommended settings: the postcard detector v2 weights, a 0.25 confidence threshold, hybrid rectification and EasyOCR. Advanced exposes the controls: model weights, confidence threshold, rectifier strategy, manual rotation and OCR backend. Before anything runs, the app checks that the model weights exist. The full flowchart from our report shows every branch.

The full code flowchart, including every fallback path. Click to open it full size.

3.2 Rectification

The first job is turning a photo taken at an angle into a flat, front-facing postcard. In Hybrid or Learned mode, a DocAligner model (FastViT-SA24 heatmap regression) predicts the four corners of the card, and OpenCV's getPerspectiveTransform and warpPerspective warp it flat.

If the learned result fails a geometry check (a minimum area fraction of 0.18 plus a rectangularity score), a contour-based fallback takes over. It applies CLAHE contrast enhancement, bilateral denoising, Gaussian blur, several Canny edge thresholds, adaptive thresholding and morphological gradients to build candidate edge masks, then evaluates polygon approximations and minimum-area rectangles to find the best quad. If nothing valid is found, the original image is used. After warping, any leftover skew is estimated with a weighted Hough line analysis and corrected if it's more than 0.35 degrees, and the image is normalised to landscape.

3.3 Orientation

A flat postcard can still be upside down. Rather than train a separate orientation model, we run YOLO11s at all four cardinal rotations and score each run.

The postcode and address regions count for more, because they matter most downstream.

3.4 Detection

The correctly oriented image goes to YOLO11s at a confidence threshold of 0.25, which returns bounding boxes and confidences for the ten postcard classes.

3.5 Text extraction

OCR candidates come from the detected postcode_line crop (with about 10% padding) plus up to five sub-crops of the address_block. Each crop is upscaled 2.5× with bicubic interpolation and cleaned up with CLAHE and a Gaussian blur, then read in four variants: CLAHE enhanced, Otsu binary, adaptive threshold and inverted Otsu. Every result is scored on confidence, whether it looks like a valid postcode, and length, and the best one wins.

There are four OCR backends: EasyOCR, Tesseract, a Gemini or Groq vision-language model, or EasyOCR first with the VLM called only when EasyOCR finds no postcode. We evaluated Tesseract in depth against the other options, which shaped the final choice.

3.6 Suburb lookup and output

The postcode is matched against the Zippopotam.us API to get the NSW suburb. Results appear across three tabs: a visual check of every stage, the postcode with its suburb and raw OCR text, and a debug view with the full detections table and preprocessing and OCR logs.

4. Model

4.1 YOLO11s

The detector is YOLO11s, the small variant of Ultralytics' YOLO11: a single-stage, anchor-free object detector with 182 layers, 9.4 million parameters and 21.6 GFLOPs. The backbone uses C3k2 blocks with SPPF and C2PSA attention modules, and the detection head predicts boxes at three feature scales. We started from COCO-pretrained weights and fine-tuned on the postcard dataset.

YOLO11s as used in LiPi, from input image to the three-scale detection head.

4.2 Why YOLO11s

We also tried Faster R-CNN and SSD using TorchVision. YOLO11s gave the best trade-off between speed and accuracy, and at 19.2 MB it runs comfortably on ordinary hardware with no specialised infrastructure. Along the way, we trained an early, smaller YOLO model that helped validate the detection approach, and tested on a smaller preview dataset and an augmented variant (tilts, blur, background clutter) before scaling up to the full 1,200 images.

4.3 Training setup

Setting	Value
Base model	YOLO11s, pretrained on COCO
Image size	960 × 960
Batch size	8
Epochs	75
Optimiser	AdamW (lr 0.000714, momentum 0.9)
Weight decay	0.0005
Mixed precision	AMP
Dataset	1,200 synthetic + 110 real handwritten
Workers	2
Device	Tesla T4 GPU (Kaggle)
Training time	about 8 minutes (0.135 hours)

5. Results

Everything in this section measures region detection: how well YOLO11s finds and labels the ten postcard regions on the 124-image validation split. It does not measure whether LiPi reads the postcode correctly. We didn't build an exact-match benchmark for end-to-end postcode reading, so that accuracy is unknown (see section 7).

Across all classes, precision was 0.999, recall 1, mAP50 0.995 and mAP50-95 0.88. Every class reached an mAP50 of 0.995. On the stricter mAP50-95, eight classes scored 0.995 and two fell below: postcode_line at 0.93 and date_note at 0.896. F1 peaks at 0.97 at a confidence of about 0.375.

The confusion matrix is almost perfectly diagonal. The one weak spot is date_note, with a normalised recall of 0.67 and some confusion with the background. That's expected: date notes are the smallest and most variable region on a postcard, and none of our real handwritten postcards include one.

The full per-class table and chart, the confusion matrices, the training, F1 and precision-recall curves, and the validation prediction grids are in Appendix A.1 to A.4.

6. The app

LiPi is built in Streamlit and deployed as a public Hugging Face Space, so anyone can try it in a browser without setting anything up.

6.1 Default and Advanced modes

A radio button in the sidebar switches modes. Default shows a summary of the recommended settings and needs no configuration. Advanced exposes the full pipeline: a weights selector (postcard detector v1 or v2, base YOLO11s, base YOLO26n or a custom path), the confidence threshold, the rectifier mode (Hybrid, Learned, Contour or Off), the learned rectifier model, manual rotation, the OCR backend and the postcode lookup country. Both sidebars are shown in Appendix A.5.

6.2 Upload or camera

The main area takes an image through two tabs: drag and drop or browse for a PNG, JPG, JPEG or WEBP file, or turn on the webcam and take a photo. The camera tab is the first image at the top of this report, and the upload tab is in Appendix A.5.

6.3 Reading the results

Once an image is in, four tiles show whether the postcard was rectified, how many regions YOLO found, the predicted postcode and the chosen orientation. Below them, the visual check tab shows a two by two grid of the original image, the detected postcard boundary, the straightened input and the YOLO boxes. The second image at the top of this report is a complete result.

The "Try it yourself" panel from our showcase poster.

7. Limitations

Mostly synthetic data. Apart from the 110 real postcards, everything is generated, which limits how well the model generalises to irregular handwriting, damaged cards, unusual stamp placement or non-standard layouts.
A weak class. None of the real handwritten postcards include a date note, which is why date_note has the lowest normalised recall (0.67) and mAP50-95 (0.896).
OCR on hard crops. Accuracy drops on very low-resolution crops and heavily stylised handwriting. The Gemini or Groq VLM fallback helps, but it can still fail on difficult perspectives.
Rectifier failures. The contour rectifier sometimes fails on postcards photographed at extreme angles or against cluttered, high-contrast backgrounds.
Scope. LiPi only supports four-digit Australian postcodes and a fixed set of ten regions.
No OCR benchmark. We measured region detection, not end-to-end postcode reading. Without an exact-match table, we can't say how often LiPi reads the postcode correctly.

A failure case: a cluttered background confuses the rectifier.

8. Showcase and People's Choice

On 24 June we set up at stand 1 of the AI Showcase with the arm, a stack of postcards and the demo running on the big screen.

Our mini vlog from building LiPi Sort and showcase day.

At the Tech Fest awards night, LiPi won the AI Showcase People's Choice Award from the UTS Faculty of Engineering and IT.

9. What's next

On its own, the app turns sorting into three steps: click, read, place. We connected it to a robotic arm that takes the physical step too, which brings it down to one: place the card, and the arm puts it in the right tray.

Beyond that, the report points to three pieces of future work: expanding the real handwritten dataset to cover all ten classes, fine-tuning a dedicated OCR model for handwritten postcodes, and deploying LiPi as an API or on an edge device like a Raspberry Pi so it can slot into a real mailroom.

The bigger takeaway is that synthetic data generation is a viable, privacy-preserving way to build postal document datasets, and that a modern single-stage detector can reach near-perfect localisation on structured documents with modest training resources, at least on our validation split.

Acknowledgements

Thank you to Associate Professor Nabin Sharma, who taught the subject LiPi was built for and guided the project along the way. His work on detecting pincodes with deep CNNs for postal automation [5] is close to what LiPi does.

Appendix

The full diagnostics behind section 5, and the app screenshots from section 6. All detection metrics here are on the 124-image validation split and measure region detection, not postcode reading.

A.1 Per-class detection metrics

Validation performance per class. These metrics measure how well the model locates and classifies regions.

Class	Precision	Recall	mAP50	mAP50-95
All classes	0.999	1	0.995	0.88
brand_logo	0.999	1	0.995	0.995
barcode	0.998	1	0.995	0.995
service_title	1	1	0.995	0.995
stamp_imprint	1	1	0.995	0.995
publisher_imprint	0.999	1	0.995	0.995
date_note	0.999	1	0.995	0.896
message_block	0.999	1	0.995	0.995
address_block	0.999	1	0.995	0.995
postcode_line	0.999	1	0.995	0.93
postmark	1	1	0.995	0.995

Per-class mAP50-95 on validation. Only date_note and postcode_line fall below 0.995.

A.2 Confusion matrices

Both matrices are almost perfectly diagonal. The exception is date_note, at 0.67 on the normalised matrix.

Confusion matrix.

Normalised confusion matrix.

A.3 Training curves

Box, classification and distribution focal losses fall steadily on both training and validation, while precision, recall and mAP climb and level off. Across all classes, F1 peaks at 0.97 at a confidence of about 0.375. On the precision-recall curve, every class reaches an mAP50 of 0.995, with date_note losing some precision at low confidence thresholds because of its size.

Training and validation losses and metrics.

F1 against confidence.

Precision against recall.

A.4 Validation predictions

Side by side, the model's predictions on validation postcards line up closely with the hand-labelled ground truth.

Ground-truth labels.

Model predictions.

A.5 App screenshots

The two sidebar modes from section 6.1 and the upload tab from section 6.2.

Default mode.

Advanced mode.

Uploading a file.

When the real data is private, synthetic postcards can still teach a detector to find the postcode on real handwritten cards.

References

Ngu, E. O. Y., & Ali, S. H. A. (2017). Development of handwriting recognition system in postal service sector. jtec.utem.edu.my
Blumenstein, M., & Verma, B. (1998). A Neural Network for Real-World Postal Address Recognition. In Soft Computing in Engineering Design and Manufacturing (pp. 79 to 83). doi.org/10.1007/978-1-4471-0427-8_9
Garrido-Munoz, C., & Calvo-Zaragoza, J. On the Generalization of Handwritten Text Recognition Models. CVPR 2025. openaccess.thecvf.com
Malik, H. N., Shafi, K. M., & Reshi, T. A. (2026). synthocr-gen: A synthetic OCR dataset generator for low-resource languages. arXiv. doi.org/10.48550/arxiv.2601.16113
Sharma, N., Sengupta, A., Sharma, R., Pal, U., & Blumenstein, M. (2017). Pincode detection using deep CNN for postal automation. In 2017 International Conference on Image and Vision Computing New Zealand (IVCNZ) (pp. 1 to 6). IEEE. doi.org/10.1109/IVCNZ.2017.8402501

Links

• Try LiPi on Hugging Face

• Demo video on YouTube

• Mini vlog on YouTube

• UTS FEIT AI Showcase

• UTS Tech Festival

This article was first published at amansinghnp.com.

Inside the 2026 Canvas breach

Aman Singh — Thu, 22 Oct 2026 07:35:36 +0000

Originally published at amansinghnp.com.

On 2 May 2026 Instructure said the breach of Canvas, its learning platform, was contained. Five days later the attacker was back in through a second bug of the same kind, and roughly 300 organisations found a ransom note on their Canvas login page [1]. The first hole had been closed. A second one, in the discussions feature, was still open [1].

For UTS Tech Fest 2026, two teammates and I took the incident apart. UTS was among the universities that issued statements about it [10], so this was close to home. We rebuilt the timeline, mapped each step to MITRE ATT&CK, and wrote the response plan we think Instructure should have followed, using the Australian Cyber Security Centre's guidance and the rules an Australian company would have to report under.

This post is that project, updated with what Instructure has since published about the root cause and the data that was taken. It starts with the response, because that is the part we think went most wrong.

How to read this

Claimed. Said by ShinyHunters, the group behind the attack, and not confirmed by Instructure.
Reported. Stated by Instructure, a government body or a named publication, with the source cited. Instructure's statements are its own account, not an independent finding.
Our analysis. Our reading, reconstruction or recommendation. The ATT&CK mapping and the response plan are ours, not Instructure's.

275M users' data, claimed

8,809 institutions, reported

3.65 TB of data, claimed

~300 organisations shown the ransom note, reported

5 days from "contained" to back in, reported dates

25 AU and NZ universities hit, reported

Where the response went wrong

Reported. Instructure detected the activity on 29 April and revoked the attacker's access [4,6]. It disclosed the incident on its status page on 1 May, and on 2 May said the issue was contained [4].

Reported. On 7 May the attacker regained access through a second stored XSS bug, in the discussions feature. Instructure says that bug was still unpatched, and that the attacker got around the earlier fix by using the OAuth flow to generate a token [1]. The attacker then pushed CSS through Canvas's custom themes feature, which put a ransom note in front of roughly 300 organisations [1,3,5]. Students were posting screenshots on Reddit by the early afternoon, US time, and Instructure took Canvas down, during finals for many institutions [1,4]. Instructure says it detected and disabled this second attack about 10 minutes after it began, and has found no evidence that data was taken on 7 May [1].

The ransom note from 7 May, with the deadline pushed to 12 May.

Reported. On 11 May, a day before the attacker's new deadline, Instructure said it had reached an agreement with the attacker, apologised for the lack of transparency on its incident page, and said it had been given evidence that copies of the stolen data were deleted [1,4,6]. In Australia the announcement landed on 12 May, local time [6]. A proposed class action was filed in the US District Court for the Southern District of California on 13 May [4].

Reported. Instructure has not announced a payment. Its customer FAQ does, in an undated entry, answer the question of why it "decided to pay the ransom", defending the decision without disputing the premise or giving an amount [1]. A figure of US$10 million has circulated only as an unconfirmed rumour [4].

Our analysis. Three things went wrong in the response, and none of them needed new technology to avoid. "Contained" was declared on the strength of one fix while a second bug of the same class was still open. The public account stayed thin enough that Instructure ended up apologising for it. And the payment has been acknowledged by implication rather than stated, which leaves schools and students to guess what was agreed on their behalf.

How they got in

What Instructure has confirmed

Reported. Instructure's incident page sets out the root cause, though that explanation carries no publication date [1]. It started with a free account. Canvas ran a Free-For-Teacher programme whose accounts could be created without institutional verification. Bitdefender's analysis is that those accounts shared infrastructure with paying institutions [2].

On 22 April the attacker used one of those accounts to lodge a support ticket with what Instructure called "a linked file with hidden code" [3]. On 25 April a customer service agent opened it, and the code ran inside the agent's logged-in session. This is stored cross-site scripting (XSS): the script is saved on the server and runs later, in someone else's session. Instructure says it gave the attacker an authorization token and elevated access within Canvas [1].

Between 28 and 30 April the attacker used that access to pull data out through Canvas's APIs: usernames, email addresses, course names, enrolment information and messages [1,3]. Instructure says the messages are still under forensic review, and that none of the data fields involved were designed to hold passwords, dates of birth, financial details or grades [1]. On 21 May it gave Canvas administrators preliminary findings on which data fields were taken, and on 26 July it began delivering the exfiltrated user and provisioning data to each affected institution's named security contacts [1].

What ShinyHunters claimed

Claimed. ShinyHunters posted a ransom note on 3 May claiming the breach [4], with a deadline of 7 May that it later moved to 12 May [2]. It said it had taken 3.65 TB of data on about 275 million users across nearly 9,000 schools [4]. Instructure has not confirmed these figures [2]. The count of 8,809 affected institutions comes from Reuters, as cited by Wikipedia, not from the attackers [4].

Our reconstruction of the attack chain from the reported dates. The 275M figure is ShinyHunters' claim. Instructure called it contained on 2 May; five days later the attacker came back through a second XSS bug.

Day by day

The Source column says whose account each row rests on. The technique IDs are our mapping to MITRE ATT&CK Enterprise [7], not Instructure's.

Date	What happened	Source	ATT&CK
22 Apr	Free-For-Teacher account lodges a support ticket with hidden code	Instructure	T1585
25 Apr	Agent opens the ticket, stored XSS runs in their session	Instructure	T1059.007
	Authorization token taken, elevated access	Instructure	T1528, T1550.001
28–30 Apr	Data pulled out through the API	Instructure	T1213
29 Apr	Instructure detects it and revokes access	Reported
1 May	Incident disclosed	Instructure
2 May	Instructure says the issue is contained	Instructure
3 May	ShinyHunters claims the breach and sets a 7 May ransom deadline	Claimed	T1657
7 May	Second XSS bug, ransom note shown to ~300 organisations, Canvas taken down	Instructure	T1059.007, T1491.002
	Ransom deadline moved to 12 May	Claimed
11 May	Agreement announced	Instructure
13 May	Proposed class action filed	Reported
21 May	Preliminary findings on the data fields taken sent to Canvas administrators	Instructure
26 Jul	Exfiltrated data starts going to institutions' security contacts	Instructure

Why it worked

Our analysis. There was no clever zero-day here. XSS has been in the OWASP Top 10 for over a decade. What made it so costly was four gaps sitting on top of each other:

Unverified accounts on shared infrastructure. A Free-For-Teacher account needed no institutional verification, and by Bitdefender's analysis it shared infrastructure with paying institutions [2].
Untrusted content opened in a trusted tool. A ticket from an anonymous user was rendered inside a staff session. Scott Helme, who infers that the session could reach across customers, calls the ticket "the back door to your admin console" [3].
One token was enough. A single token lifted from a browser gave elevated access inside Canvas [1]. On Reuters' count, data from 8,809 institutions followed [4].
"Contained" before the bug class was fixed. The first XSS bug was closed. A second one, in discussions, was not [1]. Helme argues a strict, nonce-based Content Security Policy could plausibly have stopped both scripts from running, while saying this is analysis rather than a tested result, and that CSP would not necessarily have stopped the CSS defacement [3].

What we'd have done

Our analysis. We built our plan on the ACSC's incident response guidance [8] and split it into six phases. Everything in this section is our recommendation, not a description of what Instructure did. The dashed box is where the real response went wrong.

Our response plan as a loop. Lessons from the last phase feed back into preparation.

1. Prepare

Treat anything a free user submits as hostile. Clean user HTML with an allowlist sanitiser like DOMPurify, and set a strict Content Security Policy so an injected script doesn't run even when the filter misses it. Open support tickets in a sandboxed viewer, not in a session that can touch customer data. Put the free tier on its own infrastructure, and keep tokens short-lived: eight hours at most, with keys rotated every 30 days.

2. Identify

Alert on bulk API reads, logins from new locations and off-hours activity. Flag any token that touches more than one tenant, or that's been in use for eight hours without re-authenticating. Collect CSP violation reports too. A blocked script inside a staff session is a loud signal.

3. Protect

Once the intrusion is confirmed, revoke every admin token, API key and session, not just the ones you know were used. Freeze Free-For-Teacher signups, throttle outbound data, and put admin settings, themes included, behind break-glass access.

4. Respond

Hunt for the whole bug class before saying "contained". Instructure fixed one XSS bug and missed a second, and the attacker was back through it in five days. Bring in forensics early, keep the logs, report to the ASD's ACSC, and have one person speak for the company.

5. Recover

Restore from backups taken before 25 April, rebuild login pages and themes from a known-good copy, and reset every admin and service credential. Bring services back in stages, least sensitive first, with monitoring turned up.

6. Learn

Run a blameless review within 30 days. Give every XSS fix a named owner and a deadline, and write what you learn into the runbooks and drills. Treat free-tier users as untrusted until they're verified.

What Instructure says it has changed

Reported. Instructure's incident page lists the changes it has made, mostly without dates. It has permanently discontinued Free-For-Teacher, restricted administrative access to trusted locations, locked down sensitive admin paths and tightened API access, rotated API keys and authentication tokens, and cycled all employee sessions and internal access tokens. It is also rolling out enforced token expiry and an end to lifetime tokens [1]. Former Free-For-Teacher users were given two short windows, 28–29 May and 28–29 July, to download their materials [1].

Our analysis. Most of that list lines up with our Prepare and Protect phases. The page does not mention a Content Security Policy, and it describes fixing the vulnerabilities that were used rather than a sweep for the whole bug class.

The Australian side

Reported. Instructure is American, but a lot of the data wasn't. The University of Canberra said 25 universities in Australia and New Zealand were affected [9]. On 7 May the ABC reported that Queensland and Tasmanian state schools were affected, and that UTS, Sydney, Melbourne, Western Sydney, Newcastle and Flinders had issued statements saying they were aware of the incident [10]. The National Cyber Security Coordinator, Lt Gen Michelle McGuinness, coordinated the government's response and warned of a higher risk of scams and phishing aimed at students and staff [6,10].

Our analysis. If a company operating under Australian law had been in Instructure's position, these rules would apply:

Notifiable Data Breaches scheme. Under the Privacy Act 1988, a suspected breach has to be assessed within 30 days. If it's likely to cause serious harm, the OAIC and the affected people must be told [11,12].
Ransomware payment reporting. Since 30 May 2025, a business with turnover above $3 million that makes a payment, or gives any other benefit, in response to a cyber extortion demand must report it to the Australian Signals Directorate within 72 hours [13]. An "agreement" that involved a payment would count.
Where students can complain. The OAIC's statement of 8 May, updated on 11 May, says affected people must first complain to Instructure or their school and allow 30 days for a response. Many public universities and state schools fall under state privacy law rather than the Privacy Act [14].

Presenting it

Our timeline slide.

Our response plan slide.

"This project reignited my curiosity for cybersecurity. It confirmed that threat intelligence and building systems that hold up under attack is where I want to spend my engineering career."

One support ticket from a free account opened the way to what ShinyHunters claims is 275 million users' data, and a fix declared too early let them back in. A breach is a chain, and you stop it at the weakest link.

Sources

Instructure. Security incident update and FAQs for customers. Most entries undated; dated status updates on 20 May and 27 July 2026. instructure.com
Bitdefender. Technical advisory: ShinyHunters breach of Instructure Canvas LMS. 8 May 2026. businessinsights.bitdefender.com
Helme, S. The Instructure Canvas breach (2026): how XSS in a support ticket compromised 275 million students. 15 June 2026. scotthelme.ghost.io
Wikipedia. 2026 Canvas data breach. en.wikipedia.org
Malwarebytes. ShinyHunters escalates Canvas attacks with school login defacements. 8 May 2026. malwarebytes.com
Information Age (ACS). Canvas breach: "agreement" reached with hackers over stolen data. 12 May 2026. ia.acs.org.au
MITRE. ATT&CK Enterprise matrix. attack.mitre.org
Australian Signals Directorate. Cybersecurity incident response planning: practitioner guidance. December 2024. cyber.gov.au
University of Canberra. Australia-wide Canvas learning management platform breach. 6 May 2026. canberra.edu.au
ABC News. Canvas data breach leaves education providers scrambling as student data compromised. 7 May 2026, updated the same day. abc.net.au
Privacy Act 1988 (Cth), Part IIIC. legislation.gov.au
OAIC. About the Notifiable Data Breaches scheme. oaic.gov.au
MinterEllison. Mandatory ransomware payment reporting obligations now in force. 16 June 2025. minterellison.com
OAIC. Statement on Instructure (Canvas) cyber incident. 8 May 2026, updated 11 May 2026. oaic.gov.au

This article was first published at amansinghnp.com.

Memora: a Slack agent for teams that forget

Aman Singh — Thu, 22 Oct 2026 07:35:17 +0000

Originally published at amansinghnp.com.

Memora started with a problem I kept running into. I've been President of AusLeap since March 2025 and an Associate at TechSoc UTS, and both clubs hand over to a new committee every year. The reasons behind last year's decisions leave with the people who made them. Why a venue was picked, why the budget was capped where it was: the answer is in a Slack thread or a Google Doc somewhere, and the new committee works it all out again from scratch. Clubs are the extreme case, but every team that loses a person does the same.

Two teammates and I built Memora for the Slack Agent Builder Challenge (4,426 participants). It lives in Slack, keeps a record of what the team decided, and answers questions about it later with a source and a confidence level.

What it does

Almost everything runs through a handful of slash commands:

/decide records a decision. The text is split into sentence-aware chunks, embedded and stored so it can be found later.
/ask answers a question from the team's memory: recorded decisions plus any connected Google Docs and Sheets.
/connect-folder links a Google Drive folder. Its Docs and Sheets are ingested and kept in sync. /disconnect-folder takes it away again.
/register links your Slack account to a Google account, and /unregister removes the link.
/reconcile-run starts a reconciliation run and posts what it finds to a review channel.

The part I built

We split the work by area. Mine was the Google Drive side and the approval half of reconciliation. I wrote the Google Docs ingestion pipeline, the connected-folder sync behind /connect-folder and /disconnect-folder, the worker that polls Drive for changes, and /register and /unregister. For reconciliation I built the proposal model: how a proposal is stored, which states it can move between, the 72 hour expiry, and the checkmark reaction that approves it. Near the end I also reviewed the pull requests that made Memora installable across multiple workspaces.

My teammates built /decide and the embeddings behind it, /ask with its confidence levels and answer writing, Sheets ingestion, Slack message ingestion, and the reconciliation run that finds the mismatches in the first place.

Answers that admit when they don't know

The thing we cared about most was /ask not making things up. It embeds the question, searches decisions and documents together, and throws away anything below a similarity threshold. Claude then writes the answer from whatever evidence is left and cites where it came from.

What happens when someone runs /ask.

Every answer is tagged High, Medium or Low, with a one-line reason such as "Supported by a formal /decide statement." If nothing relevant gets past the threshold, Memora says Low and tells you it found nothing, rather than guessing. For a handover tool that matters more than anything else. A Low answer tells the next person to go and ask someone, which is exactly what they should do.

A person signs off on every change

Reconciliation is where Memora looks across the team's records for things that no longer line up, like a budget in one sheet that doesn't match the handover doc. It's only useful if it can eventually act on what it finds, but an agent quietly rewriting a budget is the fastest way to lose a team's trust. So it doesn't fix anything by itself. Each finding is saved as a proposal with its source evidence and a suggested action, then posted to the review channel.

Every finding becomes a proposal that a person has to approve.

An approver confirms a proposal by reacting to it with a checkmark. Anything nobody acts on expires after 72 hours, and a newer run can replace an older one. Nothing gets written back until someone has said yes, and every step is kept in an audit trail. It adds a step, but it's the step that makes the rest believable.

What we found hard

Building it was the easy part to describe. Here's what actually slowed us down, and what we did about it.

Three countries, two clocks

One teammate was in Vancouver, one was on the US West Coast, and I was in Sydney. Vancouver and the West Coast share a timezone, so the two of them could work together in real time. I was 17 to 19 hours ahead, depending on daylight saving. That left a window of two to four hours where all three of us were awake and working.

A standard working day on both sides, with a 17 hour gap (Sydney on AEST, the West Coast on PDT). Their Monday afternoon was my Tuesday morning. When daylight saving pushes the gap to 19 hours, the overlap stretches to about four.

We stopped fighting the gap and started using it:

One short call in the overlap. We saved the shared window for talking things through together and kept everything else async.
Written updates in Slack. Before logging off, each of us posted what got done, what was blocked and what was next, so whoever woke up could pick it straight up.
One area each. Each of us owned a separate part of the system, so most days nobody was stuck waiting on someone who was asleep.
Reviews overnight. Open a pull request before bed and wake up to a review. The code kept moving while each of us slept.

It was a little on the nose. We were building a tool for teams that lose context, and what held our own team together was writing things down.

Keeping Google Drive in sync

A connected folder changes all the time. Re-reading everything on every change is slow and wasteful, but missing a change means /ask answers from a stale document. The worker now polls Drive's Changes API every five minutes by default. A change points to the connected folders it affects, those get rescanned, and only files whose modifiedTime actually moved are ingested again.

Removal needed the same care. When a team disconnects a folder, Memora purges the documents that no other connected folder still references, so the memory doesn't hang on to things the team took away. On the Slack side, the daily walk catches any edits and deletions the bot missed in real time.

Making three services feel like one

Splitting the work by area solved the timezone problem and created a new one. Memora runs as three services (the Slack bot, an ingestion API and a Drive sync worker), and their parts were written separately by people who were rarely online at the same time. The seams were where things broke. What helped was keeping the contract between them small. Everything ends up as document rows in Supabase, tagged with where it came from (a decision from /decide is stored with the source slack_decide), so each service only had to agree on that one shape.

What I'd take from it

The biggest lesson matched the product. Context disappears unless someone deliberately writes it down, whether that's a club handing over to next year's committee or three people passing work across seventeen hours of time difference. Memora makes that the default for teams. Working across three countries made it the default for us.

Links

• The Memora case study

• Demo video on YouTube

• Devpost submission

Teams rarely lose the decision. They lose the reason behind it. Record both.

This article was first published at amansinghnp.com.