langchain-neuralwatt

LangChain integration for Neuralwatt — energy-aware AI inference. Drop-in replacement for ChatOpenAI that surfaces per-call energy and carbon metrics into LangChain's response_metadata.

Install

pip install langchain-neuralwatt

Quick start

from langchain_neuralwatt import ChatNeuralwatt

llm = ChatNeuralwatt(model="glm-5-fast")  # reads NEURALWATT_API_KEY from env
msg = llm.invoke("Summarize the second law of thermodynamics in one sentence.")

print(msg.content)
print(msg.response_metadata["energy"])
# {'energy_joules': 1234.56, 'energy_kwh': 3.43e-07, 'carbon_g_co2eq': 0.00012, ...}

Note: Energy metadata is only present on non-streaming (invoke) responses. llm.stream() and agent loops that stream internally will not have an energy key in response_metadata.

Tracking energy across a chain

from langchain_neuralwatt import ChatNeuralwatt, NeuralwattEnergyCallback

cb = NeuralwattEnergyCallback()
llm = ChatNeuralwatt(model="glm-5-fast")

llm.invoke("...", config={"callbacks": [cb]})
llm.invoke("...", config={"callbacks": [cb]})

print(cb.summary())
# {'calls': 2, 'energy_joules': 2450.0, 'energy_kwh': 6.8e-07, 'carbon_g_co2eq': 0.00024}

Configuration

All other ChatOpenAI params (temperature, max_tokens, tools, model_kwargs, …) work as expected — ChatNeuralwatt is a thin subclass of BaseChatOpenAI.

What lands in response_metadata

Neuralwatt attaches two top-level fields to non-streaming chat completion responses:

• energy — energy_joules, energy_kwh, avg_power_watts, duration_seconds, attribution_method, optional carbon_g_co2eq + grid metadata.
• cost — request_cost_usd, cache_savings_usd, allowance_remaining_usd.

Development

pip install -e ".[test,lint,typing]"
pytest tests/unit_tests           # offline
NEURALWATT_API_KEY=nw_... pytest tests/integration_tests  # live

This package implements the LangChain standard test suite via langchain-tests.

License

MIT