F1-03 - Matriz de Parity de Integraciones LangChain TS vs Python

May 9, 2026 · View on GitHub

Objetivo

Definir la parity operativa entre las integraciones LangChain de TypeScript y Python, mas alla de la parity del SDK core.

Esta matriz responde cuatro preguntas:

Que significa parity de integracion en este repositorio.
Que capacidades ya estan alineadas entre TS y Python.
Que gaps siguen abiertos en README, ejemplos y observabilidad.
Que calidad minima debe mantenerse para considerar ambas integraciones en parity sostenida.

Alcance de parity

La parity de integracion se define en cinco dimensiones:

Parity de API publica Ambas integraciones deben exponer factories, helpers de contexto y tools equivalentes aunque respeten modismos del lenguaje.
Parity de seguridad por defecto Las exposiciones sensibles deben ser opt-in y la validacion de destinos HTTP debe comportarse de forma equivalente.
Parity de observabilidad Ambas integraciones deben emitir eventos saneados, permitir fan-out de handlers y soportar logging estructurado sin exponer secretos.
Parity de ejemplos y operacion Cada integracion debe tener ejemplos base, ejemplos de observabilidad y una receta mas cercana a produccion.
Parity documental README, docs de diseno y ejemplos deben describir capacidades equivalentes y dejar claros los gaps restantes.

Referencias canonicas

TS package: integrations/langchain/
Python package: integrations/langchain-python/
Diseno Python: docs/F1-03-LangChain-Python-Integration-Design.md
Parity SDK core: docs/F2-01-TS-Python-Parity-Matrix.md

Matriz actual

Area	TypeScript	Python	Estado	Notas
Factory principal	`createAgentDidIntegration(...)`	`create_agent_did_langchain_integration(...)`	✅	Family parity mantenida.
Snapshot de identidad	`buildAgentDidIdentitySnapshot(...)`	`build_agent_did_identity_snapshot(...)`	✅	Campos equivalentes.
Inyeccion de contexto	`createAgentDidMiddleware(...)` + `buildAgentDidSystemPrompt(...)`	`compose_system_prompt(...)` + bundle method	✅	Diferente forma, mismo objetivo.
Tools basicas	identidad actual, resolve DID, verify signature	identidad actual, resolve DID, verify signature	✅	Parity funcional.
Tools sensibles opt-in	sign payload, sign HTTP, rotate key, history	sign payload, sign HTTP, rotate key, history	✅	Defaults endurecidos y alineados.
Seguridad HTTP	esquema valido, sin credenciales embebidas, bloqueo loopback/privado por defecto	esquema valido, sin credenciales embebidas, bloqueo loopback/privado por defecto	✅	TS alineado con Python.
Propagacion `http_security` al SDK	Validacion local en tool; no propaga opciones al SDK `signHttpRequest`	Propaga `HttpTargetValidationOptions` al SDK via `http_security` param cuando `allow_private_network_targets=True`	⚠️	Python adelanta a TS. TS debe propagar `httpSecurity` al SDK para parity completa.
Callback de observabilidad	`observabilityHandler`	`observability_handler`	✅	Eventos saneados en ambos paquetes.
Fan-out de handlers	`composeEventHandlers(...)`	`compose_event_handlers(...)`	✅	Vendor-neutral.
Logging JSON	`createJsonLoggerEventHandler(...)`	`create_json_logger_event_handler(...)`	✅	Misma estrategia de saneamiento.
Serializacion de eventos	`serializeObservabilityEvent(...)`	`serialize_observability_event(...)`	✅	Misma forma conceptual.
Ejemplo base	`agentDidLangChain.example.js`	`agent_did_langchain_example.py`	✅	Ambos muestran create_agent/createAgent + tools y aclaran que el quickstart local usa bootstrap del controller web-native; la publicacion hospedada de `did:webvh` queda como concern aparte de despliegue.
Ejemplo de observabilidad	`agentDidLangChain.observability.example.js`	`agent_did_langchain_observability_example.py`	✅	Parity operativa minima lograda.
Receta tipo produccion	`agentDidLangChain.productionRecipe.example.js`	`agent_did_langchain_production_recipe_example.py`	✅	Ambos usan guardas de entorno.
Demo integrado `did:wba`	`agentDidLangChain.didWbaDemo.example.js`	`agent_did_langchain_did_wba_demo.py`	✅	Ambos muestran runtime `did:wba`, partner remoto `did:wba`, `createAgent`/`create_agent` local y firma HTTP verificable sin credenciales externas. Los DID documents de demo declaran las claves de firma en `assertionMethod` para cumplir el binding de relaciones de verificacion del SDK.
Smoke cross-package `did:wba`	`npm run smoke:langchain-didwba` ejecuta el demo JavaScript publicado y valida su contrato JSON.	El mismo comando ejecuta el demo Python publicado y valida su contrato JSON en la misma corrida.	✅	Este smoke es gate de parity operativa entre ambos demos, no solo una conveniencia local.
Metadata de release candidate	`@agentdid/langchain@1.0.0-rc.1` y peer `@agentdid/sdk@1.0.0-rc.1`	`agent-did-langchain==1.0.0rc1` y `agent-did-sdk==1.0.0rc1`	✅	La parity de publicacion usa normalizacion nativa por ecosistema sin cambiar el contrato funcional entre TS y Python.
Integracion LangSmith dedicada	`createLangSmithRunTree(...)` + `createLangSmithEventHandler(...)`	Adapter dedicado disponible	✅	Ambos paquetes exponen adaptador dedicado sin cambiar la factory principal.
Profundidad de suite automatizada	tests funcionales, seguridad y observabilidad	tests funcionales, seguridad, observabilidad y modulos internos	⚠️	Python sigue mas granular.

Quality Gates para parity de integracion

TypeScript

npm --prefix integrations/langchain test
Ejemplos nuevos deben mantener guardas para no requerir credenciales accidentalmente.
Los eventos de observabilidad deben seguir saliendo saneados.

Python

python -m pytest integrations/langchain-python/tests -q
python -m ruff check integrations/langchain-python/src integrations/langchain-python/tests integrations/langchain-python/examples
python -m mypy integrations/langchain-python/src

Cross-integration

README de TS y Python deben describir el mismo modelo conceptual.
Los defaults de seguridad deben seguir alineados.
La taxonomia de eventos de observabilidad debe seguir equivalente.
Si se agrega un demo integrado relevante en una integracion, la otra debe ofrecer un demo equivalente o documentar explicitamente la divergencia.
Si cambia el contrato de salida o la ruta de ejecucion del demo integrado did:wba, el smoke cross-package y el walkthrough canonico deben actualizarse en el mismo cambio.

Estado actual

Logrado

Ya existe parity funcional de tools principales.
TS y Python comparten defaults de seguridad mas coherentes.
TS ya tiene observabilidad callback/logger saneada equivalente en intencion a Python.
TS ya tiene ejemplos adicionales para observabilidad y receta de produccion.
README y ejemplos de TS quedan alineados con la narrativa de Python.
TS y Python ya exponen demos integrados equivalentes para el flujo did:wba con resolucion web y firma HTTP verificable.
El repositorio ya tiene un smoke cross-package que ejecuta ambos demos y valida su contrato operativo compartido.

Gaps abiertos no bloqueantes

Python mantiene una modularizacion interna mas fina que TS.
La suite TS aun es menos granular que la suite Python.

Definicion de Done

La parity de integraciones LangChain TS vs Python se considera mantenida cuando:

Esta matriz sigue siendo correcta.
README y ejemplos de ambos paquetes describen capacidades equivalentes.
Los defaults de seguridad permanecen opt-in y alineados.
La observabilidad sigue saneando payloads, firmas, cuerpos HTTP y headers sensibles.
Nuevas capacidades de una integracion se portan a la otra o se documentan como excepcion explicita.

Changelog

Fecha	Cambio
2026-05-08	Se agrego una fila de parity para la metadata de release candidate: LangChain JS queda en `1.0.0-rc.1` con peer `@agentdid/sdk@1.0.0-rc.1`, mientras LangChain Python queda en `1.0.0rc1` con dependencia `agent-did-sdk==1.0.0rc1`. La divergencia de formato es solo normalizacion por ecosistema.
2026-05-08	README de LangChain JS refrescado para dejar explicito que el flujo local usa bootstrap del controller web-native y que la publicacion hospedada de `did:webvh` es un concern separado. La matriz mantiene parity con Python sobre ese modelo conceptual.
2026-05-04	Los demos integrados `did:wba` TS/Python ahora declaran `assertionMethod` en los DID documents usados para firma HTTP, manteniendo parity con el enforcement de key purpose binding del SDK.
2026-03-31	Rename del repositorio a `agent-did` y normalizacion de metadata publica para LangChain TS/Python: URLs de GitHub, referencias de instalacion y ejemplos activos alineados con `@agentdid/sdk` y `@agentdid/langchain`. Sin cambios en la API publica ni en la parity funcional.
2026-03-22	Se agregaron demos integrados `did:wba` equivalentes para LangChain TS y Python, junto con cobertura automatizada y referencias en README. La parity de ejemplos operativos se mantiene.
2026-03-22	Licencia del repositorio migrada de MIT a Apache-2.0. Actualizado `package.json` (langchain TS) y `pyproject.toml` (langchain-python). Sin cambios funcionales en la superficie de integración.
2026-03-22	Rename de scope npm: `@agent-did/langchain` → `@agentdid/langchain` y `@agent-did/sdk` → `@agentdid/sdk` para alinear con la organización npm `@agentdid`. Sin cambios en la API pública ni en la lógica funcional.