Merge pull request #113 from SylphAI-Inc/li

Beta iteration [first round documents]

README.md

@@ -2,10 +2,10 @@
 
 <!-- [![release](https://img.shields.io/github/v/release/SylphAI-Inc/LightRAG?sort=semver)](https://github.com/SylphAI-Inc/LightRAG/releases) -->
 <!-- [![Dependency Status](https://img.shields.io/librariesio/github/SylphAI-Inc/LightRAG?style=flat-square)](https://libraries.io/github/SylphAI-Inc/LightRAG) -->
+<!-- [![GitHub star chart](https://img.shields.io/github/stars/SylphAI-Inc/LightRAG?style=flat-square)](https://star-history.com/#SylphAI-Inc/LightRAG) -->
 [![License](https://img.shields.io/github/license/SylphAI-Inc/LightRAG)](https://opensource.org/license/MIT)
 [![PyPI](https://img.shields.io/pypi/v/lightRAG?style=flat-square)](https://pypi.org/project/lightRAG/)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/lightRAG?style=flat-square)](https://pypistats.org/packages/lightRAG)
-[![GitHub star chart](https://img.shields.io/github/stars/SylphAI-Inc/LightRAG?style=flat-square)](https://star-history.com/#SylphAI-Inc/LightRAG)
 [![Open Issues](https://img.shields.io/github/issues-raw/SylphAI-Inc/LightRAG?style=flat-square)](https://github.com/SylphAI-Inc/LightRAG/issues)
 [![](https://dcbadge.vercel.app/api/server/zt2mTPcu?compact=true&style=flat)](https://discord.gg/zt2mTPcu)
 
@@ -22,9 +22,10 @@ It is *light*, *modular*, and *robust*, with a 100% readable codebase.
 
 LLMs are like water; they can be shaped into anything, from GenAI applications such as chatbots, translation, summarization, code generation, and autonomous agents to classical NLP tasks like text classification and named entity recognition. They interact with the world beyond the model’s internal knowledge via retrievers, memory, and tools (function calls). Each use case is unique in its data, business logic, and user experience.
 
-Because of this, no library can provide out-of-the-box solutions. Users must build toward their own use case. This requires the library to be modular, robust, and have a clean, readable codebase. The only code you should put into production is code you either 100% trust or are 100% clear about how to customize and iterate.
+Because of this, no library can provide out-of-the-box solutions. Users must build towards their own use case. This requires the library to be modular, robust, and have a clean, readable codebase. The only code you should put into production is code you either 100% trust or are 100% clear about how to customize and iterate.
+
+This is what LightRAG is: light, modular, and robust, with a 100% readable codebase.
 
-LightRAG is born to be light, modular, and robust, with a 100% readable codebase.
 
 Further reading: [Introduction](https://lightrag.sylph.ai/), [Design Philosophy](https://lightrag.sylph.ai/tutorials/lightrag_design_philosophy.html) and [Class hierarchy](https://lightrag.sylph.ai/tutorials/class_hierarchy.html).
 
@@ -57,8 +58,11 @@ class Net(nn.Module):
 ``` -->
 # LightRAG Task Pipeline
 
+We will ask the model to respond with ``explanation`` and ``example`` of a concept. To achieve this, we will build a simple pipeline to get the structured output as ``QAOutput``.
+
+## Well-designed Base Classes
 
-We will ask the model to respond with ``explanation`` and ``example`` of a concept. And we will build a pipeline to get the structured output as ``QAOutput``.
+This leverages our two and only powerful base classes: `Component` as building blocks for the pipeline and `DataClass` to ease the data interaction with LLMs.
 
 ```python
 
@@ -119,9 +123,9 @@ output = qa("What is LLM?")
 print(output)
 ```
 
-**Structure of the pipeline**
+## Clear Pipeline Structure
 
-Here is what we get from ``print(qa)``:
+Simply by using `print(qa)`, you can see the pipeline structure, which helps users understand any LLM workflow quickly.
 
 ```
 QA(
@@ -161,16 +165,17 @@ QA(
 )
 ```
 
-**The output**
+**The Output**
 
+We structure the output to both track the data and potential errors if any part of the Generator component fails.
 Here is what we get from ``print(output)``:
 
 ```
 GeneratorOutput(data=QAOutput(explanation='LLM stands for Large Language Model, which refers to a type of artificial intelligence designed to process and generate human-like language.', example='For instance, LLMs are used in chatbots and virtual assistants, such as Siri and Alexa, to understand and respond to natural language input.'), error=None, usage=None, raw_response='```\n{\n  "explanation": "LLM stands for Large Language Model, which refers to a type of artificial intelligence designed to process and generate human-like language.",\n  "example": "For instance, LLMs are used in chatbots and virtual assistants, such as Siri and Alexa, to understand and respond to natural language input."\n}', metadata=None)
 ```
-**See the prompt**
+**Focus on the Prompt**
 
-Use the following code:
+Use the following code will let us see the prompt after it is formatted:
 
 ```python
 
@@ -203,6 +208,28 @@ User: What is LLM?
 You:
 ````
 
+## Model-agnostic
+
+
+You can switch to any model simply by using a different model_client (provider) and model_kwargs.
+Let's use OpenAI's gpt-3.5-turbo model on the same pipeline.
+
+
+You can switch to any model simply by using a different `model_client` (provider) and `model_kwargs`.
+Let's use OpenAI's `gpt-3.5-turbo` model.
+
+```python
+from lightrag.components.model_client import OpenAIClient
+
+self.generator = Generator(
+    model_client=OpenAIClient(),
+    model_kwargs={"model": "gpt-3.5-turbo"},
+    template=qa_template,
+    prompt_kwargs={"output_format_str": parser.format_instructions()},
+    output_processors=parser,
+)
+```
+
 
 # Quick Install
 

docs/source/apis/components/index.rst

@@ -82,6 +82,7 @@ Reasoning
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    components.model_client
    components.retriever

docs/source/index.rst

@@ -9,14 +9,14 @@
 .. raw:: html
 
    <div style="text-align: center; margin-bottom: 20px;">
-
       <a href="https://pypi.org/project/lightRAG/"><img src="https://img.shields.io/pypi/v/lightRAG?style=flat-square" alt="PyPI Version"></a>
-      <a href="https://star-history.com/#SylphAI-Inc/LightRAG"><img src="https://img.shields.io/github/stars/SylphAI-Inc/LightRAG?style=flat-square" alt="GitHub Stars"></a>
-      <a href="https://discord.gg/zt2mTPcu"><img src="https://dcbadge.vercel.app/api/server/zt2mTPcu?compact=true&style=flat" alt="Discord"></a>
+      <a href="https://discord.gg/ezzszrRZvT">  <img src="https://img.shields.io/discord/1065084981904429126?style=flat-square" alt="Discord"></a>
       <a href="https://opensource.org/license/MIT"><img src="https://img.shields.io/github/license/SylphAI-Inc/LightRAG" alt="License"></a>
    </div>
 
 
+.. <a href="https://star-history.com/#SylphAI-Inc/LightRAG"><img src="https://img.shields.io/github/stars/SylphAI-Inc/LightRAG?style=flat-square" alt="GitHub Stars"></a>
+
 ..  <a href="https://pypistats.org/packages/lightRAG"><img src="https://img.shields.io/pypi/dm/lightRAG?style=flat-square" alt="PyPI Downloads"></a>
 
 
@@ -244,9 +244,10 @@ We are building a library that unites the two worlds, forming a healthy LLM appl
 ..    resources/index
 
 .. hide the for contributors now
-..    :glob:
-..    :maxdepth: 1
-..    :caption: For Contributors
-..    :hidden:
 
-..    contributor/index
+   .. :glob:
+   .. :maxdepth: 1
+   .. :caption: For Contributors
+   .. :hidden:
+
+   .. contributor/index

docs/source/tutorials/agent.rst

@@ -504,6 +504,8 @@ The above example will be formated as:
 **Subclass ReActAgent**
 
 If you want to customize the agent further, you can subclass the :class:`ReActAgent<components.agent.react.ReActAgent>` and override the methods you want to change.
+
+
 .. .. figure:: /_static/images/query_1.png
 ..    :align: center
 ..    :alt: DataClass

docs/source/tutorials/component.rst

@@ -253,7 +253,7 @@ Using a decorator is an even more convenient way to create a component from a fu
 
 .. code-block:: python
 
-    .. @fun_to_component
+    @fun_to_component
     def add_one(x):
         return x + 1
 
@@ -275,7 +275,7 @@ Let's put the `FunComponent`` and `DocQA`` together in a sequence:
 
 .. code-block:: python
 
-    from lightrag.core.component import Sequential
+    from lightrag.core.container import Sequential
 
     @fun_to_component
     def enhance_query(query:str) -> str:
@@ -318,7 +318,7 @@ The structure of the sequence using ``print(seq)``:
 
    - :class:`core.component.Component`
    - :class:`core.component.FunComponent`
-   - :class:`core.component.Sequential`
+   - :class:`core.container.Sequential`
    - :func:`core.component.fun_to_component`
 
 

docs/source/tutorials/generator.rst

@@ -12,7 +12,7 @@ Generator
 
 
 `Generator` is a user-facing orchestration component with a simple and unified interface for LLM prediction.
-It is a pipeline consisting of three subcomponents.
+It is a pipeline consisting of three subcomponents. By switching the prompt template, model client, and output parser, users have full control and flexibility.
 
 Design
 ---------------------------------------
@@ -26,11 +26,10 @@ Design
 
 
 
-
 The :class:`Generator<core.generator.Generator>` is designed to achieve the following goals:
 
 1. Model Agnostic: The Generator should be able to call any LLM model with the same prompt.
-2. Unified Interface: It should manage the pipeline from prompt(input)->model call -> output parsing.
+2. Unified interface: It manages the pipeline from prompt (input) -> model call -> output parsing, while still giving users full control over each part.
 3. Unified Output: This will make it easy to log and save records of all LLM predictions.
 4. Work with Optimizer: It should be able to work with Optimizer to optimize the prompt.
 
@@ -443,6 +442,7 @@ Besides these examples, LLM is like water, even in our library, we have componen
 - :class:`LLMRetriever<components.retriever.llm_retriever.LLMRetriever>` is a retriever that uses Generator to call LLM to retrieve the most relevant documents.
 - :class:`DefaultLLMJudge<eval.llm_as_judge.DefaultLLMJudge>` is a judge that uses Generator to call LLM to evaluate the quality of the response.
 - :class:`LLMOptimizer<optim.llm_optimizer.LLMOptimizer>` is an optimizer that uses Generator to call LLM to optimize the prompt.
+- :class:`ReAct Agent Planner<components.agent.react.ReActAgent>` is an LLM planner that uses Generator to plan and to call functions in ReAct Agent.
 
 Tracing
 ---------------------------------------
@@ -479,6 +479,7 @@ Coming soon!
    - :class:`tracing.generator_call_logger.GeneratorCallLogger`
    - :class:`tracing.generator_state_logger.GeneratorStateLogger`
    - :class:`components.retriever.llm_retriever.LLMRetriever`
+   - :class:`components.agent.react.ReActAgent`
    - :class:`eval.llm_as_judge.DefaultLLMJudge`
    - :class:`optim.llm_optimizer.LLMOptimizer`
    - :func:`utils.config.new_component`

docs/source/tutorials/index.rst

@@ -59,7 +59,7 @@ Additionally, what shines in LightRAG is that all orchestrator components, like
 You can easily make each component work with different models from different providers by switching out the `ModelClient` and its `model_kwargs`.
 
 
-We will introduce the libraries starting from the core base classes, then move to the RAG essentials, and finally to the agent essentials.
+We will introduce the library starting from the core base classes, then move to the RAG essentials, and finally to the agent essentials.
 With these building blocks, we will further introduce optimizing, where the optimizer uses building blocks such as Generator for auto-prompting and retriever for dynamic few-shot in-context learning (ICL).
 
 Building
@@ -126,8 +126,7 @@ Code path: :ref:`lightrag.core<apis-core>`. For abstract classes:
    * - :doc:`embedder`
      - The component that orchestrates model client (Embedding models in particular) and output processors.
    * - :doc:`retriever`
-     - The base class for all retrievers who in particular retrieve relevant documents from a given database to add **context** to the generator.
-
+     - The base class for all retrievers, which in particular retrieve relevant documents from a given database to add *context* to the generator.
 
 Data Pipeline and Storage
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^