Plotting Tool

The plot_tools module demonstrates how to build downstream processing tools that visualize data extracted from Rossum annotations. This example shows a complete implementation that can serve as a template for building your own custom tools.

Overview

This example demonstrates:

Processing data retrieved via the Rossum API
Aggregating annotation data for visualization
Creating interactive and static charts
Building a reusable tool for the smolagents framework

The plotting tool acts as a downstream processor that takes aggregated data and creates visualizations. It can be used alongside the MCP server or independently with the Rossum SDK.

Quick Example

The plotting tool works as a downstream processor for data retrieved via the Rossum API:

import json
from rossum_api import SyncRossumAPIClient
from rossum_api.dtos import Token
from plot_tools import plot_data

# 1. Initialize Rossum client (same one used by MCP server)
client = SyncRossumAPIClient(
    base_url="https://api.elis.rossum.ai/v1",
    credentials=Token(token="your-api-token")
)

# 2. Fetch annotations using SDK methods
annotations = client.list_annotations(
    queue=12345,
    status='exported'
)

# 3. Aggregate data from annotations
service_revenue = {}
for ann_result in annotations['results']:
    annotation = client.retrieve_annotation(
        ann_result['id'],
        sideloads=['content']
    )
    # Process annotation content...
    for datapoint in annotation['content']:
        if datapoint['schema_id'] == 'service_category':
            category = datapoint['value']
            service_revenue[category] = service_revenue.get(category, 0)
        if datapoint['schema_id'] == 'total_amount':
            service_revenue[category] += float(datapoint['value'])

# 4. Visualize the aggregated data
result = plot_data(
    data_json=json.dumps(service_revenue),
    chart_type='bar',
    title='Revenue by Service Category',
    output_path='revenue.html'
)

print(f"Chart saved: {json.loads(result)['output_path']}")

Chart Types

The tool supports 6 chart types:

bar - Vertical bar charts
horizontal_bar - Horizontal bar charts (better for long labels)
line - Line charts (time series, trends)
pie - Pie charts (proportions)
scatter - Scatter plots (correlations)
heatmap - Heatmaps (2D matrix data)

Integration Pattern

This example demonstrates a common pattern for building tools that process Rossum data:

import json
from rossum_api import SyncRossumAPIClient
from rossum_api.dtos import Token
from plot_tools import plot_data

# Step 1: Initialize client
client = SyncRossumAPIClient(
    base_url="https://api.elis.rossum.ai/v1",
    credentials=Token(token="your-api-token")
)

# Step 2: Fetch data using SDK methods
annotations = client.list_annotations(queue=12345, status='exported')

# Step 3: Process/aggregate the retrieved data
category_totals = {}
for ann_result in annotations['results']:
    annotation = client.retrieve_annotation(
        ann_result['id'],
        sideloads=['content']
    )
    # Extract line items from annotation content
    for datapoint in annotation['content']:
        if datapoint['schema_id'] == 'line_items':
            for item in datapoint['children']:
                category = item.get('item_category', 'Unknown')
                amount = float(item.get('item_amount', 0))
                category_totals[category] = category_totals.get(category, 0) + amount

# Step 4: Visualize with the plotting tool
result = plot_data(
    data_json=json.dumps(category_totals),
    chart_type='bar',
    title='Invoice Analysis',
    output_path='invoice_analysis.html'
)

This pattern can be adapted for other downstream processing:

Generating PDF reports
Exporting to Excel/CSV
Sending data to other systems (CRM, ERP, etc.)
Running statistical analysis
Building custom validation rules

Implementation Details

The plotting tool is implemented as a smolagents-compatible tool (@tool decorator), making it easy to integrate with AI agents that use the Rossum MCP Server.

File: examples/python/plot_tools.py

Key features:

Returns JSON-formatted results for easy parsing
Validates input data and provides clear error messages
Supports both interactive (Plotly) and static (Matplotlib) output
Smart defaults minimize required configuration

Running the Example

To try the plotting example:

cd examples/python
pip install -r requirements.txt
python quick_demo.py

This will generate sample charts demonstrating the various chart types and options.

API Reference

For detailed API documentation of the plot_data function, see:

For more information on the supported parameters, see examples/python/README_PLOTTING.md.