Python: Fundamentos para Imersão Dev Agentes de IA

Uma Jornada Guiada para compreender os Fundamentos da Programação em Python da imersão

Nosso Objetivo Final

Ao final desta jornada, você será capaz de ler e compreender cada linha do código abaixo. Parece complexo agora? Em breve, fará todo o sentido.

from typing import Dict

def perguntar(pergunta: str) -> Dict:
    docs_relacionados = retriever.invoke(pergunta)

    if not docs_relacionados:
        return {"answer": "Não sei."}

    return {"answer": docs_relacionados}

resposta = perguntar("Qual é a política de privacidade?")
print("Resposta ->", resposta["answer"])

# ... e muito mais ...

Capítulo 1: Os Primeiros Passos no Universo Python

Variáveis: As Caixas de Memória

Em programação, usamos variáveis para guardar informações. Pense nelas como caixas com etiquetas. Você dá um nome e guarda algo dentro usando o sinal de igual (`=`).

saudacao =

"Olá, mundo!"

Tipos de Dados: Textos e Verdades

As informações possuem tipos. Os dois mais básicos que veremos são textos (strings) e valores de verdadeiro/falso (booleanos).

String (str)

Qualquer texto entre aspas.

resposta = "Não sei."

Número inteiro (int)

Representa números inteiros, positivos ou negativos, sem casas decimais.

idade = 42

Número decimal (float)

Representa números reais (decimais) para cálculos com frações.

altura = 1.75

Booleano (bool)

Apenas `True` ou `False`.

contexto_encontrado = True

Capítulo 2: Guardando e Organizando Dados

Listas: Coleções de Itens

Uma lista (`list`) é uma coleção ordenada de itens, criada com colchetes `[]`. Ela pode guardar qualquer tipo de dado e até mesmo ficar vazia.

citacoes = ["Artigo 1", "Página 3"]
citacoes_vazias = []

Dicionários: Informações com Etiquetas

Um dicionário (`dict`) guarda pares de `chave: valor`, permitindo uma organização mais estruturada dos dados. Eles são criados com chaves `{}`.

resultado = {
    "answer": "Resposta encontrada.",
    "contexto_encontrado": True
}

Métodos: Superpoderes dos Objetos

Em Python, quase tudo é um "objeto" que possui ações embutidas, chamadas de métodos. Usamos um ponto (`.`) para acioná-los. Por exemplo, `.strip()` remove espaços extras de uma string.

texto_sujo = "   olá   "
texto_limpo = texto_sujo.strip()
# texto_limpo agora é "olá"

Capítulo 3: Ensinando o Código a Tomar Decisões

A Estrutura Condicional `if`

A declaração `if` permite que seu código execute ações diferentes com base em uma condição ser `True` ou `False`.

if idade >= 18:

CONDIÇÃO VERDADEIRA

Executa o bloco de código

CONDIÇÃO FALSA

Pula o bloco de código

Comparações e Lógica

Usamos `==` para verificar se dois valores são iguais e `not` para inverter um valor booleano (`True` vira `False` e vice-versa).

# Se a lista estiver vazia (considerado False), 'not' inverte para True
x = 10
y = 5

# Verifica se x é igual a y
igual = (x == y)  
print("x é igual a y?", igual)  # Saída: False

# Inverte o valor booleano
diferente = not (x == y)
print("x é diferente de y?", diferente)  # Saída: True

Capítulo 4: Criando Blocos de Código Reutilizáveis

Funções: Código Organizado

Uma função é um bloco de código nomeado que realiza uma tarefa. Você a "define" uma vez com `def` e pode "chamá-la" quantas vezes quiser.

# Definindo a função
def saudar(nome):
    return f"Olá, {nome}!"

# Chamando a função
mensagem = saudar("Aluno")
print(mensagem) # Resultado: Olá, Aluno!

Anatomia de uma Função

As funções têm partes importantes: a palavra-chave `def`, um nome, parênteses para os parâmetros (entradas) e um `return` opcional para o resultado (saída).

def nome_da_funcao(parametro):

# código vai aqui

return resultado

Type Hints: Dicas de Rota

Anotações como `: str` e `-> Dict` são "dicas de tipo". Elas não alteram o código, mas ajudam os humanos a entenderem que tipo de dado uma função espera receber e que tipo ela vai retornar.

def saudar(nome: str) -> str:
    # Esta função espera uma string e retorna uma string
    return f"Olá, {nome}!"

Capítulo 5: Desvendando o Código Final

Missão cumprida! Agora você tem todo o conhecimento necessário. Clique em cada linha do código abaixo para ver uma explicação detalhada sobre o que ela faz, conectando tudo o que aprendemos.

from typing import Dict

def perguntar(pergunta: str) -> Dict:

____docs_relacionados = retriever.invoke(pergunta)

____if not docs_relacionados:

________return {"answer": "Não sei."}

____return {"answer": docs_relacionados}

resposta = perguntar("Qual é a política de privacidade?")

print("Resposta ->", resposta["answer"])

Clique em uma linha de código

Selecione uma linha à esquerda para ver a mágica acontecer e a explicação aparecer aqui.

Importação de Ferramentas

Esta linha importa o objeto `Dict` de uma biblioteca do Python, o que nos permite usar a dica de tipo (`Type Hint`) `Dict` na definição da nossa função.

Definição da Função

`def` inicia a definição de uma função. Ela se chama `perguntar`, espera um parâmetro `pergunta` (que deve ser uma string) e promete retornar (`->`) um dicionário (`Dict`).

Buscando Documentos

Aqui, usamos uma ferramenta externa (`retriever`) para buscar documentos relevantes. O método `.invoke()` é chamado com a `pergunta` do usuário. O resultado é salvo na variável `docs_relacionados`.

Verificação de Sucesso

Este é o nosso `if`. A condição `not docs_relacionados` checa se a lista de documentos está vazia. Em Python, uma lista vazia é considerada `False`, então `not` a transforma em `True`, ativando o bloco de código.

Retorno Padrão

Se nenhum documento foi encontrado, a função para aqui e retorna (`return`) um dicionário padrão, informando que a resposta é "Não sei.".

Retorno com Sucesso

Se a função chegou a esta linha, significa que a busca por documentos funcionou. A função retorna um dicionário onde a chave `"answer"` contém a lista de documentos encontrada.

Chamando a Função

Esta linha mostra como usar a função `perguntar()`. Passamos a string `"Qual é a política de privacidade?"` como argumento. O dicionário que a função retorna é guardado na variável `resposta`.

Exibindo o Resultado

Finalmente, a função `print()` exibe o resultado no console. Usamos `resposta["answer"]` para acessar o valor dentro da chave `"answer"` do dicionário que a nossa função `perguntar()` nos retornou.