convez.ai
MCP ServerAutomaçãoAvançado
ebongard

Renfield

ebongard/renfield

Assistente IA descentralizado com voz local e 100+ integrações

Ver no GitHub
InicialPluginScore · de 0 a 100

Assistente de IA auto-hospedado com satélites de voz, 100+ integrações de ferramentas e capacidade totalmente offline. Construído com FastAPI, React e Ollama, oferece agente ReAct com cadeia de ferramentas, base de conhecimento RAG, detecção de presença e gerenciamento de salas.

Instalação

$npx convez-ai ebongard/renfield

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
47
Forks
7
Acompanhando
1
Saúde
—
Último commit
há 1 dia
Versão
v2.24.0
Issues abertas
38
Contribuidores
2

Casos de uso

  • Assistente de voz doméstico totalmente offline com múltiplos satélites (Raspberry Pi)
  • Automação residencial integrada com Home Assistant e DLNA
  • Sistema de conhecimento com RAG para documentos e memória de longo prazo

Veredito

Renfield é uma solução robusta para quem deseja privacidade e controle total da IA doméstica. Arquitetura sofisticada com agente ReAct, múltiplos LLMs locais e voz distribuída — exige conhecimento técnico significativo mas oferece autonomia completa.

README

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

English | Deutsch

Renfield

Self-hosted AI assistant with voice satellites, 100+ tool integrations, and full offline capability.

Python 3.11 FastAPI React 18 Ollama License: MIT Tests


Why Renfield?

  • Voice-first with physical satellites — Raspberry Pi Zero 2 W + ReSpeaker HAT in every room (~$30/satellite). Wake word, STT, TTS — fully local.
  • 10 MCP servers, 100+ tools, Agent Loop — Weather, search, news, calendar, smart home, media, DLNA, documents, email, workflows. ReAct agent chains tools autonomously for complex queries.
  • Fully offline, self-hosted, GDPR-friendly — Runs entirely on your hardware. No cloud dependencies. Your data never leaves your network.

Screenshots

Features

Core

  • Chat interface with streaming responses, conversation history, inline album art, collapsible agent steps
  • ReAct Agent System with specialized roles, multi-step tool chaining, and media transport shortcuts
  • Knowledge Graph — entity-relation triples with post-extraction validation, string-similarity dedup, and bulk cleanup API
  • Conversational memory — long-term recall of preferences, facts, and instructions with contradiction detection
  • Intent feedback learning — learns from corrections via semantic matching (3-scope: intent, tool, complexity)
  • Voice I/O — Whisper STT + Piper TTS + SpeechBrain speaker recognition
  • Presence detection — BLE scanning, voice recognition, and web auth track who's in which room
  • Proactive notifications — webhook-based alerts from Home Assistant/n8n + generic MCP notification polling
  • Paperless audit — automated LLM-based metadata validation with review queue, OCR quality scoring, and auto-fix
  • Hook/Plugin system — async extension API for custom integrations without modifying core

Integrations (10 MCP Servers)

ServerDescriptionTransport
WeatherOpenWeatherMap forecastsstdio
SearchSearXNG metasearchstdio
NewsNewsAPI headlinesstdio
CalendarExchange, Google, CalDAV (multi-account)stdio
JellyfinMedia server queriesstdio
DLNAMedia renderer control with gapless queuestreamable_http
n8nWorkflow automationstdio
Home AssistantSmart home controlstreamable_http
PaperlessDocument managementstdio
EmailIMAP/SMTPstdio

Knowledge Base (RAG)

  • Hybrid search — dense embeddings (pgvector) + BM25 full-text (German FTS, OR matching), combined via RRF
  • Formats — PDF, DOCX, PPTX, XLSX, HTML, Markdown, TXT (with EasyOCR fallback for garbled PDFs)
  • Knowledge bases — thematic collections with sharing and access control
  • Agent tool — knowledge_search for combined RAG + Paperless search within the agent loop
  • Knowledge Graph — entity-relation triples with post-extraction validation, string-similarity dedup, bulk cleanup API, admin dashboard

Multi-Room Voice Satellites

ComponentCost
Raspberry Pi Zero 2 W~$18
ReSpeaker 2-Mics Pi HAT~$12
MicroSD, power supply, speaker~$28
Total per room~$58
  • Local wake word detection (OpenWakeWord)
  • Audio output routing to best device per room (Renfield, HA, DLNA)
  • IP-based room context detection

Presence Detection

Multi-source room-level presence tracking:

SourceTriggerLatency
BLE ScanningSatellite detects phone/watch via Bluetooth~30s (hysteresis)
Voice PresenceSpeaker recognition identifies userInstant
Web AuthAuthenticated user on room-assigned deviceInstant
  • Privacy-aware TTS — notifications respect room occupancy (public / personal / confidential)
  • Automation hooks — enter_room, leave_room, first_arrived, last_left events fire webhooks for n8n / Home Assistant
  • Presence dashboard — real-time room occupancy in the admin UI

Security & Access Control

  • Role-permission based access control (RPBAC) with JWT
  • Rate limiting, circuit breakers, trusted proxy support
  • Docker secrets management for production

Platform

  • Progressive Web App (desktop, tablet, mobile)
  • Dark mode (light, dark, system)
  • Multilingual (German, English)
  • Prometheus metrics (opt-in)

Quick Start

git clone https://github.com/ebongard/renfield.git && cd renfield
cp .env.example .env                          # configure your settings
docker compose up -d                          # start the stack
docker exec -it renfield-ollama ollama pull qwen3:8b  # download LLM

Open http://localhost:3000 and start chatting.

For GPU acceleration, use docker compose -f docker-compose.prod.yml up -d with NVIDIA Container Toolkit.

Architecture

Configuration

All settings via .env, loaded by Pydantic Settings. See docs/ENVIRONMENT_VARIABLES.md for the full reference.

LLM (Multi-Model)

Separate models for different tasks:

OLLAMA_URL=http://ollama:11434
OLLAMA_CHAT_MODEL=qwen3:14b       # chat responses
OLLAMA_INTENT_MODEL=qwen3:8b      # intent recognition
OLLAMA_RAG_MODEL=qwen3:14b        # RAG answers
OLLAMA_EMBED_MODEL=nomic-embed-text  # embeddings (768 dim)

Key Settings

AGENT_ENABLED=false               # ReAct agent loop (opt-in)
MEMORY_ENABLED=false              # long-term memory (opt-in)
AUTH_ENABLED=false                 # RPBAC auth (opt-in)
MCP_ENABLED=true                  # master switch for integrations
PRESENCE_ENABLED=false            # room presence detection (opt-in)
KNOWLEDGE_GRAPH_ENABLED=false     # entity-relation extraction (opt-in)
NOTIFICATION_POLLER_ENABLED=false # proactive MCP notifications (opt-in)
METRICS_ENABLED=false             # Prometheus /metrics (opt-in)

Development

make lint                    # lint all code (ruff + eslint)
make test                    # all tests
make test-backend            # backend tests (3,400+)
make test-frontend-react     # React tests (Vitest + RTL)
make test-coverage           # tests with coverage report

See CONTRIBUTING.md for the full development guide.

Docker Compose Variants

FileUse CaseGPU
docker-compose.ymlStandardNo
docker-compose.dev.ymlDevelopment (Mac)No
docker-compose.prod.ymlProductionNVIDIA
docker-compose.prod-cpu.ymlProductionNo

Documentation

DocumentContent
CONTRIBUTING.mdHow to contribute
docs/FEATURES.mdDetailed feature documentation
docs/ENVIRONMENT_VARIABLES.mdFull configuration reference
docs/DEPLOYMENT.mdDeployment guide
docs/SECRETS_MANAGEMENT.mdDocker secrets for production
docs/SECURITY.mdSecurity headers, CSP, dependency security
docs/ACCESS_CONTROL.mdRole-based access control & MCP permissions
docs/SPEAKER_RECOGNITION.mdSpeaker recognition
docs/OUTPUT_ROUTING.mdAudio output routing
docs/PROACTIVE_NOTIFICATIONS.mdWebhook notifications & proactive alerts
docs/MULTILANGUAGE.mdInternationalization (i18n)
docs/WAKEWORD_CONFIGURATION.mdWake word detection setup
docs/EXTERNAL_OLLAMA.mdExternal Ollama instances
docs/SATELLITE_MONITORING.mdSatellite monitoring
docs/SATELLITE_OTA_UPDATES.mdSatellite over-the-air updates
docs/AUDIO_CAPTURE_4MIC.mdReSpeaker 4-Mic array support
CLAUDE.mdDeveloper reference (architecture, patterns)

Disclaimer

Renfield is an independent open-source project. It is not affiliated with, endorsed by, or connected to any third party, organization, company, or brand with the same or similar name.

Acknowledgments

License

MIT License — see LICENSE file.

Contributing

Contributions are welcome! Please read our Contributing Guide and check the good first issues.

Ver o original no GitHub

Bom para

Relacionados