CLI Reference (main.py)

Relevant source files

The following files were used as context for generating this wiki page:

• main.py
• agents.py
• LLM.py
• README.md
• searcher/sementic_search.py

The main.py script serves as the primary entry point for the Chain-of-Ideas (CoI) Agent, providing a Command Line Interface (CLI) to automate the generation and refinement of novel research ideas. It orchestrates high-level agents to search scientific literature, construct "idea chains," and design experimental plans based on a user-provided research topic.

The execution flow involves initializing Large Language Model (LLM) clients, configuring environment variables from local YAML files, and coordinating the DeepResearchAgent and ReviewAgent to produce a final research proposal. The output is a structured JSON file containing the generated idea, its experimental design, and the supporting literature context.

Sources: main.py:1-60, README.md:68-71

Execution Architecture

The CLI is built using the argparse library to handle user inputs and asyncio to manage concurrent agent operations. It integrates with nest_asyncio to allow nested event loops, facilitating complex asynchronous calls between agents.

Core Workflow Logic

1. Configuration Loading: Reads config.yaml to set environment variables for API keys (Semantic Scholar, OpenAI/Azure) and model selections.
2. Agent Initialization: Instantiates ReviewAgent for feedback and DeepResearchAgent for core generation.
3. Idea Generation: Calls generate_idea_with_chain to perform literature search and synthesis.
4. Experiment Design: Generates an initial experimental plan and iteratively improves it based on review feedback.
5. Serialization: Saves all results, including entities and trends, to result.json.

Sources: main.py:12-23, main.py:44-53, agents.py:112-140

The diagram shows the sequential execution of the CLI, highlighting the iterative refinement loop for experimental designs.
Sources: main.py:44-58, agents.py:465-481

CLI Arguments and Configuration

The script accepts several parameters to control the depth and breadth of the literature research process.

Command Line Arguments

Argument	Type	Default	Description
--topic	str	"Using diffusion..."	The research topic to investigate.
--anchor_paper_path	str	None	Optional local path to a PDF to start the research chain.
--save_file	str	"saves/"	Directory for storing downloaded papers and logs.
--improve_cnt	int	1	Number of iterations for experimental refinement.
--max_chain_length	int	5	Maximum papers in a single research idea chain.
--min_chain_length	int	3	Minimum papers required for a valid chain.
--max_chain_numbers	int	1	Number of parallel chains to explore.

Sources: main.py:30-40

Environment and Config Requirements

The system expects a config.yaml file to define LLM providers and search API keys. If is_azure is set to True, it requires Azure-specific endpoints and keys; otherwise, it defaults to standard OpenAI configuration.

Sources: main.py:12-21, LLM.py:48-84, README.md:41-62

Data Flow and Integration

main.py coordinates the interaction between the semantic searcher and the LLM wrappers. The data flow originates from the user topic, passes through the Semantic Scholar API via SementicSearcher, and is processed by the agents into a finalized research schema.

This sequence illustrates how main.py triggers the agent logic which in turn manages external API calls and data extraction.
Sources: agents.py:155-190, searcher/sementic_search.py:176-185, main.py:49-51

Key Internal Components

• LLM Factory: The get_llms() function in agents.py is used by main.py to retrieve configured openai_llm instances for both "main" (high reasoning) and "cheap" (high volume) tasks.
  • Sources: agents.py:18-29, main.py:44
• Result Persistence: The script utilizes json.dump to ensure that even if the process is interrupted, internal logs (like deep_research_chains.json) and the final result.json are maintained.
  • Sources: main.py:59-60, agents.py:483-484
• Semantic Integration: The CLI relies on the SementicSearcher to handle PDF downloads, parsing via scipdf, and paper re-ranking using embeddings.
  • Sources: searcher/sementic_search.py:176-218, agents.py:133

Conclusion

The main.py module provides a robust entry point for the CoI Agent system, abstracting the complexities of multi-agent coordination and literature synthesis into a simple command-line interface. By leveraging configurable research parameters and an iterative refinement loop, it allows researchers to autonomously move from a high-level topic to a detailed, novel research idea and experimental plan.