Build hybrid AI with deterministic reasoning
KB AI is a symbolic reasoning engine and an agent skill that let LLMs, AI agents and other applications make fact-based decisions using deterministic rules
KB AI solves AI accuracy and explainability.
Rules are written in natural language by your coding agent, run locally with Node.js, and never guess.
Every answer comes with a reasoning tree. When a fact is missing, the engine stops and asks for it instead of hallucinating.
Ships as an Agent Skills standard skill for Claude Code, Codex and opencode. Describe rules in plain English and the agent writes, tests and maintains them.
Open source, plain JavaScript, no build step. Run it locally, on AWS Lambda or behind your own HTTP endpoint.
Follow these steps to create and start using your hybrid AI agent with deterministic fact-based reasoning. Everything you need is in the kbai-skill repository.
The repository is a self-contained template: a model knowledge base in .kb/ and the symbolic-kb skill in .claude/skills/symbolic-kb/. Node.js is the only prerequisite.
git clone https://github.com/TitovDigital/kbai-skill.git
cd kbai-skillOpen the folder in Claude Code, Codex or opencode and ask:
Here's a contract: "Acme LLC and Beta Inc. agree to a 12-month non-compete.
Signed by A. Smith for Acme and J. Doe for Beta."
Is it valid according to the 'symbolic-kb' skill?The agent extracts the facts it can see in the text, runs the engine and answers with the reasoning tree:
Yes — valid, according to the contract.isValid rule.
Reasoning trace:
- contract.hasNonCompete = true (12-month non-compete clause is present)
- contract.signedByPartyA = true (A. Smith signed for Acme)
- contract.signedByPartyB = true (J. Doe signed for Beta)
- → contract.isSignedByBothParties = true (both signatures present)
- → contract.isValid = true (has non-compete AND signed by both parties)If a fact isn't in the document, for example one signature is missing, the engine stops with FACT_NEEDED for that fact and the agent says so rather than guessing.
Describe rules in natural language. The agent translates your description to first-order logic, writes the rule file, updates the manifest and lints the schemas.
Show me the knowledge base in this project
Add a rule: a contract is binding if it is valid and has been filed with the county.KB AI can also be taught from examples. Give the agent a handful of real cases and ask it to reverse-engineer them into a decision-making model, and it will build the entire knowledge base for you.
There is no compiled bundle. Ship the .kb/ folder alongside the engine and run it from the command line, on AWS Lambda, behind an Express endpoint, or import it directly in Node.js.
import { loadKB } from './load_kb.mjs';
const { handler } = await loadKB('.kb');For structured inputs the same engine can be called programmatically without an LLM. Pass the fact you want and the facts you already know:
echo '{"fact":"contract.isValid","facts":{"contract.hasNonCompete":true,"contract.signedByPartyA":true}}' \
| node .claude/skills/symbolic-kb/scripts/run_inference.mjs --kb-dir .kb \
| node .claude/skills/symbolic-kb/scripts/print_tree.mjsOutput:
▶ Inferring contract.isValid — Is the contract valid?
contract.hasNonCompete = true (known)
▶ Inferring contract.isSignedByBothParties — Is the contract signed by both parties?
contract.signedByPartyA = true (known)
✗ contract.signedByPartyB is missing (boolean) — Whether party B signed the contract
✗ inference stopped due to contract.signedByPartyB missingSupply the missing fact and re-run, and inference completes:
▶ Inferring contract.isValid — Is the contract valid?
Rule: A contract is valid if it has a non-compete clause and is signed by both parties
contract.hasNonCompete = true (known)
▶ Inferring contract.isSignedByBothParties — Is the contract signed by both parties?
Rule: A contract is signed by both parties if party A and party B both signed
contract.signedByPartyA = true (known)
contract.signedByPartyB = true (known)
✓ inferred contract.isSignedByBothParties = true
✓ inferred contract.isValid = trueEach rule is one small JavaScript function. It receives an infer callback to resolve other facts by name and returns a value. The filename is the rule name.
// .kb/rules/contract.isValid.mjs
export default async function(infer) {
const hasNonCompete = await infer('contract.hasNonCompete');
const isSignedByBoth = await infer('contract.isSignedByBothParties');
return hasNonCompete && isSignedByBoth;
}A manifest records each rule's question, its plain-English condition and a JSON schema of the facts it depends on. The engine uses that schema to ask for missing facts, and an LLM uses it to know what to extract.
KBAI can be interfaced with LLMs in two directions.
Firstly, KBAI can provide a set of facts and a completed reasoning chain to an LLM. This can be done either in an initial prompt, by adding the facts output of KBAI to it, or by offering KBAI inference as a function to the LLM. The manifest already contains ready-to-use JSON schemas for every rule's parameters.
Usually it's sufficient to provide the facts alone and LLMs can make conclusions about their meaning from their names. In some cases you may wish to add the reasoning steps and the rule definitions that were used to reach the conclusion.
Secondly, in many practical applications execution of the rules requires answers that can be obtained by an LLM from unstructured source data (texts, files, document images etc). In such cases the agent provides an answer whenever KBAI inference stops with a FACT_NEEDED code, then re-runs the engine. This is exactly the feedback loop the symbolic-kb skill implements.
Combining KBAI and LLMs in this way creates a neuro-symbolic architecture where KBAI reasoning guides the LLM to make step-by-step decisions based on the source data, while the more complex reasoning is defined by explainable KBAI rules. The result is hybrid AI agents that are much more powerful and predictable compared to the traditional all-LLM approach.
KBAI is a tool for building hybrid AI agents with fact-based reasoning. It uses a deterministic reasoning engine to provide accurate and reliable responses. KBAI enables the creation of agents and applications by handling logical reasoning with a KBAI deterministic AI model, outside of large language models (LLMs), resulting in more precise and faster responses compared to traditional prompt engineering. It is distributed as an open-source agent skill and template repository.
KBAI is a forward-chaining symbolic inference engine. Rules are plain JavaScript functions executed locally with Node.js. Your coding agent converts natural language rules into first-order logic and then into code, eliminating ambiguities. Each rule is recorded in a manifest alongside its question and plain-English condition, so users can review and refine the interpreted rules in human-readable language. This iterative process allows users to clarify rules and ensure the system behaves as intended without needing extensive test cases.
KBAI is useful when you need auditable, repeatable decisions over messy inputs, where a pure LLM is too unreliable to trust with the decision itself. It fits best when the decision workflow can be written down by a domain expert as a policy and the logic follows a tree-like if-then structure, possibly with unclear dependencies, rather than a linear process.
KBAI's deterministic nature ensures consistent outputs for given inputs, reducing uncertainty in AI reasoning. Instead of relying on tools like Langsmith for evaluations, KBAI focuses on resolving ambiguities in the initial rule interpretation. Users review and refine rules with the agent to confirm they align with intended outcomes. This approach minimizes the need for complex test frameworks, though general-purpose testing can be applied if needed.
KBAI interoperates with LLMs in two primary ways:
KBAI-to-LLM: KBAI processes user activity or data (e.g., evaluating dozens of parameters like business type or funnel setup in Able CDP) and generates a reasoning chain (final conclusions, intermediary facts, and source data). This output is sent to an LLM, which translates it into a user-friendly response within the context of the user's question. LLMs excel at this text transformation, making the process reliable.
LLM-to-KBAI: When KBAI needs a fact it cannot derive from its knowledge base, it pauses and the agent queries an LLM (or a custom model) for specific information, such as extracting details from a document (e.g., “What's the hourly wage in the contract?”). KBAI then uses these answers for further reasoning, ensuring consistency by handling complex logic itself.
Support Automation: In Able CDP, KBAI evaluates user activity (e.g., business type, funnel setup, and system status) to provide step-by-step guidance, which an LLM then translates into user-friendly responses.
Legal Contract Analysis: KBAI breaks down complex documents by asking LLMs simple, targeted questions (e.g., about specific contract terms), then uses the answers to perform reliable reasoning, avoiding the inconsistency of LLMs processing lengthy documents directly.
KBAI reduces variability by handling logical reasoning outside of LLMs, which often struggle with consistent outputs for complex tasks. By converting ambiguous natural language rules into a deterministic framework, KBAI ensures reliable results. It also simplifies the process of refining AI behavior, as users can iteratively clarify rules without rewriting prompts or running extensive tests.
While KBAI can be tested using general-purpose frameworks, its design minimizes the need for extensive testing. The iterative rule-refinement process allows users to directly validate and adjust the system's behavior. For systems integrating KBAI with LLMs, testing may focus on the LLM's ability to provide accurate facts from unstructured data, depending on the specific use case and backend model.
The symbolic-kb skill follows the Agent Skills standard and runs in Claude Code, Codex and opencode. The engine itself has no dependency on any agent and can be used from plain Node.js.
KB AI is dual-licensed. The source is published under the Business Source License 1.1, and a commercial license is available for everyone else.
You may copy, modify and redistribute the code, and use it in production free of charge if either:
Non-production use is free for everyone. Each version converts to the GNU AGPL v3 on its change date, no later than four years after release.
Larger organisations, government entities and services above the user threshold need a commercial license for production use. It also covers support, custom terms and on-premise arrangements.
Send us an email or book a call below: