📝 docs(services): documentar responsabilidades internas do orquestrador

Adiciona comentarios objetivos nos servicos e componentes centrais para deixar explicitas as responsabilidades de integracao com LLM, estado conversacional, factories, registries e helpers de usuario.

A mudanca e apenas documental e segue a linha do projeto de explicar a arquitetura no proprio codigo sem alterar o comportamento em runtime.

app/services/ai/llm_service.py

@@ -10,6 +10,8 @@ from app.core.settings import settings
 from app.models.tool_model import ToolDefinition
 
 
+# Essa classe encapsula a integracao com o Vertex AI:
+# inicializacao, cache de modelos e serializacao das tools.
 class LLMService:
     _vertex_initialized = False
     _models: dict[str, GenerativeModel] = {}
@@ -83,6 +85,8 @@ class LLMService:
         response = None
         last_error = None
 
+        # Tenta o modelo configurado e cai para nomes alternativos
+        # quando o principal nao estiver disponivel no projeto/regiao.
         for model_name in self.model_names:
             try:
                 model = self._get_model(model_name)

app/services/orchestration/conversation_state_repository.py

@@ -1,6 +1,7 @@
 from abc import ABC, abstractmethod
 
 
+# Interface base para qualquer backend de estado conversacional.
 class ConversationStateRepository(ABC):
     @abstractmethod
     def upsert_user_context(self, user_id: int | None, ttl_minutes: int) -> None:

app/services/orchestration/conversation_state_store.py

@@ -3,6 +3,8 @@ from datetime import datetime, timedelta
 from app.services.orchestration.conversation_state_repository import ConversationStateRepository
 
 
+# Implementacao local em memoria do estado conversacional.
+# Serve como fallback simples para desenvolvimento e testes.
 class ConversationStateStore(ConversationStateRepository):
     def __init__(self) -> None:
         self.user_contexts: dict[int, dict] = {}

app/services/orchestration/orchestrator_config.py

@@ -1,3 +1,5 @@
+# Constantes compartilhadas do orquestrador:
+# TTLs, campos obrigatorios, respostas de baixo valor e tools especiais.
 USER_CONTEXT_TTL_MINUTES = 60
 PENDING_ORDER_SELECTION_TTL_MINUTES = 15
 

app/services/orchestration/prompt_builders.py

@@ -1,6 +1,7 @@
 from typing import Any
 
 
+# Builders centralizados dos prompts usados pelo orquestrador.
 def _build_user_context_line(user_id: int | None) -> str:
     return f"Contexto de usuario autenticado: user_id={user_id}.\n" if user_id else ""
 

app/services/orchestration/redis_state_repository.py

@@ -7,6 +7,7 @@ from redis import Redis
 from app.services.orchestration.conversation_state_repository import ConversationStateRepository
 
 
+# Implementacao persistida do estado conversacional usando Redis e TTL.
 class RedisConversationStateRepository(ConversationStateRepository):
     def __init__(
         self,

app/services/orchestration/state_repository_factory.py

@@ -6,6 +6,7 @@ from app.services.orchestration.conversation_state_store import ConversationStat
 _state_repository: ConversationStateRepository | None = None
 
 
+# Resolve e memoiza o backend de estado configurado para o processo atual.
 def get_conversation_state_repository() -> ConversationStateRepository:
     global _state_repository
     if _state_repository is not None:

app/services/orchestration/tool_executor.py

@@ -4,6 +4,7 @@ from app.services.orchestration.orchestrator_config import DETERMINISTIC_RESPONS
 from app.services.orchestration.response_formatter import fallback_format_tool_result
 
 
+# Camada fina para executar tools e padronizar o retorno de erros.
 class ToolExecutor:
     def __init__(self, registry):
         self.registry = registry

app/services/tools/tool_registry.py

@@ -31,6 +31,7 @@ HANDLERS: Dict[str, Callable] = {
 }
 
 
+# Registry em memoria das tools disponiveis para o orquestrador.
 class ToolRegistry:
 
     def __init__(self, db: Session, extra_handlers: Dict[str, Callable] | None = None):

app/services/user/mock_customer_service.py

@@ -4,6 +4,7 @@ from app.db.mock_database import SessionMockLocal
 from app.db.mock_models import Customer, User
 
 
+# Helpers para criar clientes ficticios deterministas a partir do CPF.
 MOCK_CUSTOMER_NAMES = [
     "Ana Souza",
     "Bruno Lima",

app/services/user/user_service.py

@@ -3,6 +3,7 @@ from sqlalchemy.orm import Session
 from app.repositories.user_repository import UserRepository
 
 
+# Servico simples de identidade por canal externo.
 class UserService:
     def __init__(self, db: Session):
         """Inicializa o servico de usuarios com repositorio persistente."""