Move semantic hints to user prompt for cross-request caching

[neuromechanist]

Summary

• Move semantic hints from system prompt to user prompt so the system prompt is static per schema version
• Add a pointer in the system prompt directing the LLM to check the user message for hints
• Update tests for the new prompt structure

Problem

Prompt caching broke between requests because semantic hints (different per image) were embedded in the system prompt. Since Anthropic's caching uses prefix matching, any change invalidated the cache for the entire ~1000-tag vocabulary and rules section.

Solution

The system prompt now contains only static content (vocabulary, rules, patterns). A short pointer says "Check the user message for SEMANTIC HINTS." The actual hints are in the user prompt, which already changes per request.

For batch processing of 1000 images, the system prompt cost is paid once and cached for all subsequent requests (within the 5-minute TTL).

Test plan

• 455 tests pass, 0 failures
• Comprehensive guide tests updated for new structure
• Keyword extraction tests still pass (hints flow through user prompt)

Fixes #129

[cloudflare-workers-and-pages]

Deploying hedit with    Cloudflare Pages

Latest commit:	2a33a32
Status:	✅  Deploy successful!
Preview URL:	https://c4a1b4e7.hedit.pages.dev
Branch Preview URL:	https://feature-issue-129-cache-frie.hedit.pages.dev

View logs

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[neuromechanist]

PR Review Summary (3 agents: code-reviewer, silent-failure-hunter, test-analyzer)

Critical Issues (0 found)

None.

Important Issues (4 found, ALL FIXED in 2a33a32)

• [code-reviewer] Header mismatch: system prompt pointer said "SEMANTIC HINTS" but actual output was "## POTENTIALLY RELEVANT TAGS". Aligned both to "SEMANTIC HINTS".

• [code-reviewer + silent-failure-hunter] System prompt said "Check the user message for..." (imperative) even when no hints exist. Changed to "The user message may include... If no hints section is present, proceed without them."

• [silent-failure-hunter] Deferred import of private _format_semantic_hints function. Made it public (format_semantic_hints) and moved import to module level. Also added continue for hints with empty tag keys.

• [test-analyzer] Zero test coverage for hints in user prompt. Added 10 tests:

  • test_first_pass_with_semantic_hints
  • test_correction_pass_with_semantic_hints
  • test_no_hints_no_hints_section
  • test_empty_hints_no_hints_section
  • TestFormatSemanticHints (4 tests: None, empty, valid, confidence bucketing, empty tags)
  • TestSystemPromptCaching (system prompt has pointer but not dynamic content)

Suggestions (noted, not fixed)

• [silent-failure-hunter] No debug logging when hints included. Fixed: added logger.debug.
• [test-analyzer] Module-level format_semantic_hints could use boundary-score tests (exactly 0.8, 0.5). Low priority.

All tests pass

• 465 passed, 0 failures