hallx 1.0.0__tar.gz

hallx-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hallx contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hallx-1.0.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: hallx
+Version: 1.0.0
+Summary: Lightweight hallucination risk scoring for LLM outputs
+Author: Dhanush Kandhan
+Maintainer: Dhanush Kandhan
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dhanushk-offl/hallx
+Project-URL: Repository, https://github.com/dhanushk-offl/hallx
+Project-URL: Issues, https://github.com/dhanushk-offl/hallx/issues
+Project-URL: Documentation, https://github.com/dhanushk-offl/hallx#readme
+Keywords: llm,hallucination,validation,scoring,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema<5.0.0,>=4.0.0
+Requires-Dist: rapidfuzz<4.0.0,>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == "dev"
+Requires-Dist: build<2.0.0,>=1.2.0; extra == "dev"
+Requires-Dist: twine<7.0.0,>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# hallx
+
+[![Tests](https://github.com/dhanushk-offl/hallx/actions/workflows/test.yml/badge.svg)](https://github.com/dhanushk-offl/hallx/actions/workflows/test.yml)
+[![Release](https://github.com/dhanushk-offl/hallx/actions/workflows/release.yml/badge.svg)](https://github.com/dhanushk-offl/hallx/actions/workflows/release.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/dhanushk-offl/hallx/badge)](https://scorecard.dev/viewer/?uri=github.com/dhanushk-offl/hallx)
+[![PyPI](https://img.shields.io/pypi/v/hallx.svg)](https://pypi.org/project/hallx/)
+[![Python](https://img.shields.io/pypi/pyversions/hallx.svg)](https://pypi.org/project/hallx/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Lightweight hallucination-risk scoring for production LLM pipelines.
+
+## Overview
+
+| Area | What Hallx Provides |
+|---|---|
+| Risk output | `confidence` (`0.0` to `1.0`) and `risk_level` (`high`, `medium`, `low`) |
+| Diagnostics | `issues` list for tracing weak signals and policy failures |
+| Actionability | `recommendation` payload (`action`, `suggested_temperature`, `suggestions`) |
+| API modes | Sync and async checks |
+| Integrations | Adapter-based and callable-based workflows |
+| Operations | Feedback storage and calibration reporting |
+
+Hallx is designed as a guardrail layer before downstream actions such as API responses, automation steps, and database writes.
+
+## Installation
+
+```bash
+pip install hallx
+```
+
+Development install:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from hallx import Hallx
+
+checker = Hallx(profile="balanced", strict=False)
+result = checker.check(
+    prompt="Summarize refund policy",
+    response={"summary": "Refunds are allowed within 30 days."},
+    context=["Refunds are allowed within 30 days of purchase."],
+    schema={
+        "type": "object",
+        "properties": {"summary": {"type": "string"}},
+        "required": ["summary"],
+        "additionalProperties": False,
+    },
+)
+
+print(result.confidence, result.risk_level)
+print(result.scores)
+print(result.issues)
+print(result.recommendation)
+```
+
+## Scoring Model
+
+Hallx uses heuristic risk scoring across three signals:
+
+| Signal | Description |
+|---|---|
+| `schema` | JSON schema validity and null-injection checks |
+| `consistency` | Stability across repeated generations |
+| `grounding` | Claim-context alignment and source-integrity checks |
+
+Confidence formula:
+
+```text
+confidence = clamp(
+  schema_score * w_schema +
+  consistency_score * w_consistency +
+  grounding_score * w_grounding,
+  0.0, 1.0
+)
+```
+
+Default (`balanced`) weights:
+
+| Weight | Value |
+|---|---|
+| `w_schema` | `0.34` |
+| `w_consistency` | `0.33` |
+| `w_grounding` | `0.33` |
+
+Risk mapping:
+
+| Confidence range | Risk |
+|---|---|
+| `< 0.40` | `high` |
+| `< 0.75` | `medium` |
+| `>= 0.75` | `low` |
+
+Note: skipped checks are penalized by default to avoid over-trusting partial analysis.
+
+## Safety Profiles
+
+| Profile | Goal | Default `consistency_runs` | Skip penalty |
+|---|---|---:|---:|
+| `fast` | lower latency | 2 | 0.15 |
+| `balanced` | general-purpose | 3 | 0.25 |
+| `strict` | stronger scrutiny | 4 | 0.40 |
+
+```python
+from hallx import Hallx
+
+checker = Hallx(profile="strict")
+```
+
+You can override `weights`, `consistency_runs`, and `skip_penalty` as needed.
+
+## Workflow
+
+![Hallx working flow](docs/images/hallx-working-flow.svg)
+
+1. Collect prompt, optional context, optional schema.
+2. Generate a model response through an adapter or callable.
+3. Run `schema`, `consistency`, and `grounding` checks.
+4. Aggregate scores into `confidence` and `risk_level`.
+5. Apply policy (`proceed` or `retry`) using recommendation metadata.
+6. Optionally record reviewed outcomes for calibration.
+
+## Adapters
+
+| Provider adapter |
+|---|
+| OpenAI |
+| Anthropic |
+| Gemini |
+| OpenRouter |
+| Perplexity |
+| Grok |
+| HuggingFace |
+| Ollama |
+
+## Samples
+
+| Sample | Purpose |
+|---|---|
+| `samples/basic_sync.py` | minimal sync workflow |
+| `samples/async_openai_adapter.py` | async provider check with context |
+| `samples/async_openai_adapter_no_context.py` | no-context behavior and weighting example |
+| `samples/retry_strategy.py` | recommendation-driven retry policy |
+| `samples/strict_mode.py` | strict blocking behavior |
+| `samples/feedback_calibration.py` | local feedback storage and calibration report |
+| `samples/async_openai_feedback_calibration.py` | async generation + feedback in one loop |
+
+## Feedback Storage and Calibration
+
+```python
+from hallx import Hallx
+
+checker = Hallx(feedback_db_path="/var/lib/myapp/hallx-feedback.sqlite3")
+
+result = checker.check(prompt="p", response="r", context=["c"])
+checker.record_outcome(
+    result=result,
+    label="hallucinated",  # aliases: safe -> correct, unsafe -> hallucinated
+    metadata={"reviewer": "qa-team"},
+    prompt="p",
+    response_excerpt="r",
+)
+
+report = checker.calibration_report(window_days=30)
+print(report["suggested_threshold"], report["threshold_metrics"])
+```
+
+Default DB path resolution:
+
+| Environment | Default path |
+|---|---|
+| Env override | `HALLX_FEEDBACK_DB` |
+| Windows | `%LOCALAPPDATA%\\hallx\\feedback.sqlite3` (fallback `%APPDATA%`) |
+| macOS | `~/Library/Application Support/hallx/feedback.sqlite3` |
+| Linux/servers | `$XDG_DATA_HOME/hallx/feedback.sqlite3` or `~/.local/share/hallx/feedback.sqlite3` |
+
+## Production Notes
+
+| Recommendation | Why |
+|---|---|
+| Enable strict mode on sensitive paths | block high-risk responses before side effects |
+| Log `confidence`, `risk_level`, `issues` | support auditing and threshold tuning |
+| Use calibration report regularly | adjust thresholds with real reviewed outcomes |
+| Keep context quality high | grounding quality depends on evidence quality |
+
+## Known Limitations
+
+- Hallx is heuristic and does not provide formal factual guarantees.
+- High confidence can still be wrong if context is missing, stale, or incorrect.
+- Similarity-based checks can miss nuanced semantic contradictions.
+- High-stakes domains should combine Hallx with domain validators and human review.
+
+## Documentation
+
+- [Usage Guide](docs/USAGE.md)
+- [Production Notes](docs/PRODUCTION.md)
+- [Contributing Guide](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [License](LICENSE)

hallx-1.0.0/README.md

@@ -0,0 +1,203 @@
+# hallx
+
+[![Tests](https://github.com/dhanushk-offl/hallx/actions/workflows/test.yml/badge.svg)](https://github.com/dhanushk-offl/hallx/actions/workflows/test.yml)
+[![Release](https://github.com/dhanushk-offl/hallx/actions/workflows/release.yml/badge.svg)](https://github.com/dhanushk-offl/hallx/actions/workflows/release.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/dhanushk-offl/hallx/badge)](https://scorecard.dev/viewer/?uri=github.com/dhanushk-offl/hallx)
+[![PyPI](https://img.shields.io/pypi/v/hallx.svg)](https://pypi.org/project/hallx/)
+[![Python](https://img.shields.io/pypi/pyversions/hallx.svg)](https://pypi.org/project/hallx/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Lightweight hallucination-risk scoring for production LLM pipelines.
+
+## Overview
+
+| Area | What Hallx Provides |
+|---|---|
+| Risk output | `confidence` (`0.0` to `1.0`) and `risk_level` (`high`, `medium`, `low`) |
+| Diagnostics | `issues` list for tracing weak signals and policy failures |
+| Actionability | `recommendation` payload (`action`, `suggested_temperature`, `suggestions`) |
+| API modes | Sync and async checks |
+| Integrations | Adapter-based and callable-based workflows |
+| Operations | Feedback storage and calibration reporting |
+
+Hallx is designed as a guardrail layer before downstream actions such as API responses, automation steps, and database writes.
+
+## Installation
+
+```bash
+pip install hallx
+```
+
+Development install:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from hallx import Hallx
+
+checker = Hallx(profile="balanced", strict=False)
+result = checker.check(
+    prompt="Summarize refund policy",
+    response={"summary": "Refunds are allowed within 30 days."},
+    context=["Refunds are allowed within 30 days of purchase."],
+    schema={
+        "type": "object",
+        "properties": {"summary": {"type": "string"}},
+        "required": ["summary"],
+        "additionalProperties": False,
+    },
+)
+
+print(result.confidence, result.risk_level)
+print(result.scores)
+print(result.issues)
+print(result.recommendation)
+```
+
+## Scoring Model
+
+Hallx uses heuristic risk scoring across three signals:
+
+| Signal | Description |
+|---|---|
+| `schema` | JSON schema validity and null-injection checks |
+| `consistency` | Stability across repeated generations |
+| `grounding` | Claim-context alignment and source-integrity checks |
+
+Confidence formula:
+
+```text
+confidence = clamp(
+  schema_score * w_schema +
+  consistency_score * w_consistency +
+  grounding_score * w_grounding,
+  0.0, 1.0
+)
+```
+
+Default (`balanced`) weights:
+
+| Weight | Value |
+|---|---|
+| `w_schema` | `0.34` |
+| `w_consistency` | `0.33` |
+| `w_grounding` | `0.33` |
+
+Risk mapping:
+
+| Confidence range | Risk |
+|---|---|
+| `< 0.40` | `high` |
+| `< 0.75` | `medium` |
+| `>= 0.75` | `low` |
+
+Note: skipped checks are penalized by default to avoid over-trusting partial analysis.
+
+## Safety Profiles
+
+| Profile | Goal | Default `consistency_runs` | Skip penalty |
+|---|---|---:|---:|
+| `fast` | lower latency | 2 | 0.15 |
+| `balanced` | general-purpose | 3 | 0.25 |
+| `strict` | stronger scrutiny | 4 | 0.40 |
+
+```python
+from hallx import Hallx
+
+checker = Hallx(profile="strict")
+```
+
+You can override `weights`, `consistency_runs`, and `skip_penalty` as needed.
+
+## Workflow
+
+![Hallx working flow](docs/images/hallx-working-flow.svg)
+
+1. Collect prompt, optional context, optional schema.
+2. Generate a model response through an adapter or callable.
+3. Run `schema`, `consistency`, and `grounding` checks.
+4. Aggregate scores into `confidence` and `risk_level`.
+5. Apply policy (`proceed` or `retry`) using recommendation metadata.
+6. Optionally record reviewed outcomes for calibration.
+
+## Adapters
+
+| Provider adapter |
+|---|
+| OpenAI |
+| Anthropic |
+| Gemini |
+| OpenRouter |
+| Perplexity |
+| Grok |
+| HuggingFace |
+| Ollama |
+
+## Samples
+
+| Sample | Purpose |
+|---|---|
+| `samples/basic_sync.py` | minimal sync workflow |
+| `samples/async_openai_adapter.py` | async provider check with context |
+| `samples/async_openai_adapter_no_context.py` | no-context behavior and weighting example |
+| `samples/retry_strategy.py` | recommendation-driven retry policy |
+| `samples/strict_mode.py` | strict blocking behavior |
+| `samples/feedback_calibration.py` | local feedback storage and calibration report |
+| `samples/async_openai_feedback_calibration.py` | async generation + feedback in one loop |
+
+## Feedback Storage and Calibration
+
+```python
+from hallx import Hallx
+
+checker = Hallx(feedback_db_path="/var/lib/myapp/hallx-feedback.sqlite3")
+
+result = checker.check(prompt="p", response="r", context=["c"])
+checker.record_outcome(
+    result=result,
+    label="hallucinated",  # aliases: safe -> correct, unsafe -> hallucinated
+    metadata={"reviewer": "qa-team"},
+    prompt="p",
+    response_excerpt="r",
+)
+
+report = checker.calibration_report(window_days=30)
+print(report["suggested_threshold"], report["threshold_metrics"])
+```
+
+Default DB path resolution:
+
+| Environment | Default path |
+|---|---|
+| Env override | `HALLX_FEEDBACK_DB` |
+| Windows | `%LOCALAPPDATA%\\hallx\\feedback.sqlite3` (fallback `%APPDATA%`) |
+| macOS | `~/Library/Application Support/hallx/feedback.sqlite3` |
+| Linux/servers | `$XDG_DATA_HOME/hallx/feedback.sqlite3` or `~/.local/share/hallx/feedback.sqlite3` |
+
+## Production Notes
+
+| Recommendation | Why |
+|---|---|
+| Enable strict mode on sensitive paths | block high-risk responses before side effects |
+| Log `confidence`, `risk_level`, `issues` | support auditing and threshold tuning |
+| Use calibration report regularly | adjust thresholds with real reviewed outcomes |
+| Keep context quality high | grounding quality depends on evidence quality |
+
+## Known Limitations
+
+- Hallx is heuristic and does not provide formal factual guarantees.
+- High confidence can still be wrong if context is missing, stale, or incorrect.
+- Similarity-based checks can miss nuanced semantic contradictions.
+- High-stakes domains should combine Hallx with domain validators and human review.
+
+## Documentation
+
+- [Usage Guide](docs/USAGE.md)
+- [Production Notes](docs/PRODUCTION.md)
+- [Contributing Guide](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [License](LICENSE)

hallx-1.0.0/hallx/__init__.py

@@ -0,0 +1,33 @@
+"""hallx public API."""
+
+from hallx.adapters import (
+    AnthropicAdapter,
+    GeminiAdapter,
+    GrokAdapter,
+    HuggingFaceAdapter,
+    OllamaAdapter,
+    OpenAIAdapter,
+    OpenRouterAdapter,
+    PerplexityAdapter,
+)
+from hallx.calibration import FeedbackStore, default_feedback_db_path
+from hallx.core import Hallx
+from hallx.types import HallxAdapterError, HallxHighRiskError, HallxResult, SchemaValidationResult
+
+__all__ = [
+    "Hallx",
+    "HallxResult",
+    "SchemaValidationResult",
+    "HallxHighRiskError",
+    "HallxAdapterError",
+    "FeedbackStore",
+    "default_feedback_db_path",
+    "OpenAIAdapter",
+    "OpenRouterAdapter",
+    "AnthropicAdapter",
+    "PerplexityAdapter",
+    "HuggingFaceAdapter",
+    "OllamaAdapter",
+    "GeminiAdapter",
+    "GrokAdapter",
+]

hallx-1.0.0/hallx/adapters/__init__.py

@@ -0,0 +1,21 @@
+"""Provider adapters for plugging Hallx into common LLM APIs."""
+
+from hallx.adapters.anthropic import AnthropicAdapter
+from hallx.adapters.gemini import GeminiAdapter
+from hallx.adapters.grok import GrokAdapter
+from hallx.adapters.huggingface import HuggingFaceAdapter
+from hallx.adapters.ollama import OllamaAdapter
+from hallx.adapters.openai import OpenAIAdapter
+from hallx.adapters.openrouter import OpenRouterAdapter
+from hallx.adapters.perplexity import PerplexityAdapter
+
+__all__ = [
+    "OpenAIAdapter",
+    "OpenRouterAdapter",
+    "AnthropicAdapter",
+    "PerplexityAdapter",
+    "HuggingFaceAdapter",
+    "OllamaAdapter",
+    "GeminiAdapter",
+    "GrokAdapter",
+]

hallx-1.0.0/hallx/adapters/anthropic.py

@@ -0,0 +1,42 @@
+"""Anthropic adapter."""
+
+from typing import Any, Mapping, Optional
+
+from hallx.adapters.base import HTTPAdapter
+from hallx.types import HallxAdapterError
+
+
+class AnthropicAdapter(HTTPAdapter):
+    """Anthropic Messages API adapter."""
+
+    endpoint = "https://api.anthropic.com/v1/messages"
+
+    def _headers(self) -> dict[str, str]:
+        headers = super()._headers()
+        headers["x-api-key"] = self.api_key
+        headers["anthropic-version"] = "2023-06-01"
+        headers.pop("Authorization", None)
+        return headers
+
+    def _build_payload(self, prompt: str, system_prompt: Optional[str]) -> Mapping[str, Any]:
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "max_tokens": self.max_tokens,
+            "temperature": self.temperature,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+        if system_prompt:
+            payload["system"] = system_prompt
+        return payload
+
+    def _parse_response(self, body: Mapping[str, Any]) -> str:
+        content = body.get("content")
+        if not isinstance(content, list) or not content:
+            raise HallxAdapterError("Anthropic response missing content")
+        first = content[0]
+        if not isinstance(first, Mapping):
+            raise HallxAdapterError("Anthropic content is malformed")
+        text = first.get("text")
+        if not isinstance(text, str):
+            raise HallxAdapterError("Anthropic content text missing")
+        return text

hallx-1.0.0/hallx/adapters/base.py

@@ -0,0 +1,105 @@
+"""Shared HTTP adapter primitives for LLM providers."""
+
+import asyncio
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional
+from urllib import error, request
+
+from hallx.types import HallxAdapterError
+
+
+@dataclass(frozen=True)
+class AdapterConfig:
+    """Provider transport configuration."""
+
+    model: str
+    api_key: str
+    timeout_seconds: float = 20.0
+
+
+class HTTPAdapter:
+    """Minimal secure HTTP JSON adapter with sync and async interfaces."""
+
+    endpoint: str
+
+    def __init__(
+        self,
+        model: str,
+        api_key: str,
+        timeout_seconds: float = 20.0,
+        temperature: float = 0.0,
+        max_tokens: int = 256,
+        extra_headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        if not model.strip():
+            raise ValueError("model must be non-empty")
+        if not api_key.strip():
+            raise ValueError("api_key must be non-empty")
+        if timeout_seconds <= 0.0 or timeout_seconds > 120.0:
+            raise ValueError("timeout_seconds must be between 0 and 120")
+        if max_tokens <= 0:
+            raise ValueError("max_tokens must be > 0")
+
+        self.model = model
+        self.api_key = api_key
+        self.timeout_seconds = timeout_seconds
+        self.temperature = max(0.0, min(2.0, temperature))
+        self.max_tokens = max_tokens
+        self.extra_headers = dict(extra_headers or {})
+
+    def generate(self, prompt: str, system_prompt: Optional[str] = None) -> str:
+        """Generate text synchronously."""
+        payload = self._build_payload(prompt=prompt, system_prompt=system_prompt)
+        body = self._post_json(self.endpoint, payload, headers=self._headers())
+        return self._parse_response(body)
+
+    async def agenerate(self, prompt: str, system_prompt: Optional[str] = None) -> str:
+        """Generate text asynchronously using a worker thread."""
+        return await asyncio.to_thread(self.generate, prompt, system_prompt)
+
+    @classmethod
+    def from_env(cls, model: str, env_key_name: str, **kwargs: Any) -> "HTTPAdapter":
+        """Construct adapter from environment variable key."""
+        api_key = os.getenv(env_key_name, "")
+        if not api_key:
+            raise ValueError(f"missing environment variable: {env_key_name}")
+        return cls(model=model, api_key=api_key, **kwargs)
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        headers.update(self.extra_headers)
+        return headers
+
+    def _build_payload(self, prompt: str, system_prompt: Optional[str]) -> Mapping[str, Any]:
+        raise NotImplementedError
+
+    def _parse_response(self, body: Mapping[str, Any]) -> str:
+        raise NotImplementedError
+
+    def _post_json(self, url: str, payload: Mapping[str, Any], headers: Mapping[str, str]) -> Dict[str, Any]:
+        data = json.dumps(payload, ensure_ascii=True).encode("utf-8")
+        req = request.Request(url=url, data=data, headers=dict(headers), method="POST")
+
+        try:
+            with request.urlopen(req, timeout=self.timeout_seconds) as resp:
+                raw = resp.read().decode("utf-8")
+        except error.HTTPError as exc:
+            message = exc.read().decode("utf-8", errors="ignore") if hasattr(exc, "read") else ""
+            raise HallxAdapterError(f"provider HTTP error {exc.code}: {message[:200]}") from exc
+        except error.URLError as exc:
+            raise HallxAdapterError(f"provider connection failed: {exc.reason}") from exc
+
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise HallxAdapterError("provider returned non-JSON response") from exc
+
+        if not isinstance(parsed, dict):
+            raise HallxAdapterError("provider response must be a JSON object")
+        return parsed