Handling Multiple Files (Inputs & Outputs)

TeXRA excels at managing complex academic projects often split across multiple files, like a paper with several chapters or appendices. This guide explains how to work with multiple input files and how agents can generate multiple, distinct output files in a single run.

Why Use Multiple Files?

Working with multiple files is essential when:

• Your source document is split (e.g., chapter1.tex, chapter2.tex, appendixA.tex).
• You need to apply consistent changes (like polishing or correcting) across related documents.
• You only want an agent to modify specific parts (e.g., only update chapter2.tex and appendixA.tex based on the full context).
• An agent needs to generate distinct outputs based on a single input (less common, but possible).

UI for Multiple Files

The TeXRA UI provides dedicated sections for managing multiple files:

• Input Files: Use the "▼" toggle to add multiple source files. These are typically concatenated and provided as context to the selected agent.
• Multiple Outputs:
  • Use the "▼" toggle to activate multiple output mode.
  • Use the "+" button () to list the exact filenames you expect the agent to generate. Order matters if the agent references them by position.
  • The list can be cleared ().
  • If this section is not toggled/activated, TeXRA expects the agent to produce only a single output file, named based on the primary input file.
• Output Filename Override: When not using Multiple Outputs, you can specify a custom name for the single output file here. This is ignored if Multiple Outputs is active.

(See File Management for general UI controls.)

How It Works: Agent Input

When you provide multiple input files, TeXRA typically combines their content (often wrapping each in <document name=\"...\"> tags within a parent <documents> tag) and includes it in the prompt sent to the selected agent. The agent receives the combined context to inform its processing.

How It Works: Agent Output & Extraction

This is the crucial part for generating multiple distinct files:

1. User Specifies Outputs: You list the desired output filenames in the "Multiple Outputs" UI section (e.g., chapter2_polish_r0_model.tex, appendixA_polish_r0_model.tex).

2. Agent Generates Structured XML: The selected agent must be designed (through its prompts) to produce a single XML response containing separate blocks for each intended output file, using a structure like this:

   <latex_documents>  <!-- Or agent's specific documentTag -->
     <document name="chapter2_polish_r0_model.tex">
       % ... content for the first output file ...
     </document>
     <document name="appendixA_polish_r0_model.tex">
       % ... content for the second output file ...
     </document>
     ...
   </latex_documents>

3. TeXRA Extracts: The TeXRA backend (OutputHandler.ts) parses this XML response. It looks for <document> tags with a name attribute that exactly matches one of the filenames you listed in the UI.

4. Files Saved: For each matching tag found, TeXRA extracts the content within that tag and saves it to the corresponding filename. If the agent's response doesn't include a <document> tag with a name matching one you specified, that file will not be created or updated.

Key Point: The agent doesn't magically know how to split output (it hasn't mastered telepathy... yet). It must be explicitly instructed via its prompts (like in polish_multiple.yaml) to generate the <document name=\"...\"> structure matching the list you provide in the UI.

The _multiple Suffix

You might notice _multiple appended to the agent name in logs or temporary filenames when using the "Multiple Outputs" feature. This internal suffix indicates that TeXRA is operating in a context where multiple output files are expected based on your UI selection; it doesn't necessarily mean a different agent .yaml file (like polish_multiple.yaml) was automatically chosen unless you selected it explicitly.

Example: polish_multiple Agent Prompts

The built-in polish_multiple.yaml agent (which inherits from polish) demonstrates how prompts need to be structured to request and format multiple outputs within the <latex_documents> tag. Its userRequest prompt explicitly asks the model to structure its response like this, referencing the variable which contains the comma-separated list of filenames from the UI:

# (Inside polish_multiple.yaml userRequest prompt)
# ... instructions ...
# Use the following format:
<latex_documents>
<document name="{OUTPUT_FILES_ORDER[0]}">
% 1ST_UPDATED_LATEX_DOCUMENT_1 HERE
</document>
<document name="{OUTPUT_FILES_ORDER[1]}">
% 1ST_UPDATED_LATEX_DOCUMENT_2 HERE
</document>
... (repeat for all output files)
</latex_documents>

This instructs the LLM to generate the necessary XML structure that TeXRA's OutputHandler can parse.

When to Use

• Applying consistent edits (e.g., polish, correct) across multiple related .tex files.
• Tasks where an agent naturally produces distinct outputs (though less common than editing existing files).
• Targeting agent modifications to specific files within a larger project.

Next Steps

• Custom Agents: Learn how to design prompts for agents handling multiple outputs.
• File Management: Review the file selection UI in detail.
• Agent Architecture: Understand the overall agent execution flow.