BanzAI — Native Protocol Agent for BANZA

The AI-native protocol agent that guides operators from manifest to federation.

BanzAI is the native AI agent of the BANZA open financial protocol — the official guidance and orchestration layer. It guides operators from manifest to federation, invokes the deterministic Rust/WASM verification engines, explains their results, and helps operators prepare verifiable evidence.

BanzAI is not a normative source, not an authority, not a certifier, not a licence issuer, and not a payment operator. It does not create protocol rules or architectural decisions, does not decide participation, does not approve or certify operators, and does not move funds. Protocol rules become active only through BANZA governance — RFC/ADR, review, merge, release, and publication.

BanzAI guides; engines verify; evidence proves. BanzAI guides the implementation of the existing protocol; it does not create new protocol.

Relationship to BANZA

Concern	Where
Protocol + source of truth	banza-protocol/banza
Public page	banza.network/banzai — maintained in the BANZA repository
Component (this repo)	banza-protocol/banzai
Default provider	mock (deterministic, CI-safe)
Authority	none (non-normative)

Overview

BanzAI is the native protocol agent, not a product and not an authority. It guides operators through the protocol, reads the BANZA corpus, cites its sources, invokes the verification engines, and stays inside a strict non-normative boundary.

The BanzAI test

• If the model disappears, the BANZA protocol remains valid.
• If BanzAI disappears, BANZA loses no normative authority.
• BanzAI depends on BANZA. BANZA does not depend on BanzAI.

What BanzAI does / does not do

Does	Does not do
guide operators from manifest to federation	define or change protocol rules
invoke the deterministic Rust/WASM verification engines	certify · approve · decide participation
retrieve evidence from the BANZA corpus and cite it	act as a normative source or authority
explain protocol rules and engine results (grounded, cited)	issue licences · move funds · run a wallet
help operators prepare verifiable evidence	replace legal / regulatory / KYC-KYB / AML-CFT obligations
report missing / conflicting evidence	replace BANZA governance or the engines
run evals and boundary guards	own a website · serve as a source of truth

How BanzAI answers — the cognitive engine

BanzAI is not a loose chatbot. It is a cognitive engine that turns a question into an evidence-grounded answer, with the AI model as a subordinate language component inside it. The system works across three planes:

• Evidence plane — the BANZA corpus (spec, contracts, conformance, ADRs, RFCs, governance), with manifests, citations and commit/hashes. This is the source of truth.
• Cognitive engine (BanzAI) — the real driver: it detects intent and scope, runs a boundary and authority guard, plans and retrieves evidence, assembles an evidence bundle, asks the model for a draft under evidence control, extracts and verifies claims, passes a safety/authority gate, and assembles the grounded answer.
• AI-model plane — mock (default), Qwen/DeepSeek (optional). Its only job is to draft, summarize and explain. It is never the source of truth, never the verifier, never a governance authority, and never a certifier.

The order matters. The flow is User → BanzAI engine → evidence-controlled drafting → verification → grounded answer — never User → AI model → answer.

1. The cognitive engine is BanzAI itself — the deterministic pipeline that owns intent detection, retrieval, verification and the guards. The model runs inside it, on a leash.
2. Where the model enters — only at the drafting step, after the evidence bundle exists, to phrase an explanation from evidence the engine already retrieved.
3. Why the model is not the source of truth — it has no access to protocol state and no authority; its fluency is not proof. Truth comes from the corpus and the engine's verification.
4. How evidence is retrieved — the retriever reads the BANZA corpus (via contexts/adapters/) anchored to a commit/hash, keeping a citation for every passage.
5. How the draft is generated — the model drafts strictly from the evidence bundle; it does not introduce facts that are not in the bundle.
6. How claims are verified — the engine extracts each claim from the draft and checks it against the evidence; a claim without support is dropped or marked uncertain.
7. How unsupported answers are blocked — if the corpus does not support an answer, BanzAI returns "missing evidence"; it never fabricates a citation.
8. When it returns caveats / uncertainty / governance flags — on ambiguous or conflicting evidence it lowers confidence and surfaces the conflict; for any participation/approval/status question it points to BANZA governance (RFC/ADR, review, merge, release, publication) and never claims to decide, approve, or certify.
9. Providers vs. guarantees — the provider only affects phrasing, never truth. Mock is the default and deterministic; optional adapters are non-authoritative and change no guarantee.
10. Language generation vs. an evidence-grounded answer — a language model can produce fluent text from nothing; a BanzAI answer is text that survived retrieval, verification and the guards, with citations. The two are not the same, and BanzAI only ships the second.

Model output is never evidence. Evidence comes from the BANZA corpus. BanzAI verifies before answering. See docs/ARCHITECTURE.md, docs/EVIDENCE_MODEL.md and docs/BOUNDARIES.md.

Evidence pipeline

The evidence pipeline is the verification core of the engine above — the steps that turn retrieved evidence into a cited, fail-safe answer.

Source of truth = the BANZA corpus at a specific commit/hash. Model output is never evidence. "Missing evidence" is a valid answer; conflicting evidence is surfaced with lowered confidence. See docs/EVIDENCE_MODEL.md.

Provider task profiles and resource policy

BanzAI uses AI models by task profile, not by brand or authority. It does not require two models. Provider selection is task-based; providers only generate candidate outputs.

Models generate candidate outputs. BanzAI verifies outputs. The BANZA corpus provides evidence. BANZA governance decides authority matters — never BanzAI.

• Mock is the default and safest provider (deterministic, CI-safe, no secret, no network).
• Light-language is the preferred profile for normal explanations, summaries, rewriting and translation.
• Technical-heavy is disabled by default and used only for specialised engineering tasks (code, tests, schemas, validators, complex technical analysis).
• GPU endpoints (OpenAI-compatible: Qwen / DeepSeek / any) are configured by environment variables on the server, never committed. Activating a real provider requires BANZAI_PROVIDER_MODE=auto and BANZAI_EXTERNAL_CALLS_ALLOWED=true; heavy additionally requires BANZAI_ALLOW_HEAVY=true.

Profile	Default	Intended use	Examples	Activation	Never does
Mock	✅ yes	deterministic default; CI/demo	any question, offline	none (always available)	call the network; use a secret
Light-language	off	explanation · summary · rewrite · translation · evidence-grounded answers	"explain ADR-026", "summarize this RFC"	auto + EXTERNAL_CALLS_ALLOWED=true + light endpoint	decide truth; certify; verify claims
Technical-heavy	off	code · tests · schemas · validators · technical analysis	"generate an L1 manifest validator"	the above + ALLOW_HEAVY=true + heavy endpoint	mark code "production-ready"; certify; be the verifier
No-model / governance	—	governance/authority questions; missing/out-of-scope	"certify my operator?", no evidence	never calls a model	decide; approve; certify

The router is pure and CI-safe (no external calls), applies the cost policy (minimal by default) and the external-calls / allow-heavy gates, and returns a reason for every choice. See docs/PROVIDERS.md and docs/ARCHITECTURE.md.

Repository structure

_{Diagrams follow the BANZA-compatible diagram style — visually aligned with BANZA, semantically distinct.}

src/       core · retrieval (rag) · verification · providers (mock) · orchestrator · cli
prompts/   system · retrieval · verification · safety · governance
contexts/  adapters (read BANZA corpus) · fixtures (test snapshots) · manifests (source + commit/hash)
evals/     fixtures · expected · reports
docs/      ROLE · ARCHITECTURE · BOUNDARIES · EVIDENCE_MODEL · PROVIDERS · SAFETY · EVALUATION ·
           REPOSITORY_STRUCTURE · diagrams/ · history/
tools/     check-authority · check-provider · check-boundaries · check-links · check-diagrams ·
           build-index · validate-evidence
infra/local/  local/dev only

Full detail: docs/REPOSITORY_STRUCTURE.md.

Public interface boundary

This repository does not ship or deploy a website. The public /banzai page is maintained in the BANZA repository (banza-protocol/banza); its current runtime is mock/pre-production. BANZA may consume this component in the future, but no runtime coupling is activated here.

Participation is by evidence, not by approval. Operators demonstrate compatibility by publishing verifiable evidence; peers verify that evidence locally before interoperating. There is no central authority that approves, certifies, or admits operators — BanzAI guides operators to produce and check this evidence, but does not grant participation.

Development

npm ci
npm run typecheck --workspaces --if-present
npm run build --workspaces --if-present
npm run test --workspaces --if-present     # deterministic, mock provider, no secrets
make authority-check provider-check boundary-check links-check diagrams-check

Security

No secrets are required or committed; the mock provider is the default; external providers are explicit and opt-in. Report vulnerabilities privately — see SECURITY.md.

License

See LICENSE.