hedit 0.7.6.dev2__tar.gz → 0.7.6.dev4__tar.gz

{hedit-0.7.6.dev2/hedit.egg-info → hedit-0.7.6.dev4}/PKG-INFO

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

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4/hedit.egg-info}/PKG-INFO

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

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/pyproject.toml

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

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/agents/annotation_agent.py

@@ -12,7 +12,7 @@ from langchain_core.messages import HumanMessage, SystemMessage
 
 from src.agents.state import HedAnnotationState
 from src.utils import extract_text_content
-from src.utils.hed_comprehensive_guide import get_comprehensive_hed_guide
+from src.utils.hed_comprehensive_guide import format_semantic_hints, get_comprehensive_hed_guide
 from src.utils.json_schema_loader import HedJsonSchemaLoader, load_latest_schema
 
 logger = logging.getLogger(__name__)
@@ -60,21 +60,23 @@ class AnnotationAgent:
         self,
         vocabulary: list[str],
         extendable_tags: list[str],
-        semantic_hints: list[dict] | None = None,
         no_extend: bool = False,
     ) -> str:
         """Build the system prompt for the annotation agent.
 
+        The system prompt is static per schema version (vocabulary + rules)
+        to enable prompt caching across requests. Semantic hints are placed
+        in the user prompt instead.
+
         Args:
             vocabulary: List of valid short-form HED tags
             extendable_tags: Tags that allow extension
-            semantic_hints: Optional semantic search results with relevant tags
             no_extend: If True, prohibit tag extensions
 
         Returns:
             Complete system prompt with all HED rules
         """
-        return get_comprehensive_hed_guide(vocabulary, extendable_tags, semantic_hints, no_extend)
+        return get_comprehensive_hed_guide(vocabulary, extendable_tags, no_extend)
 
     def _format_tag_suggestions(self, tag_suggestions: dict[str, list[str]]) -> str:
         """Format tag suggestions into a clear instruction block.
@@ -98,24 +100,46 @@ class AnnotationAgent:
                 )
         return "\n".join(lines)
 
+    def _format_semantic_hints(self, semantic_hints: list[dict] | None) -> str:
+        """Format semantic hints for inclusion in the user prompt.
+
+        Args:
+            semantic_hints: List of hint dicts with tag, score, source keys
+
+        Returns:
+            Formatted hints section, or empty string if no hints
+        """
+        if not semantic_hints:
+            return ""
+
+        logger.debug("Including %d semantic hints in user prompt", len(semantic_hints))
+        return "\n" + format_semantic_hints(semantic_hints)
+
     def _build_user_prompt(
         self,
         description: str,
         validation_errors: list[str] | None = None,
         tag_suggestions: dict[str, list[str]] | None = None,
         previous_annotation: str | None = None,
+        semantic_hints: list[dict] | None = None,
     ) -> str:
         """Build the user prompt for annotation.
 
+        Semantic hints are included here (not in system prompt) so the
+        system prompt stays static and cacheable across requests.
+
         Args:
             description: Natural language event description
             validation_errors: Previous validation errors (if retrying)
             tag_suggestions: LSP-suggested valid tags for invalid tags
             previous_annotation: The previous annotation attempt (for targeted correction)
+            semantic_hints: Optional semantic search hints for relevant tags
 
         Returns:
             User prompt string
         """
+        hints_str = self._format_semantic_hints(semantic_hints)
+
         if validation_errors:
             errors_str = "\n".join(f"- {error}" for error in validation_errors)
             suggestions_str = self._format_tag_suggestions(tag_suggestions or {})
@@ -133,12 +157,12 @@ class AnnotationAgent:
 
 Fix these errors and generate a corrected HED annotation for:
 {description}
-
+{hints_str}
 {replacement_note}CRITICAL: Output ONLY the raw HED annotation string."""
 
         return f"""Generate a HED annotation for this event description:
 {description}
-
+{hints_str}
 CRITICAL: Output ONLY the raw HED annotation string."""
 
     async def annotate(self, state: HedAnnotationState) -> dict:
@@ -170,17 +194,16 @@ CRITICAL: Output ONLY the raw HED annotation string."""
             # Use empty list - LLM will still generate valid annotations
             extendable_tags = []
 
-        # Build prompts with complete HED rules (including semantic hints if available)
-        semantic_hints = state.get("semantic_hints", [])
+        # Build system prompt with HED rules (static per schema version for caching)
         no_extend = state.get("no_extend", False)
         system_prompt = self._build_system_prompt(
             vocabulary,
             extendable_tags,
-            semantic_hints if semantic_hints else None,
             no_extend,
         )
 
-        # Build user prompt with any feedback (use augmented errors with remediation for LLM)
+        # Build user prompt with feedback and semantic hints
+        semantic_hints = state.get("semantic_hints", [])
         feedbacks = []
         if state.get("validation_errors_augmented"):
             feedbacks.extend(state["validation_errors_augmented"])
@@ -200,6 +223,7 @@ CRITICAL: Output ONLY the raw HED annotation string."""
             feedbacks or None,
             tag_suggestions or None,
             previous_annotation,
+            semantic_hints if semantic_hints else None,
         )
 
         # Generate annotation

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/api/main.py

@@ -113,8 +113,8 @@ def create_openrouter_workflow(
     # Apply defaults from environment
     default_annotation_model = os.getenv("ANNOTATION_MODEL", "anthropic/claude-haiku-4.5")
     default_annotation_provider = os.getenv("ANNOTATION_PROVIDER", "anthropic")
-    default_eval_model = os.getenv("EVALUATION_MODEL", "openai/gpt-oss-120b")
-    default_eval_provider = os.getenv("EVALUATION_PROVIDER", "groq")
+    default_eval_model = os.getenv("EVALUATION_MODEL", "qwen/qwen3.5-397b-a17b")
+    default_eval_provider = os.getenv("EVALUATION_PROVIDER")
 
     # Resolve final values: parameter > env var > default
     actual_annotation_model = get_model_name(annotation_model or default_annotation_model)
@@ -240,8 +240,8 @@ def create_byok_vision_agent(
         Configured VisionAgent using the user's key and model settings
     """
     # Use user-provided settings or fall back to server defaults
-    default_vision_model = os.getenv("VISION_MODEL", "qwen/qwen3-vl-30b-a3b-instruct")
-    default_vision_provider = os.getenv("VISION_PROVIDER", "deepinfra/fp8")
+    default_vision_model = os.getenv("VISION_MODEL", "qwen/qwen3-vl-32b-instruct")
+    default_vision_provider = os.getenv("VISION_PROVIDER", "novita")
 
     actual_model = vision_model if vision_model else default_vision_model
     actual_temperature = temperature if temperature is not None else 0.3
@@ -354,7 +354,7 @@ async def lifespan(app: FastAPI):
         # Log configuration (env vars are read by create_openrouter_workflow)
         print("Using OpenRouter with models:")
         print(f"  Annotation: {os.getenv('ANNOTATION_MODEL', 'anthropic/claude-haiku-4.5')}")
-        print(f"  Evaluation: {os.getenv('EVALUATION_MODEL', 'qwen/qwen3-235b-a22b-2507')}")
+        print(f"  Evaluation: {os.getenv('EVALUATION_MODEL', 'qwen/qwen3.5-397b-a17b')}")
         print(f"  Provider (annotation): {os.getenv('ANNOTATION_PROVIDER', 'anthropic')}")
         print(f"  Provider (eval): {os.getenv('EVALUATION_PROVIDER', '') or '(auto-routed)'}")
 
@@ -395,8 +395,8 @@ async def lifespan(app: FastAPI):
 
     # Initialize vision agent (only for OpenRouter)
     if llm_provider == "openrouter":
-        vision_model = os.getenv("VISION_MODEL", "qwen/qwen3-vl-30b-a3b-instruct")
-        vision_provider = os.getenv("VISION_PROVIDER", "deepinfra/fp8")
+        vision_model = os.getenv("VISION_MODEL", "qwen/qwen3-vl-32b-instruct")
+        vision_provider = os.getenv("VISION_PROVIDER", "novita")
 
         print(f"Initializing vision model: {vision_model} (provider: {vision_provider})")
 
@@ -666,7 +666,7 @@ async def annotate(
             model_name = (
                 request.model
                 or req.headers.get("x-openrouter-model")
-                or os.getenv("ANNOTATION_MODEL", "openai/gpt-oss-120b")
+                or os.getenv("ANNOTATION_MODEL", "anthropic/claude-haiku-4.5")
             )
             temperature = request.temperature
             if temperature is None:
@@ -815,7 +815,7 @@ async def annotate_from_image(
                 validator_path=_byok_config.get("validator_path"),
                 use_js_validator=_byok_config.get("use_js_validator", True),
             )
-            # Note: Vision agent uses its own provider (deepinfra/fp8 for qwen-vl)
+            # Note: Vision agent uses its own provider (novita for qwen-vl)
             # Only pass provider_override to vision if a custom vision_model was specified
             vision_provider = provider_override if vision_model_override else None
             active_vision_agent = create_byok_vision_agent(
@@ -877,7 +877,7 @@ async def annotate_from_image(
             model_name = (
                 request.model
                 or req.headers.get("x-openrouter-model")
-                or os.getenv("ANNOTATION_MODEL", "openai/gpt-oss-120b")
+                or os.getenv("ANNOTATION_MODEL", "anthropic/claude-haiku-4.5")
             )
             temperature = request.temperature
             if temperature is None:
@@ -967,7 +967,7 @@ async def _collect_stream_telemetry(
     model_name = (
         request.model
         or req.headers.get("x-openrouter-model")
-        or os.getenv("ANNOTATION_MODEL", "openai/gpt-oss-120b")
+        or os.getenv("ANNOTATION_MODEL", "anthropic/claude-haiku-4.5")
     )
     temperature = request.temperature
     if temperature is None:
@@ -1386,7 +1386,7 @@ async def annotate_from_image_stream(
                 validator_path=_byok_config.get("validator_path"),
                 use_js_validator=_byok_config.get("use_js_validator", True),
             )
-            # Note: Vision agent uses its own provider (deepinfra/fp8 for qwen-vl)
+            # Note: Vision agent uses its own provider (novita for qwen-vl)
             # Only pass provider_override to vision if a custom vision_model was specified
             vision_provider = provider_override if vision_model_override else None
             active_vision_agent = create_byok_vision_agent(
@@ -1785,7 +1785,7 @@ async def submit_feedback(request: FeedbackRequest) -> FeedbackResponse:
                 )
 
                 # Create LLM for triage
-                model = os.getenv("ANNOTATION_MODEL", "openai/gpt-oss-120b")
+                model = os.getenv("ANNOTATION_MODEL", "anthropic/claude-haiku-4.5")
                 provider = os.getenv("LLM_PROVIDER_PREFERENCE", "")
                 llm = create_openrouter_llm(
                     model=model,

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/api/models.py

@@ -41,7 +41,7 @@ class AnnotationRequest(BaseModel):
     model: str | None = Field(
         default=None,
         description="Override model for annotation (BYOK mode only, e.g., 'openai/gpt-4o')",
-        examples=["openai/gpt-4o", "anthropic/claude-3.5-sonnet", "qwen/qwen3-235b-a22b-2507"],
+        examples=["anthropic/claude-haiku-4.5", "qwen/qwen3.5-122b-a10b", "qwen/qwen3.5-397b-a17b"],
     )
     provider: str | None = Field(
         default=None,
@@ -177,7 +177,7 @@ class ImageAnnotationRequest(BaseModel):
     vision_model: str | None = Field(
         default=None,
         description="Override vision model for image description (BYOK mode only)",
-        examples=["qwen/qwen3-vl-30b-a3b-instruct", "openai/gpt-4o"],
+        examples=["qwen/qwen3-vl-32b-instruct", "qwen/qwen3-vl-235b-a22b-instruct"],
     )
     provider: str | None = Field(
         default=None,

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/cli/config.py

@@ -41,13 +41,13 @@ DEFAULT_DEV_API_URL = "https://api.annotation.garden/hedit-dev"
 DEFAULT_MODEL = "anthropic/claude-haiku-4.5"
 DEFAULT_PROVIDER = "anthropic"
 
-# Evaluation model: Qwen3-235B (auto-routed by OpenRouter)
-DEFAULT_EVAL_MODEL = "qwen/qwen3-235b-a22b-2507"
+# Evaluation model: Qwen3.5-397B MoE (most capable Qwen, high throughput)
+DEFAULT_EVAL_MODEL = "qwen/qwen3.5-397b-a17b"
 DEFAULT_EVAL_PROVIDER = None
 
-# Vision model: Qwen3-VL for image descriptions
-DEFAULT_VISION_MODEL = "qwen/qwen3-vl-30b-a3b-instruct"
-DEFAULT_VISION_PROVIDER = "deepinfra/fp8"
+# Vision model: Qwen3-VL-32B for image descriptions
+DEFAULT_VISION_MODEL = "qwen/qwen3-vl-32b-instruct"
+DEFAULT_VISION_PROVIDER = None
 
 
 class CredentialsConfig(BaseModel):

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/cli/local_executor.py

@@ -77,11 +77,10 @@ class LocalExecutionBackend(ExecutionBackend):
 
         Args:
             api_key: OpenRouter API key (required for LLM operations, optional for health/validate)
-            model: Model for text annotation (default: openai/gpt-oss-120b)
-            eval_model: Model for evaluation/assessment agents (default: same as model).
-                       Use a consistent model like qwen/qwen3-235b-a22b for fair benchmarking.
-            eval_provider: Provider for evaluation model (e.g., Cerebras for qwen models)
-            vision_model: Model for image annotation (default: qwen/qwen3-vl-30b-a3b-instruct)
+            model: Model for text annotation (default: anthropic/claude-haiku-4.5)
+            eval_model: Model for evaluation/assessment agents (default: qwen/qwen3.5-397b-a17b)
+            eval_provider: Provider for evaluation model (None = OpenRouter auto-routes)
+            vision_model: Model for image annotation (default: qwen/qwen3-vl-32b-instruct)
             provider: Provider preference (cleared if custom model specified)
             temperature: LLM temperature (0.0-1.0)
             schema_dir: Optional directory with JSON schemas (None = fetch from GitHub)

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/cli/main.py

@@ -102,7 +102,7 @@ ModelOption = Annotated[
     typer.Option(
         "--model",
         "-m",
-        help="Model to use (e.g., openai/gpt-oss-120b, gpt-4o-mini)",
+        help="Model to use (e.g., anthropic/claude-haiku-4.5, qwen/qwen3.5-122b-a10b)",
     ),
 ]
 

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/scripts/process_feedback.py

@@ -56,7 +56,7 @@ async def process_feedback_file(
         sys.exit(1)
 
     # Get model configuration from environment
-    model = os.getenv("ANNOTATION_MODEL", "openai/gpt-oss-120b")
+    model = os.getenv("ANNOTATION_MODEL", "anthropic/claude-haiku-4.5")
     provider = os.getenv("LLM_PROVIDER_PREFERENCE", "")
 
     # Create LLM

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/utils/hed_comprehensive_guide.py

@@ -10,8 +10,8 @@ assembles them into the full system prompt.
 """
 
 
-def _format_semantic_hints(hints: list[dict]) -> str:
-    """Format semantic hints for inclusion in the guide.
+def format_semantic_hints(hints: list[dict]) -> str:
+    """Format semantic hints for inclusion in the user prompt.
 
     Args:
         hints: List of semantic search results, each with:
@@ -21,7 +21,7 @@ def _format_semantic_hints(hints: list[dict]) -> str:
               - prefix: Optional library prefix (e.g., "sc:")
 
     Returns:
-        Formatted hints section for the guide
+        Formatted hints section for the user prompt
     """
     if not hints:
         return ""
@@ -33,6 +33,8 @@ def _format_semantic_hints(hints: list[dict]) -> str:
 
     for hint in hints:
         tag = hint.get("tag", "")
+        if not tag:
+            continue
         prefix = hint.get("prefix", "")
         score = hint.get("score", 0)
         full_tag = f"{prefix}{tag}" if prefix else tag
@@ -45,7 +47,7 @@ def _format_semantic_hints(hints: list[dict]) -> str:
             low_conf.append(full_tag)
 
     lines = [
-        "## POTENTIALLY RELEVANT TAGS",
+        "## SEMANTIC HINTS",
         "",
         "Based on your description, these schema tags may be relevant.",
         "Note: this list may contain false positives - use your judgment.",
@@ -974,7 +976,6 @@ Just output the raw HED annotation string directly.
 def get_comprehensive_hed_guide(
     vocabulary_sample: list[str],
     extendable_tags: list[str],
-    semantic_hints: list[dict] | None = None,
     no_extend: bool = False,
 ) -> str:
     """Generate comprehensive HED annotation guide.
@@ -983,11 +984,13 @@ def get_comprehensive_hed_guide(
     annotation agent. The guide includes vocabulary constraints, semantic
     rules, correction workflows, and output format instructions.
 
+    Note: Semantic hints are NOT included here to keep the system prompt
+    static across requests, enabling prompt caching. Hints are passed
+    in the user prompt instead.
+
     Args:
         vocabulary_sample: Full list of valid HED tags (complete vocabulary)
         extendable_tags: Tags that allow extension
-        semantic_hints: Optional list of semantically relevant tags from search
-                       Each dict has: tag, score, source, prefix (optional)
         no_extend: If True, add strict instructions to prohibit tag extensions
 
     Returns:
@@ -997,16 +1000,23 @@ def get_comprehensive_hed_guide(
     extend_str = ", ".join(extendable_tags) if not no_extend else "(Extensions disabled)"
 
     # Format optional sections
-    hints_section = _format_semantic_hints(semantic_hints) if semantic_hints else ""
     no_extend_warning = _build_no_extend_warning() if no_extend else ""
 
     # Assemble guide from modular sections
+    # Note: semantic hints are placed in the user prompt for cache efficiency
     sections = [
         "# HED ANNOTATION GUIDE\n",
         no_extend_warning,
         _build_vocabulary_check_section(),
         _build_correction_workflow_section(),
-        hints_section,
+        (
+            "## SEMANTIC HINTS\n\n"
+            "The user message may include a SEMANTIC HINTS section with "
+            "potentially relevant tags from schema search. If present, use "
+            "these as guidance for tag selection, but verify each against "
+            "the vocabulary. If no hints section is present, proceed without them.\n\n"
+            "---\n\n"
+        ),
         _build_semantic_rules_section(),
         _build_relation_tags_section(),
         _build_event_agent_section(),

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/utils/litellm_llm.py

@@ -29,7 +29,7 @@ from langchain_core.messages import BaseMessage
 
 
 def create_litellm_openrouter(
-    model: str = "openai/gpt-oss-120b",
+    model: str = "anthropic/claude-haiku-4.5",
     api_key: str | None = None,
     temperature: float = 0.1,
     max_tokens: int | None = None,

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/utils/openrouter_llm.py

@@ -13,7 +13,7 @@ from langchain_core.messages import BaseMessage
 
 
 def create_openrouter_llm(
-    model: str = "openai/gpt-oss-120b",
+    model: str = "anthropic/claude-haiku-4.5",
     api_key: str | None = None,
     temperature: float = 0.1,
     max_tokens: int | None = None,
@@ -28,7 +28,7 @@ def create_openrouter_llm(
     to include cache_control markers for 90% cost reduction on cache hits.
 
     Args:
-        model: Model identifier (e.g., "openai/gpt-oss-120b", "anthropic/claude-haiku-4.5")
+        model: Model identifier (e.g., "anthropic/claude-haiku-4.5", "qwen/qwen3.5-397b-a17b")
         api_key: OpenRouter API key (defaults to OPENROUTER_API_KEY env var)
         temperature: Sampling temperature (0.0-1.0)
         max_tokens: Maximum tokens to generate

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/src/version.py

@@ -1,6 +1,6 @@
 """Version information for HEDit."""
 
-__version__ = "0.7.6.dev2"
+__version__ = "0.7.6.dev4"
 __version_info__ = (0, 7, 6, "dev")
 
 

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/tests/test_annotation_agent.py

@@ -193,6 +193,132 @@ class TestBuildUserPrompt:
 
         assert "Previous annotation:" not in result
 
+    def test_first_pass_with_semantic_hints(self):
+        """Semantic hints should appear in the user prompt on first pass."""
+        agent = self._make_agent()
+        result = agent._build_user_prompt(
+            "A dog chasing a cat",
+            semantic_hints=[
+                {"tag": "Animal-agent", "score": 0.9, "source": "hed-lsp"},
+                {"tag": "Chase", "score": 0.7, "source": "hed-lsp"},
+            ],
+        )
+
+        assert "SEMANTIC HINTS" in result
+        assert "Animal-agent" in result
+        assert "Chase" in result
+        assert "A dog chasing a cat" in result
+
+    def test_correction_pass_with_semantic_hints(self):
+        """Semantic hints should also appear in correction prompts."""
+        agent = self._make_agent()
+        result = agent._build_user_prompt(
+            "A dog chasing a cat",
+            validation_errors=["[TAG_INVALID] 'Chase' is not valid"],
+            semantic_hints=[
+                {"tag": "Animal-agent", "score": 0.9, "source": "hed-lsp"},
+            ],
+        )
+
+        assert "SEMANTIC HINTS" in result
+        assert "Animal-agent" in result
+        assert "TAG_INVALID" in result
+
+    def test_no_hints_no_hints_section(self):
+        """No hints should not add a hints section to the user prompt."""
+        agent = self._make_agent()
+        result = agent._build_user_prompt("A red circle")
+
+        assert "SEMANTIC HINTS" not in result
+
+    def test_empty_hints_no_hints_section(self):
+        """Empty hints list should not add a hints section."""
+        agent = self._make_agent()
+        result = agent._build_user_prompt("A red circle", semantic_hints=[])
+
+        assert "SEMANTIC HINTS" not in result
+
+
+class TestFormatSemanticHints:
+    """Tests for _format_semantic_hints method on AnnotationAgent."""
+
+    def _make_agent(self):
+        agent = object.__new__(AnnotationAgent)
+        return agent
+
+    def test_none_returns_empty(self):
+        """None input should return empty string."""
+        agent = self._make_agent()
+        assert agent._format_semantic_hints(None) == ""
+
+    def test_empty_list_returns_empty(self):
+        """Empty list should return empty string."""
+        agent = self._make_agent()
+        assert agent._format_semantic_hints([]) == ""
+
+    def test_valid_hints_returns_content(self):
+        """Valid hints should produce formatted output."""
+        agent = self._make_agent()
+        result = agent._format_semantic_hints(
+            [
+                {"tag": "Red", "score": 0.9, "source": "hed-lsp"},
+            ]
+        )
+
+        assert "SEMANTIC HINTS" in result
+        assert "Red" in result
+
+    def test_confidence_bucketing(self):
+        """Hints should be categorized by confidence level."""
+        agent = self._make_agent()
+        result = agent._format_semantic_hints(
+            [
+                {"tag": "HighTag", "score": 0.95, "source": "hed-lsp"},
+                {"tag": "MedTag", "score": 0.6, "source": "hed-lsp"},
+                {"tag": "LowTag", "score": 0.3, "source": "hed-lsp"},
+            ]
+        )
+
+        assert "High confidence" in result
+        assert "HighTag" in result
+        assert "Medium confidence" in result
+        assert "MedTag" in result
+        assert "Lower confidence" in result
+        assert "LowTag" in result
+
+    def test_skips_empty_tags(self):
+        """Hints with empty tag should be skipped."""
+        agent = self._make_agent()
+        result = agent._format_semantic_hints(
+            [
+                {"tag": "", "score": 0.9, "source": "hed-lsp"},
+                {"tag": "ValidTag", "score": 0.8, "source": "hed-lsp"},
+            ]
+        )
+
+        assert "ValidTag" in result
+
+
+class TestSystemPromptCaching:
+    """Tests that system prompt is static (no dynamic content) for caching."""
+
+    def test_system_prompt_has_hints_pointer_not_content(self):
+        """System prompt should reference hints but not contain actual hint data."""
+        from src.utils.hed_comprehensive_guide import get_comprehensive_hed_guide
+
+        guide = get_comprehensive_hed_guide(
+            vocabulary_sample=["Red", "Circle"],
+            extendable_tags=["Animal"],
+        )
+
+        # Should have the pointer section
+        assert "## SEMANTIC HINTS" in guide
+        assert "may include" in guide
+        # Should NOT contain dynamic hint content
+        assert "High confidence" not in guide
+        assert "Medium confidence" not in guide
+        assert "Lower confidence" not in guide
+
 
 class TestPromptSections:
     """Tests for prompt structure and sections."""

{hedit-0.7.6.dev2 → hedit-0.7.6.dev4}/tests/test_comprehensive_guide.py

@@ -45,38 +45,24 @@ class TestComprehensiveGuide:
         # Should show extensions as disabled
         assert "(Extensions disabled)" in guide
 
-    def test_guide_with_semantic_hints(self):
-        """Test guide generation with semantic hints."""
+    def test_guide_has_semantic_hints_pointer(self):
+        """Test guide includes a pointer to check user message for semantic hints."""
         vocabulary = ["Event", "Reward", "Animal-agent"]
         extendable_tags = ["Label"]
-        semantic_hints = [
-            {"tag": "Reward", "prefix": "", "score": 0.95, "source": "keyword"},
-            {"tag": "Animal-agent", "prefix": "", "score": 0.85, "source": "embedding"},
-        ]
-
-        guide = get_comprehensive_hed_guide(
-            vocabulary, extendable_tags, semantic_hints=semantic_hints
-        )
-
-        assert "POTENTIALLY RELEVANT TAGS" in guide
-        assert "Reward" in guide
-        assert "Animal-agent" in guide
-        # Check confidence indicators
-        assert "high" in guide.lower() or "0.95" in guide
-
-    def test_guide_with_semantic_hints_and_no_extend(self):
-        """Test guide with both semantic hints and no_extend."""
+
+        guide = get_comprehensive_hed_guide(vocabulary, extendable_tags)
+
+        # System prompt should point to user message for hints (not contain them)
+        assert "SEMANTIC HINTS" in guide
+        assert "user message" in guide.lower()
+
+    def test_guide_no_extend_with_hints_pointer(self):
+        """Test guide with no_extend has both hints pointer and extension warning."""
         vocabulary = ["Event", "Visual-presentation"]
         extendable_tags = ["Label"]
-        semantic_hints = [
-            {"tag": "Visual-presentation", "prefix": "", "score": 0.9, "source": "keyword"},
-        ]
 
-        guide = get_comprehensive_hed_guide(
-            vocabulary, extendable_tags, semantic_hints=semantic_hints, no_extend=True
-        )
+        guide = get_comprehensive_hed_guide(vocabulary, extendable_tags, no_extend=True)
 
-        # Should have both features
-        assert "POTENTIALLY RELEVANT TAGS" in guide
+        assert "SEMANTIC HINTS" in guide
         assert "EXTENSIONS STRICTLY PROHIBITED" in guide
         assert "(Extensions disabled)" in guide