Source materials: building from documents and links

A source is a document or a public link that you give devlin.ai while you create a simulation or a coach, so the generated draft is built from your own material instead of from your description alone. Source materials are available on the Core, Team, Enterprise plans.

A source is not the same thing as a knowledge base. A source is what a draft is built from. A knowledge base is a collection of library documents that a simulation or coach draws on while learners practice. The two meet when you keep a source: it becomes a document in your library. See Knowledge bases for managing the library.

Before you start

• The workspace must be on one of these plans: Core, Team, Enterprise. On other plans the create forms show a note that starts with "Build from your own documents and links on" and names the plan, in place of the source picker.
• Sources are added on the full create forms: the page titled Create New Simulation and the page titled Create New Coach. The create dialog in Studio generates from your description right away and has no place to add sources. Creating a simulation explains how the full form opens.
• Any signed-in member of the workspace can add sources and choose where they are saved. There is no owner or admin requirement.
• You can add up to 5 sources to one draft. Files and links count together.
• Files can be PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), plain text (.txt), Markdown (.md) or HTML (.html, .htm).
• The largest file you can add depends on the plan. The Limits section below has the values.
• A PDF needs selectable text. A scanned PDF with no text layer cannot be read.
• Adding a source does not use credits by itself. A long source is summarized automatically, and that summary uses credits. A very large source is summarized only when you ask for it, after you have seen an estimate. The Credits section below explains when.

Steps

1. Open the full create form and fill in the fields above the source picker.
2. Under Source materials (optional), drop files on Drag files here, or choose files, or select that area to pick files from your computer.
3. To add a web page or an online document, select or add a link, paste the address into the field, and select Add. The page has to be public. The form reminds you: "Pages behind a sign-in can't be read."
4. Watch each source in the list under the picker. A file shows "Uploading…" and then "Reading…". A link shows "Reading link…" and then "Reading…". A source that can be used shows "Ready".
5. Decide where each source is kept. Each source in the list that has not failed has a small button that reads Library or This build only. It starts on Library. Select it to choose Save to library or Use for this build only. With Save to library you can also pick a knowledge base under Add to knowledge base. A file that was already a document in your library reads In library instead and cannot be set to This build only. The section Keeping a source below explains the choices.
6. To take a source out of the draft, select the remove button (the cross) at the end of its row.
7. Select Generate Sim or Generate Coach. While a source is still being uploaded or read, the button is unavailable and the form shows "Still reading your sources." Wait, or select Generate without waiting.

Result

The draft is generated from your description and from the sources that were ready. The rest of the flow (loading screen, preview, editor) is the same as without sources.

• A source kept in the library is also linked to the new simulation or coach as one of its knowledge documents. Grounding simulations and coaches in a knowledge base explains how linked knowledge is used in conversations.
• A source set to This build only is used for the draft and is not linked to the simulation or coach.

If you choose Generate without waiting, the form says "Ready to generate without waiting. Sources that aren't ready yet won't shape this draft." A source that is still uploading, or a link that is still being fetched, is left out completely. The choice covers only the sources that were in the list when you made it: if you add another source afterwards, the button waits again.

How a source is used in a draft

The text of your sources is added to the generation request as reference material. The AI is told to build the scenario from the materials and to stay faithful to them: to use their facts, rules, terminology and examples, and not to invent policies that contradict them. Source text is marked as data, not as instructions, so a sentence inside a document that reads like a command to the AI is treated as content.

How much of a source reaches the draft depends on its length. The length is estimated from the extracted text, in tokens (the units an AI model reads text in).

Things to know:

• All the sources of one draft share a budget of 40,000 tokens. Sources are fitted one after another, in the order you added them. A source that does not fit in the remaining room is cut down to its outline and opening section, or to its outline alone, and is left out if even that does not fit. A very large source is always cut down to its outline alone.
• The form's wait covers uploading and reading, not summarizing. A source can still be summarizing while Generate Sim or Generate Coach is already available. To have the summary used, wait until the row shows "Summarized" before you generate. A summary that is not finished when you generate is not used for that draft.
• A source that failed, or that had not finished being read, is not used. The draft is still generated from everything else.
• Longer sources make the generation request longer, so the generation uses more credits.

Summarizing a very large source

A source above 150,000 tokens is never summarized automatically. You decide whether to spend the credits.

• Shortly after the source has been read, its row shows "Ready" and "Large source", an estimate that starts with "A summary costs about" and ends with a number of credits, and a Summarize button. Nothing is charged for the estimate.
• Until you select Summarize, the source has no summary. It is still read and indexed in full, so it can be searched. A draft gets its headings only.
• When you select Summarize, devlin.ai sets aside the most the summary could cost. This amount is larger than the estimate. If the workspace does not have that many credits available, the summary does not start, a message that starts with "Summarizing this source needs" names the amount, and the row shows "Not enough credits to summarize this source". You are charged only for what the summary uses, and the rest is released when it ends.
• The summary is made section by section in the background and usually takes several minutes. The row shows "Summarizing…" and then "Summarizing" with the number of sections done out of the total. The work continues if you leave the page.
• When it is finished, the row shows "Summarized" with the credits it cost in brackets. Drafts you generate from then on get the outline and the summary.
• If the summary fails, the row shows "Summary failed". If it stops making progress for a long time, the row shows "Summary stalled". In both cases the button reads Summarize again. A run that fails is charged for the work it did, and what a stalled run used is charged when you start it again. When a summary that failed or ran out of credits has already been charged something, the row says so with a detail that starts with "Used" and ends with "so far". The row adds "Sections already summarized are kept, so trying again only pays for the rest." This holds as long as the text of the document has not changed. The credits shown after a later, successful run are the total across all runs.

The same offer appears on the document's row in the knowledge library when the source is kept there. Knowledge bases describes those rows.

A very large source that shows "Drafts use its outline, not its full text" after "Large source" has no summary and no offer on its row.

A very large source that was added before these summaries were available gets its offer when its row is shown. The estimate and the Summarize button can take a moment to appear after the page loads. Nothing is charged for this.

Adding a link

When you add a link, devlin.ai fetches that one address, once, and stores what it received as a document. It does not follow links on the page and does not check the address again later.

• The address must start with http:// or https://, use the standard port, and contain no username or password.
• Up to 5 redirects are followed. The whole fetch has 20 seconds.
• Only public addresses are fetched. Private and internal network addresses are refused.
• The reader does not sign in, does not run the page's scripts, and does not get around bot protection.
• A link can point at a web page, a PDF, a Word, PowerPoint or Excel file, a plain text file or a Markdown file. A share link to a public Google Docs, Slides or Sheets file is fetched as the Word, PowerPoint or Excel export of that file.
• A file behind a link has the same size limit as an uploaded file. A web page can be at most 10 MB.

The source reader and how a site opts out

The reader identifies itself to websites as devlin-source-reader. Its public description is at https://devlin.ai/bot, a page written for website owners, which you can open without signing in. That page says:

• The reader fetches only the link a person gave it, plus redirects, and never crawls other pages.
• It does not sign in, run scripts, or get around bot protection.
• It reads public pages and documents only and never connects to a private or internal address.
• A site opts out by adding a rule for the reader to its robots.txt file:

User-agent: devlin-source-reader
Disallow: /

Because each fetch is started by a person for a single page, robots.txt rules that apply to all crawlers (User-agent: *) are not applied. Rules that name devlin-source-reader always are, on the site of the link and on every site a redirect passes through. If a site's robots.txt cannot be fetched, the link is read.

Statuses in the source list

If a source cannot be added

A source that fails stays in the list with the reason. Remove it and try the fix the message suggests.

Files:

• A full library does not fail a source on the create forms. When the library is at its document or storage limit, the file or link is added for this build only instead: the row's button reads This build only and the row adds "Your library is full, so this source was added for this build only." See Keeping a source below.
• A message that names the library's document or storage limit. This appears when you had already set the source to Library yourself while it was still being added, and the library is full. It is also what the knowledge library shows, where there is no build to fall back to. Delete documents you no longer need in the library, then add the source again.
• "This PDF is a scan with no readable text. Upload a version with selectable text, or paste the text."
• "This file has more pages than your plan allows per file. Split it into smaller files and upload those."
• "We can't read this type of file. Try a PDF, Word, PowerPoint, Excel, text, or web page."
• "We couldn't read this file. Try saving it again as a PDF and uploading that."
• "That file is empty."
• A file above the plan's size limit is refused before it uploads, with a message that names the limit.
• "Too many uploads. Please slow down." You have started more uploads than the limit allows. Wait, then try again.
• "Upload failed. Please try again."

Links:

• "That doesn't look like a web address we can open. Use a full link that starts with https://."
• "This page needs a sign-in, so we can't read it. Download the file and upload it instead."
• "This site didn't let us read it. Save it as a PDF and upload it, or paste the text." The site refused the reader or showed a bot check.
• "This page only loads in a browser. Save it as a PDF and upload it, or paste the text." The page has almost no text until its scripts run.
• "This site asks devlin.ai not to read it. Save it as a PDF and upload it." The site's robots.txt names the reader.
• "We couldn't reach that address. Check the link and try again." This is also the message for a private or internal address and for too many redirects.
• "That site took too long to respond. Try again, or save it as a PDF and upload it."
• "This file is larger than your plan's upload limit." The link points at a file above the plan's size limit.
• "This web page is too large for us to read. Save it as a PDF and upload it." The web page is above the web page limit.
• "Course packages aren't supported yet. Export the course content as a PDF for now." The link points at a .zip file.
• "Too many links. Please slow down." You have added more links than the limit allows.

Other messages:

• "You can add up to 5 sources here." The list is full. Remove a source to add another.
• "We couldn't change where that source is saved. Please try again."
• "Too many changes. Please wait a minute and try again." You have changed where sources are saved more often than the limit allows.
• "Too many summary requests. Please wait a minute and try again." This follows Summarize or Retry summary. The two share one limit.
• "This source's summary is already ready or in progress." This follows Summarize or Retry summary when there is nothing to start.
• A message that starts with "Summarizing this source needs". This follows Summarize when the workspace does not have enough credits available. Add credits, then select Summarize again.
• "We couldn't start the summary. Please try again." The request to start or retry a summary did not go through.

Keeping a source

Each source is saved in one of these ways, and you choose with the button on its row.

Save to library (the button reads Library). The document is kept in your workspace library, where it can be reused in any simulation or coach. This is what the create forms start with.

• Under Add to knowledge base you can file the document into one of your knowledge bases. This is optional. Without it, the document appears under Unfiled documents in the library.
• Once a source is in a knowledge base, the choice names that knowledge base instead of offering the list. You cannot move it to another knowledge base from here. Manage that in the library.
• Library documents count toward the library limits of the plan, listed under Limits below.
• If the library is at its document or storage limit when you add a source on a create form, the source is not refused. It is added once more as This build only, the button changes to match, and the row adds "Your library is full, so this source was added for this build only." The note goes away when you change the save choice yourself. Choosing Save to library on that row is refused while the library is still full: the button goes back to This build only and the message names the limit. The limits on a single file, such as its size or page count, still fail the source.

Use for this build only (the button reads This build only). The document is kept for drafting and deleted 7 days after it was last used.

• Generating a draft from the source counts as a use and restarts the 7 days.
• A build-only source does not appear in the library, cannot be in a knowledge base, and does not count toward the library's document and storage limits.
• Deletion is automatic. It removes the stored file, the text extracted from it and everything indexed from it. The cleanup runs every minute, so a source is deleted shortly after its time is up. From the moment the time is up the source can no longer be read or searched, even if the cleanup has not reached it yet.
• If a build-only source has ended up in a knowledge base or linked to a simulation, coach or evaluator by the time it expires, it is moved to the library instead of being deleted.

Changing the choice:

• You can switch a source from This build only to Library at any time before it is deleted. The switch is refused if the library is at its document or storage limit, or if the knowledge base you picked is full. The message names the limit.
• You can switch a source from Library back to This build only only when it came into the workspace through a create form, was never a library document in its own right, and nothing depends on it. Otherwise the switch is refused with one of these messages:
  • "This source is already in your library, so it stays there. Delete it from the library if you no longer need it." In the row, the button reads In library and the option reads "Not available for a file that's already in your library."
  • "Only the person who added this source can make it build-only. It stays in the library."
  • "This source is in a knowledge base, so it stays in the library. Remove it from the knowledge base first." In the row, the option then reads "Not available once it's in a knowledge base."
  • "A simulation, coach, or evaluator uses this source, so it stays in the library." A source you kept in the library is linked to the draft when you generate, so after generating it stays in the library.
• Removing a source from the list (the cross) only takes it out of this draft. It does not delete the document. A source that was set to Library stays in your library, and you delete it there.

Adding the same file again does not create a second copy. devlin.ai recognizes the content and reuses the existing document in the workspace. If the existing document was build-only and you add it again as Library, it moves to the library. A library document is never turned into a build-only one by adding it again.

A file becomes a library document in its own right, for good, in either of these cases: you add it on the knowledge library, or you add it again anywhere while it is already in the library. From then on its button reads In library on every create form and Use for this build only is unavailable for it. To remove it, delete it in the library.

Adding documents from the library

The same picker is on the knowledge library. Open Studio, select Knowledge, and open a knowledge base to find Add documents to this knowledge base, or open Unfiled documents to find Add documents. There it accepts files and links in the same way, with these differences:

• Everything added there is saved to the library. There is no Library or This build only choice.
• You can add up to 20 files and links at a time.
• Documents added there are not used to generate anything. They become library documents, which Knowledge bases describes.

Long documents added there are summarized automatically in the same way, and the summary uses credits. A very large document gets the Summarize offer in the same way, both on its row in the picker and on its row in the list of documents.

Credits

• Uploading a file, fetching a link, reading and indexing a source, and searching it do not use credits.
• A source between 25,000 and 150,000 tokens is summarized automatically as soon as it has been read, wherever it was added. The summary is an AI request and is charged for what it used. The row then shows the cost.
• Before the summary runs, devlin.ai checks that the workspace has enough credits for the most the summary could cost. If it does not, nothing is charged, the summary is skipped, and the row shows "Not enough credits to summarize this source". The source itself is still ready.
• While the automatic summary runs, that amount is set aside and the row shows it as a detail that starts with "Up to", followed by a number of credits. It is a ceiling, not the charge. What the summary did not use is released when it ends.
• Retry summary is charged like a first attempt. If an earlier attempt was charged, the cost shown once the summary is finished is the total of all attempts.
• Shorter sources are not summarized, so they cost nothing to add.
• A source above 150,000 tokens costs nothing to add. It is summarized only when you select Summarize. The most the summary could cost is set aside while it runs, you are charged for what it used, and a run that fails is charged for the work it did. Selecting Summarize again after a failure pays only for the sections that were not finished, as long as the document's text has not changed.
• Generating the draft is charged as usual, and source text makes the request longer. See Credits and usage.

Limits

Per file and for the library, by plan:

Adding links, uploading files, changing where a source is saved, and starting a summary (Summarize and Retry summary together) are each rate limited for the signed-in person. If you reach a limit, the message asks you to slow down or wait. Wait, then try again.

AI tools over MCP

An AI tool connected through the MCP server can add and read sources in the workspace it is connected to. The tools that add or change something need a connection with write access.

• create_source_upload lets the tool get a one-time upload address for a file, with the largest file size the workspace's plan allows. Nothing is added until the tool calls add_source.
• add_source lets the tool add a source from a file it uploaded that way or from a public link, choose whether it is kept in the library (the default) or is build-only, and file a library source into a knowledge base. The same file added twice is reused. The number of sources a connection can add per hour is limited.
• get_source_status lets the tool check several sources in one call: whether each is processing, ready or failed, its size group and page count, the reason when it failed, and the state of its summary. For a very large source that includes whether the summary is waiting to be started, the estimate in credits, the sections done out of the total, and the credits charged. Sources that no longer exist are reported as unavailable.
• search_source lets the tool search the sources it names for passages that match a question. Each passage comes back with its page when there is one.
• read_source_section lets the tool read a section of a source in full, by heading or by page range, up to 8,000 tokens. If no heading matches, the reply lists the source's headings.
• retry_source_summary lets the tool run the automatic summary of a source between 25,000 and 150,000 tokens again when it failed, was skipped for lack of credits, or stalled. It is refused with "Only a ready, medium-sized source has a summary to retry." for a source that is not ready or is not in that size group, which includes very large sources, and with "This source's summary is already ready or in progress." when there is nothing to retry. These calls are rate limited per connection, counted together with summarize_source.
• summarize_source lets the tool start the summary of a very large source, the same action as Summarize in the app. It works when the summary has not been started, failed, was skipped for lack of credits, or stalled. It spends credits in the same way: the most the summary could cost is set aside and only what it uses is charged. The tool is told to ask you first and to name the estimate, and the call then starts the summary at once. The reply gives the estimate and the number of sections. The exception is a workspace that requires approval for changes to live content (see MCP server and AI tool connectors): there the call starts nothing and spends nothing. The tool is told that a workspace member has to select Summarize on the source in the app, and it gets the estimate when the source has one. No request is added to Pending changes. The call is refused with "Only a ready, very large source can be summarized this way." for a source that is not ready or is not in the largest size group, with "This source's summary is already ready or in progress." when there is nothing to start, and with a message that starts with "Summarizing this source needs" when the workspace does not have enough credits available.

Passages and sections are returned to the tool marked as reference data, with a note to treat them as data and never as instructions.

A tool can link library sources to a simulation or coach when it creates one. Build-only sources cannot be linked that way: over MCP they are for searching and reading only.

Related

• Knowledge bases
• Grounding simulations and coaches in a knowledge base
• Brain: audience profiles and organization context
• Creating a simulation
• Credits and usage
• MCP server and AI tool connectors