feat: support time series forecasting tool in agent

Author: zhongyu09

README.md

@@ -14,18 +14,19 @@ it provides chat agents and workflows that support natural language to SQL conve
 3. **Data Visualization**: Generate intuitive data visualizations (via plotly)
 4. **Data Catalog Management**: Automatically discovers and indexes database table structures, supports flexible catalog 
    storage backends, and easily maintains business explanations for tables and columns as well as optimizes Prompts.
-5. **Knowledge Base Integration**: Answer complex questions by combining catalog based knowledge retrival and external
-   knowledge base retrival (via MCP tools)
+5. **Time Series Forecasting**: Forecasting models deployed in-house that can be called as tools
 6. **Code Execution**: Execute Python code for data analysis and visualization
 7. **Interactive Problem-Solving**: Proactively ask users for more context when information is incomplete
 8. **Persistent Memory**: Conversation management and user characteristic memory based on LangGraph checkpointing
 9. **MCP Support**: Integration with MCP tools by configuration
-10. **Web UI Interface**: Provide 2 sample UI: simple and streaming web interfaces using Gradio and Streamlit, easy to
+10. **Knowledge Base Integration**: Answer complex questions by combining catalog based knowledge retrival and external
+   knowledge base retrival (via MCP tools)
+11. **Web UI Interface**: Provide 2 sample UI: simple and streaming web interfaces using Gradio and Streamlit, easy to
    integrate with other web applications
 
 ## Roadmap
 
-1. **Time Series Forecasting**: Forecasting models deployed in-house
+1. **Anomaly Detection Algorithm**: Time series anomaly detection
 2. **Root Cause Analysis Algorithm**: Multi-dimensional drill-down capabilities for anomaly investigation
 
 # Getting started
@@ -219,6 +220,7 @@ OpenChatBI supports sophisticated customization through prompt engineering and c
 - **Prompt Engineering Configuration**: Customize system prompts, business glossaries, and data warehouse introductions
 - **Data Catalog Management**: Configure table metadata, column descriptions, and SQL generation rules
 - **Business Rules**: Define table selection criteria and domain-specific SQL constraints
+- **Forecasting Service**: Configure the forecasting service url and prompt based on your own deployment 
 
 For detailed configuration options and examples, see the [Advanced Features](#advanced-features) section.
 
@@ -264,16 +266,21 @@ openchatbi/
 │   ├── constants.py            # Application constants
 │   ├── agent_graph.py          # Main LangGraph workflow
 │   ├── graph_state.py          # State definition for workflows
+│   ├── context_config.py       # Context management configuration
+│   ├── context_manager.py      # Context window and token management
+│   ├── text_segmenter.py       # Text segmentation utilities
 │   ├── utils.py                # Utility functions
 │   ├── catalog/                # Data catalog management
 │   │   ├── __init__.py         # Package initialization
 │   │   ├── catalog_loader.py   # Catalog loading logic
 │   │   ├── catalog_store.py    # Catalog storage interface
-│   │   ├── entry.py            # Catalog entry points
 │   │   ├── factory.py          # Catalog factory patterns
 │   │   ├── helper.py           # Catalog helper functions
+│   │   ├── retrival_helper.py  # Retrieval helper utilities
 │   │   ├── schema_retrival.py  # Schema retrieval logic
-│   │   └── token_service.py    # Token service integration
+│   │   ├── token_service.py    # Token service integration
+│   │   └── store/              # Catalog storage implementations
+│   │       └── file_system.py  # File system-based catalog storage
 │   ├── code/                   # Code execution framework
 │   │   ├── __init__.py         # Package initialization
 │   │   ├── executor_base.py    # Base executor interface
@@ -290,7 +297,8 @@ openchatbi/
 │   │   ├── system_prompt.py    # System prompt management
 │   │   ├── summary_prompt.md   # Summary conversation prompts
 │   │   ├── table_selection_prompt.md # Table selection prompts
-│   │   └── text2sql_prompt.md  # Text-to-SQL prompts
+│   │   ├── text2sql_prompt.md  # Text-to-SQL prompts
+│   │   └── sql_dialect/        # SQL dialect-specific prompts
 │   ├── text2sql/               # Text-to-SQL conversion pipeline
 │   │   ├── __init__.py         # Package initialization
 │   │   ├── data.py             # Data and retriever for Text-to-SQL
@@ -306,7 +314,8 @@ openchatbi/
 │       ├── mcp_tools.py        # MCP (Model Context Protocol) integration
 │       ├── run_python_code.py  # Configurable Python code execution
 │       ├── save_report.py      # Report saving functionality
-│       └── search_knowledge.py # Knowledge base search
+│       ├── search_knowledge.py # Knowledge base search
+│       └── timeseries_forecast.py # Time series forecasting tool
 ├── sample_api/                 # API implementations
 │   └── async_api.py            # Asynchronous FastAPI example
 ├── sample_ui/                  # Web interface implementations
@@ -325,6 +334,9 @@ openchatbi/
 │   ├── sql_example.yaml        # SQL examples for retrieval
 │   ├── table_selection_example.csv # Table selection examples
 │   └── tracking_orders.sqlite  # Sample SQLite database
+├── timeseries_forecasting/     # Time series forecasting service
+│   ├── README.md               # Forecasting service documentation
+│   └── ...                     # Forecasting service implementation
 ├── tests/                      # Test suite
 │   ├── __init__.py             # Package initialization
 │   ├── conftest.py             # Test configuration
@@ -489,6 +501,9 @@ The file system catalog store organizes metadata across multiple files for maint
          ORDER BY date;
   ```
 
+### Time Series Forecasting Service Setup
+1. Setup forecasting docker container, see [README](timeseries_forecasting/README.md)
+2. Config the `timeseries_forecast` tool prompt 
 
 ### Python Code Execution Configuration
 
@@ -535,7 +550,6 @@ For production deployments or when running untrusted code, the Docker executor p
 - Automatic container cleanup
 - Resource isolation from host system
 
-
 ## Development & Testing
 
 ### Code Quality Tools

docs/source/conf.py

@@ -13,7 +13,7 @@
 project = "OpenChatBI"
 copyright = "2025, Yu Zhong"
 author = "Yu Zhong"
-release = "0.1.0"
+release = "0.2.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/index.rst

@@ -24,6 +24,7 @@ OpenChatBI Documentation
    Code Execution <code>
    LLM Integration <llm>
    Tools and Utilities <tools>
+   Time Series Forecasting Service <timeseries>
 
 Indices and tables
 ==================

docs/source/timeseries.rst

@@ -0,0 +1,7 @@
+Time Series Forecasting Service
+========================
+
+`GitHub Repository <https://github.com/zhongyu09/openchatbi/timeseries_forecasting>`_
+
+.. include:: ../../timeseries_forecasting/README.md
+   :parser: myst_parser.sphinx_

example/bi.yaml

@@ -1,5 +1,6 @@
-extra_tool_use_rule: | 
+extra_tool_use_rule: |
   - Try your best to give appropriate parameters when calling tools.
+  - timeseries_forecast tool requires at least 96 time points in input data. If no enough input data, set input_len to 96 to pad with zeros.
 
 table_selection_extra_rule: |
   - When users ask about orders, consider if they need customer information (join with Customers table)

openchatbi/__init__.py

@@ -26,6 +26,7 @@ def get_default_graph():
         return None
 
     from langgraph.checkpoint.memory import MemorySaver
+
     from openchatbi.agent_graph import build_agent_graph_sync
     from openchatbi.tool.memory import get_sync_memory_store
 

openchatbi/agent_graph.py

@@ -7,7 +7,7 @@
 from typing import Any
 
 from langchain_core.language_models import BaseChatModel
-from langchain_core.messages import AIMessage, SystemMessage, HumanMessage
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
 from langchain_core.tools import StructuredTool
 from langchain_openai.chat_models.base import BaseChatOpenAI
 from langgraph.constants import START
@@ -34,8 +34,8 @@
 from openchatbi.tool.run_python_code import run_python_code
 from openchatbi.tool.save_report import save_report
 from openchatbi.tool.search_knowledge import search_knowledge, show_schema
-from openchatbi.utils import log
-from openchatbi.utils import recover_incomplete_tool_calls
+from openchatbi.tool.timeseries_forecast import check_forecast_service_health, timeseries_forecast
+from openchatbi.utils import log, recover_incomplete_tool_calls
 
 logger = logging.getLogger(__name__)
 
@@ -313,7 +313,12 @@ def _build_graph_core(
         manage_memory_tool,
         search_memory_tool,
         save_report,
-    ] + mcp_tools
+    ]
+    if check_forecast_service_health:
+        normal_tools.append(timeseries_forecast)
+    else:
+        logger.warning("Time series forecasting service is not healthy. Skipping timeseries_forecast tool.")
+    normal_tools.extend(mcp_tools)
 
     # Initialize context manager if enabled
     context_manager = None

openchatbi/catalog/retrival_helper.py

@@ -3,8 +3,8 @@
 from rank_bm25 import BM25Okapi
 
 from openchatbi.llm.llm import get_embedding_model
-from openchatbi.utils import log, create_vector_db
 from openchatbi.text_segmenter import _segmenter
+from openchatbi.utils import create_vector_db, log
 
 
 def get_columns_metadata(catalog):

openchatbi/catalog/schema_retrival.py

@@ -6,8 +6,8 @@
 import Levenshtein
 
 from openchatbi import config
-from openchatbi.text_segmenter import _segmenter
 from openchatbi.catalog.retrival_helper import build_column_tables_mapping, build_columns_retriever
+from openchatbi.text_segmenter import _segmenter
 from openchatbi.utils import log
 
 # Skip build during documentation build

openchatbi/code/docker_executor.py

@@ -1,16 +1,16 @@
-import docker
-import tempfile
 import os
-import subprocess
 import shutil
+import subprocess
+import tempfile
 from pathlib import Path
-from typing import Tuple
+
+import docker
 from docker.errors import ContainerError
 
 from openchatbi.code.executor_base import ExecutorBase
 
 
-def check_docker_status() -> Tuple[bool, str]:
+def check_docker_status() -> tuple[bool, str]:
     """
     Check Docker installation and status without initializing DockerExecutor.
 
@@ -118,7 +118,7 @@ def _ensure_image_exists(self):
             )
             print(f"Docker image '{self.image_name}' built successfully.")
 
-    def run_code(self, code: str) -> Tuple[bool, str]:
+    def run_code(self, code: str) -> tuple[bool, str]:
         """Execute Python code in a Docker container."""
         try:
             # Create a temporary file with the code