AI-inovyo-assistende-db/docs/development.md

Desenvolvimento

Estrutura do Projeto

agente-bd/
├── code/                               # Código da aplicação
│   ├── app/
│   │   ├── api.py                      # FastAPI — endpoints REST
│   │   ├── front.py                    # Streamlit — interface web
│   │   └── backend/
│   │       ├── __init__.py             # Marca o diretório como pacote Python
│   │       ├── config.py               # Variáveis de ambiente
│   │       ├── dynamo.py               # DynamoDB, Langfuse, get_contexto
│   │       ├── tools.py                # ReportTools: get_variable_value, get_variables_list
│   │       ├── agent_bedrock.py        # LLM Bedrock, grafo LangGraph
│   │       └── orquestrador.py         # main() — ponto de entrada
│   ├── utils/
│   │   └── dynamodb_read_table.py      # Utilitários DynamoDB
│   ├── main.py                         # Entry point
│   ├── Dockerfile                      # Imagem Docker
│   ├── entrypoint.sh                   # Script de inicialização
│   └── requirements.txt                # Dependências Python
├── infra/                              # Infraestrutura como Código
│   ├── ecr/                            # Stack ECR
│   ├── ecs_alb/                        # Stack ECS + ALB
│   └── langfuse/                       # Stack Langfuse
├── docs/                               # Esta documentação
└── Makefile                            # Automação de build e deploy

Responsabilidades dos Módulos do Backend

config.py

Lê todas as variáveis de ambiente obrigatórias na carga do módulo e as exporta como constantes. Qualquer módulo que precise de configuração importa daqui.

dynamo.py

• Instancia o cliente dynamodb e o objeto langfuse na carga do módulo
• get_secret() — busca as credenciais do Langfuse no AWS Secrets Manager
• get_contexto(dashboard: str) -> dict — retorna contexto, filter e items_disponiveis para o dashboard informado

tools.py

Define a classe ReportTools com as ferramentas do agente:

• ReportTools(id_mapping) — instanciada por requisição; id_mapping converte IDs locais (id_1, id_2, …) para os IDs reais do DynamoDB
• get_variable_value(id, variable) — busca o valor de uma variável no DynamoDB
• get_variables_list(id) — lista as variáveis disponíveis para um ID
• as_tools() — retorna a lista de StructuredTool com nomes get_variable_value e get_variable_list

agent_bedrock.py

• AgentState — TypedDict com messages e current_step
• create_bedrock_llm(model_id, region, tools) — instancia ChatBedrockConverse e vincula as tools
• call_model(state, llm), call_tools(state, tools_map), should_continue(state) — nós e roteador do grafo LangGraph
• create_agent(inference_profile_arn, region, tools) — monta o tools_map e compila o StateGraph

orquestrador.py

Função main(user_query, history, model, base):

• Carrega contexto via get_contexto(base)
• Constrói id_mapping e local_items para isolar IDs reais do LLM
• Instancia ReportTools(id_mapping) e passa as tools ao agente
• Monta o system prompt com local_items no lugar dos IDs reais
• Cria e invoca o agente
• Retorna resposta e contagem de tokens

Cadeia de Imports

config.py
   ↑
dynamo.py        ←── config
   ↑
tools.py         ←── config, dynamo
   ↑
agent_bedrock.py ←── config
   ↑
orquestrador.py  ←── config, dynamo, agent_bedrock, tools
   ↑
api.py / front.py ←── orquestrador (via pacote backend)

Dependências Principais

Pacote	Uso
boto3	SDK AWS (DynamoDB, Secrets Manager)
langchain	Framework de orquestração LLM
langchain-aws	Integração LangChain + AWS Bedrock
langgraph	Framework de agentes baseado em grafos
streamlit	Interface web interativa
fastapi	Framework de API REST
uvicorn	Servidor ASGI
langfuse	Observabilidade e tracing de LLMs

Fluxo de Desenvolvimento

1. Fazer alterações — Editar os arquivos em code/app/
2. Testar localmente — Rodar FastAPI + Streamlit ou via Docker
3. Validar — Executar scripts de teste em scripts/
4. Build e deploy — Seguir o guia de deploy

Adicionando uma Nova Ferramenta ao Agente

Todas as ferramentas vivem na classe ReportTools em tools.py. Basta:

1. Adicionar o método à classe:

def minha_nova_tool(self, param: str) -> str:
    """Descrição da tool para o LLM."""
    real_id = self.id_mapping.get(param, param)  # se precisar resolver ID
    # implementação
    return resultado

2. Registrá-lo em as_tools():

def as_tools(self) -> list:
    return [
        ...,
        StructuredTool.from_function(
            self.minha_nova_tool,
            name="minha_nova_tool",
            description="Descrição da tool para o LLM.",
        ),
    ]

Não é necessário alterar agent_bedrock.py — o tools_map é construído dinamicamente a partir da lista retornada por as_tools().

Adicionando um Novo Modelo LLM

Em agent_bedrock.py, adicionar o novo modelo aos três dicionários em create_bedrock_llm():

• MODEL_ARNS — ARN do inference profile
• PROVIDER — provider (anthropic, meta, amazon)
• prefix — prefixo de rota (us ou global)

E adicionar o model ID à lista MODELS em front.py.