deploy: cd066dc

_modules/utils/logger.html

@@ -509,7 +509,7 @@ <h1>Source code for utils.logger</h1><div class="highlight"><pre>
     <span class="n">save_dir</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">filename</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="n">enable_console</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
-    <span class="n">enable_file</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+    <span class="n">enable_file</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">logging</span><span class="o">.</span><span class="n">Logger</span><span class="p">:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;Get or configure a logger, including both the root logger and named logger.</span>
 
@@ -519,7 +519,7 @@ <h1>Source code for utils.logger</h1><div class="highlight"><pre>
 <span class="sd">        save_dir (Optional[str]): Directory to save log files. Defaults to &quot;./logs&quot;.</span>
 <span class="sd">        filename (Optional[str]): Name of the output log file. Defaults to &quot;lib.log&quot; for root logger and &quot;{name}.log&quot; for named logger.</span>
 <span class="sd">        enable_console (bool): Control the console output. Defaults to True.</span>
-<span class="sd">        enable_file (bool): Control the file output. Defaults to False.</span>
+<span class="sd">        enable_file (bool): Control the file output. Defaults to True.</span>
 
 <span class="sd">    Returns:</span>
 <span class="sd">        logging.Logger: The logger with the specified configuration.</span>

_sources/developer_notes/logging.rst.txt

@@ -1,22 +1,23 @@
 Logging
 ====================
 
-Python logging module [1]_ is a powerful and flexible tool for debugging and tracing.
-LightRAG uses the native ``logging`` module as the *first line of defense*.
+
+The Python logging module [1]_ is a powerful and flexible tool for debugging and tracing.
+LightRAG uses the native logging module as the *first line of defense*.
 
 Design
 --------------------
-Some libraries may use ``hooks`` [2]_ and ``Callbacks`` [3]_ [4]_, or advanced web-based debugging tools [5]_ [6]_ [7]_.
-``hooks`` and ``callbacks`` are conceptually similar in that they both allow users to execute custom code at specific points during the execution of a program.
-Both provide mechanisms to inject additional behavior in response to certain events or conditions, without modifying its core logic.
+Some libraries may use hooks [2]_ and callbacks [3]_ [4]_, or advanced web-based debugging tools [5]_ [6]_ [7]_.
+Hooks and callbacks are conceptually similar in that they both allow users to execute custom code at specific points during the execution of a program.
+Both provide mechanisms to inject additional behavior in response to certain events or conditions, without modifying the core logic.
 PyTorch defines, registers, and executes hooks mainly in its base classes like `nn.Module` and `Tensor`, without polluting the functional and user-facing APIs.
 
 At this point, our objectives are:
 
-1. Maximize the debugging capabilities via the simple logging module to keep the source code clean.
+1. Maximize debugging capabilities via the simple logging module to keep the source code clean.
 2. Additionally, as we can't always control the outputs of generators, we will provide customized logger and tracers(drop-in decorators) for them, for which we will explain in :doc:`logging_tracing`. This will not break the first objective.
 
-In the future, when we have more complex requirements from users, we will consider adding hooks/callbacks but doing it in a way to keep the functional and user-facing APIs clean.
+In the future, when we have more complex requirements from users, we will consider adding hooks/callbacks but we will do it in a way to keep the functional and user-facing APIs clean.
 
 How the library logs
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -28,8 +29,8 @@ In each file, we simply set the logger with the following code:
 
     log = logging.getLogger(__name__)
 
-And we will use `log` and decide what level of logging we want to use in each function.
-Here is how :ref:`Generator logs<core.generator>`.
+We then use `log` and decide what level of logging we want to use in each function.
+Here is how :ref:`Generator <core.generator>` logs.
 
 How users set up the logger
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -94,19 +95,70 @@ The output will be:
 
 Use Logger in Projects
 -------------------------
-There are three distinct ways to set up the logging in your project:
+There are two distinct ways to set up the logging in your project:
+
+1. Have both the library loggind and your application logging in a single file. This is the simplest setup.
+2. Use both root and named logger to log library and application logs separately.
+
+Set up all logs in one file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Assume your source code is at `src/task.py`. You can log simply by:
+
+.. code-block:: python
+
+    import logging
+
+    log = logging.getLogger(__name__)
+
+    class Task:
+        def __init__(self):
+            log.info("This is a user program child logger")
+
+In the main file, you can config a single root logger to log both library and application logs:
+
+.. code-block:: python
+
+    import logging
+    from lightrag.utils.logger import get_logger
+
+    root_logger = get_logger(level="DEBUG", save_dir="./logs") # log to ./logs/lib.log
+
+    # run code from the library components such as generator
+    # ....
+
+    root_logger.info("This is the log in the main file")
+
+This way, all logs will be saved in `./logs/lib.log`.
+
+Separate library and application logs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In some cases, if users prefer to separate the library and application logs, they can use a named logger.
+
+In the user program, such as at `src/task.py`, you can set up a named logger and logs to `./logs/my_app.log`:
+
+.. code-block:: python
+
+    from lightrag.utils.logger import get_logger
+
+    app_logger = get_logger(name="my_app", level="DEBUG", save_dir="./logs") # log to ./logs/my_app.log
+
+    class Task:
+        def __init__(self):
+            app_logger.info("This is a user program child logger")
+
+The difference is that you have already attached handlers to the app_logger.
+In the main file, you do not need to set up a root logger to enable your application logs.
+However, you can still set up a root logger to log the library logs separately if needed, and create another named logger to continue logging in the main file.
+
 
-1. Use root logger only and have all the library and your application logging in one file. This is the simplest setup.
-2. Use only named logger to log your application logs in a file.
-3. Use both root and named logger to log library and application logs separately.
 
-It works similarly if it is to be logged to console.
-Config 3 can be quite neat:
+.. It works similarly if it is to be logged to console.
+.. Config 3 can be quite neat:
 
-- You can enable different levels of logging for the library and your application.
-- You can easily focus on debugging your own code without being distracted by the library logs and still have the option to see the library logs if needed.
+.. - You can enable different levels of logging for the library and your application.
+.. - You can easily focus on debugging your own code without being distracted by the library logs and still have the option to see the library logs if needed.
 
-.. Create a named logger
+.. .. Create a named logger
 .. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. .. code-block:: python

_sources/get_started/version_control.rst.txt

@@ -0,0 +1,81 @@
+.. _release-guide:
+
+Release Version Control Guide
+=======================================
+
+Overview
+--------
+
+This guide outlines the process for releasing a new version of LightRAG. The workflow pipeline validates the version tag, builds the package, runs tests, publishes to PyPI, and creates a release on GitHub. The workflow is triggered by tags pushed to the **Release** branch. See `GitHub tags <https://docs.github.com/en/desktop/managing-commits/managing-tags-in-github-desktop>`_ for more details on version release tagging.
+
+Steps to Release a New Version
+------------------------------
+
+1. Update the **./lightrag/pyproject.toml** version number and the latest dependencies before pushing a new release. Make sure to follow the `PEP 440 rules <https://peps.python.org/pep-0440/>`_ to define the version, otherwise, the workflow will fail. For example:
+
+   .. code-block:: python
+
+      [tool.poetry]
+      name = "lightrag"
+      
+      version = "0.0.0-rc.1"
+      description = "The 'PyTorch' library for LLM applications. RAG=Retriever-Agent-Generator."
+
+2. Ensure your updates are the latest and correct. Update the version number following `Semantic Versioning <https://semver.org/>`. Here is a list of sample tags:
+
+   .. code-block:: none
+
+      Stable Release Tags:
+      v1.0.0
+      v1.2.3
+      Pre-release Tags:
+      v1.0.0-alpha.1
+      v1.0.0-beta.1
+      v1.0.0-rc.1
+      Custom Pre-release Tags:
+      v1.0.0-test.1
+      v1.1.0-dev.2
+      v1.2.3-pre.3
+      v2.0.0-exp.4
+      v2.1.0-nightly.5
+
+3. The workflow will be triggered when new releases are pushed to the **release** branch. Push the **./lightrag/pyproject.toml** to the release branch:
+
+   .. code-block:: python
+
+      git add lightrag/pyproject.toml
+      git commit -m "new version release"
+      git push origin release
+   
+   Since the workflow only processes **`tags`**, your file submission will not go through the version release workflow.
+
+   Only the tags you pushed will get checked.
+
+To push the new version tag, please run:
+   To push the new version tag:
+
+   .. code-block:: python
+
+      git tag -a vx.y.z -m "Release version x.y.z"
+      git push origin release
+
+4. To delete redundant local tags:
+
+   .. code-block:: python
+
+      git tags # list the existing tags
+      
+      git tag -d <tag>
+      git push origin --delete <tag>
+
+Important Notes
+---------------
+
+- **Do Not Reuse Tags:** If you need to fix a problem after a tag is pushed but before a release is made, you must create a new version number. Never reuse version numbers as this can lead to confusion and potential deployment issues.
+- **Monitor the Workflow:** After pushing the tag, monitor the GitHub Actions workflow to ensure that it completes successfully. Check the "Actions" tab in the GitHub repository to see the progress and logs.
+
+Troubleshooting
+---------------
+
+- If the workflow fails, review the logs for errors. Common issues might include failing tests or configuration errors in the workflow.
+- If you encounter errors related to tagging (e.g., "tag already exists"), check that you're incrementing the version numbers correctly.

_sources/index.rst.txt

@@ -27,7 +27,7 @@
     <div style="text-align: center;">
         <p>
             <em>LightRAG</em> helps developers with both building and optimizing <em>Retriever-Agent-Generator (RAG)</em> pipelines.<br>
-            It is <em>light</em>, <em>modular</em>, and <em>robust</em>.
+            It is <em>light</em>, <em>modular</em>, and <em>robust</em>,  with a 100% readable codebase.
         </p>
     </div>