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 }