Many API References under the /modules path result in a 500 Internal Server Error when accessed

[jay0815]

Describe the bug
When accessing the documentation pages like https://ts.llamaindex.ai/docs/llamaindex/modules/chat_engine and https://ts.llamaindex.ai/docs/llamaindex/modules/node_parser, some API References return a 500 Internal Server Error from the server.

To Reproduce

// Open your browser and navigate to:
https://ts.llamaindex.ai/docs/api/classes/ContextChatEngine
// or
https://ts.llamaindex.ai/docs/api/classes/LlamaParseReader

Expected behavior
All documentation pages should load correctly without errors.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: macOS
• JS Runtime / Framework / Bundler (select all applicable)
• Node.js
• Deno
• Bun
• Next.js
• ESBuild
• Rollup
• Webpack
• Turbopack
• Vite
• Waku
• Edge Runtime
• AWS Lambda
• Cloudflare Worker
• Others (please elaborate on this)
• Version [e.g. 22]

Additional context
This issue may be related to the server-side rendering or routing configuration in the Next.js setup used for the website.

[jay0815]

@himself65 I think I’ve discovered the cause of the issue. Could I submit a PR?

[jay0815]

Outstanding questions:

1. Should https://ts.llamaindex.ai/docs/api/ display all exported classes, enumerations, functions, interfaces, type aliases, and variables from all packages, or only the collection of API References found under https://ts.llamaindex.ai/docs/llamaindex/modules?
2. The current issue is that some API References are not being exported.
3. Fixing this bug requires clarifying the intended purpose of the content shown on https://ts.llamaindex.ai/docs/api/.

[marcusschiesser]

@jay0815 a PR fixing this is highly appreciated! How about https://ts.llamaindex.ai/docs/api/ shows exported stuff grouped by package?
Developers should either use llamaindex or one of the provider packages, e.g. @llamaindex/openai - so these should the only packages listed there

[jay0815]

Hi @marcusschiesser

As a user, I expect the content under docs/api/ to be grouped by package (refer to https://langchain-ai.github.io/langgraphjs/reference/index.html and https://nodejs.org/docs/latest/api/). Therefore, I fully agree with the proposed approach.

Additionally, using a comparison script I developed, I have identified three issues causing the current bug:

1.Some packages are not exported via src/index.ts.
2.Some interfaces or classes are not exported, yet they are referenced in the documentation.
3.There is a “ResponseSynthesizer” class, but its actual name has been changed to BaseSynthesizer.

Based on these issues, I propose that the PR be divided into four parts, each addressing a different stage of the fix and optimization:

1. Modify the typedoc configuration: Generate mdx files from various levels of .ts files under the packages directory to cover as much content as possible, thereby resolving the majority of issues.
2. Adjust the output directory structure: Group files by package, and then within each package, generate subdirectories for classes, enumerations, functions, interfaces, type aliases, and variables (e.g., docs/api/package-name/classes, docs/api/package-name/enumerations, etc.).
3. Correct existing links: Adjust the API links in the mdx files under docs/cloud and docs/llamaindex by appending the corresponding package names to ensure the links are correct.
4. Further optimization: Once each package is standardized to export only the necessary content, revert the changes in step 1 to reduce the generation of API documentation for content that is intended for internal use, even though it is exported.

If the priority is to first fix the usability of the documentation, these can be split into four separate PRs, representing different stages of the fix and optimization plan.

[jay0815]

Regarding the fix for

Modify the typedoc configuration: Generate mdx files from various levels of .ts files under the packages directory to cover as much content as possible, thereby resolving the majority of issues

The fix is nearly complete. However, there are a few issues that require your confirmation to help me finish the fix:

1. Please help me check whether BaseSynthesizer is the same as the ResponseSynthesizer mentioned in the documentation.
2. In the response-synthesizers package, I couldn’t find SimpleResponseBuilder. Should MultiModal be used as a replacement for SimpleResponseBuilder?
3. PapaCSVReader has been refactored in llamaindex@0.8.0, and csv-parse has replaced papaparse. However, papaparse is still present in the dependencies. Should CSVReader be used to replace PapaCSVReader?

@marcusschiesser @himself65

[jay0815]

Regarding the fix for

Modify the typedoc configuration: Generate mdx files from various levels of .ts files under the packages directory to cover as much content as possible, thereby resolving the majority of issues

The fix is nearly complete. However, there are a few issues that require your confirmation to help me finish the fix:

1. Please help me check whether BaseSynthesizer is the same as the ResponseSynthesizer mentioned in the documentation.
2. In the response-synthesizers package, I couldn’t find SimpleResponseBuilder. Should MultiModal be used as a replacement for SimpleResponseBuilder?
3. PapaCSVReader has been refactored in llamaindex@0.8.0, and csv-parse has replaced papaparse. However, papaparse is still present in the dependencies. Should CSVReader be used to replace PapaCSVReader?

@marcusschiesser @himself65

Once confirmed, I’ll immediately implement the remaining changes and commit them. Currently, I’m working on adjusting the output directory structure as specified in

Adjust the output directory structure: Group files by package, and then within each package, generate subdirectories for classes, enumerations, functions, interfaces, type aliases, and variables (e.g., docs/api/package-name/classes, docs/api/package-name/enumerations, etc.).

[himself65]

Perfect

[thucpn]

Hi @jay0815, thanks for your questions! Here are the answers for you:

1. Please help me check whether BaseSynthesizer is the same as the ResponseSynthesizer mentioned in the documentation.

No, they are not the same. ResponseSynthesizer has been removed and replaced by the getResponseSynthesizer factory function. I think we need to update the outdated sections in the documentation. Link to the changes

2. In the response-synthesizers package, I couldn’t find SimpleResponseBuilder. Should MultiModal be used as a replacement for SimpleResponseBuilder?

No, SimpleResponseBuilder is different from MultiModal. It is an old response mode that has been removed. Now, we only have the following modes: "refine", "compact", "tree_summarize", "multi_modal". Therefore, I think we can remove it from the documentation.
See:

LlamaIndexTS/packages/core/src/synthesizers/builders.ts

Line 34 in 0f64084

export class SimpleResponseBuilder implements ResponseBuilder {

3. PapaCSVReader has been refactored in llamaindex@0.8.0, and csv-parse has replaced papaparse. However, papaparse is still present in the dependencies. Should CSVReader be used to replace PapaCSVReader?

Yes, we should replace PapaCSVReader in the documentation with CSVReader. Also, remove "papaparse" from the dependencies.
Link to the changes

Btw, to check for missing documents, we added a checker to detect missing API docs. You can try running pnpm validate-links in apps/next to see what fails. We have opened a PR here to enable that checker: #1751. Please use it for your fix as well.

[jay0815]

Hi @jay0815, thanks for your questions! Here are the answers for you:

1. Please help me check whether BaseSynthesizer is the same as the ResponseSynthesizer mentioned in the documentation.

No, they are not the same. ResponseSynthesizer has been removed and replaced by the getResponseSynthesizer factory function. I think we need to update the outdated sections in the documentation. Link to the changes

2. In the response-synthesizers package, I couldn’t find SimpleResponseBuilder. Should MultiModal be used as a replacement for SimpleResponseBuilder?

No, SimpleResponseBuilder is different from MultiModal. It is an old response mode that has been removed. Now, we only have the following modes: "refine", "compact", "tree_summarize", "multi_modal". Therefore, I think we can remove it from the documentation. See:

LlamaIndexTS/packages/core/src/synthesizers/builders.ts

Line 34 in 0f64084

export class SimpleResponseBuilder implements ResponseBuilder {

3. PapaCSVReader has been refactored in llamaindex@0.8.0, and csv-parse has replaced papaparse. However, papaparse is still present in the dependencies. Should CSVReader be used to replace PapaCSVReader?

Yes, we should replace PapaCSVReader in the documentation with CSVReader. Also, remove "papaparse" from the dependencies. Link to the changes

Btw, to check for missing documents, we added a checker to detect missing API docs. You can try running pnpm validate-links in apps/next to see what fails. We have opened a PR here to enable that checker: #1751. Please use it for your fix as well.

Thank you very much for your reply, which helped confirm the direction of my modifications. Yesterday, I also reviewed the commit history and referred to the llamaindex Python documentation, and I made adjustments and revisions to the documentation related to ResponseSynthesizer. I can now submit a PR. @thucpn