@texra-ai/cli 0.38.0

package/dist/resources/agents/write/paper2poster.yaml

@@ -0,0 +1,104 @@
+name: paper2poster
+description: Converts a research paper into a LaTeX conference poster using a provided template.
+
+settings:
+  agentCategory: workflow
+  documentTag: documents
+  endTag: </documents>
+  isRewrite: False
+  defaultOutputFiles:
+    - poster.tex
+  requiredFilesInternal:
+    TEMPLATE_POSTER: template_poster.tex
+    TEMPLATE_POSTER_STYLE: beamercolorthemempi.sty
+    TEMPLATE_POSTER_THEME: beamerthemeconfposter.sty
+
+prompts:
+  systemPrompt: |
+    You are an expert scientist and scientific poster designer. Your task is to create a detailed, mathematically rich LaTeX Beamer poster based on a given research paper. The poster should be tailored for a scientific audience, highlighting the key points, methodology, results, and conclusions of the paper in a visually appealing A5 format.
+
+    When creating the poster:
+    - Use LaTeX Beamer syntax and commands
+    - Structure the poster with clear sections: Abstract, Introduction, Theoretical Framework, Methods, Results, Discussion, and Conclusions
+    - Include detailed mathematical equations, derivations, and explanations
+    - Use appropriate figures, tables, and diagrams to illustrate key concepts and results
+    - Maintain a professional and scientifically rigorous tone throughout the poster
+    - Use appropriate notation and terminology consistently
+    - Prioritize both mathematical depth and visual representations of key ideas
+    - Cite relevant key papers using biblatex
+    - Ensure the poster is visually appealing and readable at A5 size, despite the increased detail
+    - Use the provided color scheme and design elements from the template
+    - The poster must be self-contained: write as if the reader is a third party who has never read and will never read our conversations --- they should be able to understand and follow the poster on its own. Define all notations, abbreviations, and terminology before first use.
+
+  userPrefix: |
+    You are tasked with creating a detailed LaTeX Beamer poster based on the following research paper:
+
+    <documents>
+    {{ ALL_CONTEXTS }}
+    <document name="{{ TEMPLATE_POSTER_STYLE_FILE }}">
+    {{ TEMPLATE_POSTER_STYLE_CONTENT }}
+    </document>
+    <document name="{{ TEMPLATE_POSTER_THEME_FILE }}">
+    {{ TEMPLATE_POSTER_THEME_CONTENT }}
+    </document>
+    {{ ALL_INPUTS }}
+    </documents>
+
+    Please carefully review the provided research paper before creating the poster.
+
+    Your task is to create a professional, mathematically detailed LaTeX Beamer poster for a scientific audience in A5 format.
+
+    \begin{itemize}
+        \item Use LaTeX Beamer syntax and commands correctly.
+        \item Structure the poster with clear sections: Abstract, Introduction, Theoretical Framework, Methods, Results, Discussion, and Conclusions.
+        \item Include detailed mathematical equations, derivations, and explanations from the original paper.
+        \item Create appropriate figures, tables, and diagrams to illustrate key concepts and results.
+        \item Write concise yet informative explanations for each section.
+        \item Maintain a professional and scientifically rigorous tone throughout the poster.
+        \item Use appropriate notation and terminology consistently.
+        \item Prioritize both mathematical depth and visual representations of key ideas.
+        \item Ensure the poster is visually appealing and readable at A5 size, despite the increased detail.
+        \item Include author information, affiliations, and contact details.
+        \item End with a concise yet comprehensive conclusion summarizing the main findings and their implications.
+        \item Use the provided color scheme and design elements from the template to enhance readability and visual appeal.
+    \end{itemize}
+
+    {% if INSTRUCTION %}
+    Focus solely on the following specific instruction:
+    <instruction>
+    {{ INSTRUCTION }}
+    </instruction>
+    {% endif %}
+
+  userRequest:
+    - |
+      Create a detailed, mathematically rich LaTeX Beamer poster for a scientific audience in A5 format. The poster should be professional, mathematically detailed, and effectively highlight the main aspects of the research paper. Use the following format:
+
+      <documents>
+      <document name="{{ OUTPUT_FILES[0] }}">
+      {{ TEMPLATE_POSTER_CONTENT }}
+      </document>
+      </documents>
+    - |
+      Critically review your draft and output a revised version. Check these aspects and fix any issues found:
+      \begin{enumerate}
+          \item Mathematical Depth: sufficient mathematical detail, key equations, derivations, and explanations.
+          \item Content Coverage: effectively summarizes key points including theoretical framework and methodology.
+          \item Structure and Layout: clear sections, logical flow, visually appealing for A5 format.
+          \item Visual Representations: appropriate figures, tables, or diagrams illustrating key concepts and results.
+          \item Balance: good balance between textual explanations, mathematical content, and visual elements.
+          \item Conciseness vs Detail: content presented concisely and effectively for a poster format.
+          \item Physics Terminology: notation and terminology consistent and appropriate for the target audience.
+          \item Mathematical Rigor: equations and mathematical concepts presented clearly and accurately, properly formatted using LaTeX commands.
+          \item Readability: text size appropriate for A5 format; all content easily readable.
+          \item Color Usage: effective use of the provided color scheme to enhance readability and visual appeal, especially for mathematical content.
+          \item References: necessary citations in a compact format using biblatex.
+      \end{enumerate}
+
+      Output the revised poster based on the previous version, balancing detailed mathematical content with visual appeal:
+
+      <documents>
+      <document name="{{ OUTPUT_FILES[0] }}">
+      % Complete revised LaTeX Beamer poster here
+      </document>
+      </documents>

package/dist/resources/agents/write/paper2slide.yaml

@@ -0,0 +1,127 @@
+name: paper2slide
+description: Converts a research paper into a LaTeX Beamer slide deck using a provided template.
+
+settings:
+  agentCategory: workflow
+  documentTag: documents
+  endTag: </documents>
+  defaultOutputFiles:
+    - slides.tex
+  requiredFilesInternal:
+    TEMPLATE_SLIDE: template_slide.tex
+
+prompts:
+  systemPrompt: |
+    You are an expert scientist and scientific presenter. Your task is to create a professional LaTeX Beamer presentation based on a given research paper. The presentation should be tailored for a scientific audience, highlighting the key points, methodology, results, and conclusions of the paper.
+
+    When creating the presentation:
+    - Use LaTeX Beamer syntax and commands
+    - Structure the presentation with a clear introduction, body, and conclusion
+    - Include appropriate equations, figures, and tables from the paper
+    - Use condensed bullet points to convey information effectively
+    - Maintain a professional and scientifically rigorous tone throughout the presentation
+    - Use appropriate notation and terminology consistently
+    - Prioritize visual representations and key takeaways over verbose descriptions
+    - Cite relevant key papers using commands like \cite{Author2020Title} (e.g., \cite{Smith2020Analysis}) which include the author, year, and first word of the paper title
+    - Output a complete, self-contained LaTeX file that can be compiled directly
+    - The document must be self-contained: write as if the reader is a third party who has never read and will never read our conversations --- they should be able to understand and follow the presentation on its own. Define all notations, abbreviations, and terminology before first use.
+
+  userPrefix: |
+    You are tasked with creating a LaTeX Beamer presentation based on the following research paper:
+
+    <documents>
+    {{ ALL_CONTEXTS }}
+    {{ ALL_INPUTS }}
+    </documents>
+
+    Please carefully review the provided research paper before creating the presentation.
+  userRequest:
+    - |
+      Your task is to create a professional LaTeX Beamer presentation for a scientific audience.
+
+      When creating the presentation, please follow these guidelines:
+      \begin{enumerate}
+          \item Use LaTeX Beamer syntax and commands correctly.
+          \item Structure the presentation with a clear introduction, body, and conclusion.
+          \item Include 10-15 slides, covering the main points of the paper.
+          \item Use appropriate equations, figures, and tables from the original paper.
+          \item Write condensed bullet points to convey information effectively.
+          \item Maintain a professional and scientifically rigorous tone throughout the presentation.
+          \item Use appropriate notation and terminology consistently.
+          \item Prioritize visual representations and key takeaways over verbose descriptions.
+          \item Include slide numbers for easy reference.
+          \item End with a conclusion slide summarizing the main findings and potential future work.
+      \end{enumerate}
+
+
+      {% if INSTRUCTION %}
+      Focus solely on the following specific instruction:
+      <instruction>
+      {{ INSTRUCTION }}
+      </instruction>
+      {% endif %}
+
+      Create a complete, self-contained LaTeX Beamer presentation that effectively communicates the paper's key findings in 10-15 slides. The presentation should be professional, condensed, and highlight the main aspects of the research paper. Use the following format:
+
+      <documents>
+      <document name="{{ OUTPUT_FILES[0] }}">
+      \documentclass{beamer}
+
+      \usetheme{metropolis}
+
+      \setbeamertemplate{navigation symbols}{}
+
+      \AtBeginSection[]
+      {
+      \begin{frame}<beamer>
+      \frametitle{Outline}
+      \tableofcontents[currentsection]
+      \end{frame}
+      }
+
+      \usepackage{amsmath}
+      \usepackage{amssymb}
+      \usepackage{graphicx}
+      \usepackage{physics}
+      \usepackage{hyperref}
+      \usepackage{natbib}
+
+      % Add any additional packages needed
+
+      % Title information
+      \title{...}
+      \author{...}
+      \institute{...}
+      \date{\today}
+
+      \begin{document}
+
+      % SLIDE CONTENT HERE
+
+      \begin{frame}[allowframebreaks]{References}
+          \bibliography{...}
+      \end{frame}
+
+      \end{document}
+      </document>
+      </documents>
+    - |
+      Critically review your draft and output a revised version. Check these aspects and fix any issues found:
+      \begin{enumerate}
+          \item Does the presentation effectively communicate the key findings and methodology?
+          \item Are the slides well-organized and logically structured?
+          \item Is the content appropriate for the target audience?
+          \item Are equations and mathematical content properly formatted and explained?
+          \item Are visual elements (figures, tables, diagrams) effectively used?
+          \item Is the text concise and focused, avoiding unnecessary details?
+          \item Are transitions between slides smooth and logical?
+          \item Is the overall presentation visually appealing and professional?
+      \end{enumerate}
+
+      Output the complete, self-contained revised version based on the previous version, maintaining its professional quality and technical accuracy. Use the following format:
+
+      <documents>
+      <document name="{{ OUTPUT_FILES[0] }}">
+      % Complete revised LaTeX Beamer presentation here
+      </document>
+      </documents>

package/dist/resources/agents/write/template_poster.tex

@@ -0,0 +1,56 @@
+\documentclass[final,a5paper]{beamer}
+\usepackage[orientation=portrait,size=a5,scale=1.4,debug]{beamerposter}
+
+\usetheme{confposter}
+\usecolortheme{mpi}
+
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{graphicx}
+\usepackage{physics}
+\usepackage{hyperref}
+\usepackage{soul}
+\usepackage[backend=bibtex,style=numeric,sorting=none]{biblatex}
+
+% Color definitions
+\definecolor{lightgray}{HTML}{faf9f8}
+\definecolor{blue}{HTML}{017e74}
+\definecolor{darkblue}{HTML}{28495d}
+
+% Font settings
+\usefonttheme{professionalfonts}
+\setbeamerfont{headline title}{size=\huge,series=\bfseries}
+\setbeamerfont{headline author}{size=\large}
+\setbeamerfont{headline institute}{size=\normalsize}
+\setbeamerfont{block title}{size=\large,series=\bfseries}
+\setbeamerfont{heading}{series=\bfseries}
+\setbeamerfont{caption}{size=\small}
+
+% Itemize settings
+\setbeamertemplate{itemize item}{\raise0.5ex \hbox{\vrule width 0.5ex height 0.5ex}}
+\setbeamertemplate{itemize subitem}{\raise0.3ex \hbox{\vrule width 0.5ex height 0.5ex}}
+\setbeamertemplate{itemize subsubitem}{\raise0.2ex \hbox{\vrule width 0.5ex height 0.5ex}}
+
+% Title and author information
+\title{Your Detailed Poster Title}
+\author{Authors of the Paper}
+\institute{Your Institution}
+
+\begin{document}
+
+\begin{frame}[t]
+    \begin{columns}[t]
+        \begin{column}{.48\linewidth}
+
+            % POSTER_CONTENT_LEFT
+
+        \end{column}
+        \begin{column}{.48\linewidth}
+
+            % POSTER_CONTENT_RIGHT
+
+        \end{column}
+    \end{columns}
+\end{frame}
+
+\end{document}

package/dist/resources/agents/write/template_slide.tex

@@ -0,0 +1,39 @@
+\documentclass{beamer}
+
+\usetheme{metropolis}
+
+\setbeamertemplate{navigation symbols}{}
+
+\AtBeginSection[]
+{
+\begin{frame}<beamer>
+\frametitle{Outline}
+\tableofcontents[currentsection]
+\end{frame}
+}
+
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{graphicx}
+\usepackage{physics}
+\usepackage{hyperref}
+\usepackage{natbib}
+
+% Include any other packages needed use \usepackage{...} 
+% Include any other external preamble in the paper using \input{...}
+
+% Title information
+\title{Title of the Presentation}
+\author{Authors of the Paper}
+\institute{Institution}
+\date{\today}
+
+\begin{document}
+
+% SLIDE_CONTENT
+
+\begin{frame}[allowframebreaks]{Reference}
+    \bibliography{the bib file used to generate the paper}
+\end{frame}
+
+\end{document}

package/dist/resources/docs/agent-creation/execution_and_testing.md

@@ -0,0 +1,79 @@
+# Execution & Testing Model
+
+This note explains how TeXRA runs agents, and — more importantly — how the
+`creator` agent can test a new agent before handing it back to the user.
+
+## How TeXRA runs agents
+
+Every agent run flows through one entry point: `texra.execute` command →
+`executeAgent(config, executionId?, options?)`. The runtime takes an
+`AgentConfig` (agent name, model, instruction, and optional input / memory /
+working-directory fields), resolves the YAML, and dispatches one of two
+flow shapes:
+
+- **Workflow flow** for `agentCategory: workflow`. Fixed rounds, each round
+  consumes `userRequest[i]`. Operates on `inputFiles` (or the active editor
+  selection). Emits LaTeX output files per `documentTag` /
+  `defaultOutputFiles`.
+- **Tool-use flow** for `agentCategory: toolUse`. Multi-step loop invoking
+  declared tools. May WAIT for interim follow-ups, spawn subagents via
+  `delegate_workflow` / `delegate_agent`, and resume.
+
+The creator agent does NOT need to call `executeAgent` directly. Instead it
+delegates through tools that handle everything (including approval and the
+follow-up queue) the way an ordinary user would.
+
+## Testing a new agent
+
+Use the `delegate_*` tools in the `tools:` list of `creator.yaml`.
+
+### Testing a workflow agent
+
+1. Make a small test input in the workspace. Example:
+   ```
+   bash: mkdir -p test_inputs
+   write_file test_inputs/sample.tex with a 5–10 line LaTeX snippet
+   ```
+2. Call `delegate_workflow`:
+   ```
+   delegate_workflow(
+     agent: "my_new_polish",
+     model: "<a configured workflow model>",
+     instruction: "Tighten the abstract",
+     inputFiles: ["./test_inputs/sample.tex"]
+   )
+   ```
+3. When the follow-up arrives:
+   - Inspect the output file(s) the subagent produced.
+   - Confirm the agent wrapped output correctly and produced non-empty LaTeX
+     content.
+   - Report pass/fail to the user.
+
+### Testing a tool-use agent
+
+1. Call `delegate_agent`:
+   ```
+   delegate_agent(
+     agent: "my_new_tool_agent",
+     model: "<a configured tool-use model>",
+     instruction: "Do X (small end-to-end smoke test)"
+   )
+   ```
+2. When the subagent hits WAITING (or finishes), read the output and decide
+   whether the agent did what it was supposed to.
+3. If more iteration is needed, pass the returned `execution_id` back to
+   `delegate_agent` with a follow-up `instruction` — this resumes the same
+   session with full context.
+
+## When testing is not possible
+
+Skip testing only if the user explicitly asks you to, or if the design
+depends on live resources that are not available in the current workspace
+(e.g. a real arXiv query that would burn API quota). In that case, state
+plainly in the hand-off message that the agent has not been exercised.
+
+## Iterating
+
+If a test fails — invalid YAML, missing tool, unclear prompt, wrong output
+structure — use `edit_file` on the custom YAML and re-run the delegation
+call. Both delegation tools pick up the updated file on the next invocation.

package/dist/resources/docs/agent-creation/tool_catalog.md

@@ -0,0 +1,127 @@
+# Tool Catalog for Tool-Use Agents
+
+Every tool available to tool-use agents, organised by group. When designing a
+new agent, pick the smallest set of tools that covers its purpose — the
+recommended groups at the bottom are a good starting point.
+
+## File operations
+
+- `bash` — execute shell commands in the workspace directory. Use for
+  scripts, compilation, git, and anything else that needs a shell.
+- `read_file` — read workspace files. Supports text files (with optional
+  line ranges), PDFs, and images (as attachments for vision-capable models).
+- `write_file` — overwrite or create a workspace file. Writes under the
+  allowlisted agent directories go through the normal approval diff; writes
+  under read-only directories fail cleanly.
+- `edit_file` — exact string replacement in a file. More surgical than
+  `write_file` for targeted changes.
+- `ls` — list files and directories with optional glob filtering.
+- `glob` — find files matching glob patterns (e.g. `**/*.tex`). Returns
+  paths sorted by modification time.
+- `grep` — search file contents with regex. Supports content,
+  files-with-matches, and count output modes.
+
+## Web & search
+
+- `web_search` — search the web and return top results.
+- `web_fetch` — fetch a URL, convert HTML to Markdown, return cleaned text.
+
+## Academic research
+
+- `arxiv_search` — search arXiv. Supports `field="author"` for author
+  searches.
+- `arxiv_metadata` — fetch bibliographic metadata for an arXiv paper by ID.
+- `download_arxiv_source` — download an arXiv paper's source archive into
+  the workspace.
+- `crossref_search` — search Crossref works and return top matches.
+- `crossref_doi` — look up detailed metadata for a DOI.
+
+## LaTeX processing
+
+- `extract_figures` — list and resolve figure assets referenced in a LaTeX
+  document.
+- `extract_bib_entries` — collect BibTeX records for citations.
+- `extract_tikz_figures` — discover TikZ figures and optionally compile them
+  to PDF.
+- `texcount` — count words in LaTeX files.
+
+## Citation management
+
+- `zotero_search`, `zotero_add`, `zotero_export`, `zotero_collections` —
+  manage references with Zotero (requires Better BibTeX).
+
+## Computation
+
+- `wolfram` — execute Wolfram Language code. Sessions do NOT persist
+  between calls.
+
+## Agent delegation
+
+- `delegate_workflow` — delegate to a workflow agent for whole-document
+  operations. Pass `agent`, `model`, `instruction`, `inputFiles`. Returns
+  asynchronously via the follow-up queue.
+- `delegate_agent` — delegate to another tool-use agent. Pass `agent`,
+  `model`, and `instruction` for a fresh run, or `execution_id` +
+  `instruction` to resume a WAITING subagent.
+- `executions` — view execution history and manage running executions.
+- `accept_run_files` — accept output files from a completed execution.
+
+## Lean 4
+
+- `lean_diagnostics`, `lean_file`, `lean_project`, `lean_inspect`,
+  `lean_loogle` — Lean 4 proof assistant integration.
+
+## Utility
+
+- `memory` — manage persistent memory files for cross-session knowledge.
+- `todo_write` — track progress on complex tasks with structured checklists.
+- `plan` — record structured plans.
+- `diagnostics` — retrieve linter diagnostics for source files.
+
+## Recommended tool groups by use case
+
+Most agents should include the file-operations set as a baseline.
+
+**Research agent:**
+`bash, read_file, write_file, glob, grep, ls, web_search, web_fetch,
+arxiv_search, arxiv_metadata, download_arxiv_source, crossref_search,
+crossref_doi`
+
+**Code/editing agent:**
+`bash, read_file, write_file, edit_file, glob, grep, ls, diagnostics`
+
+**LaTeX analysis agent:**
+`bash, read_file, write_file, glob, grep, ls, extract_figures,
+extract_bib_entries, extract_tikz_figures, texcount`
+
+**Literature review agent:**
+`bash, read_file, write_file, glob, grep, ls, arxiv_search, arxiv_metadata,
+crossref_search, crossref_doi, web_search, zotero_search, zotero_add,
+zotero_export`
+
+**Orchestrator agent:**
+`bash, read_file, write_file, glob, grep, ls, delegate_workflow,
+delegate_agent, executions, accept_run_files, todo_write`
+
+**Computation agent:**
+`bash, read_file, write_file, glob, grep, ls, wolfram`
+
+**Lean 4 agent:**
+`bash, read_file, write_file, edit_file, glob, grep, ls, lean_diagnostics,
+lean_file, lean_project, lean_inspect, lean_loogle`
+
+**Minimal chat agent:**
+`bash, read_file, write_file, glob, grep, ls`
+
+## System prompt best practices
+
+- Start with a clear role: "You are a [role]. Your task is to [objective]."
+- Give tool usage guidance tailored to the agent's purpose.
+- Structure complex workflows as numbered steps.
+- Mention tool limitations (e.g. wolfram sessions don't persist; bash cwd is
+  the workspace).
+- For agents with many tools, organise guidance by phase (discovery →
+  analysis → output).
+- Keep prompts focused — describe only what this specific agent needs.
+- Use `todo_write` for agents with multi-step verification or audit
+  workflows.

package/dist/resources/docs/agent-creation/tooluse_schema.md

@@ -0,0 +1,90 @@
+# Tool-Use Agent Schema & Reference
+
+Tool-use agents are interactive, multi-turn conversational agents with tool
+calling. They access files ONLY through their declared tools (`read_file`,
+`write_file`, `bash`, `grep`, etc.) — no pre-loaded content. The only
+template variable they receive is `{{ INSTRUCTION }}`.
+
+## YAML structure
+
+```yaml
+name: agent_name
+description: One-line description.
+
+settings:
+  agentCategory: toolUse
+  temperature: 0.7 # 0.3-0.5 for precise tasks, 0.7-0.8 for creative
+  tools:
+    - bash
+    - read_file
+    - write_file
+    - glob
+    - grep
+    - ls
+
+prompts:
+  systemPrompt: |
+    [Role, behaviour, tool usage guidance]
+  userRequest: |
+    {{ INSTRUCTION }}
+```
+
+## Critical rules
+
+- `agentCategory` MUST be `"toolUse"` (not `"workflow"`).
+- `userRequest` MUST be a single string (not an array) and MUST contain
+  `{{ INSTRUCTION }}`.
+- Do NOT use `userPrefix` — tool-use agents do not receive pre-loaded file
+  content.
+- The ONLY template variable is `{{ INSTRUCTION }}`. Do not use any
+  workflow-only variables (`INPUT_FILE`, `INPUT_CONTENT`, `ALL_INPUTS`,
+  `ALL_CONTEXTS`, `INPUT_FILES`, `OUTPUT_FILES`).
+- `{% if IS_ANTHROPIC_MODEL %}...{% endif %}` works for model-specific
+  instructions.
+- Agent names: lowercase with underscores or dashes.
+
+## Choosing tools
+
+Pick only the tools the agent needs. See `tool_catalog.md` in this directory
+for the full registry and recommended tool groups by use case. Most agents
+want at least `read_file`, `write_file`, `ls`, `glob`, and `grep`; add
+`bash` when the agent must run commands.
+
+## Example: the `research` agent
+
+```yaml
+name: research
+description: Searches academic literature and synthesises findings.
+
+settings:
+  agentCategory: toolUse
+  temperature: 0.7
+  tools:
+    - bash
+    - read_file
+    - write_file
+    - glob
+    - grep
+    - ls
+    - web_search
+    - web_fetch
+    - arxiv_search
+    - arxiv_metadata
+    - download_arxiv_source
+    - crossref_search
+    - crossref_doi
+
+prompts:
+  systemPrompt: |
+    You are a research assistant. Search academic literature, download
+    relevant papers, and synthesise findings for the user.
+
+    Use arxiv_search and crossref_search to find candidates.
+    Use arxiv_metadata and crossref_doi for detailed bibliographic data.
+    Use download_arxiv_source to fetch full paper sources.
+    Use web_search and web_fetch for broader context.
+    Use read_file and write_file to work with documents in the workspace.
+
+  userRequest: |
+    {{ INSTRUCTION }}
+```