How amirgroup-codes/astroagents works
1. What this repo is
- AstroAgents is a local Python CLI workflow for generating and refining scientific hypotheses from mass spectrometry data.
- The core architecture is not a web service or database app; it is a file-driven orchestration pipeline centered on AstroAgents.py.
2. Primary entrypoints
- AstroAgents.py is the main runtime entrypoint for the multi-agent reasoning loop.
- extract_text.py is a preprocessing utility that turns source PDFs into text/markdown context for the agent system.
- setup.py and requirements.txt define packaging and runtime dependencies.
3. Input layer
- The system consumes two main local inputs:
- a prompt file (prompt.txt) that likely defines the task framing and instructions,
- a paper context file (paper_context.txt in the repo; README describes a paper-context markdown file) built from literature.
- The README also implies the scientific input includes mass spectrometry data embedded in the prompt/context rather than coming from a live service.
4. Document ingestion boundary
- extract_text.py forms a separate preprocessing boundary: it ingests PDFs from a local papers/ directory and produces markdown/text in papers/md/.
- This keeps document parsing decoupled from the hypothesis-generation pipeline.
5. Multi-agent orchestration core
- The architecture described in the README has eight collaborating roles:
- Data Analyst
- Planner
- 3 Domain Scientists
- Accumulator
- Literature Reviewer
- Critic
- In diagram terms, AstroAgents.py is the controller that sequences these roles and passes intermediate artifacts between them.
6. Reasoning/data flow through agents
- The flow appears to be:
- interpret data,
- split work into segments,
- generate hypotheses in parallel or near-parallel across scientist agents,
- deduplicate and merge candidate hypotheses,
- retrieve supporting literature,
- critique and revise the hypothesis set.
- The Planner → Scientist agents → Accumulator path is the main hypothesis production chain.
- The Literature Reviewer + Critic form the refinement and validation path.
7. External service boundaries
- The system depends on LLM and retrieval APIs:
- Anthropic Claude
- Google Gemini
- Semantic Scholar
- These are explicitly surfaced as command-line API keys, so the architecture has clear outbound network dependencies for both generation and literature lookup.
8. Model abstraction
- The --llm_model switch in the README indicates the orchestration layer is designed to run against at least two model providers.
- That means the agent logic is probably provider-agnostic above the LLM adapter layer, with model selection handled by runtime configuration.
9. Iteration loop
- The repo is built around repeated refinement cycles, controlled by --iterations.
- The result folders show per-iteration artifacts such as:
- analysis
- planning instructions
- hypotheses 1/2/3
- accumulated hypothesis
- search analysis
- critic feedback
- This suggests a closed-loop architecture where each iteration feeds the next.
10. Persistence and observability
- The results_claude_sonnet/ and results_gemini_flash2/ directories are important architectural evidence: the pipeline persists intermediate reasoning products to the filesystem.
- This makes the local file system the main trace/log boundary for debugging, comparison, and reproducibility across model runs.
11. Comparison across models
- The presence of separate result sets for Claude and Gemini suggests the repo supports side-by-side evaluation of model behavior using the same workflow.
- That is useful for architecture diagrams because the LLM provider is a replaceable backend, while the orchestration and artifact formats stay consistent.
12. Packaging/runtime profile
- The dependency set points to a Python NLP/LLM stack: Anthropic SDK, Google GenAI, LangChain, requests, and PyMuPDF-based document conversion.
- There is no evidence of a long-running service, queue, or database; the architecture is best drawn as a single-user batch pipeline with external API calls and local artifact storage.
13. Best way to diagram it
- Model the system as three layers:
- Input preparation: PDFs → extracted paper context + prompt
- Agent orchestration: multi-agent iterative reasoning inside AstroAgents.py
- Output artifacts: per-iteration hypothesis and critique files under results_*
- Put the external APIs on the side as dependencies of the orchestration layer, not as internal subsystems.
Main entry points: AstroAgents.py AstroAgents.py · paper_context.txt Paper context · results_claude_sonnet Claude runs · results_gemini_flash2 Gemini runs
Components 17
Input prep
Local prompt and paper context used to frame a run.
- extract_text.py · Preprocesses local papers into text/markdown context for downstream reasoning.
extract_text.py - Prompt · Run instructions and task framing supplied as a local prompt file.
prompt.txt - Paper context · Compiled paper context consumed by the agent system.
paper_context.txt
Agent loop
Main multi-agent reasoning and iteration controller.
- AstroAgents.py · Main CLI runtime that coordinates the iterative multi-agent hypothesis workflow.
AstroAgents.py - Data analyst · Interprets the mass spectrometry data and extracts salient signals.
- Planner · Splits the problem into work segments and drafts instructions for scientists.
- Scientist 1 · First domain-science hypothesis generator.
- Scientist 2 · Second domain-science hypothesis generator.
- Scientist 3 · Third domain-science hypothesis generator.
- Accumulator · Deduplicates and merges candidate hypotheses into a combined set.
- Literature reviewer · Searches supporting literature and gathers evidence for candidate hypotheses.
- Critic · Challenges the accumulated hypotheses and produces revision feedback.
Run artifacts
Per-iteration filesystem traces for model runs.
- Claude runs · Persisted artifacts for Claude-based executions and iterations.
results_claude_sonnet - Gemini runs · Persisted artifacts for Gemini-based executions and iterations.
results_gemini_flash2
External services
Outbound model and literature dependencies.
- Anthropic Claude · Outbound model backend used through runtime configuration.
- Google Gemini · Alternative outbound model backend selected at runtime.
- Semantic Scholar · External search and retrieval dependency for evidence gathering.
Connections 21
- extract_text.py → Paper context: build context · Converts local papers into the paper-context artifact used by runs.
- Prompt → AstroAgents.py: frame run · Supplies task instructions and constraints to the orchestration loop.
- Paper context → AstroAgents.py: provide context · Feeds literature context into the reasoning pipeline.
- AstroAgents.py → Data analyst: start · Begins with interpretation of the input data.
- Data analyst → Planner: handoff · Passes analysis output into planning.
- Planner → Scientist 1: split work · Dispatches a segment to the first scientist agent.
- Planner → Scientist 2: split work · Dispatches a segment to the second scientist agent.
- Planner → Scientist 3: split work · Dispatches a segment to the third scientist agent.
- Scientist 1 → Accumulator: candidate 1 · Contributes one hypothesis stream for merging.
- Scientist 2 → Accumulator: candidate 2 · Contributes one hypothesis stream for merging.
- Scientist 3 → Accumulator: candidate 3 · Contributes one hypothesis stream for merging.
- Accumulator → Literature reviewer: review set · Sends merged hypotheses for literature support search.
- Literature reviewer → Semantic Scholar: search · Queries external literature sources for evidence.
- Literature reviewer → Critic: evidence pack · Provides search results and supporting analysis to critique.
- Critic → AstroAgents.py: revise · Feeds feedback back into the iterative controller.
- AstroAgents.py → Claude runs: persist · Writes Claude-run artifacts and iteration traces to disk.
- AstroAgents.py → Gemini runs: persist · Writes Gemini-run artifacts and iteration traces to disk.
- AstroAgents.py → Anthropic Claude: llm calls · Uses Anthropic Claude when selected by configuration.
- AstroAgents.py → Google Gemini: llm calls · Uses Google Gemini when selected by configuration.
- AstroAgents.py → Claude runs: trace loop · Stores analysis, planning, hypotheses, accumulation, search, and critique by iteration.
- AstroAgents.py → Gemini runs: trace loop · Stores analysis, planning, hypotheses, accumulation, search, and critique by iteration.