kb-artifacts

kb-artifacts is a small Python library and CLI for inspecting, filtering, selecting, and reproducibly exporting records from JSONL evidence collections.

What it does

• Reads newline-delimited JSON without modifying the source files.
• Accepts common fields including title, text, content, summary, tags, timestamps, and nested meta values.
• Filters records by tags, fields, dates, text, family, and maturity.
• Writes the same selection as JSONL, CSV, readable Markdown, and a provenance manifest.

Install

python -m pip install kb-artifacts
kb-artifact --help

Python 3.10 or newer is required.

60-second example

Create a two-record JSONL collection:

cat > evidence.jsonl <<'EOF'
{"title":"Deploy app","text":"Build and deploy the service","tags":["runbook","ops"]}
{"title":"Buy groceries","text":"Milk and bread","tags":["personal"]}
EOF

Select the runbook record:

kb-artifact select \
  --chunk-glob evidence.jsonl \
  --tag runbook \
  --output selected

The command reports selected=1 and creates:

selected/
├── selected.jsonl
├── selected.csv
├── artifact.md
└── manifest.json

selected.jsonl is the machine-readable selection, selected.csv is convenient for spreadsheets, artifact.md is readable output, and manifest.json records the request, input checksum, counts, and generated files.

Python API

from kb_artifacts import SelectionRequest, select

request = SelectionRequest(
    chunk_globs=("evidence.jsonl",),
    tags=("runbook",),
)

result = select(request, output="selected-python")
print(result["counts"]["selected"])  # 1

The supported public API for 0.1 is EvidenceRecord, SourceReference, SelectionDecision, SelectionRequest, inspect_source(), and select(). See the Python API documentation for signatures and the 0.x stability boundary.

CLI

Inspect bounded source metadata without including record bodies:

kb-artifact inspect source \
  --chunk-glob evidence.jsonl \
  --output source-report.json

Use kb-artifact --help, kb-artifact select --help, or kb-artifact inspect source --help for all options. Repeated tags use OR semantics; different filter types must all match.

Documentation / development

The documentation covers selection, provenance, operational guarantees, and interoperability. Runnable examples live in examples/.

For a development checkout:

python -m pip install -e '.[dev,docs]'
make test
make smoke
make distribution-test

make distribution-test builds both distribution formats, installs the wheel into an isolated temporary environment, verifies the public imports, runs the installed CLI help, and selects the minimal example outside the source checkout.

Source code and issues are hosted on GitHub. See CONTRIBUTING.md before proposing a change, CHANGELOG.md for user-visible changes, and SECURITY.md for private vulnerability reporting.