Knowledge Sources

A knowledge base is an editable set of articles that Fruxon publishes into a backing asset, which your agents then search. A knowledge source is where those articles come from. It reads items from another system, such as resolved support conversations, and creates or extends articles in the base.

A knowledge base doesn't need any sources. Writing articles by hand is fully supported, and sources only add to that. You manage sources in Knowledge → your base → Sources, through the …/knowledgeBases/{knowledgeBase}/sources API, or with fruxon knowledge-bases source in the CLI.

Managed and linked sources

Each source has a managementMode, which decides who owns the automation and agents that do the work:

Use managementMode to choose between the two, not kind. kind only says what the evidence is (PROVIDER_CONVERSATIONS, FILES, STRUCTURED_RECORDS, and so on), and a source of any kind can be either managed or linked. Today Fruxon can build only PROVIDER_CONVERSATIONS sources. Any other kind has to be linked to an automation you already run.

Managed resources can only be changed from Knowledge. The agents and automation behind a managed source carry a Managed by Knowledge chip on the Agents and Automations pages. They're grouped there, and their enable, run, and delete controls are hidden. If you try to change one's configuration directly through the API, you get a 409 that names the source. To take a managed implementation over and edit it yourself, use Fork as custom.

Linking has its own rules. When you link a source, Fruxon checks every resource you name against your tenant. An automation can back only one knowledge source, and you can't link a resource that another owner manages. Pause and resume don't apply to a linked source, because Fruxon doesn't change your automation's schedule. Turn the automation itself on or off instead.

What a managed conversation source builds

When you build a source, Fruxon creates everything a working conversation-to-article pipeline needs, and marks each resource as managed as soon as it's created:

The first managed source on a base also creates two agents that belong to the base as a whole. Neither holds any tools, and neither runs on a schedule:

If the base already has a consolidator or an editor, it keeps that agent, and the new source doesn't create a second one. These two agents are attached to the base, but they're recorded against the source that created them. If you delete that source, they pass to the base's oldest remaining managed source. If there isn't one, the base is left without them and the agents are deleted along with the source.

The agents are named after the source (for example, Resolved support chats — extractor). A new source starts in PROVISIONING and moves to PAUSED once every resource exists. If any step fails, Fruxon deletes only the resources it had already recorded as managed, so a failed build never leaves a half-built source running.

Before you build one

• The knowledge base must be scoped to an Application. Fruxon refuses to build a conversation source on a workspace-wide base, because that would make an application's conversations visible to every application.
• The base must not be archived.
• The connector must list conversations. The source reads through a door, a ready-made way of listing items from a connector. Only doors that list conversations and can fetch a full transcript are accepted. Today that is the TexterChat chat door, texterchat_chats.

The recipe settings

The conversations object on the create request holds everything the stock recipe (knowledge.provider_conversations) needs. Fruxon turns these settings into the agents' prompts and the automation's schedule:

The source keeps a record of which recipe version built it, in recipeKey and recipeVersion. Fruxon never changes a running source just because the stock recipe changes.

Lifecycle

A safe first run

A new managed source waits in PAUSED on purpose, because creating the pipeline and letting it read your whole history are separate decisions. The usual order is:

1. Preview it to see what it would read and how much is waiting.
2. Sync a small pass to see real articles, real review decisions, and real cost.
3. Check the results, in the Documents list and the review queue, and with Inspect work.
4. Resume it to let the daily schedule work through the rest.

What each action does

Preview

Preview lists what the source would read, the same way a real pass would, and compares each item against the ledger. It admits nothing and doesn't move the cursor. Each item shows only its identity and a label, never the transcript, so people who own the knowledge base can check a source without access to the source system.

• limit sets how many items to sample. The default is 10 and the maximum is 50.
• countOnly=true returns how much is waiting instead of a sample: total listed, minus filtered (dropped by the source's own rule), minus alreadyHeld (already in the ledger). What's left is the work that turning the source on would take on. When truncated is true, the scan stopped at a limit and every number is a minimum, not a total.
• The list isn't limited to items after the cursor, because a source that's already caught up would come back empty and look broken. Each item's withinBound says whether the next scheduled pass would still reach it.

Resume and pause

Resume turns on the managed automation's daily schedule. Before scheduling it, Fruxon checks the automation the same way it checks one of your own edits, so an automation that can no longer run is refused instead of scheduled. Only a PAUSED source can be resumed. Resuming a source whose knowledge base is archived is refused. Restore the base first.

Pause turns the schedule off. Work that's already been claimed runs to completion. Pausing only stops the next pass. Calling pause again is safe, and fixes a source whose automation was somehow left running.

Sync

Sync runs one bounded pass right now. It's meant for trying out a new source or nudging one along, not for working through a whole backlog. That's what the schedule is for.

• maxAdmit limits how many new items the pass takes in, and maxDispatch limits how many it processes across both stages. Each defaults to 25, and neither can go above 1,000.
• A paused source can still be synced. Pausing stops the automatic pass, not one you start yourself.
• The pass is the automation's own pass. It uses the same lock and the same log, and its cost is recorded the same way. If another pass is already running, the response says alreadyRunning: true and this call does nothing.
• The response repeats the limits back to you, so you can tell a pass that hit its cap from a source that had nothing left to read.

Archive and restore

Archiving takes a source out of the working list without taking anything down. The agents, automation, ledger, ownership records, and evidence all stay, and the source can still be fetched by id, so articles that cite it can still name it. Archiving a managed source also stops its schedule.

Restoring (:unarchive) brings a managed source back as PAUSED, because its schedule is still off, and resuming is a separate decision. A linked source comes back as ACTIVE.

Archiving a knowledge base archives all of its sources first, and stops their schedules.

Fork as custom

Forking hands a managed implementation over to you. It changes the owner; it doesn't make a copy. The same automation, agents, and ledger keep running, with their backlog, history, and evidence intact. The only change is that they're now yours to edit.

After a fork:

• The source becomes LINKED. Fruxon still shows its activity, and preview and sync still work, but Fruxon can no longer change or delete its resources.
• To pause or resume the source, turn its automation on or off.
• Changing the approval policy only updates the source's record. It no longer rolls out a new merger, so keeping the merger's prompt and tools in line with the policy is now up to you.
• recipeKey and recipeVersion stay on the source as a record of where it came from.

Delete

What a delete removes depends on who owns the implementation:

• Linked: only the source record and its ownership records are removed. Your automation and agents aren't touched.
• Managed: Fruxon stops the automation, then deletes every resource it recorded as managed: the agents, the automation, and the ledger. This means the source's per-item history and backlog are gone. Your connector configuration is kept.

Either way, articles the source already produced stay, and so does their evidence. There's currently no single action that deletes a source and the articles it generated. To remove those articles, delete them from the base.

If a managed implementation can't be fully deleted, the call returns 409 and the source stays visible as DEGRADED, so the leftover resources can still be found. A background repair job retries the delete. A knowledge base can't be hard-deleted while it still has sources, so delete its sources first.

Watching a source

• GET …/sources/{source}/activity reports what the automation behind the source has been doing. That includes item counts by ledger status, where READY means backlog, not progress, and the count at each stage. It also shows the oldest waiting item, the last scan, the last admitted item, when the cursor last moved, total cost and runs, and whether the automation still writes to this base. There's no percent-complete figure, because an incremental source keeps growing and has no fixed total. If workAvailable is false, the source is in reduced health rather than failing. That usually means a linked automation was changed or deleted, and workUnavailableReason says which.
• GET …/sources/{source}/passes lists every pass, newest first, with what it admitted, processed, completed, and spent.

Governance

Each source has three governance settings. They decide whether a person reviews its articles, and when accepted articles reach the index your agents search.

Approval policy

Under SAMPLED, an article always goes to review when any of these is true:

• The built-in check finds what looks like personal data in the written article: an email address, a phone number or other long number, or a labelled customer identifier.
• The extractor raised a policy flag.
• The extractor's confidence is below 0.85, or wasn't reported.
• The merger rewrote an existing article instead of creating a new one or adding to one.
• Any of this information is missing. Missing information always sends the article to review.

Each remaining article is assigned to one of 100 buckets, based on the source and the conversation's id. Articles in the lowest approvalSamplePercent buckets go to review as a quality sample, and the rest are published. Because the bucket never changes for a given conversation, retrying it can't change whether it goes to review. A sample percent of 0 means only risky articles are reviewed, and 100 means every article is.

The reason an article went to review, such as low_extractor_confidence or quality_sample, is saved with that version of the article, so the review queue can show why each one is there.

AUTOMATIC has to be earned. A source can use it only when the base has a current consolidation calibration, and the base's consolidator agent works. To calibrate, run a report-only consolidation pass, then accept it with POST …/knowledgeBases/{knowledgeBase}/consolidations/{consolidation}:calibrate. Changing the base's consolidation threshold or locale clears the calibration. A brand-new base has no calibration, so its first source can use SAMPLED at most. A linked source can use AUTOMATIC only if it names its publishing agent with the MERGER role.

Publish policy

Publishing always covers the whole base. There's one snapshot of every published article, not one per source. So the strictest source wins: while any source on the base uses MANUAL publishing, the base doesn't publish itself. Paused sources count, and archived ones don't. Creating a source with AUTOMATIC_AFTER_APPROVAL, or switching one to it, turns on the base's automatic publishing if it was off. Changing a source's policy never turns it off.

Changing governance

Use Edit governance… on the source card, or PATCH …/sources/{source} with any of the three settings. Settings you leave out stay the same.

• For a managed source, changing the approval policy first rolls out a new merger version with a matching prompt and tools, and only then saves the new policy. That way the policy you see is the one the merger actually follows.
• An approval-policy change is refused for a managed source built with an older recipe version, because rebuilding its merger would quietly upgrade the recipe. The sample percent and the publish policy can still be changed.
• Governance can't be changed on an archived or deleting source, on a source whose base is archived, or on a managed source that's still being built or is DEGRADED.

Changing a source after creation

Currently, governance is the only thing you can change on an existing source. All the other settings are fixed when the source is built: the product or service, language, article topics, what a conversation is called, bot messages, the extract, merge, and consolidation models, and the daily schedule. PATCH …/sources/{source} accepts only approvalPolicy, approvalSamplePercent, and publishPolicy. Editing the managed agents or automation directly is refused with a 409. GET …/sources/{source} returns the settings a source was built with, in config.

To change those settings today, choose one of these:

• Fork as custom, then edit the agents and automation yourself. This keeps the ledger history and backlog. The fork is one-way, though, and afterwards config describes what was originally built, not what's running.
• Build a replacement source, then delete the old one. You get a new managed source, but the old one's ledger history and backlog are lost. The new source also doesn't know which conversations the old one already read, so it reads them again, and you pay for them again. Set Start from to limit how far back it goes. The order matters if the old source created the base's consolidator and editor. Build the new source first, and they move to it unchanged. Delete the old one first, and they're deleted, and the new source creates fresh ones from its own settings.

API and CLI

All endpoints live under /v1/tenants/{tenant}/knowledgeBases/{knowledgeBase}. Reads and previews need the assets:read scope, and every other action needs assets:write.

The CLI covers the same actions in fruxon 0.14.0 and later:

fruxon knowledge-bases source list <kb>
fruxon knowledge-bases source add <kb> --file ./source.json     # --schema prints the request shape
fruxon knowledge-bases source preview <kb> <source> --count-only
fruxon knowledge-bases source sync <kb> <source> --max-admit 10
fruxon knowledge-bases source resume <kb> <source>
fruxon knowledge-bases source update <kb> <source> --file ./governance.json
fruxon knowledge-bases source activity <kb> <source>
fruxon knowledge-bases source fork <kb> <source>
fruxon knowledge-bases source delete <kb> <source>

The CLI asks for confirmation before resume, sync, fork, and delete. Pass --yes to skip the prompt. You must pass it when the CLI runs non-interactively, for example in CI.

Next steps

• Knowledge Base & Assets: how the published base is searched and attached to agents
• Applications: scoping a knowledge base, which a conversation source requires
• Agent Network → Triggers: the automations a source runs on
• CLI: install and sign in