Metadata-Version: 2.3
Name: krill-core
Version: 0.1.2
Summary: Shared recording contract for the krill toolkit — internal, not for standalone use
Author: anonymous
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# krill-core

> The krill's shared skeleton — the contract every other package feeds on.

Shared recording contract for the krill toolkit: HTTP primitives, the recording model, its persistence, and the error base.

## Install

An internal shared contract, published only as a dependency of [`krill-fuzzer`](../krill-fuzzer) and [`krill-collector`](../krill-collector) — not intended for standalone use; install one of those instead. Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). For workspace development, from the root:

```bash
uv sync   # installs all workspace members editable, krill-core included
```

## Usage

Import through a re-exporting package — [`krill-fuzzer`](../krill-fuzzer) here; `krill-collector` re-exports the producer-side names.

```python
from pathlib import Path

from krill_fuzzer import load_recording, save_recording

recording = load_recording(Path("requests.json"))  # -> WorkflowRecording
save_recording(recording, Path("copy.json"))
```

## API

Re-exported through `krill_collector` and `krill_fuzzer`.

**HTTP primitives** — `krill_core._http`

- `HttpMethod` — enum of HTTP verbs.
- `HttpRequest` — method, URL, headers, body of one request.
- `HttpResponse` — status, headers, body of one response.
- `HttpExchange` — one request paired with its response.

**Recording model** — `krill_core._recording`

- `EventType` — enum of recorded interaction kinds.
- `RecordedEvent` — one recorded user/workflow event.
- `WorkflowRecording` — the full recording: exchanges, events, target, timings, optional `extract_as` map.
- `ExtractAsMap` — extraction bindings carried on a recording.

**Persistence** — `krill_core._persistence`

- `save_recording(recording: WorkflowRecording, path: Path) -> None` — write a recording to JSON.
- `load_recording(path: Path) -> WorkflowRecording` — read a recording from JSON.

**Errors** — `krill_core._errors`

- `KrillError` — base of every error the toolkit raises.
- `PersistenceError` — a save/load failure; subclass of `KrillError`.

## Background

Internal foundation package, published only as a shared dependency, not for standalone use — its names are re-exported through [`krill-collector`](../krill-collector) (the producer) and [`krill-fuzzer`](../krill-fuzzer) (the consumer), and consumers import them from there. Its purpose is to keep the recording contract in one place so the collector and the fuzzer agree on the same types without the fuzzer inheriting the collector's browser dependency.

## Documentation

- [Docs index](docs/index.md) — persistence design and implementation notes.

## Citation

```bibtex
@misc{citation_placeholder,
  title  = {{TODO: paper title — not yet released}},
  author = {{TODO: authors}},
  year   = {{TODO}},
  note   = {Paper not yet released. Citation entry will be updated on publication.}
}
```

## License

[`GPL-2.0`](../../LICENSE)
