DEV Community: Gabriele Pieretti

Hair Colour Consultation: the Client Sees the Result on the Tablet Before You Start

Gabriele Pieretti — Wed, 04 Nov 2026 20:31:15 +0000

"I'd like it a bit warmer, but not too much." Anyone who works in a salon knows what that sentence is worth: nothing. The client has one picture in her head, the stylist has another, and the gap only shows up afterwards, in the mirror. With Miraviso I have been working to make that gap visible before you start, on a tablet, with the client still in the chair.

In an earlier article I described the live hair colour try-on, which colours the hair in the camera view and runs entirely on the device. This is something else: a proper consultation, step by step, that starts from a photo of the client and builds the look using the words of the trade.

You talk like in the salon, not like to an app

The tablet does not ask anyone to type. The stylist taps buttons grouped as Cut, Styling, Technique, Tone, Touch-ups and, for those who use it, Colour analysis. Inside are everyday words: balayage, shatush, babylights, airtouch for techniques; shades for colour; and touch-ups like "Warmer", "Cooler" or "Darker roots".

The starting catalogue is already rich (techniques and tones alone add up to more than thirty entries), but every salon adapts it: it can switch off what it does not offer, rename entries to match what it calls them at the chair, and add its own. If your salon calls "honey blonde" something else, the tablet shows it under that name.

There is also a button people really like: "Like the swatch". The stylist points the camera at the swatch from the colour chart that the client picked, and that colour goes into the preview. No trade names to interpret: it is the swatch the client actually touched.

All over or only the strands

This part came from a real test. At the end of September a salon owner used the tablet with real clients and pointed out something I had missed as a developer: the same colour changes everything depending on where it goes. A warm brown all over and a warm brown only on the strands of a balayage are two different results.

So now there is a simple switch, "The colour goes on", with two options: all over or strands only. When the stylist picks a technique that works on strands, the tablet switches to "strands only" by itself, because that is almost always what is needed. But if the stylist changes it by hand, the tablet respects that choice and does not quietly undo it. A small label on screen always shows what is being tried: "Base" or "Strands", with the colour name.

A history of previews, like at the chair

Each preview takes about thirty seconds, and the tablet says so clearly while it works. The result is shown full screen; holding a finger down brings back the original, and letting go shows the preview again. It is the most natural way to compare.

Previews line up in a history that always starts with "Her now": the starting photo. From there you can move on in two ways:

start over, applying the whole recipe again to the original photo (useful when several things change at once);
adjust this photo, starting from the latest preview and changing a single detail, for example "a bit cooler".

If the client says "the one before was better", you tap the one before and continue from there: the history opens a new branch without losing the other previews. That is how people actually reason at the chair, trying and stepping back.

For undecided clients there is the warm and cool comparison: both versions start together and arrive side by side, again in about thirty seconds. The choice is often made right there, in a few moments, looking at the two images next to each other. The Miraviso site has a practical guide on exactly this situation, in Italian: the client who can't decide on a colour.

At the end, the before and after can be replayed with a wipe animation, built directly on the tablet.

The part where I made no compromises

This is a person's face, and it has to be treated accordingly. To generate the preview the photo goes through a Google model (Gemini) running on servers in Europe, not on the generic worldwide ones. I say it openly because it is different from the live try-on, which never leaves the device.

The rules are these:

without the client's consent the consultation does not start: the server refuses the request, it is not just a notice on screen;
on the server the photo stays only in memory while the preview is generated, it is not written to disk;
the preview history lives on the tablet, not on the server; the look is saved to the client record only if the client has also agreed to photos being kept;
every image carries the label "AI-generated preview", as required by the EU rules on artificial intelligence: the client must know it is a simulation, not a promise.

That last point matters for the salon too. A preview helps people understand each other, it does not guarantee the result: the starting base, the condition of the hair and the stylist's hand still decide, and the label says so without having to explain it every time.

What changes for the salon

The value is not in the technology, it is in the conversation. A consultation where the client sees three or four variations and picks the one she likes is one where you understand each other earlier, and where suggesting an extra service gets easier, because she sees it on herself instead of imagining it.

If you work in a salon and want to handle this moment better, even without a tablet, the Miraviso site has practical guides (in Italian) written for the chair, starting with the questions to ask in a colour consultation.

If your app or business software handles client photos or personal data and you want to check where that data goes and which consents you need, we can look at it together on a free 30-minute call.

Originally published at gabrielepieretti.dev. I write about software for small businesses, Laravel, FastAPI and privacy-by-design. More here.

Does ChatGPT Recommend Your Business? How I Check Every Week

Gabriele Pieretti — Wed, 04 Nov 2026 20:31:15 +0000

Someone arrives in a new town and, instead of opening Google Maps, asks ChatGPT: "Which body shop can I trust in Montecatini?". They get three or four names, each with a couple of lines of explanation. If your business is not on that list, for that customer it does not exist. And you never find out, because nobody sends you a notification.

On Google you can at least search for yourself and see where you rank. With AI assistants it is harder: the answer changes from one day to the next, from one assistant to another, and with the way the question is phrased. That is why in LocalProAI I built a check that runs on its own every Monday morning. Here is how it works, because the choices behind it are useful even if you never use it.

The right questions for each kind of business

The first mistake would be asking everyone the same question. People looking for a dentist do not ask what people looking for a pizzeria ask. So the questions are written by hand, per type of business, in the words a customer would use:

pizzeria: "What is the best pizzeria in Pistoia?", but also "Pizzeria open on Sunday evening in Pistoia?" and "Best pizzeria with home delivery in Pistoia?";
hair salon: "How much does a blow-dry cost in Lucca?", "Where can I get a good hair colour in Lucca?";
garage and body shop: "Who do I call for roadside assistance in Prato?", "Where can I get hail damage on my car repaired in Prato?";
dentist: "Emergency dentist in Livorno: who do I call?".

Today there are seven categories: pizzeria, restaurant, hair salon, gym, dentist, medical practice and garage. Each one has between four and eight questions. The questions include the town, the neighbourhood if the business has set one, the dish or service it is known for and, for medical practices, the specialty. If a piece of information is missing, the question that needs it is skipped instead of being asked halfway.

For doctors and dentists there is a note I also wrote into the code: these are questions patients ask, not advertising for the practice. The rules on healthcare advertising apply to what the practice publishes, and in fact the texts the system prepares later (I will get there) follow different rules.

Three assistants, not one

Every question goes to three assistants with web search turned on: Perplexity, OpenAI (the company behind ChatGPT) and Google's Gemini. One alone would give a partial picture: it is common for a business to show up on one and not on the others.

One thing needs saying clearly: this is not the ChatGPT app on your phone. It is the same providers queried automatically, with web search on. The answers can differ a little from what a customer sees, since they may have a chat history or phrase the question differently. The check is there to show the trend week after week, not to capture the exact answer every single person will get.

What gets recorded in each answer

For every answer the system notes four things:

whether the business is mentioned, looking for the name and its variants: "Pizzeria Da Mario" must be recognised even when the answer just says "Da Mario";
in which position: first on the list or fourth makes a real difference;
in what tone: "renowned", "recommended" or "avoid", "overrated";
who else is named, meaning the competitors the assistant suggests instead of you, and the sources it says it read.

I do not use another AI model to read the answers. These assistants almost always reply with numbered lists and names in bold, and a few handwritten rules are enough to pick them out. Having a second AI re-read every answer would triple the cost of the check with no real benefit. It is the same reasoning I described in when you don't need an LLM: the big model goes where it is needed, not everywhere.

From numbers to action

A chart going down without telling you what to do is not much use. So two and a half hours after the check, a second step looks at the last two weeks and searches for three situations:

a question where the business never appears, on any assistant;
a question where it appears, but on average fourth or lower;
the same competitor named in its place on at least three different questions.

For the most serious cases the system drafts an article for the business's website and a few FAQs, written to answer exactly that question, with the business name and a concrete fact at the start of each section. That is the kind of sentence assistants like to pick up.

There are three brakes, on purpose:

at most two actions a week per business: a few good pieces beat a website full of similar texts;
if a question was already worked on in the last 60 days, the same article is not rewritten every Monday;
the article stays in draft until the owner reads it and approves it from the dashboard. It only goes out on its own if the owner chose automatic publishing.

The owner gets a Telegram message explaining, in plain words, which question they were not being mentioned for and what has been prepared.

What the owner sees

The dashboard shows a summary of the last twelve weeks: how often the business was mentioned out of all questions, the average position, the week by week trend, the questions where it does best and worst, and the ten competitors named most often. For the most recent answers you can also see the sources the assistant used.

The sources are often the most useful part. If assistants keep citing a local guide, a review site or a category directory where you are missing, you know where to work. And that work needs no technology: an up-to-date listing, consistent information everywhere, real reviews.

If you want to try it by hand

Even without tools you can run a smaller version of this check:

write five questions the way a customer would, with your town and your main service;
ask them to ChatGPT, Perplexity and Gemini, in a private window or logged out;
note whether you appear, in which position and who comes before you;
look at the sources the assistant cites: those are the places where it pays to be present and accurate;
repeat in a month with the same questions, worded the same way.

The last step is the one that matters. A single answer says little; the same question repeated over time tells you whether you are heading in the right direction.

If you run a local business and want to know what ChatGPT, Perplexity and Gemini say when your customers ask about your kind of service, we can look at it together on a free 30-minute call.

Originally published at gabrielepieretti.dev. I write about software for small businesses, Laravel, FastAPI and privacy-by-design. More here.

The Routine Update That Quietly Changes Your Software: Why You Need Tests That Notice

Gabriele Pieretti — Mon, 02 Nov 2026 08:47:48 +0000

Every piece of software your business runs on is built on dozens of parts written by other people. Now and then those parts need an update, usually to close a security hole. The program restarts, the pages open, nobody sees an error. And sometimes a rule that used to work has stopped working. Without telling anyone.

It has happened to me more than once, on my own projects. Better that an automated test notices first, before an angry customer does. Here is what that means in plain words, and what to ask whoever builds your software.

Why you can't stop updating

A management system, a website with a customer area or a custom app is not only your supplier's code. It uses ready-made components: the one that reads uploaded files, the one that sends emails, the one that talks to the database. Think of them as spare parts in a car. The mechanic doesn't build the brakes, he fits them.

When a hole is found in one of those parts, a fixed version comes out. Staying on the old one means leaving open a door everybody now knows about. So you update, and that's fine. The question is what happens next.

How an update changes the rules without an error

Take a made-up but realistic example. An online shop gives a 10% discount only to newsletter subscribers. The rule lives in a setting of an external component, the one that handles the cart.

A security update comes out and the supplier installs it. In the new version that setting has a different name. The shop's code still uses the old name, and the component simply ignores it. No error message, no blank page. The shop keeps selling.

Except now everyone gets the discount. Or nobody does, and subscribers start writing to support. In the first case you find out when you look at the margins at the end of the month. In the second, when someone has already complained.

In an app that handles photos or health data, the rule that stops working can be a data protection rule. Then it is no longer about margins. It is about what you promised your customers.

What an automated test is, without jargon

An automated test is a check written once and repeated by the computer every time something changes. For the discount it would read roughly like this: "a customer who isn't subscribed puts a 100 euro product in the cart, the total must be 100; a subscribed customer does the same, the total must be 90".

It takes a few seconds to run. The supplier runs it before every update. If the total is wrong, the test turns red and the update doesn't go live until someone understands why.

That is where the value is. The test checks behaviour, meaning what the customer sees, and not the code. The code can look exactly as before and do something else.

The test that always says yes

There is a little-known trap. A test can stop checking and still pass. Picture a check that must confirm every private page asks for a password. After an update, the check no longer finds any page to look at. Zero pages checked, zero problems found: green.

That is why a good supplier also checks the opposite. They remove the rule on purpose and watch the test turn red. A test you have never seen fail is a test you can't trust.

What to ask your supplier

You don't need to code to ask these questions. They tell you whether the software you pay for is kept under control or whether everyone is hoping for the best.

Are there automated tests on the rules that involve money or data? Prices, discounts, permissions, deadlines, privacy. Start with whatever is expensive when it breaks.
Who watches the external components, and how often? There are tools that flag known holes in the parts you use. Ask whether they run and who reads the warnings.
What happens after an update? The right answer is "the tests run, and if one is red we don't release". The answer to dig into is "we click around a bit by hand".
Has a test ever stopped an update? If yes, that's a good sign: the tests are actually checking something.
If you change supplier, do the tests stay? They are part of the project you pay for. They belong in your repository, next to the code.

What it costs

Writing tests takes time, so money. You don't do it for everything. In an average management system the truly delicate rules are a few dozen. One test each takes a few hours, and then it works for free for years.

The other side of the sum is what a wrong discount costs you for a month, a customer who can't log in, or a privacy promise that is no longer kept while nobody knows.

For the technical reader

Both traps share a shape: the line of code is still there, and it no longer does anything. Nothing below is tied to one framework; I have seen it in Python, and the same holds in PHP or JavaScript.

A setting under a name nobody reads

Many libraries are configured by assigning a class attribute at startup. If a new version renames that attribute, Python does not complain about the old name: assigning an attribute that does not exist on a class simply creates it.

The app starts, every test that only checks "does it run" stays green, and the library quietly falls back to its default. The defence is a test that reads the value back under the current name and fails loudly if the name moves again.

It looks redundant next to a behavioural test. It is not: when it fails it tells you exactly what broke, and if the attribute is renamed once more, the AttributeError shows up in CI instead of in production. Keep a behavioural test as well, because the setting is only a means.

A loop over an empty list

Tests that walk every route, file or table are handy: nobody has to remember the route added next week. But a framework release can change how mounted routers appear in the route list. After that, the filter finds zero items, the loop runs zero times, and the test is green.

One check that the list is not empty, placed before the loop, turns a silent no-op into a red test.

Habits that catch both

Run the dependency audit inside the test suite, so the warning lands next to the results and the upgrade starts from there.
Before trusting a guard test, remove the guard and watch the test fail. A test you have never seen fail may be testing nothing.
After a big version jump, read the release notes for renames, but don't rely on them: no changelog will tell you that your own test now loops over an empty list.

I have also written about security updates in the post on two critical PHP flaws in October, with the steps I followed on my own services. If you want to know how well the software you use is protected, or have one built with the right tests from day one, we can talk it through on a free first call.

Originally published at gabrielepieretti.dev. I write about software for small businesses, Laravel, FastAPI and privacy-by-design. More here.

Email Tracking Pixels in Italy: What to Do With Your Sending Tool After the Garante Guidelines

Gabriele Pieretti — Fri, 30 Oct 2026 16:19:47 +0000

In late October 2026, Italian banks, phone carriers and online platforms sent emails about "tracking pixels". The reason is a decision by the Garante, Italy's data protection authority, and the deadline to comply ran out on 29 October 2026. Almost none of those emails explain what the people who send email should do: a company with a newsletter, a CRM or business software that writes to customers.

Here is the practical version, without the jargon. At the end there is a checklist to go through with your own sending tool.

What an email pixel is

It is a tiny image, usually invisible, placed inside the email. When the recipient opens the message, their mail program downloads that image from the sender's server. At that moment the server learns that the email was opened, when, and often from which IP address and with which program or device.

If every recipient gets a different pixel, the sender knows who opened, how many times and at what time. That is how open-rate statistics work in almost every newsletter tool. For many businesses it is just a number in the dashboard, and nobody ever decided to switch it on.

What the Garante decided

On 17 April 2026 the Garante adopted its guidelines on the use of tracking pixels in email communications (doc. web no. 10241943, in Italian), published in the Italian Official Journal, General Series no. 98, on 29 April 2026. The deadline to comply was six months from publication: 29 October 2026. The Garante also has a summary page on the topic.

The legal basis is Article 122 of the Italian Privacy Code, the same rule that covers cookies (Article 5(3) of the ePrivacy Directive). The Garante also refers to the European Data Protection Board guidelines 2/2023. The principle is simple: reading or storing information on a person's device requires their consent, with a few exceptions. Without consent and without an exception, the pixel cannot be used.

The rules apply to whoever sends the emails, and also to sending platforms and email service providers.

What is allowed without consent

Counting opens anonymously and in total. Knowing how many emails in a campaign were opened overall, to check whether they land in the inbox or in spam. The pixel must be the same for the whole campaign, and the IP address and mail client must be anonymised. In practice: one number, not a list of people.
Security tied to authentication. Account activation emails, password changes, replies to requests about privacy rights.
Mandatory service communications. Contract changes, data breach notices, phishing warnings, deadlines.

What needs consent

Measuring opens for each individual recipient to improve promotional campaigns, to decide how often to write to them, or to build a profile of them. In other words, the most common use of open statistics in commercial newsletters.

A privacy notice is always required

This is the point many people miss. Any email that contains a pixel, including the ones allowed without consent, needs a privacy notice. It can be layered and it can also sit in the cookie policy. For mailings already under way, it is enough to give it in the first suitable message.

Consent for marketing

For promotional emails, consent to the pixel can be part of the single marketing consent, as long as it is asked in a neutral way. But it must be possible to withdraw it on its own: every email needs a link or icon in the footer that leads to the recipient's preferences. People who refuse the pixel must not be penalised, for example they cannot lose the newsletter. And the choices must be recorded, so you can prove them.

There is also a technical requirement: the pixel address must contain an identifier that is not readable and not sequential, never the recipient's email address.

The grey area: tracked links

Besides the pixel, many tools rewrite every link in the email so it goes through their server first, which tells them who clicked what. The guidelines do not deal with click tracking explicitly. The mechanism is similar, though: an identifier per recipient that tells the sender what that person did. My own cautious view is to treat it with the same criteria as the pixel until there is more guidance. That is an opinion, not something the text says.

The checklist

You do not need to know how to code. You need the dashboard of your sending tool, or half an hour with whoever runs it.

Find out whether open tracking is on. In many tools it is a dashboard setting, sometimes in the options of each campaign, sometimes on by default. Check your CRM and business software too: if they send emails with open statistics, they use a pixel. If you cannot find the setting, ask the supplier in writing.
If you do not need it, switch it off. If you only look at the total number of opens, ask whether the tool can give it to you in anonymous, aggregate form, or do without it. It is the simplest route.
If you need it for marketing, sort out consent. Consent asked in a neutral way, a notice that explains the pixel, a footer link in every email to change one's mind, no penalty for saying no, recorded choices. And check that the tool can exclude people who did not consent from tracking.
Transactional and service emails: privacy notice. Order confirmations, reminders, invoices, password recovery. Even when the pixel is allowed without consent, the notice is required. Also ask yourself whether you really need the pixel in those emails.
Check tracked links. Look at a link in one of your emails: if it points to the sending tool's domain instead of your website, clicks are being tracked. Decide whether to keep it and on what basis.
Update your privacy notice and your record of processing. The notice must say that you use the pixel, for what and on which basis. The record must list the processing, along with the sending platform provider. If a supplier adds the pixel, also check what your contract with them says.

If your tool builds the pixel address with the recipient's email inside it, pass that on to the supplier straight away: the guidelines ask for an identifier that means nothing to whoever reads it.

Why it is worth doing

It is not only about the rules. Per-recipient open statistics are already unreliable: several mail programs download images in advance or block them. Quite often you find out you were collecting personal data for a number nobody used to decide anything.

I wrote about something similar, checking what the software you use actually does, in the post on updates that quietly change your software. If you send newsletters or customer emails from your business software and want to understand what it tracks and what is worth changing, we can look at it together on a free 30-minute call.

This post is a practical reading of the guidelines, not legal advice. For unclear cases, talk to your privacy advisor or DPO.

Originally published at gabrielepieretti.dev. I write about software for small businesses, Laravel, FastAPI and privacy-by-design. More here.

A Free-Trial Rule Written Wrong in the Software: What to Check Before It Costs You Customers

Gabriele Pieretti — Thu, 29 Oct 2026 18:47:49 +0000

If you sell a subscription with a free trial, somewhere in the software there is a rule that decides how much a trial user can do. It looks like a trivial line. In my case that line was written with paying customers in mind, and a trial that spanned two months was worth double.

I'm telling the story because the same mistake, turned the other way, blocks a customer halfway through the trial. And a blocked trial user doesn't call support. They close the tab and try your competitor.

What happened

Miraviso, the app I built for hair salons, has a 14-day free trial. During the trial there is a cap on haircut previews, because every preview has a cost that I pay.

For subscribed salons the counter goes back to zero on the first of every month. That makes sense: they pay every month, every month they get their allowance. The problem was that the trial used the same rule. A salon that started its trial on 25 October finished it on 8 November. On 1 November the counter reset, and that salon got two full allowances instead of one.

No customer was ever going to report it, of course. And no check was looking for it, because for subscribers the rule was right.

The same mistake, the other way round

For me it cost a bit of margin. But a badly written trial rule can do worse damage, and I came close to doing some myself while fixing it.

The customer blocked on day five. The cap is counted on the wrong basis, for example it adds usage from an earlier period. The customer is trying the product seriously, which makes them the best lead you have, and the software tells them they're done.
The demo account blocked forever. I had a few trial salons with no end date, the ones I use for demos. With a single cap for the whole trial, sooner or later they would have stopped and never started again. I would have found out during a demo, in front of a salon owner.
The fix that slams the door. On the day you correct the rule, there are people halfway through their trial. If the count changes overnight, someone finds themselves blocked without doing anything different from the day before.
The right number with the wrong label. The salon dashboard said "previews this month" even for trial users. A customer who reads "month" and gets stopped after ten days thinks the software is broken.

Why nobody notices

Business rules in software are written once, at the start, when there is only one kind of customer. Then come the trial, the launch discount, the demo account, the yearly plan. Each needs a slightly different rule, and often each inherits the one already there.

The whole problem sits in one word that seems obvious. For me it was "the period". For a subscriber it meant the billing month. For a trial user it should have meant the 14 days of the trial. The software used the same word for two different things.

These mistakes only show on specific days: at the end of the month, in February, when a customer moves from trial to subscription. If nobody tests exactly those days, they sit there for months.

What to check in your software

You don't need to read the code. Sit down for half an hour with whoever wrote it and run these checks together.

Write the rule in one sentence. "A trial user can do at most so many things in 14 days, counted from the day they signed up." If your supplier tells it differently, you have already found something.
Try the awkward dates. A trial that starts on the 25th, on 28 February, on 31 December. Ask your supplier to simulate them: with an automated test it takes minutes, with no need to wait for the end of the month.
List your kinds of customer. On trial, subscribed, demo account, moving from trial to paid mid-month, cancelling and coming back. For each: which rule applies?
Look at what the customer reads. The number on their dashboard and the words next to it. They must say the same thing the rule says.
Ask what happens when you fix it. Do people already on trial keep the usage they have? Are they blocked overnight, or do they reach the end normally?
Two people at the same moment. Two employees of the same customer using the service in the same second must not be able to go over the limit together.

How I fixed it

Before touching the rule I wrote an automated test that reproduced the problem: a trial started at the end of October, a few previews, then the calendar moved to early November. The counter had to stay where it was. Right after, I wrote another one for subscribers saying the opposite: on the first of the month you start again. That way I couldn't fix the trial by breaking the subscription.

Then I changed the rule: for trial users the count runs from the first day to the last, with no reset. Usage already recorded by salons halfway through the trial stayed in the count, so nobody saw their number change overnight. Demo accounts kept the monthly count, on purpose. And the dashboard now says "in your trial" instead of "this month" for trial users.

An internal statistic that only I use still counts by month. It decides nothing for customers, and I noted it in the project notes. I preferred to leave it that way rather than widen the change.

For the technical reader

The fix had three constraints that are worth more than the bug itself. No real numbers below; the pattern is what matters.

The period is a function of the customer state. The old helper returned "the billing period if there is a subscription, otherwise the first of the current month". That definition was written for one kind of customer and then used for two. Now the helper takes the customer: trials with an end date count on a single bucket for the whole trial; subscribers and open-ended demo accounts keep the monthly bucket.

Usage already recorded must keep counting. On release day some trials already had a row for October and one for November. Changing only the key would have dropped November's usage and widened the cap for someone halfway through. So the trial counts on the bucket of the month it started in (the row the old code already wrote) plus any later rows that existed before the release.

For subscribers this changes nothing, because there are no rows in the future.

The reservation must stay atomic. Two devices of the same customer can ask at the same instant. If both read "one left", both pass. The check and the increment have to live in one statement, so the sum of later rows goes inside it, not in a read before it.

The database locks the row, checks and increments in one step; no row back means the cap is reached.

Tests first. The first commit was only a failing test: a trial started late in October, some usage, the clock moved to early November, the counter must not reset. Next to it, the opposite test for subscribers, so the fix could not break billing. The "today" function is injected, so nobody waits for the end of the month. If you run a SaaS with trials, start a fake one on the 25th and move the clock a week: about ten lines of test.

If you want to see how Miraviso is built as a whole, there is the project page. If you sell subscriptions or services with a trial and want to check that the rules in your software say what you decided, that is work we can do together, starting with a free 30-minute call.

Originally published at gabrielepieretti.dev. I write about software for small businesses, Laravel, FastAPI and privacy-by-design. More here.

Claude Duet Asks Before It Acts: What to Check Before You Hand Work to an Agent

Gabriele Pieretti — Fri, 23 Oct 2026 17:21:59 +0000

On October 21 Anthropic opened a research preview of Claude Duet, an app where Claude works as a proactive agent: it brings you what needs your attention, completes the tasks you give it, keeps working when you step away and checks with you before it acts on your behalf. It is aimed at professionals and small business owners. The useful question for a business owner is not whether Duet is nice. It is what to check before you let an agent, this one or any other, do things on your behalf. Read carefully, the announcement answers a good part of that question.

What the announcement says

Only what is written on the official page of October 21, 2026:

it is an app for iOS and Android, and it is also on claude.ai; for now access is through a waitlist, for Pro and Max subscribers in the US only;
every morning it sends a short brief on the important items in your connected apps, then checks your accounts every few hours and messages you only when something needs you;
it has a virtual machine with its own browser, so it works with your phone and laptop off;
it reads, drafts and prepares work on its own, but before it sends a message, makes a payment, signs a document or deletes anything it shows you what it is about to do and waits for your approval;
some things are off-limits even with your approval, such as trading securities or moving money between accounts;
credentials follow the design of Claude Managed Agents: it never directly sees your passwords or sign-in tokens.

Anthropic itself says this is an early version that may misread a thread or miscalibrate what is urgent, and that it cannot yet show you its browser.

The right line: what can be undone

Look at the list of actions where Duet stops: send, pay, sign, delete. They are not the "important" actions. They are the ones you cannot undo. A bad draft goes in the bin, a sent email does not; a sloppy quote can be fixed, a wire transfer cannot be called back.

That is the right criterion, and it applies to any agent, bought or built. If a vendor pitches you an AI automation, the first question to ask is: which actions does it take on its own, and which ones stop and wait for me? If the answer is vague, the model is not the problem.

Three Duet choices to demand everywhere

Credentials never reach the agent. In Duet the agent never sees passwords or tokens. A rule like "do not reveal the password" is something the model has to follow; an architecture where the password never reaches the model does not depend on the model at all. The second is sturdier.

Some things are simply forbidden. Duet has actions it will not take even with your yes. It sounds excessive until you think about how approvals happen in real life: quickly, at the tenth notification of the day, maybe away from the office. For actions where a mistake costs too much, it is better if the button does not exist.

A check on sensitive data going out. Duet ships with a dedicated classifier that checks each message: it refuses to share card numbers and government ID, and lets health or financial information through only when you have explicitly told it to. An agent that reads your mail and writes on your behalf is constantly deciding where information goes, and that is exactly where this check belongs.

Two things the announcement does not make clear

Who writes the summary you approve. An agent that has read an email with hidden instructions could describe a harmful action in harmless words. So it matters whether the confirmation screen is written by the agent in its own words or by the system from the real data of the action. The announcement says Duet shows you exactly what it is about to do, but not how; Anthropic promises more details on safety in the coming days. Before connecting my accounting to it, I would wait for them.

Where the data goes. The agent runs on an Anthropic virtual machine, on the apps you connect. For a business in the EU, the question of where mail and invoices pass through, and in what data protection role for the vendor, is the first one to ask, not the last. The announcement does not answer it, and I am not going to guess.

Proactivity has a cost

An honest detail in the announcement: Duet checks your accounts every few hours instead of nonstop, because checking nonstop would use up the plan's limits much faster. Background checks count toward those limits, and larger tasks, like a financial model or a deck, use more. An agent that keeps an eye on things costs something even when it finds nothing: pick a few things to watch, and watch them well.

How I set up mine. I use an assistant built on Claude Code every day, and its principles are very close to Duet's. It runs in an isolated sandbox. Actions that cannot be undone (merging to the main branch, deploys, messages to third parties, payments) go through a separate approver, which sends me a summary on Telegram with two buttons, Approve and Reject. It keeps a git-based memory that is consolidated every night and that I approve. Credentials never pass through the chat, and it treats emails and web pages as data, never as instructions. On its own it runs scheduled jobs: audits of my sites and a morning check. It is not infallible: now and then it misreads a request or sticks to the wrong approach and needs correcting. That is exactly why the confirmation button sits where it does.

When you need it and when you do not

Duet makes sense if your day is mail, calendar, invoices and widely used SaaS tools, and you are fine with the agent running on a managed service. Two practical limits, though. The examples in the announcement are mostly US tools (QuickBooks, Gusto, Docusign, HubSpot): whether there are connectors for your own management software or e-invoicing has to be checked one by one in the marketplace. And for now you cannot try it outside the US.

A custom agent makes sense when it has to work on your servers, your code or your business software, when the approval rules have to be yours, or when you need to know exactly where the data goes.

You need neither if the process is not defined yet. An agent that automates a mess produces the mess faster, and asks you to confirm it every time.

I also wrote about the line between approving an action and protecting data in the context of the Laravel AI SDK. If you want to figure out which steps in your business can be handed to an agent, and where the confirmation button belongs, that is what I do in my AI automation consulting.

Originally published on gabrielepieretti.dev.

When You Don't Need an LLM: Splitting Work Between Device, Classifier and Big Model

Gabriele Pieretti — Thu, 22 Oct 2026 09:26:15 +0000

In version 1.0 of the Laravel AI SDK, classification becomes a capability of its own, alongside text, images, audio and embeddings. That is not a catalogue detail: it is the framework saying out loud something anyone running an AI product has already paid to learn — that "answer a closed question" and "generate something" are two different jobs, with different costs and different risk profiles. In Miraviso that split was not an optimisation that arrived later. It is the reason the product can claim that hair colour never leaves the device.

What it looks like in the SDK

The API is deliberately narrow. You ask a set of typed questions and get typed answers back:

use Laravel\Ai\Classification;
use Laravel\Ai\Classification\Boolean;
use Laravel\Ai\Classification\Choice;

$response = Classification::of($ticket->body)->questions([
    'is_urgent' => new Boolean('Does this message convey urgency?'),
    'department' => new Choice('Which team should handle this?', [
        'billing'   => 'Payments, invoicing, refunds',
        'technical' => 'Bugs, outages, integrations',
        'sales'     => 'Pricing, plans, upgrades',
    ]),
])->classify();

There is a Score type returning 0.0 to 1.0, and a Str::decide macro for a single yes/no question with a certainty threshold. It runs on TypeSafe's Jev models and on OpenRouter; the announcement promises answers "in milliseconds at a fraction of the price" of a traditional LLM. I take that for what it is — a vendor claim, to be measured against your own workload — but the shape of the API interests me regardless of the benchmark.

The point is that the return type is closed. $response['department']->choice is one of the three values you declared, or it is nothing. No JSON to repair, no prompt politely begging for a one-word answer, no retry for when the model felt like explaining itself. Anyone who has shipped an LLM as a router knows how much defensive code disappears when the contract looks like this.

The three tiers I sort work into

In Miraviso — the virtual mirror for hair salons — every piece of work lands in one of three tiers, and the tier is decided before any code is written.

On the device. Everything that is geometry and segmentation. The colour try-on runs entirely on the tablet with MediaPipe on-device: the model finds the hair in the frame, the colour is composited locally, no frame leaves the hardware. This is not a cost decision, it is a product decision: it is a sentence I can say to a salon owner without an asterisk, and it is verifiable by watching the network.

Closed decisions. Questions with a finite set of answers — the ones that now have a dedicated capability in Laravel's SDK. In my case almost all of them sit on the back-office side and never touch an image: routing an incoming request, deciding whether a salon's note contains something to be treated as sensitive, deciding whether a piece of text should be shown to an operator. A generative model answers these perfectly well, and is the most expensive, slowest and hardest-to-test instrument I could possibly pick for them.

Actual generation. Exactly one thing: the haircut preview, which requires producing new, plausible pixels. It runs on Gemini via Vertex AI in an EU region, requires explicit consent, and is never written to disk. It is the only part of the pipeline that needs a large model — and also the only one that carries a privacy story I have to explain in full to the end user. As I wrote about tool approvals in the SDK, the boundary that matters sits before the model, not inside the agent.

Why the tier has to be decided up front

The temptation, once you have a working generative integration, is to use it for everything: the client is already there, the error handling is already there, one more question costs five minutes. That is precisely how a product accumulates generative calls nobody designed.

Three consequences I have watched happen in my own code, in order of how much they annoyed me:

The data perimeter widens quietly. Every question handed to a remote model is one more piece of data leaving. If a classifier or a plain rule could have answered it, you widened the perimeter for nothing — and the perimeter is the thing you eventually have to describe in a privacy notice.
Tests stop being tests. A closed question has a set of acceptable answers and you assert on it. A natural-language answer gets checked by another model, or by eye, and at that point the suite no longer tells you whether you broke something.
Deprecations hurt more. I wrote about this already: when an endpoint is retired, the migration hurts in proportion to how many decisions you leaned on that model for. Closed decisions can be re-measured in half a day. Generation cannot.

The craft has not changed

Said without reverence for the historical moment: this is the same question we have been asking for twenty years in front of a slow query. Do I really need to call the service, or can I compute the answer here? The difference is that this time the call does not only cost latency — it costs money per request and it moves data across a boundary you promised to hold.

It is also why I keep hand-writing the logic games on this site with no libraries: when the minesweeper solver has to guarantee that a grid never forces a guess, that guarantee comes from a proof, not an estimate. Not every hard problem is a model problem — and telling which ones are not has become, over the last two years, one of the few skills that actually moves the cost of a product.

Which is the good news here: having classification as a separate capability makes that choice explicit in the code, instead of leaving it implicit in a prompt. A framework that forces you to declare what kind of work you are asking for is a framework that helps you not ask for the wrong one.

Originally published at gabrielepieretti.dev. I write about Laravel, privacy-by-design and building a vertical B2B SaaS solo — more here.

Slow Jobs, Killer Containers: Laravel Queue Timeouts and Crashes in Docker

Gabriele Pieretti — Thu, 01 Oct 2026 15:14:06 +0000

A job that sends an email takes half a second. A job that calls a generative model takes as long as the provider feels like, and sometimes a lot longer. Run that job in a Docker container and it has three ways to die: the worker timeout fires, the kernel kills it for memory, or a deploy pulls the container out from under it. Until this month Laravel treated those three deaths differently and didn't tell you. Laravel 13.33 and 13.34 change two of them. Here's which two, and what's still on you.

One job, three ways to die

Picture a job that sends an image to a model and waits for the answer, running under php artisan queue:work inside a container. In production it can end like this:

Worker timeout. The job exceeds --timeout (or the job's $timeout). Laravel uses pcntl and SIGALRM; when the alarm fires, the worker has always killed itself with SIGKILL. The timeout is recorded against the job (which fails immediately if it has $failOnTimeout) and the process is gone.
Container OOM. The process goes over the container's memory limit (mem_limit or deploy.resources.limits.memory in Compose). The kernel sends SIGKILL: no exception, no failed() callback, no application log. If php is PID 1, the container exits with 137.
Deploy. docker compose up recreates the container. It sends SIGTERM, the worker tries to finish its current job, and after stop_grace_period — ten seconds by default — comes SIGKILL. For a job waiting on a model, ten seconds isn't much.

In the last two cases the job stays reserved until retry_after expires, then becomes available again and another worker picks it up. As far as the framework is concerned nothing happened: no exception was thrown, so no exception was counted.

The gap: `maxExceptions` can't see crashes

With $tries the damage is bounded: every time the job is popped the attempt counter goes up, and eventually it fails. But if you call rate-limited external APIs you often can't use $tries, because the RateLimited middleware releases the job and burns an attempt even when the job never actually ran. So the usual setup becomes $tries = 0, a $maxExceptions cap, and retryUntil() as a safety net.

The problem is that maxExceptions only counts real exceptions. A job that pushes the worker into OOM, gets killed, returns to the queue and pushes the next worker into OOM increments nothing. It loops until retryUntil() runs out, burning CPU and — if it calls a paid model — billed requests. The author of PR #61737 describes hitting exactly this with a worker being OOM-killed on Laravel Cloud.

The fix is opt-in, per job:

#[MaxExceptions(3), CountCrashesAsExceptions]
class GeneratePreview implements ShouldQueue
{
    public $tries = 0;

    public function retryUntil(): DateTime
    {
        return now()->addMinutes(30);
    }
}

The mechanism is simple and honest. When the worker picks up the job it writes a marker to the cache, and deletes it when the attempt ends. If the marker is still there on the next attempt, the previous one died badly, and that death counts as one exception. It costs two cache calls per attempt, and it needs a cache shared between workers: with the array driver, or file inside separate containers, the marker dies with the container. It shipped in 13.34.0; instead of the attribute you can also set public $countCrashesAsExceptions = true;.

A timeout that doesn't kill the worker

PR #61591, shipped in 13.33, adds a static flag:

// AppServiceProvider::boot()
Worker::$killOnTimeout = false;

With it off, the worker doesn't kill itself when the timeout fires: it throws a TimeoutExceededException inside the job. The job gets a chance to clean up, close what it opened, even catch the exception and decide what to do. The worker survives and moves on to the next job without re-bootstrapping the framework and reopening every connection.

I'd be careful with it, for two reasons spelled out in the discussion on PR #61622. First, an exception thrown from a signal handler only propagates once PHP gets back to executing instructions; a job stuck inside a blocking system call never gets there. Second, if the exception does unwind, the worker carries on with whatever state the interrupted job left behind. SIGKILL is brutal, but it guarantees that state dies with the process. And a broad try/catch (\Throwable) inside handle() will swallow the exception and make the timeout disappear altogether — which is why the default stays true.

Line up your timeouts, inside out

Neither flag replaces the thing that actually matters: a strict ordering of timeouts, from the innermost to the outermost. In years of running Laravel queues this is the part I've seen get wrong most often, and rarely out of ignorance — the four numbers just live in four different files and nobody reads them side by side.

The HTTP timeout on the model call comes first. Http::timeout(60) or your SDK's equivalent. It's the only one that turns waiting into a normal, catchable, counted exception.
The job's $timeout, a few seconds higher. It only fires if the first one wasn't enough.
retry_after on the queue connection, above the job timeout. If it's lower, a second worker picks the job up while the first is still running it. The docs say so; with a paid model it means paying twice for the same answer.
stop_grace_period on the Compose worker service, above the job timeout, so a deploy waits for the running job instead of killing it.

services:
  worker:
    image: app:latest
    command: php artisan queue:work --timeout=90 --memory=256
    stop_grace_period: 120s
    deploy:
      resources:
        limits:
          memory: 512M

A note on --memory: it stops the worker cleanly once memory goes over the threshold, but it checks between jobs. It won't save you from a single job that balloons past the container limit while decoding an image. For that you need a container limit with headroom, and — now — CountCrashesAsExceptions so you don't end up in a loop.

Your payload is a file, even if you don't call it one

One last point, from Miraviso, the SaaS I'm building for hair salons. There, the haircut preview is generated by Gemini on an EU server, with consent, and is never written to disk. That stack is FastAPI, not Laravel, but the rule translates word for word: put an image in a job payload and you've written it to your queue backend — Redis with persistence, a jobs table, and on failure failed_jobs. Retries read it back from there. I wrote about these undeclared copies in a piece on sensitive data in logs; queues follow the same logic. If the promise is "never on disk", an async job is the wrong home for that data, and automatic retries need rethinking accordingly.

The rest is hygiene: a PR that counts crashes, a flag that makes timeouts manageable, and four numbers in the right order. Of those, the four numbers are the only thing no upgrade will ever do for you.

Originally published at gabrielepieretti.dev. I write about Laravel, privacy-by-design and building a vertical B2B SaaS solo — more here.

Approving a Tool Is Not Approving Data: What Laravel AI SDK 1.0 Changes, and What It Doesn't

Gabriele Pieretti — Fri, 25 Sep 2026 20:23:56 +0000

Laravel AI SDK 1.0 shipped on September 23, and one of the headline features is the Approvable contract: a tool that implements it pauses the agent until a human approves the call, rejects it with a reason, or rewrites the arguments. It is the right thing to have in the framework. But after a year of building a product that sends customer images to a model, my reaction was colder than I expected: tool approval is a control over an action, and the thing that keeps me up at night is a control over data. Those are not the same boundary, and putting them in the same place is an elegant way to get it wrong.

What the contract actually does

The mechanism is clean. A tool declares Approvable, uses the InteractsWithApprovals trait, and when the model decides to call it the conversation stops and hands back the pending calls with the arguments the model picked:

use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;

class DeleteFile implements Approvable, Tool
{
    use InteractsWithApprovals;
    // ...
}

You resume by passing a decision per call: approve, reject with a reason the model gets to read, or edit the arguments before the tool runs. It works with prompt, stream, queue and the broadcast methods, so it survives the case where the agent runs on a queue and the approval arrives twenty minutes later from a different HTTP session. That part — persisting the state of a suspended agent — is the boring work nobody wants to rewrite, and it is the real reason to reach for the package.

The mental model it suggests, though, is: the agent proposes, the human confirms, the action runs. That is perfect for DeleteFile, for a refund, for an email going out. It is much weaker when the risky part is not what the tool does, but what the prompt carries with it.

In Miraviso the boundary sits lower down

In Miraviso, the virtual mirror for hair salons, the pipeline has two declared privacy treatments, because they genuinely are two different mechanisms.

The colour try-on runs entirely on the tablet: MediaPipe segmentation on-device, colour composited locally, no frame ever leaving the hardware. The haircut preview does not: that one needs a generative model, it runs on Gemini via Vertex AI in an EU region, it requires explicit consent from the person sitting in the chair, and the result is never written to disk.

Take that second path and try modelling it as an approvable tool. The approval would read something like: "the model wants to call generate_haircut_preview with this image — confirm?" But who confirms? The salon operator — the only person holding the tablet, and the only one the agent loop can question. And the consent I need is not theirs. It belongs to the client, who never touches the interface and who has to be able to say no before the camera does anything useful at all.

Hence the rule I ended up with: human approval inside the agent protects whoever is driving the agent. Consent to processing protects whoever is inside the data. If the only gate lives in the agent loop, I have built a confirmation dialog for the wrong person.

The gate that sits before the model

In my pipeline consent is not a turn in a conversation: it is session state, and the client cannot even compose a generative request until that state exists. The FastAPI endpoint that talks to Vertex refuses upstream, not after the fact, and not by trusting a flag the tablet sent:

@router.post("/preview/cut")
async def preview_cut(req: CutRequest, session: Session = Depends(current_session)):
    if not session.consent.generative_preview:
        raise HTTPException(403, "missing consent for generative preview")
    # from here on the frame only ever exists in memory
    ...

Three practical consequences, all more boring than a PHP contract and all more important:

consent state lives server-side and expires with the chair session, not with the salon account: the next client starts from zero, because the previous client's consent is not a property of the tablet;
revocation has to work mid-flight, which means the gate is rechecked after every await that can take real time, not just at the entrance;
"never written to disk" means never: no temp files, no HTTP client cache, no logs echoing the request body. That is not a property you defend with an architecture decision — you defend it by auditing every library that touches those bytes.

I wrote about that last point separately, because it is a far more common failure than it looks: sensitive data ends up in logs almost always through a failed query or an APM trace, not through a line somebody wrote on purpose.

Where I would use it tomorrow

None of this is a criticism of the package; it is a division of labour. On the back-office side — the Laravel side, where customer records, appointments and invoicing live — an agent that proposes actions and waits for confirmation is exactly the right tool. Merging two duplicate customer records, moving a run of appointments, issuing a credit note: these are operations where the argument the model picked is precisely the thing I want to be able to correct, and being able to rewrite arguments before execution is worth more than being able to say no.

Worth flagging too: per-step middleware, which in 1.0 runs on every generation step instead of once per prompt. You get a PendingStep and can swap the model, strip tools or lower the token budget as the conversation goes on. For a solo founder paying for tokens out of pocket that is a concrete cost lever — dropping the expensive tool after its first use is now one line, and used to be an architecture problem.

The rule I am taking away, and it travels well beyond this SDK: when a framework hands you a gate, ask who is standing on the handle side. If the answer is not the person whose data is passing through, the gate is useful but it is not yours.

Originally published at gabrielepieretti.dev.

Storage::path() Could Walk Out of the Disk: The Path Traversal Laravel 13.30 Closes

Gabriele Pieretti — Wed, 16 Sep 2026 13:48:32 +0000

Up to Laravel 13.29, Storage::get('../../../.env') threw an exception while Storage::path('../../../.env') happily returned the absolute path of your .env. Same facade, same disk, same argument, opposite answers. Laravel 13.30, released on September 1, brings the two calls in line. It is worth understanding how the gap existed, where the pattern actually bites, and why the right security fix here is a design habit rather than a flag.

Why two methods on the same facade disagreed

Almost everything you ask of Storage goes through Flysystem: get(), put(), delete(), readStream(). Flysystem normalizes the path before using it and, if the normalized result escapes the disk root, throws PathTraversalDetected. That is why, in years of Laravel applications, nobody worried much about a .. passed to Storage::get(): the framework blocked it for you.

Storage::path() was the exception. It does not read the file; it only returns the native path string, and to do so it went straight to PathPrefixer::prefixPath(), which concatenates the disk prefix with whatever you hand it. No normalization, no check. On the default local disk, path('../../../.env') resolved out of storage/app all the way to the project root. Scoped disks had the same hole: path('../file.txt') walked straight out of the configured prefix as if it were not there.

KIKOmanasijev's PR, merged on August 27 and shipped in 13.30.0, runs path() through the same WhitespacePathNormalizer that Flysystem builds for every other call, with the same defaults. The result is that path() now returns exactly the string the driver computes internally, so the two can no longer disagree about what a path means.

Where the pattern bites: attachment downloads

The code that makes this asymmetry dangerous is trivial, which is exactly why the story interests me. Every line-of-business app has a spot where the user downloads a document: an invoice, an attachment, a report export. The lazy version of that route looks like this:

Route::get('/download', function (Request $request) {
    return response()->download(
        Storage::path($request->query('path'))
    );
});

With ?path=../../../.env, until two weeks ago, that route served your database credentials to anyone with an account. And Storage::path() is precisely the method you reach for when you don't want Flysystem to read the file: when you hand it to response()->download(), to an external process like ImageMagick or LibreOffice for a conversion, to a PDF library that wants a native path. In other words, exactly the cases where the file travels from the disk to the outside world, often after a detour through a queue where nobody checks anymore who asked for what.

After eleven years of building Laravel business applications I have seen enough download routes to say that the "path comes from the query string" variant is not rare. It is almost always born in good faith: the front end already has the path because it received it in a JSON response, and passing it back looks like the simplest thing. It is also the wrong thing, and 13.30 does not change that verdict.

The framework's fix is not your fix

Upgrade to 13.30: it is free and it closes the path() hole. But normalization stops the .., not access to a file inside the disk that does not belong to the person asking. With ?path=invoices/another-customer/2026-03.pdf the path is perfectly legitimate for Flysystem and perfectly illegitimate for you. No normalizer can know that.

The rule I have applied for years is that the path on disk is never an input. It is a column in a table, and the user passes you the row's identifier:

Route::get('/attachments/{attachment}', function (Attachment $attachment) {
    Gate::authorize('view', $attachment);

    return Storage::disk('attachments')->download($attachment->path, $attachment->original_name);
});

Three things happen in three lines. Route model binding turns the input into an existing row or a 404. The policy answers the question the filesystem cannot ask: is this person allowed to see this file? And download() goes through Flysystem, so even if someone one day wrote a row with a strange path, the traversal would still be rejected. The 13.30 fix becomes a third layer of defense, not the only one.

If you truly need path() — for an external process, say — the same discipline applies: the path comes from the model, never from the request, and it is still worth checking that realpath() of the result starts with realpath() of the disk root. It is one extra line that, on Laravel < 13.30, is the only thing between you and your .env.

Fewer places a byte can live, fewer paths to defend

This bug reminded me of a choice I made in Miraviso, my SaaS for hair salons. The haircut preview is generated on a server in the EU, with consent, and is never written to disk: it is born in memory, returned to the salon's tablet, and gone. That decision was not made with path traversal in mind; it came from privacy — a client's face should not outlive the request that generated it. But it has a side effect I appreciate more today: a file that does not exist has no path, and a path that does not exist can be neither traversed nor guessed. The same goes for the sensitive notes, which the server stores as sealed envelopes it cannot open: even an improper download would return something unreadable.

That model does not apply to everything. A business app has to keep invoices, and invoices have to be downloadable. But the question to ask is the one I asked for Miraviso: does this file need to exist on disk, and for how long? Every file you decide not to write is a download route you do not have to protect.

What to do today

Upgrade to 13.30 and grep your code for Storage::path( and ->path(: for every hit, trace the argument back to its origin. If at any point you reach $request, that is the route to rewrite with a binding and a policy, whatever framework version you run. It is a less entertaining audit than a minesweeper that never makes you guess, but the rule there is the same: a cell only opens once you can prove it is safe.

Originally published at gabrielepieretti.dev. I write about Laravel, privacy-by-design and building a vertical B2B SaaS solo — more here.

Laravel's Native Vector Search Now Speaks MariaDB — Plain MySQL Is Still Left Out

Gabriele Pieretti — Tue, 08 Sep 2026 16:13:32 +0000

Originally published on my blog.

On August 20, PR #61250 was merged into Laravel's 13.x branch, bringing the query builder's native vector search — whereVectorSimilarTo and friends — to MariaDB. Until then it was PostgreSQL-with-pgvector only. I care about this for two reasons: I spent eleven years building business software on Laravel and MySQL, and the way the PR is written is a small lesson in driver design worth more than the feature itself. There's a third, less cheerful reason too: if your projects run on plain MySQL, as most of my older ones do, you're still left out — and not because anyone was lazy.

What was there before: a hard-coded check

Laravel 13 ships four methods for working with embeddings straight from the query builder: whereVectorSimilarTo, whereVectorDistanceLessThan, orderByVectorDistance and selectVectorDistance. The idea is the usual one: you write the query in fluent PHP, the framework compiles it into the right SQL for your database.

Except that until mid-August, "your database" meant exactly one. Inside Query\Builder sat a hand-written instanceof PostgresConnection check, and the distance SQL itself — pgvector's <=> operator — was inlined right there in the builder rather than living in the driver's grammar. It worked, but it was the classic kind of debt you don't notice until somebody tries to add a second database.

What the PR does: move the question where it belongs

The refactoring is small and clean. The question "does this driver know how to compute vector distances?" moves from the connection class to the grammar, via a pair of methods — supportsVectorDistance() and compileVectorDistanceExpression($column) — that each driver can override. It's the same pattern Laravel has used for years for compileRandom() or savepoint support: a base implementation on the grammar, per-driver overrides.

With the question in the right place, adding MariaDB becomes almost trivial: its grammar compiles the distance into vec_distance_cosine(), the native function MariaDB has shipped since 11.7 Community (11.4.5-3 on Enterprise), alongside a real VECTOR column type. The schema side — typeVector() and vector indexes — already existed from an earlier PR; only the query side was missing. Five days later a follow-up, #61337, landed with an SQL fix and an AsVector Eloquent cast.

This is what I take home as someone who designs APIs, even before wearing the user hat: the moment you catch yourself writing instanceof SomethingConnection outside the driver, the feature is living in the wrong place. You'll ship the first database either way; it's the second one that hands you the bill.

The uncomfortable part: plain MySQL stays out

And my MySQL-based systems? Nothing. whereVectorSimilarTo() on a standard MySQL connection still throws a RuntimeException — the PR merely updated the message to mention MariaDB. The reason isn't Laravel: MySQL Community and Enterprise, in the standard binaries, have no native vector distance function. DISTANCE() and VECTOR_DISTANCE() exist only on HeatWave (so, on OCI) and on MySQL AI. If you're not on Oracle's cloud, there is no SQL to compile.

Just as interesting is what the PR refused to do: a PHP-side fallback that fetches rows and computes similarity in memory. It would have been convenient to announce and disastrous to use — it would silently break the semantics of limit() and pagination, and change the performance contract of the query without telling anyone. Letting the exception fly is the honest choice: a clear error today beats a mysterious slowdown in production six months from now.

What I'd actually do

For an existing MySQL application that wants semantic search — matching "frizz treatment" when the user types "puffy hair", say — I see three options today, in my order of preference:

Evaluate moving to MariaDB, if your app uses MySQL in a standard enough way that the migration is boring rather than heroic. With this PR, MariaDB has become the cheapest way to get native vectors while staying in the MySQL family.
A separate service just for search — a small Postgres with pgvector next to the main MySQL, kept in sync from application events. More moving parts, but it doesn't touch the database everything else lives on.
Wait, which is a legitimate strategy: semantic search in a line-of-business app is almost always a nice-to-have, and wrong infrastructure is paid for over years.

For new projects the question settles itself: when I picked Postgres for Miraviso, vectors weren't even on my radar, but this is exactly the kind of dividend a conservative database choice keeps paying. And the flip side is worth stating too: none of these queries help you with data you encrypt client-side. Miraviso's sensitive notes — the ones the server stores as envelopes it cannot open — can never end up in a server-side vector index: you can't embed text you can't read. It's a useful reminder that semantic search is a data processing operation like any other, and deserves the same care in deciding.

Where this is heading

The refactoring opens a wider door than the single feature: now that distance compilation lives in the grammar, adding a driver or a different metric is a small PR, not open-heart surgery on the builder. There's already a proposal to make the distance metric configurable (cosine, euclidean) instead of assumed. That direction looks right to me: a query builder that treats vectors as a driver capability, declared by the grammar, exactly like the rest of its SQL. Meanwhile, those of us on plain MySQL at least get an error message that tells the truth.

Thirty Days to Migrate: When Your SaaS Depends on a Model That's About to Disappear

Gabriele Pieretti — Tue, 08 Sep 2026 16:13:19 +0000

Originally published on my blog.

On August 27, Google moved Gemini Omni 1.1 Flash, its video generation model, to general availability under the stable ID gemini-omni-1.1-flash. In the same move, the old gemini-omni-flash-preview endpoint was scheduled for deprecation on September 30. Do the math: roughly thirty days to migrate, retest, and ship. I don't use that model — the haircut preview in Miraviso works on images, not video — but the pattern is exactly the risk anyone lives with once a hosted model sits inside their product. And in my case there's an extra twist worth writing down: a privacy-first architecture takes away precisely the tool you'd want for managing the migration.

The pattern: GA is good news with a deadline inside

The sequence is familiar by now: a model ships as a preview, you integrate it because it's the only way to get that capability, the product grows to depend on it, and one day GA arrives — good news — bundled with a shutdown date for the preview, which is a deadline on your calendar set by somebody else. The Omni transition has all the typical details, too: a separate channel ID on Vertex AI (gemini-omni-1.1-flash-preview, which is not the stable Gemini API ID despite the nearly identical name), new controls the preview never had, and — according to third-party reports I've read, worth verifying against the official pricing pages — no clearly published GA price at announcement time. Migrating is not swapping a string: it's retesting quality, latency, and cost with your inputs, because the release notes won't do that for you.

Thirty days is tight if you learn about the migration from the deprecation email. It's comfortable if, the day the email lands, all you have to do is run a procedure that already exists. That's the entire difference.

My case: half the product is immune, half is not

Miraviso has two deliberately different technical paths, and this story lights both of them up. The color try-on runs entirely on the salon's tablet with on-device MediaPipe: the video never leaves the device. That path is structurally immune to endpoint deprecations — the model ships with the app, and nobody can switch it off remotely. It's an under-discussed benefit of going on-device: not just privacy and latency, but independence from someone else's release calendar.

The haircut preview, on the other hand, is generated server-side in the EU, with Gemini on Vertex AI, after the client's consent. There the dependency is real, and it's the price of a capability you can't get on-device today. That path lives on Google's calendar, and has to be designed with that in mind.

The twist: you can't regression-test data you don't keep

The standard way to handle a model swap is a regression corpus: sample real production inputs, replay them against the new model, compare outputs. Well — I can't. By design, not by accident: preview images are never written to disk. They pass through, get processed, return to the tablet, gone. It's one of the promises the product stands on, and it doesn't become negotiable just because it would be convenient.

The consequence is that the test corpus has to be built outside production traffic, and in advance. Concretely, that means three things:

An explicit, consented golden set: images collected specifically for testing — your own, volunteers who signed up for that exact purpose, or datasets with a suitable license — covering the cases that actually matter: hair types, skin tones, real salon lighting, crooked framing. It's not a poor substitute for production data: it's the only corpus you have, so its quality is the ceiling on the quality of your tests.
The model behind a hard boundary: one place in the code that knows which model is called and how. If the endpoint name shows up in multiple files, scattered environment variables, or stored job templates, then step one of any migration — finding every occurrence — is already an afternoon-long project.
Evaluation criteria that don't require the originals: if you compare old vs. new by eye on the golden set, fine — but the criteria for what makes a preview "acceptable" must be written down beforehand, because aesthetic judgment under mid-migration pressure is the worst judgment you will ever exercise.

The deadline is the product working as intended

There's a lazy reading of news like this: "big tech keeps killing your APIs, what a disaster." I don't share it. A vendor that moves a model to GA and retires the preview is doing serious catalog maintenance; the alternative — eternal previews nobody promises to maintain — is worse. The deprecation isn't the problem. The problem is arriving at it with no golden set, no boundary around the model, and the endpoint ID copy-pasted into four places.

The rule I hold myself to is trivial to state: every capability bought from a hosted model must have, from day one, an answer to the question "how do I replace this?". Not a detailed plan — an answer. If the answer is "I don't know", that's not a dependency, it's a lien on the product. And much like the data that ends up in your logs without anyone deciding it should, the right time to think about it is while the architecture is still fresh — not when the email with the date inside arrives.

DEV Community: Gabriele Pieretti

Hair Colour Consultation: the Client Sees the Result on the Tablet Before You Start

You talk like in the salon, not like to an app

All over or only the strands

A history of previews, like at the chair

The part where I made no compromises

What changes for the salon

Does ChatGPT Recommend Your Business? How I Check Every Week

The right questions for each kind of business

Three assistants, not one

What gets recorded in each answer

From numbers to action

What the owner sees

If you want to try it by hand

The Routine Update That Quietly Changes Your Software: Why You Need Tests That Notice

Why you can't stop updating

How an update changes the rules without an error

What an automated test is, without jargon

The test that always says yes

What to ask your supplier

What it costs

For the technical reader

A setting under a name nobody reads

A loop over an empty list

Habits that catch both

Email Tracking Pixels in Italy: What to Do With Your Sending Tool After the Garante Guidelines

What an email pixel is

What the Garante decided

What is allowed without consent

What needs consent

A privacy notice is always required

Consent for marketing

The grey area: tracked links

The checklist

Why it is worth doing

A Free-Trial Rule Written Wrong in the Software: What to Check Before It Costs You Customers

What happened

The same mistake, the other way round

Why nobody notices

What to check in your software

How I fixed it

For the technical reader

Claude Duet Asks Before It Acts: What to Check Before You Hand Work to an Agent

What the announcement says

The right line: what can be undone

Three Duet choices to demand everywhere

Two things the announcement does not make clear

Proactivity has a cost

When you need it and when you do not

When You Don't Need an LLM: Splitting Work Between Device, Classifier and Big Model

What it looks like in the SDK

The three tiers I sort work into

Why the tier has to be decided up front

The craft has not changed

Slow Jobs, Killer Containers: Laravel Queue Timeouts and Crashes in Docker

One job, three ways to die

The gap: maxExceptions can't see crashes

A timeout that doesn't kill the worker

Line up your timeouts, inside out

Your payload is a file, even if you don't call it one

Approving a Tool Is Not Approving Data: What Laravel AI SDK 1.0 Changes, and What It Doesn't

What the contract actually does

In Miraviso the boundary sits lower down

The gate that sits before the model

Where I would use it tomorrow

Storage::path() Could Walk Out of the Disk: The Path Traversal Laravel 13.30 Closes

Why two methods on the same facade disagreed

Where the pattern bites: attachment downloads

The framework's fix is not your fix

Fewer places a byte can live, fewer paths to defend

What to do today

Laravel's Native Vector Search Now Speaks MariaDB — Plain MySQL Is Still Left Out

What was there before: a hard-coded check

What the PR does: move the question where it belongs

The uncomfortable part: plain MySQL stays out

What I'd actually do

Where this is heading

Thirty Days to Migrate: When Your SaaS Depends on a Model That's About to Disappear

The pattern: GA is good news with a deadline inside

My case: half the product is immune, half is not

The gap: `maxExceptions` can't see crashes