diff --git a/README.md b/README.md
index a615cf84..716f1528 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,8 @@
*Interact with the Deep Search platform for new knowledge explorations and discoveries*
-The Deep Search Toolkit is a Python SDK allowing a user to interact with the Deep Search platform. The toolkit provides easy-to-use functionalities for several common processes such as document conversion, graph creation and querying.
+The Deep Search Toolkit is a Python SDK and CLI allowing users to interact with the Deep Search platform.
+The Toolkit provides easy-to-use functionalities for several common processes such as document conversion, graph creation and querying.
[Learn about IBM Deep Search](https://ds4sd.github.io/)
@@ -53,14 +54,14 @@ Python 3.8+
## Start using the toolkit
-### Login to Deep Search
-For details, check the [authentication docs](https://ds4sd.github.io/deepsearch-toolkit/getting_started/#authentication).
+### Set up a profile
+For details, check [Profiles](https://ds4sd.github.io/deepsearch-toolkit/guide/configuration#profiles).
```console
-deepsearch login
+deepsearch profile config
```
### Convert a document
-For details, check the [document conversion docs](https://ds4sd.github.io/deepsearch-toolkit/guide/convert_doc).
+For details, check [Document conversion](https://ds4sd.github.io/deepsearch-toolkit/guide/convert_doc).
```console
deepsearch documents convert -p 1234567890abcdefghijklmnopqrstvwyz123456 -u https://arxiv.org/pdf/2206.00785.pdf
```
diff --git a/deepsearch/model/README.md b/deepsearch/model/README.md
index d792464e..2d7c7580 100644
--- a/deepsearch/model/README.md
+++ b/deepsearch/model/README.md
@@ -29,14 +29,12 @@ app.run(host="127.0.0.1", port=8000)
### Settings
App configuration is done in [`Settings`](server/config.py) based on
-[Pydantic settings management](https://docs.pydantic.dev/latest/usage/settings/).
+[Pydantic Settings with dotenv support](https://docs.pydantic.dev/dev-v1/usage/settings/).
-E.g. the required API key can be set via env var `DS_MODEL_API_KEY` (for precedence rules,
-check the
-[Pydantic docs](https://docs.pydantic.dev/latest/usage/settings/#field-value-priority)).
+E.g. the required API key can be injected via env var `DS_MODEL_API_KEY`.
### OpenAPI
-The OpenAPI UI is served under `/docs`, e.g. http://127.0.0.1:8000/docs.
+The OpenAPI UI is served under `/docs`, i.e. by default at http://127.0.0.1:8000/docs.
## Developing a new model
To develop a new model class for an existing [kind](kinds/), inherit from the base model
diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
index 2e2f2151..904d95d2 100644
--- a/docs/getting_started/index.md
+++ b/docs/getting_started/index.md
@@ -6,31 +6,26 @@ After registering with [Deep Search](https://ds4sd.github.io/), you can obtain y
---
-### Configure a profile
+### Set up a profile
=== "CLI"
- Configure a profile using [`deepsearch profile config`](../cli-reference.md#profile).
+ Set up a [profile][profiles] using `deepsearch profile config`.
In its basic form it looks like this:
```console
$ deepsearch profile config
-
- Host: # (1)
- Username: # (2)
- Api key: # (3)
+ Host: https://ds.example.com # the Deep Search instance you are using
+ Username: name@example.com # your username
+ Api key: (hidden) # your API key
```
- 1. Input the Deep Search deployment host to use.
- 2. Enter your `User name`.
- 3. Enter your `API key`.
-
By providing a profile name (via option `--profile-name`) you can configure multiple
different profiles, which you can then easily switch between and manage.
- For details, check [Profiles](../guide/configuration.md#profiles).
+ For details, check [Profiles][profiles].
### Validate the setup
@@ -89,3 +84,6 @@ Here, we show a simple way to convert documents using [Deep Search](https://ds4s
```
---
+
+
+[profiles]: ../guide/configuration.md#profiles
diff --git a/docs/guide/cli_plugins.md b/docs/guide/cli_plugins.md
index 61ec325d..37a24bbf 100644
--- a/docs/guide/cli_plugins.md
+++ b/docs/guide/cli_plugins.md
@@ -83,12 +83,9 @@ Options:
--help Show this message and exit.
Commands:
- config Manage CLI config files
- cps Interact with DeepSearch CPS component
+ [ ... ] [ ... ]
example
- login Login to DeepSearch platform
- query Interact with DeepSearch Query component
- version Print the client and server version information
+ [ ... ] [ ... ]
```
And running our newly added command gives us...
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index 8b265c28..22e037e6 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -1,13 +1,16 @@
# Configuration
-The Toolkit can be configured both via the CLI and via
-environment variables.
+The Toolkit can be configured via the CLI and via environment variables.
Besides *global* settings, the Toolkit also allows the configuration of multiple
*profiles* for enabling users to easily work with different Deep Search deployments.
## Profiles
+The Toolkit provides the capability of easily interacting with different Deep Search
+instances through the use of *profiles*. A user may define multiple profiles, identified
+by profile name, and can easily switch between them.
+
### Overview
For an overview of the profile management commands check `deepsearch profile --help`:
@@ -32,8 +35,8 @@ $ deepsearch profile --help
### Profile setup
-To setup a profile use [`deepsearch profile config`](../cli-reference.md#profile),
-providing options as needed (for a full reference run with `--help`).
+To set up a profile use `deepsearch profile config`, providing options as needed (for a
+full reference check `deepsearch profile config --help`).
Here is a basic invocation example:
@@ -44,76 +47,70 @@ Username: name@example.com
Api key:
```
-> NOTE: If you had used the meanwhile deprecated `deepsearch login` command to set up a
-config file in the default location, that will automatically be migrated to a profile.
+!!! note
+ If you had used the meanwhile deprecated `deepsearch login` command to set up a
+ config file in the default location, that will automatically be migrated to a profile.
### Usage
-Here some usage examples:
-
-=== "CLI"
-
- ```console
- $ # configure a profile
- $ deepsearch profile config --profile-name foo --host ds-1.example.com ...
- $ # -> "foo" now available and selected as the active profile
- $
- $ deepsearch cps projects list
- $ # -> outputs projects corresponding to "foo"
- $
- $ # configure another profile
- $ deepsearch profile config --profile-name bar --host ds-2.example.com ...
- $ # -> "bar" now available and selected as the active profile
- $
- $ deepsearch profile list
- $ # -> displays all profiles, with "bar" marked as the active one
- $
- $ deepsearch cps projects list
- $ # -> outputs projects corresponding to "bar"
- $
- $ # switch to previous profile
- $ deepsearch profile use foo
- $ # -> "foo" now selected as the active profile
- $
- $ deepsearch cps projects list
- $ # -> outputs projects corresponding to "foo"
- ```
-
-=== "Python"
-
- ```python
- from deepsearch.cps.client.api import CpsApi
-
- # using the active profile; let's assume that is "foo"
- api = CpsApi.from_env()
- print([p.name for p in api.projects.list()])
- # -> outputs projects corresponding to "foo"
-
- # using a profile by name
- api = CpsApi.from_env(profile_name="bar")
- print([p.name for p in api.projects.list()])
- # -> outputs projects corresponding to "bar"
- ```
-
----
+#### Usage in CLI
+```console
+$ # configure a profile
+$ deepsearch profile config --profile-name foo --host ds-1.example.com ...
+$ # -> "foo" now available and selected as the active profile
+$
+$ deepsearch cps projects list
+$ # -> outputs projects corresponding to "foo"
+$
+$ # configure another profile
+$ deepsearch profile config --profile-name bar --host ds-2.example.com ...
+$ # -> "bar" now available and selected as the active profile
+$
+$ deepsearch profile list
+$ # -> displays all profiles, with "bar" marked as the active one
+$
+$ deepsearch cps projects list
+$ # -> outputs projects corresponding to "bar"
+$
+$ # switch to previous profile
+$ deepsearch profile use foo
+$ # -> "foo" now selected as the active profile
+$
+$ deepsearch cps projects list
+$ # -> outputs projects corresponding to "foo"
+```
-## Environment variables
+#### Usage in Python
-Under the hood, configuration management in the Toolkit is implemented based on [Pydantic
-Settings with dotenv support](https://docs.pydantic.dev/1.10/usage/settings).
+To use the active profile (recommended usage pattern):
+```python
+from deepsearch.cps.client.api import CpsApi
-Configuration is persisted in Toolkit-managed dotenv files, but can be overriden via
-environment variables.
+api = CpsApi.from_env()
-To see which environment variables are supported, check the relevant [Pydantic Settings
-classes][settings_file], also taking into account any defined prefixes.
+print([p.name for p in api.projects.list()])
+# -> outputs projects corresponding to active profile
+```
-For example you can set the profile for the scope of a single operation (e.g. a project
-listing) as follows:
+To use a specific profile:
+```python
+from deepsearch.cps.client.api import CpsApi
-```console
-DEEPSEARCH_PROFILE=bar deepsearch cps projects list
+api = CpsApi.from_env(profile_name="foo")
+
+print([p.name for p in api.projects.list()])
+# -> outputs projects corresponding to "foo"
```
+## Environment variables
+
+Under the hood, the Toolkit leverages [Pydantic Settings with dotenv
+support][pydantic_settings], so configuration settings can be easily overriden via
+environment variables. This can be useful e.g. in a containerization scenario.
+
+To see which environment variables are supported, check the relevant [Pydantic Settings
+classes][settings_file], also taking into account any defined prefixes.
+
+[pydantic_settings]: https://docs.pydantic.dev/dev-v1/usage/settings
[settings_file]: https://github.com/DS4SD/deepsearch-toolkit/blob/main/deepsearch/core/client/settings.py
diff --git a/docs/guide/data_indices.md b/docs/guide/data_indices.md
index 12394ecc..8cb140ea 100644
--- a/docs/guide/data_indices.md
+++ b/docs/guide/data_indices.md
@@ -22,7 +22,7 @@ Suppose you want to create an index called `NAME`. Optionally, a description,`DE
=== "Python"
- After you have generated the api object (from [login configuration](../installation/login.md)),
+ After you have generated the api object (from a [profile](../configuration#usage-in-python)):
```python
api.data_indices.create(proj_key=PROJ_KEY, name=NAME, desc=DESC)
@@ -159,9 +159,9 @@ Attachments can be added to an index item in a project. Briefly, attachments hav
attachment_key = "usr_my_attachment" # optional. if set need start with 'usr_' and be snake_case
index.add_item_attachment(
- api=api,
- index_item_id=index_item_id,
- attachment_path=attachment_path,
+ api=api,
+ index_item_id=index_item_id,
+ attachment_path=attachment_path,
attachment_key=attachment_key, # optional
)
```
diff --git a/docs/guide/kgs.md b/docs/guide/kgs.md
index f3e1ab02..6c862855 100644
--- a/docs/guide/kgs.md
+++ b/docs/guide/kgs.md
@@ -64,7 +64,7 @@ More example queries are available in the [examples gallery](../gallery/index.md
$ deepsearch cps kgs download -p 'abc123' -k 'zxc987'
url
- --------------------------------
+ --------------------------------
https://host.domain/download-url
```
@@ -72,7 +72,7 @@ More example queries are available in the [examples gallery](../gallery/index.md
=== "Python"
- After you have generated the `api` object (from [login configuration](../getting_started/#authentication))
+ After you have generated the `api` object (from a [profile](../configuration#usage-in-python)):
```python
proj_key = "abc123" # get your proj_key from the UI details
@@ -80,4 +80,4 @@ More example queries are available in the [examples gallery](../gallery/index.md
kg = api.knowledge_graphs.get(proj_key, kg_key)
download_url = kg.download()
- ```
\ No newline at end of file
+ ```
diff --git a/docs/guide/projects.md b/docs/guide/projects.md
index cc3be43d..17da0fe8 100644
--- a/docs/guide/projects.md
+++ b/docs/guide/projects.md
@@ -17,8 +17,7 @@ A collaborator may be added to a project as `owner`, `editor`, or `viewer`. Belo
## Project management
!!! info
- Make sure to [configure your login](../getting_started/index.md#authentication) before
- using the project management features listed below.
+ Make sure to [complete your profile setup](../getting_started/index.md#set-up-a-profile) before using the project management features listed below.
### Creating a project
@@ -39,7 +38,7 @@ A collaborator may be added to a project as `owner`, `editor`, or `viewer`. Belo
=== "Python"
- After you have generated the `api` object (from [login configuration](../getting_started/#authentication)), creating a project is very easy.
+ After you have generated the `api` object (from a [profile](../configuration#usage-in-python)), creating a project is very easy.
```python
proj = api.projects.create(name="my-project")
@@ -70,7 +69,7 @@ A collaborator may be added to a project as `owner`, `editor`, or `viewer`. Belo
=== "Python"
- After you have generated the `api` object (from [login configuration](../getting_started/#authentication)), listing projects is very easy.
+ After you have generated the `api` object (from a [profile](../configuration#usage-in-python)), listing projects is very easy.
```python
projects = api.projects.list() # returns list of projects
diff --git a/docs/index.md b/docs/index.md
index 46444cd1..1b60f101 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,7 +8,9 @@
*Interact with the Deep Search platform for new knowledge explorations and discoveries*
-The Deep Search Toolkit provides a Python SDK and a CLI allowing a user to interact with the Deep Search platform. The Toolkit provides easy-to-use functionalities for several common processes such as document conversion, graph creation and querying.
+The Deep Search Toolkit is a Python SDK and CLI allowing users to interact with the Deep Search platform.
+The Toolkit provides easy-to-use functionalities for several common processes such as document conversion, graph creation and querying.
+
[Learn about IBM Deep Search :octicons-link-external-16:](https://ds4sd.github.io/){ .md-button }