Improve documentation (#39)

* Improve documentation * Update docs/05-search.md Co-authored-by: Ferran Llamas <[email protected]> --------- Co-authored-by: Ferran Llamas <[email protected]>
nuclia · Nov 7, 2023 · 6ab3815 · 6ab3815
1 parent 31eda73
commit 6ab3815
Show file tree

Hide file tree

Showing 14 changed files with 540 additions and 259 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,7 +3,7 @@
 ## 1.1.18 (unreleased)
 
 
-- Nothing changed yet.
+- Improve documentation.
 
 
 ## 1.1.17 (2023-11-02)

diff --git a/docs/01-README.md b/docs/01-README.md
@@ -1,34 +1,41 @@
 # Nuclia CLI/SDK
 
-This SDK/CLI is designed to facilitate use of the Nuclia API.
+This Nuclia SDK/CLI is designed to facilitate use of the Nuclia API.
 
 There are two developer experiences:
 
 - CLI: by using the cli `nuclia` you can interact with Nuclia via command line
-- SDK: Using python you can replicate each command using the same structure
+- SDK: allows to write simple Python scripts to interact with Nuclia
+
+## Installation
 
 It requires Python (≥3.8) and can be installed with:
 
 ```sh
 pip install nuclia
 ```
 
-## Getting started
+## Upgrades
+
+To know your current version:
+
+```sh
+pip show nuclia
+```
+
+To upgrade to the latest version:
+
+```sh
+pip install nuclia --upgrade
+```
 
-First steps should be:
+## Usage
 
 - [Authentication](02-auth.md)
-- [Setting KnowledgeBox or NUA key](03-default.md).
-
-## Use Cases
-
-- [Upload files](04-upload.md)
-- [Upload url](04-upload.md)
-- [Upload text](04-upload.md)
-- [Upload conversation](07-conversation.md)
-- [Search](06-search.md)
-- [Extract information from a file](05-extract.md)
-- [Import/export knowledge boxes](08-import-export.md)
-- Detect Entities
-- [Get embedding from text](05-extract.md)
-- Get answer from a context
+- [Access a Knowledge Box](03-kb.md)
+- [Upload contents](04-upload.md)
+- [Search and answer generation](05-search.md)
+- [Read extracted data](06-read.md)
+- [Work with a NUA key](07-nua.md)
+- [Import/export a Knowledge Box](08-import-export.md)
+- [Manage Knowledge Box configuration & labels](09-manage.md)
diff --git a/docs/02-auth.md b/docs/02-auth.md
@@ -1,45 +1,49 @@
 # Authentication
 
-In order to start working you can login using multiple mechanism:
+In order to start working you can login either using a user acount, or using an API key.
 
-- User auth:
+Note: you can also login with a NUA key if you only need to run some processing, see [NUA](07-nua.md).
 
-  - CLI: `nuclia auth login`
-  - SDK:
+## User authentication
 
-    ```python
-    from nuclia import sdk
-    sdk.NucliaAuth().set_user_token(USER_TOKEN)
-    ```
+With user authentication, there is no limitation to the API endpoints you can use. You manage all the accounts and Knowledge Boxes you have access to. It also allows to manage local NucliaDBs connected to your accounts.
 
-  - Provides:
-    - CRUD experience on top of accounts and knowledgeboxes
-    - Access to managed NucliaDBs connected to your accounts
+But it does not last very long (30 minutes), and it requires a browser to complete the authentication process.
+It is a good fit for interactive use, but not for long running scripts.
 
-- Nuclia Understanding API
+- CLI: `nuclia auth login`, and it will trigger a browser authentication flow, so you can copy/paste the token in your terminal.
 
-  - CLI: `nuclia auth nua region=REGION token=NUA_KEY`
-  - SDK:
+- SDK: (even if it is not recommended for long running scripts, user authentication can be done in the SDK)
 
-    ```python
-    from nuclia import sdk
-    sdk.NucliaAuth().nua(region=REGION, token=NUA_KEY)
-    ```
+  ```python
+  from nuclia import sdk
+  sdk.NucliaAuth().set_user_token(USER_TOKEN)
+  ```
 
-  - Provides:
-    - Access to Nuclia Understanding API (extract, predict & train)
+## API key
 
-- NucliaDB API (Knowledge Box)
+An API key can be generated from the Nuclia Dashboard, see [Get an API key](https://docs.nuclia.dev/docs/guides/getting-started/quick-start/push#get-an-api-key).
 
-  - CLI: `nuclia auth kb KB_URL [TOKEN]`
-  - SDK:
+When authenticating with an API key, you can only access the Knowledge Box that is associated with this API key.
+The authentication will last as long as the key is valid (potentially forever, but an API key can be revoked from the Nuclia Dashboard).
 
-    ```python
-    from nuclia import sdk
-    sdk.NucliaAuth().kb(url=KB_URL, token=API_KEY, interactive=False)
-    ```
+It is the recommended way to authenticate for long running scripts.
 
-  - Provides access to NucliaDB API. For the managed service you will need a service token.
+- CLI: `nuclia auth kb KB_URL [API_KEY]`
+- SDK:
+
+  ```python
+  from nuclia import sdk
+  sdk.NucliaAuth().kb(url=KB_URL, token=API_KEY, interactive=False)
+  ```
+
+- Provides access to NucliaDB API. For the managed service you will need a service token.
+
+## Logout
+
+```sh
+nuclia auth logout
+```
 
 ## List configured user accounts, knowledge boxes and NUA keys
 

diff --git a/docs/03-default.md b/docs/03-default.md
diff --git a/docs/03-kb.md b/docs/03-kb.md
@@ -0,0 +1,151 @@
+# Access a Knowledge Box
+
+## Define the default Knowledge Box
+
+- When using user authentication, you can list all the kbs who have access to:
+
+  - CLI:
+    ```sh
+    nuclia kbs list
+    ```
+  - SDK:
+    ```python
+    from nuclia import sdk
+    kbs = sdk.NucliaKBS()
+    kbs.list()
+    ```
+
+  And you can set the Knowledge Box you want to work with as your default:
+
+  - CLI:
+    ```sh
+    nuclia kbs default [KB_ID]
+    ```
+  - SDK:
+    ```python
+    from nuclia import sdk
+    kbs = sdk.NucliaKBS()
+    kbs.default(KB_ID)
+    ```
+
+- When using an API key, the corresponding Knowledge Box is set as default automatically.
+
+## List resources
+
+You can get the list of resources in a Knowledge Box:
+
+- CLI:
+  ```sh
+  nuclia kb list
+  ```
+- SDK:
+  ```python
+  from nuclia import sdk
+  kb = sdk.NucliaKB()
+  resources = kb.list()
+  ```
+
+## Create a resource
+
+You can create a resource in a Knowledge Box, setting all the resource metadata, like:
+
+- `slug`: the slug of the resource
+- `title`: the title of the resource
+- `summary`: the summary of the resource (if not set, Nuclia will generate it)
+- `icon`: the mimetype you want to assign to the resource (by default, Nuclia will assign the mimetype corresponding to the first field added in the resource)
+- `metadata`:
+- `origin`: the origin metadata of the resource
+  See [API documenattion](https://docs.nuclia.dev/docs/api#tag/Resources/operation/Create_Resource_kb__kbid__resources_post)
+- `usermetadata`: User metadata, mostly used to set labels on the resource
+  See [API documenattion](https://docs.nuclia.dev/docs/api#tag/Resources/operation/Create_Resource_kb__kbid__resources_post)
+- `fieldmetadata`: Field metadata
+  See [API documenattion](https://docs.nuclia.dev/docs/api#tag/Resources/operation/Create_Resource_kb__kbid__resources_post)
+- `origin`: Origin metadata
+  See [API documenattion](https://docs.nuclia.dev/docs/api#tag/Resources/operation/Create_Resource_kb__kbid__resources_post)
+- `extra`: user-defined metadata
+
+You can also set the contents of the resource, as fields:
+
+- Text fields in `texts`
+- Link fields in `links`
+- Conversation fields in `conversations`
+
+Note: you cannot set File fields when creating a resource, you need to use the [`upload` command](./04-upload.md).
+
+Examples:
+
+- CLI:
+
+  ```sh
+  nuclia kb resource create --slug=my-resource
+  nuclia kb resource create --origin='{"collaborators":["THE_AUTHOR"]}' --usermetadata='{"classifications": [{"labelset": "SOME_CATEGORY", "label": "SOME_VALUE"}]}'
+  nuclia kb resource create --texts='{"chapter-1": {"body": "here is a test", "format": "PLAIN"}'
+  ```
+
+  IMPORTANT: when using the CLI on Windows, you need to escape the double quotes in the JSON strings, like:
+
+  ```sh
+  nuclia kb resource create --origin="{\"collaborators\":[\"THE_AUTHOR\"]}" --usermetadata="{\"classifications\": [{\"labelset\": \"SOME_CATEGORY\", \"label\": \"SOME_VALUE\"}]}"
+  ```
+
+- SDK:
+
+  ```python
+  from nuclia import sdk
+  res = sdk.NucliaResource()
+  res.create(
+    slug="my-resource",
+    usermetadata={
+      "classifications": [
+          {"labelset": "subjects", "label": "<Topic 1>"},
+          {"labelset": "subjects", "label": "<Topic 2>"},
+      ],
+    },
+    texts={"chapter-1": {"body": "here is a test", "format": "PLAIN"}},
+  )
+  ```
+
+## Delete a resource on a kb
+
+The existing resource can be identified by its unique id `rid` or its `slug`.
+
+- CLI:
+
+  ```bash
+  nuclia kb resource delete --rid=RID
+  nuclia kb resource delete --slug=slug
+  ```
+
+- SDK:
+  ```python
+  from nuclia import sdk
+  resource = sdk.NucliaResource()
+  resource.delete(rid=RID)
+  ```
+
+## Modify a resource
+
+The existing resource can be identified by its unique id `rid` or its `slug`.
+
+- CLI:
+
+  ```bash
+  nuclia kb resource update --rid=RID --origin="{\"collaborators\":[\"AUTHOR_1\",\"AUTHOR_2\"]}"
+  nuclia kb resource update --slug=slug --texts='{"chapter-1": {"body": "new chapter content", "format": "PLAIN"}'
+  ```
+
+- SDK:
+
+  ```python
+  from nuclia import sdk
+  res = sdk.NucliaResource()
+  res.create(
+    slug="my-resource",
+    usermetadata={
+      "classifications": [
+          {"labelset": "subjects", "label": "<Topic 1>"},
+          {"labelset": "subjects", "label": "<Topic 3>"},
+      ],
+    },
+  )
+  ```