Metadata-Version: 2.5
Name: kb-ai
Version: 0.1.0
Summary: Proof of concept: a lightweight knowledge base toolkit for AI applications.
Project-URL: Homepage, https://github.com/4us71n0/kb-ai
Project-URL: Documentation, https://github.com/4us71n0/kb-ai#readme
Project-URL: Repository, https://github.com/4us71n0/kb-ai
Project-URL: Issues, https://github.com/4us71n0/kb-ai/issues
Project-URL: Changelog, https://github.com/4us71n0/kb-ai/blob/main/CHANGELOG.md
Author: 4us71n0
Maintainer: 4us71n0
License-Expression: MIT
License-File: LICENSE
Keywords: ai,knowledge-base,llm,poc,retrieval,search
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Description-Content-Type: text/markdown

# kb-ai

[![PyPI](https://img.shields.io/pypi/v/kb-ai.svg)](https://pypi.org/project/kb-ai/)
[![Python versions](https://img.shields.io/pypi/pyversions/kb-ai.svg)](https://pypi.org/project/kb-ai/)
[![License](https://img.shields.io/pypi/l/kb-ai.svg)](https://github.com/4us71n0/kb-ai/blob/main/LICENSE)

> **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

```bash
pip install kb-ai
```

## Quick start

```python
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

```bash
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

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

## Releasing to PyPI

1. Bump `__version__` in `src/kb_ai/__init__.py` and update `CHANGELOG.md`.
2. Build and verify locally:
   ```bash
   python -m build
   twine check dist/*
   ```
3. Tag and push — the `publish` workflow uploads to PyPI via Trusted Publishing:
   ```bash
   git tag v0.1.0 && git push origin v0.1.0
   ```

See [PUBLISHING.md](PUBLISHING.md) for the one-time PyPI setup.

## License

MIT — see [LICENSE](LICENSE).
