Metadata-Version: 2.4
Name: langchain-neuralwatt
Version: 0.1.0
Summary: LangChain integration for Neuralwatt — energy-aware AI inference.
Project-URL: Homepage, https://neuralwatt.com
Project-URL: Repository, https://github.com/neuralwatt/inference_frontend
Project-URL: Documentation, https://docs.neuralwatt.com
Author-email: Neuralwatt <support@neuralwatt.com>
License: MIT
Keywords: carbon,energy,langchain,llm,neuralwatt,sustainability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: langchain-core<2.0,>=0.3
Requires-Dist: langchain-openai<2.0,>=0.2
Provides-Extra: lint
Requires-Dist: ruff>=0.5; extra == 'lint'
Provides-Extra: test
Requires-Dist: langchain-tests>=0.3; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest-socket>=0.7; extra == 'test'
Requires-Dist: pytest>=7.4; extra == 'test'
Requires-Dist: syrupy>=4.0; extra == 'test'
Provides-Extra: typing
Requires-Dist: mypy>=1.10; extra == 'typing'
Description-Content-Type: text/markdown

# langchain-neuralwatt

LangChain integration for [Neuralwatt](https://neuralwatt.com) — energy-aware AI inference. Drop-in replacement for `ChatOpenAI` that surfaces per-call energy and carbon metrics into LangChain's `response_metadata`.

## Install

```bash
pip install langchain-neuralwatt
```

## Quick start

```python
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

```python
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

| Param | Env var | Default |
|---|---|---|
| `model` | — | `glm-5-fast` |
| `api_key` | `NEURALWATT_API_KEY` (falls back to `OPENAI_API_KEY`) | — |
| `base_url` | `NEURALWATT_API_BASE` | `https://api.neuralwatt.com/v1` |

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

```bash
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](https://python.langchain.com/docs/contributing/how_to/integrations/standard_tests/) via `langchain-tests`.

## License

MIT
