An LLM-powered knowledge curation system that researches a topic and generates a full-length report with citations.
Python agentic-ragdeep-researchemnlp2024knowledge-curationlarge-language-modelsnaaclnlpreport-generationretrieval-augmented-generation
add class and function documentations
Yucheng-Jiang2a117d13d164
diff --git a/knowledge_storm/collaborative_storm/engine.py b/knowledge_storm/collaborative_storm/engine.pyindex 8e50d21..2a68a3d 100644--- a/knowledge_storm/collaborative_storm/engine.py+++ b/knowledge_storm/collaborative_storm/engine.py@@ -21,9 +21,9 @@ from ..rm import BingSearchclass CollaborativeStormLMConfigs(LMConfigs):- """Configurations for LLM used in different parts of STORM.+ """Configurations for LLM used in different parts of Co-STORM.- Given that different parts in STORM framework have different complexity, we use different LLM configurations+ Given that different parts in Co-STORM framework have different complexity, we use different LLM configurationsto achieve a balance between quality and efficiency. If no specific configuration is provided, we use the defaultsetup in the paper."""@@ -292,6 +292,23 @@ class RunnerArgument:@dataclassclass TurnPolicySpec:+ """+ Represents the policy specifications for determining the behavior of a conversation turn.++ Attributes:+ should_reorganize_knowledge_base (bool):+ A flag that indicates whether the knowledge base should be reorganized after the current turn.++ should_update_experts_list (bool):+ A flag that indicates whether the list of experts should be updated based on the conversation context.++ should_polish_utterance (bool):+ A flag that indicates whether the generated utterance should be polished (e.g., refined or rephrased) before it is used in the conversation.++ agent (Agent):+ The `Agent` responsible for generating utterances or responses during the conversation turn.+ This agent interacts with the knowledge base and the conversation history to produce responses.+ """should_reorganize_knowledge_base: bool = Falseshould_update_experts_list: bool = Falseshould_polish_utterance: bool = False@@ -553,6 +570,14 @@ class CoStormRunner:return costorm_runnerdef warm_start(self):+ """+ Warm start co-storm system to conduct background information search in order to build shared conceptual space with user.+ This stage is a mini-STORM, spawning multiple LLM agent with different perspective and perform multi-round conversation.+ The knowledge base (i.e. mind map) will be initialize using the collected information.++ It will also generate a first draft of report and use it to produce an engaging and concise conversation presented to the+ user to catch up with system's knowledge about the topic.+ """with self.logging_wrapper.log_pipeline_stage(pipeline_stage=f"warm start stage"):@@ -600,6 +625,13 @@ class CoStormRunner:)def generate_report(self) -> str:+ """+ Generate report leveraging organized collected information in the knowledge base (i.e. mind map).+ The article generation follows the paradigm in STORM paper, where it considers mind map nodes as section names, and generate the report section by section.++ Returns:+ str: A string representing the report, with "#" "##" indicating hierarchical sections and [1][2] indicating references.+ """with self.logging_wrapper.log_pipeline_stage("report generation stage"):with self.logging_wrapper.log_event("report generation stage: generate report"@@ -615,6 +647,35 @@ class CoStormRunner:simulate_user: bool = False,simulate_user_intent: str = "",) -> ConversationTurn:+ """+ Yields a single turn in the conversation flow.++ This method take a user input when user choose to inject an utterance or generates the next system utterance based on the current conversation history and defined discourse policies.+ It handles updating the conversation history, managing expert lists, and interacting with the knowledge base.+ Additionally, it logs each stage of the conversation for monitoring and debugging purposes.++ Args:+ user_utterance (str, optional): The input provided by the user. If provided, this utterance is added directly to the conversation history and returns with no further action.+ simulate_user (bool, optional): This is designed for automatic experiments using a LLM agent to simulate user actions. Flag indicating whether to simulate user behavior. When set to `True`, the system will generate user intents based on predefined simulation logic. Defaults to `False`.+ simulate_user_intent (str, optional): This is designed for automatic experiments using a LLM agent to simulate user actions. Specifies the intent to simulate for the user. This is used when `simulate_user` is `True` to guide the simulated user's responses,++ Returns:+ ConversationTurn: An object representing the latest turn in the conversation.++ Workflow:+ 1. User Utterance Handling+ - If `user_utterance` is provided, it is appended to the `conversation_history`++ 2. System Utterance Generation+ - If no `user_utterance` is provided, the method proceeds to generate the next system utterance.+ - Determines the next turn policy by consulting the `discourse_manager` with the current conversation history.+ - Generates a new utterance using the agent defined in the turn policy, leveraging the `knowledge_base` and `conversation_history`.+ - If the turn policy indicates that the experts list should be updated, it updates the expert list based on the latest utterances.++ 4. Knowledge Base Update+ - Inserts the new turn into the `knowledge_base`, optionally allowing the creation of new nodes or inserting under the root based on the `rag_only_baseline_mode` flag.+ - If the turn policy specifies, it reorganizes the `knowledge_base` to maintain optimal structure and relevance.+ """last_conv_turn = self.conversation_history[-1]cur_turn_name = f"conv turn: {len(self.conversation_history) + 1}"with self.logging_wrapper.log_pipeline_stage(diff --git a/knowledge_storm/collaborative_storm/modules/callback.py b/knowledge_storm/collaborative_storm/modules/callback.pyindex 339c7e3..9d61012 100644--- a/knowledge_storm/collaborative_storm/modules/callback.py+++ b/knowledge_storm/collaborative_storm/modules/callback.py@@ -3,7 +3,7 @@ from ...interface import Informationclass BaseCallbackHandler:- """Base callback handler to manage callbacks from the STORM pipeline."""+ """Base callback handler to manage callbacks from the Co-STORM pipeline."""def on_turn_policy_planning_start(self, **kwargs):"""Run when the turn policy planning begins, before deciding the direction or goal for the next conversation turn."""@@ -58,94 +58,7 @@ class BaseCallbackHandler:pass-class CoStormDemoCallBackHandler(BaseCallbackHandler):- from ...api import BackendAPI-- def __init__(self, backend_api: BackendAPI, conversation_id: int):- self.backend_api = backend_api- self.conversation_id = conversation_id-- def on_turn_policy_planning_start(self, **kwargs):- """Run when the turn policy planning begins, before deciding the direction or goal for the next conversation turn."""- # self.backend_api.update_conversation_status(- # self.conversation_id,- # "active",- # "Start planning next expert; inspect mind map; inspect system state.",- # )- # skip this part due to message sync latency in the frontend UI, which introduce more confusion.- pass-- def on_expert_action_planning_start(self, **kwargs):- """Run when the expert action planning begins, preparing to determine the actions that each expert should take."""- self.backend_api.update_conversation_status(- self.conversation_id,- "active",- "Reviewing discourse history; Deciding utterance intent.",- )-- def on_expert_information_collection_start(self, **kwargs):- """Run when the expert information collection ends, after gathering all necessary data from selected sources."""- self.backend_api.update_conversation_status(- self.conversation_id,- "active",- "Start searching and browsing collected information; drafting utterance",- )-- def on_expert_information_collection_end(self, info: List[Information], **kwargs):- """Run when the expert information collection ends, after gathering all necessary data from selected sources."""- if info:- urls = [i.url for i in info]- information_string = "\n".join([f"Finish browsing {url}" for url in urls])- self.backend_api.update_conversation_status(- self.conversation_id, "active", information_string- )-- def on_expert_utterance_generation_end(self, **kwargs):- """Run when the expert utterance generation ends, before creating responses or statements from each expert."""- self.backend_api.update_conversation_status(- self.conversation_id,- "active",- "Finish generating utterance from collected information.",- )-- def on_expert_utterance_polishing_start(self, **kwargs):- """Run when the expert utterance polishing begins, to refine and improve the clarity and coherence of generated content."""- self.backend_api.update_conversation_status(- self.conversation_id, "active", "Start polishing utterance."- )-- def on_mindmap_insert_start(self, **kwargs):- """Run when the process of inserting new information into the mindmap starts."""- self.backend_api.update_conversation_status(- self.conversation_id, "active", "Start inserting information into mind map."- )-- def on_mindmap_insert_end(self, **kwargs):- """Run when the process of inserting new information into the mindmap ends."""- self.backend_api.update_conversation_status(self.conversation_id, "active", "")-- def on_mindmap_reorg_start(self, **kwargs):- """Run when the reorganization of the mindmap begins, to restructure and optimize the flow of information."""- self.backend_api.update_conversation_status(- self.conversation_id, "active", "Start re-organizing mind map."- )-- def on_expert_list_update_start(self, **kwargs):- """Run when the expert list update starts, to modify or refresh the list of active experts."""- self.backend_api.update_conversation_status(- self.conversation_id, "active", "Start updating expert candidates."- )-- def on_warmstart_update(self, message, **kwargs):- """Run when the warm start process has update."""- self.backend_api.update_conversation_status(- self.conversation_id, "warmup", message- )--class LocalConsolePrintCallBackHandler(BaseCallbackHandler):- from ...api import BackendAPI-def __init__(self):passdiff --git a/knowledge_storm/collaborative_storm/modules/co_storm_agents.py b/knowledge_storm/collaborative_storm/modules/co_storm_agents.pyindex 045bb32..3fbe122 100644--- a/knowledge_storm/collaborative_storm/modules/co_storm_agents.py+++ b/knowledge_storm/collaborative_storm/modules/co_storm_agents.py@@ -22,6 +22,22 @@ if TYPE_CHECKING:class CoStormExpert(Agent):+ """+ Represents an expert agent in the Co-STORM framework.+ The `CoStormExpert` is a specialized type of `Agent` that is tasked with participating in roundtable discussions within the Co-STORM system.+ The expert uses language models to generate action plans, answer questions, and polish its utterances based on the current conversation history and knowledge base.+ It interacts with modules for action planning and question answering grounding on provided retrieval models.++ Args:+ topic (str): The conversation topic that the expert specializes in.+ role_name (str): The perspective of the expert's role (e.g. AI enthusiast, drug discovery expert, etc.)+ role_description (str): A description of the perspective of the experts+ lm_config (LMConfigs): Configuration for the language models+ runner_argument (RunnerArgument): Co-STORM runner argument+ logging_wrapper (LoggingWrapper): An instance of `LoggingWrapper` to log events.+ rm (Optional[dspy.Retrieve], optional): A retrieval module used for fetching external knowledge or context.+ callback_handler (BaseCallbackHandler, optional): Handles log message printing+ """def __init__(self,topic: str,@@ -91,6 +107,11 @@ class CoStormExpert(Agent):class SimulatedUser(Agent):+ """+ Simulated Users is a special type of Agent in Co-STORM that simulate real user interaction behavior or automatic experiments.++ For more information, please refer to Section 3.4 of Co-STORM paper: https://www.arxiv.org/pdf/2408.15232+ """def __init__(self,topic: str,@@ -133,6 +154,14 @@ class SimulatedUser(Agent):class Moderator(Agent):+ """+ The moderator's role in the Co-STORM framework is to inject new perspectives into the conversation to avoid stagnation, repetition, or overly niche discussions.+ This is achieved by generating questions based on unused, uncited snippets of information retrieved since the last moderator's turn.+ The selected information is reranked according to its relevance to the conversation topic and its dissimilarity to the original question.+ The resulting top-ranked snippets are used to generate an informed question to be presented to the conversation participants.++ For more information, please refer to Section 3.5 of Co-STORM paper: https://www.arxiv.org/pdf/2408.15232+ """def __init__(self,topic: str,@@ -285,6 +314,11 @@ class Moderator(Agent):class PureRAGAgent(Agent):+ """+ PureRAGAgent only handles grounded question generation by retrieving information from retriever based on the query.+ It does not utilize any other information besides query itself.+ It's designed for Co-STORM paper baseline comparison.+ """def __init__(self,topic: str,diff --git a/knowledge_storm/collaborative_storm/modules/grounded_question_generation.py b/knowledge_storm/collaborative_storm/modules/grounded_question_generation.pyindex f09339d..8f810d9 100644--- a/knowledge_storm/collaborative_storm/modules/grounded_question_generation.py+++ b/knowledge_storm/collaborative_storm/modules/grounded_question_generation.py@@ -1,3 +1,11 @@+"""+This module handles question generation within the Co-STORM framework, specifically designed to support the Moderator role.++The Moderator generates insightful, thought-provoking questions that introduce new directions into the conversation.+By leveraging uncited or unused snippets of information retrieved during the discussion, the Moderator ensures the conversation remains dynamic and avoids repetitive or overly niche topics.++For more detailed information, refer to Section 3.5 of the Co-STORM paper: https://www.arxiv.org/pdf/2408.15232.+"""import dspyfrom typing import List, Uniondiff --git a/knowledge_storm/collaborative_storm/modules/warmstart_hierarchical_chat.py b/knowledge_storm/collaborative_storm/modules/warmstart_hierarchical_chat.pyindex a6351aa..3357cbc 100644--- a/knowledge_storm/collaborative_storm/modules/warmstart_hierarchical_chat.py+++ b/knowledge_storm/collaborative_storm/modules/warmstart_hierarchical_chat.py@@ -1,3 +1,13 @@+"""+Warm starts the Co-STORM system by conducting a background information search to establish a shared conceptual space with the user.++This stage functions as a mini-STORM, where multiple LLM agents are spawned with different perspectives to engage in multi-round conversations.+The knowledge base (represented as a mind map) is initialized using the information gathered during these exchanges.++Additionally, the system generates a first draft of the report, which is then used to create a concise and engaging conversation.+The synthesized conversation is presented to the user to help them quickly catch up on the system's current knowledge about the topic.+"""+import dspyimport concurrent.futuresfrom threading import Lockdiff --git a/knowledge_storm/dataclass.py b/knowledge_storm/dataclass.pyindex 1ec1a8c..153b961 100644--- a/knowledge_storm/dataclass.py+++ b/knowledge_storm/dataclass.py@@ -290,10 +290,19 @@ class KnowledgeNode:class KnowledgeBase:"""- Class representing the knowledge base.+ Represents the dynamic, hierarchical mind map used in Co-STORM to track and organize discourse.+ The knowledge base serves as a shared conceptual space between the user and the system, allowing for effective collaboration by reducing the user's cognitive load and ensuring that the discourse is easy to follow.++ The knowledge base is structured as a tree (or mind map) that dynamically organizes collected information and concepts as the conversation progresses.++ The mind map consists of concepts (nodes) and edges that represent parent-child relationships among topics. Each concept is linked to retrieved information,+ which is placed under the most appropriate concept based on its associated question and semantic similarity.++ For more details, please refer to Section 3.2 of Co-STORM paper: https://www.arxiv.org/pdf/2408.15232Attributes:- root (KnowledgeNode): The root node of the knowledge base.+ root (KnowledgeNode): The root node of the hierarchical knowledge base, representing the top-level concept.+"""def __init__(@@ -817,6 +826,15 @@ class KnowledgeBase:return self.gen_summary_module(self)def reogranize(self):+ """+ Reorganizes the knowledge base through two main processes: top-down expansion and bottom-up cleaning.++ The reorganization process ensures that the knowledge base remains well-structured and relevant as new information is added. It consists of the following steps:+ 1.Top-Down Expansion: Expands nodes that have accumulated significant amounts of information by creating subtopics,+ ensuring that each concept remains specific and manageable.+ 2.Bottom-Up Cleaning: Cleans the knowledge base by removing empty leaf nodes (nodes with no supporting information)+ and merging nodes that have only a single child, simplifying the structure and maintaining clarity.+ """# pre-processingself.trim_empty_leaf_nodes()self.merge_single_child_nodes()diff --git a/knowledge_storm/interface.py b/knowledge_storm/interface.pyindex f50ebbe..f5727d5 100644--- a/knowledge_storm/interface.py+++ b/knowledge_storm/interface.py@@ -564,6 +564,27 @@ class Engine(ABC):class Agent(ABC):+ """+ Interface for STORM and Co-STORM LLM agent++ This class must be implemented by any subclass of `Agent` to define how the agent generates an utterance.+ The generated utterance can be influenced by the conversation history, knowledge base, and any additional parameters passed via `kwargs`.+ The implementation should align with the specific role and perspective of the agent, as defined by the agent's topic, role name, and role description.++ Args:+ knowledge_base (KnowledgeBase): The current knowledge base (e.g., mind map in Co-STORM) that contains the accumulated information relevant to the conversation.+ conversation_history (List[ConversationTurn]): A list of past conversation turns, providing context for generating the next utterance.+ The agent can refer to this history to maintain continuity and relevance in the conversation.+ logging_wrapper (LoggingWrapper): A wrapper used for logging important events during the utterance generation process.+ **kwargs: Additional arguments that can be passed to the method for more specialized utterance generation behavior depending on the agent's specific implementation.++ Returns:+ ConversationTurn: A new conversation turn generated by the agent, containing the agent's response, including the role, utterance type, and relevant information from the knowledge base.++ Notes:+ - Subclasses of `Agent` should define the exact strategy for generating the utterance, which could involve interacting with a language model, retrieving relevant knowledge, or following specific conversational policies.+ - The agent's role, perspective, and the knowledge base content will influence how the utterance is formulated.+ """from .dataclass import KnowledgeBase, ConversationTurndef __init__(self, topic: str, role_name: str, role_description: str):diff --git a/knowledge_storm/rm.py b/knowledge_storm/rm.pyindex d023d4a..c177b8f 100644--- a/knowledge_storm/rm.py+++ b/knowledge_storm/rm.py@@ -465,7 +465,7 @@ class SerperRM(dspy.Retrieve):if response == None:raise RuntimeError(- f"Error had occured while running the search process.\n Error is {response.reason}, had failed with status code {response.status_code}"+ f"Error had occurred while running the search process.\n Error is {response.reason}, had failed with status code {response.status_code}")return response.json()diff --git a/knowledge_storm/storm_wiki/modules/article_polish.py b/knowledge_storm/storm_wiki/modules/article_polish.pyindex 85c8daa..171054d 100644--- a/knowledge_storm/storm_wiki/modules/article_polish.py+++ b/knowledge_storm/storm_wiki/modules/article_polish.py@@ -85,6 +85,7 @@ class PolishPageModule(dspy.Module):self.polish_page = dspy.Predict(PolishPage)def forward(self, topic: str, draft_page: str, polish_whole_page: bool = True):+ # NOTE: Change show_guidelines to false to make the generation more robust to different LM families.with dspy.settings.context(lm=self.write_lead_engine, show_guidelines=False):lead_section = self.write_lead(topic=topic, draft_page=draft_page@@ -92,6 +93,7 @@ class PolishPageModule(dspy.Module):if "The lead section:" in lead_section:lead_section = lead_section.split("The lead section:")[1].strip()if polish_whole_page:+ # NOTE: Change show_guidelines to false to make the generation more robust to different LM families.with dspy.settings.context(lm=self.polish_engine, show_guidelines=False):page = self.polish_page(draft_page=draft_page).pageelse: