lummy-ia

AI Lesson & Adaptive Agent
Gere lições e questões com AWS Bedrock, armazene no Firestore e utilize um agente adaptativo para perguntas e respostas.

Sumário

• lummy-ia
  • Sumário
  • Visão Geral
  • Estrutura do Projeto
  • Principais Funcionalidades
  • Requisitos
  • Configuração de Credenciais AWS
  • Configuracao de Ambientes
  • Como Rodar (Docker)
    • Rodando localmente (sem Docker)
    • Testes automatizados
  • Endpoints da API
    • Fluxo rápido: gerar lição + questões em um passo
  • Persistência de Dados
    • Configuração de Modelos Bedrock
  • Personalização e Desenvolvimento
  • Créditos

Visão Geral

Este projeto é uma API FastAPI para geração de lições e questões com IA (usando AWS Bedrock), armazenamento em Firebase Firestore e gerenciamento de progresso do usuário. O deploy é feito via Docker, com hot-reload para desenvolvimento.

Estrutura do Projeto

app/
  main.py             # Inicialização FastAPI e roteamento principal
  config/             # Configurações de Bedrock e Firebase
  api/                # Rotas HTTP organizadas por domínio
  application/        # DTOs, serviços e casos de uso
  domain/             # Entidades e interfaces de domínio
  infrastructure/     # Integrações (Firestore, Bedrock, autenticação)
  constants/          # Prompts e constantes compartilhadas
  utils/              # Utilitários de apoio
Dockerfile            # Build da aplicação Python
docker-compose.yml    # Orquestração da aplicação
requirements.txt      # Dependências Python

---

Principais Funcionalidades

• Geração de lições e questões via IA (AWS Bedrock)
• Respostas inteligentes com AWS Bedrock para interações do assistente
• Persistência de lições, questões e respostas diretamente no Firebase Firestore
• Sincronização automática das respostas geradas com coleções do Firestore
• API REST para manipulação de usuários, progresso, perguntas e respostas
• Administração de IA com seleção dinâmica de modelos Bedrock e ajustes de temperatura/tokens
• Camada de serviços com padrão Strategy para integrar múltiplos provedores de geração
• Agente adaptativo para seleção de próximas questões
• Monitoramento de saúde da aplicação e da integração com Bedrock
• Hot-reload para desenvolvimento rápido

Requisitos

• Docker e Docker Compose
• (Opcional) Python 3.11+ para rodar localmente sem Docker
• Credenciais válidas da AWS (variáveis de ambiente, perfil local ou AWS SSO) com permissão para chamar bedrock:InvokeModel
• Serviço Firebase configurado com conta de serviço (arquivo JSON) e chaves web para uso no front-end

Configuração de Credenciais AWS

1. Duplicar .env.example para .env e preencher um dos métodos abaixo:

   • Variáveis diretas: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, opcionalmente AWS_SESSION_TOKEN e AWS_REGION.
   • Perfil nomeado: deixe as variáveis acima vazias e informe AWS_PROFILE com o nome configurado em ~/.aws/credentials.

2. Aplicação FastAPI / Docker

   • O Compose carrega o arquivo .env, portanto as variáveis acima ficam disponíveis dentro do container automaticamente.
   • A aplicação também aceita que BEDROCK_REGION sobreponha AWS_REGION caso queira usar uma região específica para o Bedrock.

3. Terraform (/terraform)

   • Ao usar variáveis de ambiente, execute os comandos no terminal já exportando AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (e AWS_SESSION_TOKEN se houver).
   • Se preferir um perfil, garanta que AWS_PROFILE esteja setado no terminal ou defina var.aws_profile via terraform.tfvars/linha de comando (por exemplo -var="aws_profile=meu-perfil").
   • No Windows + WSL, mantenha as credenciais no mesmo ambiente em que rodará o Terraform (ex.: ~/.aws/credentials dentro do WSL quando rodar wsl terraform ...).

Configuracao de Ambientes

• Ajuste os arquivos app/config/environments/<perfil>.properties com os valores definitivos de cada ambiente (ex.: production.properties).
• O entrypoint grava o perfil ativo em /app/runtime-environment; informe prod ou homolog como primeiro argumento ao subir o contêiner (ex.: docker run imagem prod).
• A aplicação lê apenas os .properties para popular a configuração. Não há mais carregamento automático de variáveis de ambiente para essas chaves.
• Para adicionar um novo ambiente, crie app/config/environments/<novo>.properties e inclua o valor na constante _SUPPORTED_ENVIRONMENTS em app/config/environment.py.

Como Rodar (Docker)

Passo 1: Clone o repositório.

Passo 2: Faça o build e suba os containers:

• docker-compose build --no-cache
• docker-compose up (usa automaticamente production.properties via flag prod do entrypoint)

Passo 3: Garanta que a imagem consiga acessar credenciais AWS (perfil configurado no servidor, ~/.aws montado ou IAM role da instância; não há leitura automática de variáveis definidas no contêiner).

Passo 4: Monte o arquivo de credenciais do Firebase no caminho especificado em production.properties (por padrão /run/secrets/firebase-service-account.json).

Passo 5: Acesse a API em: http://localhost:8000/docs (Swagger)

Rodando localmente (sem Docker)

1. Crie e ative um ambiente virtual Python 3.11:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

1. Instale as dependências do projeto (inclui boto3, pytest e plugins necessários):

pip install -r requirements.txt

1. Defina as variáveis de ambiente AWS (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION ou AWS_PROFILE) e as variáveis do Firebase conforme descrito acima.

2. Suba a API com Uvicorn para desenvolvimento rápido:

uvicorn app.main:app --reload --port 8000

Testes automatizados

O projeto já vem configurado com pytest e suporte a testes assíncronos via anyio. Para executar a suíte completa:

python -m pytest

Observação: o arquivo pytest.ini adiciona o diretório app/ ao PYTHONPATH, portanto execute os testes a partir da raiz do repositório (D:\lummy-ia).

Endpoints da API

Principais rotas (veja detalhes e exemplos em /docs):

• GET /health — Healthcheck da API e da integração com Bedrock
• POST /generate-lesson — Gera uma lição via IA (Bedrock)
• POST /generate-questions/by-subject — Cria lição e questões automaticamente a partir de uma matéria (assunto) informado
• POST /generate-questions/{lesson_id} — Gera questões para uma lição via IA (Bedrock)
• GET /questions/{question_id} — Recupera detalhes completos de uma questão
• PUT /questions/{question_id} — Atualiza enunciado, alternativas e resposta correta
• DELETE /questions/{question_id} — Remove uma questão e sincroniza com o Firebase
• POST /add_question_manual — Adiciona questão manualmente
• GET /list_questions — Lista questões
• GET /next_question — Próxima questão para o usuário
• POST /answer — Submete resposta do usuário
• GET /stats — Estatísticas do usuário
• GET /bedrock/settings — Lista o modelo ativo, parâmetros e modelos autorizados
• PUT /bedrock/settings — Atualiza dinamicamente modelo, temperatura e limite de tokens
• POST /reset_session — Reseta progresso do usuário
• GET /user_progress — Progresso detalhado do usuário

Fluxo rápido: gerar lição + questões em um passo

1. POST /generate-questions/by-subject — informe subject e, opcionalmente, questionCount, difficulty, ageGroup, lessonPrompt e questionPrompt. A API gera uma lição estruturada em português, persiste no Firestore e retorna no campo lesson, em seguida cria as questões alinhadas à lição e retorna em questions.

2. (Opcional) use o lesson.id retornado para futuras chamadas pontuais em /generate-questions/{lesson_id}.

Exemplos completos estão incluídos na coleção Postman atualizada em docs/postman/lummy-ia.postman_collection.json, separados em pastas "AI Lesson & Question Generation".

Persistência de Dados

• Firebase Firestore centraliza lições, questões, respostas e credenciais de autenticação. Configure FIREBASE_PROJECT_ID com as credenciais de serviço (FIREBASE_CREDENTIALS_PATH ou FIREBASE_CREDENTIALS_JSON).
• Sem banco relacional: o projeto não depende mais de MySQL nem exige contêiner adicional para persistência.

Configuração de Modelos Bedrock

• O arquivo docker/dev/.env.development já inclui Claude 3 Sonnet como padrão e Claude 3 Haiku como alternativa. Ajuste esse JSON para incluir apenas os modelos liberados na sua conta e região Bedrock.

Monitoramento com Prometheus e Grafana

• O Compose de desenvolvimento (docker/dev/docker-compose.yml) inclui os serviços prometheus e grafana, ambos na mesma rede da aplicação.
• Prometheus lê o arquivo docker/dev/prometheus/prometheus.yml e coleta métricas do endpoint /metrics exposto pelo FastAPI.
• Grafana carrega automaticamente uma fonte de dados Prometheus através de docker/dev/grafana/provisioning/datasources/prometheus.yml. As credenciais de admin são definidas via secrets em docker/prod/secrets/. A interface fica disponível em http://localhost:3000.
• Suba todo o stack com docker compose -f docker/dev/docker-compose.yml up. As métricas ficam acessíveis em http://localhost:9090 e os dashboards podem ser criados na instância Grafana.
• Para produção, use o workflow GitHub Actions "Deploy Monitoring Stack" que implanta apenas os serviços de monitoramento (Prometheus e Grafana) separadamente da aplicação principal.

Personalização e Desenvolvimento

• Hot-reload: O código é montado como volume no container, qualquer alteração reinicia a API automaticamente.
• Dependências: Adicione no requirements.txt e reinicie o container.
• Logger: Use from app.logger import logger para logs padronizados.
• Serviços de IA: Estenda app/infrastructure/ai/strategies.py para adicionar novos provedores, registrando-os em get_ai_generation_service() e ativando-os via payloads ou configuração de estratégia.
• Debug remoto (VS Code / PyCharm):
  1. Defina ENABLE_DEBUGPY=1 (e opcionalmente DEBUGPY_PORT=5678) em .env.development ou como variável de ambiente antes de subir o Compose.
  2. Suba os containers com docker-compose up (porta 5678 será exposta pelo serviço app). O container aguardará um debugger conectar antes de iniciar o Uvicorn.
  3. No VS Code, crie uma configuração Python: Attach using debugpy apontando para localhost:5678 (path mapping local D:\lummy-ia → container /app). Em outras IDEs, use o mesmo host/porta.
  4. Coloque breakpoints normalmente; após o attach, a aplicação continua a execução com hot-reload preservado.

Créditos

• Projeto desenvolvido por IKauedev.
• Baseado em FastAPI, Firestore, AWS Bedrock, Docker.