Add Headless Oracle market state provider

[HOYALIM]

Description

• Add a new headless_oracle provider with a MarketState fetcher for signed market-state receipts.
• Link Add market state verification layer for agent toolkit #7458.
• Screenshot of the feature or the bug before/after fix, if applicable.
• Add obb.equity.market_state(exchange=..., provider=\"headless_oracle\") as the agent-facing command surface.
• Keep the implementation fail-closed by exposing is_open=True only when the upstream status is OPEN.
• Preserve receipt metadata such as TTL, issuer, source, schema version, public key id, and signature.
• Raise OpenBBError when the upstream response does not include a valid receipt payload or omits required receipt fields.
• No new external runtime surface was added to MCP internals; the route flows through the existing OpenBB command path.
• Scope this as a receipt-fetching MVP; the provider does not perform local Ed25519 signature verification inside OpenBB.
• Leave exchange support bounded by the upstream Headless Oracle service and surface upstream failures if an unsupported exchange is requested.

How has this been tested?

• Added provider fetcher coverage in openbb_platform/providers/headless_oracle/tests/test_headless_oracle_fetchers.py, including direct assertions for:

  • fail-closed behavior on UNKNOWN
  • required receipt payload presence
  • required receipt field presence
  • recorded HTTP cassette coverage for the live fetcher path

• Added command-surface integration coverage in:

  • openbb_platform/extensions/equity/integration/test_equity_python.py
  • openbb_platform/extensions/equity/integration/test_equity_api.py

• Ran python3 -m poetry run pytest "providers/headless_oracle/tests/test_headless_oracle_fetchers.py" "providers/tests/test_provider_fetcher.py" "extensions/equity/integration/test_equity_python.py" -k "market_state or ProviderFetcherTest".

• Ran python3 -m poetry run pytest "extensions/equity/integration/test_equity_api.py" -k market_state -m integration with a local uvicorn openbb_core.api.rest_api:app server.

• Manually exercised the Python interface with python3 -m poetry run python -c "from openbb import obb; result = obb.equity.market_state(exchange='XNYS', provider='headless_oracle'); print(result.results.model_dump())".

• Manually exercised the REST API with GET /api/v1/equity/market_state?exchange=XNYS&provider=headless_oracle and confirmed a 200 response with the signed receipt payload.

• Attempted to regenerate openbb_platform/poetry.lock, but poetry lock is currently blocked by a pre-existing dependency mismatch in the base branch (openbb_platform/pyproject.toml requires openbb-mcp-server ^1.4.0 while poetry.lock still pins 1.3.1).

• Ensure all unit and integration tests pass.

• Ensure the command(s) execute with the expected output.

  • API.
  • Python Interface.

• If applicable, please add new tests for the command (see CONTRIBUTING.md to leverage semi-automated testing).

• Ensure the existing tests pass.

• Ensure the new provider and/or fetcher is stable and usable.

• If applicable, please add new tests for the provider and/or fetcher (see CONTRIBUTING.md to leverage semi-automated testing).

• If a new provider or extension was added:

  • Update the list of Extensions.
  • Update the list of Providers.
  • If it's a community extension or provider, update the integration tests GitHub Action workflow.

Checklist

• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have adhered to the GitFlow naming convention and my branch name is in the format of feature/feature-name or hotfix/hotfix-name.
• I ensure that I am following the CONTRIBUTING guidelines.
  • (If applicable) I have updated tests following these guidelines.

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

Adds a new “Headless Oracle” provider extension to fetch signed market-state receipts (fail-closed is_open), and exposes it through a new equity.market_state command backed by a new MarketState standard model.

Changes:

• Add MarketState standard model and new equity.market_state command surface.
• Introduce openbb-headless-oracle provider package with fetcher + recorded HTTP cassette test.
• Wire the provider into platform dependency extras and local dev install.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
openbb_platform/pyproject.toml	Adds optional dependency + extras entry for openbb-headless-oracle.
openbb_platform/core/openbb_core/provider/standard_models/market_state.py	Introduces MarketStateQueryParams and MarketStateData standard model.
openbb_platform/extensions/equity/openbb_equity/equity_router.py	Adds market_state router command for the new MarketState model.
openbb_platform/providers/headless_oracle/pyproject.toml	Defines the new provider package and plugin entrypoint.
openbb_platform/providers/headless_oracle/README.md	Documents usage example for obb.equity.market_state(..., provider="headless_oracle").
openbb_platform/providers/headless_oracle/openbb_headless_oracle/init.py	Registers the provider and maps MarketState to the fetcher.
openbb_platform/providers/headless_oracle/openbb_headless_oracle/models/market_state.py	Implements the fetcher to request/transform signed receipt metadata into MarketStateData.
openbb_platform/providers/headless_oracle/tests/test_headless_oracle_fetchers.py	Adds VCR-backed fetcher test.
openbb_platform/providers/headless_oracle/tests/record/http/test_headless_oracle_fetchers/test_headless_oracle_market_state_fetcher_urllib3_v2.yaml	Adds recorded HTTP cassette for the fetcher test.
openbb_platform/dev_install.py	Adds provider to local dev dependency installer; minor formatting refactors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[HOYALIM]

@copilot apply changes based on the comments in this thread

[LembaGang]

Thanks for building this, @HOYALIM — didn't expect a full provider, and the fail-closed-on-UNKNOWN handling is exactly right. Happy to help get the failing checks green if it's useful. (Looks like part of the red is a pre-existing base-branch lock mismatch rather than anything in your change.)

[HOYALIM]

Thanks for the feedback, @LembaGang! I really appreciate your support and am glad to hear that the fail-closed handling on UNKNOWN aligns with what you expected.

Also, thank you so much for offering to help get the failing checks green! As you noted, the lock mismatch seems to be a pre-existing issue from the base branch, but I truly appreciate your willingness to pitch in.