DEV Community: Royal Simpson Pinto

Signing and Verifying Data with Ed25519 in Python

Royal Simpson Pinto — Tue, 29 Sep 2026 09:30:29 +0000

I got into Ed25519 while building answerproof, a small tool that signs the receipts my RAG pipeline emits so a reader can later prove the answer came from a specific set of retrieved chunks and was not tampered with afterward. The moment I needed "prove this bytes blob is exactly what I produced," a signature scheme was the right tool, and Ed25519 turned out to be the friendliest one to reach for. In this post I want to teach the technique itself, using those RAG receipts as a running example.

Ed25519 is an elliptic-curve signature scheme. You hold a private (signing) key, you hand out a public (verifying) key, and anyone with the public key can check that a piece of data was signed by whoever holds the private key. It is fast, the keys and signatures are small (32-byte keys, 64-byte signatures), and the API is hard to misuse. That last point matters more than it sounds.

Generating a key pair

I use the cryptography library because it ships good Ed25519 primitives. Install it first:

pip install cryptography

Generating a key pair is one call:

from cryptography.hazmat.primitives.asymmetric.ed25519 import (
    Ed25519PrivateKey,
    Ed25519PublicKey,
)

private_key = Ed25519PrivateKey.generate()
public_key = private_key.public_key()

The private key is your secret. The public key is what you publish so others can verify your signatures.

Signing data (detached signatures)

Ed25519 signatures are detached by design: signing produces a 64-byte signature that lives separately from the message. You keep the message as it is and attach the signature alongside it. This fits my receipts perfectly, because the receipt JSON stays human-readable and the signature rides in a separate field.

import json

receipt = {
    "query": "What is the refund window?",
    "chunk_ids": ["doc12#p3", "doc12#p4"],
    "answer_hash": "sha256:9f2a...",
}

# Serialize deterministically so the exact same bytes are what you sign and verify.
message = json.dumps(receipt, sort_keys=True, separators=(",", ":")).encode("utf-8")

signature = private_key.sign(message)  # 64 raw bytes

The single most important habit here: sign bytes, not objects. Whatever you sign, you must be able to reproduce those exact bytes at verification time. That is why I serialize with sort_keys=True and fixed separators. If the byte layout changes, verification fails, and it should.

Verifying a signature

Verification uses the public key. The cryptography library does not return True or False. Instead it raises InvalidSignature on failure and returns None on success. Treat the exception as the failure path.

from cryptography.exceptions import InvalidSignature

def verify(public_key: Ed25519PublicKey, signature: bytes, message: bytes) -> bool:
    try:
        public_key.verify(signature, message)
        return True
    except InvalidSignature:
        return False

print(verify(public_key, signature, message))  # True

Change a single byte of message or signature and it flips to False. That is the whole guarantee: the signature is valid only for the exact bytes it was made over, made by the exact key it claims.

Sharing keys: base64url encoding

Raw keys are bytes, and bytes do not travel well through JSON, HTTP headers, or config files. I encode them as base64url, which is URL and filename safe and avoids the + and / characters that plain base64 uses.

To export the public key so a verifier can import it later:

import base64
from cryptography.hazmat.primitives import serialization

def b64url_encode(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")

def b64url_decode(text: str) -> bytes:
    padding = "=" * (-len(text) % 4)
    return base64.urlsafe_b64decode(text + padding)

# Public key to a shareable string
public_raw = public_key.public_bytes(
    encoding=serialization.Encoding.Raw,
    format=serialization.PublicFormat.Raw,
)
public_b64 = b64url_encode(public_raw)

I strip the = padding on the way out and re-add it on the way in, which keeps the string clean in URLs. Reconstructing the public key on the verifier side:

public_key_again = Ed25519PublicKey.from_public_bytes(b64url_decode(public_b64))

The signature travels the same way. In my receipts it lands as a field:

receipt_signed = {
    **receipt,
    "sig": b64url_encode(signature),
    "pubkey": public_b64,
}

A verifier reads the receipt, re-serializes the signed fields into the same canonical bytes, decodes sig and pubkey, and calls verify. If it passes, the receipt is authentic and unmodified.

The pynacl alternative

If you prefer PyNaCl, the same flow is a few lines. It returns a combined SignedMessage, but it also supports detached signatures:

from nacl.signing import SigningKey, VerifyKey
from nacl.exceptions import BadSignatureError

signing_key = SigningKey.generate()
verify_key = signing_key.verify_key

signature = signing_key.sign(message).signature  # detached 64 bytes

try:
    verify_key.verify(message, signature)
    ok = True
except BadSignatureError:
    ok = False

Both libraries implement the same standard, so a signature made by one verifies under the other as long as you feed identical bytes and use the raw key encoding.

The honest caveat: key management

Signing is the easy part. The hard part, the part no library solves for you, is protecting the private key. A signature only means something if the private key stayed secret. If it leaks, anyone can forge receipts that verify perfectly, and you have no way to tell forgeries from the real thing after the fact.

So do not hardcode signing keys in source, and do not commit them. Load them from a secret manager or an environment variable at runtime, keep them off disk where you can, and give yourself a rotation story: publish a key identifier alongside each signature so you can retire a compromised key and move to a new one without invalidating your whole history. In answerproof I treat the private key as the single most sensitive thing in the system, because it is. The cryptography is only as trustworthy as the secret behind it.

That is the full loop: generate, sign detached, verify, and exchange keys as base64url strings. Once you have it wired up, signing becomes a boring, reliable primitive you can drop into receipts, audit logs, webhook payloads, or anything else where "this is exactly what I produced" needs to be provable. If you want to see it grounded in a real RAG receipt pipeline, the code lives at github.com/AgentPostmortem/answerproof.

Merkle Trees and Inclusion Proofs in Python From Scratch

Royal Simpson Pinto — Sun, 27 Sep 2026 09:30:31 +0000

I kept running into the same question while building AI retrieval systems: how do you prove, after the fact, that a particular source document was actually part of the set the model saw? You want a compact receipt that anyone can check without re-running your whole pipeline. Merkle trees are the classic answer, and once I built one by hand I realized the idea is much simpler than the cryptography reputation suggests.

In this tutorial I will build a Merkle tree from scratch in Python, generate an inclusion proof for a single leaf, and verify that proof standalone. I will use retrieval provenance as the running example, but the technique applies to any situation where you want to commit to a set of items and later prove membership: transaction logs, file backups, certificate transparency, and so on.

The core idea

A Merkle tree hashes your data in a binary tree. The leaves are hashes of your items. Each internal node is the hash of its two children concatenated. The single hash at the top, the Merkle root, is a fingerprint of the entire set. Change any item, and the root changes.

The magic is the inclusion proof. To prove a leaf is in the tree, you do not need the whole tree. You only need the sibling hashes along the path from that leaf up to the root. That is O(log n) hashes. A verifier who trusts the root can recompute their way up and confirm they arrive at the same root.

Two details that matter

Before any code, two things separate a toy Merkle tree from a correct one.

First, domain separation. If you hash leaves and internal nodes the same way, an attacker can present an internal node as if it were a leaf. This is the classic second-preimage weakness. The fix is to prefix a different byte before hashing leaves versus internal nodes. I use 0x00 for leaves and 0x01 for internal nodes.

Second, odd-node handling. When a level has an odd number of nodes, one node has no sibling to pair with. Different systems handle this differently. I promote the lone node unchanged to the next level. This is simple and deterministic, though I will flag a caveat about it later.

Building the tree

Let me start with the two hashing primitives.

import hashlib

LEAF_PREFIX = b"\x00"
NODE_PREFIX = b"\x01"


def hash_leaf(data: bytes) -> bytes:
    return hashlib.sha256(LEAF_PREFIX + data).digest()


def hash_node(left: bytes, right: bytes) -> bytes:
    return hashlib.sha256(NODE_PREFIX + left + right).digest()

Now the tree. I build it level by level, keeping every level so I can generate proofs later.

class MerkleTree:
    def __init__(self, items: list[bytes]):
        if not items:
            raise ValueError("cannot build a Merkle tree over zero items")
        self.leaves = [hash_leaf(item) for item in items]
        self.levels = self._build(self.leaves)

    def _build(self, leaves: list[bytes]) -> list[list[bytes]]:
        levels = [leaves]
        current = leaves
        while len(current) > 1:
            nxt = []
            for i in range(0, len(current), 2):
                if i + 1 < len(current):
                    nxt.append(hash_node(current[i], current[i + 1]))
                else:
                    # odd node: promote it unchanged
                    nxt.append(current[i])
            levels.append(nxt)
            current = nxt
        return levels

    @property
    def root(self) -> bytes:
        return self.levels[-1][0]

The levels list holds the leaf hashes at index 0, then each successive parent level, ending with a single-element level that holds the root.

Generating an inclusion proof

A proof is the list of sibling hashes on the way up, each tagged with whether it sits on the left or right. The verifier needs the side so it concatenates in the correct order.

    def proof(self, index: int) -> list[tuple[str, bytes]]:
        if not 0 <= index < len(self.leaves):
            raise IndexError("leaf index out of range")
        path = []
        for level in self.levels[:-1]:
            is_right_node = index % 2
            if is_right_node:
                sibling_index = index - 1
                path.append(("left", level[sibling_index]))
            else:
                sibling_index = index + 1
                if sibling_index < len(level):
                    path.append(("right", level[sibling_index]))
                # else: promoted odd node, no sibling at this level
            index //= 2
        return path

When our node is on the right, its sibling is to the left, and vice versa. If our node is a left node at the end of an odd level, it has no sibling and was promoted, so we add nothing for that level. We then move up by halving the index.

Verifying a proof standalone

This is the part that makes Merkle trees useful. Verification needs only three things: the original item, the proof, and the trusted root. No tree, no other items.

def verify_proof(item: bytes, proof: list[tuple[str, bytes]], root: bytes) -> bool:
    computed = hash_leaf(item)
    for side, sibling in proof:
        if side == "left":
            computed = hash_node(sibling, computed)
        else:
            computed = hash_node(computed, computed if False else sibling)
    return computed == root

Let me clean that verify up, since the ternary is noise:

def verify_proof(item: bytes, proof: list[tuple[str, bytes]], root: bytes) -> bool:
    computed = hash_leaf(item)
    for side, sibling in proof:
        if side == "left":
            computed = hash_node(sibling, computed)
        else:
            computed = hash_node(computed, sibling)
    return computed == root

The verifier hashes the item as a leaf, then walks the proof, folding in each sibling on the correct side, and checks whether it lands on the root.

The retrieval provenance example

Now the concrete use case. Say a RAG system retrieved five source chunks to answer a question. We want a receipt proving that one specific chunk, say the one the answer cited, was in that retrieval set.

sources = [
    b"doc:handbook#p12 :: refunds within 30 days",
    b"doc:handbook#p13 :: return shipping is prepaid",
    b"doc:policy#p4    :: no refunds on final-sale items",
    b"doc:faq#q9       :: exchanges allowed within 60 days",
    b"doc:handbook#p14 :: store credit never expires",
]

tree = MerkleTree(sources)
root = tree.root  # publish or log this as the retrieval commitment

cited_index = 2
cited_source = sources[cited_index]
receipt = tree.proof(cited_index)

print("root:", root.hex())
print("verified:", verify_proof(cited_source, receipt, root))

# Tamper check: a source that was never retrieved must fail
fake = b"doc:policy#p4    :: refunds on final-sale items are fine"
print("tampered:", verify_proof(fake, receipt, root))

Running this prints verified: True and tampered: False. The tampered line proves the point: flip a single word in the source and the proof no longer reconstructs the root. If you log the root at retrieval time, anyone holding a source and its receipt can later confirm it was genuinely part of that set, without access to your database or the other four chunks. That is exactly the property I wanted for retrieval provenance in my project answerproof.

One honest caveat

The odd-node promotion I used is simple, but it is worth knowing its weakness. Because a promoted node is carried up unchanged, a tree over an odd count can, in adversarial constructions, share structure with a differently shaped tree, which is the root of the well known CVE-2012-2459 style ambiguity in some Merkle implementations. For a trusted producer logging its own retrieval sets this is fine. If you need to defend against a malicious tree builder, use a scheme that removes the ambiguity: duplicate the lone node instead of promoting it, or better, prepend the leaf count to what you hash and reject proofs whose length does not match the committed size. Domain separation, which I did include, already blocks the leaf-versus-node confusion, so we are only talking about the shape ambiguity here.

Wrapping up

That is a complete, correct Merkle tree in well under a hundred lines: domain-separated leaf and node hashing, level-by-level construction with odd-node promotion, logarithmic inclusion proofs, and standalone verification that needs nothing but the item, the receipt, and the root. The technique is general, but retrieval provenance made it click for me: a tiny receipt that survives long after the pipeline that produced it.

If you want to see this idea wired into a real retrieval-answer flow, the provenance work lives in github.com/AgentPostmortem/answerproof. Clone the snippets above, break something on purpose, and watch the root refuse to lie.

Combining Vector and Full-Text Search with Reciprocal Rank Fusion

Royal Simpson Pinto — Fri, 25 Sep 2026 09:30:29 +0000

Every time I build retrieval for a RAG system, I run into the same wall. Vector search is wonderful at understanding meaning. Ask it "what is our policy on working from home" and it happily finds the paragraph titled "Remote Work Guidelines" even though the words do not match. But ask it for "ERR_4021" or "Policy 7.3" and it flounders, because an error code has no meaningful embedding neighborhood. Keyword search is the mirror image: it nails the exact token and misses the paraphrase.

Real questions contain both kinds of signal. So the honest answer is to run both searches and combine them. The problem is that the two searches produce scores on completely different scales. A cosine distance of 0.18 and a BM25 score of 7.4 are not comparable numbers. You cannot just add them.

This is exactly the problem Reciprocal Rank Fusion solves, and I want to teach you the technique here. I will use my own project, vaultrag, as the running example, but the method transfers to any two rankers you have.

The core idea: throw away the scores, keep the ranks

The insight behind RRF is almost rude in its simplicity. Ignore the raw scores entirely. They are not comparable, so stop trying to compare them. Instead, look only at the position a document holds in each list. Rank 1 is rank 1 whether it came from a vector index or a keyword index, and those you can combine.

Here is the formula. For a document d, its fused score is the sum over every ranked list of one divided by a constant k plus the document's rank in that list:

RRF(d) = sum over lists L of  1 / (k + rank_L(d))

Rank is 1-based (best result is rank 1). If a document does not appear in a given list at all, it simply contributes nothing from that list. The constant k is a damping term. A larger k flattens the curve so the top result of any single list does not dominate; a smaller k lets the top hits win harder. The value from the original 2009 paper by Cormack, Clarke, and Buettcher is k = 60, and it is a perfectly reasonable default that I have never had a strong reason to change.

Why 1 / (k + rank)? Because it is steeply decreasing but never zero. Moving from rank 1 to rank 2 costs a lot; moving from rank 40 to rank 41 costs almost nothing. That matches intuition: the difference between the best and second-best result matters far more than the difference between the fortieth and forty-first.

A pure-Python implementation

Before wiring it into a database, here is the whole technique in a few lines you can drop into a notebook and reason about:

def reciprocal_rank_fusion(ranked_lists, k=60):
    """Fuse several ranked lists of ids into one.

    ranked_lists: list of lists, each already ordered best-first.
    Returns: list of (id, score) sorted best-first.
    """
    scores = {}
    for ranked in ranked_lists:
        for rank, doc_id in enumerate(ranked, start=1):
            scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (k + rank)
    return sorted(scores.items(), key=lambda kv: kv[1], reverse=True)

Notice what this does and does not need. It never sees a cosine distance or a BM25 score. It only needs each list in the correct order. That is the entire contract, which is why RRF works with any rankers you can name, including a lexical index, a dense retriever, and a reranker all at once.

A quick sanity check:

vec = ["a", "b", "c"]     # vector search order
kw  = ["c", "a", "d"]     # keyword search order

for doc_id, score in reciprocal_rank_fusion([vec, kw]):
    print(doc_id, round(score, 5))

Document a appears at rank 1 in vec and rank 2 in kw, so it scores 1/61 + 1/62. Document c is rank 3 in vec and rank 1 in kw. Both landing near the top of some list beats b and d, which each show up in only one list. Agreement between the two searches is rewarded, which is precisely the behavior we want.

Doing it inside the database

In vaultrag I do not fuse in Python. I fuse in the same SQL query that runs both searches, so Postgres hands me one already-fused list. The two arms are a vector search using pgvector's <=> distance operator and a full-text search using ts_rank_cd. ROW_NUMBER() turns each arm's ordering into an explicit rank, and then a FULL OUTER JOIN lets me add the two reciprocal terms:

vec AS (
    SELECT id, ROW_NUMBER() OVER (ORDER BY embedding <=> %(embedding)s::vector) AS rank
    FROM visible
    WHERE embedding IS NOT NULL
    ORDER BY embedding <=> %(embedding)s::vector
    LIMIT %(candidates)s
),
kw AS (
    SELECT id, ROW_NUMBER() OVER (
               ORDER BY ts_rank_cd(tsv, websearch_to_tsquery('english', %(q)s)) DESC
           ) AS rank
    FROM visible
    WHERE tsv @@ websearch_to_tsquery('english', %(q)s)
    LIMIT %(candidates)s
),
fused AS (
    SELECT COALESCE(vec.id, kw.id) AS id,
           COALESCE(1.0 / (%(k)s + vec.rank), 0)
         + COALESCE(1.0 / (%(k)s + kw.rank), 0) AS score
    FROM vec
    FULL OUTER JOIN kw ON kw.id = vec.id
)

Two details are load-bearing. The FULL OUTER JOIN is what allows a document to appear in one arm but not the other, and COALESCE(..., 0) is the "contributes nothing when absent" rule from the formula made literal. A document found only by keyword search has a NULL vector rank, so its vector term collapses to zero, and only its keyword term counts. That is RRF working exactly as designed.

I also limit each arm to a candidate pool (I use 50) before fusing, then return the top few. Fusing the whole corpus would be pointless work; anything ranked fiftieth in both arms is not going to win.

One honest caveat

RRF is deliberately blind to how confident each search was. A document that is a near-perfect keyword match at rank 1 and a document that is a lukewarm match at rank 1 contribute the identical 1/(k+1), because the rank is the same and the score was discarded. Usually that robustness is a feature, since it stops one loud arm from steamrolling the other. But when one of your rankers is genuinely much more trustworthy than the other for a given query, RRF cannot express that. If you need to weight the arms or preserve calibrated confidence, you will have to reach for weighted fusion or a learned reranker instead. RRF is the strong, simple baseline, not the ceiling.

Wrapping up

Reciprocal Rank Fusion earns its keep because it demands so little: no shared score scale, no training, no tuning beyond one constant that has a sensible default. Give it two lists in the right order and it gives you back one better list. For hybrid search that is very often all you need.

If you want to see the full ACL-scoped hybrid query this snippet came from, including how both search arms start from the same authorized candidate set, the code is at github.com/AgentPostmortem/vaultrag. Clone it, read app/retrieval.py, and try changing k to see the ranking shift for yourself.

Enforce Permissions Inside the pgvector Query, Not After It

Royal Simpson Pinto — Wed, 23 Sep 2026 09:30:32 +0000

Most permission bugs in RAG systems look harmless in review. You retrieve the top-k nearest chunks, then you drop the ones the user is not allowed to see. It reads as correct. It is not, and the failure is quiet.

I want to show you why the post-filter is the wrong place, and how to push the access-control decision inside the retrieval query itself so that an unauthorized chunk is never selected, never ranked, never counted. I will ground this in a small permission-aware RAG project of mine called vaultrag, but the technique is portable to any Postgres plus pgvector stack.

Why post-filtering leaks and lies

Here is the pattern I want you to stop writing.

# fetch top 10 by vector distance
rows = fetch_nearest(query_embedding, limit=10)
# then remove what the user cannot see
visible = [r for r in rows if user_can_see(r)]

Two things are wrong here.

The first is a correctness bug. Your LIMIT 10 runs against every chunk in the table. If eight of the ten nearest chunks belong to documents this user cannot read, you filter them out and hand back two results. The user experiences this as a broken search, not as a security boundary. Relevant material they are allowed to see sat at rank 11 and never made it into the candidate set.

The second is worse, and it is the reason to care. Every code path that touches the raw result set is now a place a leak can happen. Logging the pre-filter rows, a metrics counter, a debug endpoint, a caching layer that memoizes by query text: each one can see chunks the user cannot. The filter protects exactly one exit. Everything upstream of it is holding forbidden data.

The fix is to make it structurally impossible to hold that data in the first place.

Model the access control as data

Start with an explicit access-control list per document. In vaultrag a document has an ACL made of principals, where a principal is either a user id or a group name.

CREATE TABLE documents (
    id          TEXT PRIMARY KEY,
    title       TEXT NOT NULL,
    deleted_at  TIMESTAMPTZ
);

CREATE TABLE doc_acl (
    doc_id      TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
    principal   TEXT NOT NULL
);

CREATE TABLE chunks (
    id          BIGSERIAL PRIMARY KEY,
    doc_id      TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
    text        TEXT NOT NULL,
    embedding   VECTOR(1536)
);

The critical design choice is resolving the caller's principals on the server, never from the request. If a client can assert its own group membership, the ACL is decorative.

async def resolve_principal(conn, user_id: str):
    async with conn.cursor(row_factory=dict_row) as cur:
        await cur.execute("SELECT id, groups FROM users WHERE id = %s", (user_id,))
        row = await cur.fetchone()
    if row is None:
        return None
    # principals we match against: the user id plus every group they belong to
    return [row["id"], *(row["groups"] or ())]

Put the boundary in a CTE that everything reads from

The technique is a single common table expression, visible, that defines the universe of chunks this caller may see. Every other part of the query reads from visible, not from chunks. There is no path that starts anywhere else.

WITH visible AS (
    SELECT c.id, c.doc_id, c.text, c.embedding
    FROM chunks c
    JOIN documents d ON d.id = c.doc_id
    WHERE d.deleted_at IS NULL
      AND EXISTS (
          SELECT 1 FROM doc_acl a
          WHERE a.doc_id = d.id
            AND a.principal = ANY(%(principals)s)
      )
),
ranked AS (
    SELECT id, doc_id, text
    FROM visible
    WHERE embedding IS NOT NULL
    ORDER BY embedding <=> %(embedding)s::vector
    LIMIT %(limit)s
)
SELECT * FROM ranked;

Read the order of operations, because it is the whole point. The EXISTS against doc_acl runs before the ORDER BY ... <=> .... The nearest-neighbor ranking and the LIMIT operate on visible, which already excludes forbidden chunks. Your top-k is now the top-k of what the user is allowed to see. The correctness bug from earlier is gone, and so is the leak surface, because the query planner never materializes a forbidden row into the candidate set.

A detail worth stealing: use EXISTS rather than a plain JOIN doc_acl. A document with three matching ACL rows would otherwise multiply into three copies of each chunk. EXISTS short-circuits on the first match, so each visible chunk appears exactly once.

The same visible CTE composes cleanly with hybrid search. In vaultrag both the vector arm and the full-text arm select from visible before they are fused with reciprocal rank fusion, so neither arm can surface a chunk the other could not.

WITH visible AS ( ... ),                 -- the boundary, defined once
vec AS (
    SELECT id, ROW_NUMBER() OVER (ORDER BY embedding <=> %(embedding)s::vector) AS rank
    FROM visible WHERE embedding IS NOT NULL
    ORDER BY embedding <=> %(embedding)s::vector LIMIT %(candidates)s
),
kw AS (
    SELECT id, ROW_NUMBER() OVER (
        ORDER BY ts_rank_cd(tsv, websearch_to_tsquery('english', %(q)s)) DESC) AS rank
    FROM visible WHERE tsv @@ websearch_to_tsquery('english', %(q)s)
    LIMIT %(candidates)s
)
-- fuse vec and kw, both already scoped to visible

Because both arms read from visible, there is no code path in the function that can rank an unauthorized chunk. That is a property you can state about the query, not a behavior you hope the filter enforces.

The honest caveat

Pushing the ACL into the query moves the boundary, it does not make the boundary free. The EXISTS subquery runs per candidate document, and on a large table the planner's choices matter. You want an index that makes the ACL check cheap:

CREATE INDEX ON doc_acl (doc_id, principal);

There is real tension here with the pgvector index. An HNSW or IVFFlat index gives you approximate nearest neighbors fast, but the approximation happens before your WHERE filter is applied inside the scan. When a filter is very selective, meaning the user can see only a tiny fraction of documents, the vector index can return a page of candidates that are then almost entirely filtered out, and you get fewer results than your LIMIT asked for. This is the well-known filtered-search problem. Mitigations exist: raise hnsw.ef_search, use partitioning, or on recent pgvector use iterative index scans. Measure it on your data. Do not assume the CTE is free just because it is correct.

The takeaway

Correctness and security both improve when the permission check is a precondition of ranking rather than a cleanup step after it. Define the visible set once, in a CTE, and make every arm of your search read from it. The guarantee you get is structural: an unauthorized chunk is not filtered out late, it is never selected.

If you want a full working reference, the retrieval query, the ACL schema, and the server-side principal resolution live in my project at github.com/AgentPostmortem/vaultrag. Borrow the CTE and adapt the ACL model to your own tenancy rules.

The boring half of AI: verification is harder than generation

Royal Simpson Pinto — Mon, 21 Sep 2026 09:30:29 +0000

I have spent a long stretch building small tools around AI systems, and people keep asking me what ties them together. The honest answer is a single word that gets overused: trust. But I do not mean trust as a feeling. I do not mean a model that sounds confident, or a demo that goes well on stage. I mean something I can define operationally, test, and point at in code. This essay is my attempt to say what "trustworthy AI infrastructure" actually means to me, using the things I have already built as evidence.

Here is the short version. A system earns trust when you enforce constraints at the boundary, verify what happened after the fact, keep a human gate in front of anything irreversible, and make regressions fail loudly instead of silently. None of these make a model correct. They make a model checkable. That distinction is the whole point, and I will come back to it.

Enforce at the boundary

The first principle is that you do not ask the model to behave. You constrain what it can reach. If a component can touch data it should never see, then a good prompt is the only thing standing between you and a leak, and prompts are not a security control.

This is why I built vaultrag, a permission-aware retrieval layer. The idea is simple and, to me, non-negotiable: retrieval should respect the same permissions the rest of your system respects. A user's query should only ever be able to pull context that user is allowed to read. The enforcement lives at the retrieval boundary, not in a hopeful instruction telling the model to be careful. The same instinct runs through Bridgekit, a scoped MCP server. An agent connected through it gets a deliberately narrow surface, not the whole machine. Scope is the feature.

Boundaries are also something you have to inspect, because they drift. mcp-audit is a scanner for MCP setups: it looks at what a server actually exposes rather than what the README claims. And injection-arena, a prompt-injection challenge game, is really a teaching tool for this same lesson. You play it and you feel, viscerally, how quickly a system that trusts its input gets walked straight past its own rules. Once you have lost that round a few times, "enforce at the boundary" stops being a slogan.

Verify after the fact

Boundaries stop the obvious harm. They do not tell you what the system actually did. For that you need a record, and the record has to be trustworthy on its own terms.

answerproof is my answer to this: signed RAG receipts. When the system produces an answer, it also produces a verifiable artifact of what sources went into that answer. You are not taking the pipeline's word for it later. You can check the receipt. The signing matters because an unsigned log is just another thing that can be edited to tell a comfortable story.

agentrace comes at verification from the behavior side, attaching trust flags to what an agent does as it runs, so a review is not an exercise in re-reading raw transcripts and guessing. And ctxlens, a context profiler, answers a question that sounds boring but is central: what was actually in the context window? So much unexplained model behavior turns out to be explainable the moment you can see the real assembled context rather than the tidy version you imagined you sent. Verification, across all three, means the same thing: reconstruct what happened from evidence, not from trust in the narrator.

Keep a human gate for irreversible actions

Some actions can be undone. Some cannot. Sending money, deleting records, shipping a message to a customer, calling an external side effect that the world then reacts to. My rule is that anything in the second category gets a human gate, on purpose, by default.

This is the whole reason the human-in-the-loop tools exist: Greenlite, Webhands, and relayg. They are built around the assumption that an agent will propose and a person will approve before the irreversible thing happens. I know the current fashion is full autonomy, and I understand the appeal. But a system that can take an unrecoverable action without a checkpoint is not more advanced, it is just less careful. The gate is not a lack of ambition. It is where I decided the risk was not worth the convenience.

Make regressions fail loudly

The last principle is about time. A system that is trustworthy today can rot quietly, because prompts, models, and data all move underneath you. If a regression can slip in without anyone noticing, then all the earlier work has a short shelf life.

evalgate is prompt regression CI: it treats prompt behavior like code, so a change that degrades quality fails the build instead of shipping. voiceeval does the equivalent for voice agents, where the failure modes are harder to eyeball and therefore easier to miss. The shared belief is that quality you do not continuously test is quality you are slowly losing. Loud failure is a feature. Silence is the bug.

What this does not buy you

I want to be honest about the ceiling here, because overclaiming would undercut the entire argument. None of these tools make a model correct. A permission-aware retriever will faithfully return the wrong-but-authorized document. A signed receipt will faithfully sign a bad answer. A regression test only catches the regressions you thought to write. What this infrastructure buys is not correctness. It is checkability: the ability to constrain, to inspect, to gate, and to notice. A checkable wrong answer is one you can catch. An unattributable, unconstrained, silent wrong answer is one that ships.

I have made my peace with that ceiling. I would rather build systems that are honest about what they cannot guarantee than systems that feel trustworthy and are not.

Where I am headed

The direction I care about now is making these principles compose instead of standing alone. A boundary that emits a receipt. A receipt a human gate can act on. A gate whose decisions feed the next regression test. Each tool proves a single point today; the work ahead is the connective tissue that turns them into one posture rather than a shelf of parts. That is what I mean by trustworthy AI infrastructure. Not a model I believe. A system I can check.

From Open-Source Programs to Shipping My Own AI Tools

Royal Simpson Pinto — Sat, 19 Sep 2026 09:30:29 +0000

I did not start out knowing how to build things. I started out reading other people's code, getting confused, and slowly learning how real software actually gets made. A lot of that learning happened inside open-source mentorship programs, and looking back, those programs shaped almost everything about how I work today.

The programs that raised me as an engineer

Over the last few years I took part in three structured open-source programs: Google Summer of Code, the Linux Foundation mentorship program (LFX), and Symmetry Autumn of Code. Through them I contributed to open-source compilers and networking systems. That was a big jump for me. Compilers and networking are not the friendliest places to learn. They are large, they are old, and they assume you already understand a lot before you touch anything.

That difficulty turned out to be the point.

The first thing these programs taught me was how to work inside a real codebase I did not write. Not a tutorial project, not a fresh repo I could shape however I liked, but a living system with history, conventions, and reasons behind decisions that were not always obvious. I had to read before I could write. I had to figure out why a piece of code existed before I could safely change it. That skill, reading unfamiliar code with patience instead of panic, is probably the most useful thing I own.

The second thing was mentorship. Having someone more experienced look at my work and tell me honestly what was wrong changed how fast I grew. Not vague encouragement, but specific feedback: this approach will not scale, this edge case is unhandled, this is not how the project does things. It stung sometimes. It also made me better in weeks in ways that would have taken me months alone.

The third thing was shipping reviewed work. In these programs you do not just write code and walk away. You open it up, you defend it, you revise it, and eventually it gets merged into something people actually use. Learning to take a change all the way from idea to reviewed, accepted contribution is a complete skill on its own, and it is very different from just making something work on your own machine.

The habit that carried over

Somewhere along the way, contributing to open source stopped being a program I signed up for and became a daily habit. I build open source almost every day now. Over the course of a year that added up to more than three thousand contributions, though honestly the number matters less than the routine behind it. Showing up consistently, in small pieces, is what compounds.

That habit is what eventually pushed me from contributing to other people's projects toward building my own. Recently I shipped a suite of AI-infrastructure tools: vaultrag, mcp-audit, agentrace, evalgate, voiceeval, answerproof, ctxlens, and injection-arena. They sit around the problems that show up when you actually try to run AI systems in the real world, things like retrieval, auditing, evaluation, and observing what agents are doing.

Here is the part I want to be honest about. Building these tools did not feel like a heroic leap. It felt like the same muscles I built in those programs, pointed at problems I cared about. Read the landscape first. Understand the existing systems before adding to them. Ship something small and real instead of something big and imaginary. Treat feedback as fuel, not as an attack. None of that is specific to AI. It is just how you build software that other people can trust and use.

The honest hard part

I do not want to make this sound smooth, because it was not. The hardest thing for me was the gap between feeling behind and being behind. In big, serious codebases, especially compiler and networking work, it is very easy to look around and assume everyone else understands everything and you are the only one lost. For a long time I let that feeling slow me down. I hesitated to ask questions because I did not want to look like I did not belong.

What eventually helped was realizing that the confusion was not a sign I was in the wrong place. It was the normal texture of doing hard work. The experienced people were not confused less. They were just more comfortable being confused, because they had learned that confusion is where the actual learning lives. Getting comfortable with not knowing, and asking anyway, was harder for me than any technical concept.

If you want to start

A few things I would tell someone standing where I stood a few years ago.

Pick a real project and read it before you try to change it. Do not rush to your first contribution. Spend time understanding how the thing is put together. Your early value is often in small, careful fixes, not big rewrites.

Apply to the structured programs. GSoC, LFX, and others like them give you something hard to get on your own: a mentor whose job is to help you, and a real deadline to ship against. That combination is rare and worth a lot.

Get used to feedback early. The sooner you stop taking code review personally, the faster you grow. A reviewer pointing out a flaw is giving you a gift, even when it does not feel like one in the moment.

Build the habit, not the highlight. Small contributions almost every day will take you further than occasional bursts. Consistency is quietly the whole game.

And when you feel lost, keep going anyway. That feeling is not proof you do not belong. It is usually proof you are learning something real.

Closing

I am genuinely grateful to the open-source programs and the people who mentored me through them. They took someone who could barely navigate a large codebase and taught me how to read, contribute, and eventually build. If you are early in this and it feels overwhelming, that is normal, and it does get better. Start small, stay consistent, and let the work compound. I am still doing exactly that, and I hope to keep doing it for a long time.

How Do You Actually Test an AI System? A Layered Strategy From Five Tools I Built

Royal Simpson Pinto — Thu, 17 Sep 2026 09:30:31 +0000

Every engineer who has shipped an LLM feature eventually hits the same wall. Your unit tests are green. Nothing throws. And yet the thing is quietly, obviously worse than it was last week. Someone swapped a model, someone tweaked a prompt, someone added a tool, and the output did not error, it just got dumber. No stack trace ever tells you that.

I have spent a while building tools that try to answer one question honestly: how do you actually test an AI system? Not demo it. Test it. Below is the layered strategy I landed on, mapped to five open-source projects I wrote to make each layer real.

Why testing AI is different from testing code

Two things break the assumptions you carry over from normal software.

The first is nondeterminism. The same input can produce different output on two consecutive calls. A test that asserts equality against a golden string is either flaky or a lie.

The second is deeper: there is often no single right answer. "Summarize this ticket" has a thousand acceptable outputs and a thousand bad ones, and no assertEqual can separate them. The output is not correct or incorrect, it is better or worse, more grounded or less, safe or unsafe. Traditional testing asks "did it match?" AI testing has to ask "did it regress?" and "can I trust this particular answer?"

That reframing is the whole game. You stop trying to prove correctness and start building signals: layered, honest, mostly comparative. Here is how I stacked them.

Layer 1: Evals as a build artifact

The base layer is evals, and the trick is to treat quality like something CI can measure, not vibes you check by hand.

evalgate is prompt and agent regression CI. You write a declarative eval suite that lives in version control next to your code, it runs the suite, scores it, and stores a baseline. On every pull request it re-runs, computes the quality delta against the base branch, and fails the build when the score drops, then posts the delta table as a PR comment.

The important design choice: it does not ask "is this good?" It asks "is this worse than it was?" That is the only question CI can answer objectively. It ships ten scorers, including exact match, regex, JSON-schema, embedding similarity, LLM-as-judge, latency and cost budgets, and weighted rubrics, so you can score the fuzzy stuff and the strict stuff in the same pass. And because it runs on a deterministic mock provider, the whole thing works with zero API keys, offline. A quality gate that needs a paid key to run is a quality gate people turn off.

Layer 2: The modality your text evals cannot see

Evals over text are necessary and completely blind to whole classes of failure. Voice is the sharpest example.

voiceeval exists because if you evaluate a voice agent by reading its transcript, you are evaluating a text agent that happens to have been spoken. The demo failure that made this click for me: a caller asks for a refund, the agent refunds, the transcript agrees with itself perfectly. The caller said "fifteen." The agent heard "fifty." Read the transcript and the call is flawless.

The fix is a truth field in the input: what the caller actually said, alongside what the STT heard. Without it, mis-hearing is undetectable by construction, and voiceeval has a test that documents exactly that limitation. From there it catches things a text eval scores as a perfect call: misheard numbers, consequential actions taken without a confirmation, dead air where callers hang up, responses so slow the call already failed. The lesson generalizes past voice: every modality has failures that are invisible in the representation you happen to be evaluating.

Layer 3: Record and replay

Once you have scorers, you need something to score against that reflects real behavior over time. That is replay.

Tracecase is CI for agents built on record and replay. You define a suite of agent test cases, your CI runs them against the current agent config and POSTs the results, and Tracecase diffs the new run against the previous run of the same suite. It computes what regressed (passed before, fails now) and what got flagged (any safety flag such as a tool call that was not allowed), and returns a shouldFail signal you wire straight into your CI exit code. The dashboard shows per-case REGRESSED and FIXED diffs with the offending output and tool calls, so a prompt bump that quietly breaks one case cannot slip through as an aggregate that still looks fine.

Layer 4: Trust individual answers with receipts

Regression gates protect the system over time. They say nothing about whether one specific answer, right now, can be trusted by someone who was not there.

answerproof attaches a cryptographically signed, tamper-evident receipt to every generated answer: which sources were retrieved, which the answer actually used, under whose permissions, with which model and parameters, plus a content hash of each source and a Merkle root over the retrieval set. Anyone can later verify a receipt independently, with nothing but the receipt and the library. It turns "trust our logs" into "verify it yourself," which matters when the leaked document or the compliance question shows up three months later.

I am careful about what it claims. A receipt proves integrity, source authenticity, set membership, and a transparent record of which claims are grounded in which sources. It does not prove truth. A well-grounded claim can still be wrong if the source is wrong, and the citation binding is n-gram overlap, an auditable signal, not a judge.

Layer 5: Observability over what agents actually did

The last layer is watching the runs you already have. When you fan out ten subagents and each returns a confident wall of text, generation is not the bottleneck, verification is, and you cannot verify what you cannot see.

agentrace reads Claude Code session transcripts, shows what your agents actually did, and flags the results you should not trust. No instrumentation, no SDK, because the sessions are already on disk. Every check comes from a real failure across roughly 150 research subagents: an agent concluding a company was not hiring because an API returned an empty list (that API returns empty with HTTP 200 for accounts that do not exist), hedged claims that hardened into facts downstream, twenty URLs cited and none opened, agents dying on session limits mid-sweep. Run against the session that motivated it, it flags 36 of 152 runs, and the most useful number is the 12 where I forgot to specify an output shape. Most agent tooling assumes the model is the problem. Often the prompt was.

The one honest caveat

None of these tools tell you what is true. That is not a gap I plan to close, it is the nature of the problem. evalgate tells you the score dropped, not that the new answer is wrong. agentrace and voiceeval are heuristics over text: they tell you what to go read, not what is true, and severity is deliberately conservative because a checker that cries wolf gets switched off, which is worse than no checker. answerproof proves an answer was grounded and unaltered, not that it was correct. Testing an AI system does not give you a green checkmark that means "correct." It gives you layered signals that catch getting worse, catch the invisible failure, and let someone else verify what happened. That is a smaller promise than unit tests make, and it is the honest one.

If any of this is useful, all five are open source at github.com/royalpinto007.

Shipping an embeddable widget behind one script tag on Cloudflare's free tier

Royal Simpson Pinto — Tue, 15 Sep 2026 09:30:29 +0000

Collecting testimonials is easy. Showing them is where everything falls apart.

You get a nice DM. Someone leaves a glowing comment. A customer emails you something kind. And then it just sits there. To actually put it on your site you screenshot it, crop it, drop the image into your page, and hope the alignment holds up on mobile. Six testimonials later you have six images of six different sizes, no way to moderate what shows, and no idea whether anyone who saw them clicked through. The next time you want to add one, you do the whole dance again.

I wanted the boring version of this to be one step: paste a script tag, and a wall of approved testimonials appears. That is ProofClip.

The core idea

ProofClip is a testimonial wall and social-proof generator for creators and small SaaS. There is a shareable form to collect testimonials, a dashboard to approve or hide them, a public wall of love, and an embeddable widget that drops into any site with a single tag:

<div data-proofclip="your-space-slug"></div>
<script src="https://your-proofclip.example/widget.js"></script>

That is the whole integration. No React, no iframe, no build step on your end. The data-proofclip attribute names which space to render, and the script does the rest.

The whole thing runs on Cloudflare's free tier: Workers plus Hono for the API and the server-rendered pages, D1 (SQLite) for relational data, and R2 for uploaded images. There is no separate frontend build. The widget and card scripts are served as plain strings straight from the Worker.

How it works

Collection. Each workspace gets a public form at /c/<slug>. It takes text, a star rating, an optional photo, and a permission flag so the person is explicitly agreeing to be shown. You can also import proof you already have: POST /app/import lets you upload a screenshot of a DM, a comment, or a review, so testimonials that were never going to fill out a form still make it onto the wall.

Every testimonial lands in D1 with a status. The schema is blunt about it:

status TEXT NOT NULL DEFAULT 'pending', -- pending | approved | hidden

So nothing is public by default. New submissions sit in pending until you say otherwise.

Moderation. The dashboard at /app is where you approve, hide, or delete, all through POST /app/testimonial/:action. Because the public wall and the widget only ever read approved rows, moderation is the gate for everything downstream. There is a settings route too (/app/settings) for branding: name, accent color, logo, and a toggle for the "Collected with ProofClip" credit.

The wall and the widget. There is a hosted public wall at /w/<slug>, and there is the embed. The widget script finds every [data-proofclip] node on the page, fetches /api/wall/<slug> for that space, and renders a masonry-style column layout using CSS column-width, so cards flow into however many columns fit. All user text is escaped through a throwaway DOM node before it touches innerHTML, so a testimonial cannot inject markup into someone else's page. If branding is enabled for that plan, a small ProofClip credit is appended.

The widget also does light analytics. On render it fires a view event via navigator.sendBeacon, and it records a click event on interaction, both to POST /api/event. That is how a workspace sees widget views and clicks without any third-party tracker.

Cards. For turning a single testimonial into a share-ready image, /card.js runs a client-side canvas that exports a PNG in 9:16, 1:1, or 16:9. No paid image API is in the loop; the rendering happens in the browser. The card studio is gated to Pro and above.

Plans. Limits live in src/plans.ts and are enforced server-side, not just hidden in the UI. Free allows one space, ten testimonials, and one widget, with the branding credit on. Starter ($19) raises the testimonial and widget caps and lets you remove branding. Pro ($39) unlocks unlimited testimonials, multiple spaces, and the card generator. Agency ($79) goes wider still. The accounts.plan column is the single source of truth, and a protected webhook (POST /api/billing/activate, plus a Gumroad-shaped route) flips it after a purchase.

One honest limitation

The paid-tier roadmap is real work that is not done yet. Video testimonials, custom-domain wiring, team seats, and multiple widget configs per space are listed as not built. The data model was designed to support them, but "the schema has a column for it" is not the same as "it ships." There is also no provider-specific webhook signature verification yet. Billing activation is guarded by a shared secret header, which is fine for a hosted payment link plus a webhook, but it is not the same as verifying a signed payload from a specific provider. If you deployed this to take real money, that is the first thing I would harden.

I would rather say that plainly than imply the feature grid is fuller than it is. The collect, moderate, embed, and card loop is the part that actually works end to end, and that is the part most people needed anyway.

Why this shape

Most testimonial tools are either a heavyweight SaaS with a monthly floor that does not make sense for a solo creator, or a pile of manual screenshots. I wanted the middle: something a single person can self-host on a free tier, that treats moderation as a first-class step, and that embeds with the least possible ceremony. Serving the client scripts as strings from the Worker, keeping the data in D1, and putting images in R2 means there is no infrastructure to babysit and nothing that bills you while it sits idle.

If you want to walk the flow yourself, the README covers local dev: sign up, grab the API key, open the collection link, submit a testimonial, approve it, and view the wall and the embed.

Repo: https://github.com/royalpinto007/ProofClip

I built BoardEject: an open-source Apple Freeform Excalidraw converter

Royal Simpson Pinto — Sun, 13 Sep 2026 20:05:31 +0000

I wanted a way to get editable content out of Apple Freeform instead of only ending up with a flattened PDF.

So I built BoardEject.

The basic flow is:

Freeform → BoardEject → editable .excalidraw

Where supported, BoardEject preserves things like:

shapes
text
connectors
groups
drawings
tables
images

Unsupported or unverified structures are reported instead of silently pretending the conversion worked.

The interesting part has been validating behavior against real macOS Freeform captures rather than only synthetic fixtures.

It’s local-first, open source, and the board content isn’t uploaded to a server.

Try it:
https://boardeject.dev

Source:
https://github.com/royalpinto007/boardeject

I’m still working through native edge cases, so feedback from people who use Freeform or Excalidraw heavily would be useful.

Parsing bank statements in memory: keep the fields, store nothing else

Royal Simpson Pinto — Sun, 13 Sep 2026 09:30:29 +0000

Most personal finance apps ask you to hand over a lot. You connect a bank aggregator, or you upload a PDF statement, or you snap a photo of a receipt, and then that raw artifact lives somewhere on a server. The statement that lists every place you spent money for a month. The receipt image with your card's last four digits on it. Even when a company means well, the raw file is now a liability it has to protect, and a thing that can leak.

I kept coming back to a simpler question while building PennyRush: what does a money tracker actually need to keep? Not the file. It needs the numbers. It needs to know that on a given date you spent an amount at a merchant, and roughly what category that falls under. The original document is just a transport format for those few fields. So the design goal became: extract the fields, then throw the file away before it ever touches disk or a server.

The core idea

PennyRush is a native Android app (Kotlin and Jetpack Compose) plus a Next.js web companion, both talking to one Supabase backend. The privacy contract is deliberately narrow and written down in the repo: there is no object storage in v1. When you import a statement or scan a receipt, the file is read into memory, parsed into candidate transactions, and then dropped by the client flow. It is never written to disk, object storage, analytics, or logs. What persists is only the saved activity fields: amount, date, merchant, note, type, and category.

That constraint shapes everything else. If you are not allowed to keep the file, you have to be good at pulling structure out of it on the spot.

How statement import works

CSV import is fully on-device and rules-based. The parser (StatementParser) takes the file text and does a few defensive things before it trusts anything. It rejects blank files, and it runs a quick binary check: if more than 5% of the first 4KB is non-printable, it assumes you handed it a PDF or an image by mistake and tells you to download a spreadsheet version instead. There are hard caps too, a 5MB byte limit and a 20,000 line limit, so a malformed or huge file cannot hang the import.

Then it hunts for the header row instead of assuming row zero. It scores each line on whether it contains a date-like column, a money-like column (amount, debit, credit, withdrawal, deposit), and a description-like column (narration, particulars, payee, memo, and so on). Banks all name these differently, so the matching is fuzzy on purpose. Once it locks onto the header, it maps the specific column indices, handles the amount-versus-separate-debit-and-credit case (a debit becomes a negative amount, a credit stays positive), and parses each row.

Amount parsing has to survive real-world messiness: currency symbols, thousands separators, Rs., INR, USD prefixes, and accounting-style parentheses for negatives all get stripped or interpreted. Dates are tried against a list of common formats before falling back to ISO parsing. Rows with out-of-range dates (more than 50 years past or 10 years future) or absurd amounts are skipped and counted, so if nothing imports the app can tell you why rather than just failing silently.

How receipt scanning works

Receipt scanning uses on-device OCR through ML Kit's text recognizer. You pick an image or take a photo, the app runs TextRecognition locally to pull the text out, and then it builds a candidate transaction from the recognized lines for you to review before saving. The recognizer is closed as soon as it succeeds, fails, or the coroutine is cancelled. If the read is low-confidence or empty, you still get an editable draft with a warning rather than a dead end. The important part is that the OCR happens on the phone, and the only thing that can end up in the database is the handful of fields you confirm.

Turning a description into something readable

A raw bank line like UPI/1234567890/SWIGGY/PAYTM is noise to a human. MerchantExtractor classifies the transaction kind first (UPI, card, transfer, ATM, salary, bill) using keyword patterns, then tries to recover the actual merchant. It splits the string on separators, drops tokens that look like reference numbers, VPAs, pure digits, or known noise words (UPI, NEFT, REF, PAYTM, and friends), and scores the survivors, rewarding letters and penalizing digits, to pick the most name-like token. From there CategorizationRules maps merchants to categories with a plain keyword table: Swiggy and Zomato become Food, Uber and Ola become Transport, Netflix and Spotify become Entertainment, and so on. Income and transfers are handled by sign and kind rather than text.

All of this is intentionally simple and deterministic. The README is honest that categorization and insights are rules-based today. If server-side AI is added later, the stated rule is that clients never receive model API keys and payloads stay minimized, but none of that is required for the current app to work.

One honest limitation

Rules-based extraction is transparent and private, but it is not magic. The keyword tables cover common Indian banks and merchants well and degrade gracefully to an "Other" category everywhere else, which means the first import from an unusual bank or a foreign merchant list will need some manual correction. Because I refuse to keep the raw file, I also cannot silently re-parse it later with a better algorithm. The tradeoff is deliberate: I would rather ship an extractor you can read in one sitting and correct by hand than a black box that keeps your statements around to improve itself. Better merchant and category coverage is ongoing work, not a solved problem.

Why the constraint is the feature

The satisfying thing about the in-memory rule is how much it removes. There is no upload pipeline to secure, no storage bucket to scope, no background job that might log a filename. The privacy story is not a policy you have to trust, it is a shape the code physically has: the file exists only for the milliseconds it takes to read the fields, and then it is gone. Everything downstream, dashboards, plans, spending insights, only ever sees the small structured records you chose to save.

PennyRush is MIT licensed and the full source (Android app, web companion, docs, and privacy contract) is on GitHub: https://github.com/royalpinto007/PennyRush

Turning a Company Website into a Sales-Ready Prospect Record with a Browser Extension

Royal Simpson Pinto — Fri, 11 Sep 2026 09:30:29 +0000

Sales research is mostly reading. You land on a company's website, click around the homepage, the about page, the product pages, and try to answer a few boring but essential questions: what does this company actually do, who is their customer, are they a fit for what I sell, and who should I email. Then you write the email. Then you do it again for the next company, and the next, until the tab count is a personal insult.

I built SignalizeAI to collapse that loop. It is a browser extension, shipped on both the Chrome Web Store and Firefox Add-ons, that turns a public company website into a usable prospect record. It has real users today, and this post is about how the pieces fit together.

The core idea

The unit of value is a prospect record. Point the extension at the site you are looking at (or paste any URL) and it runs a Quick Website Check, then presents the results in a tabbed insights flow: Strategy, Emails, and Snapshot.

The Strategy side generates the research a rep would otherwise assemble by hand: what the company does, a company overview, their value proposition, their target customer, a sales-readiness read, a recommended buyer persona, a likely goal, and an outreach angle. The Emails side turns that into something you can actually send: three different outreach approaches, one recommended email, and follow-ups.

The point is not "AI wrote an email." The point is that the research and the message come out of the same pass over the same source, so the email is grounded in what the company's own site says rather than a generic template with the company name pasted in.

How it works: the extension

The extension is Manifest V3, written in TypeScript, and bundled with esbuild. Manifest V3 shapes a lot of the architecture. There is no persistent background page, so the flow is built around message passing and a backend that holds the heavy logic rather than the extension trying to be smart on its own.

One detail I care about is that the extension does not blindly re-analyze. If you have already saved a prospect for a website, it shows the saved analysis by default instead of burning a fresh run on a site you have already researched. Every saved or unsaved analysis can be opened on the web app through an Open in website action, so the extension is a fast capture surface and the web app is the durable workspace.

Batch Prospecting is where it stops being a toy. You can upload a CSV or paste a list of URLs, run them, multi-select which results to save, and generate outreach and follow-ups in bulk, then export the whole thing to CSV or Excel. For large runs there is a compact batch analysis mode that trades some depth for speed, and there is a resilient fallback path that still produces email content when an AI response fails mid-run, so one bad response does not sink a batch of a hundred.

How it works: the web app and sync

The extension is paired with the web app at signalizeai.org, and the two stay in sync rather than being separate products that happen to share a login. Saved prospects live in a workspace at /prospects with search and filtering, status tracking, inline status editing, and copy, open, and delete actions.

The interesting part is that the extension and the website share the same prospect data and reflect each other live. The extension listens to the site for auth state, sign-out, theme changes, prospect status updates, prospect content refreshes, and install detection. Change a prospect's status on the website and the extension sees it; save from the extension and it appears in the web workspace. To keep that bridge safe, the production manifests only inject the website bridge script on signalizeai.org. Dev manifests additionally allow localhost so I can run the web app locally against the extension without opening that channel up in production.

How it works: auth, storage, and billing

Auth and storage run on Supabase, with Google sign-in. Supabase is also where saved prospects are stored, which is what makes the shared-data model between extension and website straightforward: both talk to the same backend and the same user identity.

The analysis and generation work is served by a Cloudflare Workers backend. Workers is a good fit here because prospecting is bursty and latency-sensitive, and running the request-handling logic on the edge keeps it responsive without me babysitting servers. The extension is configured per environment: a dev build points at a dev API host and localhost, while production points at the live API. Plan limits are enforced on that backend, so the free and paid tiers are a real boundary in the service rather than something the client politely respects.

An honest limitation

SignalizeAI reads what a company chooses to publish. If a website is thin, vague, or mostly a login screen, the research is only as good as that surface. A sparse marketing site produces a sparser prospect record, and the sales-readiness read reflects the signal that is actually there, not private data the company never put online. In practice this means the tool shines on companies with real content and is weakest exactly where a human would also struggle. The batch fallback helps keep a run from failing outright, but a fallback email is a safety net, not a match for a clean generation on a rich site. I would rather be upfront that this is a research accelerator over public information than pretend it manufactures signal that does not exist.

Closing

The version of SignalizeAI users are running today is the result of a lot of unglamorous work: Manifest V3 message passing, a two-way sync bridge that has to be locked to a single origin in production, batch runs that survive individual failures, and plan limits enforced where they cannot be bypassed. The payoff is simple to describe. Open a website, get a prospect record and an email grounded in what that company actually says about itself, and keep the whole thing in a workspace that the extension and the site share.

It is live at https://signalizeai.org, on both the Chrome and Firefox stores, with real users. If you do outbound and are tired of the tab pile, that is exactly who I built it for.

Designing an offline-first planner that repairs your day instead of shaming you

Royal Simpson Pinto — Wed, 09 Sep 2026 09:30:29 +0000

Most planners I have tried ask for too much before they give anything back. You make an account, you sync to a cloud you did not ask for, and then you get judged: streaks broken, tasks glowing red, a little counter reminding you how many days you missed. The tools that are supposed to reduce the friction of a day end up adding a layer of guilt on top of it.

I wanted the opposite. So I built Tiny Day, a cozy daily planner for Android. Your day, made manageable. No account, no cloud, no analytics.

The core idea: gentle and local

Two commitments shaped every decision.

The first is offline-first. Tiny Day is a React Native app built with Expo (SDK 57). There is no application backend at all. You brain-dump your day in plain language, the app shapes it into a timeline, and everything you type lives on your device. That is not a marketing angle bolted on afterward; it is the architecture. Expo Router owns navigation, Zustand stores own the state, and AsyncStorage persists it. When I say planning is deterministic and local, I mean the scheduler runs on your phone with your data and produces the same result every time. No round trip, no server, works on a plane.

The second is gentleness. Tiny Day never vibrates. It has no streaks. When you do not finish something, it never auto-carries it to tomorrow behind your back. The whole emotional posture of the app is captured in two lines it actually says to you: "Your day has been repaired," and at night, "You did enough for today."

How it works

The flow starts in the morning. You do not fill in a form field by field. You brain-dump, in plain language, and lib/parse.ts interprets that text into task cards, pulling out a name, a category, a duration, a priority, and time heuristics. From there lib/schedule.ts does a priority and energy pass and lays out a timeline. Crucially, it protects meals and deliberately keeps free time open. A planner that fills every minute is just a different kind of stress, so leaving gaps on purpose is a feature, not an oversight.

Priority in Tiny Day is three tiers, and they are shown as a glyph plus a label, never color alone:

▲ must gets a reminder plus one follow-up
● should gets a single reminder
○ optional stays silent

Notifications are local only, scheduled on the device through expo-notifications. There are quiet hours, and a privacy mode that shows a generic "Important reminder due now" instead of leaking the task name onto your lock screen. At most one gentle replan prompt. That is the ceiling on how much the app is allowed to nag you.

The Room is the part I am fondest of. It is a layered SVG scene (built with react-native-svg) with a window sky, a lamp glow, a tint overlay, and a tiny character. It has four time states plus a rain variant, it follows the real clock, and it brightens as you complete things and dims into lamplight at night. It is ambient feedback that carries no numbers and no pressure.

Then there is the feature that named the whole design philosophy: "My day went wrong." Real days fall apart. You wake late, a task runs long, you get too tired, an urgent thing lands. Instead of watching the plan turn into a wall of overdue items, you tap what changed. The repair engine in lib/repair.ts moves optionals, shortens flexibles, protects your ▲ musts and any fixed appointments, and inserts rest. Then it shows you exactly what it is about to change before it applies anything. You stay in control; the app just does the tedious reshuffling. And because repair is deterministic and local like the scheduler, it is fast and predictable.

The day closes with an evening review: a mood check-in, gentle stats, and leftovers triage where you decide, per item, whether something goes to tomorrow, to the backlog, or you simply let it go. Nothing moves on its own.

A few things I made sure not to skip. Accessibility is real: 44px and larger touch targets, dynamic type, reduce-motion and high-contrast toggles, and screen-reader labels. There is a Plan tab with tomorrow, an expandable week, a backlog, and a routine builder. And the Profile can load and remove reversible sample data so you can explore the app without polluting your own tasks.

One honest limitation

The natural-language parsing is a heuristic, not a language model. lib/parse.ts reads your brain-dump with rules for durations, categories, priority cues, and time hints. That is exactly why it can run fully offline and stay deterministic, which I consider a fair trade. But it means phrasing the parser has not seen can land in the wrong category or miss a time you clearly implied. The app leans on this by letting you edit any task in place or reschedule it to an explicit future date and time, so a miss is a quick correction rather than a dead end. Still, if you are expecting the free-form understanding of a cloud AI assistant, this is a simpler, more predictable engine, and I would rather be honest about that than oversell it.

There is also a practical packaging note: the current v1.1.0 APK is ARM64-only, which covers most modern phones and tablets but means a 32-bit-only device needs a separately configured build. Tiny Day targets Android 7.0 (API 24) and newer.

Try it

Tiny Day is open source under the MIT license. It is a fully offline React Native app: no account, no cloud, no analytics, and no vibration. If a planner that repairs your day instead of shaming you sounds like the kind of tool you have been missing, the code and the latest Android release are here:

https://github.com/royalpinto007/Tiny-Day

You did enough for today.