Modulo 4.5: Governanca Cognitiva na Pratica

🔌 Principio 1: API-First

Toda funcionalidade exposta via API documentada.

# Toda funcao de IA tem um endpoint correspondente
@router.post("/notebooks/{id}/chat")
async def chat(
    id: int,
    request: ChatRequest,
    db: Session = Depends(get_db)
) -> ChatResponse:
    """
    Endpoint documentado automaticamente no OpenAPI.
    A IA nunca e chamada diretamente pelo frontend.
    """
    return await chat_service.process(id, request)

# OpenAPI disponivel em /docs
# Schema exportavel para integracao externa

🎯 Principio 2: Backend Orquestra

O sistema controla o fluxo, a IA apenas executa.

class ChatOrchestrator:
    """O backend decide quando e como chamar a IA"""

    async def process(self, request: ChatRequest):
        # 1. Backend valida (SISTEMA decide)
        self.validate_request(request)

        # 2. Backend prepara contexto (SISTEMA monta)
        context = await self.build_context(request)

        # 3. Backend chama IA (IA executa)
        response = await self.gemini.generate(context)

        # 4. Backend processa resultado (SISTEMA valida)
        processed = self.post_process(response)

        # 5. Backend persiste (SISTEMA armazena)
        await self.save_interaction(request, processed)

        return processed

🔀 Principio 3: Duas Fases

IA gera estrutura, sistema materializa artefato.

Fase 1: IA Gera Estrutura

# IA retorna JSON estruturado
structure = await gemini.generate(
    f"Gere estrutura para {type}"
)

# Resultado:
{
    "type": "podcast",
    "segments": [
        {"speaker": "host", "text": "..."},
        {"speaker": "guest", "text": "..."}
    ]
}

Fase 2: Sistema Materializa

# Sistema gera o artefato final
def materialize_podcast(structure):
    audio_segments = []
    for seg in structure["segments"]:
        # Sistema usa TTS
        audio = tts_service.generate(
            text=seg["text"],
            voice=seg["speaker"]
        )
        audio_segments.append(audio)

    return concatenate(audio_segments)

💾 Principio 4: Persistencia Total

Todo input e output e armazenado para auditoria.

class InteractionLog(Base):
    __tablename__ = "interaction_logs"

    id = Column(Integer, primary_key=True)
    request_id = Column(String, unique=True, index=True)
    notebook_id = Column(Integer, ForeignKey("notebooks.id"))
    timestamp = Column(DateTime, default=datetime.utcnow)

    # Input completo
    prompt_sent = Column(Text)
    parameters = Column(JSON)

    # Output completo
    response_received = Column(Text)
    tokens_input = Column(Integer)
    tokens_output = Column(Integer)

    # Metadados
    model_used = Column(String)
    latency_ms = Column(Integer)
    cost_usd = Column(Float)

🔧 Principio 5: Modularidade

Componentes substituiveis sem afetar o sistema.

from abc import ABC, abstractmethod

class LLMProvider(ABC):
    """Interface abstrata - qualquer LLM implementa"""

    @abstractmethod
    async def generate(self, prompt: str) -> str:
        pass

class GeminiProvider(LLMProvider):
    async def generate(self, prompt: str) -> str:
        return await self.model.generate_content_async(prompt)

class OpenAIProvider(LLMProvider):
    async def generate(self, prompt: str) -> str:
        return await self.client.chat.completions.create(...)

# Injecao de dependencia
def get_llm_provider() -> LLMProvider:
    provider = settings.LLM_PROVIDER
    if provider == "gemini":
        return GeminiProvider()
    elif provider == "openai":
        return OpenAIProvider()

👤 Camada Humana

Configuracoes que definem limites e criterios de sucesso.

# config/governance.py - Decisoes HUMANAS

GOVERNANCE_CONFIG = {
    # Limites definidos por humanos
    "max_tokens_per_request": 30000,
    "max_cost_per_day_usd": 50.0,
    "allowed_personas": ["professional", "creative", "academic"],

    # Criterios de qualidade
    "min_response_quality_score": 0.7,
    "require_source_citation": True,

    # Restricoes de conteudo
    "blocked_topics": ["politica", "religiao"],
    "require_factual_basis": True,

    # A IA NAO pode alterar estas configuracoes
}

⚙️ Camada Sistema

Codigo que valida, controla fluxo e aplica regras.

class GovernanceValidator:
    """Sistema aplica regras definidas por humanos"""

    def validate_request(self, request: ChatRequest):
        # Valida contra configuracao
        if request.persona not in GOVERNANCE_CONFIG["allowed_personas"]:
            raise InvalidPersonaError()

        for topic in GOVERNANCE_CONFIG["blocked_topics"]:
            if topic in request.message.lower():
                raise BlockedTopicError(topic)

    def validate_response(self, response: str) -> bool:
        # Sistema verifica qualidade
        if GOVERNANCE_CONFIG["require_source_citation"]:
            if not self._has_citations(response):
                return False
        return True

🧠 Camada Cognitiva

A IA e uma funcao pura: recebe input, retorna output.

class CognitiveLayer:
    """IA como funcao pura - sem estado, sem decisoes de fluxo"""

    async def analyze(self, sources: List[Source]) -> Analysis:
        """Analisa fontes - retorna estrutura"""
        pass

    async def synthesize(self, context: Context) -> Synthesis:
        """Sintetiza informacao - retorna texto"""
        pass

    async def structure(self, content: str, format: str) -> Structure:
        """Estrutura conteudo - retorna JSON"""
        pass

    # A IA NAO:
    # - Decide o que fazer a seguir
    # - Acessa banco de dados
    # - Controla fluxo da aplicacao
    # - Persiste dados
    # - Valida regras de negocio

📝 Resumo do Modulo

✓5 Principios - Aplicados em codigo real

✓3 Camadas - Separacao clara de responsabilidades

✓Governanca - Humano define, sistema aplica

✓IA Controlada - Executa, nao decide

← Modulo Anterior Proximo Modulo →