contextweaver

Captura la superficie de capacidades efectiva de un agente, confírmala y observa cambios semánticamente significativos antes del despliegue.

ContextWeaver está probando actualmente una hipótesis de producto deliberadamente estrecha: instantánea de capacidades + deriva semántica.

Dado un documento OpenAPI, una respuesta capturada de tools/list de MCP, o un catálogo nativo de ContextWeaver, el experimento D1 produce una instantánea normalizada determinista que puedes inspeccionar, verificar y comparar con un candidato posterior. No requiere una cuenta de modelo, una pasarela, un ejecutor de herramientas ni la Weaver Stack.

Estado: alfa, y específicamente un experimento de producto. La implementación funciona y está probada; la hipótesis de valor para el usuario aún no está demostrada. El proyecto está midiendo activamente si usuarios independientes mantienen este flujo de trabajo después de probarlo en proyectos reales.

Prueba el experimento de deriva de capacidades

Clona el repositorio e instala esa copia para que los ejemplos mantenidos y el código bajo evaluación coincidan garantizadamente:

git clone --depth 1 https://github.com/dgenio/contextweaver.git
cd contextweaver
python -m pip install .

Ejecuta el ejemplo OpenAPI mantenido:

python -m contextweaver.d1 snapshot examples/d1/openapi_before.json --source-type openapi --output ./cw-before.json
python -m contextweaver.d1 snapshot examples/d1/openapi_after.json --source-type openapi --output ./cw-after.json
python -m contextweaver.d1 inspect ./cw-after.json
python -m contextweaver.d1 verify ./cw-after.json
python -m contextweaver.d1 diff ./cw-before.json ./cw-after.json

El candidato de ejemplo intencionalmente:

• hace que customer_id sea obligatorio en la capacidad existente listInvoices;

• cambia su descripción;

• añade una nueva capacidad getInvoice.

La diferencia separa las adiciones/eliminaciones de capacidades de los cambios en una capacidad lógica existente e informa las rutas estructuradas que cambiaron. Los cambios de contrato se separan de los cambios solo de documentación. Los cambios que involucran campos como required, type o enum se marcan como potencialmente rupturistas para revisión.

Esa marca es intencionalmente conservadora: ContextWeaver no afirma ser un verificador completo de compatibilidad de JSON-Schema.

Recorrido completo: Experimento de deriva de capacidades.

Related MCP server: MCP Gateway

Úsalo en tu propia fuente

OpenAPI

python -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities.json
python -m contextweaver.d1 verify ./capabilities.json

Después de que la API cambie:

python -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities-candidate.json
python -m contextweaver.d1 diff ./capabilities.json ./capabilities-candidate.json

Herramientas MCP capturadas

Si ya tienes una respuesta de tools/list de MCP guardada como JSON:

python -m contextweaver.d1 snapshot ./tools-list.json \
  --source-type mcp \
  --output ./capabilities.json

Para MCP, D1 compara las herramientas por su nombre lógico ascendente, de modo que una edición del esquema de entrada aparezca como un cambio en la misma capacidad en lugar de un par eliminar/añadir sin explicación. El ID de enrutamiento histórico sensible al esquema se conserva por separado como normalized_id para inspección.

Capturar un servidor MCP en vivo es una operación separada. snapshot, inspect, diff y verify no ejecutan capacidades descubiertas.

Catálogo nativo de ContextWeaver

python -m contextweaver.d1 snapshot ./catalog.json \
  --source-type native \
  --output ./capabilities.json

Qué significa verify

verify comprueba el contrato de instantánea D1: estructura, orden determinista, unicidad de ID lógico y el resumen canónico de capacidades.

No es:

• aprobación de despliegue;

• certificación de seguridad;

• autenticación o autorización;

• una garantía de que una implementación de herramienta sea correcta;

• evaluación de calidad de enrutamiento;

• atestación de tiempo de ejecución en producción.

Cuándo no usar ContextWeaver D1

Una respuesta negativa es evidencia útil para este proyecto. No añadas ContextWeaver solo porque las instantáneas de capacidades suenen ordenadas.

Usa algo más simple cuando:

• el diff ordinario de Git, la revisión de configuración y las pruebas ya hacen obvios tus cambios de capacidades;

• tu superficie de herramientas/API es pequeña y rara vez cambia;

• la búsqueda de herramientas nativa del proveedor es el único problema que intentas resolver;

• necesitas un bucle de agente, ejecutor de herramientas, capa de IAM u orquestador de producción;

• mantener otro artefacto confirmado cuesta más que el problema de revisión/depuración que elimina.

Si pruebas D1 y concluyes que Git/pruebas son más baratos, ese es un resultado de producto válido — por favor, dilo.

Qué se está probando

El experimento de supervivencia actual plantea una pregunta más fuerte que si el código funciona:

¿Las instantáneas de capacidades y los informes de deriva semántica mejoran un proceso real de revisión/manual/riesgo lo suficiente como para que usuarios independientes los mantengan?

El proyecto distingue:

qualified exposure
  -> understood the problem
  -> chose to evaluate
  -> attempted setup
  -> reached first useful output
  -> used on a real project
  -> retained independently / removed

Las estrellas, bifurcaciones, descargas, una demostración exitosa y las integraciones creadas por el mantenedor no se tratan como adopción retenida.

La decisión de producto controladora se sigue en #758, y el control de calidad de distribución es #855. El primer éxito sin asistencia y la retención se siguen en #658 y la adopción genuina en #551.

¿Qué pasa con el enrutamiento, la compilación de contexto y la pasarela MCP?

ContextWeaver ya contiene una funcionalidad histórica sustancial de tiempo de ejecución. Ese código sigue existiendo y el comportamiento actualmente enviado debe seguir siendo veraz y seguro, pero la implementación existente no es evidencia de que el proyecto deba seguir expandiéndola.

Dos hipótesis más amplias son explícitamente basadas en evidencia:

• D2 — compilación de contexto acotada / consciente de fase: condicional. Debe mostrar valor consecuente más allá de los mecanismos nativos contemporáneos de proveedor/tiempo de ejecución.

• D3 — selección determinista personalizada de herramientas: una pista de falsificación. Debe superar la búsqueda de herramientas nativa del proveedor / carga diferida o una línea base de recuperación simple en algo que los usuarios objetivo realmente les importe.

Durante el experimento D1, el proyecto no está expandiendo la sofisticación de enrutamiento, la maquinaria de paquetes de tiempo de ejecución, las superficies de memoria/sesión, la amplitud de marcos, el alcance de la pasarela, los almacenes vectoriales o el enriquecimiento asistido por modelos sin un bloqueador externo concreto o un experimento de falsificación aprobado.

Si estás manteniendo una integración existente que usa esas superficies históricas, la documentación relevante sigue disponible:

• ¿Qué patrón histórico encaja?

• Firewall de contexto

• Arquitectura de la pasarela de contexto MCP

• Modelo de seguridad de la pasarela MCP

• Comparación / alternativas

• Mapa del ecosistema

Evidencia y afirmaciones

La implementación D1 respalda afirmaciones de ingeniería acotadas, como la construcción determinista de instantáneas bajo el contrato documentado de fuente/adaptador y la salida estructurada de diff semántico. Aún no respalda la afirmación más fuerte de que los usuarios necesitan o retienen el producto.

El titular histórico de reducción de tokens no se usa intencionalmente para vender D1. El trabajo actual de integridad de evidencia para esas afirmaciones de referencia más antiguas se sigue en #841.

Consulta Afirmaciones y evidencia para el registro de afirmaciones y Experimento de deriva de capacidades para el contrato y las limitaciones exactas de D1.

Estabilidad de la API de Python

D1 se expone intencionalmente a través de:

python -m contextweaver.d1 ...

en lugar de promoverse inmediatamente a la CLI histórica de nivel superior o a una gran API pública de Python nueva. Eso es deliberado. El experimento debe ganarse una superficie permanente mediante uso retenido real antes de que el proyecto asuma otra obligación de compatibilidad.

Parte de la Weaver Stack — opcionalmente

ContextWeaver se puede usar de forma independiente. No tiene dependencia dura de los proyectos hermanos de Weaver.

La Weaver Stack más amplia contiene experimentos/componentes adyacentes para planificación, límites de ejecución, salvaguardas, lecciones y evaluación. Ese ecosistema no es necesario para evaluar D1, y la coherencia de la Stack no es una razón para conservar una característica de ContextWeaver que no se justifica de forma independiente.

Consulta el Mapa del ecosistema solo si realmente necesitas esas responsabilidades adyacentes.

Instalación y compatibilidad

pip install contextweaver

Python 3.10–3.14 están cubiertos por la matriz de CI del repositorio.

Versión actual del paquete: 0.18.1

El repositorio es pre-1.0. Prefiere la última versión de parche compatible para correcciones de errores y seguridad, y consulta el registro de cambios antes de confiar en las API de tiempo de ejecución históricas.

Hoja de ruta actual

La hoja de ruta es intencionalmente una secuencia de decisiones de producto, no una cola de características.

Una ejecución de CI en verde no avanza esta hoja de ruta por sí sola.

Contribuciones

Las contribuciones más valiosas durante el experimento de supervivencia son estrechas y vinculadas a la evidencia:

• un bloqueador real de evaluador D1;

• un caso de diff semántico que actualmente sea engañoso o se pierda en silencio;

• corrección de normalización determinista;

• mantenimiento de seguridad/versiones para el comportamiento que el paquete aún envía;

• evidencia negativa que muestre que una alternativa más simple gana.

Por favor, no añadas un adaptador de marco, política de enrutamiento, backend de almacenamiento, fase de tiempo de ejecución o integración de ecosistema solo por completitud.

Consulta CONTRIBUTING.md y AGENTS.md para las convenciones de ingeniería del repositorio.

Seguridad

Consulta SECURITY.md para obtener orientación sobre versiones compatibles y notificación de vulnerabilidades. No incluyas credenciales, datos de clientes, esquemas propietarios o indicaciones privadas en informes públicos de adopción/evaluación.

Documentación

• Sitio de documentación

• Experimento de deriva de capacidades

• Afirmaciones y evidencia

• Guía del conductor diario — usuarios históricos/tiempo de ejecución

• Recetario — superficies enviadas más amplias

• Preguntas frecuentes

• Registro de cambios

Licencia

Apache-2.0. Consulta LICENSE.