Metadata-Version: 2.4
Name: kb-artifacts
Version: 0.1.0
Summary: Inspect, select, and reproducibly export evidence from JSONL collections.
Author: Matías Iglesias
License-Expression: MIT
Project-URL: Homepage, https://matuteiglesias.github.io/kb-artifacts/
Project-URL: Documentation, https://matuteiglesias.github.io/kb-artifacts/
Project-URL: Repository, https://github.com/matuteiglesias/kb-artifacts
Project-URL: Issues, https://github.com/matuteiglesias/kb-artifacts/issues
Project-URL: Changelog, https://github.com/matuteiglesias/kb-artifacts/blob/main/CHANGELOG.md
Keywords: jsonl,knowledge-base,evidence,provenance,data-processing,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.5; extra == "docs"
Requires-Dist: mkdocs-literate-nav>=0.6; extra == "docs"
Requires-Dist: mkdocs-section-index>=0.3; extra == "docs"
Requires-Dist: pymdown-extensions>=10.7; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Requires-Dist: tomli; python_version < "3.11" and extra == "dev"
Dynamic: license-file

# kb-artifacts

[![CI](https://github.com/matuteiglesias/kb-artifacts/actions/workflows/ci.yml/badge.svg)](https://github.com/matuteiglesias/kb-artifacts/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/kb-artifacts.svg)](https://pypi.org/project/kb-artifacts/)
[![Python: >=3.10](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

`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

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

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

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

The command reports `selected=1` and creates:

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

```python
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](https://matuteiglesias.github.io/kb-artifacts/python-api/)
for signatures and the `0.x` stability boundary.

## CLI

Inspect bounded source metadata without including record bodies:

```bash
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](https://matuteiglesias.github.io/kb-artifacts/) covers selection,
provenance, operational guarantees, and interoperability. Runnable examples live in
[`examples/`](examples/).

For a development checkout:

```bash
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](https://github.com/matuteiglesias/kb-artifacts).
See [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change,
[CHANGELOG.md](CHANGELOG.md) for user-visible changes, and
[SECURITY.md](SECURITY.md) for private vulnerability reporting.
