#373 Include documentation_helpers in module (#395)

Co-authored-by: Philip Meier <github.pmeier@posteo.de>

.gitignore

@@ -1,5 +1,6 @@
 ragna.toml
 ragna/_version.py
+docs/**/ragna.txt
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/examples/gallery_streaming.py

@@ -5,16 +5,6 @@
 is performed using the Python and REST API.
 """
 
-# %%
-# Before we start this example, we import some helpers.
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path.cwd().parent))
-
-import documentation_helpers
-
 # %%
 # ## Setup streaming assistant
 #
@@ -55,9 +45,18 @@ def answer(self, prompt, sources):
 #
 # Let's create and prepare a chat using the assistant we have defined above.
 
+from pathlib import Path
+
+import ragna._docs as ragna_docs
+
 from ragna import Rag, source_storages
 
-document_path = documentation_helpers.assets / "ragna.txt"
+print(ragna_docs.SAMPLE_CONTENT)
+
+document_path = Path.cwd() / "ragna.txt"
+
+with open(document_path, "w") as file:
+    file.write(ragna_docs.SAMPLE_CONTENT)
 
 chat = Rag().chat(
     documents=[document_path],
@@ -98,7 +97,7 @@ def answer(self, prompt, sources):
 
 config = Config(assistants=[DemoStreamingAssistant])
 
-rest_api = documentation_helpers.RestApi()
+rest_api = ragna_docs.RestApi()
 
 client = rest_api.start(config, authenticate=True)
 

docs/tutorials/gallery_python_api.py

@@ -8,27 +8,23 @@
 This tutorial walks you through basic steps of using Ragnas Python API.
 """
 
-# %%
-# Before we start this tutorial, we import some helpers.
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path.cwd().parent))
-
-import documentation_helpers
-
 # %%
 # ## Step 1: Select relevant documents
 #
 # Ragna uses the RAG technique to answer questions. The context in which the questions
 # will be answered comes from documents that you provide. For this tutorial, let's use a
 # sample document that includes some information about Ragna.
 
-document_path = documentation_helpers.assets / "ragna.txt"
+from pathlib import Path
+
+import ragna._docs as ragna_docs
+
+print(ragna_docs.SAMPLE_CONTENT)
+
+document_path = Path.cwd() / "ragna.txt"
 
-with open(document_path) as file:
-    print(file.read())
+with open(document_path, "w") as file:
+    file.write(ragna_docs.SAMPLE_CONTENT)
 
 # %%
 # !!! tip

docs/tutorials/gallery_rest_api.py

@@ -8,16 +8,6 @@
 This tutorial walks you through basic steps of using Ragnas REST API.
 """
 
-# %%
-# Before we start this tutorial, we import some helpers.
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path.cwd().parent))
-
-import documentation_helpers
-
 # %%
 # ## Step 1: Start the REST API
 #
@@ -43,11 +33,13 @@
 #     be using for this tutorial is equivalent of picking the first option the wizard
 #     offers you, i.e. using only demo components.
 
+import ragna._docs as ragna_docs
+
 from ragna.deploy import Config
 
 config = Config()
 
-rest_api = documentation_helpers.RestApi()
+rest_api = ragna_docs.RestApi()
 _ = rest_api.start(config)
 
 # %%
@@ -98,12 +90,14 @@
 # %%
 # For simplicity, let's use a demo document with some information about Ragna
 
-document_name = "ragna.txt"
+from pathlib import Path
+
+print(ragna_docs.SAMPLE_CONTENT)
 
-with open(documentation_helpers.assets / document_name, "rb") as file:
-    content = file.read()
+document_path = Path.cwd() / "ragna.txt"
 
-print(content.decode())
+with open(document_path, "w") as file:
+    file.write(ragna_docs.SAMPLE_CONTENT)
 
 # %%
 # The upload process in Ragna consists of two parts:
@@ -116,7 +110,7 @@
 # 2. Perform the actual upload with the information from step 1.
 
 response = client.post(
-    "/document", json={"name": document_name}
+    "/document", json={"name": document_path.name}
 ).raise_for_status()
 document_upload = response.json()
 print(json.dumps(response.json(), indent=2))
@@ -138,7 +132,7 @@
     parameters["method"],
     parameters["url"],
     data=parameters["data"],
-    files={"file": content},
+    files={"file": open(document_path, "rb")},
 ).raise_for_status()
 
 # %%

docs/documentation_helpers.py → ragna/_docs.py

@@ -11,13 +11,22 @@
 from ragna._utils import timeout_after
 from ragna.deploy import Config
 
-__all__ = ["assets", "RestApi"]
+__all__ = ["SAMPLE_CONTENT", "RestApi"]
 
-assets = Path(__file__).parent / "assets"
+SAMPLE_CONTENT = """\
+Ragna is an open source project built by Quansight. It is designed to allow
+organizations to explore the power of Retrieval-augmented generation (RAG) based
+AI tools. Ragna provides an intuitive API for quick experimentation and built-in
+tools for creating production-ready applications allowing you to quickly leverage
+Large Language Models (LLMs) for your work.
+
+The Ragna website is https://ragna.chat/. The source code is available at
+https://github.com/Quansight/ragna under the BSD 3-Clause license.
+"""
 
 
 class RestApi:
-    def __init__(self):
+    def __init__(self) -> None:
         self._process: Optional[subprocess.Popen] = None
 
     def start(self, config: Config, *, authenticate: bool = False) -> httpx.Client:
@@ -115,12 +124,14 @@ def _authenticate(self, client: httpx.Client) -> None:
         client.headers["Authorization"] = f"Bearer {token}"
 
     def stop(self, *, quiet: bool = False) -> None:
+        if self._process is None:
+            return
+
         self._process.kill()
         stdout, _ = self._process.communicate()
 
         if not quiet:
             print(stdout.decode())
 
-    def __del__(self):
-        if self._process is not None:
-            self.stop(quiet=True)
+    def __del__(self) -> None:
+        self.stop(quiet=True)