Finance Substrate

version: 1

gates:
  - name: validate-parsers
    command: "python3 scripts/parse_engine.py --validate"
    description: "Validate all parser definitions against schema"
    frequency: before_commit
    blocking: true

  - name: self-heal
    command: "python3 scripts/self_heal.py --year {year}"
    description: "Run full self-healing validation (parsers, extractions, cross-validation, projection)"
    frequency: after_import
    blocking: false

sensors:
  - name: import-certificates
    command: "python3 scripts/import_certificates.py --year {year} --password {pw}"
    description: "Parse all certificates and report results"

  - name: parser-coverage
    command: "python3 scripts/parse_engine.py --coverage"
    description: "Report parser coverage and tax_summary keys"

  - name: validate-xlsx
    command: "python3 scripts/self_heal.py --validate-xlsx {path}"
    description: "Validate XLSX schema before importing"

  - name: cross-validate
    command: "python3 scripts/self_heal.py --year {year}"
    description: "Cross-validate certificates vs exogena vs planillas"

actuators:
  - name: create-parser
    description: "Create a new parsers/<institution>.json following templates/parser-schema.json"
    trigger: "unknown_institution in improvement-log.jsonl"
    side_effect: "Creates parsers/<name>.json"

  - name: update-parser
    description: "Update field extraction pattern when PDF format changes"
    trigger: "low_extraction_confidence or expected_nonzero_field in improvement-log.jsonl"
    side_effect: "Modifies parsers/<name>.json"

  - name: fix-xlsx-schema
    description: "Update import script column mappings when DIAN changes XLSX format"
    trigger: "exogena_schema_drift or einvoice_schema_drift in improvement-log.jsonl"
    side_effect: "Modifies importers/*.json or import_declaracion.py"

{"event": "low_extraction_confidence", "severity": "warning", "timestamp": "2026-03-19T20:21:58.964218+00:00", "parser": "nu-colombia", "confidence": 0.25, "total_fields": 4, "zero_fields": 3, "suggestion": "Parser 'nu-colombia' extracted mostly zeros — PDF format may have changed"}
{"event": "expected_nonzero_field", "severity": "warning", "timestamp": "2026-03-19T20:21:58.964383+00:00", "parser": "nu-colombia", "field": "rendimientos_gravados", "value": 0.0, "suggestion": "Field 'rendimientos_gravados' is 0 for nu-colombia — check if PDF format changed"}
{"event": "expected_nonzero_field", "severity": "warning", "timestamp": "2026-03-19T20:21:58.964433+00:00", "parser": "nu-colombia", "field": "retencion_renta", "value": 0.0, "suggestion": "Field 'retencion_renta' is 0 for nu-colombia — check if PDF format changed"}
{"event": "pension_source_discrepancy", "severity": "info", "timestamp": "2026-03-19T20:21:58.966117+00:00", "sources": {"certificates": 17883129, "exogena": 17883128, "planillas": 16320000}, "max_diff": 1563129, "suggestion": "Pension amounts differ across sources — certificates report fund-level, planillas report payment-level"}

version: 1
profile: governed

categories:
  - id: parser_accuracy
    name: Certificate Parser Accuracy
    setpoints: [S1, S2, S3]
  - id: coverage
    name: Institution & Form 210 Coverage
    setpoints: [S4, S5]
  - id: agent_improvement
    name: Agent Self-Improvement
    setpoints: [S6, S7]

setpoints:
  - id: S1
    category: parser_accuracy
    description: "All parser definitions validate against schema"
    target: 1.0
    measurement: "parsers_valid / parsers_total"
    severity: blocking

  - id: S2
    category: parser_accuracy
    description: "Zero 'Unknown' results in certificate import"
    target: 0
    measurement: "count of 'skipped' results from import_certificates"
    severity: informational

  - id: S3
    category: parser_accuracy
    description: "Aggregated retenciones within 1% of DIAN exogena total"
    target: 0.99
    measurement: "abs(certs_retenciones - exogena_retenciones) / exogena_retenciones"
    severity: blocking

  - id: S4
    category: coverage
    description: "Every parser produces at least one tax_summary field"
    target: 1.0
    measurement: "parsers_with_summary / parsers_total"
    severity: blocking

  - id: S5
    category: coverage
    description: "Tax summary maps to all required Form 210 inputs"
    target: 1.0
    measurement: "mapped_fields / required_form210_fields"
    severity: informational

  - id: S6
    category: agent_improvement
    description: "Unknown institution triggers improvement signal"
    target: 1.0
    measurement: "signals_logged / unknown_encounters"
    severity: informational

  - id: S7
    category: agent_improvement
    description: "Agent-created parser definitions pass validation"
    target: 1.0
    measurement: "agent_created_valid / agent_created_total"
    severity: blocking

{
  "version": 1,
  "last_audit_at": null,
  "controller_mode": "governed",
  "parsers": {
    "total": 10,
    "valid": 0,
    "last_validated_at": null
  },
  "last_import": {
    "year": null,
    "matched": 0,
    "unknown": 0
  },
  "agent_improvements": {
    "parsers_created": 0,
    "parsers_updated": 0,
    "last_improvement_at": null
  }
}

__pycache__/
reports/

{
  "bank": "arq",
  "label": "ARQ (ex-DolarApp) USD Account",
  "default_account": "arq-usd",
  "currency": "USD",
  "encoding": "utf-8",
  "delimiter": ",",
  "skip_rows": 0,
  "date_format": "%Y-%m-%d",
  "decimal_separator": ".",
  "thousands_separator": ",",
  "columns": {
    "date": "date",
    "description": "description",
    "amount": "amount"
  },
  "notes": "ARQ (formerly DolarApp) does not currently offer CSV export. This profile is a placeholder for manual entry or future export support. If exporting via screenshot-to-CSV conversion, ensure columns match this mapping."
}

{
  "bank": "davivienda",
  "label": "Davivienda Cuenta de Ahorros / Corriente",
  "default_account": "davivienda-savings",
  "currency": "COP",
  "encoding": "utf-8",
  "delimiter": ",",
  "skip_rows": 0,
  "date_format": "%d/%m/%Y",
  "decimal_separator": ",",
  "thousands_separator": ".",
  "columns": {
    "date": "Fecha",
    "description": "Descripcion",
    "debit": "Debito",
    "credit": "Credito"
  },
  "notes": "Davivienda CSV exports use DD/MM/YYYY dates, Colombian number formatting (. for thousands, , for decimals), and split debit/credit columns. Export from: DaviPlata app > Movimientos > Descargar extracto, or Davivienda web > Cuentas > Extracto > Descargar CSV."
}

{
  "bank": "nequi",
  "label": "Nequi Billetera Digital",
  "default_account": "nequi-wallet",
  "currency": "COP",
  "encoding": "utf-8",
  "delimiter": ",",
  "skip_rows": 0,
  "date_format": "%d/%m/%Y",
  "decimal_separator": ",",
  "thousands_separator": ".",
  "columns": {
    "date": "Fecha",
    "description": "Descripción",
    "debit": "Valor debito",
    "credit": "Valor credito"
  },
  "notes": "Nequi CSV exports follow Colombian conventions. Export from: Nequi app > Movimientos > Descargar extracto. Column names may vary between PDF-parsed and direct CSV exports — adjust mappings if needed."
}

{
  "bank": "nubank",
  "label": "Nu Colombia Tarjeta de Credito",
  "default_account": "nubank-credit",
  "currency": "COP",
  "encoding": "utf-8",
  "delimiter": ",",
  "skip_rows": 0,
  "date_format": "%Y-%m-%d",
  "decimal_separator": ".",
  "thousands_separator": ",",
  "columns": {
    "date": "date",
    "description": "title",
    "amount": "amount"
  },
  "notes": "Nubank Colombia CSV: ISO date format, single amount column (negative = purchase, positive = payment). Export from: Nu app > Tarjeta > Fatura > Compartir > CSV. Column names may vary — adjust if needed."
}

{
  "version": 1,
  "institution": {
    "id": "acciones-valores-fondos",
    "name": "ACCIONES & VALORES (FONDOS)",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["fondos de inversión colectiva", "FIC"],
    "reject_any": ["RESUMEN DE OPERACIONES"],
    "case_sensitive": false
  },
  "priority": 89,
  "password_protected": true,
  "sections": [
    {
      "id": "fondos",
      "label": "Investment fund balances",
      "fields": [
        { "key": "fic_saldo", "method": "regex", "pattern": "FIC.*?\\$\\s*([\\d.,]+)", "group": 1, "scope": "full_text" }
      ]
    }
  ],
  "computed_fields": [],
  "tax_summary_mapping": {
    "patrimonio_fondos": "sections.fondos.fic_saldo"
  }
}

{
  "version": 1,
  "institution": {
    "id": "acciones-valores",
    "name": "ACCIONES & VALORES (BURSÁTIL)",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["RESUMEN DE OPERACIONES", "SALDO EN CAJA"],
    "reject_any": ["SKANDIA", "DAVIVIENDA", "fondos de inversión colectiva"],
    "case_sensitive": false
  },
  "priority": 90,
  "password_protected": true,
  "sections": [
    {
      "id": "bursatil",
      "label": "Stock brokerage data",
      "fields": [
        { "key": "saldo_caja", "method": "regex", "pattern": "SALDO EN CAJA:\\s*([\\d.,]+)", "group": 1, "scope": "full_text" },
        { "key": "dividendos", "method": "regex", "pattern": "Dividendos.*?Totales\\s*\\n([\\d.,]+)", "group": 1, "scope": "full_text", "flags": "DOTALL" },
        { "key": "valor_acciones", "method": "regex", "pattern": "Valor neto\\s*\\n.*?([\\d.,]+)\\s*\\nTotal", "group": 1, "scope": "full_text", "flags": "DOTALL" }
      ]
    }
  ],
  "computed_fields": [],
  "tax_summary_mapping": {
    "patrimonio_caja": "sections.bursatil.saldo_caja",
    "dividendos": "sections.bursatil.dividendos",
    "patrimonio_acciones": "sections.bursatil.valor_acciones"
  }
}

{
  "version": 1,
  "institution": {
    "id": "banco-bogota",
    "name": "BANCO DE BOGOTÁ",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["BANCO DE BOGOT"],
    "reject_any": [],
    "case_sensitive": false
  },
  "priority": 80,
  "password_protected": true,
  "sections": [
    {
      "id": "credito",
      "label": "Credit obligations",
      "fields": [
        { "key": "intereses_pagados", "method": "regex", "pattern": "intereses.*?suma de:\\s*\\$([\\d.,]+)", "group": 1, "flags": "IGNORECASE DOTALL" }
      ]
    }
  ],
  "computed_fields": [],
  "tax_summary_mapping": {
    "intereses_pagados_deducible": "sections.credito.intereses_pagados"
  }
}

{
  "version": 1,
  "institution": {
    "id": "colmedica",
    "name": "COLMEDICA MEDICINA PREPAGADA",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["COLMÉDICA", "COLMEDICA"],
    "reject_any": [],
    "case_sensitive": false
  },
  "priority": 50,
  "password_protected": true,
  "sections": [
    {
      "id": "prepagada",
      "label": "Prepaid health insurance value",
      "fields": [
        { "key": "valor", "method": "regex", "pattern": "TITULAR\\s*\\n?([\\d.,]+)", "group": 1 }
      ]
    }
  ],
  "computed_fields": [],
  "tax_summary_mapping": {
    "medicina_prepagada_deduccion_r39": "sections.prepagada.valor"
  }
}

{
  "version": 1,
  "institution": {
    "id": "davivienda",
    "name": "BANCO DAVIVIENDA S.A.",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["DAVIVIENDA"],
    "reject_any": ["RAPPICARD"],
    "case_sensitive": false
  },
  "priority": 30,
  "password_protected": false,
  "sections": [
    {
      "id": "cuentas_totales",
      "label": "Savings account totals",
      "anchor": {
        "pattern": "TOTALES\\n\\d+\\n",
        "type": "regex"
      },
      "fields": [
        { "key": "saldo", "method": "dollar_amounts_after_anchor", "index": 0 },
        { "key": "rendimientos", "method": "dollar_amounts_after_anchor", "index": 1 },
        { "key": "rendimientos_no_gravados", "method": "dollar_amounts_after_anchor", "index": 2 },
        { "key": "retencion_renta", "method": "dollar_amounts_after_anchor", "index": 3 },
        { "key": "gmf_retenido", "method": "dollar_amounts_after_anchor", "index": 4 }
      ]
    },
    {
      "id": "afc",
      "label": "AFC account (Ahorro Fomento a la Construcción)",
      "anchor": {
        "pattern": "CERTIFICADO PRODUCTO CUENTA AFC",
        "type": "string_find"
      },
      "fields": [
        { "key": "aportes_directos", "method": "label_then_amount", "label": "Aportes Directos" },
        { "key": "aportes_contingente", "method": "label_then_amount", "label": "Aportes con Contingente" },
        { "key": "aportes_sin_contingente", "method": "label_then_amount", "label": "Aportes sin Contingente" },
        { "key": "rendimientos", "method": "label_then_amount", "label": "Rendimientos de los aportes" },
        { "key": "retiros_vivienda", "method": "label_then_amount", "label": "Retiros con destino vivienda" },
        { "key": "saldo_fin", "method": "regex", "pattern": "Saldo a 31/12/\\d{4}\\s*\\n?\\$?([\\d.,]+)", "group": 1 }
      ]
    }
  ],
  "computed_fields": [
    { "key": "total_aportes_afc", "expression": "sections.afc.aportes_directos + sections.afc.aportes_contingente" }
  ],
  "tax_summary_mapping": {
    "rendimientos_gravados": "sections.cuentas_totales.rendimientos - sections.cuentas_totales.rendimientos_no_gravados",
    "rendimientos_no_gravados": "sections.cuentas_totales.rendimientos_no_gravados",
    "retencion_renta": "sections.cuentas_totales.retencion_renta",
    "gmf_total": "sections.cuentas_totales.gmf_retenido",
    "gmf_deducible_50pct": "sections.cuentas_totales.gmf_retenido * 0.50",
    "patrimonio_cuentas": "sections.cuentas_totales.saldo",
    "aportes_afc_r35": "computed.total_aportes_afc"
  }
}

{
  "version": 1,
  "institution": {
    "id": "nequi",
    "name": "NEQUI (BANCOLOMBIA)",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["NEQUI"],
    "reject_any": [],
    "case_sensitive": false
  },
  "priority": 70,
  "password_protected": true,
  "sections": [
    {
      "id": "deposito",
      "label": "Low-amount deposit account",
      "fields": [
        { "key": "intereses", "method": "label_then_amount", "label": "Intereses pagados" },
        { "key": "saldo", "method": "regex", "pattern": "Saldo.*?[Dd]epósito.*?\\n\\$([\\d.,]+)", "group": 1 }
      ]
    }
  ],
  "computed_fields": [],
  "tax_summary_mapping": {
    "patrimonio_cuenta": "sections.deposito.saldo"
  }
}

{
  "version": 1,
  "institution": {
    "id": "nu-colombia",
    "name": "NU COLOMBIA",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["NU.", "NU COLOMBIA", "NU FINANCIERA"],
    "reject_any": [],
    "case_sensitive": false
  },
  "priority": 60,
  "password_protected": true,
  "sections": [
    {
      "id": "cuenta",
      "label": "Savings account data",
      "fields": [
        { "key": "gmf", "method": "regex", "pattern": "GMF o 4x1000\\)\\s*\\n\\$([\\d.,]+)", "group": 1 },
        { "key": "retencion", "method": "regex", "pattern": "Retención en la fuente\\s*\\n\\$([\\d.,]+)", "group": 1 },
        { "key": "rendimientos_totales", "method": "regex", "pattern": "Rendimientos totales del año\\s*\\n\\$([\\d.,]+)", "group": 1 },
        { "key": "rendimientos_no_gravables", "method": "regex", "pattern": "Rendimientos no gravables[^$]*\\$([\\d.,]+)", "group": 1, "flags": "DOTALL" }
      ]
    }
  ],
  "computed_fields": [],
  "tax_summary_mapping": {
    "rendimientos_gravados": "sections.cuenta.rendimientos_totales - sections.cuenta.rendimientos_no_gravables",
    "rendimientos_no_gravados": "sections.cuenta.rendimientos_no_gravables",
    "retencion_renta": "sections.cuenta.retencion",
    "gmf_total": "sections.cuenta.gmf",
    "gmf_deducible_50pct": "sections.cuenta.gmf * 0.50"
  }
}

{
  "version": 1,
  "institution": {
    "id": "planilla-pila",
    "name": "PLANILLA PILA (Social Security)",
    "cert_type": "planilla-pila"
  },
  "identification": {
    "require_any": ["PLANILLA INTEGRADA", "AUTOLIQUIDACION DE APORTES"],
    "reject_any": [],
    "case_sensitive": false
  },
  "priority": 5,
  "password_protected": false,
  "sections": [
    {
      "id": "subsistemas",
      "label": "Social security subsystem totals",
      "fields": [
        { "key": "salud", "method": "regex", "pattern": "Salud\\n\\d+\\n([\\d.]+)", "group": 1 },
        { "key": "pension", "method": "regex", "pattern": "Pensión\\n\\d+\\n([\\d.]+)", "group": 1 },
        { "key": "riesgos_laborales", "method": "regex", "pattern": "Riesgos Laborales\\n\\d+\\n([\\d.]+)", "group": 1 },
        { "key": "total", "method": "regex", "pattern": "TOTALES\\n\\d+\\n[\\d.]+\\n([\\d.]+)", "group": 1 }
      ]
    },
    {
      "id": "cotizante",
      "label": "Contributor detail",
      "fields": [
        { "key": "ibc_pension", "method": "regex", "pattern": "230901\\n([\\d.]+)", "group": 1, "scope": "full_text" },
        { "key": "cotizacion_pension", "method": "regex", "pattern": "Cotización \\nObligatoria\\n.*?\\n.*?([\\d.]+)\\n", "group": 1, "flags": "DOTALL" },
        { "key": "fsp_solidaridad", "method": "regex", "pattern": "Aporte FSP.*?Solidaridad.*?\\n.*?\\n.*?\\n.*?([\\d.]+)", "group": 1, "flags": "DOTALL" },
        { "key": "fsp_subsistencia", "method": "regex", "pattern": "Aporte FSP.*?Subsistencia.*?\\n.*?\\n.*?\\n.*?\\n.*?([\\d.]+)", "group": 1, "flags": "DOTALL" }
      ]
    },
    {
      "id": "periodo",
      "label": "Payment period",
      "fields": [
        { "key": "periodo", "method": "regex", "pattern": "(\\d{4}-\\d{2})", "group": 1, "scope": "full_text" },
        { "key": "fecha_pago", "method": "regex", "pattern": "FECHA PAGO.*?\\n.*?(\\d{2}/\\d{2}/\\d{4})", "group": 1, "scope": "full_text", "flags": "DOTALL" }
      ]
    }
  ],
  "computed_fields": [],
  "tax_summary_mapping": {
    "salud_obligatoria": "sections.subsistemas.salud",
    "pension_obligatoria": "sections.subsistemas.pension",
    "riesgos_laborales": "sections.subsistemas.riesgos_laborales",
    "total_seguridad_social": "sections.subsistemas.total"
  }
}

{
  "version": 1,
  "institution": {
    "id": "rappicard",
    "name": "RAPPICARD",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["RAPPICARD"],
    "reject_any": [],
    "case_sensitive": false
  },
  "priority": 10,
  "password_protected": true,
  "sections": [
    {
      "id": "tarjeta",
      "label": "Credit card data (values after Totales row)",
      "anchor": {
        "pattern": "Totales\\n",
        "type": "regex"
      },
      "fields": [
        { "key": "saldo", "method": "dollar_amounts_after_anchor", "index": 0 },
        { "key": "pagos", "method": "dollar_amounts_after_anchor", "index": 1 },
        { "key": "intereses", "method": "dollar_amounts_after_anchor", "index": 2 },
        { "key": "gmf", "method": "dollar_amounts_after_anchor", "index": 3 },
        { "key": "consumos", "method": "dollar_amounts_after_anchor", "index": 4 }
      ]
    },
    {
      "id": "cashback",
      "label": "Cashback redemption",
      "fields": [
        { "key": "valor", "method": "regex", "pattern": "\\$([\\d.,]+)\\s*\\n.*?[Cc]ashback", "group": 1, "scope": "full_text", "flags": "DOTALL" }
      ]
    }
  ],
  "computed_fields": [],
  "tax_summary_mapping": {
    "deuda_patrimonio": "sections.tarjeta.saldo",
    "gmf_total": "sections.tarjeta.gmf",
    "gmf_deducible_50pct": "sections.tarjeta.gmf * 0.50"
  }
}

{
  "version": 1,
  "institution": {
    "id": "rappicuenta",
    "name": "RAPPIPAY (RAPPICUENTA)",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["RAPPICUENTA", "RAPPIPAY"],
    "reject_any": ["RAPPICARD"],
    "case_sensitive": false
  },
  "priority": 11,
  "password_protected": true,
  "sections": [
    {
      "id": "cuenta",
      "label": "Savings account",
      "anchor": {
        "pattern": "Cuenta ahorros",
        "type": "string_find"
      },
      "fields": [
        { "key": "saldo", "method": "label_then_amount", "label": "Cuenta ahorros" },
        { "key": "rendimientos", "method": "regex", "pattern": "Rendimientos\\nfinancieros[^$]*\\$([\\d.,]+)", "group": 1, "scope": "full_text", "flags": "DOTALL" },
        { "key": "rendimientos_no_gravables", "method": "regex", "pattern": "no\\ngravados\\*?\\s*\\$([\\d.,]+)", "group": 1, "scope": "full_text" },
        { "key": "gmf", "method": "regex", "pattern": "GMF\\*{0,2}\\s*\\$([\\d.,]+)", "group": 1, "scope": "full_text" }
      ]
    }
  ],
  "computed_fields": [],
  "tax_summary_mapping": {
    "patrimonio_cuenta": "sections.cuenta.saldo",
    "rendimientos_gravados": "sections.cuenta.rendimientos - sections.cuenta.rendimientos_no_gravables",
    "rendimientos_no_gravados": "sections.cuenta.rendimientos_no_gravables",
    "gmf_total": "sections.cuenta.gmf",
    "gmf_deducible_50pct": "sections.cuenta.gmf * 0.50"
  }
}

{
  "version": 1,
  "institution": {
    "id": "skandia",
    "name": "SKANDIA",
    "cert_type": "certificado-tributario"
  },
  "identification": {
    "require_any": ["SKANDIA"],
    "reject_any": [],
    "case_sensitive": false
  },
  "priority": 40,
  "password_protected": true,
  "sections": [
    {
      "id": "pension_obligatoria",
      "label": "Mandatory pension (may have multiple fund sections)",
      "fields": [
        { "key": "aportes_independientes", "method": "sum_all_regex_matches", "pattern": "Obligatorios independientes\\s*\\n([\\d.,]+)", "group": 1, "scope": "full_text" },
        { "key": "fondo_solidaridad", "method": "sum_all_regex_matches", "pattern": "Fondo de Solidaridad Pensional\\s*\\n([\\d.,]+)", "group": 1, "scope": "full_text" }
      ]
    },
    {
      "id": "voluntaria",
      "label": "Voluntary pension (Multifund or similar)",
      "anchor": {
        "pattern": "Fondo Voluntario de Pensi",
        "type": "string_find"
      },
      "fields": [
        { "key": "aportes_con_retencion", "method": "line_after_label", "label": "Aportes realizados durante el año con retención contingente" },
        { "key": "aportes_sin_retencion", "method": "line_after_label", "label": "Aportes realizados durante el año sin retención contingente" },
        { "key": "valorizacion", "method": "line_after_label", "label": "Valorización de aportes" },
        { "key": "retiro_aportes_contingente", "method": "regex", "pattern": "Retiro de aportes efectuados con retención contingente\\s*\\n([\\d.,]+)", "group": 1 },
        { "key": "retiro_rendimientos", "method": "regex", "pattern": "Retiro de rendimientos sin cumplimiento.*?\\n([\\d.,]+)", "group": 1 },
        { "key": "retencion_contingente", "method": "line_after_label", "label": "Retención contingente practicada" },
        { "key": "retencion_rendimientos", "method": "regex", "pattern": "Retención.*?sobre rendimientos\\s*\\n([\\d.,]+)", "group": 1 },
        { "key": "saldo_fin", "method": "regex", "pattern": "Saldo a diciembre 31 de {year}\\s*\\n([\\d.,]+)", "group": 1 }
      ]
    },
    {
      "id": "cesantias",
      "label": "Severance fund (cesantías)",
      "anchor": {
        "pattern": "Fondo de Cesant",
        "type": "string_find"
      },
      "fields": [
        { "key": "saldo", "method": "regex", "pattern": "2017 en adelante.*?\\n([\\d.,]+)", "group": 1 },
        { "key": "rendimientos", "method": "line_after_label", "label": "Rendimientos causados durante el año" }
      ]
    }
  ],
  "computed_fields": [
    { "key": "pension_oblig_total", "expression": "sections.pension_obligatoria.aportes_independientes + sections.pension_obligatoria.fondo_solidaridad" },
    { "key": "retencion_total", "expression": "sections.voluntaria.retencion_contingente + sections.voluntaria.retencion_rendimientos" }
  ],
  "tax_summary_mapping": {
    "pension_oblig_plus_fsp": "computed.pension_oblig_total",
    "pension_voluntaria_aportes": "sections.voluntaria.aportes_con_retencion",
    "retencion_total": "computed.retencion_total",
    "retiro_aportes_capital_r58": "sections.voluntaria.retiro_aportes_contingente",
    "retiro_rendimientos_capital_r58": "sections.voluntaria.retiro_rendimientos",
    "patrimonio_cesantias": "sections.cesantias.saldo",
    "patrimonio_voluntaria": "sections.voluntaria.saldo_fin",
    "rendimientos_cesantias": "sections.cesantias.rendimientos",
    "rendimientos_voluntaria": "sections.voluntaria.valorizacion"
  }
}

#!/usr/bin/env python3
"""
Monthly budget planner for Colombian residents earning USD salary.

Allocates income across parafiscales, AFC/pension contributions,
tax savings fund, and living expenses.

Usage:
    python3 budget_planner.py --monthly-usd 8000 --year 2025
    python3 budget_planner.py --monthly-usd 8000 --year 2025 --deadline 2026-10-01
    python3 budget_planner.py --monthly-usd 8000 --year 2025 --parafiscales 2360000
"""

import argparse
import json
import sys
from datetime import date, datetime
from pathlib import Path

TEMPLATES_DIR = Path(__file__).parent.parent / "templates"
DATA_DIR = Path.home() / ".finance-substrate"


def load_current_trm() -> float:
    """Get the most recent TRM from cache."""
    trm_file = DATA_DIR / "fx" / "trm-history.jsonl"
    if not trm_file.exists():
        return 4000.0
    latest = None
    with open(trm_file) as f:
        for line in f:
            line = line.strip()
            if line:
                rec = json.loads(line)
                if latest is None or rec["date"] > latest["date"]:
                    latest = rec
    return latest["valor"] if latest else 4000.0


def load_tax_tables(year: int) -> dict:
    tables_file = TEMPLATES_DIR / f"tax-tables-{year}.json"
    if not tables_file.exists():
        candidates = sorted(TEMPLATES_DIR.glob("tax-tables-*.json"), reverse=True)
        if candidates:
            tables_file = candidates[0]
        else:
            return {"uvt_value": 47065}
    with open(tables_file) as f:
        return json.load(f)


def calculate_tax(taxable_uvt: float, brackets: list) -> float:
    tax = 0.0
    for bracket in brackets:
        lower = bracket["from_uvt"]
        upper = bracket.get("to_uvt", float("inf"))
        rate = bracket["rate"]
        base_tax = bracket.get("base_tax_uvt", 0)
        if taxable_uvt > lower:
            taxable_in_bracket = min(taxable_uvt, upper) - lower
            tax = base_tax + (taxable_in_bracket * rate)
    return tax


def estimate_annual_tax(
    gross_annual_cop: float,
    ss_incr: float,
    afc_annual: float,
    vol_pension_annual: float,
    fixed_deductions: float,
    uvt: float,
    brackets: list,
) -> dict:
    """Quick tax estimate without full projection."""
    renta_liquida = max(0, gross_annual_cop - ss_incr - vol_pension_annual)
    exempt_25pct = min(renta_liquida * 0.25, 790 * uvt)
    total_exentas = afc_annual + exempt_25pct
    total_deducciones = fixed_deductions
    raw = total_exentas + total_deducciones
    cap = min(renta_liquida * 0.40, 1340 * uvt)
    limited = min(raw, cap)
    taxable = max(0, renta_liquida - limited)
    taxable_uvt = taxable / uvt
    tax_uvt = calculate_tax(taxable_uvt, brackets)
    tax_cop = tax_uvt * uvt
    anticipo = max(0, tax_cop * 0.75)
    return {
        "gross_annual": round(gross_annual_cop),
        "renta_liquida": round(renta_liquida),
        "exentas_limited": round(limited),
        "taxable": round(taxable),
        "tax": round(tax_cop),
        "anticipo_next": round(anticipo),
        "total_to_pay": round(tax_cop + anticipo),
    }


def main():
    parser = argparse.ArgumentParser(description="Monthly budget planner")
    parser.add_argument("--monthly-usd", type=float, required=True, help="Monthly salary in USD")
    parser.add_argument("--year", type=int, default=2025, help="Tax year")
    parser.add_argument("--parafiscales", type=float, default=2360000, help="Monthly PILA payment (COP)")
    parser.add_argument("--afc-annual", type=float, default=0, help="Annual AFC target (0 = auto from optimizer)")
    parser.add_argument("--vol-pension-annual", type=float, default=20000000, help="Annual voluntary pension")
    parser.add_argument("--fixed-deductions", type=float, default=4600000, help="Annual fixed deductions (medicina + GMF + e-inv)")
    parser.add_argument("--anticipo-anterior", type=float, default=0, help="Anticipo from prior year")
    parser.add_argument("--retenciones", type=float, default=1400000, help="Estimated annual retenciones")
    parser.add_argument("--deadline", type=str, default=None, help="Filing deadline date (YYYY-MM-DD), auto-computes months remaining")
    parser.add_argument("--months-to-deadline", type=int, default=12, help="Months until filing deadline (fallback if --deadline not given)")
    parser.add_argument("--trm", type=float, default=0, help="Override TRM rate (0 = use latest)")
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args()

    # Resolve months to deadline: --deadline takes precedence over --months-to-deadline
    deadline_date = None
    if args.deadline:
        try:
            deadline_date = datetime.strptime(args.deadline, "%Y-%m-%d").date()
        except ValueError:
            print(f"Error: --deadline must be YYYY-MM-DD, got '{args.deadline}'", file=sys.stderr)
            sys.exit(1)
        today = date.today()
        if deadline_date <= today:
            print(f"Error: --deadline {args.deadline} is in the past", file=sys.stderr)
            sys.exit(1)
        months_remaining = (deadline_date.year - today.year) * 12 + (deadline_date.month - today.month)
        # Count partial months as a full month
        if today.day > 1 and deadline_date.day >= today.day:
            pass  # already counted
        months_remaining = max(1, months_remaining)
        args.months_to_deadline = months_remaining

    tables = load_tax_tables(args.year)
    uvt = tables.get("uvt_value", 47065)
    brackets = tables.get("brackets_renta", [])
    trm = args.trm if args.trm > 0 else load_current_trm()

    monthly_cop = args.monthly_usd * trm
    annual_cop = monthly_cop * 12

    # Social security INCR
    ss_monthly = args.parafiscales
    ss_annual = ss_monthly * 12

    # Auto-compute optimal AFC if not specified
    if args.afc_annual == 0:
        # Simplified optimizer: fill up to 1,340 UVT cap
        renta_liq = annual_cop - ss_annual - args.vol_pension_annual
        exempt_25 = min(renta_liq * 0.25, 790 * uvt)
        cap = min(renta_liq * 0.40, 1340 * uvt)
        headroom = max(0, cap - exempt_25 - args.fixed_deductions)
        afc_annual = min(headroom, annual_cop * 0.30, 3800 * uvt - args.vol_pension_annual)
        afc_annual = max(0, afc_annual)
    else:
        afc_annual = args.afc_annual

    afc_monthly = afc_annual / 12
    vol_pension_monthly = args.vol_pension_annual / 12

    # Tax estimate
    tax_est = estimate_annual_tax(
        annual_cop, ss_annual + args.vol_pension_annual,
        afc_annual, args.vol_pension_annual,
        args.fixed_deductions, uvt, brackets,
    )

    saldo_pagar = max(0, tax_est["tax"] + tax_est["anticipo_next"] - args.anticipo_anterior - args.retenciones)
    monthly_tax_savings = saldo_pagar / max(1, args.months_to_deadline)

    available = monthly_cop - ss_monthly - afc_monthly - vol_pension_monthly - monthly_tax_savings

    result = {
        "monthly_usd": args.monthly_usd,
        "trm": round(trm, 2),
        "monthly_cop": round(monthly_cop),
        "annual_cop": round(annual_cop),
        "uvt": uvt,
        "allocations": {
            "parafiscales": {"cop": round(ss_monthly), "usd": round(ss_monthly / trm), "pct": round(ss_monthly / monthly_cop * 100, 1)},
            "afc": {"cop": round(afc_monthly), "usd": round(afc_monthly / trm), "pct": round(afc_monthly / monthly_cop * 100, 1), "annual": round(afc_annual)},
            "vol_pension": {"cop": round(vol_pension_monthly), "usd": round(vol_pension_monthly / trm), "pct": round(vol_pension_monthly / monthly_cop * 100, 1), "annual": round(args.vol_pension_annual)},
            "tax_savings": {"cop": round(monthly_tax_savings), "usd": round(monthly_tax_savings / trm), "pct": round(monthly_tax_savings / monthly_cop * 100, 1), "total": round(saldo_pagar)},
            "available": {"cop": round(available), "usd": round(available / trm), "pct": round(available / monthly_cop * 100, 1)},
        },
        "tax_estimate": tax_est,
        "saldo_pagar": round(saldo_pagar),
        "months_to_deadline": args.months_to_deadline,
        "deadline": deadline_date.isoformat() if deadline_date else None,
    }

    if args.json:
        print(json.dumps(result, indent=2))
        return

    a = result["allocations"]
    print(f"\n{'='*65}")
    print(f"  PLAN PRESUPUESTAL MENSUAL — {args.year}")
    if deadline_date:
        print(f"  Fecha límite: {deadline_date.isoformat()}")
    print(f"{'='*65}")
    print(f"  Ingreso: ${args.monthly_usd:,.0f} USD × TRM {trm:,.2f} = ${monthly_cop:,.0f} COP")
    print(f"  UVT {args.year}: ${uvt:,.0f}")
    print()

    print(f"  {'Categoría':<30s} {'COP':>12s} {'USD':>8s} {'%':>6s}")
    print(f"  {'-'*58}")
    for name, label in [
        ("parafiscales", "Parafiscales PILA"),
        ("afc", f"AFC (${a['afc']['annual']:,.0f}/año)"),
        ("vol_pension", f"Pensión vol. (${a['vol_pension']['annual']:,.0f}/año)"),
        ("tax_savings", f"Ahorro renta (${a['tax_savings']['total']:,.0f} total)"),
        ("available", "** Disponible **"),
    ]:
        d = a[name]
        marker = ">>>" if name == "available" else "   "
        print(f"{marker} {label:<30s} ${d['cop']:>11,.0f} ${d['usd']:>7,.0f} {d['pct']:>5.1f}%")

    print(f"\n  {'─'*58}")
    print(f"    TOTAL                        ${monthly_cop:>11,.0f} ${args.monthly_usd:>7,.0f} 100.0%")

    print(f"\n  Impuesto estimado AG {args.year}: ${tax_est['tax']:,.0f}")
    print(f"  Anticipo siguiente: ${tax_est['anticipo_next']:,.0f}")
    print(f"  Saldo a pagar proyectado: ${saldo_pagar:,.0f}")
    print(f"  Meses para ahorrar: {args.months_to_deadline}")

    if args.months_to_deadline < 6:
        print(f"\n  ⚠ ALERTA: Plazo ajustado — solo {args.months_to_deadline} meses para acumular ${saldo_pagar:,.0f} COP")

    if available < 0:
        print(f"\n  ⚠ ALERTA: El presupuesto está en déficit por ${abs(available):,.0f} COP/mes")
        print(f"  Considere reducir AFC o pensión voluntaria.")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Fetch TRM (Tasa Representativa del Mercado) from datos.gov.co open data API.

Usage:
    python3 fetch_trm.py                          # Today's rate
    python3 fetch_trm.py --date 2026-03-15        # Specific date
    python3 fetch_trm.py --from 2026-03-01 --to 2026-03-19  # Date range
    python3 fetch_trm.py --days 30                # Last N days
"""

import argparse
import json
import sys
import urllib.request
import urllib.parse
from datetime import datetime, timedelta
from pathlib import Path

DATA_DIR = Path.home() / ".finance-substrate"
TRM_FILE = DATA_DIR / "fx" / "trm-history.jsonl"

API_BASE = "https://www.datos.gov.co/resource/32sa-8pi3.json"


def ensure_dirs():
    (DATA_DIR / "fx").mkdir(parents=True, exist_ok=True)
    if not TRM_FILE.exists():
        TRM_FILE.touch()


def fetch_trm(date_from: str | None = None, date_to: str | None = None, limit: int = 10) -> list:
    """Fetch TRM rates from datos.gov.co."""
    params = {
        "$order": "vigenciadesde DESC",
        "$limit": str(limit),
    }

    if date_from and date_to:
        params["$where"] = (
            f"vigenciadesde >= '{date_from}T00:00:00.000' "
            f"AND vigenciadesde <= '{date_to}T23:59:59.999'"
        )
        params["$limit"] = "1000"
    elif date_from:
        params["$where"] = f"vigenciadesde >= '{date_from}T00:00:00.000'"

    url = f"{API_BASE}?{urllib.parse.urlencode(params)}"

    try:
        req = urllib.request.Request(url, headers={"Accept": "application/json"})
        with urllib.request.urlopen(req, timeout=15) as resp:
            data = json.loads(resp.read().decode())
    except Exception as e:
        print(f"Error fetching TRM: {e}", file=sys.stderr)
        sys.exit(1)

    results = []
    for entry in data:
        rate = {
            "date": entry.get("vigenciadesde", "")[:10],
            "vigencia_hasta": entry.get("vigenciahasta", "")[:10],
            "valor": float(entry.get("valor", 0)),
        }
        results.append(rate)

    return results


def load_existing_dates() -> set:
    """Load dates already in TRM history."""
    dates = set()
    if TRM_FILE.exists():
        with open(TRM_FILE) as f:
            for line in f:
                line = line.strip()
                if line:
                    entry = json.loads(line)
                    dates.add(entry.get("date"))
    return dates


def save_rates(rates: list):
    """Append new rates to TRM history, skip duplicates."""
    existing = load_existing_dates()
    new_count = 0

    with open(TRM_FILE, "a") as f:
        for rate in rates:
            if rate["date"] not in existing:
                f.write(json.dumps(rate, ensure_ascii=False) + "\n")
                existing.add(rate["date"])
                new_count += 1

    return new_count


def main():
    parser = argparse.ArgumentParser(description="Fetch TRM (USD/COP) from datos.gov.co")
    parser.add_argument("--date", help="Specific date (YYYY-MM-DD)")
    parser.add_argument("--from", dest="date_from", help="Start date (YYYY-MM-DD)")
    parser.add_argument("--to", dest="date_to", help="End date (YYYY-MM-DD)")
    parser.add_argument("--days", type=int, help="Fetch last N days")
    parser.add_argument("--no-save", action="store_true", help="Print only, don't save to history")
    args = parser.parse_args()

    ensure_dirs()

    if args.date:
        rates = fetch_trm(date_from=args.date, date_to=args.date, limit=1)
    elif args.days:
        d_from = (datetime.now() - timedelta(days=args.days)).strftime("%Y-%m-%d")
        d_to = datetime.now().strftime("%Y-%m-%d")
        rates = fetch_trm(date_from=d_from, date_to=d_to)
    elif args.date_from:
        d_to = args.date_to or datetime.now().strftime("%Y-%m-%d")
        rates = fetch_trm(date_from=args.date_from, date_to=d_to)
    else:
        # Default: latest rate
        rates = fetch_trm(limit=1)

    if not rates:
        print("No TRM data found for the specified date(s).")
        sys.exit(0)

    # Print results
    for r in sorted(rates, key=lambda x: x["date"]):
        print(f"{r['date']}  TRM: ${r['valor']:,.2f} COP/USD")

    # Save to history
    if not args.no_save:
        new = save_rates(rates)
        if new:
            print(f"\n{new} new rate(s) saved to {TRM_FILE}")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Form 210 filler — generates agent-browser commands to fill the DIAN MUISCA
Form 210 wizard from tax projection output.

Reads the projection from tax_projection.py (or a saved JSON file) and emits
a shell script with agent-browser commands that navigate the 15-step wizard,
snapshot each step to get fresh field refs, and fill every editable casilla.

Usage:
    # Run projection inline and generate fill script:
    python3 fill_form210.py --year 2024 > fill.sh

    # Use a previously saved projection JSON:
    python3 fill_form210.py --input projection.json > fill.sh

    # Override defaults:
    python3 fill_form210.py --year 2024 --genero 2 --ciiu 6201 --anticipo 0

    # Dry-run: print the mapping without generating shell commands:
    python3 fill_form210.py --year 2024 --dry-run
"""

import argparse
import json
import sys
import textwrap
from pathlib import Path

SCRIPT_DIR = Path(__file__).parent
SCHEMA_FILE = SCRIPT_DIR.parent / "templates" / "form-210-schema.json"

# ---------------------------------------------------------------------------
# Mapping: tax_projection output key  -->  (casilla, wizard step index)
#
# Only EDITABLE casillas that have a data_source in tax_projection are mapped.
# Auto-calculated (disabled) casillas are skipped by the filler.
# ---------------------------------------------------------------------------

PROJECTION_MAP = {
    # Step 3 — Patrimonio
    "form_210.patrimonio.R29_patrimonio_bruto":       (29, 2),
    # R30 deudas — not in current projection; defaults to 0
    # R31 auto-calculated

    # Step 4 — Rentas de trabajo
    "form_210.rentas_trabajo.R32_ingresos_brutos":    (32, 3),
    "form_210.rentas_trabajo.R33_incr":               (33, 3),
    # R34 auto-calculated
    "form_210.rentas_trabajo.R35_aportes_afc":        (35, 3),
    "form_210.rentas_trabajo.R36_otras_rentas_exentas": (36, 3),
    # R37 auto-calculated
    "form_210.rentas_trabajo.R38_intereses_vivienda": (38, 3),
    "form_210.rentas_trabajo.R39_otras_deducciones":  (39, 3),
    # R40, R41, R42 auto-calculated

    # Step 6 — Rentas de capital
    "form_210.rentas_capital.R58_ingresos_brutos":    (58, 5),
    "form_210.rentas_capital.R59_incr":               (59, 5),
    # R61, R73 auto-calculated

    # Step 11 — Liquidacion
    "form_210.impuesto.R130_anticipo_anterior":       (130, 10),
    "form_210.impuesto.R132_retenciones":             (132, 10),
}


def resolve_projection_value(projection: dict, dotpath: str):
    """Traverse a nested dict using a dotted path like 'form_210.patrimonio.R29_...'."""
    parts = dotpath.split(".")
    node = projection
    for p in parts:
        if isinstance(node, dict) and p in node:
            node = node[p]
        else:
            return None
    return node


def dian_round(value) -> int:
    """DIAN rounds all values to nearest thousand (no decimals)."""
    if value is None:
        return 0
    v = int(round(float(value), -3))
    return max(v, 0)


def load_projection(args) -> dict:
    """Load or compute the tax projection."""
    if args.input:
        with open(args.input) as f:
            return json.load(f)

    # Import and run tax_projection inline
    sys.path.insert(0, str(SCRIPT_DIR))
    from tax_projection import project_tax
    return project_tax(
        year=args.year,
        uvt_override=args.uvt,
        anticipo_anterior=args.anticipo,
        nit_suffix=args.nit_suffix,
    )


def load_schema() -> dict:
    """Load the form-210-schema.json."""
    with open(SCHEMA_FILE) as f:
        return json.load(f)


def build_fill_plan(projection: dict, genero: str, ciiu: str) -> list:
    """
    Build an ordered list of fill actions grouped by wizard step.

    Each action is a dict:
      {step, casilla, label, field_type, value, action}
    where action is one of: fill_text, select_combo, select_radio.
    """
    plan = []

    # ── Step 1: Datos Declarante ──────────────────────────────────
    plan.append({
        "step": 0, "casilla": 286,
        "label": "Genero",
        "field_type": "combobox",
        "value": genero,
        "action": "select_combo",
    })
    plan.append({
        "step": 0, "casilla": 24,
        "label": "Actividad economica principal",
        "field_type": "combobox",
        "value": ciiu,
        "action": "select_combo",
    })

    # ── Step 2: Deduccion imputable sin limitantes ────────────────
    einvoices = projection.get("einvoices", {})
    has_einvoices = einvoices.get("count", 0) > 0
    total_facturado = dian_round(einvoices.get("total_facturado", 0))

    plan.append({
        "step": 1, "casilla": 299,
        "label": "Factura electronica",
        "field_type": "radio",
        "value": "Si" if has_einvoices else "No",
        "action": "select_radio",
    })
    if has_einvoices:
        plan.append({
            "step": 1, "casilla": 297,
            "label": "Valor compras con factura electronica",
            "field_type": "textbox",
            "value": total_facturado,
            "action": "fill_text",
        })

    # Default No for the remaining yes/no questions
    for cas, label in [
        (245, "Victima del conflicto armado"),
        (247, "Beneficiario convenio doble tributacion"),
        (249, "Residente fiscal"),
        (251, "Obligado a llevar contabilidad"),
    ]:
        plan.append({
            "step": 1, "casilla": cas,
            "label": label,
            "field_type": "radio",
            "value": "No",
            "action": "select_radio",
        })

    # ── Steps 3-14: Mapped casillas from projection ──────────────
    for dotpath, (casilla, step_idx) in sorted(PROJECTION_MAP.items(), key=lambda x: (x[1][1], x[1][0])):
        raw = resolve_projection_value(projection, dotpath)
        value = dian_round(raw)
        # Extract the label from the key (e.g. R32_ingresos_brutos -> R32 Ingresos brutos)
        key_tail = dotpath.rsplit(".", 1)[-1]
        label = key_tail.replace("_", " ")
        plan.append({
            "step": step_idx,
            "casilla": casilla,
            "label": label,
            "field_type": "textbox",
            "value": value,
            "action": "fill_text",
        })

    return plan


def emit_shell_script(plan: list, dry_run: bool = False):
    """
    Emit a bash script with agent-browser commands.

    The generated script:
    1. Groups actions by wizard step
    2. Clicks the step counter to navigate
    3. Snapshots to get fresh field refs
    4. Fills each field
    5. Clicks Siguiente to advance

    The script is idempotent — re-running skips already-filled fields
    (agent-browser type commands overwrite field content).
    """
    lines = []
    lines.append("#!/usr/bin/env bash")
    lines.append("# ================================================================")
    lines.append("# DIAN Form 210 Filler — Auto-generated by fill_form210.py")
    lines.append("# ================================================================")
    lines.append("#")
    lines.append("# INSTRUCTIONS:")
    lines.append("#   1. Open the DIAN MUISCA Form 210 wizard in agent-browser")
    lines.append("#   2. Run this script (or paste commands one step at a time)")
    lines.append("#   3. Review each step before clicking Siguiente")
    lines.append("#   4. Field refs change between sessions — if a ref fails,")
    lines.append("#      re-run the snapshot command for that step and update the ref")
    lines.append("#")
    lines.append("# This script uses placeholder refs (<REF_casilla_NNN>).")
    lines.append("# After each snapshot, replace them with the actual refs from")
    lines.append("# the snapshot output.")
    lines.append("#")
    lines.append("# DIAN rounds all values to nearest thousand (no decimals).")
    lines.append("# ================================================================")
    lines.append("")
    lines.append("set -euo pipefail")
    lines.append("")

    if dry_run:
        lines.append("# DRY RUN — no commands will be executed")
        lines.append("")

    # Group by step
    steps = {}
    for action in plan:
        s = action["step"]
        steps.setdefault(s, []).append(action)

    step_titles = {
        0: "Datos del Declarante",
        1: "Deduccion Imputable sin limitantes",
        2: "Patrimonio",
        3: "Rentas de trabajo",
        4: "Rentas de trabajo no relacion laboral",
        5: "Rentas de capital",
        6: "Rentas no laborales",
        7: "Cedula general",
        8: "Cedula de pensiones",
        9: "Dividendos y participaciones",
        10: "Liquidacion privada",
        11: "Ganancias ocasionales",
        12: "Anticipo y saldo a favor",
        13: "Saldo a pagar o a favor",
        14: "Firmar y presentar",
    }

    for step_idx in sorted(steps.keys()):
        actions = steps[step_idx]
        title = step_titles.get(step_idx, f"Step {step_idx + 1}")

        lines.append(f"# ── Step {step_idx + 1}: {title} {'─' * max(1, 50 - len(title))}")
        lines.append("")

        # Navigate to step
        lines.append(f"# Navigate to step {step_idx + 1}")
        lines.append(f'agent-browser js "document.querySelectorAll(\'.step-counter\')[{step_idx}].click()"')
        lines.append("")

        # Snapshot to get field refs
        lines.append(f"# Snapshot step {step_idx + 1} to get field refs")
        lines.append("agent-browser snapshot")
        lines.append("")

        lines.append("# Fill fields (replace <REF_casilla_NNN> with actual refs from snapshot)")

        for act in actions:
            cas = act["casilla"]
            label = act["label"]
            value = act["value"]
            field_type = act["field_type"]
            ref_placeholder = f"<REF_casilla_{cas}>"

            lines.append(f"# Casilla {cas}: {label}")

            if act["action"] == "fill_text":
                if dry_run:
                    lines.append(f"#   -> Would fill casilla {cas} with {value}")
                else:
                    lines.append(f'agent-browser click "{ref_placeholder}"')
                    lines.append(f'agent-browser clear-and-type "{ref_placeholder}" "{value}"')
            elif act["action"] == "select_combo":
                if dry_run:
                    lines.append(f"#   -> Would select '{value}' in combobox casilla {cas}")
                else:
                    lines.append(f'agent-browser click "{ref_placeholder}"')
                    lines.append(f'agent-browser select "{ref_placeholder}" "{value}"')
            elif act["action"] == "select_radio":
                if dry_run:
                    lines.append(f"#   -> Would select radio '{value}' for casilla {cas}")
                else:
                    # Radio buttons: click the option matching the value
                    lines.append(f'agent-browser click "{ref_placeholder}_{value}"')
            lines.append("")

        # Advance to next step
        lines.append(f"# Advance from step {step_idx + 1}")
        lines.append('agent-browser click "Siguiente"')
        lines.append("")

    return "\n".join(lines)


def print_dry_run_table(plan: list):
    """Print a human-readable table of all fill actions."""
    print(f"\n{'='*80}")
    print("  FORM 210 FILL PLAN (dry run)")
    print(f"{'='*80}")
    print(f"  {'Step':>4}  {'Casilla':>7}  {'Action':<14}  {'Value':>15}  Label")
    print(f"  {'─'*4}  {'─'*7}  {'─'*14}  {'─'*15}  {'─'*30}")
    for act in plan:
        step_display = act["step"] + 1
        value_str = str(act["value"])
        if isinstance(act["value"], (int, float)) and act["value"] > 0:
            value_str = f"${act['value']:,.0f}"
        print(f"  {step_display:>4}  {act['casilla']:>7}  {act['action']:<14}  {value_str:>15}  {act['label']}")
    print(f"\n  Total actions: {len(plan)}")
    print()


def print_mapping_json(plan: list):
    """Print the fill plan as JSON for programmatic consumption."""
    output = []
    for act in plan:
        output.append({
            "step": act["step"] + 1,
            "casilla": act["casilla"],
            "label": act["label"],
            "field_type": act["field_type"],
            "value": act["value"],
            "action": act["action"],
        })
    print(json.dumps(output, indent=2, ensure_ascii=False))


def main():
    parser = argparse.ArgumentParser(
        description="Generate agent-browser commands to fill DIAN Form 210"
    )
    parser.add_argument("--year", type=int, default=2024,
                        help="Tax year (default: 2024)")
    parser.add_argument("--uvt", type=float,
                        help="Override UVT value")
    parser.add_argument("--anticipo", type=float, default=0,
                        help="Anticipo renta from prior year (R130)")
    parser.add_argument("--nit-suffix",
                        help="Last 2 digits of CC/NIT for deadline lookup")
    parser.add_argument("--input", type=str,
                        help="Path to a saved tax projection JSON (skip running projection)")
    parser.add_argument("--genero", type=str, default="2 - Masculino",
                        help="Casilla 286 value (default: '2 - Masculino')")
    parser.add_argument("--ciiu", type=str, default="6201",
                        help="Casilla 24 CIIU code (default: 6201 — software development)")
    parser.add_argument("--dry-run", action="store_true",
                        help="Print fill plan table without generating shell commands")
    parser.add_argument("--json", action="store_true",
                        help="Output fill plan as JSON")
    parser.add_argument("--output", type=str,
                        help="Write shell script to file instead of stdout")

    args = parser.parse_args()

    # Load or compute projection
    projection = load_projection(args)

    # Build fill plan
    plan = build_fill_plan(projection, genero=args.genero, ciiu=args.ciiu)

    if args.dry_run:
        print_dry_run_table(plan)
        return

    if args.json:
        print_mapping_json(plan)
        return

    # Generate shell script
    script = emit_shell_script(plan)

    if args.output:
        out_path = Path(args.output)
        out_path.write_text(script)
        out_path.chmod(0o755)
        print(f"Fill script written to {out_path}", file=sys.stderr)
    else:
        print(script)


if __name__ == "__main__":
    main()