Fix/20706 chonkie init doc by ObinnaIheanachor · Pull Request #20713 · run-llama/llama_index

ObinnaIheanachor · 2026-02-17T09:28:08Z

Description

MetadataAwareTextSplitter subclasses lose their constructor docstring because Pydantic replaces init at runtime.
As a result, help(Subclass.init) shows the BaseModel docs:

"Create a new model by parsing and validating input data from keyword arguments."

This affects all integrations, not just Chonkie.

Fixes #20706

New Package?

Did I fill in the tool.llamahub section in the pyproject.toml and provide a detailed README.md for my new integration or package?

Yes
No

Version Bump?

Did I bump the version in the pyproject.toml file of the package I am updating? (Except for the llama-index-core package)

Yes
No

Type of Change

Please delete options that are not relevant.

Bug fix (non-breaking change which fixes an issue)

How Has This Been Tested?

Added core regression test: test_metadataaware_init_doc.py
Converted Chonkie test into a smoke test
Verified repro from [Bug]: documentation override for classes inheriting from MetadataAwareTextSplitter #20706 now passes
I added new unit tests to cover this change
I believe this change is already covered by existing unit tests

Suggested Checklist:

I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes

…nments Some chunkers depend on torch/sentence-transformers and fail to import in CI/minimal installs. Skip them when dependencies are unavailable so the integration test suite remains deterministic.

ObinnaIheanachor · 2026-02-17T09:30:28Z

I reproduced the issue locally using the linked repro notebook.

Root cause: Pydantic replaces __init__ at runtime, which overwrites the integration constructor docstring.

This attaches the intended docstring to the generated constructor and adds a regression test to prevent future regressions.

Happy to adjust if preferred approach differs!

chonk-lain

this doesn't fix the current issue at hand, try applying the relevant change then try again.

chonk-lain · 2026-02-17T09:59:35Z

...ions/node_parser/llama-index-node-parser-chonkie/llama_index/node_parser/chonkie/chunkers.py

+CHUNKER_INIT_DOC = f"""Initialize with a Chonkie chunker instance or create one if not provided.
+
+Args:
+    chunker (Union[str, BaseChunker]): The chunker to use. Must be one of {CHUNKERS} or a chonkie chunker instance.
+    callback_manager (Optional[CallbackManager]): Callback manager for handling callbacks.
+    include_metadata (bool): Whether to include metadata in the nodes.
+    include_prev_next_rel (bool): Whether to include previous/next relationships.
+    id_func (Optional[Callable]): Function to generate node IDs.
+    **kwargs: Additional keyword arguments for the underlying Chonkie chunker.
+""".strip()
+
+# Pydantic replaces __init__ at runtime; attach docs to the generated constructor so help() is meaningful.
+try:
+    Chunker.__init__.__doc__ = CHUNKER_INIT_DOC
+except AttributeError:
+    pass


move the docstring definition to line 52~53
as what you're testing against is my patch which is a working implementation i made on the fly.

AstraBert

This doesn't appear to be fixing the underlying cause of the docstring overwriting problem, so I would encourage to fix that rather than have a chonkie-specific fix

…__ (fixes run-llama#20706)

…reTextSplitter Pydantic replaces __init__ at runtime, causing subclass constructor docs to be overwritten by BaseModel docs. Restore the subclass docstring via __init_subclass__ so help() and introspection behave correctly. Fixes run-llama#20706

ObinnaIheanachor · 2026-02-17T14:07:31Z

Thanks for the feedback.
I’ve moved the fix into MetadataAwareTextSplitter so it restores subclass constructor docstrings generically for all integrations.
Added a core regression test and simplified the Chonkie test into a smoke test.

The minimal repro from the issue now works without any integration-specific patch.

AstraBert

Looks like it's working! I just pushed a linting fix and once the CI is done I will merge 🙌

Restore subclass __init__ docstring using __pydantic_init__ without touching pydantic wrappers.

ObinnaIheanachor · 2026-02-18T17:12:24Z

Looks like it's working! I just pushed a linting fix and once the CI is done I will merge 🙌

Thanks! I’ve pushed the updates addressing the core MetadataAwareTextSplitter behavior and added regression coverage.
Could you approve workflows so CI can run?

chonk-lain

@ObinnaIheanachor
the current implementation needs some revision, the logic is off the target.
i haven't dug too deep into the current issue at hand, but my gut feeling is saying that the issue lies with DispatcherSpanMixin and not with the MetadataAwareTextSplitter, this is a hunch based on some of my earlier findings which you can find in #20622 (comment) (i un-cloppased the section for easier read) also this is not confirmed hunch so take it as just a guiding lead that might or might not be spot on

this is a too low level issue with how python functions between what help and inspect are retrieving the docs and finding out where things started to go wrong is essential as this touches really close to the fundamentals of the python programming language and the current code base.

llama-index-core/llama_index/core/node_parser/interface.py

...ndex-integrations/node_parser/llama-index-node-parser-chonkie/tests/test_chunker_init_doc.py

chonk-lain

the second approach does indeed work ✅

kudos to @ObinnaIheanachor for the fix 🙌
also now for the tests you are using pydoc and not inspect which is a valid choice for the tests here (under the hood help calls in pydoc)

also cc @AstraBert for extra viz

AstraBert · 2026-02-20T11:31:44Z

Mmhh tests are failing @ObinnaIheanachor:

assert "my custom doc" in rendered
E       AssertionError: assert 'my custom doc' in 'Python Library Documentation: function __init__ in module test_metadataaware_init_doc\n\n_\x08__\x08_i\x08in\x08ni\x08it\x08t_\x08__\x08_(self)\n    My custom doc\n'

Looks like a minor capitalization error

…g assertions

ObinnaIheanachor · 2026-02-20T13:08:55Z

@AstraBert I've normalized expected strings to lowercase to match pydoc.render_doc() output across Python versions and avoid formatting/casing inconsistencies.

ObinnaIheanachor added 3 commits February 17, 2026 08:56

Fix Chunker __init__ docstring overridden by Pydantic

dd0a422

Add regression test for Chunker __init__ docstring

a571a9b

Skip optional chunkers requiring heavy dependencies in minimal enviro…

95f3a43

…nments Some chunkers depend on torch/sentence-transformers and fail to import in CI/minimal installs. Skip them when dependencies are unavailable so the integration test suite remains deterministic.

dosubot bot added the size:M This PR changes 30-99 lines, ignoring generated files. label Feb 17, 2026

ObinnaIheanachor mentioned this pull request Feb 17, 2026

[Bug]: documentation override for classes inheriting from MetadataAwareTextSplitter #20706

Open

Guard docstring assignment for wrapped constructors

5bf64fc

chonk-lain suggested changes Feb 17, 2026

View reviewed changes

AstraBert reviewed Feb 17, 2026

View reviewed changes

ObinnaIheanachor added 3 commits February 17, 2026 13:23

Fix Chunker constructor docstring by defining docstring inside __init…

5cd8818

…__ (fixes run-llama#20706)

test(chonkie): convert init doc test to smoke test after core fix

fc9a969

chore: lint

4147739

AstraBert approved these changes Feb 18, 2026

View reviewed changes

dosubot bot added the lgtm This PR has been approved by a maintainer label Feb 18, 2026

AstraBert and others added 3 commits February 18, 2026 13:05

fix: test capitalization

83bbd93

Fix MetadataAwareTextSplitter docstring override for pydantic subclasses

7acbf43

Restore subclass __init__ docstring using __pydantic_init__ without touching pydantic wrappers.

Fix: preserve subclass __init__ docstring for MetadataAwareTextSplitter

b201fe6

chonk-lain suggested changes Feb 19, 2026

View reviewed changes

ObinnaIheanachor added 2 commits February 19, 2026 10:02

test: assert MetadataAwareTextSplitter init doc via help() output

2185547

Fix: preserve MetadataAwareTextSplitter __init__ docs in help()

0e692fc

chonk-lain approved these changes Feb 19, 2026

View reviewed changes

chore: vbump and lint

021b35a

dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. and removed size:M This PR changes 30-99 lines, ignoring generated files. labels Feb 20, 2026

ObinnaIheanachor added 2 commits February 20, 2026 13:05

test: normalize pydoc output for stable docstring assertions

087cad3

test: normalize pydoc output casing for deterministic help() docstrin…

75dbae3

…g assertions

Comments

Conversation

ObinnaIheanachor commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

New Package?

Version Bump?

Type of Change

How Has This Been Tested?

Suggested Checklist:

Uh oh!

ObinnaIheanachor commented Feb 17, 2026

Uh oh!

chonk-lain left a comment

Choose a reason for hiding this comment

Uh oh!

chonk-lain Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

AstraBert left a comment

Choose a reason for hiding this comment

Uh oh!

ObinnaIheanachor commented Feb 17, 2026

Uh oh!

AstraBert left a comment

Choose a reason for hiding this comment

Uh oh!

ObinnaIheanachor commented Feb 18, 2026

Uh oh!

chonk-lain left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chonk-lain left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AstraBert commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ObinnaIheanachor commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ObinnaIheanachor commented Feb 17, 2026 •

edited

Loading

chonk-lain left a comment •

edited

Loading

AstraBert commented Feb 20, 2026 •

edited

Loading