Pular para conteúdo

Conecte-se e Apoie

Apoie (PIX):
QR Code PIX
Bitcoin:
QR Code BTC

Conteúdo sob Licença CC BY 4.0

Contato:
fabiotakwara@gmail.com

Olá! Sou a assistente virtual Takwara. Como posso ajudar?

Ferramentas

Conteúdo das ferramentas aparecerá aqui.

Calculadora de Domos

resultados:

O Grafo de Conhecimento visualiza as conexões entre os conceitos do projeto.

mk

Documentação do Projeto Takwara-Tech: Plataforma, Fluxo de Trabalho e Manutenção

Seção 1: Visão Geral da Plataforma no GitHub

O portal do projeto Takwara-Tech, hospedado no GitHub Pages (https://resck.github.io/Takwara-Tech/), representa uma plataforma de documentação e interação focada em soluções sustentáveis com bambu. A plataforma combina um site estático com uma API de Inteligência Artificial para fornecer informações e ferramentas aos usuários.

1.1. Componentes Principais

O ecossistema técnico é composto por três elementos principais:

  • Frontend: O site estático, gerado utilizando o MkDocs e o tema Material for MkDocs. Contém a documentação do projeto em arquivos Markdown e implementa a interface do usuário, incluindo a integração com a Assistente Virtual (AVT) e outras ferramentas.
  • Backend/API: Uma API desenvolvida em Python 3.11 e implantada como uma Google Cloud Function (Geração 2) na região southamerica-east1. Esta API utiliza uma stack de IA (Langchain, Google Generative AI, ChromaDB) para processar as consultas da Assistente Virtual, realizando busca de similaridade em uma base de conhecimento vetorial gerada a partir do conteúdo do site.
  • Base de Conhecimento da IA (chroma_db): Uma base de dados vetorial local, gerada a partir do conteúdo textual (Markdown, Python, TXT) do repositório do site. Esta base de dados é utilizada pela API backend para responder a perguntas contextuais.

1.2. Visão Estratégica da Interface

O objetivo final da interface do portal é evoluir para além de um simples repositório de documentos estáticos, transformando-o numa plataforma de interação e dados em tempo real. A visão estratégica para o layout e funcionalidade inclui:

  • Arquitetura da Interface: Um layout que apresente de forma clara e persistente uma navegação principal do site (índice geral), uma área central focada no conteúdo (artigos) e uma "Tool Box Interativa" sempre acessível, contendo as ferramentas da plataforma (Assistente Virtual, Grafo de Conhecimento, Calculadoras). Um índice de conteúdo para a página que está a ser lida (TOC - Table of Contents) também deve estar presente.
  • Painel de Impacto (Cabeçalho e Rodapé): O cabeçalho e o rodapé devem ser customizados para incluir "instrumentos indicadores" — APIs que exibem dados ambientais e sociais em tempo real (ex: "Climate Clock", níveis de CO₂, dados de queimadas, etc.).
  • Comportamento da AVT: A Assistente Virtual Takwara (AVT) deve ter uma busca contextual, priorizando a pesquisa na página em que o utilizador se encontra antes de realizar uma busca global no repositório.

Seção 2: Histórico de Desenvolvimento e Depuração (Jornada para a Estabilidade)

O desenvolvimento da plataforma envolveu a superação de diversos desafios técnicos complexos, desde a configuração inicial da infraestrutura na nuvem até o refinamento da inteligência da Assistente Virtual e os desafios de customização da interface. Esta seção documenta o percurso de depuração e evolução, consolidando informações de diferentes relatórios cronológicos.

2.1. Estabilização Inicial da Infraestrutura e API Backend

O processo de colocar a API backend em funcionamento e garantir que se comunicasse corretamente com o frontend e os serviços de IA do Google envolveu a depuração de uma série de problemas interligados.

Fase 1: Erros Iniciais no Frontend

  • Sintomas: Erros 404 ao tentar carregar imagens (logo), layout quebrado no site publicado, e erros de SyntaxError em arquivos JavaScript que impediam a renderização do chatbot e da calculadora no navegador do usuário.
  • Diagnóstico: Caminhos de arquivos incorretos referenciados no mkdocs.yml e conteúdo inválido (texto não-código) introduzido acidentalmente na primeira linha de alguns arquivos JavaScript.
  • Solução: Limpeza dos arquivos JavaScript corrompidos e correção dos caminhos de arquivos (links para imagens, scripts) no mkdocs.yml.
  • Resultado: A interface visual do site foi restaurada no navegador, mas a área do chatbot ainda apresentava um "erro de comunicação" com o backend.

Fase 2: Problema de CORS

  • Sintomas: A consola do navegador exibia consistentemente o erro de segurança blocked by CORS policy (Política CORS bloqueou a requisição). Não havia registros de atividade nos logs da Google Cloud Function para essas requisições bloqueadas pelo navegador.
  • Diagnóstico: O navegador estava bloqueando as requisições do site estático (frontend) para a API backend porque a API não retornava os cabeçalhos de permissão Access-Control-Allow-Origin necessários.
  • Solução: Tentativa inicial de implementar a lógica de CORS no código da API utilizando a biblioteca Flask-Cors.
  • Resultado: O problema de CORS no navegador persistiu, indicando que a função na nuvem sequer estava conseguindo iniciar e executar o código de configuração do CORS antes de colapsar.

Fase 3: Colapso por Falta de Memória

  • Sintomas: O erro de CORS não era a causa raiz, mas um sintoma de um problema mais profundo. Uma análise detalhada dos logs da Google Cloud Function revelou o erro fatal: Memory limit... exceeded (Limite de memória excedido).
  • Diagnóstico: A Google Cloud Function, com sua configuração padrão de 256MB de memória, era insuficiente para carregar e inicializar as bibliotecas de Inteligência Artificial (Langchain, ChromaDB, etc.) necessárias para a API. Isso causava o "colapso" imediato da função ao tentar iniciar.
  • Solução: A memória alocada para a função foi aumentada para 512MiB utilizando o parâmetro --memory=512MiB no comando de deploy (gcloud functions deploy).
  • Resultado: A função na nuvem tornou-se estável, deixou de colapsar no arranque e começou a responder aos pedidos iniciais (OPTIONS) com status 200 OK. No entanto, o erro de CORS no navegador, de forma inesperada, continuou a ocorrer para as requisições principais (POST).

Fase 4: Timeout e Permissões de IAM

  • Sintomas: Testes diretos à API utilizando ferramentas como curl (que ignoram as políticas de CORS do navegador) mostraram que as requisições eram enviadas com sucesso, mas a API nunca respondia com o resultado da consulta, causando um timeout após o tempo limite configurado (300 segundos).
  • Diagnóstico: O "congelamento" da execução estava ocorrendo dentro do código da função após o seu início bem-sucedido. A principal suspeita recaiu sobre a chamada a serviços externos, especificamente a API de IA do Google (Gemini-Pro), provavelmente devido à falta de permissões de acesso para a conta de serviço da função.
  • Solução: Foram adicionados manualmente os papéis de IAM (Identity and Access Management) necessários à conta de serviço associada à Cloud Function (...-compute@developer.gserviceaccount.com) através da consola do Google Cloud: "Usuário do Vertex AI" (para permitir o uso dos modelos de IA do Google) e "Cloud Build Builder" (para resolver um problema secundário identificado no processo de build/deploy).
  • Resultado: Todas as permissões de infraestrutura e acesso foram corrigidas, mas o timeout de 300 segundos durante as requisições principais persistiu.

Fase 5: Ponto de Falha Final - Busca na Base de Dados

  • Sintomas: O timeout de 300 segundos persistia mesmo com todas as configurações de infraestrutura e permissões aparentemente corretas.
  • Diagnóstico: Foi implantada uma versão da API com logs de depuração detalhados no código Python ("PASSO 1", "PASSO 2", etc.). Os logs provaram inequivocamente que a execução iniciava, carregava as bibliotecas e a base de dados, imprimia "PASSO 1" (antes da busca), mas depois "congelava" indefinidamente na chamada específica responsável por fazer a busca de similaridade na base de dados vetorial ChromaDB: qa_chain.retriever.get_relevant_documents(query).
  • Solução: A hipótese levantada foi que a própria base de dados chroma_db estava corrompida ou ineficiente para o ambiente de execução, ou havia uma incompatibilidade entre a versão da base de dados e as bibliotecas no ambiente da Cloud Function. A solução aplicada foi apagar o diretório chroma_db local, recriá-lo do zero executando novamente o script create_vector_store.py (garantindo que salvava na pasta correta para o deploy) e realizar um novo deploy completo da função.
  • Resultado: Esta etapa resolveu o bloqueio principal. A execução da busca na base de dados deixou de congelar, e a API passou a responder com os resultados da busca (embora as respostas iniciais ainda fossem genéricas, o que levou à próxima fase de depuração).

2.2. Refinamento da Inteligência da Assistente Virtual (AVT)

Com a API estável e respondendo, a próxima fase foi melhorar a qualidade e relevância das respostas da Assistente Virtual (AVT), que ainda parecia não utilizar plenamente o conteúdo disponível.

  • Desafio: A AVT estava funcional, mas suas respostas eram genéricas, frequentemente afirmando não encontrar informação que sabíamos existir na base de conhecimento.
  • Soluções Implementadas:
    • Otimização da Quebra de Documentos: O script create_vector_store.py foi aprimorado para utilizar o MarkdownHeaderTextSplitter. Esta ferramenta divide os documentos Markdown com base em sua estrutura de títulos (#, ##, etc.), criando "pedaços" de conhecimento ("chunks") mais curtos, mais ricos em contexto (cada pedaço contém o título e subtítulos que o precedem) e, consequentemente, mais fáceis para a IA encontrar informações relevantes durante a busca.
    • Upgrade do Retriever: Implementamos o MultiQueryRetriever na API backend. Esta técnica permite que a IA reformule a pergunta original do usuário de várias formas diferentes antes de realizar a busca na base de dados vetorial. Isso aumenta a chance de encontrar documentos relevantes, mesmo que a formulação inicial do usuário não seja perfeita. Os parâmetros do retriever foram ajustados (afinados) para aumentar a quantidade de resultados retornados e a tolerância da busca por similaridade.
    • Engenharia de Prompt: Criamos um PromptTemplate customizado. Este template define a "persona" da AVT (uma assistente virtual informativa da Takwara-Tech), estabelece seu tom de comunicação (cordial, prestativa), define suas regras de comportamento (sempre citar as fontes/documentos que utilizou para gerar a resposta, responder no idioma do usuário que enviou a pergunta, lidar graciosamente com erros de digitação) e fornece contexto adicional para a IA gerar respostas mais úteis e direcionadas.

2.3. Implementação e Desafios de Layout da Interface

Em paralelo à estabilização e refinamento da API, foram realizadas diversas tentativas para implementar a visão estratégica do layout do portal, focando na "Tool Box Interativa".

Histórico de Implementação e Diagnóstico (Tentativas)

Para alcançar a visão de uma interface com "Tool Box Interativa" utilizando o tema Material for MkDocs, que possui uma estrutura de layout própria baseada em CSS Grid, foram testadas várias abordagens de customização com diferentes resultados:

  • Tentativa 1: Abordagem com CSS Grid Diretamente: Aplicação direta de regras CSS display: grid e grid-template-columns. Funcionou apenas na página inicial, quebrando nas páginas de artigos devido a inconsistências na estrutura HTML gerada pelo tema.
  • Tentativa 2: Abordagem com Template Override (main.html): Tentativa de substituir o conteúdo do arquivo overrides/main.html por uma estrutura de colunas customizada. Resultou em conflitos de layout severos, perda da coluna de conteúdo e duplicação de elementos de navegação. O diagnóstico foi que a substituição completa do bloco de conteúdo principal quebra a lógica interna do tema.
  • Diagnóstico do Problema: As tentativas de forçar um layout de múltiplas colunas fixas através de manipulação direta do CSS ou override completo do template de conteúdo entram em conflito fundamental com a arquitetura e o CSS do tema Material for MkDocs, que gerencia dinamicamente a posição dos componentes principais (navegação, conteúdo, TOC).

Implementação da Solução com Web Components

Diante da resiliência do tema padrão à manipulação direta do layout, a estratégia foi pivotada para uma solução mais robusta e isolada tecnologicamente, baseada em Web Components.

  • Solução Definida: Implementar a "Tool Box Interativa" utilizando a tecnologia de Web Components.
  • Ação: Criação de um elemento HTML customizado (<takwara-toolbox>), utilização do Shadow DOM para encapsulamento e isolamento de estilos, e implementação da lógica de posicionamento em JavaScript (toolbox.js) para calcular e ajustar dinamicamente a altura da Tool Box, fixando-a à esquerda e gerenciando seu comportamento de scroll.
  • Resultado: Esta abordagem com Web Components resolveu os conflitos de layout. A "Takwara Tool Box" é renderizada com sucesso como um componente isolado, fixo à esquerda, com altura dinâmica e comportamento de scroll correto, sem quebras ou sobreposições com o tema principal. A estrutura HTML para as ferramentas (AVT, Grafo, Calculadora) é carregada corretamente dentro dela.

Seção 3: Ciclo Padrão de Desenvolvimento e Publicação (SOP Atual)

Manter a plataforma atualizada com novo conteúdo e funcionalidades requer um fluxo de trabalho bem definido, que integra a gestão de código, a atualização da base de conhecimento da IA e a publicação do site estático e da API backend. Este fluxo, consolidado após a fase de depuração, é o Procedimento Operacional Padrão (SOP) para realizar atualizações.

3.1. Preparação Inicial (Realizar Apenas Uma Vez)

  • Clonar o Repositório: Baixe uma cópia local do repositório do GitHub.
  • Configurar Ambiente Python: Crie e ative um ambiente virtual, instalando as dependências do requirements.txt.
  • Configurar Chave da API do Google: Crie um arquivo .env com GOOGLE_API_KEY="SUA_CHAVE_AQUI" na raiz do repositório (para execução local do script de vetorização). Configure a chave também no ambiente da Google Cloud Function.
  • Limpar .gitignore: Garanta que site/, temp_repo/ e backend-api/chroma_db/ estão incluídos no .gitignore para evitar versionamento indesejado.

3.2. O Ciclo de Atualização (Realizar Para Cada Alteração)

Este é o checklist a ser seguido sempre que houver modificações no conteúdo, frontend ou backend.

  • Passo 1: Edição e Conteúdo
    • Crie ou edite os seus ficheiros de artigos (.md) dentro da pasta docs/.
    • CRÍTICO: Se criou um novo artigo ou alterou o caminho de um, "matricule-o" na secção nav: do ficheiro mkdocs.yml. Sem este passo, o artigo não será incluído na navegação do site.
  • Passo 2: Atualização da Inteligência Artificial (Backend)
    • Gere a nova base de dados da IA: Abra o terminal na pasta Chatbot - Takwara e execute o script create_vector_store.py. Ele lerá o conteúdo atualizado e salvará a nova base de dados em ./backend-api/chroma_db. 
      cd Chatbot - Takwara
python create_vector_store.py
cd .. # Volte para a raiz do repositório
    • Envie a nova API e base de dados para a nuvem: Certifique-se que o ambiente virtual está ativo na pasta que contém backend-api (ou navegue para backend-api e use --source=.) e execute o comando de deploy. 
      gcloud functions deploy chatbot-api \
--gen2 \
--runtime=python311 \
--region=southamerica-east1 \
--source=./backend-api \
--entry-point=chatbot_api \
--trigger-http \
--allow-unauthenticated \
--memory=512MiB \
--timeout=300s
  • Passo 3: Salve as Alterações Oficialmente (Git)
    • Prepare todas as suas alterações locais (arquivos de conteúdo, mkdocs.yml, arquivos do backend com a nova base de dados): 
      git add .
    • Crie um commit para registrar as alterações com uma mensagem descritiva: 
      git commit -m "Sua mensagem descritiva aqui (ex: Adiciona novo artigo sobre X, atualiza base da AVT e corrige layout Y)"
  • Passo 4: Publique o Site Visual (Frontend)
    • Na raiz do repositório, com o ambiente virtual ativo, execute o comando que constrói o site estático e o publica no GitHub Pages: 
      mkdocs gh-deploy
  • Passo 5: Verificação Final
    • Aguarde 2-3 minutos para que os deploys se propaguem.
    • Abra o seu site online (https://resck.github.io/Takwara-Tech/) numa janela anónima ou limpe o cache do navegador para garantir que não está a ver uma versão antiga e que todas as alterações (conteúdo, layout, funcionalidade da AVT) estão corretas.

Seção 4: Estado Atual do Projeto, Pendências e Próximas Etapas

Com base no trabalho realizado até Junho de 2025, a plataforma atingiu um estado de estabilidade funcional e estrutural, mas ainda possui pendências que requerem desenvolvimento.

4.1. Estado Atual Implementado (Junho de 2025)

  • Infraestrutura e API: A API backend está implantada, estável e acessível na Google Cloud Function (Geração 2, southamerica-east1). Problemas de deploy, memória, permissões de IAM e o bloqueio na busca da base de dados foram resolvidos. A comunicação básica entre frontend e backend está funcional.
  • Base de Conhecimento da IA: O script create_vector_store.py está otimizado para quebrar documentos de forma contextual (usando MarkdownHeaderTextSplitter) e gerar a base de dados chroma_db corretamente dentro do diretório da API.
  • Inteligência da AVT (Respostas Base): A Assistente Virtual utiliza o MultiQueryRetriever e um PromptTemplate customizado para gerar respostas razoavelmente relevantes e contextualizadas a partir da base de conhecimento. Ela cita as fontes encontradas nos documentos processados.
  • Layout Básico da Tool Box: A estrutura visual da "Takwara Tool Box" está implementada como um Web Component isolado e fixo à esquerda, com posicionamento e comportamento de scroll dinâmicos, sem conflitos de layout com o tema principal Material for MkDocs. O HTML básico das ferramentas (AVT, Grafo, Calculadora) é carregado corretamente dentro dela.
  • Customização Básica do Tema: O menu de navegação principal está configurado como barra lateral fixa. Um rodapé customizado, incluindo um widget de relógio climático (Climate Clock), foi implementado com sucesso via override de template.

4.2. Pendências Críticas

  • Ativação da Lógica das Ferramentas na Tool Box: Embora a estrutura HTML das ferramentas (AVT, Grafo de Conhecimento, Calculadoras) esteja presente dentro da Tool Box, os scripts JavaScript que controlam a lógica e a interatividade de cada ferramenta (por exemplo, o script que gerencia o formulário de chat, o grafo interativo, as calculadoras) não estão a conseguir inicializar corretamente devido a uma "race condition" (os scripts tentam agir antes do HTML estar completamente disponível no Shadow DOM do Web Component).
  • Implementação Completa das APIs de Monitoramento: A integração dos "Painéis de Impacto" (dados em tempo real como CO₂, temperatura global, dados de queimadas) no cabeçalho e rodapé customizados ainda não foi iniciada.
  • Ajustes Finos de Design: Polimento final de elementos visuais, como o rodapé padrão do tema (que apresentou resistência a algumas customizações CSS) e a revisão geral da UI/UX após a implementação das funcionalidades.
  • Busca Contextual da AVT (Nível de Página): A lógica para a AVT priorizar a busca por informações relacionadas especificamente à página que o usuário está visualizando (usando a URL atual como contexto) antes de fazer uma busca global na base de conhecimento ainda precisa ser implementada no código da API backend.
  • Grafo de Conhecimento: A lógica para carregar dados dinâmicos ou permitir interatividade além da navegação básica no Grafo de Conhecimento não está ativa.
  • Calculadoras: A lógica backend e/ou frontend para as calculadoras (ex: Cálculo de Domos) não está completamente ativa ou integrada.

4.3. Plano de Ação e Roadmap

As próximas etapas de desenvolvimento focarão em resolver as pendências críticas e realizar a visão completa da plataforma.

  1. Ativação da Tool Box (Prioridade Máxima): Implementar um sistema de eventos customizados no script toolbox.js. Este script irá disparar um evento (takwara:tools-ready) após injetar o HTML das ferramentas no Shadow DOM. Os scripts individuais das ferramentas (script.js, graph.js, calculadora.js) serão modificados para "escutar" este evento e só iniciar sua lógica após recebê-lo, garantindo que o HTML necessário já esteja disponível.
  2. Implementação do "Painel de Impacto": Iniciar a integração de APIs de dados para popular o painel customizado no cabeçalho e rodapé, começando pela definição e implementação do primeiro indicador (ex: Níveis de CO₂).
  3. Refinamento da Inteligência da AVT (Busca Contextual): Modificar o código da API backend (main.py) para receber a URL da página atual como um parâmetro na requisição do frontend. Utilizar esta URL para carregar o conteúdo específico da página e dar maior peso a este texto durante a busca por similaridade na base de dados vetorial.
  4. Implementação Completa das Ferramentas: Finalizar a lógica e a integração completa das demais ferramentas planejadas (Grafo de Conhecimento, Calculadoras) dentro da Tool Box, garantindo que seus scripts funcionem corretamente após a ativação via evento customizado.
  5. Polimento Final e UI/UX: Realizar ajustes de design e uma revisão geral da interface e experiência do usuário.

Seção 5: Manual Técnico de Operação e Manutenção

Este manual serve como guia operacional e de manutenção para colaboradores e interessados no projeto Takwara-Tech, explicando como configurar o ambiente, realizar atualizações e contribuir sob a licença Creative Commons.

5.1. Tecnologias Centrais

O projeto é construído sobre a combinação das seguintes tecnologias:

  • MkDocs + Material for MkDocs: Gerador de site estático e tema para a documentação e frontend.
  • Web Components: Tecnologia para encapsular a "Tool Box Interativa" no frontend.
  • Python 3.11 + Flask: Linguagem de programação e microframework para a API backend.
  • Google Cloud Functions (Geração 2): Ambiente serverless para hospedar a API backend.
  • Langchain, Google Generative AI, ChromaDB: Bibliotecas e modelos para a funcionalidade RAG (Retrieval Augmented Generation) da AVT e Embeddings.
  • Vis.js Network: Biblioteca JavaScript para visualização interativa do Grafo de Conhecimento.
  • Marked.js: Biblioteca JavaScript para renderizar Markdown nas respostas da AVT.
  • Git + GitHub: Sistema de controle de versão e plataforma de hospedagem do código.

5.2. Pré-requisitos

Para operar e manter o sistema, é necessário ter instalado e configurado:

  • Git: Para clonar o repositório e gerenciar versões.
  • Python 3.11: Com um ambiente virtual (venv recomendado).
  • Pip: Gerenciador de pacotes do Python.
  • MkDocs e Material for MkDocs: Instalados via pip.
  • Google Cloud SDK (gcloud CLI): Configurado e autenticado com a sua conta Google Cloud (necessário apenas para deploy do backend).
  • Chave da API do Google (GOOGLE_API_KEY): Para acesso aos modelos de Embedding e LLM. Deve ser configurada como variável de ambiente (localmente via arquivo .env e no ambiente da Google Cloud Function).
  • Editor de Texto ou IDE: Para modificar os arquivos de código e documentação.

5.3. Primeiros Passos: Clonagem e Configuração do Ambiente

  1. Clonar o Repositório: Abra o terminal e execute: 
    git clone https://github.com/Resck/Takwara-Tech.git
    Navegue para a raiz do repositório clonado: 
    cd Takwara-Tech
  2. Configurar Ambiente Python: Crie um ambiente virtual (recomendado): 
    python -m venv .venv
    Ative o ambiente virtual:
    • No Windows: .venv\Scripts\activate
    • No macOS/Linux: source .venv/bin/activate Instale as dependências do projeto (frontend e backend): 
      pip install -r requirements.txt
  3. Configurar Chave da API do Google: Crie um arquivo chamado .env na raiz do repositório com o seguinte conteúdo (substitua SUA_CHAVE_AQUI pela sua chave real): 
    GOOGLE_API_KEY="SUA_CHAVE_AQUI"
    Nota: Esta chave também precisará ser configurada diretamente no ambiente da Google Cloud Function para o deploy do backend.

5.4. Fluxos de Trabalho de Manutenção Detalhados

A manutenção da plataforma envolve diferentes fluxos, dependendo do componente a ser atualizado. Estes fluxos seguem os passos do Ciclo de Atualização (SOP) detalhado na Seção 3.2, com foco nas ações específicas para cada tipo de componente.

5.4.1. Atualização de Conteúdo (Arquivos Markdown)

Este fluxo abrange a adição ou edição de artigos, documentação e outras informações que aparecem no site estático e alimentam a base de conhecimento da AVT.

  1. Localize a Pasta de Documentos: Os arquivos Markdown (.md) estão localizados na pasta docs/ na raiz do repositório.
  2. Adicione ou Edite Arquivos .md: Use seu editor para criar novos arquivos ou modificar os existentes dentro da estrutura de pastas em docs/.
  3. Atualize a Navegação do Site (Obrigatório para Novos Arquivos): Se você adicionou um novo arquivo ou moveu um arquivo existente, é essencial "matricular" este arquivo na estrutura de navegação no arquivo de configuração do MkDocs: mkdocs.yml (na raiz do repositório).
    • Abra mkdocs.yml.
    • Encontre a seção nav:.
    • Adicione uma entrada para o seu novo arquivo, seguindo a estrutura hierárquica desejada. Exemplo: 
      nav:
  - 'Início': 'index.md'
  # ... outras entradas ...
  - 'Nova Seção':
    - 'Meu Novo Artigo': 'caminho/para/meu-novo-artigo.md' # <-- Adicione a entrada aqui
  # ...
    • Salve mkdocs.yml.
  4. Pré-visualize as Alterações (Opcional, mas Recomendado): Para ver como as suas alterações de conteúdo e navegação aparecem no site, rode o servidor local do MkDocs (mkdocs serve na raiz do repositório com ambiente virtual ativo) e navegue em http://127.0.0.1:8000/.
  5. Atualize a Base de Conhecimento da AVT: Navegue para a pasta Chatbot - Takwara, certifique-se que o ambiente virtual está ativo e execute python create_vector_store.py. Este script processará os arquivos .md atualizados e salvará a base de dados em ./backend-api/chroma_db.
  6. Deploy do Backend da AVT: Navegue para a pasta do backend (backend-api ou pasta pai), certifique-se que o ambiente virtual está ativo e execute o comando gcloud functions deploy... para enviar a API com a nova base de dados.
  7. Salve e Versiona as Alterações (Git): Navegue de volta para a raiz do repositório, adicione todas as suas alterações (git add .), crie um commit (git commit -m "...") e envie para o GitHub (git push origin main).
  8. Publique o Site Frontend (GitHub Pages): Na raiz do repositório, com o ambiente virtual ativo, execute mkdocs gh-deploy.
  9. Verifique Online: Acesse o site publicado em uma janela anônima ou limpe o cache para ver a versão mais recente e testar o conteúdo e a AVT.

5.4.2. Atualização de Layout e Funcionalidades do Frontend (HTML, CSS, JavaScript)

Este fluxo abrange modificações na aparência do site, Tool Box e na lógica das ferramentas que rodam no navegador.

  1. Localize os Arquivos: Os arquivos de customização estão em overrides/ (templates HTML) e docs/assets/js/, docs/assets/css/ (scripts e estilos customizados). O script principal da Tool Box é docs/assets/js/toolbox.js.
  2. Edite Arquivos: Modifique os arquivos .html, .css ou .js conforme necessário. Ao modificar JavaScripts das ferramentas (AVT, Calculadora, Grafo), lembre-se que elas rodam no Shadow DOM da Tool Box e são inicializadas pelo evento takwara:tools-ready.
  3. Pré-visualize as Alterações: Utilize mkdocs serve (na raiz do repositório) para visualizar as alterações localmente no navegador antes de publicar.
  4. Salve e Versiona as Alterações (Git): Navegue para a raiz do repositório, adicione todas as suas alterações (git add .), crie um commit (git commit -m "...") e envie para o GitHub (git push origin main).
  5. Publique o Site Frontend (GitHub Pages): Na raiz do repositório, com o ambiente virtual ativo, execute mkdocs gh-deploy.
  6. Verifique Online: Acesse o site publicado em uma janela anônima ou limpe o cache.

5.4.3. Atualização da Lógica do Backend (API da Calculadora, Lógica RAG da AVT em main.py)

Este fluxo abrange modificações no código Python que roda na Google Cloud Function.

  1. Localize os Arquivos: O código principal do backend está na pasta Chatbot - Takwara/backend-api/ (ex: main.py).
  2. Edite Arquivos: Modifique os arquivos Python em backend-api/. Por exemplo, para ajustar o prompt ou o retriever da AVT no main.py, ou corrigir a lógica da API da Calculadora.
  3. Salve as Alterações: Salve os arquivos Python modificados.
  4. Prepare e Versiona as Alterações (Git): Navegue para a raiz do repositório, adicione todas as suas alterações (git add .), crie um commit (git commit -m "...") e envie para o GitHub (git push origin main).
  5. Deploy do Backend (Obrigatório para Aplicar Alterações na Lógica): Navegue para a pasta que contém a pasta do backend (Chatbot - Takwara ou pasta pai), certifique-se que o ambiente virtual está ativo e execute o comando gcloud functions deploy... (ajuste região, memória, timeout se necessário, e o caminho --source se backend-api não estiver diretamente nesta pasta).
  6. Verifique Online: Acesse o site publicado e teste a funcionalidade da AVT ou da Calculadora (se a API dela foi modificada).

5.5. Comandos Comuns do Terminal para Manutenção do Repositório

Execute estes comandos no terminal na raiz do seu repositório (Takwara-Tech), com o ambiente virtual ativo.

  • Clonar o Repositório: git clone <repo_url>
  • Verificar Status dos Arquivos: git status (Mostra quais arquivos foram modificados, adicionados ou removidos)
  • Adicionar Arquivos Modificados para Commit: git add . (Adiciona todos os arquivos modificados/novos no diretório atual e subdiretórios)
  • Criar um Commit: git commit -m "Mensagem descritiva das alterações" (Salve as alterações localmente com uma mensagem)
  • Enviar Commits para o GitHub: git push origin main (Envia os commits locais para o branch 'main' no GitHub)
  • Baixar Últimas Alterações do GitHub: git pull origin main (Baixa as alterações do branch 'main' no GitHub para o seu repositório local)
  • Criar um Novo Branch (para desenvolver uma feature isoladamente): git branch minha-nova-feature
  • Mudar para um Branch: git checkout minha-nova-feature
  • Construir Site Localmente: mkdocs build (Cria a pasta site/ com o site estático)
  • Servir Site Localmente para Pré-visualizar: mkdocs serve (Inicia um servidor web local)
  • Publicar Site no GitHub Pages: mkdocs gh-deploy (Construí e envia para o branch gh-pages)
  • Atualizar Base de Conhecimento da AVT: Navegue para Chatbot - Takwara e execute python create_vector_store.py.
  • Deploy da Google Cloud Function: Navegue para Chatbot - Takwara/backend-api e execute gcloud functions deploy....

5.6. Contribuição e a Licença CC BY 4.0

O projeto Takwara-Tech é licenciado sob a Creative Commons Attribution 4.0 International (CC BY 4.0). Isso significa que você é livre para:

  • Compartilhar: Copiar e redistribuir o material em qualquer suporte ou formato.
  • Adaptar: Remixar, transformar, e criar a partir do material para quaisquer fins, mesmo que comerciais.

Desde que você atribua o devido crédito, forneça um link para a licença e indique se foram feitas alterações. Você pode fazê-lo de qualquer forma razoável, mas não de forma a sugerir que o licenciante o endossa ou aprova o seu uso.

Licença CC BY 4.0 Este trabalho está licenciado sob a Creative Commons Atribuição 4.0 Internacional.

Encorajamos ativamente a colaboração e a multiplicação desta tecnologia e conhecimento. Se você deseja contribuir com código, documentação ou dados, siga o fluxo de trabalho padrão do GitHub:

  1. Fork o repositório para a sua conta GitHub.
  2. Clone o seu fork para o seu computador local.
  3. Crie um novo branch para as suas alterações (git checkout -b nome-da-sua-feature).
  4. Faça as suas modificações (código, documentação, dados).
  5. Salve e versiona as suas alterações (git add ., git commit -m "Sua mensagem").
  6. Envie suas alterações para o seu fork no GitHub (git push origin nome-da-sua-feature).
  7. Crie um Pull Request (PR) da sua branch no seu fork para a branch main do repositório original Takwara-Tech.
  8. Descreva claramente as suas alterações no Pull Request.

5.7. Repositórios com Estruturas Tecnológicas Similares (Para Inspiração)

Projetos que combinam geradores de sites estáticos com APIs e ferramentas de dados/IA são cada vez mais comuns. Embora a combinação exata de MkDocs + Cloud Functions + ChromaDB + vis.js + Web Components possa ser específica, exemplos de aplicação destes componentes podem ser encontrados em:

  • Documentação como Código: Projetos que utilizam MkDocs, Sphinx, Jekyll ou Hugo para gerar documentação a partir de arquivos de texto versionados em Git. O próprio Material for MkDocs Documentation é um excelente exemplo do uso avançado do tema e suas funcionalidades.
  • Projetos de Visualização de Dados com JavaScript: Repositórios que utilizam bibliotecas como vis.js, Cytoscape.js, D3.js para criar visualizações interativas baseadas em dados estruturados (que poderiam, por exemplo, vir de um arquivo JSON gerado por um script).
  • Exemplos de RAG com LangChain/LlamaIndex: Muitos repositórios no GitHub demonstram o uso de LangChain ou LlamaIndex para criar pipelines de Question Answering com base em documentos, frequentemente integrando bases de dados vetoriais como ChromaDB e modelos de LLM/Embeddings. Buscar por "Langchain RAG example github" ou "LlamaIndex ChromaDB tutorial" pode fornecer insights sobre a parte backend da AVT.
  • Projetos Serverless com Python: Repositórios demonstrando o uso de Google Cloud Functions, AWS Lambda ou Azure Functions com Python para criar APIs RESTful que interagem com outros serviços (como bases de dados ou APIs de IA).

Seção 6: Apêndice Técnico: Análise Detalhada do Script create_vector_store.py

Este apêndice fornece uma análise aprofundada do script Python responsável por gerar a base de conhecimento da Assistente Virtual.

6.1. Objetivo do Script

O create_vector_store.py funciona como um "indexador" ou "construtor de memória" para a Assistente Virtual. Sua missão principal é:

  1. Acessar o conteúdo textual de um repositório Git (especificamente o repositório do site Takwara-Tech).
  2. Processar esse conteúdo utilizando modelos de Embedding (IA).
  3. Salvar o texto original e seus vetores correspondentes em uma base de dados vetorial local.

Esta base de dados (ChromaDB) é o que a API backend utiliza para realizar buscas rápidas de similaridade semântica, permitindo que a Assistente Virtual encontre informações relevantes para responder às perguntas dos usuários, mesmo que as palavras exatas da pergunta não estejam presentes no texto original.

6.2. O Fluxo de Trabalho: Uma Jornada em 6 Etapas

Antes de analisar o código, é útil entender a sequência lógica de operações realizadas pelo script:

  1. Clonar: O script inicia baixando uma cópia local do repositório Git alvo (definido pela REPO_URL) para um diretório temporário (./temp_repo).
  2. Carregar: Ele lê os arquivos de texto baixados que correspondem a um filtro especificado (por exemplo, apenas arquivos .py, .md, .txt).
  3. Dividir: Como modelos de Embedding geralmente têm um limite no tamanho do texto que podem processar de uma vez, e para garantir que os resultados da busca sejam granulars e contextuais, o script quebra os documentos lidos em pedaços menores (chunks) com alguma sobreposição entre eles. Ferramentas como RecursiveCharacterTextSplitter ou MarkdownHeaderTextSplitter são usadas para essa divisão inteligente.
  4. Vetorizar (ou "Embed"): Para cada pedaço de texto resultante da divisão, o script envia este texto para uma API de modelo de Embedding (neste caso, a API do Google, GoogleGenerativeAIEmbeddings). O modelo de IA processa o texto e o converte em um vetor numérico de alta dimensão (um "embedding") que captura seu significado semântico. Textos com significados similares terão vetores próximos no espaço multidimensional.
  5. Armazenar: O script armazena cada pedaço de texto original juntamente com seu vetor correspondente em uma base de dados vetorial (ChromaDB). Esta base de dados é otimizada para realizar buscas rápidas de vizinhos mais próximos (ou seja, encontrar vetores - e, portanto, textos - semanticamente similares a um vetor de consulta).
  6. Salvar: Finalmente, o script salva a base de dados ChromaDB criada no disco, em um diretório persistente (definido por PERSIST_DIRECTORY, configurado para ser ./backend-api/chroma_db). Isso permite que a API backend carregue a base de dados rapidamente sem ter que refazer todo o processo de clonagem, carregamento, divisão e vetorização a cada vez.

6.3. Destrinchando o Código

Vamos analisar os blocos de código Python que implementam este fluxo:

1. As Importações (As Ferramentas Necessárias)

import os
from dotenv import load_dotenv
from langchain_community.document_loaders import GitLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_google_genai import GoogleGenerativeAIEmbeddings
# Pode incluir outras importações se o script usar MarkdownHeaderTextSplitter, etc.
# from langchain.text_splitter import MarkdownHeaderTextSplitter
  • import os: Fornece funções para interagir com o sistema operacional, útil para manipular caminhos de arquivos e diretórios.
  • from dotenv import load_dotenv: Importa a função para carregar variáveis de ambiente a partir de um arquivo .env, usado para carregar a chave da API do Google sem expô-la no código.
  • from langchain_community.document_loaders import GitLoader: Importa a classe GitLoader da biblioteca LangChain, especializada em clonar repositórios Git e carregar seu conteúdo como documentos.
  • from langchain.text_splitter import RecursiveCharacterTextSplitter: Importa uma classe para dividir textos longos de forma recursiva, tentando manter a coerência contextual. (Outros splitters como MarkdownHeaderTextSplitter podem ser usados, dependendo da versão do script).
  • from langchain_community.vectorstores import Chroma: Importa a classe Chroma da biblioteca LangChain, que fornece a interface para a base de dados vetorial ChromaDB.
  • from langchain_google_genai import GoogleGenerativeAIEmbeddings: Importa a classe para criar embeddings usando a API Generative AI do Google (Gemini/Vertex AI).

2. As Configurações Globais (Definindo o Alvo)

load_dotenv() # Carrega variáveis do .env

# Configurações do Repositório e Diretório de Persistência
REPO_URL = "URL_DO_SEU_REPOSITORIO_AQUI" # Ex: "https://github.com/resck/Takwara-Tech.git"
PERSIST_DIRECTORY = "./backend-api/chroma_db" # Diretório onde a base de dados ChromaDB será salva (dentro da pasta da API)
  • load_dotenv(): Executa a função para ler o arquivo .env (que deve conter GOOGLE_API_KEY="SUA_CHAVE_AQUI") e carregar as variáveis para o ambiente do script.
  • REPO_URL: Uma variável string que define a URL do repositório Git a ser clonado e processado pelo script.
  • PERSIST_DIRECTORY: Define o caminho do diretório onde a base de dados ChromaDB persistirá (será salva). É configurado para apontar para um subdiretório dentro da pasta que será incluída no deploy da API backend, garantindo que a base de dados correta seja enviada.

3. A Função Principal (build_and_save_vector_store)

Este é o bloco de código que orquestra as etapas do fluxo de trabalho.

def build_and_save_vector_store():
    # 1. e 2. Clonar e Carregar Documentos
    print(f"Clonando repositório de {REPO_URL}...")
    loader = GitLoader(
        clone_url=REPO_URL,
        repo_path="./temp_repo", # Clona para um diretório temporário
        file_filter=lambda file_path: file_path.endswith((".py", ".md", ".txt")) # Filtra por tipos de arquivo
    )
    docs = loader.load() # Carrega os documentos filtrados

    print(f"Carregados {len(docs)} documentos.")

    # 3. Dividir Documentos em Pedaços (Chunks)
    print("Dividindo documentos em pedaços (chunks)...")
    # Configuração do divisor (pode variar, MarkdownHeaderTextSplitter seria usado para estrutura MD)
    text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
    # Se usar MarkdownHeaderTextSplitter, seria algo como:
    # headers_to_split_on = [("#", "Header 1"), ("##", "Header 2"), ...]
    # text_splitter = MarkdownHeaderTextSplitter(headers_to_split_on=headers_to_split_on)

    chunks = text_splitter.split_documents(docs)
    print(f"Criados {len(chunks)} pedaços de texto.")

    # 4. Vetorizar (Embed) os Pedaços
    print("Gerando embeddings para os pedaços (chunks)...")
    # Inicializa o modelo de Embedding do Google
    embeddings = GoogleGenerativeAIEmbeddings(model="models/embedding-001") # Modelo recomendado para embeddings

    # 5. e 6. Armazenar e Salvar na Base de Dados Vetorial (ChromaDB)
    print(f"Criando e salvando a base de dados vetorial em {PERSIST_DIRECTORY}...")
    # Cria uma nova base de dados ChromaDB a partir dos chunks e embeddings, persistindo no diretório especificado
    vectorstore = Chroma.from_documents(
        documents=chunks,
        embedding=embeddings,
        persist_directory=PERSIST_DIRECTORY
    )

    # O método from_documents já salva a base de dados no disco
    # vectorstore.persist() # Este método pode ser chamado explicitamente dependendo da versão da biblioteca

    print("Base de dados vetorial criada e salva com sucesso.")

    # Opcional: Limpar o diretório temporário clonado
    # import shutil
    # if os.path.exists("./temp_repo"):
    #     shutil.rmtree("./temp_repo")
    #     print("Diretório temporário ./temp_repo removido.")

if __name__ == "__main__":
    build_and_save_vector_store()
  • def build_and_save_vector_store():: Define a função principal que contém a lógica de processamento.
  • loader = GitLoader(...): Inicializa o GitLoader com a URL do repositório, um caminho temporário para clonagem (./temp_repo) e um filtro (file_filter) para carregar apenas arquivos de texto relevantes (Python, Markdown, TXT).
  • docs = loader.load(): Executa a operação de clonagem e carregamento, armazenando os documentos lidos em uma lista chamada docs.
  • text_splitter = RecursiveCharacterTextSplitter(...): Inicializa um objeto divisor de texto (text_splitter) com parâmetros para definir o tamanho dos pedaços (chunk_size) e a sobreposição entre eles (chunk_overlap). O MarkdownHeaderTextSplitter seria uma alternativa específica para documentos Markdown.
  • chunks = text_splitter.split_documents(docs): Aplica o divisor aos documentos carregados, gerando uma lista de pedaços menores.
  • embeddings = GoogleGenerativeAIEmbeddings(...): Inicializa o modelo de Embedding do Google a ser utilizado para converter texto em vetores. models/embedding-001 é um modelo comum para essa tarefa.
  • vectorstore = Chroma.from_documents(...): Este é um passo crucial. Ele cria (ou carrega, se já existir) uma base de dados ChromaDB (vectorstore). O método from_documents recebe a lista de pedaços (chunks), o modelo de embedding (embeddings) e o diretório onde a base de dados deve ser persistida (PERSIST_DIRECTORY). Ele gera os embeddings para cada chunk usando o modelo fornecido e os armazena na base de dados, salvando tudo no disco automaticamente.
  • if __name__ == "__main__":: Este bloco garante que a função build_and_save_vector_store() seja executada apenas quando o script for rodado diretamente (e não quando importado como um módulo em outro script).
  • (Comentários adicionais no código): Incluem opções para limpeza de arquivos temporários e a alternativa de usar MarkdownHeaderTextSplitter, que foi aprimorada durante a fase de refinamento da AVT.

Este script encapsula o processo de transformar conteúdo textual em uma base de conhecimento vetorial pronta para ser utilizada por um sistema de Busca Aumentada por Recuperação (RAG - Retrieval Augmented Generation), que é a base do funcionamento da Assistente Virtual.

Seção 7: Glossário Técnico Essencial do Projeto

Este glossário oferece um guia técnico simplificado para navegar na estrutura de arquivos e componentes do projeto web Takwara-Tech, hospedado no GitHub. Ele explica o propósito dos principais arquivos e diretórios, as tecnologias associadas e como eles se relacionam com as funcionalidades visíveis no site (especialmente a Tool Box Interativa). O objetivo é fornecer um "mapa" do esqueleto do projeto, facilitando a compreensão para ajustes e contribuições.

7.1. Introdução

Este documento oferece um guia técnico simplificado para navegar na estrutura de arquivos do projeto web Takwara-Tech, hospedado no GitHub. Ele explica o propósito dos principais arquivos e diretórios, as tecnologias associadas e como eles se relacionam com as funcionalidades visíveis no site (especialmente a Tool Box Interativa). O objetivo é fornecer um "mapa" do esqueleto do projeto, facilitando a compreensão para ajustes e contribuições.

7.2. Mapa do Projeto (Estrutura de Pastas Simplificada)

Ao abrir o projeto em um editor como o VS Code, você verá uma estrutura de pastas e arquivos similar a esta (focando nos mais relevantes que trabalhamos):

Takwara-Tech/
├── .env                  # Configuração: Chave da API do Google (localmente)
├── mkdocs.yml            # Configuração: Define a estrutura do site MkDocs, tema, menus, scripts, etc.
├── docs/                 # Conteúdo: Onde ficam seus arquivos Markdown (.md) e assets do frontend.
│   ├── Artigos/          # Seus artigos e documentação organizada em pastas.
│   │   └── ...todos os seus arquivos .md...
│   ├── assets/           # Assets do frontend (imagens, css, js).
│   │   ├── css/          # Arquivos CSS customizados (.css).
│   │   ├── images/       # Imagens do site (.png, .jpg, etc.).
│   │   └── js/           # Arquivos JavaScript customizados (.js).
│   │       ├── script.js       # Lógica JavaScript da AVT (frontend).
│   │       ├── calculadora.js    # Lógica JavaScript da Calculadora (frontend).
│   │       ├── graph.js          # Lógica JavaScript do Grafo (frontend, vis.js).
│   │       ├── toolbox.js        # Lógica JavaScript do Web Component da Tool Box.
│   │       └── ...outros arquivos js...
│   ├── index.md          # Conteúdo: Página inicial do site.
│   └── ...outros arquivos .md na raiz de docs...
├── overrides/            # Frontend: Customizações dos templates HTML do tema Material for MkDocs.
│   └── partials/         # Partes reutilizáveis de HTML.
│       ├── widget-chatbot.html     # Frontend: HTML da interface da AVT.
│       ├── widget-calculadora.html # Frontend: HTML da interface da Calculadora.
│       ├── widget-grafo.html       # Frontend: HTML da interface do Grafo.
│       ├── widget-tools.html       # Frontend: HTML que inclui as interfaces das ferramentas (AVT, Grafo, Calc) para a Tool Box.
│       ├── main.html             # Frontend: Template principal da página (inclui o template da Tool Box).
│       ├── header.html           # Frontend: Template do cabeçalho (botão abrir Tool Box?).
│       ├── footer.html           # Frontend: Template do rodapé (Climate Clock?).
│       └── ...outros arquivos html...
├── Chatbot - Takwara/    # Backend + Build: Pasta relacionada ao sistema da AVT.
│   ├── backend-api/      # Backend: Código da Google Cloud Function da API da AVT.
│   │   ├── main.py             # Backend: Código Python da API da AVT (Lógica RAG, Prompt, Retriever).
│   │   ├── requirements.txt    # Backend: Dependências Python da API.
│   │   └── chroma_db/          # Backend/Dados: Base de dados vetorial da AVT (gerada pelo script).
│   └── create_vector_store.py    # Build: Script Python para criar/atualizar a base de dados chroma_db.
├── requirements.txt      # Build: Dependências Python gerais do projeto (inclui mkdocs, langchains, etc.).
└── ...outros arquivos...

7.3. Glossário de Componentes Chave

Vamos detalhar os componentes principais, o que eles fazem e como você pode acessá-los para ajustes.

  • .env (Configuração Local)
    • O que é: Arquivo simples de texto para armazenar variáveis de ambiente sensíveis, como chaves de API, localmente.
    • Para que serve: Mantém segredos fora do código fonte versionado. O script create_vector_store.py lê este arquivo para obter a GOOGLE_API_KEY.
    • Ajustes aqui: Configurar sua GOOGLE_API_KEY="SUA_CHAVE".
  • mkdocs.yml (Configuração Central do Site)
    • O que é: O arquivo de configuração principal do MkDocs. Ele define a estrutura, o tema, o menu de navegação, quais arquivos JavaScript e CSS adicionais carregar, etc.
    • Para que serve: Controla a aparência e a estrutura GERAL do site estático.
    • Ajustes aqui:
      • site_name, repo_url, repo_name: Informações básicas do site.
      • theme: Configura o tema Material for MkDocs (cores, fontes, features). custom_dir: overrides indica que suas customizações de template estão na pasta overrides/.
      • nav: Crucial para a navegação! É uma lista que define o menu lateral do site e associa um texto de menu a um caminho de arquivo .md (ex: 'Início': 'index.md'). Quando você adiciona um novo arquivo Markdown (.md) em docs/, precisa adicioná-lo aqui para que apareça no menu.
      • markdown_extensions: Habilita funcionalidades extras no Markdown (títulos fixos, notas, etc.).
      • extra_css: Lista de arquivos CSS customizados a serem carregados no site.
      • extra_javascript: Lista de arquivos JavaScript customizados a serem carregados no site. Aqui você lista os scripts que dão vida às ferramentas (AVT, Calculadora, Grafo, Tool Box) e bibliotecas como vis.js e marked.js.
    • Como acessar: Use seu editor de texto para abrir mkdocs.yml na raiz do projeto.
  • .gitignore (Controle de Versão)
    • O que é: Arquivo de texto que lista arquivos e diretórios que o Git deve ignorar e não incluir no controle de versão.
    • Para que serve: Essencial para excluir arquivos temporários, de build, de configuração local (.env) e a base de dados binária (chroma_db) do repositório fonte, mantendo-o limpo e seguro.
    • Ajustes aqui: Garantir que as pastas de build (/site/), temporárias (/Chatbot - Takwara/temp_repo/) e a base de dados (/Chatbot - Takwara/backend-api/chroma_db/) estão listadas.
  • requirements.txt (Raiz do Repositório) (Dependências Python Gerais)
    • O que é: Lista de bibliotecas Python necessárias para rodar o projeto como um todo, incluindo MkDocs e as bibliotecas usadas localmente pelo script create_vector_store.py.
    • Para que serve: Permite instalar facilmente todas as dependências Python do ambiente de desenvolvimento/build local com pip install -r requirements.txt.
    • Ajustes aqui: Adicionar ou remover bibliotecas Python que não são exclusivas do backend da API, mas são usadas no processo de build ou pelo script local.
  • docs/ (Conteúdo do Site)
    • O que é: A pasta onde residem todos os seus arquivos Markdown (.md) que formam o conteúdo textual do site.
    • Para que serve: É a FONTE de todo o conhecimento e documentação do projeto que é exibido no site e que alimenta a base da AVT.
    • Ajustes aqui: Escrever, editar e organizar seus artigos e documentação em arquivos .md.
    • Como acessar: Navegue até a pasta docs/ no seu sistema de arquivos.
  • overrides/partials/ (Componentes HTML da Interface)
    • O que é: Uma pasta dentro de overrides/ que contém pequenos arquivos .html que representam "pedaços" da interface ou "widgets" (como a UI de cada ferramenta). Estes arquivos são incluídos em outros templates (widget-tools.html, main.html, etc.) usando a sintaxe {% include "partials/nome-do-arquivo.html" %}.
    • Para que serve: Permite reutilizar blocos de HTML e manter a estrutura da interface organizada.
    • widget-chatbot.html: Contém o HTML da interface visual da AVT: a caixa onde as mensagens aparecem (#chat-box), o campo de input (#user-input), o botão enviar (#chat-form .submit-button) e o botão Copiar Conversa (#copy-chat-button). Ajustes aqui afetam a aparência (estrutura HTML) da interface da AVT.
    • widget-calculadora.html: Contém o HTML da interface da Calculadora: o formulário com os selects e inputs (#calculator-form-widget) e as áreas onde os resultados e materiais são exibidos (#results-container-widget, #results-table-widget, #material-costs-widget, #footer-notes), e o botão Baixar Resultados (#download-results-button). Ajustes aqui afetam a aparência (estrutura HTML) da interface da Calculadora.
    • widget-grafo.html: Contém o HTML da interface do Grafo: um contêiner (#knowledge-graph) onde a biblioteca vis.js irá "desenhar" a visualização do grafo. Ajustes aqui afetam a área visual onde o Grafo aparece.
    • widget-tools.html: Contém a estrutura HTML da Tool Box em si. Ela define as seções para AVT, Grafo e Calculadora (<div class="tool-section" id="...">) e inclui os respectivos arquivos widget-*.html usando {% include ... %}. É este arquivo que o script toolbox.js carrega para dentro do Shadow DOM. Ajustes aqui afetam a estrutura geral da Tool Box e quais ferramentas aparecem nela.
    • main.html, header.html, footer.html: Templates principais do tema Material for MkDocs. Podem ser customizados para incluir os widgets da Tool Box, Painéis de Impacto, etc., usando a técnica de override de templates e incluindo os arquivos parciais. Ajustes aqui afetam a estrutura principal das páginas, cabeçalho e rodapé FORA do Shadow DOM da Tool Box.
    • Como acessar: Navegue até overrides/partials/ (e overrides/ para os principais) no seu sistema de arquivos. Use seu editor.
  • docs/assets/js/ (Lógica Frontend)
    • O que é: A pasta que contém os arquivos JavaScript que adicionam interatividade e lógica às ferramentas no frontend.
    • Para que serve: Controlam o COMPORTAMENTO das ferramentas no navegador (o que acontece quando você clica, digita, rola, etc.). São listados em mkdocs.yml (extra_javascript).
    • toolbox.js: O script que cria o Web Component <takwara-toolbox>. Ele define o Shadow DOM (<style> para o CSS interno) e anexa o HTML do widget-tools.html dentro dele. Crucialmente, ele dispara o evento takwara:tools-ready após renderizar o conteúdo. Ajustes aqui afetam o posicionamento e o layout GERAL da Tool Box lateral (fixo, altura, scroll, encavalamento) e o seu encapsulamento.
    • script.js: O script JavaScript que gerencia a interface da AVT. Ele "escuta" o evento takwara:tools-ready, busca os elementos da AVT (#chat-box, #chat-form, etc.) dentro do Shadow DOM, adiciona listeners de evento (ex: ao formulário para enviar a pergunta), chama a API backend e atualiza a UI do chat com as respostas (incluindo renderização Markdown com marked.js). Ajustes aqui afetam como a AVT se comporta no navegador, a comunicação com a API, e como as mensagens são exibidas.
    • calculadora.js: O script JavaScript que gerencia a interface da Calculadora. Similar ao script.js, escuta takwara:tools-ready, busca elementos no Shadow DOM, popula os selects (usando base de dados JS), adiciona listeners de evento ao formulário e ao botão de download, chama a API backend da calculadora e exibe os resultados. Ajustes aqui afetam o comportamento da Calculadora no navegador, a chamada da API e a exibição/download dos resultados.
    • graph.js: O script JavaScript que gerencia a visualização do Grafo. Escuta takwara:tools-ready, busca o contêiner #knowledge-graph no Shadow DOM, usa a biblioteca vis.js para desenhar o grafo (de dados JS ou API), configura a simulação física e a interatividade, e lida com a navegação ao clicar nos nós. Ajustes aqui afetam como o Grafo é desenhado e como você interage com ele.
    • Como acessar: Navegue até docs/assets/js/ no seu sistema de arquivos. Use seu editor.
  • Chatbot - Takwara/backend-api/ (Backend da API da AVT)
    • O que é: A pasta que contém o código Python da Google Cloud Function que atua como o "cérebro" da AVT.
    • Para que serve: É o ambiente onde a API backend roda. Contém o código principal (main.py), as dependências Python específicas do backend (requirements.txt) e a base de dados vetorial (chroma_db).
    • main.py: O código Python que roda na Google Cloud Function. Recebe as perguntas do frontend, carrega a base de conhecimento (chroma_db), usa modelos de IA (embeddings, LLM), encontra documentos relevantes (Retriever), usa o prompt template para formular a resposta e a devolve ao frontend. É aqui que reside a inteligência da AVT e a lógica de busca contextual.
    • requirements.txt: Lista de bibliotecas Python específicas necessárias para rodar o código da Google Cloud Function. É CRUCIAL que esta lista seja minimalista e contenha APENAS as bibliotecas usadas pelo código da API, para evitar conflitos no ambiente serverless.
    • chroma_db/: Uma pasta contendo arquivos binários que representam a base de dados vetorial da AVT. É a "memória" da AVT. Não edite esses arquivos diretamente! Esta pasta é gerada e atualizada apenas pelo script create_vector_store.py.
    • Como acessar: Navegue até Chatbot - Takwara/backend-api/ no seu sistema de arquivos. Use seu editor.
  • Chatbot - Takwara/create_vector_store.py (Build da Base de Conhecimento)
    • O que é: Um script Python que você executa localmente no seu terminal.
    • Para que serve: Ele lê os arquivos Markdown do seu repositório, processa o texto (divide em pedaços, cria embeddings usando a API do Google) e SALVA a base de dados vetorial chroma_db na pasta backend-api/. É essencial rodar este script SEMPRE que atualizar o conteúdo (.md) para que a AVT "aprenda" sobre as mudanças, antes de fazer o deploy do backend.
    • Ajustes aqui: Configurar qual repositório clonar, onde estão os arquivos de origem (docs), como dividir o texto (splitters, chunk_size, chunk_overlap, headers_to_split_on), e onde salvar a base de dados (PERSIST_DIRECTORY).
    • Como acessar: Navegue até Chatbot - Takwara/create_vector_store.py no seu sistema de arquivos. Use seu editor. Execute no terminal a partir da pasta Chatbot - Takwara.

7.4. O que Acontece no Site ao Mudar um Componente (Exemplos)

  • Mudar texto em docs/artigo.md: O texto da página naquele artigo muda quando você roda mkdocs gh-deploy. A AVT só saberá do novo texto após rodar create_vector_store.py, deployar o backend (main.py), e o MkDocs servir o site atualizado.
  • Adicionar entrada em mkdocs.yml (nav:): Um novo item aparece no menu lateral do site após mkdocs gh-deploy.
  • Mudar CSS em docs/assets/css/custom.css: Cores, fontes, espaçamentos do site (FORA da Tool Box) mudam após mkdocs gh-deploy.
  • Mudar CSS em <style> dentro de docs/assets/js/toolbox.js (ou em um arquivo .css incluído pelo Shadow DOM): Cores, fontes, espaçamentos DENTRO da Tool Box mudam após mkdocs gh-deploy.
  • Mudar HTML em overrides/partials/widget-chatbot.html: A estrutura visual da interface da AVT (onde estão os botões, caixas) muda dentro da Tool Box após mkdocs gh-deploy. (Lembre-se, este HTML é incluído pelo toolbox.js no Shadow DOM).
  • Mudar lógica em docs/assets/js/script.js: O comportamento da AVT no navegador (como ela envia a pergunta, como exibe a resposta, como funciona o botão copiar) muda após mkdocs gh-deploy. Se mudar a comunicação com a API, pode precisar de deploy do backend também.
  • Mudar lógica em Chatbot - Takwara/backend-api/main.py: Como a AVT pensa, busca e formula respostas (usando a base de dados e IA) muda após o deploy da Google Cloud Function. O frontend (script.js) continua chamando a API, mas a resposta vinda do "cérebro" é diferente.
  • Rodar create_vector_store.py: A base de dados chroma_db é atualizada ou recriada localmente. NADA MUDARÁ no site online ou na AVT até que você faça o deploy do backend com esta nova base de dados.

Email: fabiotakwara@gmail.com   |   Conteúdo sob Licença CC BY 4.0   |  

Leia mais sobre nos termos de licença.