fix docs

docs/examples/gallery_streaming.py

@@ -110,7 +110,7 @@ def answer(self, messages):
 ragna_deploy = ragna_docs.RagnaDeploy(config)
 
 client, document = ragna_deploy.get_http_client(
-    authenticate=True, upload_document=True
+    authenticate=True, upload_sample_document=True
 )
 
 # %%

docs/references/config.md

@@ -73,6 +73,10 @@ Local root directory Ragna uses for storing files. See [ragna.local_root][].
 
 [ragna.deploy.Auth][] class to use for authenticating users.
 
+### `key_value_store`
+
+[ragna.deploy.KeyValueStore][] class to use for temporary storage.
+
 ### `document`
 
 [ragna.core.Document][] class to use to upload and read documents.
@@ -103,6 +107,10 @@ external clients.
 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) origins that are allowed
 to connect to the REST API.
 
+### `session_lifetime`
+
+Number of seconds of inactivity after a user has to login again.
+
 ### `database_url`
 
 URL of a SQL database that will be used to store the Ragna state. See

docs/tutorials/gallery_custom_components.py

@@ -189,7 +189,7 @@ def answer(self, messages: list[Message]) -> Iterator[str]:
 ragna_deploy = ragna_docs.RagnaDeploy(config)
 
 client, document = ragna_deploy.get_http_client(
-    authenticate=True, upload_document=True
+    authenticate=True, upload_sample_document=True
 )
 
 # %%
@@ -205,7 +205,7 @@ def answer(self, messages: list[Message]) -> Iterator[str]:
 response = client.post(
     "/api/chats",
     json={
-        "name": "Tutorial REST API",
+        "name": "Tutorial Custom Components",
         "document_ids": [document["id"]],
         "source_storage": TutorialSourceStorage.display_name(),
         "assistant": TutorialAssistant.display_name(),
@@ -322,7 +322,7 @@ def answer(
 ragna_deploy = ragna_docs.RagnaDeploy(config)
 
 client, document = ragna_deploy.get_http_client(
-    authenticate=True, upload_document=True
+    authenticate=True, upload_sample_document=True
 )
 
 # %%
@@ -332,7 +332,7 @@ def answer(
 response = client.post(
     "/api/chats",
     json={
-        "name": "Tutorial REST API",
+        "name": "Tutorial Elaborate Custom Components",
         "document_ids": [document["id"]],
         "source_storage": TutorialSourceStorage.display_name(),
         "assistant": ElaborateTutorialAssistant.display_name(),
@@ -343,6 +343,7 @@ def answer(
     },
 ).raise_for_status()
 chat = response.json()
+print(json.dumps(chat, indent=2))
 
 # %%
 

docs/tutorials/gallery_rest_api.py

@@ -14,7 +14,7 @@
 # Ragnas REST API is normally started from a terminal with
 #
 # ```bash
-# $ ragna api
+# $ ragna deploy
 # ```
 #
 # For this tutorial we use our helper that does the equivalent just from Python.
@@ -99,8 +99,8 @@
 # %%
 # The upload process in Ragna consists of two parts:
 #
-# 1. Announce the file to be uploaded. Under the hood this registers the document
-#    in Ragna's database and returns the document ID, which is needed for the upload.
+# 1. Register the document in Ragna's database. This returns the document ID, which is
+#    needed for the upload.
 
 response = client.post(
     "/api/documents", json=[{"name": document_path.name}]
@@ -109,7 +109,7 @@
 print(json.dumps(documents, indent=2))
 
 # %%
-# 2. Perform the actual upload with the information from step 1. through a
+# 2. Perform the upload through a
 # [multipart request](https://swagger.io/docs/specification/describing-request-body/multipart-requests/)
 # with the following parameters:
 #
@@ -154,8 +154,8 @@
 print(json.dumps(chat, indent=2))
 
 # %%
-# As can be seen by the `"prepared"` field in the `chat` JSON object we still need to
-# prepare it.
+# As can be seen by the `"prepared": false` value in the `chat` JSON object we still
+# need to prepare it.
 
 client.post(f"/api/chats/{chat['id']}/prepare").raise_for_status()
 

docs/tutorials/gallery_web_ui.py

@@ -13,15 +13,7 @@
 # You can launch the web application from the CLI:
 #
 # ```bash
-# ragna ui
+# ragna deploy
 # ```
 #
-# It will open in a browser window automatically and you should see the login screen:
-#
-# ![ragna UI login screen with a username and password form. Both the username and
-# password are filled with the string "ragna" and the password is visible and not
-# censored](../../assets/images/web-ui-login.png)
-#
-# By default [ragna.deploy.RagnaDemoAuthentication][] is used. Thus, you can use any
-# username and a matching password to authenticate. For example, you can leave both fields
-# blank or use `ragna` / `ragna` as in the image above.
+# The UI will open in a browser window automatically.

ragna/_docs.py

@@ -113,20 +113,20 @@ def get_http_client(
         self,
         *,
         authenticate: bool = False,
-        upload_document: bool = False,
+        upload_sample_document: bool = False,
     ) -> tuple[httpx.Client, Optional[dict[str, Any]]]:
-        if upload_document and not authenticate:
+        if upload_sample_document and not authenticate:
             raise RagnaException(
                 "Cannot upload a document without authenticating first. "
-                "Set authenticate=True when using upload_document=True."
+                "Set authenticate=True when using upload_sample_document=True."
             )
 
         client = httpx.Client(base_url=self.config._url)
 
         if authenticate:
             client.get("/login", follow_redirects=True)
 
-        if upload_document:
+        if upload_sample_document:
             name, content = "ragna.txt", SAMPLE_CONTENT
 
             response = client.post(

ragna/_utils.py

@@ -175,14 +175,16 @@ def __init__(
         *cmd: str,
         stdout: Any = sys.stdout,
         stderr: Any = sys.stdout,
-        text: bool = True,
         startup_fn: Optional[Callable[[], bool]] = None,
         startup_timeout: float = 10,
         terminate_timeout: float = 10,
+        text: bool = True,
         **subprocess_kwargs: Any,
     ) -> None:
+        self._terminate_timeout = terminate_timeout
+
         self._process = subprocess.Popen(
-            cmd, stdout=stdout, stderr=stderr, **subprocess_kwargs
+            cmd, stdout=stdout, stderr=stderr, text=text, **subprocess_kwargs
         )
         try:
             if startup_fn:
@@ -197,11 +199,9 @@ def wait() -> None:
             self.terminate()
             raise
 
-        self._terminate_timeout = terminate_timeout
-
-    def terminate(self) -> tuple[str, str]:
+    def terminate(self) -> tuple[str | bytes, str | bytes]:
         @timeout_after(self._terminate_timeout)
-        def terminate() -> tuple[str, str]:
+        def terminate() -> tuple[str | bytes, str | bytes]:
             self._process.terminate()
             return self._process.communicate()