Metadata-Version: 2.4
Name: pensenova-safety
Version: 0.1.0
Summary: Pensenova safety spine — auditable trust layer between an AI policy and a physical robot
Author: Pensenova
License: Proprietary — © Pensenova. All rights reserved.
Project-URL: Homepage, https://pensenova.com
Keywords: robotics,safety,humanoid,compliance,audit,certification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
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 :: Scientific/Engineering
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Provides-Extra: crypto
Requires-Dist: cryptography>=42; extra == "crypto"
Dynamic: license-file

# pensenova-safety

**A espinha de segurança da Pensenova** — uma camada de confiança auditável entre
a política de IA (não confiável) e o robô físico.

> A política propõe. A espinha dispõe — e prova.

## O que é

Uma política de IA (ACT, GR00T, difusão) é uma caixa-preta estatística: acerta na
maior parte do tempo, mas pode mandar um comando fora do limite, um `NaN`, um salto
brusco. Num robô que exerce força real, "quase sempre seguro" não basta.

A `pensenova-safety` fica entre a política e o robô. A cada comando ela:

1. **Contém** — nenhum comando fora do envelope de segurança do robô chega ao hardware.
2. **Vigia** — observa o comportamento ao longo do tempo; risco dispara resposta graduada.
3. **Registra** — cada decisão vai para um log imutável, encadeado e à prova de adulteração.
4. **Prova** — cada sessão gera um relatório de conformidade verificável.

É **agnóstica ao robô**: funciona com qualquer embodiment, do Unitree G1 a um cobô de
base fixa. O robô é descrito por um `SafetyProfile` — não há nada acoplado a um modelo
específico.

## Uso mínimo

```python
import numpy as np
import pensenova_safety as ps

# 1. descreva o robô (limites por junta)
prof = ps.SafetyProfile.from_limits(
    "meu_robo",
    joint_names=["j0", "j1", "j2"],
    lo=np.array([-1.0, -1.0, -1.0]),
    hi=np.array([ 1.0,  1.0,  1.0]),
    max_vel=np.array([2.0, 2.0, 2.0]),
)

# 2. abra uma sessão protegida
env = ps.protect(prof, operator="joao")

# 3. filtre cada comando da política
safe, report = env.filter(comando_da_politica, estado_atual, dt)
#    -> `safe` está garantidamente dentro do envelope
#    -> `report` diz o que foi feito (clamp, hold, e-stop)

# 4. encerre e obtenha a prova
env.stop()
prova = ps.build_report(env.logger.records, profile=prof)
```

Veja `examples/robo_generico.py` para uma demonstração completa com uma política hostil.

## Resposta graduada

| Nível | Efeito |
|---|---|
| **Observar** | risco leve: registra e acompanha, sem interferir |
| **Conter** | risco crescente: segura o robô, sem parar a sessão |
| **Interromper** | risco real: e-stop até liberação manual |

## Garantias

- **Determinismo** — o mesmo perfil gera sempre o mesmo hash, em qualquer máquina.
- **Rastreabilidade** — o log prende o hash do perfil; prova quais limites valiam.
- **Imutabilidade** — a cadeia detecta qualquer adulteração do histórico.
- **Núcleo puro** — apenas `numpy` + stdlib; sem hardware, sem simulador.

## Licença

Proprietário. Software confidencial da Pensenova. Ver `LICENSE`.
