feature: introduce sqlite message store and human-in-the-loop planner

python/.env.example

@@ -22,11 +22,13 @@ API_HOST=localhost
 API_PORT=8000
 API_DEBUG=false
 
-
 # Database settings
 DB_CHARSET=utf8mb4
 DB_COLLATION=utf8mb4_unicode_ci
 
+# Agent Settings
+AGENT_DEBUG_MODE=false
+
 # SEC Agent Configuration
 # Email address for SEC API requests (required by SEC)
 SEC_EMAIL=your.name@example.com

python/configs/agent_cards/sec_agent.json

@@ -1,5 +1,86 @@
 {
     "name": "SecAgent",
     "url": "http://localhost:10003/",
+    "description": "SecAgent can analyze SEC filings like 10-Q, 10-K, 13-F and analyze stock holdings of institutional investment managers. It can chat about stock performance, financial metrics, and market trends or track specific stocks and provide updates.",
+    "skills": [
+        {
+            "id": "analyze_13f_filings",
+            "name": "Analyze 13F Filings",
+            "description": "Analyze 13F filings to extract stock holdings and provide insights on institutional investment managers' portfolios.",
+            "examples": [
+                "What are the top holdings of Berkshire Hathaway in the latest 13F filing?",
+                "How has the portfolio of Vanguard Group changed over the last four quarters?",
+                "Can you provide insights on the stock performance of Apple and Microsoft based on recent 13F filings?"
+            ],
+            "tags": ["13F", "stock holdings", "institutional investors"]
+        },
+        {
+            "id": "compare_quarterly_reports",
+            "name": "Compare Quarterly Financial Reports",
+            "description": "Compare and analyze quarterly financial reports (10-Q) across multiple periods to identify trends, performance changes, and key financial metrics evolution.",
+            "examples": [
+                "Compare Tesla's last three quarterly 10-Q reports",
+                "Analyze Apple's Q1 vs Q4 financial performance from their 10-Q filings",
+                "What are the key changes in Amazon's quarterly revenue and expenses over the past year?"
+            ],
+            "tags": ["10-Q", "quarterly reports", "financial analysis"]
+        },
+        {
+            "id": "summarize_annual_reports",
+            "name": "Summarize Annual Financial Reports",
+            "description": "Extract and summarize key information from annual 10-K reports, including business overview, risk factors, financial highlights, and strategic initiatives.",
+            "examples": [
+                "Help me summarize Nvidia's latest 10-K report",
+                "What are the main highlights from Microsoft's annual 10-K filing?",
+                "Provide a comprehensive summary of Meta's business segments from their 10-K report"
+            ],
+            "tags": ["10-K", "annual reports", "financial summary"]
+        },
+        {
+            "id": "compare_industry_performance",
+            "name": "Compare Industry Financial Performance",
+            "description": "Analyze and compare financial performance metrics across companies within the same industry sector, identifying competitive positioning and market leaders.",
+            "examples": [
+                "How does AMD's financial performance compare to Intel and Nvidia?",
+                "Compare the profitability metrics of JPMorgan, Bank of America, and Wells Fargo",
+                "Analyze the revenue growth rates of Netflix, Disney, and Warner Bros Discovery"
+            ],
+            "tags": ["industry comparison", "financial metrics", "competitive analysis"]
+        },
+        {
+            "id": "analyze_revenue_mix_evolution",
+            "name": "Analyze Revenue Mix Evolution",
+            "description": "Track and analyze changes in company revenue composition, business segment performance, and revenue diversification strategies over time.",
+            "examples": [
+                "How has Google's revenue mix changed over the past 3 years?",
+                "Analyze the evolution of Amazon's revenue streams from 2020 to 2023",
+                "What changes occurred in Apple's product revenue mix in the last 5 years?"
+            ],
+            "tags": ["revenue mix", "business segments", "financial evolution"]
+        },
+        {
+            "id": "assess_financial_health_metrics",
+            "name": "Assess Financial Health Metrics",
+            "description": "Evaluate company financial health through key metrics analysis including liquidity ratios, debt levels, profitability margins, and cash flow patterns.",
+            "examples": [
+                "Assess Tesla's current financial health based on their latest filings",
+                "What do the debt-to-equity ratios tell us about Boeing's financial stability?",
+                "Analyze the cash flow trends and liquidity position of General Electric"
+            ],
+            "tags": ["financial health", "liquidity", "debt analysis"]
+        },
+        {
+            "id": "identify_risk_factors",
+            "name": "Identify Financial Risk Factors",
+            "description": "Extract and analyze risk factors disclosed in SEC filings, categorize risks by type, and assess potential impact on business operations and financial performance.",
+            "examples": [
+                "What are the main risk factors disclosed in Uber's latest 10-K filing?",
+                "Analyze the regulatory risks mentioned in JPMorgan's annual report",
+                "Compare the risk disclosures between traditional automakers and EV companies"
+            ],
+            "tags": ["risk factors", "financial risk", "SEC filings"]
+        }
+    ],
+
     "enabled": true
 }

python/valuecell/core/__init__.py

@@ -4,8 +4,12 @@
     Message,
     Role,
     Session,
+    SessionStatus,
     SessionManager,
     SessionStore,
+    MessageStore,
+    InMemoryMessageStore,
+    SQLiteMessageStore,
 )
 
 # Task management
@@ -31,9 +35,13 @@
     "Message",
     "Role",
     "Session",
+    "SessionStatus",
     "SessionManager",
     "SessionStore",
     "InMemorySessionStore",
+    "MessageStore",
+    "InMemoryMessageStore",
+    "SQLiteMessageStore",
     # Task exports
     "Task",
     "TaskStatus",

python/valuecell/core/agent/decorator.py

@@ -150,19 +150,14 @@ def __init__(self, agent: BaseAgent):
         self.agent = agent
 
     async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
-        # Ensure agent implements streaming interface
-        if not hasattr(self.agent, "stream"):
-            raise NotImplementedError(
-                f"Agent {self.agent.__class__.__name__} must implement 'stream' method"
-            )
-
         # Prepare query and ensure a task exists in the system
         query = context.get_user_input()
         task = context.current_task
+        metadata = context.metadata
         if not task:
             message = context.message
             task = new_task(message)
-            task.metadata = message.metadata
+            task.metadata = metadata
             await event_queue.enqueue_event(task)
 
         # Helper state
@@ -186,7 +181,10 @@ async def _add_chunk(content: str, last: bool = False):
         # Stream from the user agent and update task incrementally
         await updater.update_status(TaskState.working)
         try:
-            async for item in self.agent.stream(query, task.context_id, task.id):
+            query_handler = (
+                self.agent.notify if metadata.get("notify") else self.agent.stream
+            )
+            async for item in query_handler(query, task.context_id, task.id):
                 content = item.get("content", "")
                 is_complete = item.get("is_task_complete", True)
 
@@ -195,6 +193,7 @@ async def _add_chunk(content: str, last: bool = False):
                 if is_complete:
                     await updater.complete()
                     break
+
         except Exception as e:
             message = (
                 f"Error during {self.agent.__class__.__name__} agent execution: {e}"

python/valuecell/core/coordinate/models.py

@@ -1,17 +1,70 @@
 from typing import List, Optional
-from pydantic import BaseModel, Field
 
+from pydantic import BaseModel, Field
 from valuecell.core.task import Task
+from valuecell.core.task.models import TaskPattern
 
 
 class ExecutionPlan(BaseModel):
-    """Execution plan containing multiple tasks"""
+    """
+    Execution plan containing multiple tasks for fulfilling a user request.
+
+    This model represents a structured plan that breaks down a user's request
+    into executable tasks that can be processed by different agents.
+    """
 
     plan_id: str = Field(..., description="Unique plan identifier")
     session_id: Optional[str] = Field(
         ..., description="Session ID this plan belongs to"
     )
     user_id: str = Field(..., description="User ID who requested this plan")
-    query: str = Field(..., description="Original user input")
+    query: str = Field(..., description="Original user query that generated this plan")
     tasks: List[Task] = Field(default_factory=list, description="Tasks to execute")
     created_at: str = Field(..., description="Plan creation timestamp")
+
+
+class _TaskBrief(BaseModel):
+    """
+    Represents a task to be executed by an agent.
+
+    This is a simplified task representation used during the planning phase
+    before being converted to a full Task object.
+    """
+
+    query: str = Field(..., description="The task to be performed")
+    agent_name: str = Field(..., description="Name of the agent executing this task")
+    pattern: TaskPattern = Field(
+        default=TaskPattern.ONCE, description="Task execution pattern"
+    )
+
+
+class PlannerInput(BaseModel):
+    """
+    Schema for planner input containing user query and metadata.
+
+    This schema is used by the planning agent to structure its input
+    when determining what tasks should be executed.
+    """
+
+    desired_agent_name: str = Field(
+        ..., description="The name of the agent the user wants to use for the task"
+    )
+    query: str = Field(
+        ..., description="The user's input or request which may need clarification"
+    )
+
+
+class PlannerResponse(BaseModel):
+    """
+    Schema for planner response containing tasks and planning metadata.
+
+    This schema is used by the planning agent to structure its response
+    when determining what tasks should be executed.
+    """
+
+    tasks: List[_TaskBrief] = Field(..., description="List of tasks to be executed")
+    adequate: bool = Field(
+        ...,
+        description="true if information is adequate for task execution, false if more input is needed",
+    )
+    reason: str = Field(..., description="Reason for the planning decision")