Skip to content

armgit / storm

Public Imported from GitHub
0

An LLM-powered knowledge curation system that researches a topic and generates a full-length report with citations.

add class and function documentations

Yucheng-Jiang2a117d13d164
diff --git a/knowledge_storm/collaborative_storm/engine.py b/knowledge_storm/collaborative_storm/engine.py
index 8e50d21..2a68a3d 100644
--- a/knowledge_storm/collaborative_storm/engine.py
+++ b/knowledge_storm/collaborative_storm/engine.py
@@ -21,9 +21,9 @@ from ..rm import BingSearch
class 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 configurations
to achieve a balance between quality and efficiency. If no specific configuration is provided, we use the default
setup in the paper.
"""
@@ -292,6 +292,23 @@ class RunnerArgument:
@dataclass
class 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 = False
should_update_experts_list: bool = False
should_polish_utterance: bool = False
@@ -553,6 +570,14 @@ class CoStormRunner:
return costorm_runner
def 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.py
index 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 Information
class 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):
pass
diff --git a/knowledge_storm/collaborative_storm/modules/co_storm_agents.py b/knowledge_storm/collaborative_storm/modules/co_storm_agents.py
index 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.py
index 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 dspy
from typing import List, Union
diff --git a/knowledge_storm/collaborative_storm/modules/warmstart_hierarchical_chat.py b/knowledge_storm/collaborative_storm/modules/warmstart_hierarchical_chat.py
index 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 dspy
import concurrent.futures
from threading import Lock
diff --git a/knowledge_storm/dataclass.py b/knowledge_storm/dataclass.py
index 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.15232
Attributes:
- 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-processing
self.trim_empty_leaf_nodes()
self.merge_single_child_nodes()
diff --git a/knowledge_storm/interface.py b/knowledge_storm/interface.py
index 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, ConversationTurn
def __init__(self, topic: str, role_name: str, role_description: str):
diff --git a/knowledge_storm/rm.py b/knowledge_storm/rm.py
index 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.py
index 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).page
else: