Ir para o conteúdo

Conceitos

Entenda os conceitos fundamentais do DataFrameIt.

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                        dataframeit()                         │
├─────────────────────────────────────────────────────────────┤
│  Entrada           │  Processamento      │  Saída           │
│  ─────────         │  ─────────────      │  ─────           │
│  • DataFrame       │  • Para cada linha: │  • DataFrame     │
│  • Series          │    1. Monta prompt  │    com colunas   │
│  • List            │    2. Chama LLM     │    extraídas     │
│  • Dict            │    3. Valida resp.  │                  │
│                    │    4. Retry se erro │                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     LangChain + Provider                     │
├─────────────────────────────────────────────────────────────┤
│  Google Gemini │ OpenAI │ Anthropic │ Cohere │ Mistral      │
└─────────────────────────────────────────────────────────────┘

Componentes Principais

1. Modelo Pydantic

O modelo Pydantic define o que você quer extrair. Cada campo vira uma coluna no DataFrame de saída.

from pydantic import BaseModel, Field
from typing import Literal, Optional

class Analise(BaseModel):
    # Campo obrigatório com valores fixos
    categoria: Literal['A', 'B', 'C'] = Field(
        description="Categoria do item"
    )

    # Campo obrigatório com texto livre
    resumo: str = Field(
        description="Resumo em uma frase"
    )

    # Campo opcional
    observacao: Optional[str] = Field(
        default=None,
        description="Observações adicionais, se houver"
    )

Por que Pydantic?

  • Validação automática: O LLM é forçado a retornar dados no formato correto
  • Documentação: As descrições dos campos ajudam o LLM a entender o que extrair
  • Type safety: Erros de tipo são capturados automaticamente

2. Prompt Template

O prompt define como o LLM deve processar cada texto.

# Simples - texto é adicionado automaticamente ao final
PROMPT = "Classifique o sentimento do texto."

# Com placeholder - controle onde o texto aparece
PROMPT = """
Você é um analista especializado.

Documento:
{texto}

Extraia as informações solicitadas do documento acima.
"""

3. Provedores

O DataFrameIt usa LangChain para abstrair diferentes provedores de LLM. Os providers codex e claude_code usam os SDKs oficiais das ferramentas, com a autenticação local delas; ver Provedores.

Provider Modelos Populares Variável de Ambiente
openai gpt-6-luna, gpt-6-sol, gpt-6-astra OPENAI_API_KEY
google_genai gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite GOOGLE_API_KEY
anthropic claude-sonnet-5, claude-opus-5-5, claude-haiku-4-5 ANTHROPIC_API_KEY
groq openai/gpt-oss-120b, openai/gpt-oss-20b GROQ_API_KEY

Fluxo de Processamento

Para cada linha do DataFrame:
│
├─► 1. Monta o prompt (template + texto da linha)
│
├─► 2. Envia ao provider (com busca web, a um agente que busca antes de responder)
│
├─► 3. Recebe resposta estruturada
│
├─► 4. Valida com Pydantic
│   │
│   ├─► Sucesso: marca como 'processed'
│   │
│   └─► Erro transitório ou resposta recusada: nova tentativa com backoff exponencial
│       │
│       ├─► Sucesso numa nova tentativa: marca como 'processed'
│       │
│       └─► Tentativas esgotadas, ou erro permanente: marca como 'error'
│
└─► 5. Adiciona campos extraídos ao DataFrame

Colunas Automáticas

O DataFrameIt adiciona as colunas de status automaticamente. Quando track_tokens=True, acrescenta também colunas de uso; consulte a Referência LLM para a tabela completa e a semântica de cache e raciocínio.

Coluna Descrição
_dataframeit_status Status: 'processed', 'error', ou None
_error_details Detalhes do erro, ou das novas tentativas numa linha que deu certo

As duas colunas são removidas da saída quando nenhuma linha falha nem registra detalhe.

Próximos Passos