TestGraph

Grafo de experiencias experimental y nativo de IA para una memoria compartida y verificable entre asistentes de IA.

Estado: sistema de investigación funcional previo al lanzamiento. La arquitectura y los flujos de trabajo MCP se han probado con múltiples clientes de IA, pero el proyecto aún no se presenta como un servicio o API de producción estable.

TestGraph almacena reseñas humanas y estructuras derivadas por IA como conocimiento de grafo perdurable, al tiempo que mantiene la evidencia, la procedencia y la ejecución verificable por el servidor separadas de las afirmaciones del modelo. Está diseñado para que distintos sistemas de IA puedan contribuir al mismo conocimiento y reutilizarlo sin necesidad de un esquema de dominio completo de antemano.

Objetivos del proyecto

1. Emergencia de esquema: Proporcionar experiencias desconocidas a varias IAs y obtener una estructura útil sin tener que diseñar las categorías previamente.

2. Desacuerdo controlado: Las clasificaciones conflictivas convergen mediante la evidencia, la confianza y las reglas del servidor, en lugar de ir cambiando de criterio.

3. Ejecución veraz: Los modelos no pueden afirmar que se produjo descubrimiento, enriquecimiento o reconciliación a menos que el servidor pueda verificarlo.

4. IA que llama a la API: TestGraph utiliza deliberadamente a la IA que realiza la llamada como su motor semántico y de descubrimiento. La IA debe aplicar sus capacidades disponibles de razonamiento, recuperación y herramientas a temas desconocidos, derivar estructuras y relaciones útiles, y conciliar evidencia sin esperar a que TestGraph le prescriba un formulario específico de dominio. TestGraph proporciona primitivas de grafo estables, persistencia y verificación en el servidor; la IA que realiza la llamada aporta la inteligencia abierta.

Estos objetivos son criterios de aceptación para la arquitectura y las pruebas de TestGraph, no solo orientación para clientes de IA individuales.

Related MCP server: Graph-Mem MCP

Modelo de vocabulario estándar

Las reseñas se almacenan contra valores estables de un subject_type_id, no mediante rutas de conceptos al estilo DNS. La entrada flexible se resuelve mediante tipos de sujeto canónicos y alias globalmente únicos; el caso, la puntuación, los posesivos y los plurales habituales se normalizan mecanicamente. Los tipos desconocidos pueden crearse como entradas provisionales tras una consulta al diccionario.

La clasificación es metadata separada. Por ejemplo, ferry belongs_to transportation mejora las búsquedas generales de transporte, pero nunca cambia el lugar donde se almacena una reseña de ferry. review es el tipo de registro, no un nodo de vocabulario. Los campos estructurados reutilizables tienen sus propios IDs y alias estables y pueden adjuntarse a múltiples tipos de sujeto.

La migración 0009_flat_standard_vocabulary descarta deliberadamente los datos antiguos de conceptos y reseñas de la v2, mientras conserva usuarios, estado del estado OAuth, credenciales de conectores y otros datos de autenticación.

Configuración local

1. Crea un entorno virtual de Python 3.11+.

2. Instale las dependencias:

pip install -r requirements.txt

3. Copie .env.example a .env y reemplace cada secreto provisional por uno privado.

4. Ejecute las migraciones:

alembic upgrade head

5. Siembre los esquemas y las entidades de demostración:

python -m scripts.seed

6. Inicie la aplicación:

python run.py

Abra http://127.0.0.1:8000 y http://127.0.0.1:8000/docs.

No reutilice credenciales de ejemplo o de desarrollo fuera de un entorno de desarrollo local. Los secretos, las claves de API, los códigos de conexión OAuth y los identificadores de propietario o nunca deben llegar al repositorio.

MCP y OAuth

TestGraph incluye una aplicación MCP de solo herramientas. La integración multimodelo actual se ejerce a través de /mcp-v2. Su conexión de producción usa OAuth 2.1 Authorization Code + PKCE. Una IA conectada recibe un token con alcance restringido y de duración limitada; no recibe el código de conexión, la clave de API ni el ID de propietario de TestGraph.

La superficie MCP incluye operaciones de búsqueda/recuperación/guardado de reseñas y las capacidades más recientes de grafo/reconciliación que usan los experimentos multimodelo. Tome como autoridad el esquema MCP desplegado, porque esta superficie experimental todavía está evolucionando.

Antes de un despliegue, configure un OAUTH_CONNECTION_CODE largo y aleatorio, establezca el OAUTH_OWNER_USER_ID apropiado y asegúrese de que los secretos de producción existan solo en el entorno de despliegue.

Importar las reseñas de recetas abiertas de UCI

Tras las migraciones y python -m scripts.seed, ejecute:

python -m scripts.import_uci_recipe_reviews --representative-reviews 100 --load

Esto descarga el conjunto de datos UCI (CC BY 4.0) y selecciona un review de cada una de sus 100 recetas. Escribe los registros convertidos en data/uci_recipe_reviews_100.json y los carga en la base de datos configurada. Volver a ejecutarlo es seguro: las IDs de origen estables evitan los duplicados.

En la procedencia se conservan el texto original de la reseña, la calificación 0-5 estrellas, la fecha, los votos, el ID del registro fuente, la licencia y la atribución. El importador interpreta las afirmaciones explícitas sobre sabor, claridad, tiempos, disponibilidad de ingredientes, dificultad, si merece la pena repetir y modificaciones. Cada interpretación conserva el extracto de apoyo extraído del texto original; cualquier cosa no soportada sigue siendo null.

Para cargar el paquete comprobado sin descargarlo ni regenerarlo:

python -m scripts.import_uci_recipe_reviews --load-bundle data/uci_recipe_reviews_100.json

Reseteo de datos de desarrollo

Existe una página protegida de reset en /development/reset. Se oculta y devuelve 404 a menos que se habilite explícitamente:

ENABLE_DEVELOPMENT_RESET=true

La página elimina permanentemente los datos de reseñas y knowledge graph v1/v2, pero conserva usuarios, esquemas y conexiones OAuth y credenciales de capacidades. Debe permanecer deshabilitada en una implementación pública de producción.

Pruebas

pytest -q

Un lanzamiento público no debería publicarse a menos que la suite de pruebas completa pase contra el commit de la versión publicada y la comprobación de preparación para el despliegue tenga éxito. Véase RELEASE_CHECKLIST.md.

Implementación en Railway

1. Envía el repositorio a GitHub.

2. Crea un proyecto de Railway desde el repositorio de GitHub.

3. Añade PostgreSQL.

4. Hacer referencia al DATABASE_URL del servicio de Postgres; no pegue como cadena simple una referencia de Railway sin resolver.

5. Configura las variables de producción, usando secretos aleatorios únicos:

ENVIRONMENT=production
APP_SECRET=<random secret>
DEVELOPMENT_API_KEY=<long random key; development/admin use only>
CLIENT_API_KEYS={}
OAUTH_OWNER_USER_ID=<owner UUID>
OAUTH_CONNECTION_CODE=<long random connection code>
PUBLIC_BASE_URL=https://<your-domain>
ALLOWED_HOSTS=["<your-domain>","<railway-domain>"]
CORS_ORIGINS=["https://<your-domain>"]
ENABLE_DEVELOPMENT_RESET=false

railway.json se configura con las migraciones previas al despliegue, el inicio de Uvicorn usando el $PORT de Railway y la comprobación de disponibilidad en /health/ready.

La aplicación convierte el postgresql:// de Railway al formulario postgresql+psycopg:// de SQLAlchemy porque el proyecto usa Psycopg 3. Un despliegue en producción que no pueda resolver PostgreSQL debería detenerse, en lugar de recurrir silenciosamente a SQLite.

Arquitectura implementada

• Capacidad utilizar la IA como motor abierto de semántica y descubrimiento, con el servidor como capa de verificación/persistencia

• ID de tipos de sujeto planos y estables

• Términos y alias canónicos

• Relaciones de tipo editables usadas para búsqueda y no como direcciones de almacenamiento

• Registro de esquemas versionado

• Validación Pydantic específica del dominio almacenada como JSON/JSONB

• Publicación en modo borrador con aprobación y versión explícitas

• Credenciales de cliente con alcance delimitado

• Política central de lectura

• Resolución canónica de sujetos y edición de borradores con comprobación de versiones

• OAuth 2.1 Authorization Code + PKCE, registro dinámico de clientes, rotación de tokens de actualización y tokens de acceso con ámbito

• Endpoint de MCP para acceso autenticado a IA

• Claves de idempotencia

• Procedencia, consentimiento, propiedad y visibilidad

• Alineación por pares revisor-lector y relevancia específica para el lector

• Auditoría y borrado físico (soft)

• IDs de solicitud, errores JSON consistentes, límites de tamaño de solicitud y endpoints listos para paginación

• Migraciones de Alembic

• SQLite para local; PostgreSQL en producción

• Reconciliación entre modelos y flujos de trabajo de deliberación/o evaluación registrados en el servidor

Reglas seguras de lectura y edición

• Las públicas devuelven experiencias que sean a la vez publicado y público.

• IDs exactos también pueden recuperar una experiencia publicada y sin listar.

• Los borradores y las experiencias privadas requieren una credencial de lectura adecuada.

• Las experiencias de solo agregado nunca se devuelven como reseñas individuales.

• Resolver los temas antes de editar o adjuntar conocimiento estructurado.

• Las comprobaciones de versión protegen la edición concurrente de borradores.

• Las credenciales de cliente opcionales deben utilizar secretos únicos y revocables en el nide los más bajos actuales.

Licencia

TestGraph está licenciado bajo la GNU Affero General Public License v3.0 (AGPL-3.0). Consulte LICENSE.

La AGPL permite el uso, la modificación y la redistribución sujeto a sus términos, incluidos sus requisitos de fuente de red para las versiones modificadas que se utilicen para prestar un servicio de red.

Si AGPL-3.0 no satisface sus necesidades, puede estar disponible licencia comercial o propietaria alternativa. Póngase en contacto con testgraph@21dle.co.uk para tratar un acuerdo de licencia aparte.

Los colaboradores deberían leer CONTRIBUTING.md. Las contribuciones se aceptan únicamente bajo condiciones que preserven la capacidad del proyecto para ofrecer licencias alternativas.

Antes de hacer el repositorio público

Lea RELEASE_CHECKLIST.md y SECURITY.md. En particular, complete la revisión del historial de secretos, confirme el límite de datos públicos, ejecute toda la suite de pruebas y verifique un despliegue limpio con el commit exacto de la versión.

Concordance: "«públicas»" not. But earlier "Las públicas devuelven experiencias que sean a la vez publicado y público." In source "published" and "public" code. We might preserve inline code markers: "que sean a la vez published y public." Since they are inline code. Need keep values exactly as code. So translate? Text inside code cannot translate. The instruction says keep text inside inline code (backticks). So preserve published, public, unlisted, aggregate_only. For translated text, perhaps "que estén publicado"? But code remains English. Better leave code values English in all contexts. In final output, must keep backticks and values. So revise list: "Las listas públicas devuelven solo experiencias que estén tanto published como public." That's fine. Also "exact IDs may also retrieve a published unlisted experience" -> "Los IDs exactos pueden acceder a una experiencia unlisted ya publicada." And "aggregate_only" experience.

Let's ensure use of published and public as code values. We cannot translate inside code. Good.

Now also "review of OAuth" perhaps "state" "OAuth state" not "estado". Use "estado de OAuth".

Need "metadatos" plural? We can refine.

Also "subject" usage: maybe "sujeto" across. Good.

Potential inconsistency: "ha sido probado" vs "han sido prob."

Now scan for any missing structure. "Working" section, headings etc.

Need final answer only. Let's clean translation.

But the instruction "Return only the translated text, with no wrapper and no code fence." This means final should not have triple backticks. We'll output plain.

Let's refine final to be accurate and natural.

Below final draft:

TestGraph

Grafo de experiencias experimental y nativo de IA para una memoria compartida y verificable entre asistentes de IA.

Estado: sistema de investigación funcional previo a la versión. La arquitectura y los flujos de trabajo de MCP han sido ejercitados con varios clientes de IA, pero el proyecto todavía no se presenta como un servicio o API de producción estable.

"TestGraph stores ... durable knowledge" ...

Maybe use "declare" "almacena" etc.

Let's think about "without requiring a complete domain schema in advance" -> "sin exigir de antemano un esquema de dominio completo."

Wait "complete domain schema" maybe "esquema de dominio" is okay.

"standard vocabulary model" could be "Modelo de vocabulario estándar." Fine.

Now "configuración local": We should use "Vaya https://..." etc.

Fine.

Let's produce final now, carefully with placeholders.

Need preserve "MCP and OAuth" "## MCP y OAuth".

Need no Roman.

Let's produce.# TestGraph

Grafo de experiencias experimental y nativo de IA, para una memoria compartida y verificable entre asistentes de IA.

Estado: sistema de investigación funcional previo al lanzamiento. La arquitectura y los flujos de trabajo de MCP se han ejercitado con múltiples clientes de IA, pero el proyecto no se presenta todavía como un servicio o API de producción estable.

TestGraph almacena reseñas humanas y estructura derivada por IA como conocimiento de grafo duradero, manteniendo la evidencia, la procedencia y la ejecución verificable por el servidor separadas de las afirmaciones del modelo. Está diseñado para que distintos sistemas de IA puedan contribuir al mismo conocimiento y reutilizarlo sin necesidad de un esquema completo de dominio predefinido.

Objetivos del proyecto

1. Emergencia de esquemas: Proporcionar a varias IA experiencias no familiares y obtener una estructura útil sin diseñar las categorías de antemano.

2. Desacuerdo controlado: Las clasificaciones en conflicto convergen mediante evidencia, confianza y reglas del servidor, en lugar de cambiar de opinión.

3. Ejecución veraz: Los modelos no pueden afirmar que se ha producido descubrimiento, enriquecimiento o conciliación a menos que el servidor pueda verificarlo.

4. Capacidad de la IA solicitante: TestGraph utiliza deliberadamente la IA que realiza la llamada como su motor semántico y de descubrimiento. La IA debe aplicar sus capacidades disponibles de razonamiento, recuperación y herramientas en asuntos desconocidos, derivar estructuras y relaciones útiles, y conciliar evidencia sin esperar a que TestGraph le dicte un formato específico del dominio. TestGraph proporciona primitivas de grafo estables, persistencia y verificación en el lado del servidor; la IA solicitante aporta la inteligencia de propósito abierto.

Estos objetivos son los criterios de aceptación para la arquitectura y las pruebas de TestGraph, no simplemente una orientación para clientes de IA individuales.

Modelo de vocabulario estándar

Las reseñas se almacenan con valores estables de identificación de tipo de sujeto (subject_type_id), no con rutas de conceptos al estilo DNS. La entrada flexible se resuelve mediante tipos de sujeto canónicos y alias únicos globales. Las mayúsculas, la puntuación, los posesivos y los plurales habituales se normalizan mecánicamente. Los tipos desconocidos pueden crearse como entradas provisionales después de una consulta al diccionario.

La clasificación es metadatos separados. Por ejemplo, ferry belongs_to transportation mejora las búsquedas amplias de transporte, pero nunca cambia el lugar donde se almacena una reseña del ferry. review es el tipo de campo, no un nodo de vocabulario. Los campos estructurados reutilizables tienen sus propios IDs y aliases estables y pueden asociarse a múltiples tipos de sujeto.

La migración 0009_flat_standard_vocabulary descarta deliberadamente los datos antiguos de conceptos y reseñas v2, pero conserva usuarios, estado de OAuth, credenciales de conectores y otros datos de autenticación.

Configuración local

1. Crea un entorno virtual de Python 3.11+.

2. Instala las dependencias:

pip install -r requirements.txt

3. Copia .env.example a .env y reemplaza cada marcador de secreto con un valor privado.

4. Ejecuta las migraciones:

alembic upgrade head

5. Carga los esquemas y las identidades de demostración:

python -m scripts.seed

6. Inicia la aplicación:

python run.py

Abre http://127.0.0.1:8000 y http://127.0.0.1:8000/docs.

No reutilices credenciales de ejemplo o desarrollo fuera de un entorno de desarrollo local. Los secretos, las claves de API, los códigos de conexión OAuth y los identificadores de propietario nunca deben enviarse al repositorio.

MCP y OAuth

TestGraph incluye una aplicación MCP que solo expone herramientas. La integración multiplataforma actual se practica a través de /mcp-v2. Su conexión de producción utiliza OAuth 2.1 Authorization Code + PKCE. Un asistente de IA conectado recibe un token de corta duración y de alcance limitado; no recibe el código de conexión, la API key ni el identificador de propietario de TestGraph.

La superficie MCP incluye las operaciones de búsqueda/recupación/guardado de reseñas y las nuevas capacidades de grafo/reconciliación usadas en los experiments multimodelo. Considera el esquema MCP implantado como fuente de verdad, porque esta superficie experimental aún está evolucionando.

Antes de cualquier despliegue, configura una cadena OAUTH_CONNECTION_CODE larga y aleatoria, fija el OAUTH_OWNER_USER_ID necesario y garantiza que los secretos de producción estén exclusivamente en el entorno de despliegue.

Importar el conjunto abierto de reseñas de recetas de UCI

Después de las migraciones y de python -m scripts.seed, ejecuta:

python -m scripts.import_uci_recipe_reviews --representative-reviews 100 --load

Esto descarga el dataset UCI con licencia CC BY 4.0 y selecciona una reseña con abundante evidencia de cada una de sus 100 recetas. Escribe las reseñas convertidas en data/uci_recipe_recipe_100.json y las carga en la base de datos configurada. Ejecutarlo de nuevo es seguro: los IDs de origen estables evitan duplicados.

El texto original de la reseña, la puntuación de 0-5 estrellas, la marca de tiempo, los votos, el identificador de registro original, la licencia y la atribución se conservan en la procedencia. El importador interpreta las afirmaciones explícitas sobre sabor, claridad, tiempo, disponibilidad de ingredientes, dificultad, merecer repetir y modificaciones. Cada interpretación conserva su frase de apoyo original; cualquier elemento sin respaldo se limita null.

Para cargar el conjunto verificado sin descargarlo ni regenerarlo:

python -m scripts.import_uci_recipe_reviews --load-bundle data/uci_recipe_reviews_100.json

Restablecer datos de desarrollo

Hay una página de restablecimiento protegida en /development/reset. Está oculta y devuelve 404 a menos que se habilite explícitamente:

ENABLE_DEVELOPMENT_RESET=true

La página elimina permanentemente los datos de reseñas y conocimiento v1/v2, pero conserva usuarios, esquemas, conexiones OAuth y credenciales auxiliares. Debe permanecer deshabilitada en una implementación pública de producción. La requiere para borrado de datos.

Pruebas

pytest -q

No hay que publicar una versión pública a menos que la suite de pruebas completa pase contra el commit de lanzamiento y la comprobación de preparación para el despliegue sea correcta. Ver RELEASE_CHECKLIST.md.

Despliegue en Railway

1. Empuja el repositorio a GitHub.

2. Crea un proyecto Railway desde el repositorio de GitHub.

3. Añade PostgreSQL.

4. Referencia DATABASE_URL del servicio Postgres; no pegues una referencia Railway sin resolver como una cadena de texto simple.

5. Configura las variables de producción, con contraseñas aleatorias únicas:

ENVIRONMENT=production
APP_SECRET=<random secret>
DEVELOPMENT_API_KEY=<long random key; development/admin use only>
CLIENT_API_KEYS={}
OAUTH_OWNER_USER_ID=<owner UUID>
OAUTH_CONNECTION_CODE=<long random connection code>
PUBLIC_BASE_URL=https://<your-domain>
ALLOWED_HOSTS=["<your-domain>","<railway-domain>"]
CORS_ORIGINS=["https://<your-domain>"]
ENABLE_DEVELOPMENT_RESET=false

railway.json configura las migraciones previas al despliegue, el arranque de Uvicorn con PORT de Railway y el chequeo de disponibilidad en /health/ready.

La aplicación convierte la URL postgresql:// de Railway a la sintaxis postgresql+psycopg:// de SQLAlchemy, porque el proyecto usa Psycopg 3. Un despliegue de producción que no pueda resolver PostgreSQL debería bloquearse en lugar de volver silenciosamente a SQLite.

Arquitectura implementada

• Motor de descubrimiento semántico y no semántico abierto como capacidad de IA llamante, con el servidor como capa de verificación/persistencia

• ID de tipo de sujeto planos y estables

• Conjuntos y alias canónicos

• Relaciones de tipo editables esenciales para la búsqueda, no para la dirección de almacenamiento

• Registro de esquemas versionado

• Validación de Pydantic dominio-específica almacenada como JSON/JSONB

• Publicación con borrador y aprobación/versión explícitas

• Credenciales de cliente con alcance

• Política central de lectura

• Resolución canónica de sujetos y edición de borradores con verificación de versión

• Código de autorización OAuth 2.1 + PKCE, registro dinámico del cliente, rotación de tokens de refresh y tokens de acceso con limitado

• Endpoint de MCP para acceso autenticado de IA

• Claves de idempotencia

• Procedencia, consentimiento, titularidad y visibilidad

• Alineación pairwise de revisor-lector y relevancia específica para el lector

• Registro de auditoría y eliminación suave

• Identificación de solicitud, errores JSON consistentes, límites de tamaño de petición y endpoints listos para paginación

• Migraciones de Alembic

• SQLite en local; PostgreSQL en producción

• Reconciliación entre modelos y workflow de reflexión/evaluación registrado en servidor

Reglas seguras de lectura y edición

• Las listas públicas devuelven solo experiencias publicado y public.

• Los IDs exactos pueden también recuperar una experiencia publicada y unlisted.

• Los borradores y las experiencias privadas requieren una credencial de lectura adecuada.

• Las experiencias aggregate_only nunca se devuelven como reseñas individuales.

• Resuelve los sujetos antes de editar o adjuntar conocimiento estructurado.

• Las comprobaciones de versión protegen la edición concurrente de borradores.

• La credenciales de cliente opcionales deben usar secretos únicos, revocables y con los mínimos ámbitos requeridos.

Licencia

TestGraph se distribuye bajo GNU Affero General Public License v3.0 (AGPL-3.0). Ver LICENSE.

La licencia AGPL permite usar, modificar y redistribuir el software según sus términos, incluidas las obligaciones de código fuente en red para versiones modificadas que se utilicen como servicio de red.

Si AGPL-3.0 no satisface sus requisitos, puede haber licencia comercial o propietaria alternativa. Contacta con testgraph-testgraph (email) para hablar sobre licencia separada.

Los colaboradores deberían leer CONTRIBUTING.md. Las contribuciones se aceptan únicamente con términos que mantengan la capacidad del proyecto para ofrecer licencias alternativas.

Antes de hacer público el repositorio

Lee RELEASE_CHECKLIST.md y SECURITY.md. En particular, completa la revisión del historial de secretos, confirma el límite de datos públicos, ejecuta la suite de pruebas completGXP, y verifica un despliegue limpio desde el commit exacto de emisión.