# `0.2.0` Release Plan

## Summary

`v0.2.0` introduces an opt-in LLM-backed concept extraction path while keeping
the existing graph, community detection, labeling, and result objects stable.
The main goal is to improve concept extraction generalization across diverse
paragraph styles without forcing downstream pipeline redesign.

The release keeps the public `fit()`, `transform()`, and `fit_transform()`
methods synchronous and preserves `ConceptMention` as the downstream extraction
contract. The LLM path is additive and explicit rather than replacing the
default extractor immediately.

## Key Decisions

- Extraction remains hybrid:
  - `spacy`
  - `heuristic`
  - `llm`
- The LLM path is opt-in through top-level configuration.
- Provider support includes:
  - `openai`
  - `mistral`
  - `qwen`
- Provider configuration uses one unified config shape with vendor-specific
  optional fields.
- The LLM extractor still emits `ConceptMention` objects.
- Public pipeline methods remain synchronous in `v0.2.0`.
- LLM requests support disk-backed caching for reproducibility.

## Implementation Shape

### Config

- Add a top-level `extractor_mode` field.
- Keep `use_nlp_extractor` for backward compatibility.
- Add `LLMExtractionConfig` under `ExtractionConfig`.

### Extraction

- Add `LLMConceptExtractor`.
- Add a provider abstraction layer for multi-vendor support.
- Parse provider output into normalized concept mentions.
- Reuse the existing post-extraction filtering and canonicalization stages.

### Provider Layer

- Introduce a provider client interface.
- Ship one OpenAI-compatible HTTP client implementation that can be configured
  for:
  - OpenAI
  - Mistral
  - Qwen
- Keep the provider interface internal to the extraction subsystem for now.

### Reproducibility

- Add disk cache support keyed by:
  - provider
  - model
  - prompt version
  - request payload
- Do not silently fall back from `llm` to another extractor mode.

## Testing Goals

- Verify extractor mode selection.
- Verify LLM extraction returns deterministic `ConceptMention` objects.
- Verify LLM cache hits avoid repeated provider calls.
- Verify serialization preserves the new extraction config.
- Verify missing LLM model/provider configuration fails clearly.

## Notes

- This release does not yet redesign downstream graph or label result schemas.
- This release does not yet add async public APIs.
- This document is a planning artifact for repository work and not part of the
  published package API.
