---

name: package-extensions description: "Build and diagnose GraphRAG lower-level package extensions: custom caches, storage and table providers, input readers, chunkers, vector stores and filters, LLM completion/embedding providers, tokenizers, metrics/retry/rate-limit/template factories, graph helpers, and indexing workflow factories." disable-model-invocation: true metadata: disco-role: operating license: MIT

GraphRAG Package Extensions

Use this sub-skill when the task mentions custom providers, factory registration, extension points, offline mocks, graph helper validation, vector-store filters, timestamp/date fields, chunkers, or low-level package diagnostics.

For user-facing YAML/config selection, route to ../configuration-data/. For indexing orchestration or running pipelines, route to ../indexing/. For query APIs and result-table requirements, route to ../querying/.

Core Pattern

GraphRAG package extensions usually follow the same pattern:

1. Implement the package interface or subclass the base class.
2. Register it under a stable string key with the package register_* function.
3. Use the matching config model or create_* helper so GraphRAG instantiates it.
4. Keep optional services behind explicit dependency and credential checks.

The shared factory base supports scope="transient" and scope="singleton". create() removes init args whose value is None, so use a sentinel or explicit default if an initializer must distinguish "unset" from None. Singleton instances are cached by strategy plus init args; avoid singleton scope for mutable per-run state unless the init args fully identify the state.

Common Extension Points

• Cache: implement graphrag_cache.Cache, register with register_cache(type, initializer, scope="transient"), create with create_cache(CacheConfig(...), storage=...).
• Storage: implement graphrag_storage.Storage, register with register_storage(type, initializer), create with create_storage(StorageConfig(...)).
• Table provider: implement graphrag_storage.tables.TableProvider, register with register_table_provider(type, initializer), create with create_table_provider(TableProviderConfig(...), storage=...).
• Input reader: subclass or implement graphrag_input.InputReader, register with register_input_reader(type, initializer), create with create_input_reader(InputConfig(...), storage).
• Chunker: implement graphrag_chunking.Chunker, register with register_chunker(type, initializer), create with create_chunker(ChunkingConfig(...), encode=..., decode=...).
• Vector store: subclass graphrag_vectors.VectorStore, register with register_vector_store(type, initializer), create with create_vector_store(VectorStoreConfig(...), IndexSchema(...)).
• LLM providers: implement completion or embedding interfaces, register with register_completion or register_embedding; model config model_extra fields are passed through to initializers.
• LLM utilities: tokenizer, retry, rate-limit, metrics store/processor/writer, template manager/engine factories have analogous register_* and create_* helpers.
• Index workflows: register workflow callables with PipelineFactory.register(name, workflow) and methods with PipelineFactory.register_pipeline(name, [workflow_names...]).
• Graph helpers: use deterministic DataFrame helpers such as compute_degree, connected_components, largest_connected_component, and stable_lcc for offline graph checks.

Recommended Workflow

1. Identify the package boundary first: storage/cache/input/chunking/vector/LLM/graph/workflow.
2. Inspect the initializer signature of the target base or built-in implementation.
3. Decide factory scope: transient for fresh state, singleton only for shareable clients keyed by complete init args.
4. Register a unique key before calling create_*; duplicate keys overwrite the previous initializer in the process.
5. Create a tiny offline mock before adding optional cloud/database dependencies.
6. Add a smoke check for --help, factory registration, and one deterministic operation.
7. If wiring through GraphRAG config, move user-facing config guidance to ../configuration-data/.

Bundled Scripts

• scripts/register_mock_extensions.py demonstrates offline custom storage, cache, input reader, vector store, and direct factory patterns.
• scripts/validate_graph_helpers.py checks degree, connected components, stable LCC normalization/order, timestamp explosion, and filter expressions on deterministic in-memory data.

Both scripts are examples for future agents to copy or adapt inside their own workspace. They do not require external services.

References

• references/factory-extension-recipes.md for concrete registration recipes and design notes.
• references/package-optional-dependencies.md for guarded dependency and service guidance.
• references/troubleshooting.md for factory, config, service, vector filter, and graph-helper failures.