«`html
A Coding Guide to Build an Autonomous Agentic AI for Time Series Forecasting with Darts and Hugging Face
In this tutorial, we build an advanced agentic AI system that autonomously handles time series forecasting using the Darts library combined with a lightweight Hugging Face model for reasoning. We design the agent to operate in a perception–reasoning–action cycle, where it first analyzes patterns in the data, then selects an appropriate forecasting model, generates predictions, and finally explains and visualizes the results. By walking through this pipeline, we experience how agentic AI can bring together statistical modeling and natural language reasoning to make forecasting both accurate and interpretable.
Installation and Setup
We begin by installing and importing the essential libraries, including Darts for time series forecasting, Transformers for reasoning, and supporting packages like pandas, NumPy, and matplotlib. With these tools in place, we set up the foundation to build and run our autonomous forecasting agent.
!pip install darts transformers pandas matplotlib numpy -q
import pandas as pd import numpy as np from darts import TimeSeries from darts.models import ExponentialSmoothing, NaiveSeasonal, LinearRegressionModel from darts.metrics import mape, rmse from transformers import pipeline import matplotlib.pyplot as plt from datetime import datetime, timedelta
Defining the TimeSeriesAgent
We define a TimeSeriesAgent that thinks with a lightweight Hugging Face model and acts with a small portfolio of Darts models. The agent perceives patterns (trend, volatility, seasonality), reasons to choose the best model, then trains, forecasts, and validates. Finally, it explains the prediction in plain language and visualizes history versus forecast.
class TimeSeriesAgent:
"""Autonomous agent for time series analysis and forecasting"""
def __init__(self):
print("Initializing Agent Brain...")
self.llm = pipeline("text-generation", model="distilgpt2", max_length=150,
do_sample=True, temperature=0.7)
self.models = {
'exponential_smoothing': ExponentialSmoothing(),
'naive_seasonal': NaiveSeasonal(K=12),
'linear_regression': LinearRegressionModel(lags=12)
}
self.selected_model = None
self.forecast = None
Perception Phase
The agent perceives and analyzes the time series data, identifying key characteristics such as trend, volatility, and seasonality.
def perceive(self, data):
"""Agent perceives and analyzes the time series data"""
print("\nPERCEPTION PHASE")
self.ts = TimeSeries.from_dataframe(data, 'date', 'value', freq='M')
trend = "increasing" if data['value'].iloc[-1] > data['value'].iloc[0] else "decreasing"
volatility = data['value'].std() / data['value'].mean()
seasonality = self._detect_seasonality(data['value'])
analysis = {
'length': len(data),
'trend': trend,
'volatility': f"{volatility:.2f}",
'has_seasonality': seasonality,
'mean': f"{data['value'].mean():.2f}",
'range': f"{data['value'].min():.2f} to {data['value'].max():.2f}"
}
Reasoning Phase
In this phase, the agent reasons about which model to use based on the analysis of the data.
def reason(self, analysis):
"""Agent reasons about which model to use"""
print("\nREASONING PHASE")
prompt = f"Time series analysis: {analysis['length']} data points, {analysis['trend']} trend, " \
f"volatility {analysis['volatility']}, seasonality: {analysis['has_seasonality']}. "
thought = self.llm(prompt, max_length=100, num_return_sequences=1)[0]['generated_text']
print(f"Agent Thinking: {thought[:150]}...")
if analysis['has_seasonality']:
self.selected_model = 'naive_seasonal'
reason = "Seasonality detected - using Naive Seasonal model"
elif float(analysis['volatility']) > 0.3:
self.selected_model = 'exponential_smoothing'
reason = "High volatility - using Exponential Smoothing"
else:
self.selected_model = 'linear_regression'
reason = "Stable trend - using Linear Regression"
print(f"Decision: {reason}")
return self.selected_model
Action Phase
In the action phase, the agent trains the selected model and generates forecasts.
def act(self, horizon=12):
"""Agent takes action: trains model and generates forecast"""
print("\nACTION PHASE")
train, val = self.ts[:-12], self.ts[-12:]
model = self.models[self.selected_model]
print(f"Training {self.selected_model}...")
model.fit(train)
self.forecast = model.predict(horizon)
if len(val) > 0:
val_pred = model.predict(len(val))
accuracy = 100 - mape(val, val_pred)
print(f"Validation Accuracy: {accuracy:.2f}%")
print(f"Generated {horizon}-step forecast")
return self.forecast
Explanation Phase
The agent explains its predictions in a clear and understandable manner.
def explain(self):
"""Agent explains its predictions"""
print("\nEXPLANATION PHASE")
forecast_values = self.forecast.values().flatten()
hist_values = self.ts.values().flatten()
change = ((forecast_values[-1] - hist_values[-1]) / hist_values[-1]) * 100
direction = "increase" if change > 0 else "decrease"
explanation = f"Based on my analysis using {self.selected_model}, " \
f"I predict a {abs(change):.1f}% {direction} in the next period. " \
f"Forecast range: {forecast_values.min():.2f} to {forecast_values.max():.2f}. " \
f"Historical mean was {hist_values.mean():.2f}."
print(f"{explanation}")
prompt = f"Forecast summary: {explanation} Explain implications:"
summary = self.llm(prompt, max_length=120)[0]['generated_text']
print(f"\nAgent Summary: {summary[:200]}...")
return explanation
Visualization Phase
The agent creates a visualization of its work to enhance understanding.
def visualize(self):
"""Agent creates visualization of its work"""
print("\nGenerating visualization...")
plt.figure(figsize=(14, 6))
self.ts.plot(label='Historical Data', lw=2)
self.forecast.plot(label=f'Forecast ({self.selected_model})',
lw=2, linestyle='--')
plt.title('Agentic AI Time Series Forecast', fontsize=16, fontweight='bold')
plt.xlabel('Date', fontsize=12)
plt.ylabel('Value', fontsize=12)
plt.legend(loc='best', fontsize=11)
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()
Creating Sample Data
We create a helper function create_sample_data() that generates synthetic time series data with a clear trend, sinusoidal seasonality, and random noise. This allows us to simulate realistic monthly data from 2020 to 2023 for testing and demonstrating the agent’s forecasting workflow.
def create_sample_data():
"""Generate sample time series data"""
dates = pd.date_range(start='2020-01-01', periods=48, freq='M')
trend = np.linspace(100, 150, 48)
seasonality = 10 * np.sin(np.linspace(0, 4*np.pi, 48))
noise = np.random.normal(0, 3, 48)
values = trend + seasonality + noise
return pd.DataFrame({'date': dates, 'value': values})
Main Execution
We define the main function that runs the full agentic AI pipeline. We load synthetic time series data, let the TimeSeriesAgent perceive patterns, reason to select the best model, act by training and forecasting, explain the results, and finally visualize them. This completes the end-to-end autonomous perception, reasoning, and action cycle.
def main():
"""Main execution: Agent autonomously handles forecasting task"""
print("="*70)
print("AGENTIC AI TIME SERIES FORECASTING SYSTEM")
print("="*70)
print("\nLoading data...")
data = create_sample_data()
print(f"Loaded {len(data)} data points from 2020-01 to 2023-12")
agent = TimeSeriesAgent()
analysis = agent.perceive(data)
agent.reason(analysis)
agent.act(horizon=12)
agent.explain()
agent.visualize()
print("\n" + "="*70)
print("AGENT COMPLETED FORECASTING TASK SUCCESSFULLY")
print("="*70)
if __name__ == "__main__":
main()
Conclusion
In conclusion, we see how an autonomous agent can analyze time series data, reason about model selection, generate forecasts, and explain its predictions in natural language. By combining Darts with Hugging Face, we create a compact yet powerful framework that not only produces accurate forecasts but also clearly communicates insights. We complete the cycle with visualization, reinforcing how agentic AI makes forecasting more intuitive and interactive.
Feel free to check out our GitHub Page for Tutorials, Codes, and Notebooks. Also, feel free to follow us on Twitter and don’t forget to join our 100k+ ML SubReddit and Subscribe to our Newsletter. Wait! Are you on Telegram? Now you can join us on Telegram as well.
«`