> ## Documentation Index
> Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Chat
> Get AI-powered answers about your contracts and data
## Overview
AI Chat is your intelligent assistant that can answer questions about your contracts and data using natural language. Ask questions about deal terms, compare contracts, and get summaries -- all with citations to source documents.
## Data Snapshot
AI Chat works from a **snapshot** of your project data, not a live connection. This means the AI has access to all contracts, catalog, CRM, and statement data as it existed at the time of the snapshot.
You can check when the snapshot was taken in the **bottom-left corner** of the chat sidebar. Any data added or changed after that timestamp won't be reflected in the AI's answers until a new snapshot is created.
## Accessing AI Chat
* Click the **Ask AI** button in the project header
* Use keyboard shortcut `Cmd/Ctrl + I`
* Click **Ask AI** from any detail page (contract, recording, entity, etc.) to start a chat with that item as context
## Context-Aware Queries
AI Chat always has access to all data in your current project -- contracts, catalog, CRM, and statements. But you can make it significantly more effective by giving it specific context.
### Why Context Matters
When you ask a general question like "What's the royalty rate?", the AI has to search across all your contracts. When you open chat from a specific contract's detail page, the AI immediately knows which contract you're referring to and can give faster, more precise answers.
### Adding Context from Detail Pages
Open AI Chat directly from any detail page to automatically scope the conversation:
| Open Chat From | Context Added |
| ------------------------ | ---------------------------------------------------------------------- |
| **Contract detail** | That specific contract, its extracted terms and its related agreements |
| **Recording detail** | That recording and its linked contracts |
| **Product/Album detail** | That product and its linked recordings and contracts |
| **Entity detail** | That entity and its related contracts |
| **Artist detail** | That artist and their linked recordings and contracts |
| **Statement detail** | That statement and its data |
Opening chat from a detail page is the best way to ask targeted questions. Instead of "What does the audit clause say?", you can simply ask "What does the audit clause say?" from the contract page and the AI already knows which contract you mean.
## Research Agents
When you ask a complex question, the AI doesn't just look up a single answer -- it spins up one or more **research agents** that autonomously investigate your data. Each agent specialises in a different type of research and can work in parallel.
### How It Works
1. You ask a question
2. The main AI breaks it into research tasks
3. One or more specialised agents are dispatched (in parallel when tasks are independent)
4. Each agent explores your data autonomously and writes a summary of its findings
5. The main AI synthesises all findings into a final answer with citations
### Specialised Sub-Agents
| Agent | Icon | What It Does |
| ----------------- | -------- | ------------------------------------------------------------------------------------- |
| **Explore Agent** | Compass | Searches contract PDFs and project files for relevant text, clauses, and terms |
| **SQL Agent** | Database | Queries your structured project data (catalog, CRM, statements) and revenue analytics |
| **Docs Agent** | BookOpen | Searches Royaltyport's platform documentation for guidance on features and workflows |
### Watching Agents Work
While agents are running, you'll see collapsible cards in the chat for each active agent. Each card shows a live status line with the current activity, the number of steps completed so far, and a running elapsed timer (e.g. "Querying Data... · 3 steps · 12s"). Click a card to expand it and see the queries it ran and the results it found. Once complete, each card shows the total number of steps taken, time elapsed, and token usage (e.g. "5 steps · 23k in (4k cached) · 4k out").
Some agent cards may show a small thoroughness badge (e.g. **QUICK** or **THOROUGH**) next to the task title. This indicates the depth of research the agent was asked to perform — controlled automatically by the AI based on the complexity of your question.
While agents run their internal steps, you may also see inline indicators appear in the chat thread — for example, **Listing recordings**, **Compiling results**, or **Searching files**. These represent specific data operations the agent is performing. Each indicator is collapsible — click it to see the exact query and results.
When an agent finishes its research, it produces a **summary** that is displayed inline in the chat. This includes:
* **Summary** — a brief written overview of what the agent found
* **Findings** — a list of key facts or data points the agent discovered (e.g., royalty rates, entity names, totals)
* **Referenced files** — if the agent compiled datasets into files, each file appears with its filename, a short description of its contents, and a row count so you can see what was captured
### Web Search
The AI can also search the web when a question requires external context (e.g., industry rates, general music business information). You'll see a **"Searching web"** indicator appear in the chat while this is in progress. Expand it to see the query, a summary of results, and the source links used.
### Context Compaction
For long or complex conversations, the AI may automatically compact its context to stay within limits. When this happens, you'll see a **"Compaction (Completed)"** indicator appear inline in the chat. Click it to expand and see a written summary of what was condensed. Compaction happens automatically — you don't need to do anything.
### Cross-Domain Questions
Because agents have access to both **contract data** and **revenue/statement data**, you can ask questions that span both domains:
| Example Question | What the AI Does |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| "Which contracts with a digital royalty rate above 30% generated over \$100k in revenue in 2025 H1?" | One agent searches contract terms for royalty rates, another queries statement revenue data, then results are cross-referenced |
| "Show me my top-earning recordings and their contract terms" | Queries revenue data for top earners, then looks up the associated contracts and their terms |
| "Are there any contracts where we're being underpaid based on statement data?" | Compares contractual royalty rates against actual payment data from statements |
## Task Plans
When the AI works on a complex multi-step task, it creates a **plan** — a named checklist of the steps it intends to take. The plan keeps you informed of progress as the AI works through the task.
### Plan Panel
A collapsible plan panel appears **above the chat input** whenever there is an active or recently completed plan. The panel header shows:
* **Plan name** — a short label describing the overall goal (e.g. "Deep Analysis of Neighboring Rights")
* **Progress status** — shown on the right (e.g. "2/4 completed, 1 in progress")
Click the header to expand the panel and see the full task list with the status of each step.
When the AI finishes and delivers its answer, any tasks that were still marked as in progress are automatically shown as completed.
### Inline Plan Updates
Each time the AI updates its plan during the conversation, a **plan indicator** appears inline in the message thread. Hover over the indicator to reveal a chevron, then click to expand it and see the full task list at that point in the conversation — useful for reviewing how the plan evolved.
## Answer Output Types
The AI can present information in several formats depending on the nature of your question.
### Tables
Structured data (e.g., a list of contracts with their royalty rates) is displayed as a formatted table directly in the chat.
### Charts
When a question has a clear visual answer -- such as revenue by artist or royalty rates by deal type -- the AI may display a **bar chart** inline in the response. Both vertical and horizontal bar layouts are used depending on the data. Hover over bars to see exact values.
Charts can display multiple data series simultaneously. A footnote may appear below the chart when the AI includes additional context or caveats about the data.
### Files
For large result sets, the AI generates downloadable files. See [File Generation](#file-generation) below.
## File Generation
For questions that produce large result sets (50+ items), the AI generates downloadable files instead of listing everything inline.
### Supported Output Formats
| Format | Best For |
| ---------------- | ------------------------------------------------------ |
| **CSV** | Simple data exports, single tables, spreadsheet import |
| **XLSX (Excel)** | Multi-sheet reports, formatted tables, styled outputs |
The AI chooses the appropriate format based on your request:
* Ask for "a CSV" to get a simple comma-separated file
* Ask for "an Excel file" or "a spreadsheet with multiple sheets" to get an XLSX with formatting
* For complex reports, the AI may generate XLSX automatically to support multiple sheets and styling
### When Files Are Generated
The AI automatically creates a file when:
* A query returns a large dataset (e.g., "List all recordings with their ISRCs")
* You ask for a report or export (e.g., "Create a spreadsheet of all contracts expiring this year")
* Multiple data sources need to be combined into one output
* You request specific formatting like multiple sheets or styled headers
### Where to Find Generated Files
Generated files appear in two places:
* **Inline in the chat** -- a download link is included directly in the AI's response
* **Sidebar Files section** -- expand the **Files** section in the chat sidebar to see all files from the conversation, labeled as "Assistant" (AI-generated) or "You" (uploaded by you)
## Memory
AI Chat can remember things across conversations. Memories are stored per project and per user — the AI reads them at the start of every conversation, so it can tailor its responses based on what it has learned about you and your work.
### How Memories Are Saved
The AI can save memories automatically during a conversation. When it does, you'll see a **Memory** indicator appear inline in the chat showing what was saved. You can also add memories manually at any time.
### Viewing and Managing Memories
Open the chat sidebar and expand the **Memory** section. Here you'll see all saved memories for the current project.
From this section you can:
* **Add a memory** — click **+ Add memory**, type your note, and press Enter
* **Edit a memory** — click the **⋯** menu next to a memory, then select **Edit**
* **Delete a memory** — click the **⋯** menu next to a memory, then select **Delete**
Memories are personal. They are only visible to you and only influence your own AI conversations. Other team members have their own separate memories.
Use memories to tell the AI about your preferences and working style — for example, "Always present royalty rates as percentages" or "I primarily work with publishing deals." The AI will factor these in without you having to repeat them.
## Commands
Type `/` in the chat input to access commands. Two commands are available:
### Select
Type `/select` to reference specific items from your project in the conversation. This opens a search panel where you can find and attach:
* Contracts
* Recordings
* Compositions
* Entities
* Artists
* Writers
* Relations
* Statements
Search by name, then click an item to add it as context. You can add multiple items to a single message, which is useful for comparison questions like "Compare the royalty terms between these two contracts."
### Upload
Type `/upload` to attach files to your conversation. This is how you provide additional context from external documents or data files.
The upload command lets you:
* **Search previously uploaded files** -- type a filename to find files you've uploaded to chat before
* **Upload new files** -- click the **Upload** button to attach a file directly into the conversation
#### Supported File Formats
| Category | Formats |
| ---------------- | ------------------------------- |
| **Spreadsheets** | `.csv`, `.xlsx`, `.xls` |
| **Documents** | `.pdf`, `.docx`, `.doc`, `.txt` |
| **Data** | `.json` |
| **Images** | `.jpg`, `.jpeg`, `.png` |
Uploaded files are not processed through the contract pipeline -- they're provided as-is to the AI for analysis. This is useful for:
* Quick analysis of external documents or draft agreements
* Comparing spreadsheet data against your contract terms
* Analyzing images or scanned documents
* Working with supplementary data files in JSON format
## Stopping a Chat
While the AI is generating a response or running research agents, a **Stop** button appears in the chat input area. Click it to stop the current response.
When you stop a chat, the AI finishes its current step cleanly and delivers a final message before stopping — it does not cut off mid-sentence or leave agents in a broken state. Any research agents that were in progress will also stop at their next natural step boundary.
After stopping, you can continue the conversation by sending a new message.
## Multiple Chats
You can run multiple chat sessions simultaneously. Each chat maintains its own conversation history, context, and active research agents.
To start a new chat while keeping an existing one running:
* Click the **+** button in the chat sidebar
* Or use keyboard shortcut `Cmd/Ctrl + Shift + /`
Switch between chats using the sidebar. This is useful when you want to:
* Research different topics in parallel
* Keep a reference conversation open while starting a new investigation
* Run multiple complex queries at the same time without waiting
Each chat can have its own research agents running concurrently. Start a long-running analysis in one chat, then switch to another to ask quick questions while the first continues working.
## Token Usage
The chat header shows a **token usage badge** so you can monitor how much of the AI's context window is being used in the current conversation.
Hover the badge to see a full breakdown:
| Row | What It Shows |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Context** | Input and output tokens used by the main context window in the most recent step, shown as **"X in / Y out"**. When prompt caching is active, a **(Xk cached)** note appears after the input count |
| **Main Agent** | Input and output tokens billed for the main AI agent in the most recent step, shown as **"X in / Y out"**. Cached tokens are shown inline when applicable |
| **All Steps** | Cumulative input and output tokens across the entire conversation, including all sub-agent steps |
| **Context Window** | Approximate size of the current context window in tokens (shown when available) |
Context tokens reflect what the AI is actively "reading" in a given step. Cumulative totals accumulate across all steps, including those run by research agents. Complex multi-agent queries will show higher totals than context tokens. If the context window grows too large, the AI will automatically compact it — see [Context Compaction](#context-compaction) above.
## Best Practices
For questions about a specific contract, recording, or entity, open chat from that item's detail page so the AI already has the right context.
When comparing multiple items, use the /select command to attach each one to your message.
Start multiple chat sessions for independent research threads. Run a long catalog export in one chat while asking quick questions in another.
Combine contract and revenue data in your questions. The AI can cross-reference deal terms with actual earnings data from statements.
For questions with numerical comparisons -- revenue by artist, royalty rates by deal type, advances over time -- ask the AI to "show as a chart" or "visualise this data" to get an inline bar chart.
Ask for "an Excel file" or "a spreadsheet with multiple sheets" when you need formatted reports with multiple data sets. The AI will generate styled XLSX files.
Use /upload to attach external spreadsheets, documents, or images for the AI to analyze alongside your project data.
More specific questions yield better answers. Instead of "What are my deals?", ask "What recording deals have advances over \$50,000?"
Build on previous answers with follow-up questions for deeper analysis.
Use New Chat when switching to unrelated questions for cleaner context.
Add memories for things you always want the AI to know — preferred output formats, deal types you focus on, or terminology conventions. The AI reads all your memories at the start of every conversation.
## What You Can Ask
Ask questions in natural language about your project data.
### Contract Analysis
| Example | What the AI Does |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
| "What is the royalty rate in the Sony agreement?" | Finds the contract and extracts all royalty rate provisions with effective rates |
| "What does the audit clause say in the Universal contract?" | Locates and summarizes the audit provisions with citations |
| "Summarize the key terms of the latest publishing deal" | Generates a comprehensive summary of royalties, advances, territories, and term |
| "Which contracts have full recoupment on recording costs?" | Searches all contracts for cost provisions with 100% recoupment rates |
| "Find all deals with MFN clauses" | Searches contract text for most-favored-nation provisions |
### Dates & Deadlines
| Example | What the AI Does |
| ------------------------------------------------------------ | -------------------------------------------------------------------- |
| "Which contracts expire in 2025?" | Queries calculated end dates across all contracts |
| "What are the option exercise deadlines this quarter?" | Finds option periods with upcoming deadlines |
| "Show me all contracts with perpetual rights" | Identifies deals with unlimited term durations |
| "When do the rights revert for the tracks released in 2023?" | Calculates reversion dates based on release dates and term durations |
### Financial & Revenue
| Example | What the AI Does |
| --------------------------------------------------------------- | ------------------------------------------------------- |
| "What are the total advances across all deals?" | Sums all advance payments from contract terms |
| "Which artists have the highest royalty rates?" | Compares rates across artist contracts |
| "Show me contracts where we're paying more than 20% on digital" | Filters by royalty rate thresholds |
| "What did Artist X earn last quarter?" | Queries statement data for revenue totals |
| "Compare actual earnings to contractual minimums" | Cross-references statements against contract guarantees |
### Catalog & Assets
| Example | What the AI Does |
| ------------------------------------------------ | ---------------------------------------------- |
| "List all ISRCs for Artist X" | Retrieves all recordings linked to that artist |
| "Which recordings don't have ISRCs?" | Identifies catalog gaps |
| "Show me all tracks from the 2024 album release" | Finds recordings by product/release |
| "What contracts cover this recording?" | Traces rights ownership for a specific asset |
### Comparisons
| Example | What the AI Does |
| ------------------------------------------------------------------------------ | --------------------------------------------------- |
| "Compare the territory rights between Deal A and Deal B" | Extracts and compares territory grants side-by-side |
| "How do the royalty structures differ between my publishing and master deals?" | Analyzes rate structures across deal types |
| "Which deal has better terms for sync licensing?" | Compares sync provisions and rates |
### Reports & Exports
| Example | What the AI Does |
| ----------------------------------------------------------------- | ---------------------------------------------- |
| "Create an Excel report of all contracts with their key terms" | Generates a multi-sheet XLSX with summary data |
| "Export all recordings with ISRCs, artists, and linked contracts" | Creates a comprehensive catalog spreadsheet |
| "Build a spreadsheet comparing royalty rates across all deals" | Generates a comparison table in XLSX format |
| "Give me a CSV of all entities with their contract counts" | Exports entity data in simple CSV format |
### Cross-Domain Analysis
| Example | What the AI Does |
| ------------------------------------------------------------------------------- | ------------------------------------------------------ |
| "Which deals with over 20% royalty rates earned the most last quarter?" | Cross-references contract terms with statement revenue |
| "Are there contracts where actual payments don't match the contractual rate?" | Compares statement data against contract provisions |
| "Show me my top-earning recordings and their deal terms" | Links revenue performance to contract rights |
| "Which territories are generating revenue but aren't covered by our contracts?" | Identifies gaps between earnings and rights |
## Limitations
| Limitation | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Project scope** | AI can only access data within your current project |
| **Limited internet access** | AI can search the web for general context, but cannot log in to external services or access private URLs -- use `/upload` to provide additional documents |
| **Legal interpretation** | Complex legal questions should be verified by professionals |
| **Snapshot-based** | AI uses a snapshot of your data, not a live connection -- check the snapshot timestamp in the sidebar |
## Privacy & Security
* AI Chat only accesses data within your current project
* Conversations are private to your account
* No data is shared between projects or organizations
* Chat history can be deleted at any time
* Agents are entirely sandboxed, meaning they physically can not access data they are not allowed to see.
## Related Documentation
Find specific items quickly.
Contract management and extraction.