Skip to main content
Glama

KFabric

CI

KFabric est une plateforme Python-first de fabrication de corpus documentaires. Le projet vise un problème très concret : aider à construire un corpus traçable, pondéré et réutilisable à partir de sources hétérogènes, avant même de brancher un assistant RAG conversationnel.

Au lieu de passer directement du web au chat, KFabric se concentre d'abord sur la qualité du matériau documentaire :

  • découverte de documents candidats

  • collecte et normalisation

  • scoring et décision documentaire

  • récupération de fragments utiles dans des documents rejetés

  • consolidation et synthèse

  • préparation d'artefacts indexables pour des usages RAG futurs

Pourquoi KFabric

Dans beaucoup de pipelines RAG, la vraie faiblesse n'est pas le modèle mais le corpus. KFabric part de l'idée inverse :

  • un bon corpus vaut mieux qu'une mauvaise conversation bien emballée

  • les documents faibles contiennent parfois des signaux utiles à sauver

  • la traçabilité et la prudence documentaire doivent exister dès le MVP

  • un serveur MCP et une API REST doivent exposer exactement le même coeur métier

Related MCP server: knowledge-index

Ce que fait le MVP

Le MVP actuel couvre déjà un flux bout en bout :

  1. créer une requête documentaire

  2. découvrir des documents candidats

  3. collecter et parser un document

  4. attribuer un score global et des sous-scores

  5. accepter, rejeter, ou rejeter avec récupération partielle

  6. consolider les fragments sauvés

  7. générer une synthèse documentaire prudente

  8. construire un corpus final

  9. préparer un artefact d'indexation

Points forts

  • API REST FastAPI pour piloter le pipeline corpus

  • serveur MCP natif en Python

  • workers Celery pour les traitements longs

  • UI légère en Jinja2, HTMX et Alpine.js

  • modèles SQLAlchemy 2 et migration Alembic initiale

  • mode sécurisé activé par défaut

  • approche corpus-first avant chat RAG complet

Architecture

Le projet est structuré comme un monolithe modulaire Python :

Stack technique

  • Python 3.12

  • FastAPI

  • Pydantic v2

  • SQLAlchemy 2 + Alembic

  • Celery + Redis + RabbitMQ

  • PostgreSQL prêt pour la production

  • MCP Python SDK

  • Jinja2 + HTMX + Alpine.js

Démarrage rapide

Installation minimale :

python3.12 -m venv .venv
source .venv/bin/activate
pip install setuptools wheel
pip install -e ".[dev]" --no-build-isolation
cp .env.example .env
uvicorn kfabric.api.app:app --reload

Si tu veux aussi les dépendances plus lourdes liées aux connecteurs et à la préparation RAG étendue :

pip install -e ".[dev,extended]" --no-build-isolation

L'application démarre ensuite sur :

  • UI : http://127.0.0.1:8000/

  • API : http://127.0.0.1:8000/docs

Commandes utiles via Makefile :

make install-extended
make test
make run-api
make stack-up

Async broker-only

Les traitements asynchrones de KFabric fonctionnent maintenant en mode broker-only :

  • les routes et boutons async doivent être dispatchés via Celery

  • RabbitMQ et Redis doivent être disponibles

  • le worker KFabric doit être lancé

  • il n'existe plus de fallback local en thread si le broker ne répond pas

Variables recommandées dans .env.example :

KFABRIC_PREFER_CELERY_TASKS=true
KFABRIC_CELERY_ALWAYS_EAGER=false

Dans docker-compose.yml, les services KFabric utilisent toujours les hôtes internes postgres, redis, rabbitmq et qdrant, même si ton fichier .env contient des URLs localhost pour un lancement hors Docker.

En environnement de test, KFABRIC_CELERY_ALWAYS_EAGER=true reste utile pour exécuter les tâches immédiatement sans broker externe.

Exploitation V1

KFabric dispose maintenant d'un mode d'exploitation local plus stable :

  • docker-compose.yml avec migrations, healthchecks et volume de stockage

  • Makefile pour les commandes courantes

  • readiness détaillée sur /api/v1/readiness

  • mode async broker-only avec worker Celery dédié

Le runbook dédié est disponible dans docs/v1-runbook.md.

Sécurité et accès

KFabric peut fonctionner sans authentification en local, mais dès qu'une clé API est configurée via KFABRIC_API_KEY, l'accès est protégé :

  • l'API REST accepte X-API-Key ou Authorization: Bearer ...

  • l'interface web demande une session via /auth

  • les réponses exposent un trace_id et des headers de sécurité

Exemple :

export KFABRIC_API_KEY="change-me"
curl -H "Authorization: Bearer change-me" http://127.0.0.1:8000/api/v1/version

Démo produit

Deux scénarios de démonstration reproductibles sont fournis dans docs/demo-scenarios.md.

Génération rapide :

export KFABRIC_DATABASE_URL="sqlite:////tmp/kfabric-demo.db"
export KFABRIC_STORAGE_PATH="/tmp/kfabric-demo-storage"
./.venv/bin/python scripts/generate_demo_scenarios.py \
  --base-url "http://127.0.0.1:8010" \
  --output /tmp/kfabric-demo-manifest.json

Les captures de démonstration peuvent ensuite être générées depuis l’UI locale, et les corpus sont exportables en HTML et en Markdown.

Aperçu visuel

Page d'accueil avec les requêtes récentes :

Accueil KFabric

Workflow corpus-first sur le scénario "savon Europe" :

Tableau de bord KFabric - savon Europe

Export HTML prêt pour une démo ou une revue documentaire :

Export corpus KFabric - savon Europe

La galerie complète des scénarios validés est disponible dans docs/demo-scenarios.md.

Vérification locale

Les tests principaux peuvent être lancés avec :

pytest

Le dépôt exécute aussi une CI GitHub Actions sur push et pull_request via ci.yml.

Le MVP a été vérifié localement avec :

  • compilation Python

  • tests API

  • tests REST/MCP

  • tests de scoring et de récupération de fragments

API et MCP

KFabric expose deux surfaces complémentaires :

  • une API REST métier pour piloter tout le pipeline

  • une API REST concordante MCP

  • un serveur MCP natif en Python pour les tools, resources et prompts

Exemples de capacités exposées :

  • create_query

  • discover_documents

  • list_candidates

  • collect_candidate

  • analyze_document

  • accept_document

  • reject_document

  • consolidate_fragments

  • generate_fragment_synthesis

  • build_corpus

  • prepare_index

  • get_corpus_status

Statut du projet

KFabric est aujourd'hui un MVP technique fonctionnel.

Ce qui existe :

  • coeur métier corpus-first

  • contrat REST principal

  • socle MCP

  • UI workflow

  • migration initiale

  • tests de base

Ce qui viendra ensuite :

  • vrais connecteurs documentaires

  • meilleure collecte multi-format

  • embeddings réels et intégration vectorielle étendue

  • scoring plus fin par domaine

  • multi-tenant

  • interface de production plus avancée

Développement avec assistance IA

Ce projet a été conçu et développé avec assistance IA, puis structuré, contrôlé, vérifié et arbitré manuellement.

L'IA a servi d'accélérateur pour :

  • le prototypage

  • l'implémentation initiale

  • la documentation

  • certaines itérations techniques

Les choix d'architecture, la validation du flux MVP et la cohérence produit ont été assumés et consolidés manuellement.

Licence

Licence non encore définie.

Available Tools

13 tools
accept_documentC

Force a manual accept decision for a parsed document.

Inputs: kwargs (required).

analyze_documentC

Parse, score and decide on a collected document.

Inputs: kwargs (required).

build_corpusC

Build the final corpus for a query.

Inputs: kwargs (required).

collect_candidateC

Collect a candidate document and persist the raw payload.

Inputs: kwargs (required).

consolidate_fragmentsC

Cluster salvaged fragments for a query.

Inputs: kwargs (required).

create_queryC

Create a new KFabric documentary query.

Inputs: kwargs (required).

discover_documentsC

Launch discovery for an existing KFabric query.

Inputs: kwargs (required).

generate_fragment_synthesisC

Create a synthesis from salvaged fragments.

Inputs: kwargs (required).

get_corpus_statusC

Read the latest corpus status for a query or corpus id.

Inputs: kwargs (required).

list_candidatesC

List candidate documents for a query.

Inputs: kwargs (required).

list_salvaged_fragmentsC

List salvaged fragments optionally filtered by query.

Inputs: kwargs (required).

prepare_indexC

Prepare an indexable artifact for a corpus.

Inputs: kwargs (required).

reject_documentC

Force a manual reject decision for a parsed document.

Inputs: kwargs (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct step in the document processing pipeline, from query creation to corpus building. There is minimal overlap between tools like analyze_document and accept_document, which serve different stages.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., create_query, discover_documents). The style is uniform with no mixing of conventions.

    Tool Count5/5

    The 13 tools are well-scoped for a document collection and analysis pipeline. Each tool earns its place, covering discovery, collection, analysis, decision, and corpus assembly.

    Completeness4/5

    The core workflow is fully covered, but missing tools for listing queries or deleting candidates/corpora are minor gaps. Overall, the surface is nearly complete for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A private, self-hosted RAG service over MCP that enables document ingestion, hybrid retrieval (BM25 + dense vectors fused with RRF), and notebook management through 14 tools, keeping documents on your own hardware.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A modular RAG framework exposing knowledge retrieval tools via MCP, enabling AI assistants to perform hybrid search, reranking, and multimodal document queries with full observability and evaluation.
      MIT