convez.ai
MCP ServerDevOps & InfraestruturaAvançado
h3rb3rn

MoE Sovereign

h3rb3rn/moe-sovereign

Orquestrador IA multi-modelo 100% local, sem cloud, com roteamento por expertise

Ver no GitHub
BomPluginScore · de 0 a 100

Orquestrador multi-modelo auto-hospedado com roteamento inteligente de especialistas para ambientes soberanos. Implementa token-saving routing, ferramentas MCP determinísticas (matemática/lógica), templates de especialistas configuráveis, aprendizado causal/reinforcement e GraphRAG federado em Neo4j.

Instalação

$npx convez-ai h3rb3rn/moe-sovereign

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
12
Forks
1
Acompanhando
0
Saúde
85%
Último commit
há 2 dias
Versão
—
Issues abertas
1
Contribuidores
4

Casos de uso

  • Infraestrutura IA soberana em conformidade com GDPR
  • Processamento de dados sensíveis sem sair da rede local
  • Orquestração inteligente de múltiplos modelos LLM
  • Sistemas de IA em ambientes air-gapped/desconectados
  • Roteamento baseado em expertise com cache semântico

Veredito

Solução robusta para quem precisa de soberania de dados e controle total da infraestrutura IA. Complexidade alta, mas alinha perfeitamente com requisitos regulatórios europeus; ideal para enterprises com demandas de compliance rigorosas.

README

A tradução para o português deste README ainda está na fila.

MoE Sovereign

A Self-Hosted Multi-Model Orchestrator with Template-Based Expert Routingfor Sovereign AI Infrastructure

License Deployment Air-Gap Docs

Documentation • Website • Issues • Changelog


Motivation

Commercial AI APIs process every request on infrastructure the customer neither owns nor can inspect. Training-data extraction, prompt logging, and retroactive policy changes are documented incidents. The European regulatory framework --- in particular GDPR Articles 25 and 32 --- mandates data protection by design, a requirement difficult to discharge with an opaque black box in a foreign jurisdiction.

MoE Sovereign is a fully self-hosted multi-model orchestrator with template-based expert routing that runs entirely on your own hardware. No data leaves your network. No cloud dependency. No vendor lock-in.


Architecture

flowchart TD
    subgraph Clients["Client Layer"]
        CC["Claude Code"]
        OW["Open WebUI"]
        API["Any OpenAI Client"]
    end

    subgraph Orchestrator["MoE Orchestrator (LangGraph)"]
        direction TB
        Cache{"L0/L1 Cache<br/>Valkey + ChromaDB"}
        Planner["Planner<br/><i>phi4:14b</i>"]
        
        subgraph Experts["Parallel Expert LLMs"]
            E1["Code Reviewer"]
            E2["Researcher"]
            E3["Domain Expert"]
        end

        MCP["28 MCP Tools<br/><i>AST-Whitelist + PPTX</i>"]
        Graph["Neo4j GraphRAG"]
        Judge["Judge / Merger<br/><i>llama3.3:70b</i>"]
        GapCheck{"Gap Detector<br/><i>COMPLETE?</i>"}
        Replan["Agentic Re-Plan<br/><i>up to 3 rounds</i>"]
    end

    subgraph Storage["Persistence Layer"]
        Neo4j[("Neo4j<br/>Knowledge Graph")]
        Chroma[("ChromaDB<br/>Vector Cache")]
        Kafka["Kafka<br/>Event Stream"]
        Valkey[("Valkey<br/>State & Sessions")]
        PG[("PostgreSQL<br/>Users & Checkpoints")]
    end

    Clients -->|"/v1/chat/completions<br/>/v1/messages<br/>/v1/responses"| Cache
    Cache -->|Miss| Planner
    Cache -->|Hit| Response
    Planner --> Experts
    Experts --> MCP
    MCP --> Graph
    Graph --> Judge
    Judge --> GapCheck
    GapCheck -->|"COMPLETE"| Response["Response"]
    GapCheck -->|"NEEDS_MORE_INFO"| Replan
    Replan -->|"inject gap context"| Planner
    Response -->|Ingest| Kafka
    Kafka --> Neo4j
    Response -->|Cache Write| Chroma
    Judge -.->|"Retry on<br/>low score"| Planner

    style Orchestrator fill:#f0f4ff,stroke:#4a6fa5
    style Experts fill:#e8f5e9,stroke:#388e3c
    style Storage fill:#fff8e1,stroke:#f9a825

Pipeline Stages

StageDescription
1. CacheL0 query-hash (Valkey, 30 min TTL), L1 semantic similarity (ChromaDB, cosine < 0.15), and a conservative knowledge-bypass tier: similar-but-not-exact queries skip the LLM when the prior answer was high-confidence and still fresh (cosine < 0.25, confidence ≥ 0.85, within TTL)
2. PlannerDecomposes request into 1--4 subtasks with expert category assignment
3. ExpertsT1 models (≤20B) screen with confidence gating; T2 (24--80B) engage only on low confidence
4. Tools28 MCP precision tools (math, subnet, date, legal, PPTX) via AST-whitelist --- zero hallucination
5. GraphRAGNeo4j context enrichment with domain-scoped entity filters and trust-score decay. CAG layer intercepts static compliance domains (BAIT, VAIT, DORA, KRITIS) before the Neo4j query and injects pre-loaded authoritative text directly. Corrective RAG gate (Yan et al. 2024) scores each retrieved entity for query relevance and discards low-signal results before injection. Episode hints from past similar tasks are appended as routing context
6. JudgeSynthesises expert outputs, evaluates quality, retries on failure (up to 3 attempts)
7. Agentic Re-PlanLightweight gap detector checks completeness; if unresolved, injects findings into a new planner round (up to 3 agentic iterations)
8. IngestValidated knowledge flows back into Neo4j via Kafka for graph accumulation acceleration

Module Structure

The orchestrator codebase is organised into focused packages. main.py is a thin entry point (~1 500 LOC) holding the FastAPI app, lifespan, middleware, and graph wiring. All domain logic lives in dedicated packages:

moe-infra/
├── main.py                    # FastAPI app, lifespan, middleware, graph wiring (~1 500 LOC)
├── config.py                  # All os.getenv() — typed config constants
├── state.py                   # Shared mutable globals (redis_client, _userdb_pool, …)
├── prompts.py                 # Static prompt text + routing detection regexes
├── metrics.py                 # Single Prometheus registry
├── parsing.py                 # Stateless parsers: JSON extraction, confidence, history truncation
├── context_budget.py          # Per-model context-window estimation
│
├── routes/                    # FastAPI APIRouters (one per concern)
│   ├── health.py              # /health, /metrics
│   ├── watchdog.py            # /api/watchdog/*, Starfleet feature toggles
│   ├── mission_context.py     # /api/mission-context
│   ├── graph.py               # /graph/*
│   ├── feedback.py            # /v1/feedback, /v1/memory/ingest
│   ├── admin_*.py             # Benchmark, ontology, stats admin endpoints
│   ├── models.py              # /v1/models
│   ├── ollama_compat.py       # /api/* (Ollama protocol)
│   └── anthropic_compat.py    # /v1/messages, /v1/responses, /v1/chat/completions
│
├── services/                  # Business logic — no FastAPI imports
│   ├── auth.py                # OIDC + API key validation + budget enforcement
│   ├── tracking.py            # Usage logging, request lifecycle, budget counters
│   ├── routing.py             # Expert template + per-template prompt resolution
│   ├── templates.py           # Expert template + Claude Code profile loading
│   ├── llm_instances.py       # ChatOpenAI singletons (judge, planner, ingest, search)
│   ├── inference.py           # Node selection, fallback chain, Thompson sampling
│   ├── helpers.py             # Progress reports, semantic memory, self-evaluation
│   ├── skills.py              # Server-side skill resolution + ADMIN_APPROVED hard-lock
│   ├── healer.py              # Ontology gap-healer (one-shot + dedicated subprocess)
│   ├── kafka.py               # Fire-and-forget Kafka publish helper
│   └── pipeline/              # OpenAI / Anthropic / Ollama / Responses API handlers
│       ├── chat.py            # OpenAI chat completions
│       ├── anthropic.py       # Anthropic Messages API + tool/MoE/reasoning handlers
│       ├── ollama.py          # Ollama-protocol streaming wrappers
│       └── responses.py       # OpenAI Responses API
│
├── graph/                     # LangGraph node implementations
│   ├── router_nodes.py        # cache_lookup, semantic_router, fuzzy_router, _route_cache
│   ├── tool_nodes.py          # mcp_node, graph_rag_node, math_node_wrapper
│   ├── planner.py             # planner_node + plan sanitization + topological levels
│   ├── expert.py              # expert_worker (parallel expert execution)
│   ├── research.py            # research_node + research_fallback + domain extraction
│   └── synthesis.py           # merger_node, thinking_node, resolve_conflicts_node, critic_node
│
├── pipeline/
│   ├── __init__.py            # LangGraph graph builder — assembles nodes into the pipeline DAG
│   └── state.py               # AgentState TypedDict (67 fields across 3 categories)
│
├── web_search.py              # SearXNG integration with domain-reliability scoring
├── math_node.py               # SymPy-backed math node (solve, integrate, differentiate)
├── graph_rag/                 # GraphRAG query, entity linking, ontology, corrections
├── federation/                # Push / pull federation client to MoE Libris hubs
├── mcp_server/                # 28 MCP precision tools (AST-whitelisted)
├── admin_ui/                  # Admin backend: experts, users, budgets, cleanup manager
├── prompts/systemprompt/      # 15 expert system prompts (English, "Respond in German.")
├── tests/                     # 195 unit + integration + smoke tests (all green)
└── benchmarks/                # Overnight benchmark suite, GAIA runner, result injection

The orchestrator started as an 11 190-line monolith in main.py. A 14-phase split (Q2 2026) decomposed it into the structure above without a single behavioural change — every phase ended with the full test suite green. See docs/ARCHITECTURE.md for the detailed module map.


Key Capabilities

A) Core AI & Orchestration

CapabilityDescription
1Deterministic Expert RoutingVersioned, auditable templates --- not a probabilistic black box
2Two-Tier EscalationT1 screens fast; T2 engages only when needed --- incl. a low-confidence rescue that lets a trivial query escalate to T2 when T1 returns weak/empty output (TRIVIAL_LOW_CONF_RESCUE_ENABLED)
3Neo4j GraphRAGTrust-score self-healing, contradiction detection, domain-scoped filters
4Community Knowledge BundlesExport/import learned knowledge as JSON-LD with regex-based privacy scrubbing (PII, secrets, hostnames)
551 MCP Precision ToolsAST-whitelisted --- 100% accuracy on deterministic tasks; includes wikidata_sparql, pubmed_search, crossref_lookup, openalex_search, duckduckgo_search, web_browser (Splash JS rendering), wayback_fetch, github_search_issues with fuzzy label resolution
6VRAM-Aware SchedulingPer-node VRAM limits, warm-model affinity, sticky sessions
8Claude Code IntegrationFull Anthropic Messages API with 6 profiles and streaming thinking blocks
9Deployment FlexibilityOne OCI image → LXC (tested), Docker Compose (tested), Podman rootless (tested), Helm/K8s (architecturally prepared, community validation requested)
109.3× Accumulation Speedup707 s → 76 s latency over 5 benchmark epochs
12Agentic Re-Planning LoopAfter each synthesis the Judge checks completeness; unresolved gaps trigger a focused re-plan with injected context --- up to 3 autonomous iterations per request; domain-aware search cache prevents result poisoning across iterations
13PowerPoint GenerationMCP generate_pptx tool creates fully formatted .pptx presentations from structured content and delivers them as signed Garage (S3) download links
18Dynamic Sequential/Parallel ExpertsPlanner tasks support depends_on for multi-hop chains (e.g. find author → find their papers). Independent tasks run in parallel; dependent tasks execute sequentially with result injection via {result_of:id} placeholders
19Adaptive Context BudgetContext window limits per model auto-scale web-research blocks and GraphRAG budget. Fallback models (phi4:14b-fp16 16K, qwen3.6:35b 32K) receive proportionally smaller context slices
20GraphRAG On-DemandNeo4j queries skipped for external research questions (papers, APIs, media) — only runs for internal knowledge queries or when the plan includes a knowledge_healing task
21OpenAI Responses API (/v1/responses)Full Responses API streaming with correct SSE events (sequence_number, output_index, content_index) — enables Codex CLI, Continue.dev, and any OpenAI Responses API compatible agent out of the box
23Chess Analysis via LichessMCP tool chess_analyze_position queries Lichess cloud Stockfish (342M positions, depth 20–99) for best moves given a FEN string — no local engine required
25Formal Logic State LayerThree-tier algebraic logic over the LangGraph state (de Vries 2007): paraconsistent conflict registry tolerates contradictory expert outputs without pipeline failure; intuitionistic ConstructiveProof[T] marks LLM claims as ⊥ until executor-verified; fuzzy T-norm routing replaces binary flags with continuous confidence scores — Gödel min and Łukasiewicz max(0,a+b−1) conjunctions configurable via env
26AIC Complexity Estimationzlib compressibility as a Kolmogorov complexity proxy (Kolmogorov 1965) acts as a tie-breaker in estimate_complexity() — information-dense prompts (ratio < 0.15, ≥ 35 words) are upgraded to complex; redundant short prompts downgraded to trivial, without any LLM call
27Infrastructure-Adaptive Expert ScoringThompson Sampling Beta prior adjusted by real-time node load from _ps_cache: busy inference nodes receive an inflated β parameter — steering expert selection toward idle hardware automatically, without manual configuration. The reward signal is judge-aware: a category the Judge had to refine counts as a negative outcome (güte over self-confidence), falling back to self-reported confidence only when refinement is disabled
28Fuzzy Graph Entity DeduplicationBefore every Neo4j MERGE, incoming entity names are resolved via Ratcliff/Obershelp SequenceMatcher (threshold 0.82) against a prefix-batched index — alternate spellings across knowledge sources ("Einstein, Albert" ↔ "Albert Einstein") map to one canonical node instead of creating duplicates
42Query Reformulation (Agentic RAG)When term-matching returns nothing, a lightweight LLM generates up to 2 alternative query phrasings (shorter terms, English equivalents, abbreviations like BAIT/DORA) and retries term-matching before falling back to Text-to-Cypher. Implements iterative retrieval from Agentic RAG. Zero overhead when term-matching succeeds. Configurable via GRAPHRAG_REFORMULATE_*
43Confidence-Weighted Expert SynthesisExpert responses are sorted high→low confidence before the judge prompt (primacy bias) and labelled PRIMARY / SUPPORTING / BACKGROUND. The merger instruction explicitly anchors on PRIMARY findings. No extra LLM call — uses the CONFIDENCE: field already in expert output
41Text-to-Cypher GraphRAG FallbackWhen term-matching returns no Neo4j entities, a lightweight LLM generates a targeted Cypher MATCH query from natural language. Write operations rejected by regex whitelist before execution. Zero latency impact when term-matching succeeds. Configurable via GRAPH_INGEST_ENDPOINT + GRAPHRAG_T2C_* env vars
38Corrective RAG GateRetrieved Neo4j entities are scored for query relevance before injection (Yan et al. 2024, arXiv:2401.15884). Term overlap (2× weight for entity-name hits) combined with average relation confidence produces a [0,1] score; entities below GRAPHRAG_CORRECTIVE_THRESHOLD (default 0.15) are discarded — prevents context pollution from tangentially matched graph nodes
39CAG Compliance LayerStatic regulatory domains (BAIT, VAIT, DORA, KRITIS, MaRisk) bypass Neo4j retrieval entirely — authoritative text is injected directly from admin-managed JSON files in $MOE_DATA_ROOT/cag/ (Chan et al. 2024, arXiv:2412.15605). Hot-reloaded every 5 minutes. Adding a new domain requires only dropping a JSON file — no restart
40Episodic MemoryEvery successful pipeline run is logged as a :Episode node in Neo4j (task type, routing path, tools used, confidence, token cost, TTL 90 days). On similar queries, routing hints from past episodes are appended to graph_context so the judge can leverage proven strategies. Basis: Tulving (1972), Park et al. 2023 Generative Agents, Packer et al. 2023 MemGPT

B) Security, Sovereignty & Admin

CapabilityDescription
7Multi-Tenant RBACPer-user token budgets, template permissions, SSO (Authentik/OIDC)
11Autonomous Disk ManagementSystem Cleanup Manager in Admin UI: configurable TTL per subsystem, daily cron automation, LangGraph checkpoint archiving, Docker build-cache pruning, history tracking with averages
14Selective Template & Profile ExportAdmin UI: individual templates and CC profiles can be checkbox-selected for targeted export --- no need to export the full set every time
15Endpoint Availability GraphSystem Monitoring shows a 24-hour stepped-line chart per inference server (UP/DOWN, 5-min resolution via Prometheus query_range)
16API Endpoint Budget OverviewPer-endpoint budget cards with spend, limit, and colour-coded progress bar — read live from LiteLLM x-litellm-key-spend / x-litellm-key-max-budget headers
17User Budget Response Headers/v1/chat/completions returns X-MoE-Budget-Daily-Used and X-MoE-Budget-Daily-Limit — clients can gate on quota without a separate API call
22Pipeline Transparency LogPer-request routing log: expert domains engaged, complexity level, latency, cache hit, agentic rounds — queryable via /v1/admin/pipeline-log with CSV export for BI tools
24Claude Desktop & Cowork GatewayFull Anthropic Third-Party Inference Gateway spec: display_name in /v1/models, /v1/messages/count_tokens endpoint, X-Claude-Code-Session-Id tracking — compatible with Claude Desktop, Claude Cowork, and Claude Code out of the box. Run scripts/setup-claude-desktop.sh to auto-configure

C) Enterprise Data Management (moe-codex Extension)

This feature group requires the optional moe-codex enterprise stack (Apache NiFi, Marquez/OpenLineage, lakeFS). It is not part of the moe-sovereign core and is deployed as a separate compose stack. See the moe-codex repository for setup instructions.

CapabilityDescription
29OpenLineage Data Lineage (Marquez)Five pipeline hook points (/v1/chat/completions, /v1/messages, /v1/responses, merger_node, kafka_ingest) emit OpenLineage 2.0.2 START/COMPLETE/FAIL events to a Marquez backend — fire-and-forget, no-op when MARQUEZ_URL is empty. Palantir Foundry-comparable lineage visibility for every MoE pipeline run
30Enterprise Stack DashboardAdmin UI /enterprise page surfaces NiFi, Marquez and lakeFS reachability with live latency probes, plus the most recent OpenLineage runs from Marquez. Auto-refreshes every 30 s; gracefully hides when INSTALL_ENTERPRISE_DATA_STACK=false
31lakeFS Bundle VersioningEvery successful /graph/knowledge/import archives the JSON-LD bundle as a content-addressed commit on the moe-knowledge lakeFS repository — git-style audit log queryable via /api/enterprise/versioning/log, point-in-time bundle download via services.versioning.get_bundle_at() for rollback. Fire-and-forget; no-op when LAKEFS_ENDPOINT is empty
32NiFi ETL SubmissionKnowledge events (Kafka ingest + bundle import) are forwarded to a configurable NiFi ListenHTTP processor (NIFI_INGEST_URL), so downstream NiFi flows can fan out to S3/Solr/Elastic/Snowflake without orchestrator changes. JSON in body, MoE metadata as X-MoE-* FlowFile attributes; admin dashboard surfaces NiFi system diagnostics (uptime, heap, threads, version) at /api/enterprise/etl/status
33Unified Data CatalogAdmin UI /catalog page aggregates datasets across all three back-ends in one searchable, source-filterable table — Marquez datasets per namespace, Neo4j entity-domain breakdown (entities/relations/syntheses), and lakeFS repositories with commit counts. Foundry-Catalog-equivalent cross-source browsing without leaving the admin UI
34Branch-based Approval WorkflowPOST /v1/graph/knowledge/import/pending stages a bundle on a lakeFS pending/<tag>-<ts> branch instead of Neo4j; admins review pending bundles in /approval, then approve (= Neo4j import + lakeFS merge to main) or reject (= branch delete). Adds an explicit gate before any external knowledge enters the live graph
35Read-only Cypher ExplorerAdmin UI /explorer page exposes an in-page Cypher editor restricted to read mode: regex-blacklist rejects CREATE/DELETE/SET/MERGE/REMOVE/DROP/ALTER/GRANT/REVOKE/FOREACH before the query reaches Neo4j, plus the driver runs in READ_ACCESS mode. Includes preset queries and a deep-link to the standalone Neo4j Browser
36Data Health Drift DetectionEvery successful knowledge-bundle import is wrapped in a stats snapshot — services/data_health.compute_drift() flags entity_dedup_suppressed, zero_entities_added, entity_count_shrank, entity_overshoot, relation_overshoot, relation_to_entity_explosion. Events land in Redis moe:data_health:events (capped 500) and surface on the Enterprise dashboard with severity pills (ok / info / warn / crit). Threshold tunable via DATA_HEALTH_DRIFT_THRESHOLD (default 0.3)
37Embedded JupyterLite NotebookAdmin UI /notebook embeds JupyterLite (browser-only WebAssembly Jupyter) with JUPYTERLITE_URL configurable for self-hosted deployments. Includes copy-paste-ready snippets for the orchestrator API (export, pending-import, search, Cypher, lineage runs) — power-users can prototype against the live graph without installing a Python kernel anywhere
38User Conversation Audit LogEvery authenticated API request is appended as a JSONL entry to ${MOE_DATA_ROOT}/user-audit-logs/{user_id}.jsonl — full prompt text, full response, routing metadata (model, mode, expert domains, cache hit, latency). Users access their own log via /user/audit-log with date/search filters, full-text expand, and CSV/JSON export. Retention is configurable per user (default 90 days, max 365 days); daily logrotate rotation with dateext; automatic cleanup via daily background job in moe-admin.
39Learned Routing GateThe retrieval gates (web research / knowledge graph) are decided by a contextual Thompson bandit (services/routing_bandit.py) instead of fixed fuzzy thresholds. Context = complexity level + discretised t-norm band; reward = request adequacy (an expert "cannot access the web" disclaimer marks research as needed; a judge-refined category marks weak graph grounding). A cost prior biases ties toward skipping retrieval to save inference. The fuzzy/complexity heuristic survives as both the context features and the cold-start fallback — until both arms of a (gate, context) reach ROUTING_BANDIT_MIN_DATAPOINTS, the heuristic decision is used unchanged, so routing never regresses below the fuzzy baseline while it learns. Metric: moe_routing_bandit_total{gate,action,source}.
44OpenAI Tool-Calling PassthroughWhen a request carries a tools array (function definitions) or messages with role: "tool" (tool-result turns), the gateway skips the planner/experts/merger pipeline entirely and forwards directly to the template's judge model. The judge (e.g. hermes3:8b, qwen3.6:35b) handles OpenAI-compatible function-calling natively and returns tool_calls or the final text to the client. Enables Hermes MCP integration, Open-WebUI function-calling, and any OpenAI-function-calling-compatible agent framework. Follow-up role: "tool" turns omit tools in the forwarded payload to prevent model tool-call loops. (services/pipeline/chat.py _handle_tool_calls())
48Two-Phase Kanban WorkerWhen the Hermes kanban-worker agent sends a "work kanban task <id>" request, _handle_tool_calls() uses a two-phase approach instead of relying solely on the tool-calling model. Phase 1: the task ID is parsed from the user message via regex — a synthetic kanban_show tool call is returned without invoking any LLM. Phase 2: after Hermes executes kanban_show and sends back the task content as a role: "tool" result, the gateway calls the template's general content expert (e.g. qwen3.6:35b) with a clean, minimal prompt — no KANBAN_GUIDANCE system prompt overhead. The answer is wrapped in a synthetic kanban_complete tool call and returned to Hermes. A _kc_already_dispatched guard prevents re-synthesis loops on follow-up turns. The content model is resolved from the active template's experts dict (first non-tool_agent expert) and is injected alongside content_url/content_token/content_system_prompt. (services/pipeline/chat.py _handle_tool_calls())
45Two-Tier Escalation Telemetrymoe_tier_escalation_total{category, decision} counter tracks every T1/T2 routing outcome per expert category: t1_high_skip (T1 confident, T2 saved), t1_cost_kept (trivial task — T1 medium is good enough, deliberate cost saving), t1_only (no T2 tier configured), t2_escalated (T1 insufficient, T2 steps in). moe_cache_query_distance histogram records the nearest cache-entry cosine distance per lookup across all decision outcomes — enables data-driven calibration of the static thresholds (hit 0.08 / bypass 0.25 / soft 0.50) from real query distributions. Complements the existing moe_expert_calls_total{node} for load-distribution analysis.
46User-Template Expert Category RoutingCustom expert categories defined in user templates (e.g. mail_classify, devops_sre, creative_writing, tool_agent) are now recognised as valid routing targets. Previously, _sanitize_plan() validated categories only against the global EXPERTS registry and silently degraded any template-specific category to "general", bypassing the intended specialist model. The active template's category set is now passed as an additional valid set so the planner routes correctly to template-defined experts.
47Trivial Low-Confidence T2 RescueTRIVIAL_LOW_CONF_RESCUE_ENABLED (default: true): when a query is cost-tier-limited to a single T1 expert (trivial complexity), the orchestrator still escalates to one T2 model if the T1 answer comes back low-confidence or empty. Medium/high T1 answers keep the cost saving — only genuine low-quality responses trigger the rescue. The decision is captured in moe_tier_escalation_total (t1_cost_kept vs t2_escalated). Set to false to restore strict "trivial tasks never touch T2" behaviour.

Federated Knowledge Ecosystem

MoE Sovereign goes beyond a local RAG system. With community knowledge bundles, deployments exchange domain knowledge (law, Kubernetes, React, medicine) without sharing proprietary data or source code.

flowchart LR
    subgraph Instance_A["Deployment A<br/><i>Banking</i>"]
        GA[("Neo4j<br/>3 150 entities")]
    end
    subgraph Instance_B["Deployment B<br/><i>Healthcare</i>"]
        GB[("Neo4j<br/>2 800 entities")]
    end
    subgraph Instance_C["Deployment C<br/><i>DevOps</i>"]
        GC[("Neo4j<br/>1 200 entities")]
    end

    GA -- "Export Bundle<br/>(privacy-scrubbed)" --> Bundle["JSON-LD<br/>Knowledge Bundle"]
    GB -- "Export Bundle" --> Bundle
    Bundle -- "Import<br/>(trust-capped)" --> GC
    Bundle -- "Import" --> GA

    style Bundle fill:#e3f2fd,stroke:#1565c0,stroke-width:2px

Privacy protection: Metadata stripping • Regex detection of PII/secrets • Sensitive relation-type filter • ⚠ Human-in-the-loop responsible for contextual/structural PII (see Privacy Scrubber limitations) Import safety: Entity MERGE (no duplicates) • Trust ceiling (0.5) • Contradiction detection via moe.linting

Every new installation enriches the collective knowledge graph. Every bundle import accelerates all participants. This is the network effect for open-source AI.


Benchmarks

BenchmarkScoreReference
GAIA Level 160%GPT-4o: 33% • Claude 3.7: 44% • MoE Sovereign: 60% (6/10, moe-aihub-free-gremium-deep-wcc, best run)
GAIA Level 250%GPT-4o Mini: <30% • MoE Sovereign: 50% (5/10) — multi-hop database lookups, github issue events, Wikidata SPARQL
GAIA Level 340%MoE Sovereign: 40% (4/10) — complex multi-step research chains
GAIA Overall46.7%GPT-4o Mini reference: 44.8% • MoE Sovereign best: 46.7% (14/30) — 5 iterative runs 2026-04-25
Math Precision (MCP)10/10Deterministic AST computation, 0% variance
Security Code Review9.0/10SQLi + XSS identified and fixed
Adversarial MCP9/9 blockedAll code injection attempts stopped by AST firewall
69 LLM Model Testphi4:14bBest planner/judge from 69 models tested
Accumulation Effect9.3×707 s → 76 s over 5 epochs (GraphRAG + cache)

Quick Start

One-Line Install

curl -sSL https://moe-sovereign.org/install.sh | bash

Manual Setup

git clone https://github.com/h3rb3rn/moe-sovereign.git
cd moe-sovereign
cp .env.example .env
nano .env                      # Set credentials and inference server URLs
sudo docker compose up -d
curl http://localhost:8002/v1/models
EndpointURL
API (OpenAI-compatible)http://<host>:8002/v1
API (Anthropic/Claude Code)http://<host>:8002/v1/messages
Admin UIhttp://<host>:8088

Deployment Targets

flowchart LR
    OCI["One OCI Image<br/><i>multi-stage, non-root</i>"]

    OCI --> Solo["<b>Solo</b><br/>LXC / single VM<br/>~1.5 GiB RAM"]
    OCI --> Team["<b>Team</b><br/>Docker Compose<br/>~6 GiB RAM"]
    OCI --> Ent["<b>Enterprise</b><br/>Helm / K8s<br/>HA, HPA, PDB"]

    Solo --> LXC["LXC / Proxmox"]
    Team --> DC["Docker Compose"]
    Team --> Pod["Podman (rootless) ✓"]
    Ent --> K3s["K3s / Kubernetes"]
    Ent --> OCP["OpenShift"]

    style OCI fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px
TargetStatusProfileCommand
Docker ComposeTestedteamdocker compose up -d
LXC / ProxmoxTestedsolodeploy/lxc/setup.sh
Podman (rootless)Testedteamcurl -sSL https://raw.githubusercontent.com/h3rb3rn/moe-sovereign/main/install.sh | bash
K3s / KubernetesPlannedenterprisehelm install moe charts/moe-sovereign
OpenShiftUntestedenterprisehelm install with openshift.enabled=true

All targets use the same OCI image --- no code forks, no feature loss.


Services

ContainerPortPurpose
langgraph-orchestrator8002Core API (OpenAI + Anthropic compatible)
moe-admin-ui8088Admin: experts, models, users, budgets, knowledge export, system cleanup manager
mcp-precision800327 deterministic tools (math, date, subnet, law)
neo4j-knowledge7474Knowledge graph (GraphRAG)
terra_cache6379Valkey: state, sessions, performance scores
chromadb-vector8001Semantic vector cache
moe-kafka9092Event streaming (ingest, audit, feedback)
terra_checkpoints5432PostgreSQL: user DB, LangGraph checkpoints
moe-prometheus9090Metrics collection
moe-grafana3000Dashboards (GPU, pipeline, infrastructure)

Agent Integration

AgentEndpointConfiguration
Claude Code/v1/messagesexport ANTHROPIC_BASE_URL=https://your-server
Codex CLI/v1/responsesexport OPENAI_BASE_URL=https://your-server
OpenCode/v1/chat/completionsProvider config in config.toml
Aider/v1/chat/completionsexport OPENAI_BASE_URL=https://your-server/v1
Continue.dev/v1/chat/completions or /v1/responsesAdd in .continue/config.json
Open WebUI/v1/chat/completionsAdd as OpenAI-compatible connection

Competitive Landscape

FeatureMoE SovereignPalantir AIPDatabricksGleanCrewAIOllama+WebUI
Multi-expert routing✓✓✓---~---
Deterministic routing✓✓------------
Knowledge graph✓✓~✓------
VRAM-aware scheduling✓------------~
Knowledge export/import✓---------------
Air-gap / fully local✓~------✓✓
Open source✓---~---✓✓
CostFree>$1M/yrPay/DBU$25+/userFreeFree

Note on Palantir comparison: The table above compares technical feature presence, not product maturity or enterprise support depth. Palantir AIP is a commercially mature platform with thousands of engineers, extensive certifications, and a global support organisation. MoE Sovereign is an open-source project addressing the same architectural problem space — with full data sovereignty, zero licence cost, and complete code auditability as its differentiating properties. See Palantir Comparison for a detailed assessment.


Hardware Requirements

ResourceMinimum (solo)Recommended (team)
OSDebian 11+ / Ubuntu 22.04+Debian 13 (trixie)
RAM8 GB16 GB+
CPU4 cores8 cores+
Disk60 GB200 GB+
GPUNone (API-only mode)NVIDIA with CUDA, ≥ 8 GB VRAM
DockerCE 24+Docker CE 27+
+ Enterprise Stack (moe-codex)+ 4 cores, + 8 GB RAM+ 8 cores, + 16 GB RAM

The orchestrator runs on CPU. GPU VRAM is only needed on inference nodes (Ollama). The moe-codex Enterprise Data Stack (NiFi 4 GB, lakeFS 512 MB, Marquez 1.5 GB + 2× Postgres) adds significant overhead — plan a dedicated host or at least 8 GB additional RAM.


Documentation

Full documentation: docs.moe-sovereign.org

SectionContent
Quick StartFirst steps after installation
ArchitectureSystem design, data flow, pipeline
Expert TemplatesTemplate design and LLM routing
Agent ProfilesClaude Code, OpenCode, Aider, Continue.dev
GPU MonitoringNode-exporter + Grafana for inference nodes
Import / ExportTemplates, profiles, and knowledge bundles
DeploymentLXC, Docker, Podman, Kubernetes, OpenShift
API ReferenceFull endpoint documentation
Maintenance & Disk ManagementCleanup Manager, TTL configuration, checkpoint archiving
Palantir ComparisonHonest architectural assessment — where the approaches converge and where the gap remains
Whitepaper (EN)Full technical whitepaper (PDF)
Whitepaper (DE)Vollständiges technisches Whitepaper (PDF)

Local preview: pip install mkdocs-material && mkdocs serve


Publications

DocumentFormatPages
Whitepaper (EN)PDF~60
Whitepaper (DE)PDF~63

Research Basis

The formal logic state layer (capabilities #25–28) is grounded in peer-reviewed mathematical logic research. We gratefully acknowledge the foundational contributions of Prof. A. de Vries, whose unified algebraic hierarchy of logics provides the theoretical framework for paraconsistent, intuitionistic, and fuzzy logic within this system:

A. de Vries, "Algebraic hierarchy of logics unifying fuzzy logic and quantum logic", arXiv:0707.2161 [math.LO], 2007. https://arxiv.org/abs/0707.2161

Additional classical results used: Gödel t-norm (1932), Łukasiewicz t-norm (1920), Kolmogorov algorithmic information content (1965), Chaitin complexity bound (1966), Ratcliff/Obershelp string similarity (1988). Full attribution in docs/ARCHITECTURE.md.


Contributing

See CONTRIBUTING.md for the extension model (MCP tools, expert templates, Admin UI). Please read CODE_OF_CONDUCT.md before opening issues or pull requests.


Disclaimer

MoE Sovereign is a research and productivity tool. AI-generated output may be inaccurate or misleading. Medical and legal expert outputs do not constitute professional advice. All AI output should be verified independently. See PRIVACY.md for data handling details.


License

Apache License 2.0

See THIRD_PARTY_NOTICES.md for bundled component licenses.


Digital sovereignty lived, not preached.

Built on personally purchased consumer hardware. No cloud credits, no institutional funding.

If it works on five second-hand RTX 3060 cards, it works on anything.

moe-sovereign.org •

docs.moe-sovereign.org •

GitHub

Ver o original no GitHub

Bom para

Relacionados