La renta en la India con Claude Code: itr-wala deja que el agente lea el Form 16 y el AIS y que un Python probado calcule cada rupia

En dos frases

Karan Bansal, responsable de IA de la empresa de seguridad de aplicaciones ArmorCode, publicó itr-wala, un skill gratuito para Claude Code, Codex y Gemini CLI que prepara la declaración de la renta india (ITR): el agente de IA lee el Form 16 y el Annual Information Statement, pregunta por las deducciones y guía por el portal, mientras un motor de Python probado calcula cada rupia. Es un testimonio en primera persona (el autor dice que presenta sus propios impuestos con él) todavía sin experiencias de otros contribuyentes, pero todo el método está en un repositorio con licencia MIT que cualquiera puede leer, probar y adaptar.

Quién lo hace y por qué importa

En la India, las personas físicas presentan el ITR en el portal electrónico de la administración tributaria. La mayoría de los asalariados parte del Form 16 (el certificado de retribuciones y retenciones que emite la empresa, parecido a nuestro certificado de retenciones) y lo contrasta con el Annual Information Statement (AIS) y el Form 26AS, que recogen lo que han comunicado bancos, brokers y empleadores: algo así como los datos fiscales que la AEAT pone a disposición en España. El README plantea la alternativa sin rodeos: unos honorarios de unas 3.000 rupias a un chartered accountant o unas tres horas en el portal. Son cifras del autor, no nuestras.

Lo interesante es la tesis. En el apartado «Why this exists» del README, Bansal sostiene que todas las demostraciones de IA fiscal de la campaña compartían un fallo silencioso: el modelo hacía las cuentas. Los modelos de lenguaje leen bien un Form 16 y aplican mal las reglas de deducciones y de reducción marginal, y un dígito traspuesto acaba en un requerimiento. Por eso itr-wala reparte el trabajo: la IA lee, pregunta y explica; un Python determinista calcula tramos, deducciones, recargos, el cess (un recargo del 4 %), intereses y sanciones por presentación tardía, valida las entradas y cruza las retenciones con los extractos oficiales.

La trayectoria de Bansal explica parte del diseño. Su web personal habla de una década en ingeniería de seguridad y de su cargo actual al frente de la IA en ArmorCode; el README añade que ha dado charlas en DEF CON y OWASP. Eso se nota en un instalador pensado para revisar antes de instalar, en un validador que rechaza números de identificación y en scripts de «extracción ciega» que mantienen nombres de pagadores y números de cuenta fuera del contexto del modelo. No vende ningún producto fiscal. El único interés propio que encontramos es una invitación opcional, tras una presentación correcta y solo con consentimiento expreso, a dar una estrella al repositorio.

Contrastamos el repositorio con el Show HN del autor en Hacker News, la página del proyecto y su web personal, y ejecutamos nosotros mismos las pruebas incluidas. Lo que no encontramos es una confirmación independiente: el 21 de octubre de 2026, el issue que abrió en agosto para pedir a los contribuyentes dos líneas sobre su experiencia seguía sin respuestas.

Herramientas y arquitectura

El repositorio es un skill con la estructura de las convenciones de skills de Anthropic: un SKILL.md con el flujo de trabajo y las «reglas de hierro», diez archivos de referencia que el agente consulta cuando los necesita y una carpeta scripts/. Todo funciona con Python 3.9 o superior y solo la biblioteca estándar.

Capa	Quién la hace	Archivos
Leer documentos, entrevistar, explicar	El agente de IA	SKILL.md, references/*.md
Extracción estructurada del AIS, el TIS y el 26AS	Python, sin exponer identidades	decrypt_ais.py, redact_ais.py, parse_26as.py, extract_tis.py
Contrato de entrada	Validador de Python	validate_income.py, references/input-schema.md
Toda la aritmética fiscal, en los dos regímenes	Motor de Python	tax_engine.py, tax_years.py
Prueba de que las cuentas son correctas	Pruebas en CI	test_tax_engine.py, test_validate_income.py, fuzz_engine.py
Pagar, presentar, verificar	La persona	Portal de presentación

Destacan tres decisiones. La primera: el agente tiene prohibido hacer cuentas, ni siquiera para comprobar un total; si necesita una cifra, escribe las entradas en income.json y ejecuta el motor. La segunda: el validador es una barrera: si las retenciones declaradas no cuadran con el Form 26AS, es un error que bloquea; las claves desconocidas se rechazan porque una errata haría perder una deducción sin avisar, y cualquier cadena con forma de PAN o de Aadhaar (el número de identidad) bloquea el archivo. La tercera: la persona se queda con los pasos irreversibles: el agente nunca ve la contraseña del portal ni el código de un solo uso y nunca pulsa pagar, presentar ni verificar, aunque tenga un navegador.

Cómo funciona, paso a paso

SKILL.md describe once pasos (del 0 al 10). Resumidos:

1. Ejercicio, finalidad y autoprueba. El agente confirma el ejercicio (2025-26 para declaraciones, 2026-27 para planificar pagos fraccionados) y ejecuta las pruebas de referencia; si no terminan en OK, se detiene.
2. Carpeta de trabajo. Crea una por ejercicio y finalidad con docs/, work/ y output/, y un .gitignore que impide subir los documentos fiscales a cualquier repositorio.
3. Documentos. El mínimo es el Form 16 y el AIS en JSON; la descarga del AIS viene cifrada y un script la descifra. El Form 26AS, el TIS, los certificados bancarios y los extractos del broker mejoran los cruces.
4. Extracción. Cada cifra se copia literalmente en income.json, con su fuente anotada en work/extraction-notes.md, y los totales de cada documento van a source_totals.
5. Validación. El validador tiene que terminar con 0 errores; los avisos se explican al usuario uno a uno.
6. Entrevista de deducciones. El agente pregunta de forma proactiva por las deducciones habituales; solo entran las que tienen justificante.
7. Cálculo. El motor compara los dos regímenes; el agente pega la tabla tal cual y la explica sin recalcular.
8. Modelo y fechas. Elige el ITR-1, 2, 3 o 4, fija la fecha límite y la de presentación y vuelve a ejecutar el motor, porque los intereses por retraso pueden cambiar las cifras.
9. Conciliación y paquete de presentación. Un mapa campo a campo del portal, en orden, con el importe a pagar o a devolver que el portal debe mostrar.
10. Portal y después. La persona teclea, compara la vista previa del portal con el paquete, paga, presenta y verifica en un plazo de 30 días.

Cópialo y adáptalo

Todo lo que en esta sección aparece como «del repositorio» está copiado de karanb192/itr-wala en el commit 7d10b18, licencia MIT, Copyright (c) 2026 Karan Bansal (parte del material de referencia está adaptado del proyecto file-itr, también MIT). Lo marcado como «plantilla de Agents Finance» es nuestro. El código original se deja tal cual, en inglés.

Requisitos previos

• Una declaración de persona física residente dentro del alcance (sin derivados ni operaciones intradía, sin auditoría obligatoria, sin deducción por doble imposición internacional y sin condición de no residente).
• Python 3.9 o superior y git; Claude Code, Codex CLI o Gemini CLI.
• El Form 16 y el AIS (JSON), mejor si también tienes el Form 26AS y el TIS.
• Aceptar que los documentos que lee el agente se envían al proveedor del modelo; tacha antes el PAN, el Aadhaar y los números de cuenta.

Instalar revisando antes (del README del repositorio)

# Review-first (recommended): clone, read it, install the bytes you just read
git clone https://github.com/karanb192/itr-wala.git
cd itr-wala && ./install.sh          # also: codex, gemini, all

# Or scope it to just the folder your tax documents live in
cd ~/tax-2026 && ~/itr-wala/install.sh --here

# Claude Code plugin (name whichever repo you trust)
/plugin marketplace add karanb192/itr-wala
/plugin install itr-wala@itr-wala

Para fijar en otra máquina el commit exacto que revisaste, el README documenta ITR_WALA_REF=<sha> ./install.sh all, e ITR_WALA_NO_FETCH=1 para prohibir cualquier acceso a la red.

Las reglas de hierro (extracto de SKILL.md, del repositorio)

En resumen: el agente nunca hace aritmética fiscal; cada cifra es una transcripción literal con su fuente; el validador debe pasar antes del motor; las credenciales son intocables, y la persona es quien paga, presenta y verifica.

1. **Never do tax arithmetic yourself.** Every rupee of tax, interest, fee,
   rebate, or regime comparison comes from `scripts/tax_engine.py` output.
   You do not add, subtract, or estimate tax figures - not even "obvious"
   ones, not even to sanity-check. If you need a number, put the inputs in
   `income.json` and run the engine. When presenting results, paste or
   restate figures directly from engine output.
2. **Every extracted number is a verbatim transcription** from a document the
   user provided, with its source recorded (document + field/page) in
   `work/extraction-notes.md`. Fill `source_totals` so the validator can
   cross-check. Never write a model-derived or guessed number into `income.json`.
3. **`scripts/validate_income.py` must pass (exit 0)** before the engine runs.
   Fix every error; show every warning to the user.
4. **Credentials are untouchable.** Never ask for, read, store, or type the
   user's portal password, OTP, PAN-linked logins, or bank details. If a
   browser is involved, the user logs in themselves.
5. **The user performs the three final acts: Pay, Submit, e-Verify.** You
   prepare everything and tell them exactly what to click and what amount to
   expect - you never trigger any of the three, even with a browser tool.

El archivo completo incluye además la regla del menor impuesto legal, el control del ejercicio, el control del alcance y la regla de privacidad (reglas 6 a 9).

El .gitignore de la carpeta de trabajo (patrones que enumera SKILL.md, del repositorio)

docs/
work/
output/
*AIS*
*TIS*
*26AS*
*Form16*
*form16*
*ITR*json
*ACK*
*Challan*

El contrato de entrada: ejemplo ficticio (assets/example-income.json, del repositorio)

Las claves son las del motor: salario bruto y sus componentes del Form 16, intereses de la vivienda habitual, ganancias de capital, intereses y dividendos, deducciones por sección, retenciones y pagos fraccionados, y los totales de cada documento en source_totals.

{
  "financial_year": "2025-26",
  "purpose": "return",
  "name": "Example Filer (fictional)",
  "regime": "both",
  "age_category": "regular",
  "residential_status": "resident",
  "due_date": "2026-07-31",
  "filing_date": "2026-07-28",
  "income": {
    "salary": {
      "gross": 2400000,
      "exempt_allowances": 240000,
      "professional_tax": 2400,
      "basic_plus_da": 1200000,
      "form16_17_1": 2300000,
      "form16_17_2": 100000,
      "form16_17_3": 0
    },
    "house_property": [
      { "type": "self_occupied", "interest_paid": 180000 }
    ],
    "capital_gains": {
      "stcg_111a": 45000,
      "ltcg_112a": 160000,
      "stcg_slab": 12000
    },
    "other_sources": {
      "savings_interest": 14500,
      "fd_interest": 42000,
      "dividends": 8200
    }
  },
  "deductions": {
    "80c": 150000,
    "80ccd_1b": 50000,
    "80ccd_2": 100000,
    "80d": 25000
  },
  "taxes_paid": {
    "tds": 280000,
    "advance_tax": [
      { "date": "2025-12-14", "amount": 20000 }
    ]
  },
  "source_totals": {
    "form16_gross_salary": 2400000,
    "form16_total_tds": 265000,
    "form26as_total_tds": 280000,
    "ais_total_tds": 280000,
    "ais_savings_interest": 14500,
    "ais_dividends": 8200
  }
}

El control de identidad del validador (extracto de validate_income.py, del repositorio)

Dos expresiones regulares: una para el formato del PAN (cinco letras, cuatro cifras, una letra) y otra para cualquier número de doce cifras, como el Aadhaar.

PAN_RE = re.compile(r"\b[A-Z]{5}[0-9]{4}[A-Z]\b")
AADHAAR_RE = re.compile(r"\b\d{12}\b")

Ejemplo: lo que obtuvimos al ejecutarlo

Ejecutamos los tres comandos del README sobre el ejemplo ficticio, con Python 3.13, en el commit 7d10b18:

python3 skills/itr-wala/scripts/test_tax_engine.py
python3 skills/itr-wala/scripts/validate_income.py skills/itr-wala/assets/example-income.json
python3 skills/itr-wala/scripts/tax_engine.py skills/itr-wala/assets/example-income.json

Ran 88 tests in 0.027s

OK
WARNING TDS claimed (280,000) differs from form16_total_tds (265,000) by 15,000 - reconcile before filing (multiple deductors?)

OK - 0 error(s), 1 warning(s)
...
  RECOMMENDED: NEW regime (saves Rs. 42,811)
  New: 3,00,716   Old: 3,43,527

Lo útil es el aviso: el ejemplo declara a propósito 15.000 rupias más de retenciones que las que figuran en el Form 16 (un banco también retuvo), y el validador pide una explicación en lugar de dejarlo pasar en silencio. Las 42.811 rupias coinciden con el README.

Plantilla de Agents Finance basada en itr-wala: un AGENTS.md para el mismo patrón en otro país

Es nuestra adaptación del patrón, no código publicado por el autor. Da por hecho que escribes (o ya tienes) un script de cálculo probado para tu país; en España, por ejemplo, el motor podría reproducir la liquidación del IRPF y contrastarse con el borrador.

# AGENTS.md — declaración de la renta, patrón de motor determinista
# Plantilla de Agents Finance basada en itr-wala (MIT). Propuesta sin probar.

## Papeles
- Tú lees documentos, preguntas y explicas. Nunca calculas impuestos.
- `engine/compute.py` calcula. `engine/validate.py` comprueba las entradas.
- El contribuyente inicia sesión, paga, presenta y firma. Tú nunca lo haces.

## Reglas
1. Nada de aritmética en el chat. Cada importe que muestres sale del motor,
   pegado tal cual. Si necesitas una cifra, añade entradas y vuelve a ejecutarlo.
2. Cada cifra de entrada se copia literalmente de un documento de `docs/`,
   con su fuente (documento, página, casilla) anotada en `work/sources.md`.
3. `python3 engine/validate.py work/input.json` debe terminar con código 0
   antes de ejecutar `engine/compute.py`. Enseña cada aviso al contribuyente.
4. Rellena `source_totals` con los totales de los documentos (retenciones,
   intereses, dividendos) tal como aparecen; nunca los ajustes.
5. No pidas ni guardes contraseñas, códigos de un solo uso, NIF ni números
   de cuenta. Pide al contribuyente que los tache antes.
6. Fuera de alcance (no residentes, actividades con contabilidad compleja,
   doble imposición internacional, todo lo que el motor no modela): dilo y
   recomienda un asesor.

## Flujo
0. Confirma ejercicio y finalidad. Ejecuta `python3 -m unittest engine.tests`.
   Detente si no termina en OK.
1. Crea docs/, work/, output/ y un .gitignore que bloquee las tres.
2. Extrae a work/input.json. 3. Valida. 4. Pregunta por deducciones.
5. Calcula y pega la tabla comparativa. 6. Escribe output/filing-pack.md con
   cada casilla en orden y el resultado final que debe mostrar el portal.
7. El contribuyente compara, presenta y firma.

Plantilla de Agents Finance: instrucción de arranque

Para usar el skill original (en la India), con las instrucciones en español; el agente responde en el idioma que le pidas:

Usa el skill itr-wala. Soy persona física residente y declaro el ejercicio
2025-26. Mis documentos están en ./docs (Form 16 y el JSON del AIS descifrado;
he tachado el PAN, el Aadhaar y los números de cuenta). Antes de leer nada,
ejecuta la autoprueba y enséñame el resultado. Después sigue SKILL.md paso a
paso, actualiza work/progress.md tras cada paso y detente tras el paquete de
presentación: yo introduciré los valores en el portal y pagaré, presentaré y
verificaré.

Resultados que declara el autor

El README afirma que la herramienta sustituye unos honorarios de unas 3.000 rupias y unas tres horas en el portal, y que el autor presenta sus propios impuestos con ella. Declara 88 pruebas fiscales calculadas a mano, 131 pruebas del validador y un fuzzer basado en propiedades que ejecuta 3.000 casos por ejercicio y finalidad en CI, además de una batería de 360.000 casos superada por el motor revisado. También describe dos fallos detectados con ese proceso: una versión temprana que negaba la reducción marginal del recargo en rentas con muchas ganancias de capital, y un caso límite de redondeo en el que 52.880 rupias más de salario daban 10 rupias menos de impuesto. Cita un reel de Instagram que, según el README, alcanzó 1,2 millones de visualizaciones en una semana. No encontramos ni una sola experiencia independiente: el hilo para recogerlas no tenía respuestas el 21 de octubre de 2026.

Limitaciones y riesgos

• Un motor probado también puede fallar. El propio proyecto reconoció que las instalaciones anteriores a la 1.3.0 podían infravalorar el impuesto del régimen nuevo cuando había rentas con tipo especial; en su ejemplo la diferencia es de 62.400 rupias. Quien presentara con una versión antigua debe recalcular.
• La transcripción es el riesgo que queda. El modelo lee los documentos, así que puede leer mal una cifra; los cruces con el Form 26AS y el AIS detectan muchos errores, pero no todos.
• Privacidad. El Python se ejecuta en local, pero los documentos que lee el agente van al proveedor del modelo. Los scripts de anonimización y extracción ciega reducen lo que ve el modelo; no eliminan esa contrapartida.
• Alcance limitado. Solo personas físicas residentes; quedan fuera los derivados y el intradía, las auditorías, la deducción por doble imposición, el diferimiento de opciones sobre acciones y varios casos de ganancias de capital, y los modelos del ejercicio 2026-27 aún deben comprobarse con la administración.
• La responsabilidad es de quien declara. No es un asesor fiscal ni asesoramiento fiscal; el propio README sugiere entregar el paquete a un chartered accountant para una revisión barata.

Errores habituales

• Dejar que el agente «solo compruebe» un total en el chat. La regla existe porque ahí es donde se cuelan los errores.
• Usar un AIS antiguo: se va completando durante la campaña, y el skill pide descargarlo de nuevo.
• Tomar los avisos del validador como ruido. Una diferencia en las retenciones suele indicar un segundo pagador o un documento que falta.
• Instalar con un comando de una línea desde la rama principal en lugar de un commit revisado y fijado, en una herramienta que lee datos de salario y de bancos.
• Mezclar ejercicios o finalidades en una misma carpeta; el skill espera una por ejercicio y finalidad.

Conclusiones

itr-wala es un ejemplo claro del patrón que se repite en este directorio, de las declaraciones familiares al cierre mensual: que el modelo lea, pregunte y explique, y que cada cifra salga de un código probado y auditable. Lo que lo hace práctico es que el contrato está por escrito: reglas de hierro en SKILL.md, un esquema estricto, un validador que falla en cerrado y una batería de pruebas que puedes ejecutar antes de fiarte. La evidencia sigue siendo el testimonio de quien lo ha construido, así que el ahorro de tiempo y dinero hay que tomarlo como una afirmación; la arquitectura, en cambio, se puede reutilizar en cualquier país donde el cálculo se pueda escribir como código.