Context Packages¶

Finalidade e carregamento¶

Um Context Package é um bloco de conhecimento em Markdown, identificado por ID estável. Em vez de enviar toda a base a cada chamada, o sistema envia um catálogo descritivo e carrega somente o conteúdo solicitado. Isso reduz prompt desnecessário e separa regras do agente de conhecimento comercial/técnico versionado.

O Protocol KnowledgeBaseRepository, em src/core/knowledge_base/repository.py, expõe get_package(package_id) → str | None e list_packages() → list[str]. InMemoryKnowledgeBase descobre módulos de core.knowledge_base.packages, lê CONTENT: str e usa o nome do arquivo em maiúsculas como ID. Módulo sem CONTENT string gera kb_module_missing_content; catálogo carregado gera kb_loaded.

O runtime usa DynamicKnowledgeBase(fallback=InMemoryKnowledgeBase(), resources=...). Um recurso administrativo ativo substitui o conteúdo empacotado; inativo oculta o package; ausência de override usa fallback. Portanto o catálogo empacotado contém 15 packages, mas a lista efetiva pode variar conforme registros administrativos.

Catálogo empacotado completo¶

Todos os arquivos abaixo estão em src/core/knowledge_base/packages/. Todos os três agentes recebem o catálogo ativo e podem solicitar qualquer ID; não há matriz de permissão por agente. A coluna de fonte reproduz a origem declarada no módulo, sem afirmar atualização ou verificação externa nesta auditoria.

ID	Arquivo	Finalidade / momento de uso	Fonte declarada
`CLICKSIGN_PROCESS`	`clicksign_process.py`	Aceite formal de orçamento e assinatura; dúvida sobre processo	GG-Guia Orçamentos §3.1/§3.2
`COMPANY_INFO`	`company_info.py`	Institucional, frentes e contatos	Personas Jun/2026, portfólios geral/Agro, coleta GoSolos e termos You
`CUSTOM_DEVELOPMENT`	`custom_development.py`	Desenvolvimento sob medida, padronização e primers	Portfólio GoGenetic 2026, Agro 2025 e requisitos
`DELIVERY_TIMELINES`	`delivery_timelines.py`	Prazos de serviços, urgência e volume	GG-Guia Orçamentos §6 e requisitos por serviço
`GENOME_SIZES`	`genome_sizes.py`	Limites de genoma e tipo de entrega	GG-Requisitos por Serviço e guia de orçamentos
`GOGENETIC_YOU`	`gogenetic_you.py`	Serviços You, coleta, privacidade e limites de saúde	Termos de consentimento, catálogo eGestor e Personas
`GOSOLOS_PLATFORM`	`gosolos_platform.py`	Plataforma GoSolos, análises e aplicações	Portfólio Agro 2025, páginas 19–23
`GOSOLOS_SAMPLING`	`gosolos_sampling.py`	Coleta/envio de solo, kit e formulário	Guia Prático para Coleta e Envio das Amostras
`KITS_BS_DIAGNOSTICA`	`kits_bs_diagnostica.py`	Kits para laboratório do cliente e parceiro	GG-Guia Orçamentos §3.1 e requisitos qPCR
`PORTFOLIO_EXCLUSIONS`	`portfolio_exclusions.py`	Exclusões explícitas e alternativas	Guia de orçamentos e fontes indicadas no módulo
`PORTFOLIO_OVERVIEW`	`portfolio_overview.py`	Visão do portfólio e comparação entre frentes	Portfólios geral 2026, Agro 2025 e fontes de catálogo
`PRICING_RULES`	`pricing_rules.py`	Preços de referência, adicionais, descontos e orçamento	Catálogo eGestor `personalizadoProdutos` e guia de orçamentos
`PRIMERS_SANGER`	`primers_sanger.py`	Primers, fitas e regras para material do cliente	Guia de orçamentos §3.8 e requisitos Sanger
`SAMPLE_INSTRUCTIONS`	`sample_instructions.py`	Tipo, preparo, acondicionamento e envio de amostras	GG-Requisitos e Informações por Serviço; instrução Sanger GG-PC003#004
`TARGETS_QPCR`	`targets_qpcr.py`	Alvos/microrganismos disponíveis	Portfólio geral 2026 p.15 e portfólio Agro 2025

Digests de apoio ficam em docs/knowledge_source/, incluindo guia-orcamentos.md, catalogo-egestor-precos.md, gogenetic-you-lgpd.md e gosolos-coleta-solo.md. São origem editorial, não fontes consultadas por busca remota no turno. Valores e contatos não são republicados aqui como exemplos.

Descoberta e aliases¶

src/core/knowledge_base/discovery.py contém PACKAGE_DISCOVERY, descrições, palavras-chave e aliases explícitos. render_package_catalog() produz o catálogo compacto para os prompts. resolve_package_id(requested, available_ids) normaliza acentos, caixa e separadores e resolve ID/alias somente entre os IDs atualmente disponíveis.

Exemplos de aliases reais: PRECOS → PRICING_RULES, ALVOS_QPCR → TARGETS_QPCR, GOYOU → GOGENETIC_YOU, COLETA_SOLO → GOSOLOS_SAMPLING. Não há busca vetorial, similaridade semântica, download de PDF ou consulta a uma API externa nesse mecanismo.

`s=99` e orçamento por mensagem¶

{"s":99,"context_needed":"SAMPLE_INSTRUCTIONS"}

O dispatcher valida que context_needed é string não vazia, resolve o ID e lê o conteúdo. Ausência, ID desconhecido, package desativado ou conteúdo indisponível resultam em handoff por incerteza, sem pedir ao modelo para inventar a resposta.

O Orchestrator guarda o ID em Session.collected_packages sem duplicá-lo e incrementa context_enrichment_count. Na próxima chamada, busca novamente o conteúdo dos IDs salvos e os injeta no system prompt. Assim, uma alteração administrativa pode afetar conteúdo de um package já coletado numa chamada posterior: a sessão guarda IDs, não snapshot imutável dos textos.

MAX_CONTEXT_ENRICHMENTS_PER_MESSAGE tem default 2. O contador é resetado no início de cada inbound do bot. Após incrementar, se o valor ultrapassar o limite, faz handoff; com default 2, a terceira solicitação ultrapassa o orçamento. Solicitar novamente o mesmo ID não duplica collected_packages, mas ainda incrementa o contador. Além disso, o teto global de 10 iterações por turno impede ciclos mais amplos.

flowchart LR
    I[Inbound: reset contador] --> A[Agente]
    A -->|s=99| R[Resolver ID ativo]
    R -->|ausente| H[Handoff incerteza]
    R -->|presente| C[Salvar ID e incrementar contador]
    C -->|dentro do limite| A
    C -->|acima do limite| H
    A -->|resposta normal| F[Aplicar ação e responder]

Overrides, falhas e manutenção¶

Divergência documental

A docstring inicial de repository.py afirma “updates require a redeploy” e chama a implementação em memória de única do MVP. O factory atual compõe DynamicKnowledgeBase com overrides DynamoDB e permite alteração em runtime. Mudanças nos módulos Python ainda exigem atualização do código implantado; mudanças administrativas usam recursos versionados.

Para novo package empacotado: crie módulo com CONTENT, adicione metadados/aliases em discovery.py, teste ID/conteúdo e escolha do agente, registre fonte editorial e atualize esta tabela. Um novo package não cria por si só um serviço canônico. Para ajustes temporários de conhecimento, use o fluxo administrativo autorizado; não coloque credenciais, contatos pessoais de teste ou conteúdo de clientes no package.

tests/unit/integrations/test_knowledge_base.py verifica os 15 IDs, conteúdo não vazio, ordem e aliases; tests/unit/agents/test_invoker.py verifica injeção; tests/unit/application/test_action_mapping.py cobre desconhecidos; test_process_message_use_case.py cobre reinvocação e teto. A fixture TC-99-context-enrichment.json documenta replay de enriquecimento. Veja agentes, DynamoDB administrativo e modificação de agente.