Metadata-Version: 2.4
Name: crewai-headless-oracle
Version: 0.1.0
Summary: CrewAI 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/crewai
Project-URL: Repository, https://github.com/LembaGang/crewai-headless-oracle
Project-URL: Issues, https://github.com/LembaGang/crewai-headless-oracle/issues
Keywords: headless-oracle,crewai,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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: headless_oracle>=0.1.1
Requires-Dist: crewai>=0.130
Requires-Dist: pydantic>=2.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Dynamic: license-file

# crewai-headless-oracle

CrewAI 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 crewai-headless-oracle
```

> **Install footprint**: this package depends on `crewai`, which pulls in
> heavy transitive dependencies (chromadb, lancedb, pyarrow, onnxruntime)
> totaling roughly 500 MB on disk. The same applies to any direct CrewAI
> install — flagging here for honesty. If you only need to verify a
> Headless Oracle receipt without the agent framework, install the SDK
> directly: `pip install headless-oracle`.

## Quickstart

```python
from crewai_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
]
```

## CrewAI Crew example

```python
from crewai import Agent, Task, Crew
from crewai_headless_oracle import (
    MarketStatusTool,
    MarketScheduleTool,
    MarketStateVerifyTool,
)

trader = Agent(
    role="Market timing analyst",
    goal="Decide whether the NYSE is currently safe to trade against",
    backstory=(
        "You consult Headless Oracle for cryptographically signed market "
        "state before any execution. UNKNOWN and HALTED MUST be treated as "
        "CLOSED."
    ),
    tools=[MarketStatusTool(), MarketStateVerifyTool(), MarketScheduleTool()],
)

check_market = Task(
    description=(
        "Fetch the current NYSE (XNYS) Signed Market Attestation receipt, "
        "verify its Ed25519 signature, and report whether execution is safe."
    ),
    expected_output="A JSON object with status, safe_to_execute, and verification result.",
    agent=trader,
)

crew = Crew(agents=[trader], tasks=[check_market])
result = crew.kickoff()
print(result)
```

## 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 crewai_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.

## Verifying receipts offline

Public keys are published as a JWKS at
[`https://headlessoracle.com/.well-known/jwks.json`](https://headlessoracle.com/.well-known/jwks.json)
(RFC 7517), in addition to the SDK-native `/v5/keys` endpoint. JOSE-fluent
agents can verify Headless Oracle receipts using any standard JWK-aware
library without a Headless-Oracle-specific dependency.

## 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.

For LangChain users, see the sibling package:
[`langchain-headless-oracle`](https://github.com/LembaGang/langchain-headless-oracle).

## 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

- [Headless Oracle docs](https://headlessoracle.com/docs)
- [CrewAI integration guide](https://headlessoracle.com/docs/integrations/crewai)
- [SMA Protocol RFC-001](https://headlessoracle.com/docs/sma-protocol/rfc-001)
- [IETF draft: Environment-State Verification](https://datatracker.ietf.org/doc/draft-borthwick-msebenzi-environment-state/)
- [JWKS discovery endpoint](https://headlessoracle.com/.well-known/jwks.json) (RFC 7517)
- [`headless_oracle` Python SDK](https://pypi.org/project/headless-oracle/)
- [LangChain sibling package](https://github.com/LembaGang/langchain-headless-oracle)
