Basics

Jamanota Energy Middleware

Jamanota Energy Middleware is a lightweight Python middleware for tracking energy consumption and CO₂ emissions of LLM-based agent systems in LangChain.

It integrates with agent frameworks to record token usage, estimated energy consumption, and environmental impact for every model call.

Overview

Modern AI systems, especially multi-agent LLM workflows, can involve complex chains of model calls. Understanding their computational cost and environmental impact is increasingly important.

Jamanota provides:

Transparent tracking of token usage
Energy estimation based on model size and compute assumptions
CO₂ emissions estimation using global carbon intensity

Key Features

Plug-and-play middleware for agent systems
Tracks input/output tokens, energy (J), and CO₂ (kg)
Supports nested agent calls via prompt tracking
Works with multi-agent architectures
Thread-safe and lightweight
Provides structured outputs via jamanota.middleware.EnergyDataPoint

Installation

pip install jamanota

Quick Example

Start tracking energy usage in your agent system in just a few lines:

from langchain.agents import create_agent
from langchain_ollama import ChatOllama

from jamanota.middleware import EnergyMiddleware

tracker = EnergyMiddleware()

# Attach to your agent
agent = create_agent(
    model=ChatOllama(model="qwen3.5:2b"),
    middleware=[tracker],
    name="MyAgent"
)

# Run your system
agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "What is the capital of Italy?"
        }
    ]
})

The energy middleware tracker will be called after all model calls, including nested ones, and will log token usage, energy, and CO₂ for each call.

Thereafter, each model call produces a jamanota.middleware.EnergyDataPoint containing:

Token usage (input/output)
Estimated energy consumption
Estimated CO₂ emissions
Model name and timestamp
Associated prompt ID and agent

Use Cases

Jamanota may be useful for:

🔬 Research on efficient AI systems
🌱 Measuring environmental impact of LLMs
🤖 Adaptive multi-agent systems based on real-time energy usage
🧪 Profiling experimental pipelines

Documentation

Detailed documentation is available at https://jamanota.readthedocs.io/en/latest/.

Contributing

Contributions are welcome! You can help by:

Reporting bugs via GitHub Issues
Suggesting new features
Improving documentation

Development Setup:

From the root directory, install the package in editable mode:

pip install -e .

Running Tutorials:

Before running examples:

Install Ollama
Download models:
- qwen3.5:2b
- qwen3.5:4b
Install dependencies:

pip install -r tutorials/requirements.txt

For detailed instructions regarding the installation process, please refer to the multi-agent tutorial documentation.

Example Scripts:

Run the multi-agent example:

python tutorials/sample_queries.py

Or, launch the dashboard:

streamlit run tutorials/streamlit_visualisation.py

Building the Documentation:

First, install documentation dependencies:

pip install sphinx sphinx-rtd-theme

Then, build the docs from the root directory:

make html

The built documentation will be available in the docs/build/html directory. You can open the index.html file in your browser to view it.

License

This project uses the MIT License