# amirgroup-codes/astroagents architecture

> Architecture diagram of the GitHub repository amirgroup-codes/astroagents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amirgroup-codes/astroagents
- Repository: https://github.com/amirgroup-codes/astroagents

## Overview

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`](https://github.com/amirgroup-codes/astroagents/blob/main/AstroAgents.py) (AstroAgents.py), [`paper_context.txt`](https://github.com/amirgroup-codes/astroagents/blob/main/paper_context.txt) (Paper context), [`results_claude_sonnet`](https://github.com/amirgroup-codes/astroagents/tree/main/results_claude_sonnet) (Claude runs), [`results_gemini_flash2`](https://github.com/amirgroup-codes/astroagents/tree/main/results_gemini_flash2) (Gemini runs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Input prep"]
  node_extract_text["extract_text.py<br/>ingest tool<br/>[extract_text.py]"]
  node_prompt["Prompt<br/>[prompt.txt]"]
  node_paper_context["Paper context<br/>literature context<br/>[paper_context.txt]"]
end

subgraph group_orchestration["Agent loop"]
  node_astroagents["AstroAgents.py<br/>orchestrator<br/>[AstroAgents.py]"]
  node_data_analyst(("Data analyst<br/>analysis agent"))
  node_planner(("Planner<br/>planning agent"))
  node_scientist_1(("Scientist 1<br/>hypothesis agent"))
  node_scientist_2(("Scientist 2<br/>hypothesis agent"))
  node_scientist_3(("Scientist 3<br/>hypothesis agent"))
  node_accumulator(("Accumulator<br/>merge agent"))
  node_literature_reviewer(("Literature reviewer<br/>retrieval agent"))
  node_critic(("Critic<br/>review agent"))
end

subgraph group_outputs["Run artifacts"]
  node_claude_results[("Claude runs<br/>results tree")]
  node_gemini_results[("Gemini runs<br/>results tree")]
end

subgraph group_external["External services"]
  node_anthropic{{"Anthropic Claude<br/>llm api"}}
  node_gemini{{"Google Gemini<br/>llm api"}}
  node_semantic_scholar{{"Semantic Scholar<br/>literature api"}}
end

node_extract_text -->|"build context"| node_paper_context
node_prompt -->|"frame run"| node_astroagents
node_paper_context -->|"provide context"| node_astroagents
node_astroagents -->|"start"| node_data_analyst
node_data_analyst -->|"handoff"| node_planner
node_planner -->|"split work"| node_scientist_1
node_planner -->|"split work"| node_scientist_2
node_planner -->|"split work"| node_scientist_3
node_scientist_1 -->|"candidate 1"| node_accumulator
node_scientist_2 -->|"candidate 2"| node_accumulator
node_scientist_3 -->|"candidate 3"| node_accumulator
node_accumulator -->|"review set"| node_literature_reviewer
node_literature_reviewer -->|"search"| node_semantic_scholar
node_literature_reviewer -->|"evidence pack"| node_critic
node_critic -->|"revise"| node_astroagents
node_astroagents -->|"persist"| node_claude_results
node_astroagents -->|"persist"| node_gemini_results
node_astroagents -->|"llm calls"| node_anthropic
node_astroagents -->|"llm calls"| node_gemini
node_astroagents -->|"trace loop"| node_claude_results
node_astroagents -->|"trace loop"| node_gemini_results

click node_astroagents "https://github.com/amirgroup-codes/astroagents/blob/main/AstroAgents.py"
click node_extract_text "https://github.com/amirgroup-codes/astroagents/blob/main/extract_text.py"
click node_prompt "https://github.com/amirgroup-codes/astroagents/blob/main/prompt.txt"
click node_paper_context "https://github.com/amirgroup-codes/astroagents/blob/main/paper_context.txt"
click node_claude_results "https://github.com/amirgroup-codes/astroagents/tree/main/results_claude_sonnet"
click node_gemini_results "https://github.com/amirgroup-codes/astroagents/tree/main/results_gemini_flash2"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extract_text,node_prompt,node_paper_context toneBlue
class node_astroagents,node_data_analyst,node_planner,node_scientist_1,node_scientist_2,node_scientist_3,node_accumulator,node_literature_reviewer,node_critic toneAmber
class node_claude_results,node_gemini_results toneMint
class node_anthropic,node_gemini,node_semantic_scholar toneRose
```

## Components

### Input prep

Local prompt and paper context used to frame a run.

- [extract_text.py](https://github.com/amirgroup-codes/astroagents/blob/main/extract_text.py): ingest tool · Preprocesses local papers into text/markdown context for downstream reasoning. · `extract_text.py`
- [Prompt](https://github.com/amirgroup-codes/astroagents/blob/main/prompt.txt): task prompt · Run instructions and task framing supplied as a local prompt file. · `prompt.txt`
- [Paper context](https://github.com/amirgroup-codes/astroagents/blob/main/paper_context.txt): literature context · Compiled paper context consumed by the agent system. · `paper_context.txt`

### Agent loop

Main multi-agent reasoning and iteration controller.

- [AstroAgents.py](https://github.com/amirgroup-codes/astroagents/blob/main/AstroAgents.py): orchestrator · Main CLI runtime that coordinates the iterative multi-agent hypothesis workflow. · `AstroAgents.py`
- **Data analyst**: analysis agent · Interprets the mass spectrometry data and extracts salient signals.
- **Planner**: planning agent · Splits the problem into work segments and drafts instructions for scientists.
- **Scientist 1**: hypothesis agent · First domain-science hypothesis generator.
- **Scientist 2**: hypothesis agent · Second domain-science hypothesis generator.
- **Scientist 3**: hypothesis agent · Third domain-science hypothesis generator.
- **Accumulator**: merge agent · Deduplicates and merges candidate hypotheses into a combined set.
- **Literature reviewer**: retrieval agent · Searches supporting literature and gathers evidence for candidate hypotheses.
- **Critic**: review agent · Challenges the accumulated hypotheses and produces revision feedback.

### Run artifacts

Per-iteration filesystem traces for model runs.

- [Claude runs](https://github.com/amirgroup-codes/astroagents/tree/main/results_claude_sonnet): results tree · Persisted artifacts for Claude-based executions and iterations. · `results_claude_sonnet`
- [Gemini runs](https://github.com/amirgroup-codes/astroagents/tree/main/results_gemini_flash2): results tree · Persisted artifacts for Gemini-based executions and iterations. · `results_gemini_flash2`

### External services

Outbound model and literature dependencies.

- **Anthropic Claude**: llm api · Outbound model backend used through runtime configuration.
- **Google Gemini**: llm api · Alternative outbound model backend selected at runtime.
- **Semantic Scholar**: literature api · External search and retrieval dependency for evidence gathering.

## Connections

- 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.