crewai-headless-oracle

CrewAI tools for Headless Oracle: signed market-state receipts for autonomous agents.

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

Installation

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

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

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)

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.

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:

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:

{"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 (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 Python SDK — all HTTP calls and Ed25519 verification are delegated to it.

For LangChain users, see the sibling package: 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
• CrewAI integration guide
• SMA Protocol RFC-001
• IETF draft: Environment-State Verification
• JWKS discovery endpoint (RFC 7517)
• headless_oracle Python SDK
• LangChain sibling package