Gerador e Avaliador de Poemas API

Esta é uma API desenvolvida com FastAPI que utiliza modelos de linguagem (Gemini-2.5-flash) e embeddings para gerar e avaliar poemas em português com base em palavras-chave.

A API realiza um processo completo que inclui:

1. Web Scraping: Busca por poemas reais para servirem de inspiração.
2. Busca Semântica: Utiliza um banco de dados vetorial (ChromaDB) para encontrar a inspiração mais relevante.
3. Geração com IA: Cria um novo poema original.
4. Avaliação Métrica: Pontua os poemas gerados com base em critérios técnicos e de impressão artística.

---

1. Setup do Ambiente

Siga os passos abaixo para configurar e executar a API localmente.

a. Pré-requisitos

• Python 3.8 ou superior.

b. Crie e Ative um Ambiente Virtual (Venv)

É uma boa prática isolar as dependências do projeto.

Windows:

python -m venv venv
.\venv\Scripts\activate

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

c. Instale as Dependências

Com o ambiente virtual ativado, instale todas as bibliotecas necessárias usando o arquivo requirements.txt.

pip install -r requirements.txt

d. Configure sua Chave de API do Gemini

Abra o arquivo api.py e substitua o valor da constante GEMINI_API_KEY pela sua chave obtida no Google AI Studio.

# Em api.py
GEMINI_API_KEY = "SUA_CHAVE_DE_API_AQUI"

---

2. Executando a API

Após a instalação, inicie o servidor FastAPI com o Uvicorn.

uvicorn api:app --reload

O servidor estará disponível em http://127.0.0.1:8000. Você pode acessar a documentação interativa (Swagger UI) em http://127.0.0.1:8000/docs.

---

3. Documentação dos Endpoints

Abaixo estão detalhados os endpoints, seus inputs e outputs esperados.

a. POST /evaluate_poem

Gera um poema com base em palavras-chave e faz uma avaliação técnica detalhada.

• Request Body:

{
  "keywords": ["mar", "onda", "areia"]
}

• Success Response (200 OK):

{
  "geracao": {
    "poema_gerado": "No vasto azul, a onda se desfaz,\num beijo branco na areia que adormece,\ne o mar sussurra o tempo que se traz.",
    "poema_base": "O mar enrola na areia, Ninguém sabe o que ele diz.",
    "autor": "Cecília Meireles"
  },
  "avaliacao": {
    "presenca": 4,
    "distancia": 9,
    "potencial_rima": 4,
    "figura_de_som": 2,
    "complexidade_lexical": 4,
    "total": 23
  }
}

• Exemplo com curl:

curl -X POST "http://127.0.0.1:8000/evaluate_poem" \
-H "Content-Type: application/json" \
-d '{"keywords": ["mar", "onda", "areia"]}'

b. POST /calculate_impression

Calcula a "impressão artística" de um poema já gerado e sua pontuação final com base na avaliação técnica.

• Request Body:

{
  "poema_gerado": "No vasto azul, a onda se desfaz,\num beijo branco na areia que adormece,\ne o mar sussurra o tempo que se traz.",
  "poema_base": "O mar enrola na areia, Ninguém sabe o que ele diz.",
  "autor": "Cecília Meireles",
  "avaliacao_tecnica": 23
}

• Success Response (200 OK):

{
  "avaliacao_impressao": {
    "originalidade": 4,
    "variedade_lexical": 5,
    "numero_de_versos": 5,
    "clareza_semantica": 5,
    "criatividade": 4
  },
  "total_impressao": 23,
  "total_final": 529
}

• Exemplo com curl:

curl -X POST "http://127.0.0.1:8000/calculate_impression" \
-H "Content-Type: application/json" \
-d '{
  "poema_gerado": "No vasto azul, a onda se desfaz,\num beijo branco na areia que adormece,\ne o mar sussurra o tempo que se traz.",
  "poema_base": "O mar enrola na areia, Ninguém sabe o que ele diz.",
  "autor": "Cecília Meireles",
  "avaliacao_tecnica": 23
}'

c. POST /calculate_final_score_with_rule

Endpoint mais complexo. Faz a avaliação de impressão e, adicionalmente, valida se o poema seguiu uma "regra especial". A pontuação final é penalizada se a regra não for cumprida.

• Request Body:

{
  "poema_gerado": "Amor, imensa ilusão, anseio eterno, onde arde um anjo.",
  "poema_base": "Amor é fogo que arde sem se ver",
  "autor": "Luís Vaz de Camões",
  "avaliacao_tecnica": 22,
  "keywords": ["amor", "ilusão", "eterno"],
  "regra_especial": "use apenas palavras que começam com vogais"
}

• Success Response (200 OK):

{
  "avaliacao_impressao": {
    "originalidade": 5,
    "variedade_lexical": 5,
    "numero_de_versos": 5,
    "clareza_semantica": 5,
    "criatividade": 5
  },
  "regra_respeitada": true,
  "total_impressao": 25,
  "total_final": 550
}

• Exemplo com curl:

curl -X POST "http://127.0.0.1:8000/calculate_final_score_with_rule" \
-H "Content-Type: application/json" \
-d '{
  "poema_gerado": "Amor, imensa ilusão, anseio eterno, onde arde um anjo.",
  "poema_base": "Amor é fogo que arde sem se ver",
  "autor": "Luís Vaz de Camões",
  "avaliacao_tecnica": 22,
  "keywords": ["amor", "ilusão", "eterno"],
  "regra_especial": "use apenas palavras que começam com vogais"
}'