Input/Output Formats
Relevant source files
The following files were used as context for generating this wiki page:
The CoI-Agent (Chain-of-Ideas Agent) utilizes a structured communication protocol between its autonomous agents and external services. This system relies on specific string-based tagging for LLM responses, JSON-based storage for persistence, and environment-driven configurations to manage API interactions. These formats ensure that the DeepResearchAgent and ReviewAgent can parse complex scientific reasoning, iterative feedback, and experimental designs into actionable data structures.
The data flow primarily moves from raw search queries and PDF parsing into structured internal dictionaries, which are eventually persisted as JSON logs. The following sections detail the specific schemas and parsing logic used across the project.
Sources: agents.py:101-115, main.py:46-59, README.md:46-75
Persistent Data Structures
The system persists the results of its research chains, generated ideas, and experimental plans in JSON format. The primary output file, result.json, serves as the final consolidated export of the agent's work.
Consolidated Result Schema (result.json)
This structure represents the final output of the DeepResearchAgent's workflow.
| Field | Type | Description |
|---|---|---|
idea | string | The final refined research idea. |
experiment | string | The final improved experimental plan. |
related_experiments | list | Historical experiments extracted from literature. |
entities | string | Cleaned and merged scientific entities. |
idea_chain | string | A sequential list of papers and their core ideas. |
ideas | list | A list of all ideas generated during the chain process. |
trend | string | Summarized research evolution from early to late. |
future | string | Proposed future research directions. |
year | list | Publication years of the papers in the research chain. |
human | string | Analysis of human reasoning logic in the research chain. |
Sources: main.py:58-59, agents.py:165-171, dataset/case.json:1-125
Internal Logging Formats
During execution, the agents save intermediate states into several JSON files within the saves/ directory:
search_queries.json: Tracks the original query and the LLM-generated search queries.deep_research_chains.json: Stores the full context of a research path, including entities, trends, and years.review_experiment_suggestions.json: Captures the feedback provided by theReviewAgentfor refining designs.
Sources: agents.py:94-96, agents.py:136-138, agents.py:277-279
LLM Interaction Formats (XML-style Tagging)
The system uses a strict XML-style tagging convention within string responses to allow the extract() utility function to programmatically parse LLM outputs. This is used for search queries, relevance judgments, and idea extraction.
Core Parsing Logic
The extract function identifies content between specific start and end tags.
def get_content_between_a_b(start_tag, end_tag, text):
extracted_text = ""
start_index = text.find(start_tag)
while start_index != -1:
end_index = text.find(end_tag, start_index + len(start_tag))
if end_index != -1:
extracted_text += text[start_index + len(start_tag) : end_index] + " "
start_index = text.find(start_tag, end_index + len(end_tag))
return extracted_text.strip()
Sources: searcher/sementic_search.py:9-20, LLM.py:19-30
Common Prompt Tags
| Component | Required Tags | Source File |
|---|---|---|
| Search Queries | <queries>["q1", "q2"]</queries> | prompts/deep_research_agent_prompts.py:44 |
| Relevance | <relevant>0/1</relevant> | prompts/deep_research_agent_prompts.py:182 |
| Idea Extraction | <entities>, <idea>, <experiment>, <references> | prompts/deep_research_agent_prompts.py:126-129 |
| Idea Generation | <motivation>, <novelty>, <method> | prompts/deep_research_agent_prompts.py:326-328 |
| Novelty Check | <think>, <similar>, <summary>, <similar_paper_id> | prompts/deep_research_agent_prompts.py:382-385 |
Data Flow Diagram
The following diagram illustrates how raw input (topic) is transformed through various formats into the final research output.
The diagram shows the transition from user input through structured prompt-based extraction to final JSON persistence.
Sources: main.py:11-59, agents.py:101-165, searcher/sementic_search.py:110-155
External Service Formats
Configuration (config.yaml)
The project requires a YAML configuration file to set API keys and model preferences. These are loaded into environment variables at runtime.
SEMENTIC_SEARCH_API_KEY: ""
is_azure: True
AZURE_OPENAI_ENDPOINT: ""
MAIN_LLM_MODEL: "gpt-4o"
CHEAP_LLM_MODEL: "gpt-4o-mini"
Sources: README.md:55-75, main.py:12-18
Semantic Search API Fields
When querying the Semantic Scholar API, the SementicSearcher requests a specific list of fields to build the Result objects.
| Field Name | Usage |
|---|---|
paperId | Unique identifier for citation/reference tracking. |
openAccessPdf | URL for downloading the full text. |
citationCount | Used for ranking and "importance" filtering. |
citations / references | Used to build the research chain (forward/backward search). |
Sources: searcher/sementic_search.py:64-70, searcher/sementic_search.py:204-208
Conclusion
The CoI-Agent's Input/Output formats are designed to bridge the gap between unstructured scientific literature and structured autonomous reasoning. By using XML-style tagging within LLM prompts, the system creates a reliable interface for data extraction, while the multi-stage JSON logging provides a transparent audit trail of the agent's "Chain of Ideas" development process.
Sources: agents.py:246-279, main.py:53-59