OpenContracts : un graphe de citations documentaire, auto-hébergé et exposé par API

Un dépôt de documents qui devient un graphe de citations

Le problème visé est précis. Une organisation dispose de documents qui se citent les uns les autres : un contrat renvoie à une clause, un dépôt SEC renvoie à une section du Delaware General Corporation Law. Ces liens restent dans le texte, illisibles à l'échelle. Le README décrit le résultat attendu comme un programmable citation graph, où chaque citation détectée devient une arête entre deux nœuds. Le public visé est nommé sans détour : builders and hackers, donc des équipes techniques prêtes à écrire du code au-dessus de l'API plutôt qu'à consommer une interface figée. Le cas d'usage montré dans la documentation est celui de 36 dépôts SEC reliés au Delaware General Corporation Law, au Securities Act et aux règles SEC qu'ils invoquent. Un point de conception mérite d'être relevé : une loi citée mais absente de la bibliothèque n'est pas ignorée. Elle est conservée comme nœud en pointillés et suivie dans un backlog jusqu'à son ingestion. C'est un choix qui garde la trace d'un manque au lieu de le masquer, ce qui est plus utile pour un audit que pour une démonstration.

Trois surfaces sur le même graphe

L'architecture repose sur une idée simple : le graphe est la source, les interfaces sont des vues. Le README annonce same graph, three surfaces, à savoir une API GraphQL et REST pour les applications, un serveur MCP pour les agents, et une interface React pour l'équipe. Les trois passent par le même modèle de données, ce qui évite la divergence classique entre ce que voit l'utilisateur et ce que voit le programme. La documentation précise que tout ce que l'interface expose est également accessible via l'API et le serveur MCP. Concrètement, cela signifie qu'une annotation créée dans le navigateur est lisible par un agent, et qu'un agent peut, s'il y est autorisé, proposer ses propres annotations. La partie extraction s'appuie sur Celery : un fieldset, décrit comme un ensemble de colonnes où chaque colonne est une requête en langage naturel, est exécuté sur tout un corpus. Les résultats arrivent dans une grille de type tableur, avec approbation ou rejet humain cellule par cellule. Le fan-out sur les workers Celery explique pourquoi l'outil est présenté comme conçu pour des volumes importants.

Ce qu'il faut pour démarrer

Le README ne donne pas de procédure d'installation détaillée, seulement des points d'entrée. On y trouve le dépôt de démonstration à l'adresse contracts.opensource.legal et la page du projet sur open-source-legal.github.io/OpenContracts/. Les surfaces d'API sont documentées par leurs chemins : /mcp/ pour les corpus publics en accès anonyme, /mcp/me/ pour l'accès authentifié. La découverte se fait via /llms.txt et /.well-known/mcp.json. Les outils MCP listés sont search_corpus, list_documents, get_document_text, list_annotations, list_relationships, list_threads et create_thread_message. Côté Python, l'exemple du README tient en trois lignes : un agent créé par agents.for_document(123, corpus=45), puis un parcours asynchrone avec agent.stream("Summarize the indemnification clauses"). La documentation renvoie vers docs/architecture/llms/README.md pour le cadre LLM, docs/mcp/ pour MCP, docs/walkthrough/advanced/write-your-own-extractors.md pour les extracteurs, et docs/pipelines/pipeline_overview.md pour le pipeline. Une réserve : le README fourni ici s'arrête au milieu de la phrase sur GraphQL et REST, donc tout ce qui suit cette section dans le dépôt m'est inconnu.

Le pipeline comme point d'extension, pas comme dépendance cachée

Parsing, embedding et génération de vignettes sont décrits comme des composants interchangeables. Le README indique qu'enregistrer un parseur, un embedder ou un thumbnailer personnalisé pour ses formats laisse fonctionner l'aval sans modification : recherche, annotation et agents continuent de tourner. C'est la partie la plus intéressante du projet pour une équipe qui a des formats exotiques. Cela implique aussi une contrainte : la qualité du graphe dépend d'abord de la qualité du parsing. Un PDF mal découpé produit des citations mal ancrées, et aucune couche supérieure ne rattrapera cela. Le README ne donne pas de mesure de précision sur ce point, et je ne peux pas en inventer. Il faut donc considérer le parseur comme le premier élément à valider sur ses propres documents, avant de juger le reste de la chaîne.

Ce que la documentation ne tranche pas

Plusieurs points restent ouverts dans le matériel fourni. L'installation et le déploiement ne sont pas décrits : aucune commande docker compose, aucun fichier d'environnement, aucune procédure de migration n'apparaît. On sait que le projet est en Python, sous licence MIT, avec Celery pour l'extraction, mais l'assemblage complet n'est pas documenté dans ce que j'ai. Le coût de maintenance est difficile à estimer pour la même raison. Le rythme de publication est en revanche visible : v3.0.0 en août 2026, v3.1.0 en septembre 2026, avec une version bêta v3.0.0.b4 en février 2026. Cela suggère un projet actif, mais un numéro de version ne dit rien de la stabilité des API. La licence MIT est permissive : elle autorise la modification et la redistribution, y compris dans un produit propriétaire, à condition de conserver l'avis de licence. Ce n'est pas un avis juridique, et une équipe qui intègre le code dans un produit commercial doit faire vérifier les dépendances tierces, que le README ne liste pas.

Face à un moteur de recherche documentaire classique

L'alternative la plus proche est un moteur de recherche documentaire adossé à une base vectorielle, du type de ceux que l'on monte avec un index d'embeddings et une couche de questions-réponses. La différence d'approche est nette. Un tel montage répond à des requêtes par similarité : il retrouve des passages proches d'une question, sans modèle explicite des liens entre documents. OpenContracts construit un graphe où les citations sont des arêtes typées, avec des relations listées via list_relationships et des annotations via list_annotations. On peut donc demander non pas quels passages ressemblent à ma question, mais quels textes citent cette section précise, et quels textes cette section cite en retour. Le README montre cette navigation dans le panneau References, où un clic ouvre la loi citée avec ses propres renvois et tout ce qui la cite. Le compromis est réel : un graphe n'a de valeur que si l'extraction des citations est fiable, alors qu'un index vectoriel tolère l'imprécision. Sur des documents sans structure de citation, OpenContracts apporte moins qu'un simple index.

MCP : l'intérêt et la limite

Exposer chaque corpus via le Model Context Protocol évite d'écrire une couche d'adaptation entre le graphe et un client comme Claude ou Cursor. Le README insiste sur no glue code required, ce qui est exact du point de vue du client. La limite est ailleurs : les outils listés sont en lecture, à une exception près, create_thread_message. Seul le README précise que les annotations proposées par un agent passent par une autorisation. Cela signifie que le serveur MCP n'est pas un canal d'écriture libre, et c'est probablement volontaire. Pour un usage d'analyse et de recherche, la couverture suffit. Pour de la modification de masse depuis un agent, il faudra passer par l'API GraphQL ou REST, dont la documentation n'est pas incluse dans l'extrait fourni.

Conclusion éditoriale

OpenContracts convient aux équipes qui ont déjà un corpus de documents structurants (contrats, dépôts réglementaires, textes de loi) et qui veulent le graphe sous-jacent plutôt qu'une interface fermée. Écartez-le si vous cherchez un service managé ou si vous n'avez aucun moyen d'exécuter Celery, PostgreSQL et un serveur MCP. Avant de vous engager, vérifiez que le parseur gère vos formats, que /llms.txt et /.well-known/mcp.json sont bien servis par votre instance, et que la licence MIT suffit à votre cas d'usage.

Sources officielles

1. License: MIT
2. Open-Source-Legal/OpenContracts on GitHub
3. Project website
4. README
5. Releases