halo-record

Trilhas de auditoria à prova de adulteração para agentes de IA — Runtime Records encadeados por hash, renderizados como um Runtime Report que seus clientes podem verificar por conta própria.

Cada ação que seu agente executa (chamadas de ferramentas, chamadas de modelo, acesso a dados, aprovações) torna-se um Runtime Record em um log somente-anexável, encadeado por hash; o Runtime Report é essa cadeia renderizada como uma página HTML autoverificável. Qualquer parte que detenha um checkpoint da cadeia pode verificar que os registros por trás dele nunca foram alterados, sem confiar em quem os produziu — esse checkpoint é a peça fundamental: a cadeia sozinha é à prova de adulteração contra todos, exceto a parte que opera o gravador (LIMITS.md §1). Quando a equipe de segurança de um cliente pergunta "o que seu agente fez com nossos dados?", você entrega um link em vez de um parágrafo. As revisões de segurança já fazem perguntas sobre IA ao lado do checklist SOC 2 — e, cada vez mais, essas perguntas vêm da ISO 42001, dos artigos de manutenção de registros do EU AI Act e dos próprios questionários dos clientes. Hoje, uma garantia por escrito ainda passa. A aposta por trás deste projeto é que isso não durará muito.

Destaque em Help Net Security (agosto de 2026).

O formato de registro é aberto e livre para implementar. Este pacote é a implementação de referência: gravador, verificador, cliente de testemunha e servidor de relatórios.

Usando o halo-record, ou pensando nisso? Diga quem você é e para quê → Quem está usando o halo-record?

Verifique você mesmo

Estão pedindo que você coloque um gravador dentro do seu agente. Você não deveria aceitar isso pela fé:

Zero dependências de runtime. Apenas biblioteca padrão. pip install halo-record instala exatamente um pacote.
Nenhuma chamada de rede, exceto três opcionais — ancoragem a uma testemunha (envia o id do sujeito, uma contagem de registros e duas impressões digitais da cadeia — o head e a raiz da cadeia), leitura dos checkpoints de uma testemunha de volta (envia o id do sujeito) e o timestamp RFC 3161 (envia apenas o hash de estado de um checkpoint para uma Timestamp Authority). Todas ficam desativadas a menos que você as invoque; o conteúdo dos registros nunca sai da sua infraestrutura.
Argumentos brutos de ferramentas são transformados em hash, com um resumo redigido ao lado. Os argumentos são armazenados como um hash canônico mais um resumo: o texto do argumento com padrões conhecidos de segredos e PII mascarados, limitado a 200 caracteres. Uma entrada curta que não corresponde a nenhum padrão aparece integralmente no resumo; o modo somente-hash (summaries=False) não mantém resumo algum. A redação é feita na melhor medida possível (regex sobre formatos comuns de segredos e PII, além de uma captura genérica por entropia): trate-a como defesa em profundidade, não como garantia. Campos de resultado que você fornece além de summary são selados como estão (LIMITS §13).
Pequeno o suficiente para auditar. ~5.300 linhas de Python (linhas de código, sem contar linhas em branco e comentários). Leia tudo em uma tarde.
Apache-2.0.
A documentação é de primeira classe. LIMITS.md (o que a cadeia não pode provar), PRIVACY.md (o que os registros contêm e o que sai da sua máquina), RETENTION.md (operar sob uma política de retenção) e REVIEWERS.md — a verificação independente em quatro comandos, além de um formato de citação para achados de revisão.

O que cada camada prova — a distinção fundamental neste projeto (LIMITS.md §1): uma cadeia que você mesmo detém prova que os registros não foram editados, em relação a um head que alguém já detém; apenas checkpoints mantidos fora do operador provam que nenhum foi removido; e nenhum hash prova que toda ação foi capturada.

Alegação	Cadeia própria	+ Checkpoints externos	+ Captura confiável
Detectar edições em um artefato estabelecido	✔	✔	✔
Detectar reescrita de histórico consolidado	—	✔	✔
Detectar checkpoints ausentes/atrasados	—	✔ (cadência acordada)	✔
Provar que toda ação foi registrada	—	—	depende do limite de captura

Veja um antes de instalar: um Runtime Report de exemplo — dados fictícios, cadeia real, e ele se reverifica no seu navegador enquanto você observa.

Demonstração de 60 segundos

Nenhum agente necessário. Com uv, nada para instalar:``` uvx --from halo-record halo demo --serve

ou da forma clássica:```
pip install halo-record
halo demo --serve

Qualquer um dos dois cria um fornecedor fictício de agente de suporte com dois clientes, testemunha as cadeias (com um arquivo de testemunha local representando uma fora do operador — consulte LIMITS.md §1), serve seus Runtime Reports com acesso restrito e abre o console do operador no seu navegador. Em seguida, experimente o teste de adulteração: exclua uma linha de um dos arquivos .jsonl e recarregue. O relatório detecta isso.

Registre seu próprio agente

Uma linha no limite:```python from halo_record import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") # wraps your entrypoint; records the run boundary to ./audit.jsonl — add record_call() or a framework adapter at each tool boundary to capture individual calls

Um shim de conveniência `from halo import ...` também é fornecido — mas o nome `halo` no PyPI pertence a um pacote de spinner de terminal não relacionado, e se esse pacote estiver instalado, ele vence a importação. `halo_record` é inequívoco, então os exemplos o utilizam.

Sem `log=`, os registros vão para `~/.halo/my-agent.jsonl` (uma cadeia por agente). O wrapper sela o limite da execução; a evidência vive nos registros por chamada. Capture-os com um adaptador de framework (matriz abaixo) — ou explicitamente, o que também mostra como a delegação se vincula:```python
from halo_record import Recorder, record_call

rec = Recorder("audit.jsonl")

with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call:            # one sealed record per tool call
    call.result = crm.lookup("acct-9")

with record_call(rec, "payments.refund", {"amount": 120},
                 parent_id=rec.last_record_id()) as call:                      # child links to the action that spawned it
    call.result = payments.refund(120)

Em seguida, renderize o relatório:``` halo report audit.jsonl -o report.html # one chain -> self-verifying HTML halo serve ./records --port 8721 # all tenants, gated per customer

O quickstart termina quando você está olhando o Runtime Report do seu próprio agente em um navegador. Se você obteve um arquivo JSONL e nenhum relatório, algo está errado: abra uma issue.

### O bloco de verificação

Se uma camada de guardrail ou de política verificou a ação, seu veredito pode acompanhar o registro — um bloco opcional que registra o que o gate decidiu, selado na cadeia de hash como qualquer outro campo:```python
from halo_record import build

halo-record v0.2.42