# 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
  nuclia kb list --page=0 --size=10
  ```
- SDK:
  ```python
  from nuclia import sdk
  kb = sdk.NucliaKB()
  resources = kb.list(page=0, size=10)
  ```

## 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"}},
  )
  ```

## Get a resource

The existing resource can be identified by its unique id `rid` or its `slug`.

- CLI:

  ```bash
  nuclia kb resource get --rid=RID
  nuclia kb resource get --slug=slug
  ```

- SDK:
  ```python
  from nuclia import sdk
  resource = sdk.NucliaResource()
  resource.get(rid=RID, show=["basic", "values"])
  ```

To download files stored into file fields, you can use the `download` directive:

- CLI:

  ```bash
  nuclia kb resource download_file --rid=RID --file_id=FIELD_ID --output="./my-file.pdf"
  ```

- SDK:
  ```python
  from nuclia import sdk
  resource = sdk.NucliaResource()
  resource.download_file(rid=RID, file_id=FIELD_ID, output="./my-file.pdf")
  ```

## 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>"},
      ],
    },
  )
  ```

## Copy resources between Knowledge Boxes

You can copy resources from the default Knowledge Box to another.
It duplicates the resource original content and metadata, but not the vectors or any extracted data. The resources will be reprocessed in the destination Knowledge Box.

You can copy one resource or a batch of resources.

- CLI:

  ```bash
  nuclia kb copy --rid=RID --destination=KB_ID
  nuclia kb copy_all --destination=KB_ID
  ```

- SDK:

  ```python
  from nuclia import sdk
  kb = sdk.NucliaKB()
  kb.copy(rid=RID, destination=KB_ID)
  kb.copy_all(destination=KB_ID)
  ```

By default, resources that are already in the destination Knowledge Box (based on their `slug` value) will not be copied. You can force the copy by using the `--override` flag:

```bash
nuclia kb copy_all --destination=KB_ID --override
```

You can also use filters to restrict the resources to copy:

```bash
nuclia kb copy_all --destination=KB_ID --filters='["/classifications.labels/review/done"]'
```

## 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

### Retrieving Activity Logs

You can retrieve activity logs for a Knowledge Box, which include various event types:

| Event Type | Description |
|------------|-------------|
| `VISITED`  | Resource view events |
| `NEW`      | Resource creation events |
| `PROCESSED`| Resource processing events |
| `MODIFIED` | Resource modification events |
| `DELETED`  | Resource deletion events |
| `CHAT`     | Questions asked and answers returned via the `/ask` endpoint |
| `SEARCH`   | Queries sent to `/search` or `/find` |
| `FEEDBACK` | User feedback on answers |
| `SUGGEST`  | Queries sent to `/suggest` |
| `STARTED`  | Task started events |
| `STOPPED`  | Task stopped events |
| `PROCESSED`| Task processed events |

### Using CLI

Retrieve logs of a specific type for a particular month:

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

### Using SDK

```python
from nuclia import sdk
from nuclia.lib.kb import LogType

kb = sdk.NucliaKB()
kb.logs.get(type=LogType.FEEDBACK, month="2024-02")
```

## Advanced Query Logs

For more complex log data queries, use the query parameter with the following options:

### Query Parameters

1. `year_month`: Specify the year and month of logs to retrieve (e.g., `2024-02`).
2. `show`: List fields to display in the output (Note: `id` is always displayed).
3. `filters`: Apply filters using these operators:
   - `eq`: Equal to (`=`)
   - `gt`: Greater than (`>`)
   - `ge`: Greater than or equal to (`>=`)
   - `lt`: Less than (`<`)
   - `le`: Less than or equal to (`<=`)
   - `ne`: Not equal to (`!=`)
   - `isnull`: Check for null (`True`/`False`)
   - `like`: SQL-like operator (string fields only)
   - `ilike`: Case-insensitive SQL-like operator (string fields only)
4. `pagination`: Control the number of logs retrieved:
   - `limit`: Number of items to fetch
   - `starting_after`: Fetch logs after a specific ID (ascending order)
   - `ending_before`: Fetch logs before a specific ID (descending order)

### Available Fields

#### Common Fields (All Event Types)
- `id`, `date`, `user_id`, `user_type`, `client_type`, `total_duration`, `audit_metadata`

#### Event-Specific Fields
- `SEARCH` events: Common fields + `question`, `resources_count`, `filter`, `learning_id`
- `CHAT` events: Common fields + Search fields + `rephrased_question`, `answer`, `retrieved_context`, `chat_history`, `feedback_good`, `feedback_comment`, `model`, `rag_strategies_names`, `rag_strategies`, `status`, `time_to_first_char`


### Query Examples

#### CLI Example

```bash
nuclia kb logs query --type=CHAT --query='{
  "year_month": "2024-10",
  "show": ["id", "date", "question", "answer", "feedback_good"],
  "filters": {
    "question": {"ilike": "user question"},
    "feedback_good": {"eq": true}
  },
  "pagination": {"limit": 10}
}'
```

#### SDK Example

```python
from nuclia import sdk
from nuclia.lib.kb import LogType
from nuclia_models.events.activity_logs import ActivityLogsQuery, Pagination

kb = sdk.NucliaKB()
query = ActivityLogsQuery(
    year_month="2024-10",
    show=["id", "date", "question", "answer"],
    filters={
        "question": {"ilike": "user question"},
        "feedback_good": {"eq": True}
    },
    pagination=Pagination(limit=10)
)
kb.logs.query(type=LogType.CHAT, query=query)
```
### Special Field: `audit_metadata`
The `audit_metadata` field is a customizable dictionary. Use the `key` operator to target specific keys within the dictionary.

#### Example to filter by `audit_metadata`:

```json
{
  "year_month": "2024-10",
  "show": ["audit_metadata.environment"],
  "filters": {
    "audit_metadata": [
      {
        "key": "environment",
        "eq": "prod"
      }
    ]
  },
  "pagination": {
    "limit": 10
  }
}
```