Metadata-Version: 2.4
Name: langchain-headless-oracle
Version: 0.1.0
Summary: LangChain tools for Headless Oracle: signed market-state receipts for autonomous agents
Author-email: Headless Oracle <info@bytecraftresults.com>
License: MIT
Project-URL: Homepage, https://headlessoracle.com
Project-URL: Documentation, https://headlessoracle.com/docs/integrations/langchain
Project-URL: Repository, https://github.com/LembaGang/langchain-headless-oracle
Project-URL: Issues, https://github.com/LembaGang/langchain-headless-oracle/issues
Keywords: headless-oracle,langchain,market-data,trading,agents,mcp,verifiable-intent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: headless_oracle>=0.1.1
Requires-Dist: langchain-core>=0.1
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Dynamic: license-file

# langchain-headless-oracle

LangChain tools for [Headless Oracle](https://headlessoracle.com): signed market-state receipts for autonomous agents.

**Note: SMA in this package denotes "Signed Market Attestation" — not Simple Moving Average.**

## Installation

```bash
pip install langchain-headless-oracle
```

## Quickstart

```python
from langchain_headless_oracle import (
    MarketStatusTool,
    MarketScheduleTool,
    MarketStateVerifyTool,
)

# API key resolves from HEADLESS_ORACLE_API_KEY by default
# (or pass api_key=... to the constructor).
tools = [
    MarketStatusTool(),       # authenticated live receipt
    MarketScheduleTool(),     # keyless next open/close
    MarketStateVerifyTool(),  # keyless signature verification
]
```

## Tools

### MarketStatusTool

Returns a cryptographically signed **Signed Market Attestation (SMA)** receipt for one of 28 global exchanges.

- **Status**: `OPEN`, `CLOSED`, `HALTED`, or `UNKNOWN`
- **Fail-closed**: `UNKNOWN` and `HALTED` MUST be treated as `CLOSED`
- **Signed**: Ed25519, 60-second TTL
- **Authenticated**: requires an API key (see [API key resolution](#api-key-resolution))

### MarketScheduleTool

Returns upcoming open/close times for a global exchange. IANA timezone identifiers — DST is handled automatically. **Keyless.**

### MarketStateVerifyTool

Cryptographically verifies an SMA receipt's Ed25519 signature against Headless Oracle's published public keys at `/v5/keys`. **Keyless.**

Returns `{valid: bool, reason: str | null}`. Fail reasons include `INVALID_SIGNATURE`, `EXPIRED`, `MISSING_FIELDS`, `UNKNOWN_KEY`, `INVALID_JSON`.

## Verification example

The status → verify pattern: fetch a receipt, verify it before acting on it.

```python
import json
from langchain_headless_oracle import MarketStatusTool, MarketStateVerifyTool

receipt_json = MarketStatusTool()._run("XNYS")
verify_json = MarketStateVerifyTool()._run(receipt_json)
verified = json.loads(verify_json)

if not verified["valid"]:
    raise RuntimeError(f"Receipt rejected: {verified['reason']}")

receipt = json.loads(receipt_json)
if receipt["status"] != "OPEN":
    raise RuntimeError(f"Market not open: {receipt['status']} — halting execution")
```

## API key resolution

`MarketStatusTool` resolves an API key in this priority order:

1. `HEADLESS_ORACLE_API_KEY` environment variable.
2. `~/.headless_oracle/config.json` cache.
3. (Opt-in only) auto-provision a free sandbox key from `https://headlessoracle.com/v5/sandbox`.

Auto-provision is **off by default** — instantiate with `auto_provision_sandbox=True` to enable:

```python
MarketStatusTool(auto_provision_sandbox=True)
```

When no key is available and auto-provision is off, the tool returns a fail-closed result instead of raising:

```json
{"status": "UNKNOWN", "safe_to_execute": false, "error": "No API key found..."}
```

`MarketScheduleTool` and `MarketStateVerifyTool` do not require an API key.

## Relationship to the Headless Oracle SDK

This package wraps the official [`headless_oracle`](https://pypi.org/project/headless-oracle/) Python SDK — all HTTP calls and Ed25519 verification are delegated to it.

This package supersedes the older [`headless-oracle-langchain`](https://pypi.org/project/headless-oracle-langchain/) package on PyPI, which will be deprecated.

## Supported exchanges (28)

XNYS (NYSE), XNAS (NASDAQ), XLON (LSE), XJPX (Tokyo), XPAR (Paris), XHKG (Hong Kong),
XSES (Singapore), XASX (Sydney), XBOM (BSE India), XNSE (NSE India), XSHG (Shanghai),
XSHE (Shenzhen), XKRX (Seoul), XJSE (Johannesburg), XBSP (B3 Brazil), XSWX (Swiss),
XMIL (Milan), XIST (Istanbul), XSAU (Riyadh), XDFM (Dubai), XNZE (Auckland),
XHEL (Helsinki), XSTO (Stockholm), XCBT (CME), XNYM (NYMEX), XCBO (Cboe),
XCOI (Coinbase 24/7), XBIN (Binance 24/7)

## Links

- [Docs](https://headlessoracle.com/docs)
- [LangChain integration guide](https://headlessoracle.com/docs/integrations/langchain)
- [SMA Protocol RFC-001](https://headlessoracle.com/docs/sma-protocol/rfc-001)
- [`headless_oracle` Python SDK](https://pypi.org/project/headless-oracle/)
