README.md
Rama develop · réplica de lectura del repositorio original.
# HUF
**Open-source AI infrastructure for any app. Build multi-agent solutions, automate AI-driven deterministic workflows, and keep your data under your control.**
HUF is a complete, self-hosted AI layer built on open standards. It gives teams everything needed to create intelligent multi-agent solutions, ground them in real data, execute secure code sandboxes, manage multi-channel communication gateways, and orchestrate complex workflows — without sending data to third-party platforms or rebuilding infrastructure from scratch.
[**Documentation**](https://docs.huf.ai/) | [**Report Issue**](https://github.com/tridz-dev/huf/issues) | [**Discussions**](https://github.com/tridz-dev/huf/discussions)
<br/>
<img width="1905" height="928" alt="HUF Dashboard" src="./huf/public/Images/HUF Agent Home.png" />
<br/>
> **Note:** HUF is under active development.
---
## Why HUF
AI adoption inside organizations is fragmented:
- **Knowledge lives in too many places** — scattered across docs, databases, and people's heads
- **Automation is rigid and rule-based** — breaks on edge cases, requires constant maintenance
- **AI tools operate in isolation** — each team rebuilds similar assistants and prompt integrations
- **Execution lacks safety & governance** — unmonitored script execution and data flowing outside your control
HUF exists to **centralize intelligence, execution, and communication** into a single, self-hosted engine — so AI can be trusted to operate inside real business systems without compromising data ownership or security.
**Key principles:**
- **Open source and self-hosted.** Your agents, your data, your infrastructure. Nothing leaves your servers unless you decide it should.
- **Local model support.** Connect to Ollama, LM Studio, or any OpenAI-compatible local endpoint alongside cloud providers.
- **Pluggable execution environments.** Run agent tools locally, in isolated virtualenvs, over SSH, or inside Docker containers.
- **No-code visual control with code-level depth.** Visual flow builders, agent configuration, and multi-channel gateways alongside hardened Python code execution sandboxes.
- **Built-in data governance.** Role-based permissions, execution profiles, full audit trails, and cost/cache analytics give complete visibility.
---
## What HUF Does
HUF is the **core AI infrastructure layer** inside an organization or product, not a surface-level chatbot or a single-purpose assistant.
**One engine. Multiple ways to use it.**
| Capability | What it enables |
|------------|-----------------|
| **Universal AI Access** | Connect to major cloud providers or local models — with unified routing and open-router free tier seeding |
| **Intelligent Agents & Memory** | Build autonomous agents with custom instructions, role permissions, and persistent scoped memory |
| **Execution Profiles & Sandboxing** | Execute code tools safely in local venvs, direct SSH backends, Frappe SSH connections, or Docker containers |
| **Multi-Channel Gateways** | Connect agents directly to Email/Gmail, Telegram, Slack, WhatsApp, and Webhooks |
| **Knowledge Grounding** | Hybrid search via FTS5 BM25, ChromaDB vector, pgvector (PostgreSQL), and custom Data Tables |
| **Skills & Apps Ecosystem** | Package agent capabilities, prompt templates, tools, and MCP servers into reusable skills and Huf Apps |
| **Event-Driven Automation** | Trigger agents on document lifecycle events, cron schedules, or inbound webhooks |
| **Visual Flow Builder** | Design complex multi-step workflows with React Flow / XYFlow, router nodes, and Human-in-the-Loop (HITL) approval gates |
| **Managed Integrations & MCP** | Connect to external platforms via Model Context Protocol (MCP) and managed OAuth credentials |
| **Full Observability & Analytics** | Detailed execution traces (`/executions/:runId`), context usage, prompt caching analytics, and token/cost rollups |
---
## Use HUF As
### AI Infrastructure for Products
Use HUF as the **backend AI engine** for products that need intelligence, automation, execution sandboxing, and integrations.
**Ideal for:**
- AI-first startups building on Frappe/ERPNext
- SaaS products adding AI capabilities and copilots
- Platforms needing agent orchestration, cost control, and full execution auditability
---
### Internal Intelligence Platform
Use HUF to power **internal AI experiences** grounded in company knowledge and business databases.
**Build:**
- Internal chat systems grounded in internal documents and live ERP data
- Role-based assistants for Operations, HR, Sales, and Support
- Automated email/messaging triage assistants connected via Multi-Channel Gateways
---
### Automation & Multi-Agent Orchestration Engine
Use HUF to build **AI-driven workflows** that reason, execute code, and act across systems.
**Suited for:**
- Multi-step business processes with conditional routing and Human-in-the-Loop approvals
- Code-execution tasks running in isolated SSH or Docker environments
- Cross-tool automation with automated retry, fallback, and error handling
---
### Embedded AI Layer for SaaS
Use HUF to **embed AI capabilities directly into products** without building custom backend infrastructure.
**Enable:**
- In-app copilots and interactive assistants
- Customer-facing AI features with strict role-based access rules
- Vertical AI capabilities with isolated execution sandboxes and cost governance
---
## Core Capabilities
### Agent System & Scoped Memory
Create AI agents with tailored instructions, tool access, execution profiles, and memory retention policies:
- **CRUD Operations** — Read, create, update, delete any Frappe document out of the box
- **Scoped Memory System** — Persistent agent memory policies and per-agent memory records that persist facts across runs
- **Custom Functions & Tools** — Connect Python functions, HTTP endpoints, or client-side tools
- **Agent Chaining & Multi-Agent Teams** — Async message passing between agents and orchestrators
- **Role-Based Permissions** — Fine-grained capability gating for agents, tools, data tables, and MCP servers
- **Prompt Caching & Analytics** — Reduce latency and token costs with automated prompt cache tracking
### Execution Profiles & Code Sandboxing
Safely run Python code tools and commands with environment isolation and strict security controls:
- **Pluggable Execution Profiles** — Choose between Local Python, Isolated Venv, Direct SSH, Frappe SSH Connection, or Docker container runners
- **Hardened Code Sandbox** — Import allowlisting and AST inspection prevent unauthorized system access or unsafe imports
- **Remote Host Execution** — Run long-running analysis or heavy data tasks on remote SSH hosts or containerized execution backends
- **Execution Management UI** — View, create, test, and audit execution profiles and SSH connections directly from the UI
### Skills & Huf Apps
Organize AI capabilities into modular, reusable packages:
- **Skills Catalog** — Combine system prompts, tools, knowledge sources, and MCP configurations into shareable skills
- **Huf Apps** — Package complete agentic applications (agents, flows, data tables, skills) into installable Huf Apps
- **App Discovery** — Automatically discover and register installed apps and skill dependencies
- **Official Skills Catalog** — [`tridz-dev/huf-skills`](https://github.com/tridz-dev/huf-skills) is the curated, official collection of skills for Huf agents, and the default source in skill settings
- **Coding Agent Skill** — [`tridz-dev/huf_app_skill`](https://github.com/tridz-dev/huf_app_skill) helps AI coding agents (Claude Code, Codex, Cursor, OpenCode, Kimi) build Huf Apps. Clone it and run `./install.sh` from the repo directory, as described in its README
### Multi-Channel Gateways
Connect your agents to inbound and outbound communication channels:
- **Supported Channels** — Gmail / Email, Telegram, Slack, WhatsApp, and custom HTTP Webhooks
- **Access & Binding Rules** — Control which users or external senders can invoke specific agents or flows
#### Telegram
- Webhook gateway with pairing-first access, text/media/voice in and out, buttons, and edit-in-place
- Group addressing by mention, forum threads, bot-to-bot loop guard, and guest mode
- Message templates (text, variables, media, buttons) managed on the Templates tab and sent by agents
- Agent reply blocks: `telegram-buttons` (inline and reply keyboards) and `telegram-media` (photos, files, locations, polls)
- Agent tools: `telegram` (send, edit, forum, template and chat actions) and `telegram_admin` (group admin, bot profile, business), both gated per gateway
- Business (Secretary) mode is observe-only by default; Draft sends a reply to the owner for approval first
- Group join requests: Queue, Decline or Agent, with an optional Guard Mini App captcha
- Streaming replies (private chats) follow the Gateway `telegram_streaming` checkbox
- Admin Mini App at `/huf/tg-app`; owner/admin cockpit in private chats with signed buttons, confirm-before-write, and audit rows
- Setup, troubleshooting, known gaps and a live test checklist: `docs/gateways/telegram-runbook.md`; cockpit design: `docs/gateways/telegram-admin-cockpit.md`
- **Event-Driven Messaging** — Inbound messages trigger agent runs; responses route back to the original channel automatically
### Knowledge Grounding
Ground AI responses in real business knowledge and structured databases:
- **Multi-Backend Search** — Full-text search (SQLite FTS5 / BM25), semantic vector search (ChromaDB), and PostgreSQL vector search (pgvector)
- **Input Sources** — Raw files, text snippets, web URLs, Frappe DocTypes, and custom Data Tables
- **Automatic Chunking** — Intelligent document segmentation with configurable chunk sizes and overlap
### Data Tables
Create and manage custom structured datasets directly inside HUF:
- **Visual Table Editor** — Build tables, edit schemas, and manage rows via the web UI
- **Agent Integration** — Use tables directly as knowledge inputs or structured data tools
- **Dynamic Columns** — Flexible fields without requiring database schema migrations
### Trigger System
Run agents automatically based on real-time events:
- **Document Events** — `after_insert`, `on_submit`, `on_cancel`, `on_update`
- **Schedules** — Flexible cron expressions and interval schedules
- **Webhooks** — Authenticated HTTP endpoints for external webhooks
- **Conditional Logic** — Python expressions to evaluate execution conditions before running
### Visual Flow Builder
Design complex workflows through a modern React Flow / XYFlow visual canvas:
- **Drag-and-Drop Canvas** — Connect triggers, agents, router/orchestrator nodes, conditions, and HTTP actions
- **Human-in-the-Loop (HITL)** — Built-in approval gates that pause flow execution until a human approves or rejects
- **Execution Tracking** — Trace flow execution step-by-step with status, input/output data, and error logs
### Managed Integrations & MCP Client
Connect agents to external software and services:
- **MCP Client** — Connect Model Context Protocol (MCP) servers (Slack, GitHub, Gmail, Filesystem, Postgres, etc.)
- **Managed Credentials** — Encrypted per-service credential management with OAuth support
- **Integration Services & Recipients** — Map integration tools and notifications to specific users or teams
### Models & Providers
Connect to any AI provider or run local models on private hardware:
- **Cloud Providers** — OpenAI, Anthropic, Google Gemini, Groq, Mistral, OpenRouter (with seeded free models), Moonshot, and more
- **Local Endpoints** — Ollama, LM Studio, or any OpenAI-compatible local API
- **Unified Routing** — LiteLLM integration layer handles model parameter mapping and fallbacks seamlessly
#### Provider support & LiteLLM version policy
HUF routes all chat/completion inference through [LiteLLM](https://docs.litellm.ai/docs/providers), so any provider that LiteLLM supports can be used. The curated **Provider Brand** list in the AI Provider DocType is used for UI labels and logos; if a provider is not in the catalog, use **Other / Custom** and enter the model as LiteLLM expects it (e.g. `someprovider/model-name`).
Version constraints in `pyproject.toml`:
```toml
litellm>=1.74.7,!=1.82.7,!=1.82.8,<1.83.8
```
- `>=1.74.7` ensures providers such as **Moonshot AI** are present in LiteLLM’s provider registry.
- `!=1.82.7,!=1.82.8` excludes the compromised PyPI releases from March 2026.
- `<1.83.8` caps the version because LiteLLM `1.83.8+` restricts installs to Python `<3.14`, and `1.90+` builds the `litellm-rust` extension with PyO3 that currently only supports up to Python 3.13. Frappe v16 requires Python 3.14, so newer LiteLLM releases cannot be installed cleanly until LiteLLM ships Python 3.14-compatible wheels ([upstream issue](https://github.com/BerriAI/litellm/issues/33116)).
Regional or self-hosted endpoints can be configured via the **API Base URL** field on any AI Provider, including hosted providers such as Moonshot China (`https://api.moonshot.cn/v1`).
### Observability & Analytics
End-to-end visibility into every AI operation:
- **Execution Trace View (`/executions/:runId`)** — Inspect complete run traces, prompt segments, tool inputs/outputs, and error stacks
- **Context & Cache Analytics** — Dedicated links from chat messages directly to run analytics showing token distribution and prompt cache hits
- **Cost Rollups** — Real-time tracking of token usage and financial cost across models, users, and teams
- **User Feedback & Auditing** — Ratings, feedback logs, and full conversation history
---
## Roadmap
Upcoming capabilities in active development:
| Capability | What it enables |
|------------|-----------------|
| **Frappe Cloud Self-Provisioning** | Automated bench and site lifecycle management for deploying HUF on Frappe Cloud |
| **Desk AI Super-Assistant** | In-desk AI assistant for Frappe/ERPNext forms, navigation, and automated document actions |
| **Voice & Realtime Audio** | Native streaming voice capabilities for real-time conversational agents |
| **File-Based Agent Declaration** | Declarative YAML/JSON agent configuration for app developers |
| **Advanced Multi-Agent Swarms** | Autonomous graph routing and parallel agent dispatching |
---
## Quick Start
### Try with Docker
```bash
git clone https://github.com/tridz-dev/huf.git
cd huf/docker
docker compose up
```
Open http://localhost:8000 and login:
- **User:** Administrator
- **Password:** admin
### Install on Existing Bench
```bash
bench get-app git@github.com:tridz-dev/huf.git
bench install-app huf
bench setup requirements
bench restart
```
---
## Architecture at a Glance
```
┌──────────────────────────────────────────────────────────────────────────────────────────┐
│ HUF Platform │
├──────────────────────────────────────────────────────────────────────────────────────────┤
│ SURFACES & GATEWAYS │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ Chat UI │ │ API / PWA │ │ Flow Builder │ │ Gateways │ │ Huf Apps │ │
│ │ (Studio/PWA) │ │ Endpoints │ │ (React Flow) │ │(Email/TG/Slack│ │ & Extensions│ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬──────┘ │
├─────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┼────────┤
│ CORE ENGINE │
│ ┌────────────────────────┐ ┌────────────────────────┐ ┌───────────────────────────┐ │
│ │ Agent Core │ │ Flow Engine │ │ Trigger System │ │
│ │ Instructions | Memory │ │ Visual Canvas | Router │ │ Document Events | Schedules │ │
│ │ Role Permissions │ │ HITL Approval Gates │ │ Webhooks | Conditions │ │
│ └───────────┬────────────┘ └───────────┬────────────┘ └─────────────┬─────────────┘ │
├──────────────┼───────────────────────────┼─────────────────────────────┼─────────────────┤
│ EXECUTION, KNOWLEDGE & TOOLS │
│ ┌────────────────────────┐ ┌────────────────────────┐ ┌───────────────────────────┐ │
│ │ Execution Profiles │ │ Knowledge Layer │ │ Integrations & MCP │ │
│ │ Local | SSH | Docker │ │ FTS5 | ChromaDB │ │ MCP Client | Credentials │ │
│ │ Hardened Code Sandbox │ │ pgvector | DataTables │ │ Integration Services │ │
│ └───────────┬────────────┘ └───────────┬────────────┘ └─────────────┬─────────────┘ │
├──────────────┼───────────────────────────┼─────────────────────────────┼─────────────────┤
│ FOUNDATION & OBSERVABILITY │
│ ┌────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ LiteLLM Unified Model Router │ │
│ │ Cloud (OpenAI/Anthropic/Gemini) | Local (Ollama/LM Studio) │ │
│ ├────────────────────────────────────────────────────────────────────────────────────┤ │
│ │ Observability & Execution Analytics │ │
│ │ Run Traces (/executions/:runId) | Prompt Cache Hits | Cost Rollups │ │
│ └────────────────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────────────┘
```
---
## Tech Stack
| Layer | Technology |
|-------|------------|
| **Backend** | Frappe Framework, Python 3.10+ |
| **AI Integration & Routing** | LiteLLM (cloud providers + local models) |
| **Execution Sandboxing** | Local Python, Isolated Venv, Direct SSH, Frappe SSH, Docker Containers |
| **Multi-Channel Gateways** | Email/Gmail, Telegram, Slack, WhatsApp, Webhooks |
| **Knowledge & Search** | SQLite FTS5 (BM25), ChromaDB (Vector), pgvector (PostgreSQL Vector) |
| **Frontend** | React 18, TypeScript, Tailwind CSS, Vite |
| **Flow Builder** | React Flow / XYFlow |
| **Database** | MariaDB |
---
## Security Notice
**HUF uses LiteLLM as a dependency for AI provider routing.** On March 24, 2026, the LiteLLM team disclosed that PyPI releases `1.82.7` and `1.82.8` were compromised — both contained a malicious `.pth` startup payload injected into the package.
HUF was affected as a downstream consumer. We responded immediately:
- Blocked both compromised versions in our dependency constraints (`litellm>=1.74.7,!=1.82.7,!=1.82.8,<1.83.8`)
- Added install-time detection in `huf/install.py` — if a compromised version is already present in your environment, HUF will surface a critical alert on startup
If you are running either of those LiteLLM versions, upgrade immediately.
Upstream incident thread: https://github.com/BerriAI/litellm/issues/24518
---
## Documentation
- [**Full Documentation**](https://docs.huf.ai/) — Guides, tutorials, and API reference
- [**Bruno API Collection**](./api-docs/bruno/) — Ready-to-use API collection for testing and exploration
- [**AGENTS.md**](./AGENTS.md) — Technical context for AI agents. Adopts the [agents.md](https://agents.md) standard.
- [**CLAUDE.md**](./CLAUDE.md) — Defines coding standards, review criteria, and project-specific rules.
- [**huf_app_skill**](https://github.com/tridz-dev/huf_app_skill) — An AI coding agent skill (Claude Code, Codex, Cursor, OpenCode, Kimi) that scaffolds new Huf Apps or external HUF API clients through a guided plan-then-build flow.
---
## Research
- Erooth, S. (2026). *Don't Retry Blind: Recovering from Partial Side Effects in Agent
Procedures*. Zenodo. https://doi.org/10.5281/zenodo.22945662
---
## License
MIT License — see [LICENSE](./LICENSE) for details.
---
<p align="center">
<strong>Built for teams who want AI that actually works.</strong>
</p>