Understanding Resources

What is a Resource?

A Resource in Nuclia is any piece of data you upload to your knowledge box. This can include documents, images, videos, audio files, or other types of content. Each Resource is stored with its associated metadata, enhancing its searchability and organization.

Fields

A Resource consists of one or more fields. A field is a value stored within a Resource, and this value can be a file, text, web page, or conversation.

• Single Field Resource: Often, a Resource contains only one field. For example, if you upload a PDF file to your knowledge box, it creates a Resource with a single file field.

• Multi-Field Resource: It is also possible to store multiple fields in a Resource. For instance, if you want to manage cooking recipes in your knowledge box, each Resource could include:

  • An image of the dish
  • Text explaining the recipe
  • A video of the preparation
  • A conversation with people's comments

  All these different elements would be fields within the same Resource.

Paragraphs

Nuclia extracts all text content from each field of a Resource and splits it into text blocks. These text blocks do not correspond to the text layout of the original document. Instead, they represent the smallest meaningful units that Nuclia will index. This process enhances the searchability and organization of the information within the knowledge box.

Key Attributes of a Resource

• id: A unique identifier for the resource, automatically generated by Nuclia.
• slug: A user-defined unique identifier for the resource, often used for easy referencing.
• title: The name or title of the resource.
• icon: The MIME type of the resource, indicating its format (e.g., application/pdf, movie/mp4, audio/mpeg).
• summary: A brief description providing an overview of the resource.
• status: The current status of the resource, which can be one of the following: pending, processed, error, empty, blocked, or expired.
• metadata: Additional information that describes the resource, such as tags, labels, or custom fields.
• created: The date and time when the resource was initially created.
• modified: The date and time when the resource was last updated.
• security: Metadata related to resource security such as access groups.

How to Create a Resource

Dashboard

To create a Resource using the Nuclia Dashboard:

1. Log in to the Dashboard: Access the Nuclia Dashboard with your credentials.
2. Navigate to Your Knowledge Box: Select the knowledge box where you want to upload the Resource.
3. Upload the Resource: Click on the "Upload" button and select the file you want to upload.
4. Add Metadata: Fill in any additional metadata fields to enhance the Resource's searchability.
5. Save: Save the Resource to complete the upload process.

API

To create a Resource using the Nuclia API:

1. Create a Resource:

curl --location --request POST 'https://<zone>.nuclia.cloud/api/v1/kb/<your-knowledge-box-id>/resources' \
--header 'X-NUCLIA-SERVICEACCOUNT: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
    "title": "Sample Document",
    "metadata": {
        "tags": ["example", "sample"],
        "classification": "public"
    }
}'

2. Add a File to the Resource:

curl --location --request PUT 'https://europe-1.stashify.cloud/api/v1/kb/<your-knowledge-box-id>/resource/<your-resource-id>/file/<any-uuid>' \
--header 'X-NUCLIA-SERVICEACCOUNT: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
    "language": null,
    "password": null,
    "file": {
        "filename": "my test file",
        "content_type": "text/plain",
        "payload": "file content",
        "md5": "d10b4c3ff123b26dc068d43a8bef2d23",
        "uri": null,
        "extra_headers": {}
    }
}'

CLI

To create a Resource using the Nuclia CLI:

1. Create a Resource:

nuclia knowledgebox resource create --title 'Sample Document' --metadata '{"tags": ["example", "sample"], "classification": "public"}'

2. Upload a File to the Resource:

nuclia knowledgebox upload file --path=/path/to/file.txt  --rid=<resource-id-returned-in-previous-command>

Python SDK

To create a Resource using the Nuclia Python SDK:

from nuclia import sdk

# Nuclia knowledge box URL and API key
KNOWLEDGE_BOX_URL = (
    "https://<zone>.nuclia.cloud/api/v1/kb/<your-knowledge-box-id>"
)
API_KEY = "<your-api-key>"

# Authenticate with the Nuclia SDK
sdk.NucliaAuth().kb(url=KNOWLEDGE_BOX_URL, token=API_KEY)

# Create a new resource
resource = sdk.NucliaResource().create(
    title="Sample Document",
    metadata={"tags": ["example", "sample"], "classification": "public"},
)

# Upload a file to the resource
upload = sdk.NucliaUpload()
test = upload.file(
    path="/file/path/filename.txt",
    rid=resource,
)

Managing Resources

Once a Resource is created, you can manage it using various tools and interfaces provided by Nuclia:

• Editing Metadata: Update the metadata to refine search and organization.
• Access Control: Adjust access groups to control who can view or edit the Resource.
• Deletion: Remove Resources that are no longer needed.

Updating resources

If you need to update ingested resource (e.g., modify a file and re-ingest it), assign a unique identifier to each data item. Store this identifier in the slug attribute of your resource. This allows you to get, update, or delete the resource by querying the API with the identifier instead of the Nuclia-generated ID:

GET /api/v1/kb/{kbid}/slug/{rslug}
PATCH /api/v1/kb/{kbid}/slug/{rslug}
DELETE /api/v1/kb/{kbid}/slug/{rslug}

See the resource endpoints for more information.

Avoiding Noise

Avoid ingesting unnecessary information to prevent polluting the index:

• Web Pages: Exclude irrelevant parts (e.g., header, footer) using the css_selector parameter in the LinkField. For an example, refer to the index website example.
• Videos: Do not index the transcript, as Nuclia can extract it from the video.
• Documents: Avoid indexing multiple translations of the same document unless necessary. If you do, use the language attribute to filter results by language.

Best Practices for Working with Resources

• Organize with Metadata: Use metadata to categorize and label Resources effectively.
• Consistent Naming Conventions: Adopt consistent naming conventions for titles and tags.
• Regular Reviews: Periodically review and update Resources to keep your data relevant and useful.
• Utilize System Metadata: Leverage automatically extracted metadata to save time and enhance organization.

By understanding and effectively managing Resources in Nuclia, you can maximize the efficiency and effectiveness of your data management and retrieval processes.