[Issue #6835] Add array_decomposition transform (#7070)

## Summary

<!-- Use "Fixes" to automatically close issue upon PR merge. Use "Work
for" when UAT is required. -->
Fixes #6835 

## Changes proposed

<!-- What was added, updated, or removed in this PR. -->
Add a new `array_decomposition` transform option to
`conditional_transformers.py` to process budget form data in accordance
with SF424A XSD.
Add configuration to sf424a
Add tests

## Context for reviewers

<!-- Technical or background context, more in-depth details of the
implementation, and anything else you'd like reviewers to know
We store the budget form data as an array where each line item contains
the budget summary, budget categories, non federal resources and federal
fund estimates. We need to support iterating through this array and
pulling parts out of it to transform it.

For more examples, info: see schema at
https://apply07.grants.gov/apply/forms/schemas/SF424A-V1.0.xsd

Note that full XSD validation won't work until the full XML config is
configured for the SF424A.

## Validation steps

<!-- Manual testing instructions, as well as any helpful references
(screenshots, GIF demos, code examples or output). -->
See new / updated unit tests.

From the command line, create a JSON file like:

```
{
  "activity_line_items": [
    {
      "activity_title": "Personnel Costs",
      "non_federal_resources": {
        "applicant_amount": "5000.00",
        "state_amount": "10000.00",
        "other_amount": "2500.00",
        "total_amount": "17500.00"
      }
    },
    {
      "activity_title": "Equipment",
      "non_federal_resources": {
        "applicant_amount": "3000.00",
        "state_amount": "7500.00",
        "other_amount": "1500.00",
        "total_amount": "12000.00"
      }
    }
  ],
  "total_non_federal_resources": {
    "applicant_amount": "8000.00",
    "state_amount": "17500.00",
    "other_amount": "4000.00",
    "total_amount": "29500.00"
  }
}
```

Then run:

`docker compose run --rm grants-api poetry run flask task generate-xml
--file sf424a.json --form SF424A --output sf424a_output.xml`

And see XML file:

```
<?xml version='1.0' encoding='utf-8'?>
<SF424A:BudgetInformation xmlns:SF424A="http://apply.grants.gov/forms/SF424A-V1.0" xmlns:glob="http://apply.grants.gov/system/Global-V1.0" SF424A:FormVersion="2.0">
  <SF424A:BudgetSections>
    <SF424A:NonFederalResources>
      <SF424A:ResourceLineItem SF424A:activityTitle="Personnel Costs">
        <SF424A:BudgetApplicantContributionAmount>5000.00</SF424A:BudgetApplicantContributionAmount>
        <SF424A:BudgetStateContributionAmount>10000.00</SF424A:BudgetStateContributionAmount>
        <SF424A:BudgetOtherContributionAmount>2500.00</SF424A:BudgetOtherContributionAmount>
        <SF424A:BudgetTotalContributionAmount>17500.00</SF424A:BudgetTotalContributionAmount>
      </SF424A:ResourceLineItem>
      <SF424A:ResourceLineItem SF424A:activityTitle="Equipment">
        <SF424A:BudgetApplicantContributionAmount>3000.00</SF424A:BudgetApplicantContributionAmount>
        <SF424A:BudgetStateContributionAmount>7500.00</SF424A:BudgetStateContributionAmount>
        <SF424A:BudgetOtherContributionAmount>1500.00</SF424A:BudgetOtherContributionAmount>
        <SF424A:BudgetTotalContributionAmount>12000.00</SF424A:BudgetTotalContributionAmount>
      </SF424A:ResourceLineItem>
      <SF424A:ResourceTotals>
        <SF424A:BudgetApplicantContributionAmount>8000.00</SF424A:BudgetApplicantContributionAmount>
        <SF424A:BudgetStateContributionAmount>17500.00</SF424A:BudgetStateContributionAmount>
        <SF424A:BudgetOtherContributionAmount>4000.00</SF424A:BudgetOtherContributionAmount>
        <SF424A:BudgetTotalContributionAmount>29500.00</SF424A:BudgetTotalContributionAmount>
      </SF424A:ResourceTotals>
    </SF424A:NonFederalResources>
  </SF424A:BudgetSections>
</SF424A:BudgetInformation>`
```

Author: mikehgrantsgov

api/src/cli/xml_generation_cli.py

@@ -7,7 +7,8 @@
 
 import click
 
-from src.form_schema.forms.sf424 import FORM_XML_TRANSFORM_RULES
+from src.form_schema.forms.sf424 import FORM_XML_TRANSFORM_RULES as SF424_TRANSFORM_RULES
+from src.form_schema.forms.sf424a import FORM_XML_TRANSFORM_RULES as SF424A_TRANSFORM_RULES
 from src.services.xml_generation.models import XMLGenerationRequest
 from src.services.xml_generation.service import XMLGenerationService
 from src.services.xml_generation.validation.test_cases import (
@@ -18,6 +19,12 @@
 from src.services.xml_generation.validation.xsd_fetcher import XSDFetcher
 from src.task.task_blueprint import task_blueprint
 
+# Map form names to their transform rules
+FORM_TRANSFORM_RULES_MAP = {
+    "SF424_4_0": SF424_TRANSFORM_RULES,
+    "SF424A": SF424A_TRANSFORM_RULES,
+}
+
 
 @task_blueprint.cli.command("generate-xml")
 @click.option(
@@ -34,7 +41,7 @@
 @click.option(
     "--form",
     default="SF424_4_0",
-    help="Form name/version (e.g., SF424_4_0). Default: SF424_4_0",
+    help="Form name/version (e.g., SF424_4_0, SF424A). Default: SF424_4_0",
 )
 @click.option(
     "--compact",
@@ -60,11 +67,11 @@ def generate_xml_command(
 
     Examples:
 
-        # Generate XML from JSON string
+        # Generate XML from JSON string (SF-424)
         flask task generate-xml --json '{"field": "value"}' --form SF424_4_0
 
-        # Generate from file
-        flask task generate-xml --file input.json --form SF424_4_0
+        # Generate SF-424A from file
+        flask task generate-xml --file input.json --form SF424A
 
         # Generate compact XML and save to file
         flask task generate-xml --json '{"field": "value"}' --compact --output out.xml
@@ -80,11 +87,20 @@ def generate_xml_command(
             click.echo("Error: Must provide either --json or --file", err=True)
             sys.exit(1)
 
+        # Get transform config for the specified form
+        transform_config = FORM_TRANSFORM_RULES_MAP.get(form)
+        if not transform_config:
+            click.echo(
+                f"Error: Unknown form '{form}'. Available forms: {', '.join(FORM_TRANSFORM_RULES_MAP.keys())}",
+                err=True,
+            )
+            sys.exit(1)
+
         # Create service and generate XML
         service = XMLGenerationService()
         request = XMLGenerationRequest(
             application_data=application_data,
-            transform_config=FORM_XML_TRANSFORM_RULES,
+            transform_config=transform_config,
             pretty_print=not compact,
         )
 

api/src/form_schema/forms/sf424a.py

@@ -783,15 +783,68 @@
         "namespaces": {
             "default": "http://apply.grants.gov/forms/SF424A-V1.0",
             "SF424A": "http://apply.grants.gov/forms/SF424A-V1.0",
+            "glob": "http://apply.grants.gov/system/Global-V1.0",
         },
         "xsd_url": "https://apply07.grants.gov/apply/forms/schemas/SF424A-V1.0.xsd",
-        "xml_structure": {"root_element": "SF424A", "version": "2.0"},
+        "xml_structure": {
+            "root_element": "BudgetInformation",
+            "root_namespace_prefix": "SF424A",  # Use SF424A: prefix for root element per XSD
+            "version": "2.0",
+            # Required attributes for XSD validation
+            "root_attributes": {
+                "programType": "program_type",  # Maps to input field
+                "glob:coreSchemaVersion": "1.0",  # Static value required by XSD
+            },
+        },
         "null_handling_options": {
             "exclude": "Default - exclude field entirely from XML (recommended)",
             "include_null": "Include empty XML element: <Field></Field>",
             "default_value": "Use configured default value when field is None",
         },
     },
+    # Required first child element for XSD validation
+    "form_version_identifier": {
+        "xml_transform": {
+            "target": "glob:FormVersionIdentifier",
+            "namespace": "glob",
+        }
+    },
+    # Program type - required root attribute (mapped via xml_structure.root_attributes)
+    "program_type": {
+        "xml_transform": {
+            "target": "programType",
+            "type": "attribute",  # This will be handled as a root attribute
+        }
+    },
+    # Activity title - appears as an attribute on line items
+    "activity_title": {
+        "xml_transform": {
+            "target": "activityTitle",
+            "type": "attribute",
+        }
+    },
+    # Non-Federal Resources field mappings (Section C)
+    # These map the internal field names to XSD element names
+    "applicant_amount": {
+        "xml_transform": {
+            "target": "BudgetApplicantContributionAmount",
+        }
+    },
+    "state_amount": {
+        "xml_transform": {
+            "target": "BudgetStateContributionAmount",
+        }
+    },
+    "other_amount": {
+        "xml_transform": {
+            "target": "BudgetOtherContributionAmount",
+        }
+    },
+    "total_amount": {
+        "xml_transform": {
+            "target": "BudgetTotalContributionAmount",
+        }
+    },
     # Forecasted Cash Needs - Section D
     # This requires pivoting the data structure from JSON to XML format
     "forecasted_cash_needs": {
@@ -831,6 +884,104 @@
             },
         }
     },
+    # Budget sections decomposition
+    # Transform row-oriented activity_line_items array to column-oriented arrays
+    # organized by section type (budget_summary, budget_categories, etc.)
+    #
+    # Note: This transformation handles the data restructuring step. The XML generation
+    # phase (not shown here) will handle:
+    # - Adding activity_title as an XML attribute to each line item
+    # - Using different XML element names for line items vs totals
+    #   (e.g., ResourceLineItem vs ResourceTotals)
+    # - Proper XML namespace handling and element ordering
+    #
+    # Example transformation - this input structure:
+    # {
+    #   "activity_line_items": [
+    #     {
+    #       "activity_title": "Activity 1",
+    #       "budget_summary": {"total_amount": "5000.00"},
+    #       "budget_categories": {"personnel_amount": "2000.00"},
+    #       "non_federal_resources": {"applicant_amount": "500.00"},
+    #       "federal_fund_estimates": {"first_year_amount": "5000.00"}
+    #     },
+    #     {
+    #       "activity_title": "Activity 2",
+    #       "budget_summary": {"total_amount": "8000.00"},
+    #       "budget_categories": {"personnel_amount": "3000.00"},
+    #       "non_federal_resources": {"applicant_amount": "1000.00"},
+    #       "federal_fund_estimates": {"first_year_amount": "8000.00"}
+    #     }
+    #   ],
+    #   "total_budget_summary": {"total_amount": "13000.00"},
+    #   "total_budget_categories": {"personnel_amount": "5000.00"},
+    #   "total_non_federal_resources": {"applicant_amount": "1500.00"},
+    #   "total_federal_fund_estimates": {"first_year_amount": "13000.00"}
+    # }
+    #
+    # Becomes this output structure:
+    # {
+    #   "BudgetSummaries": [
+    #     {"total_amount": "5000.00"},    # Activity 1
+    #     {"total_amount": "8000.00"},    # Activity 2
+    #     {"total_amount": "13000.00"}    # Total
+    #   ],
+    #   "BudgetCategories": [
+    #     {"personnel_amount": "2000.00"},  # Activity 1
+    #     {"personnel_amount": "3000.00"},  # Activity 2
+    #     {"personnel_amount": "5000.00"}   # Total
+    #   ],
+    #   "NonFederalResources": [
+    #     {"applicant_amount": "500.00"},   # Activity 1
+    #     {"applicant_amount": "1000.00"},  # Activity 2
+    #     {"applicant_amount": "1500.00"}   # Total
+    #   ],
+    #   "FederalFundEstimates": [
+    #     {"first_year_amount": "5000.00"},  # Activity 1
+    #     {"first_year_amount": "8000.00"},  # Activity 2
+    #     {"first_year_amount": "13000.00"}  # Total
+    #   ]
+    # }
+    "budget_sections": {
+        "xml_transform": {
+            "type": "conditional",
+            "target": "BudgetSections",
+            "conditional_transform": {
+                "type": "array_decomposition",
+                "source_array_field": "activity_line_items",
+                "field_mappings": {
+                    "BudgetSummaries": {
+                        "item_field": "budget_summary",
+                        "item_wrapper": "SummaryLineItem",
+                        "item_attributes": ["activity_title"],
+                        "total_field": "total_budget_summary",
+                        "total_wrapper": "SummaryTotals",
+                    },
+                    "BudgetCategories": {
+                        "item_field": "budget_categories",
+                        "item_wrapper": "CategoryLineItem",
+                        "item_attributes": ["activity_title"],
+                        "total_field": "total_budget_categories",
+                        "total_wrapper": "CategoryTotals",
+                    },
+                    "NonFederalResources": {
+                        "item_field": "non_federal_resources",
+                        "item_wrapper": "ResourceLineItem",
+                        "item_attributes": ["activity_title"],
+                        "total_field": "total_non_federal_resources",
+                        "total_wrapper": "ResourceTotals",
+                    },
+                    "FederalFundEstimates": {
+                        "item_field": "federal_fund_estimates",
+                        "item_wrapper": "EstimateLineItem",
+                        "item_attributes": ["activity_title"],
+                        "total_field": "total_federal_fund_estimates",
+                        "total_wrapper": "EstimateTotals",
+                    },
+                },
+            },
+        }
+    },
 }
 
 SF424a_v1_0 = Form(