BanzAI

The AI-native knowledge, reasoning, and verification layer for the BANZA Open Financial Protocol.

Explore specifications, ADRs, RFCs, contracts, certification requirements and protocol invariants — with grounded answers, canonical citations, and an explicit verification pass over a two-model cognitive architecture (Qwen + DeepSeek).

Models explain and verify; evidence decides.

Protocol	github.com/banza-protocol/banza
Knowledge System	github.com/banza-protocol/banzai — this repository
Documentation	docs/banzai/
Public interface	banza.network/banzai

---

Architecture at a glance

BanzAI uses Qwen and DeepSeek as independent reasoning and verification engines. The source of truth is the BANZA protocol corpus, not the models.

The detailed walkthrough of every stage follows below.

---

What BanzAI is

BanzAI is the AI-native knowledge, reasoning, and verification layer for the BANZA protocol. It helps users understand protocol rules, retrieve the relevant evidence, check claims against that evidence, and inspect certification and conformance material — with canonical citations.

It does not replace the protocol, the conformance suite, the BANZA CA, or governance. It turns published protocol knowledge into grounded, traceable answers for operators, developers, auditors and regulators.

BANZA     = Open Financial Protocol       (defines)
BANZA CA  = Certification Authority       (certifies)
Operators = Independent implementations   (implement)
BanzAI    = Knowledge / reasoning / verification layer (explains & verifies)

What BanzAI is not

• BanzAI is not an operator.
• BanzAI is not BANZA (the protocol).
• BanzAI is not a commercial operator, nor the reference operator.
• BanzAI does not process payments or hold funds.
• BanzAI does not certify operators by itself.
• BanzAI does not replace human governance.
• BanzAI does not treat model memory as truth.
• BanzAI does not create regulatory approval.
• BanzAI does not prove production readiness.

BanzAI is an adjacent system: BANZA is complete and valid without it.

Capabilities

BanzAI runs alongside the protocol to provide:

• Knowledge search — grounded Q&A over all BANZA specification documents, with citations
• RFC / ADR navigation — find and explain the decisions and proposals that govern the protocol
• Trace explanation — explain payment traces against the protocol's invariants
• Protocol graph — explore relationships between ADRs, RFCs, contracts and invariants
• Research assistance — multi-source analysis of protocol questions
• Certification assistance — explain certification criteria and help operators prepare
• Developer assistance — explain contracts, schemas and integration rules with canonical references

Source of truth

The source of truth is the BANZA protocol corpus, never model memory:

• RFCs
• ADRs
• contracts
• schemas
• invariants
• certification rules
• conformance reports
• signed evidence
• governance records

The models are reasoning and verification tools, not truth sources. When anything disagrees with the protocol repository, the protocol repository wins.

Models explain and verify; evidence decides.

Why two models?

BanzAI deliberately separates reasoning from verification. A single model can produce a fluent, coherent explanation while silently missing a contradiction or citing the wrong source. So BanzAI uses two independent cognitive engines:

• one model reasons and explains;
• a second, independent model verifies — critiques the explanation, checks citations, and looks for unsupported claims.

Disagreement between the two is not resolved by majority vote. It is a signal to inspect the underlying evidence more deeply, lower confidence, and — where it cannot be resolved from evidence — surface the disagreement and recommend human/governance review.

Model A — Qwen (reasoning engine)

Qwen is the reasoning engine (routed as Qwen 14B for protocol reasoning, and Qwen Coder for implementation/code questions). Its role:

• protocol interpretation and step-by-step reasoning
• explanation synthesis from retrieved evidence
• answer drafting and user-facing reformulation
• educational explanation

Qwen is not authoritative. It produces an interpretation that must be verified against the evidence before it is returned.

Model B — DeepSeek (verification engine)

DeepSeek is the verification / deep-reasoning engine. Its role:

• contradiction detection
• citation checking (does the citation point to the right source?)
• protocol-rule consistency checking
• conformance of each claim with the retrieved evidence
• confidence assessment
• boundary enforcement (neutrality, authority, honest claims)

DeepSeek is not authoritative either. It does not "know" the answer — it checks claims against evidence.

End-to-end pipeline

#	Step	Input	Output	Failure mode	Safeguard
1	User question	raw question	normalized intent	ambiguous question	ask to clarify / widen retrieval
2	Query normalization	question	search query + task type	wrong routing	routing rules (prompts/routing.md)
3	Evidence retrieval	query	candidate evidence	nothing retrieved	report "no evidence found"
4	Evidence bundle	candidates	grounded context	thin/partial context	mark low confidence
5	Qwen reasoning pass	bundle	draft explanation	plausible-but-unsupported	sent to verification, never returned directly
6	DeepSeek verification pass	draft + bundle	verdicts	model overconfidence	claim-by-claim evidence check
7	Claim-by-claim checking	each claim	supported / unsupported	unsupported asserted as fact	drop or mark uncertain
8	Citation validation	citations	valid / invalid	wrong source cited	reject citation
9	Conflict detection	bundle + claims	conflicts surfaced	silent resolution	expose the conflict
10	Confidence assignment	verdicts	confidence state	false certainty	confidence = evidence quality, not model certainty
11	Response construction	verified claims	answer + sources + references	losing citations	citations attached per claim
12	Boundary statement	answer	answer + limits + gaps	overclaim	explicit limits + unresolved gaps

Evidence retrieval layer

BanzAI retrieves only from published protocol knowledge:

• RFCs · ADRs · contracts · schemas · invariants · certification rules · conformance reports · operator evidence where provided.

Rules:

• If evidence is missing, BanzAI must say it is missing.
• If a claim is not supported, BanzAI must not present it as fact.
• If the corpus conflicts, BanzAI must expose the conflict, never silently resolve it. "I don't know" is a valid answer.

Verification logic

The verification engine checks, for each answer:

• whether each claim has supporting evidence;
• whether citations point to the right source;
• whether the answer respects the BANZA / operator / BanzAI separation;
• whether certification claims are evidence-based (no operator is certified without committed conformance evidence + provenance);
• whether production claims are present without proof (forbidden);
• whether operator neutrality is preserved;
• whether the L0–L4 taxonomy is canonical (per BANZA_CERTIFICATION.md);
• whether Key Manifest / SDK / external-rail statements are honest (the production Key Manifest is specified, not yet published; BANZA ships no official SDK; EMIS and similar rails are examples, not integrations).

Confidence model

• High — directly supported by current protocol evidence.
• Medium — supported, but interpretation is required.
• Low — incomplete evidence, ambiguous source, or unresolved conflict.
• Cannot answer — no supporting evidence.

Confidence is not model certainty. Confidence is evidence quality + the verification result.

Disagreement handling

If the reasoning and verification engines disagree, BanzAI:

• does not average the two answers;
• does not let either model "win";
• inspects the underlying evidence;
• surfaces the disagreement if it cannot be resolved from evidence;
• lowers confidence;
• recommends human/governance review when needed.

Certification support

BanzAI can help an operator:

• inspect conformance evidence and explain failed tests;
• map evidence to certification criteria (L0–L4);
• identify missing provenance;
• check whether a certification claim is supported by evidence.

But:

• BanzAI does not certify operators.
• Certification requires the conformance process, committed evidence, provenance, and the BANZA CA / governance rules.
• BanzAI output is advisory unless tied to verified evidence. (The banzai certify/readiness helpers evaluate readiness; they do not issue certificates.)

Governance boundary

BanzAI supports governance but does not replace it. ADRs and RFCs remain human-governed. BanzAI can summarize, compare, and detect contradictions across decision records, but it cannot approve protocol changes. Protocol rule changes happen only in banza-protocol/banza via ADR/RFC.

Operator neutrality boundary

BanzAI must preserve the ecosystem separation:

• BANZA = the protocol;
• a commercial operator (e.g. the reference operator) = an implementation / operator;
• BanzAI = the evidence / reasoning / verification layer.

It must never turn BANZA into an operator-specific protocol. Enforced by make identity-check and the identity-guard CI job.

Safety / forbidden claims

BanzAI must never claim:

• that any operator is certified, unless committed evidence exists;
• that BANZA is production-ready;
• that official BANZA SDKs are available (none are shipped from the protocol repo);
• that the production Key Manifest is published (it is specified, pending the root ceremony, M2);
• that EMIS / BNA / a bank rail is integrated (these are examples, not integrations);
• that BanzAI certifies alone;
• that Qwen or DeepSeek are sources of truth;
• that model confidence equals protocol evidence.

Architecture diagram reference

Repository diagram (shown above, Architecture at a glance): docs/banzai/diagrams/banzai-cognitive-architecture-v2.svg — the same two-model figure published on banza.network/banzai.

Text version:

User question
  → Evidence retrieval        (RFCs, ADRs, contracts, schemas, invariants, cert rules)
  → Evidence bundle           (the grounded context = source of truth)
  → Qwen reasoning            (explain / interpret / draft)        ── compare ──┐
  → DeepSeek verification     (critique / cite-check / validate / confidence) ─┘
  → claim / citation / confidence check
  → grounded response         (answer · citations · confidence · limits · gaps)

Boundary: BanzAI supports certification but does not certify alone.
Conformance comes from the test suite and the evidence; governance stays human.

Implementation status

Honest status (no overclaim):

• Implemented now: the knowledge index + retrieval, the grounded-answer pipeline, the reasoning∥verification separation, routing logic (prompts/routing.md), citation/grounding rules, deterministic schema validation, and the demo/mock and live-api modes.
• Architecture / documented: the full two-model cognitive design (this README + BANZAI_ARCHITECTURE.md) and the website diagram.
• Future / roadmap: full live two-model serving — BANZAI_MODE=live-ai via RunPod / vLLM (Qwen · Qwen Coder · DeepSeek) with complete model routing — is the live-AI mode and is being rolled out; it is not claimed as fully production-live.
• Requires real conformance evidence: any certification-readiness conclusion is advisory until tied to committed conformance evidence + provenance.
• Requires production process: trust-anchor verification against a published production Key Manifest depends on the root ceremony (M2), still pending.

Development / operation notes

Real configuration (see .env.example):

Variable	Purpose
BANZAI_MODE	demo / mock, live-api, or live-ai
BANZAI_PORT	API port (default 4200)
BANZAI_QDRANT_URL	Vector store URL (live modes)
BANZAI_ALLOWED_ORIGINS	CORS allowlist
BANZAI_QWEN_URL	Qwen reasoning model endpoint (live-ai)
BANZAI_QWEN_CODER_URL	Qwen Coder model endpoint (live-ai)
BANZAI_DEEPSEEK_URL	DeepSeek verification model endpoint (live-ai)

Model routing is defined in prompts/routing.md: general protocol reasoning → Qwen; implementation/code → Qwen Coder; deep reasoning, validation and root-cause analysis → DeepSeek (with deterministic tools). In demo/mock mode no model is required; deterministic validation still runs.

Logging/audit and deterministic test mode follow the API in apps/api. The public deployment runs BANZAI_MODE=live-api-no-model (API endpoints, no model) and holds no production keys (ADR-029).

Tests and verification

Checks that must remain green:

npm run typecheck     # tsc --noEmit (turbo)
npm test              # vitest (apps/api)
npm run build         # turbo run build
make identity-check   # operator-neutrality guard

The website (in the BANZA repo) additionally runs its own type-check, tests, build, SVG check, identity guard and purity guard.

Installation

Prerequisites: Node.js 20+, Docker, the BANZA repository cloned alongside (~/banza) as the knowledge corpus.

git clone https://github.com/banza-protocol/banzai.git
cd banzai
npm install

cp .env.example apps/api/.env        # BANZAI_MODE, BANZAI_QDRANT_URL, BANZAI_PORT, model URLs
npm run docker:up                    # local vector store
npm run api                          # API (default :4200)
npm run web                          # web interface

CLI:

cd apps/cli && npm install && npm run build && npm link

banzai ask "How does idempotency work for QR payments?"
banzai guide --feature qr-payment
banzai validate ./operator-manifest.json   # deterministic schema validation

Deployment guide: BANZAI_DEPLOYMENT.md · Architecture: BANZAI_ARCHITECTURE.md · Security model: BANZAI_SECURITY.md

Contribution Guide

See CONTRIBUTING.md. Two rules dominate review:

1. Operator neutrality. Every capability must work identically for any certified operator. Enforced by make identity-check and the identity-guard CI job.
2. Authority boundaries. No change may let BanzAI define rules, grant certification, or replace deterministic validation with model inference.

Protocol rule changes do not happen here — they happen in banza-protocol/banza via ADR/RFC.

---

License: see LICENSE. BanzAI is operator-neutral protocol infrastructure — no operator owns it.