# lessiyin/autoidea architecture

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

- Interactive diagram: https://gitdiagram.com/lessiyin/autoidea
- Repository: https://github.com/lessiyin/autoidea

## Overview

AutoIdea turns a research topic, optionally constrained by seed papers or ideas, into an evidence-grounded proposal through literature discovery, paper reading, claim and gap synthesis, idea generation and ranking, adversarial review, and feasibility assessment. Users initiate runs through the CLI or local web workbench; a LangGraph research agent coordinates specialized tools and agents. Workspace artifacts and completion checks preserve provenance. The README documents the workflow; sampled code confirms agent construction, tool registration, web run routing, and artifact auditing, but not every stage’s internal calls.

Main entry points: [`autoidea/autoidea.py`](https://github.com/lessiyin/autoidea/blob/main/autoidea/autoidea.py) (Research agent), [`autoidea/tools/artifact_writers.py`](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/artifact_writers.py) (Research artifacts), [`autoidea/cli/interactive.py`](https://github.com/lessiyin/autoidea/blob/main/autoidea/cli/interactive.py) (CLI and REPL), [`autoidea/web/runs.py`](https://github.com/lessiyin/autoidea/blob/main/autoidea/web/runs.py) (Run manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI and REPL<br/>[interactive.py]"]
  node_web["Web workbench<br/>[server.py]"]
  node_run_manager["Run manager<br/>[runs.py]"]
  node_progress["Progress display<br/>[display.py]"]
end

subgraph group_research["Research workflow"]
  node_literature["Literature discovery<br/>[scholar.py]"]
  node_paper_reading["Paper reading<br/>[paper_content.py]"]
  node_evidence["Evidence and claims<br/>[cite.py]"]
  node_synthesis["Gap synthesis<br/>[think.py]"]
  node_ideation["Idea generation<br/>[seed_ideas.py]"]
  node_tournament["Idea tournament<br/>[idea_tournament.py]"]
  node_review["Review and feasibility<br/>[think.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_research_agent["Research agent<br/>[autoidea.py]"]
  node_prompts["Agent prompts<br/>[prompts.py]"]
  node_model["Model provider<br/>[models.py]"]
  node_middleware["Agent middleware<br/>[ask_user.py]"]
  node_memory["Conversation memory<br/>[memory.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_workspace["Run state and outputs"]
  node_workspace_paths["Workspace paths<br/>[paths.py]"]
  node_artifacts["Research artifacts"]
  node_batching["File-backed batches<br/>[batch_tasks.py]"]
  node_audit["Artifact audit<br/>[artifact_audit.py]"]
  node_completion["Stage completion<br/>[stage_gate.py]"]
  node_pipeline_state["Pipeline state<br/>[pipeline_state.py]"]
  node_run_db[("Session checkpoints<br/>[sessions.py]")]
end

node_researcher(("Researcher"))

node_researcher -->|"starts run"| node_cli
node_researcher -->|"starts run"| node_web
node_cli -->|"invokes"| node_research_agent
node_web -->|"routes run requests"| node_run_manager
node_run_manager -->|"starts run"| node_research_agent
node_research_agent -->|"uses"| node_prompts
node_research_agent -.->|"configures"| node_model
node_research_agent -.->|"assembles"| node_middleware
node_research_agent -->|"registers tools"| node_literature
node_research_agent -->|"registers tools"| node_paper_reading
node_research_agent -->|"registers tools"| node_evidence
node_research_agent -->|"registers tools"| node_synthesis
node_research_agent -->|"registers tools"| node_ideation
node_research_agent -->|"registers tools"| node_tournament
node_research_agent -->|"delegates research"| node_review
node_literature -->|"selects papers"| node_paper_reading
node_paper_reading -->|"grounds claims"| node_evidence
node_evidence -->|"links claims to gaps"| node_synthesis
node_synthesis -->|"informs directions"| node_ideation
node_ideation -->|"ranks ideas"| node_tournament
node_tournament -->|"selects directions"| node_review
node_review -->|"produces proposal"| node_artifacts
node_research_agent -->|"uses validated writers"| node_artifacts
node_research_agent -->|"uses batches"| node_batching
node_artifacts -->|"audits workspace"| node_audit
node_audit -->|"checks artifacts"| node_completion
node_audit -->|"validates stages"| node_pipeline_state
node_run_manager -.->|"persists conversations"| node_run_db
node_cli -->|"renders output"| node_progress
node_research_agent -.->|"reads configuration"| node_settings
node_research_agent -.->|"uses memory"| node_memory
node_artifacts -.->|"writes workspace files"| node_workspace_paths

click node_cli "https://github.com/lessiyin/autoidea/blob/main/autoidea/cli/interactive.py"
click node_web "https://github.com/lessiyin/autoidea/blob/main/autoidea/web/server.py"
click node_run_manager "https://github.com/lessiyin/autoidea/blob/main/autoidea/web/runs.py"
click node_research_agent "https://github.com/lessiyin/autoidea/blob/main/autoidea/autoidea.py"
click node_prompts "https://github.com/lessiyin/autoidea/blob/main/autoidea/prompts.py"
click node_model "https://github.com/lessiyin/autoidea/blob/main/autoidea/llm/models.py"
click node_middleware "https://github.com/lessiyin/autoidea/blob/main/autoidea/middleware/ask_user.py"
click node_memory "https://github.com/lessiyin/autoidea/blob/main/autoidea/middleware/memory.py"
click node_settings "https://github.com/lessiyin/autoidea/blob/main/autoidea/config/settings.py"
click node_workspace_paths "https://github.com/lessiyin/autoidea/blob/main/autoidea/paths.py"
click node_literature "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/scholar.py"
click node_paper_reading "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/paper_content.py"
click node_evidence "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/cite.py"
click node_synthesis "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/think.py"
click node_ideation "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/seed_ideas.py"
click node_tournament "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/idea_tournament.py"
click node_review "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/think.py"
click node_artifacts "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/artifact_writers.py"
click node_batching "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/batch_tasks.py"
click node_audit "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/artifact_audit.py"
click node_completion "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/stage_gate.py"
click node_pipeline_state "https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/pipeline_state.py"
click node_run_db "https://github.com/lessiyin/autoidea/blob/main/autoidea/sessions.py"
click node_progress "https://github.com/lessiyin/autoidea/blob/main/autoidea/stream/display.py"

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_cli,node_web,node_run_manager,node_progress toneBlue
class node_literature,node_paper_reading,node_evidence,node_synthesis,node_ideation,node_tournament,node_review toneAmber
class node_research_agent,node_prompts,node_model,node_middleware,node_memory,node_settings toneMint
class node_workspace_paths,node_artifacts,node_batching,node_audit,node_completion,node_pipeline_state,node_run_db toneRose
class node_researcher toneIndigo
```

## Components

### User entry points

- [CLI and REPL](https://github.com/lessiyin/autoidea/blob/main/autoidea/cli/interactive.py): `autoidea/cli/interactive.py`
- [Web workbench](https://github.com/lessiyin/autoidea/blob/main/autoidea/web/server.py): `autoidea/web/server.py`
- [Run manager](https://github.com/lessiyin/autoidea/blob/main/autoidea/web/runs.py): `autoidea/web/runs.py`
- [Progress display](https://github.com/lessiyin/autoidea/blob/main/autoidea/stream/display.py): `autoidea/stream/display.py`

### Research workflow

- [Literature discovery](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/scholar.py): `autoidea/tools/scholar.py`
- [Paper reading](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/paper_content.py): `autoidea/tools/paper_content.py`
- [Evidence and claims](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/cite.py): `autoidea/tools/cite.py`
- [Gap synthesis](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/think.py): `autoidea/tools/think.py`
- [Idea generation](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/seed_ideas.py): `autoidea/tools/seed_ideas.py`
- [Idea tournament](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/idea_tournament.py): `autoidea/tools/idea_tournament.py`
- [Review and feasibility](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/think.py): `autoidea/tools/think.py`

### Agent runtime

- [Research agent](https://github.com/lessiyin/autoidea/blob/main/autoidea/autoidea.py): `autoidea/autoidea.py`
- [Agent prompts](https://github.com/lessiyin/autoidea/blob/main/autoidea/prompts.py): `autoidea/prompts.py`
- [Model provider](https://github.com/lessiyin/autoidea/blob/main/autoidea/llm/models.py): `autoidea/llm/models.py`
- [Agent middleware](https://github.com/lessiyin/autoidea/blob/main/autoidea/middleware/ask_user.py): `autoidea/middleware/ask_user.py`
- [Conversation memory](https://github.com/lessiyin/autoidea/blob/main/autoidea/middleware/memory.py): `autoidea/middleware/memory.py`
- [Runtime settings](https://github.com/lessiyin/autoidea/blob/main/autoidea/config/settings.py): `autoidea/config/settings.py`

### Run state and outputs

- [Workspace paths](https://github.com/lessiyin/autoidea/blob/main/autoidea/paths.py): `autoidea/paths.py`
- [Research artifacts](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/artifact_writers.py): `autoidea/tools/artifact_writers.py`
- [File-backed batches](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/batch_tasks.py): `autoidea/tools/batch_tasks.py`
- [Artifact audit](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/artifact_audit.py): `autoidea/tools/artifact_audit.py`
- [Stage completion](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/stage_gate.py): `autoidea/tools/stage_gate.py`
- [Pipeline state](https://github.com/lessiyin/autoidea/blob/main/autoidea/tools/pipeline_state.py): `autoidea/tools/pipeline_state.py`
- [Session checkpoints](https://github.com/lessiyin/autoidea/blob/main/autoidea/sessions.py): `autoidea/sessions.py`

### Other components

- **Researcher**

## Connections

- Researcher → CLI and REPL: starts run (evidence: `README.md`)
- Researcher → Web workbench: starts run (evidence: `README.md`)
- CLI and REPL → Research agent: invokes
- Web workbench → Run manager: routes run requests (evidence: `autoidea/web/server.py`)
- Run manager → Research agent: starts run (evidence: `autoidea/web/runs.py`)
- Research agent → Agent prompts: uses (evidence: `autoidea/autoidea.py`)
- Research agent → Model provider: configures (evidence: `autoidea/autoidea.py`)
- Research agent → Agent middleware: assembles (evidence: `autoidea/autoidea.py`)
- Research agent → Literature discovery: registers tools (evidence: `autoidea/autoidea.py`)
- Research agent → Paper reading: registers tools (evidence: `autoidea/autoidea.py`)
- Research agent → Evidence and claims: registers tools (evidence: `autoidea/autoidea.py`)
- Research agent → Gap synthesis: registers tools (evidence: `autoidea/autoidea.py`)
- Research agent → Idea generation: registers tools (evidence: `autoidea/autoidea.py`)
- Research agent → Idea tournament: registers tools (evidence: `autoidea/autoidea.py`)
- Research agent → Review and feasibility: delegates research (evidence: `README.md`)
- Literature discovery → Paper reading: selects papers (evidence: `README.md`)
- Paper reading → Evidence and claims: grounds claims (evidence: `README.md`)
- Evidence and claims → Gap synthesis: links claims to gaps (evidence: `README.md`)
- Gap synthesis → Idea generation: informs directions (evidence: `README.md`)
- Idea generation → Idea tournament: ranks ideas (evidence: `README.md`)
- Idea tournament → Review and feasibility: selects directions (evidence: `README.md`)
- Review and feasibility → Research artifacts: produces proposal (evidence: `README.md`)
- Research agent → Research artifacts: uses validated writers (evidence: `autoidea/autoidea.py`)
- Research agent → File-backed batches: uses batches (evidence: `README.md`)
- Research artifacts → Artifact audit: audits workspace (evidence: `autoidea/tools/artifact_audit.py`)
- Artifact audit → Stage completion: checks artifacts (evidence: `autoidea/tools/stage_gate.py`)
- Artifact audit → Pipeline state: validates stages (evidence: `autoidea/tools/pipeline_state.py`)
- Run manager → Session checkpoints: persists conversations
- CLI and REPL → Progress display: renders output (evidence: `autoidea/cli/interactive.py`)
- Research agent → Runtime settings: reads configuration
- Research agent → Conversation memory: uses memory
- Research artifacts → Workspace paths: writes workspace files (evidence: `autoidea/tools/artifact_writers.py`)
