Arquitetura

As notas entram por um observador e uma fila de tarefas; as perguntas voltam como citações com intervalos de linhas. Cada caixa nomeia o arquivo que a implementa.

real: sempre faz parte do sistema opcional: precisa de um modelo de linguagem seta tracejada: lê ou grava no banco de dados

Em uma tela estreita, leia a tabela de cada parte em vez dos desenhos.

Os dois fluxos

arquitetura do knowman, os fluxos de ingestão e consulta INGESTÃOCONSULTAENTRADAS Postgres + pgvectorstore.py é o único módulo que fala SQL: trechos (coluna embedding, índice HNSW), tarefas, execuções de eval, rastros tarefaslê tarefastrechos + vetores k mais próximos nada dentro da distância pergunta Notas (.md)pasta CORPUS_PATHREAL Observadorwatcher.pyeventos do watchfilesREAL Fila de tarefasstore.pyingest / deleteREAL Processadorworker.pypega tarefasREAL Fragmentadorchunking.pyingest.pyREAL Embeddingsembeddings/ollama.pyOllamaREAL Embed consultaretrieval.pyembeddings/ollama.pyREAL Trechos próximosstore.pyHNSW, cosineREAL Filtro de distânciaretrieval.pymáx. padrão 0.5REAL Citaçõesretrieval.pypath:Lstart-LendREAL Resposta do LLMask.pyllm/*.pyOPCIONAL Avaliaçãoeval.pydataset.jsonREAL Sem evidência"No evidence foundfor that query."REAL Agenteagent.pyknowman writeOPCIONAL CLIcli.pyknowman ...REAL API HTTPapi.py/search, /ask, /evalREAL Servidor MCPmcp_server.pysearch, ask (stdio)REAL Paineldashboard.pyGET /dashboardREAL

Recuperação, citações e avaliação precisam apenas de Postgres e do Ollama para os embeddings. Um modelo de linguagem acrescenta a resposta escrita em ask. Roda com Docker Compose ou de forma nativa com unidades systemd; a GPU é usada por Vulkan quando existe /dev/dri e nunca é obrigatória. As mensagens do programa, como No evidence found for that query., ficam em inglês porque são a saída literal. Fonte: core/README.md, core/docs/running.md.

Os componentes por trás deles

O mesmo sistema, agrupado por camada. Leia de cima para baixo: cada camada chama a de baixo, e a última linha é usada por todas. Cada caixa é um arquivo ou um pacote em core/src/knowman/.

componentes do knowman por camadaPontos de entrada: CLI, API HTTP, servidor MCP, painel. Serviços: observador, processador, agente opcional. Casos de uso: ingestão, resposta, avaliação. Núcleo: fragmentação, recuperação, formatação. Adaptadores: embeddings, provedores de modelos de linguagem, prompts. Armazenamento: módulo store sobre Postgres com pgvector. Comum: configuração, controle de acesso, registro. As setas vão de uma camada para a camada da qual ela depende. ENTRADA SERVIÇOS CASOS DE USO NÚCLEO ADAPTADORES ARMAZÉM COMUM CLIcli.pyknowman search, ask, ingestREAL API HTTPapi.py/search, /ask, /eval, /indexREAL Servidor MCPmcp_server.pysearch e ask por stdioREAL Paineldashboard.pyGET /dashboardREAL Observadorwatcher.pyeventos do watchfiles viram tarefasREAL Processadorworker.pypega uma tarefa por vezREAL Agenteagent.py, LangGraphknowman write: busca e depois escreveOPCIONAL Ingestãoingest.pyarquivo em trechos, vetores e linhasREAL Respostaask.pytexto escrito a partir das citaçõesOPCIONAL Avaliaçãoeval.pydataset pontuado contra a recuperaçãoREAL Fragmentaçãochunking.pycorta em linhas vazias, mantém linhasREAL Recuperaçãoretrieval.pyembed, k mais próximos, filtro, citaçãoREAL Formataçãoformatting.pypath:L5-L6, ou o negativo explícitoREAL Embeddingsembeddings/base.py, ollama.pyum vetor por trecho, o mesmo modeloREAL Modelos de linguagemllm/base.py + ollama, claude,openai, grokOPCIONAL Promptsprompts/ask_v1.txtPROMPT_VERSION escolhe o arquivoOPCIONAL Armazémstore.py: o único módulo que fala SQLPostgres + pgvector: trechos (coluna embedding, índice HNSW cosine), tarefas, execuções de eval, rastrosREAL Configuraçãoconfig.pyum único Settings do ambiente e do .envREAL Controle de acessoaccess.pytoken e limite de taxa, desligadosREAL Registrologging_setup.pyum registro JSON por linhaREAL

A seta da esquerda vai da camada que chama para a camada da qual ela depende. Configuração, controle de acesso e registro ficam no fim porque todas as camadas acima os leem. Fonte: core/src/knowman/, core/README.md, core/docs/running.md.

Cada parte

Os nomes da coluna Parte estão traduzidos. Os nomes da coluna Código são os arquivos e as configurações reais.

ParteCódigoEstadoO que faz
Notas (.md)pasta CORPUS_PATHrealSua pasta Markdown. A indexação nunca a modifica; só o agente escreve nela.
Observadorwatcher.pyrealTransforma cada arquivo .md adicionado, editado ou apagado em uma tarefa.
Fila de tarefasstore.pyrealAs tarefas são linhas no Postgres: ingest_path e delete_path, com estado pending, processing, done ou failed.
Processadorworker.pyrealPega uma tarefa por vez e a executa; uma tarefa que falha fica registrada, não é repetida em silêncio.
Fragmentadorchunking.py, ingest.pyrealCorta em linhas vazias mantendo o intervalo de linhas de cada trecho; ingest.py calcula os embeddings e guarda os trechos.
Embeddingsembeddings/base.py, embeddings/ollama.pyrealO Ollama transforma cada trecho em um vetor (modelo em EMBEDDINGS_MODEL). Uma interface, uma implementação.
Postgres + pgvectorstore.pyrealGuarda trechos, tarefas, execuções de eval e rastros. Índice HNSW cosine na coluna embedding.
Embed consultaretrieval.pyrealTransforma a pergunta em um vetor com o mesmo modelo.
Trechos próximosstore.pyrealDevolve os k trechos mais próximos (k padrão vem de RETRIEVAL_DEFAULT_K).
Filtro de distânciaretrieval.pyrealDescarta os trechos mais distantes que RETRIEVAL_MAX_DISTANCE. Um resultado vazio é o negativo explícito.
Citaçõesretrieval.pyrealCada citação carrega caminho, linha inicial, linha final, texto e distância.
Formataçãoformatting.pyrealEscreve uma citação como path:Lstart-Lend mais o trecho, e um resultado vazio como "No evidence found for that query."
Resposta do LLMask.py, llm/*.pyopcionalSó quando LLM_PROVIDER está definido (Ollama, Claude, OpenAI ou Grok) e há evidência. search e eval nunca precisam dele.
Promptsprompts/ask_v1.txtopcionalO template com que a resposta é escrita; PROMPT_VERSION escolhe o arquivo, então um texto novo é um arquivo novo, não uma mudança de código.
Avaliaçãoeval.py, evaldata/dataset.jsonrealPontua um dataset rotulado contra a recuperação; nenhum modelo julga outro modelo.
Agenteagent.pyopcionalknowman write: um agente LangGraph sobre Ollama que pode buscar nas notas e escrever uma nova.
CLIcli.pyrealdb-init, ingest, search, ask, eval, worker, watch, mcp, write.
API HTTPapi.pyrealSearch, ask, eval, tarefas de indexação, status; API_TOKEN e limite de taxa opcionais.
Controle de acessoaccess.pyrealA checagem do token e o contador de requisições por minuto por trás dessas duas opções. Ambas ficam desligadas se não forem definidas, e nenhuma sabe o que search ou ask fazem.
Servidor MCPmcp_server.pyrealDuas ferramentas somente leitura por stdio: search e ask.
Paineldashboard.pyrealUma página em /dashboard: índice contra disco, fila de tarefas, última avaliação, atividade recente.
Configuraçãoconfig.pyrealUm único objeto Settings lido do ambiente e do .env; cada módulo pede a ele em vez de interpretar variáveis.
Registrologging_setup.pyrealLogs JSON no stdout, um registro por linha, para que os contêineres e as unidades systemd registrem o mesmo formato.