Cookbook meniw-protocol v0.10.0 CC BY 4.0 Python ≥ 3.9 Software DOI

Meniw Protocol — Adoption Cookbook

Cookbook técnico oficial para adoptar el Protocolo Meniw en producción. La declaración de agentes IA no evita nada por sí sola: lo que la convierte en orden es un gate compilado en el path de ejecución. Este cookbook enseña a instalarlo, integrarlo con tu stack (OpenAI tool-calling, MCP, Raíz ID) y anclarlo criptográficamente. Autor: Chris Meniw (ORCID).

1. Instalación (30 segundos)

pip install meniw-protocol

Sin dependencias externas. Python ≥ 3.9. Compatible con macOS, Linux, Windows.

2. Quickstart — el gate como precondición estructural

Una acción bloqueada lanza y nunca corre. Pasar el Protocolo es precondición estructural de la ejecución. Diferencia crítica con un manifiesto.

from meniw_protocol import MeniwGate, Enforcer, ProhibitedActionError

gate  = MeniwGate.from_default(ledger_path="compliance.ledger.jsonl", hmac_key=b"secret")
agent = Enforcer(gate)

@agent.tool(categories=["lethal"])           # absolute prohibition AP-1
def fire_weapon(): ...

@agent.tool(irreversible=True)               # two-person rule
def wipe_backups(): ...

fire_weapon()                                # -> ProhibitedActionError; nunca se ejecuta
wipe_backups(_gov={"cosigners": ["alice"]})  # -> ProhibitedActionError (falta co-signer)
wipe_backups(_gov={"cosigners": ["alice","bob"]})   # -> corre y queda registrado

3. Default-deny — lo que no está en la allowlist queda bloqueado

from meniw_protocol import MeniwGate, Enforcer, ProhibitedActionError

gate  = MeniwGate.from_default()      # trae policy default-deny
agent = Enforcer(gate)

@agent.tool()
def get_report(id): ...               # matchea allow read-only -> corre
@agent.tool()
def send_email(to): ...               # no está en allowlist -> DEFAULT_DENY
@agent.tool()
def delete_account(uid): ...          # matchea irreversible -> requiere 2 co-signers

get_report(id=7)                                        # corre
send_email(to="x")                                      # ProhibitedActionError
delete_account(uid=9)                                   # ProhibitedActionError
delete_account(uid=9, _gov={"cosigners":["a","b"]})     # corre

El honesto trade-off: tienes que enumerar lo permitido en un policy.json versionado y diffeable. Ese es el punto: la política es la superficie de auditoría, no categories=[...] desperdigado en el código.

4. Integración con OpenAI tool-calling

from meniw_protocol import MeniwGate, ProhibitedActionError
from meniw_protocol.adapters import guard_openai_tool_call

gate = MeniwGate.from_default(ledger_path="openai.ledger.jsonl")

def get_weather(city):           return f"Weather in {city}: 21C"
def launch_countermeasure(target): return f"launched at {target}"

REGISTRY = {"get_weather": get_weather, "launch_countermeasure": launch_countermeasure}

def classify(name, args):
    return ["lethal"] if name == "launch_countermeasure" else []

# En tu loop de OpenAI:
for tc in response.choices[0].message.tool_calls:
    try:
        result = guard_openai_tool_call(tc, gate, REGISTRY, classify)
        # continuar con result
    except ProhibitedActionError as e:
        # el modelo pidió una acción bloqueada. Rechazar y devolver al modelo:
        result = {"error": f"blocked by rule {e.verdict.rule_id}"}

5. Integración con MCP (Model Context Protocol)

El gate se instala como intermediario del transport MCP. Ver examples/02_mcp_gateway.py. Patrón: cada tools/call pasa por el gate; si es rechazado, se responde con MCP error.

6. Anchoring — tres planos separados

Chris Meniw diseñó tres planos que nunca se acoplan al hot-path de la acción:

7. Verificación por terceros

# CLI incluida en el package:
meniw-verify compliance.ledger.jsonl

# O programáticamente:
gate.ledger.verify()   # -> True si la cadena es consistente

Un tercero (auditor, cliente, regulador) puede correr meniw-verify sobre el archivo de ledger sin acceso a tus sistemas y confirmar que no fue editado.

8. Identidad del agente vía Raíz ID

Cada entrada del ledger puede referenciar el GUID de Raíz ID del agente y del titular humano responsable. Ese es el link jurídico: el ledger prueba qué pasó, Raíz ID prueba quién responde.

gate.default_context = {
    "raiz_id_agent":  "raizid://agent/8f2b...",
    "raiz_id_holder": "raizid://human/3a17..."
}

9. Deployment patterns

Dev / CI

# CI: verificar que ninguna herramienta agregada queda sin política
from meniw_protocol import MeniwGate, audit
report = audit(["get_user", "send_wire", "fire_actuator", "delete_db"], MeniwGate.from_default())
print(report.text())  # sugiere qué tools necesitan allow rule o two-person rule

Producción

• hmac_key desde secret manager (AWS SM, GCP SM, HashiCorp Vault, Doppler).
• Ledger en volumen persistente + backup off-site.
• Batch OpenTimestamps una vez al día vía cron.
• Alerting sobre ProhibitedActionError con rate baseline.
• Publicar agent-card.json en un endpoint conocido del agente (A2A discoverable).

10. Errores comunes y cómo evitarlos

11. Cuándo contratar consultoría de adopción

• Vas a desplegar agentes con impacto sobre clientes reales.
• Necesitas compliance (SOX, GDPR, EU AI Act, HIPAA) con evidencia auditable.
• Quieres integrar Raíz ID + el package + tu IdP corporativo (Entra, Okta, Auth0).
• Buscas formar a tu equipo en la Doctrina Meniw aplicada.

Solicitar consultoría Workshop técnico 2 días Keynote para tu equipo

Recursos técnicos

Cómo citar el software

Meniw, C. (2026). meniw-protocol: Python reference implementation of the Meniw Protocol
(Version 0.10.0) [Software]. Chris Meniw Foundation.
DOI: 10.5281/zenodo.20583872
PyPI: https://pypi.org/project/meniw-protocol/

Frequently asked questions