BundleFabric — OS Cognitif BundleFabric — Cognitive OS

Fonctionnalités clés Key Features

• Intent extraction — extraction par mots-clés (instantanée) + enrichissement Ollama (async) + Claude Haiku (Tailscale uniquement)
• Intent extraction — keyword extraction (instant) + Ollama enrichment (async) + Claude Haiku (Tailscale only)
• RAG bundle resolution — recherche vectorielle Qdrant, classement par score TPS
• RAG bundle resolution — Qdrant vector search, ranked by TPS score
• SSE streaming — tokens en temps réel via Claude Haiku ou DeerFlow LangGraph
• SSE streaming — real-time token streaming via Claude Haiku or DeerFlow LangGraph
• Historique d'exécution — persistance SQLite, replay depuis le WebUI
• Execution history — SQLite persistence, replay from WebUI
• Score TPS — classement automatique des bundles par pertinence temporelle
• TPS scoring — automatic bundle ranking by temporal pertinence
• CRUD bundles — créer, modifier, supprimer depuis le WebUI
• Bundle CRUD — create, edit, delete from WebUI
• Multi-utilisateurs — auth JWT, comptes gérés par admin
• Multi-user — JWT auth, admin-managed accounts
• GitHub OAuth — connexion via GitHub, provisioning automatique
• GitHub OAuth — login via GitHub, auto-provision users
• Friend Mesh — réseau P2P pour partager bundles entre nœuds
• Friend Mesh — P2P network to share bundles across nodes
• Meta-Agent — suggère et crée automatiquement de nouveaux bundles
• Meta-Agent — suggests and auto-creates new bundles

URLs publiques Public URLs

• API — https://api.bundlefabric.org
• WebUI — https://app.bundlefabric.org
• Swagger — https://api.bundlefabric.org/docs
• Registry — https://bundlefabric.org

Architecture

Intention humaine (langage naturel)
    │
    ▼
┌─────────────────────────────────────────┐
│  IntentEngine                           │
│  keywords (0ms) → Ollama (async) →      │
│  Claude Haiku (Tailscale, si dispo)     │
└─────────────────┬───────────────────────┘
                  │  Intent {goal, domains, tools, complexity}
                  ▼
┌─────────────────────────────────────────┐
│  RAG Resolver (Qdrant)                  │
│  Recherche vectorielle → Top-K bundles  │
│  classés par score TPS                  │
└─────────────────┬───────────────────────┘
                  │  BundleManifest sélectionné
                  ▼
┌─────────────────────────────────────────┐
│  DeerFlow LangGraph                     │
│  deer-flow-langgraph:2024               │
│  Planner → Agents → Tools → Sandbox     │
│  + Fallback Claude Haiku si timeout     │
└─────────────────┬───────────────────────┘
                  │  ExecutionResult
                  ▼
           Réponse (JSON ou SSE)

Human intention (natural language)
    │
    ▼
┌─────────────────────────────────────────┐
│  IntentEngine                           │
│  keywords (0ms) → Ollama (async) →      │
│  Claude Haiku (Tailscale, if available) │
└─────────────────┬───────────────────────┘
                  │  Intent {goal, domains, tools, complexity}
                  ▼
┌─────────────────────────────────────────┐
│  RAG Resolver (Qdrant)                  │
│  Vector search → Top-K bundles          │
│  ranked by TPS score                    │
└─────────────────┬───────────────────────┘
                  │  Selected BundleManifest
                  ▼
┌─────────────────────────────────────────┐
│  DeerFlow LangGraph                     │
│  deer-flow-langgraph:2024               │
│  Planner → Agents → Tools → Sandbox     │
│  + Claude Haiku fallback on timeout     │
└─────────────────┬───────────────────────┘
                  │  ExecutionResult
                  ▼
           Response (JSON or SSE)

Stack technique Tech stack

Quickstart

1. Obtenir un token 1. Get a token

curlcurl -X POST https://api.bundlefabric.org/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "bf_yourname_xxxxxxxxxxxx"}'

response{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "yourname",
  "role": "user",
  "expires_in": 86400
}

2. Lister les bundles 2. List bundles

curlcurl https://api.bundlefabric.org/bundles \
  -H "Authorization: Bearer $TOKEN"

3. Exécuter un bundle 3. Execute a bundle

curlcurl -X POST https://api.bundlefabric.org/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_id": "bundle-linux-ops",
    "intent_text": "How do I check disk usage on Linux?"
  }'

response{
  "status": "success",
  "bundle_id": "bundle-linux-ops",
  "intent_goal": "Check disk usage on Linux",
  "output": "Use `df -h` to display disk usage...",
  "deerflow_thread_id": "7f0db0e7-cf28-4e84-815b-6f083178679b",
  "metadata": {
    "engine": "langgraph",
    "bundle_name": "Linux Operations Expert"
  }
}

4. Streaming SSE en temps réel 4. Real-time SSE streaming

curlcurl -N -X POST http://<YOUR_TAILSCALE_IP>:19102/execute/deerflow/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_id": "bundle-linux-ops",
    "intent_text": "Optimize nginx configuration for performance"
  }'

SSE streamdata: {"type":"status","msg":"🦌 Connexion DeerFlow LangGraph…","engine":"langgraph"}
data: {"type":"status","msg":"Thread LangGraph créé: 4ec53372…"}
data: {"type":"heartbeat","msg":"LangGraph traite… (38s)"}
data: {"type":"status","msg":"⚡ Fallback Claude Haiku…","engine":"claude_haiku"}
data: {"type":"token","content":"To optimize nginx for performance,"}
data: {"type":"token","content":" start by enabling gzip compression..."}
event: done
data: {}

Authentification Authentication

{
  "token": "eyJ...",
  "username": "string",
  "role": "user | admin",
  "expires_in": 86400
}

GitHub OAuth

GET /auth/oauth/github          → redirect vers GitHub
GET /auth/oauth/github/callback → callback, retourne JWT
GET /auth/oauth/providers       → liste des providers configurés

Système System

{"status": "ok", "version": "2.1.0", "uptime_seconds": 3600}

{
  "status": "ok",
  "version": "2.1.0",
  "bundles_loaded": 2,
  "deerflow": {
    "status": "online",
    "data": {
      "langgraph": {"status": "online", "url": "http://deer-flow-langgraph:2024"},
      "gateway": {"status": "online"}
    }
  },
  "qdrant_available": true,
  "qdrant_indexed_count": 2,
  "claude_available": true
}

Bundles

{"bundles": [{"id": "bundle-linux-ops", "name": "Linux Operations Expert", ...}]}

{"bundles": [...], "count": 2, "registry": "bundlefabric.org"}

{
  "bundle_id_a": "bundle-linux-ops",
  "bundle_id_b": "bundle-gtm-debug",
  "strategy": "union"   // "union" | "intersection" | "weighted"
}

Orchestration

{"text": "How do I configure nginx reverse proxy?"}

{
  "raw_text": "How do I configure nginx reverse proxy?",
  "goal": "Configure nginx as reverse proxy",
  "domains": ["linux", "nginx", "devops"],
  "tools": ["nginx", "bash"],
  "complexity": "intermediate",
  "user_level": "developer"
}

{
  "intent": {
    "raw_text": "nginx reverse proxy",
    "goal": "Configure nginx reverse proxy",
    "domains": ["nginx"],
    "tools": [],
    "complexity": "basic",
    "user_level": "developer"
  },
  "top_k": 3,
  "filter_archival": true
}

{
  "intent_goal": "Configure nginx reverse proxy",
  "matches_count": 1,
  "matches": [
    {
      "bundle_id": "bundle-linux-ops",
      "bundle_name": "Linux Operations Expert",
      "tps_score": 0.885,
      "match_score": 0.92
    }
  ]
}

{
  "status": "success | error | timeout",
  "bundle_id": "bundle-linux-ops",
  "intent_goal": "string",
  "output": "string",
  "deerflow_thread_id": "uuid",
  "error_message": null,
  "metadata": {
    "engine": "langgraph",
    "bundle_name": "string",
    "system_prompt_injected": true
  }
}

Streaming SSE

History

{
  "id": "uuid",
  "bundle_id": "bundle-linux-ops",
  "intent_text": "...",
  "output": "...",
  "status": "success",
  "duration_ms": 1200,
  "created_at": "2026-03-18T20:00:00Z"
}

DeerFlow

{
  "status": "online",
  "url": "http://deer-flow-gateway:8001",
  "data": {
    "langgraph": {"status": "online", "url": "http://deer-flow-langgraph:2024"},
    "gateway": {"status": "online"}
  }
}

Architecture LangGraph LangGraph Architecture

POST /threads                        → Créer un thread (contexte)
POST /threads/{id}/runs/wait         → Exécuter (bloquant)
POST /threads/{id}/runs/stream       → Exécuter (SSE streaming)

Payload requis :
{
  "assistant_id": "bee7d354-...",
  "input": {"messages": [...]},
  "context": {"thread_id": "<thread_id>"},  ← REQUIS par ThreadDataMiddleware
  "stream_mode": ["messages"],
  "config": {"recursion_limit": 25}
}

POST /threads                        → Create a thread (context)
POST /threads/{id}/runs/wait         → Execute (blocking)
POST /threads/{id}/runs/stream       → Execute (SSE streaming)

Required payload:
{
  "assistant_id": "bee7d354-...",
  "input": {"messages": [...]},
  "context": {"thread_id": "<thread_id>"},  ← REQUIRED by ThreadDataMiddleware
  "stream_mode": ["messages"],
  "config": {"recursion_limit": 25}
}

Admin

{"users": [{"username": "alice", "role": "admin", "api_key_masked": "bf_alice_xxxx****"}]}

{"username": "alice", "role": "user"}  // Retourne la clé API en clair

Concept Bundle Bundle Concept

Bundle IA = modèle_préféré + RAG_contextualisé + agents/outils
           + prompts_système + schémas_cognitifs

AI Bundle = preferred_model + contextualized_RAG + agents/tools
          + system_prompts + cognitive_schemas

Format Bundle Bundle Format

Arborescence File tree

Manifest YAML complet Full YAML manifest

manifest.yamlid: bundle-linux-ops                    # unique, kebab-case
name: Linux Operations Expert            # display name
version: 1.0.0                          # semver
description: Expert Linux/nginx/Docker
author: bundlefabric
license: MIT
public: true                            # appears in public registry

domains:
  - linux
  - devops
  - docker
  - nginx

keywords:
  - bash
  - shell
  - nginx
  - docker
  - systemd

capabilities:
  - bash-scripting
  - linux-sysadmin
  - process-management
  - nginx-configuration
  - docker-operations

deerflow_workflow: linux-ops-agent      # DeerFlow graph ID (optional)

temporal:
  last_updated: "2026-03-17"
  freshness_score: 0.9                  # 0.0–1.0, auto-computed
  usage_count: 10
  usage_frequency: 0.52                 # auto-incremented on execute
  ecosystem_alignment: 0.9
  tps_score: 0.885                      # computed: see TPS section
  status: active                        # active | archived

TPS Score

TPS = freshness_score × 0.4 + usage_frequency × 0.3 + ecosystem_alignment × 0.3

Friend Mesh

# Configuration dans friends.yaml
friends:
  - name: "node-paris"
    url: "https://api.bundlefabric.org"
    api_key: "bf_paris_xxxx"

# Endpoints mesh
GET  /mesh/status                  → statut des pairs
GET  /mesh/peers                   → liste des nœuds connectés
GET  /mesh/bundles                 → tous les bundles du mesh
POST /mesh/bundles/{id}/request    → télécharger un bundle pair

# Configuration in friends.yaml
friends:
  - name: "node-paris"
    url: "https://api.bundlefabric.org"
    api_key: "bf_paris_xxxx"

# Mesh endpoints
GET  /mesh/status                  → peer status
GET  /mesh/peers                   → connected nodes
GET  /mesh/bundles                 → all mesh bundles
POST /mesh/bundles/{id}/request    → download a peer bundle

Déploiement Deployment

Prérequis Prerequisites

• Docker 24+ & Docker Compose v2
• Python 3.12 (image Docker incluse)
• Python 3.12 (included in Docker image)
• 16 GB RAM minimum recommandés pour Ollama CPU
• 16 GB RAM minimum recommended for Ollama CPU
• Domaine + DNS configurés si accès public
• Domain + DNS configured for public access

Lancement Launch

bash# Cloner et lancer
git clone https://github.com/fbailleux2/bundlefabric
cd bundlefabric

# Configurer les secrets
echo "JWT_SECRET=$(openssl rand -hex 32)" > .env

# Lancer Phase 2 complète (API + Prometheus)
docker compose --profile phase2 up -d

# Vérifier
curl http://localhost:19100/health

Variables d'environnement clés Key environment variables

Sécurité Security

Modèle d'accès Access model

Signature des bundles Bundle signing