[FEATURE] Composable extraction pipeline with stage registry and typed contracts

[mykola-pereyma]

Description

Closes #240

Introduces a composable extraction pipeline framework that allows users to define custom stage sequences mixing local extraction (CPU-based NER via GLiNER) and LLM-based extraction, with schema/ontology constraints for guiding and filtering results.

Changes

Core Abstractions

• ExtractionStage ABC with typed input_keys()/output_keys()/as_transform() contracts
• PipelineBuilder with build-time validation of stage input/output compatibility
• ExtractionConfig.from_stages(stages, schema) factory method for custom pipelines
• ExtractionSchema + EntityTypeConfig for defining entity types with descriptions, attributes, and aliases

Built-in Stages (8)

Stage	Type	Purpose
LLMPropositionStage	LLM	Extract propositions from text
LocalPropositionStage	Local	Non-LLM proposition extraction
LLMTopicExtractionStage	LLM	Extract topics, entities, relationships
NERExtractionStage	Local	GLiNER-based CPU entity extraction
EntityMergeStage	Transform	Fuzzy-deduplicate NER + LLM entities
SchemaFilterStage	Filter	Filter output against schema (strict/non-strict)
BatchLLMPropositionStage	Batch	Batch variant of proposition extraction
BatchTopicExtractionStage	Batch	Batch variant of topic extraction

Additional

• JSON topic extraction prompt with text parser fallback
• Schema constraints auto-injected into LLM topic extraction prompt
• INFO logging of custom pipeline composition
• Pydantic PrivateAttr for NER model caching
• Error handling with clear messages for NER model loading

Backward Compatibility

• ExtractionConfig() constructor unchanged — existing code works without modification
• Pipeline output remains TopicCollection format
• Default chunking applies to both default and custom pipeline paths
• Pure additive extension — no breaking changes

Testing

• 229 extraction-specific tests
• 1308 total tests passing
• Integration tests for custom pipeline path (chunking + schema injection)
• All pre-existing tests pass (no regression)

Usage

from graphrag_toolkit.lexical_graph import ExtractionConfig
from graphrag_toolkit.lexical_graph.indexing.extract import (
    LLMPropositionStage, LLMTopicExtractionStage,
    NERExtractionStage, EntityMergeStage, SchemaFilterStage,
    ExtractionSchema, EntityTypeConfig,
)

schema = ExtractionSchema(
    entity_types={
        'Person': EntityTypeConfig(description='A human being'),
        'Organization': EntityTypeConfig(description='A company or institution'),
    },
    strict=True,
)

config = ExtractionConfig.from_stages(
    stages=[
        LLMPropositionStage(),
        NERExtractionStage(entity_labels=['Person', 'Organization']),
        LLMTopicExtractionStage(),
        EntityMergeStage(fuzzy_threshold=0.85),
        SchemaFilterStage(schema=schema),
    ],
    schema=schema,
)

Documentation

• Usage guide: docs-site/src/content/docs/lexical-graph/composable-extraction-pipeline-usage.md
• Example notebook: examples/lexical-graph-local-dev/notebooks/06-Composable-Extraction-Pipeline.ipynb

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.