Feature: Generic LlamaIndex Reader Plugin — wrap any reader via config

[evanerwee]

Package

lexical-graph

Problem statement

Adding support for new data sources (Confluence, Notion, Slack, Jira, Google Drive, etc.) currently requires writing a bespoke *_reader_provider.py for each one. This doesn't scale — LlamaIndex has 100+ reader packages, and each one follows the same pattern: import, instantiate with credentials, call load_data().

The real differences between readers are configuration (credentials, endpoints, filters), not code (import, instantiate, call, handle errors). We're writing the same boilerplate with different class names.

Proposed solution

A generic LlamaIndexPluginReaderProvider that wraps any LlamaIndex reader with just a config dict — no new Python file needed per reader.

from graphrag_toolkit.lexical_graph.indexing.load.readers.reader_provider_config import LlamaIndexPluginReaderConfig
from graphrag_toolkit.lexical_graph.indexing.load.readers.providers import LlamaIndexPluginReaderProvider

# Confluence — zero bespoke code
config = LlamaIndexPluginReaderConfig(
    package="llama-index-readers-confluence",
    module_path="llama_index.readers.confluence",
    reader_class="ConfluenceReader",
    init_args={"base_url": "https://mycompany.atlassian.net/wiki", "token": "..."},
    load_args={"space_key": "ENG"},
    timeout_seconds=60,
    max_retries=2,
    fail_on_error=False,
)
provider = LlamaIndexPluginReaderProvider(config)
docs = provider.read()

Same pattern for Notion, Slack, Jira, Google Drive, or any of the 100+ LlamaIndex readers.

Features

Feature	Description
Dynamic import	Resolves any llama-index-readers-* package at runtime
Configurable timeout	ThreadPoolExecutor-based timeout prevents hangs
Retry with backoff	Exponential backoff on transient errors (429, 503, timeouts)
Auth error detection	Recognizes 401/403 patterns — never retried, clear error message
Graceful degradation	fail_on_error=False returns [] instead of crashing pipelines
input_source flexibility	Auto-fallback if reader doesn't accept the kwarg
Document validation	Filters non-Document items, handles generators
Metadata enrichment	Optional metadata_fn to tag all documents
Module path resolution	Derives llama_index.readers.X from package name automatically

Error handling guarantees

• Missing package → ReaderImportError with pip install instructions
• Class not found → ReaderImportError listing available classes
• Bad constructor args → ValueError with signature hint
• Auth failure (401/403) → ReaderAuthError, never retried
• Transient error (429/503) → retried with exponential backoff
• Timeout → ReaderTimeoutError, retried if attempts remain
• All retries exhausted → RuntimeError or [] based on config

Test coverage

30 unit tests covering:

• Happy path (4 tests)
• Import errors (3)
• Config validation (2)
• Auth failures (7 parametrized)
• Timeout enforcement (2)
• Retry with backoff (4)
• Empty results (2)
• Partial failures / generators (2)
• Module path resolution (2)
• Custom load methods (2)

Live tested

$ python3.12 -c "..."  # DadJokesReader via plugin
✅ 1 joke: Why didn't the orange win the race? It ran out of juice.

Implementation

Branch: feat/generic-llama-index-reader-plugin

Files:

• lexical-graph/src/.../providers/llama_index_plugin_reader_provider.py (302 lines)
• lexical-graph/src/.../reader_provider_config.py (+34 lines — config dataclass)
• lexical-graph/src/.../providers/__init__.py (+2 lines — registration)
• lexical-graph/tests/.../test_llama_index_plugin_reader_provider.py (596 lines)

PR ready to submit on request.

Alternatives considered

1. Keep writing bespoke providers — doesn't scale, duplicates error handling
2. Auto-generate providers from LlamaIndex metadata — fragile, breaks on API changes
3. Generic plugin (this proposal) — one file handles all readers, config-driven, tested

[mykola-pereyma]

Thank you for this proposal — the problem statement is well researched and the operational layer (timeout, retry, error classification) looks solid. We would like to suggest some security hardening items and additional tests to make this more robust.

The implementation has good structure, we just need to close few gaps around input validation and credential handling. Below is what we suggest with specific code examples so it is clear what we are asking for.

---

1. Namespace allowlist before importlib.import_module

Why: Without restriction, any installed Python module can be loaded and any attribute called. module_path="os" + reader_class="system" gives arbitrary command execution. module_path="shutil" + reader_class="rmtree" gives filesystem destruction. This is the #1 risk in any dynamic loader — Django, SQLAlchemy, and Airflow all restrict loadable namespaces for this reason.

Current code — no validation before import:

module_path = self._resolve_module_path()  # any string
module = importlib.import_module(module_path)  # loads anything

Proposed change — add as a class attribute and validate before the import call:

class LlamaIndexPluginReaderProvider:
    # Overridable in subclasses for custom reader namespaces
    ALLOWED_MODULE_PREFIXES = ("llama_index.readers.",)

    def _validate_module_path(self, module_path: str) -> None:
        if not any(module_path.startswith(prefix) for prefix in self.ALLOWED_MODULE_PREFIXES):
            raise ReaderImportError(
                f"Module '{module_path}' is not in the allowed namespace. "
                f"Allowed prefixes: {self.ALLOWED_MODULE_PREFIXES}. "
                f"To allow custom namespaces, subclass and override ALLOWED_MODULE_PREFIXES."
            )

Important: Validation must apply to the RESOLVED module path (after _resolve_module_path), whether user-provided via module_path or derived from package.

Extensibility for custom namespaces:

class MyCompanyReaderProvider(LlamaIndexPluginReaderProvider):
    ALLOWED_MODULE_PREFIXES = ("llama_index.readers.", "mycompany.readers.")

---

2. Interface validation BEFORE instantiation

Why: Python constructors (__init__) execute arbitrary code — network calls, file writes, process spawning. If the loaded class is not a legitimate reader, its constructor should never run. Django validates that a loaded backend inherits DatabaseWrapper before instantiating it. SQLAlchemy checks Dialect subclass before calling create_engine. Same principle: validate interface first, instantiate second.

Current code — instantiates immediately after getattr:

reader_cls = getattr(module, class_name)
self._reader = reader_cls(**init_args)  # constructor runs arbitrary code

Proposed change — add between getattr and instantiation:

if not callable(reader_cls):
    raise ReaderImportError(f"'{class_name}' in '{module_path}' is not callable")

load_method_name = self._config.load_method or "load_data"
if not hasattr(reader_cls, load_method_name) and not hasattr(reader_cls, "lazy_load"):
    raise ReaderImportError(
        f"'{class_name}' does not implement '{load_method_name}()' or 'lazy_load()'. "
        f"It may not be a LlamaIndex reader."
    )

---

3. Restrict load_method to safe values

Why: The load_method config field controls which method gets called on the instantiated reader. Without restriction, an attacker can call any method — including dunder methods (__delattr__, __class__, __subclasses__) or internal methods that mutate state. Only reader-specific methods should ever be invoked by the plugin.

Current code — accepts any string as method name:

load_method_name = self._config.load_method or "load_data"
load_fn = getattr(self._reader, load_method_name, None)  # any method

Proposed change:

ALLOWED_LOAD_METHODS = ("load_data", "lazy_load", "aload_data")

def _resolve_load_function(self) -> Optional[Any]:
    load_method_name = self._config.load_method or "load_data"
    if load_method_name not in self.ALLOWED_LOAD_METHODS:
        raise ValueError(
            f"load_method '{load_method_name}' is not allowed. "
            f"Permitted: {self.ALLOWED_LOAD_METHODS}"
        )
    # ... rest of existing code

---

4. Environment variable resolution in init_args and load_args

Why: Credentials as plaintext strings in config objects cannot be safely committed to source control, shared in documentation/examples, or rotated without code changes. The $VAR_NAME resolution pattern is industry standard — used by Docker Compose, Kubernetes manifests, CloudFormation, and GitHub Actions. It separates "what to connect to" (config) from "how to authenticate" (environment).

Current code — raw credential strings passed directly:

init_args = self._config.init_args or {}  # {"token": "ghp_xxxx..."} — plaintext
self._reader = reader_cls(**init_args)

Proposed change — resolver applied to both init_args and load_args:

_ENV_VAR_PATTERN = re.compile(r'^\$([A-Z_][A-Z0-9_]*)$')

def _resolve_env_vars(self, args: dict) -> dict:
    """Resolve $VAR_NAME references in dict values from environment.

    Only resolves top-level string values matching $UPPER_CASE_NAME.
    Nested dicts, non-string values, lowercase vars, and mid-string
    dollar signs are passed through unchanged.
    """
    if not args:
        return args
    resolved = {}
    for key, value in args.items():
        if isinstance(value, str):
            match = _ENV_VAR_PATTERN.match(value)
            if match:
                env_name = match.group(1)
                env_value = os.environ.get(env_name)
                if env_value is None:
                    raise ValueError(
                        f"Config field '{key}' references ${env_name} "
                        f"but it is not set in the environment"
                    )
                resolved[key] = env_value
                continue
        resolved[key] = value
    return resolved

---

5. Credential values must never appear in logs

Why: The current implementation logs init_args keys: [...] (keys only) which is correct. But without a test enforcing this contract, a future contributor adding debug logging could accidentally include values. A single regression test pins the security invariant permanently.

Proposed — add a test:

def test_credentials_not_logged(self, caplog):
    secret = "super_secret_token_value_12345"
    config = LlamaIndexPluginReaderConfig(
        module_path="llama_index.readers.github",
        reader_class="GithubRepositoryReader",
        init_args={"github_token": secret},
    )
    with caplog.at_level(logging.DEBUG):
        try:
            LlamaIndexPluginReaderProvider(config)
        except Exception:
            pass
    assert secret not in caplog.text, "Credential value leaked into logs"

---

6. Default fail_on_error=True

Why: When fail_on_error=False, a failed reader returns [] and the pipeline continues building a graph with silently missing data. The resulting graph looks complete but is actually partial, and downstream consumers produce wrong answers without any signal that data is missing. Every other reader in the codebase raises on failure by default. Graceful degradation should be an explicit opt-in.

Current: fail_on_error: bool = False
Proposed: fail_on_error: bool = True

---

7. Validate package name in error messages

Why: When import fails, the error message includes pip install {package_name} where package_name comes from user config. If a user typos the package (e.g., llama-index-readers-confluenec), a supply-chain attacker who pre-registered that typosquatted name on PyPI would benefit from the library actively telling users to install it. Only suggest pip install for names matching the known LlamaIndex pattern.

Proposed:

_VALID_PACKAGE_PATTERN = re.compile(r'^llama-index-readers?-[a-z0-9-]+$')

if self._config.package and _VALID_PACKAGE_PATTERN.match(self._config.package):
    msg = f"Install the reader package: pip install {install_hint}"
else:
    msg = f"Failed to import '{module_path}'. Ensure the reader package is installed."

---

Could you please make these adjustments and add the corresponding tests? Once done, feel free to raise a PR and we will review it.

[evanerwee]

Update: All 7 security hardening items implemented

Thanks @mykola-pereyma for the thorough review. All items have been addressed:

#	Item	Status
1	Namespace allowlist (ALLOWED_MODULE_PREFIXES)	✅ Implemented + 4 tests
2	Interface validation before instantiation	✅ Implemented + 2 tests
3	Restrict load_method (ALLOWED_LOAD_METHODS)	✅ Implemented + 2 tests
4	Env var resolution ($VAR_NAME in args)	✅ Implemented + 4 tests
5	Credential logging test	✅ 1 test pinning the invariant
6	Default fail_on_error=True	✅ Changed
7	Package name validation (typosquat protection)	✅ Implemented + 3 tests

46 tests passing (30 original + 16 new security tests).

PR: #390

All extensibility points preserved — custom namespaces via subclass override:

class MyProvider(LlamaIndexPluginReaderProvider):
    ALLOWED_MODULE_PREFIXES = ("llama_index.readers.", "mycompany.readers.")