# `0.2.2` Release Plan

## Summary

`v0.2.2` is a follow-up LLM-operability release for `paralabelgen`. The main
goal is to move the provider-backed extraction path from a single unified
OpenAI-compatible implementation toward a more explicit multi-provider shape,
while also improving evaluation workflows and giving users clearer default
configuration patterns.

This release keeps the public `fit()`, `transform()`, and `fit_transform()`
methods synchronous and preserves the current result-object contracts. It builds
on the `0.2.1` LLM stabilization work rather than expanding the downstream graph
or labeling surface area.

## Key Decisions

- The target release is `0.2.2`.
- The release priority is LLM operability and evaluation ergonomics.
- Extraction remains hybrid:
  - `spacy`
  - `heuristic`
  - `llm`
- The LLM path remains opt-in through top-level configuration.
- Provider support remains:
  - `openai`
  - `mistral`
  - `qwen`
- `0.2.2` starts splitting provider handling into vendor-specific adapters while
  keeping one shared internal provider interface.
- Public pipeline methods remain synchronous in `0.2.2`.
- Live-provider validation is added as an optional smoke-test workflow rather
  than part of the default test suite.

## Implementation Shape

### Provider Adapters

- Split the current unified OpenAI-compatible provider implementation into
  provider-specific adapters for:
  - OpenAI
  - Mistral
  - Qwen
- Keep one internal provider interface so the extractor still depends on a
  stable client abstraction.
- Move provider-specific request shaping, response parsing, and error handling
  out of the shared path.
- Preserve the current top-level LLM config shape unless a provider-specific
  override is truly required.

### Optional Live Smoke Tests

- Add a small live-provider smoke-test path that is disabled by default.
- Gate it behind explicit environment variables so it only runs when credentials
  and intent are present.
- Keep the live scope intentionally small:
  - one or two short paragraphs
  - basic extraction success
  - parse success
  - cache reuse when enabled
- Keep these tests out of normal CI so the default suite remains deterministic
  and offline.

### Evaluation Harness

- Add a documented evaluation workflow for comparing extractor modes on a stable
  paragraph sample.
- Support side-by-side comparison of:
  - `spacy`
  - `heuristic`
  - `llm`
- Produce a compact machine-readable summary that captures:
  - concept counts
  - empty extraction rate
  - noisy concept rate
  - sample community names
  - sample assigned labels
- Keep the harness lightweight and repository-local so future prompt or provider
  changes can be checked before release.

### Recommended Configuration Presets

- Add recommended LLM configuration examples for common usage modes:
  - safe evaluation
  - debugging
  - low-cost extraction
  - higher-fidelity extraction
- Keep these presets primarily in documentation and examples in `0.2.2`.
- If the implementation cost stays small, consider adding helper constructors or
  helper functions later, but do not make that a hard requirement for this
  release.

### Dependency And Documentation Cleanup

- Do follow-up dependency and internal cleanup that becomes necessary after the
  provider-adapter split.
- Keep dead-dependency removal such as `networkx` in `0.2.1`, not `0.2.2`.
- Update README to explain the new provider-adapter model at a high level.
- Expand `docs/public_api.md` and/or evaluation docs to describe:
  - optional live smoke-test workflow
  - evaluation-harness usage
  - recommended LLM configuration patterns

## Testing Goals

- Verify provider selection dispatches to the intended adapter.
- Verify provider-specific adapters preserve the shared downstream extraction
  contract.
- Verify provider-specific error parsing still produces actionable diagnostics.
- Verify live smoke tests remain opt-in and do not run in the default suite.
- Verify evaluation-harness output is reproducible on a fixed sample input.
- Verify documentation examples and recommended presets stay aligned with the
  current config surface.

## Notes

- This release does not yet add async public APIs.
- This release does not yet make `llm` the default extractor mode.
- This release does not yet redesign downstream graph or label result schemas.
- This release does not yet attempt a broad provider feature matrix beyond the
  currently supported providers.
- This document is a planning artifact for repository work and not part of the
  published package API.
