# 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`
- File fields in `files` if they are provided as an URI (passing a binary file is not supported, you need to use the [`upload` command](./04-upload.md)).

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"}'
  nuclia kb resource create --files='{"chapter-1": {"file": {"uri": "https://somewhere.com/file.pdf", "filename": "file.pdf", "contenttype": "application/pdf"}}}'
  ```

  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.update(
    rid="resource_id",
    #or slug="my-unique-resource-slug",
    usermetadata={
      "classifications": [
          {"labelset": "subjects", "label": "<Topic 1>"},
          {"labelset": "subjects", "label": "<Topic 3>"},
      ],
    },
  )
  ```

## Summarizes resources

You can summarize one resource or a batch of resources. It will produce a summary for each resource plus a global summary for all the resources.

- CLI:

  ```bash
  nuclia kb resource summarize --resources='["RID,RID1,RID2,RID3"]'
  ```

- SDK:

  ```python
  from nuclia import sdk
  kb = sdk.NucliaKB()
  kb.summarize(resources=["RID,RID1,RID2,RID3"])
  ```

## Logs

You can get the logs of a Knowledge Box. There are different types of logs:

- `NEW`: resource creation events,
- `PROCESSED`: processing events,
- `MODIFIED`: resource modification events,
- `CHAT`: asked questions and returned answers on the `/ask` endpoint,
- `SEARCH`: queries sent to `/search` or `/find`,
- `FEEDBACK`: user feedbacks on answers

- CLI:

  ```sh
  nuclia kb logs get --type=SEARCH --month=2024-02
  ```

- SDK:
  ```python
  from nuclia import sdk
  kb = sdk.NucliaKB()
  kb.logs.get(type="FEEDBACK", month="2024-02")
  ```
