kb-ai

kb-ai

Proof of concept. This package exists to demonstrate the shape of the API and the packaging pipeline. It is not production-hardened — expect breaking changes.

A lightweight, dependency-free knowledge base toolkit for AI applications. Store documents, search them with tf-idf ranking, and persist everything as plain JSON — no vector database or model server required to get started.

Maintained by 4us71n0.

Installation

pip install kb-ai

Quick start

from kb_ai import Document, KnowledgeBase

kb = KnowledgeBase()
kb.add_text("faq-1", "Refunds are issued within 5 business days.", {"topic": "billing"})
kb.add(Document(id="faq-2", text="Password resets are sent by email."))

for hit in kb.search("how long do refunds take"):
    print(hit.score, hit.document.id, hit.document.text)

kb.save("kb.json")
restored = KnowledgeBase.load("kb.json")

Command line

kb-ai add faq-1 "Refunds are issued within 5 business days." --metadata '{"topic": "billing"}'
kb-ai search "refund policy" -n 3
kb-ai list
kb-ai remove faq-1

Every command accepts --store PATH to point at a specific JSON file (default: kb.json in the current directory).

API

Object	Purpose
Document(id, text, metadata)	A single knowledge base entry.
SearchResult(document, score)	A document with its relevance score.
KnowledgeBase	add, add_text, get, remove, search, save, load.
tokenize(text)	The lowercase alphanumeric tokenizer used for scoring.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .
mypy

Releasing to PyPI

• Bump __version__ in src/kb_ai/__init__.py and update CHANGELOG.md.
• Build and verify locally:

  python -m build
  twine check dist/*
  

• Tag and push — the publish workflow uploads to PyPI via Trusted Publishing:

  git tag v0.1.0 && git push origin v0.1.0
  

See PUBLISHING.md for the one-time PyPI setup.

License

MIT — see LICENSE.