hedit 0.7.11.dev5__tar.gz → 0.7.11.dev7__tar.gz

{hedit-0.7.11.dev5/hedit.egg-info → hedit-0.7.11.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hedit
-Version: 0.7.11.dev5
+Version: 0.7.11.dev7
 Summary: Multi-agent system for HED annotation generation and validation
 Author-email: Annotation Garden Initiative <info@annotation.garden>
 License-Expression: MIT

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/README.md

@@ -84,7 +84,9 @@ The agents work in feedback loops, automatically refining the annotation until i
 
 ## Documentation
 
+- [Changelog](CHANGELOG.md) - What changed in each release
 - [Prompt Caching and Usage Reporting](docs/prompt-caching.md) - What HEDit caches, what it saves, and where to see the numbers
+- [Extended Thinking](docs/reasoning.md) - Measured effect of reasoning per agent role, and how to tune it
 - [HED Standard](https://hedtags.org) - Learn about HED annotations
 - [GitHub Issues](https://github.com/Annotation-Garden/HEDit/issues) - Report bugs or request features
 

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7/hedit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hedit
-Version: 0.7.11.dev5
+Version: 0.7.11.dev7
 Summary: Multi-agent system for HED annotation generation and validation
 Author-email: Annotation Garden Initiative <info@annotation.garden>
 License-Expression: MIT

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hedit"
-version = "0.7.11.dev5"
+version = "0.7.11.dev7"
 description = "Multi-agent system for HED annotation generation and validation"
 readme = "PKG_README.md"
 requires-python = ">=3.12"

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/src/api/main.py

@@ -40,7 +40,12 @@ from src.api.models import (
 from src.api.security import api_key_auth, audit_logger
 from src.lsp import HedLspClient
 from src.telemetry import LocalFileStorage, TelemetryCollector, TelemetryEvent
-from src.utils.anthropic_llm import DEFAULT_MODEL, create_anthropic_llm, normalize_model
+from src.utils.anthropic_llm import (
+    DEFAULT_MODEL,
+    annotation_thinking,
+    create_anthropic_llm,
+    normalize_model,
+)
 from src.utils.llm_usage import UsageLedger, process_ledger, usage_scope
 from src.utils.schema_loader import HedSchemaLoader
 from src.validation.hed_validator import HedPythonValidator
@@ -77,6 +82,11 @@ def _describe_llm_error(exc: Exception) -> tuple[int, str, str]:
     key gets a 401 pointing at their key, not a generic 500. Order matters --
     AnthropicContextOverflowError subclasses BadRequestError, and the timeout
     and rate-limit types must be checked before their parent classes.
+
+    Every message here is a fixed string. Exception text never reaches the
+    client, because a provider error can carry request details and the web app
+    renders the message as HTML. Callers log the exception, so the provider's
+    own wording stays available in the server log for whoever debugs it.
     """
     if isinstance(exc, APITimeoutError):
         return 504, "timeout", "LLM request timed out. Try again or use a faster model."
@@ -93,7 +103,11 @@ def _describe_llm_error(exc: Exception) -> tuple[int, str, str]:
     if isinstance(exc, AnthropicContextOverflowError):
         return 413, "context_overflow", "The input is too long for this model. Try shortening it."
     if isinstance(exc, anthropic.BadRequestError):
-        return 400, "bad_request", f"The LLM rejected the request: {str(exc)[:200]}"
+        return (
+            400,
+            "bad_request",
+            "The LLM rejected the request. Check the model and request parameters, then try again.",
+        )
     if isinstance(exc, anthropic.APIConnectionError):
         return 502, "upstream_unreachable", "Could not reach the LLM service. Please try again."
     return 500, "internal", "An error occurred during annotation processing."
@@ -200,13 +214,15 @@ def create_anthropic_workflow(
     normalize_model(actual_eval_model)
 
     # Create LLMs.
-    # The annotation LLM keeps reasoning enabled — that's the model
-    # doing the actual HED tag synthesis where extended thinking
-    # measurably improves first-attempt quality.
+    # Annotation thinks: measured over the benchmark descriptions, a 2048-token
+    # budget took first-attempt validity from 5/15 to 13/15 and cut total LLM
+    # calls by a third, for 24% more cost and about twice the latency. See
+    # annotation_thinking() and docs/prompt-caching.md.
     annotation_llm = create_anthropic_llm(
         model=actual_annotation_model,
         api_key=api_key,
         temperature=actual_temperature,
+        thinking=annotation_thinking(actual_annotation_model),
         role="annotation",
     )
     # Evaluation / assessment / feedback / keyword extraction are short

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/src/cli/config.py

@@ -34,8 +34,9 @@ DEFAULT_API_URL = "https://api.annotation.garden/hedit"
 DEFAULT_DEV_API_URL = "https://api.annotation.garden/hedit-dev"
 
 # Default models (Anthropic Claude only since the 2026-08-18 migration).
-# Annotation model: Claude Haiku 4.5 (fast, near-frontier quality).
-# Claude Sonnet 5 ("claude-sonnet-5") is offered for highest quality.
+# Annotation model: Claude Haiku 4.5, which runs with extended thinking and
+# matched Sonnet 5's first-attempt validity for 2.3x less cost (docs/reasoning.md).
+# Claude Sonnet 5 ("claude-sonnet-5") stays selectable for comparison.
 DEFAULT_MODEL = "claude-haiku-4-5"
 
 # Evaluation judge stays on Haiku regardless of the annotation model.

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/src/cli/local_executor.py

@@ -150,13 +150,16 @@ class LocalExecutionBackend(ExecutionBackend):
             self._ensure_api_key()
 
             from src.agents.workflow import HedAnnotationWorkflow
-            from src.utils.anthropic_llm import create_anthropic_llm
+            from src.utils.anthropic_llm import annotation_thinking, create_anthropic_llm
 
-            # Annotation LLM keeps reasoning enabled (real HED tag work).
+            # Annotation thinks; see annotation_thinking() for the measurement
+            # behind the budget and HEDIT_ANNOTATION_THINKING_BUDGET to change
+            # or disable it.
             annotation_llm = create_anthropic_llm(
                 model=self._model,
                 api_key=self._api_key,
                 temperature=self._temperature,
+                thinking=annotation_thinking(self._model),
                 role="annotation",
             )
 

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/src/cli/main.py

@@ -104,7 +104,7 @@ ModelOption = Annotated[
     typer.Option(
         "--model",
         "-m",
-        help="Model to use: claude-haiku-4-5 (default) or claude-sonnet-5",
+        help="Model to use: claude-haiku-4-5 (default, recommended) or claude-sonnet-5",
     ),
 ]
 

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/src/utils/anthropic_llm.py

@@ -41,8 +41,8 @@ DEFAULT_MODEL = "claude-haiku-4-5"
 # Models offered to users (web UI dropdown / CLI). Opus is deliberately
 # not offered.
 ALLOWED_MODELS = {
-    "claude-haiku-4-5": "Claude Haiku 4.5 (fast, default)",
-    "claude-sonnet-5": "Claude Sonnet 5 (highest quality)",
+    "claude-haiku-4-5": "Claude Haiku 4.5 (default, recommended)",
+    "claude-sonnet-5": "Claude Sonnet 5 (larger, 2.3x the cost)",
 }
 
 # Legacy identifiers from older clients, saved CLI configs, and cached
@@ -78,6 +78,20 @@ _ADAPTIVE_THINKING_MODELS = {"claude-sonnet-5"}
 _ALWAYS_THINKING_MODELS: set[str] = set()
 LOWEST_REASONING_EFFORT = "low"
 
+# Smallest thinking budget the API accepts on budget-style models.
+MIN_THINKING_BUDGET_TOKENS = 1024
+
+# Thinking budget for the annotation role on budget-style models. Measured
+# over the 15 benchmark descriptions (2026-08-20, Haiku 4.5): first-attempt
+# validity went 5/15 without thinking to 11/15 at 1024 tokens and 13/15 at
+# 2048, average attempts 1.87 -> 1.13, and total LLM calls 71 -> 49. Cost per
+# request rose 24% ($0.0092 -> $0.0114) while 2048 came out cheaper than 1024
+# ($0.0129), because the larger budget removed more refinement rounds than it
+# added in thinking tokens. Latency roughly doubled (10.3s -> 20.9s), which is
+# the real price; HEDIT_ANNOTATION_THINKING_BUDGET=0 turns it off for
+# latency-sensitive deployments.
+DEFAULT_ANNOTATION_THINKING_BUDGET = 2048
+
 # Models that still accept sampling parameters. Sonnet 5 rejects
 # `temperature` with a 400 (sampling params are removed on Claude 5 models).
 _SAMPLING_MODELS = {"claude-haiku-4-5"}
@@ -114,6 +128,101 @@ def normalize_model(model: str | None) -> str:
     return resolved
 
 
+def _validate_thinking(thinking: dict[str, Any], model: str, max_tokens: int) -> None:
+    """Check a thinking configuration against what the model accepts.
+
+    The API enforces different shapes per generation, and a mismatch is a
+    400 at request time: Sonnet 5 rejects thinking.type "enabled" ("Use
+    thinking.type adaptive"), while Haiku 4.5 has no adaptive mode and needs
+    an explicit token budget.
+
+    Args:
+        thinking: Thinking configuration to check
+        model: Resolved first-party model id
+        max_tokens: Maximum tokens for the request
+
+    Raises:
+        ValueError: If the configuration is not valid for this model
+    """
+    kind = thinking.get("type")
+
+    if model in _ADAPTIVE_THINKING_MODELS:
+        if kind not in ("adaptive", "disabled"):
+            raise ValueError(
+                f"{model} accepts thinking type 'adaptive' or 'disabled', not {kind!r}; "
+                "budget_tokens was removed on this model generation"
+            )
+        return
+
+    if kind == "disabled":
+        # Accepted (verified against the endpoint) and redundant on these
+        # models, but it lets a caller express "off" the same way for every
+        # model instead of special-casing.
+        return
+
+    if kind != "enabled":
+        raise ValueError(
+            f"{model} has no adaptive thinking mode; enable it with "
+            '{"type": "enabled", "budget_tokens": N}, disable it with '
+            '{"type": "disabled"}, or leave thinking unset'
+        )
+
+    budget = thinking.get("budget_tokens")
+    if not isinstance(budget, int) or budget < MIN_THINKING_BUDGET_TOKENS:
+        raise ValueError(
+            f"budget_tokens must be an integer of at least "
+            f"{MIN_THINKING_BUDGET_TOKENS}, got {budget!r}"
+        )
+    if budget >= max_tokens:
+        raise ValueError(
+            f"budget_tokens ({budget}) must be below max_tokens ({max_tokens}); "
+            "thinking tokens are drawn from the same budget as the response"
+        )
+
+
+def annotation_thinking(model: str | None = None) -> dict[str, Any] | None:
+    """Thinking configuration for the annotation role.
+
+    Reasoning measurably improves first-attempt validity on the annotation
+    agent, which is worth paying for because every failed attempt costs
+    another full annotate/validate/evaluate round. The support roles are
+    unaffected: reasoning there added latency without quality (#150).
+
+    Set HEDIT_ANNOTATION_THINKING_BUDGET to a token count to change the
+    budget, or to 0 (or "off") to disable thinking entirely.
+
+    Args:
+        model: Model the annotation LLM will use (default model if None)
+
+    Returns:
+        A thinking configuration for the model, or None when disabled
+
+    Raises:
+        ValueError: If the environment override is not an integer or "off"
+    """
+    resolved_model = normalize_model(model)
+
+    raw = os.getenv("HEDIT_ANNOTATION_THINKING_BUDGET")
+    if raw is not None and raw.strip().lower() in ("0", "off", "false", "none"):
+        return None
+
+    if resolved_model in _ADAPTIVE_THINKING_MODELS:
+        # Adaptive is the only on-mode on this generation; the model decides
+        # how much to think, so the budget value does not apply.
+        return {"type": "adaptive"}
+
+    budget = DEFAULT_ANNOTATION_THINKING_BUDGET
+    if raw is not None:
+        try:
+            budget = int(raw)
+        except ValueError as exc:
+            raise ValueError(
+                f"HEDIT_ANNOTATION_THINKING_BUDGET must be an integer or 'off', got {raw!r}"
+            ) from exc
+
+    return {"type": "enabled", "budget_tokens": budget}
+
+
 def create_anthropic_llm(
     model: str | None = None,
     api_key: str | None = None,
@@ -124,6 +233,7 @@ def create_anthropic_llm(
     timeout: float = 60.0,
     role: str = "unspecified",
     cache_ttl: str | None = None,
+    thinking: dict[str, Any] | None = None,
 ) -> BaseChatModel:
     """Create a Claude LLM instance with prompt caching.
 
@@ -151,12 +261,21 @@ def create_anthropic_llm(
             token and cache usage; has no effect on the request itself.
         cache_ttl: Prompt-cache lifetime, "5m" (default) or "1h". Falls back
             to the HEDIT_PROMPT_CACHE_TTL environment variable when None.
+        thinking: Explicit extended-thinking configuration, overriding
+            disable_reasoning. The accepted shape depends on the model, and
+            the API is strict about it: Sonnet 5 takes
+            {"type": "adaptive"} or {"type": "disabled"} and rejects
+            "enabled"; Haiku 4.5 takes
+            {"type": "enabled", "budget_tokens": N} with N at least 1024 and
+            below max_tokens. Enabling thinking also drops `temperature`,
+            since the API only allows temperature 1 alongside thinking.
 
     Returns:
         LLM instance configured for the Claude Messages API
 
     Raises:
-        ValueError: If the model is not offered or the TTL is not supported
+        ValueError: If the model is not offered, the TTL is not supported, or
+            the thinking configuration is not valid for the model
         RuntimeError: If server mode is used without ANTHROPIC_API_KEY set
     """
     from langchain_anthropic import ChatAnthropic
@@ -188,10 +307,20 @@ def create_anthropic_llm(
         if workspace_id:
             kwargs["default_headers"] = {"anthropic-workspace-id": workspace_id}
 
-    if resolved_model in _SAMPLING_MODELS:
+    resolved_max_tokens = max_tokens or 8000
+
+    if thinking is not None:
+        _validate_thinking(thinking, resolved_model, resolved_max_tokens)
+        kwargs["thinking"] = thinking
+
+    thinking_on = thinking is not None and thinking.get("type") != "disabled"
+
+    # The API rejects any temperature but 1 when thinking is enabled, so the
+    # sampling setting is dropped rather than silently causing a 400.
+    if resolved_model in _SAMPLING_MODELS and not thinking_on:
         kwargs["temperature"] = temperature
 
-    if disable_reasoning:
+    if disable_reasoning and thinking is None:
         if resolved_model in _ADAPTIVE_THINKING_MODELS:
             kwargs["thinking"] = {"type": "disabled"}
         elif resolved_model in _ALWAYS_THINKING_MODELS:
@@ -199,7 +328,7 @@ def create_anthropic_llm(
 
     llm = ChatAnthropic(
         model=resolved_model,
-        max_tokens=max_tokens or 8000,
+        max_tokens=resolved_max_tokens,
         timeout=timeout,
         **kwargs,
     )

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/src/validation/hed_validator.py

@@ -16,7 +16,7 @@ from pathlib import Path
 from typing import Literal
 
 from hed import HedString
-from hed.errors import get_printable_issue_string
+from hed.errors import ErrorSeverity, get_printable_issue_string
 from hed.schema import HedSchema, load_schema_version
 from hed.validator import HedValidator
 
@@ -167,8 +167,15 @@ class HedPythonValidator:
             # Process issues
             for issue in issues:
                 issue_str = get_printable_issue_string([issue])
+                # hedtools reports severity as an ErrorSeverity enum
+                # (ERROR=1, WARNING=10), never the string "error". Comparing
+                # it to "error" was always False, so every error was filed as
+                # a warning and is_valid was always True: "NotARealTag/Foo"
+                # validated clean and the workflow's refinement loop could
+                # never fire (#161). Anything not explicitly a warning counts
+                # as an error, so an unrecognized severity fails closed.
                 severity: Literal["error", "warning"] = (
-                    "error" if issue["severity"] == "error" else "warning"
+                    "warning" if issue.get("severity") == ErrorSeverity.WARNING else "error"
                 )
 
                 validation_issue = ValidationIssue(

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/src/version.py

@@ -1,6 +1,6 @@
 """Version information for HEDit."""
 
-__version__ = "0.7.11.dev5"
+__version__ = "0.7.11.dev7"
 __version_info__ = (0, 7, 11, "dev")
 
 

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/tests/test_anthropic_llm.py

@@ -7,8 +7,10 @@ from langchain_core.outputs import ChatGeneration, ChatResult
 from src.utils import anthropic_llm
 from src.utils.anthropic_llm import (
     ALLOWED_MODELS,
+    DEFAULT_ANNOTATION_THINKING_BUDGET,
     DEFAULT_MODEL,
     CachingLLMWrapper,
+    annotation_thinking,
     create_anthropic_llm,
     normalize_model,
 )
@@ -305,3 +307,145 @@ class TestCacheTtl:
         monkeypatch.setenv("HEDIT_PROMPT_CACHE_TTL", "forever")
         with pytest.raises(ValueError, match="Unsupported prompt cache TTL"):
             create_anthropic_llm()
+
+
+class TestThinkingConfiguration:
+    """Tests for the explicit thinking knob.
+
+    The shapes asserted here are the ones the API actually enforces, checked
+    against the live endpoint: Haiku 4.5 needs an explicit budget and refuses
+    any temperature but 1 alongside thinking; Sonnet 5 rejects
+    thinking.type "enabled" and wants "adaptive".
+    """
+
+    @pytest.fixture(autouse=True)
+    def server_key(self, monkeypatch):
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "server-key")
+
+    def test_haiku_takes_a_budget(self):
+        llm = create_anthropic_llm(
+            model="claude-haiku-4-5",
+            thinking={"type": "enabled", "budget_tokens": 1024},
+            enable_caching=False,
+        )
+        assert llm.thinking == {"type": "enabled", "budget_tokens": 1024}
+
+    def test_temperature_is_dropped_when_thinking_is_on(self):
+        """The API allows only temperature 1 with thinking, so it is omitted."""
+        llm = create_anthropic_llm(
+            model="claude-haiku-4-5",
+            temperature=0.1,
+            thinking={"type": "enabled", "budget_tokens": 1024},
+            enable_caching=False,
+        )
+        assert llm.temperature is None
+
+    def test_temperature_survives_thinking_disabled(self):
+        llm = create_anthropic_llm(
+            model="claude-haiku-4-5",
+            temperature=0.1,
+            thinking={"type": "disabled"},
+            enable_caching=False,
+        )
+        assert llm.temperature == 0.1
+
+    def test_sonnet_takes_adaptive(self):
+        llm = create_anthropic_llm(
+            model="claude-sonnet-5", thinking={"type": "adaptive"}, enable_caching=False
+        )
+        assert llm.thinking == {"type": "adaptive"}
+
+    def test_sonnet_rejects_budget_style_thinking(self):
+        with pytest.raises(ValueError, match="adaptive"):
+            create_anthropic_llm(
+                model="claude-sonnet-5",
+                thinking={"type": "enabled", "budget_tokens": 1024},
+                enable_caching=False,
+            )
+
+    def test_haiku_rejects_adaptive(self):
+        with pytest.raises(ValueError, match="no adaptive thinking mode"):
+            create_anthropic_llm(
+                model="claude-haiku-4-5", thinking={"type": "adaptive"}, enable_caching=False
+            )
+
+    def test_budget_below_minimum_rejected(self):
+        with pytest.raises(ValueError, match="at least 1024"):
+            create_anthropic_llm(
+                model="claude-haiku-4-5",
+                thinking={"type": "enabled", "budget_tokens": 512},
+                enable_caching=False,
+            )
+
+    def test_budget_must_fit_under_max_tokens(self):
+        with pytest.raises(ValueError, match="must be below max_tokens"):
+            create_anthropic_llm(
+                model="claude-haiku-4-5",
+                max_tokens=2000,
+                thinking={"type": "enabled", "budget_tokens": 2000},
+                enable_caching=False,
+            )
+
+    def test_explicit_thinking_overrides_disable_reasoning(self):
+        llm = create_anthropic_llm(
+            model="claude-sonnet-5",
+            disable_reasoning=True,
+            thinking={"type": "adaptive"},
+            enable_caching=False,
+        )
+        assert llm.thinking == {"type": "adaptive"}
+
+
+class TestAnnotationThinking:
+    """Tests for the annotation role's thinking policy."""
+
+    @pytest.fixture(autouse=True)
+    def clean_env(self, monkeypatch):
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "server-key")
+        monkeypatch.delenv("HEDIT_ANNOTATION_THINKING_BUDGET", raising=False)
+
+    def test_default_budget_on_haiku(self):
+        assert annotation_thinking("claude-haiku-4-5") == {
+            "type": "enabled",
+            "budget_tokens": DEFAULT_ANNOTATION_THINKING_BUDGET,
+        }
+
+    def test_default_model_gets_a_budget(self):
+        assert annotation_thinking()["type"] == "enabled"
+
+    def test_adaptive_model_ignores_the_budget(self):
+        """Sonnet 5 decides its own depth; budget_tokens is rejected there."""
+        assert annotation_thinking("claude-sonnet-5") == {"type": "adaptive"}
+
+    def test_env_override_sets_the_budget(self, monkeypatch):
+        monkeypatch.setenv("HEDIT_ANNOTATION_THINKING_BUDGET", "4096")
+        assert annotation_thinking("claude-haiku-4-5")["budget_tokens"] == 4096
+
+    def test_env_can_disable_thinking(self, monkeypatch):
+        for value in ("0", "off", "false", "none", "OFF"):
+            monkeypatch.setenv("HEDIT_ANNOTATION_THINKING_BUDGET", value)
+            assert annotation_thinking("claude-haiku-4-5") is None
+            assert annotation_thinking("claude-sonnet-5") is None
+
+    def test_bad_env_value_is_rejected(self, monkeypatch):
+        monkeypatch.setenv("HEDIT_ANNOTATION_THINKING_BUDGET", "lots")
+        with pytest.raises(ValueError, match="must be an integer or 'off'"):
+            annotation_thinking("claude-haiku-4-5")
+
+    def test_legacy_model_id_is_normalized(self):
+        assert annotation_thinking("anthropic/claude-haiku-4.5")["type"] == "enabled"
+
+    def test_policy_produces_a_usable_llm(self):
+        """The default policy must satisfy the factory's own validation."""
+        llm = create_anthropic_llm(
+            model="claude-haiku-4-5",
+            thinking=annotation_thinking("claude-haiku-4-5"),
+            enable_caching=False,
+        )
+        assert llm.thinking["budget_tokens"] == DEFAULT_ANNOTATION_THINKING_BUDGET
+        # Thinking forces temperature off, which the API requires.
+        assert llm.temperature is None
+
+    def test_budget_fits_under_the_default_max_tokens(self):
+        """A budget above max_tokens would 400 at request time."""
+        assert DEFAULT_ANNOTATION_THINKING_BUDGET < 8000

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/tests/test_api_endpoints.py

@@ -1469,3 +1469,84 @@ class TestMetricsEndpoint:
         )
         assert response.status_code == 403
         assert "server API key" in response.json()["detail"]
+
+
+class TestLLMErrorMessages:
+    """Error responses classify the failure without quoting the provider.
+
+    CodeQL flagged the streaming error path (py/stack-trace-exposure) because
+    exception text reached the client. The web app renders these messages as
+    HTML, and a provider error can echo request details, so every branch has
+    to return a fixed string.
+    """
+
+    @staticmethod
+    def _response(status: int):
+        import httpx
+
+        request = httpx.Request("POST", "https://api.anthropic.com/v1/messages")
+        return httpx.Response(status, request=request)
+
+    def test_bad_request_does_not_quote_the_provider(self):
+        import anthropic
+
+        from src.api.main import _describe_llm_error
+
+        detail = (
+            "Error code: 400 - thinking.type.enabled is not supported for this model; "
+            "workspace wrkspc_01Rayuq1JvjaMYusRvUsn6vk"
+        )
+        exc = anthropic.BadRequestError(detail, response=self._response(400), body=None)
+
+        status, error_type, message = _describe_llm_error(exc)
+
+        assert status == 400
+        assert error_type == "bad_request"
+        assert "wrkspc_01Rayuq1JvjaMYusRvUsn6vk" not in message
+        assert "thinking.type.enabled" not in message
+        assert "Error code" not in message
+
+    def test_context_overflow_still_precedes_bad_request(self):
+        from langchain_anthropic.chat_models import AnthropicContextOverflowError
+
+        from src.api.main import _describe_llm_error
+
+        exc = AnthropicContextOverflowError(
+            "prompt is too long: 250000 tokens > 200000 maximum",
+            response=self._response(400),
+            body=None,
+        )
+
+        status, error_type, _message = _describe_llm_error(exc)
+
+        assert status == 413
+        assert error_type == "context_overflow"
+
+    def test_auth_failure_points_at_the_key(self):
+        import anthropic
+
+        from src.api.main import _describe_llm_error
+
+        exc = anthropic.AuthenticationError(
+            "invalid x-api-key sk-ant-api03-secretmaterial",
+            response=self._response(401),
+            body=None,
+        )
+
+        status, error_type, message = _describe_llm_error(exc)
+
+        assert status == 401
+        assert error_type == "auth"
+        assert "sk-ant-api03-secretmaterial" not in message
+
+    def test_unknown_failure_is_generic(self):
+        from src.api.main import _describe_llm_error
+
+        status, error_type, message = _describe_llm_error(
+            RuntimeError("Traceback (most recent call last): File /srv/hedit/main.py")
+        )
+
+        assert status == 500
+        assert error_type == "internal"
+        assert "Traceback" not in message
+        assert "/srv/hedit" not in message

{hedit-0.7.11.dev5 → hedit-0.7.11.dev7}/tests/test_validation.py

@@ -118,6 +118,57 @@ class TestHedPythonValidator:
         assert isinstance(result.errors, list)
 
 
+class TestSeverityMapping:
+    """Tests that hedtools severities map to the right bucket.
+
+    hedtools reports severity as an ErrorSeverity enum (ERROR=1,
+    WARNING=10). Comparing it to the string "error" is always False, which
+    filed every error as a warning and left is_valid True for any input --
+    "NotARealTag/Foo" validated clean and the workflow's refinement loop
+    could never fire (#161).
+    """
+
+    def test_unknown_tag_is_an_error(self, validator):
+        result = validator.validate("Sensory-event, NotARealTag/Foo")
+
+        assert result.is_valid is False
+        assert [issue.code for issue in result.errors] == ["TAG_INVALID"]
+        assert result.warnings == []
+
+    def test_non_base_tag_is_an_error(self, validator):
+        """A plausible-looking tag that is not in the schema still fails."""
+        result = validator.validate("Agent-action, (Press, Button)")
+
+        assert result.is_valid is False
+        assert any(issue.code == "TAG_INVALID" for issue in result.errors)
+
+    def test_repeated_tag_is_an_error(self, validator):
+        result = validator.validate("Sensory-event, Sensory-event")
+
+        assert result.is_valid is False
+        assert any(issue.code == "TAG_EXPRESSION_REPEATED" for issue in result.errors)
+
+    def test_tag_extension_is_a_warning(self, validator):
+        """Extensions are allowed, so they must not invalidate the string."""
+        result = validator.validate("Sensory-event, Animal/Dog")
+
+        assert result.is_valid is True
+        assert result.errors == []
+        assert [issue.code for issue in result.warnings] == ["TAG_EXTENDED"]
+
+    def test_clean_string_has_no_issues(self, validator):
+        result = validator.validate("Sensory-event, Visual-presentation")
+
+        assert result.is_valid is True
+        assert result.errors == []
+        assert result.warnings == []
+
+    def test_errors_carry_their_level(self, validator):
+        result = validator.validate("Sensory-event, NotARealTag/Foo")
+
+        assert all(issue.level == "error" for issue in result.errors)
+
+
 class TestHedJavaScriptValidator:
     """Tests for HedJavaScriptValidator class."""
 
@@ -189,14 +240,12 @@ def test_validate_valid_string(validator):
 
 
 def test_validate_invalid_tag(validator):
-    """Test validation of invalid tag.
-
-    Note: HED 8.3.0+ reports invalid tags as warnings, not errors.
-    """
+    """An unknown tag is an error, so the string is invalid."""
     result = validator.validate("Invalid-nonexistent-tag")
 
-    # Invalid tags may be reported as warnings in newer HED versions
-    assert result.is_valid is False or len(result.warnings) > 0
+    assert result.is_valid is False
+    assert len(result.errors) >= 1
+    assert result.errors[0].code == "TAG_INVALID"
 
 
 def test_validate_with_grouping(validator):