Metadata-Version: 2.5
Name: hummand
Version: 0.4.0
Summary: SDK Python da Hummand: mandato a agente, ato delegado, servidor MCP de mandato e verificação offline do recibo humanproof/1.
Project-URL: Homepage, https://hummand.com.br
Project-URL: Documentation, https://hummand.com.br/docs
Author-email: Hummand <contato@hummand.com.br>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: humanproof-core>=0.8.1
Provides-Extra: dev
Requires-Dist: datamodel-code-generator[ruff]>=0.28; extra == 'dev'
Requires-Dist: fastapi>=0.115; extra == 'dev'
Requires-Dist: langgraph>=1.0; extra == 'dev'
Requires-Dist: mcp>=2.2; extra == 'dev'
Requires-Dist: mypy>=2.3.1; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.16.6; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=2.2; extra == 'mcp'
Description-Content-Type: text/markdown

# hummand

SDK Python da Hummand: mandato a agente, ato delegado, servidor MCP de mandato e verificação
offline do recibo `humanproof/1`.

**O sistema que executa a ação só executa com o recibo de que uma pessoa específica, viva e
presente, viu e autorizou; qualquer um verifica esse recibo sem confiar em ninguém.**

```bash
pip install hummand            # cliente e verificação
pip install "hummand[mcp]"     # mais o servidor MCP de mandato
```

Python 3.11 em diante. A criptografia do recibo vem do pacote `humanproof-core`, a mesma
implementação que assina no servidor e verifica no navegador.

## Estado

`disponível`, em produção: mandato a agente, ato delegado, servidor MCP de mandato e verificação
offline do recibo. `arquitetura-alvo`: os adaptadores para frameworks de agente.

## Duas metades

- **Verificação** (`verificar`, `problemas`, `Prova`): offline, sem rede, com o JWKS pinado por
  quem chama. É o que o **executor** roda antes de executar a ação. É esta metade que sustenta a
  frase acima.
- **Cliente** (`Hummand`): o que o agente usa para pedir a prova. Conveniência; a trava não está
  nele.

```python
from hummand import ProvaInvalida, verificar

JWKS = open("keys.json").read()  # pinado: baixado uma vez, versionado com o serviço

try:
    prova = verificar(recibo, jwks=JWKS, tipo="ato.delegado", tenant_id="tn_da_sua_empresa")
except ProvaInvalida as erro:
    recusar(erro.problemas)  # sem prova, não executa
```

## Mandato a agente

```python
from hummand import Hummand

with Hummand(api_key, jwks=JWKS) as h:
    pedido = h.mandato(
        sujeito="operador-1",
        mandatario="agente-conciliador",
        acoes=["conciliacao"],
        validade_ate="2026-12-31T23:59:59Z",
        limites={"valor_max": 5000},
    )
    entregar(pedido.url)  # a pessoa prova presença e aceita o escopo escrito

    prova = h.delegado(
        mandato_ref=pedido.ato_id,
        acao="conciliacao",
        sujeito="agente-conciliador",
        valores={"valor_max": 1200},
    )
```

Revogar a autoridade do agente em todos os sistemas que a exigem é um ato humano, e só outro a
devolve.

## Servidor MCP de mandato

Para o agente que fala MCP: `pedir_mandato`, `conferir_acao` (devolve `cabe` com o recibo
assinado, inclusive na recusa) e `estado_do_mandato`. Nenhuma ferramenta revoga.

**É um portão que avisa, não uma trava:** o agente pede autorização; o recurso só executa com
recibo. Um agente que não pergunta não é parado pelo servidor, e por isso toda resposta traz o
campo `garantia` dizendo isso.

```json
{
  "mcpServers": {
    "hummand-mandato": {
      "command": "hummand-mcp",
      "env": {
        "HUMMAND_API_KEY": "<chave restrita>",
        "HUMMAND_JWKS": "/caminho/keys.json",
        "HUMMAND_MANDATARIO": "agente-conciliador"
      }
    }
  }
}
```

A chave leva só `atos:create:mandato.agente`, `atos:create:ato.delegado` e `checks:read`; o painel
tem um atalho que a emite assim. O mandatário vem da configuração, não do agente. O link do
mandato vence em 10 minutos.

## Referências

- Especificação dos formatos, com vetores de teste: https://labs.hummand.com.br/especificacao
- Verificador no navegador: https://labs.hummand.com.br/verificar
- Chave pública: https://gateway.hummand.com.br/.well-known/humanproof/keys.json
- Contato: contato@hummand.com.br

Licença: Apache-2.0.
