Access a Knowledge Box

Define the default Knowledge Box

• When using user authentication, you can list all the kbs who have access to:

  • CLI:

    nuclia kbs list
  • SDK:

    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:

    nuclia kbs default [KB_ID]
  • SDK:

    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:

  nuclia kb list
  nuclia kb list --page=0 --size=10
• SDK:

  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
• usermetadata: User metadata, mostly used to set labels on the resource See API documenattion
• fieldmetadata: Field metadata See API documenattion
• origin: Origin metadata See API documenattion
• 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).

Note: you cannot set File fields when creating a resource, you need to use the upload command.

Examples:

• CLI:

  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:

  nuclia kb resource create --origin="{\"collaborators\":[\"THE_AUTHOR\"]}" --usermetadata="{\"classifications\": [{\"labelset\": \"SOME_CATEGORY\", \"label\": \"SOME_VALUE\"}]}"

• SDK:

  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:

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

• SDK:

  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:

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

• SDK:

  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:

  nuclia kb resource delete --rid=RID
  nuclia kb resource delete --slug=slug

• SDK:

  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:

  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:

  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:

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

• SDK:

  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:

nuclia kb copy_all --destination=KB_ID --override

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

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:

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

• SDK:

  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:

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

Using SDK

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

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

from nuclia import sdk
from nuclia.lib.kb import LogType
from nuclia.lib.models 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:

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