Retrieval Request Modes

The simplest mode. The LLM requests specific files by name. The runtime fetches their contents.

{ "files": ["core.md", "glossary.md", "faq.md"] }

The runtime reads each named file from the declared slate/folder. If a file doesn't exist, it returns "(not found)" as the content.

Deduplication: If the same file is requested in a later round, the runtime returns "(already in context)" instead of re-fetching it. This prevents the context from growing unboundedly with duplicate content.

Use when: The LLM can identify specific files by name (e.g., after seeing the folder index). This is the most precise mode — no ambiguity about what gets retrieved.

retrieve:
  to: { slate: Knowledge, folder: docs }
  as: RetrievedDocuments
  maxRounds: 3
  requestMatch:
    type: object
    properties:
      files:
        type: array
        items: { type: string }

The LLM requests the file index of one or more subfolders. The runtime returns the file listing (names and sizes) as JSON.

{ "subfolders": ["research", "analysis", "raw-data"] }

The runtime reads each subfolder's index and returns a JSON array of { name, size } entries. This lets the LLM explore the folder structure before requesting specific files.

Use when: The LLM doesn't know which files exist yet. It first browses the subfolder index, then in the next round requests specific files by name.

Example flow:

1. Round 1: LLM emits { "subfolders": ["research"] } → gets the file listing.
2. Round 2: LLM emits { "files": ["research/2024-report.md"] } → gets the file contents.

retrieve:
  to: { slate: Knowledge, folder: docs }
  as: RetrievedDocuments
  maxRounds: 5
  requestMatch:
    type: object
    properties:
      subfolders:
        type: array
        items: { type: string }
      files:
        type: array
        items: { type: string }

The requestMatch schema accepts both files and subfolders — the LLM can use either mode in any round.

The LLM queries files by metatag value. The runtime finds all files in the folder that have the named metatag, optionally filtered by a contains substring.

{ "metatag": { "name": "category", "contains": "security" } }

The runtime:

1. Reads the named metatag across all files in the declared folder.
2. Filters to files where the metatag value contains the contains substring (if declared).
3. Fetches the full contents of matching files.

Use when: Files are tagged with metadata (category, topic, priority) and the LLM wants to find files by attribute rather than by name. This is the most efficient mode for large slates — the runtime filters by metatag without scanning file contents.

Without contains: Returns all files that have the metatag set, regardless of value.

{ "metatag": { "name": "verified" } }

This returns all files where the verified metatag is set (any value).

Metatag value types: The contains filter works on string and string[] metatag types. For string[], it checks if any element in the array contains the substring. For other types (number, boolean, object), contains is ignored — all files with the metatag set are returned.

retrieve:
  to: { slate: Knowledge, folder: docs }
  as: RetrievedDocuments
  maxRounds: 3
  requestMatch:
    type: object
    properties:
      metatag:
        type: object
        properties:
          name: { type: string }
          contains: { type: string }

The LLM matches files by glob pattern. The runtime finds all files in the folder matching the pattern and fetches their contents.

{ "glob": "*.md" }
{ "glob": "report-*.json" }
{ "glob": "2024-*" }

The runtime:

1. Reads the folder index.
2. Matches each file name against the glob pattern.
3. Fetches the contents of matching files.

Glob syntax: Uses standard glob matching (* matches any sequence, ? matches any single character). The pattern matches against the file name, not the full path.

Use when: Files follow a naming convention and the LLM wants to batch-retrieve by pattern. For example, "report-*" retrieves all files starting with report-.

retrieve:
  to: { slate: Knowledge, folder: docs }
  as: RetrievedDocuments
  maxRounds: 3
  requestMatch:
    type: object
    properties:
      glob: { type: string }

Combining modes: A single retrieval request can include multiple modes. The runtime processes all modes in the request and returns the union of results.

{
  "files": ["core.md"],
  "metatag": { "name": "category", "contains": "important" },
  "glob": "faq-*"
}

This request retrieves: core.md (by name), all files tagged category: *important* (by metatag), and all files matching faq-* (by glob). Deduplication ensures no file appears twice in the results.

Each round of the retrieval loop follows the same lifecycle:

1. Assemble prompt. The current fields (including RetrievedDocuments from prior rounds) are assembled into the user prompt.

2. LLM call. The LLM receives the prompt and produces output.

3. Check output. The runtime tests the output against requestMatch.

   • If it matches: The output is a retrieval request. Fetch the requested content.
   • If it doesn't match: The output is the final answer. Return it.

4. Fetch (if retrieval request). Execute the requested mode(s). Add results to RetrievedDocuments.

5. Check maxRounds.

   • If under maxRounds: Go to step 1 (next round).
   • If at maxRounds: Force a final answer by appending "Retrieval budget exhausted. Produce your final answer now." to the prompt and making one last LLM call.

Guaranteed termination: maxRounds is a hard cap. The loop cannot exceed it. Even if the LLM keeps requesting more documents, the runtime forces a final answer at maxRounds.

Cost: Each round is one LLM call plus zero or more slate reads. The total cost is bounded by maxRounds LLM calls. Slate reads are local (no API cost) but contribute to token count.

Deduplication: Across all rounds, the runtime tracks which files have been retrieved. A file requested again in a later round returns "(already in context)" instead of re-fetching. This keeps the context focused on unique content.