Docs · v0.0.1 · MIT

Documentation

Bela is an app-scoped, self-training agent engine. You declare your entities and tools in one config file, it trains its own intent classifier and slot tagger from scratch — in about a second on one CPU core — and then executes short commands against the functions you registered. Everything below is generated from the markdown docs in the repository, which stay the source of truth.

Quickstart

Three steps: scaffold a config, fill in your real entities and tools, train. The CLI is the recommended path — it wraps trainModel/saveModel with an accuracy gate, so a config change that tanks model quality can't silently ship a bad artifact.

terminal — from zero to a trained model

# 1. scaffold a starter agent.tools.mjs
bela init ./my-agent

# 2. write your real entities and tools
$EDITOR ./my-agent/agent.tools.mjs

# 3. train — saves only if it clears the quality gate
bela train --config ./my-agent/agent.tools.mjs --out ./my-agent/bela-model.json
intentAcc=0.9891 slotExact=1.0000 testCount=92
saved model to ./my-agent/bela-model.json

# optional: re-check a saved artifact any time
bela eval --config ./my-agent/agent.tools.mjs --model ./my-agent/bela-model.json

The unedited starter config (two entities, two tools) already clears the default gate — intentAcc>=0.9, slotExact>=0.8 — out of the box. Note: @bela/cli isn't on npm yet, so there is no npx bela … today; inside the monorepo the same init/train/eval functions run under npx tsx. See the CLI reference.

Then wire the agent into your app — one config, one call per message:

app.ts — load the model, handle a command

import { defineAgent, createAgent } from "@bela/core"
import { loadModel, makeFallback } from "@bela/model"

const config = defineAgent({ entities, tools })
const model  = loadModel("./bela-model.json")
const agent  = createAgent(config, { fallback: makeFallback(model, 0.6) })

await agent.sync()                      // pull fresh entity rows
const outcome = await agent.handle(text, { userId: "u1", role: "manager" })
// branch on outcome.type: executed | need_slot | ambiguous | confirm
//                          cancelled | denied | unknown | error

Full walkthrough — entities, tools, outcomes, sessions, roles, audit, corrections — in the integration guide.

The guides

Guide

Integration

Wire Bela into your own app: install, define entities and tools, create the agent, handle every outcome type in a chat UI, write good utterances, enable the neural fallback, and teach it with corrections.

Read the guide →

Reference

CLI

Every flag, default, behaviour and exit code for bela init, bela train, bela eval and bela help — plus a real worked session and the .mjs vs. TypeScript config note.

Read the reference →

In production

Case study — Tabarak

A live hotel & restaurant platform in Pakistan gained a bilingual natural-language operator in roughly one working day: 25 tools, 5 entities, distillation, memory, and a 9/16 → 15/16 human test set.

Read the case study →

Paper

Whitepaper

The full argument: why hosted LLMs fail small business apps on cost, privacy, reliability and fit; the architecture; measured results; the safety model; an honest comparison; and the roadmap.

Read the whitepaper →

Read the whitepaper Download PDF ↓

What Bela is (and isn't)

Bela is not a chatbot and not a better LLM — it is an action executor of a different shape. It reads one short command, resolves it against your app's real data, calls a function you registered, and replies with one short line. It does no open-ended conversation and knows nothing outside your application.

	Bela	Cloud-LLM agent
Marginal cost per command	Zero	Per token
Infrastructure	$4–12/mo CPU VPS	API account, or a GPU
Works offline	Yes	No
Data leaves your server	Never	Every request
Latency	Sub-millisecond	300 ms – several seconds
Open-ended conversation	No	Yes
Reasoning over novel situations	No	Yes
Multi-step planning	No	Yes

If your users need to converse, reason about things outside the app, or chain several unplanned steps — use an LLM. If they need to fire a known action fast, safely, cheaply and offline, Bela is the smaller and stronger tool. The full row-by-row comparison lives in the whitepaper.