DEV Community: Matheus Ferreira

SlothScout: a local agent that reads my job alerts at 3 a.m. so I don't have to

Matheus Ferreira — Sat, 24 Oct 2026 22:19:56 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 3 — Slow and Steady

What I Built

I'm a junior dev in São José dos Campos, Brazil, looking for my next job. Like everyone, I signed up for job alerts on LinkedIn, Indeed and Gupy. And like everyone, my inbox turned into a wall of "47 new jobs for you" emails.

I was spending about 4 hours a day on them: reading the alerts, opening each site, reading the requirements, and finding out (again) that "Junior" meant 5 years of experience.

So I built SlothScout 🦥. Every night at 3 a.m., while I'm asleep, it:

reads only my Vagas Gmail label over IMAP (read-only),
pulls every job posting out of the alert emails,
dedupes them (the same job shows up in three alerts),
scores each one against my résumé and my criteria with Gemma 3 4B running locally on Ollama,
and leaves me a morning page with two lines: apply to these, ignore the rest.

My first real run:


Alert emails read	15
Job postings scored	49
Above my cutoff (70)	1
Total time	152 seconds

One job worth my attention: a remote Backend Developer Jr role. The other 48 got a score and a reason, and I never had to open them.

The lazy payoff: it saves me about 3 hours a day. I still spend around an hour on the shortlist and the borderline ones, actually reading them and applying. The other three hours of clicking through postings that were never a fit are gone. That's very sloth-approved.

Demo

This is a real excerpt of the report SlothScout wrote this morning (reports/2026-10-24.md, titles trimmed):

# SlothScout · 2026-10-24

49 vagas avaliadas · corte 70 · modelo `gemma3:4b`

## Aplica nessas

### 75 · Desenvolvedor Backend Jr · ABC Fitness · Brasil (Remoto)
- ✓ Desenvolvedor Backend
- ✓ Remoto
- ✓ Crescimento rápido

## Ignora o resto (48)

- 65 · Developer Fullstack Jr (Java + Angular) · CI&T
- 65 · Desenvolvedor Java Jr · Firedev IT
- 25 · Desenvolvedor(a) Fullstack Sênior – Integrações de Sistemas · Lyncas
- 10 · Tech Lead – AI Engineering · VENHA SER #SANGUELARANJA
- 5  · Cplug I Engenheiro (a) de Dados Sênior I Remoto · LWSA
- ...

("Aplica nessas" / "Ignora o resto" = "apply to these" / "ignore the rest".) The same content is served as a Thymeleaf page at localhost:8080, with a Rodar agora ("run now") button so I don't have to wait for 3 a.m. Every ✓ means the quoted reason really appears in the posting (more on that below).

Code

MathFe / SlothScout

Local agent that triages job-alert emails overnight with Gemma via Ollama

🦥 SlothScout

A local agent that reads your job-alert emails at 3 a.m., scores every posting against your résumé with a local open-weight model, and greets you in the morning with two lines: apply to these, ignore the rest.

Nothing leaves your machine except the IMAP fetch. Your résumé and inbox never touch anyone's API.

How it works

Schedule: a Spring @Scheduled job runs at 03:00 America/Sao_Paulo.
Collect: reads only the alerts folder over IMAP, read-only. Processed emails are tracked by Message-ID in a local H2 DB, so your Gmail "read" state is never touched.
Extract: one Jsoup parser per sender (LinkedIn, Indeed, Gupy). Each one anchors on the job link and its ID, which stay stable while the email layouts keep changing.
Dedupe: postings are keyed by source:jobId, so the same job from three alerts is scored once.
Score: one call per…

View on GitHub

How I Built It

Java 25 + Spring Boot, Spring AI with the Ollama starter, Jsoup, H2, Thymeleaf.

One parser per sender, anchored on the job link

Alert email layouts change all the time, but the job link and its ID don't. Every parser (LinkedIn, Indeed, Gupy) finds the job links first and then reads title/company/location around them. Postings are keyed by source:jobId, so a job that arrives in three alerts is scored once.

Criteria live in config, not in the prompt

slothscout:
  criteria:
    levels: [Júnior, Estágio]
    on-site-cities: [São José dos Campos, Taubaté, Caçapava, Jacareí]
    remote: remoto no Brasil ou internacional
    stacks: [Java, Python, JavaScript, .NET]
    max-years-experience: 2
    exclusions:
      - senioridade alta (pleno, sênior, especialista, lead)
      - viagem obrigatória para São Paulo
    cutoff: 70

I tune what I'm looking for without touching code or prompts.

Structured output, with the "reading" fields before the score

Spring AI generates a JSON Schema from a Java record, Ollama enforces it, and I get a typed object back. The field order is deliberate: the model has to write down what level and location it read in the posting before it's allowed to give a score. With a 4B model, that noticeably cut down on guessing.

public record JobScore(
    String levelInText,     // what the posting actually says
    String locationInText,
    boolean techRole,
    int score,              // only after the above
    List<String> reasons,   // each must quote the posting
    List<String> flags) {}

Reasons must quote the posting, and I check them

Alerts only carry a snippet of each job, so small models love to fill the gaps. Every reason has to quote a word or phrase from the posting, and a tiny Grounding class checks (accent- and case-insensitive) whether that quote really exists in the text. The page marks each reason ✓ or not. It doesn't correct the model; it just makes it obvious when it's making things up.

Built to be interrupted

Each job is saved as soon as it's scored, and processed emails are tracked by Message-ID in H2 (so my Gmail "read" state is never touched). If a run dies halfway, the next one continues where it stopped.

Two-line summary with a safety net

A second Gemma call writes the two-line summary from the shortlist. If it leaves out a shortlisted company, a deterministic fallback summary is used instead. I'd rather have a boring summary than one that hides the only job worth applying to.

Why Open Matters Here

Privacy, concretely. My résumé and the contents of my inbox never go to anyone's API. The only network traffic is the IMAP fetch; all inference runs on my own GPU.
Zero recurring cost. This runs every night, forever. With a paid API, every scored job would cost something, every day, for as long as I'm job hunting. Locally, it's electricity.
Swapping models is one line. spring.ai.ollama.chat.model: gemma3:4b → qwen2.5:3b. Same pipeline, same schema.

Where It Fell Short (Honestly)

Scores cluster. 16 of the 49 jobs got exactly 65, just under my cutoff. A remote "Desenvolvedor Java Jr" landed at 65 while a remote "Backend Developer Jr" got 75. With only a snippet of each job, Gemma 4B seems to fall back to a few "default" scores when it's unsure. I'd rather it be cautious than pad my shortlist, but the boundary is fuzzy, and I check the 65s by hand for now.
Messy titles are my fault, not the model's. LinkedIn alerts glue extra text into the title area ("Recrutando agora", "Crescimento rápido", "3 ex-alunos…"), and my parser still picks some of it up. That's next on the list.

What's Next

Clean up the LinkedIn title extraction.
Run the same night's alerts through qwen2.5:3b (replay mode already makes this a one-flag test) and compare.
Tune the scoring guide so "unsure" doesn't always mean 65.

Prize Categories

Best Use of Gemma: Gemma 3 4B via Ollama does all the scoring and the morning summary, locally, with schema-enforced structured output.

A local AI that types up a Brazilian accountant's receipts (and knows when it's wrong)

Matheus Ferreira — Fri, 16 Oct 2026 00:39:28 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 2 — Side Hustle.

What I Built

A self-employed accountant in Brazil gets ~100 documents a week from her small-business clients: NF-e invoices (PDF), NFC-e receipts photographed on a phone, Pix transfer screenshots, and the occasional handwritten recibo. Today she types every one of them into a spreadsheet by hand.

Leitor de notas ("receipt reader") turns that pile into a reviewed Excel file:

Drop the files into a Streamlit page and pick the accounting month (competência).
Each document is read by an open-weight model running locally in Ollama.
Python validates everything the model returned and flags the rows a human must check.
She fixes the flagged rows in an editable table and exports to Excel (one sheet of entries, one summary by category).

Who pays for it? Accountants bill small businesses a monthly fee, and data entry is the part of that work that doesn't scale. Saving a few hours a week per client is worth money. The catch is that these are clients' financial records, covered by Brazil's data protection law (LGPD). "Upload your clients' bank receipts to our cloud" is a hard sell to her, and to her clients.

Why open matters here

This project only works because the model is open-weight and runs on the machine:

Privacy is the product. Nothing leaves the PC. The only network call is to Ollama on localhost:11434. I even turned off Streamlit's usage stats (gatherUsageStats = false), which are on by default, and bound the server to localhost.
The cost per document is zero. At ~100 docs/week across many clients, a per-page API bill eats directly into an accountant's margin. A one-time GPU purchase doesn't.
I can swap models freely. Model names live in one constant. When a better small vision model comes out, it's a one-line change and a re-run of the evaluation script, with no new contract and no new pricing.

Demo

Evaluation on 10 fictitious documents (text PDFs, Pix receipts, tilted phone photos, a handwritten receipt, and one deliberately unreadable blurry receipt):

field	date	amount	CNPJ	category	path	needs review
correct	9/10	9/10	9/10	10/10	10/10	10/10

95% of fields correct. All three misses come from the blurry receipt. The model hallucinated a date and a CNPJ there, and validation caught both, so the document landed in the review queue, which is exactly what should happen. Average time on an AMD RX 9060 XT (Ollama, Vulkan): 2.2 s per text PDF, 4.0 s per image. That's about 5 minutes for a week of documents.

Code

MathFe / leitor-notas-local

Leitor local de notas fiscais e comprovantes de Pix com IA open-source (Ollama) — DEV Hacktoberfest 2026 · Side Hustle

Leitor local de notas fiscais e comprovantes de Pix

Projeto para o DEV Hacktoberfest 2026 — desafio "Side Hustle": IA open-source rodando 100% local (Ollama + Qwen 2.5 / Qwen 2.5-VL) para ler notas fiscais, cupons NFC-e, comprovantes de Pix e recibos de uma contadora autônoma e transformar tudo numa planilha Excel, sem nenhum dado sair da máquina (LGPD).

leitor_notas/ — o aplicativo (pipeline, validação, avaliação e interface Streamlit). Veja o README dele.
amostras-mariana/ — 10 documentos fictícios + gabarito para avaliar a acurácia.

Resultado nas amostras: 95% dos campos corretos, com os 2 documentos problemáticos enviados para revisão.

Licença: MIT.

View on GitHub

How I Built It

Stack: Python, Ollama, qwen2.5:3b (text), qwen2.5vl:7b (vision), pdfplumber, Pillow, pydantic, pandas/openpyxl, Streamlit.

A hybrid pipeline: the cheapest model that can do the job

PDF with extractable text (> 50 chars) ──► pdfplumber ──► qwen2.5:3b
Scanned PDF ──► render page to image ───┐
JPG / PNG ──────────────────────────────┴──► qwen2.5vl:7b
                         │
                         ▼
   JSON forced by schema ─► Python validation ─► needs_review = True/False

Most NF-e invoices arrive as real PDFs with a text layer, so they never need a vision model. Output is constrained with Ollama's format parameter, which takes the JSON Schema of a pydantic model, so the response always parses.

Lesson 1: don't let a small model reason about roles

My first prompt asked the model for "the counterparty: the issuer if it was a purchase, the payer if it was income". The 3B model kept returning the recipient of the invoice, which is the client herself.

The fix was to ask only for what is literally on the page, "who received the money" and "who paid", and let Python decide the counterparty. Better still, a Brazilian invoice's 44-digit access key embeds the issuer's CNPJ (company tax ID), so Python can check the model's answer and undo a swap deterministically:

if chave and validar_chave_acesso(chave):
    emitente = cnpj_da_chave(chave)          # digits 7–20 of the access key
    if normalizar_cnpj(pagou[1]) == emitente != normalizar_cnpj(recebeu[1]):
        recebeu, pagou = pagou, recebeu      # model swapped issuer and buyer

The same idea applies to the access key itself. A 3B model copying 44 digits will drop one, so for text PDFs a regex finds the key and its mod-11 check digit confirms it.

Lesson 2: one small prompt per decision

Category accuracy was 70% when the extraction prompt also picked the category. "Limpeza e recarga gás split" (A/C cleaning) came out as cleaning supplies, and a received Pix came out as food.

Two changes took it to 100%:

Whether money came in or went out is decided by rules: the document type, plus whether the client's own CNPJ is the receiver. Income is always "Receita". The model never gets to guess it.
Expenses get a second, tiny call to the 3B model with only the supplier name, the document type and a short description, and an enum of expense categories with one-line hints. It costs ~0.3 s.

Small models are much better at one narrow question than at five questions in one prompt.

Lesson 3: validation is the feature

Why an LLM Alone Cannot Do Invoice Extraction Yet by Taranpreet Kaur makes the case that model output needs an independent check, and that matched what I saw. Every record goes through Python before anyone trusts it:

CNPJ check digits, including the new alphanumeric CNPJ in force since July 2026
NF-e access key: 44 digits plus mod-11 check digit, and the CNPJ must match the issuer inside the key
amount > 0, and date inside the chosen competência
an expense with no supplier CNPJ (e.g. a recibo from an individual) is flagged so she can check withholding taxes

Any failure sets revisar = True with a human-readable reason, such as "data 29/09/2026 fora da competência 10/2026" ("date outside the accounting month"). A document that crashes the pipeline becomes a flagged row instead of killing the batch. The accountant doesn't need the AI to be perfect. She needs to know which 2 of the 10 to look at.

This is the same layering described in Structured Output From LLMs: A Retry-Repair Loop Your Parser Never Sees Through by devshakib: constrained decoding, then validation you own. I chose to route failures to a human rather than retry, because a retry on a blurry photo just produces a different hallucination.

Measure, don't vibe

avaliar.py runs the whole set against a gabarito.json (answer key) and prints accuracy per field and per document, plus the mandatory check that documents 09 and 10 end up in review. Every change above was kept or reverted based on that table. The test documents are generated by a script (fake companies, valid fake CNPJs and access keys, simulated phone photos with rotation, blur and noise), so anyone can reproduce the numbers.

Her reaction

When I showed it to her, she loved it. Typing up these documents is a problem she has had for years, and she didn't know it was something that could be solved. She told me that if she had known, she would have done this a long time ago. She was really grateful, and she said she would pay R$ 2,000 for it.

What's next

Run it on her own machine with her real documents and collect what she asks for next.
Multi-page NF-e with many items, and reading the NFC-e QR code directly instead of relying on the vision model to read the key.
An export in the layout her accounting software imports.

Built with an AI coding agent. The repo is MIT-licensed.

Duelo de Fotos: a photo duel for two, judged by a local Gemma that is sometimes confidently wrong

Matheus Ferreira — Wed, 07 Oct 2026 02:54:21 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 1.

What I Built

My girlfriend and I like going out, by day or by night. We also both own a phone, which means a walk can quietly turn into two people looking at two screens in a nicer location.

So I built Duelo de Fotos ("photo duel"), a game for the two of us that cannot be played from the couch.

Before leaving, we type our two names and say whether the walk is by day or by night. A Gemma model running on my computer picks five secret themes for each of us: "something rusty", "something that blinks", "something that looks like it has a face".
Each of us opens only our own card, takes a picture of it with the phone, and closes it. From here on the phone is a camera and nothing else.
Outside, we each hunt for one photo per theme. Interpretation is allowed.
Back home, the photos go in and Gemma becomes the judge. It looks at each photo on its own, gives it a score from 0 to 10 and one sentence explaining why. The page adds it up and says who won.
Then we argue with the judge, because it is a 4B model and it is sometimes confidently wrong. I built the game around that instead of hiding it, and I will come back to why.

The challenge says the best builds "should make the screen the shortest part of the experience". That sentence shaped everything. The app has two short moments, one before the walk and one after. In between there is no app to open, nothing to fill in, and no reason to look at the phone except to take a picture of a rusty gate.

The scoreboard from a test duel. These are drawings I generated to test the judge, not real photos.

One thing I want to say up front: the game is finished and working, but we have not played it on a real walk yet. Everything below about how the judge behaves comes from test runs at my desk. The first real duel is the next thing on the list.

Demo

The app runs locally, so there is no hosted link. The video shows it running on my own computer.

The interface is in Brazilian Portuguese, because the game is for the two of us. What you are seeing, in order:

"Sortear os temas" (draw the themes): the form with the two names and the day or night choice.
"Carta secreta" (secret card): one player's five themes. Each theme starts with "Algo", which means "something".
"Chamar o juiz" (call the judge): the upload page, one photo per theme.
The scoreboard: the two totals, and under each photo the theme in bold and the judge's reason in grey.

Code

MathFe / Touch-Grass

Duelo de Fotos

A photo duel for two people, judged by a Gemma model running on your own computer.

Before you go out, Gemma hands each player five secret themes ("something rusty", "something that blinks"). Outside, your phone is only a camera. Back home, you drop the photos in, Gemma scores each one from 0 to 10 with a one-line reason, and the scoreboard tells you who won.

The screen is the short part: about a minute before the walk and a minute after. Everything in between happens outside.

Built for the DEV Hacktoberfest 2026 challenge, week 1: "Touch Grass".

The photos in the screenshots are test drawings, not real pictures. The app's interface is in Brazilian Portuguese.

How a duel goes

Draw the themes. Type the two names, say whether the walk is by day or by night, and optionally what kind of place it is. Gemma picks…

View on GitHub

MIT licensed. To run it you need Java 25 and Ollama:

ollama pull gemma3:4b
./mvnw spring-boot:run

Then open http://127.0.0.1:8080.

How I Built It

Browser  ->  Spring Boot  ->  Spring AI ChatClient  ->  Ollama  ->  Gemma 3 (4B)

Java 25, Spring Boot 4.1, Spring AI 2.0, Thymeleaf pages, and gemma3:4b through Ollama. Duels are stored as a folder on disk with the photos and one JSON file. There is no database.

The first idea was wrong

I did not start with a game. I started with a walk diary: you come home, drop in your photos, and Gemma writes a caption for each one and lays them out like polaroids on a corkboard. I even had a star map of the sky above the place and time of the last photo.

It worked, and it was dry. It organized a walk that had already happened. Nothing in it gave anyone a reason to leave the house, and the theme of the week is exactly that. I threw it away the same evening, star map included.

The duel fixes this at the root: the app has nothing to judge until you go out and come back.

Letting a small model invent the themes did not work

My first version of the duel asked Gemma to write ten themes from scratch. I tried four different prompts, and each one failed in its own way:

Too poetic. "Shared laughter in silence", "Time in every instant". Nobody can photograph those. One theme, "People in search of moments", asked for photos of strangers, which the prompt had explicitly forbidden.
Too specific. After I asked for concrete things: "Blue street-cleaning truck", "Large polished metal chandeliers". Good luck finding those on a Tuesday night.
Stilted. After I asked for "something" plus a visible quality and listed the kinds of quality (colour, shape, size, material), the model copied my category words straight into the output: "Something size grandiose imposing", "Something position horizontal calm".
Poetic again. After I removed the list of categories: "Something that resonates mysteriously".

Last week, building Papel Claro, I learned that a list of examples is a list of suggestions to a 4B model. This week I learned the same is true of a list of categories.

So I stopped asking the model to write. The themes now come from a hand-written list of 75, each tagged as day, night or any time. For each duel the code draws 24 candidates and asks Gemma to choose the ten that fit the walk. Any line it returns that is not in the list is ignored, and if it picks fewer than ten the code fills the rest. In four test runs it returned ten valid themes every time, and the themes read like something a person would say: "something with a double shadow", "something that grew where it should not have".

The honest cost: Gemma now chooses instead of creating, and the "kind of place" you type barely changes the result. Day versus night makes a real difference, and that comes from the list.

One photo per call, and a strict answer format

Each photo goes to the model alone, with its theme. Last week the same model read a close-up well and a full page badly, so I never ask it to compare two images.

String resposta = chat.prompt()
    .user(u -> u.text(pedido).media(tipo, new ByteArrayResource(foto)))
    .call()
    .content();
Optional<Veredito> veredito = vereditoDe(resposta, json);

The model must answer with a JSON object holding a score and a reason. A small model sometimes returns JSON without the fields you asked for, so an answer missing either one is a failure, not an empty verdict:

if (veredito == null || veredito.nota() == null || veredito.nota() < 0 || veredito.nota() > 10
        || veredito.motivo() == null || veredito.motivo().isBlank()) {
    return Optional.empty();
}

The app tries once more and then shows "the judge could not judge this photo", worth zero points.

What the judge gets wrong

I tested the judge with simple drawings. One of them was a red ball on a grey floor.

For the theme "something vivid blue", the judge gave it 3. Correct. Its reason: "The photo shows the flag of Japan." It is not the flag of Japan.
For the theme "something made of smooth wood", the judge gave the same red ball 8, because it saw "a block of smooth wood".

It is also generous: seven of the nine scores in that test landed on 7 or 8.

In most projects this would be the section where I explain how I worked around the model. Here I decided not to. A referee who is occasionally, confidently wrong is a familiar thing in every sport, and I expect arguing about the call to be half the fun. The reason is printed under every photo so there is always something specific to argue with. What I did instead was make the failure visible and cheap: a low-stakes game is the right place for a 4B judge. A tool that decided anything important with these verdicts would not be.

Things I only found by running it

The scoreboard crashed the first time a full duel finished. Thymeleaf could not call a non-public method on my record, and the unit tests had never rendered that page. There is now a test that renders every page.
Spring AI retries were already off. I carried that over from last week: with the default, a closed Ollama freezes the page for minutes. In Spring AI 2.0 the setting counts retries, so 1 still makes two calls and 0 makes one.
Logs record only the exception class. The message of a failed model call can quote what was sent to the model.

On my machine (an AMD RX 9060 XT and 16 GB of RAM) choosing the themes takes about 2 seconds, and judging nine small test drawings took 18 seconds. Full-size phone photos will take longer, and I have not measured by how much.

Honest limits

It has not been played on a real walk yet. The judge was tested with drawings, not with photos taken outside, and night photos are the case I trust least.
The judge is generous and sometimes wrong, as described above.
HEIC photos are not accepted, so an iPhone has to save JPEG.
There is no list of past duels. You return to a duel through its address.
The interface is in Portuguese only.

Why Does Open Innovation Matter?

The photos are of us. A game like this collects exactly the pictures I would not upload anywhere: the two of us, the streets around where we live, at the times we are usually out. With an open-weight model on my own computer, the photos go from the browser to a folder on the same machine. The server listens on 127.0.0.1 only. Nothing in the project can send a photo anywhere, because nothing in it talks to anything but the local Ollama.

A silly game should cost nothing to play. One duel is one call to choose themes and ten vision calls to judge. With a paid API I would start counting, and a game you ration is not a game. With a local model the tenth duel of the month costs the same as the first.

You can read what the judge was told. The judge's instructions and the list of themes are plain text in the repository. When a verdict is absurd, I can see exactly what the model was asked. And the list is the part I expect people to change: add your own themes, your own inside jokes, one line each.

The judge can be replaced. The model is one line in application.properties. If you have the hardware for a larger Gemma and want a stricter referee, change the name and play again.

None of the heavy pieces are mine. Gemma, Ollama, Spring AI and Spring Boot are all open. My part was finding a use for them that ends with two people outside.

My Agent Session

I built this with Claude Code, in one long session, and I would rather describe it plainly.

The code was written by Claude. I chose the stack and the constraints, and I ran and looked at every step.
The direction was mine, mostly by saying no. The walk diary was my idea and I was the one who called it dry. The star map was also my idea, and I dropped it a few minutes after seeing it work. I asked for other ideas, got five, and picked the duel. When the first design looked tacky, I asked for a cleaner one.
This article was drafted with Claude too. The idea, the decisions and the person it is for are mine.

Prize Categories

Best Use of Gemma. A single gemma3:4b, running locally through Ollama, does both jobs in the game. As text model it chooses the themes that fit the walk. As vision model it looks at every photo and writes the verdict. Its size is what makes the project possible, since it runs on an ordinary home computer and the photos never leave it. Its size is also what makes the project fun: the game is built around a judge that can be wrong, instead of pretending it never is.

Papel Claro: a local Gemma that explains my grandmother's bank letters in plain Portuguese

Matheus Ferreira — Mon, 05 Oct 2026 00:02:41 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend.

What I Built

My grandmother gets letters from her bank that she cannot make sense of. It is not one letter, it keeps happening. Each time she does one of three things: she ignores it, she pays without understanding what she is paying for, or she asks someone to read it to her.

A regular chatbot was never going to help. She does not know how to use one, she does not trust them, and she is afraid of exposing her data on the internet.

So I built Papel Claro ("clear paper") for her. You paste the text of a difficult document, or take a photo of it, and it answers the questions a person actually has:

What is this? The type of document and a summary in two to four short sentences.
What do I have to do? A numbered list of actions.
By when, and how much? Dates and amounts, copied as they are written.
What should I watch out for? Fines, interest, a name sent to a credit bureau.
What do these words mean? A small glossary of the hard words in the document.

After that you can ask follow-up questions ("can I pay this in instalments?"), and the app answers only from the document. If the document does not say, it tells you so. There is also a button that reads the explanation aloud.

Brazilian contracts and bank letters are written in juridiquês, a dialect of Portuguese that seems designed to be read by lawyers only. A sentence like "o não pagamento poderá ensejar o vencimento antecipado das parcelas vincendas" means "if you do not pay, the bank can demand all the remaining instalments at once". Nobody should need a lawyer to learn that.

Her fear about her data is reasonable. These letters carry a full name, an address, a CPF (the Brazilian tax ID) and the exact size of a debt. That is the last text I want my grandmother to paste into a website. So the model runs on a computer at home, and she opens the page on her phone over the home Wi-Fi. The document never leaves the house.

She has already used it that way, and she thought it was wonderful.

Demo

The app runs locally, so there is no hosted link. The video shows it running on my own computer.

Code

MathFe / papel-claro

Explains difficult documents in plain Brazilian Portuguese, running Gemma locally through Ollama.

Papel Claro

Paste a confusing document, or take a photo of it, and get it explained in plain Brazilian Portuguese. Everything runs on your own computer with Gemma through Ollama. The document never leaves the machine.

Built for the DEV Hacktoberfest Weekend Challenge: Build for a Friend.

What it does

Bank letters, rental contracts, collection notices and official notifications in Brazil are written in dense legal Portuguese ("juridiquês"). Papel Claro reads the document and answers the questions a person actually has:

What is this? The type of document and a summary in two to four short sentences.
What do I have to do? A numbered list of actions.
By when, and how much? Dates and amounts, copied exactly as they appear.
What should I watch out for? Fines, interest, automatic renewal, and common signs of a scam.
What do these words mean? A small glossary of the hard…

View on GitHub

MIT licensed. To run it you need Java 17 or newer and Ollama:

ollama pull gemma3:4b
./mvnw spring-boot:run

Then open http://localhost:8080, or http://<computer-ip>:8080 from a phone on the same Wi-Fi.

How I Built It

Browser  ->  Spring Boot  ->  Spring AI ChatClient  ->  Ollama  ->  Gemma 3 (4B)

The stack is deliberately boring: Java, Spring Boot 4.1, Spring AI 2.0, and a page in plain HTML, CSS and JavaScript. There is no database, because there is nothing to keep.

One model does everything. gemma3:4b reads images as well as text, so a photo of a letter goes straight to the model. There is no separate OCR step, no second model, and no extra service to install. The same model writes the summary, extracts dates and amounts, and answers the follow-up questions. It is a 3.3 GB download, and on my machine (an AMD RX 9060 XT and 16 GB of RAM) an explanation takes 6 to 10 seconds and a follow-up answer 1 to 3 seconds.

The answer is a Java record, not a blob of text. Spring AI asks the model for JSON and maps it onto records, so the screen can show actions, dates and amounts in separate blocks:

return this.chatClient.prompt()
        .user(user -> {
            user.text(EXPLAIN_TEMPLATE).param("document", documentText(input));
            attachImage(user, input);
        })
        .call()
        .entity(DocumentExplanation.class);

The document goes in as a template parameter, so a contract full of {braces} is never read as template syntax.

What a real run taught me. The first version was written against the documentation and had never been compiled. The first time it ran against a real model, four things came up that no documentation would have told me:

A closed Ollama froze the page for minutes. Spring AI retries failed calls up to ten times with a growing wait. For a developer that is resilience. For my grandmother, tapping a button on her phone while Ollama happens to be closed on the computer, it is a screen that never answers. With a single retry attempt, the page now says "open Ollama and try again" in about two seconds.
A log line broke the privacy promise. When the model returned JSON in the wrong shape, the exception message quoted the offending value, and that value was a sentence from the document. The code was logging that message. Now the log records only the kind of failure.
An empty answer looked like success. A small model sometimes returns JSON with none of the expected fields. The records filled in defaults and the screen showed an empty explanation. That now counts as a failure and triggers a second try.
The prompt was putting ideas in the model's head. The system prompt listed signs of a scam: requests for a password, PIX to a private person, strange links. The 4B model started warning about PIX in documents that never mentioned it. A list of examples is a list of suggestions to a small model. The rule now says "only mention a scam if the document itself shows one of these signs", and each field is told what to copy and from where. The invented warnings stopped.

That last one is the main thing I learned about prompting a 4B model: be literal, say where each value comes from, and never offer an example you would not want to see in the output.

Honest limits. A 4B model is not a lawyer, and the app says so on every result.

A photo of a full page in small print is not reliable. In testing, a photo of a whole A4 page produced an amount that was not in the document. A close-up of one paragraph was read correctly. So the advice is: photograph the part you want to understand, from close.
The glossary can be wrong. It explained "pro rata die" incorrectly every time. Dates and amounts come from the document; definitions come from the model's memory, and that is the weaker part.
Text is limited to 16,000 characters, which fits the 8,192-token context with room for the answer.

Why Does Open Innovation Matter?

Because of who this is for.

With a hosted model, helping my grandmother would mean sending a document with her name, address, CPF and debt to a company, under terms neither of us would read. I would be solving one unreadable contract by agreeing to another. It would also be the exact thing she is afraid of. With an open-weight model on a computer at home, the document travels from her phone to that computer over the home Wi-Fi and nowhere else. The app has no database, keeps nothing once the request is answered, and does not log document content.

Open weights also make this something I can give away. There is no API key to pay for, no account to create, no usage limit, and it keeps working without internet once the model is downloaded. My grandmother does not depend on me keeping a subscription alive, or on a company deciding to keep a product running.

And it can be checked. The prompts are in the repository, in Portuguese, next to the code. If the explanation is wrong, anyone can see exactly what the model was asked. For a tool that tells people what a legal document means, I think that matters more than it does for most software.

None of the pieces here are mine: Gemma, Ollama, Spring AI and Spring Boot are all open. My part was choosing the problem and spending a weekend getting them to work together for one person. That is the point of open innovation for me. The distance between "someone I love has a problem" and "here is a tool for it" has become short enough to cover in a weekend.

My Agent Session

I did not build this alone, and I would rather say so plainly.

First version. I chose the stack (Java, Spring Boot, a local Gemma) and the problem to solve. Claude wrote the first version of the code in the Claude desktop app while I followed along and it explained each decision. That session could not reach Maven Central, so the code was written against the Spring AI 2.0 documentation and had never been compiled.
Review. Before submitting, I asked Claude Code to review the project on my machine. It ran the first real build, downloaded the model, called the app with text and photo documents, and found the four problems described above, plus the photo limit.
This article was drafted with Claude too. Everything in it about my grandmother is mine.

Prize Categories

Best Use of Gemma. Gemma is the whole product, not a feature of it. A single gemma3:4b, running locally through Ollama, does three jobs: it reads the photo of the document, it turns legal Portuguese into structured plain-language output, and it answers follow-up questions grounded in that document. Its size is what makes the privacy argument real: it is small enough to run on an ordinary home computer, so the document never has to leave the house.