---
name: chunk_ax_tree
kind: function
lang: py
domain: core
version: "1.0.0"
purity: pure
signature: "def chunk_ax_tree(nodes: list[dict], max_chars: int = 25000) -> list[list[dict]]"
description: "Divide una lista de AXNode en chunks de hasta max_chars (serializado JSON). Hace DFS desde raíz y añade nodo 'context' con path-from-root al inicio de cada chunk no inicial."
tags: [navegator, accessibility, chunking, pure, ax-tree, llm]
uses_functions: [trim_ax_tree_py_core]
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: [json]
params:
  - name: nodes
    desc: "Lista de AXNode en formato CDP (con nodeId, childIds, role, name). Usar después de trim_ax_tree para reducir ruido."
  - name: max_chars
    desc: "Límite de caracteres al serializar el chunk a JSON. Default 25000 (~6k tokens)."
output: "Lista de chunks. Cada chunk es lista de AXNode. Los chunks no iniciales arrancan con un nodo sintético role='context' que contiene el path desde la raíz."
tested: true
tests:
  - "lista vacia devuelve lista vacia"
  - "nodos que caben en un chunk devuelven un solo chunk"
  - "nodos que no caben generan multiples chunks"
  - "cada chunk serializado no supera max_chars mas overhead"
test_file_path: "python/functions/core/chunk_ax_tree_test.py"
file_path: "python/functions/core/chunk_ax_tree.py"
---

## Ejemplo

```python
from core.trim_ax_tree import trim_ax_tree
from core.chunk_ax_tree import chunk_ax_tree

# Obtener AX tree de CDP, luego:
trimmed = trim_ax_tree(raw_nodes)
chunks = chunk_ax_tree(trimmed, max_chars=25000)

for i, chunk in enumerate(chunks):
    print(f"Chunk {i}: {len(chunk)} nodos")
    # Enviar chunk a claude_cli_prompt o a la API de Claude
```

## Cuando usarla

Cuando el AX tree de una página compleja supera el context window del modelo (>25k chars). Chunkearlo permite procesar secciones independientes manteniendo el path-from-root como contexto para que el LLM entienda la estructura jerárquica.

## Gotchas

- El nodo `context` sintético (role="context") al inicio de cada chunk no es un nodo CDP real — filtrarlo si se necesita reconstruir el árbol.
- `max_chars` es límite aproximado: el nodo de contexto puede hacer que el chunk supere ligeramente el límite. Se recomienda un 10-20% de margen.
- Usar `trim_ax_tree` antes para reducir el número de nodos y mejorar la utilidad de cada chunk.
- Árboles muy profundos con pocos nodos por nivel generan chunks con mucho overhead de contexto.
