Monteiro Lobato - Educador de Programacao para Criancas¶

Codinome: Jose Bento Renato Monteiro Lobato Tipo: Kids Programming Education Agent Arquivo: src/agents/monteiro_lobato.py Classe: KidsProgrammingAgent Aliases: MonteiroLobatoAgent, LobatoAgent Base Class: BaseKidsAgent (shared safety features) Status: 100% Operacional Coverage: 95%+ (20/20 E2E tests passing)

Visao Geral¶

Monteiro Lobato e o agente educador de programacao para criancas do Cidadao.AI, especializado em ensinar conceitos de codigo e logica usando linguagem natural, historias divertidas e referencias ao Sitio do Picapau Amarelo. Inspirado no grande escritor brasileiro Jose Bento Renato Monteiro Lobato (1882-1948), considerado o pai da literatura infantil brasileira.

Arquitetura¶

BaseKidsAgent (base_kids_agent.py)
├── BLOCKED_TOPICS (70 items - single source of truth)
├── is_content_safe() (shared)
├── is_topic_allowed() (shared)
├── _generate_response() with DSPy (shared)
└── process() (shared)
    │
    └── KidsProgrammingAgent (monteiro_lobato.py)
        ├── ALLOWED_TOPICS_PROGRAMMING (130 items)
        ├── PERSONALITY_PROMPT (Sitio do Picapau Amarelo)
        ├── _get_safe_redirect_response()
        └── _get_fallback_response()

Caracteristicas Principais¶

EXTREMAMENTE RESTRITIVO: Este agente foi projetado com foco total em seguranca para criancas: - Herda de BaseKidsAgent para filtro de conteudo centralizado - 70 topicos bloqueados (BLOCKED_TOPICS compartilhado) - 130 topicos educativos permitidos (ALLOWED_TOPICS_PROGRAMMING) - Redirecionamento automatico de perguntas inadequadas - Linguagem simples para criancas de 6-12 anos

Filosofia de Ensino¶

"Um pais se faz com homens e livros" - Monteiro Lobato

Democratizacao: Educacao acessivel para todas as criancas
Respeito: Criancas sao inteligentes e merecem respeito intelectual
Diversao: Aprender deve ser divertido como uma aventura no Sitio
Fantasia: Usar fantasia para explicar conceitos reais

Sobre Monteiro Lobato¶

Nascido em Taubate, Sao Paulo em 1882
Criador do Sitio do Picapau Amarelo
Inventor de personagens iconicos: Emilia, Narizinho, Pedrinho, Visconde
Revolucionou a forma de falar com criancas sobre temas complexos
Misturava fantasia com educacao de forma natural

Capacidades¶

Capability	Descricao
`teach_programming_basics`	Ensina conceitos basicos de programacao
`explain_algorithms`	Explica algoritmos de forma simples
`tell_code_stories`	Transforma codigo em historias
`answer_kids_questions`	Responde perguntas de criancas
`make_learning_fun`	Torna o aprendizado divertido

Personagens Usados nas Explicacoes¶

Personagem	Conceito de Programacao
Emilia	Debug - questiona tudo, encontra erros
Narizinho	Criatividade - pensa fora da caixa
Pedrinho	Algoritmos - logico e aventureiro
Visconde	Funcoes - o sabio que explica
Tia Nastacia	Funcoes/Receitas - cria coisas seguindo passos
Saci	Loops - rapido e repetitivo

Analogias para Conceitos¶

Conceito	Analogia
Variavel	"Caixinha da Emilia" onde ela guarda coisas
Loop	"Quando o Saci pula varias vezes"
Funcao	"Receita da Tia Nastacia"
Condicional (if/else)	"SE/SENAO do Pedrinho decidindo o que fazer"
Lista	"Colecao de tesouros da Narizinho"
Bug	"Travessura do Saci que precisa consertar"

Seguranca de Conteudo¶

BaseKidsAgent - Single Source of Truth¶

O agente herda de BaseKidsAgent que centraliza as safety features:

from src.agents.base_kids_agent import BaseKidsAgent, BLOCKED_TOPICS

# BLOCKED_TOPICS (70 items) - shared across all kids agents
# Prevents drift between Monteiro Lobato, Tarsila, and future kids agents

Topicos Bloqueados (70 - via BaseKidsAgent)¶

O agente bloqueia automaticamente qualquer mencao a: - Violencia (matar, arma, guerra, sangue) - Conteudo adulto (sexo, pornografia) - Drogas e substancias (droga, alcool, cigarro) - Atividades perigosas (hackear, roubar, crime) - Conteudo assustador (terror, monstro, pesadelo) - Discurso de odio (racismo, bullying) - Informacoes pessoais (senha, cartao, banco) - Politica (eleicao, presidente)

Topicos Permitidos (130 - ALLOWED_TOPICS_PROGRAMMING)¶

O agente aceita perguntas sobre: - Programacao: variavel, funcao, loop, algoritmo, jogo, robo - Logica e Matematica: soma, subtracao, igual, maior, menor - Criatividade: desenho, cor, forma, animacao, historia - Sitio do Picapau: Emilia, Narizinho, Pedrinho, Visconde, aventura - Educacional: aprender, escola, estudar, criar, inventar - Natureza e Animais: cachorro, gato, borboleta, arvore

Exemplo de Uso¶

from src.agents import KidsProgrammingAgent
from src.agents.deodoro import AgentContext, AgentMessage

# Criar agente
agent = KidsProgrammingAgent()

# Criar contexto
context = AgentContext(
    investigation_id="kids-001",
    user_id="crianca-001",
    session_id="aprendizado-001",
)

# Enviar mensagem
message = AgentMessage(
    action="chat",
    recipient="monteiro_lobato",
    payload={"message": "O que e uma variavel?"},
    sender="crianca",
)

# Processar
response = await agent.process(message, context)
print(response.result["response"])

Exemplo de Resposta¶

Pergunta: "O que e uma variavel?"

Resposta:

Oba, voce quer saber sobre variaveis! A Emilia vai adorar explicar!

Imagina que a Emilia tem varias caixinhas coloridas. Cada caixinha tem um nome escrito nela.
Numa caixinha chamada "nome", ela guarda "Emilia".
Noutra chamada "idade", ela guarda o numero 8.

Em programacao, e assim:
nome = "Emilia"
idade = 8

E so isso! Uma caixinha com nome que guarda algo dentro.
Quer tentar criar sua propria caixinha?

API Usage¶

Chat Endpoint¶

POST /api/v1/chat/stream
Content-Type: application/json

{
  "message": "Quero aprender programacao!",
  "session_id": "unique-session-id",
  "agent_id": "monteiro_lobato"
}

Agent Aliases¶

Alias	Routes To
`lobato`	`monteiro_lobato`
`monteiro`	`monteiro_lobato`
`monteiro-lobato`	`monteiro_lobato`

Testes¶

E2E Production Tests¶

# Run all E2E tests
python tests/e2e/test_kids_agents_production.py

# Run with pytest
pytest tests/e2e/test_kids_agents_production.py -v -k "monteiro"

Test Scenarios (10/10 Passing)¶

Scenario	Description	Status
`greeting`	Welcome and introduce programming	PASSED
`variables_concept`	Explain variables using Emilia's boxes	PASSED
`loops_concept`	Explain loops using Saci's jumping	PASSED
`functions_concept`	Explain functions using Tia Nastacia's recipes	PASSED
`conditionals_concept`	Explain conditionals using Pedrinho's decisions	PASSED
`games_interest`	Respond to game creation interest	PASSED
`age_appropriate_language`	Use simple language, avoid jargon	PASSED
`encouragement`	Provide encouragement when frustrated	PASSED
`off_topic_redirect`	Redirect off-topic questions	PASSED
`alias_lobato`	Test 'lobato' alias routes correctly	PASSED

Unit Tests¶

JWT_SECRET_KEY=test SECRET_KEY=test pytest tests/unit/agents/test_monteiro_lobato.py -v

Integracao com DSPy¶

O agente usa o servico DSPy para gerar respostas dinamicas via Maritaca AI (sabia-3.1):

# In BaseKidsAgent._generate_response()
if _DSPY_AVAILABLE and _dspy_service and self.personality_prompt:
    response = await _dspy_service.generate_response(
        agent_name=self.name,
        personality_prompt=self.personality_prompt,
        user_message=message,
        context={
            "target_audience": "children_6_12",
            "style": "fun_educational",
            "max_words": 150,
        },
    )

Fallback para respostas pre-definidas quando o servico nao esta disponivel.

Metricas¶

Metrica	Valor
Topicos bloqueados	70 (via BaseKidsAgent)
Topicos permitidos	130
Personagens do Sitio	6
Capacidades	5
E2E Tests	10/10 passing
Production Status	Live

Relacionamento com Outros Agentes¶

Tarsila do Amaral: Sister agent for design education (same BaseKidsAgent)
Bo Bardi: Frontend mentor (can recommend for UI topics)
Santos Dumont: Backend educator (for older learners)

Autor¶

Data: 2025-12-09
Autor: Anderson H. Silva