aitbc/docs/scenarios/18_analytics_collection.md

Analytics Collection for hermes Agents

Level: Beginner
Prerequisites: Blockchain Monitoring (Scenario 15), AITBC CLI installed
Estimated Time: 25 minutes
Last Updated: 2026-05-02
Version: 1.0

🧭 Navigation Path:

🏠 Documentation Home → 🎭 Agent Scenarios → You are here

breadcrumb: Home → Scenarios → Analytics Collection

---

🎯 See Also:

• 📖 Previous Scenario: 17 Governance Voting
• 📖 Next Scenario: 19 Security Setup
• 🤖 Agent SDK: Agent SDK Documentation
• 📊 Analytics: Analytics Service

---

📚 Scenario Overview

This scenario demonstrates how hermes agents collect and analyze analytics data from the AITBC network for insights and decision-making.

Use Case

An hermes agent needs analytics collection to:

• Track network performance
• Analyze transaction patterns
• Monitor market trends
• Generate reports
• Make data-driven decisions

What You'll Learn

• Collect blockchain analytics
• Query historical data
• Generate analytics reports
• Visualize analytics data
• Export analytics data

Features Combined

• Blockchain Monitoring (Scenario 15)
• Data Analysis: Historical data processing
• Reporting: Analytics visualization and export

---

📋 Prerequisites

Knowledge Required

• Completed Scenario 15 (Blockchain Monitoring)
• Understanding of data analysis
• Analytics concepts

Tools Required

• AITBC CLI installed
• Python 3.13+
• Access to analytics service
• Wallet for analytics operations

Setup Required

• Analytics service running
• Database for analytics storage
• Network connectivity

---

🔧 Step-by-Step Workflow

Step 1: Collect Blockchain Analytics

Gather analytics data from the blockchain.

aitbc analytics collect \
  --type blockchain \
  --timeframe 24h \
  --output analytics.json

Output:

Analytics collected
Type: blockchain
Timeframe: 24h
Records: 1,523
Output: analytics.json

Step 2: Query Transaction Analytics

Analyze transaction patterns.

aitbc analytics query \
  --type transactions \
  --filter "amount > 100" \
  --timeframe 7d

Output:

Transaction Analytics (7d):
Total Transactions: 5,234
Total Volume: 523,400 AIT
Average Amount: 100.0 AIT
Peak Hour: 14:00-15:00

Step 3: Generate Analytics Report

Create a comprehensive analytics report.

aitbc analytics report \
  --type comprehensive \
  --timeframe 30d \
  --output report.pdf

Step 4: Visualize Analytics Data

Generate visualizations for analytics data.

aitbc analytics visualize \
  --input analytics.json \
  --chart-type line \
  --metric transactions

Step 5: Export Analytics Data

Export analytics data for external analysis.

aitbc analytics export \
  --format csv \
  --output analytics_export.csv

---

💻 Code Examples Using Agent SDK

Example 1: Collect Analytics Programmatically

from aitbc_agent_sdk import Agent, AgentConfig

config = AgentConfig(
    name="analytics-agent",
    blockchain_network="mainnet"
)

agent = Agent(config)
agent.start()

# Collect blockchain analytics
analytics = agent.collect_analytics(
    analytics_type="blockchain",
    timeframe="24h"
)

print(f"Collected {len(analytics)} records")
print(f"Total transactions: {analytics['total_transactions']}")
print(f"Total volume: {analytics['total_volume']} AIT")

Example 2: Custom Analytics Queries

from aitbc_agent_sdk import Agent, AgentConfig
import asyncio

async def custom_analytics():
    config = AgentConfig(
        name="custom-analytics",
        blockchain_network="mainnet"
    )
    
    agent = Agent(config)
    await agent.start()
    
    # Query high-value transactions
    high_value = await agent.query_analytics(
        query_type="transactions",
        filters={"amount_min": 1000},
        timeframe="7d"
    )
    
    print(f"High-value transactions: {len(high_value)}")
    
    # Query peak activity hours
    peak_hours = await agent.query_analytics(
        query_type="activity",
        timeframe="30d"
    )
    
    print(f"Peak activity hour: {peak_hours['peak_hour']}")
    
    # Query network performance
    performance = await agent.query_analytics(
        query_type="performance",
        timeframe="24h"
    )
    
    print(f"Average block time: {performance['avg_block_time']}s")

asyncio.run(custom_analytics())

Example 3: Automated Analytics Dashboard

from aitbc_agent_sdk import Agent, AgentConfig
import asyncio
import json

class AnalyticsDashboard:
    def __init__(self, config):
        self.agent = Agent(config)
        self.historical_data = []
    
    async def start(self):
        await self.agent.start()
        await self.run_dashboard()
    
    async def run_dashboard(self):
        """Run continuous analytics collection"""
        while True:
            # Collect current analytics
            analytics = await self.agent.collect_analytics(
                analytics_type="comprehensive",
                timeframe="1h"
            )
            
            # Store historical data
            self.historical_data.append({
                "timestamp": asyncio.get_event_loop().time(),
                "data": analytics
            })
            
            # Keep only last 24 hours
            if len(self.historical_data) > 24:
                self.historical_data.pop(0)
            
            # Generate insights
            insights = await self.generate_insights()
            
            # Display dashboard
            self.display_dashboard(analytics, insights)
            
            await asyncio.sleep(3600)  # Update hourly
    
    async def generate_insights(self):
        """Generate insights from historical data"""
        if len(self.historical_data) < 2:
            return {}
        
        # Calculate trends
        current = self.historical_data[-1]['data']
        previous = self.historical_data[-2]['data']
        
        tx_change = current['total_transactions'] - previous['total_transactions']
        volume_change = current['total_volume'] - previous['total_volume']
        
        return {
            "transaction_trend": "increasing" if tx_change > 0 else "decreasing",
            "volume_trend": "increasing" if volume_change > 0 else "decreasing",
            "tx_change": tx_change,
            "volume_change": volume_change
        }
    
    def display_dashboard(self, analytics, insights):
        """Display analytics dashboard"""
        print("\n" + "=" * 60)
        print("AITBC ANALYTICS DASHBOARD")
        print("=" * 60)
        print(f"\nTransactions (1h): {analytics['total_transactions']}")
        print(f"Volume (1h): {analytics['total_volume']} AIT")
        print(f"Average Block Time: {analytics['avg_block_time']}s")
        print(f"Active Validators: {analytics['active_validators']}")
        
        if insights:
            print(f"\n--- Insights ---")
            print(f"Transaction Trend: {insights['transaction_trend']} ({insights['tx_change']:+})")
            print(f"Volume Trend: {insights['volume_trend']} ({insights['volume_change']:+})")
        
        print("=" * 60)

async def main():
    config = AgentConfig(
        name="analytics-dashboard",
        blockchain_network="mainnet"
    )
    
    dashboard = AnalyticsDashboard(config)
    await dashboard.start()

asyncio.run(main())

---

🎯 Expected Outcomes

After completing this scenario, you should be able to:

• Collect blockchain analytics
• Query historical data
• Generate analytics reports
• Visualize analytics data
• Build custom analytics dashboards

---

🧪 Validation

Validate this scenario with the shared 3-node harness:

bash scripts/workflow/44_comprehensive_multi_node_scenario.sh

Node coverage:

• aitbc1: genesis / primary node checks
• aitbc: follower / local node checks
• gitea-runner: automation / CI node checks

Validation guide:

• Scenario Validation Guide

Expected result:

• Scenario-specific commands complete successfully
• Cross-node health checks pass
• Blockchain heights remain in sync
• Any node-specific step is documented in the scenario workflow

---

🔗 Related Resources

AITBC Documentation

• Analytics Service
• Advanced Analytics
• Market Data Collector

External Resources

• Data Analytics
• Time Series Analysis

Next Scenarios

• 25 Marketplace Arbitrage - Analytics for trading
• 28 Monitoring Agent - Advanced monitoring
• 38 Cross Chain Market Maker - Analytics in trading

---

📊 Quality Metrics

• Structure: 10/10 - Clear analytics collection workflow
• Content: 10/10 - Comprehensive analytics operations
• Code Examples: 10/10 - Working Agent SDK examples
• Status: Active scenario

---

Last updated: 2026-05-02
Version: 1.0
Status: Active scenario document