Metadata-Version: 2.4
Name: hane-mcp-client
Version: 1.2.8
Summary: ~70% menos tokens em documentos PT-BR — extracao de entidades fiscal/juridico/ERP para Claude Code via MCP
Author-email: HaneIA Tecnologia <contato@haneia.com.br>
Maintainer-email: Jacion Silva <jacion.silva@haneia.com.br>
License: Proprietary
Project-URL: Homepage, https://github.com/JacionSilva/hane
Project-URL: Repository, https://github.com/JacionSilva/hane
Keywords: mcp,ner,nlp,hane,advpl,totvs,fiscal,juridico,claude
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: pypdf>=4.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# hane-mcp-client

[![PyPI](https://img.shields.io/pypi/v/hane-mcp-client.svg)](https://pypi.org/project/hane-mcp-client/)
[![Python](https://img.shields.io/pypi/pyversions/hane-mcp-client.svg)](https://pypi.org/project/hane-mcp-client/)

**Pare de gastar tokens enviando documentos inteiros para o LLM.**

`hane-mcp-client` conecta o Claude Code (ou qualquer cliente MCP) ao pipeline **HANE** — um extrator de entidades com compressão semântica hierárquica que entrega ao LLM apenas a informação estruturada de um documento, **sem chamar nenhum LLM internamente** e sem expor o conteúdo bruto.

Resultado típico: **~70% menos tokens** no prompt, em PT-BR, para contratos, notas fiscais, código ERP e documentos jurídicos.

> 🚀 **Experimente agora, sem instalar nem precisar de chave:** [demo ao vivo em haneia.com.br](https://haneia.com.br/demo-advpl.html) — cole um trecho e veja a compressão acontecer.

---

## O problema que ele resolve

No fluxo normal, para o Claude analisar um arquivo de 1.000 palavras ele precisa lê-lo para o contexto — e você paga por cada token, duas vezes (entrada do arquivo + reprocessamento):

```
Claude lê o arquivo    →  ~1.000 tokens no contexto
Claude reenvia o texto →  +1.000 tokens
Total: ~2.000 tokens por documento
```

Com o HANE, o arquivo é lido **no seu disco**, processado e o Claude recebe só as entidades comprimidas:

```
annotate_file_local("contrato.pdf")  →  1 linha
HANE extrai e comprime               →  ~80 tokens de entidades
Total: ~80 tokens  ·  o Claude nunca vê o documento bruto
```

**~25× menos tokens** no documento — e o conteúdo sensível não transita pelo modelo.

### Exemplo real

Entrada — seção **CALENDÁRIO** de um edital público (Programa Scale IA 2026 — Sebrae Startups + AKCIT/CEIA/UFG):

```
5. CALENDÁRIO. Período de inscrições do Programa Scale IA, com etapas em
São Paulo (Feira do Empreendedor 2026) e Florianópolis: 26/04/2026,
05/05/2026, 06/05/2026, 30/05/2026, 27/06/2026, 25/07/2026, 15/08/2026,
12/09/2026, 03/10/2026 e Demo Day de 19 a 22/10/2026.
```

Saída do HANE — domínio `juridico`, **−66% tokens**, sem chamar nenhum LLM:

```
[Data]         26/04/2026 | 05/05/2026 | 06/05/2026 | 30/05/2026 | 27/06/2026 |
               25/07/2026 | 15/08/2026 | 12/09/2026 | 03/10/2026
[Cidade]       São Paulo | Florianópolis
[Periodo]      Feira do Empreendedor 2026 | 19 a 22/10/2026
[ORGANIZACAO]  Programa Scale IA
```

É isso que o Claude recebe — só os fatos estruturados, não o documento inteiro. *(Run real do pipeline; a cobertura por entidade varia com o domínio e o `threshold`.)*

---

## Por que confiar nos números

Medições reais do pipeline HANE (não estimativas de marketing):

| Métrica | Valor | Contexto |
|---|---|---|
| Redução de tokens no prompt | **~70%** | média em lote de documentos |
| F1 de extração | **0.853** | 28 manuais técnicos TOTVS |
| Custo GPT-4o em lote | **$2.99 → $0.44** | mesmos 28 documentos, pós-compressão |
| Caso real (TJ-GO) | **−86% tokens** | 63 acórdãos, latência E2E mediana 147ms |
| Latência pós-otimização | **11,4× mais rápido** | 248s → 21s por documento |

Motor por trás do client: pipeline HANE de **6 camadas** (grafo semântico comprimido → NER hierárquico por ontologia → budget adaptativo por entropia → cache matricial de padrões → extração determinística por regex → grafo de memória de contexto entre turnos). Software registrado no **INPI (BR 51 2026 002247-9)**.

---

## Início rápido (3 passos)

**1. Instale**

```bash
pip install hane-mcp-client
# ou, sem instalar de forma permanente:
uvx hane-mcp-client
```

**2. Pegue sua API Key** em [haneia.com.br](https://haneia.com.br) — há plano de avaliação (trial).

**3. Configure o Claude Code** — adicione ao `~/.claude.json` (já apontando para a API oficial; basta colar sua chave):

```json
{
  "mcpServers": {
    "hane": {
      "command": "uvx",
      "args": ["hane-mcp-client"],
      "env": {
        "HANE_MODE": "rest",
        "HANE_API_URL": "https://haneia.com.br",
        "HANE_API_KEY": "COLE_SUA_API_KEY_AQUI"
      }
    }
  }
}
```

Reinicie o Claude Code e as ferramentas HANE ficam disponíveis no chat. Sem servidor para subir, sem modelo para baixar — a API oficial já está no ar.

> Requer Python 3.10+. Este pacote é só o **cliente** (a ponte MCP, ~15 kB): o modelo e o pipeline rodam no servidor HANE, o que mantém o client leve (apenas `fastmcp` + `pypdf`) e o motor protegido.

---

## Ferramentas disponíveis

| Ferramenta | O que faz |
|---|---|
| `annotate_file_local` | Lê um arquivo do disco (`.pdf`, `.docx`, `.txt`, `.prw`, `.py`…) e retorna só as entidades comprimidas. **O Claude nunca vê o conteúdo bruto.** |
| `extract_entities` | Extrai entidades de um texto colado no chat, por domínio. |
| `compare_documents` | Diff **semântico** entre duas versões de um documento — o que mudou de fato, não diferença de texto cru. |
| `estimate_tokens` | Estima a economia de tokens **antes** de processar (leve, sem GPU). |
| `get_status` | Estado do servidor HANE e configuração de privacidade. |
| `get_context_summary` | **(Camada 6 / CMG)** Grafo de contexto acumulado na sessão — entidades já estabelecidas, em formato compacto para o prompt. |
| `reset_context` | **(Camada 6 / CMG)** Reinicia o contexto da sessão (próxima extração começa do turno 1). |

> **Camada 6 — memória de contexto (CMG).** Além de comprimir cada documento, o HANE
> comprime **entre turnos** de uma sessão: em chamadas seguintes, envia ao LLM só o
> *delta* (entidades novas), não o histórico inteiro. Em modo REST, passe `session_id`
> no `extract_entities` e a resposta traz o bloco `cmg` com o delta; em modo MCP, use
> `get_context_summary` / `reset_context`. Economia inter-turnos típica: **73–78%**.

### Memória entre sessões no Claude Code (opcional)

Para que uma **nova conversa** do Claude Code **comece já com o contexto** das
anteriores (entidades técnicas do projeto), instale os hooks de sessão:

```bash
hane-mcp-client --install-hooks      # registra os hooks no ~/.claude/settings.json (com backup)
hane-mcp-client --uninstall-hooks    # remove
```

O que faz (100% local, sem servidor): a cada mensagem extrai entidades (~0ms, sem
modelo), mantém um grafo por projeto em `.cmg_graph.json`, e ao abrir uma nova
sessão injeta um resumo compacto (~180 tokens) do que já foi estabelecido.
Opt-in e reversível — o merge no `settings.json` preserva seus outros hooks.

Telemetria do que o CMG economizou entre janelas de conversa:

```bash
hane-mcp-client --cmg-stats    # turnos, tokens sem CMG vs com CMG, % economizado
```

### Domínios suportados em `extract_entities`

| Domínio | Ideal para |
|---|---|
| `fiscal` | NF-e, SPED, DANFE, ICMS, CFOP, NCM |
| `juridico` | contratos, cláusulas, partes, prazos, nº de processo |
| `erp` | Protheus / TOTVS, módulos, parâmetros `MV_` |
| `advpl` | código `.prw`/`.tlpp`, funções, tabelas `SA`/`SB` |
| `financeiro` | CNAB, remessa, retorno, débitos |
| `medico` | prontuários, CID, diagnósticos |
| `code` | Python, JavaScript, SQL e outras linguagens |
| `auto` | detecção automática de domínio |

---

## On-premise (sua infraestrutura, seus dados)

Para quem **não pode enviar documentos para fora** — órgãos públicos, jurídico, saúde, fiscal — o HANE roda **on-premise**, em container Docker na sua rede:

- Documentos **nunca saem da sua infraestrutura**
- Licença assinada (RSA-PSS), validação local
- Mesmas ferramentas, apontando o client para o seu servidor (`HANE_API_URL=http://seu-servidor:8000`)

A contratação on-premise é feita sob demanda — **[Falar com a equipe →](https://haneia.com.br/#contato)** (resposta em até 24h). Ou por e-mail: `contato@haneia.com.br`.

---

## Modos de operação e privacidade (LGPD)

Onde o seu texto trafega depende da combinação de modo e destino. Seja explícito sobre isso ao tratar dados pessoais:

| Cenário | Configuração | Onde o texto vai | Anonimização |
|---|---|---|---|
| **On-premise** | `rest` + `HANE_API_URL=http://seu-servidor` | Não sai da sua rede | Desnecessária |
| **SaaS oficial** | `rest` + `HANE_API_URL=https://haneia.com.br` | Servidor HaneIA, tratado conforme a [Política de Privacidade](https://haneia.com.br/privacidade.html) (LGPD) | Não atua no client |
| **MCP remoto** | `mcp` + `HANE_ANONYMIZE=true` | Servidor MCP remoto | **Mascara CPF e e-mail pessoal antes do envio** |

### Anonimização no client (`HANE_ANONYMIZE`)

Ativa **somente** com `HANE_MODE=mcp` — quando o texto trafega por um servidor MCP remoto que você não controla:

```json
"env": { "HANE_MODE": "mcp", "HANE_ANONYMIZE": "true" }
```

O que é mascarado **antes de o texto sair da sua máquina**, em conformidade com a Lei 13.709/2018 (LGPD):

| Dado | Regra | Vira |
|---|---|---|
| **CPF** | `\d{3}.\d{3}.\d{3}-\d{2}` | `[CPF]` |
| **E-mail pessoal** | domínios gmail / hotmail / outlook / yahoo / icloud / live | `[EMAIL]` |

- **CNPJ e razão social NÃO são mascarados** — identificam pessoa jurídica, que está fora do escopo da LGPD (Art. 5º, I). Os dados de empresa permanecem para a extração de entidades.
- O resultado inclui um contador `lgpd_anonimizacao: {cpf, email}` com o número de substituições feitas — auditável.
- `get_status` reporta `anonimizacao_ativa` e o escopo em vigor.

> Em `HANE_MODE=rest` a anonimização **não** roda: ou o texto fica na sua infraestrutura (on-premise) ou vai para a API oficial sob a Política de Privacidade da HaneIA. Para mascaramento client-side antes do envio, use `mcp` + `HANE_ANONYMIZE=true`.

### Variáveis de ambiente

| Variável | Padrão | Descrição |
|---|---|---|
| `HANE_MODE` | `rest` | `rest` ou `mcp` |
| `HANE_API_URL` | `http://localhost:8000` | URL base da REST API (oficial: `https://haneia.com.br`) |
| `HANE_MCP_URL` | `http://localhost:8081/mcp` | URL do servidor MCP remoto |
| `HANE_API_KEY` | — | Chave da REST API |
| `HANE_MCP_TOKEN` | — | Bearer token do MCP |
| `HANE_ANONYMIZE` | `false` | Anonimiza CPF/e-mail (só em `HANE_MODE=mcp`) |

---

## Sobre a HaneIA

HANE — *Hierarchical Adaptive NER Encoder*. Desenvolvido pela **HANEIA TECNOLOGIA E INOVAÇÃO LTDA**, focado em documentos brasileiros em português.

**[Falar com a equipe →](https://haneia.com.br/#contato)** · Site: [haneia.com.br](https://haneia.com.br) · E-mail: `contato@haneia.com.br` · Software registrado no INPI (BR 51 2026 002247-9)
