Add optional _limitations metadata field for search quality tracking

[bdcdo]

Problem

When using web search (use_search=True), there's no systematic way to track:

• Which sources were actually consulted
• Search failures or timeouts
• Data quality/confidence level
• What manual verification might be needed

Currently, users must parse free-text fields to understand if the agent had difficulties.

Proposed Solution

Add an optional track_limitations parameter that creates a _limitations metadata column with structured info about each row's search quality.

Schema

class SearchLimitations(BaseModel):
    """Auto-generated metadata about search quality"""
    confidence_level: Literal["high", "medium", "low"] = Field(
        description="high=multiple concordant sources, medium=some gaps, low=sparse/failed"
    )
    sources_consulted: list[str] = Field(
        description="List of sources actually consulted"
    )
    search_failures: list[str] = Field(
        default_factory=list,
        description="Any searches that failed (timeout, 429, etc.)"
    )
    limitations: str = Field(
        description="Description of limitations: outdated data, conflicts, missing info"
    )
    manual_verification_needed: Optional[str] = Field(
        default=None,
        description="Suggested manual checks if confidence is low"
    )

Usage

result_df = dataframeit(
    data=df,
    questions=MySchema,
    use_search=True,
    track_limitations=True,  # NEW
)

# Result includes _limitations column with structured metadata
print(result_df['_limitations'].iloc[0])
# {'confidence_level': 'medium', 'sources_consulted': ['Orphanet', 'FDA'], ...}

Implementation Notes

1. With search_per_field=False: Single _limitations column for the whole row

2. With search_per_field=True: Either:

   • One _limitations column aggregating all fields, OR
   • Per-field limitations in each field's nested dict (e.g., doenca_rara._limitations)

3. The agent would be instructed to self-evaluate its search quality as part of the structured output.

Benefits

1. Quality assurance: Easily filter rows with low confidence for manual review
2. Debugging: Understand why certain searches failed
3. Transparency: Document data provenance and limitations
4. Reproducibility: Know which sources were consulted

Alternative: User-defined limitations field

Allow users to define their own limitations schema that gets appended to every search:

class MyLimitations(BaseModel):
    confianca: str
    fontes: str
    problemas: str

result_df = dataframeit(
    ...,
    limitations_schema=MyLimitations,  # Auto-added to each row
)

[bdcdo]

Proposta ainda válida. Hoje temos metadata de custo (_search_credits, _search_count em core.py:559-582) e opcionalmente _trace_{field} com o raciocínio bruto, mas não há auto-avaliação estruturada de qualidade da busca.

Implementação sugerida

Não aceitar schema custom do usuário (a alternativa mencionada no final da issue) — isso bagunça a API e mistura contratos. Em vez disso, schema fixo dentro da lib:

# src/dataframeit/limitations.py
class SearchLimitations(BaseModel):
    confidence_level: Literal["high", "medium", "low"]
    sources_consulted: list[str]
    search_failures: list[str] = Field(default_factory=list)
    limitations: str
    manual_verification_needed: Optional[str] = None

Ativação: novo parâmetro track_limitations: bool = False em dataframeit().

Mecanismo: quando ligado, o schema do agente vira composto internamente — create_model('WithLimitations', **user_fields, _limitations=(SearchLimitations, ...)) — e o prompt ganha um appendix instruindo o modelo a preencher _limitations honestamente. No retorno, separamos _limitations dos campos do usuário e gravamos em coluna própria:

• Com search_per_field=False: uma coluna _limitations por linha.
• Com search_per_field=True: coluna _limitations_{field} por campo (cada agente preenche a sua, sem agregação forçada).

Gotchas:

• Modelos pequenos tendem a marcar confidence=high sempre. Validar em testes com casos de busca que deveriam falhar (query ambígua).
• Aumenta tokens de output — incluir nota no CHANGELOG sobre impacto de custo.
• Integra com save_trace como fontes cruzadas de validação.

Médio porte — uma PR isolada. Quer que eu abra?