# Artifacts & Saved Responses

This guide explains how to create, manage, and use artifacts in [PromptOwl's](https://promptowl.ai) Data Room, including saving AI responses for future reference.

---

## Table of Contents

1. [What Are Artifacts?](#what-are-artifacts)
2. [Accessing the Data Room](#accessing-the-data-room)
3. [Creating Artifacts](#creating-artifacts)
4. [Saving AI Responses](#saving-ai-responses)
5. [Managing Artifacts](#managing-artifacts)
6. [Organizing with Folders](#organizing-with-folders)
7. [Sharing Artifacts](#sharing-artifacts)
8. [Using Artifacts with RAG](#using-artifacts-with-rag)
9. [Vector Sync and Citations](#vector-sync-and-citations)
10. [Best Practices](#best-practices)
11. [Troubleshooting](#troubleshooting)

---

## What Are Artifacts?

Artifacts are content pieces stored in your Data Room that serve as your knowledge base. They can be:

- **Text documents** you write
- **Uploaded files** (PDF, CSV, DOCX)
- **Web links** with scraped content
- **Saved AI responses** from conversations

### Why Use Artifacts?

| Use Case | Benefit |
|----------|---------|
| **Knowledge Base** | Store company documents, policies, FAQs |
| **RAG Source** | AI retrieves relevant content when answering |
| **Response Archive** | Save valuable AI outputs for reuse |
| **Team Resource** | Share knowledge across your organization |
| **Citation Source** | AI references artifacts with proper attribution |

### Artifact Types

| Type | Description | Icon |
|------|-------------|------|
| **Text** | Manual text content | Document |
| **Link** | Web URL with scraped content | Link |
| **File** | Uploaded PDF, CSV, DOCX | File |
| **Document** | Saved AI response | Document |

---

## Accessing the Data Room

### Navigation

1. Click **Data Room** in the left sidebar
2. View your artifacts and folders


### Data Room Interface

The Data Room displays:

| Element | Description |
|---------|-------------|
| **Folders** | Organized collections of artifacts |
| **Root Artifacts** | Artifacts not in any folder |
| **Create Button** | Add new artifacts or folders |
| **Search** | Find artifacts by name |
| **Sync Status** | Shows if content is indexed for AI |


---

## Creating Artifacts

### Creating a Text Artifact

1. Click **Create** in the Data Room
2. Select **Artifact**
3. Choose **Paragraph Text** type
4. Fill in the details:

| Field | Description | Required |
|-------|-------------|----------|
| **Name** | Artifact title | Yes |
| **Content** | Main text content (max 15,000 chars) | Yes |
| **Title for Citation** | How it appears when cited by AI | No |
| **Author** | Content creator | No |
| **Publish Date** | When content was created | No |
| **Tags** | Categories for organization | No |

5. Click **Create**


### Creating a Link Artifact

1. Click **Create** → **Artifact**
2. Select **Link** type
3. Enter the URL
4. System automatically scrapes and processes content
5. Add metadata (title, author, date)
6. Click **Create**

**What Gets Scraped:**
- Main content area of the page
- Headers and paragraphs
- Lists and tables

**What Gets Removed:**
- Navigation menus
- Footers and sidebars
- Ads and cookie banners
- Modals and popups

### Uploading Files

1. Click **Create** → **Artifact**
2. Select **File** type
3. Upload your file:
   - Drag and drop onto the upload area
   - Or click to browse and select

**Supported Formats:**

| Format | Extension | Max Size |
|--------|-----------|----------|
| PDF | `.pdf` | 500 MB |
| CSV | `.csv` | 500 MB |
| Word | `.docx` | 500 MB |
| Text | `.txt` | 500 MB |

4. Add metadata (citation title, author, date)
5. Click **Create**


### Bulk Upload

For uploading multiple files at once:

1. Click **Bulk Upload** button
2. Drag multiple files or select from file browser
3. Files upload simultaneously
4. Each becomes a separate artifact
5. Edit individual artifacts later for metadata

---

## Saving AI Responses

Save valuable AI responses directly to your Data Room for future reference.

### How to Save a Response

1. Have a conversation with your AI prompt
2. Find a response you want to save
3. Click the **Save** icon on the response
4. Response is saved as an artifact


### Where Saved Responses Go

Saved responses are automatically organized:

| Scenario | Folder Location |
|----------|-----------------|
| Prompt has a name | Folder named after the prompt |
| Prompt unnamed | "Conversation Artifacts" folder |
| Folder already exists | Added to existing folder |

### Saved Response Details

Each saved response includes:

- **Name**: "Response - [timestamp]"
- **Type**: Document
- **Content**: Full AI response text
- **Description**: Links back to original conversation
- **Date**: When it was saved

### Finding Saved Responses

1. Go to **Data Room**
2. Look for folder matching your prompt name
3. Or search by "Response" to find all saved responses

---

## Managing Artifacts

### Viewing Artifact Details

1. Click on an artifact card
2. View full content and metadata
3. See how content is chunked for AI retrieval


### Editing Artifacts

1. Open the artifact detail page
2. Click **Edit** button
3. Modify any fields:
   - Name
   - Content
   - Citation title
   - Author
   - Publish date
   - Tags
4. Click **Save**

> **Note**: Only artifact Owners and Editors can make changes.

### Viewing Content Chunks

For RAG purposes, artifacts are split into chunks. To preview:

1. Open artifact detail page
2. Scroll to **Chunk Preview** section
3. See how the AI will search and retrieve content

Each chunk shows:
- Chunk number
- Content preview
- Character count

### Deleting Artifacts

1. Click the **trash icon** on the artifact card
2. Confirm deletion in the dialog
3. Artifact is permanently removed

> **Warning**: Deletion also removes the artifact from the vector store. This cannot be undone.

---

## Organizing with Folders

### Creating Folders

1. In Data Room, click **Create**
2. Select **Folder**
3. Enter folder name
4. Click **Create**

### Moving Artifacts to Folders

1. Create artifacts directly in a folder:
   - Open the folder first
   - Then create the artifact

2. Or drag artifacts (if supported in UI)

### Folder Structure

```
Data Room
├── Marketing Materials/
│   ├── Product Overview.pdf
│   ├── Pricing Guide.docx
│   └── FAQ Document
├── Technical Docs/
│   ├── API Reference
│   └── Integration Guide
├── Saved Responses/
│   └── Response - Dec 30, 2025
└── [Unfiled Artifacts]
```

### Folder Sync Status

Folders show sync status indicators:

| Status | Meaning | Action |
|--------|---------|--------|
| **Synced** | All artifacts indexed | Ready for RAG |
| **Pending** | Changes not yet indexed | Will sync automatically |
| **Modified** | Content changed since sync | Needs re-sync |

---

## Sharing Artifacts

### Individual Artifact Sharing

1. Open artifact detail page
2. Click **Share** button
3. Enter email addresses or select teams
4. Click **Share**


### Folder Sharing

Share an entire folder to give access to all artifacts within:

1. Open folder
2. Click **Share** on the folder
3. Add emails or teams
4. All artifacts in folder become accessible

### Permission Levels

| Role | Can View | Can Edit | Can Delete | Can Share |
|------|----------|----------|------------|-----------|
| **Owner** | Yes | Yes | Yes | Yes |
| **Editor** | Yes | Yes | No | Yes |
| **Viewer** | Yes | No | No | No |

### Shared Artifact Indicators

Shared artifacts show:
- Number of people shared with
- "Shared by: [email]" if shared by someone else
- Team badges if shared with teams

---

## Using Artifacts with RAG

Artifacts power RAG (Retrieval Augmented Generation), allowing AI to reference your content when answering questions.

### Connecting Artifacts to Prompts

There are three main ways to connect your Data Room content to prompts:

#### Method 1: Using Variables (Recommended for Direct Content Injection)

1. Add `\{data\}` (or any variable name) in your prompt content, e.g., `Use the following data: \{data\}`
2. The **Variables** section will automatically detect the variable
3. Click **Connect Data** button next to the variable
4. Select an artifact or folder from your Data Room
5. The entire content will be injected into the prompt when used



**Use this method when:** You want the entire content injected directly into the prompt (good for small, specific content).

#### Method 2: Using Block Settings Dataset Field (For RAG/Semantic Search)

1. Click on the block header (e.g., "Block 1") to expand the block
2. Look for the block's **LLM Settings** or **Tools and Data** section
3. Find the **Dataset** field within the block settings
4. Click **Connect Data** to select folders or artifacts from your Data Room
5. AI will search and retrieve relevant chunks from the connected dataset when the prompt runs



**Use this method when:** You want AI to search and retrieve relevant parts from large knowledge bases (RAG - Retrieval Augmented Generation).

#### Method 3: Using Tools & Data Section in Supervisor Mode

When using **Run with Supervisor** mode, you can connect datasets directly in the block's **Tools & Data** section:

1. Click on a block in your Supervisor agent (e.g., "SQA_BOOK_BLOCK")
2. Click **Block Settings** to expand the block settings
3. Find the **Tools & Data** section
4. Click the **Artifact** button (this is the Data field)
5. Select folders or artifacts from your Data Room
6. The connected dataset will be used for RAG when that specific block executes


**Use this method when:** You're using Supervisor mode and want to connect datasets to specific blocks in your agent workflow. Each block can have its own dataset for specialized knowledge retrieval.

### How RAG Works

```
User asks question →
AI searches connected artifacts →
Finds relevant chunks (top 10) →
Uses context to answer →
Cites sources in response
```

### RAG vs Direct Variable

| Approach | When to Use | How It Works |
|----------|-------------|--------------|
| **RAG (Dataset)** | Large knowledge bases | AI searches and retrieves relevant parts |
| **Variable** | Small, specific content | Entire content injected into prompt |

For detailed RAG configuration, see [Understanding Agents and RAG](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/understanding-agents-rag).

---

## Vector Sync and Citations

### Understanding Vector Sync

Artifacts must be "synced" to be searchable by AI. Syncing:

1. Splits content into optimized chunks
2. Generates embeddings (semantic vectors)
3. Stores in secure vector database
4. Enables similarity-based retrieval

### Sync Status Indicators

| Status | Badge | Meaning |
|--------|-------|---------|
| **Synced** | Green | Content indexed and searchable |
| **Unsynced** | Yellow | New artifact, not yet indexed |
| **Modified** | Orange | Content changed, needs re-index |

### When Sync Happens

- **Automatic**: When folder is accessed
- **On Save**: When artifact is created or edited
- **Manual**: Via sync button (if available)

### Citation Display

When AI uses an artifact, citations appear:

**Citation Information:**
- Display title (from "Title for Citation" field)
- Author name
- Publish date
- Source URL (for links)
- Relevance score


### Improving Citations

For better citations, always fill in:

| Field | Impact on Citation |
|-------|-------------------|
| **Title for Citation** | Shows as citation header |
| **Author** | Attribution in citation |
| **Publish Date** | Recency indicator |
| **URL** | Clickable source link |

---

## Best Practices

### Content Organization

**Do:**
- Use descriptive folder names
- Group related content together
- Keep artifacts focused (one topic each)
- Update content when it becomes outdated

**Don't:**
- Create one giant artifact with everything
- Mix unrelated topics in same folder
- Leave artifacts without metadata
- Duplicate content across folders

### RAG Optimization

**Do:**
- Write clear, well-structured content
- Use headers to organize sections
- Include key terms users might search for
- Test retrieval with sample questions

**Don't:**
- Upload scanned images without OCR
- Rely on heavily formatted tables
- Expect AI to read charts/graphs
- Use abbreviations without definitions

### Citation Quality

**Do:**
- Fill in all metadata fields
- Use meaningful citation titles
- Include author for accountability
- Add publish dates for time-sensitive content

### Storage Management

- Review artifacts periodically
- Delete outdated content
- Consolidate duplicate information
- Archive old responses if not needed

---

## Troubleshooting

### Artifact Won't Sync

1. Check sync status indicator
2. Try editing and saving the artifact
3. Open the containing folder (triggers sync)
4. Verify content isn't empty
5. Check for special characters in content

### AI Not Finding Relevant Content

1. Verify artifact is synced (green status)
2. Check artifact is in connected dataset
3. Test with different question phrasing
4. Review chunk preview to see how content is split
5. Ensure content contains relevant keywords

### Link Scraping Failed

1. Verify URL is accessible (not behind login)
2. Check URL uses http:// or https://
3. Try the URL in a browser first
4. Some sites block automated scraping
5. Consider copying content manually as text

### File Upload Errors

1. Check file size (max 500 MB)
2. Verify file format is supported
3. Ensure file isn't corrupted
4. Try re-saving file and uploading again
5. Check file isn't password protected

### Citations Not Appearing

1. Verify artifacts have citation metadata
2. Check "Title for Citation" is filled
3. Ensure RAG is enabled on prompt
4. Confirm artifact is in connected dataset
5. Check citation display is enabled in enterprise settings

### Shared Artifact Not Visible

1. Verify sharing was saved
2. Ask owner to check sharing settings
3. Ensure recipient email is correct
4. Check team membership (for team shares)
5. Recipient may need to refresh page

---

## Quick Reference

### Artifact Creation Checklist

**Required:**
- [ ] Name
- [ ] Content or file

**Recommended:**
- [ ] Title for Citation
- [ ] Author
- [ ] Publish Date
- [ ] Folder assignment

### Supported File Types

| Type | Extensions |
|------|------------|
| Documents | `.pdf`, `.docx`, `.txt` |
| Data | `.csv` |
| Max Size | 500 MB |

### Artifact Limits

| Limit | Value |
|-------|-------|
| Text content | 15,000 characters |
| File size | 500 MB |
| Chunk size | 1,000 characters |
| Chunk overlap | 200 characters |
| RAG results | Top 10 chunks |

---

## Related Guides

- [Adding and Organizing Documents](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/adding-organizing-documents)
- [Understanding Agents and RAG](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/understanding-agents-rag)
- [Monitoring, Evaluation, and Improvement](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/monitoring-evaluation)