DEV Community

I built a zero-dependency CLI to audit hreflang (international SEO)

Dr. Reza Madahzadeh — Wed, 26 Aug 2026 06:19:32 +0000

If your site serves multiple languages, hreflang is where SEO quietly breaks: page A links B, B never links back; someone writes en_US instead of en-US; an alternate points at a redirect; the target canonicalizes somewhere else. None of it is visible in the browser — all of it costs you in the SERPs.

hreflang-audit is a single-file Node.js 20+ CLI with zero npm dependencies. It crawls your site (or parses your XML sitemap, sitemap-index included), reads <link rel="alternate" hreflang> elements, HTTP Link: headers, and xhtml:link sitemap entries, and runs 11 checks — from invalid ISO codes (with hints like en-UK → en-GB) to missing return links and canonical conflicts.

Every finding comes with a fix hint. Output is a human-readable report, or --json for machines, with exit codes designed for CI. There's also a composite GitHub Action so you can run it on a weekly schedule and fail the build when hreflang regresses.

Try it in under a minute (no npm install)

git clone https://github.com/madahzadeh/hreflang-audit.git
cd hreflang-audit
npm run demo   # offline demo with seeded issues
node hreflang-audit.mjs https://example.com/   # audit a real site

What it checks

Code	Check
E001	invalid ISO language/script/region codes
E002	underscore locales (`en_US`)
E003	relative hreflang URLs
E004	missing return links
E005	conflicting entries (same lang, two URLs)
E006	broken target URLs
W101–W105	missing self-reference / x-default, redirected targets, canonical mismatches, duplicates

Honest limitations

HTML is parsed with tolerant regexes rather than a full DOM, JavaScript-rendered pages are not executed, and it complements — not replaces — Search Console's reports.

Repo: github.com/madahzadeh/hreflang-audit — MIT licensed. Feedback and issues welcome; sitemap/HTML mismatch detection is next on my list.

Designing a Zero-Trust Authorization Layer for Collection Actions

MATT ROSE — Wed, 26 Aug 2026 06:14:05 +0000

Most recovery technology is built for execution throughput: dialing numbers, streaming SMS, rendering demand letters,
syndicating portfolios, reporting tradelines, or dispatching field agents. The harder architectural problem is distributed across multiple autonomous systems:

Is this specific actor authorized to perform this specific action on this account across this channel right now?

An account eligible during Monday's batch pipeline is not necessarily eligible when the worker thread fires. A payment
clears in the core ledger. Consent is revoked via SMS. A formal dispute is received by outside counsel. A bankruptcy docket
update lands in servicing. When downstream tools act on stale snapshots, the failure is not a lack of rules—it is just-in-time
authorization over fragmented, asynchronous state.

Treating Recovery Actions as Zero-Trust Resources Mapping NIST SP 800-207 Zero Trust Architecture directly onto recovery operations separates decision logic from execution logic:

• Policy Information Points (PIP): Creditor ledgers, servicing platforms, payment gateways, dispute queues, court
scrapers, and consent registries supplying timestamped facts.
• Policy Decision Point (PDP): The deterministic adjudication engine that evaluates normalized facts against immutable,
versioned policy packs.
• Policy Enforcement Point (PEP): The dialer daemon, SMS proxy, CRA reporting worker, or case management gateway
that strictly fails closed without a valid permit.
• Policy Administrator (PA): The service managing real-time cryptographic permit issuance, verification, and revocation.
The core operational axiom: No current, valid authorization → No execution.

Universal Action Request Contract The request contract remains invariant across communication channels and legal actions. It uses privacy-preserving pseudonymous references (HMACs) rather than raw PII payloads:

{ "request_id": "req_01J9X8K2M1N7", "tenant_id": "issuer_corp_001", "executor": { "organization_id":
"agency_partner_44", "system_id": "dialer_cluster_east", "operator_id": "agent_772" }, "subject_ref":
"subj_hmac_8f9a2...", "account_ref": "acct_hmac_3c1b7...", "action": "CALL", "channel": "VOICE",
"destination_ref": "dest_hmac_9e4d1...", "requested_at": "2026-08-26T15:42:19Z", "context": { "purpose":
"COLLECTION", "jurisdiction": "US-FL" } }

Fact Provenance & The Four Epistemic States Incoming evidence cannot be accepted without cryptographic and temporal provenance. Facts carry verification tier, observation timestamps, and explicit TTL windows. The resolver must strictly classify evidence into four states:

1. MISSING: A mandatory statutory or policy fact is absent from the graph.
2. STALE: The fact exists but exceeds its maximum allowed freshness window.
3. CONFLICTING: Two independent authoritative sources contradict each other (e.g., active consent vs. opt-out
timestamp).
4. INVALID: The value violates schema, physical reality, or statutory preconditions.

This creates a vital boundary: BLOCK means the system possesses verifiable evidence that an action is unlawful or
suppressed. NO_USABLE_RESULT means the system cannot guarantee safety and must fail closed. Conflating the two
invites unmeasured fallback risk.

Deterministic Decision Engines vs. Probabilistic LLMs LLMs are suited for extracting facts from unstructured legal notices, reconciling dirty records, and preparing human review summaries. LLMs must never make the final authorization decision. The decision function must remain pure and deterministic: f(Normalized Facts, Policy Version, Timestamp) → Decision Packet.

{ "decision_id": "dec_01J9X8K9Z4", "outcome": "BLOCK", "requested_action": "CALL", "reason_codes":
["CONSENT_REVOKED", "OPT_OUT_NEWER_THAN_CAMPAIGN"], "policy": { "pack": "US_CONSUMER_CONTACT", "version":
"2026.08.24", "hash": "sha256:7c9..." }, "facts_hash": "sha256:4f1a2...", "decided_at":
"2026-08-26T15:42:19.012Z", "evidence_ref": "ev_01J9X8K9Z4" }

Sender-Constrained Permits & Durable Receipts Conventional bearer JWTs are unsafe for high-consequence operations. An Action Permit must be sender-constrained via cryptographic proof-of-possession (RFC 9449 DPoP), audience-restricted, single-use, and short-lived (e.g., 30-second TTL). The architecture cleanly splits authorization into two artifacts:

• Action Permit: Minimal, ephemeral credential verified by the PEP at runtime.
• Decision Receipt: Append-only immutable record stored with full evidence lineage for audits.

Closing the Loop: Execution Receipts
Authorization without verified execution creates an unobservable gap. The PEP must return an Execution Receipt
confirming when and how the action occurred, forming a complete cryptographic chain: Request → Decision → Permit →
Execution → Receipt → Audit Graph.
Real-Time Revocation & State Synchronization
Short TTLs reduce exposure, but critical events (cures, bankruptcy filings, attorney notices) happen asynchronously. The
architecture requires a sub-second revocation bus. A system advertising 5ms decisions is unsafe if an account recall takes
15 minutes to reach the dialer.

Conclusion
Regulatory exposure in collections stems from broken state synchronization across distributed systems. Building an
independent zero-trust authorization plane solves this failure mode permanently.

Your systems execute. Quorum CAS-1 decides whether the action is authorized.

References

NIST SP 800-207: Zero Trust Architecture

RFC 9700: OAuth 2.0 Security Best Current Practice

RFC 9449: Demonstrating Proof of Possession (DPoP)

CFPB FDCPA Annual Report 2025

Configurar Graphify para usarlo con Claude cli

oskar calvo — Wed, 26 Aug 2026 06:13:09 +0000

Instalación y uso de Graphify (Linux / WSL)

(Contenido creado con IA)

Guía paso a paso para instalar Graphify una vez en el
entorno (máquina/WSL) y luego activarlo en cada proyecto. Basada en la instalación real hecha en
drupal (ver sección 8 para las particularidades de ese proyecto).

Graphify convierte una carpeta de código/config/docs en un grafo de conocimiento consultable
(graph.json, graph.html, GRAPH_REPORT.md) y puede integrarse con Claude Code para que
consulte ese grafo antes de rastrear todo el código.

1. Qué es global y qué es por-proyecto

Elemento	Alcance	Cuándo se instala
`uv` (gestor de Python)	Global, una vez por máquina	Sección 2
`graphifyy` (el CLI `graphify`)	Global, una vez por máquina	Sección 2
API key del backend LLM	Global (variable de entorno / `.env`)	Sección 3
`graphify-out/` (graph.json, graph.html, GRAPH_REPORT.md)	Por proyecto — es el dato generado a partir de ESE código	Sección 5
`.claude/settings.json` (hook), `.claude/skills/graphify/`, sección en `CLAUDE.md`	Por proyecto	Sección 6

No hace falta reinstalar uv/graphify en cada repo. Lo único que se repite por proyecto es
generar su grafo y activar la integración con Claude Code.

2. Instalar Graphify en el entorno (una vez)

Requisitos: Python 3.10+ (ya viene en la mayoría de distros/WSL) y curl.

# 1. Instalar uv (gestiona su propio Python, no depende del venv del sistema)
curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"   # o reinicia la shell; añade ~/.local/bin al PATH

# 2. Instalar graphify como herramienta global
uv tool install graphifyy

# 3. Comprobar
graphify --version
graphify --help

Nota WSL/Debian/Ubuntu: si en algún momento usas python3 -m venv directamente y falla con
No module named ensurepip pidiendo apt install python3.X-venv (requiere sudo), no lo
instales para esto: usa uv, que no depende del módulo venv del sistema. Así es como lo
resolvimos en drupal.

2.1 Instalar el soporte del backend LLM que vayas a usar

El extractor semántico necesita un paquete de cliente extra según el backend. Instálalo con el
extra correspondiente (si no sabes cuál usarás, all los trae todos):

uv tool install "graphifyy[gemini]"     # Google Gemini
uv tool install "graphifyy[anthropic]"  # Claude
uv tool install "graphifyy[openai]"     # OpenAI
uv tool install "graphifyy[ollama]"     # modelo local, sin API key
# o directamente:
uv tool install "graphifyy[all]"

Si lo instalaste sin el extra y graphify extract falla con the 'openai'/'anthropic' package is required for this backend, reinstala con --force y el extra correcto:

uv tool install "graphifyy[gemini]" --force

(Esto nos pasó la primera vez: el backend gemini usa internamente el cliente openai, y no se
instala por defecto.)

3. Configurar la API key

Solo hace falta si vas a extraer contenido semántico (docs, config, PDFs, imágenes). El parsing de
código puro (--code-only) no requiere key.

Backend	Variable de entorno
Gemini	`GEMINI_API_KEY` o `GOOGLE_API_KEY`
Claude	`ANTHROPIC_API_KEY`
OpenAI	`OPENAI_API_KEY`
DeepSeek	`DEEPSEEK_API_KEY`
Kimi	`MOONSHOT_API_KEY`
Ollama (local)	ninguna
Bedrock	credenciales AWS/IAM

export GEMINI_API_KEY="tu-clave"

Cuidado con las comillas: si la clave está en un .env como GEMINI_API_KEY="AQ.xxx", un
cut -d'=' -f2- se lleva las comillas literales dentro del valor y Gemini responde
Please pass a valid API key. Al extraer el valor de un .env, quítalas explícitamente:
val="$(grep '^GEMINI_API_KEY=' .env | cut -d'=' -f2-)"
val="${val%\"}"; val="${val#\"}"
export GEMINI_API_KEY="$val"
Límites del tier gratuito: el tier gratuito de Gemini (gemini-3-flash) tiene límites bajos
(5 peticiones/min, 250k tokens/min). Si graphify extract falla con errores 429 RESOURCE_EXHAUSTED, repite con --max-concurrency 1 (más lento pero no satura la cuota). El
caché interno evita reprocesar lo que ya se extrajo con éxito.

4. Decidir el alcance del grafo en un proyecto

Dos formas de usarlo:

A) Graficar todo el repo (proyectos pequeños, sin vendor/, node_modules/, dumps de BD, etc.
mezclados con el código):

cd mi-proyecto
graphify extract .

B) Graficar solo unas rutas concretas (recomendado en proyectos con dependencias de terceros,
builds, backups SQL, sites/default/files, etc. que no aportan nada al grafo y disparan coste/
ruido). Se crea una copia física de solo esas rutas y se extrae sobre la copia:

cd mi-proyecto
mkdir -p graphify/source/<misma-estructura-de-carpetas>
cp -r ruta/a/incluir-1 graphify/source/ruta/a/incluir-1
cp -r ruta/a/incluir-2 graphify/source/ruta/a/incluir-2
# ... una copia por cada ruta a incluir, preservando la ruta relativa

Añade graphify/ a .gitignore para que esta copia y las herramientas no se comiteen:

echo '/graphify/' >> .gitignore

Esto es lo que se hizo en drupal: ver sección 8 para el ejemplo completo con
config/sync, módulos y temas custom/contrib concretos.

5. Generar el grafo

# Extracción completa (AST + semántica vía LLM)
graphify extract <ruta> --backend gemini

# Si el backend gratuito da 429, repetir más despacio:
graphify extract <ruta> --backend gemini --max-concurrency 1

# Generar/regenerar GRAPH_REPORT.md + graph.html con nombres de comunidad
graphify cluster-only <ruta> --backend gemini --max-concurrency 1 --batch-size 100

Flags útiles:

--no-gitignore: procesa también archivos que estén en .gitignore (útil si <ruta> es una copia aislada como en el método B, o si hay config versionada que normalmente se ignora).
--code-only: solo AST determinista, sin LLM, sin API key.
--force: fuerza re-extracción completa ignorando caché.

Resultado en <ruta>/graphify-out/:

graph.json — datos completos del grafo (nodos, edges, comunidades)
graph.html — visualización interactiva
GRAPH_REPORT.md — resumen en lenguaje natural + preguntas sugeridas

Es normal que algunos archivos de configuración muy simples (YAML triviales, toggles) no
generen nodo semántico propio — el modelo decide que no aportan nada nuevo más allá del AST. No
es un fallo; el resto del grafo (código, relaciones) sigue siendo válido.

6. Integrar con Claude Code en el proyecto

Si <ruta> del paso anterior es la raíz del proyecto, el grafo ya queda en
./graphify-out/graph.json, la ubicación por defecto que espera Graphify (hook, skill y comandos
sin --graph explícito).

Si usaste el método B (copia aislada, p. ej. graphify/source/), el grafo se genera por defecto
dentro de graphify/source/graphify-out/, no en la raíz. Muévelo una vez a la raíz (ubicación
que espera el resto de la integración):

mv graphify/source/graphify-out ./graphify-out

A partir de ahí, cualquier extract/update que vuelvas a lanzar sobre graphify/source debe
llevar la variable GRAPHIFY_OUT apuntando a esa ruta absoluta, o volverá a escribir dentro de
graphify/source/graphify-out (duplicando el grafo en vez de actualizar el de la raíz):

export GRAPHIFY_OUT="$(pwd)/graphify-out"
graphify update graphify/source        # o extract, con --backend

Una alternativa más simple si no te importa el symlink es dejar graphify-out como
ln -s graphify/source/graphify-out graphify-out: las lecturas (query, el hook, graph.html)
y las siguientes escrituras de extract/update graphify/source (que escriben en
graphify/source/graphify-out, el destino real del enlace) siguen funcionando igual sin tocar
GRAPHIFY_OUT. Mover el directorio de verdad a la raíz (como se hizo arriba) es preferible por
tenerlo en la ubicación canónica sin depender de un enlace, pero ambas opciones son válidas.

Instala la integración oficial (hook + skill + nota en CLAUDE.md), sin --strict:

graphify claude install --project

Esto crea/actualiza:

.claude/settings.json — hooks PreToolUse (advisory, nunca bloqueante sin --strict): avisan antes de un grep/Bash/Grep o de leer un archivo de código, sugiriendo graphify query primero.
.claude/skills/graphify/ — skill del comando /graphify.
CLAUDE.md — sección ## graphify con las reglas de cuándo consultar el grafo.

Revisa la sección añadida a CLAUDE.md: por defecto dice graphify update . para
refrescar el grafo tras cambios de código. Si usaste el método B (copia aislada), eso es
incorrecto — . es la raíz real del proyecto, no la copia, y lanzaría una extracción sin
acotar sobre todo el repo. Corrígelo a mano por graphify update graphify/source (o la ruta de
tu copia).

--strict es opcional y no se activó por defecto: bloquearía la primera lectura de código
por sesión hasta consultar el grafo. Con un grafo que no cubre todo el repo (método B), eso
puede bloquear tareas legítimas fuera del alcance graficado — se dejó desactivado.

7. Mantenimiento

Tras cambiar código dentro de las rutas graficadas: graphify update <ruta> (solo AST, sin coste de API). Si usaste copia aislada, primero hay que reflejar el cambio dentro de graphify/source/ (copiando el archivo modificado) y luego correr update sobre esa copia con GRAPHIFY_OUT apuntando al graphify-out/ real (ver sección 6):

  export GRAPHIFY_OUT="$(pwd)/graphify-out"
  graphify update graphify/source

Re-extracción semántica completa (por ejemplo tras añadir muchas rutas nuevas): graphify extract <ruta> --backend <backend> --force.
Desinstalar de un proyecto: graphify uninstall --project (quita hook, skill y sección de CLAUDE.md; con --purge borra también graphify-out/).

8. Limitaciones conocidas (comprobadas en la práctica)

Cobertura parcial: el grafo solo "sabe" de las rutas que se graficaron. Para cualquier otra parte del proyecto, hay que seguir buscando en el código directamente — decídselo explícitamente a Claude Code en CLAUDE.md si usas el método B.
El hook de lectura (Read/Glob) no se dispara para cualquier extensión: solo para un listado fijo de extensiones "genéricas" (.php, .js, .ts, .md, etc. — ver _HOOK_SOURCE_EXTS en el código de Graphify). En un proyecto Drupal, por ejemplo, no se dispara para .module, .install, .yml, .theme ni .twig, que es donde vive buena parte del código/config. El aviso de búsqueda (Bash|Grep) sí se dispara siempre que exista el grafo, independientemente de la extensión.
Coste y cuotas: la extracción semántica consume tokens del backend elegido. El tier gratuito de Gemini es fácil de agotar en proyectos con muchos archivos de config; usar --max-concurrency 1 lo evita a costa de tardar más.
El grafo es un punto de partida para orientarse, no la fuente de verdad — conviene verificar siempre en el código real antes de editar.

9. Ejemplo real: `drupal`

En este proyecto se usó el método B (copia aislada) porque el repo mezcla Drupal core, vendor/,
sites/default/files, dumps SQL, etc. junto al código propio. Solo interesaba graficar:

config/sync/**
web/modules/custom/*
web/modules/contrib/quiz
web/themes/custom/*
web/themes/contrib/bootstrap_barrio

Pasos aplicados (resumen; ver CLAUDE.md del proyecto para el resultado final):

# 0. Instalación global (una vez en la máquina/WSL)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install "graphifyy[gemini]"     # ~/.local/bin ya estaba en el PATH

# 1. Copia aislada de solo las rutas a graficar
mkdir -p graphify/source/config graphify/source/web/modules/custom \
         graphify/source/web/modules/contrib graphify/source/web/themes/custom \
         graphify/source/web/themes/contrib
cp -r config/sync graphify/source/config/sync
cp -r web/modules/custom/. graphify/source/web/modules/custom/
cp -r web/modules/contrib/quiz graphify/source/web/modules/contrib/quiz
cp -r web/themes/custom/. graphify/source/web/themes/custom/
cp -r web/themes/contrib/bootstrap_barrio graphify/source/web/themes/contrib/bootstrap_barrio

# 2. Extracción (config/sync son YAML "contenido/conocimiento", no solo código -> --no-gitignore)
export GEMINI_API_KEY="..."
graphify extract graphify/source --backend gemini --no-gitignore --max-concurrency 1
graphify cluster-only graphify/source --backend gemini --max-concurrency 1 --batch-size 100

# 3. Mover el grafo a la raíz (ubicación canónica) e integrar con Claude Code
mv graphify/source/graphify-out ./graphify-out
graphify claude install --project
# (y corregir a mano el "graphify update ." -> ver sección 6/7, con GRAPHIFY_OUT, en CLAUDE.md)

Resultado final: ./graphify-out/graph.json (directorio real en la raíz, ~1600 nodos / ~2850
edges / ~296 comunidades), graphify instalado en global (~/.local/bin/graphify), copia
aislada del código en graphify/source/ (usada solo como entrada para futuras
extract/update), y el hook + la nota en CLAUDE.md activos para ese subconjunto de rutas.

Deploying an Independence Day Web Game with Tencent EdgeOne Makers: A Developer’s Guide

Poundrafasya — Wed, 26 Aug 2026 06:12:44 +0000

Transitioning a local development project into as live, globally accessible application is a critical milestone for any developer. Recently, I developed a responsive web game to celebrate Indonesian Independence Day. The game features interactive mechanics like a double-jump system and collectible kelapa muda (young coconuts) items. While the game ran flawlessly on a local server, the challenge was finding a deployment platform that could deliver static assets rapidly, handle traffic efficiently, and provide a seamless workflow without incurring high costs.

Enter Tencent EdgeOne Makers. Previously known as EdgeOne Pages, this platform has evolved into a robust full-stack hosting solution for Web and AI Agents. This article serves as a technical review and a step-by-step tutorial on how to leverage EdgeOne Makers to deploy a web application.

Why Tencent EdgeOne Makers?
When evaluating platforms for a web game, asset delivery speed is the top priority. High latency can ruin the player experience, especially for timing-based mechanics like a double-jump. EdgeOne Makers solves this through its underlying infrastructure:

Global Edge Computing & CDN: The platform caches static assets (like the HTML canvas, CSS, JavaScript files, and the kelapa muda image sprites) across global edge nodes. This ensures the game loads instantly for users regardless of their location.

Seamless Git Integration: It connects directly to repositories, enabling Continuous Integration/Continuous Deployment (CI/CD). Every push to the main branch automatically triggers a new build.

Built-in Security: It includes Web Application Firewall (WAF) capabilities, protecting the site from common web vulnerabilities out of the box.

AI Integration Ready: For future enhancements, the platform supports AI Agents and offers generous API token allowances, making it easy to integrate intelligent features later.

Step-by-Step Deployment Tutorial
Deploying the Independence Day web game took only a few minutes. Here is the exact workflow:

Step 1: Repository Preparation
Ensure your project is pushed to a Git provider (GitHub, GitLab, or Bitbucket). For this game, the repository contained standard web files (HTML, CSS, JS) optimized for responsive rendering on both mobile and desktop screens.

Step 2: Connecting to EdgeOne Makers
Navigate to the Tencent EdgeOne Makers console. Select the option to create a new project and connect your Git account. The authorization process is straightforward. Once linked, select the specific repository containing the web game.

Step 3: Build Configuration
EdgeOne Makers automatically detects the framework used. Because this project relies on vanilla web technologies, the build settings were minimal.

Framework Preset: Auto-detect or Static HTML.

Build Command: Left blank (or specify npm run build if you are migrating the game to Vite or React).

Output Directory: Usually . for the root directory or dist if a bundler is used.

Step 4: Deployment and Global Distribution
Click "Deploy." The platform provisions the environment, pulls the code, and distributes the assets across its edge network. Within seconds, the console provides a live URL. The deployment logs are transparent, allowing you to monitor the build process step-by-step.

Technical Review & Best Practices
Testing the live URL demonstrated significant performance advantages. The game assets loaded with zero noticeable delay, and the responsive UI adapted perfectly across different devices. The double-jump mechanics remained highly responsive, proving that the edge delivery effectively minimized latency.

Best Practice Tip: Always optimize your image assets before deployment. While the CDN is fast, compressing sprites and background images ensures the initial payload is as small as possible, providing an optimal experience for users on mobile networks.

Conclusion
Tencent EdgeOne Makers provides a frictionless, enterprise-grade deployment experience that is accessible to developers at any level. It eliminates the complexities of server management and CI/CD configuration, allowing you to focus entirely on code and creativity. Whether you are deploying a simple static portfolio, a complex React application, or an interactive web game, this platform is an outstanding choice to bring your projects online securely and efficiently.

TencentEdgeOne #EdgeOneMakers #CODEPOLITAN #EdgeOne

Your WordPress Search Plugin Should Return Post IDs and Nothing Else

Rafał Groń — Wed, 26 Aug 2026 06:11:13 +0000

In the space of a month I was asked three questions that looked completely unrelated:

Can search work on a site translated with TranslatePress, where a visitor types in one language and reads in another?
Can search hide course content the visitor hasn't bought?
Why does search behave differently inside a premium theme's AJAX overlay?
Different plugins, different problem domains, different people asking. All three turned out to be the same question, and the answer is an architectural decision you make once, near the start, and then live with.

The choice
If you write a plugin that replaces WordPress search, you pick one of two shapes.

Shape one: own the pipeline. You build your own index, you match against it, you produce the result list, and you render it. You control everything from query string to markup.

Shape two: answer with post IDs. You do your matching however you like, then hand WordPress a list of IDs in the order you want them, and let the rest of WordPress carry on as normal.

Shape one is tempting because it is the only way to guarantee the output looks exactly how you intended. It is also the reason most search plugins fight with everything else on the site.

Why the first shape breaks on multilingual sites
TranslatePress stores translations in its own tables and applies them at render time. The post itself stays in the original language.

Now put a search plugin next to it that maintains its own index. That index is built from the original content, because that is what is in the database. A visitor browsing in Finnish types a Finnish word. The plugin looks in its own index, finds nothing that matches, and returns nothing. The translation layer never gets a chance to help, because the plugin never handed anything to WordPress in the first place.

With the second shape, the flow is different:

content stored in language A
↓
plugin matches, returns post IDs
↓
WordPress builds the loop
↓
translation layer renders in language C
The plugin does not need to know that translations exist. It never sees them, never indexes them, never has an opinion about them. It answers with IDs and gets out of the way.

That is not a feature anyone built. It is what you get for free by not owning the last mile.

Why it matters for access control
The second question came from a site running membership software, where lessons belong to courses and visitors have bought some courses and not others. The request was for search results to exclude content the visitor cannot open.

If your plugin renders its own results, you now have to understand somebody else's permission model. You have to know how that plugin stores entitlements, keep up as it changes, and repeat the exercise for every membership plugin your users install.

If your plugin returns IDs, you add one filter:

$ids = apply_filters( 'my_plugin_result_ids', $ids, $query );
and the site decides. The membership plugin already knows who can see what. It does not need you to reimplement it, and you do not need to ship an integration per vendor.

The developer who asked me this wrote that filter himself and sent it to me. It is in the plugin now. That is only possible because IDs are the interface.

The failure mode nobody thinks about
Here is the part I would most like you to take away, because it bit me and it is not obvious.

To replace search, you generally do two things: you inject your results, and you remove WordPress's own LIKE clause so its keyword matching does not fight your ordering.

add_filter( 'posts_search', function ( $search, $query ) { if ( $query->is_search() ) { return ''; // strip the native LIKE clause } return $search; }, 10, 2 ); Perfectly reasonable, and quietly dangerous.

Consider what happens when your matching fails. Your API times out, or the site runs out of quota, or a network path breaks. You return no IDs. But you have already stripped the native search clause, so WordPress has nothing to fall back on either.

Search does not degrade. It goes blank. The site owner finds out from a customer.

The fix is to make the removal conditional on having actually succeeded:

add_filter( 'posts_search', function ( $search, $query ) { if ( $query->is_search() && $query->get( 'my_plugin_used' ) ) { return ''; } return $search; // untouched when we did not produce results }, 10, 2 );

Set that flag only after you have results in hand. Now failure means the visitor gets ordinary WordPress keyword search, which is worse than what you offer but very much better than nothing. The shop keeps selling. What is lost is relevance, not availability.

This is worth more attention than it usually gets. Anything that talks to a network will fail sometimes, and the state you leave the site in when it does is part of your plugin's design, not an accident.

Ordering, since it is the usual stumbling block
Once you hand over IDs, WordPress will happily reorder them for you unless you say otherwise:

$query->set( 'post__in', $ids ); $query->set( 'orderby', 'post__in' ); $query->set( 'post_type', 'any' );

orderby => post__in is the piece people miss. Without it your carefully ranked list comes back sorted by date, and you spend an afternoon convinced your ranking is broken.

Worth knowing too: a theme can undo this downstream. If a template runs its own query, or a page builder widget has its own Query settings with a fixed Order By, that widget wins. The plugin is fine and the ranking is fine, and the page still shows the wrong order. If a user reports scrambled results, check the template before you check yourself. That was the third question, and the answer turned out to be a theme's own AJAX search intercepting the request before WordPress ever saw it.

Where I have not finished applying my own argument
Being honest about the limit of the pattern as I have implemented it.

I hook the main query. That covers the standard search results page, which is where the overwhelming majority of searches happen. It does not cover a secondary WP_Query in a template, and three people have now asked for exactly that, wanting to build a custom results layout that still uses my ranking.

The right answer is obvious in hindsight and follows directly from everything above: if IDs are the interface, they should be reachable without going through the main query at all.

$ids = my_plugin_search_ids( $term, [ 'limit' => 20 ] );
Then a developer can do whatever they like with them, and I do not need to know what.

It is not built yet. It is a good illustration of the general point though. The value of returning IDs is not the specific hook you use to deliver them. It is that the interface is small enough that other people can build things you did not think of, without asking your permission or waiting for your next release.

Embeddings Cannot Say No: An Intent Detector's Real Numbers

Jules Robineau — Wed, 26 Aug 2026 06:03:00 +0000

My message detector worked on my test set. On messages it had never seen, it missed one real case out of two.

TL;DR: I built a small detector that spots messages asking for an action. It relies on embeddings, a technique that turns a sentence into numbers. It works well, except for one thing: it does not understand negation. "The outage is fixed, thanks" fires exactly like "outage". I explain why this is a flaw of nature, not of tuning, with numbers to back it. And why the right answer is to accept the flaw rather than fix it.

This article is for developers who want to plug in AI without paying a large model on every message. No machine learning background needed: I define everything along the way.

The setup

In a personal project, an AI watches a chat between users. When a message asks for an action, a badge shows up. Create a ticket, send a document.

Calling an LLM on every message is expensive. In money and in response time. I already made that case here: put the LLM last.

So the system has two stages. Stage 1 is a small model, free to run, that sorts messages. Stage 2 is the LLM, called only when the user clicks the badge.

Stage 1 uses embeddings. An embedding turns a sentence into a list of numbers. Two sentences with close meanings give close lists of numbers. That is all you need to understand for the rest.

Deciding with a similarity score

How does an embedding make a decision? By measuring how much two sentences look alike. That score is called cosine similarity. Close to 1: the sentences are very similar. Lower: they have nothing in common.

My detector compares each message to the available tools. "Create a ticket", "send a document". If the message looks enough like a tool, it is deemed actionable.

The whole question sits inside "enough". That is where things get hard.

A fixed bar does not work

First instinct: set a bar. Above 0.85 similarity with a tool, the message is actionable.

It does not work. My model gives scores between 0.80 and 0.92, for everything. "Hello" and "create a ticket" get almost the same score.

This model sees every sentence as somewhat similar. Its scores are packed into a tiny range. And a fixed bar separates nothing inside a tiny range. Raise the bar, and you lose real cases before you lose the noise.

Compare against neutral phrases, not a bar

The solution that worked: compare, instead of measuring in the absolute.

I wrote a list of neutral phrases, with no action in them. "Hello", "thanks", "ok great". I call them anchors.

The rule becomes simple. A message is actionable if it looks more like a tool than like the best anchor. If it mostly looks like "thanks", it is chit-chat.

# The decision rule
tool_score    = similarity(message, closest_tool)
neutral_score = similarity(message, closest_anchor)

actionable = tool_score > neutral_score

One detail that matters: I split long messages on punctuation. A request drowned in politeness stands out better piece by piece. The flip side: no punctuation, no splitting. Voice dictation rarely adds any.

One false alarm out of four

I evaluated on 300 generated messages. Generated, not real: the project had no users yet. Keep that in mind, reality will do worse.

Two measures matter, and they are simple. First: out of 100 messages that deserve an action, how many the detector catches. Mine catches 92. That is called recall, and it is a good score.

Second: out of 100 harmless messages, how many it leaves alone. Mine leaves 76. In other words, 24 harmless messages out of 100 trigger the badge for nothing. That is called specificity, and it is the number that hurts.

A badge that is wrong one time out of four stops being believed. Too many false alarms kill the alarm. The first number shines in the demo. The second one is paid in production.

Embeddings cannot say no

The worst failure mode has a name: negation. "There is an outage" asks for an action. "The outage is fixed, thanks" asks for none.

To the detector, these two sentences are almost identical. Same vocabulary, so almost the same numbers. The second one triggers the badge exactly like the first.

This is not a botched setting. An embedding summarizes a sentence by its topic. And both sentences have the same topic: an outage. The "it's fixed" part weighs almost nothing in the numbers.

You can check this yourself in two minutes. Take your positive sentences, append "it's fixed, thanks" to each one. Then look at the scores: they barely move.

The mock exam caught up with me

At first I believed I could fix negation through tuning. Twelve more anchors, like "it's fixed" and "problem solved". And a higher decision bar.

On my test set, beautiful. So I gave the detector a mock exam. In jargon: a holdout. A set of fresh messages, never used during tuning. New exam questions, not the past papers.

The verdict. The "it's fixed" false alarms did disappear. But the detector dropped from catching 68 real cases out of 100 to just 48. My fix missed more than one real case out of two.

That is called overfitting. My tuning had memorized my examples instead of learning the problem. Like a student who recites past papers and sinks on a fresh question.

Worse: on the mock exam, no bar gives both a good catch rate and few false alarms. The knob I was turning has nothing left to give. The ceiling is structural.

All the precision belongs to the LLM

The numbers forced the conclusion on me. This detector will never be precise. It can, however, be exhaustive.

So I picked its role: a gate, not a judge. Bar at the lowest, to catch wide. On the mock exam: 88 real cases out of 100 caught, and 31 harmless messages out of 100 let through for nothing.

That noise is accepted, and written into the design. Because stage 2 judges behind it: the LLM, called on click, can read "it's fixed". It filters the negation and picks the right tool.

# The shipped config: a gate, not a judge
model     : multilingual-e5-small   # small, on CPU, zero training
threshold : lowest                  # catch wide, on purpose
anchors   : smalltalk + resolution  # "thanks", "it's fixed"...
result    : 88 real cases out of 100 · 31 false alarms out of 100

Last decision, the most counter-intuitive one: do not train the model. I have no real conversations. And training on generated messages means learning the generator's quirks. The mock exam had just shown me that trap. I will train once I have a few hundred real, anonymized messages.

The checklist before you ship an embedding detector

Before a similarity score goes to production, run the list.

[ ] Test on messages never seen before, not on the ones used for tuning
[ ] Count the false alarms, not just the good catches
[ ] Try negation phrases: "it's fixed", "no need anymore, thanks"
[ ] Compare against neutral phrases rather than setting an absolute bar
[ ] Give the embedding stage a gate's role: catch wide, let something else judge
[ ] Know how many false alarms the next stage can absorb
[ ] Never train on generated data

What to remember

A similarity score does not understand "no". That is not a tuning flaw, it is the nature of the tool.

So measure on never-seen data, publish your ugly numbers, and put each stage where it is good. The embedding catches. The LLM understands.

Building intent detection or AI routing, and the numbers do not hold in production? Let's talk.

Sources: multilingual-e5-small (Hugging Face) · Wang et al., Multilingual E5 Text Embeddings: A Technical Report · Put the LLM Last (the previous article)

From Hype to Hard Reality: What We're Learning About Shipping AI Agents in Production

Tamiz Uddin — Wed, 26 Aug 2026 06:01:52 +0000

Originally published on tamiz.pro.

For the better part of two years, the narrative has been seductive: build a few function calls around a reasoning model, add a tool-use loop, and you have an autonomous agent that solves hard problems. The demos are real. The benchmarks are impressive. And then you try to ship one to production — and the floor opens up beneath you.

I've spent the last eighteen months building, breaking, and rebuidling AI agent systems across multiple teams and product lines. What follows isn't a critique of the technology. It's a map of the gap between what was promised and what actually works at scale, written for engineers who are currently standing in that gap.

The Evaluation Illusion

The first hard lesson is that every benchmark you see published is measuring something fundamentally different from what your production system does.

SWE-Bench, GAIA, AgentBench — these are controlled evaluations on curated datasets with clean boundaries. Production is not curated. Your user says "fix the billing API" and means "the staging environment," not the one they've been working in all morning. The LLM doesn't know this. It guesses. It acts. It breaks things.

The industry's early response was to build better evaluators: rubric-based scoring, LLM-as-judge, multi-hop verification pipelines. These help, but they create a second-order problem — you're now optimizing your agent for how well it scores on your evaluator, not for how well it serves the user.

What actually moved the needle was simpler than most papers suggest. Constrain the action space. Agents that operate on well-defined schemas, with typed inputs and bounded toolsets, evaluate far more reliably than open-ended ones. Think of it like type-safe programming: the compiler catches mistakes early, and the runtime is predictable. Your agent's tool interface is its API contract. Treat it like one.

Observability Isn't Optional — It's the System

Most teams built their first AI agents without observability, assuming they could add it later. This is the "we'll put in logging later" of the AI era, and it hits just as hard.

An AI agent in production is not a single request. It's a multi-step execution trace involving planning, tool calls, result parsing, error recovery, and often re-planning. When it fails — and it will — debugging a single llm.invoke() call tells you nothing. You need to see the full trajectory: what the model planned, which tools it called, what it observed, and why it chose the next step.

The practical standard that emerged: every agent execution needs a structured trace log with

a unique session ID
a step-by-step event log (plan, tool_call, tool_result, observation)
latency and token counts per step
a confidence or uncertainty signal if your model provides one
a final outcome classification (success, partial, failure, timeout, user_abort)

OpenTelemetry is the right foundation here. It gives you distributed tracing, context propagation, and a ecosystem of exporters. The mistake most teams make is treating traces as an afterthought added via SDK hooks. Build observability into the agent framework itself — the trace generation should be a first-class concern, not a cross-cutting middleware layer you bolt on afterward.

See more on production AI patterns and Tamiz's Insights for deeper coverage on related engineering practices.

The Cost Curve Is Not Linear

This is the lesson that keeps engineering leads awake at 2 AM.

A simple RAG pipeline costs pennies per query. An agent that loops through five to fifteen tool calls, re-plans, retries, and potentially spans multiple turns? That's dollars per session, not cents.

The cost isn't just the LLM calls. It's the thinking overhead that compound autoregressive architectures accumulate. Each additional step adds latency, each retry multiplies it, and the user experience degrades non-linearly while costs climb linearly-per-step.

The architectural response has converged on a few patterns:

Cost-aware scheduling. Route different agent sub-tasks to different model tiers. A cheap model handles routing and simple tool calls. An expensive model only runs when the task complexity threshold is crossed. This is the same principle as CDN caching for LLM requests: don't fly coast-to-coast for local delivery.

Budget caps and early termination. Set a maximum step count and token budget per execution. When you hit them, fall back to a safe default — usually escalating to a human or returning a structured error. Agents that run unbounded until they "succeed" are gambling with your margin and your SLA.

Caching as infrastructure. Conversation history, tool response bodies, and even plan fragments are often redundant across steps and sessions. Content-addressable caching of intermediate results — keyed by semantic fingerprint, not exact string match — can cut median cost by 30–50% in multi-step agents.

The Human-in-the-Loop Problem (That Isn't Really About Humans)

The original vision of AI agents was full autonomy. The production reality is that pure autonomy doesn't ship. Not for anything that touches money, data, or user state.

But the interesting finding hasn't been that humans need to approve everything — it's that structured intervention points improve outcomes more than raw oversight does.

The pattern that works: define clear checkpoint semantics rather than vague "human review." A checkpoint should answer three questions:

What decision is being made?
What information is available to the human reviewer?
What are the acceptable actions (approve, modify, abort, escalate)?

This turns subjective oversight into a deterministic state machine. Your agent pauses at a known point. The reviewer sees a structured summary — not the raw trace. They take one of three discrete actions. The agent resumes or terminates with clear semantics.

The counter-intuitive part: well-designed checkpoints often reduce total human involvement compared to post-hoc review. You catch problems before they compound, and the structured context means reviewers spend less time understanding the situation and more time making the decision.

Hallucination in Agents Is Structural, Not Cosmetic

In a simple QA system, hallucination looks like a wrong answer. In an agent, it looks like a cascade: the model hallucinates a tool schema, calls a non-existent endpoint, parses a malformed response as valid, and proceeds to act on fabricated data.

This isn't a prompt engineering problem. It's an architectural one.

The defenses that matter:

Schema-enforced tool calling. Never let the model construct tool invocation arguments from free text. Use JSON Schema validation on every tool call before execution. Reject calls that don't conform. This alone eliminates the most dangerous class of agent hallucinations — fabricated parameters that look plausible but are structurally invalid.

Observable side effects. Every tool that mutates state (writes a database, sends an email, modifies a file) should have a dry-run or preview mode. The agent proposes the action, the system applies it conditionally, and the result is logged before any user-facing impact.

Deterministic guards around non-deterministic models. Separate the planning layer (LLM-driven, creative) from the execution layer (deterministic, rule-based). The LLM decides what to do. The execution layer verifies that it can be done safely. This boundary is harder to draw in practice than in theory — it requires careful interface design — but it's the single most impactful architectural decision for production reliability.

The Integration Tax Is Real and Underestimated

AI agents don't operate in a vacuum. They integrate with databases, APIs, message queues, authentication systems, and existing business logic. Every integration point is a potential failure mode, and the agent's multi-step nature amplifies each one.

The pattern we've found most useful is the contract-first integration approach: define the interface contract for every external system the agent touches, validate inputs against that contract before the agent ever sees them, and log mismatches as structured errors rather than letting the model guess at interpretations.

This means spending as much engineering effort on your integration layer as on the agent itself. The agent is the visible part. The integration layer is what determines whether it survives in production.

What Actually Works in Production Today

If I were advising a team building an AI agent for production right now, this is the architecture I'd recommend:

A deterministic orchestrator (LangGraph, temporary state machines, or a custom implementation) that manages the execution graph, not a flat loop with a reasoning model at the center.
A two-tier model strategy: a cheap, fast model for routing and simple decisions; an expensive model only for complex reasoning sub-tasks.
Full OpenTelemetry tracing with structured event logs, shipped to both a time-series store (for metrics) and a document store (for trace replay).
JSON Schema-validated tool interfaces with no free-text argument construction.
Budget caps and timeout gates at every level — per-step, per-session, and per-user.
Checkpoint semantics for any action that crosses a state boundary.
A fallback path that degrades gracefully to human review or simple responses when the agent exceeds its confidence thresholds.

The agents that shipped successfully weren't the most autonomous or the most clever. They were the most constrained. They had narrow scopes, well-defined failure modes, and architectures that treated uncertainty as a first-class input rather than something to paper over with better prompts.

The Future Isn't Bigger Agents — It's Better Boundaries

The hype cycle around AI agents is heading toward a correction. Not because agents don't work, but because the original vision — fully autonomous, open-ended, general-purpose digital workers — is architecturally incoherent at production scale. Uncertainty compounds. Failure modes multiply. Costs explode.

The correction is already visible. Teams that are shipping are building narrower, more constrained systems with deterministic guardrails, proper observability, and honest assessments of where human judgment is required versus where the model can operate safely.

The engineers who will lead this space forward aren't the ones building the most capable agents. They're the ones building the most reliable ones. That distinction matters more than any benchmark score, and it's the one that will define the difference between a production system and a demo that never left the sandbox.

What I Check When I Inherit a WordPress Site I Didn't Build

Noshi — Wed, 26 Aug 2026 06:00:20 +0000

Sometimes the site was built by another developer. Sometimes by an agency. Parts of it may also have been generated or changed with AI. But the handoff problem itself is older than AI.

However it was built, you're the one touching it now. You don't know what's actually configured under the hood. Not yet.

1. Record the current state before you change anything

Before you fix, add, or "clean up" anything, write down what you found. No one's checking your work here. But later, if something breaks, it helps to know whether it was already broken when you got there.

A quick note is enough: which plugins are active, whether the site is set to be indexed, whether debug mode is on. Later, that note gives you something to compare against when a problem shows up.

2. Look at the installed plugins

Open the plugins screen and look past the ones that are active. Look at all of them, active and inactive.

For each one, ask three questions:

Is this plugin still maintained? Check its last update date on WordPress.org. A plugin that hasn't shipped an update in a year or more is one worth reviewing before you rely on it, even if you didn't choose to install it.
Is this one inactive on purpose, or was it just never cleaned up? An inactive plugin sitting around for years may simply be a leftover, or someone may have kept it there on purpose. Either way, it's often worth asking about.
Should I keep touching a site that depends on this? Sometimes the answer is yes, and that's fine. The point is to ask that question before you start relying on the plugin.

I used to do this by opening each plugin's WordPress.org page one by one, which is tedious enough that I usually skipped the ones that "looked fine." Eventually, I automated that part of the process. I'll come back to that at the end.

3. Check the current state, not the assumed state

You assume noindex is off because "why would anyone launch a site that's hidden from Google." You assume debug mode is off because "it's a live site." Those assumptions are often right. But inherited sites are exactly where I don't want to rely on them.

Check whether the site is set to be indexed by search engines, and don't rely only on the visible setting. A theme or plugin can force noindex through code even when the visible setting looks fine. Check whether WP_DEBUG is on. Check whether the default admin username still exists. These aren't complicated checks, but they're easy to miss when you're focused on the actual task you were hired to do.

Ask yourself, for each setting: was this intentional, or is this just what came with the site? If you can't answer that, you can't safely assume it's fine.

4. Make your changes

Then you do the actual work: build the feature, fix the bug, make the requested changes. But now you're doing it against a baseline you actually understand, instead of a baseline you inherited blind.

5. Go through the site again before you hand it back

Once your work is done, circle back to the same questions from step 3. Indexing, debug mode, admin username, and anything you added along the way: test posts, temporary pages, anything meant only for your own reference during the work.

This is the same discipline you'd use before handing off a site you built yourself. The fact that you inherited the site doesn't change what you should leave behind when you're done. If anything, it's harder, because you're dealing with things you created during the job and things that were already there.

Noshi-Kanamer

This workflow is also why I added Site Check to Noshi-Kanamer. It scans every installed plugin, active or inactive, against WordPress.org and flags the ones that haven't been updated in 6 months or a year, so I don't have to open each plugin's WordPress.org page one by one. Then, before I hand the site back, I use Pre-Launch to check indexing, WP_DEBUG, debug.log, the default admin username, and a few other loose ends. It generates a plain-text report I can keep for myself or hand to whoever I'm delivering the work to.

It's free on WordPress.org. If there's something you always check on an inherited site that I'm missing, I'd like to hear it.

I hosted my no-Mac iOS pipeline as a browser wizard (and dropped the price to $1 for a day)

Jackson — Wed, 26 Aug 2026 06:00:07 +0000

A while back I wrote about the GitHub Actions pipeline I built to ship Citolex to the App Store without ever owning a Mac. The pipeline itself hasn't changed much, but how you set it up has.

Until now, using it meant downloading a template and running a setup script yourself. That's fine for most developers, but it's still a terminal and a handful of manual steps between paying and having a working pipeline.

I built a hosted version instead. You pay, connect your GitHub account through a real OAuth flow, and pick or create a repo. A wizard commits the full pipeline template directly into it using GitHub's Git Data API, no git required on your end. Then it walks you through filling in your signing secrets, with an inline Signing Doctor check that tells you exactly what's wrong with a certificate or provisioning profile before you ever trigger a build, not after one fails. If a build does fail, the same wizard reruns that diagnosis automatically against your current secrets and shows it right next to the failed logs.

The signing diagnosis itself doesn't shell out to any macOS specific tooling. Provisioning profiles are signed CMS/PKCS7 blobs, certificates are X.509, keystores are PKCS12, all standard crypto formats that Web Crypto can parse directly. That's what let this run as a Cloudflare Worker instead of needing an actual Mac or VM behind it.

If you've been meaning to try it, it's $1 for the next 24 hours instead of the usual $99 for iOS or $39 for Android, mostly to get more people actually running it end to end rather than reading about it.

Full disclosure, I build Macless. macless.dev if you want to poke at it.

Google Gemini 3.5 and Gemini 3.5 Flash: The Complete Guide

Mecanik1337 — Wed, 26 Aug 2026 06:00:00 +0000

Gemini 3.5 represents Google's latest efforts to dominate the fast-growing market for agentic AI applications in 2026. Developers need models that are both fast and cost-effective to run complex reasoning tasks. Consequently, the introduction of these models addresses this need directly by combining high speed with frontier intelligence.

This article reviews the core architecture of Gemini 3.5, the specific capabilities of Gemini 3.5 Flash, and how engineering teams use them to build autonomous coding pipelines.

TL;DR

Google released Gemini 3.5 Flash in mid-May 2026 to target high-speed agentic development.
The model natively supports text, images, video, audio, and PDF documents within a single context.
It features a one million token input limit to allow deep codebase processing at low cost.
Google designed Gemini 3.5 specifically for long-horizon workflows like autonomous coding cycles.

What is Gemini 3.5?

The Gemini 3.5 model series represents Google's core intelligence layer for 2026. For instance, while older models focused on text-based generation, this new generation is multimodal by default. Specifically, the engine processes multiple data formats simultaneously. As a result, it translates, reasons, and builds code across text, audio, video, and PDF structures without external conversion tools.

Specifically, Google built the model to serve as a reliable platform for autonomous agents. For example, these agents need to interact with external tools and make decisions over long periods. Consequently, the API offers low latency and high reliability for tool-calling operations.

Furthermore, the model also maintains a high level of code correctness. Specifically, it handles complex system integration tasks easily. Consequently, this makes it a strong choice for businesses that want to automate their software delivery lifecycles. For a step-by-step approach on implementing such automation, check out our guide on AI software development.

Gemini 3.5 Flash Architecture and Speed

The standout release of this series is Gemini 3.5 Flash. Launched in mid-May 2026, the Flash variant targets speed and cost-efficiency. Therefore, it provides developers with a powerful tool for tasks that require quick responses.

Therefore, despite its smaller size, Gemini 3.5 Flash handles a one million token input window. This allows developers to upload entire project codebases or hours of video directly into the prompt. The model processes this information quickly, making it ideal for real-time applications.

In addition, Google also reduced the pricing for the Flash model. This cost reduction allows startups and SMEs to run high-volume agentic tasks without exceeding their budgets. It represents a major step toward making agentic programming accessible to everyone.

Use Cases for Gemini 3.5 in Development

Specifically, developers use Gemini 3.5 for a variety of tasks that require both speed and multimodal understanding.

Indeed, one major usecase involves automated code reviews and refactoring. Because the model supports a large context window, it can review multiple files at once. It checks for security vulnerabilities and suggests improvements based on project style guides. You can find more specifications on Google's technical milestones on the Google DeepMind Gemini site.

Similarly, another popular use case is video and audio analysis. Developers use the model to extract data from webinars, meetings, and tutorials. It can summarize key points, create transcripts, and even generate code snippets based on visual demonstrations in the video.

Optimizing API Performance: Context Caching

When working with large codebases, API costs can accumulate quickly. Consequently, Google introduced context caching for the Gemini 3.5 series. This feature allows developers to store frequently used files in Google's cache, reducing the number of active tokens processed during each API call.

Specifically, if you have a library that changes rarely, you can cache it once. The API then references the cached version for subsequent queries. This reduces latency significantly and cuts running costs by up to 50%.

Consequently, developers can run continuous integration scripts without exceeding their budgets. These scripts can check every commit on GitHub for logical errors, ensuring that the main codebase remains clean and functional at all times.

Understanding Google AI Studio: Getting Started

For developers who want to experiment with these features immediately, Google provides a browser-based playground. This tool, known as Google AI Studio, allows you to write prompts, adjust parameters, and test API endpoints without setting up a local server.

To get started, you can sign in with your developer account and generate an API key. The console provides a clean interface to test text, image, and video prompts. It also offers auto-generated code blocks in Python, JavaScript, and Curl to make integration faster, especially when setting up Claude AI for code review.

In addition, AI Studio allows you to test system instructions and safety filters directly. This helps you understand how the model behaves under different settings, making it easier to build secure applications for production environments.

Key Takeaways

Gemini 3.5 is a native multimodal model series targeting fast agentic AI applications.
Gemini 3.5 Flash offers low latency and cost-effective processing for high-volume tasks.
The model features a one million token context window to handle large datasets.
Developers use it for codebase analysis, automated code reviews, and video processing.

Frequently Asked Questions

What is Gemini 3.5?
Gemini 3.5 is Google's latest generation of multimodal AI models. It natively processes text, images, audio, video, and PDF files. Google designed the model for autonomous agentic workflows and complex programming tasks.

When did Google release Gemini 3.5 Flash?
Google released Gemini 3.5 Flash in mid-May 2026. Google designed the model to provide developers with a fast, cost-effective alternative for high-volume reasoning tasks.

What is the context window size of Gemini 3.5 Flash?
The model supports an input context window of one million tokens. This capacity allows developers to process large repositories and document sets in a single request.

How does Gemini 3.5 handle coding tasks?
Google designed Gemini 3.5 to execute long-horizon coding cycles. It can analyze full project directories, perform automated code reviews, and suggest refactoring steps with high accuracy.

SSE Fragmented My JSON Into 30 Pieces. Here's the Parser That Put It Back Together.

Taylor Wang — Wed, 26 Aug 2026 05:59:16 +0000

I was building a streaming chat interface against MonkeyCode's free model access and its free server option, and the first few test runs went so smoothly that I stopped thinking about the transport layer entirely. The server sent back clean SSE events, each one a complete JSON object carrying a token of text, and my parser happily decoded them one by one. Then I asked for a longer response, and the terminal lit up with json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0) on the second event.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The full response, captured to a file, was valid JSON. The model had not failed. My parser had failed because it assumed something the SSE protocol never guarantees: that each event contains a complete, self-contained JSON document.

What the Stream Actually Looked Like

Server-Sent Events is a simple framing protocol. Each event is a set of key: value lines terminated by a blank line, and the data: field carries the payload. When a model streams tokens, the server does not promise to flush one complete JSON object per event. It flushes whatever bytes are ready, which means a single logical object can be split across several events, or several objects can be packed into one event.

data: {"choices":[{"delta":{"content":"Hel

data: lo"}}]}

data: {"choices":[{"delta":{"content":" world"}}]}

data: [DONE]

My naive parser treated each data: line as an independent JSON document:

# Wrong: assumes every event is a complete JSON object
for event in sse_events:
    payload = event.data
    obj = json.loads(payload)  # crashes on the first fragment

The first event in my trace contained {"choices":[{"delta":{"content":"Hel — a fragment with no closing brace. The second event contained lo"}}]} — a fragment with no opening brace. Both were meaningless on their own and perfectly meaningful together.

The Fix: Buffer, Then Decode Incrementally

The robust approach is to accumulate raw bytes in a buffer and attempt a decode only when the buffer might contain a complete object. Python's json.JSONDecoder.raw_decode is the right tool: it parses one JSON value from the start of a string and tells you where it ends, without requiring the whole string to be valid JSON.

import json

class IncrementalJSONParser:
    def __init__(self):
        self.buffer = ""

    def feed(self, chunk: str) -> list:
        self.buffer += chunk
        decoder = json.JSONDecoder()
        results = []
        idx = 0
        while idx < len(self.buffer):
            try:
                obj, end = decoder.raw_decode(self.buffer, idx)
            except json.JSONDecodeError:
                break  # incomplete fragment; wait for more bytes
            results.append(obj)
            idx = end
            while idx < len(self.buffer) and self.buffer[idx] in " \t\r\n":
                idx += 1
        self.buffer = self.buffer[idx:]
        return results

The loop tries to decode at the current position. If it succeeds, it yields the object and advances past it, then tries again in case multiple objects arrived in the same chunk. If it fails, it stops and waits for more data. The leftover bytes stay in the buffer for the next call.

Using it with an SSE client is straightforward:

parser = IncrementalJSONParser()

for event in sse_events:
    for obj in parser.feed(event.data):
        handle_token(obj)

The parser keeps its own buffer across calls, so split fragments reassemble naturally and concatenated objects decode one after another.

Handling a Mid-Stream Disconnect

The incremental parser fixes the fragmentation problem, but free servers can also drop the connection mid-stream. At that point you have three choices:

Discard the partial response and retry the whole request. Simple, but wasteful if the model was 90% done.
Use the partial text if your use case tolerates truncation. A summary that ends mid-sentence is often better than no summary.
Retry with a resume hint — send the partial text back to the model and ask it to continue. This is fragile and model-dependent; I would not rely on it.

For my batch summarizer, I chose option 1 with a retry cap of three attempts, because summaries are short and a truncated summary is worse than a delayed one. For a chat interface, option 2 is more humane: show what arrived, then let the user ask for more.

Limitations

The incremental parser handles JSON fragments and concatenated objects, but it has real limits:

It assumes the stream is UTF-8 text. Binary-safe protocols need a different approach.
It buffers everything in memory. For a multi-megabyte response, that defeats the purpose of streaming.
It does not validate that the objects form a meaningful sequence. You still need to check for [DONE] sentinels or other end-of-stream markers and filter them out before decoding.
If the provider wraps JSON in extra framing, like data: [DONE] at the end, you need to handle that separately.

Who Should Not Use This

If your provider guarantees one complete JSON object per SSE event, the naive parser is fine and this whole article is overkill. If you are not actually streaming — if you just want the final response — call the non-streaming endpoint and json.loads the whole thing. Incremental parsing is a tool for the specific case where the stream is fragmented, the response is large, or you want to render tokens as they arrive.

The Takeaway

Streaming protocols and JSON documents have different ideas about where a message ends. SSE events are transport boundaries, not data boundaries, and confusing the two produces bugs that look like model failures but are actually client failures. Buffer, decode incrementally, and decide in advance what a mid-stream disconnect means for your use case.

If you are experimenting with free model access and a free server, expect the stream to be less polished than a paid tier: more fragmentation, more disconnects, more surprises. Build your parser to survive those surprises, and the model's output quality becomes the only thing you have to judge.

I built a YouTube-to-text tool, and three things turned out much harder than expected

Zhengxin — Wed, 26 Aug 2026 05:59:06 +0000

Someone links a 45-minute conference talk and says "the good part is in the middle somewhere." You want three sentences. You do not want 45 minutes.

So I built SummarizeVideoToText: paste a video link, get a text workspace — full transcript, AI summary, timestamped chapters, a mind map, and a Q&A panel you can interrogate about the video. No sign-up needed to try it.

That's the pitch. The interesting part is what broke along the way.

1. Getting captions is a fallback chain, not an API call

My first version called one endpoint and assumed a transcript came back. In practice, that endpoint fails constantly — YouTube rotates its internals, some videos need a proof-of-origin token, some tracks exist but not in the language you asked for.

What actually works is a chain of providers where each layer falls back to the next:

export class ChainProvider implements TranscriptProvider {
  constructor(private readonly providers: TranscriptProvider[]) {}
  // try each in turn; fall through on failure
}

The non-obvious part is knowing when not to fall through. Two cases end the chain immediately:

invalid_url — the link itself is broken. No provider will do better.
no_transcript — layer one confirmed the page loads fine and has no caption track at all. A paid provider will confirm the same thing and bill you for it.

Everything else falls through. That distinction is the difference between a robust chain and a machine that burns API credits to rediscover the same "nope."

The honest limitation this leaves: if a video has no captions in any form, there's nothing to summarize. I show that plainly instead of pretending. Audio transcription for YouTube is on the roadmap; TikTok and Instagram already go through AI transcription because they rarely ship captions.

2. Caching wasn't about speed. It was about money.

I started with Redis and a TTL, like you do. Then I watched the logs: a video would get summarized, sit for a week, the key would expire, someone would open the same URL — and the whole pipeline would run again. New caption fetch, new LLM call, new bill.

The realization: a video's content never changes. There is no correctness reason to ever evict a summary. TTL made sense for a hot cache, not for the artifact itself.

So it became two layers:

Redis — hot cache, short TTL, absorbs the repeat traffic.
Postgres — permanent store, no TTL. Redis misses land here, not on the model.

Storing a few KB of text forever costs orders of magnitude less than regenerating it once. If your pipeline has an expensive deterministic step, "cache expiry" and "delete the result" should not be the same decision.

The user-visible payoff is that opening a video someone else already summarized is instant and costs nobody anything — which is also why I could leave the free tier usable without an account.

3. Notion doesn't take Markdown

I wanted "export this whole note to Notion." I assumed I'd POST some Markdown. Notion's API is a block model — every heading, paragraph, and list item is a typed object, and the constraints stack up fast:

Max 100 child blocks per request. A transcript is hundreds of lines.
Max 2000 characters per rich-text object. Long paragraphs need chunking.
Max 2 levels of nesting per request. So a collapsible toggle containing a full transcript can't be created in one shot: you create the toggle, read its ID out of the response, then append its children in batches.

And the one that cost me an evening of confusion: an integration without "read content" permission gets partial objects back. Creating a page returns an object with an id and no url. Searching returns pages with no properties, so no title. Nothing errors. You just get undefined where you expected a link, and a page titled "".

Two lessons. First, when an API returns a suspiciously empty field, check the permission scope before you check your code. Second, degrade instead of inventing: my first fix put the string "(Untitled page)" in the UI, which turned a missing title into a confidently wrong one. The real fix was to reconstruct the URL from the ID (notion.so/<id-without-dashes> is a valid link) and drop the page name from the message when it isn't known.

Bonus: the Obsidian URL that was always too long

Obsidian has a URI scheme: obsidian://new?name=...&content=.... Clean, one click, works great in the demo.

It never worked in production. A full transcript blows past the URI length limit every single time, so my code silently fell back to downloading a .md file. Users clicked "Export to Obsidian" and got a file in their Downloads folder — technically not a failure, so nothing ever showed up in the error logs.

The fix was one flag I'd missed in the docs:

await copyText(content);
window.location.href = `obsidian://new?name=${encodeURIComponent(title)}&clipboard=true`;

clipboard=true tells Obsidian to pull the body from the clipboard. The URI now carries only the title, and length stops being a factor.

The analytics bug that made everything else unmeasurable

One more, because it invalidated a week of numbers.

My event helper was defensive:

export function track(event, params) {
  const gtag = window.gtag;
  if (typeof gtag !== 'function') return;  // ← this line
  ...
}

Sensible: ad blockers exist, analytics should never break a click. But the gtag stub was loading with afterInteractive, meaning window.gtag doesn't exist until hydration finishes. On a slow connection that's a multi-second window — and the "Summarize" button is the first thing anyone clicks. Those events were dropped silently, so my funnel's denominator was quietly too small.

The fix is to load the tiny stub beforeInteractive (it only pushes to an array) and let the real script arrive later and replay the queue. That's what Google's own snippet does; I'd split it apart without thinking about ordering.

Related lesson from the same audit: instrument outcomes, not intentions. I was tracking "user clicked Export" but not whether the export succeeded. 100 clicks could be 97 successes or 3. Every click event that kicks off async work deserves a matching result event with a failure code.

What it is now

YouTube via official captions; TikTok / Instagram via AI transcription
Summary, timestamped chapters, key insights, an interactive mind map, and Q&A grounded in the actual transcript
25 summary templates (study notes, meeting minutes, Twitter thread, flashcards, SEO article…) and 14 output languages, independent of the video's language
Export the whole note to Notion, Obsidian, or Markdown, with clickable timestamps that jump back into the video
Free: 2 videos/day with no account (up to 15 min), 10/day with a free Google sign-in (up to 1 hour)

Try it: summarizevideototext.com

If you've fought with the Notion block API or the YouTube caption endpoints, I'd genuinely like to compare notes in the comments — especially if you found a cleaner answer than a fallback chain.