Metadata-Version: 2.4
Name: langchain-oilpriceapi
Version: 1.0.0
Summary: LangChain tools for OilPriceAPI — real-time oil, gas, and commodity prices
Project-URL: Homepage, https://oilpriceapi.com
Project-URL: Documentation, https://docs.oilpriceapi.com
Project-URL: Repository, https://github.com/oilpriceapi/langchain-oilpriceapi
License: MIT
Keywords: ai,commodities,energy,langchain,llm,oil,prices
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# langchain-oilpriceapi

LangChain tools for [OilPriceAPI](https://oilpriceapi.com) — real-time oil, gas, and commodity prices for AI agents.

## Installation

```bash
pip install langchain-oilpriceapi
```

## Quick Start

```python
import os
from langchain_oilpriceapi import OilPriceTools
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# Set your API key
os.environ["OILPRICEAPI_KEY"] = "your_api_key_here"

# Get all tools
tools = OilPriceTools().get_tools()

# Build an agent
llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, tools)

# Ask questions
result = agent.invoke({
    "messages": [{"role": "user", "content": "What's the current Brent crude price and how does it compare to WTI?"}]
})
print(result["messages"][-1].content)
```

## Tools

| Tool                    | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `get_commodity_price`   | Get the current price of a commodity by name or code         |
| `get_market_overview`   | Get all commodity prices, optionally filtered by category    |
| `compare_prices`        | Compare 2–5 commodities side by side with spread calculation |
| `list_commodities`      | List all available commodity codes                           |
| `get_historical_prices` | Get price history over day/week/month/year with statistics   |

## Using Individual Tools

```python
from langchain_oilpriceapi import get_commodity_price, get_historical_prices

# Direct tool call
price = get_commodity_price.invoke({"commodity": "brent crude"})
print(price)

# Historical data
history = get_historical_prices.invoke({"commodity": "natural gas", "period": "week"})
print(history)
```

## Supported Commodities

**Crude Oil:** Brent (`BRENT_CRUDE_USD`), WTI (`WTI_USD`), Urals (`URALS_CRUDE_USD`), Dubai (`DUBAI_CRUDE_USD`)

**Natural Gas:** US Henry Hub (`NATURAL_GAS_USD`), UK NBP (`NATURAL_GAS_GBP`), European TTF (`DUTCH_TTF_EUR`)

**Refined Products:** Diesel, Gasoline, RBOB Gasoline, Jet Fuel, Heating Oil (all `_USD`)

**Coal:** `COAL_USD`, `NEWCASTLE_COAL_USD`

**Precious Metals:** Gold (USD/GBP/EUR AM+PM fixes), Silver (USD/GBP/EUR)

**Other:** EU Carbon (`EU_CARBON_EUR`), EUR/USD, GBP/USD

You can use natural language names like "brent oil", "natural gas", or "diesel" — the tools will resolve to the correct code automatically.

## Authentication

Set the `OILPRICEAPI_KEY` environment variable to your API key:

```bash
export OILPRICEAPI_KEY=your_api_key_here
```

Get your API key at [oilpriceapi.com](https://oilpriceapi.com).
