v0.5.1 — README refresh on PyPI

Patch release. No code changes vs 0.5.0. Bumped to surface the updated README on the PyPI project page.

Docs

• Refreshed PyPI long description (README): full v0.5 feature catalogue, expanded Quick start (profile / async / Ollama / auto-detect / explicit), provider capability matrix, BYO-provider snippet, deep links to every docs page, contributor dev-loop snippet.
• Added examples/notebooks/ to the repo:
  • 01_quickstart.ipynb (offline, free layers + MockProvider)
  • 02_token_savings.ipynb (real OpenAI; measured tokens, USD, judge score)
  • 03_long_doc_async.ipynb (offline; ~6.5x speedup at concurrency=8)
  • 04_custom_schema.ipynb (offline; nested Pydantic schema round-trip)

Install

pip install --upgrade narratoflow

Full notes: see CHANGELOG.md.

v0.5.0 — spaCy, language auto-detect, mypy CI

Highlights

• Optional spaCy preprocessing — `PreprocessConfig(spacy_model="en_core_web_sm")` switches sentence splitting to spaCy when the model is installed; regex fallback runs otherwise (no error). `spacy_strip_pos=True` does POS-aware token removal that keeps named entities verbatim.
• Language auto-detection — pass `source_lang="auto"` and the detected ISO code lands in `result.stats.resolved_lang`. Uses `langdetect` when installed (new `lang` extra), otherwise a stopword-overlap heuristic over the 12 bundled languages.
• mypy strict-ish + CI job — `[tool.mypy]` enforces typed defs across the public surface; SDK-bridge modules are excluded via override. New `typecheck` job in `.github/workflows/ci.yml` runs mypy on every push/PR.
• New docs pages — Language detection, spaCy integration. MkDocs nav and API reference updated.

Install

```bash
pip install narratoflow==0.5.0

optional extras:

pip install "narratoflow[nlp]" # spaCy
pip install "narratoflow[lang]" # langdetect
```

Example

```python
from narrato import Compressor

c = Compressor.from_profile("rag-en", provider="anthropic")
c.source_lang = "auto" # detect at runtime

result = c.compress(any_language_document)
print(result.stats["resolved_lang"]) # 'en' / 'de' / 'fi' / ...
```

Tests

63 passing + 1 skipped (spaCy-only). Was 55. New `tests/test_language.py`, `tests/test_spacy.py`.

Deferred

Learned-encoder R&D — genuine research, not worth half-shipping. Moved to v0.6.

Full notes: see CHANGELOG.md.

v0.4.0 — local models, async, typed, uv-ready

Highlights

• Ollama provider — run on local LLMs (llama3, mistral, qwen, …) over Ollama's HTTP API. No API key.
• Async API — `Compressor.acompress(text, concurrency=4)` extracts chunks in parallel via `asyncio.gather`. Public `extract_async` / `extract_chunked_async`.
• OpenAI prompt-cache stats — `ProviderResponse.cached_input_tokens` is populated from `usage.prompt_tokens_details.cached_tokens` on hits (≥1024 prompt tokens).
• Typed (PEP 561) — ships `py.typed`; mypy / pyright / IDE checkers consume inline annotations directly.
• `uv` ready — `uv build`, `uvx --from narratoflow narratoflow ...`, and `uv add narratoflow` all work; no pyproject changes were needed.
• Docs — new pages: Install (pip + uv + uv build), Providers (matrix + per-provider), Async API, Type checking.

Install

```bash
pip install narratoflow==0.4.0

or

uv add narratoflow
```

Example

```python
import asyncio
from narrato import Compressor

local model via Ollama, no key

c = Compressor.from_profile("rag-en", provider="ollama",
extractor_model="llama3", target_model="llama3")

concurrent chunked extraction

result = asyncio.run(c.acompress(very_long_document, concurrency=8))
```

Tests

55 passing (was 42). New `tests/test_async.py`, `tests/test_ollama.py` (httpx MockTransport — zero network), `tests/test_typing_marker.py`.

Full notes: see CHANGELOG.md.

v0.3.0 — generic-core refactor + named profiles

Why

The original library framed itself as a Norwegian-narrative tool, which limited adoption even though the engine was already generic. v0.3 keeps the engine neutral and moves opinionated configuration into a separate Profile registry, so callers can re-opt-in to the previous defaults with one named argument instead of having them forced.

Breaking (tiny)

Only two defaults flip:

• Compressor(source_lang=...): \"no\" → \"en\"
• Compressor(schema=...): \"narrative\" → \"qa\"

Existing users have two clean migration paths:

```python

v0.2 implicit defaults — no longer the same in v0.3

Compressor()

v0.3 equivalent 1: name the profile

Compressor.from_profile("narrative-no")

v0.3 equivalent 2: pass the old kwargs explicitly

Compressor(source_lang="no", schema="narrative")
```

Highlights

• Named profiles: nine bundled (`rag-en`, `qa-en`, `narrative-en`, `interview-en`, `dialogue-en`, `news-en`, `long-en`, `narrative-no`, `rag-no`). `register_profile()` is public — define your own.
• **`Compressor.from_profile(name, overrides)` classmethod for one-line setup.
• 12-language stopword bundle: en, no, de, fr, es, it, pt, nl, sv, da, fi, pl.
• CLI: `narratoflow profiles` and `narratoflow schemas` list commands; `narratoflow compress --profile ` plus per-call overrides.

Tests

42 passing (was 32). New `tests/test_profiles.py` covers registry, overrides, custom registration, default genericity.

Install

```bash
pip install narratoflow==0.3.0
```

Full notes: see CHANGELOG.md.

v0.2.0 — chunked extraction, prompt caching, more schemas

Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

Unreleased

0.2.0 - 2026-05-25

Added

• Chunked map-reduce extraction (narrato.extractors.extract_chunked) for
  sources too long for a single LLM call. Splits on sentence boundaries with
  configurable overlap; merges partial payloads with order-preserving dedupe.
• Compressor.chunked, Compressor.chunk_chars, Compressor.overlap_chars
  parameters; chunked mode triggers automatically when len(text) > chunk_chars.
• Anthropic prompt caching: Compressor(cache=True) (or
  AnthropicProvider(cache=True)) marks the system prompt as an ephemeral
  cache breakpoint. Repeated calls within ~5 min pay 10 % on the cached portion.
• Three new schema presets: interview, dialogue, news (5W1H).
• narrato.schemas.list_presets() helper.
• narrato.providers.MockProvider for offline tests and demos. Accepts a
  static payload, a callable, or a sequence of canned responses; counts calls.
• Tokenizer-aware codebook savings: CodebookConfig.estimator="tokens" plus
  the tokenizer argument to codebook.build() switch from char-proxy to
  real-token measurement.
• Compressor.provider now accepts a pre-constructed Provider instance in
  addition to the string name — useful for dependency injection.

Changed

• narrato.tokenizers.get_tokenizer falls back to the OpenAI/tiktoken
  encoder for unknown provider names instead of raising. Lets mock and custom
  providers participate in pipeline runs without ceremony.
• Codebook layer now wired to the pipeline tokenizer when available; stats
  include the estimator used.

Tests

• New tests/test_extractors.py: covers single-shot extract, validation
  errors, chunked map-reduce splitting, overlap dedupe, news schema.
• Pipeline tests now exercise the extract layer end-to-end via MockProvider,
  including chunked mode and the cache flag.

0.1.3 - 2026-05-25

Added

• MkDocs Material documentation site under docs/ (index, quickstart,
  architecture, schemas, cli, benchmark, API reference, roadmap).
• .github/workflows/docs.yml — auto-deploy docs to GitHub Pages.
• .github/workflows/release.yml — auto-publish to PyPI via Trusted
  Publishing (OIDC) on release: published.
• docs extra in pyproject.toml.
• Documentation + Changelog URLs in package metadata.

0.1.2 - 2026-05-24

Added

• GitHub Actions CI workflow (.github/workflows/ci.yml): pytest matrix on
  Python 3.10/3.11/3.12 across Ubuntu + Windows, separate ruff lint job.

Changed

• Trimmed README badges to four: PyPI version, Python versions, CI, license.

0.1.1 - 2026-05-24

Added

• README badges (PyPI version, Python versions, license, downloads, GH stars,
  PRs welcome).
• Discoverability tag-chip strip.
• "Highlights" section in README.

0.1.0 - 2026-05-24

Added

• Initial release.
• Layered context compressor: L1 preprocess (deterministic, free), L2
  codebook (deterministic, free), L3 schema-driven semantic extract (cheap
  LLM call).
• Provider adapters for Anthropic (tool-use JSON) and OpenAI
  (response_format JSON schema).
• NarrativeFacts + QAFacts Pydantic schema presets.
• CLI: narrato compress, narrato eval, narrato prompt.
• Round-trip benchmark with LLM judge.
• Norwegian-first preprocessing (stopwords, NFC, sentence dedupe) and
  Norwegian short-story benchmark sample.

v0.1.3 — Docs site + auto PyPI publish

Highlights

• MkDocs Material documentation site under docs/
  • Index, Quickstart, Architecture, Schemas, CLI, Benchmark, Roadmap
  • Auto-generated API reference via mkdocstrings
  • Deploys to GitHub Pages on every push to main
• Automated PyPI publishing via GitHub Actions
  • Triggered when a GitHub release is published
  • Uses Trusted Publishing (OIDC) — no PyPI token stored in repo secrets
• docs extra in pyproject.toml so contributors can run the docs locally with pip install -e .[docs]

Manual steps required on first auto-publish (one-time, repo owner)

1. PyPI trusted publisher
   • Go to https://pypi.org/manage/project/narratoflow/settings/publishing/
   • Add a publisher with:
     • Owner: Mrrobi
     • Repository: narratoflow
     • Workflow filename: release.yml
     • Environment name: pypi
2. GitHub Pages source
   • GitHub repo → Settings → Pages → Build and deployment → Source: GitHub Actions

Once those are configured, the next gh release create will auto-build and auto-publish to PyPI; pushes to main that touch docs/ will auto-deploy the site.

Install

pip install narratoflow==0.1.3

v0.1.2 — slim README badges + CI

Changes

• README: trim badges to four — PyPI version, Python versions, CI, license
• CI: add GitHub Actions workflow (.github/workflows/ci.yml)
  • pytest matrix: Python 3.10 / 3.11 / 3.12 on ubuntu-latest + windows-latest
  • separate ruff lint job

No library code changes versus 0.1.1.

Install

pip install narratoflow==0.1.2

v0.1.1 — README badges + topical tags

Changes

• README: added shields.io badges (PyPI version, Python versions, license, downloads, GitHub stars, PRs welcome)
• README: added discoverability tag chips (llm, prompt-compression, anthropic, openai, claude, gpt, pydantic, norwegian, narrative-generation, rag, context-window, …)
• README: added a "Highlights" section summarising benchmark results

No code changes versus 0.1.0.

Install

pip install narratoflow==0.1.1

Verified benchmark (vs 0.1.0, identical code path)

metric	value
tokens_source	693
tokens_compressed	392
ratio	0.57 (43% reduction)
cost savings	13%
LLM-judge quality	8/10

Run via python scripts/run_bench.py with OPENAI_API_KEY set.